diff --git a/docs/javascript-application-workflows.md b/docs/javascript-application-workflows.md index 6b7655e0f..f866d64ba 100644 --- a/docs/javascript-application-workflows.md +++ b/docs/javascript-application-workflows.md @@ -141,14 +141,33 @@ Nested callable returns are not assigned to their parent callable. Projected graph observations carry source ranges but never source text. Return variants pair only when a literal discriminant such as `/type` has one -unique occurrence on each side and pairing is reciprocal. Changes use JSON -Pointer paths with `added`, `removed`, `changed`, or `unknown` status. A missing -field is added or removed only when the relevant parent-property coverage is -complete on both shapes. The output includes exact selector candidates, -omissions, Evidence links, coverage, and limitations; it does not execute -JavaScript. When runtime semantics matter, run behavioral probes directly -against the relevant application versions and capture them through the -available browser, Electron, or process workflows. +unique occurrence on each side and pairing is reciprocal. Source order never +implies correspondence. Each retained variant contributes a property inventory +of observed JSON Pointer names, including fields whose static values stay +unknown, plus that variant's parent-property coverage. + +Changes use JSON Pointer paths with `added`, `removed`, `changed`, or `unknown` +status and a separate `presence` object (`present`, `absent`, or +`unknown-coverage`) on each side. A name is `added` or `removed` when one paired +shape proves presence and the other proves absence. Complete parent-property +coverage can establish absence even when field values stay unresolved. Identical literals are +omitted. Unresolved values that remain on both sides stay `unknown` when the +projections differ, and are omitted when presence is unchanged and the unknown +projections match. Incomplete spreads and other partial parent coverage keep +one-sided names `unknown` with `unknown-coverage` on the incomplete side. +Unpaired variants remain visible as unknown changes and still list their +property inventories, each with its own `source_range`. Inventories exclude +array holes and slots whose presence was invalidated by mutation; an unresolved +value alone does not make an observed property uncertain. `summary.added` and +`summary.removed` count +presence-level add/remove as well as literal value add/remove; +`summary.unknown` does not absorb complete-coverage presence-only gaps. + +The output includes exact selector candidates, omissions, Evidence links, +coverage, and limitations; it does not execute JavaScript. When runtime +semantics matter, run behavioral probes directly against the relevant +application versions and capture them through the available browser, Electron, +or process workflows. ## CLI and verification diff --git a/skill-src/reverse-engineer-anything/references/javascript-applications.md b/skill-src/reverse-engineer-anything/references/javascript-applications.md index 6d62eaf95..0ee112a51 100644 --- a/skill-src/reverse-engineer-anything/references/javascript-applications.md +++ b/skill-src/reverse-engineer-anything/references/javascript-applications.md @@ -40,7 +40,13 @@ changed, analyze each version once and then call `compare_javascript_export_shapes` with explicit module paths and export names. Use the returned IDs on the same connection, or complete inline Evidence records, from both analysis calls. Accept variant -pairing only through the tool's unique exact literal discriminant. Cite the +pairing only through the tool's unique exact literal discriminant. Read +`property_inventories` and each change's `presence` before treating `unknown` as +"the name was not observed": inventories list observed property names even when +values stay unknown, with a `source_range` for each paired or unpaired variant. +Array holes and mutation-invalidated slots are not observed properties. +Complete parent coverage reports presence-only +`added`/`removed` independently of unresolved values. Cite the comparison Evidence and report JSON Pointer changes; dynamic values, ambiguous variants, and incomplete parent-property coverage stay unknown. This is static inference, not runtime behavior. When runtime semantics are needed, run diff --git a/src/application/javascript/JavaScriptModuleRelationships.ts b/src/application/javascript/JavaScriptModuleRelationships.ts index ab033e744..ff5843758 100644 --- a/src/application/javascript/JavaScriptModuleRelationships.ts +++ b/src/application/javascript/JavaScriptModuleRelationships.ts @@ -32,7 +32,7 @@ import { resolveArtifactPathByContext, type ArtifactPathResolution, } from "./JavaScriptArtifactPathResolution.js"; -import { projectJavaScriptExportReturnShapes } from "./JavaScriptReturnShapeProjection.js"; +import { projectJavaScriptExportReturnShapes } from "../../domain/javascript/javascriptExportReturnShapeProjection.js"; import type { JavaScriptModuleSemanticIr } from "./JavaScriptArtifactAnalysisTypes.js"; diff --git a/src/application/javascript/JavaScriptSemanticGraphValueProjection.ts b/src/application/javascript/JavaScriptSemanticGraphValueProjection.ts index f4fdfad32..93bd79ca7 100644 --- a/src/application/javascript/JavaScriptSemanticGraphValueProjection.ts +++ b/src/application/javascript/JavaScriptSemanticGraphValueProjection.ts @@ -69,7 +69,10 @@ const projectValue = (input: ValueProjectionInput): void => { source: target, target: slot, relation: "writes-property", - resolution: value.unknownProperties ? "candidate" : "resolved", + resolution: + value.unknownProperties || property.presence === "unknown-coverage" + ? "candidate" + : "resolved", }); projectValue({ context, diff --git a/src/contracts/applicationToolContracts.ts b/src/contracts/applicationToolContracts.ts index 6ef806c36..d8c1cb342 100644 --- a/src/contracts/applicationToolContracts.ts +++ b/src/contracts/applicationToolContracts.ts @@ -155,13 +155,14 @@ export const APPLICATION_TOOL_CONTRACTS = [ name: "compare_javascript_export_shapes", ...toolContractMetadata("compare_javascript_export_shapes"), description: - "Compare static return shapes for one exact module/export selector on each authenticated JavaScript Application Graph supplied as inline Evidence or exact same-session retained references. Variants pair only by reciprocal unique literal discriminants; dynamic values, incomplete properties, and ambiguous variants remain unknown. Reports JSON Pointer changes without executing JavaScript; runtime behavior requires a separate agent-run probe.", + "Compare static return shapes for one exact module/export selector on each authenticated JavaScript Application Graph supplied as inline Evidence or exact same-session retained references. Variants pair only by reciprocal unique literal discriminants. Each retained variant lists observed return-property names even when values stay unknown. Presence (present, absent, or unknown-coverage) is separate from value resolution: a name present on only one paired shape is added or removed when parent-property coverage is complete on both sides, including when the static value is unresolved. Dynamic values, incomplete parent coverage, and unpaired variants remain unknown. Reports JSON Pointer changes without executing JavaScript; runtime behavior requires a separate agent-run probe.", kind: "application", inputSchema: compareJavaScriptExportShapesRequestSchema, outputSchema: exportShapeComparisonOutputSchema, examples: [ { - title: "Compare one exact parser export without execution", + title: + "Report observed return-property presence when static values stay unknown", input: JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE, }, { diff --git a/src/contracts/javascript/javascriptApplicationWorkflowExamples.ts b/src/contracts/javascript/javascriptApplicationWorkflowExamples.ts index 7cd7c25d5..70c1724a2 100644 --- a/src/contracts/javascript/javascriptApplicationWorkflowExamples.ts +++ b/src/contracts/javascript/javascriptApplicationWorkflowExamples.ts @@ -102,15 +102,7 @@ export const SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE = { application: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE, }; -/** Exact static return-shape comparison with both Evidence records inline. */ -export const JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE = { - left: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE, - right: reconciliationEvidence, - left_module_path: "parser.mjs", - left_export_name: "default", - right_module_path: "parser.mjs", - right_export_name: "default", -}; +export { JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE } from "./javascriptExportShapeComparisonExample.js"; /** Full-Evidence compatibility fixture used by pure domain and adapter tests. */ export const JAVASCRIPT_FEATURE_TRACE_FULL_EVIDENCE_EXAMPLE = { diff --git a/src/contracts/javascript/javascriptExportShapeComparisonExample.ts b/src/contracts/javascript/javascriptExportShapeComparisonExample.ts new file mode 100644 index 000000000..69deff0ac --- /dev/null +++ b/src/contracts/javascript/javascriptExportShapeComparisonExample.ts @@ -0,0 +1,270 @@ +import { createEvidence } from "../../domain/evidence.js"; +import { createWebTextArtifact } from "../../domain/webContentArtifact.js"; +import { analyzeJavaScriptSemantics } from "../../domain/javascript/javascriptSemanticAnalysis.js"; +import { projectJavaScriptExportReturnShapes } from "../../domain/javascript/javascriptExportReturnShapeProjection.js"; +import { + completeApplicationCoverage, + partialApplicationCoverage, +} from "../../domain/javascript/javascriptApplicationEvidenceSchemas.js"; +import { + createJavaScriptApplicationGraph, + createJavaScriptApplicationNode, +} from "../../domain/javascript/javascriptApplicationGraph.js"; +import { + createJavaScriptSemanticGraph, + createJavaScriptSemanticGraphNode, +} from "../../domain/javascript/javascriptSemanticGraph.js"; +import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES } from "../../domain/javascript/javascriptSemanticGraphSchemas.js"; +import { javascriptApplicationAnalysisResultSchema } from "../../domain/javascript/javascriptApplicationAnalysis.js"; + +// Inventory identities/counters captured from real analysis of these two sources. +// The inline example retains only source-derived export facts, with explicit gaps. +const captures = { + count: { + input_path: "/examples/javascript-export-presence/left", + root_artifact_sha256: + "5005ebc2f35719a2fc014f19a81c669f3a1ab471b7245ef6985a111b6845a747", + inventory_manifest_id: + "agm_f30ded9a83d43a3980417bbe63dfad569e83386f243c4d6a01af0166372cb9e6", + inventory_graph_sha256: + "4b8aceaf67e43fd8317ec1f5fd1df5235f8fa402335accf011683e008c6bc62c", + }, + total: { + input_path: "/examples/javascript-export-presence/right", + root_artifact_sha256: + "269ae72a601ad5ac02f1c2dda6ff9accffa2d2e4f4a9e406facee0d5a78a5377", + inventory_manifest_id: + "agm_d3ceaa1af38fb3474070ca25c0d4644282e5fb7d5824cee3e3a81391481e9fc1", + inventory_graph_sha256: + "3e9bc926951480c35385efe5650d9d781631bd74c37a523d543b5fbe06b01ce6", + }, +}; +const summary = { + browser_windows: 0, + explicit_web_preferences: 0, + preload_entrypoints: 0, + context_bridge_apis: 0, + exposed_api_members: 0, + ipc: { + operations: 0, + literal_channels: 0, + dynamic_channel_operations: 0, + renderer_transmissions: 0, + renderer_listeners: 0, + main_handlers: 0, + paired_renderer_transmissions: 0, + ambiguous_renderer_transmissions: 0, + unpaired_literal_renderer_transmissions: 0, + }, + sender_validation_observations: 0, + utility_processes: 0, + resolved_utility_entrypoints: 0, + native_addon_bindings: 0, + resolved_native_addon_bindings: 0, +}; +const statistics = { + relevant_files: 1, + nested_asar_containers: 0, + text_bytes_read: 60, + invalid_utf8_files: 0, + parsed_javascript_files: 1, + visited_ast_nodes: 12, + findings: 1, + modules: 0, + parse_failures: 0, + truncated_scopes: 0, +}; +const modulePath = "parser.mjs"; +const limitations = [ + "This example retains export and return-shape facts only; other application and semantic relationships are omitted.", +]; + +const exampleEvidence = (property: "count" | "total") => { + const metadata = captures[property]; + const source = `export default () => ({ kind: "results", ${property}: query() });\n`; + const artifact = createWebTextArtifact(source, "text/javascript"); + const ir = analyzeJavaScriptSemantics(source); + const link = ir.moduleLinks.find( + ({ exportedName }) => exportedName === "default", + ); + if (link === undefined) + throw new Error("Example source must define a default export"); + const coverage = + ir.coverage.status === "complete" + ? completeApplicationCoverage() + : partialApplicationCoverage([], ir.coverage.omittedCount); + const projection = projectJavaScriptExportReturnShapes({ + ir, + link, + modulePath, + baseCoverage: coverage, + }); + if (projection === null) + throw new Error("Example export must retain return shapes"); + const evidence = { + artifact: { + available: true, + artifact_id: `art_${artifact.sha256}`, + sha256: artifact.sha256, + }, + location: { + available: true, + value: { kind: "source-range", source: modulePath, ...link.location }, + }, + extractor: { + name: "rea-javascript-artifact-reconstruction", + version: "1", + operation: "recover-module-export", + executable_sha256: null, + }, + coverage, + limitations: ir.limitations, + evidence_ids: [], + }; + const exported = createJavaScriptApplicationNode({ + kind: "javascript-module", + identity: { + strategy: "artifact-local-key", + stability: "artifact-version", + artifact_sha256: artifact.sha256, + namespace: "module-export", + key: `${metadata.root_artifact_sha256}:${modulePath}:default`, + }, + observations: [ + { + label: `${modulePath}:default`, + properties: { + semantic_role: "export-binding", + module_path: modulePath, + relationship_kind: link.kind, + exported_name: link.exportedName, + local_name: link.localName, + imported_name: link.importedName, + declared_specifier: link.specifier, + }, + evidence: { + ...evidence, + authority: "ast-static-analysis", + state: "observed", + confidence: "exact", + }, + }, + { + label: `${modulePath}:default:return-shapes`, + properties: projection.properties, + evidence: { + ...evidence, + authority: "static-relationship-inference", + state: "inferred", + confidence: "high", + location: { + available: true, + value: { + kind: "source-range", + source: modulePath, + ...projection.range, + }, + }, + extractor: { + ...evidence.extractor, + operation: "recover-export-return-shapes", + }, + coverage: projection.coverage, + limitations: projection.limitations, + }, + }, + ], + }); + const graph = createJavaScriptApplicationGraph({ + schema: "JavaScriptApplicationGraph", + root_node_ids: [exported.node_id], + nodes: [exported], + edges: [], + coverage: partialApplicationCoverage([], null), + limitations, + }); + const module = createJavaScriptSemanticGraphNode({ + kind: "module", + identity: { + artifact_sha256: artifact.sha256, + module_path: modulePath, + source_range: null, + role_key: "example-module", + }, + function_node_id: null, + application_node_ids: [exported.node_id], + label: modulePath, + properties: {}, + evidence: { + ...evidence, + authority: "ast-static-analysis", + state: "observed", + confidence: "exact", + }, + }); + const semanticGraph = createJavaScriptSemanticGraph({ + schema: "JavaScriptSemanticRelationGraph", + root_artifact_sha256: metadata.root_artifact_sha256, + application_graph_id: graph.graph_id, + root_node_ids: [module.node_id], + nodes: [module], + relations: [], + fingerprints: [], + unknowns: [], + coverage: { + status: "unknown", + truncated: false, + omitted_nodes: null, + omitted_relations: null, + limits: [], + families: JAVASCRIPT_SEMANTIC_RELATION_FAMILIES.map((family) => ({ + family, + status: "unknown", + retained_relations: 0, + omitted_relations: null, + unknown_ids: [], + })), + }, + limitations, + }); + const result = javascriptApplicationAnalysisResultSchema.parse({ + ...metadata, + format: "directory", + graph, + semantic_graph: semanticGraph, + summary, + statistics, + limitations, + }); + return createEvidence( + { + path: result.input_path, + sha256: result.root_artifact_sha256, + format: "directory", + }, + { + id: "rea-javascript-application", + name: "REA JavaScript application analyzer", + version: "1", + }, + { + predicateType: "rea.javascript-application-analysis", + operation: "analyze_javascript_application", + parameters: {}, + result, + confidence: "derived", + authority: "shipped-artifact", + limitations, + }, + ); +}; + +/** Source-derived tagged exports with known presence and unresolved values. */ +export const JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE = { + left: exampleEvidence("count"), + right: exampleEvidence("total"), + left_module_path: modulePath, + left_export_name: "default", + right_module_path: modulePath, + right_export_name: "default", +}; diff --git a/src/application/javascript/JavaScriptReturnShapeProjection.ts b/src/domain/javascript/javascriptExportReturnShapeProjection.ts similarity index 79% rename from src/application/javascript/JavaScriptReturnShapeProjection.ts rename to src/domain/javascript/javascriptExportReturnShapeProjection.ts index f22a5feca..da2fb2e37 100644 --- a/src/application/javascript/JavaScriptReturnShapeProjection.ts +++ b/src/domain/javascript/javascriptExportReturnShapeProjection.ts @@ -1,30 +1,31 @@ -import { jsonObjectSchema, jsonValueSchema } from "../../domain/jsonValue.js"; +import { jsonObjectSchema, jsonValueSchema } from "../jsonValue.js"; import { partialApplicationCoverage, truncatedApplicationCoverage, -} from "../../domain/javascript/javascriptApplicationEvidenceSchemas.js"; + type ApplicationCoverage, +} from "./javascriptApplicationEvidenceSchemas.js"; import type { JavaScriptSemanticCallable, JavaScriptSemanticModuleLink, -} from "../../domain/javascript/javascriptSemanticIr.js"; -import { flattenSemanticReturnValue } from "../../domain/javascript/javascriptSemanticReturns.js"; -import type { JavaScriptSourceRange } from "../../domain/javascript/javascriptStaticAnalysisTypes.js"; -import type { JavaScriptArtifactGraphCoverage } from "./JavaScriptArtifactGraphContext.js"; -import type { JavaScriptModuleSemanticIr } from "./JavaScriptArtifactAnalysisTypes.js"; + JavaScriptSemanticIr, +} from "./javascriptSemanticIr.js"; +import { flattenSemanticReturnValue } from "./javascriptSemanticReturns.js"; +import type { JavaScriptSourceRange } from "./javascriptStaticAnalysisTypes.js"; +/** Return-shape facts and coverage inferred for one exported callable. */ export interface JavaScriptReturnShapeProjection { readonly properties: ReturnType; readonly range: JavaScriptSourceRange; - readonly coverage: JavaScriptArtifactGraphCoverage; + readonly coverage: ApplicationCoverage; readonly limitations: readonly string[]; } -/** Project one exact export/callable link into shallow bounded graph values. */ +/** Project one exact export/callable link into inert return-shape observations. */ export const projectJavaScriptExportReturnShapes = (input: { - readonly ir: JavaScriptModuleSemanticIr; + readonly ir: Pick; readonly link: JavaScriptSemanticModuleLink; readonly modulePath: string; - readonly baseCoverage: JavaScriptArtifactGraphCoverage; + readonly baseCoverage: ApplicationCoverage; }): JavaScriptReturnShapeProjection | null => { if (input.link.callableId === null || input.link.exportedName === null) return null; diff --git a/src/domain/javascript/javascriptExportShapeComparison.ts b/src/domain/javascript/javascriptExportShapeComparison.ts index c991746bc..63cb22dd0 100644 --- a/src/domain/javascript/javascriptExportShapeComparison.ts +++ b/src/domain/javascript/javascriptExportShapeComparison.ts @@ -17,6 +17,7 @@ import { } from "./javascriptExportShapeSelection.js"; import { buildJavaScriptExportShapeChanges, + buildJavaScriptExportShapeInventories, hasPartialJavaScriptExportPropertyCoverage, pairJavaScriptExportShapeVariants, type JavaScriptExportShapePairing, @@ -56,6 +57,11 @@ export const compareJavaScriptExportShapes = ( ); const changes = allChanges; const omittedChanges = 0; + const propertyInventories = buildJavaScriptExportShapeInventories({ + pairing, + leftShapes: leftRetained.shapes, + rightShapes: rightRetained.shapes, + }); const coverage = comparisonCoverage({ input, left, @@ -70,6 +76,7 @@ export const compareJavaScriptExportShapes = ( const semantic = { left: left.selection, right: right.selection, + property_inventories: propertyInventories, summary: summarize(allChanges), changes, coverage, diff --git a/src/domain/javascript/javascriptExportShapeComparisonIdentity.ts b/src/domain/javascript/javascriptExportShapeComparisonIdentity.ts index 9c320076c..256fa42e5 100644 --- a/src/domain/javascript/javascriptExportShapeComparisonIdentity.ts +++ b/src/domain/javascript/javascriptExportShapeComparisonIdentity.ts @@ -2,7 +2,12 @@ import { createHash } from "node:crypto"; import canonicalize from "canonicalize"; -/** Canonically encode one export-shape comparison value. */ +/** + * Canonically encode one export-shape comparison value. + * + * Comparison identifiers hash the full result semantics, including each + * change's presence object and the per-variant property inventories. + */ export const canonicalExportShapeValue = (value: unknown): string => { const encoded = canonicalize(value); if (encoded === undefined) diff --git a/src/domain/javascript/javascriptExportShapeComparisonSchemas.test.ts b/src/domain/javascript/javascriptExportShapeComparisonSchemas.test.ts index 3ab413e85..b8ab01aea 100644 --- a/src/domain/javascript/javascriptExportShapeComparisonSchemas.test.ts +++ b/src/domain/javascript/javascriptExportShapeComparisonSchemas.test.ts @@ -1,6 +1,9 @@ import { expect, it } from "vitest"; -import { projectedExportReturnShapesSchema } from "./javascriptExportShapeComparisonSchemas.js"; +import { + javaScriptExportShapeComparisonChangeSchema, + projectedExportReturnShapesSchema, +} from "./javascriptExportShapeComparisonSchemas.js"; const projectionWithField = (field: unknown) => ({ semantic_role: "export-return-shapes", @@ -29,6 +32,40 @@ const projectionWithField = (field: unknown) => ({ }, }); +it("rejects a comparison change object missing presence", () => { + const digest = "a".repeat(64); + const change = { + change_id: `jesc_change_${digest}`, + status: "added", + path: "/total", + discriminant: { path: "/kind", value: "results" }, + left: { availability: "absent" }, + right: { + availability: "unknown", + reason: "Static field value is unknown.", + }, + left_source_range: { + start: { line: 4, column: 9 }, + end: { line: 4, column: 48 }, + }, + right_source_range: { + start: { line: 4, column: 9 }, + end: { line: 4, column: 62 }, + }, + evidence_links: [`ev_${digest}`, `ev_${"b".repeat(64)}`], + limitations: [], + }; + expect( + javaScriptExportShapeComparisonChangeSchema.safeParse(change).success, + ).toBe(false); + expect( + javaScriptExportShapeComparisonChangeSchema.safeParse({ + ...change, + presence: { left: "absent", right: "present" }, + }).success, + ).toBe(true); +}); + it("parses projected fields into literal, union, or unknown values", () => { expect( projectedExportReturnShapesSchema.safeParse( diff --git a/src/domain/javascript/javascriptExportShapeComparisonSchemas.ts b/src/domain/javascript/javascriptExportShapeComparisonSchemas.ts index 1e0d47795..9a1fae67c 100644 --- a/src/domain/javascript/javascriptExportShapeComparisonSchemas.ts +++ b/src/domain/javascript/javascriptExportShapeComparisonSchemas.ts @@ -73,7 +73,10 @@ export const compareJavaScriptExportShapesInputSchema = z }); }); -const projectedReturnFieldShape = { path: jsonPointerSchema }; +const projectedReturnFieldShape = { + path: jsonPointerSchema, + presence: z.enum(["present", "absent", "unknown-coverage"]).optional(), +}; const projectedReturnFieldSchema = z.discriminatedUnion("state", [ z.strictObject({ ...projectedReturnFieldShape, @@ -229,11 +232,21 @@ const discriminantSchema = z.strictObject({ value: semanticPrimitiveSchema, }); +const propertyPresenceSchema = z.enum([ + "present", + "absent", + "unknown-coverage", +]); + const comparisonChangeSchema = z.strictObject({ change_id: prefixedDigestSchema("jesc_change"), status: z.enum(["added", "removed", "changed", "unknown"]), path: jsonPointerSchema, discriminant: discriminantSchema.nullable(), + presence: z.strictObject({ + left: propertyPresenceSchema, + right: propertyPresenceSchema, + }), left: valueAvailabilitySchema, right: valueAvailabilitySchema, left_source_range: sourceRangeSchema.nullable(), @@ -242,11 +255,31 @@ const comparisonChangeSchema = z.strictObject({ limitations: z.array(textSchema), }); +/** One change row; presence is required even when values stay unknown. */ +export const javaScriptExportShapeComparisonChangeSchema = + comparisonChangeSchema; + +const inventoryPropertyCoverageSchema = z.strictObject({ + path: jsonPointerSchema, + status: z.enum(["complete", "partial"]), +}); + +const propertyInventorySchema = z.strictObject({ + side: z.enum(["left", "right"]), + variant_index: z.number().int().nonnegative(), + discriminant: discriminantSchema.nullable(), + paired: z.boolean(), + source_range: sourceRangeSchema, + properties: z.array(jsonPointerSchema), + property_coverage: z.array(inventoryPropertyCoverageSchema), +}); + /** Static export-return comparison with explicit unknown semantics. */ export const javaScriptExportShapeComparisonResultSchema = z.strictObject({ comparison_id: prefixedDigestSchema("jesc"), left: selectorResultSchema, right: selectorResultSchema, + property_inventories: z.array(propertyInventorySchema), summary: z.strictObject({ added: z.number().int().min(0), removed: z.number().int().min(0), @@ -295,3 +328,6 @@ export type JavaScriptExportShapeComparisonResult = z.output< export type JavaScriptExportShapeComparisonChange = z.output< typeof comparisonChangeSchema >; +export type JavaScriptExportShapePropertyInventory = z.output< + typeof propertyInventorySchema +>; diff --git a/src/domain/javascript/javascriptExportShapeSelection.ts b/src/domain/javascript/javascriptExportShapeSelection.ts index 10c706780..c20df16bd 100644 --- a/src/domain/javascript/javascriptExportShapeSelection.ts +++ b/src/domain/javascript/javascriptExportShapeSelection.ts @@ -10,6 +10,9 @@ import { import { compareCodePoints } from "../canonicalOrdering.js"; type Shape = ProjectedExportReturnShapes["static_return_shapes"][number]; +type Field = Shape["fields"][number]; +type NormalizedField = Field & { presence: NonNullable }; +type NormalizedShape = Omit & { fields: NormalizedField[] }; type SelectorResult = JavaScriptExportShapeComparisonResult["left"]; type SelectorBase = Omit; type ReturnShapeSelection = @@ -55,7 +58,7 @@ export type SelectedJavaScriptExport = /** Complete return-shape inventory retained from an authenticated projection. */ export interface RetainedJavaScriptExportShapes { - readonly shapes: readonly Shape[]; + readonly shapes: readonly NormalizedShape[]; readonly omitted: number; } @@ -126,11 +129,22 @@ export const selectJavaScriptExport = ( }; }; -/** Retain every projected return variant. */ +/** Retain every variant and normalize legacy presence on comparison-owned copies. */ export const retainJavaScriptExportShapes = ( selection: SelectedJavaScriptExport, ): RetainedJavaScriptExportShapes => { - const shapes = selection.projection?.static_return_shapes ?? []; + const shapes = ( + selection.projection?.static_return_shapes ?? [] + ).map((shape) => ({ + ...shape, + fields: shape.fields.map((field) => ({ + ...field, + // Legacy unknown fields did not distinguish values from uncertain slots. + presence: + field.presence ?? + (field.state === "unknown" ? "unknown-coverage" : "present"), + })), + })); return { shapes, omitted: 0 }; }; diff --git a/src/domain/javascript/javascriptExportShapeVariants.ts b/src/domain/javascript/javascriptExportShapeVariants.ts index e5880aca6..e9420daed 100644 --- a/src/domain/javascript/javascriptExportShapeVariants.ts +++ b/src/domain/javascript/javascriptExportShapeVariants.ts @@ -5,19 +5,28 @@ import { import type { JavaScriptExportShapeComparisonChange, JavaScriptExportShapeComparisonResult, - ProjectedExportReturnShapes, + JavaScriptExportShapePropertyInventory, } from "./javascriptExportShapeComparisonSchemas.js"; import { compareCodePoints, uniqueSorted } from "../canonicalOrdering.js"; -import type { SelectedJavaScriptExport } from "./javascriptExportShapeSelection.js"; +import type { + SelectedJavaScriptExport, + RetainedJavaScriptExportShapes, +} from "./javascriptExportShapeSelection.js"; type Primitive = string | number | boolean | null; -type Shape = ProjectedExportReturnShapes["static_return_shapes"][number]; +type Shape = RetainedJavaScriptExportShapes["shapes"][number]; type Field = Shape["fields"][number]; type SelectorResult = JavaScriptExportShapeComparisonResult["left"]; type ValueAvailability = JavaScriptExportShapeComparisonChange["left"]; +type PropertyPresence = + JavaScriptExportShapeComparisonChange["presence"]["left"]; type Discriminant = NonNullable< JavaScriptExportShapeComparisonChange["discriminant"] >; +const UNKNOWN_COVERAGE_PRESENCE = { + left: "unknown-coverage", + right: "unknown-coverage", +} as const satisfies JavaScriptExportShapeComparisonChange["presence"]; interface VariantPair { readonly leftIndex: number; @@ -112,12 +121,62 @@ export const buildJavaScriptExportShapeChanges = ( return [...paired, ...unpairedLeft, ...unpairedRight]; }; +/** List observed property names per retained variant, including unknown values. */ +export const buildJavaScriptExportShapeInventories = (input: { + readonly pairing: JavaScriptExportShapePairing; + readonly leftShapes: readonly Shape[]; + readonly rightShapes: readonly Shape[]; +}): JavaScriptExportShapePropertyInventory[] => { + const leftPairs = new Map( + input.pairing.pairs.map((pair) => [pair.leftIndex, pair]), + ); + const rightPairs = new Map( + input.pairing.pairs.map((pair) => [pair.rightIndex, pair]), + ); + return [ + ...input.leftShapes.map((shape, index) => + inventoryFor("left", index, shape, leftPairs.get(index)), + ), + ...input.rightShapes.map((shape, index) => + inventoryFor("right", index, shape, rightPairs.get(index)), + ), + ]; +}; + +const inventoryFor = ( + side: JavaScriptExportShapePropertyInventory["side"], + variantIndex: number, + shape: Shape, + pair: VariantPair | undefined, +): JavaScriptExportShapePropertyInventory => ({ + side, + variant_index: variantIndex, + discriminant: pair?.discriminant ?? null, + paired: pair !== undefined, + source_range: shape.source_range, + properties: uniqueSorted([ + ...shape.fields + .filter((field) => fieldPresence(shape, field, field.path) === "present") + .map(({ path }) => path), + ...shape.property_coverage.map(({ path }) => path), + ]).filter((path) => path !== ""), + property_coverage: shape.property_coverage.map(({ path, status }) => ({ + path, + status, + })), +}); + /** Report whether any retained shape lacks complete property coverage. */ export const hasPartialJavaScriptExportPropertyCoverage = ( shapes: readonly Shape[], ): boolean => - shapes.some((shape) => - shape.property_coverage.some(({ status }) => status === "partial"), + shapes.some( + (shape) => + shape.property_coverage.some(({ status }) => status === "partial") || + shape.fields.some( + (field) => + fieldPresence(shape, field, field.path) === "unknown-coverage", + ), ); interface DiscriminantOccurrence { @@ -131,6 +190,7 @@ const discriminantOccurrences = ( const output = new Map(); shapes.forEach((shape, index) => { for (const field of shape.fields) { + if (fieldPresence(shape, field, field.path) !== "present") continue; const value = literalValue(field); if (!value.found) continue; const discriminant = { path: field.path, value: value.value }; @@ -204,6 +264,7 @@ const selectionUnknownChange = ( status: "unknown", path: "", discriminant: null, + presence: UNKNOWN_COVERAGE_PRESENCE, left: selectionAvailability(input.leftSelection.selection, "left"), right: selectionAvailability(input.rightSelection.selection, "right"), left_source_range: null, @@ -221,6 +282,7 @@ const emptyShapeUnknownChange = ( status: "unknown", path: "", discriminant: null, + presence: UNKNOWN_COVERAGE_PRESENCE, left: emptyShapeAvailability(input.leftShapes, "left"), right: emptyShapeAvailability(input.rightShapes, "right"), left_source_range: null, @@ -261,6 +323,10 @@ const diffPair = ( status, path, discriminant, + presence: { + left: fieldPresence(left, leftField, path), + right: fieldPresence(right, rightField, path), + }, left: fieldAvailability(leftField), right: fieldAvailability(rightField), left_source_range: left.source_range, @@ -288,6 +354,7 @@ const fieldAtPath = ( return undefined; return { path, + presence: "present", state: "unknown", value: null, reason: @@ -312,24 +379,40 @@ const fieldChangeStatus = ({ }: FieldChangeInput): | JavaScriptExportShapeComparisonChange["status"] | null => { - if (leftField !== undefined && rightField !== undefined) { - if ( - canonicalExportShapeValue(leftField) === + const leftPresence = fieldPresence(leftShape, leftField, path); + const rightPresence = fieldPresence(rightShape, rightField, path); + if ( + leftField !== undefined && + rightField !== undefined && + canonicalExportShapeValue(leftField) === canonicalExportShapeValue(rightField) - ) - return null; + ) + return null; + if (leftPresence === "absent" && rightPresence === "absent") return null; + if ( + leftPresence === "unknown-coverage" || + rightPresence === "unknown-coverage" + ) + return "unknown"; + if (leftPresence === "absent") return "added"; + if (rightPresence === "absent") return "removed"; + if (leftField !== undefined && rightField !== undefined) { return leftField.state === "unknown" || rightField.state === "unknown" ? "unknown" : "changed"; } - const present = leftField ?? rightField; - if (present === undefined) return null; - const parent = parentPointer(path); - const parentsComplete = - propertyCoverageComplete(leftShape, parent) && - propertyCoverageComplete(rightShape, parent); - if (present.state === "unknown" || !parentsComplete) return "unknown"; - return leftField === undefined ? "added" : "removed"; + return null; +}; + +const fieldPresence = ( + shape: Shape, + field: Field | undefined, + path: string, +): PropertyPresence => { + if (field !== undefined) return field.presence; + return propertyCoverageComplete(shape, parentPointer(path)) + ? "absent" + : "unknown-coverage"; }; const propertyCoverageComplete = (shape: Shape, path: string | null): boolean => @@ -345,7 +428,8 @@ const parentPointer = (path: string): string | null => { }; const fieldAvailability = (field: Field | undefined): ValueAvailability => { - if (field === undefined) return { availability: "absent" }; + if (field === undefined || field.presence === "absent") + return { availability: "absent" }; if (field.state === "unknown") return { availability: "unknown", @@ -390,6 +474,7 @@ const unpairedChange = ( status: "unknown", path: "", discriminant: null, + presence: UNKNOWN_COVERAGE_PRESENCE, left: { availability: "unknown", reason: diff --git a/src/domain/javascript/javascriptSemanticAnalysis.member_depth.test.ts b/src/domain/javascript/javascriptSemanticAnalysis.member_depth.test.ts index e9f8d8159..59d153a8f 100644 --- a/src/domain/javascript/javascriptSemanticAnalysis.member_depth.test.ts +++ b/src/domain/javascript/javascriptSemanticAnalysis.member_depth.test.ts @@ -63,9 +63,17 @@ it("invalidates a deep mutation while retaining unrelated literal properties", ( status: "object", properties: [ { name: "untouched", value: { status: "literal", value: "retained" } }, + { + name: "next", + presence: "unknown-coverage", + value: { + status: "unknown", + reason: "This property may have been mutated.", + }, + }, ], - unknownProperties: true, - omittedProperties: null, + unknownProperties: false, + omittedProperties: 0, }); expect(onlyBinding(ir, "value").value).toEqual({ status: "literal", diff --git a/src/domain/javascript/javascriptSemanticMutationValues.ts b/src/domain/javascript/javascriptSemanticMutationValues.ts index f4876658d..d9946ff3a 100644 --- a/src/domain/javascript/javascriptSemanticMutationValues.ts +++ b/src/domain/javascript/javascriptSemanticMutationValues.ts @@ -20,23 +20,16 @@ export const invalidateSemanticMutationPath = ( property.name === name ? { ...property, + ...(remaining.length === 0 + ? { presence: "unknown-coverage" as const } + : {}), value: invalidateSemanticMutationPath(property.value, remaining), } : property, ); - return value.unknownProperties || !observed - ? { - status: "object", - properties, - unknownProperties: true, - omittedProperties: observed ? value.omittedProperties : null, - } - : { - status: "object", - properties, - unknownProperties: false, - omittedProperties: 0, - }; + if (!observed) + properties.push({ name, value: unknown, presence: "unknown-coverage" }); + return { ...value, properties }; } if (value.status === "array") { const index = typeof key === "number" ? key : Number(key); @@ -46,20 +39,18 @@ export const invalidateSemanticMutationPath = ( String(index) !== String(key) ) return unknown; - const observed = value.items[index] !== undefined; const items = value.items.map((item, position) => position === index ? invalidateSemanticMutationPath(item, remaining) : item, ); - return value.unknownItems || !observed - ? { - status: "array", - items, - unknownItems: true, - omittedItems: observed ? value.omittedItems : null, - } - : { status: "array", items, unknownItems: false, omittedItems: 0 }; + const itemPresence = { + ...value.itemPresence, + ...(remaining.length === 0 || value.items[index] === undefined + ? { [index]: "unknown-coverage" as const } + : {}), + }; + return { ...value, items, itemPresence }; } return unknown; }; diff --git a/src/domain/javascript/javascriptSemanticReturns.ts b/src/domain/javascript/javascriptSemanticReturns.ts index 0e63527ca..74183f357 100644 --- a/src/domain/javascript/javascriptSemanticReturns.ts +++ b/src/domain/javascript/javascriptSemanticReturns.ts @@ -211,14 +211,33 @@ const flattenValue = ( path: string, fields: ProjectedReturnField[], coverage: ProjectedPropertyCoverage[], + presence: "present" | "absent" | "unknown-coverage" = "present", ): void => { + if (presence !== "present") { + fields.push({ + path, + presence, + state: "unknown", + value: null, + reason: + "reason" in value ? value.reason : "Property presence is uncertain.", + }); + return; + } if (value.status === "literal") { - fields.push({ path, state: "literal", value: value.value, reason: null }); + fields.push({ + path, + presence, + state: "literal", + value: value.value, + reason: null, + }); return; } if (value.status === "union") { fields.push({ path, + presence, state: "union", value: [...value.values], reason: null, @@ -237,6 +256,7 @@ const flattenValue = ( `${path}/${escapePointer(property.name)}`, fields, coverage, + property.presence ?? "present", ); return; } @@ -247,11 +267,30 @@ const flattenValue = ( : { path, status: "complete", omitted: 0 }, ); value.items.forEach((item, index) => - flattenValue(item, `${path}/${String(index)}`, fields, coverage), + flattenValue( + item, + `${path}/${String(index)}`, + fields, + coverage, + value.itemPresence?.[index] ?? "present", + ), ); + // Sparse mutation metadata retains uncertain slots without expanding arrays. + for (const [index, itemPresence] of Object.entries( + value.itemPresence ?? {}, + )) { + if (Number(index) < value.items.length) continue; + flattenValue(value, `${path}/${index}`, fields, coverage, itemPresence); + } return; } - fields.push({ path, state: "unknown", value: null, reason: value.reason }); + fields.push({ + path, + presence, + state: "unknown", + value: null, + reason: value.reason, + }); }; const escapePointer = (value: string): string => diff --git a/src/domain/javascript/javascriptSemanticValueTypes.ts b/src/domain/javascript/javascriptSemanticValueTypes.ts index e2545b2b6..9d4917b64 100644 --- a/src/domain/javascript/javascriptSemanticValueTypes.ts +++ b/src/domain/javascript/javascriptSemanticValueTypes.ts @@ -24,6 +24,9 @@ type JavaScriptSemanticObjectValue = { type JavaScriptSemanticArrayValue = { readonly status: "array"; readonly items: readonly JavaScriptSemanticValue[]; + readonly itemPresence?: Readonly< + Record + >; } & ( | { readonly unknownItems: false; @@ -57,4 +60,5 @@ export type JavaScriptSemanticValue = export interface JavaScriptSemanticProperty { readonly name: string; readonly value: JavaScriptSemanticValue; + readonly presence?: "unknown-coverage"; } diff --git a/src/domain/javascript/javascriptSemanticValues.ts b/src/domain/javascript/javascriptSemanticValues.ts index ab8bcf37f..cf8ca5288 100644 --- a/src/domain/javascript/javascriptSemanticValues.ts +++ b/src/domain/javascript/javascriptSemanticValues.ts @@ -299,6 +299,7 @@ const evaluateArray = ( context: EvaluationContext, ): JavaScriptSemanticValue => { const items: JavaScriptSemanticValue[] = []; + const itemPresence: Record = {}; let unknownItems = false; let omittedItems: number | null = 0; for (const element of node.elements) { @@ -309,8 +310,7 @@ const evaluateArray = ( break; } if (element === null) { - unknownItems = true; - if (omittedItems !== null) omittedItems += 1; + itemPresence[items.length] = "absent"; items.push({ status: "unknown", reason: "Array hole has no primitive value.", @@ -320,8 +320,14 @@ const evaluateArray = ( items.push(evaluateExpression(element, nestedContext(context))); } return unknownItems - ? { status: "array", items, unknownItems: true, omittedItems } - : { status: "array", items, unknownItems: false, omittedItems: 0 }; + ? { status: "array", items, itemPresence, unknownItems: true, omittedItems } + : { + status: "array", + items, + itemPresence, + unknownItems: false, + omittedItems: 0, + }; }; const evaluateMember = ( diff --git a/tests/acceptance/applications/applicationWorkflowCli.test.ts b/tests/acceptance/applications/applicationWorkflowCli.test.ts index 265a84737..c5963e708 100644 --- a/tests/acceptance/applications/applicationWorkflowCli.test.ts +++ b/tests/acceptance/applications/applicationWorkflowCli.test.ts @@ -509,6 +509,7 @@ describe("application workflow CLI export Evidence", () => { { status: "added", path: "/depth", + presence: { left: "absent", right: "present" }, right: { availability: "literal", value: 1 }, }, ], @@ -517,6 +518,103 @@ describe("application workflow CLI export Evidence", () => { }, 20_000); }); +describe("application workflow CLI export property presence", () => { + it("reports tagged search property presence through compare-javascript-export-shapes", async () => { + const root = await createTestTempDirectory( + "rea-export-shape-presence-cli-", + ); + temporary.push(root); + const leftRoot = join(root, "left"); + const rightRoot = join(root, "right"); + await Promise.all([mkdir(leftRoot), mkdir(rightRoot)]); + await Promise.all([ + writeFile( + join(leftRoot, "search.js"), + [ + "export function search(items, q) {", + " const matches = items.filter((item) => item.includes(q));", + ' return { kind: "results", matches, count: matches.length };', + "}", + "", + ].join("\n"), + ), + writeFile( + join(rightRoot, "search.js"), + [ + "export function search(items, q) {", + " const matches = items.filter((item) => item.includes(q));", + ' return { kind: "results", matches, total: matches.length, query: String(q) };', + "}", + "", + ].join("\n"), + ), + ]); + const [left, right] = await Promise.all([ + analyzeJavaScriptApplication({ input_path: leftRoot }), + analyzeJavaScriptApplication({ input_path: rightRoot }), + ]); + if (!left.ok) throw left.error; + if (!right.ok) throw right.error; + const inputPath = join(root, "comparison.json"); + await writeFile( + inputPath, + JSON.stringify({ + left: left.value, + right: right.value, + left_module_path: "search.js", + left_export_name: "search", + right_module_path: "search.js", + right_export_name: "search", + }), + ); + const compared = await runCli([ + "compare-javascript-export-shapes", + inputPath, + "--json", + ]); + expect(compared).toMatchObject({ + operation: "compare_javascript_export_shapes", + normalized_result: { + summary: { added: 2, removed: 1 }, + property_inventories: expect.arrayContaining([ + expect.objectContaining({ + side: "left", + paired: true, + properties: expect.arrayContaining(["/count", "/kind", "/matches"]), + }), + expect.objectContaining({ + side: "right", + paired: true, + properties: expect.arrayContaining([ + "/kind", + "/matches", + "/query", + "/total", + ]), + }), + ]), + changes: expect.arrayContaining([ + expect.objectContaining({ + status: "removed", + path: "/count", + presence: { left: "present", right: "absent" }, + }), + expect.objectContaining({ + status: "added", + path: "/total", + presence: { left: "absent", right: "present" }, + }), + expect.objectContaining({ + status: "added", + path: "/query", + presence: { left: "absent", right: "present" }, + }), + ]), + }, + }); + }, 20_000); +}); + describe("application workflow CLI validation", () => { it("returns safe actionable JSON validation details", async () => { const malformed = await runCli([ diff --git a/tests/boundary/filesystem/javascriptExportContainerCoverage.test.ts b/tests/boundary/filesystem/javascriptExportContainerCoverage.test.ts index 660eaa38c..f410e4f29 100644 --- a/tests/boundary/filesystem/javascriptExportContainerCoverage.test.ts +++ b/tests/boundary/filesystem/javascriptExportContainerCoverage.test.ts @@ -20,40 +20,46 @@ describe("JavaScript export container coverage through authenticated Evidence", before: "", after: ", options: {}", paths: ["/options"], + addedPaths: ["/options"], }, { name: "empty array", before: "", after: ", options: []", paths: ["/options"], + addedPaths: ["/options"], }, { name: "nested object", before: ", options: {}", after: ", options: { nested: {} }", paths: ["/options/nested"], + addedPaths: ["/options/nested"], }, { name: "nested array", before: ", options: []", after: ", options: [[]]", paths: ["/options/0"], + addedPaths: ["/options/0"], }, { name: "container subtree", before: "", after: ", options: { nested: {} }", paths: ["/options", "/options/nested"], + addedPaths: ["/options"], }, { name: "escaped property keys", before: ', "a/b~c": {}', after: ', "a/b~c": { "d/e~f": [] }', paths: ["/a~1b~0c/d~1e~0f"], + addedPaths: ["/a~1b~0c/d~1e~0f"], }, ])( - "reports absent versus $name as unknown in both directions", - async ({ before, after, paths }) => { + "reports $name presence independently of unresolved values in both directions", + async ({ before, after, paths, addedPaths }) => { const [absent, retained] = await analyzeReturns(before, after); for (const path of paths) { expect( @@ -71,16 +77,17 @@ describe("JavaScript export container coverage through authenticated Evidence", ); } - for (const [left, right, leftAvailability, rightAvailability] of [ - [absent, retained, "absent", "unknown"], - [retained, absent, "unknown", "absent"], + for (const [left, right, leftAvailability, rightAvailability, status] of [ + [absent, retained, "absent", "unknown", "added"], + [retained, absent, "unknown", "absent", "removed"], ] as const) { const result = compareEvidence(left, right); expect(result.summary).toEqual({ added: 0, removed: 0, changed: 0, - unknown: paths.length, + unknown: paths.length - addedPaths.length, + [status]: addedPaths.length, }); expect(result.changes).toHaveLength(paths.length); expect(result.changes).toEqual( @@ -88,7 +95,7 @@ describe("JavaScript export container coverage through authenticated Evidence", paths.map((path) => expect.objectContaining({ path, - status: "unknown", + status: addedPaths.includes(path) ? status : "unknown", discriminant: { path: "/type", value: "item" }, left: expect.objectContaining({ availability: leftAvailability, @@ -102,15 +109,20 @@ describe("JavaScript export container coverage through authenticated Evidence", left.evidence.evidence_id, right.evidence.evidence_id, ], - limitations: [ - "The static value or relevant parent-property coverage is incomplete.", - ], + limitations: addedPaths.includes(path) + ? [] + : [ + "The static value or relevant parent-property coverage is incomplete.", + ], }), ), ), ); expect(result.coverage).toMatchObject({ - status: "partial", + status: + addedPaths.length === paths.length + ? "complete-within-inputs" + : "partial", paired_variants: 1, unpaired_left_variants: 0, unpaired_right_variants: 0, diff --git a/tests/boundary/filesystem/javascriptExportShapeComparison.test.ts b/tests/boundary/filesystem/javascriptExportShapeComparison.test.ts index 05e3f8e2d..5b1b260e7 100644 --- a/tests/boundary/filesystem/javascriptExportShapeComparison.test.ts +++ b/tests/boundary/filesystem/javascriptExportShapeComparison.test.ts @@ -8,7 +8,10 @@ import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; import { analyzeJavaScriptApplication } from "../../../src/application/javascript/JavaScriptApplicationService.js"; import { parseApplicationGraphEvidence } from "../../../src/application/javascript/JavaScriptApplicationEvidenceGraph.js"; import { compareJavaScriptExportShapes } from "../../../src/domain/javascript/javascriptExportShapeComparison.js"; -import { javaScriptExportShapeComparisonResultSchema } from "../../../src/domain/javascript/javascriptExportShapeComparisonSchemas.js"; +import { + javaScriptExportShapeComparisonResultSchema, + projectedExportReturnShapesSchema, +} from "../../../src/domain/javascript/javascriptExportShapeComparisonSchemas.js"; import { createJavaScriptApplicationGraph, createJavaScriptApplicationNode, @@ -53,6 +56,7 @@ describe("JavaScript export return-shape comparison", () => { status: "added", path: "/depth", discriminant: { path: "/type", value: "heading" }, + presence: { left: "absent", right: "present" }, left: { availability: "absent" }, right: { availability: "literal", value: 1 }, }), @@ -83,7 +87,11 @@ describe("JavaScript export return-shape comparison", () => { const result = compare(left, right); expect(result.changes).toEqual([ - expect.objectContaining({ status: "unknown", path: "/depth" }), + expect.objectContaining({ + status: "unknown", + path: "/depth", + presence: { left: "unknown-coverage", right: "present" }, + }), ]); expect(result.coverage.status).toBe("partial"); }); @@ -102,6 +110,81 @@ describe("JavaScript export return-shape comparison", () => { expect(first.changes).toEqual(second.changes); expect(first.comparison_id).toBe(second.comparison_id); }); +}); + +describe("JavaScript export return-shape pairing limits", () => { + it.each([ + { presence: "absent", side: "left" }, + { presence: "unknown-coverage", side: "left" }, + { presence: "absent", side: "right" }, + { presence: "unknown-coverage", side: "right" }, + ] as const)( + "does not pair an inline $side discriminant whose presence is $presence", + async ({ presence, side }) => { + const [left, right] = await analyzeSources({ + left: 'export default () => ({ kind: "result", count: 1 });', + right: 'export default () => ({ kind: "result", total: 2 });', + }); + const selected = side === "left" ? left : right; + const graph = createJavaScriptApplicationGraph({ + schema: "JavaScriptApplicationGraph", + root_node_ids: selected.graph.root_node_ids, + edges: selected.graph.edges, + coverage: selected.graph.coverage, + limitations: selected.graph.limitations, + nodes: selected.graph.nodes.map((node) => + createJavaScriptApplicationNode({ + kind: node.kind, + identity: node.identity, + observations: node.observations.map( + ({ label, properties, evidence }) => ({ + label, + evidence, + properties: + properties.semantic_role !== "export-return-shapes" + ? properties + : { + ...properties, + static_return_shapes: projectedExportReturnShapesSchema + .parse(properties) + .static_return_shapes.map((shape) => ({ + ...shape, + fields: shape.fields.map((field) => + field.path === "/kind" + ? { ...field, presence } + : field, + ), + })), + }, + }), + ), + }), + ), + }); + const result = + side === "left" + ? compare({ ...left, graph }, right) + : compare(left, { ...right, graph }); + expect(result.coverage).toMatchObject({ + status: "partial", + paired_variants: 0, + unpaired_left_variants: 1, + unpaired_right_variants: 1, + }); + expect(result.changes).toHaveLength(2); + expect( + result.changes.every( + ({ status, discriminant }) => + status === "unknown" && discriminant === null, + ), + ).toBe(true); + expect( + result.property_inventories.every( + ({ paired, discriminant }) => !paired && discriminant === null, + ), + ).toBe(true); + }, + ); it("does not pair discriminants that an unknown trailing spread can overwrite", async () => { const [left, right] = await analyzeSources({ @@ -172,6 +255,432 @@ describe("JavaScript export return-shape comparison", () => { }); }); +describe("JavaScript export return-shape uncertain presence", () => { + it.each([false, true])( + "keeps deleted property presence unknown (reversed: %s)", + async (reversed) => { + const plain = 'export default () => ({ kind: "result" });'; + const mutated = `export default function make() { + const result = { kind: "result", count: 1 }; + delete result.count; + return result; + }`; + const graphs = await analyzeSources({ + left: reversed ? mutated : plain, + right: reversed ? plain : mutated, + }); + const result = compare(...graphs); + expect(result.changes).toContainEqual( + expect.objectContaining({ + path: "/count", + status: "unknown", + presence: reversed + ? { left: "unknown-coverage", right: "absent" } + : { left: "absent", right: "unknown-coverage" }, + }), + ); + expect( + inventoryProperties(result, reversed ? "left" : "right", 0), + ).not.toContain("/count"); + expect(result.summary.added + result.summary.removed).toBe(0); + expect(result.coverage.status).toBe("partial"); + }, + ); + + it("excludes array holes while preserving observed unknown elements", async () => { + const holes = 'export default () => ({ kind: "result", items: [,] });'; + const empty = await analyzeSources({ + left: holes, + right: 'export default () => ({ kind: "result", items: [] });', + }); + const result = compare(...empty); + expect(result.coverage.status).toBe("complete-within-inputs"); + expect(inventoryProperties(result, "left", 0)).not.toContain("/items/0"); + expect(result.changes.some(({ path }) => path === "/items/0")).toBe(false); + const filled = await analyzeSources({ + left: holes, + right: 'export default () => ({ kind: "result", items: [call()] });', + }); + expect(compare(...filled).changes).toContainEqual( + expect.objectContaining({ + path: "/items/0", + status: "added", + presence: { left: "absent", right: "present" }, + left: { availability: "absent" }, + right: expect.objectContaining({ availability: "unknown" }), + }), + ); + }); + + it("retains unpaired inventory locations when the opposite export has no return", async () => { + const graphs = await analyzeSources({ + left: "export default function f() {}", + right: `export default function f(flag) { + if (flag) return { count: call() }; + return { total: call() }; + }`, + }); + const result = compare(...graphs); + expect(result.property_inventories).toEqual([ + expect.objectContaining({ + side: "right", + paired: false, + variant_index: 0, + properties: expect.arrayContaining(["/count"]), + source_range: expect.objectContaining({ + start: expect.objectContaining({ line: 2 }), + }), + }), + expect.objectContaining({ + side: "right", + paired: false, + variant_index: 1, + properties: expect.arrayContaining(["/total"]), + source_range: expect.objectContaining({ + start: expect.objectContaining({ line: 3 }), + }), + }), + ]); + expect(() => + javaScriptExportShapeComparisonResultSchema.parse(result), + ).not.toThrow(); + }); +}); + +describe("JavaScript export matching uncertain projections", () => { + it.each(["delete result.count;", "result.count = query();"])( + "omits matching uncertain projections after %s", + async (mutation) => { + const source = `export default function make() { + const result = { kind: "result", count: 1 }; + ${mutation} + return result; + }`; + const graphs = await analyzeSources({ left: source, right: source }); + const result = compare(...graphs); + expect(result.changes).toEqual([]); + expect(result.summary).toEqual({ + added: 0, + removed: 0, + changed: 0, + unknown: 0, + }); + expect(result.coverage.status).toBe("partial"); + expect( + result.property_inventories.every( + ({ properties }) => !properties.includes("/count"), + ), + ).toBe(true); + }, + ); +}); + +describe("JavaScript export localized mutation uncertainty", () => { + it.each([ + { + initializer: '{ kind: "result", count: 1 }', + mutation: "delete result.count;", + uncertain: "/count", + right: '{ kind: "result", total: 1 }', + added: "/total", + }, + { + initializer: '{ kind: "result" }', + mutation: "result.count = query();", + uncertain: "/count", + right: '{ kind: "result", total: 1 }', + added: "/total", + }, + { + initializer: '{ kind: "result" }', + mutation: "delete result.count;", + uncertain: "/count", + right: '{ kind: "result", total: 1 }', + added: "/total", + }, + { + initializer: '{ kind: "result", nested: {} }', + mutation: "result.nested.count = query();", + uncertain: "/nested/count", + right: '{ kind: "result", nested: { total: 1 } }', + added: "/nested/total", + }, + { + initializer: '{ kind: "result", items: [] }', + mutation: "result.items[1] = query();", + uncertain: "/items/1", + right: '{ kind: "result", items: [,,1] }', + added: "/items/2", + }, + { + initializer: '{ kind: "result", items: [] }', + mutation: "delete result.items[1];", + uncertain: "/items/1", + right: '{ kind: "result", items: [,,1] }', + added: "/items/2", + }, + { + initializer: '{ kind: "result", items: [] }', + mutation: "result.items[1000000000] = query();", + uncertain: "/items/1000000000", + right: '{ kind: "result", items: [,,1] }', + added: "/items/2", + }, + ])( + "localizes $mutation without losing sibling absence", + async ({ initializer, mutation, uncertain, right, added }) => { + const graphs = await analyzeSources({ + left: `export default function make() { + const result = ${initializer}; + ${mutation} + return result; + }`, + right: `export default () => (${right});`, + }); + const result = compare(...graphs); + expect(result.changes).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + path: uncertain, + status: "unknown", + presence: { left: "unknown-coverage", right: "absent" }, + }), + expect.objectContaining({ + path: added, + status: "added", + presence: { left: "absent", right: "present" }, + }), + ]), + ); + expect(result.summary).toEqual({ + added: 1, + removed: 0, + changed: 0, + unknown: 1, + }); + }, + ); +}); + +describe("JavaScript export property presence boundaries", () => { + it("normalizes omitted legacy presence before comparing identical literals and unions", async () => { + const source = + 'export default () => ({ kind: "result", count: flag ? 1 : 2, nested: { enabled: true } });'; + const [left, right] = await analyzeSources({ left: source, right: source }); + const graph = createJavaScriptApplicationGraph({ + schema: "JavaScriptApplicationGraph", + root_node_ids: left.graph.root_node_ids, + edges: left.graph.edges, + coverage: left.graph.coverage, + limitations: left.graph.limitations, + nodes: left.graph.nodes.map((node) => + createJavaScriptApplicationNode({ + kind: node.kind, + identity: node.identity, + observations: node.observations.map( + ({ label, properties, evidence }) => { + if (properties.semantic_role !== "export-return-shapes") + return { label, properties, evidence }; + const projection = + projectedExportReturnShapesSchema.parse(properties); + return { + label, + evidence, + properties: { + ...properties, + static_return_shapes: projection.static_return_shapes.map( + (shape) => ({ + ...shape, + fields: shape.fields.map( + ({ path, state, value, reason }) => ({ + path, + state, + value, + reason, + }), + ), + }), + ), + }, + }; + }, + ), + }), + ), + }); + for (const sides of [ + [{ ...left, graph }, right], + [right, { ...left, graph }], + ] as const) { + const result = compare(sides[0], sides[1]); + expect(result.coverage.paired_variants).toBe(1); + expect(result.changes).toEqual([]); + expect(result.coverage.status).toBe("complete-within-inputs"); + } + }); + + it("proves absence beyond literal holes while retaining unknown spread coverage", async () => { + const right = + 'export default () => ({ kind: "result", items: [,, call()] });'; + const literal = await analyzeSources({ + left: 'export default () => ({ kind: "result", items: [,] });', + right, + }); + const result = compare(...literal); + expect(result.changes).toEqual([ + expect.objectContaining({ + path: "/items/2", + status: "added", + presence: { left: "absent", right: "present" }, + }), + ]); + expect(result.coverage.status).toBe("complete-within-inputs"); + const spread = await analyzeSources({ + left: 'export default () => ({ kind: "result", items: [, ...rest] });', + right, + }); + expect(compare(...spread).changes).toContainEqual( + expect.objectContaining({ + path: "/items/2", + status: "unknown", + presence: { left: "unknown-coverage", right: "present" }, + }), + ); + }); + + it("excludes the return root but retains empty property names and nested containers", async () => { + const source = + 'export default () => ({ kind: "result", "": call(), options: {} });'; + const graphs = await analyzeSources({ left: source, right: source }); + const result = compare(...graphs); + expect(inventoryProperties(result, "left", 0)).toEqual([ + "/", + "/kind", + "/options", + ]); + expect(result.property_inventories[0]?.property_coverage).toContainEqual({ + path: "", + status: "complete", + }); + }); +}); + +describe("JavaScript export return-shape property presence", () => { + it("lists observed names without pairing untagged search variants", async () => { + const graphs = await analyzeSources( + { + left: untaggedSearchSource("count"), + right: untaggedSearchSource("total"), + }, + "search.js", + ); + const first = compare(...graphs, { + modulePath: "search.js", + leftExportName: "search", + rightExportName: "search", + }); + const second = compare(...graphs, { + modulePath: "search.js", + leftExportName: "search", + rightExportName: "search", + }); + + expect(first.comparison_id).toBe(second.comparison_id); + expect(first.coverage).toMatchObject({ + paired_variants: 0, + unpaired_left_variants: 1, + unpaired_right_variants: 1, + }); + expect(first.summary).toEqual({ + added: 0, + removed: 0, + changed: 0, + unknown: 2, + }); + expect( + first.changes.every(({ discriminant }) => discriminant === null), + ).toBe(true); + expect(inventoryProperties(first, "left", 0)).toEqual( + expect.arrayContaining(["/count", "/matches"]), + ); + expect(inventoryProperties(first, "right", 0)).toEqual( + expect.arrayContaining(["/matches", "/query", "/total"]), + ); + expect(inventoryProperties(first, "left", 0)).not.toEqual( + inventoryProperties(first, "right", 0), + ); + }); + + it("reports presence-only added and removed names for tagged search variants", async () => { + const graphs = await analyzeSources( + { + left: taggedSearchSource({ count: true }), + right: taggedSearchSource({ total: true, query: true }), + }, + "search.js", + ); + const first = compare(...graphs, { + modulePath: "search.js", + leftExportName: "search", + rightExportName: "search", + }); + const second = compare(...graphs, { + modulePath: "search.js", + leftExportName: "search", + rightExportName: "search", + }); + + expect(first.comparison_id).toBe(second.comparison_id); + expect(() => + javaScriptExportShapeComparisonResultSchema.parse(first), + ).not.toThrow(); + expect(first.coverage.paired_variants).toBe(1); + expect(first.summary.added).toBe(2); + expect(first.summary.removed).toBe(1); + expect( + first.changes.filter(({ path }) => + ["/count", "/total", "/query"].includes(path), + ), + ).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + status: "removed", + path: "/count", + presence: { left: "present", right: "absent" }, + left: expect.objectContaining({ availability: "unknown" }), + right: { availability: "absent" }, + }), + expect.objectContaining({ + status: "added", + path: "/total", + presence: { left: "absent", right: "present" }, + left: { availability: "absent" }, + right: expect.objectContaining({ availability: "unknown" }), + }), + expect.objectContaining({ + status: "added", + path: "/query", + presence: { left: "absent", right: "present" }, + left: { availability: "absent" }, + right: expect.objectContaining({ availability: "unknown" }), + }), + ]), + ); + expect( + first.changes.some( + ({ path, status }) => + ["/count", "/total", "/query"].includes(path) && status === "unknown", + ), + ).toBe(false); + expect(inventoryProperties(first, "left", 0)).toEqual( + expect.arrayContaining(["/count", "/kind", "/matches"]), + ); + expect(inventoryProperties(first, "right", 0)).toEqual( + expect.arrayContaining(["/kind", "/matches", "/query", "/total"]), + ); + }); +}); + describe("JavaScript export return-shape container presence", () => { it.each(["{}", "[]", "{ nested: 1 }"])( "does not report a retained %s container property as removed", @@ -399,6 +908,7 @@ const compare = ( left: GraphSource, right: GraphSource, options: { + readonly modulePath?: string; readonly leftExportName?: string; readonly rightExportName?: string; } = {}, @@ -407,13 +917,13 @@ const compare = ( left: { evidenceId: left.evidence.evidence_id, graph: left.graph, - modulePath: "parser.mjs", + modulePath: options.modulePath ?? "parser.mjs", exportName: options.leftExportName ?? "default", }, right: { evidenceId: right.evidence.evidence_id, graph: right.graph, - modulePath: "parser.mjs", + modulePath: options.modulePath ?? "parser.mjs", exportName: options.rightExportName ?? "default", }, }); @@ -426,21 +936,74 @@ const analyzeGraph = async (root: string) => { return parseApplicationGraphEvidence(result.value); }; -const analyzeSources = async (sources: { - readonly left: string; - readonly right: string; -}): Promise<[GraphSource, GraphSource]> => { +const analyzeSources = async ( + sources: { + readonly left: string; + readonly right: string; + }, + fileName = "parser.mjs", +): Promise<[GraphSource, GraphSource]> => { const root = await temporaryRoot(); const leftRoot = join(root, "left"); const rightRoot = join(root, "right"); await Promise.all([mkdir(leftRoot), mkdir(rightRoot)]); await Promise.all([ - writeFile(join(leftRoot, "parser.mjs"), sources.left), - writeFile(join(rightRoot, "parser.mjs"), sources.right), + writeFile(join(leftRoot, fileName), sources.left), + writeFile(join(rightRoot, fileName), sources.right), ]); return Promise.all([analyzeGraph(leftRoot), analyzeGraph(rightRoot)]); }; +const inventoryProperties = ( + result: ReturnType, + side: "left" | "right", + variantIndex: number, +): string[] => { + const inventory = result.property_inventories.find( + (entry) => entry.side === side && entry.variant_index === variantIndex, + ); + if (inventory === undefined) + throw new Error( + `Missing ${side} property inventory ${String(variantIndex)}`, + ); + return inventory.properties; +}; + +const untaggedSearchSource = (countKey: "count" | "total"): string => + countKey === "count" + ? ` + export function search(items, q) { + const matches = items.filter((item) => item.includes(q)); + return { matches, count: matches.length }; + } + ` + : ` + export function search(items, q) { + const matches = items.filter((item) => item.includes(q)); + return { matches, total: matches.length, query: String(q) }; + } + `; + +const taggedSearchSource = (fields: { + readonly count?: boolean; + readonly total?: boolean; + readonly query?: boolean; +}): string => { + const extra = [ + fields.count === true ? "count: matches.length" : null, + fields.total === true ? "total: matches.length" : null, + fields.query === true ? "query: String(q)" : null, + ] + .filter((field): field is string => field !== null) + .join(", "); + return ` + export function search(items, q) { + const matches = items.filter((item) => item.includes(q)); + return { kind: "results", matches${extra.length > 0 ? `, ${extra}` : ""} }; + } + `; +}; + const sourceOwnedParsers = async (): Promise<[GraphSource, GraphSource]> => { const root = await temporaryRoot(); const leftRoot = join(root, "left"); diff --git a/tests/boundary/mcp/applicationExportShapeMcp.test.ts b/tests/boundary/mcp/applicationExportShapeMcp.test.ts index 7769dfa49..17a0dc22d 100644 --- a/tests/boundary/mcp/applicationExportShapeMcp.test.ts +++ b/tests/boundary/mcp/applicationExportShapeMcp.test.ts @@ -1,6 +1,8 @@ -import { describe, expect, it } from "vitest"; +import { describe, expect, it, onTestFinished } from "vitest"; import { copyFile, mkdir, rm, writeFile } from "node:fs/promises"; import { join, relative, resolve } from "node:path"; +import { Ajv2020 } from "ajv/dist/2020.js"; +import { z } from "zod"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; @@ -9,6 +11,110 @@ import { compareJavaScriptExportShapesEvidence } from "../../../src/application/ import { javascriptApplicationAnalysisResultSchema } from "../../../src/domain/javascript/javascriptApplicationAnalysis.js"; import { javaScriptExportShapeComparisonResultSchema } from "../../../src/domain/javascript/javascriptExportShapeComparisonSchemas.js"; import { createApplicationMcpHarness } from "../../fixtures/applicationMcpHarness.js"; +import { APPLICATION_TOOL_CONTRACTS } from "../../../src/contracts/applicationToolContracts.js"; +import { JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE } from "../../../src/contracts/javascript/javascriptExportShapeComparisonExample.js"; + +it("executes the advertised export presence example with matching analyzed Evidence", async () => { + const contract = APPLICATION_TOOL_CONTRACTS.find( + ({ name }) => name === "compare_javascript_export_shapes", + ); + const example = contract?.examples.find( + ({ title }) => + title === + "Report observed return-property presence when static values stay unknown", + ); + if (example === undefined) + throw new Error("Missing advertised presence example"); + const { client, close } = await createApplicationMcpHarness(); + onTestFinished(close); + const listing = await client.listTools(); + const advertised = listing.tools.find( + ({ name }) => name === "compare_javascript_export_shapes", + ); + const examples = z.array(z.unknown()).parse(advertised?.inputSchema.examples); + expect(new Set(examples.map((input) => JSON.stringify(input))).size).toBe( + examples.length, + ); + const response = await client.callTool({ + name: "compare_javascript_export_shapes", + arguments: example.input, + }); + expect(response.isError).not.toBe(true); + expect(response.structuredContent).toMatchObject({ + result: { + left: { status: "selected" }, + right: { status: "selected" }, + summary: { added: 1, removed: 1, changed: 0, unknown: 0 }, + property_inventories: expect.arrayContaining([ + expect.objectContaining({ + side: "left", + paired: true, + properties: ["/count", "/kind"], + }), + expect.objectContaining({ + side: "right", + paired: true, + properties: ["/kind", "/total"], + }), + ]), + changes: expect.arrayContaining([ + expect.objectContaining({ + path: "/count", + status: "removed", + presence: { left: "present", right: "absent" }, + left: { availability: "unknown", reason: expect.any(String) }, + }), + expect.objectContaining({ + path: "/total", + status: "added", + presence: { left: "absent", right: "present" }, + right: { availability: "unknown", reason: expect.any(String) }, + }), + ]), + }, + }); +}); + +it("traces example semantic modules with their parsed artifact digests", async () => { + const { client, close } = await createApplicationMcpHarness(); + onTestFinished(close); + for (const application of [ + JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE.left, + JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE.right, + ]) { + const analysis = javascriptApplicationAnalysisResultSchema.parse( + application.normalized_result, + ); + const module = analysis.semantic_graph.nodes.find( + ({ kind }) => kind === "module", + ); + if (module === undefined || !module.evidence.artifact.available) + throw new Error("Example must retain an artifact-backed semantic module"); + const response = await client.callTool({ + name: "trace_javascript_semantics", + arguments: { + application, + query: { + seed: { kind: "semantic-node", node_id: module.node_id }, + direction: "ownership", + }, + }, + }); + expect(response.isError).not.toBe(true); + expect(response.structuredContent).toMatchObject({ + result: { + nodes: expect.arrayContaining([ + expect.objectContaining({ + node_id: module.node_id, + identity: expect.objectContaining({ + artifact_sha256: module.evidence.artifact.sha256, + }), + }), + ]), + }, + }); + } +}); describe("application workflow MCP parity", () => { it("compares exact parser export shapes with inline Evidence", async () => { @@ -68,15 +174,35 @@ describe("application workflow MCP parity", () => { expect(full.structuredContent).toMatchObject({ result: { summary: { added: 1, removed: 0, changed: 0, unknown: 0 }, + property_inventories: expect.arrayContaining([ + expect.objectContaining({ + side: "right", + paired: true, + properties: expect.arrayContaining(["/depth"]), + }), + ]), changes: [ { status: "added", path: "/depth", + presence: { left: "absent", right: "present" }, right: { availability: "literal", value: 1 }, }, ], }, }); + const advertised = (await client.listTools()).tools.find( + ({ name }) => name === "compare_javascript_export_shapes", + ); + if (advertised?.outputSchema === undefined) + throw new Error("Missing advertised export-shape output schema"); + const validate = new Ajv2020({ + strict: false, + validateFormats: false, + }).compile( + z.record(z.string(), z.unknown()).parse(advertised.outputSchema), + ); + expect(validate(full.structuredContent)).toBe(true); expect(session.exportEvidenceBundle().records).toEqual( expect.arrayContaining([ expect.objectContaining({ diff --git a/tests/boundary/mcp/applicationMutationPresenceMcp.test.ts b/tests/boundary/mcp/applicationMutationPresenceMcp.test.ts new file mode 100644 index 000000000..47e0591a2 --- /dev/null +++ b/tests/boundary/mcp/applicationMutationPresenceMcp.test.ts @@ -0,0 +1,113 @@ +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { expect, it, onTestFinished } from "vitest"; +import { z } from "zod"; + +import { analyzeJavaScriptApplication } from "../../../src/application/javascript/JavaScriptApplicationService.js"; +import { javascriptApplicationAnalysisResultSchema } from "../../../src/domain/javascript/javascriptApplicationAnalysis.js"; +import { javaScriptSemanticTraceResultSchema } from "../../../src/domain/javascript/javascriptSemanticTraceSchemas.js"; +import { createApplicationMcpHarness } from "../../fixtures/applicationMcpHarness.js"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; + +it.each([ + { + title: "deleting an absent slot", + initializer: '{ kind: "r" }', + mutation: "delete result.count;", + uncertainPresence: true, + }, + { + title: "deleting an initialized slot", + initializer: '{ kind: "r", count: 1 }', + mutation: "delete result.count;", + uncertainPresence: true, + }, + { + title: "assigning an absent slot", + initializer: '{ kind: "r" }', + mutation: "result.count = query();", + uncertainPresence: true, + }, + { + title: "an unresolved value with known presence", + initializer: '{ kind: "r", count: query() }', + mutation: "", + uncertainPresence: false, + }, +])( + "respects property presence when tracing $title", + async ({ initializer, mutation, uncertainPresence }) => { + const root = await createTestTempDirectory("rea-mutation-presence-mcp-"); + await writeFile( + join(root, "parser.mjs"), + `export default function make() { + const result = ${initializer}; + ${mutation} + return result; + }`, + ); + const application = await analyzeJavaScriptApplication({ + input_path: root, + }); + if (!application.ok) throw application.error; + const graph = javascriptApplicationAnalysisResultSchema.parse( + application.value.normalized_result, + ).semantic_graph; + const binding = graph.nodes.find( + ({ kind, label }) => kind === "binding" && label === "result", + ); + const uncertain = graph.nodes.find( + ({ kind, properties }) => + kind === "property-slot" && properties.name === "count", + ); + const known = graph.nodes.find( + ({ kind, properties }) => + kind === "property-slot" && properties.name === "kind", + ); + if (binding === undefined || uncertain === undefined || known === undefined) + throw new Error("Expected binding and both property slots"); + + const { client, close } = await createApplicationMcpHarness(); + onTestFinished(close); + for (const includeCandidates of [false, true]) { + const response = await client.callTool({ + name: "trace_javascript_semantics", + arguments: { + application: application.value, + query: { + seed: { kind: "semantic-node", node_id: binding.node_id }, + direction: "forward-influence", + allowed_relations: ["writes-property"], + include_ambiguous_dynamic_edges: includeCandidates, + }, + }, + }); + expect(response.isError).not.toBe(true); + const { result } = z + .object({ result: javaScriptSemanticTraceResultSchema }) + .parse(response.structuredContent); + const nodeIds = result.nodes.map(({ node_id }) => node_id); + expect(nodeIds).toContain(known.node_id); + expect(nodeIds.includes(uncertain.node_id)).toBe( + includeCandidates || !uncertainPresence, + ); + expect(result.relations).toContainEqual( + expect.objectContaining({ + source_node_id: binding.node_id, + target_node_id: known.node_id, + relation: "writes-property", + resolution: "resolved", + }), + ); + if (includeCandidates || !uncertainPresence) + expect(result.relations).toContainEqual( + expect.objectContaining({ + source_node_id: binding.node_id, + target_node_id: uncertain.node_id, + relation: "writes-property", + resolution: uncertainPresence ? "candidate" : "resolved", + }), + ); + } + }, +); diff --git a/tests/boundary/mcp/retainedApplicationEvidenceMcp.test.ts b/tests/boundary/mcp/retainedApplicationEvidenceMcp.test.ts index c01fd212f..1dfe0093a 100644 --- a/tests/boundary/mcp/retainedApplicationEvidenceMcp.test.ts +++ b/tests/boundary/mcp/retainedApplicationEvidenceMcp.test.ts @@ -21,6 +21,7 @@ const retained = (evidence_id: string) => ({ }); const application = JAVASCRIPT_FEATURE_TRACE_EXAMPLE.application; const pair = JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE; +const exportPair = JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE; async function connect() { const session = createTestBinarySession(() => { @@ -39,6 +40,8 @@ it("runs the same trace/compare workflows with inline and retained application E const { client, session } = await connect(); expect(session.recordEvidence(pair.left).ok).toBe(true); expect(session.recordEvidence(pair.right).ok).toBe(true); + expect(session.recordEvidence(exportPair.left).ok).toBe(true); + expect(session.recordEvidence(exportPair.right).ok).toBe(true); const scenarios = [ { name: "trace_application_feature", @@ -61,8 +64,8 @@ it("runs the same trace/compare workflows with inline and retained application E inline: JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE, refs: { ...JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE, - left: retained(pair.left.evidence_id), - right: retained(pair.right.evidence_id), + left: retained(exportPair.left.evidence_id), + right: retained(exportPair.right.evidence_id), }, }, {