Repository navigation
fix(firmware): name missing extractor dependencies in partial extraction - #1879
Merged
morluto merged 1 commit intoOct 11, 2026
Merged
Conversation
Unblob reports a missing external extractor as an
ExtractorDependencyNotFoundReport nested inside a chunk or multi-file
report, and normalizeUnblobReport forwarded that value verbatim into
diagnostics as { input_path, report }. A caller that reached partial
coverage therefore had to decode the raw producer report to learn which
extractor was absent and at which stage, even though the report already
names the dependencies.
Extraction diagnostics now normalize those entries: the named
dependencies are collected from the report and any nested value, the
producing handler is recorded as the stage, and the original report stays
retained for provenance. Entries without a dependency report keep their
previous shape.
Validation: FirmwareReports unit cases cover the chunk-nested and
multi-file-nested dependency reports and the retained raw report;
firmware suite passes; typecheck, oxlint and oxfmt on changed files. Real
Unblob extraction is unverified here because it needs the external
extractor stack.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
3 tasks done
Owner
|
Thanks for making partial firmware results easier to act on, @DeryFerd. The normalized diagnostic now names missing extractors and the handler stage inline, while retaining the raw Unblob report and keeping coverage marked partial. Callers get the cause without having to decode the producer payload. |
Closed
2 tasks done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #1853. When Unblob reaches partial extraction because an external extractor is absent, it reports an
ExtractorDependencyNotFoundReportthat already names the missing dependencies, butnormalizeUnblobReportforwarded that value verbatim intodiagnosticsas{ input_path, report }. A caller that landed on partial coverage therefore had to decode the raw producer report to learn which extractor was missing and at which stage. This PR normalizes those entries: the missing dependency names are collected from the report and any nested value, the producing handler is recorded as the stage, and the original report stays retained for provenance.Problem and expected behavior
Smallest trigger: run
extract_firmwareon a firmware image whose format needs an extractor that is not onPATH. Unblob finishes its configured extraction, retains the carved region, and reports the missing extractor as a nestedExtractorDependencyNotFoundReportwithdependencies: ["sasquatch"]. Prior behavior: the normalized result carriedcoverage: "partial"and adiagnosticsentry of{ input_path, report }, wherereportheld the raw producer report, so the dependency name and the stage existed only inside an unparsed producer value. The violated invariant: a partial result should explain the exact missing dependency and extraction stage, and distinguish carving from content extraction, without making the caller reverse-engineer the producer's report shape. Expected behavior: the diagnostic names the missing dependencies and the producing stage inline, the raw report is still retained, and coverage stayspartialrather than implying a corrupt target or an empty filesystem.Change and scope
src/firmware/FirmwareReports.tsgains one normalization helper used at both places where nested extraction problems are collected: the chunk-report branch (which carries ahandler_nameand anextraction_reportsarray) and the multi-file branch. The helper walks the report and any nested value forExtractorDependencyNotFoundReportentries, collects theirdependenciesin first-seen order, records the handler asstage, and keeps the original report underreport. Entries that carry no dependency report keep their previous{ input_path, report }shape, so unrelated diagnostics such as unknown chunk types are unchanged. Intentionally not included: no change to theextract_firmwareresult schema, no change to howcoverageis derived, no attempt to install or resolve extractors, and no reinterpretation of a missing dependency as a corrupt target.Contract and boundary impact
src/firmware/FirmwareReports.ts, which interprets the pinned Unblob report before it is projected into theextract_firmwareresult.diagnosticsis an open array of JSON values in the result contract, so the addedstageandmissing_dependenciesfields are additive and the tool catalog does not move.docs/public/product-catalog.json), package, or installation impact (CI generates and validates ignored catalogs andskills/; edit authored instructions inskill-src/and never commit build outputs): none committed.Evidence and regression coverage
src/firmware/FirmwareReports.test.tsbuilds a chunk report with a nestedExtractorDependencyNotFoundReportand asserts the normalized diagnostic names the dependency and thegzipstage while retaining the raw report; the existing multi-file case now asserts the same enriched shape for a nested dependency report, and the firmware integration fixture expectation for the dependency mode is updated to the enriched diagnostic.{ input_path, report }; after the change the firmware unit suite passes with the dependency named inline.extract_firmwareresult now lists the missing extractor and the stage directly indiagnosticsinstead of burying them in a raw producer report.For evidence-bearing changes:
Validation performed
npx vitest run src/firmware/FirmwareReports.test.ts— 7 passed, including the new dependency-diagnostic case.npx vitest run src/firmware/ tests/boundary/firmware/— 23 passed, 30 skipped; the skipped cases are the real-toolchain lanes that need an installed Unblob.npm run typecheck— exit 0.npx oxlinton the changed files — 0 errors; the three warnings (complexity,max-lines-per-function,max-depth) are pre-existing on the base innormalizeUnblobReportand reproduced with the change stashed.oxfmt --checkon the committed (LF) form — clean.Compatibility, safety, and release
Review checklist
type(scope): outcome.