Hotspot analysis → test-generation prioritization (Java)

This skill is a thin wrapper around a Java CLI. The jar does the analysis deterministically; the skill's job is to build it, configure it, run it, and hand the ranked, machine-readable output to whatever generates tests (typically RestAssured API tests, or unit tests for the top methods).

What makes it worth a separate step (vs. asking a model to "guess the risky endpoints"):

• Deterministic & reproducible — pure JVM computation; same inputs → same

scores and same ordering. No randomness, no model variance.

• Method-level, hunk-accurate Java — churn is attributed to the exact

methods whose line ranges a commit's diff hunks touched, not the whole file.

• Recency-weighted — recent churn counts more via exponential decay

(configurable half-life).

• JaCoCo-integrated — real line-coverage gaps raise priority of untested

code; coverage can be a scoring input or an observational column.

• CI-gating — --strict returns a non-zero exit code on empty results.

The primary deliverable is a priority queue of REST API endpoints: for each endpoint you get its HTTP method + route, the aggregated risk over its whole call graph, the call graph itself, and a coverage signal — i.e. exactly what an agent needs to decide which endpoint to test first and which under-tested path to target.

When to use

• "Generate RestAssured tests for this Spring app, most important endpoints first."
• "Which API endpoints / methods are riskiest and least tested? In what order?"
• Producing a deterministic prioritization that a test-generation step consumes.

Not for: non-Java repos; deciding test content (it ranks what to test, the test generator decides how).

Target must be a directory containing a real .git/ folder. Phase 1 runs local-git end-to-end; github target needs a local clone (see Troubleshooting).

Prerequisites

Workflow

A convenience wrapper, scripts/run-analysis.sh, resolves the jar (downloading the released fat jar if needed) and runs analyze. The steps below show the explicit form.

1. Get the jar. No build required — the resolver downloads the released fat

jar to a cache (or reuses a local build, or builds from source as a fallback):

   JAR="$(skills/hotspot-analysis/scripts/get-jar.sh)"   # prints the jar path
   # manual alternative (no clone needed):
   #   curl -fsSL https://github.com/baekchangjoon/hotspot-analysis/releases/latest/download/hotspot.jar -o hotspot.jar
   #   JAR=hotspot.jar
   # from-source alternative (needs the repo + a JDK):  ./gradlew bootJar

No JDK at all? Use the Docker image, mounting the target repo at /work: docker run --rm -v "$PWD":/work ghcr.io/baekchangjoon/hotspot-analysis:latest analyze --config /work/hotspot.yml

1. Generate a config.

   java -jar "$JAR" init -o hotspot.yml

1. Configure for endpoint prioritization. Point analysis.target.path at

the target repo, enable API analysis, and (if available) supply a JaCoCo report. If the user can't hand-write the YAML, run the interview below ("Configure interactively") — ask, fill defaults, write the file. See Config reference for every key. The key block:

   analysis:
     apiAnalysis:
       enabled: true
       sharedComponentMode: BOTH            # CUMULATIVE | SEPARATE | BOTH
       classpathDirectories:                # optional but improves call-graph resolution
         - build/libs
     jacocoReportPath: build/reports/jacoco/test/jacocoTestReport.xml
   output:
     formats: [yaml, md, html]
     apiLayout: BOTH                        # COMBINED | STANDALONE | BOTH
     topN: 30

1. Analyze (add --strict in CI).

   java -jar "$JAR" analyze --config hotspot.yml --strict
   # or, in one shot (resolves the jar for you):
   #   skills/hotspot-analysis/scripts/run-analysis.sh hotspot.yml --strict

Outputs land in output.path. With API analysis on and apiLayout: BOTH:

   hotspot-report/
   ├── api_report.yml        ← STANDALONE: apiHotspots + sharedComponents (agent input)
   ├── hotspots.yml          ← COMBINED: file + method + api + shared in one doc
   ├── hotspots.md / .html   ← human-readable
   ├── file_hotspots.csv
   └── method_hotspots.csv

1. Consume the ranking for RestAssured. Read api_report.yml and iterate

apiHotspots in compositeRank order. Field-by-field schema: references/api-report-schema.md. Each row carries:

Generate tests highest-rank first, targeting the least-covered paths in each endpoint's call graph. Do not fabricate the ranking — run the CLI and read the actual file.

