Find Complexity Hotspots

/find-complexity-hotspots

Kotlin/JVM 2.4.10 branch

Trigger this branch only for manifest-selected authored .kt functions. Keep sibling _kotlin, read ../_kotlin/GUIDE.md, and enter through scripts/run_kotlin.py. Its frozen direct-body branch-keyword score is advisory syntax evidence only; lambdas/local or inline functions, contracts, resolved control flow, generated members, Java, Gradle variants, frameworks, runtime cost, and refactor safety remain unresolved.

C# 14 / .NET 10 branch

Use scripts/run_csharp.py with the sibling _csharp provider; run it with --help for the exact CLI. It reports named methods whose direct Roslyn body has a syntactic branch score of at least eight in the current compiled manifest closure. The score is advisory source syntax, not runtime cost, cognitive complexity, resolved control flow, or refactor safety. Without the product-specific csharp-project.json, this branch retains hash-bound authored-source findings as partial / safe-defer-incomplete without claiming build membership, dependency resolution, generated inputs, or native-test coverage. For a read-only real-repository scan, pass an external --output-dir with --no-host-write.

C++20 branch

Use scripts/run_cpp.py with the sibling _cpp provider; run the script with --help for the exact CLI. It scores direct function bodies from a current target-covering C++20 compile database, with compiler-owned headers and exact namespace/signature/overload identity. The score says nothing about runtime cost, ODR/ABI, specializations, dynamic dispatch, or external variants. --compile-database accepts a standard CMake-style database outside the host; --no-host-write requires only the report output to stay outside. A database that omits other target translation units retains facts from covered units and their owned headers as partial / safe-defer-incomplete rather than erasing them or claiming a clean result.

C17 branch

Use scripts/run_c.py with the sibling _c-syntax provider; run python3 scripts/run_c.py --help for the exact CLI. This external-library branch emits a direct-function-body syntax score from one current C17 compile-command snapshot. Macro meaning, runtime cost/control flow, performance, behavior, and refactor safety remain unresolved. Pass an external Meson/CMake compilation database with --compile-database and external artifacts with --no-host-write when dogfooding a clean checkout. Standard command or arguments rows and mixed C/C++ databases are accepted; only selected C17 entries become C evidence.

External syntax variants

For PHP, Ruby, or Swift, load the selected skill with its sibling provider and read the matching on-demand guide before execution:

• ../_php-syntax/GUIDE.md
• ../_ruby-syntax/GUIDE.md
• ../_swift-project-lexical/GUIDE.md

These are frozen direct-body syntax scores and advisory leads. The guides own the exact commands, nested-callable boundaries, native gates, and non-claims. For Ruby complexity only, a missing gem lockfile or unavailable frozen bundle does not erase source-bound Prism leads; the report remains partial / safe-defer-incomplete and never claims a clean project result. Swift complexity likewise accepts an external --output-dir with --no-host-write. A dependency, plugin, or target-shape gate may preserve hash-bound lexical leads under partial / incomplete; only a passed compiler gate labels them compiler-validated.

Dart v1

Dart v1 consumes the shared _dart D3 syntax snapshot and reports named direct bodies at the frozen score threshold of 18. Nested closures and local functions do not inflate their owners. The score is advisory syntax evidence, not runtime or cognitive complexity.

SKILL_ROOT=".agents/skills/on-demand/find-complexity-hotspots"
python3 "${SKILL_ROOT}/scripts/run_dart.py" \
  --project-root "$PWD" --target lib --facts /tmp/dart-d3-facts.json \
  --output-dir "$PWD/reports/complexity-hotspots/dart"

For source-preserving dogfood, set --output-dir to a path outside the host and add --no-host-write. A partial/native_contract_unavailable snapshot may still publish hash-bound syntax leads, but its outcome remains incomplete and must not be reported as a clean scan.

Rust v1

Rust v1 reports advisory direct-body branch scores for named functions. It excludes nested functions and braced closures and never infers runtime cost. The copied closure must include sibling _rust-syntax; cfg, macro/build, generated, and symlink uncertainty prevents a clean result. Locked/offline native checks may reuse dependencies already present in the user's Cargo cache but never fetch them. A missing cached dependency leaves source-bound syntax leads visible with partial / safe-defer-incomplete; it is not a clean scan.

