code-gauge

A command-line tool for measuring code metrics with tree-sitter. It scans a project and reports high-risk files, functions, and React components so you can spot code that is worth refactoring. A programmatic API is also available.

Getting started

# Run without installing
npx code-gauge path/to/project

# Or install globally
npm install -g code-gauge
code-gauge path/to/project

The CLI scans JavaScript, JSX, TypeScript, TSX, Python, Go, and Rust files. By default it skips generated, vendor, test, and tool directories, prints a summary, and lists the highest-risk findings. TypeScript project metrics and React component classification turn on automatically when a tsconfig.json is found.

Options

| Option | Description | | -------------------------- | --------------------------------------------------------------------------- | | --config <path> | Use this config file instead of the auto-detected code-gauge.config.json. | | --include-tests | Include test files and test directories. | | --tsconfig <path> | Use this tsconfig.json instead of the auto-detected one. | | --max-findings <n> | Maximum number of findings to print (default: 20). | | --largest-files <n> | List the n largest files by code LOC (config key: largestFiles). | | --json | Print machine-readable JSON. | | --fail-on-risk | Exit with code 1 when any high-risk finding is reported. | | --fail-on-error | Exit with code 1 when any file or directory cannot be scanned. | | --<metric>-threshold <n> | Override a risk threshold (see below). |

Risk thresholds

A finding is reported when a measured value is greater than or equal to its threshold. Every threshold can be set on the command line (e.g. --file-loc-threshold 400) or in a config file; the command line wins over the config file, which wins over the defaults.

code-gauge looks for code-gauge.config.json by walking up from the target directory (override with --config). The following config reproduces every built-in default:

{
  "thresholds": {
    "fileLoc": 500,
    "functionLoc": 120,
    "componentLoc": 350,
    "cognitive": 25,
    "cyclomatic": 20,
    "call": 50,
    "import": 25,
    "fanOut": 10,
    "parameter": 8,
    "duplicateBlock": 2,
    "transitiveDependency": 25,
    "structuralBreadth": 8,
    "structuralCoordination": 300,
    "stateMutation": 50,
    "duplicateSymbolGroup": 5
  },
  "languageThresholds": {
    "python": { "stateMutation": 90, "structuralCoordination": 350 },
    "react": { "import": 30 }
  },
  "maxFindings": 20,
  "includeTests": false,
  "failOnRisk": false,
  "failOnError": false
}

| Threshold | CLI flag | Reports when a … | | ------------------------ | ------------------------------------- | ------------------------------------------------ | | fileLoc | --file-loc-threshold | file's code LOC is large. | | functionLoc | --function-loc-threshold | function's physical LOC span is large. | | componentLoc | --component-loc-threshold | React component's physical LOC span is large. | | cognitive | --cognitive-threshold | function's cognitive complexity is high. | | cyclomatic | --cyclomatic-threshold | function's cyclomatic complexity is high. | | call | --call-threshold | function makes many calls. | | import | --import-threshold | file has many unique import sources. | | fanOut | --fan-out-threshold | function calls many other in-file functions. | | parameter | --parameter-threshold | function declares many parameters. | | duplicateBlock | --duplicate-block-threshold | file contains copy-pasted code blocks. | | transitiveDependency | --transitive-dependency-threshold | file transitively reaches many local files. | | structuralBreadth | --structural-breadth-threshold | file coordinates many structural concerns. | | structuralCoordination | --structural-coordination-threshold | file's structural coordination score is high. | | stateMutation | --state-mutation-threshold | file mutates state heavily. | | duplicateSymbolGroup | --duplicate-symbol-group-threshold | file shares many duplicated symbols with others. |

Per-language thresholds

Some metrics distribute very differently by language or file type, so a single global threshold either over-flags one language or under-flags another. languageThresholds overrides individual thresholds for a profile without repeating the whole set. Each file resolves its thresholds as base → its language profile → the react profile (the last applies when the file contains a React component), so later profiles win.

Valid profile keys are javascript, jsx, typescript, tsx, python, go, rust, and react. Built-in overrides raise stateMutation and structuralCoordination for Python (every binding is an assignment, so these run far higher than in TypeScript) and raise import for React files (which pull in many components). Anything you specify is merged on top of the built-in overrides, so { "python": { "stateMutation": 8 } } restores the global value for Python while keeping the other built-in adjustments.

{
  "languageThresholds": {
    "python": { "stateMutation": 120 },
    "react": { "componentLoc": 400, "import": 35 }
  }
}

Command-line --<metric>-threshold flags set the global base only; use the config file for per-language tuning.

Metrics

• Physical LOC, code lines, comment-only lines, and blank lines
• Function and class counts
• Cyclomatic and cognitive complexity (per function and maximum)
• Nesting depth
• Intra-file call graph metrics: call counts, fan-in/fan-out, recursion, call depth, and parameter counts
• Within-file structural duplication: copy-pasted code blocks (distinct from cross-file duplicate symbol names)
• File coupling (imports/exports) and cohesion (shared function identifiers)
• Architecture metrics: transitive local dependencies, structural coordination and breadth, state mutation, and cross-file duplicate symbols
• TypeScript type-shape metrics: annotations, aliases, interfaces, generics, unions, intersections, assertions, and conditional types
• Halstead metrics and the maintainability index

Supported languages

Built-in parsers cover JavaScript, JSX, TypeScript, TSX, Python, Go, and Rust. Additional tree-sitter grammars can be registered with TreeMeasurer.registerLanguage.

Programmatic API

import { measureCode } from 'code-gauge';

const metrics = measureCode(
  `
function score(value) {
  if (value < 0 || value == null) {
    return 0;
  }
  return value > 10 ? 10 : value;
}
`,
  { language: 'javascript' }
);

console.log(metrics.cyclomaticComplexity);