rea-agents 6.4.0 → 6.5.0

package/dist/firmware/FirmwareReports.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { digestSchema } from "../domain/digests.js";
+import { uniqueSorted } from "../domain/canonicalOrdering.js";
 import { firmwareLogicalPath } from "./FirmwareFiles.js";
 const integer = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
 const signature = z.object({
@@ -46,6 +47,15 @@ const multiFile = z.object({
     extraction_reports: z.array(jsonValueSchema),
 });
 const hashes = z.object({ sha256: digestSchema });
+/**
+ * The provider's structured missing-dependency report. Non-strict on purpose:
+ * unfamiliar extra fields stay in retained diagnostics, only the dependency
+ * names are derived here.
+ */
+const missingDependency = z.object({
+    __typename__: z.literal("ExtractorDependencyNotFoundReport"),
+    dependencies: z.array(z.string()),
+});
 const region = z.object({
     id: z.string(),
     start_offset: integer,
@@ -62,6 +72,51 @@ const known = new Set([
     "CarveDirectoryReport",
     "MultiFileReport",
 ]);
+const dependencyFailure = z.object({
+    __typename__: z.literal("ExtractorDependencyNotFoundReport"),
+    dependencies: z.array(z.string().min(1)).min(1),
+});
+/** Collect the named extractors from any dependency report nested in one value. */
+const missingDependencies = (value) => {
+    // Producer-controlled name volume must not make deduplication quadratic;
+    // a Set keeps collection linear and uniqueSorted restores canonical order.
+    const found = new Set();
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item);
+            return;
+        }
+        if (typeof node !== "object" || node === null)
+            return;
+        const failure = dependencyFailure.safeParse(node);
+        if (failure.success) {
+            for (const dependency of failure.data.dependencies)
+                found.add(dependency);
+            return;
+        }
+        for (const child of Object.values(node))
+            visit(child);
+    };
+    visit(value);
+    return [...found];
+};
+/**
+ * Name the missing extractors and the producing stage for one extraction
+ * problem so a caller can act without decoding the raw report. The original
+ * report stays retained alongside the normalized fields.
+ */
+const extractionDiagnostic = (inputPath, stage, report) => {
+    const dependencies = missingDependencies(report);
+    return {
+        input_path: inputPath,
+        ...(stage === null ? {} : { stage }),
+        ...(dependencies.length === 0
+            ? {}
+            : { missing_dependencies: dependencies }),
+        report,
+    };
+};
 /** Interpret the pinned Binwalk report without inventing validated region lengths. */
 export const normalizeBinwalkReport = (raw, inputPath, size) => {
     const records = scan.parse(raw);
@@ -98,9 +153,74 @@ export const normalizeUnblobReport = (raw, context) => {
     const files = new Map();
     const sizes = new Map();
     const depths = [];
+    const failedExtractionStages = [];
     const diagnostics = [];
+    const blobOrigins = new Map();
+    const addBlobOrigin = (parentPath, id, origin) => {
+        const key = JSON.stringify([parentPath, id]);
+        if (blobOrigins.has(key))
+            throw new AnalysisOutputError("extract_firmware", `Duplicate blob identity in parent task: ${parentPath} (${id})`);
+        blobOrigins.set(key, origin);
+    };
     const chunks = [];
     const seen = new Set();
+    const taskFailures = new Set();
+    const missingDependencies = new Map();
+    /** Dependencies reported by one chunk's extraction, keyed with its chunk id. */
+    const chunkMissingDependencies = new Map();
+    const dependencyNames = (reports) => {
+        const names = new Set();
+        let unnamed = false;
+        let reported = false;
+        for (const item of reports) {
+            const parsed = missingDependency.safeParse(item);
+            if (!parsed.success)
+                continue;
+            reported = true;
+            if (parsed.data.dependencies.length === 0 ||
+                parsed.data.dependencies.includes(""))
+                unnamed = true;
+            for (const name of parsed.data.dependencies)
+                if (name !== "")
+                    names.add(name);
+        }
+        return reported ? { names, unnamed } : null;
+    };
+    const dependencyRows = (facts) => [
+        ...(facts.names.size > 0
+            ? [{ dependencies: uniqueSorted([...facts.names]) }]
+            : []),
+        ...(facts.unnamed ? [{ dependencies: [] }] : []),
+    ];
+    const noteMissingDependencies = (path, reports) => {
+        const names = dependencyNames(reports);
+        // null means no accepted failure; [] means a definite dependency failure
+        // whose executable identity the producer left unavailable.
+        if (names === null)
+            return;
+        const known = missingDependencies.get(path) ?? {
+            names: new Set(),
+            unnamed: false,
+        };
+        for (const name of names.names)
+            known.names.add(name);
+        known.unnamed ||= names.unnamed;
+        missingDependencies.set(path, known);
+    };
+    const noteChunkMissingDependencies = (path, chunkId, reports) => {
+        const names = dependencyNames(reports);
+        if (names === null)
+            return;
+        const key = JSON.stringify([path, chunkId]);
+        const known = chunkMissingDependencies.get(key) ?? {
+            names: new Set(),
+            unnamed: false,
+        };
+        for (const name of names.names)
+            known.names.add(name);
+        known.unnamed ||= names.unnamed;
+        chunkMissingDependencies.set(key, known);
+    };
     for (const record of records) {
         const path = logical(record.task.path);
         if (seen.has(path))
@@ -133,6 +253,18 @@ export const normalizeUnblobReport = (raw, context) => {
         for (const item of record.reports) {
             if (!known.has(item.__typename__))
                 diagnostics.push(jsonValueSchema.parse({ input_path: path, report: item }));
+            noteMissingDependencies(path, [item]);
+            if (item.__typename__ === "ExtractorExecutionErrorReport" &&
+                !taskFailures.has(path)) {
+                taskFailures.add(path);
+                failedExtractionStages.push({
+                    input_path: path,
+                    provider_id: null,
+                    handler: null,
+                    dependencies: [],
+                    kind: "extractor-failure",
+                });
+            }
             if (item.__typename__ === "ChunkReport" ||
                 item.__typename__ === "UnknownChunkReport") {
                 const parsed = region.parse(item);
@@ -149,15 +281,24 @@ export const normalizeUnblobReport = (raw, context) => {
                     })
                         .parse(item)
                     : null;
+                const extractionFailed = detail !== null && detail.extraction_reports.length > 0;
                 if (detail !== null)
-                    for (const problem of detail.extraction_reports)
-                        diagnostics.push({ input_path: path, report: problem });
+                    for (const problem of detail.extraction_reports) {
+                        diagnostics.push(extractionDiagnostic(path, detail.handler_name, jsonValueSchema.parse(problem)));
+                        // Nested under one chunk: keep the owning chunk, not the whole task.
+                        noteChunkMissingDependencies(path, parsed.id, [problem]);
+                    }
+                addBlobOrigin(path, parsed.id, {
+                    handler: detail?.handler_name ?? null,
+                    range: { offset: parsed.start_offset, length: parsed.size },
+                });
                 chunks.push({
                     input_path: path,
                     provider_id: parsed.id,
                     range: { offset: parsed.start_offset, length: parsed.size },
                     handler: detail?.handler_name ?? null,
                     encrypted: detail?.is_encrypted ?? null,
+                    extraction_failed: extractionFailed,
                     root_file_range: path === "$input"
                         ? {
                             offset: context.offset + parsed.start_offset,
@@ -168,19 +309,35 @@ export const normalizeUnblobReport = (raw, context) => {
             }
             if (item.__typename__ === "MultiFileReport") {
                 const parsed = multiFile.parse(item);
-                if (parsed.extraction_reports.length > 0)
-                    diagnostics.push({ input_path: path, report: item });
+                addBlobOrigin(path, parsed.id, {
+                    handler: parsed.handler_name,
+                    range: null,
+                });
+                if (parsed.extraction_reports.length > 0) {
+                    diagnostics.push(extractionDiagnostic(path, parsed.handler_name, jsonValueSchema.parse(item)));
+                    // The report owns its failure and dependencies. A produced subtask
+                    // is a derivation, not a new owner for the parent's report.
+                    const dependencies = dependencyNames(parsed.extraction_reports);
+                    const rows = dependencies === null
+                        ? [{ dependencies: [] }]
+                        : dependencyRows(dependencies);
+                    for (const row of rows)
+                        failedExtractionStages.push({
+                            input_path: path,
+                            provider_id: parsed.id,
+                            handler: parsed.handler_name,
+                            dependencies: dependencies === null
+                                ? []
+                                : uniqueSorted([...row.dependencies]),
+                            kind: dependencies === null
+                                ? "extractor-failure"
+                                : "missing-extractor-dependency",
+                        });
+                }
             }
         }
     }
     const recordsByPath = new Map(records.map((record) => [record.task.path, record.task]));
-    const chunksByOrigin = new Map();
-    for (const item of chunks) {
-        const key = JSON.stringify([item.input_path, item.provider_id]);
-        if (chunksByOrigin.has(key))
-            throw new AnalysisOutputError("extract_firmware", `Duplicate chunk identity in ${item.input_path}`);
-        chunksByOrigin.set(key, item);
-    }
     const derivations = records.flatMap((record) => record.subtasks.map((child) => {
         const parentPath = logical(record.task.path);
         const childPath = logical(child.path);
@@ -191,7 +348,7 @@ export const normalizeUnblobReport = (raw, context) => {
             reportedChild.blob_id !== child.blob_id ||
             reportedChild.is_multi_file !== child.is_multi_file)
             throw new AnalysisOutputError("extract_firmware", `Child task identity disagrees with its analysis: ${childPath}`);
-        const origin = chunksByOrigin.get(JSON.stringify([parentPath, child.blob_id]));
+        const origin = blobOrigins.get(JSON.stringify([parentPath, child.blob_id]));
         return {
             parent_path: parentPath,
             child_path: childPath,
@@ -225,7 +382,40 @@ export const normalizeUnblobReport = (raw, context) => {
         chunks,
         derivations,
         depth_limited_paths: depths.sort(),
+        failed_extraction_stages: failedExtractionStages.sort((left, right) => `${left.input_path}\u0000${left.provider_id ?? ""}` <
+            `${right.input_path}\u0000${right.provider_id ?? ""}`
+            ? -1
+            : `${left.input_path}\u0000${left.provider_id ?? ""}` >
+                `${right.input_path}\u0000${right.provider_id ?? ""}`
+                ? 1
+                : 0),
         diagnostics,
+        missing_dependencies: [...missingDependencies.entries()]
+            .flatMap(([input_path, facts]) => dependencyRows(facts).map(({ dependencies }) => ({
+            input_path,
+            dependencies,
+        })))
+            .sort((left, right) => left.input_path < right.input_path
+            ? -1
+            : left.input_path > right.input_path
+                ? 1
+                : 0),
+        chunk_missing_dependencies: [...chunkMissingDependencies.entries()]
+            .flatMap(([key, facts]) => {
+            const [input_path, provider_id] = JSON.parse(key);
+            return dependencyRows(facts).map(({ dependencies }) => ({
+                input_path,
+                provider_id,
+                dependencies,
+            }));
+        })
+            .sort((left, right) => `${left.input_path}\u0000${left.provider_id}` <
+            `${right.input_path}\u0000${right.provider_id}`
+            ? -1
+            : `${left.input_path}\u0000${left.provider_id}` >
+                `${right.input_path}\u0000${right.provider_id}`
+                ? 1
+                : 0),
         coverage: depths.length > 0 ||
             diagnostics.length > 0 ||
             chunks.some((c) => c.handler === null || c.encrypted === true)