agent-cfml-check 0.2.0 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@
 
 ## Current status
 
-Version `0.2.0` extends the `0.1.1` structural profile with parameter and exception tags. The implementation checks:
+Version `0.3.0` extends the structural profile with transaction and switch tags and adds inspection workflows. The implementation checks:
 
 - paired CFML tag nesting;
 - `cfelse` and `cfelseif` ownership and ordering;
@@ -69,6 +69,15 @@ agent-cfml-check capabilities [--json] [--pretty]
 agent-cfml-check check --root <directory> <file> [--json] [--pretty]
 ```
 
+Version `0.3.0` provides `inspect` for one or more explicit files, scoped line findings, and an explicit before/after comparison:
+
+```text
+agent-cfml-check inspect --root <directory> <file> [file ...] [--lines <start:end>] --json
+agent-cfml-check inspect --root <directory> --baseline <before-file> <after-file> --json
+```
+
+`inspect` uses its own v2 result schema. It can continue after bounded unsupported tags, but the result remains incomplete and findings are provisional. A line range filters reported findings while the whole file is scanned for context; unsupported syntax elsewhere still makes the result incomplete. Comparison classifications use conservative diagnostic signatures and may be `uncertain`; they do not prove a semantic regression or code identity. This functionality is not in the published `0.2.0` artifact.
+
 Check limits can be overridden with `--max-source-bytes`, `--max-nesting`, `--max-findings`, `--max-output-bytes`, and `--time-limit-ms`, subject to the hard caps reported by `capabilities`.
 
 `max_output_bytes` must be at least 512, reserving a complete failure envelope.
@@ -76,11 +85,11 @@ CLI ceilings count actual UTF-8 stdout, including indentation and the final
 newline. If pretty output cannot fit, checking returns incomplete/exit 3 and may
 emit its failure envelope as compact JSON. Default fitting output is unchanged.
 
-The checker requires one explicit root and one `.cfm` or `.cfc` file. JSON mode emits one envelope on stdout; diagnostics stay on stderr. A completed check with structural violations still exits `0` and reports `data.verdict: "violations"`. Exit `3` means unsupported syntax, insufficient evidence, or a resource limit. Exit `4` means an explicit-root or access-policy rejection. See [SPEC.md](SPEC.md) for the complete contract.
+The `check` command requires one explicit root and one `.cfm` or `.cfc` file. JSON mode emits one envelope on stdout; diagnostics stay on stderr. A completed check with structural violations still exits `0` and reports `data.verdict: "violations"`. Exit `3` means unsupported syntax, insufficient evidence, or a resource limit. Exit `4` means an explicit-root or access-policy rejection. See [SPEC.md](SPEC.md) for the complete contract.
 
 ## Safety and boundaries
 
-The checker never executes CFML or JavaScript from the inspected source, follows includes, reads directories as input, uses the network, installs packages, or modifies the inspected source tree. It reads exactly one regular UTF-8 source file under the explicit root, rejects symlink escapes, and fails closed when the bounded profile cannot establish a result.
+The checker never executes CFML or JavaScript from the inspected source, follows includes, reads directories as input, uses the network, installs packages, or modifies the inspected source tree. `check` reads exactly one regular UTF-8 source file under the explicit root; `inspect` reads only the explicitly selected files under that root. Both reject symlink escapes and report incomplete when the bounded profile cannot establish a result.
 
 The supported profile is `cfml-structure-v1`. Unknown/custom/imported tags, optional-body semantics outside the catalog, full expression and runtime semantics, SQL/HTML validity, CFML tag islands inside `cfscript`, and engine behavior are outside the profile or explicitly unverified.
 
@@ -100,4 +109,4 @@ The supported profile is `cfml-structure-v1`. Unknown/custom/imported tags, opti
 - `dist/`: generated package output;
 - `DESIGN.md`, `EPIC.md`, `ROADMAP.md`, `TASK.md`, `GOAL.md`, `PROGRESS.md`, `GOAL_PROMPT.md`, `CHANGELOG.md`: repository design, planning, status, and maintenance documents.
 
-`package.json` includes `dist`, `README.md`, `SPEC.md`, `schema`, and `fixtures` in the package; the design, planning, progress, goal, prompt, changelog, and Agent Skill documents remain repository-maintainer documentation. The repository exposes the TypeScript library through `main`, `types`, and `exports`. The source package version is `0.2.0`.
+`package.json` includes `dist`, `README.md`, `SPEC.md`, `schema`, and `fixtures` in the package; the design, planning, progress, goal, prompt, changelog, and Agent Skill documents remain repository-maintainer documentation. The repository exposes the TypeScript library through `main`, `types`, and `exports`. The source package version is `0.3.0`.

package/SPEC.md

@@ -1,13 +1,13 @@
 # Agent CFML Check Specification
 
 **Status:** frozen feasibility contract for implementation baseline `c76b8be`, extended by release hardening
-**Tool version:** `0.2.0`
+**Tool version:** `0.3.0`
 **Profile:** `cfml-structure-v1`
 **Envelope schema:** `schema/agent-cfml-check-result-v1.schema.json`
 
 ## 1. Scope
 
-The tool performs deterministic, read-only structural checks on exactly one explicitly selected local UTF-8 `.cfm` or `.cfc` file under an explicitly supplied root. It does not execute CFML, resolve includes, inspect a directory as source input, use the network, or modify the inspected source tree.
+The v1 `check` operation performs deterministic, read-only structural checks on exactly one explicitly selected local UTF-8 `.cfm` or `.cfc` file under an explicitly supplied root. The `inspect` operation accepts multiple explicitly selected files under one root. Neither operation executes CFML, resolves includes, inspects a directory as source input, uses the network, or modifies the inspected source tree.
 
 A completed result proves only the checks listed in that result. It does not prove Lucee or Adobe ColdFusion execution compatibility.
 
@@ -22,7 +22,7 @@ agent-cfml-check check --root <directory> <file> [--json] [--pretty]
 
 `capabilities` reports the profile, operations, extensions, tag catalogue, effective default limits, and exclusions. The CLI does not accept a file, root, or check-limit override for this operation.
 
-`check` requires exactly one explicit root and one `.cfm` or `.cfc` file. `--pretty` requires `--json`. `--help` prints usage and `--version` prints `0.2.0`; neither may be combined with other options.
+`check` requires exactly one explicit root and one `.cfm` or `.cfc` file. `--pretty` requires `--json`. `--help` prints usage and `--version` prints `0.3.0`; neither may be combined with other options.
 
 ### TypeScript interface
 
@@ -32,6 +32,14 @@ The TypeScript `capabilities(limitsInput)` API may receive limit overrides, whil
 
 ## 3. Supported structures
 
+### Inspection extension
+
+Version `0.3.0` additionally recognizes `cftransaction`, `cfswitch`, `cfcase`, and `cfdefaultcase`. A switch case must belong to the directly open switch, which can contain at most one default case. For transactions, absent or literal `begin` action is treated as a paired body; literal `commit`, `rollback`, and `setsavepoint` are treated as bodyless. Dynamic, duplicate, attribute-collection, or otherwise unrecognized transaction attributes return incomplete. This checks tag structure only, not database transaction behavior. These additions are not part of the published `0.2.0` artifact.
+
+The opt-in `inspect` operation uses `schema/agent-cfml-inspect-result-v2.schema.json` and does not alter the v1 `check` envelope. It accepts one to 32 explicitly named source files under one root, an optional `--lines start:end`, or a `--baseline` file plus one current file. Relative file paths are resolved against the selected root; all paths use the existing source reader. Scope is recorded per file; the scanner reads the entire file for surrounding context, then filters findings to the requested range. Unsupported syntax anywhere in the scanned file makes that file incomplete, and its findings are provisional. Recoverable unsupported tags and CFScript tag islands are located and scanning continues; unterminated lexical constructs can stop scanning, reflected by `scan_complete: false`. No incomplete file receives a `pass` verdict.
+
+Inspection reports file, position, related opener and a non-automatic hint. It uses the existing per-file byte and nesting limits, a shared time limit, a 16 MiB aggregate source limit, a 32-file cap, and the output limit. When output cannot fit, results are withheld rather than truncated into apparent success. For a baseline comparison, the complete baseline is compared with findings in the current file's requested range; line numbers may have shifted. Unique matches of finding code and normalized source/opening lines are `existing`; findings with a code absent from the complete baseline are `new`; ambiguous or incomplete cases are `uncertain`. The response includes `comparison_basis` to state that these are diagnostic-signature classifications, not proof of semantic identity, causation, or runtime behavior. Baseline and current files must both be explicitly selected under the root; each is read as an individually verified snapshot rather than a simultaneous filesystem snapshot. `0` means inspection completed, including findings; `3` means incomplete, and input/security errors retain their applicable exit code.
+
 ### Paired bodies
 
 `cfcatch`, `cfcomponent`, `cffinally`, `cffunction`, `cfif`, `cfloop`, `cfoutput`, `cfquery`, `cfsavecontent`, `cfscript`, `cfsilent`, and `cftry` require matching closing tags in this profile. Self-closing spellings of paired tags return incomplete; this does not assert that every CFML engine rejects them.

package/dist/cli/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { capabilities, checkFile, fitOutput } from "../core/checker.js";
+import { inspectMain } from "./inspect.js";
 import { DEFAULT_LIMITS } from "../core/limits.js";
 import { ToolFailure } from "../schema/errors.js";
 import { TOOL_ID, TOOL_VERSION } from "../schema/types.js";
@@ -10,9 +11,11 @@ const HELP = `agent-cfml-check — deterministic, read-only structural checks fo
 Usage:
   agent-cfml-check capabilities [--json] [--pretty]
   agent-cfml-check check --root <directory> <file> [--json] [--pretty]