Configure interactively (interview)

A freshly-installed user usually can't write hotspot.yml cold. Don't make them. Generate a starting file (init), then fill it by Q&A: auto-detect what you can, ask only what's ambiguous, confirm, and write the file.

Procedure:

1. Detect first, then ask. Inspect the target repo to pre-fill defaults so

most questions become a yes/no confirmation:

• Spring app? — grep -rl "@RestController\|@RequestMapping" <repo>/src → if

hits, default apiAnalysis.enabled: true.

• Multi-module? — more than one src/main/java root → include both globs.
• JaCoCo report present? — look for **/jacoco/**/*.xml (e.g.

build/reports/jacoco/test/jacocoTestReport.xml) → default jacocoReportPath.

• Built classes/jars? — build/libs, build/classes → default

apiAnalysis.classpathDirectories.

• Recent activity? — git -C <repo> log -1 --format=%cd → if older than a

year, propose absolute window.since/until instead of days.

1. Ask, one decision at a time (skip any you confidently detected — just

state the default and let the user correct it):

1. Write `hotspot.yml` from the answers, show it back to the user for a

final OK, then run step 4. If a tool like AskUserQuestion is available, prefer it for crisp multiple-choice prompts; otherwise ask in plain text.

Keep it short: a typical session is "confirm repo path → confirm Spring/API on → accept window default → confirm the detected JaCoCo path → go".

How the score is computed

Four input factors → two scores. Full per-granularity derivations (with source references and worked examples) live in [`docs/scoring/`](../../docs/scoring/README.en.md): file · method · REST API endpoint · shared component.

For an API endpoint, each factor is aggregated over the controller method plus its whole call graph; coverage is the average over those methods. Sorted by Composite DESC, ties broken deterministically (route,httpMethod).

Config reference

analysis:
  target:
    type: local-git          # local-git | github (Phase 1 CLI: local-git end-to-end)
    path: /path/to/target/repo   # must contain a .git/ folder
  window:
    days: 365                # Mode A: relative window from now
    # since: "2024-01-01"    # Mode B: absolute ISO range (use INSTEAD of days)
    # until: "2026-01-01"
  scope:
    granularity: [file, method]
    include:
      - "src/main/java/**/*.java"     # single-module repos
      - "**/src/main/java/**/*.java"  # multi-module repos (list both if unsure)
    exclude:
      - "**/generated/**"
      - "**/test/**"
      - "**/build/**"
  scoring:
    decayHalfLifeDays: 90    # half-life for recency decay (days)
    excludeCoverage: false   # true → Composite = CC × Decay; coverage shown raw, not scored
  apiAnalysis:
    enabled: true            # off by default; required for api/shared granularities
    sharedComponentMode: BOTH        # CUMULATIVE | SEPARATE | BOTH
    classpathDirectories: []         # dirs with dependency jars/classes for symbol resolution
  jacocoReportPath: build/reports/jacoco/test/jacocoTestReport.xml   # optional
output:
  formats: [csv, yaml, md, html]   # case-insensitive; ≥1 required
  apiLayout: BOTH          # COMBINED (into hotspots.*) | STANDALONE (api_report.*) | BOTH
  coverageBreakdown: false # true → also write coverage_breakdown.yml: the audit
                           # trail behind every coverage number (per-file counts;
                           # per-endpoint per-method covered/executable lines)
  path: ./hotspot-report
  topN: 30                 # 0 = all rows

