From 9be6a96fd645cf7ab418398b9922c9b27966422e Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 15 Nov 2026 19:40:22 +0800 Subject: [PATCH] refactor(cli): project reconstruction and source-to-bundle documents from their contracts (#10697) * refactor(cli): project reconstruction ledger and coverage commands from their contracts * refactor(cli): project compare-source-to-bundle from its contract and refuse omitted document fields * fix(cli): advertise caller paths in JSON documents as the CLI admits them * fix(cli): advertise that JSON document caller paths exclude URLs * refactor(cli): narrow omitted document field refusal to object documents * test(cli): give the coverage document fixture the current evidence_format --- .../JavaScriptApplicationWorkflowService.ts | 12 +- .../javascript/SourceToBundleReference.ts | 8 +- src/cli/applicationCommands.ts | 132 ++++++-------- src/cli/contractCliDescription.ts | 72 +++++++- src/cli/contractCommand.ts | 34 ++++ src/cli/sourceToBundleCommand.ts | 105 ++++++------ src/cliJsonInput.ts | 15 +- .../applicationWorkflowInputContracts.ts | 18 +- .../compareSourceToBundle.ts | 1 - .../cli/cliContractCommandParity.test.ts | 2 + tests/boundary/cli/jsonInputSchema.test.ts | 161 +++++++++++++++--- tests/boundary/cli/jsonInputStatus.test.ts | 78 ++++++++- 12 files changed, 456 insertions(+), 182 deletions(-) diff --git a/src/application/javascript/JavaScriptApplicationWorkflowService.ts b/src/application/javascript/JavaScriptApplicationWorkflowService.ts index 76e6813890..1dfc553927 100644 --- a/src/application/javascript/JavaScriptApplicationWorkflowService.ts +++ b/src/application/javascript/JavaScriptApplicationWorkflowService.ts @@ -6,7 +6,6 @@ import { import { compareApplicationVersionsRequestSchema, compareJavaScriptExportShapesRequestSchema, - compareSourceToBundleCliInputSchema, compareSourceToBundleRequestSchema, traceApplicationFeatureRequestSchema, } from "../../contracts/javascript/applicationWorkflowInputContracts.js"; @@ -235,12 +234,12 @@ export const compareApplicationVersionsEvidence = ( /** Select the application record and historical graph through their shared owners. */ export const executeSourceToBundleComparison = async ( rawInput: unknown, - schema: - | typeof compareSourceToBundleCliInputSchema - | typeof compareSourceToBundleRequestSchema, lookup: EvidenceLookup | undefined, resources: ArtifactResourceScope, - options: Pick = {}, + options: Pick & { + /** The reference file path as the caller spelled it. */ + readonly requestedReferencePath?: string; + } = {}, ): Promise< Result< ApplicationWorkflowExecution, @@ -250,7 +249,7 @@ export const executeSourceToBundleComparison = async ( const selected = resolveEvidenceRequest( "compare_source_to_bundle", rawInput, - schema, + compareSourceToBundleRequestSchema, lookup, options, ); @@ -261,6 +260,7 @@ export const executeSourceToBundleComparison = async ( selected.value.input.reference, options.signal, resources, + options.requestedReferencePath, ); return reference.ok ? compareSourceToBundleEvidence({ diff --git a/src/application/javascript/SourceToBundleReference.ts b/src/application/javascript/SourceToBundleReference.ts index e62b8bba0d..7f19daa138 100644 --- a/src/application/javascript/SourceToBundleReference.ts +++ b/src/application/javascript/SourceToBundleReference.ts @@ -1,7 +1,7 @@ import { requireAuthenticationHeadroom } from "../JsonAuthenticationHeadroom.js"; import { setImmediate } from "node:timers/promises"; import type { z } from "zod"; -import type { compareSourceToBundleCliInputSchema } from "../../contracts/javascript/applicationWorkflowInputContracts.js"; +import type { compareSourceToBundleRequestSchema } from "../../contracts/javascript/applicationWorkflowInputContracts.js"; import { historicalSourceGraphSchema, type HistoricalSourceGraph, @@ -25,9 +25,11 @@ export type ResolvedSourceToBundleReference = { /** Resolve one caller-selected historical graph using the shared bounded regular-file reader. No file cache. */ export const resolveSourceToBundleReference = async ( - reference: z.output["reference"], + reference: z.output["reference"], signal?: AbortSignal, resources?: ArtifactResourceScope, + /** The file path as the caller spelled it, when an adapter resolved it. */ + requestedPath?: string, ): Promise> => { if (isAborted(signal)) return err(cancelledBy("compare_source_to_bundle", signal)); @@ -71,7 +73,7 @@ export const resolveSourceToBundleReference = async ( reference_source: { kind: "file", path: read.value.path, - requested_path: reference.path, + requested_path: requestedPath ?? reference.path, }, }); }; diff --git a/src/cli/applicationCommands.ts b/src/cli/applicationCommands.ts index ea87380266..4e28e09b5d 100644 --- a/src/cli/applicationCommands.ts +++ b/src/cli/applicationCommands.ts @@ -1,21 +1,15 @@ import { registerPlaywrightTraceCommand } from "./playwrightTraceCommand.js"; import { registerApiContractCommand } from "./apiContractCommand.js"; import { registerNtfsJournalCommand } from "./ntfsJournalCommand.js"; -import { Cli, z } from "incur"; +import { Cli } from "incur"; import { CLI_COMMANDS } from "../cliCommandNames.js"; -import { parseCliJsonInput } from "../cliJsonInput.js"; -import { logCliCommand } from "../cliLogging.js"; import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import type { JsonValue } from "../domain/jsonValue.js"; import type { Logger } from "pino"; import { registerSourceToBundleCommand } from "./sourceToBundleCommand.js"; import { registerStaticObservedEndpointsCommand } from "./staticObservedEndpointsCommand.js"; -import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js"; -import { reconstructionCoverageRequestSchema } from "../domain/reconstructionCoverageInput.js"; -import { reconstructionObligationLedgerRequestSchema } from "../application/ReconstructionObligationLedgerRequest.js"; -import { jsonInputArgument } from "./jsonInputArgument.js"; import { APPLICATION_TOOL_CONTRACTS } from "../contracts/applicationToolContracts.js"; import { contractNamed } from "./contractCliDescription.js"; import { registerContractDocumentCommand } from "./contractCommand.js"; @@ -166,99 +160,73 @@ export const registerApplicationCommands = ( }); }; +/** + * Inline reconstruction workflows. Each owner authenticates its embedded + * Evidence bundle itself, so the handler passes the decoded document on. + */ +const registerReconstructionDocumentCommand = < + Operation extends + | "build_reconstruction_obligation_ledger" + | "evaluate_reconstruction_coverage", +>( + cli: CliInstance, + logger: Logger, + operation: Operation, + command: string, + description: string, + workflow: ( + input: unknown, + ) => Promise< + | { readonly ok: true; readonly value: JsonValue } + | { readonly ok: false; readonly error: AnalysisError } + >, +): void => + registerContractDocumentCommand( + cli, + logger, + contractNamed(APPLICATION_TOOL_CONTRACTS, operation), + { command, description, document: workflowJsonDescription }, + async (input) => { + const result = await workflow(input); + return result.ok + ? result.value + : { + error: "Application workflow failed", + ...projectAnalysisError(result.error, "invocation"), + }; + }, + ); + const registerObligationLedgerCommand = ( cli: CliInstance, logger: Logger, ): void => - registerJsonCommand({ + registerReconstructionDocumentCommand( cli, logger, - name: CLI_COMMANDS.buildReconstructionObligationLedger, - description: - "Generate a deterministic Evidence-backed reconstruction obligation ledger page", - inputSchema: z.unknown(), - documentSchema: reconstructionObligationLedgerRequestSchema, - workflow: async (input) => { + "build_reconstruction_obligation_ledger", + CLI_COMMANDS.buildReconstructionObligationLedger, + "Generate a deterministic Evidence-backed reconstruction obligation ledger page", + async (input) => { const { buildReconstructionObligationLedgerEvidence } = await import("../application/ReconstructionObligationLedgerService.js"); return buildReconstructionObligationLedgerEvidence(input); }, - }); + ); const registerCoverageCommand = (cli: CliInstance, logger: Logger): void => - registerJsonCommand({ + registerReconstructionDocumentCommand( cli, logger, - name: CLI_COMMANDS.evaluateReconstructionCoverage, - description: "Evaluate inline fail-closed reconstruction coverage", - inputSchema: z.unknown(), - documentSchema: reconstructionCoverageRequestSchema, - workflow: async (input) => { + "evaluate_reconstruction_coverage", + CLI_COMMANDS.evaluateReconstructionCoverage, + "Evaluate inline fail-closed reconstruction coverage", + async (input) => { const { evaluateReconstructionCoverage } = await import("../application/ReconstructionCoverageService.js"); return evaluateReconstructionCoverage(input); }, - }); - -interface JsonCommandOptions { - readonly cli: CliInstance; - readonly logger: Logger; - readonly name: string; - readonly description: string; - readonly inputSchema: Schema; - /** Contract advertised by `--schema`. Runtime parsing stays `inputSchema`. */ - readonly documentSchema?: z.ZodType; - readonly workflow: ( - input: z.output, - ) => Promise< - | { readonly ok: true; readonly value: JsonValue } - | { readonly ok: false; readonly error: AnalysisError } - >; -} - -const registerJsonCommand = ({ - cli, - logger, - name, - description, - inputSchema, - documentSchema, - workflow, -}: JsonCommandOptions): void => { - cli.command(name, { - description, - args: z.object({ - inputJson: jsonInputArgument( - workflowJsonDescription, - documentSchema ?? inputSchema, - ), - }), - run: ({ args }) => - logCliCommand(logger, name, async () => { - const input = await parseCliJsonInput(args.inputJson, name); - if (!input.ok) return input.error; - const parsed = inputSchema.safeParse(input.value); - if (!parsed.success) - return { - error: "Application workflow failed", - ...projectAnalysisError( - analysisInputErrorFromIssues( - name, - parsed.error.issues, - input.value, - ), - ), - }; - const result = await workflow(parsed.data); - return result.ok - ? result.value - : { - error: "Application workflow failed", - ...projectAnalysisError(result.error, "invocation"), - }; - }), - }); -}; + ); /** Evidence consumers share one explicit portable source and cancellation lifetime. */ const registerEvidenceJsonCommand = ({ diff --git a/src/cli/contractCliDescription.ts b/src/cli/contractCliDescription.ts index 10577d91e7..c7b3259d1d 100644 --- a/src/cli/contractCliDescription.ts +++ b/src/cli/contractCliDescription.ts @@ -13,6 +13,7 @@ import { } from "./analysisEvidenceDelivery.js"; import { parseCliJsonOption } from "./cliJsonOption.js"; import { getEvidenceInputContract } from "../domain/evidenceInputContract.js"; +import { cliJsonCallerPathSchema } from "../cliJsonInput.js"; import { safeParseJson } from "../domain/safeJson.js"; import { cliDecimalShape } from "./options.js"; @@ -611,6 +612,72 @@ export interface ContractCliDocumentDescription { ) => Readonly>; } +/** + * The document field at `path` as the CLI admits it: a caller path the + * command resolves against the working directory, so a relative spelling is + * admitted where the contract requires an absolute one. Unions and wrappers + * keep their other branches; clones keep the source's registry metadata. + */ +const admitDocumentCallerPath = ( + schema: z.ZodType, + path: readonly string[], +): z.ZodType => { + const [head, ...tail] = path; + if (head === undefined) { + const admitted = + core(schema) instanceof z.ZodArray + ? z.array(cliJsonCallerPathSchema) + : cliJsonCallerPathSchema; + const field = admitsOmission(schema) ? admitted.optional() : admitted; + return schema.description === undefined + ? field + : field.describe(schema.description); + } + if ( + schema instanceof z.ZodOptional || + schema instanceof z.ZodExactOptional || + schema instanceof z.ZodDefault || + schema instanceof z.ZodPrefault || + schema instanceof z.ZodNullable || + schema instanceof z.ZodReadonly + ) + return z.clone( + schema, + { + ...schema.def, + innerType: admitDocumentCallerPath(schema.unwrap() as z.ZodType, path), + }, + { parent: true }, + ); + if (schema instanceof z.ZodUnion) + return z.clone( + schema, + { + ...schema.def, + options: schema.options.map((option) => + admitDocumentCallerPath(option as z.ZodType, path), + ), + }, + { parent: true }, + ); + if (schema instanceof z.ZodObject && Object.hasOwn(schema.shape, head)) + return z.clone( + schema, + { + ...schema.def, + shape: { + ...schema.shape, + [head]: admitDocumentCallerPath( + schema.shape[head] as z.ZodType, + tail, + ), + }, + }, + { parent: true }, + ); + return schema; +}; + /** The CLI key of a JSON input document. */ const DOCUMENT_KEY = "inputJson"; @@ -646,6 +713,9 @@ export const describeContractDocumentCommand = < ) as never, ); } + const callerPaths = projection.callerPaths ?? []; + for (const path of callerPaths) + admitted = admitDocumentCallerPath(admitted, path); const cliOptions: CliOptionShape = projection.cliOptions ?? {}; if (Object.hasOwn(cliOptions, DOCUMENT_KEY)) throw new Error(`${contract.name} projects two fields to one CLI key`); @@ -656,7 +726,7 @@ export const describeContractDocumentCommand = < key: DOCUMENT_KEY, documentDescription: projection.document, content: getEvidenceInputContract(admitted).frameSchema, - callerPaths: projection.callerPaths ?? [], + callerPaths, omitted, cliOnlyOptions: Object.entries(cliOptions).map(([key, schema]) => ({ key, diff --git a/src/cli/contractCommand.ts b/src/cli/contractCommand.ts index 4c972c645a..af8bf03e64 100644 --- a/src/cli/contractCommand.ts +++ b/src/cli/contractCommand.ts @@ -4,6 +4,7 @@ import type { Logger } from "pino"; import { logCliCommand } from "../cliLogging.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; +import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js"; import type { DirectAnalysis } from "../composition/directAnalysis.js"; import type { CallerInputPaths, Evidence } from "../domain/evidence.js"; import type { JsonValue } from "../domain/jsonValue.js"; @@ -329,6 +330,28 @@ export const contractDocumentCommandDescriptions = ( ): readonly ContractCliDocumentDescription[] => documentDescriptions.get(cli) ?? []; +/** + * A document field the projection omits is refused with its reason rather + * than passed to an owner that would act on it. + */ +const omittedDocumentFieldError = ( + operation: string, + omitted: Readonly>, + document: object, +): AnalysisError | undefined => { + const issues = Object.entries(omitted) + .filter(([field]) => Object.hasOwn(document, field)) + .map(([field, reason]) => ({ + code: "custom" as const, + path: [field], + message: `${field} is not accepted by this command: ${reason}`, + input: (document as Readonly>)[field], + })); + return issues.length === 0 + ? undefined + : analysisInputErrorFromIssues(operation, issues, document); +}; + /** * Register one CLI command whose whole contract input is one JSON document. * The handler receives the decoded document with its caller paths made @@ -378,6 +401,17 @@ export const registerContractDocumentCommand = < signal, ); if (!decoded.ok) return decoded.error; + // A document that is not an object has no fields to refuse; the + // contract refuses it. + const refused = + typeof decoded.value === "object" && decoded.value !== null + ? omittedDocumentFieldError( + contract.name, + description.omitted, + decoded.value, + ) + : undefined; + if (refused !== undefined) return projectAnalysisError(refused); return run( resolveCliJsonPaths(decoded.value, description.callerPaths), { diff --git a/src/cli/sourceToBundleCommand.ts b/src/cli/sourceToBundleCommand.ts index 4a71c947be..727415ad27 100644 --- a/src/cli/sourceToBundleCommand.ts +++ b/src/cli/sourceToBundleCommand.ts @@ -1,63 +1,70 @@ -import { z } from "incur"; import type { Logger } from "pino"; import type { CliInstance } from "./types.js"; import { CLI_COMMANDS } from "../cliCommandNames.js"; -import { parseCliJsonInput } from "../cliJsonInput.js"; -import { logCliCommand } from "../cliLogging.js"; -import { compareSourceToBundleCliInputSchema } from "../contracts/javascript/applicationWorkflowInputContracts.js"; -import { getEvidenceInputContract } from "../domain/evidenceInputContract.js"; -import { withCommandCancellation } from "./commandCancellation.js"; -import { jsonInputArgument } from "./jsonInputArgument.js"; +import { APPLICATION_TOOL_CONTRACTS } from "../contracts/applicationToolContracts.js"; +import { contractNamed } from "./contractCliDescription.js"; +import { registerContractDocumentCommand } from "./contractCommand.js"; import { evidenceBundleOption, runEvidenceInputCommand, } from "./evidenceInputCommand.js"; +/** The reference file path exactly as the caller spelled it, if any. */ +const spelledReferencePath = (document: unknown): string | undefined => { + if (typeof document !== "object" || document === null) return undefined; + const reference = (document as { readonly reference?: unknown }).reference; + if (typeof reference !== "object" || reference === null) return undefined; + const path = (reference as { readonly path?: unknown }).path; + return typeof path === "string" ? path : undefined; +}; + /** CLI file transport delegates graph authentication and comparison to the same owners as MCP. */ export const registerSourceToBundleCommand = ( cli: CliInstance, logger: Logger, -): void => { - const name = CLI_COMMANDS.compareSourceToBundle; - cli.command(name, { - description: - "Compare historical source (inline graph or reference {kind:file,path}) with authenticated application Evidence. Save the complete JSON to query with inspect-analysis-view.", - args: z.object({ - inputJson: jsonInputArgument( - "Inline workflow JSON or JSON file path", - getEvidenceInputContract(compareSourceToBundleCliInputSchema) - .frameSchema, - ), - }), - options: z.object({ evidenceBundle: evidenceBundleOption }), - run: ({ args, options }) => - withCommandCancellation((signal) => - logCliCommand(logger, name, async () => { - const input = await parseCliJsonInput(args.inputJson, name, signal); - if (!input.ok) return input.error; - const result = await runEvidenceInputCommand( - "compare_source_to_bundle", - options.evidenceBundle, - signal, - async (lookup, resources) => { - const { executeSourceToBundleComparison } = - await import("../application/javascript/JavaScriptApplicationWorkflowService.js"); - const compared = await executeSourceToBundleComparison( - input.value, - compareSourceToBundleCliInputSchema, - lookup, - resources, - { signal }, - ); - return compared.ok - ? { ok: true, value: compared.value.evidence } - : compared; +): void => + registerContractDocumentCommand( + cli, + logger, + contractNamed(APPLICATION_TOOL_CONTRACTS, "compare_source_to_bundle"), + { + command: CLI_COMMANDS.compareSourceToBundle, + description: + "Compare historical source (inline graph or reference {kind:file,path}) with authenticated application Evidence. Save the complete JSON to query with inspect-analysis-view.", + document: "Inline workflow JSON or JSON file path", + callerPaths: [["reference", "path"]], + omit: { + view: "A one-shot command retains no session Evidence for a selected view; save the complete comparison and query it with inspect-analysis-view", + }, + cliOptions: { evidenceBundle: evidenceBundleOption }, + }, + async (document, { signal, operation, spelled, cliOptions }) => { + const requestedReferencePath = spelledReferencePath(spelled); + const result = await runEvidenceInputCommand( + operation, + cliOptions.evidenceBundle, + signal, + async (lookup, resources) => { + const { executeSourceToBundleComparison } = + await import("../application/javascript/JavaScriptApplicationWorkflowService.js"); + const compared = await executeSourceToBundleComparison( + document, + lookup, + resources, + { + signal, + ...(requestedReferencePath === undefined + ? {} + : { requestedReferencePath }), }, ); - return result.ok - ? result.value - : { error: "Application workflow failed", ...result.error }; - }), - ), - }); -}; + return compared.ok + ? { ok: true, value: compared.value.evidence } + : compared; + }, + ); + return result.ok + ? result.value + : { error: "Application workflow failed", ...result.error }; + }, + ); diff --git a/src/cliJsonInput.ts b/src/cliJsonInput.ts index 4031066adb..fa8ea88ab7 100644 --- a/src/cliJsonInput.ts +++ b/src/cliJsonInput.ts @@ -3,6 +3,7 @@ import type { Readable } from "node:stream"; import { getHeapStatistics } from "node:v8"; import { absoluteCallerPath } from "./filesystem/callerPath.js"; +import { localPathStringSchema } from "./domain/localPath.js"; import { sealOwnedJsonInput } from "./application/OwnedJsonInput.js"; import { @@ -263,7 +264,19 @@ const accessDeniedSystemCode = ( * A `file:` URL or `scheme://` URL is not an operator-relative filesystem path. * One-letter prefixes stay paths so Windows drive paths resolve normally. */ -const URL_REFERENCE = /^(?:file:|[A-Za-z][A-Za-z0-9+.-]+:\/\/)/iu; +const URL_REFERENCE_SOURCE = "(?:[Ff][Ii][Ll][Ee]:|[A-Za-z][A-Za-z0-9+.-]+://)"; +const URL_REFERENCE = new RegExp(`^${URL_REFERENCE_SOURCE}`, "u"); + +/** + * A caller-path field of a CLI JSON document as the CLI admits it: any + * nonempty local spelling, which it resolves, but not a URL, which it leaves + * for the contract to refuse. The pattern spells case-insensitivity out so + * JSON Schema, which carries no regex flags, advertises the same rule. + */ +export const cliJsonCallerPathSchema = localPathStringSchema.regex( + new RegExp(`^(?!${URL_REFERENCE_SOURCE})`, "u"), + "must be a local path, not a URL", +); /** * Resolve named string fields of CLI-supplied JSON against the operator diff --git a/src/contracts/javascript/applicationWorkflowInputContracts.ts b/src/contracts/javascript/applicationWorkflowInputContracts.ts index c5448d1bc9..847d917e64 100644 --- a/src/contracts/javascript/applicationWorkflowInputContracts.ts +++ b/src/contracts/javascript/applicationWorkflowInputContracts.ts @@ -1,7 +1,4 @@ -import { - absoluteLocalPathStringSchema, - localPathStringSchema, -} from "../../domain/localPath.js"; +import { absoluteLocalPathStringSchema } from "../../domain/localPath.js"; import { sourceToBundleViewRequestSchema } from "../../domain/analysisView/sourceToBundleView.js"; import { featureTraceViewRequestSchema } from "../../domain/analysisView/featureTraceView.js"; import { z } from "zod"; @@ -85,9 +82,10 @@ export const compareApplicationVersionsRequestSchema = z.strictObject({ right: evidenceInputSchema, }); +/** Historical graph JSON is a transport alternative to the inline graph, authenticated by the same graph parser. */ const referenceFile = z.strictObject({ kind: z.literal("file"), - path: localPathStringSchema, + path: absoluteLocalPathStringSchema, }); const sourceToBundleSelection = { view: z @@ -97,19 +95,11 @@ const sourceToBundleSelection = { ]) .optional(), }; -/** Historical graph JSON is a transport alternative to the inline graph, authenticated by the same graph parser. */ -export const compareSourceToBundleCliInputSchema = z.strictObject({ - reference: z.union([ - compareSourceToBundleInputSchema.shape.reference, - referenceFile, - ]), - application: evidenceInputSchema, -}); /** The MCP host accepts absolute local paths; omitted view preserves the full report. */ export const compareSourceToBundleRequestSchema = z.strictObject({ reference: z.union([ compareSourceToBundleInputSchema.shape.reference, - referenceFile.extend({ path: absoluteLocalPathStringSchema }), + referenceFile, ]), application: evidenceInputSchema, ...sourceToBundleSelection, diff --git a/src/server/registerApplicationTools/compareSourceToBundle.ts b/src/server/registerApplicationTools/compareSourceToBundle.ts index 9abc80aa06..f3f3688675 100644 --- a/src/server/registerApplicationTools/compareSourceToBundle.ts +++ b/src/server/registerApplicationTools/compareSourceToBundle.ts @@ -40,7 +40,6 @@ export const registerCompareSourceToBundleTool = ( () => executeSourceToBundleComparison( input, - contract.inputSchema, options.evidenceById, options.artifactResources, { signal: context.mcpReq.signal }, diff --git a/tests/boundary/cli/cliContractCommandParity.test.ts b/tests/boundary/cli/cliContractCommandParity.test.ts index f893c7ebd6..b4ab38ced1 100644 --- a/tests/boundary/cli/cliContractCommandParity.test.ts +++ b/tests/boundary/cli/cliContractCommandParity.test.ts @@ -768,6 +768,8 @@ describe("JSON-document contract commands", () => { "compare-artifacts", "inspect-analysis-view", "match-native-functions", + "build-reconstruction-obligation-ledger", + "evaluate-reconstruction-coverage", ]), ); }); diff --git a/tests/boundary/cli/jsonInputSchema.test.ts b/tests/boundary/cli/jsonInputSchema.test.ts index 11478550bf..0f26762d6c 100644 --- a/tests/boundary/cli/jsonInputSchema.test.ts +++ b/tests/boundary/cli/jsonInputSchema.test.ts @@ -9,7 +9,7 @@ import { artifactComparisonInputSchema } from "../../../src/contracts/artifactCo import { compareApplicationVersionsRequestSchema, compareJavaScriptExportShapesRequestSchema, - compareSourceToBundleCliInputSchema, + compareSourceToBundleRequestSchema, compareStaticObservedEndpointsFactsSchema, reconcileJavaScriptRuntimeRequestSchema, traceApplicationFeatureRequestSchema, @@ -19,8 +19,8 @@ import { getEvidenceBundleInputSchema, importEvidenceBundleInputSchema, } from "../../../src/contracts/sessionToolSchemas.js"; -import { reconstructionCoverageRequestSchema } from "../../../src/domain/reconstructionCoverageInput.js"; -import { reconstructionObligationLedgerRequestSchema } from "../../../src/application/ReconstructionObligationLedgerRequest.js"; +import { reconstructionCoverageEvaluationInputSchema } from "../../../src/domain/reconstructionCoverageInput.js"; +import { reconstructionObligationLedgerInputSchema } from "../../../src/domain/reconstructionObligationLedgerSchemas.js"; import { inspectAnalysisViewInputSchema } from "../../../src/domain/analysisView/analysisViewRequest.js"; import { browserScenarioSchema } from "../../../src/domain/browserScenario.js"; import { getEvidenceInputContract } from "../../../src/domain/evidenceInputContract.js"; @@ -36,6 +36,7 @@ import { jsonInputArgument, jsonInputContentSchema, } from "../../../src/cli/jsonInputArgument.js"; +import { cliJsonCallerPathSchema } from "../../../src/cliJsonInput.js"; import { visitRegisteredCommands } from "../../../src/cli/visitRegisteredCommands.js"; import type { CliInstance } from "../../../src/cli/types.js"; @@ -51,7 +52,12 @@ const inventoryDocumentSchema = frame( ); /** Every positional JSON document and the schema its handler parses. */ -const documents = [ +const documents: readonly { + readonly command: string; + readonly schema: z.ZodType; + /** Fields the CLI resolves against the working directory before parsing. */ + readonly callerPaths?: readonly (readonly string[])[]; +}[] = [ { command: CLI_COMMANDS.traceApplicationFeature, schema: frame(traceApplicationFeatureRequestSchema), @@ -70,7 +76,8 @@ const documents = [ }, { command: CLI_COMMANDS.compareSourceToBundle, - schema: frame(compareSourceToBundleCliInputSchema), + schema: frame(compareSourceToBundleRequestSchema.omit({ view: true })), + callerPaths: [["reference", "path"]], }, { command: CLI_COMMANDS.compareJavaScriptExportShapes, @@ -78,11 +85,11 @@ const documents = [ }, { command: CLI_COMMANDS.buildReconstructionObligationLedger, - schema: reconstructionObligationLedgerRequestSchema, + schema: reconstructionObligationLedgerInputSchema, }, { command: CLI_COMMANDS.evaluateReconstructionCoverage, - schema: reconstructionCoverageRequestSchema, + schema: reconstructionCoverageEvaluationInputSchema, }, { command: CLI_COMMANDS.projectAndroidApplicationGraph, @@ -103,10 +110,16 @@ const documents = [ { command: CLI_COMMANDS.inspectAnalysisView, schema: inspectAnalysisViewInputSchema, + callerPaths: [["source", "path"]], }, { command: CLI_COMMANDS.captureElectronScenario, schema: electronActiveObservationInputSchema, + callerPaths: [ + ["executable_path"], + ["application_path"], + ["application_root"], + ], }, { command: CLI_COMMANDS.reconcileJavaScriptRuntime, @@ -131,6 +144,10 @@ const documents = [ { command: CLI_COMMANDS.compareArtifacts, schema: artifactComparisonInputSchema, + callerPaths: [ + ["left", "path"], + ["right", "path"], + ], }, { command: CLI_COMMANDS.compareWasmInterfaces, @@ -210,18 +227,66 @@ const advertisedInput = (stdout: string): InputJsonSchema => { return inputJson as InputJsonSchema; }; +type JsonSchemaNode = Record; + +const cliCallerPath = jsonInputContentSchema( + cliJsonCallerPathSchema, +) as JsonSchemaNode; + +/** Expect a caller path as the CLI admits it: any nonempty local spelling. */ +const admitRelativePath = ( + schema: JsonSchemaNode, + path: readonly string[], +): JsonSchemaNode => { + const [head, ...tail] = path; + if (head === undefined) { + const { allOf: _patterns, pattern: _pattern, ...rest } = schema; + return { ...rest, ...cliCallerPath }; + } + const branches = (["anyOf", "oneOf"] as const).flatMap((keyword) => + Array.isArray(schema[keyword]) + ? [ + [ + keyword, + (schema[keyword] as JsonSchemaNode[]).map((branch) => + admitRelativePath(branch, path), + ), + ] as const, + ] + : [], + ); + const properties = schema.properties as + | Record + | undefined; + return { + ...schema, + ...Object.fromEntries(branches), + ...(properties?.[head] === undefined + ? {} + : { + properties: { + ...properties, + [head]: admitRelativePath(properties[head], tail), + }, + }), + }; +}; + it("advertises the parsed document for every JSON-input command", async () => { const ajv = new Ajv2020({ strict: false, validateFormats: false }); expect(jsonInputCommands(cli).sort()).toEqual( documents.map(({ command }) => command).sort(), ); - for (const { command, schema } of documents) { + for (const { command, schema, callerPaths = [] } of documents) { const served = await serve([command, "--schema", "--json"]); expect(served.exitCode, served.stdout).toBe(0); const inputJson = advertisedInput(served.stdout); expect(inputJson.contentSchema, command).toBeDefined(); expect(inputJson.contentSchema, command).toEqual( - jsonInputContentSchema(schema), + callerPaths.reduce( + admitRelativePath, + jsonInputContentSchema(schema) as JsonSchemaNode, + ), ); expect(inputJson.contentSchema, command).not.toEqual({}); expect( @@ -231,6 +296,25 @@ it("advertises the parsed document for every JSON-input command", async () => { } }); +it("advertises caller paths as local spellings the CLI resolves, not URLs", async () => { + const input = advertisedInput( + (await serve([CLI_COMMANDS.compareSourceToBundle, "--schema", "--json"])) + .stdout, + ); + const validate = new Ajv2020({ + strict: false, + validateFormats: false, + }).compile(input.contentSchema as AnySchema); + const document = (path: string) => ({ + reference: { kind: "file", path }, + application: {}, + }); + for (const path of ["ref.json", "./file:ref.json", "C:\\ref.json"]) + expect(validate(document(path)), path).toBe(true); + for (const path of ["file:ref.json", "FILE:ref.json", "https://x/ref.json"]) + expect(validate(document(path)), path).toBe(false); +}); + it("validates representative parsed documents with the advertised schema", async () => { const input = advertisedInput( ( @@ -245,20 +329,45 @@ it("validates representative parsed documents with the advertised schema", async strict: false, validateFormats: false, }).compile(input.contentSchema as AnySchema); - const accepted = { coverage: { arbitrary: true }, boundary_id: "main" }; + const evidence_bundle = { + evidence_format: 1, + artifacts: [], + providers: [], + environments: [], + scenarios: [], + captures: [], + unknowns: [], + records: [], + }; + const coverage = { + evidence_bundle, + artifacts: [], + surfaces: [], + owners: [], + claims: [], + verifier_contracts: [], + verifier_results: [], + residual_unknown_ids: [], + contradictions: [], + package_proofs: [], + boundaries: [], + }; + const accepted = { coverage, boundary_id: "main" }; const rejected = [ - { coverage: {}, boundary_id: "" }, - { coverage: {} }, - { coverage: {}, boundary_id: "main", extra: true }, + { coverage, boundary_id: "" }, + { coverage }, + { coverage, boundary_id: "main", extra: true }, + { coverage: { arbitrary: true }, boundary_id: "main" }, + { + coverage: { ...coverage, evidence_bundle: { records: [] } }, + boundary_id: "main", + }, ]; - expect(reconstructionCoverageRequestSchema.safeParse(accepted).success).toBe( - true, - ); + const contract = reconstructionCoverageEvaluationInputSchema; + expect(contract.safeParse(accepted).success).toBe(true); expect(validate(accepted)).toBe(true); for (const document of rejected) { - expect( - reconstructionCoverageRequestSchema.safeParse(document).success, - ).toBe(false); + expect(contract.safeParse(document).success).toBe(false); expect(validate(document)).toBe(false); } }); @@ -307,7 +416,7 @@ it("names the feature-trace, semantic-query, and browser-scenario fields", async ); }); -it("keeps unknown envelope fields permissive and named fields constrained", async () => { +it("advertises the reconstruction documents their readers admit", async () => { const coverage = advertisedInput( ( await serve([ @@ -317,7 +426,12 @@ it("keeps unknown envelope fields permissive and named fields constrained", asyn ]) ).stdout, ); - expect(coverage.contentSchema?.properties?.coverage).toEqual({}); + // The reader authenticates the embedded bundle, but --schema still shows + // the document it admits, as the MCP contract does. + expect(coverage.contentSchema?.properties?.coverage).toMatchObject({ + type: "object", + required: expect.arrayContaining(["evidence_bundle", "boundaries"]), + }); // boundary_id is a stable identifier (#9919), so its pattern is advertised. expect(coverage.contentSchema?.properties?.boundary_id).toMatchObject({ type: "string", @@ -334,7 +448,10 @@ it("keeps unknown envelope fields permissive and named fields constrained", asyn ]) ).stdout, ); - expect(ledger.contentSchema?.properties?.evidence_bundle).toEqual({}); + expect(ledger.contentSchema?.properties?.evidence_bundle).toMatchObject({ + type: "object", + required: expect.arrayContaining(["artifacts", "records"]), + }); expect(ledger.contentSchema?.required).toEqual( expect.arrayContaining([ "evidence_bundle", diff --git a/tests/boundary/cli/jsonInputStatus.test.ts b/tests/boundary/cli/jsonInputStatus.test.ts index 0dd9b0b3e5..7a17059890 100644 --- a/tests/boundary/cli/jsonInputStatus.test.ts +++ b/tests/boundary/cli/jsonInputStatus.test.ts @@ -11,13 +11,13 @@ const JSON_COMMANDS = [ ["trace-application-feature", "trace_application_feature"], ["trace-javascript-semantics", "trace_javascript_semantics"], ["compare-application-versions", "compare_application_versions"], - ["compare-source-to-bundle", "compare-source-to-bundle"], + ["compare-source-to-bundle", "compare_source_to_bundle"], ["compare-javascript-export-shapes", "compare_javascript_export_shapes"], [ "build-reconstruction-obligation-ledger", - "build-reconstruction-obligation-ledger", + "build_reconstruction_obligation_ledger", ], - ["evaluate-reconstruction-coverage", "evaluate-reconstruction-coverage"], + ["evaluate-reconstruction-coverage", "evaluate_reconstruction_coverage"], ["project-android-application-graph", "project_android_application_graph"], ["project-apple-application-graph", "project_apple_application_graph"], ["import-managed-reconstruction", "import_managed_reconstruction"], @@ -89,6 +89,78 @@ describe("compiled CLI JSON input failure status", () => { ); }); +describe("compiled CLI JSON document omissions", () => { + // A one-shot command retains no session Evidence, so a selected view would + // otherwise reach an owner that accepts it and be silently dropped. + for (const [command, operation] of [ + ["compare-source-to-bundle", "compare_source_to_bundle"], + ["trace-application-feature", "trace_application_feature"], + ] as const) + cliTest(`${command} refuses an omitted view field`, async ({ cli }) => { + const root = await createTestTempDirectory("rea-cli-json-omitted-"); + const result = await cli.run({ + arguments: [ + command, + JSON.stringify({ view: { kind: "summary" } }), + "--json", + ], + environment: { + HOME: root, + XDG_CONFIG_HOME: root, + XDG_CACHE_HOME: root, + }, + }); + expect(result.json).toMatchObject({ + code: "invalid_request", + category: "invalid_input", + details: { + operation, + issues: [ + { + path: ["view"], + message: expect.stringContaining("inspect-analysis-view"), + }, + ], + }, + }); + expect(result.exitCode).toBe(1); + }); +}); + +describe("compiled CLI JSON document caller paths", () => { + // A `file:` spelling is a URL, never resolved against the working directory + // (#2577); a caller names such a file as `./file:ref.json`. + cliTest( + "compare-source-to-bundle refuses a file URL reference path", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-cli-json-url-path-"); + const result = await cli.run({ + arguments: [ + "compare-source-to-bundle", + JSON.stringify({ + reference: { kind: "file", path: "file:ref.json" }, + application: {}, + }), + "--json", + ], + environment: { + HOME: root, + XDG_CONFIG_HOME: root, + XDG_CACHE_HOME: root, + }, + }); + expect(result.json).toMatchObject({ + code: "invalid_request", + details: { + operation: "compare_source_to_bundle", + issues: [{ path: ["reference", "path"], reason: "invalid_format" }], + }, + }); + expect(result.exitCode).toBe(1); + }, + ); +}); + describe("compiled CLI JSON input diagnostic preservation", () => { for (const [format, flags] of [ ["JSON", ["--json"]],