From 940d71a45aadd9e6b90977396f48b17928fa6154 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Fri, 30 Oct 2026 05:41:58 +0800 Subject: [PATCH] refactor(analysis-view): break the analysis view hub cycle (#8061) * refactor(analysis-view): break the analysis view hub cycle Move request fragments, the request union, and the result union out of analysisView.ts so projectors no longer import the module that imports them. The dispatcher re-exports the public schemas and seals projector results. Co-authored-by: morluto * fix(analysis-view): check inferred projector results Require each projector result to match the unsigned result union before sealing it, and parse the cycle guard's imports with Babel so comments and side-effect imports are not misread. * fix(analysis-view): close IL2CPP and Android symbol view inputs Admit those projectors through AdmittedView and check test selections against their request schemas, so misspelled fields fail at the call site. --------- Co-authored-by: Cursor Agent Co-authored-by: morluto --- .../EnvironmentManifestAccumulator.ts | 29 +- .../EnvironmentStateAccumulator.ts | 28 +- .../WebNetworkApiSurfaceAccumulator.ts | 26 +- .../WebNetworkProjectionAccumulator.ts | 2 +- src/domain/analysisView/analysisView.ts | 1773 +++-------------- .../analysisView/analysisViewCycles.test.ts | 167 ++ src/domain/analysisView/analysisViewParent.ts | 21 +- .../analysisView/analysisViewRequest.ts | 132 ++ src/domain/analysisView/analysisViewResult.ts | 1277 ++++++++++++ src/domain/analysisView/analysisViewShape.ts | 127 ++ src/domain/analysisView/androidJniView.ts | 66 +- src/domain/analysisView/androidPackageView.ts | 37 +- .../analysisView/androidSymbolView.test.ts | 11 +- src/domain/analysisView/androidSymbolView.ts | 31 +- src/domain/analysisView/apiSurfaceSchema.ts | 67 + src/domain/analysisView/apkSignatureView.ts | 24 +- .../artifactInventoryView.test.ts | 3 +- .../analysisView/artifactInventoryView.ts | 43 +- src/domain/analysisView/binaryLayoutView.ts | 37 +- .../analysisView/browserScenarioView.ts | 26 +- src/domain/analysisView/byteEntropyView.ts | 25 +- .../analysisView/commandObservationView.ts | 25 +- src/domain/analysisView/dartAotView.ts | 27 +- .../analysisView/desktopApplicationView.ts | 27 +- src/domain/analysisView/devicetreeView.ts | 25 +- .../analysisView/environmentCoverageView.ts | 17 +- .../analysisView/environmentManifestSchema.ts | 90 + .../analysisView/environmentManifestView.ts | 134 +- .../analysisView/environmentStateView.ts | 27 +- src/domain/analysisView/erlangBeamView.ts | 27 +- src/domain/analysisView/evmInterfaceView.ts | 31 +- .../analysisView/fridaSessionStatusView.ts | 25 +- src/domain/analysisView/goBinaryView.ts | 33 +- src/domain/analysisView/gpuCodeObjectsView.ts | 28 +- .../analysisView/il2cppMetadataView.test.ts | 38 +- src/domain/analysisView/il2cppMetadataView.ts | 24 +- .../analysisView/interfaceBuilderView.ts | 24 +- .../analysisView/javascriptApplicationView.ts | 49 +- .../analysisView/javascriptRoutesView.ts | 17 +- src/domain/analysisView/machoView.ts | 22 +- .../analysisView/managedArtifactView.ts | 27 +- .../analysisView/managedMemberView.test.ts | 6 +- src/domain/analysisView/managedMemberView.ts | 27 +- src/domain/analysisView/modelArtifactView.ts | 27 +- src/domain/analysisView/nativeExportsView.ts | 27 +- .../nativeFunctionMatchingView.ts | 25 +- src/domain/analysisView/nativeFunctionView.ts | 39 +- .../analysisView/nativeInventoryView.ts | 33 +- .../analysisView/nativeLoadImageView.ts | 27 +- .../analysisView/nativeObservationView.ts | 31 +- src/domain/analysisView/pcapCaptureView.ts | 31 +- src/domain/analysisView/pythonPycView.ts | 27 +- src/domain/analysisView/rustBinaryView.ts | 36 +- .../analysisView/scenarioCaptureRecords.ts | 2 +- src/domain/analysisView/sourceToBundleView.ts | 27 +- src/domain/analysisView/wasmArtifactView.ts | 31 +- src/domain/analysisView/webBundleView.ts | 30 +- .../analysisView/webNetworkApiSurfaceView.ts | 106 +- .../analysisView/webNetworkCaptureView.ts | 33 +- 59 files changed, 2915 insertions(+), 2319 deletions(-) create mode 100644 src/domain/analysisView/analysisViewCycles.test.ts create mode 100644 src/domain/analysisView/analysisViewRequest.ts create mode 100644 src/domain/analysisView/analysisViewResult.ts create mode 100644 src/domain/analysisView/analysisViewShape.ts create mode 100644 src/domain/analysisView/apiSurfaceSchema.ts create mode 100644 src/domain/analysisView/environmentManifestSchema.ts diff --git a/src/domain/analysisView/EnvironmentManifestAccumulator.ts b/src/domain/analysisView/EnvironmentManifestAccumulator.ts index 5dd44d28d2..fb3018c064 100644 --- a/src/domain/analysisView/EnvironmentManifestAccumulator.ts +++ b/src/domain/analysisView/EnvironmentManifestAccumulator.ts @@ -16,7 +16,8 @@ import { } from "./recordedResponseBody.js"; import { readRecordedRequestBody } from "./recordedExchangeBody.js"; import { isJson, isJsonLike, mediaTypeEssence } from "./recordedMediaType.js"; -import type { UnsignedAnalysisView } from "./analysisView.js"; +import { z } from "zod"; +import { environmentManifestFields } from "./environmentManifestSchema.js"; import type { ScenarioResponseBodyRetention } from "./scenarioCaptureRecords.js"; import { WebNetworkProjectionAccumulator } from "./WebNetworkProjectionAccumulator.js"; import { @@ -55,21 +56,13 @@ import { type RouteTemplate, } from "./webNetworkRouteTemplates.js"; -type Manifest = Extract; -type ManifestFields = Pick< - Manifest, - | "origin" - | "name" - | "tools" - | "records" - | "excluded" - | "unknowns" - | "templated_groups" - | "coverage" - | "limitations" ->; -type Tool = Manifest["tools"][number]; -type Exclusion = Manifest["excluded"][number]; +type ManifestCore = { + [Key in keyof typeof environmentManifestFields]: z.output< + (typeof environmentManifestFields)[Key] + >; +}; +type Tool = ManifestCore["tools"][number]; +type Exclusion = ManifestCore["excluded"][number]; type RequestLine = Extract; interface RecordLine { @@ -134,7 +127,7 @@ const WRITE_METHODS = new Set(["POST", "PUT", "PATCH"]); const BODILESS_WRITE_METHODS = new Set([...WRITE_METHODS, "DELETE"]); /** Quotes, separators and brackets a four-part composite key adds around its texts. */ const KEY_OVERHEAD_CHARS = 32; -const UNKNOWNS: Manifest["unknowns"] = [ +const UNKNOWNS: ManifestCore["unknowns"] = [ { kind: "authorization-model", statement: @@ -477,7 +470,7 @@ export class EnvironmentManifestAccumulator extends WebNetworkProjectionAccumula } /** Project the complete manifest; tools, records and exclusions are sorted deterministically. */ - finish(): Result { + finish() { const primary = primaryOrigin(this.#origins); const toolGroups: GroupState[] = []; const exclusions = new Map(); diff --git a/src/domain/analysisView/EnvironmentStateAccumulator.ts b/src/domain/analysisView/EnvironmentStateAccumulator.ts index bf8b2763c5..4808d9506f 100644 --- a/src/domain/analysisView/EnvironmentStateAccumulator.ts +++ b/src/domain/analysisView/EnvironmentStateAccumulator.ts @@ -11,7 +11,6 @@ import { WEB_NETWORK_CAPTURE_LIMITS, type WebNetworkCaptureRecord, } from "../webNetworkCapture.js"; -import type { UnsignedAnalysisView } from "./analysisView.js"; import { EnvironmentManifestAccumulator } from "./EnvironmentManifestAccumulator.js"; import { isJsonLike, mediaTypeEssence } from "./recordedMediaType.js"; import { readRecordedRequestBody } from "./recordedExchangeBody.js"; @@ -40,23 +39,6 @@ import { textBytes, } from "./webNetworkRouteTemplates.js"; -type StateView = Extract; -type StateFields = Pick< - StateView, - | "origin" - | "name" - | "timeline" - | "types" - | "entities" - | "documents" - | "views" - | "writes" - | "write_clock" - | "unknowns" - | "coverage" - | "limitations" ->; - /** * Levels the state's own nesting adds above a recorded value: Evidence, a `data/get` reply and a * JSON-RPC response hold a body's members about ten levels down, so a body must leave this much @@ -102,19 +84,19 @@ interface RecordEntry { readonly record: WebNetworkCaptureRecord; } -const UNKNOWNS: StateView["unknowns"] = [ +const UNKNOWNS = [ { - kind: "authorization-model", + kind: "authorization-model" as const, statement: "Authorization headers and cookies are structurally excluded from captures; the state states no authorization model.", }, { - kind: "response-semantics", + kind: "response-semantics" as const, statement: "Views reproduce their recorded responses from the state; they do not establish how the application computes responses, derived values or values copied outside entity objects.", }, { - kind: "state-transition", + kind: "state-transition" as const, statement: "The state is one snapshot from before the first related recorded write; write effects are modelled only from the calls the capture recorded, and served only where its later reads confirmed them.", }, @@ -340,7 +322,7 @@ export class EnvironmentStateAccumulator extends EnvironmentManifestAccumulator } /** Project the init state of the manifest's primary origin; records keep timeline order. */ - finishState(): Result { + finishState() { const manifest = this.finish(); if (!manifest.ok) return manifest; const entries = [...this.#entries.values()].filter( diff --git a/src/domain/analysisView/WebNetworkApiSurfaceAccumulator.ts b/src/domain/analysisView/WebNetworkApiSurfaceAccumulator.ts index 5f603b26b3..fbbf65426d 100644 --- a/src/domain/analysisView/WebNetworkApiSurfaceAccumulator.ts +++ b/src/domain/analysisView/WebNetworkApiSurfaceAccumulator.ts @@ -7,7 +7,8 @@ import { type WebNetworkCaptureRecord, } from "../webNetworkCapture.js"; import { pageViewCoverage } from "./analysisViewCoverage.js"; -import type { UnsignedAnalysisView } from "./analysisView.js"; +import { z } from "zod"; +import { apiSurfaceFields } from "./apiSurfaceSchema.js"; import { WebNetworkProjectionAccumulator } from "./WebNetworkProjectionAccumulator.js"; import { CAPTURE_CONTAINER_BYTES, @@ -23,9 +24,13 @@ import { type RouteTemplate, } from "./webNetworkRouteTemplates.js"; -type Surface = Extract; -type Group = Surface["groups"][number]; -type Exclusion = Surface["excluded_records"][number]; +type ApiSurfaceFields = { + [Key in keyof typeof apiSurfaceFields]: z.output< + (typeof apiSurfaceFields)[Key] + >; +}; +type Group = ApiSurfaceFields["groups"][number]; +type Exclusion = ApiSurfaceFields["excluded_records"][number]; interface GroupState { readonly method: string; readonly origin: string; @@ -181,18 +186,7 @@ export class WebNetworkApiSurfaceAccumulator extends WebNetworkProjectionAccumul return ok(undefined); } - page( - offset: number, - limit: number, - ): Pick< - Surface, - | "coverage" - | "groups" - | "templated_groups" - | "excluded_records" - | "limitations" - | "unknowns" - > { + page(offset: number, limit: number) { this.#groups.sort( (a, b) => compare(a.origin, b.origin) || diff --git a/src/domain/analysisView/WebNetworkProjectionAccumulator.ts b/src/domain/analysisView/WebNetworkProjectionAccumulator.ts index 0c9d7128e3..05099da027 100644 --- a/src/domain/analysisView/WebNetworkProjectionAccumulator.ts +++ b/src/domain/analysisView/WebNetworkProjectionAccumulator.ts @@ -14,7 +14,7 @@ import { import { admitAnalysisViewData } from "./analysisViewDataAdmission.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { analysisViewResultInputError } from "./analysisViewParent.js"; -import type { AnalysisViewParent } from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; import { ENTRY_BYTES, textBytes, diff --git a/src/domain/analysisView/analysisView.ts b/src/domain/analysisView/analysisView.ts index cb32f401f7..b68199ab1c 100644 --- a/src/domain/analysisView/analysisView.ts +++ b/src/domain/analysisView/analysisView.ts @@ -1,184 +1,32 @@ -import { analysisViewCoverageSchema } from "./analysisViewCoverage.js"; -import { - javaScriptRouteInventorySourceSchema, - javaScriptRouteInventorySchema, -} from "../javascript/javascriptRouteInventory.js"; -import { nativeFunctionMatchingContextSchema } from "../native/functionMatching.js"; -import { - nativeObservationViewRequestSchema, - nativeContextViewRequestSchema, - nativeObservationItemsSchemas, - nativeContextItemsSchemas, - nativeSourceContextReferenceSchema, - nativeObservationOperationSchema, -} from "./nativeObservationSchemas.js"; -import { - NATIVE_OBSERVATION_OPERATIONS, - type NativeObservationOperation, -} from "../native/nativeObservation.js"; +import { NATIVE_OBSERVATION_OPERATIONS } from "../native/nativeObservation.js"; import { projectNativeObservationView } from "./nativeObservationView.js"; -import { - devicetreeViewRequestSchema, - devicetreeViewItemsSchema, - devicetreeSummarySchema, - devicetreePageContextSchema, - projectDevicetreeView, -} from "./devicetreeView.js"; -import { - apkSignatureViewRequestSchema, - apkSignatureViewItemsSchema, -} from "../apkSignature/apkSignatureQuery.js"; -import { - projectApkSignatureView, - apkSignatureSummarySchema, - apkSignatureSourceCoverageSchema, -} from "./apkSignatureView.js"; +import { projectDevicetreeView } from "./devicetreeView.js"; +import { projectApkSignatureView } from "./apkSignatureView.js"; import { byteEntropySchema } from "../native/byteEntropy.js"; -import { - erlangBeamViewRequestSchema, - erlangBeamViewPageSchema, - erlangBeamSummarySchema, - projectErlangBeamView, -} from "./erlangBeamView.js"; -import { - pythonPycViewRequestSchema, - pythonPycViewItemsSchema, - pythonPycSummarySchema, - projectPythonPycView, -} from "./pythonPycView.js"; -import { - nativeExportsViewRequestSchema, - nativeExportsViewItemsSchema, - nativeExportsSummarySchema, - projectNativeExportsView, -} from "./nativeExportsView.js"; -import { - byteEntropySummarySchema, - projectByteEntropyView, -} from "./byteEntropyView.js"; +import { projectErlangBeamView } from "./erlangBeamView.js"; +import { projectPythonPycView } from "./pythonPycView.js"; +import { projectNativeExportsView } from "./nativeExportsView.js"; +import { projectByteEntropyView } from "./byteEntropyView.js"; import { parseAnalysisViewResult, analysisViewResultInputError, } from "./analysisViewParent.js"; -import { - javaScriptRoutesViewRequestSchema, - javaScriptRoutesViewItemsSchema, - javaScriptRoutesViewSummarySchema, - projectJavaScriptRoutesView, -} from "./javascriptRoutesView.js"; -import { - webBundleViewRequestSchema, - webBundleViewItemsSchema, - webBundleSummarySchema, - projectWebBundleView, -} from "./webBundleView.js"; -import { webBundleAnalysisSchema } from "../webBundleAnalysis.js"; -import { recordedBrowserOriginSchema } from "../browserObservation.js"; -import { - sourceToBundleViewRequestSchema, - sourceToBundleViewItemsSchema, - sourceToBundleViewContextSchema, - projectSourceToBundleView, -} from "./sourceToBundleView.js"; -import { - gpuCodeObjectsViewRequestSchema, - gpuCodeObjectsSummarySchema, - gpuCodeObjectsItemsSchema, - gpuCodeObjectsPtxPageSchema, - projectGpuCodeObjectsView, -} from "./gpuCodeObjectsView.js"; -import { gpuCodeObjectsObjectSchema } from "../gpu/gpuCodeObjects.js"; -import { modelArtifactViewRequestSchema } from "../model/modelArtifactQuery.js"; -import { - projectModelArtifactView, - modelArtifactSummarySchema, - modelArtifactViewItemsSchema, - modelArtifactViewContextSchema, -} from "./modelArtifactView.js"; -import { - commandSummaryContext, - gdbCommandSummarySchema, - projectCommandObservationView, -} from "./commandObservationView.js"; -import { - fridaSessionStatusSummarySchema, - fridaSessionStatusViewContext, - projectFridaSessionStatusView, -} from "./fridaSessionStatusView.js"; -import { commandObservationSchema } from "../commandObservation.js"; -import { - rustBinaryViewPageSchema, - rustBinaryViewRequestSchema, -} from "../rust/rustBinaryQuery.js"; -import { - goBinarySummarySchema, - goBinaryViewContextSchema, - goBinaryViewPageSchema, - goBinaryViewRequestSchema, - projectGoBinaryView, -} from "./goBinaryView.js"; -import { - rustBinarySummarySchema, - rustBinaryViewContextSchema, - projectRustBinaryView, -} from "./rustBinaryView.js"; -import { - projectNativeFunctionMatchingView, - nativeFunctionMatchingViewRequestSchema, - nativeFunctionMatchingViewItemsSchema, -} from "./nativeFunctionMatchingView.js"; -import { - protobufViewRequestSchema, - protobufViewItemsSchema, - protobufViewContextSchema, -} from "./protobufCaptureView.js"; -import { - nativeInventoryViewRequestSchema, - nativeInventoryViewRowSchema, - nativeInventorySummarySchema, - projectNativeInventoryView, -} from "./nativeInventoryView.js"; -import { nativeViewSourceContext } from "./nativeViewContext.js"; -import { - NATIVE_INVENTORY_OPERATIONS, - nativeInventoryOperationSchema, -} from "../native/nativeInventory.js"; - -import { - evidenceFileReferenceSchema, - retainedEvidenceReferenceSchema, -} from "../evidenceReference.js"; +import { projectJavaScriptRoutesView } from "./javascriptRoutesView.js"; +import { projectWebBundleView } from "./webBundleView.js"; +import { projectSourceToBundleView } from "./sourceToBundleView.js"; +import { projectGpuCodeObjectsView } from "./gpuCodeObjectsView.js"; +import { projectModelArtifactView } from "./modelArtifactView.js"; +import { projectCommandObservationView } from "./commandObservationView.js"; +import { projectFridaSessionStatusView } from "./fridaSessionStatusView.js"; +import { projectGoBinaryView } from "./goBinaryView.js"; +import { projectRustBinaryView } from "./rustBinaryView.js"; +import { projectNativeFunctionMatchingView } from "./nativeFunctionMatchingView.js"; +import { projectNativeInventoryView } from "./nativeInventoryView.js"; +import { NATIVE_INVENTORY_OPERATIONS } from "../native/nativeInventory.js"; import { z } from "zod"; -import { - browserScenarioSummarySchema, - browserScenarioViewContextSchema, - browserScenarioViewItemsSchema, - browserScenarioViewRequestSchema, -} from "./browserScenarioViewSchemas.js"; import { projectBrowserScenarioView } from "./browserScenarioView.js"; -import { - nativeLoadImageViewRequestSchema, - nativeLoadImageViewItemsSchema, - nativeLoadImageSummarySchema, - projectNativeLoadImageView, -} from "./nativeLoadImageView.js"; -import { - desktopViewRequestSchema, - desktopViewItemsSchema, - desktopSummarySchema, - projectDesktopApplicationView, -} from "./desktopApplicationView.js"; -import { desktopCoverageSchema } from "../desktopApplication.js"; -import { - javascriptModuleReferencesRequestSchema, - javascriptModuleReferenceSchema, -} from "./javascriptModuleReferences.js"; -import { javascriptApplicationSourceCoverageSchema } from "./javascriptApplicationCoverage.js"; -import { - javascriptFactsViewRequestSchema, - javascriptFactRowSchema, -} from "./javascriptFactsView.js"; -import { javaScriptSourceSelectionSchema } from "../javascript/javascriptSourceSelection.js"; +import { projectNativeLoadImageView } from "./nativeLoadImageView.js"; +import { projectDesktopApplicationView } from "./desktopApplicationView.js"; import { AnalysisUnsupportedTargetError } from "../analysisErrorCore.js"; import { @@ -186,25 +34,11 @@ import { analysisViewInputError, } from "./analysisViewErrors.js"; import { digestCanonicalValue } from "../canonicalDigest.js"; -import { digestSchema, prefixedDigestSchema } from "../digests.js"; -import { evidenceSchema, type Evidence } from "../evidence.js"; -import { jsonObjectSchema, jsonValueSchema } from "../jsonValue.js"; +import { digestSchema } from "../digests.js"; import { err, ok, type Result } from "../result.js"; import type { AnalysisError } from "../analysisErrorBase.js"; -import { - binaryLayoutSchema, - safeParseOwnedBinaryLayout, -} from "../native/binaryLayout.js"; -import { bundleResourceRootSchema } from "../apple/bundleResourceRoot.js"; -import { - functionDossierSchema, - functionFacetAvailabilitySchema, -} from "../native/functionDossier.js"; -import { - artifactGraphManifestSchema, - artifactInventoryCoverageSchema, -} from "../artifactGraph.js"; -import { artifactInspectionResultSchema } from "../artifactInspection.js"; +import { safeParseOwnedBinaryLayout } from "../native/binaryLayout.js"; +import { functionDossierSchema } from "../native/functionDossier.js"; import { parseOwnedJavaScriptApplicationAnalysisSteps, type JavaScriptApplicationAnalysisResult, @@ -214,62 +48,16 @@ import { projectJavaScriptApplicationView } from "./javascriptApplicationView.js import { createApiSurfaceAccumulator, projectWebNetworkApiSurfaceView, - apiSurfaceFields, - apiSurfaceViewSchema, } from "./webNetworkApiSurfaceView.js"; import { projectNativeFunctionView } from "./nativeFunctionView.js"; -import { - projectEvmInterfaceView, - evmViewRequestSchema, - evmViewItemSchema, - evmSummarySchema, -} from "./evmInterfaceView.js"; -import { - projectArtifactInventoryView, - artifactInventoryViewRequestSchema, - artifactInventoryItemsSchema, - artifactInventorySummarySchema, -} from "./artifactInventoryView.js"; -import { - projectManagedArtifactView, - managedViewRequestSchema, - managedViewItemSchema, - managedSummarySchema, - managedViewContextSchema, -} from "./managedArtifactView.js"; -import { - managedMembersViewRequestSchema, - managedMembersViewPageSchema, - managedMemberSummarySchema, - managedMembersViewContextSchema, -} from "./managedMemberViewSchemas.js"; +import { projectEvmInterfaceView } from "./evmInterfaceView.js"; +import { projectArtifactInventoryView } from "./artifactInventoryView.js"; +import { projectManagedArtifactView } from "./managedArtifactView.js"; import { projectManagedMemberView } from "./managedMemberView.js"; -import { - projectWasmArtifactView, - wasmViewRequestSchema, - wasmViewItemSchema, - wasmSummarySchema, -} from "./wasmArtifactView.js"; -import { - machoSummarySchema, - machoViewContextSchema, - machoViewRows, - machoViewRequestSchema, - projectMachoView, -} from "./machoView.js"; -import { - interfaceBuilderSummarySchema, - interfaceBuilderViewContextSchema, - interfaceBuilderViewItemsSchema, - interfaceBuilderViewRequestSchema, - projectInterfaceBuilderView, -} from "./interfaceBuilderView.js"; -import { - projectWebNetworkCaptureView, - captureViewRequestSchema, - captureViewItemsSchema, - captureSummarySchema, -} from "./webNetworkCaptureView.js"; +import { projectWasmArtifactView } from "./wasmArtifactView.js"; +import { projectMachoView } from "./machoView.js"; +import { projectInterfaceBuilderView } from "./interfaceBuilderView.js"; +import { projectWebNetworkCaptureView } from "./webNetworkCaptureView.js"; import type { WebNetworkApiSurfaceAccumulator } from "./WebNetworkApiSurfaceAccumulator.js"; import type { EnvironmentManifestAccumulator } from "./EnvironmentManifestAccumulator.js"; import type { EnvironmentStateAccumulator } from "./EnvironmentStateAccumulator.js"; @@ -277,1262 +65,155 @@ import { admitAnalysisViewData } from "./analysisViewDataAdmission.js"; import { createEnvironmentManifestAccumulator, projectEnvironmentManifestView, - environmentManifestFields, - environmentManifestViewRequestSchema, } from "./environmentManifestView.js"; import { createEnvironmentStateAccumulator, - environmentStateFields, - environmentStateViewRequestSchema, projectEnvironmentStateView, } from "./environmentStateView.js"; +import { projectEnvironmentCoverageView } from "./environmentCoverageView.js"; +import { projectPcapCaptureView } from "./pcapCaptureView.js"; +import { projectAndroidPackageView } from "./androidPackageView.js"; +import { projectAndroidSymbolSummary } from "./androidSymbolView.js"; +import { projectAndroidJniView } from "./androidJniView.js"; +import { projectDartAotView } from "./dartAotView.js"; +import { projectIl2cppMetadataView } from "./il2cppMetadataView.js"; + +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import type { GroupingViewKind } from "./analysisViewShape.js"; import { - environmentCoverageFields, - environmentCoverageViewRequestSchema, - projectEnvironmentCoverageView, -} from "./environmentCoverageView.js"; + analysisViewRequestSchema, + analysisViewSourceSchema, + inspectAnalysisViewInputSchema, + type AnalysisViewRequest, + type InspectAnalysisViewInput, +} from "./analysisViewRequest.js"; import { - pcapViewRequestSchema, - pcapViewPageSchema, - pcapSummarySchema, - projectPcapCaptureView, -} from "./pcapCaptureView.js"; -import { - qlogViewRequestSchema, - qlogViewPageSchema, - qlogViewContextSchema, -} from "./qlogCaptureView.js"; -import { - projectAndroidPackageView, - androidPackageSummarySchema, - androidViewRequestSchema, - androidManifestViewItemSchema, - androidManifestViewRequestSchema, - androidComponentsViewRequestSchema, - androidComponentSummaryViewRequestSchema, - androidComponentViewRowSchema, - androidComponentViewContextSchema, - androidComponentSummarySchema, -} from "./androidPackageView.js"; -import { - projectAndroidSymbolSummary, - androidClassSummarySchema, - androidMethodSummarySchema, -} from "./androidSymbolView.js"; -import { - projectAndroidJniView, - androidJniSummarySchema, -} from "./androidJniView.js"; -import { - androidJniViewRequestSchema, - androidJniViewItemsSchema, -} from "../android/androidJniQuery.js"; -import { - projectDartAotView, - dartAotSummarySchema, - dartAotViewRequestSchema, - dartAotViewContextSchema, -} from "./dartAotView.js"; -import { - projectIl2cppMetadataView, - il2cppMetadataSummarySchema, - il2cppMetadataViewRequestSchema, - il2cppMetadataViewContextSchema, - il2cppMetadataViewItemsSchema, -} from "./il2cppMetadataView.js"; - -const summaryViewSchema = z.strictObject({ kind: z.literal("summary") }); -const facetViewSchema = z.strictObject({ - kind: z.literal("facet"), - facet: z.enum(["mitigations", "linkage"]), -}); -const indexSelectorSchema = z.strictObject({ - index: z.int().nonnegative(), -}); -const nameSelectorSchema = z.strictObject({ - name: z - .string() - .describe( - "Exact UTF-8 section or symbol name, matched against retained source bytes. Use index for non-UTF-8 names or unresolved name bytes.", - ), -}); -const pathSelectorSchema = z.strictObject({ - path: z - .string() - .describe( - "Exact observed module path or original source-map reference from a module page; an empty reference is valid.", - ), -}); -const nodeIdSelectorSchema = z.strictObject({ - node_id: prefixedDigestSchema("jag_node"), -}); -const moduleItemViewSchema = z.strictObject({ - kind: z.literal("item"), - collection: z.literal("modules"), - selector: z.union([pathSelectorSchema, nodeIdSelectorSchema]), -}); -const sectionOrSymbolItemViewSchema = z.strictObject({ - kind: z.literal("item"), - collection: z.enum(["sections", "symbols"]), - selector: z.union([indexSelectorSchema, nameSelectorSchema]), -}); -/** - * The collection-specific selector alternatives are expressed in the owning - * contract so the advertised JSON Schema preserves them: modules accept - * path/node_id, sections and symbols accept index/name. Refinement-only - * constraints do not survive JSON Schema conversion, so the advertised - * schema previously accepted combinations that runtime input validation - * rejects. - */ -const itemViewSchema = z.discriminatedUnion("collection", [ - moduleItemViewSchema, - sectionOrSymbolItemViewSchema, -]); -const pageViewSchema = z.strictObject({ - kind: z.literal("page"), - collection: z.enum(["sections", "symbols", "modules"]), - offset: z.int().nonnegative(), - limit: z.int().positive(), -}); - -/** Bounded native function facets of already authenticated analyze_function Evidence. */ -const nativeViewSchema = z.strictObject({ - kind: z.literal("native"), - facet: z.enum([ - "procedure", - "pseudocode", - "assembly", - "basic_blocks", - "comments", - "callers", - "callees", - "incoming_references", - "outgoing_references", - "unresolved_calls", - "referenced_strings", - "referenced_names", - "swift_string_literals", - "swift_string_literal_omissions", - "native_api", - "value_flow_summary", - "value_flow_operations", - "value_flow_def_use", - "value_flow_effects", - "value_flow_parameters", - "value_flow_parameter_uses", - ]), - offset: z.int().nonnegative().default(0), - limit: z.int().positive().default(64), -}); - -/** Caller-selected projection of already completed analysis Evidence. */ -export const analysisViewRequestSchema = z.discriminatedUnion("kind", [ - nativeObservationViewRequestSchema, - nativeContextViewRequestSchema, - devicetreeViewRequestSchema, - erlangBeamViewRequestSchema, - pythonPycViewRequestSchema, - nativeExportsViewRequestSchema, - javaScriptRoutesViewRequestSchema, - webBundleViewRequestSchema, - nativeFunctionMatchingViewRequestSchema, - sourceToBundleViewRequestSchema, - summaryViewSchema, - goBinaryViewRequestSchema, - rustBinaryViewRequestSchema, - desktopViewRequestSchema, - facetViewSchema, - itemViewSchema, - pageViewSchema, - javascriptModuleReferencesRequestSchema, - javascriptFactsViewRequestSchema, - nativeViewSchema, - nativeInventoryViewRequestSchema, - nativeLoadImageViewRequestSchema, - artifactInventoryViewRequestSchema, - wasmViewRequestSchema, - machoViewRequestSchema, - interfaceBuilderViewRequestSchema, - evmViewRequestSchema, - managedViewRequestSchema, - managedMembersViewRequestSchema, - androidViewRequestSchema, - androidJniViewRequestSchema, - apiSurfaceViewSchema, - environmentManifestViewRequestSchema, - environmentStateViewRequestSchema, - environmentCoverageViewRequestSchema, - captureViewRequestSchema, - browserScenarioViewRequestSchema, - protobufViewRequestSchema, - qlogViewRequestSchema, - pcapViewRequestSchema, - dartAotViewRequestSchema, - il2cppMetadataViewRequestSchema, - apkSignatureViewRequestSchema, - modelArtifactViewRequestSchema, - gpuCodeObjectsViewRequestSchema, -]); - -// The application owns admission and authenticated Evidence parsing. SDK and -// CLI envelope parsing must borrow this unknown value rather than clone it -// before admission. Advertise the owning Evidence contract in both dialects. -const inlineEvidenceInputSchema = z.unknown().nonoptional(); -inlineEvidenceInputSchema._zod.processJSONSchema = - evidenceSchema._zod.processJSONSchema; - -/** Unauthenticated inline input, an exact same-session retained reference, or one local Evidence file. */ -export const analysisViewSourceSchema = z.discriminatedUnion("kind", [ - retainedEvidenceReferenceSchema, - z.strictObject({ - kind: z.literal("inline"), - evidence: inlineEvidenceInputSchema, - }), - evidenceFileReferenceSchema, -]); - -/** Public inspect_analysis_view input. */ -export const inspectAnalysisViewInputSchema = z.strictObject({ - source: analysisViewSourceSchema, - view: analysisViewRequestSchema, -}); - -const artifactSchema = z.strictObject({ - path: z - .string() - .describe( - "Selected artifact path, or the canonical resource root when resource-only Evidence has no executable subject.", - ), - sha256: digestSchema.nullable(), -}); - -const layoutSummarySchema = z.strictObject({ - bytes: binaryLayoutSchema.shape.artifact.shape.bytes, - format: binaryLayoutSchema.shape.format, - architecture: binaryLayoutSchema.shape.architecture, - image_type: binaryLayoutSchema.shape.image_type, - entry: z.strictObject({ - reported_value: z.string().min(1), - meaning: z.enum(["linked-virtual-address", "not-applicable", "absent"]), - execution_status: z.literal("unknown"), - }), - counts: z.strictObject({ - sections: z.int().nonnegative(), - segments: z.int().nonnegative(), - symbols: z.int().nonnegative(), - relocations: z.int().nonnegative(), - }), - limitation_count: z.int().nonnegative(), -}); - -const javascriptSummarySchema = z.strictObject({ - input_path: z.string().min(1), - format: z.enum(["asar", "directory"]), - root_artifact_sha256: digestSchema, - source_selection: javaScriptSourceSelectionSchema.exactOptional(), - statistics: jsonObjectSchema, - electron: jsonObjectSchema, - coverage: jsonObjectSchema, - limitation_count: z.int().nonnegative(), -}); - -const viewResultBase = { - parent_evidence_id: prefixedDigestSchema("ev"), - parent_operation: z.enum([ - "inspect_python_pyc", - "inspect_erlang_beam", - "inspect_devicetree", - "inspect_byte_entropy", - "inspect_native_exports", - "inspect_binary_layout", - "inspect_go_binary", - "gdb_console", - "frida_session_status", - "inspect_with_objdump", - "inspect_desktop_application", - "analyze_javascript_application", - "analyze_web_bundle", - "analyze_function", - "inspect_artifact", - "inventory_artifact", - "inspect_wasm_artifact", - "inspect_macho", - "decode_interface_builder", - "inspect_evm_interface", - "inspect_managed_artifact", - "inspect_managed_members", - "inspect_web_network_capture", - "inspect_android_package", - "inspect_android_class", - "inspect_android_method", - "inspect_android_jni_bindings", - "inspect_pcap_capture", - "inspect_dart_aot", - "inspect_il2cpp_metadata", - "inspect_model_artifact", - "inspect_gpu_code_objects", - ...NATIVE_INVENTORY_OPERATIONS, - ...NATIVE_OBSERVATION_OPERATIONS, - "match_native_functions", - ]), - parent_digest: digestSchema, - view_digest: digestSchema, - artifact: artifactSchema, - coverage: analysisViewCoverageSchema, - limitations: z.array(z.string()), - unknowns: z.array(z.string()), -} as const; - -const summaryViewResultBase = { - kind: z.literal("summary"), - view: summaryViewSchema, - ...viewResultBase, -} as const; - -const nativeObservationSummaryFor = < - Operation extends NativeObservationOperation, ->( - operation: Operation, -) => - z.strictObject({ - ...summaryViewResultBase, - ...nativeViewSourceContext, - artifact: artifactSchema.nullable(), - parent_operation: z.literal(operation), - source_context: nativeSourceContextReferenceSchema, - summary: z.strictObject({ observations: z.int().nonnegative() }), - items: nativeObservationItemsSchemas[operation], - }); -export const nativeObservationSummaryViewResultSchemas = { - procedure_address: nativeObservationSummaryFor("procedure_address"), - procedure_callees: nativeObservationSummaryFor("procedure_callees"), - procedure_callers: nativeObservationSummaryFor("procedure_callers"), - resolve_containing_procedure: nativeObservationSummaryFor( - "resolve_containing_procedure", - ), - get_call_graph: nativeObservationSummaryFor("get_call_graph"), -}; -const nativeObservationSummaryViewResultSchema = z.discriminatedUnion( - "parent_operation", - [ - nativeObservationSummaryViewResultSchemas.procedure_address, - nativeObservationSummaryViewResultSchemas.procedure_callees, - nativeObservationSummaryViewResultSchemas.procedure_callers, - nativeObservationSummaryViewResultSchemas.resolve_containing_procedure, - nativeObservationSummaryViewResultSchemas.get_call_graph, - ], -); -const nativeObservationPageFor = ( - operation: Operation, -) => - nativeObservationSummaryFor(operation) - .omit({ kind: true, view: true }) - .extend({ - kind: z.literal("native-observation"), - view: nativeObservationViewRequestSchema, - }); -const nativeObservationPageViewResultSchema = z.discriminatedUnion( - "parent_operation", - [ - nativeObservationPageFor("procedure_address"), - nativeObservationPageFor("procedure_callees"), - nativeObservationPageFor("procedure_callers"), - nativeObservationPageFor("resolve_containing_procedure"), - nativeObservationPageFor("get_call_graph"), - ], -); -const nativeContextFor = ( - facet: Facet, -) => - z.strictObject({ - ...viewResultBase, - ...nativeViewSourceContext, - kind: z.literal("native-context"), - artifact: artifactSchema.nullable(), - parent_operation: nativeObservationOperationSchema, - source_context: nativeSourceContextReferenceSchema, - facet: z.literal(facet), - view: nativeContextViewRequestSchema.extend({ facet: z.literal(facet) }), - items: nativeContextItemsSchemas[facet], - }); -const nativeContextViewResultSchema = z.discriminatedUnion("facet", [ - nativeContextFor("overview"), - nativeContextFor("analysis-profile"), - nativeContextFor("limitations"), - nativeContextFor("result-limitations"), -]); - -export const byteEntropySummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - summary: byteEntropySummarySchema, - parent_operation: z.literal("inspect_byte_entropy"), -}); - -export const nativeExportsSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_native_exports"), - summary: nativeExportsSummarySchema, -}); - -export const devicetreeSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_devicetree"), - summary: devicetreeSummarySchema, -}); -export const erlangBeamSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_erlang_beam"), - summary: erlangBeamSummarySchema, -}); -export const erlangBeamTableViewResultSchema = z.strictObject({ - ...viewResultBase, - kind: z.literal("beam"), - parent_operation: z.literal("inspect_erlang_beam"), - view: erlangBeamViewRequestSchema, - beam: erlangBeamSummarySchema, - page: erlangBeamViewPageSchema, -}); - -export const pythonPycSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_python_pyc"), - summary: pythonPycSummarySchema, -}); - -export const pythonPycCodeObjectsViewResultSchema = z.strictObject({ - ...viewResultBase, - kind: z.literal("python-pyc"), - parent_operation: z.literal("inspect_python_pyc"), - view: pythonPycViewRequestSchema, - pyc: pythonPycSummarySchema, - items: pythonPycViewItemsSchema, -}); - -/** Opt-in command delivery keeps output once and retains the complete parent. */ -export const gdbCommandSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - ...commandSummaryContext, - parent_operation: z.literal("gdb_console"), - artifact: artifactSchema.nullable(), - summary: gdbCommandSummarySchema, -}); - -export const objdumpSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - ...commandSummaryContext, - parent_operation: z.literal("inspect_with_objdump"), - artifact: artifactSchema.nullable(), - summary: commandObservationSchema, -}); - -export const fridaSessionStatusSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - ...fridaSessionStatusViewContext, - parent_operation: z.literal("frida_session_status"), - artifact: artifactSchema.nullable(), - summary: fridaSessionStatusSummarySchema, -}); - -/** Opt-in Go delivery retains original bytes and exposes build identity/counts. */ -export const goBinarySummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - ...goBinaryViewContextSchema.shape, - parent_operation: z.literal("inspect_go_binary"), - summary: goBinarySummarySchema, -}); - -/** Compact source identity and counts, retaining the complete embedded graph. */ -export const rustBinarySummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - ...rustBinaryViewContextSchema.shape, - parent_operation: z.literal("inspect_rust_binary"), - summary: rustBinarySummarySchema, -}); - -export const rustBinaryPageViewResultSchema = z.strictObject({ - ...viewResultBase, - ...rustBinaryViewContextSchema.shape, - kind: z.literal("rust"), - parent_operation: z.literal("inspect_rust_binary"), - view: rustBinaryViewRequestSchema, - rust: rustBinarySummarySchema, - page: rustBinaryViewPageSchema, -}); - -/** Summary `inspect_binary_layout` detail returns; no other view kind. */ -export const binaryLayoutSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - summary: layoutSummarySchema, - parent_operation: z.literal("inspect_binary_layout"), -}); - -/** Summary `analyze_javascript_application` detail returns; no other view kind. */ -export const javascriptApplicationSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - summary: javascriptSummarySchema, - parent_operation: z.literal("analyze_javascript_application"), -}); - -/** Typed reference page; full item observations remain available separately. */ -export const javascriptModuleReferencesViewResultSchema = z.strictObject({ - ...viewResultBase, - kind: z.literal("javascript"), - view: javascriptModuleReferencesRequestSchema, - parent_operation: z.literal("analyze_javascript_application"), - rows: z.array(javascriptModuleReferenceSchema), - source_coverage: javascriptApplicationSourceCoverageSchema, -}); - -/** Paged retained observations with exact selected properties and provenance. */ -const javascriptFactsViewResultSchema = z.strictObject({ - ...viewResultBase, - kind: z.literal("javascript-facts"), - view: javascriptFactsViewRequestSchema, - parent_operation: z.literal("analyze_javascript_application"), - rows: z.array(javascriptFactRowSchema), - source_coverage: javascriptApplicationSourceCoverageSchema, -}); - -/** Exact summary carrier for artifact inspection's optional delivery contract. */ -export const artifactInventorySummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.enum(["inspect_artifact", "inventory_artifact"]), - summary: artifactInventorySummarySchema, -}); - -export const desktopApplicationSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_desktop_application"), - summary: desktopSummarySchema, -}); - -/** Exact summary carrier for WASM inspection's optional delivery contract. */ -export const wasmArtifactSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_wasm_artifact"), - summary: wasmSummarySchema, -}); - -/** Exact slice identity and collection counts for Mach-O's selected delivery. */ -export const machoSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_macho"), - summary: machoSummarySchema, -}); - -/** Decoded documents and graph counts for Interface Builder's selected delivery. */ -export const interfaceBuilderSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("decode_interface_builder"), - resource_root: bundleResourceRootSchema.optional(), - summary: interfaceBuilderSummarySchema, -}); - -/** Exact inferred-interface summary for EVM's caller-selected delivery. */ -export const evmInterfaceSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_evm_interface"), - summary: evmSummarySchema, -}); - -/** Exact metadata overview for the managed artifact's selected delivery. */ -export const managedArtifactSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_managed_artifact"), - summary: managedSummarySchema, -}); - -/** Exact member selection, coverage and counts for the selected delivery. */ -export const managedMemberSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_managed_members"), - summary: managedMemberSummarySchema, -}); - -/** Exact historical capture summary, with no body or member-inventory payload. */ -export const webNetworkCaptureSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_web_network_capture"), - summary: captureSummarySchema, -}); - -/** Compact outcomes and the focus screen from a retained browser scenario. */ -export const browserScenarioSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - artifact: z.null(), - parent_operation: z.literal("capture_browser_scenario"), - summary: browserScenarioSummarySchema, -}); - -/** Exact package declarations with retained decoded manifest text. */ -export const androidPackageSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_android_package"), - summary: androidPackageSummarySchema, -}); -export const androidJniSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_android_jni_bindings"), - summary: androidJniSummarySchema, -}); -export const androidJniPageViewResultSchema = z.strictObject({ - ...viewResultBase, - kind: z.literal("android-jni"), - parent_operation: z.literal("inspect_android_jni_bindings"), - view: androidJniViewRequestSchema, - items: androidJniViewItemsSchema, - source: androidJniSummarySchema.pick({ - native_inventory: true, - library_inventory: true, - selection: true, - }), -}); - -/** Exact class facts with complete raw protocol Evidence retained separately. */ -export const androidClassSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_android_class"), - summary: androidClassSummarySchema, -}); - -/** Exact selected method body, source coverage and optional mapping facts. */ -export const androidMethodSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_android_method"), - summary: androidMethodSummarySchema, -}); - -/** Legacy manifest views keep their original shape; new facets are explicit. */ -export const androidManifestViewResultSchema = z.strictObject({ - ...viewResultBase, - kind: z.literal("android"), - facet: z.literal("manifest").optional(), - view: androidManifestViewRequestSchema, - item: androidManifestViewItemSchema, - parent_operation: z.literal("inspect_android_package"), -}); -export const androidComponentsViewResultSchema = z.strictObject({ - ...viewResultBase, - ...androidComponentViewContextSchema.shape, - kind: z.literal("android"), - facet: z.literal("components"), - view: androidComponentsViewRequestSchema, - items: z.array(androidComponentViewRowSchema), - byte_limited: z.boolean(), - parent_operation: z.literal("inspect_android_package"), -}); -export const androidComponentSummaryViewResultSchema = z.strictObject({ - ...viewResultBase, - ...androidComponentViewContextSchema.shape, - kind: z.literal("android"), - facet: z.literal("component-summary"), - view: androidComponentSummaryViewRequestSchema, - summary: androidComponentSummarySchema, - parent_operation: z.literal("inspect_android_package"), -}); -const androidPackageViewResultSchema = z.discriminatedUnion("facet", [ + nativeObservationSummaryViewResultSchemas, + byteEntropySummaryViewResultSchema, + nativeExportsSummaryViewResultSchema, + devicetreeSummaryViewResultSchema, + erlangBeamSummaryViewResultSchema, + erlangBeamTableViewResultSchema, + pythonPycSummaryViewResultSchema, + pythonPycCodeObjectsViewResultSchema, + gdbCommandSummaryViewResultSchema, + objdumpSummaryViewResultSchema, + fridaSessionStatusSummaryViewResultSchema, + goBinarySummaryViewResultSchema, + rustBinarySummaryViewResultSchema, + rustBinaryPageViewResultSchema, + binaryLayoutSummaryViewResultSchema, + javascriptApplicationSummaryViewResultSchema, + javascriptModuleReferencesViewResultSchema, + artifactInventorySummaryViewResultSchema, + desktopApplicationSummaryViewResultSchema, + wasmArtifactSummaryViewResultSchema, + machoSummaryViewResultSchema, + interfaceBuilderSummaryViewResultSchema, + evmInterfaceSummaryViewResultSchema, + managedArtifactSummaryViewResultSchema, + managedMemberSummaryViewResultSchema, + webNetworkCaptureSummaryViewResultSchema, + browserScenarioSummaryViewResultSchema, + androidPackageSummaryViewResultSchema, + androidJniSummaryViewResultSchema, + androidJniPageViewResultSchema, + androidClassSummaryViewResultSchema, + androidMethodSummaryViewResultSchema, androidManifestViewResultSchema, androidComponentsViewResultSchema, androidComponentSummaryViewResultSchema, -]); - -export const pcapCaptureSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_pcap_capture"), - summary: pcapSummarySchema, -}); - -/** Exact snapshot and pool-coverage carrier for selected AOT delivery. */ -export const dartAotSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_dart_aot"), - summary: dartAotSummarySchema, -}); - -export const javaScriptRoutesViewResultSchema = z.strictObject({ - ...viewResultBase, - artifact: artifactSchema.nullable(), - kind: z.literal("javascript-routes"), - parent_operation: z.enum([ - "analyze_javascript_application", - "analyze_web_bundle", - ]), - view: javaScriptRoutesViewRequestSchema, - inventory_id: javaScriptRouteInventorySchema.shape.inventory_id, - source_manifest_sha256: digestSchema, - source_coverage: javaScriptRouteInventorySchema.shape.coverage, - inventory_capacity: javaScriptRouteInventorySchema.shape.capacity, - capture_url: z.string().nullable(), - items: javaScriptRoutesViewItemsSchema, - sources: z.array(javaScriptRouteInventorySourceSchema), - summary: javaScriptRoutesViewSummarySchema.nullable(), - byte_limited: z.boolean(), -}); - -/** Compact web bundle findings retain endpoint observations and inference candidates. */ -export const webBundleSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - artifact: artifactSchema.nullable(), - parent_operation: z.literal("analyze_web_bundle"), - target_url: z.string(), - target_origin: recordedBrowserOriginSchema.nullable().optional(), - source_unknowns: webBundleAnalysisSchema.shape.unknowns, - summary: webBundleSummarySchema, -}); - -export const webBundlePageViewResultSchema = z.strictObject({ - ...viewResultBase, - artifact: artifactSchema.nullable(), - kind: z.literal("web-bundle"), - parent_operation: z.literal("analyze_web_bundle"), - target_url: z.string(), - target_origin: recordedBrowserOriginSchema.nullable().optional(), - source_unknowns: webBundleAnalysisSchema.shape.unknowns, - view: webBundleViewRequestSchema, - completeness: webBundleAnalysisSchema.shape.completeness, - items: webBundleViewItemsSchema, - summary: webBundleSummarySchema.nullable(), - byte_limited: z.boolean(), -}); - -export const gpuCodeObjectsSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_gpu_code_objects"), - summary: gpuCodeObjectsSummarySchema, -}); -export const gpuCodeObjectsPageViewResultSchema = z.strictObject({ - kind: z.literal("gpu-code-objects"), - view: gpuCodeObjectsViewRequestSchema, - items: gpuCodeObjectsItemsSchema, - ptx: gpuCodeObjectsPtxPageSchema.nullable(), - source_coverage: gpuCodeObjectsObjectSchema.shape.coverage, - ...viewResultBase, - parent_operation: z.literal("inspect_gpu_code_objects"), -}); - -export const apkSignatureSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_apk_signature"), - summary: apkSignatureSummarySchema, -}); -export const apkSignaturePageViewResultSchema = z.strictObject({ - ...viewResultBase, - kind: z.literal("apk-signature"), - parent_operation: z.literal("inspect_apk_signature"), - view: apkSignatureViewRequestSchema, - items: apkSignatureViewItemsSchema, - source_coverage: apkSignatureSourceCoverageSchema, -}); - -export const modelArtifactSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_model_artifact"), - summary: modelArtifactSummarySchema, -}); - -export const modelArtifactPageViewResultSchema = z.strictObject({ - kind: z.literal("model-artifact"), - view: modelArtifactViewRequestSchema, - items: modelArtifactViewItemsSchema, - ...viewResultBase, - ...modelArtifactViewContextSchema.shape, - parent_operation: z.literal("inspect_model_artifact"), -}); - -/** Metadata identity and row counts for selected IL2CPP delivery. */ -export const il2cppMetadataSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_il2cpp_metadata"), - summary: il2cppMetadataSummarySchema, -}); - -/** Exact inventory summary with the original observation's provider and query. */ -export const nativeInventorySummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - ...nativeViewSourceContext, - parent_operation: nativeInventoryOperationSchema, - artifact: artifactSchema.nullable(), - summary: nativeInventorySummarySchema, -}); - -/** Compact provider load observations retain the independent verification state. */ -export const nativeLoadImageSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - ...nativeViewSourceContext, - artifact: artifactSchema.nullable(), - parent_operation: z.literal("inspect_native_load_image"), - summary: nativeLoadImageSummarySchema, -}); - -/** Compact native matching discovery retains the complete matching report. */ -export const nativeFunctionMatchingSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - artifact: z.null(), - parent_operation: z.literal("match_native_functions"), - summary: nativeFunctionMatchingContextSchema, -}); - -/** Rows observed for one facet, or null when the provider declared that facet unavailable. */ -const declaredFacetCountSchema = z - .number() - .int() - .nonnegative() - .nullable() - .describe( - "Observed rows; null when facet_availability declares the facet unavailable, so no rows is not evidence of none.", - ); - -/** Rows of an optional dossier record, or null when the dossier omitted it. */ -const recordedFacetCountSchema = z - .number() - .int() - .nonnegative() - .nullable() - .describe( - "Observed rows; null when the dossier did not record the facet (the native facet view reports it not recorded), so no rows is not evidence of none.", - ); - -/** Rows of one value-flow facet, or null when value flow is unavailable. */ -const valueFlowFacetCountSchema = z - .number() - .int() - .nonnegative() - .nullable() - .describe( - "Observed rows; null when value_flow.available is false because native_value_flow was not recorded or the provider declared it unavailable (unknowns names which), so no rows is not evidence of none.", - ); - -/** Compact analyze_function dossier; the complete dossier stays retained for facet paging. */ -export const nativeFunctionSummarySchema = z.strictObject({ - procedure: z.strictObject({ - name: z.string(), - address: z.string(), - }), - pseudocode: z.strictObject({ - available: z - .boolean() - .describe( - "Provider facet_availability for pseudocode when declared; otherwise whether decompiled text is present. The flag is authoritative over raw length.", - ), - code_units: z - .number() - .int() - .nonnegative() - .describe( - "Pseudocode length in UTF-16 code units, the unit inspect_analysis_view pages pseudocode by.", - ), - }), - value_flow: z.strictObject({ - available: z.boolean(), - truncated: z - .boolean() - .describe( - "True only when value-flow is available and the provider truncated it; false when value-flow is unavailable (see available).", - ), - }), - facet_availability: functionFacetAvailabilitySchema - .nullable() - .describe( - "The provider's declared availability per facet, or null when it declared none. Unavailable facets name their reason here and in unknowns.", - ), - counts: z.strictObject({ - assembly: declaredFacetCountSchema, - basic_blocks: declaredFacetCountSchema, - comments: declaredFacetCountSchema, - callers: declaredFacetCountSchema, - callees: declaredFacetCountSchema, - incoming_references: declaredFacetCountSchema, - outgoing_references: declaredFacetCountSchema, - unresolved_calls: recordedFacetCountSchema, - referenced_strings: declaredFacetCountSchema, - referenced_names: declaredFacetCountSchema, - swift_string_literals: recordedFacetCountSchema, - swift_string_literal_omissions: recordedFacetCountSchema, - value_flow_operations: valueFlowFacetCountSchema, - value_flow_def_use: valueFlowFacetCountSchema, - value_flow_effects: valueFlowFacetCountSchema, - value_flow_parameters: valueFlowFacetCountSchema, - value_flow_parameter_uses: valueFlowFacetCountSchema, - }), - limitation_count: z.number().int().nonnegative(), -}); - -/** Compact analyze_function summary that retains the complete native dossier Evidence. */ -export const nativeFunctionSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("analyze_function"), - procedure_address: z.string().nullable(), - summary: nativeFunctionSummarySchema, -}); - -export const sourceToBundleSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - artifact: z.null(), - parent_operation: z.literal("compare_source_to_bundle"), - summary: sourceToBundleViewContextSchema, -}); -export const sourceToBundlePageViewResultSchema = z.strictObject({ - ...viewResultBase, - ...sourceToBundleViewContextSchema.shape, - kind: z.literal("source-to-bundle"), - artifact: z.null(), - parent_operation: z.literal("compare_source_to_bundle"), - view: sourceToBundleViewRequestSchema, - items: sourceToBundleViewItemsSchema, -}); - -/** Bind the existing nested facet selection to its producer-owned rows. */ -const machoPage = (facet: Facet) => - z.strictObject({ - ...viewResultBase, - ...machoViewContextSchema.shape, - kind: z.literal("macho"), - parent_operation: z.literal("inspect_macho"), - view: machoViewRequestSchema.extend({ facet: z.literal(facet) }), - item: machoViewRows[facet], - }); - -// The input tag preserves kind dispatch; the output projection advertises the -// correlated pages without adding a discriminator to their public wire shape. -const machoPageViewResultSchema = z - .object({ kind: z.literal("macho") }) - .passthrough() - .pipe( - z.union([ - machoPage("entrypoints"), - machoPage("architectures"), - machoPage("build_metadata"), - machoPage("load_commands"), - machoPage("dependencies"), - machoPage("imports"), - machoPage("exports"), - machoPage("segments"), - machoPage("encryption"), - machoPage("provenance"), - ]), - ); - -/** Projected facts for one selected view of retained analysis Evidence. */ -export const analysisViewResultSchema = z.discriminatedUnion("kind", [ - nativeObservationPageViewResultSchema, - nativeContextViewResultSchema, + pcapCaptureSummaryViewResultSchema, + dartAotSummaryViewResultSchema, javaScriptRoutesViewResultSchema, + webBundleSummaryViewResultSchema, webBundlePageViewResultSchema, - sourceToBundlePageViewResultSchema, - z.strictObject({ - ...viewResultBase, - ...nativeFunctionMatchingContextSchema.shape, - kind: z.literal("function-matches"), - artifact: z.null(), - view: nativeFunctionMatchingViewRequestSchema, - items: nativeFunctionMatchingViewItemsSchema, - parent_operation: z.literal("match_native_functions"), - }), - z.strictObject({ - ...viewResultBase, - ...apiSurfaceFields, - kind: z.literal("api-surface"), - parent_operation: z.literal("inspect_web_network_capture"), - view: apiSurfaceViewSchema, - artifact: z.strictObject({ - path: z.string(), - sha256: digestSchema.nullable(), - }), - }), - z.strictObject({ - ...viewResultBase, - ...environmentManifestFields, - kind: z.literal("environment-manifest"), - parent_operation: z.enum([ - "inspect_web_network_capture", - "capture_browser_scenario", - ]), - view: environmentManifestViewRequestSchema, - }), - z.strictObject({ - ...viewResultBase, - ...environmentStateFields, - kind: z.literal("environment-state"), - parent_operation: z.enum([ - "inspect_web_network_capture", - "capture_browser_scenario", - ]), - view: environmentStateViewRequestSchema, - }), - z.strictObject({ - ...viewResultBase, - ...environmentCoverageFields, - kind: z.literal("environment-coverage"), - parent_operation: z.enum([ - "inspect_web_network_capture", - "capture_browser_scenario", - ]), - view: environmentCoverageViewRequestSchema, - }), - z.discriminatedUnion("parent_operation", [ - nativeObservationSummaryViewResultSchema, - erlangBeamSummaryViewResultSchema, - devicetreeSummaryViewResultSchema, - pythonPycSummaryViewResultSchema, - nativeExportsSummaryViewResultSchema, - byteEntropySummaryViewResultSchema, - gdbCommandSummaryViewResultSchema, - objdumpSummaryViewResultSchema, - fridaSessionStatusSummaryViewResultSchema, - goBinarySummaryViewResultSchema, - rustBinarySummaryViewResultSchema, - binaryLayoutSummaryViewResultSchema, - desktopApplicationSummaryViewResultSchema, - javascriptApplicationSummaryViewResultSchema, - artifactInventorySummaryViewResultSchema, - wasmArtifactSummaryViewResultSchema, - machoSummaryViewResultSchema, - interfaceBuilderSummaryViewResultSchema, - evmInterfaceSummaryViewResultSchema, - managedArtifactSummaryViewResultSchema, - managedMemberSummaryViewResultSchema, - webNetworkCaptureSummaryViewResultSchema, - browserScenarioSummaryViewResultSchema, - androidPackageSummaryViewResultSchema, - androidJniSummaryViewResultSchema, - androidClassSummaryViewResultSchema, - androidMethodSummaryViewResultSchema, - pcapCaptureSummaryViewResultSchema, - dartAotSummaryViewResultSchema, - il2cppMetadataSummaryViewResultSchema, - apkSignatureSummaryViewResultSchema, - modelArtifactSummaryViewResultSchema, - gpuCodeObjectsSummaryViewResultSchema, - nativeInventorySummaryViewResultSchema, - nativeLoadImageSummaryViewResultSchema, - nativeFunctionMatchingSummaryViewResultSchema, - nativeFunctionSummaryViewResultSchema, - sourceToBundleSummaryViewResultSchema, - webBundleSummaryViewResultSchema, - ]), - z.strictObject({ - ...viewResultBase, - kind: z.literal("devicetree"), - parent_operation: z.literal("inspect_devicetree"), - view: devicetreeViewRequestSchema, - devicetree: devicetreePageContextSchema, - items: devicetreeViewItemsSchema, - }), - erlangBeamTableViewResultSchema, - pythonPycCodeObjectsViewResultSchema, - z.strictObject({ - ...viewResultBase, - kind: z.literal("native-exports"), - parent_operation: z.literal("inspect_native_exports"), - view: nativeExportsViewRequestSchema, - exports: nativeExportsSummarySchema, - items: nativeExportsViewItemsSchema, - }), - z.strictObject({ - ...viewResultBase, - ...nativeViewSourceContext, - kind: z.literal("native-inventory"), - parent_operation: nativeInventoryOperationSchema, - artifact: artifactSchema.nullable(), - view: nativeInventoryViewRequestSchema, - rows: z.array(nativeInventoryViewRowSchema), - }), - z.strictObject({ - ...viewResultBase, - kind: z.literal("native-load-image"), - ...nativeViewSourceContext, - verification_status: z.enum(["unsupported", "verified", "mismatch"]), - parent_operation: z.literal("inspect_native_load_image"), - artifact: artifactSchema.nullable(), - view: nativeLoadImageViewRequestSchema, - items: nativeLoadImageViewItemsSchema, - }), - z.strictObject({ - kind: z.literal("protobuf"), - view: protobufViewRequestSchema, - items: protobufViewItemsSchema, - ...viewResultBase, - ...protobufViewContextSchema.shape, - parent_operation: z.literal("inspect_web_network_capture"), - }), - z.strictObject({ - kind: z.literal("capture"), - view: captureViewRequestSchema, - items: captureViewItemsSchema, - ...viewResultBase, - parent_operation: z.literal("inspect_web_network_capture"), - }), - z.strictObject({ - kind: z.literal("browser-scenario"), - view: browserScenarioViewRequestSchema, - items: browserScenarioViewItemsSchema, - ...viewResultBase, - ...browserScenarioViewContextSchema.shape, - artifact: z.null(), - parent_operation: z.literal("capture_browser_scenario"), - }), - z.strictObject({ - kind: z.literal("qlog"), - view: qlogViewRequestSchema, - page: qlogViewPageSchema, - context: qlogViewContextSchema, - ...viewResultBase, - parent_operation: z.literal("inspect_web_network_capture"), - }), - z.strictObject({ - kind: z.literal("pcap"), - view: pcapViewRequestSchema, - page: pcapViewPageSchema, - source_coverage: z.enum(["complete", "partial"]), - ...viewResultBase, - parent_operation: z.literal("inspect_pcap_capture"), - }), - z.strictObject({ - kind: z.literal("facet"), - view: facetViewSchema, - facet: jsonValueSchema, - ...viewResultBase, - }), - z.strictObject({ - ...viewResultBase, - ...goBinaryViewContextSchema.shape, - kind: z.literal("go"), - parent_operation: z.literal("inspect_go_binary"), - view: goBinaryViewRequestSchema, - page: goBinaryViewPageSchema, - }), - rustBinaryPageViewResultSchema, - z.strictObject({ - kind: z.literal("item"), - view: itemViewSchema, - item: jsonValueSchema, - ...viewResultBase, - }), - z.strictObject({ - kind: z.literal("page"), - view: pageViewSchema, - items: z.array(jsonValueSchema), - ...viewResultBase, - }), - javascriptModuleReferencesViewResultSchema, - javascriptFactsViewResultSchema, - z.strictObject({ - kind: z.literal("native"), - view: nativeViewSchema, - procedure_address: z.string().nullable(), - item: jsonValueSchema, - ...viewResultBase, - }), - z.strictObject({ - kind: z.literal("wasm"), - view: wasmViewRequestSchema, - item: wasmViewItemSchema, - ...viewResultBase, - }), - z.strictObject({ - kind: z.literal("desktop-application"), - view: desktopViewRequestSchema, - items: desktopViewItemsSchema, - ...viewResultBase, - source_coverage: desktopCoverageSchema, - parent_operation: z.literal("inspect_desktop_application"), - }), - machoPageViewResultSchema, - z.strictObject({ - kind: z.literal("interface-builder"), - view: interfaceBuilderViewRequestSchema, - items: interfaceBuilderViewItemsSchema, - ...viewResultBase, - resource_root: bundleResourceRootSchema.optional(), - ...interfaceBuilderViewContextSchema.shape, - parent_operation: z.literal("decode_interface_builder"), - }), - z.strictObject({ - kind: z.literal("evm"), - view: evmViewRequestSchema, - item: evmViewItemSchema, - ...viewResultBase, - parent_operation: z.literal("inspect_evm_interface"), - }), - z.strictObject({ - kind: z.literal("managed"), - view: managedViewRequestSchema, - item: managedViewItemSchema, - ...viewResultBase, - ...managedViewContextSchema.shape, - parent_operation: z.literal("inspect_managed_artifact"), - }), - z.strictObject({ - kind: z.literal("managed-members"), - view: managedMembersViewRequestSchema, - page: managedMembersViewPageSchema, - ...viewResultBase, - ...managedMembersViewContextSchema.shape, - parent_operation: z.literal("inspect_managed_members"), - }), - androidPackageViewResultSchema, - androidJniPageViewResultSchema, - z.strictObject({ - kind: z.literal("dart-aot"), - view: dartAotViewRequestSchema, - items: z.array(z.string()), - ...viewResultBase, - ...dartAotViewContextSchema.shape, - parent_operation: z.literal("inspect_dart_aot"), - }), - apkSignaturePageViewResultSchema, - modelArtifactPageViewResultSchema, + gpuCodeObjectsSummaryViewResultSchema, gpuCodeObjectsPageViewResultSchema, - z.strictObject({ - kind: z.literal("il2cpp-metadata"), - view: il2cppMetadataViewRequestSchema, - items: il2cppMetadataViewItemsSchema, - ...viewResultBase, - ...il2cppMetadataViewContextSchema.shape, - parent_operation: z.literal("inspect_il2cpp_metadata"), - }), - z.strictObject({ - kind: z.literal("inventory"), - view: artifactInventoryViewRequestSchema, - source_coverage: artifactInventoryCoverageSchema.exactOptional(), - manifest: artifactGraphManifestSchema, - inventory_evidence_ids: z.array(prefixedDigestSchema("ev")).min(1), - source_complete: z.boolean(), - items: artifactInventoryItemsSchema, - ...viewResultBase, - }), -]); - -export type AnalysisViewRequest = z.output; -export type InspectAnalysisViewInput = z.output< - typeof inspectAnalysisViewInputSchema ->; -export type AnalysisViewResult = z.output; - -/** Parent record already resolved from inline Evidence or a session reference. */ -export interface AnalysisViewParent { - readonly evidenceId: string; - readonly operation: string; - readonly normalizedResult: unknown; - readonly provider?: Evidence["provider"]; - readonly analysisProfile?: Evidence["analysis_profile"]; - readonly authority?: Evidence["authority"]; - readonly environment?: Evidence["environment"]; - /** The owner proved normalizedResult belongs to a sealed, deep-frozen Evidence snapshot. */ - readonly sealedResult?: boolean; - /** Subject presentation for this delivery, including explicit absence. */ - readonly subject?: Evidence["subject"]; - readonly limitations: readonly string[]; - readonly artifact?: { readonly path: string; readonly sha256: string } | null; - /** Parent Evidence parameters, when the parent operation records them. */ - readonly parameters?: unknown; -} - -/** View payload before the content digest is attached. */ -type WithoutViewDigest = T extends { readonly view_digest: string } - ? Omit - : never; -export type UnsignedAnalysisView = WithoutViewDigest; + apkSignatureSummaryViewResultSchema, + apkSignaturePageViewResultSchema, + modelArtifactSummaryViewResultSchema, + modelArtifactPageViewResultSchema, + il2cppMetadataSummaryViewResultSchema, + nativeInventorySummaryViewResultSchema, + nativeLoadImageSummaryViewResultSchema, + nativeFunctionMatchingSummaryViewResultSchema, + nativeFunctionSummarySchema, + nativeFunctionSummaryViewResultSchema, + sourceToBundleSummaryViewResultSchema, + sourceToBundlePageViewResultSchema, + analysisViewResultSchema, + type AnalysisViewResult, + type UnsignedAnalysisView, +} from "./analysisViewResult.js"; +export { + analysisViewRequestSchema, + analysisViewSourceSchema, + inspectAnalysisViewInputSchema, + type AnalysisViewRequest, + type InspectAnalysisViewInput, + type AnalysisViewParent, +}; +export { type GroupingViewKind }; +export { + nativeObservationSummaryViewResultSchemas, + byteEntropySummaryViewResultSchema, + nativeExportsSummaryViewResultSchema, + devicetreeSummaryViewResultSchema, + erlangBeamSummaryViewResultSchema, + erlangBeamTableViewResultSchema, + pythonPycSummaryViewResultSchema, + pythonPycCodeObjectsViewResultSchema, + gdbCommandSummaryViewResultSchema, + objdumpSummaryViewResultSchema, + fridaSessionStatusSummaryViewResultSchema, + goBinarySummaryViewResultSchema, + rustBinarySummaryViewResultSchema, + rustBinaryPageViewResultSchema, + binaryLayoutSummaryViewResultSchema, + javascriptApplicationSummaryViewResultSchema, + javascriptModuleReferencesViewResultSchema, + artifactInventorySummaryViewResultSchema, + desktopApplicationSummaryViewResultSchema, + wasmArtifactSummaryViewResultSchema, + machoSummaryViewResultSchema, + interfaceBuilderSummaryViewResultSchema, + evmInterfaceSummaryViewResultSchema, + managedArtifactSummaryViewResultSchema, + managedMemberSummaryViewResultSchema, + webNetworkCaptureSummaryViewResultSchema, + browserScenarioSummaryViewResultSchema, + androidPackageSummaryViewResultSchema, + androidJniSummaryViewResultSchema, + androidJniPageViewResultSchema, + androidClassSummaryViewResultSchema, + androidMethodSummaryViewResultSchema, + androidManifestViewResultSchema, + androidComponentsViewResultSchema, + androidComponentSummaryViewResultSchema, + pcapCaptureSummaryViewResultSchema, + dartAotSummaryViewResultSchema, + javaScriptRoutesViewResultSchema, + webBundleSummaryViewResultSchema, + webBundlePageViewResultSchema, + gpuCodeObjectsSummaryViewResultSchema, + gpuCodeObjectsPageViewResultSchema, + apkSignatureSummaryViewResultSchema, + apkSignaturePageViewResultSchema, + modelArtifactSummaryViewResultSchema, + modelArtifactPageViewResultSchema, + il2cppMetadataSummaryViewResultSchema, + nativeInventorySummaryViewResultSchema, + nativeLoadImageSummaryViewResultSchema, + nativeFunctionMatchingSummaryViewResultSchema, + nativeFunctionSummarySchema, + nativeFunctionSummaryViewResultSchema, + sourceToBundleSummaryViewResultSchema, + sourceToBundlePageViewResultSchema, + analysisViewResultSchema, + type AnalysisViewResult, + type UnsignedAnalysisView, +}; /** Attach the content digest that must change when projected bytes change. */ export const sealAnalysisView = ( @@ -1591,46 +272,63 @@ const parentArtifactPath = (parent: AnalysisViewParent): string => { return parent.evidenceId; }; +/** Check a projector result against the result union before sealing it. */ +const sealProjected = ( + projected: Result, +): Result => + projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + /** Named source owners for views that need no extra decoder or accumulator. */ -const retainedViewProjectors = new Map([ - ...NATIVE_OBSERVATION_OPERATIONS.map( - (operation) => [operation, projectNativeObservationView] as const, +type RetainedViewProjector = ( + parent: AnalysisViewParent, + view: AnalysisViewRequest, +) => Result; + +/** Register a projector whose inferred result must be in the result union. */ +const retain = ( + operation: string, + project: RetainedViewProjector, +): readonly [string, RetainedViewProjector] => [operation, project]; + +const retainedViewProjectors = new Map([ + ...NATIVE_OBSERVATION_OPERATIONS.map((operation) => + retain(operation, projectNativeObservationView), ), - ["inspect_erlang_beam", projectErlangBeamView], - ["inspect_devicetree", projectDevicetreeView], - ["inspect_native_exports", projectNativeExportsView], - ["inspect_native_load_image", projectNativeLoadImageView], - ["inspect_python_pyc", projectPythonPycView], - ["frida_session_status", projectFridaSessionStatusView], - ["gdb_console", projectCommandObservationView], - ["inspect_with_objdump", projectCommandObservationView], - ["inspect_go_binary", projectGoBinaryView], - ["inspect_rust_binary", projectRustBinaryView], - ...NATIVE_INVENTORY_OPERATIONS.map( - (operation) => [operation, projectNativeInventoryView] as const, + retain("inspect_erlang_beam", projectErlangBeamView), + retain("inspect_devicetree", projectDevicetreeView), + retain("inspect_native_exports", projectNativeExportsView), + retain("inspect_native_load_image", projectNativeLoadImageView), + retain("inspect_python_pyc", projectPythonPycView), + retain("frida_session_status", projectFridaSessionStatusView), + retain("gdb_console", projectCommandObservationView), + retain("inspect_with_objdump", projectCommandObservationView), + retain("inspect_go_binary", projectGoBinaryView), + retain("inspect_rust_binary", projectRustBinaryView), + ...NATIVE_INVENTORY_OPERATIONS.map((operation) => + retain(operation, projectNativeInventoryView), ), - ["inspect_desktop_application", projectDesktopApplicationView], - ["inspect_wasm_artifact", projectWasmArtifactView], - ["inspect_macho", projectMachoView], - ["decode_interface_builder", projectInterfaceBuilderView], - ["inspect_evm_interface", projectEvmInterfaceView], - ["inspect_managed_artifact", projectManagedArtifactView], - ["inspect_managed_members", projectManagedMemberView], - ["inspect_android_package", projectAndroidPackageView], - ["inspect_android_class", projectAndroidSymbolSummary], - ["inspect_android_method", projectAndroidSymbolSummary], - ["inspect_android_jni_bindings", projectAndroidJniView], - ["capture_browser_scenario", projectBrowserScenarioView], - ["inspect_dart_aot", projectDartAotView], - ["inspect_il2cpp_metadata", projectIl2cppMetadataView], - ["inspect_apk_signature", projectApkSignatureView], - ["inspect_model_artifact", projectModelArtifactView], - ["inspect_gpu_code_objects", projectGpuCodeObjectsView], - ["match_native_functions", projectNativeFunctionMatchingView], - ["compare_source_to_bundle", projectSourceToBundleView], - ["inspect_artifact", projectArtifactInventoryView], - ["inventory_artifact", projectArtifactInventoryView], - ["analyze_web_bundle", projectWebBundleView], + retain("inspect_desktop_application", projectDesktopApplicationView), + retain("inspect_wasm_artifact", projectWasmArtifactView), + retain("inspect_macho", projectMachoView), + retain("decode_interface_builder", projectInterfaceBuilderView), + retain("inspect_evm_interface", projectEvmInterfaceView), + retain("inspect_managed_artifact", projectManagedArtifactView), + retain("inspect_managed_members", projectManagedMemberView), + retain("inspect_android_package", projectAndroidPackageView), + retain("inspect_android_class", projectAndroidSymbolSummary), + retain("inspect_android_method", projectAndroidSymbolSummary), + retain("inspect_android_jni_bindings", projectAndroidJniView), + retain("capture_browser_scenario", projectBrowserScenarioView), + retain("inspect_dart_aot", projectDartAotView), + retain("inspect_il2cpp_metadata", projectIl2cppMetadataView), + retain("inspect_apk_signature", projectApkSignatureView), + retain("inspect_model_artifact", projectModelArtifactView), + retain("inspect_gpu_code_objects", projectGpuCodeObjectsView), + retain("match_native_functions", projectNativeFunctionMatchingView), + retain("compare_source_to_bundle", projectSourceToBundleView), + retain("inspect_artifact", projectArtifactInventoryView), + retain("inventory_artifact", projectArtifactInventoryView), + retain("analyze_web_bundle", projectWebBundleView), ]); /** Budgets retained across source admission and the selected grouping projection. */ @@ -1674,13 +372,6 @@ export const prepareAnalysisViewProjection = ( }; }; -/** Views that group a capture's records into tools. */ -export type GroupingViewKind = - | "api-surface" - | "environment-manifest" - | "environment-state" - | "environment-coverage"; - type GroupingViewRequest = Extract< AnalysisViewRequest, { kind: GroupingViewKind } @@ -1699,7 +390,7 @@ const projectGroupingView = ( parent: AnalysisViewParent, view: GroupingViewRequest, accumulators: AnalysisViewAccumulators, -): Result => { +) => { if (view.kind === "api-surface") return projectWebNetworkApiSurfaceView( parent, @@ -1732,29 +423,29 @@ export const projectAnalysisView = ( ); if (view.kind === "javascript-routes") { const projected = projectJavaScriptRoutesView(parent, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } if (view.kind === "web-bundle") { const projected = projectWebBundleView(parent, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } if (isGroupingView(view)) { const grouped = projectGroupingView(parent, view, accumulators); - return grouped.ok ? ok(sealAnalysisView(grouped.value)) : grouped; + return sealProjected(grouped); } if (parent.operation === "inspect_web_network_capture") { const projected = projectWebNetworkCaptureView(parent, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } if (parent.operation === "inspect_pcap_capture") { const projected = projectPcapCaptureView(parent, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } if (parent.operation === "inspect_byte_entropy") { const report = parseAnalysisViewResult(byteEntropySchema, parent); if (!report.ok) return report; const projected = projectByteEntropyView(parent, report.value, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } if (parent.operation === "inspect_binary_layout") { const layout = parseAnalysisViewResult( @@ -1763,7 +454,7 @@ export const projectAnalysisView = ( ); if (!layout.ok) return layout; const projected = projectBinaryLayoutView(parent, layout.value, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } if (parent.operation === "analyze_javascript_application") { const analysis = parseJavaScriptParent(parent.normalizedResult); @@ -1773,18 +464,18 @@ export const projectAnalysisView = ( analysis.value, view, ); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } if (parent.operation === "analyze_function") { const native = parseAnalysisViewResult(functionDossierSchema, parent); if (!native.ok) return native; const projected = projectNativeFunctionView(parent, native.value, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } const project = retainedViewProjectors.get(parent.operation); if (project !== undefined) { const projected = project(parent, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } return err(unsupportedParent(parent)); }; diff --git a/src/domain/analysisView/analysisViewCycles.test.ts b/src/domain/analysisView/analysisViewCycles.test.ts new file mode 100644 index 0000000000..d4441ac681 --- /dev/null +++ b/src/domain/analysisView/analysisViewCycles.test.ts @@ -0,0 +1,167 @@ +import { parse } from "@babel/parser"; +import { traverseFast, type Node } from "@babel/types"; +import { readdirSync, readFileSync, statSync } from "node:fs"; +import { dirname, join, relative, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import { describe, expect, it } from "vitest"; + +const root = dirname(fileURLToPath(import.meta.url)); + +/** String specifiers only, matching scripts/lib/module-boundaries.mjs. */ +const literalValue = (node: Node | null | undefined): string | undefined => { + if (node?.type === "StringLiteral") return node.value; + if (node?.type === "TemplateLiteral" && node.expressions.length === 0) + return node.quasis[0]?.value.cooked ?? undefined; + return undefined; +}; + +const importSpecifier = (node: Node): string | undefined => { + switch (node.type) { + case "ImportDeclaration": + case "ExportAllDeclaration": + case "TSImportType": + return literalValue(node.source); + case "ExportNamedDeclaration": + case "ImportExpression": + return literalValue(node.source); + case "TSImportEqualsDeclaration": + return node.moduleReference.type === "TSExternalModuleReference" + ? literalValue(node.moduleReference.expression) + : undefined; + default: + return undefined; + } +}; + +/** Import and re-export specifiers, using the same Babel nodes as the module-boundary guard. */ +export const relativeSpecifiers = (source: string): readonly string[] => { + const specifiers: string[] = []; + const tree = parse(source, { sourceType: "module", plugins: ["typescript"] }); + traverseFast(tree, (node) => { + const specifier = importSpecifier(node); + if (specifier?.startsWith(".") === true) specifiers.push(specifier); + }); + return specifiers; +}; + +/** + * Cycles that already existed outside the analysis-view hub. Membership is + * exact so a new edge cannot hide inside the allow-list. + */ +const allowedCycles = [ + [ + "StateRecordChronology.ts", + "environmentStateListQuery.ts", + "environmentStateRules.ts", + "environmentStateWriteRules.ts", + ], + ["environmentStateGate.ts", "environmentStateListFacts.ts"], + ["environmentStateWriteAddress.ts", "environmentStateWriteEffects.ts"], +]; + +const productionFiles = (directory: string): string[] => { + const files: string[] = []; + for (const name of readdirSync(directory)) { + const path = join(directory, name); + if (statSync(path).isDirectory()) files.push(...productionFiles(path)); + else if (name.endsWith(".ts") && !name.includes(".test.")) files.push(path); + } + return files; +}; + +const importGraph = (): Map> => { + const files = new Set( + productionFiles(root).map((path) => relative(root, path)), + ); + const graph = new Map>(); + for (const file of files) { + const source = readFileSync(join(root, file), "utf8"); + const edges = new Set(); + for (const spec of relativeSpecifiers(source)) { + const resolved = resolve(dirname(join(root, file)), spec).replace( + /\.js$/, + ".ts", + ); + const target = relative(root, resolved); + if (files.has(target)) edges.add(target); + } + graph.set(file, edges); + } + return graph; +}; + +const stronglyConnected = ( + graph: Map>, +): readonly (readonly string[])[] => { + let index = 0; + const stack: string[] = []; + const onStack = new Set(); + const indices = new Map(); + const low = new Map(); + const components: string[][] = []; + const visit = (node: string): void => { + indices.set(node, index); + low.set(node, index); + index += 1; + stack.push(node); + onStack.add(node); + for (const next of graph.get(node) ?? []) { + if (!indices.has(next)) { + visit(next); + low.set(node, Math.min(low.get(node) ?? index, low.get(next) ?? index)); + } else if (onStack.has(next)) { + low.set( + node, + Math.min(low.get(node) ?? index, indices.get(next) ?? index), + ); + } + } + if (low.get(node) === indices.get(node)) { + const component: string[] = []; + let member = ""; + while (member !== node) { + member = stack.pop() ?? node; + onStack.delete(member); + component.push(member); + } + if (component.length > 1) components.push(component.sort()); + } + }; + for (const node of [...graph.keys()].sort()) { + if (!indices.has(node)) visit(node); + } + return components.sort( + (left, right) => + right.length - left.length || left.join().localeCompare(right.join()), + ); +}; + +describe("analysis view import cycles", () => { + it("reads side-effect imports and ignores import-like text", () => { + expect( + relativeSpecifiers(` + // from "./commented.js" + /* import "./block-comment.js"; */ + const text = "from './string.js'"; + import "./side-effect.js"; + import { value } from "./named.js"; + export { value as again } from "./reexported.js"; + const loaded = import("./dynamic.js"); + `), + ).toEqual([ + "./side-effect.js", + "./named.js", + "./reexported.js", + "./dynamic.js", + ]); + }); + + it("keeps projectors from importing the request and result hub", () => { + const cycles = stronglyConnected(importGraph()).map((cycle) => + cycle.join("\n"), + ); + expect(cycles).toEqual( + allowedCycles.map((cycle) => [...cycle].sort().join("\n")), + ); + }); +}); diff --git a/src/domain/analysisView/analysisViewParent.ts b/src/domain/analysisView/analysisViewParent.ts index 9e2d9e2311..4f1698ccd1 100644 --- a/src/domain/analysisView/analysisViewParent.ts +++ b/src/domain/analysisView/analysisViewParent.ts @@ -1,10 +1,29 @@ import type { z } from "zod"; import type { AnalysisInputError } from "../analysisErrorCore.js"; import type { AnalysisError } from "../analysisErrorBase.js"; +import type { Evidence } from "../evidence.js"; import { analysisInputErrorFromIssues } from "../inputIssueProjection.js"; import { err, ok, type Result } from "../result.js"; -import type { AnalysisViewParent } from "./analysisView.js"; import { ownedJsonValueSchema } from "../jsonValue.js"; + +/** Parent record already resolved from inline Evidence or a session reference. */ +export interface AnalysisViewParent { + readonly evidenceId: string; + readonly operation: string; + readonly normalizedResult: unknown; + readonly provider?: Evidence["provider"]; + readonly analysisProfile?: Evidence["analysis_profile"]; + readonly authority?: Evidence["authority"]; + readonly environment?: Evidence["environment"]; + /** The owner proved normalizedResult belongs to a sealed, deep-frozen Evidence snapshot. */ + readonly sealedResult?: boolean; + /** Subject presentation for this delivery, including explicit absence. */ + readonly subject?: Evidence["subject"]; + readonly limitations: readonly string[]; + readonly artifact?: { readonly path: string; readonly sha256: string } | null; + /** Parent Evidence parameters, when the parent operation records them. */ + readonly parameters?: unknown; +} import { canBorrowParsedJsonSnapshot, freezeOwnedJsonTreeSnapshot, diff --git a/src/domain/analysisView/analysisViewRequest.ts b/src/domain/analysisView/analysisViewRequest.ts new file mode 100644 index 0000000000..697b0ac9c8 --- /dev/null +++ b/src/domain/analysisView/analysisViewRequest.ts @@ -0,0 +1,132 @@ +import { + nativeObservationViewRequestSchema, + nativeContextViewRequestSchema, +} from "./nativeObservationSchemas.js"; +import { devicetreeViewRequestSchema } from "./devicetreeView.js"; +import { apkSignatureViewRequestSchema } from "../apkSignature/apkSignatureQuery.js"; +import { erlangBeamViewRequestSchema } from "./erlangBeamView.js"; +import { pythonPycViewRequestSchema } from "./pythonPycView.js"; +import { nativeExportsViewRequestSchema } from "./nativeExportsView.js"; +import { javaScriptRoutesViewRequestSchema } from "./javascriptRoutesView.js"; +import { webBundleViewRequestSchema } from "./webBundleView.js"; +import { sourceToBundleViewRequestSchema } from "./sourceToBundleView.js"; +import { gpuCodeObjectsViewRequestSchema } from "./gpuCodeObjectsView.js"; +import { modelArtifactViewRequestSchema } from "../model/modelArtifactQuery.js"; +import { rustBinaryViewRequestSchema } from "../rust/rustBinaryQuery.js"; +import { goBinaryViewRequestSchema } from "./goBinaryView.js"; +import { nativeFunctionMatchingViewRequestSchema } from "./nativeFunctionMatchingView.js"; +import { protobufViewRequestSchema } from "./protobufCaptureView.js"; +import { nativeInventoryViewRequestSchema } from "./nativeInventoryView.js"; + +import { + evidenceFileReferenceSchema, + retainedEvidenceReferenceSchema, +} from "../evidenceReference.js"; +import { z } from "zod"; +import { browserScenarioViewRequestSchema } from "./browserScenarioViewSchemas.js"; +import { nativeLoadImageViewRequestSchema } from "./nativeLoadImageView.js"; +import { desktopViewRequestSchema } from "./desktopApplicationView.js"; +import { javascriptModuleReferencesRequestSchema } from "./javascriptModuleReferences.js"; +import { javascriptFactsViewRequestSchema } from "./javascriptFactsView.js"; +import { evidenceSchema } from "../evidence.js"; +import { apiSurfaceViewSchema } from "./webNetworkApiSurfaceView.js"; +import { evmViewRequestSchema } from "./evmInterfaceView.js"; +import { artifactInventoryViewRequestSchema } from "./artifactInventoryView.js"; +import { managedViewRequestSchema } from "./managedArtifactView.js"; +import { managedMembersViewRequestSchema } from "./managedMemberViewSchemas.js"; +import { wasmViewRequestSchema } from "./wasmArtifactView.js"; +import { machoViewRequestSchema } from "./machoView.js"; +import { interfaceBuilderViewRequestSchema } from "./interfaceBuilderView.js"; +import { captureViewRequestSchema } from "./webNetworkCaptureView.js"; +import { environmentManifestViewRequestSchema } from "./environmentManifestView.js"; +import { environmentStateViewRequestSchema } from "./environmentStateView.js"; +import { environmentCoverageViewRequestSchema } from "./environmentCoverageView.js"; +import { pcapViewRequestSchema } from "./pcapCaptureView.js"; +import { qlogViewRequestSchema } from "./qlogCaptureView.js"; +import { androidViewRequestSchema } from "./androidPackageView.js"; +import { androidJniViewRequestSchema } from "../android/androidJniQuery.js"; +import { dartAotViewRequestSchema } from "./dartAotView.js"; +import { il2cppMetadataViewRequestSchema } from "./il2cppMetadataView.js"; +import { + facetViewSchema, + itemViewSchema, + nativeViewSchema, + pageViewSchema, + summaryViewSchema, +} from "./analysisViewShape.js"; +/** Caller-selected projection of already completed analysis Evidence. */ +export const analysisViewRequestSchema = z.discriminatedUnion("kind", [ + nativeObservationViewRequestSchema, + nativeContextViewRequestSchema, + devicetreeViewRequestSchema, + erlangBeamViewRequestSchema, + pythonPycViewRequestSchema, + nativeExportsViewRequestSchema, + javaScriptRoutesViewRequestSchema, + webBundleViewRequestSchema, + nativeFunctionMatchingViewRequestSchema, + sourceToBundleViewRequestSchema, + summaryViewSchema, + goBinaryViewRequestSchema, + rustBinaryViewRequestSchema, + desktopViewRequestSchema, + facetViewSchema, + itemViewSchema, + pageViewSchema, + javascriptModuleReferencesRequestSchema, + javascriptFactsViewRequestSchema, + nativeViewSchema, + nativeInventoryViewRequestSchema, + nativeLoadImageViewRequestSchema, + artifactInventoryViewRequestSchema, + wasmViewRequestSchema, + machoViewRequestSchema, + interfaceBuilderViewRequestSchema, + evmViewRequestSchema, + managedViewRequestSchema, + managedMembersViewRequestSchema, + androidViewRequestSchema, + androidJniViewRequestSchema, + apiSurfaceViewSchema, + environmentManifestViewRequestSchema, + environmentStateViewRequestSchema, + environmentCoverageViewRequestSchema, + captureViewRequestSchema, + browserScenarioViewRequestSchema, + protobufViewRequestSchema, + qlogViewRequestSchema, + pcapViewRequestSchema, + dartAotViewRequestSchema, + il2cppMetadataViewRequestSchema, + apkSignatureViewRequestSchema, + modelArtifactViewRequestSchema, + gpuCodeObjectsViewRequestSchema, +]); + +// The application owns admission and authenticated Evidence parsing. SDK and +// CLI envelope parsing must borrow this unknown value rather than clone it +// before admission. Advertise the owning Evidence contract in both dialects. +const inlineEvidenceInputSchema = z.unknown().nonoptional(); +inlineEvidenceInputSchema._zod.processJSONSchema = + evidenceSchema._zod.processJSONSchema; + +/** Unauthenticated inline input, an exact same-session retained reference, or one local Evidence file. */ +export const analysisViewSourceSchema = z.discriminatedUnion("kind", [ + retainedEvidenceReferenceSchema, + z.strictObject({ + kind: z.literal("inline"), + evidence: inlineEvidenceInputSchema, + }), + evidenceFileReferenceSchema, +]); + +/** Public inspect_analysis_view input. */ +export const inspectAnalysisViewInputSchema = z.strictObject({ + source: analysisViewSourceSchema, + view: analysisViewRequestSchema, +}); + +export type AnalysisViewRequest = z.output; +export type InspectAnalysisViewInput = z.output< + typeof inspectAnalysisViewInputSchema +>; diff --git a/src/domain/analysisView/analysisViewResult.ts b/src/domain/analysisView/analysisViewResult.ts new file mode 100644 index 0000000000..f7ee6a1aa1 --- /dev/null +++ b/src/domain/analysisView/analysisViewResult.ts @@ -0,0 +1,1277 @@ +import { analysisViewCoverageSchema } from "./analysisViewCoverage.js"; +import { + javaScriptRouteInventorySourceSchema, + javaScriptRouteInventorySchema, +} from "../javascript/javascriptRouteInventory.js"; +import { nativeFunctionMatchingContextSchema } from "../native/functionMatching.js"; +import { + nativeObservationViewRequestSchema, + nativeContextViewRequestSchema, + nativeObservationItemsSchemas, + nativeContextItemsSchemas, + nativeSourceContextReferenceSchema, + nativeObservationOperationSchema, +} from "./nativeObservationSchemas.js"; +import { + NATIVE_OBSERVATION_OPERATIONS, + type NativeObservationOperation, +} from "../native/nativeObservation.js"; +import { + devicetreeViewRequestSchema, + devicetreeViewItemsSchema, + devicetreeSummarySchema, + devicetreePageContextSchema, +} from "./devicetreeView.js"; +import { + apkSignatureViewRequestSchema, + apkSignatureViewItemsSchema, +} from "../apkSignature/apkSignatureQuery.js"; +import { + apkSignatureSummarySchema, + apkSignatureSourceCoverageSchema, +} from "./apkSignatureView.js"; +import { + erlangBeamViewRequestSchema, + erlangBeamViewPageSchema, + erlangBeamSummarySchema, +} from "./erlangBeamView.js"; +import { + pythonPycViewRequestSchema, + pythonPycViewItemsSchema, + pythonPycSummarySchema, +} from "./pythonPycView.js"; +import { + nativeExportsViewRequestSchema, + nativeExportsViewItemsSchema, + nativeExportsSummarySchema, +} from "./nativeExportsView.js"; +import { byteEntropySummarySchema } from "./byteEntropyView.js"; +import { + javaScriptRoutesViewRequestSchema, + javaScriptRoutesViewItemsSchema, + javaScriptRoutesViewSummarySchema, +} from "./javascriptRoutesView.js"; +import { + webBundleViewRequestSchema, + webBundleViewItemsSchema, + webBundleSummarySchema, +} from "./webBundleView.js"; +import { webBundleAnalysisSchema } from "../webBundleAnalysis.js"; +import { recordedBrowserOriginSchema } from "../browserObservation.js"; +import { + sourceToBundleViewRequestSchema, + sourceToBundleViewItemsSchema, + sourceToBundleViewContextSchema, +} from "./sourceToBundleView.js"; +import { + gpuCodeObjectsViewRequestSchema, + gpuCodeObjectsSummarySchema, + gpuCodeObjectsItemsSchema, + gpuCodeObjectsPtxPageSchema, +} from "./gpuCodeObjectsView.js"; +import { gpuCodeObjectsObjectSchema } from "../gpu/gpuCodeObjects.js"; +import { modelArtifactViewRequestSchema } from "../model/modelArtifactQuery.js"; +import { + modelArtifactSummarySchema, + modelArtifactViewItemsSchema, + modelArtifactViewContextSchema, +} from "./modelArtifactView.js"; +import { + commandSummaryContext, + gdbCommandSummarySchema, +} from "./commandObservationView.js"; +import { + fridaSessionStatusSummarySchema, + fridaSessionStatusViewContext, +} from "./fridaSessionStatusView.js"; +import { commandObservationSchema } from "../commandObservation.js"; +import { + rustBinaryViewPageSchema, + rustBinaryViewRequestSchema, +} from "../rust/rustBinaryQuery.js"; +import { + goBinarySummarySchema, + goBinaryViewContextSchema, + goBinaryViewPageSchema, + goBinaryViewRequestSchema, +} from "./goBinaryView.js"; +import { + rustBinarySummarySchema, + rustBinaryViewContextSchema, +} from "./rustBinaryView.js"; +import { + nativeFunctionMatchingViewRequestSchema, + nativeFunctionMatchingViewItemsSchema, +} from "./nativeFunctionMatchingView.js"; +import { + protobufViewRequestSchema, + protobufViewItemsSchema, + protobufViewContextSchema, +} from "./protobufCaptureView.js"; +import { + nativeInventoryViewRequestSchema, + nativeInventoryViewRowSchema, + nativeInventorySummarySchema, +} from "./nativeInventoryView.js"; +import { nativeViewSourceContext } from "./nativeViewContext.js"; +import { + NATIVE_INVENTORY_OPERATIONS, + nativeInventoryOperationSchema, +} from "../native/nativeInventory.js"; +import { z } from "zod"; +import { + browserScenarioSummarySchema, + browserScenarioViewContextSchema, + browserScenarioViewItemsSchema, + browserScenarioViewRequestSchema, +} from "./browserScenarioViewSchemas.js"; +import { + nativeLoadImageViewRequestSchema, + nativeLoadImageViewItemsSchema, + nativeLoadImageSummarySchema, +} from "./nativeLoadImageView.js"; +import { + desktopViewRequestSchema, + desktopViewItemsSchema, + desktopSummarySchema, +} from "./desktopApplicationView.js"; +import { desktopCoverageSchema } from "../desktopApplication.js"; +import { + javascriptModuleReferencesRequestSchema, + javascriptModuleReferenceSchema, +} from "./javascriptModuleReferences.js"; +import { javascriptApplicationSourceCoverageSchema } from "./javascriptApplicationCoverage.js"; +import { + javascriptFactsViewRequestSchema, + javascriptFactRowSchema, +} from "./javascriptFactsView.js"; +import { javaScriptSourceSelectionSchema } from "../javascript/javascriptSourceSelection.js"; +import { digestSchema, prefixedDigestSchema } from "../digests.js"; +import { jsonObjectSchema, jsonValueSchema } from "../jsonValue.js"; +import { binaryLayoutSchema } from "../native/binaryLayout.js"; +import { bundleResourceRootSchema } from "../apple/bundleResourceRoot.js"; +import { functionFacetAvailabilitySchema } from "../native/functionDossier.js"; +import { + artifactGraphManifestSchema, + artifactInventoryCoverageSchema, +} from "../artifactGraph.js"; +import { + apiSurfaceFields, + apiSurfaceViewSchema, +} from "./webNetworkApiSurfaceView.js"; +import { + evmViewRequestSchema, + evmViewItemSchema, + evmSummarySchema, +} from "./evmInterfaceView.js"; +import { + artifactInventoryViewRequestSchema, + artifactInventoryItemsSchema, + artifactInventorySummarySchema, +} from "./artifactInventoryView.js"; +import { + managedViewRequestSchema, + managedViewItemSchema, + managedSummarySchema, + managedViewContextSchema, +} from "./managedArtifactView.js"; +import { + managedMembersViewRequestSchema, + managedMembersViewPageSchema, + managedMemberSummarySchema, + managedMembersViewContextSchema, +} from "./managedMemberViewSchemas.js"; +import { + wasmViewRequestSchema, + wasmViewItemSchema, + wasmSummarySchema, +} from "./wasmArtifactView.js"; +import { + machoSummarySchema, + machoViewContextSchema, + machoViewRows, + machoViewRequestSchema, +} from "./machoView.js"; +import { + interfaceBuilderSummarySchema, + interfaceBuilderViewContextSchema, + interfaceBuilderViewItemsSchema, + interfaceBuilderViewRequestSchema, +} from "./interfaceBuilderView.js"; +import { + captureViewRequestSchema, + captureViewItemsSchema, + captureSummarySchema, +} from "./webNetworkCaptureView.js"; +import { + environmentManifestFields, + environmentManifestViewRequestSchema, +} from "./environmentManifestView.js"; +import { + environmentStateFields, + environmentStateViewRequestSchema, +} from "./environmentStateView.js"; +import { + environmentCoverageFields, + environmentCoverageViewRequestSchema, +} from "./environmentCoverageView.js"; +import { + pcapViewRequestSchema, + pcapViewPageSchema, + pcapSummarySchema, +} from "./pcapCaptureView.js"; +import { + qlogViewRequestSchema, + qlogViewPageSchema, + qlogViewContextSchema, +} from "./qlogCaptureView.js"; +import { + androidPackageSummarySchema, + androidManifestViewItemSchema, + androidManifestViewRequestSchema, + androidComponentsViewRequestSchema, + androidComponentSummaryViewRequestSchema, + androidComponentViewRowSchema, + androidComponentViewContextSchema, + androidComponentSummarySchema, +} from "./androidPackageView.js"; +import { + androidClassSummarySchema, + androidMethodSummarySchema, +} from "./androidSymbolView.js"; +import { androidJniSummarySchema } from "./androidJniView.js"; +import { + androidJniViewRequestSchema, + androidJniViewItemsSchema, +} from "../android/androidJniQuery.js"; +import { + dartAotSummarySchema, + dartAotViewRequestSchema, + dartAotViewContextSchema, +} from "./dartAotView.js"; +import { + il2cppMetadataSummarySchema, + il2cppMetadataViewRequestSchema, + il2cppMetadataViewContextSchema, + il2cppMetadataViewItemsSchema, +} from "./il2cppMetadataView.js"; +import { + facetViewSchema, + itemViewSchema, + nativeViewSchema, + pageViewSchema, + summaryViewSchema, +} from "./analysisViewShape.js"; +const artifactSchema = z.strictObject({ + path: z + .string() + .describe( + "Selected artifact path, or the canonical resource root when resource-only Evidence has no executable subject.", + ), + sha256: digestSchema.nullable(), +}); + +const layoutSummarySchema = z.strictObject({ + bytes: binaryLayoutSchema.shape.artifact.shape.bytes, + format: binaryLayoutSchema.shape.format, + architecture: binaryLayoutSchema.shape.architecture, + image_type: binaryLayoutSchema.shape.image_type, + entry: z.strictObject({ + reported_value: z.string().min(1), + meaning: z.enum(["linked-virtual-address", "not-applicable", "absent"]), + execution_status: z.literal("unknown"), + }), + counts: z.strictObject({ + sections: z.int().nonnegative(), + segments: z.int().nonnegative(), + symbols: z.int().nonnegative(), + relocations: z.int().nonnegative(), + }), + limitation_count: z.int().nonnegative(), +}); + +const javascriptSummarySchema = z.strictObject({ + input_path: z.string().min(1), + format: z.enum(["asar", "directory"]), + root_artifact_sha256: digestSchema, + source_selection: javaScriptSourceSelectionSchema.exactOptional(), + statistics: jsonObjectSchema, + electron: jsonObjectSchema, + coverage: jsonObjectSchema, + limitation_count: z.int().nonnegative(), +}); + +const viewResultBase = { + parent_evidence_id: prefixedDigestSchema("ev"), + parent_operation: z.enum([ + "inspect_python_pyc", + "inspect_erlang_beam", + "inspect_devicetree", + "inspect_byte_entropy", + "inspect_native_exports", + "inspect_binary_layout", + "inspect_go_binary", + "gdb_console", + "frida_session_status", + "inspect_with_objdump", + "inspect_desktop_application", + "analyze_javascript_application", + "analyze_web_bundle", + "analyze_function", + "inspect_artifact", + "inventory_artifact", + "inspect_wasm_artifact", + "inspect_macho", + "decode_interface_builder", + "inspect_evm_interface", + "inspect_managed_artifact", + "inspect_managed_members", + "inspect_web_network_capture", + "inspect_android_package", + "inspect_android_class", + "inspect_android_method", + "inspect_android_jni_bindings", + "inspect_pcap_capture", + "inspect_dart_aot", + "inspect_il2cpp_metadata", + "inspect_model_artifact", + "inspect_gpu_code_objects", + ...NATIVE_INVENTORY_OPERATIONS, + ...NATIVE_OBSERVATION_OPERATIONS, + "match_native_functions", + ]), + parent_digest: digestSchema, + view_digest: digestSchema, + artifact: artifactSchema, + coverage: analysisViewCoverageSchema, + limitations: z.array(z.string()), + unknowns: z.array(z.string()), +} as const; + +const summaryViewResultBase = { + kind: z.literal("summary"), + view: summaryViewSchema, + ...viewResultBase, +} as const; + +const nativeObservationSummaryFor = < + Operation extends NativeObservationOperation, +>( + operation: Operation, +) => + z.strictObject({ + ...summaryViewResultBase, + ...nativeViewSourceContext, + artifact: artifactSchema.nullable(), + parent_operation: z.literal(operation), + source_context: nativeSourceContextReferenceSchema, + summary: z.strictObject({ observations: z.int().nonnegative() }), + items: nativeObservationItemsSchemas[operation], + }); +export const nativeObservationSummaryViewResultSchemas = { + procedure_address: nativeObservationSummaryFor("procedure_address"), + procedure_callees: nativeObservationSummaryFor("procedure_callees"), + procedure_callers: nativeObservationSummaryFor("procedure_callers"), + resolve_containing_procedure: nativeObservationSummaryFor( + "resolve_containing_procedure", + ), + get_call_graph: nativeObservationSummaryFor("get_call_graph"), +}; +const nativeObservationSummaryViewResultSchema = z.discriminatedUnion( + "parent_operation", + [ + nativeObservationSummaryViewResultSchemas.procedure_address, + nativeObservationSummaryViewResultSchemas.procedure_callees, + nativeObservationSummaryViewResultSchemas.procedure_callers, + nativeObservationSummaryViewResultSchemas.resolve_containing_procedure, + nativeObservationSummaryViewResultSchemas.get_call_graph, + ], +); +const nativeObservationPageFor = ( + operation: Operation, +) => + nativeObservationSummaryFor(operation) + .omit({ kind: true, view: true }) + .extend({ + kind: z.literal("native-observation"), + view: nativeObservationViewRequestSchema, + }); +const nativeObservationPageViewResultSchema = z.discriminatedUnion( + "parent_operation", + [ + nativeObservationPageFor("procedure_address"), + nativeObservationPageFor("procedure_callees"), + nativeObservationPageFor("procedure_callers"), + nativeObservationPageFor("resolve_containing_procedure"), + nativeObservationPageFor("get_call_graph"), + ], +); +const nativeContextFor = ( + facet: Facet, +) => + z.strictObject({ + ...viewResultBase, + ...nativeViewSourceContext, + kind: z.literal("native-context"), + artifact: artifactSchema.nullable(), + parent_operation: nativeObservationOperationSchema, + source_context: nativeSourceContextReferenceSchema, + facet: z.literal(facet), + view: nativeContextViewRequestSchema.extend({ facet: z.literal(facet) }), + items: nativeContextItemsSchemas[facet], + }); +const nativeContextViewResultSchema = z.discriminatedUnion("facet", [ + nativeContextFor("overview"), + nativeContextFor("analysis-profile"), + nativeContextFor("limitations"), + nativeContextFor("result-limitations"), +]); + +export const byteEntropySummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + summary: byteEntropySummarySchema, + parent_operation: z.literal("inspect_byte_entropy"), +}); + +export const nativeExportsSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_native_exports"), + summary: nativeExportsSummarySchema, +}); + +export const devicetreeSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_devicetree"), + summary: devicetreeSummarySchema, +}); +export const erlangBeamSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_erlang_beam"), + summary: erlangBeamSummarySchema, +}); +export const erlangBeamTableViewResultSchema = z.strictObject({ + ...viewResultBase, + kind: z.literal("beam"), + parent_operation: z.literal("inspect_erlang_beam"), + view: erlangBeamViewRequestSchema, + beam: erlangBeamSummarySchema, + page: erlangBeamViewPageSchema, +}); + +export const pythonPycSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_python_pyc"), + summary: pythonPycSummarySchema, +}); + +export const pythonPycCodeObjectsViewResultSchema = z.strictObject({ + ...viewResultBase, + kind: z.literal("python-pyc"), + parent_operation: z.literal("inspect_python_pyc"), + view: pythonPycViewRequestSchema, + pyc: pythonPycSummarySchema, + items: pythonPycViewItemsSchema, +}); + +/** Opt-in command delivery keeps output once and retains the complete parent. */ +export const gdbCommandSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + ...commandSummaryContext, + parent_operation: z.literal("gdb_console"), + artifact: artifactSchema.nullable(), + summary: gdbCommandSummarySchema, +}); + +export const objdumpSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + ...commandSummaryContext, + parent_operation: z.literal("inspect_with_objdump"), + artifact: artifactSchema.nullable(), + summary: commandObservationSchema, +}); + +export const fridaSessionStatusSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + ...fridaSessionStatusViewContext, + parent_operation: z.literal("frida_session_status"), + artifact: artifactSchema.nullable(), + summary: fridaSessionStatusSummarySchema, +}); + +/** Opt-in Go delivery retains original bytes and exposes build identity/counts. */ +export const goBinarySummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + ...goBinaryViewContextSchema.shape, + parent_operation: z.literal("inspect_go_binary"), + summary: goBinarySummarySchema, +}); + +/** Compact source identity and counts, retaining the complete embedded graph. */ +export const rustBinarySummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + ...rustBinaryViewContextSchema.shape, + parent_operation: z.literal("inspect_rust_binary"), + summary: rustBinarySummarySchema, +}); + +export const rustBinaryPageViewResultSchema = z.strictObject({ + ...viewResultBase, + ...rustBinaryViewContextSchema.shape, + kind: z.literal("rust"), + parent_operation: z.literal("inspect_rust_binary"), + view: rustBinaryViewRequestSchema, + rust: rustBinarySummarySchema, + page: rustBinaryViewPageSchema, +}); + +/** Summary `inspect_binary_layout` detail returns; no other view kind. */ +export const binaryLayoutSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + summary: layoutSummarySchema, + parent_operation: z.literal("inspect_binary_layout"), +}); + +/** Summary `analyze_javascript_application` detail returns; no other view kind. */ +export const javascriptApplicationSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + summary: javascriptSummarySchema, + parent_operation: z.literal("analyze_javascript_application"), +}); + +/** Typed reference page; full item observations remain available separately. */ +export const javascriptModuleReferencesViewResultSchema = z.strictObject({ + ...viewResultBase, + kind: z.literal("javascript"), + view: javascriptModuleReferencesRequestSchema, + parent_operation: z.literal("analyze_javascript_application"), + rows: z.array(javascriptModuleReferenceSchema), + source_coverage: javascriptApplicationSourceCoverageSchema, +}); + +/** Paged retained observations with exact selected properties and provenance. */ +const javascriptFactsViewResultSchema = z.strictObject({ + ...viewResultBase, + kind: z.literal("javascript-facts"), + view: javascriptFactsViewRequestSchema, + parent_operation: z.literal("analyze_javascript_application"), + rows: z.array(javascriptFactRowSchema), + source_coverage: javascriptApplicationSourceCoverageSchema, +}); + +/** Exact summary carrier for artifact inspection's optional delivery contract. */ +export const artifactInventorySummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.enum(["inspect_artifact", "inventory_artifact"]), + summary: artifactInventorySummarySchema, +}); + +export const desktopApplicationSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_desktop_application"), + summary: desktopSummarySchema, +}); + +/** Exact summary carrier for WASM inspection's optional delivery contract. */ +export const wasmArtifactSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_wasm_artifact"), + summary: wasmSummarySchema, +}); + +/** Exact slice identity and collection counts for Mach-O's selected delivery. */ +export const machoSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_macho"), + summary: machoSummarySchema, +}); + +/** Decoded documents and graph counts for Interface Builder's selected delivery. */ +export const interfaceBuilderSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("decode_interface_builder"), + resource_root: bundleResourceRootSchema.optional(), + summary: interfaceBuilderSummarySchema, +}); + +/** Exact inferred-interface summary for EVM's caller-selected delivery. */ +export const evmInterfaceSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_evm_interface"), + summary: evmSummarySchema, +}); + +/** Exact metadata overview for the managed artifact's selected delivery. */ +export const managedArtifactSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_managed_artifact"), + summary: managedSummarySchema, +}); + +/** Exact member selection, coverage and counts for the selected delivery. */ +export const managedMemberSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_managed_members"), + summary: managedMemberSummarySchema, +}); + +/** Exact historical capture summary, with no body or member-inventory payload. */ +export const webNetworkCaptureSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_web_network_capture"), + summary: captureSummarySchema, +}); + +/** Compact outcomes and the focus screen from a retained browser scenario. */ +export const browserScenarioSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + artifact: z.null(), + parent_operation: z.literal("capture_browser_scenario"), + summary: browserScenarioSummarySchema, +}); + +/** Exact package declarations with retained decoded manifest text. */ +export const androidPackageSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_android_package"), + summary: androidPackageSummarySchema, +}); +export const androidJniSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_android_jni_bindings"), + summary: androidJniSummarySchema, +}); +export const androidJniPageViewResultSchema = z.strictObject({ + ...viewResultBase, + kind: z.literal("android-jni"), + parent_operation: z.literal("inspect_android_jni_bindings"), + view: androidJniViewRequestSchema, + items: androidJniViewItemsSchema, + source: androidJniSummarySchema.pick({ + native_inventory: true, + library_inventory: true, + selection: true, + }), +}); + +/** Exact class facts with complete raw protocol Evidence retained separately. */ +export const androidClassSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_android_class"), + summary: androidClassSummarySchema, +}); + +/** Exact selected method body, source coverage and optional mapping facts. */ +export const androidMethodSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_android_method"), + summary: androidMethodSummarySchema, +}); + +/** Legacy manifest views keep their original shape; new facets are explicit. */ +export const androidManifestViewResultSchema = z.strictObject({ + ...viewResultBase, + kind: z.literal("android"), + facet: z.literal("manifest").optional(), + view: androidManifestViewRequestSchema, + item: androidManifestViewItemSchema, + parent_operation: z.literal("inspect_android_package"), +}); +export const androidComponentsViewResultSchema = z.strictObject({ + ...viewResultBase, + ...androidComponentViewContextSchema.shape, + kind: z.literal("android"), + facet: z.literal("components"), + view: androidComponentsViewRequestSchema, + items: z.array(androidComponentViewRowSchema), + byte_limited: z.boolean(), + parent_operation: z.literal("inspect_android_package"), +}); +export const androidComponentSummaryViewResultSchema = z.strictObject({ + ...viewResultBase, + ...androidComponentViewContextSchema.shape, + kind: z.literal("android"), + facet: z.literal("component-summary"), + view: androidComponentSummaryViewRequestSchema, + summary: androidComponentSummarySchema, + parent_operation: z.literal("inspect_android_package"), +}); +const androidPackageViewResultSchema = z.discriminatedUnion("facet", [ + androidManifestViewResultSchema, + androidComponentsViewResultSchema, + androidComponentSummaryViewResultSchema, +]); + +export const pcapCaptureSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_pcap_capture"), + summary: pcapSummarySchema, +}); + +/** Exact snapshot and pool-coverage carrier for selected AOT delivery. */ +export const dartAotSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_dart_aot"), + summary: dartAotSummarySchema, +}); + +export const javaScriptRoutesViewResultSchema = z.strictObject({ + ...viewResultBase, + artifact: artifactSchema.nullable(), + kind: z.literal("javascript-routes"), + parent_operation: z.enum([ + "analyze_javascript_application", + "analyze_web_bundle", + ]), + view: javaScriptRoutesViewRequestSchema, + inventory_id: javaScriptRouteInventorySchema.shape.inventory_id, + source_manifest_sha256: digestSchema, + source_coverage: javaScriptRouteInventorySchema.shape.coverage, + inventory_capacity: javaScriptRouteInventorySchema.shape.capacity, + capture_url: z.string().nullable(), + items: javaScriptRoutesViewItemsSchema, + sources: z.array(javaScriptRouteInventorySourceSchema), + summary: javaScriptRoutesViewSummarySchema.nullable(), + byte_limited: z.boolean(), +}); + +/** Compact web bundle findings retain endpoint observations and inference candidates. */ +export const webBundleSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + artifact: artifactSchema.nullable(), + parent_operation: z.literal("analyze_web_bundle"), + target_url: z.string(), + target_origin: recordedBrowserOriginSchema.nullable().optional(), + source_unknowns: webBundleAnalysisSchema.shape.unknowns, + summary: webBundleSummarySchema, +}); + +export const webBundlePageViewResultSchema = z.strictObject({ + ...viewResultBase, + artifact: artifactSchema.nullable(), + kind: z.literal("web-bundle"), + parent_operation: z.literal("analyze_web_bundle"), + target_url: z.string(), + target_origin: recordedBrowserOriginSchema.nullable().optional(), + source_unknowns: webBundleAnalysisSchema.shape.unknowns, + view: webBundleViewRequestSchema, + completeness: webBundleAnalysisSchema.shape.completeness, + items: webBundleViewItemsSchema, + summary: webBundleSummarySchema.nullable(), + byte_limited: z.boolean(), +}); + +export const gpuCodeObjectsSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_gpu_code_objects"), + summary: gpuCodeObjectsSummarySchema, +}); +export const gpuCodeObjectsPageViewResultSchema = z.strictObject({ + kind: z.literal("gpu-code-objects"), + view: gpuCodeObjectsViewRequestSchema, + items: gpuCodeObjectsItemsSchema, + ptx: gpuCodeObjectsPtxPageSchema.nullable(), + source_coverage: gpuCodeObjectsObjectSchema.shape.coverage, + ...viewResultBase, + parent_operation: z.literal("inspect_gpu_code_objects"), +}); + +export const apkSignatureSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_apk_signature"), + summary: apkSignatureSummarySchema, +}); +export const apkSignaturePageViewResultSchema = z.strictObject({ + ...viewResultBase, + kind: z.literal("apk-signature"), + parent_operation: z.literal("inspect_apk_signature"), + view: apkSignatureViewRequestSchema, + items: apkSignatureViewItemsSchema, + source_coverage: apkSignatureSourceCoverageSchema, +}); + +export const modelArtifactSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_model_artifact"), + summary: modelArtifactSummarySchema, +}); + +export const modelArtifactPageViewResultSchema = z.strictObject({ + kind: z.literal("model-artifact"), + view: modelArtifactViewRequestSchema, + items: modelArtifactViewItemsSchema, + ...viewResultBase, + ...modelArtifactViewContextSchema.shape, + parent_operation: z.literal("inspect_model_artifact"), +}); + +/** Metadata identity and row counts for selected IL2CPP delivery. */ +export const il2cppMetadataSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_il2cpp_metadata"), + summary: il2cppMetadataSummarySchema, +}); + +/** Exact inventory summary with the original observation's provider and query. */ +export const nativeInventorySummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + ...nativeViewSourceContext, + parent_operation: nativeInventoryOperationSchema, + artifact: artifactSchema.nullable(), + summary: nativeInventorySummarySchema, +}); + +/** Compact provider load observations retain the independent verification state. */ +export const nativeLoadImageSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + ...nativeViewSourceContext, + artifact: artifactSchema.nullable(), + parent_operation: z.literal("inspect_native_load_image"), + summary: nativeLoadImageSummarySchema, +}); + +/** Compact native matching discovery retains the complete matching report. */ +export const nativeFunctionMatchingSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + artifact: z.null(), + parent_operation: z.literal("match_native_functions"), + summary: nativeFunctionMatchingContextSchema, +}); + +/** Rows observed for one facet, or null when the provider declared that facet unavailable. */ +const declaredFacetCountSchema = z + .number() + .int() + .nonnegative() + .nullable() + .describe( + "Observed rows; null when facet_availability declares the facet unavailable, so no rows is not evidence of none.", + ); + +/** Rows of an optional dossier record, or null when the dossier omitted it. */ +const recordedFacetCountSchema = z + .number() + .int() + .nonnegative() + .nullable() + .describe( + "Observed rows; null when the dossier did not record the facet (the native facet view reports it not recorded), so no rows is not evidence of none.", + ); + +/** Rows of one value-flow facet, or null when value flow is unavailable. */ +const valueFlowFacetCountSchema = z + .number() + .int() + .nonnegative() + .nullable() + .describe( + "Observed rows; null when value_flow.available is false because native_value_flow was not recorded or the provider declared it unavailable (unknowns names which), so no rows is not evidence of none.", + ); + +/** Compact analyze_function dossier; the complete dossier stays retained for facet paging. */ +export const nativeFunctionSummarySchema = z.strictObject({ + procedure: z.strictObject({ + name: z.string(), + address: z.string(), + }), + pseudocode: z.strictObject({ + available: z + .boolean() + .describe( + "Provider facet_availability for pseudocode when declared; otherwise whether decompiled text is present. The flag is authoritative over raw length.", + ), + code_units: z + .number() + .int() + .nonnegative() + .describe( + "Pseudocode length in UTF-16 code units, the unit inspect_analysis_view pages pseudocode by.", + ), + }), + value_flow: z.strictObject({ + available: z.boolean(), + truncated: z + .boolean() + .describe( + "True only when value-flow is available and the provider truncated it; false when value-flow is unavailable (see available).", + ), + }), + facet_availability: functionFacetAvailabilitySchema + .nullable() + .describe( + "The provider's declared availability per facet, or null when it declared none. Unavailable facets name their reason here and in unknowns.", + ), + counts: z.strictObject({ + assembly: declaredFacetCountSchema, + basic_blocks: declaredFacetCountSchema, + comments: declaredFacetCountSchema, + callers: declaredFacetCountSchema, + callees: declaredFacetCountSchema, + incoming_references: declaredFacetCountSchema, + outgoing_references: declaredFacetCountSchema, + unresolved_calls: recordedFacetCountSchema, + referenced_strings: declaredFacetCountSchema, + referenced_names: declaredFacetCountSchema, + swift_string_literals: recordedFacetCountSchema, + swift_string_literal_omissions: recordedFacetCountSchema, + value_flow_operations: valueFlowFacetCountSchema, + value_flow_def_use: valueFlowFacetCountSchema, + value_flow_effects: valueFlowFacetCountSchema, + value_flow_parameters: valueFlowFacetCountSchema, + value_flow_parameter_uses: valueFlowFacetCountSchema, + }), + limitation_count: z.number().int().nonnegative(), +}); + +/** Compact analyze_function summary that retains the complete native dossier Evidence. */ +export const nativeFunctionSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("analyze_function"), + procedure_address: z.string().nullable(), + summary: nativeFunctionSummarySchema, +}); + +export const sourceToBundleSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + artifact: z.null(), + parent_operation: z.literal("compare_source_to_bundle"), + summary: sourceToBundleViewContextSchema, +}); +export const sourceToBundlePageViewResultSchema = z.strictObject({ + ...viewResultBase, + ...sourceToBundleViewContextSchema.shape, + kind: z.literal("source-to-bundle"), + artifact: z.null(), + parent_operation: z.literal("compare_source_to_bundle"), + view: sourceToBundleViewRequestSchema, + items: sourceToBundleViewItemsSchema, +}); + +/** Bind the existing nested facet selection to its producer-owned rows. */ +const machoPage = (facet: Facet) => + z.strictObject({ + ...viewResultBase, + ...machoViewContextSchema.shape, + kind: z.literal("macho"), + parent_operation: z.literal("inspect_macho"), + view: machoViewRequestSchema.extend({ facet: z.literal(facet) }), + item: machoViewRows[facet], + }); + +// The input tag preserves kind dispatch; the output projection advertises the +// correlated pages without adding a discriminator to their public wire shape. +const machoPageViewResultSchema = z + .object({ kind: z.literal("macho") }) + .passthrough() + .pipe( + z.union([ + machoPage("entrypoints"), + machoPage("architectures"), + machoPage("build_metadata"), + machoPage("load_commands"), + machoPage("dependencies"), + machoPage("imports"), + machoPage("exports"), + machoPage("segments"), + machoPage("encryption"), + machoPage("provenance"), + ]), + ); + +/** Projected facts for one selected view of retained analysis Evidence. */ +export const analysisViewResultSchema = z.discriminatedUnion("kind", [ + nativeObservationPageViewResultSchema, + nativeContextViewResultSchema, + javaScriptRoutesViewResultSchema, + webBundlePageViewResultSchema, + sourceToBundlePageViewResultSchema, + z.strictObject({ + ...viewResultBase, + ...nativeFunctionMatchingContextSchema.shape, + kind: z.literal("function-matches"), + artifact: z.null(), + view: nativeFunctionMatchingViewRequestSchema, + items: nativeFunctionMatchingViewItemsSchema, + parent_operation: z.literal("match_native_functions"), + }), + z.strictObject({ + ...viewResultBase, + ...apiSurfaceFields, + kind: z.literal("api-surface"), + parent_operation: z.literal("inspect_web_network_capture"), + view: apiSurfaceViewSchema, + artifact: z.strictObject({ + path: z.string(), + sha256: digestSchema.nullable(), + }), + }), + z.strictObject({ + ...viewResultBase, + ...environmentManifestFields, + kind: z.literal("environment-manifest"), + parent_operation: z.enum([ + "inspect_web_network_capture", + "capture_browser_scenario", + ]), + view: environmentManifestViewRequestSchema, + }), + z.strictObject({ + ...viewResultBase, + ...environmentStateFields, + kind: z.literal("environment-state"), + parent_operation: z.enum([ + "inspect_web_network_capture", + "capture_browser_scenario", + ]), + view: environmentStateViewRequestSchema, + }), + z.strictObject({ + ...viewResultBase, + ...environmentCoverageFields, + kind: z.literal("environment-coverage"), + parent_operation: z.enum([ + "inspect_web_network_capture", + "capture_browser_scenario", + ]), + view: environmentCoverageViewRequestSchema, + }), + z.discriminatedUnion("parent_operation", [ + nativeObservationSummaryViewResultSchema, + erlangBeamSummaryViewResultSchema, + devicetreeSummaryViewResultSchema, + pythonPycSummaryViewResultSchema, + nativeExportsSummaryViewResultSchema, + byteEntropySummaryViewResultSchema, + gdbCommandSummaryViewResultSchema, + objdumpSummaryViewResultSchema, + fridaSessionStatusSummaryViewResultSchema, + goBinarySummaryViewResultSchema, + rustBinarySummaryViewResultSchema, + binaryLayoutSummaryViewResultSchema, + desktopApplicationSummaryViewResultSchema, + javascriptApplicationSummaryViewResultSchema, + artifactInventorySummaryViewResultSchema, + wasmArtifactSummaryViewResultSchema, + machoSummaryViewResultSchema, + interfaceBuilderSummaryViewResultSchema, + evmInterfaceSummaryViewResultSchema, + managedArtifactSummaryViewResultSchema, + managedMemberSummaryViewResultSchema, + webNetworkCaptureSummaryViewResultSchema, + browserScenarioSummaryViewResultSchema, + androidPackageSummaryViewResultSchema, + androidJniSummaryViewResultSchema, + androidClassSummaryViewResultSchema, + androidMethodSummaryViewResultSchema, + pcapCaptureSummaryViewResultSchema, + dartAotSummaryViewResultSchema, + il2cppMetadataSummaryViewResultSchema, + apkSignatureSummaryViewResultSchema, + modelArtifactSummaryViewResultSchema, + gpuCodeObjectsSummaryViewResultSchema, + nativeInventorySummaryViewResultSchema, + nativeLoadImageSummaryViewResultSchema, + nativeFunctionMatchingSummaryViewResultSchema, + nativeFunctionSummaryViewResultSchema, + sourceToBundleSummaryViewResultSchema, + webBundleSummaryViewResultSchema, + ]), + z.strictObject({ + ...viewResultBase, + kind: z.literal("devicetree"), + parent_operation: z.literal("inspect_devicetree"), + view: devicetreeViewRequestSchema, + devicetree: devicetreePageContextSchema, + items: devicetreeViewItemsSchema, + }), + erlangBeamTableViewResultSchema, + pythonPycCodeObjectsViewResultSchema, + z.strictObject({ + ...viewResultBase, + kind: z.literal("native-exports"), + parent_operation: z.literal("inspect_native_exports"), + view: nativeExportsViewRequestSchema, + exports: nativeExportsSummarySchema, + items: nativeExportsViewItemsSchema, + }), + z.strictObject({ + ...viewResultBase, + ...nativeViewSourceContext, + kind: z.literal("native-inventory"), + parent_operation: nativeInventoryOperationSchema, + artifact: artifactSchema.nullable(), + view: nativeInventoryViewRequestSchema, + rows: z.array(nativeInventoryViewRowSchema), + }), + z.strictObject({ + ...viewResultBase, + kind: z.literal("native-load-image"), + ...nativeViewSourceContext, + verification_status: z.enum(["unsupported", "verified", "mismatch"]), + parent_operation: z.literal("inspect_native_load_image"), + artifact: artifactSchema.nullable(), + view: nativeLoadImageViewRequestSchema, + items: nativeLoadImageViewItemsSchema, + }), + z.strictObject({ + kind: z.literal("protobuf"), + view: protobufViewRequestSchema, + items: protobufViewItemsSchema, + ...viewResultBase, + ...protobufViewContextSchema.shape, + parent_operation: z.literal("inspect_web_network_capture"), + }), + z.strictObject({ + kind: z.literal("capture"), + view: captureViewRequestSchema, + items: captureViewItemsSchema, + ...viewResultBase, + parent_operation: z.literal("inspect_web_network_capture"), + }), + z.strictObject({ + kind: z.literal("browser-scenario"), + view: browserScenarioViewRequestSchema, + items: browserScenarioViewItemsSchema, + ...viewResultBase, + ...browserScenarioViewContextSchema.shape, + artifact: z.null(), + parent_operation: z.literal("capture_browser_scenario"), + }), + z.strictObject({ + kind: z.literal("qlog"), + view: qlogViewRequestSchema, + page: qlogViewPageSchema, + context: qlogViewContextSchema, + ...viewResultBase, + parent_operation: z.literal("inspect_web_network_capture"), + }), + z.strictObject({ + kind: z.literal("pcap"), + view: pcapViewRequestSchema, + page: pcapViewPageSchema, + source_coverage: z.enum(["complete", "partial"]), + ...viewResultBase, + parent_operation: z.literal("inspect_pcap_capture"), + }), + z.strictObject({ + kind: z.literal("facet"), + view: facetViewSchema, + facet: jsonValueSchema, + ...viewResultBase, + }), + z.strictObject({ + ...viewResultBase, + ...goBinaryViewContextSchema.shape, + kind: z.literal("go"), + parent_operation: z.literal("inspect_go_binary"), + view: goBinaryViewRequestSchema, + page: goBinaryViewPageSchema, + }), + rustBinaryPageViewResultSchema, + z.strictObject({ + kind: z.literal("item"), + view: itemViewSchema, + item: jsonValueSchema, + ...viewResultBase, + }), + z.strictObject({ + kind: z.literal("page"), + view: pageViewSchema, + items: z.array(jsonValueSchema), + ...viewResultBase, + }), + javascriptModuleReferencesViewResultSchema, + javascriptFactsViewResultSchema, + z.strictObject({ + kind: z.literal("native"), + view: nativeViewSchema, + procedure_address: z.string().nullable(), + item: jsonValueSchema, + ...viewResultBase, + }), + z.strictObject({ + kind: z.literal("wasm"), + view: wasmViewRequestSchema, + item: wasmViewItemSchema, + ...viewResultBase, + }), + z.strictObject({ + kind: z.literal("desktop-application"), + view: desktopViewRequestSchema, + items: desktopViewItemsSchema, + ...viewResultBase, + source_coverage: desktopCoverageSchema, + parent_operation: z.literal("inspect_desktop_application"), + }), + machoPageViewResultSchema, + z.strictObject({ + kind: z.literal("interface-builder"), + view: interfaceBuilderViewRequestSchema, + items: interfaceBuilderViewItemsSchema, + ...viewResultBase, + resource_root: bundleResourceRootSchema.optional(), + ...interfaceBuilderViewContextSchema.shape, + parent_operation: z.literal("decode_interface_builder"), + }), + z.strictObject({ + kind: z.literal("evm"), + view: evmViewRequestSchema, + item: evmViewItemSchema, + ...viewResultBase, + parent_operation: z.literal("inspect_evm_interface"), + }), + z.strictObject({ + kind: z.literal("managed"), + view: managedViewRequestSchema, + item: managedViewItemSchema, + ...viewResultBase, + ...managedViewContextSchema.shape, + parent_operation: z.literal("inspect_managed_artifact"), + }), + z.strictObject({ + kind: z.literal("managed-members"), + view: managedMembersViewRequestSchema, + page: managedMembersViewPageSchema, + ...viewResultBase, + ...managedMembersViewContextSchema.shape, + parent_operation: z.literal("inspect_managed_members"), + }), + androidPackageViewResultSchema, + androidJniPageViewResultSchema, + z.strictObject({ + kind: z.literal("dart-aot"), + view: dartAotViewRequestSchema, + items: z.array(z.string()), + ...viewResultBase, + ...dartAotViewContextSchema.shape, + parent_operation: z.literal("inspect_dart_aot"), + }), + apkSignaturePageViewResultSchema, + modelArtifactPageViewResultSchema, + gpuCodeObjectsPageViewResultSchema, + z.strictObject({ + kind: z.literal("il2cpp-metadata"), + view: il2cppMetadataViewRequestSchema, + items: il2cppMetadataViewItemsSchema, + ...viewResultBase, + ...il2cppMetadataViewContextSchema.shape, + parent_operation: z.literal("inspect_il2cpp_metadata"), + }), + z.strictObject({ + kind: z.literal("inventory"), + view: artifactInventoryViewRequestSchema, + source_coverage: artifactInventoryCoverageSchema.exactOptional(), + manifest: artifactGraphManifestSchema, + inventory_evidence_ids: z.array(prefixedDigestSchema("ev")).min(1), + source_complete: z.boolean(), + items: artifactInventoryItemsSchema, + ...viewResultBase, + }), +]); + +export type AnalysisViewResult = z.output; + +/** View payload before the content digest is attached. */ +type WithoutViewDigest = T extends { readonly view_digest: string } + ? Omit + : never; +export type UnsignedAnalysisView = WithoutViewDigest; diff --git a/src/domain/analysisView/analysisViewShape.ts b/src/domain/analysisView/analysisViewShape.ts new file mode 100644 index 0000000000..8a9bf062b8 --- /dev/null +++ b/src/domain/analysisView/analysisViewShape.ts @@ -0,0 +1,127 @@ +import { z } from "zod"; +import { prefixedDigestSchema } from "../digests.js"; + +export const summaryViewSchema = z.strictObject({ kind: z.literal("summary") }); +export const facetViewSchema = z.strictObject({ + kind: z.literal("facet"), + facet: z.enum(["mitigations", "linkage"]), +}); +const indexSelectorSchema = z.strictObject({ + index: z.int().nonnegative(), +}); +const nameSelectorSchema = z.strictObject({ + name: z + .string() + .describe( + "Exact UTF-8 section or symbol name, matched against retained source bytes. Use index for non-UTF-8 names or unresolved name bytes.", + ), +}); +const pathSelectorSchema = z.strictObject({ + path: z + .string() + .describe( + "Exact observed module path or original source-map reference from a module page; an empty reference is valid.", + ), +}); +const nodeIdSelectorSchema = z.strictObject({ + node_id: prefixedDigestSchema("jag_node"), +}); +const moduleItemViewSchema = z.strictObject({ + kind: z.literal("item"), + collection: z.literal("modules"), + selector: z.union([pathSelectorSchema, nodeIdSelectorSchema]), +}); +const sectionOrSymbolItemViewSchema = z.strictObject({ + kind: z.literal("item"), + collection: z.enum(["sections", "symbols"]), + selector: z.union([indexSelectorSchema, nameSelectorSchema]), +}); +/** + * The collection-specific selector alternatives are expressed in the owning + * contract so the advertised JSON Schema preserves them: modules accept + * path/node_id, sections and symbols accept index/name. Refinement-only + * constraints do not survive JSON Schema conversion, so the advertised + * schema previously accepted combinations that runtime input validation + * rejects. + */ +export const itemViewSchema = z.discriminatedUnion("collection", [ + moduleItemViewSchema, + sectionOrSymbolItemViewSchema, +]); +export const pageViewSchema = z.strictObject({ + kind: z.literal("page"), + collection: z.enum(["sections", "symbols", "modules"]), + offset: z.int().nonnegative(), + limit: z.int().positive(), +}); + +/** Bounded native function facets of already authenticated analyze_function Evidence. */ +export const nativeViewSchema = z.strictObject({ + kind: z.literal("native"), + facet: z.enum([ + "procedure", + "pseudocode", + "assembly", + "basic_blocks", + "comments", + "callers", + "callees", + "incoming_references", + "outgoing_references", + "unresolved_calls", + "referenced_strings", + "referenced_names", + "swift_string_literals", + "swift_string_literal_omissions", + "native_api", + "value_flow_summary", + "value_flow_operations", + "value_flow_def_use", + "value_flow_effects", + "value_flow_parameters", + "value_flow_parameter_uses", + ]), + offset: z.int().nonnegative().default(0), + limit: z.int().positive().default(64), +}); + +export type SummaryAnalysisView = z.output; +export type FacetAnalysisView = z.output; +export type ItemAnalysisView = z.output; +export type PageAnalysisView = z.output; +export type NativeFacetAnalysisView = z.output; + +/** Views that group a capture's records into tools. */ +export type GroupingViewKind = + | "api-surface" + | "environment-manifest" + | "environment-state" + | "environment-coverage"; + +/** + * View request already admitted by analysisViewRequestSchema. + * Projectors use this supertype so they do not import the request union. + */ +export type AdmittedView = { readonly kind: string }; + +/** + * Restore the owning schema output after admission. + * analysisViewRequestSchema already checked the fields for these kinds. + */ +export const ownedView = ( + view: AdmittedView, + ...kinds: readonly View["kind"][] +): View | undefined => + (kinds as readonly string[]).includes(view.kind) ? (view as View) : undefined; + +/** Narrow an admitted view after the projector has rejected other kinds. */ +export function assertOwnedView( + view: AdmittedView, + ...kinds: readonly View["kind"][] +): asserts view is View { + if (!(kinds as readonly string[]).includes(view.kind)) { + throw new Error( + `Analysis view kind ${JSON.stringify(view.kind)} is not owned by this projector.`, + ); + } +} diff --git a/src/domain/analysisView/androidJniView.ts b/src/domain/analysisView/androidJniView.ts index c91407956b..6c978d81cb 100644 --- a/src/domain/analysisView/androidJniView.ts +++ b/src/domain/analysisView/androidJniView.ts @@ -6,17 +6,20 @@ import { androidJniDeclarationSchema, androidJniLibrarySchema, } from "../android/androidJniBindings.js"; -import { androidJniViewItemsSchema } from "../android/androidJniQuery.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; +import { + androidJniViewItemsSchema, + androidJniViewRequestSchema, +} from "../android/androidJniQuery.js"; import { AnalysisResourceConstraintError } from "../analysisErrorCore.js"; import type { JsonValue } from "../jsonValue.js"; import { jsonValueByteLength } from "../jsonValueByteLength.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { ANALYSIS_VIEW_PAGE_BUDGET_RECOVERY, analysisViewInputError, @@ -63,8 +66,8 @@ export const androidJniSummarySchema = reportSchema /** Source facts are already parsed; views never reopen the APK or rerun either reader. */ export const projectAndroidJniView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if ( parent.operation !== "inspect_android_jni_bindings" || (view.kind !== "summary" && view.kind !== "android-jni") @@ -79,6 +82,9 @@ export const projectAndroidJniView = ( }, ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "android-jni"); const parsed = readReport(parent); if (!parsed.ok) return parsed; const report = parsed.value; @@ -98,7 +104,19 @@ export const projectAndroidJniView = ( "unknowns", ), }; - let result: UnsignedAnalysisView; + const overBudget = (value: object): boolean => + jsonValueByteLength(value as unknown as JsonValue, 1024 * 1024 - 128) > + 1024 * 1024 - 128; + const budgetError = () => + err( + new AnalysisResourceConstraintError( + "inspect_analysis_view", + "transport", + "JNI view exceeds its 1 MiB serialized allowance.", + { parent_evidence_id: parent.evidenceId, limit_bytes: 1024 * 1024 }, + ANALYSIS_VIEW_PAGE_BUDGET_RECOVERY, + ), + ); if (view.kind === "summary") { const bindings = report.bindings.slice(0, 64); const candidateIds = new Set( @@ -124,9 +142,9 @@ export const projectAndroidJniView = ( unknown: 0, }; for (const binding of report.bindings) counts[binding.status]++; - result = { + const summary = { ...shared, - kind: "summary", + kind: "summary" as const, view, coverage: pageViewCoverage(0, bindings.length, report.bindings.length), summary: { @@ -152,6 +170,8 @@ export const projectAndroidJniView = ( ), }, }; + if (overBudget(summary)) return budgetError(); + return ok(summary); } else { const indices = view.indices === undefined ? undefined : new Set(view.indices); @@ -240,9 +260,9 @@ export const projectAndroidJniView = ( library_inventory: report.library_inventory, selection: report.selection, }; - result = { + const page = { ...shared, - kind: "android-jni", + kind: "android-jni" as const, view, source, items: androidJniViewItemsSchema.parse(selected.rows), @@ -252,19 +272,7 @@ export const projectAndroidJniView = ( selected.total, ), }; + if (overBudget(page)) return budgetError(); + return ok(page); } - if ( - jsonValueByteLength(result as unknown as JsonValue, 1024 * 1024 - 128) > - 1024 * 1024 - 128 - ) - return err( - new AnalysisResourceConstraintError( - "inspect_analysis_view", - "transport", - "JNI view exceeds its 1 MiB serialized allowance.", - { parent_evidence_id: parent.evidenceId, limit_bytes: 1024 * 1024 }, - ANALYSIS_VIEW_PAGE_BUDGET_RECOVERY, - ), - ); - return ok(result); }; diff --git a/src/domain/analysisView/androidPackageView.ts b/src/domain/analysisView/androidPackageView.ts index e4a029ed4a..ec6809186d 100644 --- a/src/domain/analysisView/androidPackageView.ts +++ b/src/domain/analysisView/androidPackageView.ts @@ -11,11 +11,13 @@ import { jsonValueByteLength } from "../jsonValueByteLength.js"; import type { JsonValue } from "../jsonValue.js"; import { err, ok, type Result } from "../result.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { androidViewRequestSchema } from "../android/androidPackageQuery.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { boundedViewMessages, completeWithinViewCoverage, @@ -106,8 +108,8 @@ const choose = ( /** Project authenticated retained facts without reopening the APK or engine. */ export const projectAndroidPackageView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "summary" && view.kind !== "android") return err( analysisViewInputError([ @@ -119,6 +121,9 @@ export const projectAndroidPackageView = ( }, ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "android"); if (parent.operation !== "inspect_android_package") return err( analysisViewInputError([ @@ -166,7 +171,7 @@ export const projectAndroidPackageView = ( if (view.kind === "summary") { const { text, ...manifest } = report.manifest; return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -174,7 +179,7 @@ export const projectAndroidPackageView = ( manifest: { ...manifest, text_code_units: text.length, - text_included: false, + text_included: false as const, }, }, coverage: completeWithinViewCoverage(1, 1), @@ -189,7 +194,7 @@ export const projectAndroidPackageView = ( ); if (!page.ok) return page; return ok({ - kind: "android", + kind: "android" as const, view, ...shared, item: { @@ -295,10 +300,10 @@ export const projectAndroidPackageView = ( ]++; summary.declaration_coverage[row.declaration_coverage]++; } - const result: UnsignedAnalysisView = { + const result = { ...context, - kind: "android", - facet: "component-summary", + kind: "android" as const, + facet: "component-summary" as const, view, summary, coverage: completeWithinViewCoverage(rows.length, rows.length), @@ -365,10 +370,10 @@ export const projectAndroidPackageView = ( bytes += added; items.push(item); } - const result: UnsignedAnalysisView = { + const result = { ...context, - kind: "android", - facet: "components", + kind: "android" as const, + facet: "components" as const, view, items, byte_limited, diff --git a/src/domain/analysisView/androidSymbolView.test.ts b/src/domain/analysisView/androidSymbolView.test.ts index 32397d1a06..72c38013f0 100644 --- a/src/domain/analysisView/androidSymbolView.test.ts +++ b/src/domain/analysisView/androidSymbolView.test.ts @@ -1,4 +1,6 @@ import { expect, it, vi } from "vitest"; +import { z } from "zod"; +import { androidComponentsViewRequestSchema } from "../android/androidPackageQuery.js"; import { createEvidence } from "../evidence.js"; import { immutableJsonSnapshotMember } from "../immutableJson.js"; import { @@ -7,11 +9,18 @@ import { projectAnalysisView, type AnalysisViewParent, } from "./analysisView.js"; +import type { AdmittedView } from "./analysisViewShape.js"; import { androidClassSummarySchema, - projectAndroidSymbolSummary, + projectAndroidSymbolSummary as projectAdmittedAndroidSymbolSummary, } from "./androidSymbolView.js"; +const projectAndroidSymbolSummary = ( + parent: Parameters[0], + view: z.input, +): ReturnType => + projectAdmittedAndroidSymbolSummary(parent, view satisfies AdmittedView); + type Operation = "inspect_android_class" | "inspect_android_method"; const engine = { name: "jadx", diff --git a/src/domain/analysisView/androidSymbolView.ts b/src/domain/analysisView/androidSymbolView.ts index 688d7b8401..3a39270ecf 100644 --- a/src/domain/analysisView/androidSymbolView.ts +++ b/src/domain/analysisView/androidSymbolView.ts @@ -1,14 +1,14 @@ -import type { AnalysisError } from "../analysisErrorBase.js"; import { AnalysisResourceConstraintError } from "../analysisErrorCore.js"; import { androidResultSchemas } from "../android/androidAnalysis.js"; import type { JsonValue } from "../jsonValue.js"; import { jsonValueByteLength } from "../jsonValueByteLength.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { boundedViewMessages, completeWithinViewCoverage, @@ -27,9 +27,9 @@ const PAGE_BYTES = 1024 * 1024; const DIGEST_BYTES = jsonValueByteLength({ view_digest: "0".repeat(64) }) - 1; const PROJECTION_BYTES = PAGE_BYTES - DIGEST_BYTES; -const boundedSummary = ( - result: UnsignedAnalysisView, -): Result => +const boundedSummary = ( + result: View, +) => jsonValueByteLength(result as unknown as JsonValue, PROJECTION_BYTES) > PROJECTION_BYTES ? err( @@ -53,9 +53,10 @@ const boundedSummary = ( /** Reuse authenticated Android facts without reopening the APK, mapping or engine. */ export const projectAndroidSymbolSummary = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary") + admitted: AdmittedView, +) => { + const view = ownedView(admitted, "summary"); + if (view === undefined) return err( analysisViewInputError([ { @@ -115,7 +116,7 @@ export const projectAndroidSymbolSummary = ( if (!parsed.ok) return parsed; return boundedSummary({ ...shared, - parent_operation: "inspect_android_class", + parent_operation: "inspect_android_class" as const, summary: parsed.value, }); } @@ -123,7 +124,7 @@ export const projectAndroidSymbolSummary = ( if (!parsed.ok) return parsed; return boundedSummary({ ...shared, - parent_operation: "inspect_android_method", + parent_operation: "inspect_android_method" as const, summary: parsed.value, unknowns: [ ...shared.unknowns, diff --git a/src/domain/analysisView/apiSurfaceSchema.ts b/src/domain/analysisView/apiSurfaceSchema.ts new file mode 100644 index 0000000000..b788e95ab5 --- /dev/null +++ b/src/domain/analysisView/apiSurfaceSchema.ts @@ -0,0 +1,67 @@ +import { z } from "zod"; +import { ROUTE_RULES } from "./webNetworkRouteTemplates.js"; + +export const apiSurfaceViewSchema = z.strictObject({ + kind: z.literal("api-surface"), + offset: z.int().nonnegative().default(0), + limit: z.int().positive().default(50), + include_query_parameter_names: z + .boolean() + .optional() + .describe( + "Include distinct observed query parameter names and their original record ordinals; names do not establish required parameters or a complete API schema.", + ), +}); +const ruleSchema = z.enum(ROUTE_RULES); +const groupSchema = z.strictObject({ + method: z.string(), + origin: z.string(), + path_template: z.string(), + templated_segments: z.array( + z.strictObject({ + segment_index: z.int().nonnegative(), + rule: ruleSchema, + basis: z.literal("inferred"), + observed_values: z.array(z.string()), + }), + ), + record_ordinals: z.array(z.int().nonnegative()), + statuses: z.array(z.number()), + content_types: z.array(z.string()), + query_parameter_names: z + .array( + z.strictObject({ + name: z.string(), + record_ordinals: z.array(z.int().nonnegative()), + }), + ) + .optional(), + flags: z.array( + z.enum(["single-sample", "mixed-statuses", "mixed-content-types"]), + ), +}); +export const apiSurfaceFields = { + records: z.strictObject({ + examined: z.int().nonnegative(), + total: z.int().nonnegative(), + excluded: z.int().nonnegative(), + }), + templated_groups: z + .int() + .nonnegative() + .describe( + "Groups across every page that carry at least one templated segment.", + ), + groups: z.array(groupSchema), + excluded_records: z.array( + z.strictObject({ + ordinal: z.int().nonnegative(), + reason: z.enum([ + "url-redacted", + "url-unparseable", + "request-unavailable", + "method-unavailable", + ]), + }), + ), +}; diff --git a/src/domain/analysisView/apkSignatureView.ts b/src/domain/analysisView/apkSignatureView.ts index 8172766d2e..812c3cf2c7 100644 --- a/src/domain/analysisView/apkSignatureView.ts +++ b/src/domain/analysisView/apkSignatureView.ts @@ -9,17 +9,18 @@ import { import { apkSignatureSchemeSchema, apkSignatureViewItemsSchema, - type apkSignatureViewRequestSchema, + apkSignatureViewRequestSchema, } from "../apkSignature/apkSignatureQuery.js"; import { isImmutableJsonSnapshot } from "../immutableJson.js"; import type { JsonValue } from "../jsonValue.js"; import { err, ok, type Result } from "../result.js"; import type { AnalysisError } from "../analysisErrorBase.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { @@ -263,8 +264,8 @@ function* records( export const projectApkSignatureView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "summary" && view.kind !== "apk-signature") return err( analysisViewInputError([ @@ -276,6 +277,9 @@ export const projectApkSignatureView = ( }, ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "apk-signature"); const parsed = read(parent); if (!parsed.ok) return parsed; const { report, summary } = parsed.value; @@ -297,7 +301,7 @@ export const projectApkSignatureView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary, @@ -324,7 +328,7 @@ export const projectApkSignatureView = ( items.push(item); } return ok({ - kind: "apk-signature", + kind: "apk-signature" as const, view, ...shared, source_coverage: summary.source_coverage, diff --git a/src/domain/analysisView/artifactInventoryView.test.ts b/src/domain/analysisView/artifactInventoryView.test.ts index fc510639e4..4323daebd5 100644 --- a/src/domain/analysisView/artifactInventoryView.test.ts +++ b/src/domain/analysisView/artifactInventoryView.test.ts @@ -100,8 +100,7 @@ const page = (source: AnalysisViewParent, view: unknown) => { artifactInventoryViewRequestSchema.parse(view), ); if (!result.ok) throw result.error; - if (result.value.kind !== "inventory") - throw new Error("Expected an inventory page"); + if (!("items" in result.value)) throw new Error("Expected an inventory page"); return result.value; }; afterEach(() => vi.restoreAllMocks()); diff --git a/src/domain/analysisView/artifactInventoryView.ts b/src/domain/analysisView/artifactInventoryView.ts index d0b8773edb..f3608826ef 100644 --- a/src/domain/analysisView/artifactInventoryView.ts +++ b/src/domain/analysisView/artifactInventoryView.ts @@ -27,11 +27,12 @@ import { type InventorySet, } from "../artifactInventoryEvidence.js"; import type { ArtifactInspectionResult } from "../artifactInspection.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -231,8 +232,8 @@ const sourceFailure = ( /** Project exact source records; exhausted pages cover available records, not runtime behavior. */ export const projectArtifactInventoryView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { const operation = parent.operation; if (operation !== "inventory_artifact" && operation !== "inspect_artifact") return err( @@ -248,6 +249,9 @@ export const projectArtifactInventoryView = ( "Artifact Evidence supports summary and inventory views.", ), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "inventory"); const parsed = parseSource(parent); if (!parsed.ok) return parsed; const source = parsed.value; @@ -301,22 +305,21 @@ export const projectArtifactInventoryView = ( "Parent inventory is partial; counts and exhausted pages cover only available records. Missing matches do not establish absence.", ]), ], - } satisfies Pick< - UnsignedAnalysisView, - | "parent_evidence_id" - | "parent_operation" - | "parent_digest" - | "artifact" - | "limitations" - | "unknowns" - >; + } satisfies { + parent_evidence_id: string; + parent_operation: "inspect_artifact" | "inventory_artifact"; + parent_digest: string; + artifact: { path: string; sha256: string }; + limitations: readonly string[]; + unknowns: readonly string[]; + }; if (view.kind === "summary") { const examined = inventory.nodes.length + inventory.occurrences.length + inventory.edges.length; return ok({ - kind: "summary", + kind: "summary" as const, view, summary: { manifest: inventory.manifest, @@ -373,7 +376,7 @@ export const projectArtifactInventoryView = ( : inventory.integrityContradictions.length, }; return ok({ - kind: "inventory", + kind: "inventory" as const, view, manifest: inventory.manifest, inventory_evidence_ids: [...evidenceIds], @@ -406,7 +409,7 @@ const occurrencePage = (source: InventorySource, view: OccurrenceView) => { const nodePage = ( source: InventorySource, view: Extract< - AnalysisViewRequest, + z.output, { kind: "inventory"; collection: "nodes" } >, ) => { @@ -451,7 +454,7 @@ const inventoryCounts = (source: InventorySource): InventoryCounts => { }; type OccurrenceView = Extract< - AnalysisViewRequest, + z.output, { kind: "inventory"; collection: "occurrences" } >; diff --git a/src/domain/analysisView/binaryLayoutView.ts b/src/domain/analysisView/binaryLayoutView.ts index b4b7865ff4..f3d38e7aec 100644 --- a/src/domain/analysisView/binaryLayoutView.ts +++ b/src/domain/analysisView/binaryLayoutView.ts @@ -5,12 +5,15 @@ import { import type { AnalysisError } from "../analysisErrorBase.js"; import type { BinaryLayout } from "../native/binaryLayout.js"; import { err, ok, type Result } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, - GroupingViewKind, -} from "./analysisView.js"; + AdmittedView, + FacetAnalysisView, + ItemAnalysisView, + PageAnalysisView, + SummaryAnalysisView, +} from "./analysisViewShape.js"; +import { assertOwnedView } from "./analysisViewShape.js"; import { boundedViewMessages, completeWithinViewCoverage as completeCoverage, @@ -171,8 +174,8 @@ const layoutSummary = (layout: BinaryLayout) => ({ export const projectBinaryLayoutView = ( parent: AnalysisViewParent, layout: BinaryLayout, - view: Exclude, -): Result => { + view: AdmittedView, +) => { const shared = parentFields(parent, layout); if (view.kind === "native") return err( @@ -190,9 +193,10 @@ export const projectBinaryLayoutView = ( return err( layoutIncompatible("EVM views require inspect_evm_interface Evidence."), ); - if (view.kind === "summary") + if (view.kind === "summary") { + assertOwnedView(view, "summary"); return ok({ - kind: "summary", + kind: "summary" as const, view, summary: layoutSummary(layout), coverage: completeCoverage( @@ -207,15 +211,19 @@ export const projectBinaryLayoutView = ( ), ...shared, }); - if (view.kind === "facet") + } + if (view.kind === "facet") { + assertOwnedView(view, "facet"); return ok({ - kind: "facet", + kind: "facet" as const, view, facet: view.facet === "mitigations" ? layout.mitigations : layout.linkage, coverage: completeCoverage(1, 1), ...shared, }); + } if (view.kind === "item") { + assertOwnedView(view, "item"); if (view.collection === "modules") return err( layoutIncompatible( @@ -228,7 +236,7 @@ export const projectBinaryLayoutView = ( : selectLayoutItem(view.collection, layout.symbols, view.selector); if (!selected.ok) return selected; return ok({ - kind: "item", + kind: "item" as const, view, item: selected.value, coverage: completeCoverage( @@ -246,6 +254,7 @@ export const projectBinaryLayoutView = ( "Layout views require summary, facet, item or page selections.", ), ); + assertOwnedView(view, "page"); if (view.collection === "modules") return err( layoutIncompatible( @@ -259,7 +268,7 @@ export const projectBinaryLayoutView = ( ? pageRows(layout.sections, view.offset, view.limit) : pageRows(layout.symbols, view.offset, view.limit); return ok({ - kind: "page", + kind: "page" as const, view, items: [...items], coverage: pageCoverage(view.offset, items.length, rows.length), @@ -270,7 +279,7 @@ export const projectBinaryLayoutView = ( const selectLayoutItem = ( collection: "sections" | "symbols", rows: readonly Row[], - selector: Extract["selector"], + selector: ItemAnalysisView["selector"], ): Result => { if ("index" in selector) return selectIndexed(collection, rows, selector.index); diff --git a/src/domain/analysisView/browserScenarioView.ts b/src/domain/analysisView/browserScenarioView.ts index a64363a275..b2df96a119 100644 --- a/src/domain/analysisView/browserScenarioView.ts +++ b/src/domain/analysisView/browserScenarioView.ts @@ -6,7 +6,7 @@ import { } from "../browserScenarioCapture.js"; import type { BrowserScenarioStep as Step } from "../browserScenarioCaptureValues.js"; import { compareAsciiStrings } from "../canonicalOrdering.js"; -import { err, ok, type Result } from "../result.js"; +import { err, ok } from "../result.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { completeWithinViewCoverage, @@ -14,11 +14,12 @@ import { type AnalysisViewCoverage, } from "./analysisViewCoverage.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { ARTIFACT_SECTIONS, stepRowSchema, @@ -314,10 +315,15 @@ const pageRecords = ( /** Project retained scenario Evidence without relaunching the browser or replaying actions. */ export const projectBrowserScenarioView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "summary" && view.kind !== "browser-scenario") return err(unsupportedView()); + assertOwnedView( + view, + "summary", + "browser-scenario", + ); const parsed = readCapture(parent); if (!parsed.ok) return parsed; const capture = parsed.value; @@ -339,7 +345,7 @@ export const projectBrowserScenarioView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -371,7 +377,7 @@ export const projectBrowserScenarioView = ( ]), ); return ok({ - kind: "browser-scenario", + kind: "browser-scenario" as const, view, ...shared, source_completeness: capture.completeness, diff --git a/src/domain/analysisView/byteEntropyView.ts b/src/domain/analysisView/byteEntropyView.ts index c00e15a8a1..ae04201a6e 100644 --- a/src/domain/analysisView/byteEntropyView.ts +++ b/src/domain/analysisView/byteEntropyView.ts @@ -1,13 +1,13 @@ import { z } from "zod"; import { AnalysisInputError } from "../analysisErrorCore.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { byteEntropySchema, type ByteEntropy } from "../native/byteEntropy.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage } from "./analysisViewCoverage.js"; export const byteEntropySummarySchema = byteEntropySchema @@ -22,8 +22,8 @@ export const byteEntropySummarySchema = byteEntropySchema export const projectByteEntropyView = ( parent: AnalysisViewParent, report: ByteEntropy, - view: Exclude, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "summary") return err( new AnalysisInputError("inspect_analysis_view", undefined, [ @@ -35,11 +35,12 @@ export const projectByteEntropyView = ( }, ]), ); + assertOwnedView(view, "summary"); return ok({ - kind: "summary", + kind: "summary" as const, view, parent_evidence_id: parent.evidenceId, - parent_operation: "inspect_byte_entropy", + parent_operation: "inspect_byte_entropy" as const, parent_digest: parent.evidenceId.slice(3), artifact: { path: report.artifact.path, sha256: report.artifact.sha256 }, summary: { @@ -61,6 +62,6 @@ export const projectByteEntropyView = ( limitations: [ ...new Set([...parent.limitations, ...report.limitations]), ].sort(), - unknowns: [], + unknowns: [] as string[], }); }; diff --git a/src/domain/analysisView/commandObservationView.ts b/src/domain/analysisView/commandObservationView.ts index 6779a7255e..19d5482d88 100644 --- a/src/domain/analysisView/commandObservationView.ts +++ b/src/domain/analysisView/commandObservationView.ts @@ -1,5 +1,4 @@ import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { commandObservationSchema, gdbCommandResultSchema, @@ -8,12 +7,13 @@ import { digestSchema } from "../digests.js"; import { providerSchema } from "../evidence.js"; import { analysisInputErrorFromIssues } from "../inputIssueProjection.js"; import { jsonValueSchema } from "../jsonValue.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { boundedViewMessages, completeWithinViewCoverage, @@ -42,9 +42,10 @@ export const gdbCommandSummarySchema = gdbCommandResultSchema /** Select existing owner facts without parsing a command or its output protocol. */ export const projectCommandObservationView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary") + admitted: AdmittedView, +) => { + const view = ownedView(admitted, "summary"); + if (view === undefined) return err( analysisViewInputError([ { @@ -136,7 +137,7 @@ export const projectCommandObservationView = ( const { console, target, log, ...records } = parsed.value; return ok({ ...shared, - parent_operation: "gdb_console", + parent_operation: "gdb_console" as const, summary: { ...records, available_counts: { @@ -170,7 +171,7 @@ export const projectCommandObservationView = ( ); return ok({ ...shared, - parent_operation: "inspect_with_objdump", + parent_operation: "inspect_with_objdump" as const, summary: report, }); }; diff --git a/src/domain/analysisView/dartAotView.ts b/src/domain/analysisView/dartAotView.ts index 83625736f0..d1c196bf24 100644 --- a/src/domain/analysisView/dartAotView.ts +++ b/src/domain/analysisView/dartAotView.ts @@ -1,14 +1,14 @@ import { analysisViewInputError } from "./analysisViewErrors.js"; import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { flutterResultSchemas } from "../flutter/flutterBuildAnalysis.js"; -import { err, ok, type Result } from "../result.js"; +import { err, ok } from "../result.js"; import { parseAnalysisViewResult } from "./analysisViewParent.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -47,9 +47,12 @@ export const dartAotViewContextSchema = z.strictObject({ /** Reuse authenticated AOT Evidence without opening the APK or rescanning its ELF. */ export const projectDartAotView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "dart-aot") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "dart-aot"); + if (view === undefined) return err( analysisViewInputError([ { @@ -90,7 +93,7 @@ export const projectDartAotView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { ...report, string_pool }, @@ -99,7 +102,7 @@ export const projectDartAotView = ( const collection = report.string_pool[view.collection]; const items = collection.slice(view.offset, view.offset + view.limit); return ok({ - kind: "dart-aot", + kind: "dart-aot" as const, view, ...shared, items, diff --git a/src/domain/analysisView/desktopApplicationView.ts b/src/domain/analysisView/desktopApplicationView.ts index a179baf873..3be4848187 100644 --- a/src/domain/analysisView/desktopApplicationView.ts +++ b/src/domain/analysisView/desktopApplicationView.ts @@ -16,13 +16,13 @@ import { completeWithinViewCoverage, pageViewCoverage, } from "./analysisViewCoverage.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import { ok, err, type Result } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; +import { ok, err } from "../result.js"; // Bound diagnostic context independently of the retained report size. Previews // are display values; stable file IDs select the original paths and all issues. @@ -146,9 +146,12 @@ type DesktopViewRow = DesktopApplication[DesktopCollection][number]; const validatedParents = new WeakSet(); export const projectDesktopApplicationView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "desktop-application") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "desktop-application"); + if (view === undefined) return err( analysisViewInputError([ { @@ -272,7 +275,7 @@ export const projectDesktopApplicationView = ( else group.count++; } return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -342,7 +345,7 @@ export const projectDesktopApplicationView = ( ), ); return ok({ - kind: "desktop-application", + kind: "desktop-application" as const, view, ...shared, source_coverage: report.coverage, diff --git a/src/domain/analysisView/devicetreeView.ts b/src/domain/analysisView/devicetreeView.ts index c27e1a12ed..54232e38f4 100644 --- a/src/domain/analysisView/devicetreeView.ts +++ b/src/domain/analysisView/devicetreeView.ts @@ -1,12 +1,12 @@ import { z } from "zod"; import { devicetreeSchema } from "../firmware/devicetree.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { @@ -57,8 +57,8 @@ export const devicetreePageContextSchema = devicetreeSchema const readReport = createAnalysisViewResultReader(devicetreeSchema); export const projectDevicetreeView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { const invalid = (message: string) => err( analysisViewInputError([ @@ -69,6 +69,9 @@ export const projectDevicetreeView = ( return invalid( "Devicetree Evidence supports summary and devicetree views.", ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "devicetree"); const parsed = readReport(parent); if (!parsed.ok) return parsed; const r = parsed.value; @@ -99,7 +102,7 @@ export const projectDevicetreeView = ( if (view.kind === "summary") return ok({ ...shared, - kind: "summary", + kind: "summary" as const, view, summary: { ...context, summary: r.summary }, coverage: completeWithinViewCoverage(r.nodes.length, r.nodes.length), @@ -148,7 +151,7 @@ export const projectDevicetreeView = ( const { items, total } = selected; return ok({ ...shared, - kind: "devicetree", + kind: "devicetree" as const, view, devicetree: { ...context, alias_count: r.summary.aliases.length }, items, diff --git a/src/domain/analysisView/environmentCoverageView.ts b/src/domain/analysisView/environmentCoverageView.ts index 40cca47794..4cd86896d4 100644 --- a/src/domain/analysisView/environmentCoverageView.ts +++ b/src/domain/analysisView/environmentCoverageView.ts @@ -1,11 +1,6 @@ import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import { ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; import { templateRulesSchema } from "./environmentManifestView.js"; import type { StateView } from "./environmentStateRules.js"; import { @@ -154,18 +149,18 @@ export const summarizeEnvironmentCoverage = (state: { /** Project the state an environment would serve and summarize which tools it answers from that state. */ export const projectEnvironmentCoverageView = ( parent: AnalysisViewParent, - view: Extract, + view: z.output, accumulator = createEnvironmentStateAccumulator(view), -): Result => { +) => { const projected = projectEnvironmentStateView( parent, - { kind: "environment-state", template_rules: view.template_rules }, + { kind: "environment-state" as const, template_rules: view.template_rules }, accumulator, ); if (!projected.ok) return projected; const state = projected.value; return ok({ - kind: "environment-coverage", + kind: "environment-coverage" as const, view, parent_evidence_id: state.parent_evidence_id, parent_operation: state.parent_operation, diff --git a/src/domain/analysisView/environmentManifestSchema.ts b/src/domain/analysisView/environmentManifestSchema.ts new file mode 100644 index 0000000000..9abea82b90 --- /dev/null +++ b/src/domain/analysisView/environmentManifestSchema.ts @@ -0,0 +1,90 @@ +import { z } from "zod"; +import { jsonRecordSchema } from "../jsonRecord.js"; +import { TEMPLATE_RULES } from "./environmentManifestRules.js"; +import { ROUTE_RULES } from "./webNetworkRouteTemplates.js"; + +const manifestRuleSchema = z.enum([...ROUTE_RULES, ...TEMPLATE_RULES]); +const jsonTypeNameSchema = z.enum([ + "string", + "number", + "boolean", + "object", + "array", + "null", +]); +const toolSchema = z.strictObject({ + name: z.string(), + method: z.string(), + path_template: z.string(), + api_surface_template: z + .string() + .describe("Four-rule template of the tool's earliest record."), + params: z.array( + z.strictObject({ + index: z.number().int().nonnegative(), + name: z.string(), + rule: manifestRuleSchema, + basis: z.literal("inferred"), + observed_values: z.array(z.string()), + }), + ), + query_parameter_names: z.array(z.string()), + body_shape: z + .strictObject({ + type: z.literal("object"), + properties: jsonRecordSchema(jsonTypeNameSchema), + }) + .nullable(), + statuses: z.array(z.number()), + content_types: z.array(z.string()), + record_ordinals: z.array(z.number().int().nonnegative()), +}); +export const environmentManifestFields = { + origin: z + .string() + .describe("Primary origin: the origin with the most JSON-like records."), + name: z + .string() + .describe( + "Kebab-case environment name derived from the primary origin host.", + ), + tools: z.array(toolSchema), + records: z + .array( + z.strictObject({ + ordinal: z.number().int().nonnegative(), + method: z.string(), + path: z.string(), + status: z.number().nullable(), + content_type: z.string().nullable(), + }), + ) + .describe( + "Pointers to the retained parent records cited by tools; no bodies.", + ), + excluded: z.array( + z.strictObject({ + method: z.string(), + origin: z.string(), + path_template: z.string(), + reason: z.enum(["other-origin", "ui-page-or-asset", "non-json"]), + }), + ), + unknowns: z.array( + z.strictObject({ + kind: z.enum([ + "authorization-model", + "response-semantics", + "state-transition", + ]), + statement: z.string(), + }), + ), + templated_groups: z + .number() + .int() + .nonnegative() + .describe( + "Tools and excluded groups that carry at least one templated segment.", + ), +}; diff --git a/src/domain/analysisView/environmentManifestView.ts b/src/domain/analysisView/environmentManifestView.ts index 9dcd88f8f4..cabf1085d4 100644 --- a/src/domain/analysisView/environmentManifestView.ts +++ b/src/domain/analysisView/environmentManifestView.ts @@ -1,15 +1,11 @@ import { z } from "zod"; -import { jsonRecordSchema } from "../jsonRecord.js"; import type { WebNetworkCaptureRecord } from "../webNetworkCapture.js"; import { AnalysisUnsupportedTargetError } from "../analysisErrorCore.js"; import type { AnalysisError } from "../analysisErrorBase.js"; import { uniqueSorted } from "../canonicalOrdering.js"; import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { ownedView, type AdmittedView } from "./analysisViewShape.js"; import { EnvironmentManifestAccumulator } from "./EnvironmentManifestAccumulator.js"; import { TEMPLATE_RULES, @@ -20,7 +16,9 @@ import { admitScenarioCaptureParent, type ScenarioResponseBodyRetention, } from "./scenarioCaptureRecords.js"; -import { ROUTE_RULES } from "./webNetworkRouteTemplates.js"; +import { environmentManifestFields } from "./environmentManifestSchema.js"; + +export { environmentManifestFields }; /** Opt-in template rules, each listed at most once; shared by every view that groups tools. */ export const templateRulesSchema = z @@ -44,92 +42,6 @@ export const environmentManifestViewRequestSchema = z.strictObject({ ), }); -const manifestRuleSchema = z.enum([...ROUTE_RULES, ...TEMPLATE_RULES]); -const jsonTypeNameSchema = z.enum([ - "string", - "number", - "boolean", - "object", - "array", - "null", -]); -const toolSchema = z.strictObject({ - name: z.string(), - method: z.string(), - path_template: z.string(), - api_surface_template: z - .string() - .describe("Four-rule template of the tool's earliest record."), - params: z.array( - z.strictObject({ - index: z.number().int().nonnegative(), - name: z.string(), - rule: manifestRuleSchema, - basis: z.literal("inferred"), - observed_values: z.array(z.string()), - }), - ), - query_parameter_names: z.array(z.string()), - body_shape: z - .strictObject({ - type: z.literal("object"), - properties: jsonRecordSchema(jsonTypeNameSchema), - }) - .nullable(), - statuses: z.array(z.number()), - content_types: z.array(z.string()), - record_ordinals: z.array(z.number().int().nonnegative()), -}); -export const environmentManifestFields = { - origin: z - .string() - .describe("Primary origin: the origin with the most JSON-like records."), - name: z - .string() - .describe( - "Kebab-case environment name derived from the primary origin host.", - ), - tools: z.array(toolSchema), - records: z - .array( - z.strictObject({ - ordinal: z.number().int().nonnegative(), - method: z.string(), - path: z.string(), - status: z.number().nullable(), - content_type: z.string().nullable(), - }), - ) - .describe( - "Pointers to the retained parent records cited by tools; no bodies.", - ), - excluded: z.array( - z.strictObject({ - method: z.string(), - origin: z.string(), - path_template: z.string(), - reason: z.enum(["other-origin", "ui-page-or-asset", "non-json"]), - }), - ), - unknowns: z.array( - z.strictObject({ - kind: z.enum([ - "authorization-model", - "response-semantics", - "state-transition", - ]), - statement: z.string(), - }), - ), - templated_groups: z - .number() - .int() - .nonnegative() - .describe( - "Tools and excluded groups that carry at least one templated segment.", - ), -}; - /** The records, coverage and identity a manifest projects from, for either parent kind. */ export interface CaptureParent { readonly operation: @@ -227,28 +139,36 @@ const addCaptureRecords = ( /** Create the manifest budget with its selected query names and template rules. */ export const createEnvironmentManifestAccumulator = ( - view: AnalysisViewRequest, -): EnvironmentManifestAccumulator => - view.kind === "environment-manifest" - ? new EnvironmentManifestAccumulator( + view: AdmittedView, +): EnvironmentManifestAccumulator => { + const selected = ownedView< + z.output + >(view, "environment-manifest"); + return selected === undefined + ? new EnvironmentManifestAccumulator() + : new EnvironmentManifestAccumulator( undefined, - view.include_query_parameter_names, - view.template_rules, - ) - : new EnvironmentManifestAccumulator(); + selected.include_query_parameter_names, + selected.template_rules, + ); +}; /** Project retained request lines, from a HAR or a browser scenario, into a replayable tool surface; templates are inferences. */ export const projectEnvironmentManifestView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, - accumulator = createEnvironmentManifestAccumulator(view), -): Result => { - if (view.kind !== "environment-manifest") + admitted: AdmittedView, + accumulator = createEnvironmentManifestAccumulator(admitted), +) => { + const view = ownedView>( + admitted, + "environment-manifest", + ); + if (view === undefined) return err( new AnalysisUnsupportedTargetError( "inspect_analysis_view", parent.evidenceId, - `View ${view.kind} is unsupported for parent operation ${parent.operation}; environment-manifest requires inspect_web_network_capture or capture_browser_scenario.`, + `View ${admitted.kind} is unsupported for parent operation ${parent.operation}; environment-manifest requires inspect_web_network_capture or capture_browser_scenario.`, ), ); const grouped = groupCaptureRecords(parent, view.kind, view.template_rules, { @@ -265,7 +185,7 @@ export const projectEnvironmentManifestView = ( const manifest = accumulator.finish(); if (!manifest.ok) return manifest; return ok({ - kind: "environment-manifest", + kind: "environment-manifest" as const, view, parent_evidence_id: parent.evidenceId, parent_operation: capture.operation, diff --git a/src/domain/analysisView/environmentStateView.ts b/src/domain/analysisView/environmentStateView.ts index 82e0f0fb32..044dd91931 100644 --- a/src/domain/analysisView/environmentStateView.ts +++ b/src/domain/analysisView/environmentStateView.ts @@ -1,13 +1,8 @@ import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { jsonObjectSchema, jsonValueSchema } from "../jsonValue.js"; import { jsonRecordSchema } from "../jsonRecord.js"; -import { ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; import { EnvironmentStateAccumulator } from "./EnvironmentStateAccumulator.js"; import { DELETED_FLAGS } from "./environmentStateRules.js"; import { isClockZone } from "./environmentStateWriteValues.js"; @@ -558,23 +553,17 @@ export const environmentStateFields = { }; /** State extraction and coverage share the same budget and template-rule policy. */ -export const createEnvironmentStateAccumulator = ( - view: Extract< - AnalysisViewRequest, - { kind: "environment-state" | "environment-coverage" } - >, -): EnvironmentStateAccumulator => +export const createEnvironmentStateAccumulator = (view: { + readonly template_rules: z.output; +}): EnvironmentStateAccumulator => new EnvironmentStateAccumulator(undefined, view.template_rules); /** Extract the init state a capture's reads observed and each read tool's render plan; types and identity are inferences. */ export const projectEnvironmentStateView = ( parent: AnalysisViewParent, - view: Extract, + view: z.output, accumulator = createEnvironmentStateAccumulator(view), -): Result< - Extract, - AnalysisError -> => { +) => { const grouped = groupCaptureRecords(parent, view.kind, view.template_rules, { accumulator, noun: "state", @@ -586,7 +575,7 @@ export const projectEnvironmentStateView = ( const state = accumulator.finishState(); if (!state.ok) return state; return ok({ - kind: "environment-state", + kind: "environment-state" as const, view, parent_evidence_id: parent.evidenceId, parent_operation: grouped.value.operation, diff --git a/src/domain/analysisView/erlangBeamView.ts b/src/domain/analysisView/erlangBeamView.ts index e2e25c2939..7f14f88ee2 100644 --- a/src/domain/analysisView/erlangBeamView.ts +++ b/src/domain/analysisView/erlangBeamView.ts @@ -1,12 +1,12 @@ import { z } from "zod"; import { erlangBeamSchema, type ErlangBeam } from "../erlang/beam.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { @@ -165,9 +165,12 @@ const selectRows = (rows: readonly Row[] | null, view: BeamView) => { /** Project retained BEAM facts without reopening files or reinterpreting chunks. */ export const projectErlangBeamView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "beam") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "beam"); + if (view === undefined) return err( analysisViewInputError([ { @@ -215,7 +218,7 @@ export const projectErlangBeamView = ( if (view.kind === "summary") return ok({ ...shared, - kind: "summary", + kind: "summary" as const, view, summary, coverage: completeWithinViewCoverage(chunks.length, chunks.length), @@ -223,7 +226,7 @@ export const projectErlangBeamView = ( const selected = selectRows(parsed.value[view.collection], view); return ok({ ...shared, - kind: "beam", + kind: "beam" as const, view, beam: summary, page: { collection: view.collection, items: selected.rows }, diff --git a/src/domain/analysisView/evmInterfaceView.ts b/src/domain/analysisView/evmInterfaceView.ts index 246e525a0f..9a5148aa0a 100644 --- a/src/domain/analysisView/evmInterfaceView.ts +++ b/src/domain/analysisView/evmInterfaceView.ts @@ -1,15 +1,15 @@ import { analysisViewInputError } from "./analysisViewErrors.js"; import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { uniqueSorted } from "../canonicalOrdering.js"; import { evmInterfaceSchema } from "../evm/evmInterface.js"; -import { err, ok, type Result } from "../result.js"; +import { err, ok } from "../result.js"; import { parseAnalysisViewResult } from "./analysisViewParent.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -51,9 +51,12 @@ export const evmSummarySchema = z.strictObject({ /** Select already authenticated producer facts; no interpreter or provider is invoked. */ export const projectEvmInterfaceView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "evm") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "evm"); + if (view === undefined) return err( analysisViewInputError([ { @@ -96,7 +99,7 @@ export const projectEvmInterfaceView = ( const { hex: _hex, ...bytecode } = report.bytecode; const { stdout, ...diagnostics } = report.diagnostics; return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -118,7 +121,7 @@ export const projectEvmInterfaceView = ( if (view.facet === "functions") { const item = report.functions.slice(view.offset, view.offset + view.limit); return ok({ - kind: "evm", + kind: "evm" as const, view, item, ...shared, @@ -134,5 +137,7 @@ export const projectEvmInterfaceView = ( ? report.bytecode.hex : report.diagnostics[view.facet]; const page = analysisTextPage(text, view.offset, view.limit, view.facet); - return page.ok ? ok({ kind: "evm", view, ...page.value, ...shared }) : page; + return page.ok + ? ok({ kind: "evm" as const, view, ...page.value, ...shared }) + : page; }; diff --git a/src/domain/analysisView/fridaSessionStatusView.ts b/src/domain/analysisView/fridaSessionStatusView.ts index 87ee04b696..b2bf3989cb 100644 --- a/src/domain/analysisView/fridaSessionStatusView.ts +++ b/src/domain/analysisView/fridaSessionStatusView.ts @@ -1,13 +1,13 @@ import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { providerSchema } from "../evidence.js"; import { fridaSessionStatusSchema } from "../fridaSessionStatus.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { boundedViewMessages, completeWithinViewCoverage, @@ -27,9 +27,10 @@ export const fridaSessionStatusViewContext = { /** Summarize captured facts without interpreting caller-authored message payloads. */ export const projectFridaSessionStatusView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary") + admitted: AdmittedView, +) => { + const view = ownedView(admitted, "summary"); + if (view === undefined) return err( analysisViewInputError([ { @@ -60,11 +61,11 @@ export const projectFridaSessionStatusView = ( ); const { messages, ...status } = report.value; return ok({ - kind: "summary", + kind: "summary" as const, view, parent_evidence_id: parent.evidenceId, parent_digest: parent.evidenceId.slice(3), - parent_operation: "frida_session_status", + parent_operation: "frida_session_status" as const, artifact: null, source_provider: parent.provider ?? null, source_parameters: parameters.data, diff --git a/src/domain/analysisView/goBinaryView.ts b/src/domain/analysisView/goBinaryView.ts index 83e2510a07..54e11cfb09 100644 --- a/src/domain/analysisView/goBinaryView.ts +++ b/src/domain/analysisView/goBinaryView.ts @@ -1,19 +1,19 @@ import { binaryMetadataArchitecture } from "../binaryMetadataArchitecture.js"; import { metadataReportSubjectFormat } from "../apple/machoTargetSelection.js"; import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { goBinarySchema, goBuildInfoSchema, goModuleMetadataSchema, goModuleSchema, } from "../go/goBinary.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { boundedViewMessages, completeWithinViewCoverage, @@ -107,9 +107,12 @@ const parseReport = createAnalysisViewResultReader(goBinarySchema); /** Query the existing metadata owner's facts; never reopen or reinterpret a file. */ export const projectGoBinaryView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "go") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "go"); + if (view === undefined) return err( analysisViewInputError([ { @@ -183,7 +186,7 @@ export const projectGoBinaryView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -242,10 +245,10 @@ export const projectGoBinaryView = ( }), ); return ok({ - kind: "go", + kind: "go" as const, view, ...shared, - page: { collection: "dependencies", rows: selected.rows }, + page: { collection: "dependencies" as const, rows: selected.rows }, coverage: pageViewCoverage( view.offset, selected.rows.length, @@ -266,10 +269,10 @@ export const projectGoBinaryView = ( }), ); return ok({ - kind: "go", + kind: "go" as const, view, ...shared, - page: { collection: "settings", rows: selected.rows }, + page: { collection: "settings" as const, rows: selected.rows }, coverage: pageViewCoverage( view.offset, selected.rows.length, diff --git a/src/domain/analysisView/gpuCodeObjectsView.ts b/src/domain/analysisView/gpuCodeObjectsView.ts index 671489002b..f8d82e6b29 100644 --- a/src/domain/analysisView/gpuCodeObjectsView.ts +++ b/src/domain/analysisView/gpuCodeObjectsView.ts @@ -12,11 +12,12 @@ import { type GpuCodeObjects, } from "../gpu/gpuCodeObjects.js"; import type { AnalysisError } from "../analysisErrorBase.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { ANALYSIS_VIEW_PAGE_BUDGET_RECOVERY, analysisViewInputError, @@ -222,9 +223,12 @@ const readGpuFacts = ( }; export const projectGpuCodeObjectsView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "gpu-code-objects") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "gpu-code-objects"); + if (view === undefined) return err( analysisViewInputError([ { @@ -258,7 +262,7 @@ export const projectGpuCodeObjectsView = ( }; if (view.kind === "summary") { return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { ...summary, limitations: shared.limitations }, @@ -312,7 +316,7 @@ export const projectGpuCodeObjectsView = ( ), ); return ok({ - kind: "gpu-code-objects", + kind: "gpu-code-objects" as const, view, ...shared, source_coverage: report.coverage, @@ -324,7 +328,7 @@ export const projectGpuCodeObjectsView = ( byte_length: artifact.byte_length, text, offset: view.offset, - offset_unit: "utf16-code-unit", + offset_unit: "utf16-code-unit" as const, }, coverage: pageViewCoverage( view.offset, @@ -419,7 +423,7 @@ export const projectGpuCodeObjectsView = ( ), ); return ok({ - kind: "gpu-code-objects", + kind: "gpu-code-objects" as const, view, ...shared, source_coverage: report.coverage, diff --git a/src/domain/analysisView/il2cppMetadataView.test.ts b/src/domain/analysisView/il2cppMetadataView.test.ts index 67d1109700..9aa9a4b9e4 100644 --- a/src/domain/analysisView/il2cppMetadataView.test.ts +++ b/src/domain/analysisView/il2cppMetadataView.test.ts @@ -1,5 +1,6 @@ import { createEmptyIl2cppMetadataFixture } from "../il2cpp/il2cppMetadata.fixture.js"; import { afterEach, expect, it, vi } from "vitest"; +import { z } from "zod"; import { il2cppMetadataParentSchema, type Il2cppMetadata, @@ -7,7 +8,22 @@ import { import { createEvidence } from "../evidence.js"; import { freezeJsonSnapshot } from "../immutableJson.js"; import { jsonObjectSchema } from "../jsonValue.js"; -import { projectIl2cppMetadataView } from "./il2cppMetadataView.js"; +import type { AdmittedView, SummaryAnalysisView } from "./analysisViewShape.js"; +import { + il2cppMetadataViewRequestSchema, + projectIl2cppMetadataView as projectAdmittedIl2cppMetadataView, +} from "./il2cppMetadataView.js"; + +type Il2cppMetadataViewInput = + | SummaryAnalysisView + | z.input; + +/** Check a caller selection against the closed request, then pass the admitted view. */ +const projectIl2cppMetadataView = ( + parent: Parameters[0], + view: Il2cppMetadataViewInput, +): ReturnType => + projectAdmittedIl2cppMetadataView(parent, view satisfies AdmittedView); afterEach(() => { vi.restoreAllMocks(); @@ -638,7 +654,15 @@ const genericLinked = (): Il2cppMetadata => { it("pages generic method instances by definition, state, address, name and field", () => { const source = parent(freezeJsonSnapshot(genericLinked()), true); - const view = (filters: Record) => { + const view = ( + filters: Omit< + Extract< + Il2cppMetadataViewInput, + { collection: "generic_method_instances" } + >, + "kind" | "collection" | "offset" | "limit" + >, + ) => { const result = projectIl2cppMetadataView(source, { kind: "il2cpp-metadata", collection: "generic_method_instances", @@ -649,7 +673,15 @@ it("pages generic method instances by definition, state, address, name and field if (!result.ok) throw result.error; return result.value; }; - const items = (filters: Record) => { + const items = ( + filters: Omit< + Extract< + Il2cppMetadataViewInput, + { collection: "generic_method_instances" } + >, + "kind" | "collection" | "offset" | "limit" + >, + ) => { const value = view(filters); return "items" in value ? value.items : undefined; }; diff --git a/src/domain/analysisView/il2cppMetadataView.ts b/src/domain/analysisView/il2cppMetadataView.ts index e62d2a4fd2..1d89c1c26a 100644 --- a/src/domain/analysisView/il2cppMetadataView.ts +++ b/src/domain/analysisView/il2cppMetadataView.ts @@ -25,11 +25,12 @@ import { } from "../il2cpp/il2cppMetadata.js"; import { err, ok, type Result } from "../result.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -519,9 +520,12 @@ const selection = (view: Request, report: Report) => { /** Reuse retained facts; source indices stay distinct from filtered page offsets. */ export const projectIl2cppMetadataView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "il2cpp-metadata") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "il2cpp-metadata"); + if (view === undefined) return err( analysisViewInputError([ { @@ -653,7 +657,7 @@ export const projectIl2cppMetadataView = ( }), }))(report.binary); return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -729,7 +733,7 @@ export const projectIl2cppMetadataView = ( } } return ok({ - kind: "il2cpp-metadata", + kind: "il2cpp-metadata" as const, view, ...shared, items, diff --git a/src/domain/analysisView/interfaceBuilderView.ts b/src/domain/analysisView/interfaceBuilderView.ts index 06e132f150..2d5a32757f 100644 --- a/src/domain/analysisView/interfaceBuilderView.ts +++ b/src/domain/analysisView/interfaceBuilderView.ts @@ -15,11 +15,12 @@ import { import { err, ok, type Result } from "../result.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { selectViewRows } from "./selectViewRows.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -183,9 +184,12 @@ const summarizeInterfaceBuilder = ( /** Project retained decode_interface_builder Evidence without reopening archives. */ export const projectInterfaceBuilderView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "interface-builder") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "interface-builder"); + if (view === undefined) return err( analysisViewInputError([ { @@ -230,7 +234,7 @@ export const projectInterfaceBuilderView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, ...summarizeInterfaceBuilder(report, limitations.length), @@ -262,7 +266,7 @@ export const projectInterfaceBuilderView = ( ? selectDocumentRows(graph.nodes, view, document) : selectDocumentRows(graph.edges, view, document); return ok({ - kind: "interface-builder", + kind: "interface-builder" as const, view, items: selected.rows, ...shared, diff --git a/src/domain/analysisView/javascriptApplicationView.ts b/src/domain/analysisView/javascriptApplicationView.ts index b63898d0b8..46872962ec 100644 --- a/src/domain/analysisView/javascriptApplicationView.ts +++ b/src/domain/analysisView/javascriptApplicationView.ts @@ -8,24 +8,31 @@ import { jsonObjectSchema, type JsonValue } from "../jsonValue.js"; import type { JavaScriptApplicationAnalysisResult } from "../javascript/javascriptApplicationAnalysis.js"; import type { ApplicationNode } from "../javascript/javascriptApplicationGraphSchemas.js"; import { err, ok, type Result } from "../result.js"; +import { z } from "zod"; import type { JavaScriptModuleReference } from "./javascriptModuleReferences.js"; +import { javascriptModuleReferencesRequestSchema } from "./javascriptModuleReferences.js"; import { javascriptApplicationSourceCoverage, javascriptStaticSourceCoverageSummary, type JavaScriptApplicationSourceCoverage, } from "./javascriptApplicationCoverage.js"; -import { projectJavaScriptFacts } from "./javascriptFactsView.js"; +import { + projectJavaScriptFacts, + javascriptFactsViewRequestSchema, +} from "./javascriptFactsView.js"; import { boundedViewMessages, completeWithinViewCoverage as completeCoverage, pageViewCoverage as pageCoverage, } from "./analysisViewCoverage.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, - GroupingViewKind, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type ItemAnalysisView, + type PageAnalysisView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; const OPERATION = "inspect_analysis_view"; @@ -96,9 +103,8 @@ const modulePage = ( view: { readonly offset: number; readonly limit: number; - readonly where?: Extract< - AnalysisViewRequest, - { kind: "javascript" } + readonly where?: z.output< + typeof javascriptModuleReferencesRequestSchema >["where"]; }, ): { entries: ModuleEntry[]; total: number } => { @@ -281,7 +287,7 @@ const parentFields = ( const selectModule = ( modules: readonly ModuleEntry[], - selector: Extract["selector"], + selector: ItemAnalysisView["selector"], ): Result => { if ("node_id" in selector) { const matches = modules.filter( @@ -342,8 +348,8 @@ const selectModule = ( export const projectJavaScriptApplicationView = ( parent: AnalysisViewParent, analysis: JavaScriptApplicationAnalysisResult, - view: Exclude, -): Result => { + view: AdmittedView, +) => { if ( view.kind !== "summary" && view.kind !== "item" && @@ -356,6 +362,13 @@ export const projectJavaScriptApplicationView = ( "JavaScript application Evidence supports summary, module item/page, typed module references or selected JavaScript facts.", ), ); + assertOwnedView< + | SummaryAnalysisView + | ItemAnalysisView + | PageAnalysisView + | z.output + | z.output + >(view, "summary", "item", "page", "javascript", "javascript-facts"); const sourceCoverage = javascriptApplicationSourceCoverage(analysis); const { fields: shared, limitationCount } = parentFields( parent, @@ -366,7 +379,7 @@ export const projectJavaScriptApplicationView = ( const { rows, total } = projectJavaScriptFacts(analysis.graph.nodes, view); return ok({ ...shared, - kind: "javascript-facts", + kind: "javascript-facts" as const, view, rows, source_coverage: sourceCoverage, @@ -378,7 +391,7 @@ export const projectJavaScriptApplicationView = ( const rows = entries.map(moduleReference); return ok({ ...shared, - kind: "javascript", + kind: "javascript" as const, view, rows, source_coverage: sourceCoverage, @@ -393,7 +406,7 @@ export const projectJavaScriptApplicationView = ( 0, ); return ok({ - kind: "summary", + kind: "summary" as const, view, summary: { input_path: analysis.input_path, @@ -438,7 +451,7 @@ export const projectJavaScriptApplicationView = ( const selected = selectModule(modules, view.selector); if (!selected.ok) return selected; return ok({ - kind: "item", + kind: "item" as const, view, item: moduleItem(selected.value.node, selected.value.path), coverage: completeCoverage(1, modules.length), @@ -458,7 +471,7 @@ export const projectJavaScriptApplicationView = ( path, })); return ok({ - kind: "page", + kind: "page" as const, view, items, coverage: pageCoverage(view.offset, items.length, total), diff --git a/src/domain/analysisView/javascriptRoutesView.ts b/src/domain/analysisView/javascriptRoutesView.ts index cabb87dd7c..f28569c133 100644 --- a/src/domain/analysisView/javascriptRoutesView.ts +++ b/src/domain/analysisView/javascriptRoutesView.ts @@ -21,11 +21,8 @@ import { type JavaScriptRouteInventorySource, } from "../javascript/javascriptRouteInventory.js"; import { javaScriptRouteMechanismSchema } from "../javascript/javascriptRouteFacts.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { assertOwnedView, type AdmittedView } from "./analysisViewShape.js"; import { ANALYSIS_VIEW_PAGE_BUDGET_RECOVERY, analysisViewInputError, @@ -319,10 +316,14 @@ const captureIdentity = z.object({ /** Historical projection: no source file reads, browser connection or reanalysis. */ export const projectJavaScriptRoutesView = ( parent: AnalysisViewParent, - selected: AnalysisViewRequest, -): Result => { + selected: AdmittedView, +) => { if (selected.kind !== "javascript-routes") return err(inputError("Select a javascript-routes view.")); + assertOwnedView>( + selected, + "javascript-routes", + ); const operation = parent.operation; if ( operation !== "analyze_javascript_application" && @@ -452,7 +453,7 @@ export const projectJavaScriptRoutesView = ( item: Record; sources: readonly string[]; }, - ): Result => { + ) => { const rows = candidates(source, ids).filter(predicate), items: Record[] = [], refs = new Map(); diff --git a/src/domain/analysisView/machoView.ts b/src/domain/analysisView/machoView.ts index ef8d382530..6c471e5880 100644 --- a/src/domain/analysisView/machoView.ts +++ b/src/domain/analysisView/machoView.ts @@ -9,11 +9,12 @@ import { } from "../native/nativeInspection.js"; import { err, ok, type Result } from "../result.js"; import { parseAnalysisViewResult } from "./analysisViewParent.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -155,9 +156,12 @@ const summarizeMacho = ( /** Project retained inspect_macho Evidence without rerunning native tools. */ export const projectMachoView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "macho") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "macho"); + if (view === undefined) return err( analysisViewInputError([ { @@ -203,7 +207,7 @@ export const projectMachoView = ( parent.limitations, ); return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, limitations, diff --git a/src/domain/analysisView/managedArtifactView.ts b/src/domain/analysisView/managedArtifactView.ts index 0e64e4c30d..5dcb92b1d5 100644 --- a/src/domain/analysisView/managedArtifactView.ts +++ b/src/domain/analysisView/managedArtifactView.ts @@ -1,18 +1,18 @@ import { analysisViewInputError } from "./analysisViewErrors.js"; import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { uniqueSorted } from "../canonicalOrdering.js"; import { managedArtifactInspectionSchema, managedMemberInspectionSchema, } from "../managed/managedArtifact.js"; -import { err, ok, type Result } from "../result.js"; +import { err, ok } from "../result.js"; import { parseAnalysisViewResult } from "./analysisViewParent.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -72,9 +72,12 @@ export const managedViewIdentityUnknowns = ( /** Project authenticated metadata without reading a path or invoking a provider. */ export const projectManagedArtifactView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "managed") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "managed"); + if (view === undefined) return err( analysisViewInputError([ { @@ -116,7 +119,7 @@ export const projectManagedArtifactView = ( }; const total = references.length + resources.length + attributes.length; return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { ...summary, reported_counts, identity_scope }, @@ -126,7 +129,7 @@ export const projectManagedArtifactView = ( const collection = report[view.collection]; const item = collection.slice(view.offset, view.offset + view.limit); return ok({ - kind: "managed", + kind: "managed" as const, view, item, ...shared, diff --git a/src/domain/analysisView/managedMemberView.test.ts b/src/domain/analysisView/managedMemberView.test.ts index 7bafab84a8..e6d8f401f4 100644 --- a/src/domain/analysisView/managedMemberView.test.ts +++ b/src/domain/analysisView/managedMemberView.test.ts @@ -107,7 +107,7 @@ it("intersects exact filters before paging and preserves identity while omitting request, ); if (!result.ok) throw result.error; - if (result.value.kind !== "managed-members") throw new Error("Wrong view"); + if (!("page" in result.value)) throw new Error("Wrong view"); expect(result.value.page).toEqual({ collection: "methods", source_count: 4, @@ -161,7 +161,7 @@ it("keeps unresolved exact-filter candidates unknown under complete and partial }), ); if (!result.ok) throw result.error; - if (result.value.kind !== "managed-members") throw new Error("Wrong view"); + if (!("page" in result.value)) throw new Error("Wrong view"); expect(result.value).toMatchObject({ source_coverage: { state }, coverage: { total: 1 }, @@ -220,7 +220,7 @@ it("distinguishes empty selectors from omitted selectors and pages projections w expect(full.value).toMatchObject({ page: { collection: "methods", rows: report.methods.slice(1, 3) }, }); - if (full.value.kind !== "managed-members") throw new Error("Wrong view"); + if (!("page" in full.value)) throw new Error("Wrong view"); expect(full.value.page.rows).toEqual(report.methods.slice(1, 3)); }); diff --git a/src/domain/analysisView/managedMemberView.ts b/src/domain/analysisView/managedMemberView.ts index 1888c9afa5..f11c4b04b0 100644 --- a/src/domain/analysisView/managedMemberView.ts +++ b/src/domain/analysisView/managedMemberView.ts @@ -1,20 +1,22 @@ import { analysisViewInputError } from "./analysisViewErrors.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { uniqueSorted } from "../canonicalOrdering.js"; import { managedMemberInspectionSchema, type ManagedMemberInspection, } from "../managed/managedArtifact.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, } from "./analysisViewCoverage.js"; +import { z } from "zod"; +import { managedMembersViewRequestSchema } from "./managedMemberViewSchemas.js"; import { managedViewIdentityUnknowns } from "./managedArtifactView.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; @@ -275,8 +277,8 @@ const summarizeMembers = ( /** Project authenticated member Evidence without reading a path or invoking a provider. */ export const projectManagedMemberView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "summary" && view.kind !== "managed-members") return err( analysisViewInputError([ @@ -288,6 +290,9 @@ export const projectManagedMemberView = ( }, ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "managed-members"); const parsed = parseMemberReport(parent); if (!parsed.ok) return parsed; const report = parsed.value; @@ -317,7 +322,7 @@ export const projectManagedMemberView = ( 0, ); return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary, @@ -345,7 +350,7 @@ export const projectManagedMemberView = ( `${page.unresolved_filter_rows} source rows have unknown requested names or declaring types and may match the filters; the matched total excludes them.`, ); return ok({ - kind: "managed-members", + kind: "managed-members" as const, view, page, ...shared, diff --git a/src/domain/analysisView/modelArtifactView.ts b/src/domain/analysisView/modelArtifactView.ts index e71d6a9815..9ddb513059 100644 --- a/src/domain/analysisView/modelArtifactView.ts +++ b/src/domain/analysisView/modelArtifactView.ts @@ -1,4 +1,7 @@ -import { modelTypeRowSchema } from "../model/modelArtifactQuery.js"; +import { + modelArtifactViewRequestSchema, + modelTypeRowSchema, +} from "../model/modelArtifactQuery.js"; import { z } from "zod"; import { modelArtifactSchema, @@ -14,11 +17,12 @@ import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { isImmutableJsonSnapshot } from "../immutableJson.js"; import type { JsonValue } from "../jsonValue.js"; import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, boundedViewMessages, @@ -180,8 +184,8 @@ const read = (parent: AnalysisViewParent): Result => { /** Historical pages never reopen weights or report a scoped header digest as full-file identity. */ export const projectModelArtifactView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "summary" && view.kind !== "model-artifact") return err( analysisViewInputError([ @@ -193,6 +197,9 @@ export const projectModelArtifactView = ( }, ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "model-artifact"); const parsed = read(parent); if (!parsed.ok) return parsed; const { @@ -225,7 +232,7 @@ export const projectModelArtifactView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -318,7 +325,7 @@ export const projectModelArtifactView = ( return result; }); return ok({ - kind: "model-artifact", + kind: "model-artifact" as const, view, ...shared, source: report.artifact, diff --git a/src/domain/analysisView/nativeExportsView.ts b/src/domain/analysisView/nativeExportsView.ts index d0d8d1ee97..1d9be08030 100644 --- a/src/domain/analysisView/nativeExportsView.ts +++ b/src/domain/analysisView/nativeExportsView.ts @@ -5,13 +5,13 @@ import { elfNativeExportsSchema as elf, type NativeExports, } from "../native/nativeExports.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { @@ -88,8 +88,8 @@ const readReport = createAnalysisViewResultReader(nativeExportsSchema); /** Read selected export facts without reopening the artifact or reinterpreting its tables. */ export const projectNativeExportsView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { const invalid = (message: string) => err( analysisViewInputError([ @@ -100,6 +100,9 @@ export const projectNativeExportsView = ( return invalid( "Native export Evidence supports summary and native-exports views.", ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "native-exports"); const parsed = readReport(parent); if (!parsed.ok) return parsed; const report = parsed.value; @@ -131,7 +134,7 @@ export const projectNativeExportsView = ( if (view.kind === "summary") return ok({ ...shared, - kind: "summary", + kind: "summary" as const, view, summary, coverage: completeWithinViewCoverage(exports.length, exports.length), @@ -158,7 +161,7 @@ export const projectNativeExportsView = ( ); return ok({ ...shared, - kind: "native-exports", + kind: "native-exports" as const, view, exports: summary, items: selected.rows, @@ -246,7 +249,7 @@ export const projectNativeExportsView = ( ); return ok({ ...shared, - kind: "native-exports", + kind: "native-exports" as const, view, exports: summary, items: selected.rows, diff --git a/src/domain/analysisView/nativeFunctionMatchingView.ts b/src/domain/analysisView/nativeFunctionMatchingView.ts index e6870322aa..4d5d8cfe3d 100644 --- a/src/domain/analysisView/nativeFunctionMatchingView.ts +++ b/src/domain/analysisView/nativeFunctionMatchingView.ts @@ -16,11 +16,12 @@ import { } from "./analysisViewCoverage.js"; import { err, ok, type Result } from "../result.js"; import type { AnalysisError } from "../analysisErrorBase.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import type { JsonValue } from "../jsonValue.js"; const matchRow = nativeFunctionMatchSchema.extend({ @@ -259,9 +260,13 @@ const selectedItems = ( /** Query immutable matching facts without copying full alias groups into selected pages. */ export const projectNativeFunctionMatchingView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "function-matches") + admitted: AdmittedView, +) => { + const view = ownedView< + | SummaryAnalysisView + | z.output + >(admitted, "summary", "function-matches"); + if (view === undefined) return err( analysisViewInputError([ { @@ -283,7 +288,7 @@ export const projectNativeFunctionMatchingView = ( const shared = sharedContext(parent, entry.report); if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: context, @@ -292,7 +297,7 @@ export const projectNativeFunctionMatchingView = ( const rows = filterRows(entry, view), items = selectedItems(entry, view, rows); return ok({ - kind: "function-matches", + kind: "function-matches" as const, view, ...shared, ...context, diff --git a/src/domain/analysisView/nativeFunctionView.ts b/src/domain/analysisView/nativeFunctionView.ts index dea093806e..8ce34ee53f 100644 --- a/src/domain/analysisView/nativeFunctionView.ts +++ b/src/domain/analysisView/nativeFunctionView.ts @@ -4,12 +4,14 @@ import type { AnalysisError } from "../analysisErrorBase.js"; import { uniqueSorted } from "../canonicalOrdering.js"; import type { FunctionDossier } from "../native/functionDossier.js"; import { jsonValueSchema } from "../jsonValue.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type NativeFacetAnalysisView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -62,7 +64,7 @@ const parentFields = ( const nativeRows = ( dossier: FunctionDossier, facet: Exclude< - Extract["facet"], + NativeFacetAnalysisView["facet"], "procedure" | "pseudocode" | "native_api" | "value_flow_summary" >, ): readonly unknown[] | undefined => { @@ -196,11 +198,11 @@ const summarizeDossier = (dossier: FunctionDossier) => { }; const summaryView = ( - view: Extract, + view: SummaryAnalysisView, dossier: FunctionDossier, common: ReturnType, -): UnsignedAnalysisView => ({ - kind: "summary", +) => ({ + kind: "summary" as const, view, summary: summarizeDossier(dossier), coverage: completeWithinViewCoverage(1, 1), @@ -216,12 +218,17 @@ const summaryView = ( export const projectNativeFunctionView = ( parent: AnalysisViewParent, dossier: FunctionDossier, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "native" && view.kind !== "summary") return err( viewError("analyze_function Evidence requires a native or summary view."), ); + assertOwnedView( + view, + "summary", + "native", + ); const artifact = parent.artifact; if (!artifact) return err( @@ -239,8 +246,8 @@ export const projectNativeFunctionView = ( const availability = facetAvailability(dossier, view.facet); if (availability?.available === false) common.unknowns = uniqueSorted([...common.unknowns, availability.reason]); - const singleton = (item: unknown): UnsignedAnalysisView => ({ - kind: "native", + const singleton = (item: unknown) => ({ + kind: "native" as const, view, item: jsonValueSchema.parse(item), coverage: completeWithinViewCoverage(1, 1), @@ -286,7 +293,7 @@ export const projectNativeFunctionView = ( if (view.facet === "pseudocode") { const page = analysisTextPage(dossier.pseudocode, view.offset, view.limit); return page.ok - ? ok({ kind: "native", view, ...page.value, ...common }) + ? ok({ kind: "native" as const, view, ...page.value, ...common }) : page; } const rows = nativeRows(dossier, view.facet); @@ -305,7 +312,7 @@ export const projectNativeFunctionView = ( ); const items = rows.slice(view.offset, view.offset + view.limit); return ok({ - kind: "native", + kind: "native" as const, view, item: jsonValueSchema.parse(items), coverage: pageViewCoverage(view.offset, items.length, rows.length), diff --git a/src/domain/analysisView/nativeInventoryView.ts b/src/domain/analysisView/nativeInventoryView.ts index 2ef5dedccc..01c22de8c0 100644 --- a/src/domain/analysisView/nativeInventoryView.ts +++ b/src/domain/analysisView/nativeInventoryView.ts @@ -6,13 +6,13 @@ import { isNativeInventoryOperation, nativeInventoryRowsSchemas, } from "../native/nativeInventory.js"; -import { err, ok, type Result } from "../result.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { @@ -68,8 +68,8 @@ const readStrings = createAnalysisViewResultReader( /** Project already completed provider observations without another provider read or sort. */ export const projectNativeInventoryView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if ( !isNativeInventoryOperation(parent.operation) || (view.kind !== "summary" && view.kind !== "native-inventory") @@ -84,6 +84,9 @@ export const projectNativeInventoryView = ( }, ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "native-inventory"); const strings = parent.operation === "list_strings" || parent.operation === "search_strings"; @@ -113,16 +116,16 @@ export const projectNativeInventoryView = ( if (view.kind === "summary") return ok({ ...shared, - kind: "summary", + kind: "summary" as const, view, summary: { collection: strings - ? "strings" + ? ("strings" as const) : parent.operation === "list_names" - ? "names" - : "procedures", + ? ("names" as const) + : ("procedures" as const), row_count: rows.length, - discovery_coverage: "unknown", + discovery_coverage: "unknown" as const, selectable_fields: fieldSchema.options, }, coverage: completeWithinViewCoverage(rows.length, rows.length), @@ -137,7 +140,7 @@ export const projectNativeInventoryView = ( const selected = rows.slice(view.offset, view.offset + view.limit); return ok({ ...shared, - kind: "native-inventory", + kind: "native-inventory" as const, view, rows: selected.map((record, index) => ({ source_index: view.offset + index, diff --git a/src/domain/analysisView/nativeLoadImageView.ts b/src/domain/analysisView/nativeLoadImageView.ts index c8908989de..c4975e00dc 100644 --- a/src/domain/analysisView/nativeLoadImageView.ts +++ b/src/domain/analysisView/nativeLoadImageView.ts @@ -10,13 +10,13 @@ import { } from "../native/nativeLoadImage.js"; import { nativeAddressObservationSchema } from "../native/nativeAddress.js"; import { jsonValueSchema } from "../jsonValue.js"; -import { err, ok, type Result } from "../result.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { @@ -199,9 +199,12 @@ const selectRows = (source: readonly (Row | string)[], view: PageRequest) => { /** Query the owner's parsed historical observations without reopening the target. */ export const projectNativeLoadImageView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "native-load-image") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "native-load-image"); + if (view === undefined) return err( analysisViewInputError([ { @@ -257,7 +260,7 @@ export const projectNativeLoadImageView = ( if (view.kind === "summary") return ok({ ...shared, - kind: "summary", + kind: "summary" as const, view, summary: { verification: smallVerification, @@ -289,7 +292,7 @@ export const projectNativeLoadImageView = ( const page = selectRows(selected ?? [], view); return ok({ ...shared, - kind: "native-load-image", + kind: "native-load-image" as const, verification_status: report.status, view, items: nativeLoadImageViewItemsSchema.parse({ diff --git a/src/domain/analysisView/nativeObservationView.ts b/src/domain/analysisView/nativeObservationView.ts index a8c9d85ceb..a532242c2d 100644 --- a/src/domain/analysisView/nativeObservationView.ts +++ b/src/domain/analysisView/nativeObservationView.ts @@ -1,4 +1,5 @@ import type { AnalysisError } from "../analysisErrorBase.js"; +import { z } from "zod"; import { evidenceSubjectIdentity } from "../evidence.js"; import { digestCanonicalValue } from "../canonicalDigest.js"; import { jsonValueSchema } from "../jsonValue.js"; @@ -9,11 +10,12 @@ import { nativeObservationSourceSchemas, type NativeObservation, } from "../native/nativeObservation.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { @@ -21,6 +23,8 @@ import { completeWithinViewCoverage, } from "./analysisViewCoverage.js"; import { + nativeContextViewRequestSchema, + nativeObservationViewRequestSchema, nativeSourceContextSchema, type NativeSourceContext, } from "./nativeObservationSchemas.js"; @@ -166,7 +170,7 @@ const observationRows = ( }; const contextRows = ( source: NativeSourceContext, - view: Extract, + view: z.output, ) => { switch (view.facet) { case "overview": { @@ -245,8 +249,8 @@ const contextRows = ( /** Select recorded native facts without repeating provider profiles or complete caveat inventories. */ export const projectNativeObservationView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if ( view.kind !== "summary" && view.kind !== "native-observation" && @@ -262,6 +266,11 @@ export const projectNativeObservationView = ( }, ]), ); + assertOwnedView< + | SummaryAnalysisView + | z.output + | z.output + >(view, "summary", "native-observation", "native-context"); const source = readSource(parent); if (!source.ok) return source; const context = readContext(parent, source.value); @@ -296,7 +305,7 @@ export const projectNativeObservationView = ( const { total, ...page } = contextRows(context.value, view); return ok({ ...common, - kind: "native-context", + kind: "native-context" as const, ...page, parent_operation: source.value.operation, coverage: @@ -321,6 +330,6 @@ export const projectNativeObservationView = ( coverage: pageViewCoverage(selection.offset, page.items.rows.length, total), }; return view.kind === "summary" - ? ok({ ...observation, kind: "summary", view }) - : ok({ ...observation, kind: "native-observation", view }); + ? ok({ ...observation, kind: "summary" as const, view }) + : ok({ ...observation, kind: "native-observation" as const, view }); }; diff --git a/src/domain/analysisView/pcapCaptureView.ts b/src/domain/analysisView/pcapCaptureView.ts index 5ca03a1875..cc7f05b9b7 100644 --- a/src/domain/analysisView/pcapCaptureView.ts +++ b/src/domain/analysisView/pcapCaptureView.ts @@ -4,11 +4,12 @@ import { pcapEvidenceSchemas } from "../pcap/pcapAnalysis.js"; import { parseAnalysisViewResult } from "./analysisViewParent.js"; import type { AnalysisError } from "../analysisErrorBase.js"; import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -253,9 +254,12 @@ const selectRows = ( /** Historical packet facts are paged without reopening the source or rerunning Wireshark. */ export const projectPcapCaptureView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "pcap") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "pcap"); + if (view === undefined) return err( analysisViewInputError([ { @@ -284,7 +288,7 @@ export const projectPcapCaptureView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: summarize(capture), @@ -303,14 +307,15 @@ export const projectPcapCaptureView = ( ); if (!text.ok) return text; return ok({ - kind: "pcap", + kind: "pcap" as const, view, ...shared, source_coverage: capture.coverage, page: { - facet: "diagnostics", + facet: "diagnostics" as const, text: text.value.item.text, - status: value === undefined ? "unknown" : "retained", + status: + value === undefined ? ("unknown" as const) : ("retained" as const), }, coverage: text.value.coverage, unknowns: @@ -325,7 +330,7 @@ export const projectPcapCaptureView = ( const selected = selectRows(capture, view); return selected.ok ? ok({ - kind: "pcap", + kind: "pcap" as const, view, ...shared, source_coverage: capture.coverage, diff --git a/src/domain/analysisView/pythonPycView.ts b/src/domain/analysisView/pythonPycView.ts index 1cd0381c08..8676db842e 100644 --- a/src/domain/analysisView/pythonPycView.ts +++ b/src/domain/analysisView/pythonPycView.ts @@ -3,13 +3,13 @@ import { pythonPycSchema, type PythonPycCodeObject, } from "../python/pythonPyc.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { @@ -62,9 +62,12 @@ const readReport = createAnalysisViewResultReader(pythonPycSchema); /** Project code-constant references from historical facts, without reopening the pyc. */ export const projectPythonPycView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "python-pyc") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "python-pyc"); + if (view === undefined) return err( analysisViewInputError([ { @@ -96,7 +99,7 @@ export const projectPythonPycView = ( if (view.kind === "summary") return ok({ ...shared, - kind: "summary", + kind: "summary" as const, view, summary, coverage: completeWithinViewCoverage( @@ -132,7 +135,7 @@ export const projectPythonPycView = ( ); return ok({ ...shared, - kind: "python-pyc", + kind: "python-pyc" as const, view, pyc: summary, items: selected.rows, diff --git a/src/domain/analysisView/rustBinaryView.ts b/src/domain/analysisView/rustBinaryView.ts index 5354e2441e..027d17eeda 100644 --- a/src/domain/analysisView/rustBinaryView.ts +++ b/src/domain/analysisView/rustBinaryView.ts @@ -1,26 +1,29 @@ import { binaryMetadataArchitecture } from "../binaryMetadataArchitecture.js"; import { metadataReportSubjectFormat } from "../apple/machoTargetSelection.js"; import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { rustBinarySchema, rustAuditableMetadataSchema, rustcCommitSchema, type RustBinary, } from "../rust/rustBinary.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import { + createAnalysisViewResultReader, + type AnalysisViewParent, +} from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; +import { rustBinaryViewRequestSchema } from "../rust/rustBinaryQuery.js"; import { boundedViewMessages, completeWithinViewCoverage, pageViewCoverage, } from "./analysisViewCoverage.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; -import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { selectViewRows } from "./selectViewRows.js"; const count = z.number().int().nonnegative(); @@ -108,8 +111,8 @@ const summarize = ( /** Query owner-normalized facts without reopening a source or walking dependency paths. */ export const projectRustBinaryView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "summary" && view.kind !== "rust") return err( analysisViewInputError([ @@ -120,6 +123,9 @@ export const projectRustBinaryView = ( }, ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "rust"); const parsed = parseReport(parent); if (!parsed.ok) return parsed; const report = parsed.value; @@ -177,7 +183,7 @@ export const projectRustBinaryView = ( const summary = summarize(report); if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary, @@ -214,11 +220,11 @@ export const projectRustBinaryView = ( }), ); return ok({ - kind: "rust", + kind: "rust" as const, view, ...shared, rust: summary, - page: { collection: "packages", rows: selected.rows }, + page: { collection: "packages" as const, rows: selected.rows }, coverage: pageViewCoverage( view.offset, selected.rows.length, @@ -246,11 +252,11 @@ export const projectRustBinaryView = ( }), ); return ok({ - kind: "rust", + kind: "rust" as const, view, ...shared, rust: summary, - page: { collection: "edges", rows: selected.rows }, + page: { collection: "edges" as const, rows: selected.rows }, coverage: pageViewCoverage( view.offset, selected.rows.length, diff --git a/src/domain/analysisView/scenarioCaptureRecords.ts b/src/domain/analysisView/scenarioCaptureRecords.ts index f43d8fedd0..59e7294293 100644 --- a/src/domain/analysisView/scenarioCaptureRecords.ts +++ b/src/domain/analysisView/scenarioCaptureRecords.ts @@ -17,7 +17,7 @@ import type { JsonValue } from "../jsonValue.js"; import { err, ok, type Result } from "../result.js"; import type { WebNetworkCaptureRecord } from "../webNetworkCapture.js"; import { analysisViewResultInputError } from "./analysisViewParent.js"; -import type { AnalysisViewParent } from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; import type { WebNetworkProjectionAccumulator } from "./WebNetworkProjectionAccumulator.js"; import { ENTRY_BYTES, textBytes } from "./webNetworkRouteTemplates.js"; diff --git a/src/domain/analysisView/sourceToBundleView.ts b/src/domain/analysisView/sourceToBundleView.ts index 38a2f616b5..9443b52b67 100644 --- a/src/domain/analysisView/sourceToBundleView.ts +++ b/src/domain/analysisView/sourceToBundleView.ts @@ -4,13 +4,13 @@ import { sourceToBundleComparisonResultSchema, type SourceToBundleComparisonResult, } from "../javascript/sourceToBundleComparisonSchemas.js"; -import { err, ok, type Result } from "../result.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { @@ -109,9 +109,12 @@ const columns = ( /** Page facts owned by a complete comparison; page exhaustion does not upgrade source coverage. */ export const projectSourceToBundleView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "source-to-bundle") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "source-to-bundle"); + if (view === undefined) return err( analysisViewInputError([ { @@ -153,7 +156,7 @@ export const projectSourceToBundleView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: context, @@ -234,7 +237,7 @@ export const projectSourceToBundleView = ( } } return ok({ - kind: "source-to-bundle", + kind: "source-to-bundle" as const, view, ...shared, ...context, diff --git a/src/domain/analysisView/wasmArtifactView.ts b/src/domain/analysisView/wasmArtifactView.ts index de6b65fb31..4d16729658 100644 --- a/src/domain/analysisView/wasmArtifactView.ts +++ b/src/domain/analysisView/wasmArtifactView.ts @@ -1,18 +1,18 @@ import { analysisViewInputError } from "./analysisViewErrors.js"; import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { uniqueSorted } from "../canonicalOrdering.js"; -import { err, ok, type Result } from "../result.js"; +import { err, ok } from "../result.js"; import { parseAnalysisViewResult } from "./analysisViewParent.js"; import { wasmArtifactSchema, wasmArtifactMatchesSubject, } from "../wasm/wasmArtifact.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -74,9 +74,12 @@ export const wasmSummarySchema = z.strictObject({ /** Read the exact retained WABT forms with source identity and explicit uncertainty. */ export const projectWasmArtifactView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "wasm") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "wasm"); + if (view === undefined) return err( analysisViewInputError([ { @@ -131,7 +134,7 @@ export const projectWasmArtifactView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -173,7 +176,7 @@ export const projectWasmArtifactView = ( ]), ); return ok({ - kind: "wasm", + kind: "wasm" as const, view, item: report.tool_profile, coverage: completeWithinViewCoverage(1, 1), @@ -188,13 +191,13 @@ export const projectWasmArtifactView = ( const text = view.facet === "wat" ? report.wat.text : report[view.facet]; const page = analysisTextPage(text, view.offset, view.limit, view.facet); return page.ok - ? ok({ kind: "wasm", view, ...page.value, ...shared }) + ? ok({ kind: "wasm" as const, view, ...page.value, ...shared }) : page; } const rows = report[view.facet]; const item = rows.slice(view.offset, view.offset + view.limit); return ok({ - kind: "wasm", + kind: "wasm" as const, view, item, coverage: pageViewCoverage(view.offset, item.length, rows.length), diff --git a/src/domain/analysisView/webBundleView.ts b/src/domain/analysisView/webBundleView.ts index 75b55fe6f2..fadf8b78e5 100644 --- a/src/domain/analysisView/webBundleView.ts +++ b/src/domain/analysisView/webBundleView.ts @@ -9,11 +9,12 @@ import { type WebBundleAnalysis, } from "../webBundleAnalysis.js"; import { recordedBrowserOriginSchema } from "../browserObservation.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { boundedViewMessages, completeWithinViewCoverage, @@ -119,8 +120,8 @@ const choose = ( /** Historical projection of completed analyze_web_bundle Evidence. */ export const projectWebBundleView = ( parent: AnalysisViewParent, - selected: AnalysisViewRequest, -): Result => { + selected: AdmittedView, +) => { if (selected.kind !== "web-bundle" && selected.kind !== "summary") return err( analysisViewInputError([ @@ -132,6 +133,9 @@ export const projectWebBundleView = ( ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(selected, "summary", "web-bundle"); if (parent.operation !== "analyze_web_bundle") return err( analysisViewInputError([ @@ -216,8 +220,8 @@ export const projectWebBundleView = ( if (selected.kind === "summary") { const summary = buildSummary(); - const result: UnsignedAnalysisView = { - kind: "summary", + const result = { + kind: "summary" as const, view: selected, ...shared, summary, @@ -234,8 +238,8 @@ export const projectWebBundleView = ( const view = selected; if (view.collection === "summary") { const summary = buildSummary(); - const result: UnsignedAnalysisView = { - kind: "web-bundle", + const result = { + kind: "web-bundle" as const, view, ...shared, completeness: report.completeness, @@ -261,7 +265,7 @@ export const projectWebBundleView = ( rows: readonly T[], matches: ((row: T, source_index: number) => boolean) | undefined, project: (row: T, source_index: number) => Item, - ): Result => { + ) => { const baseEnvelope = { ...shared, kind: "web-bundle" as const, @@ -323,7 +327,7 @@ export const projectWebBundleView = ( } const coverage = pageViewCoverage(view.offset, items.length, total); - const result: UnsignedAnalysisView = { + const result = { ...shared, kind: "web-bundle" as const, view, diff --git a/src/domain/analysisView/webNetworkApiSurfaceView.ts b/src/domain/analysisView/webNetworkApiSurfaceView.ts index 40da068fa3..d1bd0224c7 100644 --- a/src/domain/analysisView/webNetworkApiSurfaceView.ts +++ b/src/domain/analysisView/webNetworkApiSurfaceView.ts @@ -1,96 +1,39 @@ import { z } from "zod"; import { AnalysisUnsupportedTargetError } from "../analysisErrorCore.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + ownedView, + type AdmittedView, +} from "./analysisViewShape.js"; import { WebNetworkApiSurfaceAccumulator } from "./WebNetworkApiSurfaceAccumulator.js"; import { admitHarCaptureParent } from "./WebNetworkProjectionAccumulator.js"; -import { ROUTE_RULES } from "./webNetworkRouteTemplates.js"; -export const apiSurfaceViewSchema = z.strictObject({ - kind: z.literal("api-surface"), - offset: z.int().nonnegative().default(0), - limit: z.int().positive().default(50), - include_query_parameter_names: z - .boolean() - .optional() - .describe( - "Include distinct observed query parameter names and their original record ordinals; names do not establish required parameters or a complete API schema.", - ), -}); -const ruleSchema = z.enum(ROUTE_RULES); -const groupSchema = z.strictObject({ - method: z.string(), - origin: z.string(), - path_template: z.string(), - templated_segments: z.array( - z.strictObject({ - segment_index: z.int().nonnegative(), - rule: ruleSchema, - basis: z.literal("inferred"), - observed_values: z.array(z.string()), - }), - ), - record_ordinals: z.array(z.int().nonnegative()), - statuses: z.array(z.number()), - content_types: z.array(z.string()), - query_parameter_names: z - .array( - z.strictObject({ - name: z.string(), - record_ordinals: z.array(z.int().nonnegative()), - }), - ) - .optional(), - flags: z.array( - z.enum(["single-sample", "mixed-statuses", "mixed-content-types"]), - ), -}); -export const apiSurfaceFields = { - records: z.strictObject({ - examined: z.int().nonnegative(), - total: z.int().nonnegative(), - excluded: z.int().nonnegative(), - }), - templated_groups: z - .int() - .nonnegative() - .describe( - "Groups across every page that carry at least one templated segment.", - ), - groups: z.array(groupSchema), - excluded_records: z.array( - z.strictObject({ - ordinal: z.int().nonnegative(), - reason: z.enum([ - "url-redacted", - "url-unparseable", - "request-unavailable", - "method-unavailable", - ]), - }), - ), -}; +import { apiSurfaceFields, apiSurfaceViewSchema } from "./apiSurfaceSchema.js"; + +export { apiSurfaceFields, apiSurfaceViewSchema }; /** Create the budget and query-name policy shared by admission and projection. */ export const createApiSurfaceAccumulator = ( - view: AnalysisViewRequest, -): WebNetworkApiSurfaceAccumulator => - new WebNetworkApiSurfaceAccumulator( - undefined, - view.kind === "api-surface" && view.include_query_parameter_names === true, + view: AdmittedView, +): WebNetworkApiSurfaceAccumulator => { + const selected = ownedView>( + view, + "api-surface", ); + return new WebNetworkApiSurfaceAccumulator( + undefined, + selected?.include_query_parameter_names === true, + ); +}; /** Group retained HAR request lines; format matches do not establish handler identity. */ export const projectWebNetworkApiSurfaceView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, + view: AdmittedView, accumulator = createApiSurfaceAccumulator(view), -): Result => { +) => { if (view.kind !== "api-surface") return err( new AnalysisUnsupportedTargetError( @@ -99,6 +42,7 @@ export const projectWebNetworkApiSurfaceView = ( `View ${view.kind} is unsupported for parent operation ${parent.operation}; api-surface requires inspect_web_network_capture.`, ), ); + assertOwnedView>(view, "api-surface"); const admitted = admitHarCaptureParent(parent, "api-surface", accumulator); if (!admitted.ok) return admitted; const capture = admitted.value; @@ -124,10 +68,10 @@ export const projectWebNetworkApiSurfaceView = ( } const page = accumulator.page(view.offset, view.limit); return ok({ - kind: "api-surface", + kind: "api-surface" as const, view, parent_evidence_id: parent.evidenceId, - parent_operation: "inspect_web_network_capture", + parent_operation: "inspect_web_network_capture" as const, parent_digest: parent.evidenceId.slice(3), artifact: { path: capture.artifact.path, sha256: capture.artifact.sha256 }, records: { diff --git a/src/domain/analysisView/webNetworkCaptureView.ts b/src/domain/analysisView/webNetworkCaptureView.ts index 90555e317e..83c737ea9b 100644 --- a/src/domain/analysisView/webNetworkCaptureView.ts +++ b/src/domain/analysisView/webNetworkCaptureView.ts @@ -1,4 +1,7 @@ -import { projectProtobufCapturePage } from "./protobufCaptureView.js"; +import { + projectProtobufCapturePage, + protobufViewRequestSchema, +} from "./protobufCaptureView.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createHash } from "node:crypto"; import { z } from "zod"; @@ -17,17 +20,19 @@ import { type WebNetworkCaptureRecord, type WebNetworkCapture, } from "../webNetworkCapture.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, } from "./analysisViewCoverage.js"; import { qlogSummarySchema, + qlogViewRequestSchema, summarizeQlogCapture, projectQlogCapturePage, } from "./qlogCaptureView.js"; @@ -468,8 +473,8 @@ const parseCaptureParent = ( /** Page immutable retained facts; no capture file, provider or network is consulted. */ export const projectWebNetworkCaptureView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if ( view.kind !== "summary" && view.kind !== "capture" && @@ -486,6 +491,12 @@ export const projectWebNetworkCaptureView = ( }, ]), ); + assertOwnedView< + | SummaryAnalysisView + | z.output + | z.output + | z.output + >(view, "summary", "capture", "protobuf", "qlog"); const parsed = parseCaptureParent(parent); if (!parsed.ok) return parsed; const report = parsed.value; @@ -519,7 +530,7 @@ export const projectWebNetworkCaptureView = ( }); if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -558,7 +569,7 @@ export const projectWebNetworkCaptureView = ( const projected = projectQlogCapturePage(report.qlog, view); return projected.ok ? ok({ - kind: "qlog", + kind: "qlog" as const, view, ...shared, ...projected.value, @@ -571,7 +582,7 @@ export const projectWebNetworkCaptureView = ( } const records = report.records.slice(view.offset, view.offset + view.limit); return ok({ - kind: "capture", + kind: "capture" as const, view, ...shared, items: captureViewItemsSchema.parse(