jade-core-scanner

Production-grade scanner that reads a breaking-changes manifest, scans workspace sources against rule patterns using regex, injects deterministic inline // JADE-FLAG:<rule_id> markers into matched sou

SKILL.md

GitHub

JADE Scanner — Deterministic Source Tagger

Objective

Read the breaking-changes manifest, match every rule pattern against workspace source files via regex, and inject inline // JADE-FLAG:<rule_id> <reason> <confidence> markers exactly once per matched location. Write a flag index and a human-readable scan summary.

Core constraints

  • Idempotent. Re-running on already-tagged sources must not create duplicate flags.
  • No prompt payload handoff. Scanner writes artifacts to disk; never dump source contents into context.
  • Atomic file writes. Only touching files that contain a new match; using temp-file + rename.
  • Deterministic. Same manifest + same workspace + same graph → byte-identical output every time (no volatile timestamps).

Required inputs

  • {artifacts}/01-breaking-changes-manifest.json
  • {artifacts}/02-linter-findings.json (optional — merged with manifest rules if present)
  • {artifacts}/03.5-knowledge-graph.json (optional — enriches each flag with advisory graph impact metadata when present and valid)
  • {workspace} — directory tree of source files to scan (e.g., migration-runs/sample/workspace)

Produced outputs

  • {artifacts}/04-flag-index.json — every injected flag with file/line/rule/confidence, plus additive graph impact metadata when a valid graph is available
  • {artifacts}/04-scan-summary.json — per-rule and per-confidence counts, total files touched
  • Tagged source files under {workspace} (modified in-place; only files with new matches)

Inline marker format

// JADE-FLAG:<rule_id> <reason> <confidence>

The scanner inserts this comment on the line after the matched line. If the matched line already ends with a comment the exact rule_id was already injected on, the scanner skips that location.

Example — before scan:

Vector agents = new Vector();

Example — after scan:

Vector agents = new Vector();
// JADE-FLAG:RAW_TYPES Raw collection instantiation (Vector) HIGH

Phase 0: Validate inputs

python3 .claude/skills/jade-scanner/scripts/scan_and_tag.py \
  --workspace "{workspace}" \
  --artifacts "{artifacts}" \
  --dry-run

A dry-run exits 0 when the manifest is valid and the workspace is readable. It writes nothing. If it fails, fix the manifest or workspace path before proceeding.


Phase 1: Full scan

python3 .claude/skills/jade-scanner/scripts/scan_and_tag.py \
  --workspace "{workspace}" \
  --artifacts "{artifacts}"

The scanner:

  1. Loads 01-breaking-changes-manifest.json and validates every rule and pattern.
  2. Loads 02-linter-findings.json (if present) and merges its entries as additional rules with rule_id prefixed LINT:.
  3. Walks the workspace, collecting only files whose extensions match at least one pattern's target_extensions list.
  4. For each candidate file, loads its contents into memory and tests every pattern line-by-line.
  5. When a pattern matches, checks whether a JADE-FLAG:<rule_id> comment already exists on the matched line or the line immediately after. If yes → skip (idempotent). If no → insert the flag comment on the next line and record the flag.
  6. Writes modified files back via temp-file + atomic rename.
  7. Writes 04-flag-index.json (every flag) and 04-scan-summary.json (aggregate stats).

Phase 2: Verify

After the scan completes, check the exit code and confirm outputs exist:

test -f {artifacts}/04-flag-index.json && echo "PASS" || echo "FAIL"
test -f {artifacts}/04-scan-summary.json && echo "PASS" || echo "FAIL"
python3 -c "import json; d=json.load(open('{artifacts}/04-flag-index.json')); print(f'Flags: {len(d[\"flags\"])}')"

A second run must produce the exact same flag count (zero new injections):

python3 .claude/skills/jade-scanner/scripts/scan_and_tag.py \
  --workspace "{workspace}" \
  --artifacts "{artifacts}"
# Exit code 0, summary.total_new_flags == 0, summary.idempotent_skips == previous total

Manifest schema (01-breaking-changes-manifest.json)

{
  "rules": [
    {
      "id": "RAW_TYPES",
      "name": "Raw Types to Generics",
      "severity": "HIGH",
      "patterns": [
        {
          "type": "regex",
          "pattern": "new\\s+(Vector|Hashtable|ArrayList|HashMap|LinkedList|HashSet)\\s*\\(\\)",
          "target_extensions": [".java"],
          "reason": "Raw collection instantiation",
          "confidence": "HIGH"
        }
      ]
    }
  ]
}

Pattern types supported: regex. Each target_extensions entry must include the leading dot.


Flag index schema (04-flag-index.json)

{
  "run_id": "sample-run",
  "workspace": "migration-runs/sample/workspace",
  "total_flags": 42,
  "total_files_scanned": 847,
  "flags": [
    {
      "rule_id": "RAW_TYPES",
      "file": "workspace/jade/core/Agent.java",
      "line": 142,
      "confidence": "HIGH",
      "reason": "Raw collection instantiation (HashMap)",
      "graph": {
        "source_artifact": "03.5-knowledge-graph.json",
        "node_exists": true,
        "declaration": "jade.core.Agent",
        "impact_files": ["jade/core/Container.java"],
        "artifact_diagnostics": {"parse_failures": 0, "unresolved_types": 0, "ambiguous_symbols": 0}
      }
    }
  ]
}

Scan summary schema (04-scan-summary.json)

{
  "run_id": "sample-run",
  "workspace": "migration-runs/sample/workspace",
  "total_files_scanned": 847,
  "total_new_flags": 42,
  "idempotent_skips": 0,
  "by_rule": {
    "RAW_TYPES": {
      "name": "Raw Types to Generics",
      "severity": "HIGH",
      "count": 30
    },
    "ENHANCED_FOR": {
      "name": "Enhanced For Loops",
      "severity": "MEDIUM",
      "count": 12
    }
  },
  "by_confidence": {
    "HIGH": 30,
    "MEDIUM": 12,
    "LOW": 0
  }
}

Constraints

  1. Never modify files outside {workspace}.
  2. Never inject a flag comment that already exists on the matched line or adjacent line.
  3. Never insert a flag into a comment block or Javadoc — only match within active code.
  4. Respect .gitignore exclusions when present under {workspace}.
  5. Exit non-zero on manifest parse errors or unreadable workspace.
  6. Always write artifacts via temp-file + atomic rename.

Exit criteria

  • scan_and_tag.py exits 0.
  • 04-flag-index.json and 04-scan-summary.json are valid JSON.
  • A second identical run produces zero new flags and equal idempotent_skips.