KNOTS(1)

NAME
knots - multi-language code complexity analyzer with AI cost metrics

SYNOPSIS
knots [OPTIONS] [FILE...]
knots [OPTIONS] --compile-commands <FILE>

DESCRIPTION
knots is a fast multi-language code complexity analyzer built on tree-sitter. It measures traditional complexity metrics alongside two AI-specific cost scores — AIRD (AI Reasoning Difficulty) and AICP (AI Context Pressure) — to identify which functions are genuinely expensive to modify with AI assistance.

knots computes the following metrics for each function:

McCabe Cyclomatic Complexity
    Counts decision points (if, while, for, do, switch, ternary, logical operators). Validated to match pmccabe output exactly.

Cognitive Complexity
    Measures difficulty to understand code, emphasizing nesting and structural complexity. Based on the SonarSource specification.

Nesting Depth
    Maximum nesting level of control structures.

SLOC
    Source lines of code (non-blank, non-comment).

ABC Complexity
    Assignment, Branch, Condition magnitude: sqrt(A² + B² + C²).

Return Count
    Number of return statements in a function.

Test Scoring
    Multi-dimensional test difficulty metric across signature, dependency, observable, implementation, and documentation axes.

External Calls
    Count of unique identifier-form call targets not defined in the same translation unit. Measures external dependency breadth (out-of-file functions and function-like macros).

AIRD — AI Reasoning Difficulty
    Normalized 0–100 score predicting how much reasoning effort an AI model needs to safely modify a function. Formula: (cognitive/75 × 55) + (sloc/200 × 15) + (nesting/8 × 15) + (test_score/20 × 15) - (doc_score/10 × 15). Corpus-validated; recommended CI threshold: 85.

AICP — AI Context Pressure
    Normalized 0–100 score predicting how much context an AI model must load before it can act. Complements AIRD: a function can be cheap to load but hard to reason about, or expensive to load but trivial once context is assembled. Formula: (external_calls/20 × 60) + (sloc/200 × 40) - (doc_score/10 × 15).

OPTIONS

-r, --recursive
    Recursively process all supported source files in directories. When used, a report.txt file is generated with per-function details. Header files (.h, .hpp, .hxx) are skipped by default.

-v, --verbose
    Show detailed per-function analysis.

-m, --matrix
    Show testability matrix categorization. Functions are placed into four quadrants: QUICK WINS (low complexity, easy to test), INVEST IN TESTS (high complexity, easy to test), ADD DOCS (low complexity, hard to test), REFACTOR (high complexity, hard to test).

--compile-commands FILE
    Use a compile_commands.json file (from CMake, Bear, etc.) to get the list of files to analyze. C/C++ only — compilation databases are not produced by Rust, Python, or JavaScript toolchains. Mutually exclusive with the positional FILE argument.

--include FILE
    Include filter rules from a JSON file (whitelist). See FILTERS below.

--exclude FILE
    Exclude filter rules from a JSON file (blacklist). See FILTERS below.

--format FORMAT
    Output format. One of:

    text
        Human-readable output (default).

    sarif
        SARIF 2.1.0 JSON for VS Code / GitHub Code Scanning.

    json
        JSON array of per-function metrics.

    ndjson
        Newline-delimited JSON — one record per line, composable via find/xargs.

    csv CSV with header row.

--mccabe-threshold N
    Exit 1 if any function exceeds this McCabe complexity.

--cognitive-threshold N
    Exit 1 if any function exceeds this cognitive complexity.

--nesting-threshold N
    Exit 1 if any function exceeds this nesting depth.

--sloc-threshold N
    Exit 1 if any function exceeds this SLOC count.

--abc-threshold F
    Exit 1 if any function exceeds this ABC magnitude.

--return-threshold N
    Exit 1 if any function exceeds this return count.

--aird-threshold N
    Exit 1 if any function exceeds this AIRD score. Recommended value: 85 (empirically validated against Sonnet 4.6 and Opus 4.8).

--aicp-threshold N
    Exit 1 if any function exceeds this AICP score.

--external-calls-threshold N
    Exit 1 if any function exceeds this external call count.

-h, --help
    Print help message.

-V, --version
    Print version information.

FILTERS
Filter rules are specified in JSON files with the following optional fields:

file_patterns
    Glob patterns for file paths. Supports *, **, and ! for negation.

function_patterns
    Regular expression patterns for function names.

min_complexity
    Minimum complexity threshold (inclusive).

max_complexity
    Maximum complexity threshold (inclusive).

Example filter file:
    {
        "file_patterns": ["src/**/*.c"],
        "function_patterns": ["^handle_"],
        "min_complexity": 10
    }

COMPLEXITY INDICATORS
knots uses visual emoji indicators based on the maximum of McCabe and Cognitive complexity:

    1-10   Good     - Low complexity, easy to maintain
    11-20  Okay     - Moderate complexity, may need attention
    21-49  Bad      - High complexity, consider refactoring
    50+    Critical - Very high complexity, refactor immediately

EXIT STATUS

0   Successful analysis, no threshold violations.

1   Error occurred (file not found, parse error, invalid arguments), or one or more threshold violations were detected (when any --*-threshold flag is set).

EXAMPLES
Analyze a single file:
    knots path/to/file.c

Recursively analyze a directory:
    knots -r path/to/project/

CI gate — fail if any function has AIRD > 85:
    knots -r src/ --aird-threshold 85

Analyze a Rust project:
    knots -r src/

Corpus analysis — one JSON record per function, composable across files:
    find . -name "*.c" -o -name "*.rs" | xargs knots --format ndjson > metrics.ndjson

Filter high-AIRD functions via jq:
    find src/ -name "*.rs" | xargs knots --format ndjson | jq 'select(.aird > 70)'

Analyze files from a compilation database:
    knots --compile-commands build/compile_commands.json

SARIF output for GitHub Code Scanning:
    knots -r --format sarif src/ > knots.sarif

FILES

report.txt
    Generated in the current directory when using -r mode. Contains per-function complexity details.

compile_commands.json
    Compilation database used with --compile-commands.

AUTHORS
Brandon Arrendondo <brandon.arrendondo@bissell.com>

BUGS
Report bugs at: https://github.com/brandon-arrendondo/knots/issues

SEE ALSO
knots-test-complexity(1), pmccabe(1)