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.claude/skills/jade-core-scanner/SKILL.md
GitHubJADE 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 additivegraphimpact 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:
- Loads
01-breaking-changes-manifest.jsonand validates every rule and pattern. - Loads
02-linter-findings.json(if present) and merges its entries as additional rules with rule_id prefixedLINT:. - Walks the workspace, collecting only files whose extensions match at least one
pattern's
target_extensionslist. - For each candidate file, loads its contents into memory and tests every pattern line-by-line.
- 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. - Writes modified files back via temp-file + atomic rename.
- Writes
04-flag-index.json(every flag) and04-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
- Never modify files outside
{workspace}. - Never inject a flag comment that already exists on the matched line or adjacent line.
- Never insert a flag into a comment block or Javadoc — only match within active code.
- Respect
.gitignoreexclusions when present under{workspace}. - Exit non-zero on manifest parse errors or unreadable workspace.
- Always write artifacts via temp-file + atomic rename.
Exit criteria
scan_and_tag.pyexits 0.04-flag-index.jsonand04-scan-summary.jsonare valid JSON.- A second identical run produces zero new flags and equal
idempotent_skips.