rea-agents 2.0.0 → 2.1.0

package/dist/domain/managedApplicationGraphNodes.js

@@ -0,0 +1,336 @@
+import { basename } from "node:path";
+import { createJavaScriptApplicationEdge, createJavaScriptApplicationNode, } from "./javascriptApplicationGraph.js";
+import { managedSourceCoverage, managedSourcePageCoverage, } from "./managedApplicationGraphCoverage.js";
+import {} from "./managedArtifact.js";
+import { moduleCoverageState } from "./managedApplicationGraphNodeCoverage.js";
+/** Add the root managed artifact node to the graph state. */
+export 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;
+};
+/** Add managed assembly and module identity nodes for the artifact. */
+export const addArtifactIdentityNodes = (state, artifactNode, parsed) => {
+    const artifact = parsed.artifact?.result;
+    const artifactCoverage = managedSourceCoverage(parsed.artifact?.result.coverage.state ?? "complete");
+    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", artifactCoverage),
+                },
+            ],
+        });
+        state.nodes.push(assembly);
+        addContainsEdge(state, artifactNode, assembly, {
+            kind: "declares-managed-assembly",
+            coverage: artifactCoverage,
+        });
+    }
+    const module = artifact?.module ??
+        parsed.members?.result.module ??
+        parsed.boundaries?.result.module;
+    if (module !== undefined && module !== null) {
+        const moduleCoverage = managedSourceCoverage(moduleCoverageState(parsed));
+        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", moduleCoverage),
+                },
+            ],
+        });
+        state.nodes.push(moduleNode);
+        addContainsEdge(state, artifactNode, moduleNode, {
+            kind: "declares-managed-module",
+            coverage: moduleCoverage,
+        });
+    }
+};
+/** Add managed type, method, and field nodes from member evidence. */
+export 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);
+    const typeCoverage = managedSourcePageCoverage(members.coverage.state, members.types, "types");
+    const methodCoverage = managedSourcePageCoverage(members.coverage.state, members.methods, "methods");
+    const fieldCoverage = managedSourcePageCoverage(members.coverage.state, members.fields, "fields");
+    for (const type of types) {
+        const node = typeNode(state, type, typeCoverage);
+        state.nodes.push(node);
+        state.typeNodes.set(type.token, node);
+        addContainsEdge(state, artifactNode, node, {
+            kind: "declares-managed-type",
+            coverage: typeCoverage,
+        });
+    }
+    for (const method of methods) {
+        const node = methodNode(state, method, methodCoverage);
+        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, {
+            kind: "declares-managed-method",
+            coverage: methodCoverage,
+        });
+    }
+    for (const field of fields) {
+        const node = fieldNode(state, field, fieldCoverage);
+        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, {
+            kind: "declares-managed-field",
+            coverage: fieldCoverage,
+        });
+    }
+    return {
+        types: types.length,
+        methods: methods.length,
+        fields: fields.length,
+    };
+};
+/** Build a managed type application node. */
+const typeNode = (state, type, coverage) => 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", coverage),
+        },
+    ],
+});
+/** Build a managed method application node. */
+const methodNode = (state, method, coverage) => 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", coverage),
+        },
+    ],
+});
+/** Build a managed field application node. */
+const fieldNode = (state, field, coverage) => 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", coverage),
+        },
+    ],
+});
+/** Add P/Invoke import and native implementation boundary nodes. */
+export 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);
+    const pinvokeCoverage = managedSourcePageCoverage(boundaries.coverage.state, boundaries.pinvoke_imports, "pinvoke_imports");
+    const implementationCoverage = managedSourcePageCoverage(boundaries.coverage.state, boundaries.native_implementations, "native_implementations");
+    for (const pinvoke of pinvokes) {
+        const node = pinvokeNode(state, pinvoke, pinvokeCoverage);
+        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", pinvokeCoverage),
+        }));
+    }
+    for (const implementation of implementations) {
+        const node = nativeImplementationNode(state, implementation, implementationCoverage);
+        state.nodes.push(node);
+        const owner = state.methodNodes.get(implementation.token) ?? artifactNode;
+        addContainsEdge(state, owner, node, {
+            kind: "declares-managed-native-implementation",
+            coverage: implementationCoverage,
+        });
+    }
+    return {
+        pinvoke_imports: pinvokes.length,
+        native_implementations: implementations.length,
+    };
+};
+/** Build a managed P/Invoke import application node. */
+const pinvokeNode = (state, pinvoke, coverage) => 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", coverage),
+        },
+    ],
+});
+/** Build a managed native implementation application node. */
+const nativeImplementationNode = (state, implementation, coverage) => 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", coverage),
+        },
+    ],
+});
+/** Add a contains relationship edge between two nodes. */
+const addContainsEdge = (state, source, target, options) => {
+    state.edges.push(createJavaScriptApplicationEdge({
+        source_node_id: source.node_id,
+        target_node_id: target.node_id,
+        relation: "contains",
+        properties: { kind: options.kind },
+        evidence: managedEvidence(state, "project-managed-contains", options.coverage),
+    }));
+};
+/** Build an artifact-local key identity for a managed graph entity. */
+const artifactLocalIdentity = (artifactSha256, namespace, key) => ({
+    strategy: "artifact-local-key",
+    stability: "artifact-version",
+    artifact_sha256: artifactSha256,
+    namespace,
+    key,
+});
+/** Build managed static-analysis evidence for a graph observation. */
+const managedEvidence = (state, operation, coverage = managedSourceCoverage("complete")) => ({
+    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,
+    limitations: coverage.status === "complete"
+        ? []
+        : [
+            "The source managed Evidence slice is incomplete; unreturned or unavailable items remain unobserved.",
+        ],
+    evidence_ids: state.evidenceLinks,
+});
+/** Sanitize an artifact path into a managed graph location. */
+const graphArtifactPath = (path) => {
+    const name = basename(path).replaceAll(/[^A-Za-z0-9._-]/gu, "_");
+    return `managed/${name.length === 0 ? "artifact.pe" : name}`;
+};