Env vars substitute as ${VAR_NAME} in any string value; YAML comment lines (#) are left untouched.

sharedComponentMode

• CUMULATIVE — shared methods counted inside every endpoint's aggregate; no separate list.
• SEPARATE — shared methods excluded from endpoint aggregates and reported once on their own.
• BOTH (default) — endpoint aggregates include them and a separate shared list is emitted.

analyze options

Exit codes: 0 ok · 1 config/pipeline failure · 2 usage error · 3 --strict empty result.

Decision rules (IF → THEN)

• IF the user wants the order to write API tests in THEN read

api_report.yml and iterate apiHotspots by ascending compositeRank.

• IF apiHotspots is empty but the app clearly has endpoints THEN check,

in order: apiAnalysis.enabled: true, controllers carry @RestController/@Controller + a mapping annotation, and apiAnalysis.classpathDirectories includes the dependency jars/classes so cross-type calls resolve. Do not report "no endpoints".

• IF every coverageMultiplier is 10 (or every lineCoverage is 0)

THEN the JaCoCo report doesn't match the analyzed sources — supply a report from the same build/module; do not conclude "nothing is tested".

• IF the summary shows Files: 0 THEN fix scope.include (single-module

needs src/main/java/**/*.java, multi-module needs **/src/main/java/**/*.java; list both).

• IF the summary shows Commits: 0 THEN widen window.days or switch to

absolute window.since/window.until overlapping real activity.

• IF target.type is github THEN clone the repo locally and re-run with

target.type: local-git (Phase 1 wires only local-git end-to-end).

• IF running in CI THEN pass --strict so an empty result fails loudly.
• IF you only need observational coverage, not coverage-driven scoring

THEN set scoring.excludeCoverage: true (Composite becomes CC × Decay).

Anti-patterns & pitfalls

• Don't fabricate or estimate the ranking. Run the jar and read the actual

api_report.yml; the whole point is determinism, not a model guess.

• Don't treat an empty `apiHotspots` as "no endpoints." It almost always

means apiAnalysis is off or the call graph couldn't resolve (missing classpathDirectories).

• Don't feed a JaCoCo report from a different module/build. Path mismatch

reads as 0% coverage → every multiplier maxes at 10 and the ranking is bogus.

• Don't run the jar on JDK < 21 — it's compiled for 21 (UnsupportedClassVersionError).
• Don't analyze generated or build output — keep **/generated/**,

**/build/**, **/target/**, **/test/** in scope.exclude.

• Don't present the Composite Score as a verdict. It's prioritization

evidence; surface the factors (churn, recency, complexity, coverage) so the choice is explainable.

• Don't reorder by Simple Score when the goal is risk. compositeRank, not

simpleRank, is the test-priority signal.

Testing

The project's own suite exercises every layer (parser, scoring, output, E2E):

./gradlew test            # comprehensive; run before trusting a build

Skill-level smoke check — analyze this very repo and assert a non-empty result:

bash -n skills/hotspot-analysis/scripts/get-jar.sh skills/hotspot-analysis/scripts/run-analysis.sh
JAR="$(skills/hotspot-analysis/scripts/get-jar.sh)"   # resolves/downloads the jar
java -jar "$JAR" init -o /tmp/h.yml -f
# set analysis.target.path in /tmp/h.yml to this repo's absolute path, then:
java -jar "$JAR" analyze --config /tmp/h.yml --strict
echo "exit=$?"   # 0 = produced output; 3 = empty (misconfigured)

A green ./gradlew test plus a 0 exit on the smoke run means the skill's toolchain is sound end-to-end.

Changelog

• 0.1.4 — endpoint coverage is now line-weighted (Σcovered/Σexecutable over

the call graph) instead of a mean of per-method ratios, so a large untested method can no longer hide behind a small covered one; new opt-in output.coverageBreakdown writes coverage_breakdown.yml, the calculation trace behind every coverage number; releases enforce 4-way version consistency (tag = gradle = CLI = plugin/marketplace manifests).

• 0.1.3 — one-click release button + skills-validation CI gate + tag

protection; the button reliably fans out to jar/image via workflow_call (a GITHUB_TOKEN-created release doesn't re-trigger event workflows).

• 0.1.2 — releases are now event-driven: every published release (incl. one

created by gh skill publish) auto-attaches hotspot.jar and builds the Docker image, so a new release never breaks the download. license added to frontmatter.

• 0.1.1 — distribute the jar via GitHub Releases (version-stable

hotspot.jar asset) + ghcr Docker image; a missing jacocoReportPath now warns and disables coverage instead of silently penalizing every artifact.

• 0.1.0 — initial skill: file / method / REST API endpoint / shared-component

prioritization driving the Phase 1 CLI; RestAssured consumption guide; apiAnalysis + JaCoCo + --strict exposed; per-granularity scoring docs.

References

• API report field schema: references/api-report-schema.md.
• Scoring derivations: docs/scoring/.
• Jar resolver / wrapper: scripts/get-jar.sh · scripts/run-analysis.sh.
• Prebuilt jar: GitHub Releases.
• Project README and docs/ (architecture, advanced techniques, theory).
• Adam Tornhill, Your Code as a Crime Scene.