rea-agents 2.0.0 → 2.1.0

package/dist/domain/managedApplicationGraph.js

@@ -1,10 +1,11 @@
 import { createHash } from "node:crypto";
-import { basename } from "node:path";
 import canonicalize from "canonicalize";
 import { z } from "zod";
 import { evidenceSchema, parseEvidence } from "./evidence.js";
-import { createJavaScriptApplicationEdge, createJavaScriptApplicationGraph, createJavaScriptApplicationNode, javascriptApplicationGraphSchema, } from "./javascriptApplicationGraph.js";
+import { createJavaScriptApplicationGraph, javascriptApplicationGraphSchema, } from "./javascriptApplicationGraph.js";
 import { managedArtifactInspectionSchema, managedMemberInspectionSchema, managedNativeBoundaryInspectionSchema, } from "./managedArtifact.js";
+import { assessManagedGraphOmissions, managedGraphEvidenceCoverage, managedGraphResultCoverage, totalManagedGraphOmitted, } from "./managedApplicationGraphCoverage.js";
+import { addArtifactNode, addArtifactIdentityNodes, addBoundaryNodes, addMemberNodes, } from "./managedApplicationGraphNodes.js";
 const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
 const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
 const boundedTextSchema = z.string().min(1).max(4_096);
@@ -114,7 +115,7 @@ export const projectManagedApplicationGraph = (input) => {
         root_node_ids: [artifactNode.node_id],
         nodes: state.nodes,
         edges: state.edges,
-        coverage: graphCoverage(omissions),
+        coverage: managedGraphEvidenceCoverage(omissions),
         limitations,
     });
     const withoutId = {
@@ -134,7 +135,7 @@ export const projectManagedApplicationGraph = (input) => {
             ...boundaryCounts,
         },
         graph,
-        coverage: resultCoverage(omissions),
+        coverage: managedGraphResultCoverage(omissions),
         evidence_links: evidenceLinks,
         limitations,
     };
@@ -177,364 +178,11 @@ const assertSameArtifact = (parsed, sha256Value) => {
         if (result !== undefined && result.artifact.sha256 !== sha256Value)
             throw new TypeError("Managed graph projection inputs must describe the same artifact SHA-256");
 };