package/dist/domain/managedArtifact.js

@@ -2,6 +2,10 @@ import { z } from "zod";
 const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
 const tokenSchema = z.string().regex(/^0x[0-9a-f]{8}$/u);
 const offsetSchema = z.number().int().min(0);
+/** A 16-byte CLI metadata GUID without RFC 4122 version/variant restrictions. */
+export const cliMetadataGuidSchema = z
+    .string()
+    .regex(/^[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}$/u);
 const managedPage = (item) => z.object({
     items: z.array(item),
     offset: offsetSchema,
@@ -33,9 +37,9 @@ const assemblyIdentitySchema = z.object({
 const moduleIdentitySchema = z.object({
     name: z.string(),
     generation: z.number().int().min(0).max(0xffff),
-    mvid: z.string().uuid().nullable(),
-    enc_id: z.string().uuid().nullable(),
-    enc_base_id: z.string().uuid().nullable(),
+    mvid: cliMetadataGuidSchema.nullable(),
+    enc_id: cliMetadataGuidSchema.nullable(),
+    enc_base_id: cliMetadataGuidSchema.nullable(),
     token: tokenSchema,
     row_offset: offsetSchema,
 });
@@ -142,7 +146,7 @@ const managedInstructionAnchorSchema = z.object({
     operand: z.string().nullable(),
 });
 const managedMethodBodySchema = z.object({
-    status: z.enum(["present", "absent", "malformed", "too-large"]),
+    status: z.enum(["present", "partial", "absent", "malformed", "too-large"]),
     header_format: z.enum(["tiny", "fat", "none", "unknown"]),
     rva: z.number().int().min(0).max(0xffff_ffff),
     file_offset: offsetSchema.nullable(),
@@ -150,8 +154,12 @@ const managedMethodBodySchema = z.object({
     init_locals: z.boolean().nullable(),
     local_var_sig_token: tokenSchema.nullable(),
     il_size: z.number().int().min(0),
-    il_sha256: digestSchema.nullable(),
-    normalized_il_sha256: digestSchema.nullable(),
+    il_sha256: digestSchema
+        .nullable()
+        .describe("SHA-256 of exactly the raw il_size CIL bytes; excludes the method header, locals signature, alignment, and extra sections"),
+    normalized_il_sha256: digestSchema
+        .nullable()
+        .describe("Member-result-v1 SHA-256 of UTF-8 JSON [opcode, operand_kind, operand] tuples for a complete decode; retains build-local tokens, omits switch targets, and excludes headers, locals, and exception regions"),
     instruction_count: z.number().int().min(0),
     decoded_instruction_count: z.number().int().min(0),
     truncated_instructions: z.number().int().min(0),
@@ -383,7 +391,7 @@ export const managedMemberInspectionSchema = z.object({
     identity_scope: z.object({
         token_identity: z.literal("build-local"),
         requires_artifact_sha256: digestSchema,
-        requires_mvid: z.string().uuid().nullable(),
+        requires_mvid: cliMetadataGuidSchema.nullable(),
     }),
     types: managedPage(managedTypeSchema),
     fields: managedPage(managedFieldSchema),
@@ -415,7 +423,7 @@ export const managedNativeBoundaryInspectionSchema = z.object({
     identity_scope: z.object({
         token_identity: z.literal("build-local"),
         requires_artifact_sha256: digestSchema,
-        requires_mvid: z.string().uuid().nullable(),
+        requires_mvid: cliMetadataGuidSchema.nullable(),
     }),
     cli_native: z.object({
         il_only: z.boolean(),