SKILL_ROOT=".agents/skills/on-demand/find-complexity-hotspots"
python3 "${SKILL_ROOT}/scripts/run_rust.py" \
  --project-root "$PWD" --target src \
  --output-dir "$PWD/reports/complexity-hotspots/rust"

Run a read-only SUSPECT audit. A finding is a lead worth reading, never a proof that an optimization is safe or valuable.

How success is judged

• The final report directory contains detections.jsonl, report.md, and findings.json, with latest pointing to that run. Go and Java reports also state complete or partial plus their explicit ambiguity or unsupported evidence. Do not claim a scan ran without these artifacts.
• Python findings preserve the six established bands. JavaScript, TypeScript, Go, and Java findings carry their exact language, native analyzer, function start/end lines, LOC, and branch score in both JSON artifacts; report.md prints the analyzer provenance.
• Use one verdict: no-hotspots, measure-first, actionable-hotspot, safe-defer-incomplete, or scan-blocked. Incomplete evidence must never be presented as no-hotspots. TypeScript findings are normally measure-first until native tests and realistic input sizes justify a change.
• This skill never edits source files or claims framework identity, API ownership, runtime cost, Java type resolution, or Kotlin/JVM-wide support.

Scope

• Target: one or more explicit files, directories, or globs. There is no whole-repository default.
• Python branch: the existing stdlib AST detector remains intact: nested loops, membership scans, sort/repeated scans, Django QuerySet-like calls in loops, and high-branch functions. --include-tests affects this branch only.
• JavaScript/TypeScript v1: .js, .jsx, .mjs, .cjs, .ts, and .tsx function declarations, methods, block-bodied arrows and variable function expressions, and CommonJS/prototype or object-property function assignments. It counts only syntactically established counterparts of the existing branch invariant: conditionals, loop forms, try/catch, with, switch, &&/||, and ternaries. It does not infer data cost from these syntax facts.
• JavaScript/TypeScript exclusions: React/Node/ORM semantics, receiver or type claims, anonymous callback-only function expressions, expression-bodied arrows, declarations and overload signatures without a body, declarations (.d.ts), and generated, vendor, minified, bundle, test, spec, and fixture paths. These exclusions are deliberate even when --include-tests is present.
• JavaScript/TypeScript prerequisite: Node plus a typescript package. The parser prefers the target host's package when available and otherwise uses the pinned package installed at the external engineering-skills library root. The family-local Compiler API parser uses createSourceFile, not a tsconfig, Program, TypeChecker, shared parser, or fact platform. Missing both parser packages, missing Node, malformed parser output, or source syntax errors stop the run with exit code 2 instead of silently under-detecting.
• Go v1: .go named functions and receiver methods using the host Go toolchain's standard-library go/parser and go/ast. It counts if, for, range, switch, type-switch, select, &&, and || in the direct function body only. Nested function literals, imports, calls, interfaces, and type/package identity are outside the claim.
• Go exclusions and ambiguity: _test.go, vendor, generated/gen, fixture, build, and report paths are excluded even when directly targeted. Go's Code generated ... DO NOT EDIT. marker is excluded using ast.IsGenerated. Explicit //go:build or // +build files are withheld with build-constraint-ambiguous, and the final report is partial, never clean.
• Go prerequisite: a go executable on PATH, version Go >= 1.22.0. Missing or older Go, malformed eligible source, or malformed parser output stops the run with exit code 2; do not present a previous latest report as this run's result.
• Java v1: .java declared methods and constructors using the host JDK compiler tree API. It counts if, classic/enhanced for, while, do, switch statements/expressions, catch, ternaries, &&, and || in the direct method body. Nested lambdas and local/anonymous class bodies do not contribute to their enclosing method. Methods of local/anonymous classes, type resolution, call graphs, framework semantics, build configuration, and runtime cost are outside the claim.
• Java exclusions and mixed source: test (including Gradle integrationTest and testFixtures), vendor, generated, fixture, build/output, report, and symlink paths are excluded even when directly targeted. Generated headers and top-level type @Generated markers are withheld. A target containing only excluded Java source is partial, not a clean no-hotspot result; Markdown and JSON name the excluded paths. Eligible .kt/.kts files are inventoried as kotlin_source_present, make the Java result partial, and are never presented as Java or JVM support.
• Java prerequisite: both java and javac on PATH from JDK >= 17.0.0. The family-local source launcher batches all eligible .java files through the public compiler tree API. It does not invoke Maven/Gradle, resolve a project classpath, download a JAR, or import a shared analysis platform. Missing/old JDK, malformed eligible source, or malformed helper output stops the run with exit code 2.

