From 0035d8edb375dcde8ef10021386c31f0bb123c27 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 09:54:50 +0800 Subject: [PATCH] feat(errors): name the fields a failure's recovery selects so the CLI renders their flags (#11644) * feat(errors): name the fields a failure's recovery selects so the CLI renders their flags AnalysisError gains related { parameters, operations } (contract fields and operation names), projected as details.related_parameters / related_operations and kept through the domain re-attribution helpers. The CLI projection adds details.related_cli_flags for its own command's fields. inspect_plist's missing-default failure and inspect_sqlite_database's column-evaluation failure name fields only in their text. * test(sqlite): check MCP omits CLI flags on the failure that names related fields --- .../cli-option-text-outside-cli.json | 4 +- src/cli/projectCliAnalysisResult.ts | 34 +++++++++++++- src/domain/analysisErrorBase.ts | 27 +++++++++++ src/domain/analysisErrorCore.ts | 2 + src/domain/analysisErrorProjection.ts | 17 +++++++ src/domain/explicitSensitiveFailure.ts | 6 +++ src/native/NativePlistSource.ts | 8 +++- src/sqlite/SqliteDatabaseWorkerExecution.ts | 3 +- tests/acceptance/sqliteDatabaseCli.test.ts | 27 +++++++++-- .../nativePlistSelectionFailureCli.test.ts | 11 +++-- .../cli/projectCliAnalysisResult.test.ts | 46 ++++++++++++++++++- 11 files changed, 168 insertions(+), 17 deletions(-) diff --git a/scripts/verify/baselines/cli-option-text-outside-cli.json b/scripts/verify/baselines/cli-option-text-outside-cli.json index 2698b01270..424a449e91 100644 --- a/scripts/verify/baselines/cli-option-text-outside-cli.json +++ b/scripts/verify/baselines/cli-option-text-outside-cli.json @@ -6,7 +6,5 @@ "src/ghidra/GhidraFileOffsetFailure.ts": 1, "src/ghidra/GhidraProviderClient.ts": 5, "src/javascript/analysis/JavaScriptAnalysisWorker.ts": 1, - "src/kuna/KunaProjectReader.ts": 1, - "src/native/NativePlistSource.ts": 1, - "src/sqlite/SqliteDatabaseWorkerExecution.ts": 1 + "src/kuna/KunaProjectReader.ts": 1 } diff --git a/src/cli/projectCliAnalysisResult.ts b/src/cli/projectCliAnalysisResult.ts index 6ac82ae909..d875bf3ec3 100644 --- a/src/cli/projectCliAnalysisResult.ts +++ b/src/cli/projectCliAnalysisResult.ts @@ -27,7 +27,9 @@ export const isObject = ( * Issue paths owned by this operation take the CLI key, and a per-call * control a failure reports (`details.limit.parameter`, which services name * by contract field) gains `cli_flag`, the option that sets it on this - * command. Any other output is returned unchanged. + * command, and the fields its recovery names (`details.related_parameters`) + * gain `related_cli_flags`, each field's option. Any other output is returned + * unchanged. */ export const projectCliInputFields = ( output: Output, @@ -37,17 +39,45 @@ export const projectCliInputFields = ( if (!isObject(error) || !isObject(error.details)) return output; const issues = renamedIssues(error, error.details, binding); const limit = flaggedLimit(error.details.limit, binding); - if (issues === undefined && limit === undefined) return output; + const relatedFlags = relatedCliFlags(error.details, binding); + if (issues === undefined && limit === undefined && relatedFlags === undefined) + return output; return { ...error, details: { ...error.details, ...(issues === undefined ? {} : { issues }), ...(limit === undefined ? {} : { limit }), + ...(relatedFlags === undefined + ? {} + : { related_cli_flags: relatedFlags }), }, } as Output; }; +/** + * The option of each field this command's failure names for its recovery, + * keyed by contract field, or undefined when it takes none of them. Fields + * of another operation are that command's to render. + */ +const relatedCliFlags = ( + details: Record, + binding: CliInputFieldBinding, +): Record | undefined => { + if ( + details.operation !== binding.operation || + !Array.isArray(details.related_parameters) + ) + return undefined; + const flags: Record = {}; + for (const parameter of details.related_parameters) { + if (typeof parameter !== "string") continue; + const flag = cliFlagFor(parameter, binding); + if (flag !== undefined) flags[parameter] = flag; + } + return Object.keys(flags).length === 0 ? undefined : flags; +}; + /** Issue paths renamed to CLI keys, or undefined when none changes. */ const renamedIssues = ( error: Record, diff --git a/src/domain/analysisErrorBase.ts b/src/domain/analysisErrorBase.ts index 8c02a6b03e..f7e10ddb11 100644 --- a/src/domain/analysisErrorBase.ts +++ b/src/domain/analysisErrorBase.ts @@ -94,6 +94,18 @@ export interface AnalysisContinuingCallerGuidance { readonly remediationAction?: string; } +/** + * Inputs a failure's recovery names: fields of the failing operation's + * contract (`path`, or `field.member`) the caller may set instead, and other + * operations, by contract name, the caller may call. Each adapter renders its + * own spelling (a CLI flag or command, an MCP field or tool), so the + * message and remediation name contract fields and operations only. + */ +export interface AnalysisRelatedInputs { + readonly parameters?: readonly string[]; + readonly operations?: readonly string[]; +} + /** Optional provider-neutral context that must survive typed error projection. */ export interface AnalysisErrorOptions extends ErrorOptions { /** Typed primary retained when a later lifecycle failure composes this error. */ @@ -101,6 +113,8 @@ export interface AnalysisErrorOptions extends ErrorOptions { /** Producer-owned, caller-safe facts retained through every typed projection. */ readonly diagnostics?: Readonly> | undefined; readonly limit?: AnalysisLimit | undefined; + /** Inputs the recovery names, rendered by each adapter. */ + readonly related?: AnalysisRelatedInputs | undefined; readonly continuingCallerGuidance?: | AnalysisContinuingCallerGuidance | undefined; @@ -188,6 +202,8 @@ export abstract class AnalysisError extends Error { | { readonly cleanupResources: readonly string[] } | undefined; readonly diagnostics: Readonly> | undefined; + /** Inputs the recovery names, rendered by each adapter. */ + readonly related: Readonly | undefined; readonly continuingCallerGuidance: | Readonly | undefined; @@ -216,6 +232,17 @@ export abstract class AnalysisError extends Error { super(message, options); this.#cleanupPrimary = options?.cleanupPrimary; if (options?.limit !== undefined) this.bindLimit(options.limit); + this.related = + options?.related === undefined + ? undefined + : Object.freeze({ + ...(options.related.parameters === undefined + ? {} + : { parameters: Object.freeze([...options.related.parameters]) }), + ...(options.related.operations === undefined + ? {} + : { operations: Object.freeze([...options.related.operations]) }), + }); this.diagnostics = options?.diagnostics === undefined ? undefined diff --git a/src/domain/analysisErrorCore.ts b/src/domain/analysisErrorCore.ts index a0b11f387e..4071e6dd01 100644 --- a/src/domain/analysisErrorCore.ts +++ b/src/domain/analysisErrorCore.ts @@ -134,6 +134,8 @@ export const reattributedResourceConstraint = ( ...options, ...resourceConstraintRecovery(error), ...(error.limit === undefined ? {} : { limit: error.limit }), + + ...(error.related === undefined ? {} : { related: error.related }), ...(error.requestSent === undefined ? {} : { requestSent: error.requestSent }), diff --git a/src/domain/analysisErrorProjection.ts b/src/domain/analysisErrorProjection.ts index a24ab41a2a..dbfd07fe11 100644 --- a/src/domain/analysisErrorProjection.ts +++ b/src/domain/analysisErrorProjection.ts @@ -57,6 +57,7 @@ import { type AnalysisCallerLifetime, type AnalysisError, type AnalysisErrorOptions, + type AnalysisRelatedInputs, type AnalysisErrorTag, } from "./analysisErrorBase.js"; import { invocationLimit } from "./analysisSettingDefinitions.js"; @@ -71,6 +72,21 @@ import { isRecord } from "../kernel/isRecord.js"; * releases its provider session and runtime after this request, such as a * one-shot CLI command, passes `"invocation"`. */ +/** + * Inputs the recovery names, by contract field and operation name. Each + * adapter renders them in its own spelling. + */ +const relatedInputDetails = ( + related: AnalysisRelatedInputs | undefined, +): Record => ({ + ...(related?.parameters === undefined || related.parameters.length === 0 + ? {} + : { related_parameters: [...related.parameters] }), + ...(related?.operations === undefined || related.operations.length === 0 + ? {} + : { related_operations: [...related.operations] }), +}); + export const projectAnalysisError = ( error: AnalysisError, callerLifetime: AnalysisCallerLifetime = "continuing", @@ -438,6 +454,7 @@ const projectError = ( ...(refusal === undefined ? {} : { refusal: analysisRefusalDetails(refusal) }), + ...relatedInputDetails(primary.related), ...(!options.secondary || secondary.size === 0 ? {} : { diff --git a/src/domain/explicitSensitiveFailure.ts b/src/domain/explicitSensitiveFailure.ts index 77a0f1a5cc..b264f4a08a 100644 --- a/src/domain/explicitSensitiveFailure.ts +++ b/src/domain/explicitSensitiveFailure.ts @@ -147,6 +147,8 @@ const redactFailure = ( const context = { cause: error, ...(error.limit === undefined ? {} : { limit: error.limit }), + + ...(error.related === undefined ? {} : { related: error.related }), ...(guidance === undefined ? {} : { @@ -246,6 +248,8 @@ const redactFailure = ( ? {} : { remediationAction: text(error.remediationAction) }), ...(error.limit === undefined ? {} : { limit: error.limit }), + + ...(error.related === undefined ? {} : { related: error.related }), }); if (error instanceof AnalysisAccessDeniedError) return new AnalysisAccessDeniedError( @@ -331,6 +335,8 @@ const redactFailure = ( ...context, ...resourceConstraintRecovery(error, text), ...(error.limit === undefined ? {} : { limit: error.limit }), + + ...(error.related === undefined ? {} : { related: error.related }), ...(error.requestSent === undefined ? {} : { requestSent: error.requestSent }), diff --git a/src/native/NativePlistSource.ts b/src/native/NativePlistSource.ts index 7b25614697..cc4bdc961a 100644 --- a/src/native/NativePlistSource.ts +++ b/src/native/NativePlistSource.ts @@ -125,12 +125,16 @@ export const unreadablePlist = ( switch (selection.origin) { case "default": { // Name the default that is missing and the selection that still works. - const missingDefault = `The target has no readable default plist at ${path}: ${sentence} Select another plist in the target with the path input (CLI: --relative-path).`; + const missingDefault = `The target has no readable default plist at ${path}: ${sentence} Select another plist in the target with the path input.`; return new AnalysisCapabilityUnavailableError( IDENTITY.id, "inspect_plist", missingDefault, - { ...options, userMessage: missingDefault }, + { + ...options, + userMessage: missingDefault, + related: { parameters: ["path"] }, + }, ); } case "target": diff --git a/src/sqlite/SqliteDatabaseWorkerExecution.ts b/src/sqlite/SqliteDatabaseWorkerExecution.ts index 3ccf5982d9..e3479a74f5 100644 --- a/src/sqlite/SqliteDatabaseWorkerExecution.ts +++ b/src/sqlite/SqliteDatabaseWorkerExecution.ts @@ -119,10 +119,11 @@ const rejectedReply = ( { capturedOutput, userMessage: reply.message, + related: { parameters: ["columns", "table", "schema_scope"] }, remediationAction: `The database is readable; only the listed column values failed. REA's SQLite connection loads no extensions or application functions and disables schema trust. ${ readable.length === 0 ? "No other readable column was found" - : `Select columns whose values were read: columns: ${JSON.stringify(readable)} (CLI: one --column per name)` + : `Select columns whose values were read: columns: ${JSON.stringify(readable)}` }; omit table and use schema_scope: database to read the stored declarations without evaluating rows. Obtaining the failed values needs a SQLite connection able to evaluate them. Do not repeat the unchanged request.`, }, ); diff --git a/tests/acceptance/sqliteDatabaseCli.test.ts b/tests/acceptance/sqliteDatabaseCli.test.ts index e1e0ae0ea2..4bedfd14bf 100644 --- a/tests/acceptance/sqliteDatabaseCli.test.ts +++ b/tests/acceptance/sqliteDatabaseCli.test.ts @@ -273,7 +273,8 @@ for (const expectedErrno of ["ELOOP", "ENAMETOOLONG"] as const) { expect(result.json).toMatchObject(expectedError); const { call } = await connectLocalToolsMcp(); const response = await call("inspect_sqlite_database", { path }); - expect(parseMcpToolError(response).error).toMatchObject(expectedError); + const mcpError = parseMcpToolError(response).error; + expect(mcpError).toMatchObject(expectedError); }, ); } @@ -1258,10 +1259,14 @@ cliTest.runIf(SQLITE_NATIVE_LIMITS_AVAILABLE)( code: "capability_unavailable", retryable: false, message, - details: { provider_id: "sqlite", reason: message }, + details: { + provider_id: "sqlite", + reason: message, + related_parameters: ["columns", "table", "schema_scope"], + }, remediation: { action: expect.stringContaining( - 'Select columns whose values were read: columns: ["a"] (CLI: one --column per name)', + 'Select columns whose values were read: columns: ["a"];', ), }, }; @@ -1279,13 +1284,27 @@ cliTest.runIf(SQLITE_NATIVE_LIMITS_AVAILABLE)( }); expect(result.exitCode, result.stdout + result.stderr).toBe(1); expect(result.json).toMatchObject(expectedError); + // The CLI renders each named field's flag; MCP output names fields only. + expect(result.json).toMatchObject({ + details: { + related_cli_flags: { + columns: "--column", + table: "--table", + schema_scope: "--schema-scope", + }, + }, + }); expect(result.stdout).not.toContain("invalid_format"); const response = await call("inspect_sqlite_database", { path, table: "t", ...(columns === undefined ? {} : { columns }), }); - expect(parseMcpToolError(response).error).toMatchObject(expectedError); + const mcpError = parseMcpToolError(response).error; + expect(mcpError).toMatchObject(expectedError); + // MCP names the related fields only; flags are the CLI's spelling. + expect(mcpError.details).not.toHaveProperty("related_cli_flags"); + expect(JSON.stringify(mcpError)).not.toContain("--column"); } const base = await cli.run({ arguments: [ diff --git a/tests/boundary/cli/nativePlistSelectionFailureCli.test.ts b/tests/boundary/cli/nativePlistSelectionFailureCli.test.ts index c00edf0096..27ed3cf2cf 100644 --- a/tests/boundary/cli/nativePlistSelectionFailureCli.test.ts +++ b/tests/boundary/cli/nativePlistSelectionFailureCli.test.ts @@ -136,14 +136,17 @@ describe.skipIf(process.platform !== "darwin")( expect(result.exitCode).toBe(1); expect(result.json).toMatchObject({ code: "capability_unavailable", - message: expect.stringContaining("(CLI: --relative-path)"), + message: expect.stringMatching( + /select another plist.*with the path input\.$/iu, + ), remediation: { - action: expect.stringMatching( - /select another plist.*path input.*--relative-path/iu, - ), + action: expect.stringMatching(/select another plist.*path input/iu), }, details: { operation: "inspect_plist", + // The message names the contract field; the CLI renders its flag. + related_parameters: ["path"], + related_cli_flags: { path: "--relative-path" }, reason: expect.stringContaining( `no readable default plist at ${join(directory, "Contents/Info.plist")}: no file exists there.`, ), diff --git a/tests/boundary/cli/projectCliAnalysisResult.test.ts b/tests/boundary/cli/projectCliAnalysisResult.test.ts index fd522bfdbb..f81d543d65 100644 --- a/tests/boundary/cli/projectCliAnalysisResult.test.ts +++ b/tests/boundary/cli/projectCliAnalysisResult.test.ts @@ -1,6 +1,10 @@ import { expect, it } from "vitest"; -import { AnalysisInputError } from "../../../src/domain/analysisErrorCore.js"; +import { + AnalysisInputError, + AnalysisResourceConstraintError, + reattributedResourceConstraint, +} from "../../../src/domain/analysisErrorCore.js"; import { analysisErrorWithCleanupFailure } from "../../../src/domain/analysisErrorCleanup.js"; import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js"; import { freezeJsonSnapshot } from "../../../src/domain/immutableJson.js"; @@ -139,3 +143,43 @@ it("passes through successful data, unbound operations and unknown error values" }; expect(projectCliInputFields(unknown, binding)).toBe(unknown); }); + +it("names related fields and operations by contract identity and renders only this command's flags", () => { + const constraint = new AnalysisResourceConstraintError( + "inspect_sqlite_database", + "memory", + "fixture limit", + null, + { + related: { + parameters: ["columns", "table", "row_limit"], + operations: ["inspect_artifact"], + }, + }, + ); + // Re-attribution keeps the inputs the recovery names, as it keeps `limit`. + const projected = projectAnalysisError( + reattributedResourceConstraint("inspect_sqlite_database", constraint), + ); + expect(projected.details).toMatchObject({ + related_parameters: ["columns", "table", "row_limit"], + related_operations: ["inspect_artifact"], + }); + const sqlite = { + operation: "inspect_sqlite_database", + fields: {}, + flags: { columns: "--column", table: "--table" }, + }; + // A field the command takes no flag for is left to the contract name. + expect(projectCliInputFields(projected, sqlite)).toMatchObject({ + details: { related_cli_flags: { columns: "--column", table: "--table" } }, + }); + // Another command's failure keeps its fields for that command to render. + expect( + projectCliInputFields(projected, { ...sqlite, operation: "inspect_plist" }), + ).toBe(projected); + // An error that names nothing projects no related fields. + expect( + projectAnalysisError(new AnalysisInputError("inspect_plist")).details ?? {}, + ).not.toHaveProperty("related_parameters"); +});