@focusedobjective/code-scan

Local multi-language code metrics scanner for DeliveryTower engineering analytics.

The scanner runs locally and writes summary metrics to JSON. It does not upload source code.

Usage

npx @focusedobjective/code-scan .

Write to a specific file:

npx @focusedobjective/code-scan . --out deliverytower-code-metrics.json

Print JSON to stdout:

npx @focusedobjective/code-scan . --stdout

Output

The scanner writes a deliverytower-code-metrics.json file by default:

{
  "schemaVersion": "1.0",
  "scanner": "deliverytower-code-scan",
  "scannerVersion": "0.4.1",
  "scannerMode": "auto-enhanced",
  "summary": {
    "sourceFiles": 120,
    "sourceLines": 42000,
    "functions": 900,
    "duplicationPercent": 8.4,
    "averageComplexity": 2.7,
    "functionsOver10LinesPercent": 34.1,
    "maintainabilityIndex": 22,
    "bytesProcessed": 16601962,
    "codeToCommentRatio": 5.3,
    "totalComplexity": 57734,
    "complexityPerKLines": 166.9,
    "topLanguages": [
      { "language": "TypeScript", "sourceLines": 28000, "files": 80, "complexity": 4200 }
    ],
    "mostComplexLanguages": [
      { "language": "TypeScript", "complexity": 4200, "complexityPerKLines": 150, "sourceLines": 28000 }
    ],
    "locomo": {
      "source": "deliverytower-estimate",
      "preset": "medium",
      "inputTokens": 3000000,
      "outputTokens": 700000,
      "costToGenerate": 20,
      "estimatedCycles": 2.1,
      "generationTimeHours": 3.9,
      "humanReviewTimeHours": 5.9
    }
  }
}

Ignore Rules

The scanner honors:

• .gitignore
• .deliverytowerignore
• built-in ignores for common dependency, build, coverage, and generated folders

The effective ignore configuration is included in the output configHash, so trend comparisons can verify that scans used comparable settings.

Metric Intent

This tool is designed for consistent trend signals over time, not compiler-grade static analysis. It uses a built-in scanner by default so every repo can produce a stable report without installing language-specific tools.

Optional External Scanners

The scanner works without external dependencies. By default, it uses these tools when they are installed and falls back to built-in metrics when they are not:

• Strongly recommended: scc for fast language, file, line, broad complexity, and LOCOMO AI rebuild estimates
• Optional: jscpd for stronger duplicate-code detection

Install them only if you want more robust local metrics. The JSON schema stays the same either way.

The scanner still detects lizard if it is installed and can use it for function-level metrics, but the recommended setup is scc plus optional jscpd.

The scanner stores an optional summary.locomo block for DeliveryTower's AI rebuild estimate: tokens, estimated generation cost, serial generation time, and human review time. If the installed scc supports --locomo, the source is scc-locomo. Otherwise, the scanner uses a DeliveryTower estimate derived from local line and complexity metrics.

When scc is installed, the scanner also stores optional codebase metrics such as bytesProcessed, totalComplexity, complexityPerKLines, topLanguages, mostComplexLanguages, and, if exposed by the installed scc output, uniqueLines / drynessPercent.

Quick Install

The scanner looks for an installed scc command on PATH. Do not use npx scc; that resolves to an unrelated npm package.

Windows:

winget install --id benboyter.scc --source winget
npm install -g jscpd

macOS:

brew install scc
npm install -g jscpd

Linux:

npm install -g jscpd

For Linux scc, use your distro package manager if available, or download a release binary from GitHub.

Manual scc Install

If your package manager does not have scc, install the binary manually:

1. Open the scc releases page: https://github.com/boyter/scc/releases
2. Open the latest release.
3. Scroll to the Assets section.
4. Download the archive for your operating system and CPU architecture. Examples:
   • Windows x64: look for a Windows x86_64 / amd64 asset.
   • macOS Apple Silicon: look for a Darwin arm64 asset.
   • macOS Intel: look for a Darwin x86_64 asset.
   • Linux x64: look for a Linux x86_64 / amd64 asset.
5. Extract the archive.
6. Put the scc or scc.exe binary in a folder on PATH.
7. Open a new terminal and verify:

scc --version

On Windows, good places for scc.exe are:

• C:\Users\<you>\bin\scc.exe
• C:\Tools\scc\scc.exe
• any existing tools folder your terminal already has on PATH

If you choose C:\Tools\scc, add it to your user PATH:

[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\Tools\scc",
  "User"
)

Then open a new terminal and run:

scc --version

On macOS or Linux, put scc somewhere like /usr/local/bin, ~/bin, or ~/.local/bin, and make sure that folder is on PATH.

If you already have Go installed, this also works:

go install github.com/boyter/scc/v3@latest

jscpd is the npm-native optional component. scc is a Go binary distributed through OS package managers and GitHub releases.

Verify

scc --version
jscpd --version

When these tools are on PATH, the scanner records them in the output:

{
  "tools": {
    "scc": { "available": true, "used": false },
    "jscpd": { "available": true, "used": false }
  }
}

used is true when a tool was available, ran successfully, and replaced the built-in value for its metric group.

To force the built-in scanner only:

npx @focusedobjective/code-scan . --mode built-in