CodeFlow Documentation

The Debug Statements security rule (triggered by excessive console.log, console.debug, or console.info calls) should have its severity adjusted based on whether the file is part of the backend architecture.

• Backend/Server paths: Severity should be info.
• Client/Other paths: Severity should be low.

This uses the isArchitectureBackendPath(path) classifier to determine the appropriate level.

if(scanContent.match(/console\.(log|debug|info)\(\)){
    var consoleCount=(scanContent.match(/console\.(log|debug|info)\(\)/g)||[]).length;
    if(consoleCount>3){
        var debugSeverity=isArchitectureBackendPath(f.path)?'info':'low';
        issues.push({
            severity:debugSeverity,
            title:'Debug Statements',
            file:f.name,
            path:f.path,
            desc:consoleCount+' console statements found. Remove before production.',
            code:''
        });
    }
}

To verify layer violation logic, follow the existing golden-fixture pattern used in tests/codeflow-golden.test.mjs. This involves extracting the analyzer from index.html via vm, providing constructed files and connections, and asserting on the output.

When testing Parser.detectLayerViolations and Parser.detectLayer directly, ensure the following behaviors are validated:

• Healthy dependencies: A file in a higher layer (e.g., services) depending on a file in a lower layer (e.g., utils) should produce 0 violations.
• Genuine violations: A file in a lower layer (e.g., utils) depending on a file in a higher layer (e.g., services) should produce 1 violation. The violation object should include from (the violating file) and a suggestion such as "utils should not import from services".
• Gap threshold: Dependencies between adjacent layers (a level difference of 1) should produce no violations.
• Root-level folder detection: Ensure detectLayer correctly identifies layers for paths like services/x.ts (layer: services) or nested paths like src/services/x.ts (layer: services).
• Non-regression: Ensure node --test passes and existing golden fixtures remain green, as they exercise the full buildAnalysisData pipeline.

If layer violations are being reported in the wrong direction (e.g., reporting a healthy downward dependency as a violation), you must ensure the logic correctly identifies the importer and the imported file.

In the connections.forEach loop within detectLayerViolations, the target property of the connection object represents the importerFile. A violation is triggered if importerLevel > importedLevel and the difference between levels is greater than 1.

// Correct implementation logic for detectLayerViolations
connections.forEach(function(c){
    var importedFile=fileByPath[c.source];
    var importerFile=fileByPath[c.target];
    if(!importedFile||!importerFile)return;
    var importedLayer=(importedFile.layer||'').toLowerCase();
    var importerLayer=(importerFile.layer||'').toLowerCase();
    var importedLevel=layerOrder[importedLayer];
    var importerLevel=layerOrder[importerLayer];
    
    if(importerLevel!==undefined&&importedLevel!==undefined&&importerLevel>importedLevel&&importerLevel-importedLevel>1){
        violations.push({
            from:importerFile.path,
            fromLayer:importerFile.layer,
            to:importedFile.path,
            toLayer:importedFile.layer,
            fn:c.fn,
            suggestion:importerFile.layer+' should not import from '+importedFile.layer+'. Consider inverting the dependency or using dependency injection.'
        });
    }
});

To prevent false positives in XSS detection, update the detectSecurity function in index.html to recognize when dangerouslySetInnerHTML is being used with a static string literal. The rule should still flag instances where variable interpolation (e.g., {{ __html: rawUserBio }}) is used, as these pose a real XSS risk.

var hasInnerHtmlAssignment=scanContent.match(/innerHTML\s*=/");
var hasDangerousHtmlRender=scanContent.match(/dangerouslySetInnerHTML/);
var isSafePreviewRender=!hasInnerHtmlAssignment&&hasDangerousHtmlRender&&isSanitizedPreviewRenderer(f.content||'');
var htmlValueMatch=scanContent.match(/dangerouslySetInnerHTML\s*[:=]\s*\{\{?\s*__html\s*:\s*([^}]+)\}/);
var isLiteralOnlyHtml=!!(htmlValueMatch&&/^(['"`])(?:(?!\1)[\s\S])*\1$/.test(htmlValueMatch[1].trim()));
var isSafeStaticHtml=!hasInnerHtmlAssignment&&hasDangerousHtmlRender&&isLiteralOnlyHtml;
if((hasInnerHtmlAssignment||hasDangerousHtmlRender)&&!isSafePreviewRender&&!isSafeStaticHtml){
    issues.push({severity:'high',title:'XSS Vulnerability',file:f.name,path:f.path,desc:'Direct HTML injection can lead to XSS attacks. Sanitize user input.',code:''});
}

The SQL Injection Risk rule in index.html should be updated to anchor detections to actual database call receivers (query, execute, or raw) and ensure it only flags code files (f.isCode). This prevents markdown prose containing SQL-like syntax from being incorrectly flagged. The rule now checks for both string concatenation (+) and template literal interpolation (${) within the arguments of a database call.

var dbCallMatch=scanContent.match(/\b(?:query|execute|raw)\s*\(([^)]*)\)/i);
var hasSqlConcat=scanContent.match(/query\s*\(\s*['"`][^'"`]*\s*\+/)||scanContent.match(/execute\s*\(\s*['"`][^'"`]*\$\{/);
var hasSqlTemplateInjection=dbCallMatch&&/\$\{/.test(dbCallMatch[1])&&/(?:SELECT|INSERT|UPDATE|DELETE)/i.test(dbCallMatch[1]);
if(f.isCode&&(hasSqlConcat||hasSqlTemplateInjection)){
    var m=scanContent.match(/.*(query|execute|SELECT|INSERT|UPDATE|DELETE).*(\+|\$\{).*/i);
    issues.push({severity:'high',title:'SQL Injection Risk',file:f.name,path:f.path,desc:'String concatenation in SQL queries. Use parameterized queries instead.',code:m?m[0].trim().substring(0,80):''});
}

The CodeFlow Card is a GitHub Action that generates an auto-updating SVG card for your repository's README, displaying metrics like health grade, scale, fragility, and hidden costs.

To set it up:

1. Create a workflow file at .github/workflows/codeflow-card.yml with the configuration provided below.
2. Add the generated SVG to your README using an <img> tag.

The Action requires contents: write permissions to commit the SVG and the history file. If you enable receipts, it also requires pull-requests: write permissions.

name: CodeFlow Card
on:
  push:
    branches: [main]
  pull_request:
    types: [closed]
  workflow_dispatch:

jobs:
  card:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: braedonsaunders/codeflow/card@v1
        with:
          receipts: false  # set true to post merged-PR comments

Then add this to your README:

<img src=".github/codeflow-card.svg" alt="CodeFlow card" />