+  agent-cfml-check inspect --root <directory> <file> [file ...] [--lines <start:end>] [--json] [--pretty]
+  agent-cfml-check inspect --root <directory> --baseline <file> <current-file> [--json] [--pretty]
 
-The checker reads exactly one .cfm or .cfc file under the explicit root. It never
-executes CFML, follows includes, uses the network, or modifies source files.
+Check reads one file; inspect reads only explicitly selected files under the root.
+The tool never executes CFML, follows includes, uses the network, or modifies sources.
 `;
 function parseInteger(value, name) {
     if (!/^\d+$/u.test(value))
@@ -115,6 +118,8 @@ function renderText(envelope) {
     return `${lines.join("\n")}\n`;
 }
 export function main(argv = process.argv.slice(2)) {
+    if (argv[0] === "inspect")
+        return inspectMain(argv.slice(1));
     try {
         const args = parseArgs(argv);
         if (args.help) {

package/dist/cli/inspect.d.ts

@@ -0,0 +1 @@
+export declare function inspectMain(argv: readonly string[]): number;

package/dist/cli/inspect.js

@@ -0,0 +1,108 @@
+import { inspectFiles } from "../core/inspect.js";
+import { DEFAULT_LIMITS } from "../core/limits.js";
+import { ToolFailure } from "../schema/errors.js";
+import { TOOL_ID, TOOL_VERSION } from "../schema/types.js";
+const HELP = `agent-cfml-check inspect --root <directory> <file> [file ...] [--lines <start:end>] [--json] [--pretty]\nagent-cfml-check inspect --root <directory> --baseline <file> <current-file> [--lines <start:end>] [--json] [--pretty]\n`;
+function safeText(value) {
+    return value.replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/gu, (character) => `\\u${character.codePointAt(0).toString(16).padStart(4, "0")}`);
+}
+function errorResult(failure) {
+    return { schema_version: "2.0.0", tool: { id: TOOL_ID, version: TOOL_VERSION }, status: failure.exitCode === 3 ? "incomplete" : "error", complete: false, mode: "inspect", files: [], comparison: null, comparison_basis: null, errors: [{ code: failure.code, message: failure.message }], limits: DEFAULT_LIMITS };
+}
+function textResult(result) {
+    const lines = [`${result.status}: ${result.mode}`];
+    for (const file of result.files) {
+        lines.push(`${safeText(file.path)}: ${file.status}${file.range === null ? "" : ` (lines ${file.range.start}-${file.range.end})`}`);
+        for (const item of [...file.unsupported, ...file.findings]) {
+            const location = item.location === null ? "" : `:${item.location.start.line}:${item.location.start.column}`;
+            lines.push(`  ${safeText(item.file)}${location}: ${item.code}: ${safeText(item.message)} [${item.confidence}]`);
+            if (item.related_open !== null)
+                lines.push(`    opening: ${item.related_open.start.line}:${item.related_open.start.column}`);
+            lines.push(`    hint: ${item.hint}`);
+        }
+        for (const error of file.errors)
+            lines.push(`  ${error.code}: ${safeText(error.message)}`);
+    }
+    if (result.comparison !== null) {
+        if (result.comparison_basis !== null)
+            lines.push(result.comparison_basis);
+        for (const item of result.comparison)
+            lines.push(`  ${item.classification}: ${item.finding.code} at ${item.finding.location?.start.line ?? "unknown"}`);
+    }
+    for (const error of result.errors)
+        lines.push(`${error.code}: ${safeText(error.message)}`);
+    return `${lines.join("\n")}\n`;
+}
+export function inspectMain(argv) {
+    let json = argv.includes("--json");
+    let pretty = false;
+    try {
+        if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) {
+            process.stdout.write(HELP);
+            return 0;
+        }
+        const options = { root: "", files: [], limits: {} };
+        const seen = new Set();
+        const limitFlags = { "--max-source-bytes": "max_source_bytes", "--max-nesting": "max_nesting", "--max-findings": "max_findings", "--max-output-bytes": "max_output_bytes", "--time-limit-ms": "time_limit_ms" };
+        for (let index = 0; index < argv.length; index += 1) {
+            const arg = argv[index];
+            if (arg === "--json" || arg === "--pretty") {
+                if (seen.has(arg))
+                    throw new ToolFailure("INVALID_ARGUMENT", `Duplicate option ${arg}`, 2);
+                seen.add(arg);
+                if (arg === "--json")
+                    json = true;
+                else
+                    pretty = true;
+                continue;
+            }
+            if (arg === "--root" || arg === "--baseline" || arg === "--lines" || limitFlags[arg] !== undefined) {
+                if (seen.has(arg))
+                    throw new ToolFailure("INVALID_ARGUMENT", `Duplicate option ${arg}`, 2);
+                seen.add(arg);
+                const value = argv[++index];
+                if (value === undefined || value.startsWith("--"))
+                    throw new ToolFailure("INVALID_ARGUMENT", `${arg} requires a value`, 2);
+                if (arg === "--root")
+                    options.root = value;
+                else if (arg === "--baseline")
+                    options.baseline = value;
+                else if (arg === "--lines") {
+                    const match = /^(\d+):(\d+)$/u.exec(value);
+                    if (match === null)
+                        throw new ToolFailure("INVALID_ARGUMENT", "--lines requires start:end", 2);
+                    options.range = { start: Number(match[1]), end: Number(match[2]) };
+                }
+                else {
+                    if (!/^\d+$/u.test(value) || !Number.isSafeInteger(Number(value)))
+                        throw new ToolFailure("INVALID_ARGUMENT", `${arg} requires an integer`, 2);
+                    options.limits[limitFlags[arg]] = Number(value);
+                }
+                continue;
+            }
+            if (arg.startsWith("-"))
+                throw new ToolFailure("INVALID_ARGUMENT", `Unknown option ${arg}`, 2);
+            options.files.push(arg);
+        }
+        if (pretty && !json)
+            throw new ToolFailure("INVALID_ARGUMENT", "--pretty requires --json", 2);
+        const checked = inspectFiles(options);
+        let result = checked.result;
+        let output = json ? `${JSON.stringify(result, null, pretty ? 2 : undefined)}\n` : textResult(result);
+        let exitCode = checked.exit_code;
+        if (Buffer.byteLength(output) > result.limits.max_output_bytes) {
+            result = { ...result, status: "incomplete", complete: false, files: [], comparison: null, errors: [{ code: "LIMIT_EXCEEDED", message: "The output limit was reached; partial results were withheld" }] };
+            output = json ? `${JSON.stringify(result)}\n` : textResult(result);
+            exitCode = 3;
+        }
+        process.stdout.write(output);
+        return exitCode;
+    }
+    catch (error) {
+        const failure = error instanceof ToolFailure ? error : new ToolFailure("INTERNAL_ERROR", "The inspection failed without a safe result", 1);
+        const result = errorResult(failure);
+        process.stdout.write(json ? `${JSON.stringify(result)}\n` : textResult(result));
+        process.stderr.write(`error: ${failure.code}: ${safeText(failure.message)}\n`);
+        return failure.exitCode;
+    }
+}

package/dist/core/checker.js

@@ -27,7 +27,7 @@ export function capabilities(limitsInput) {
         complete: true,
         data: {
             profile: PROFILE_ID,
-            operations: ["capabilities", "check"],
+            operations: ["capabilities", "check", "inspect"],
             extensions: [".cfm", ".cfc"],
             supported_tags: {
                 paired_bodies: [...PAIRED_TAGS].sort(),

package/dist/core/inspect.d.ts

@@ -0,0 +1,62 @@
+import { TOOL_ID, TOOL_VERSION } from "../schema/types.js";
+import type { CheckLimits, SourceInfo, SourceLocation } from "../schema/types.js";
+export interface LineRange {
+    start: number;
+    end: number;
+}
+export interface InspectOptions {
+    root: string;
+    files: string[];
+    range?: LineRange;
+    baseline?: string;
+    limits?: Partial<CheckLimits>;
+}
+export interface InspectDiagnostic {
+    code: string;
+    message: string;
+    file: string;
+    location: SourceLocation | null;
+    related_open: SourceLocation | null;
+    hint: string;
+    confidence: "confirmed" | "provisional";
+}
+export interface InspectedFile {
+    path: string;
+    status: "ok" | "incomplete" | "error";
+    complete: boolean;
+    scan_complete: boolean;
+    verdict: "pass" | "violations" | null;
+    source: SourceInfo | null;
+    range: LineRange | null;
+    findings: InspectDiagnostic[];
+    unsupported: InspectDiagnostic[];
+    errors: Array<{
+        code: string;
+        message: string;
+    }>;
+}
+export interface InspectResult {
+    schema_version: "2.0.0";
+    tool: {
+        id: typeof TOOL_ID;
+        version: typeof TOOL_VERSION;
+    };
+    status: "ok" | "incomplete" | "error";
+    complete: boolean;
+    mode: "inspect" | "compare";
+    files: InspectedFile[];
+    comparison: Array<{
+        finding: InspectDiagnostic;
+        classification: "existing" | "new" | "uncertain";
+    }> | null;
+    comparison_basis: string | null;
+    errors: Array<{
+        code: string;
+        message: string;
+    }>;
+    limits: CheckLimits;
+}
+export declare function inspectFiles(options: InspectOptions): {
+    result: InspectResult;
+    exit_code: number;
+};

package/dist/core/inspect.js

@@ -0,0 +1,167 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { checkPureScriptCfc } from "./lexer.js";
+import { normalizeLimits } from "./limits.js";
+import { loadSource } from "./source-reader.js";
+import { ToolFailure } from "../schema/errors.js";
+import { TOOL_ID, TOOL_VERSION } from "../schema/types.js";
+const MAX_FILES = 32;
+const MAX_TOTAL_SOURCE_BYTES = 16 * 1024 * 1024;
+const HINTS = {
+    UNEXPECTED_CLOSE: "Check whether this closing tag has an opening tag.",
+    MISMATCHED_CLOSE: "Check nesting and close the most recently opened tag first.",
+    UNCLOSED_TAG: "Check whether the matching closing tag is missing.",
+    INVALID_BRANCH: "Check the branch owner and ordering.",
+    UNTERMINATED_STRING: "Check the string's closing quote.",
+    UNTERMINATED_COMMENT: "Check the comment's closing delimiter.",
+    UNBALANCED_DELIMITER: "Check the matching script delimiter.",
+};
+function inRange(location, range) {
+    return range === undefined || location === null || (location.start.line <= range.end && location.end.line >= range.start);
+}
+function inspectOne(root, file, limits, deadline, range) {
+    try {
+        const selected = path.isAbsolute(file) ? file : path.resolve(root, file);
+        const loaded = loadSource({ root, file: selected, limits });
+        if (range !== undefined) {
+            const lines = loaded.source.split(/\r\n|\r|\n/u).length;
+            if (!Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 1 || range.end < range.start || range.end > lines) {
+                throw new ToolFailure("INVALID_ARGUMENT", "The requested line range is invalid for the selected source", 2);
+            }
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw new ToolFailure("LIMIT_EXCEEDED", "The inspection time limit was reached", 3);
+        const scan = checkPureScriptCfc(loaded.source, path.extname(loaded.relative_path), { ...limits, time_limit_ms: remaining }, true);
+        if (Date.now() > deadline)
+            throw new ToolFailure("LIMIT_EXCEEDED", "The inspection time limit was reached", 3);
+        const complete = scan.incomplete.length === 0 && scan.scan_complete;
+        const confidence = complete ? "confirmed" : "provisional";
+        const findings = scan.findings.filter((item) => inRange(item.location, range)).map((item) => ({
+            ...item, file: loaded.relative_path, hint: HINTS[item.code], confidence,
+        }));
+        const unsupported = scan.incomplete.map((item) => ({
+            code: item.code, message: item.message, file: loaded.relative_path,
+            location: item.location ?? null, related_open: null,
+            hint: "Review the unsupported or incomplete syntax before relying on structural findings.", confidence: "provisional",
+        }));
+        return {
+            result: {
+                path: loaded.relative_path, status: complete ? "ok" : "incomplete", complete,
+                scan_complete: scan.scan_complete, verdict: complete ? (findings.length === 0 ? "pass" : "violations") : null,
+                source: { path: loaded.relative_path, sha256: createHash("sha256").update(loaded.bytes).digest("hex"), byte_size: loaded.bytes.byteLength, encoding: "utf-8", bom: loaded.bom },
+                range: range ?? null, findings, unsupported, errors: [],
+            },
+            sourceText: loaded.source, exitCode: complete ? 0 : 3, bytes: loaded.bytes.byteLength,
+        };
+    }
+    catch (error) {
+        const failure = error instanceof ToolFailure ? error : new ToolFailure("INTERNAL_ERROR", "The checker failed without a safe result", 1);
+        return {
+            result: { path: file, status: failure.exitCode === 3 ? "incomplete" : "error", complete: false, scan_complete: false, verdict: null, source: null, range: range ?? null, findings: [], unsupported: [], errors: [{ code: failure.code, message: failure.message }] },
+            sourceText: "", exitCode: failure.exitCode, bytes: 0,
+        };
+    }
+}
+function signature(finding, lines) {
+    const line = finding.location === null ? "" : (lines[finding.location.start.line - 1] ?? "").trim();
+    const opening = finding.related_open === null ? "" : (lines[finding.related_open.start.line - 1] ?? "").trim();
+    return createHash("sha256").update(JSON.stringify([finding.code, line, opening])).digest("hex");
+}
+function compare(before, after) {
+    const prior = before.result.findings;
+    const current = after.result.findings;
+    if (!before.result.complete || !after.result.complete)
+        return current.map((finding) => ({ finding, classification: "uncertain" }));
+    const beforeLines = before.sourceText.split(/\r\n|\r|\n/u);
+    const afterLines = after.sourceText.split(/\r\n|\r|\n/u);
+    const beforeCounts = new Map();
+    const afterCounts = new Map();
+    const priorCodes = new Set(prior.map((item) => item.code));
+    for (const item of prior) {
+        const key = signature(item, beforeLines);
+        beforeCounts.set(key, (beforeCounts.get(key) ?? 0) + 1);
+    }
+    for (const item of current) {
+        const key = signature(item, afterLines);
+        afterCounts.set(key, (afterCounts.get(key) ?? 0) + 1);
+    }
+    return current.map((finding) => {
+        const key = signature(finding, afterLines);
+        const earlier = beforeCounts.get(key) ?? 0;
+        const later = afterCounts.get(key) ?? 0;
+        if (earlier === 1 && later === 1)
+            return { finding, classification: "existing" };
+        if (earlier === 0 && !priorCodes.has(finding.code))
+            return { finding, classification: "new" };
+        return { finding, classification: "uncertain" };
+    });
+}
+export function inspectFiles(options) {
+    let limits;
+    try {
+        limits = normalizeLimits(options?.limits);
+    }
+    catch (error) {
+        const failure = error instanceof ToolFailure ? error : new ToolFailure("INVALID_LIMIT", "Invalid limits", 2);
+        return { result: { schema_version: "2.0.0", tool: { id: TOOL_ID, version: TOOL_VERSION }, status: "error", complete: false, mode: "inspect", files: [], comparison: null, comparison_basis: null, errors: [{ code: failure.code, message: failure.message }], limits: normalizeLimits(undefined) }, exit_code: failure.exitCode };
+    }
+    const mode = options?.baseline === undefined ? "inspect" : "compare";
+    const result = { schema_version: "2.0.0", tool: { id: TOOL_ID, version: TOOL_VERSION }, status: "ok", complete: true, mode, files: [], comparison: null, comparison_basis: mode === "compare" ? "Diagnostic signatures are heuristic matches, not proof of semantic identity or causation." : null, errors: [], limits };
+    const range = options?.range;
+    const invalidRange = range !== undefined && (range === null || typeof range !== "object" || !Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 1 || range.end < range.start);
+    if (!options || typeof options.root !== "string" || !options.root || !Array.isArray(options.files) || options.files.length < 1 || options.files.length > MAX_FILES || options.files.some((file) => typeof file !== "string" || !file) || (mode === "compare" && (options.files.length !== 1 || typeof options.baseline !== "string" || !options.baseline))) {
+        result.status = "error";
+        result.complete = false;
+        result.errors.push({ code: "INVALID_ARGUMENT", message: "Select one to 32 explicit files; comparison requires exactly one current file and one baseline" });
+        return { result, exit_code: 2 };
+    }
+    if (invalidRange) {
+        result.status = "error";
+        result.complete = false;
+        result.errors.push({ code: "INVALID_ARGUMENT", message: "The line range must contain positive ordered integers" });
+        return { result, exit_code: 2 };
+    }
+    const names = options.baseline === undefined ? options.files : [options.baseline, options.files[0]];
+    const internal = [];
+    const deadline = Date.now() + limits.time_limit_ms;
+    let totalBytes = 0;
+    for (const [index, name] of names.entries()) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0 || totalBytes >= MAX_TOTAL_SOURCE_BYTES) {
+            result.status = "incomplete";
+            result.complete = false;
+            result.errors.push({ code: "LIMIT_EXCEEDED", message: "The aggregate inspection limit was reached; remaining files were not scanned" });
+            break;
+        }
+        // A changed line range belongs to the current source; baseline line numbers
+        // may have shifted, so compare against the entire baseline.
+        const selectedRange = mode === "compare" && index === 0 ? undefined : options.range;
+        const item = inspectOne(options.root, name, { ...limits, max_source_bytes: Math.min(limits.max_source_bytes, MAX_TOTAL_SOURCE_BYTES - totalBytes), time_limit_ms: remaining }, deadline, selectedRange);
+        totalBytes += item.bytes;
+        internal.push(item);
+        result.files.push(item.result);
+    }
+    const failed = internal.find((item) => item.exitCode === 4) ?? internal.find((item) => item.exitCode === 1) ?? internal.find((item) => item.exitCode !== 0 && item.exitCode !== 3);
+    if (failed !== undefined) {
+        result.status = "error";
+        result.complete = false;
+    }
+    else if (result.status !== "incomplete" && internal.some((item) => item.exitCode === 3)) {
+        result.status = "incomplete";
+        result.complete = false;
+    }
+    if (mode === "compare" && internal.length === 2 && Date.now() <= deadline)
+        result.comparison = compare(internal[0], internal[1]);
+    if (Date.now() > deadline && failed === undefined) {
+        result.status = "incomplete";
+        result.complete = false;
+        result.comparison = null;
+        result.errors.push({ code: "LIMIT_EXCEEDED", message: "The aggregate inspection time limit was reached" });
+    }
+    const exitCode = failed?.exitCode ?? (result.status === "incomplete" ? 3 : 0);
+    if (Buffer.byteLength(`${JSON.stringify(result)}\n`, "utf8") > limits.max_output_bytes) {
+        return { result: { ...result, status: "incomplete", complete: false, files: [], comparison: null, errors: [{ code: "LIMIT_EXCEEDED", message: "The output limit was reached; partial results were withheld" }] }, exit_code: 3 };
+    }
+    return { result, exit_code: exitCode };
+}

package/dist/core/lexer.d.ts

@@ -1,4 +1,4 @@
-import type { Finding } from "../schema/types.js";
+import type { Finding, SourceLocation } from "../schema/types.js";
 export declare const PAIRED_TAGS: Set<string>;
 export declare const BRANCH_TAGS: Set<string>;
 export declare const BODYLESS_TAGS: Set<string>;
@@ -6,23 +6,25 @@ interface ScriptRegion {
     content_start: number;
     content_end: number;
 }
-interface ScanResult {
+export interface ScanResult {
     findings: Finding[];
     incomplete: Array<{
         code: string;
         message: string;
+        location?: SourceLocation;
     }>;
     script_regions: ScriptRegion[];
     saw_cfml_tag: boolean;
+    scan_complete: boolean;
 }
 export declare function scanCfml(source: string, limits: {
     max_nesting: number;
     max_findings: number;
     time_limit_ms: number;
-}): ScanResult;
+}, recover?: boolean): ScanResult;
 export declare function checkPureScriptCfc(source: string, extension: string, limits: {
     max_nesting: number;
     max_findings: number;
     time_limit_ms: number;
-}): ScanResult;
+}, recover?: boolean): ScanResult;
 export {};

package/dist/core/lexer.js

@@ -13,6 +13,10 @@ export const PAIRED_TAGS = new Set([
     "cftry",
     "cfcatch",
     "cffinally",
+    "cftransaction",
+    "cfswitch",
+    "cfcase",
+    "cfdefaultcase",
 ]);
 export const BRANCH_TAGS = new Set(["cfelseif", "cfelse"]);
 export const BODYLESS_TAGS = new Set(["cfset", "cfreturn", "cfinclude", "cfargument", "cfqueryparam", "cfparam"]);
@@ -45,6 +49,34 @@ function consumeCfmlComment(source, start) {
     }
     return null;
 }
+// Transaction control actions can be bodyless. Only classify literal attributes;
+// dynamic attribute collections and expressions cannot safely establish a form.
+function transactionKind(attributes) {
+    const matcher = /\s*([A-Za-z_][A-Za-z0-9_:.-]*)\s*=\s*("(?:""|[^"])*"|'(?:''|[^'])*'|[^\s"'=<>`]+)\s*/gy;
+    let cursor = 0;
+    let action;
+    while (cursor < attributes.length) {
+        if (/^\s*$/u.test(attributes.slice(cursor)))
+            break;
+        matcher.lastIndex = cursor;
+        const match = matcher.exec(attributes);
+        if (match === null)
+            return "unknown";
+        const name = match[1]?.toLowerCase();
+        const raw = match[2];
+        if (name === undefined || raw === undefined || name === "attributecollection")
+            return "unknown";
+        if (name === "action") {
+            if (action !== undefined)
+                return "unknown";
+            action = (raw.startsWith('"') || raw.startsWith("'") ? raw.slice(1, -1) : raw).toLowerCase();
+        }
+        cursor = matcher.lastIndex;
+    }
+    if (action === undefined || action === "begin")
+        return "open";
+    return action === "commit" || action === "rollback" || action === "setsavepoint" ? "bodyless" : "unknown";
+}
 function parseTag(source, start) {
     const closing = source[start + 1] === "/";
     let cursor = closing ? start + 2 : start + 1;
@@ -52,6 +84,7 @@ function parseTag(source, start) {
     while (isNameCharacter(source[cursor]))
         cursor += 1;
     const name = source.slice(nameStart, cursor).toLowerCase();
+    const attributesStart = cursor;
     if (!name.startsWith("cf"))
         return { error: "NOT_CF_TAG", at: start };
     let quote = null;
@@ -91,13 +124,15 @@ function parseTag(source, start) {
             const selfClosing = source[beforeEnd] === "/";
             const kind = closing
                 ? "close"
-                : BRANCH_TAGS.has(name)
-                    ? "branch"
-                    : BODYLESS_TAGS.has(name)
-                        ? "bodyless"
-                        : PAIRED_TAGS.has(name)
-                            ? "open"
-                            : "unknown";
+                : name === "cftransaction"
+                    ? transactionKind(source.slice(attributesStart, selfClosing ? beforeEnd : cursor))
+                    : BRANCH_TAGS.has(name)
+                        ? "branch"
+                        : BODYLESS_TAGS.has(name)
+                            ? "bodyless"
+                            : PAIRED_TAGS.has(name)
+                                ? "open"
+                                : "unknown";
             return { token: { kind, name, start, end: cursor + 1, self_closing: selfClosing }, next: cursor + 1 };
         }
         cursor += 1;
@@ -201,10 +236,11 @@ function scanScriptDelimiters(context, start, end, findings) {
         addFinding(context, findings, finding(context, "UNBALANCED_DELIMITER", `Unclosed CFScript delimiter "${open.character}"`, open.start, open.start + 1));
     }
 }
-function scanScriptRegion(context, start) {
+function scanScriptRegion(context, start, recover = false) {
     let quote = null;
     let blockCommentStart = null;
     let cursor = start;
+    const issues = [];
     while (cursor < context.source.length) {
         checkDeadline(context, cursor);
         const character = context.source[cursor];
@@ -253,19 +289,26 @@ function scanScriptRegion(context, start) {
         if (startsCfTag(context.source, cursor)) {
             const parsed = parseTag(context.source, cursor);
             if ("error" in parsed)
-                return { close: null, content_end: cursor, incomplete: { code: parsed.error, message: `CFScript region cannot be parsed (${parsed.error})` } };
+                return { close: null, content_end: cursor, issues, incomplete: { code: parsed.error, message: `CFScript region cannot be parsed (${parsed.error})` } };
             if (parsed.token.name === "cfscript" && parsed.token.kind === "close") {
-                return { close: parsed.token, content_end: cursor };
+                return { close: parsed.token, content_end: cursor, issues };
+            }
+            if (recover) {
+                if (issues.length >= context.max_findings)
+                    throw new ToolFailure("LIMIT_EXCEEDED", "The diagnostic limit was reached", 3);
+                issues.push({ code: "UNSUPPORTED_SYNTAX", message: `CFML tag island "${parsed.token.name}" inside cfscript is outside the supported profile`, start: cursor, end: parsed.next });
+                cursor = parsed.next;
+                continue;
             }
             return { close: null, content_end: cursor, incomplete: { code: "UNSUPPORTED_SYNTAX", message: "CFML tag island inside cfscript is outside the supported profile" } };
         }
         cursor += 1;
     }
     if (quote !== null)
-        return { close: null, content_end: context.source.length, incomplete: { code: "UNTERMINATED_STRING", message: "Unterminated CFScript string" } };
+        return { close: null, content_end: context.source.length, issues, incomplete: { code: "UNTERMINATED_STRING", message: "Unterminated CFScript string" } };
     if (blockCommentStart !== null)
-        return { close: null, content_end: context.source.length, incomplete: { code: "UNTERMINATED_COMMENT", message: "Unterminated CFScript block comment" } };
-    return { close: null, content_end: context.source.length, incomplete: { code: "UNTERMINATED_TAG", message: "cfscript has no closing tag" } };
+        return { close: null, content_end: context.source.length, issues, incomplete: { code: "UNTERMINATED_COMMENT", message: "Unterminated CFScript block comment" } };
+    return { close: null, content_end: context.source.length, issues, incomplete: { code: "UNTERMINATED_TAG", message: "cfscript has no closing tag" } };
 }
 function processTag(context, token, stack, findings) {
     if (token.kind === "unknown") {
@@ -311,7 +354,19 @@ function processTag(context, token, stack, findings) {
                     current.try_finally_seen = true;
             }
         }
-        stack.push({ name: token.name, start: token.start, end: token.end, branch_else_seen: false, try_handler_seen: false, try_finally_seen: false });
+        if (token.name === "cfcase" || token.name === "cfdefaultcase") {
+            const current = stack[stack.length - 1];
+            if (current?.name !== "cfswitch") {
+                addFinding(context, findings, finding(context, "INVALID_BRANCH", `${token.name} must belong to the directly open cfswitch`, token.start, token.end));
+            }
+            else if (token.name === "cfdefaultcase") {
+                if (current.switch_default_seen) {
+                    addFinding(context, findings, finding(context, "INVALID_BRANCH", "cfswitch cannot contain more than one cfdefaultcase", token.start, token.end, current));
+                }
+                current.switch_default_seen = true;
+            }
+        }
+        stack.push({ name: token.name, start: token.start, end: token.end, branch_else_seen: false, try_handler_seen: false, try_finally_seen: false, switch_default_seen: false });
         return;
     }
     if (token.name === "cfscript" && stack[stack.length - 1]?.name !== "cfscript") {
@@ -335,21 +390,23 @@ function processTag(context, token, stack, findings) {
     }
     stack.pop();
 }
-export function scanCfml(source, limits) {
-    const index = new SourceIndex(source);
+export function scanCfml(source, limits, recover = false) {
+    const index = new SourceIndex(source, recover);
     const context = { source, index, deadline: Date.now() + limits.time_limit_ms, max_nesting: limits.max_nesting, max_findings: limits.max_findings };
     const findings = [];
     const incomplete = [];
     const script_regions = [];
     const stack = [];
     let saw_cfml_tag = false;
+    let scan_complete = true;
     let cursor = 0;
     while (cursor < source.length) {
         checkDeadline(context, cursor);
         if (source.startsWith("<!---", cursor)) {
             const end = consumeCfmlComment(source, cursor);
             if (end === null) {
-                incomplete.push({ code: "UNTERMINATED_COMMENT", message: `Unterminated CFML comment at line ${index.position(cursor).line}, column ${index.position(cursor).column}` });
+                incomplete.push({ code: "UNTERMINATED_COMMENT", message: `Unterminated CFML comment at line ${index.position(cursor).line}, column ${index.position(cursor).column}`, ...(recover ? { location: index.location(cursor, Math.min(cursor + 5, source.length)) } : {}) });
+                scan_complete = false;
                 break;
             }
             cursor = end;
@@ -362,17 +419,38 @@ export function scanCfml(source, limits) {
         saw_cfml_tag = true;
         const parsed = parseTag(source, cursor);
         if ("error" in parsed) {
-            incomplete.push({ code: parsed.error, message: `CFML tag cannot be parsed (${parsed.error}) at line ${index.position(parsed.at).line}, column ${index.position(parsed.at).column}` });
+            incomplete.push({ code: parsed.error, message: `CFML tag cannot be parsed (${parsed.error}) at line ${index.position(parsed.at).line}, column ${index.position(parsed.at).column}`, ...(recover ? { location: index.location(parsed.at, Math.min(parsed.at + 1, source.length)) } : {}) });
+            scan_complete = false;
             break;
         }
         const token = parsed.token;
+        if (recover && token.kind === "close" && !PAIRED_TAGS.has(token.name) && !BODYLESS_TAGS.has(token.name) && !BRANCH_TAGS.has(token.name)) {
+            if (incomplete.length >= limits.max_findings)
+                throw new ToolFailure("LIMIT_EXCEEDED", "The diagnostic limit was reached", 3);
+            incomplete.push({ code: "UNSUPPORTED_SYNTAX", message: `Unsupported CFML tag "${token.name}"`, location: index.location(token.start, token.end) });
+            cursor = parsed.next;
+            continue;
+        }
+        if (recover && token.kind === "open" && token.name === "cfscript" && token.self_closing) {
+            if (incomplete.length >= limits.max_findings)
+                throw new ToolFailure("LIMIT_EXCEEDED", "The diagnostic limit was reached", 3);
+            incomplete.push({ code: "UNSUPPORTED_SYNTAX", message: 'Paired tag "cfscript" cannot be self-closing', location: index.location(token.start, token.end) });
+            cursor = parsed.next;
+            continue;
+        }
         if (token.kind === "open" && token.name === "cfscript") {
             processTag(context, token, stack, findings);
-            const script = scanScriptRegion(context, token.end);
+            const script = scanScriptRegion(context, token.end, recover);
             scanScriptDelimiters(context, token.end, script.content_end, findings);
             script_regions.push({ content_start: token.end, content_end: script.content_end });
+            for (const issue of script.issues ?? []) {
+                if (incomplete.length >= limits.max_findings)
+                    throw new ToolFailure("LIMIT_EXCEEDED", "The diagnostic limit was reached", 3);
+                incomplete.push({ code: issue.code, message: issue.message, location: index.location(issue.start, issue.end) });
+            }
             if (script.incomplete !== undefined) {
-                incomplete.push({ code: script.incomplete.code, message: `${script.incomplete.message} at line ${index.position(script.content_end).line}, column ${index.position(script.content_end).column}` });
+                incomplete.push({ code: script.incomplete.code, message: `${script.incomplete.message} at line ${index.position(script.content_end).line}, column ${index.position(script.content_end).column}`, ...(recover ? { location: index.location(script.content_end, Math.min(script.content_end + 1, source.length)) } : {}) });
+                scan_complete = false;
                 break;
             }
             if (script.close !== null) {
@@ -381,27 +459,36 @@ export function scanCfml(source, limits) {
                 continue;
             }
         }
-        processTag(context, token, stack, findings);
+        try {
+            processTag(context, token, stack, findings);
+        }
+        catch (error) {
+            if (!recover || !(error instanceof ToolFailure) || error.code !== "UNSUPPORTED_SYNTAX")
+                throw error;
+            if (incomplete.length >= limits.max_findings)
+                throw new ToolFailure("LIMIT_EXCEEDED", "The diagnostic limit was reached", 3);
+            incomplete.push({ code: error.code, message: error.message, location: index.location(token.start, token.end) });
+        }
         cursor = parsed.next;
     }
     for (const open of stack.reverse()) {
         addFinding(context, findings, finding(context, "UNCLOSED_TAG", `Unclosed CFML tag "${open.name}"`, open.start, open.end, open));
     }
     findings.sort((left, right) => left.location.start_byte - right.location.start_byte || left.code.localeCompare(right.code));
-    return { findings, incomplete, script_regions, saw_cfml_tag };
+    return { findings, incomplete, script_regions, saw_cfml_tag, scan_complete };
 }
-export function checkPureScriptCfc(source, extension, limits) {
+export function checkPureScriptCfc(source, extension, limits, recover = false) {
     const leading = source.replace(/^\uFEFF/u, "").trimStart();
     const pureScript = extension.toLowerCase() === ".cfc" && /^(?:component|interface)\b/iu.test(leading);
     if (pureScript) {
-        const result = { findings: [], incomplete: [], script_regions: [], saw_cfml_tag: false };
-        const index = new SourceIndex(source);
+        const result = { findings: [], incomplete: [], script_regions: [], saw_cfml_tag: false, scan_complete: true };
+        const index = new SourceIndex(source, recover);
         const context = { source, index, deadline: Date.now() + limits.time_limit_ms, max_nesting: limits.max_nesting, max_findings: limits.max_findings };
         scanScriptDelimiters(context, 0, source.length, result.findings);
         result.findings.sort((left, right) => left.location.start_byte - right.location.start_byte || left.code.localeCompare(right.code));
         return result;
     }
-    const result = scanCfml(source, limits);
+    const result = scanCfml(source, limits, recover);
     if (extension.toLowerCase() !== ".cfc" || result.saw_cfml_tag)
         return result;
     if (!pureScript) {

package/dist/core/source-index.d.ts

@@ -3,7 +3,7 @@ export declare class SourceIndex {
     readonly source: string;
     private readonly byteOffsets;
     private readonly lineStarts;
-    constructor(source: string);
+    constructor(source: string, crAsNewline?: boolean);
     byteOffset(index: number): number;
     position(index: number): Position;
     location(start: number, end: number): SourceLocation;

package/dist/core/source-index.js

@@ -3,7 +3,7 @@ export class SourceIndex {
     source;
     byteOffsets;
     lineStarts = [0];
-    constructor(source) {
+    constructor(source, crAsNewline = false) {
         this.source = source;
         this.byteOffsets = new Uint32Array(source.length + 1);
         const encoder = new TextEncoder();
@@ -23,6 +23,8 @@ export class SourceIndex {
             this.byteOffsets[index] = byteOffset;
             if (character === "\n")
                 this.lineStarts.push(index);
+            else if (crAsNewline && character === "\r" && source[index] !== "\n")
+                this.lineStarts.push(index);
         }
     }
     byteOffset(index) {

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { capabilities, checkFile } from "./core/checker.js";
+export { inspectFiles } from "./core/inspect.js";
+export type { InspectOptions, InspectResult, InspectDiagnostic, InspectedFile, LineRange } from "./core/inspect.js";
 export { DEFAULT_LIMITS, HARD_LIMITS, normalizeLimits } from "./core/limits.js";
 export type * from "./schema/types.js";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { capabilities, checkFile } from "./core/checker.js";
+export { inspectFiles } from "./core/inspect.js";
 export { DEFAULT_LIMITS, HARD_LIMITS, normalizeLimits } from "./core/limits.js";

package/dist/schema/types.d.ts

@@ -1,5 +1,5 @@
 export declare const TOOL_ID: "agent-cfml-check";
-export declare const TOOL_VERSION: "0.2.0";
+export declare const TOOL_VERSION: "0.3.0";
 export declare const PROFILE_ID: "cfml-structure-v1";
 export interface Position {
     line: number;

package/dist/schema/types.js

@@ -1,3 +1,3 @@
 export const TOOL_ID = "agent-cfml-check";
-export const TOOL_VERSION = "0.2.0";
+export const TOOL_VERSION = "0.3.0";
 export const PROFILE_ID = "cfml-structure-v1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-cfml-check",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Deterministic, read-only structural checks for a bounded CFML subset.",
   "repository": {
     "type": "git",

package/schema/agent-cfml-inspect-result-v2.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:agent-cfml-check:inspect-result-v2",
+  "type": "object",
+  "required": ["schema_version", "tool", "status", "complete", "mode", "files", "comparison", "comparison_basis", "errors", "limits"],
+  "properties": {
+    "schema_version": { "const": "2.0.0" },
+    "tool": {
+      "type": "object", "required": ["id", "version"],
+      "properties": { "id": { "const": "agent-cfml-check" }, "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" } },
+      "additionalProperties": false
+    },
+    "status": { "enum": ["ok", "incomplete", "error"] },
+    "complete": { "type": "boolean" },
+    "mode": { "enum": ["inspect", "compare"] },
+    "files": { "type": "array", "maxItems": 32, "items": { "$ref": "#/$defs/file" } },
+    "comparison": { "anyOf": [{ "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/comparison" } }] },
+    "comparison_basis": { "type": ["string", "null"] },
+    "errors": { "type": "array", "items": { "$ref": "#/$defs/error" } },
+    "limits": { "$ref": "#/$defs/limits" }
+  },
+  "allOf": [
+    { "if": { "properties": { "status": { "const": "ok" } } }, "then": { "properties": { "complete": { "const": true }, "errors": { "maxItems": 0 }, "files": { "items": { "properties": { "complete": { "const": true } } } } } } },
+    { "if": { "properties": { "status": { "enum": ["incomplete", "error"] } } }, "then": { "properties": { "complete": { "const": false } } } }
+  ],
+  "additionalProperties": false,
+  "$defs": {
+    "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false },
+    "position": { "type": "object", "required": ["line", "column"], "properties": { "line": { "type": "integer", "minimum": 1 }, "column": { "type": "integer", "minimum": 1 } }, "additionalProperties": false },
+    "location": { "type": "object", "required": ["start", "end", "start_byte", "end_byte"], "properties": { "start": { "$ref": "#/$defs/position" }, "end": { "$ref": "#/$defs/position" }, "start_byte": { "type": "integer", "minimum": 0 }, "end_byte": { "type": "integer", "minimum": 0 } }, "additionalProperties": false },
+    "diagnostic": {
+      "type": "object", "required": ["code", "message", "file", "location", "related_open", "hint", "confidence"],
+      "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "file": { "type": "string" }, "location": { "anyOf": [{ "$ref": "#/$defs/location" }, { "type": "null" }] }, "related_open": { "anyOf": [{ "$ref": "#/$defs/location" }, { "type": "null" }] }, "hint": { "type": "string" }, "confidence": { "enum": ["confirmed", "provisional"] } },
+      "additionalProperties": false
+    },
+    "source": { "type": "object", "required": ["path", "sha256", "byte_size", "encoding", "bom"], "properties": { "path": { "type": "string" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byte_size": { "type": "integer", "minimum": 0 }, "encoding": { "const": "utf-8" }, "bom": { "type": "boolean" } }, "additionalProperties": false },
+    "range": { "type": "object", "required": ["start", "end"], "properties": { "start": { "type": "integer", "minimum": 1 }, "end": { "type": "integer", "minimum": 1 } }, "additionalProperties": false },
+    "file": {
+      "type": "object", "required": ["path", "status", "complete", "scan_complete", "verdict", "source", "range", "findings", "unsupported", "errors"],
+      "properties": { "path": { "type": "string" }, "status": { "enum": ["ok", "incomplete", "error"] }, "complete": { "type": "boolean" }, "scan_complete": { "type": "boolean" }, "verdict": { "enum": ["pass", "violations", null] }, "source": { "anyOf": [{ "$ref": "#/$defs/source" }, { "type": "null" }] }, "range": { "anyOf": [{ "$ref": "#/$defs/range" }, { "type": "null" }] }, "findings": { "type": "array", "items": { "$ref": "#/$defs/diagnostic" } }, "unsupported": { "type": "array", "items": { "$ref": "#/$defs/diagnostic" } }, "errors": { "type": "array", "items": { "$ref": "#/$defs/error" } } },
+      "allOf": [
+        { "if": { "properties": { "status": { "const": "ok" } } }, "then": { "properties": { "complete": { "const": true }, "verdict": { "enum": ["pass", "violations"] } } } },
+        { "if": { "properties": { "status": { "enum": ["incomplete", "error"] } } }, "then": { "properties": { "complete": { "const": false }, "verdict": { "type": "null" } } } }
+      ],
+      "additionalProperties": false
+    },
+    "comparison": { "type": "object", "required": ["finding", "classification"], "properties": { "finding": { "$ref": "#/$defs/diagnostic" }, "classification": { "enum": ["existing", "new", "uncertain"] } }, "additionalProperties": false },
+    "limits": { "type": "object", "required": ["max_source_bytes", "max_nesting", "max_findings", "max_output_bytes", "time_limit_ms"], "properties": { "max_source_bytes": { "type": "integer", "minimum": 1 }, "max_nesting": { "type": "integer", "minimum": 1 }, "max_findings": { "type": "integer", "minimum": 1 }, "max_output_bytes": { "type": "integer", "minimum": 512 }, "time_limit_ms": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }
+  }
+}