-const addArtifactNode = (state) => {
-    const node = createJavaScriptApplicationNode({
-        kind: "artifact",
-        identity: {
-            strategy: "content-digest",
-            stability: "global-exact",
-            sha256: state.artifactSha256,
-        },
-        observations: [
-            {
-                label: basename(state.artifactPath),
-                properties: {
-                    format: "pe",
-                    source: "managed-application-graph",
-                },
-                evidence: managedEvidence(state, "project-managed-artifact"),
-            },
-        ],
-    });
-    state.nodes.push(node);
-    return node;
-};
-const addArtifactIdentityNodes = (state, artifactNode, parsed) => {
-    const artifact = parsed.artifact?.result;
-    if (artifact?.assembly !== undefined && artifact.assembly !== null) {
-        const assembly = createJavaScriptApplicationNode({
-            kind: "managed-assembly",
-            identity: artifactLocalIdentity(state.artifactSha256, "managed-assembly", artifact.assembly.token),
-            observations: [
-                {
-                    label: artifact.assembly.name,
-                    properties: {
-                        name: artifact.assembly.name,
-                        version: artifact.assembly.version,
-                        culture: artifact.assembly.culture,
-                        public_key_kind: artifact.assembly.public_key.kind,
-                    },
-                    evidence: managedEvidence(state, "inspect_managed_artifact"),
-                },
-            ],
-        });
-        state.nodes.push(assembly);
-        addContainsEdge(state, artifactNode, assembly, "declares-managed-assembly");
-    }
-    const module = artifact?.module ??
-        parsed.members?.result.module ??
-        parsed.boundaries?.result.module;
-    if (module !== undefined && module !== null) {
-        const moduleNode = createJavaScriptApplicationNode({
-            kind: "managed-module",
-            identity: artifactLocalIdentity(state.artifactSha256, "managed-module", module.mvid ?? module.token),
-            observations: [
-                {
-                    label: module.name,
-                    properties: {
-                        name: module.name,
-                        mvid: module.mvid,
-                        generation: module.generation,
-                        token: module.token,
-                    },
-                    evidence: managedEvidence(state, "inspect_managed_artifact"),
-                },
-            ],
-        });
-        state.nodes.push(moduleNode);
-        addContainsEdge(state, artifactNode, moduleNode, "declares-managed-module");
-    }
-};
-const addMemberNodes = (state, artifactNode, parsed, limits) => {
-    const members = parsed.members?.result;
-    if (members === undefined)
-        return { types: 0, methods: 0, fields: 0 };
-    const types = members.types.items.slice(0, limits.max_types);
-    const methods = members.methods.items.slice(0, limits.max_methods);
-    const fields = members.fields.items.slice(0, limits.max_fields);
-    for (const type of types) {
-        const node = typeNode(state, type);
-        state.nodes.push(node);
-        state.typeNodes.set(type.token, node);
-        addContainsEdge(state, artifactNode, node, "declares-managed-type");
-    }
-    for (const method of methods) {
-        const node = methodNode(state, method);
-        state.nodes.push(node);
-        state.methodNodes.set(method.token, node);
-        const owner = method.declaring_type_token === null
-            ? artifactNode
-            : (state.typeNodes.get(method.declaring_type_token) ?? artifactNode);
-        addContainsEdge(state, owner, node, "declares-managed-method");
-    }
-    for (const field of fields) {
-        const node = fieldNode(state, field);
-        state.nodes.push(node);
-        state.fieldNodes.set(field.token, node);
-        const owner = field.declaring_type_token === null
-            ? artifactNode
-            : (state.typeNodes.get(field.declaring_type_token) ?? artifactNode);
-        addContainsEdge(state, owner, node, "declares-managed-field");
-    }
-    return {
-        types: types.length,
-        methods: methods.length,
-        fields: fields.length,
-    };
-};
-const typeNode = (state, type) => createJavaScriptApplicationNode({
-    kind: "managed-type",
-    identity: artifactLocalIdentity(state.artifactSha256, "managed-type-token", type.token),
-    observations: [
-        {
-            label: type.full_name,
-            properties: {
-                token: type.token,
-                namespace: type.namespace,
-                name: type.name,
-                full_name: type.full_name,
-                flags: type.flags,
-                extends_token: type.extends_token,
-            },
-            evidence: managedEvidence(state, "inspect_managed_members"),
-        },
-    ],
-});
-const methodNode = (state, method) => createJavaScriptApplicationNode({
-    kind: "managed-method",
-    identity: artifactLocalIdentity(state.artifactSha256, "managed-method-token", method.token),
-    observations: [
-        {
-            label: method.declaring_type === null
-                ? method.name
-                : `${method.declaring_type}.${method.name}`,
-            properties: {
-                token: method.token,
-                declaring_type_token: method.declaring_type_token,
-                declaring_type: method.declaring_type,
-                name: method.name,
-                rva: method.rva,
-                signature_sha256: method.signature.raw_sha256,
-                signature_status: method.signature.parse_status,
-                body_status: method.body.status,
-                normalized_il_sha256: method.body.normalized_il_sha256,
-                il_size: method.body.il_size,
-            },
-            evidence: managedEvidence(state, "inspect_managed_members"),
-        },
-    ],
-});
-const fieldNode = (state, field) => createJavaScriptApplicationNode({
-    kind: "managed-field",
-    identity: artifactLocalIdentity(state.artifactSha256, "managed-field-token", field.token),
-    observations: [
-        {
-            label: field.declaring_type === null
-                ? field.name
-                : `${field.declaring_type}.${field.name}`,
-            properties: {
-                token: field.token,
-                declaring_type_token: field.declaring_type_token,
-                declaring_type: field.declaring_type,
-                name: field.name,
-                flags: field.flags,
-                signature_sha256: field.signature.raw_sha256,
-                signature_status: field.signature.parse_status,
-            },
-            evidence: managedEvidence(state, "inspect_managed_members"),
-        },
-    ],
-});
-const addBoundaryNodes = (state, artifactNode, parsed, limits) => {
-    const boundaries = parsed.boundaries?.result;
-    if (boundaries === undefined)
-        return { pinvoke_imports: 0, native_implementations: 0 };
-    const pinvokes = boundaries.pinvoke_imports.items.slice(0, limits.max_pinvoke_imports);
-    const implementations = boundaries.native_implementations.items.slice(0, limits.max_native_implementations);
-    for (const pinvoke of pinvokes) {
-        const node = pinvokeNode(state, pinvoke);
-        state.nodes.push(node);
-        const owner = pinvoke.member_token === null
-            ? artifactNode
-            : (state.methodNodes.get(pinvoke.member_token) ?? artifactNode);
-        state.edges.push(createJavaScriptApplicationEdge({
-            source_node_id: owner.node_id,
-            target_node_id: node.node_id,
-            relation: "imports",
-            properties: {
-                kind: "managed-pinvoke",
-                import_name: pinvoke.import_name,
-                import_scope_name: pinvoke.import_scope_name,
-            },
-            evidence: managedEvidence(state, "inspect_managed_native_boundaries"),
-        }));
-    }
-    for (const implementation of implementations) {
-        const node = nativeImplementationNode(state, implementation);
-        state.nodes.push(node);
-        const owner = state.methodNodes.get(implementation.token) ?? artifactNode;
-        addContainsEdge(state, owner, node, "declares-managed-native-implementation");
-    }
-    return {
-        pinvoke_imports: pinvokes.length,
-        native_implementations: implementations.length,
-    };
-};
-const pinvokeNode = (state, pinvoke) => createJavaScriptApplicationNode({
-    kind: "managed-pinvoke-import",
-    identity: artifactLocalIdentity(state.artifactSha256, "managed-pinvoke-token", pinvoke.token),
-    observations: [
-        {
-            label: pinvoke.import_name,
-            properties: {
-                token: pinvoke.token,
-                member_token: pinvoke.member_token,
-                member_name: pinvoke.member_name,
-                import_name: pinvoke.import_name,
-                import_scope_name: pinvoke.import_scope_name,
-                char_set: pinvoke.char_set,
-                call_convention: pinvoke.call_convention,
-                verification: pinvoke.verification,
-            },
-            evidence: managedEvidence(state, "inspect_managed_native_boundaries"),
-        },
-    ],
-});
-const nativeImplementationNode = (state, implementation) => createJavaScriptApplicationNode({
-    kind: "managed-native-implementation",
-    identity: artifactLocalIdentity(state.artifactSha256, "managed-native-implementation-token", implementation.token),
-    observations: [
-        {
-            label: implementation.name,
-            properties: {
-                token: implementation.token,
-                name: implementation.name,
-                rva: implementation.rva,
-                code_type: implementation.code_type,
-                managed_kind: implementation.managed_kind,
-                pinvoke_declared: implementation.pinvoke_declared,
-                boundary_kind: implementation.boundary_kind,
-                body_interpretation: implementation.body_interpretation,
-            },
-            evidence: managedEvidence(state, "inspect_managed_native_boundaries"),
-        },
-    ],
-});
-const addContainsEdge = (state, source, target, kind) => {
-    state.edges.push(createJavaScriptApplicationEdge({
-        source_node_id: source.node_id,
-        target_node_id: target.node_id,
-        relation: "contains",
-        properties: { kind },
-        evidence: managedEvidence(state, "project-managed-contains"),
-    }));
-};
-const artifactLocalIdentity = (artifactSha256, namespace, key) => ({
-    strategy: "artifact-local-key",
-    stability: "artifact-version",
-    artifact_sha256: artifactSha256,
-    namespace,
-    key,
-});
-const managedEvidence = (state, operation) => ({
-    authority: "managed-static-analysis",
-    state: "observed",
-    confidence: "exact",
-    artifact: {
-        available: true,
-        artifact_id: `art_${state.artifactSha256}`,
-        sha256: state.artifactSha256,
-    },
-    location: {
-        available: true,
-        value: {
-            kind: "artifact-path",
-            path: graphArtifactPath(state.artifactPath),
-        },
-    },
-    extractor: {
-        name: "rea-dotnet-static",
-        version: "1",
-        operation,
-        executable_sha256: null,
-    },
-    coverage: completeCoverage(),
-    limitations: [],
-    evidence_ids: state.evidenceLinks,
-});
-const graphArtifactPath = (path) => {
-    const name = basename(path).replaceAll(/[^A-Za-z0-9._-]/gu, "_");
-    return `managed/${name.length === 0 ? "artifact.pe" : name}`;
-};
-const completeCoverage = () => ({
-    status: "complete",
-    truncated: false,
-    omitted_count: 0,
-    limits: [],
-});
-const graphCoverage = (omissions) => {
-    const omitted = totalOmitted(omissions);
-    return {
-        status: omitted === 0 ? "complete" : "partial",
-        truncated: omitted > 0,
-        omitted_count: omitted,
-        limits: [
-            { name: "max_types", value: omissions.limits.max_types, unit: "items" },
-            {
-                name: "max_methods",
-                value: omissions.limits.max_methods,
-                unit: "items",
-            },
-            { name: "max_fields", value: omissions.limits.max_fields, unit: "items" },
-            {
-                name: "max_pinvoke_imports",
-                value: omissions.limits.max_pinvoke_imports,
-                unit: "items",
-            },
-            {
-                name: "max_native_implementations",
-                value: omissions.limits.max_native_implementations,
-                unit: "items",
-            },
-        ],
-    };
-};
-const resultCoverage = (omissions) => {
-    const omitted = totalOmitted(omissions);
-    return {
-        status: omitted > 0
-            ? "truncated"
-            : omissions.partialInput
-                ? "partial"
-                : "complete-within-inputs",
-        omitted_types: omissions.types,
-        omitted_methods: omissions.methods,
-        omitted_fields: omissions.fields,
-        omitted_pinvoke_imports: omissions.pinvokeImports,
-        omitted_native_implementations: omissions.nativeImplementations,
-    };
-};
-const omittedCounts = (parsed, limits) => ({
-    limits,
-    partialInput: (parsed.members !== null &&
-        parsed.members.result.coverage.state !== "complete") ||
-        (parsed.boundaries !== null &&
-            parsed.boundaries.result.coverage.state !== "complete") ||
-        (parsed.artifact !== null &&
-            parsed.artifact.result.coverage.state !== "complete"),
-    types: Math.max(0, (parsed.members?.result.types.items.length ?? 0) - limits.max_types),
-    methods: Math.max(0, (parsed.members?.result.methods.items.length ?? 0) - limits.max_methods),
-    fields: Math.max(0, (parsed.members?.result.fields.items.length ?? 0) - limits.max_fields),
-    pinvokeImports: Math.max(0, (parsed.boundaries?.result.pinvoke_imports.items.length ?? 0) -
-        limits.max_pinvoke_imports),
-    nativeImplementations: Math.max(0, (parsed.boundaries?.result.native_implementations.items.length ?? 0) -
-        limits.max_native_implementations),
-});
-const totalOmitted = (omissions) => omissions.types +
-    omissions.methods +
-    omissions.fields +
-    omissions.pinvokeImports +
-    omissions.nativeImplementations;
+const omittedCounts = (parsed, limits) => assessManagedGraphOmissions({
+    artifact: parsed.artifact?.result ?? null,
+    members: parsed.members?.result ?? null,
+    boundaries: parsed.boundaries?.result ?? null,
+}, limits);
 const projectionLimitations = (parsed, omissions) => [
     "Managed graph projection preserves static metadata observations only; it does not execute managed code, load assemblies, or map managed tokens to native addresses.",
     ...(parsed.members === null
@@ -550,7 +198,9 @@ const projectionLimitations = (parsed, omissions) => [
     ...(omissions.partialInput
         ? ["At least one supplied managed Evidence record has partial coverage."]
         : []),
-    ...(totalOmitted(omissions) > 0
-        ? ["Projection output was truncated by managed application graph limits."]
+    ...(totalManagedGraphOmitted(omissions) > 0
+        ? [
+            "Projection output omits managed entities because of source pagination or managed application graph limits.",
+        ]
         : []),
 ];

package/dist/domain/managedApplicationGraphCoverage.js

@@ -0,0 +1,170 @@
+import { assessKnownPageCoverage, } from "./knownPageCoverage.js";
+/** Complete application-graph fact coverage. */
+const completeManagedGraphCoverage = () => ({
+    status: "complete",
+    truncated: false,
+    omitted_count: 0,
+    limits: [],
+});
+/** Translate one managed parser coverage state without inventing omissions. */
+export const managedSourceCoverage = (state) => state === "complete"
+    ? completeManagedGraphCoverage()
+    : {
+        status: state,
+        truncated: false,
+        omitted_count: null,
+        limits: [],
+    };
+/** Preserve one known source page's coverage on a projected graph fact. */
+export const managedSourcePageCoverage = (state, page, scope) => {
+    if (state !== "complete")
+        return managedSourceCoverage(state);
+    const assessment = assessKnownPageCoverage(page);
+    if (assessment.complete)
+        return completeManagedGraphCoverage();
+    return {
+        status: "partial",
+        truncated: assessment.omittedCount > 0,
+        omitted_count: assessment.omittedCount,
+        limits: assessment.omittedCount > 0
+            ? [
+                { name: `${scope}_offset`, value: page.offset, unit: "items" },
+                { name: `${scope}_limit`, value: page.limit, unit: "items" },
+            ]
+            : [],
+    };
+};
+/** Assess exact source-page and local-limit omissions for graph projection. */
+export const assessManagedGraphOmissions = (sources, limits) => {
+    const { typeAssessment, methodAssessment, fieldAssessment } = assessMemberPages(sources.members, limits);
+    const { pinvokeAssessment, implementationAssessment } = assessBoundaryPages(sources.boundaries, limits);
+    const pageAssessments = [
+        typeAssessment,
+        methodAssessment,
+        fieldAssessment,
+        pinvokeAssessment,
+        implementationAssessment,
+    ];
+    const unknownInputCoverage = hasUnknownInputCoverage(sources);
+    return {
+        limits,
+        unknownInputCoverage,
+        partialInput: pageAssessments.some(({ sourceComplete }) => !sourceComplete) ||
+            unknownInputCoverage,
+        types: typeAssessment.omittedCount,
+        methods: methodAssessment.omittedCount,
+        fields: fieldAssessment.omittedCount,
+        pinvokeImports: pinvokeAssessment.omittedCount,
+        nativeImplementations: implementationAssessment.omittedCount,
+        sourceLimits: [
+            ...memberSourceLimits(sources.members),
+            ...boundarySourceLimits(sources.boundaries),
+        ],
+    };
+};
+/** Project aggregate omissions into the application graph coverage contract. */
+export const managedGraphEvidenceCoverage = (omissions) => {
+    const omitted = totalManagedGraphOmitted(omissions);
+    if (omissions.unknownInputCoverage)
+        return {
+            status: "partial",
+            truncated: false,
+            omitted_count: null,
+            limits: [],
+        };
+    return {
+        status: omitted === 0 && !omissions.partialInput ? "complete" : "partial",
+        truncated: omitted > 0,
+        omitted_count: omitted > 0 ? omitted : omissions.partialInput ? null : 0,
+        limits: omitted > 0 ? projectionLimits(omissions) : [],
+    };
+};
+/** Project aggregate omissions into the managed workflow result contract. */
+export const managedGraphResultCoverage = (omissions) => {
+    const omitted = totalManagedGraphOmitted(omissions);
+    return {
+        status: omissions.unknownInputCoverage
+            ? "partial"
+            : omitted > 0
+                ? "truncated"
+                : omissions.partialInput
+                    ? "partial"
+                    : "complete-within-inputs",
+        omitted_types: omissions.types,
+        omitted_methods: omissions.methods,
+        omitted_fields: omissions.fields,
+        omitted_pinvoke_imports: omissions.pinvokeImports,
+        omitted_native_implementations: omissions.nativeImplementations,
+    };
+};
+/** Sum all exact entity omissions represented by the managed graph result. */
+export const totalManagedGraphOmitted = (omissions) => omissions.types +
+    omissions.methods +
+    omissions.fields +
+    omissions.pinvokeImports +
+    omissions.nativeImplementations;
+const COMPLETE_EMPTY_PAGE = {
+    complete: true,
+    sourceComplete: true,
+    includedCount: 0,
+    omittedCount: 0,
+    sourceOmittedCount: 0,
+};
+const assessMemberPages = (members, limits) => members === null
+    ? {
+        typeAssessment: COMPLETE_EMPTY_PAGE,
+        methodAssessment: COMPLETE_EMPTY_PAGE,
+        fieldAssessment: COMPLETE_EMPTY_PAGE,
+    }
+    : {
+        typeAssessment: assessKnownPageCoverage(members.types, limits.max_types),
+        methodAssessment: assessKnownPageCoverage(members.methods, limits.max_methods),
+        fieldAssessment: assessKnownPageCoverage(members.fields, limits.max_fields),
+    };
+const assessBoundaryPages = (boundaries, limits) => boundaries === null
+    ? {
+        pinvokeAssessment: COMPLETE_EMPTY_PAGE,
+        implementationAssessment: COMPLETE_EMPTY_PAGE,
+    }
+    : {
+        pinvokeAssessment: assessKnownPageCoverage(boundaries.pinvoke_imports, limits.max_pinvoke_imports),
+        implementationAssessment: assessKnownPageCoverage(boundaries.native_implementations, limits.max_native_implementations),
+    };
+const hasUnknownInputCoverage = (sources) => [
+    sources.members?.coverage.state,
+    sources.boundaries?.coverage.state,
+    sources.artifact?.coverage.state,
+].some((state) => state !== undefined && state !== "complete");
+const pageLimits = (name, page) => [
+    { name: `${name}_offset`, value: page.offset, unit: "items" },
+    { name: `${name}_limit`, value: page.limit, unit: "items" },
+];
+const memberSourceLimits = (members) => members === null
+    ? []
+    : [
+        ...pageLimits("source_types", members.types),
+        ...pageLimits("source_methods", members.methods),
+        ...pageLimits("source_fields", members.fields),
+    ];
+const boundarySourceLimits = (boundaries) => boundaries === null
+    ? []
+    : [
+        ...pageLimits("source_pinvoke_imports", boundaries.pinvoke_imports),
+        ...pageLimits("source_native_implementations", boundaries.native_implementations),
+    ];
+const projectionLimits = (omissions) => [
+    { name: "max_types", value: omissions.limits.max_types, unit: "items" },
+    { name: "max_methods", value: omissions.limits.max_methods, unit: "items" },
+    { name: "max_fields", value: omissions.limits.max_fields, unit: "items" },
+    {
+        name: "max_pinvoke_imports",
+        value: omissions.limits.max_pinvoke_imports,
+        unit: "items",
+    },
+    {
+        name: "max_native_implementations",
+        value: omissions.limits.max_native_implementations,
+        unit: "items",
+    },
+    ...omissions.sourceLimits,
+];

package/dist/domain/managedApplicationGraphNodeCoverage.js

@@ -0,0 +1,6 @@
+/** Derive module coverage from the best available managed evidence source. */
+export const moduleCoverageState = (parsed) => parsed.artifact !== null && parsed.artifact.result.module !== null
+    ? parsed.artifact.result.coverage.state
+    : parsed.members !== null && parsed.members.result.module !== null
+        ? parsed.members.result.coverage.state
+        : (parsed.boundaries?.result.coverage.state ?? "complete");