mirror of
https://github.com/morluto/rea.git
synced 2026-11-20 13:45:30 +00:00
* feat(artifacts): inspect NES 2.0 container headers and regions Problem: the iNES lane refused every header whose byte 7 bits 2-3 select NES 2.0, so NES 2.0 cartridges could not be inventoried, extracted or reconstructed even though their file layout extends classic iNES. Fix: the single iNES-family header parser now reads NES 2.0 alongside classic iNES. It reports the 12-bit mapper, submapper, 12-bit and exponent-multiplier PRG/CHR sizes, declared PRG/CHR RAM and NVRAM sizes, CPU/PPU timing, console type with Vs. System and extended console codes, miscellaneous ROM count and default expansion device in a "nes-2.0" header variant; classic headers keep their exact serialization. Regions add one prg.bin/chr.bin for exponent sizes and misc-rom.bin for the bytes after CHR-ROM when miscellaneous ROMs are declared. Oversized declarations (with exact totals, including exponent sizes beyond safe integers), nonzero unused header bits, empty PRG-ROM and declared but absent miscellaneous ROM bytes are refused through the existing format error. Nested byte classification now admits NES 2.0 through the same parser. The reader limitation, tool description, guide and skill reference now state that UNIF remains unsupported and that RAM, timing and console values are declarations. Validation: new synthetic NES 2.0 unit cases fail on the base (15 of 24) and pass after the change; focused boundary and acceptance iNES suites (75 tests) pass, including NES 2.0 inventory, extraction, reconstruction and compiled CLI inspection; npm run check:fast passes. Refs morluto/rea#2072 * test(artifacts): extract an exponent-sized NES 2.0 ROM area Review follow-up for NES 2.0 headers. The exponent-multiplier case stopped at parseInesLayout, and the extraction test used counted ROM units, so prg.bin and chr.bin from an exponent-sized area never went through the reader or extraction. A boundary case now builds a NES 2.0 file with a 2^10 * 3 byte PRG-ROM area beside one counted 8 KiB CHR-ROM unit. It checks the header omits the PRG unit count, the source offsets of prg.bin and chr/000.bin, the verified reconstruction order, and that the extracted regions match the original bytes exactly. Tests: tests/boundary/filesystem/inesArtifact.test.ts passes (38). * refactor(artifacts): read NES header bytes through one helper The NES 2.0 declaration added a sixth raw Buffer read to inesContainer.ts. On current main the architecture guard allows five there, so the merged tree failed Static checks. iNES and NES 2.0 declarations and the format probe now read header bytes through one headerByte helper. The file has one raw read, and its counted baseline drops from 5 to 1 through --shrink-baselines. Tests: inesContainer domain tests (24) and the NES boundary and acceptance tests (76) pass. architecture-guards, format:check and check:ci:fast pass on the branch merged with main. * refactor(artifacts): report iNES header failures through ParseFailure Review follow-up: the NES 2.0 declaration added plain-string failures. The iNES-family parser now returns Result<_, ParseFailure> with its kind and where it was found: - malformed: a missing signature, a dirty legacy header, an empty PRG-ROM area, reserved NES 2.0 bits or an invalid file extent; - truncated: a short header, a short payload, or declared miscellaneous ROM with no bytes; - unsupported: UNIF or another header variant, with undecoded content. The detail text is unchanged. The format registry refuses with the detail, and the iNES reader and root classifier translate the failure at their boundary into the existing format ArtifactReaderFailure, with the ParseFailureError as its cause. Tests: the refusal table now asserts each failure's kind and format as well as its detail. iNES domain and recognition tests, NES boundary and acceptance tests (76), architecture-guards, format:check and check:ci:fast pass on the branch merged with main. * fix(artifacts): preserve NES header declarations and iNES evidence --------- Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
360 lines
13 KiB
TypeScript
360 lines
13 KiB
TypeScript
import { createHash } from "node:crypto";
|
|
import { readFile, rm, writeFile } from "node:fs/promises";
|
|
import { join } from "node:path";
|
|
import { expect } from "vitest";
|
|
import { artifactInspectionResultSchema } from "../../src/domain/artifactInspection.js";
|
|
import {
|
|
artifactInventoryResultSchema,
|
|
artifactExtractionResultSchema,
|
|
} from "../../src/domain/artifactGraph.js";
|
|
import { analysisViewResultSchema } from "../../src/domain/analysisView/analysisViewResult.js";
|
|
import { parseEvidence } from "../../src/domain/evidence.js";
|
|
import { cliTest } from "../support/cli/cliFixture.js";
|
|
import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";
|
|
import { connectLocalToolsMcp } from "../fixtures/localToolsMcp.js";
|
|
import { parseMcpToolError } from "../fixtures/mcpToolError.js";
|
|
import { inesFixture, nes2Fixture } from "../fixtures/ines.js";
|
|
import { writeOrderedZip } from "../fixtures/artifactEntryOrder.js";
|
|
import { ZIP_PACKAGE_FORMATS } from "../../src/domain/zipPackageFormat.js";
|
|
import { toolContract } from "../../src/contracts/toolContracts.js";
|
|
import { buildBinary } from "plist";
|
|
|
|
cliTest(
|
|
"refuses extraction after an already open plist is replaced through MCP",
|
|
async () => {
|
|
const root = await createTestTempDirectory("rea-ines-plist-refresh-");
|
|
const path = join(root, "source.bin");
|
|
await writeFile(path, buildBinary({ value: "old" }));
|
|
const { call } = await connectLocalToolsMcp();
|
|
const opened = await call("open_binary", { path });
|
|
expect(opened.isError, JSON.stringify(opened.structuredContent)).not.toBe(
|
|
true,
|
|
);
|
|
expect(
|
|
toolContract("open_binary").outputSchema.parse(opened.structuredContent)
|
|
.result,
|
|
).toMatchObject({ format: "plist" });
|
|
const bytes = inesFixture();
|
|
await writeFile(path, bytes);
|
|
const extracted = await call("extract_artifact", {});
|
|
expect(extracted.isError).toBe(true);
|
|
expect(JSON.stringify(parseMcpToolError(extracted))).toContain(
|
|
"Artifact format has no extraction reader: plist",
|
|
);
|
|
await call("close_binary", {});
|
|
},
|
|
);
|
|
|
|
cliTest(
|
|
"refreshes an iNES path through MCP for every ZIP package family",
|
|
async () => {
|
|
const root = await createTestTempDirectory("rea-ines-zip-refresh-");
|
|
const { call } = await connectLocalToolsMcp();
|
|
for (const format of ZIP_PACKAGE_FORMATS) {
|
|
const path = join(
|
|
root,
|
|
`cartridge.${format === "app-pack" ? "app" : format}`,
|
|
);
|
|
await writeFile(path, inesFixture());
|
|
const first = await call("open_binary", { path });
|
|
expect(first.isError, JSON.stringify(first)).not.toBe(true);
|
|
await writeOrderedZip(path, ["payload.txt"]);
|
|
const refreshed = await call("open_binary", { path });
|
|
expect(
|
|
refreshed.isError,
|
|
JSON.stringify({ format, response: refreshed }),
|
|
).not.toBe(true);
|
|
expect(
|
|
toolContract("open_binary").outputSchema.parse(
|
|
refreshed.structuredContent,
|
|
).result,
|
|
).toMatchObject({ kind: "archive", format });
|
|
const session = await call("binary_session", {});
|
|
expect(
|
|
session.isError,
|
|
JSON.stringify(session.structuredContent),
|
|
).not.toBe(true);
|
|
expect(
|
|
toolContract("binary_session").outputSchema.parse(
|
|
session.structuredContent,
|
|
).result,
|
|
).toMatchObject({ open: true, kind: "archive", format });
|
|
}
|
|
},
|
|
);
|
|
|
|
const inventoryFrom = (input: unknown) => {
|
|
const evidence = parseEvidence(input);
|
|
expect(evidence.subject).toMatchObject({
|
|
identity: { format: "ines", architecture: null },
|
|
});
|
|
const inspection = artifactInspectionResultSchema.parse(
|
|
evidence.normalized_result,
|
|
);
|
|
expect(inspection.coverage.status).toBe("complete-within-substeps");
|
|
expect(inspection.observations.map(({ kind }) => kind)).toEqual([
|
|
"root-manifest",
|
|
"container-header",
|
|
"reconstruction",
|
|
]);
|
|
const substep = inspection.substeps[0];
|
|
if (substep === undefined) throw new Error("Missing inventory substep");
|
|
parseEvidence(substep.evidence);
|
|
const inventory = artifactInventoryResultSchema.parse(
|
|
substep.evidence.normalized_result,
|
|
);
|
|
expect(inventory.coverage.status).toBe("complete");
|
|
expect(inventory.limitations).toContainEqual(
|
|
expect.stringContaining("CPU bank mappings"),
|
|
);
|
|
return inventory;
|
|
};
|
|
|
|
cliTest(
|
|
"classic iNES has the same complete byte inventory through compiled CLI and stdio MCP",
|
|
async ({ cli }) => {
|
|
const root = await createTestTempDirectory("rea-ines-public-");
|
|
const path = join(root, "卡带.hop");
|
|
const bytes = inesFixture({
|
|
trainer: true,
|
|
trailing: Buffer.from([0, 255, 3, 0]),
|
|
});
|
|
await writeFile(path, bytes);
|
|
const cliResult = await cli.run({
|
|
arguments: ["inspect-artifact", path, "--json"],
|
|
});
|
|
expect(cliResult.exitCode, cliResult.stderr).toBe(0);
|
|
const inventory = inventoryFrom(cliResult.json);
|
|
expect(inventory.limitations).toContain(
|
|
"Classic iNES file regions are observed; mapper execution, CPU bank mappings, CHR-RAM contents, 6502 analysis and emulator behavior are not observed. Trailing bytes are retained without interpretation. NES 2.0 and UNIF are unsupported.",
|
|
);
|
|
const digest = createHash("sha256").update(bytes).digest("hex");
|
|
expect(inventory.ines).toMatchObject({
|
|
header: {
|
|
header_hex: bytes.subarray(0, 16).toString("hex"),
|
|
mapper: 19,
|
|
trainer_present: true,
|
|
prg_rom_units_16k: 2,
|
|
chr_rom_units_8k: 1,
|
|
},
|
|
reconstruction: { bytes: bytes.length, sha256: digest, verified: true },
|
|
});
|
|
const expected = [
|
|
["header.bin", 0, 16],
|
|
["trainer.bin", 16, 512],
|
|
["prg/000.bin", 528, 16_384],
|
|
["prg/001.bin", 16_912, 16_384],
|
|
["chr/000.bin", 33_296, 8_192],
|
|
["trailing.bin", 41_488, 4],
|
|
] as const;
|
|
const nodes = new Map(
|
|
inventory.nodes.map((node) => [node.artifact_id, node]),
|
|
);
|
|
for (const [logical_path, offset, length] of expected) {
|
|
const occurrence = inventory.occurrences.find(
|
|
(item) => item.logical_path === logical_path,
|
|
);
|
|
if (
|
|
occurrence?.artifact_id === undefined ||
|
|
occurrence.artifact_id === null
|
|
)
|
|
throw new Error(`Missing region ${logical_path}`);
|
|
expect(occurrence.source_location).toEqual({ offset, length });
|
|
expect(nodes.get(occurrence.artifact_id)?.sha256).toBe(
|
|
createHash("sha256")
|
|
.update(bytes.subarray(offset, offset + length))
|
|
.digest("hex"),
|
|
);
|
|
expect(nodes.get(occurrence.artifact_id)?.size).toBe(length);
|
|
if (logical_path === "header.bin") {
|
|
expect(nodes.get(occurrence.artifact_id)?.format).toBe("file");
|
|
}
|
|
}
|
|
expect(inventory.ines?.reconstruction.region_order).toEqual(
|
|
expected.map(([logicalPath]) => logicalPath),
|
|
);
|
|
|
|
const { call } = await connectLocalToolsMcp();
|
|
const opened = await call("open_binary", { path });
|
|
if (opened.isError) throw new Error(JSON.stringify(opened));
|
|
const inspected = await call("inspect_artifact", {});
|
|
expect(
|
|
inspected.isError,
|
|
JSON.stringify(inspected.structuredContent),
|
|
).not.toBe(true);
|
|
expect(inventoryFrom(inspected.structuredContent)).toEqual(inventory);
|
|
const typed = artifactInspectionResultSchema.parse(
|
|
parseEvidence(inspected.structuredContent).normalized_result,
|
|
);
|
|
expect(typed.substeps[0]?.evidence.normalized_result).toMatchObject({
|
|
ines: inventory.ines,
|
|
});
|
|
const withInventory = (normalized_result: unknown) => ({
|
|
...typed,
|
|
substeps: typed.substeps.map((substep) => ({
|
|
...substep,
|
|
evidence: { ...substep.evidence, normalized_result },
|
|
})),
|
|
});
|
|
expect(
|
|
artifactInspectionResultSchema.safeParse(
|
|
withInventory({ ...inventory, ines: undefined }),
|
|
).success,
|
|
).toBe(false);
|
|
const withoutInes = { ...inventory };
|
|
delete withoutInes.ines;
|
|
expect(
|
|
artifactInspectionResultSchema.safeParse(withInventory(withoutInes))
|
|
.success,
|
|
).toBe(true);
|
|
|
|
const summary = await call("inspect_artifact", { detail: "summary" });
|
|
expect(summary.isError, JSON.stringify(summary.structuredContent)).not.toBe(
|
|
true,
|
|
);
|
|
const view = analysisViewResultSchema.parse(
|
|
parseEvidence(summary.structuredContent).normalized_result,
|
|
);
|
|
expect(view.kind).toBe("summary");
|
|
const regions = await call("inspect_analysis_view", {
|
|
source: {
|
|
kind: "retained-evidence",
|
|
evidence_id: view.parent_evidence_id,
|
|
},
|
|
view: {
|
|
kind: "inventory",
|
|
collection: "occurrences",
|
|
logical_paths: ["prg/000.bin"],
|
|
},
|
|
});
|
|
expect(regions.isError, JSON.stringify(regions.structuredContent)).not.toBe(
|
|
true,
|
|
);
|
|
expect(
|
|
parseEvidence(regions.structuredContent).normalized_result,
|
|
).toMatchObject({
|
|
kind: "inventory",
|
|
items: inventory.occurrences.filter(
|
|
(item) => item.logical_path === "prg/000.bin",
|
|
),
|
|
});
|
|
const extracted = await call("extract_artifact", {});
|
|
expect(
|
|
extracted.isError,
|
|
JSON.stringify(extracted.structuredContent),
|
|
).not.toBe(true);
|
|
const extraction = artifactExtractionResultSchema.parse(
|
|
parseEvidence(extracted.structuredContent).normalized_result,
|
|
);
|
|
try {
|
|
expect(extraction.artifacts).toHaveLength(expected.length);
|
|
const reconstructed = Buffer.concat(
|
|
await Promise.all(
|
|
expected.map(([region]) =>
|
|
readFile(join(extraction.output_root, region)),
|
|
),
|
|
),
|
|
);
|
|
expect(reconstructed.equals(bytes)).toBe(true);
|
|
} finally {
|
|
// The successful extraction transfers this exact output directory to the caller.
|
|
await rm(extraction.output_root, { recursive: true, force: true });
|
|
}
|
|
await call("close_binary", {});
|
|
expect((await readFile(path)).equals(bytes)).toBe(true);
|
|
},
|
|
);
|
|
|
|
cliTest(
|
|
"NES 2.0 header declarations and miscellaneous ROM bytes reach compiled CLI inspection",
|
|
async ({ cli }) => {
|
|
const root = await createTestTempDirectory("rea-nes2-public-");
|
|
const path = join(root, "cartridge.nes");
|
|
const bytes = nes2Fixture({
|
|
header: { 6: 0x38, 8: 0x10, 12: 0x01, 14: 1, 15: 0x40 },
|
|
miscRom: Buffer.from("misc"),
|
|
});
|
|
await writeFile(path, bytes);
|
|
const result = await cli.run({
|
|
arguments: ["inspect-artifact", path, "--json"],
|
|
});
|
|
expect(result.exitCode, result.stderr).toBe(0);
|
|
const inventory = inventoryFrom(result.json);
|
|
expect(inventory.limitations).toContainEqual(
|
|
expect.stringContaining("UNIF is unsupported"),
|
|
);
|
|
expect(inventory.ines).toMatchObject({
|
|
header: {
|
|
format: "nes-2.0",
|
|
header_hex: bytes.subarray(0, 16).toString("hex"),
|
|
mapper: 19,
|
|
submapper: 1,
|
|
cpu_ppu_timing: "pal",
|
|
nametable_layout_flags: {
|
|
arrangement_bit: false,
|
|
alternative_layout_bit: true,
|
|
},
|
|
misc_rom_count: 1,
|
|
default_expansion_device: 0x40,
|
|
},
|
|
reconstruction: {
|
|
region_order: [
|
|
"header.bin",
|
|
"prg/000.bin",
|
|
"prg/001.bin",
|
|
"chr/000.bin",
|
|
"misc-rom.bin",
|
|
],
|
|
bytes: bytes.length,
|
|
sha256: createHash("sha256").update(bytes).digest("hex"),
|
|
verified: true,
|
|
},
|
|
});
|
|
},
|
|
);
|
|
|
|
cliTest(
|
|
"unsupported NES containers fail explicitly and leave a valid MCP session usable",
|
|
async ({ cli }) => {
|
|
const root = await createTestTempDirectory("rea-ines-public-refusal-");
|
|
const validPath = join(root, "valid.nes");
|
|
await writeFile(validPath, inesFixture({ chrUnits: 0 }));
|
|
const { call } = await connectLocalToolsMcp();
|
|
const opened = await call("open_binary", { path: validPath });
|
|
if (opened.isError) throw new Error(JSON.stringify(opened));
|
|
for (const [name, bytes, reason] of [
|
|
["truncated", inesFixture().subarray(0, 20), "truncated iNES payload"],
|
|
[
|
|
"nes2",
|
|
nes2Fixture({ header: { 9: 0x01 } }),
|
|
"truncated NES 2.0 payload",
|
|
],
|
|
["unif", Buffer.from("UNIF"), "unif"],
|
|
] as const) {
|
|
const path = join(root, `${name}.nes`);
|
|
await writeFile(path, bytes);
|
|
const refused = await cli.run({
|
|
arguments: ["inspect-artifact", path, "--json"],
|
|
});
|
|
expect(refused.exitCode).not.toBe(0);
|
|
expect(JSON.stringify(refused.json)).toContain(reason);
|
|
const switched = await call("open_binary", { path });
|
|
expect(switched.isError).toBe(true);
|
|
expect(JSON.stringify(parseMcpToolError(switched))).toContain(reason);
|
|
}
|
|
const retained = await call("inspect_artifact", {});
|
|
expect(
|
|
retained.isError,
|
|
JSON.stringify(retained.structuredContent),
|
|
).not.toBe(true);
|
|
const inventory = inventoryFrom(retained.structuredContent);
|
|
expect(inventory.ines?.header.chr_rom_units_8k).toBe(0);
|
|
expect(
|
|
inventory.occurrences.some(({ logical_path }) =>
|
|
logical_path.startsWith("chr/"),
|
|
),
|
|
).toBe(false);
|
|
await call("close_binary", {});
|
|
},
|
|
);
|