Installed command

Set TARGET to the requested source directory. Run this resolver verbatim from the host root; it supports both a stock install and this source checkout.

SKILL_ROOT=""
for SKILL_CANDIDATE in \
  ".agents/skills/find-complexity-hotspots" \
  ".claude/skills/find-complexity-hotspots"
do
  if [ -f "${SKILL_CANDIDATE}/SKILL.md" ]; then
    SKILL_ROOT="$(cd "${SKILL_CANDIDATE}" && pwd)"
    break
  fi
done
if [ -z "${SKILL_ROOT}" ]; then
  printf '%s\n' "find-complexity-hotspots is not installed in .agents/skills or .claude/skills" >&2
  exit 2
fi
if [ -x ".venv/bin/python" ]; then
  HOST_PYTHON="$(pwd)/.venv/bin/python"
else
  HOST_PYTHON="python3"
fi

: "${TARGET:?Set TARGET to a file, directory, or glob to audit}"
"${HOST_PYTHON}" "${SKILL_ROOT}/scripts/run.py" \
  --project-root "$(pwd)" \
  --skip-effectiveness-log \
  "${TARGET}"

Use --language typescript, --language go, or --language java to make a narrow native-parser contract explicit, or --language python to retain the Python-only scan. The default is additive: it scans supported Python, JavaScript, TypeScript, Go, and Java files found under TARGET. --skip-effectiveness-log is retained for command compatibility; selected-skill execution has no toolkit telemetry dependency.

For direct detector debugging, write only JSONL:

"${HOST_PYTHON}" "${SKILL_ROOT}/scripts/detect.py" \
  --project-root "$(pwd)" \
  --output /tmp/complexity-hotspots.jsonl \
  --language typescript \
  "${TARGET}"

Finding buckets

• django-query-in-loop, nested-loop, membership-scan-in-loop, sort-in-loop, and repeated-scan-in-loop are Python-only heuristic leads. Preserve filters, authorization, ordering, duplicates, and data-size behavior before replacing a loop with a query, map, set, grouping, or batch.
• high-branch-function is structural. Python preserves its historical AST score. TypeScript, Go, and Java report the same threshold only from their narrow syntax lists above, never from calls, receivers, types, interfaces, or framework conventions.

Summarize and act

Report in 10 lines or fewer: total findings and bucket counts; up to three locations/symbols; the verdict; the reports/find-complexity-hotspots/latest/ report path; and one evidence-based next step. Do not optimize cold code or small collections. For TypeScript, Go, or Java, state the score is syntactic and name any unknown input size. For Go partial, name every build-constraint ambiguity; for Java partial, name the unsupported Kotlin paths.

Replay check

After changing this skill, run the Python oracle and native outcome suites:

python3 "${SKILL_ROOT}/scripts/smoke.py"
python3 -m pytest -q tests/test_find_complexity_hotspots_typescript.py
python3 -m pytest -q tests/test_find_complexity_hotspots_go.py
python3 -m pytest -q tests/test_find_complexity_hotspots_java.py
node --check "${SKILL_ROOT}/scripts/detect_typescript_complexity.mjs"
gofmt -d "${SKILL_ROOT}/scripts/detect_go_complexity.go"
java "${SKILL_ROOT}/scripts/detect_java_complexity.java" \
  --project-root "$(pwd)" \
  --file tests/fixtures/find-complexity-hotspots-java/src/main/java/example/CleanService.java

The locked TypeScript fixture runs npm ci --offline --ignore-scripts, npm run typecheck (tsc --noEmit), and npm test. It proves positive, clean, generated/vendor/minified/test/spec/declaration exclusions, syntax and prerequisite failures, copied closure, and stock installation commands.

When things go sideways