Skip to content
effect-analyzer

Coverage Audit

The coverage audit scans an entire directory of TypeScript files and produces a comprehensive report of Effect usage across your project. Use it to understand how much of your codebase uses Effect, identify files the analyzer struggles with, and track analysis quality over time.

Example corpus: packages/effect-analyzer/src/__fixtures__/docs/audit

$ npx effect-analyze ./src/__fixtures__/docs/audit --coverage-audit


Files discovered:      4
Effect-bearing files:  2
No Effect programs:    2
Analysis failures:     0
Suspicious zero files: 0
Effect adoption:       50.0% (2/4 discovered files)
Analysis success:      100.0% (2/2 relevant files)
IR source resolution:  100.00% (8/8 IR nodes)
Duration:              1183ms
Zero categories: barrel/index=1, config/build=0, test/dtslint=0, type-only=0, suspicious=0, other=1

Running a Coverage Audit

Section titled “Running a Coverage Audit”
Terminal window
npx effect-analyze ./src --coverage-audit

This produces a report covering:

  • Discovery - how many files were found, analyzed, and failed
  • Effect adoption - Effect-bearing files divided by all discovered files
  • Analysis success - successfully analyzed Effect-bearing files divided by those files plus analysis failures
  • IR source resolution - resolved IR nodes divided by all IR nodes
  • Zero-program files - files with no Effect programs, classified by type
  • Top offenders - files with highest complexity
  • Fidelity findings - located source patterns the analyzer could not represent exactly

Audit Output

Section titled “Audit Output”

Named Assessment Dimensions

Section titled “Named Assessment Dimensions”
Effect adoption:      69.7% (99/142 discovered files)
Analysis success:     96.1% (99/103 relevant files)
IR source resolution: 98.4% (1842/1872 IR nodes)

Each dimension includes its numerator and denominator in human and JSON output. This prevents a mixed TypeScript project from looking like an analyzer failure: zero-program files lower Effect adoption, while only failed analysis lowers analysis success.

Zero-Program Classification

Section titled “Zero-Program Classification”

Files with no detected Effect programs are classified into categories:

Classification Description
Barrel Re-export files (index.ts with only export * from)
Config Configuration files (constants, env vars)
Test Test files (.test.ts, .spec.ts)
Type-only Files with only type definitions
Suspicious Files that look like they should contain Effect but don’t

Suspicious Zeros

Section titled “Suspicious Zeros”

Show files that appear to import Effect but have no detected programs:

Terminal window
npx effect-analyze ./src --coverage-audit --show-suspicious-zeros

Located Fidelity Findings

Section titled “Located Fidelity Findings”

Show source locations where the analyzer could not represent an expression:

Terminal window
npx effect-analyze ./src --coverage-audit --show-top-unknown

Add --show-top-unknown-reasons to aggregate the unresolved patterns by reason:

Terminal window
npx effect-analyze ./src --coverage-audit --show-top-unknown --show-top-unknown-reasons

By-Folder Breakdown

Section titled “By-Folder Breakdown”

Aggregate results by folder to see which parts of your project have the highest Effect adoption:

Terminal window
npx effect-analyze ./src --coverage-audit --show-by-folder

CI Mode

Section titled “CI Mode”

Output the audit as JSON for CI/CD integration:

Terminal window
npx effect-analyze ./src --coverage-audit --json-summary

This produces a machine-readable JSON object with the same named assessment dimensions as the human report.

Use native audit policy flags to fail CI without a separate parsing script:

Terminal window
npx effect-analyze ./src --coverage-audit --quiet \
  --max-audit-failed-files 0 \
  --max-audit-suspicious-zeros 0 \
  --min-audit-source-resolution 98

Quiet mode prints one summary line plus any policy violations. A failed policy returns exit code 1. JSON output includes the typed policy decision and violations.

Performance Timing

Section titled “Performance Timing”

Include per-file timing data to identify slow files:

Terminal window
npx effect-analyze ./src --coverage-audit --per-file-timing

Additional Options

Section titled “Additional Options”
Flag Description
--min-meaningful-nodes <n> Minimum node count to consider a file meaningful
--known-effect-internals-root <path> Treat local paths as Effect-like (reduces false suspicious zeros)
--exclude-from-suspicious-zero <pattern> Exclude patterns from suspicious-zero reporting

Programmatic Usage

Section titled “Programmatic Usage”
import { runCoverageAudit } from "effect-analyzer/analysis"


const audit = await runCoverageAudit("./src", {
  showSuspiciousZeros: true,
  showTopUnknown: true,
  jsonSummary: false,
})


console.log(audit.discovered)  // Total files found
console.log(audit.analyzed)    // Files successfully analyzed
console.log(audit.failed)      // Files that failed analysis
console.log(audit.assessment.effectAdoption)      // { numerator, denominator, rate }
console.log(audit.assessment.analysisSuccess)     // { numerator, denominator, rate }
console.log(audit.assessment.sourceResolution)    // { numerator, denominator, rate }
Section titled “Related”