feat: @dcmjs-org/dicomdir assembly — DICOMDIR reading and writing

[awatson1978]

This is the assembly PR for the dicomdir package: it brings release/1.0-beta-dicomdir into 1.0-beta, carrying wave PR #573 and its follow-up #580 on top of the core branch. Like the other assemblies (#542, #543) it's open as a draft on purpose — please don't merge it yet; the landing order in RELEASE_PLAN.md section 6 means the assemblies go in deliberately, not as soon as they're green.

What this is in plain terms. A DICOMDIR is the index file at the root of a patient CD, DVD, or USB stick — the Media Storage Directory of PS3.10 / PS3.3 Annex F. It's what lets a workstation show the patients, studies, and series on the disc without opening every file. @dcmjs-org/dicomdir builds and writes one: you hand writeDicomDir a flat list of file-set entries (one per file on the media, with its path, SOP identity, and patient/study/series attributes), and it builds the PATIENT → STUDY → SERIES → leaf directory record hierarchy, computes the real byte offsets that chain the records together, and serializes the complete Part 10 file in a single pass. The interesting engineering fact is in how those offsets are computed: every DICOMDIR offset attribute is VR UL — a fixed four bytes — so the values never affect the layout, and one measurement pass with placeholder zeros yields the exact offsets of the final file. No patch-and-rewrite, no buffer scanning.

The package depends on @dcmjs-org/core and nothing else at runtime — and that claim is now enforced, not just implied by the imports. The v2 code this was ported from leaned on what is now @dcmjs-org/legacy in two places (size measurement through DicomMessage.write, and serialization through DicomDict.write); both were rebuilt on core's writeDataSet/writeTagObject primitives — the exact functions those legacy statics delegate to — and I verified the inlined Part 10 envelope byte-identical against legacy DicomDict.write on the same denaturalized { meta, dict } before relying on the argument (details in #573). Then, while verifying this PR's worked example in a clean process, I found core's sequence writer still reached for the late-bound DicomMessage that only legacy registers — so the package worked only when legacy happened to be loaded. #580 fixes that at the root (core's writeCore.js registers writeDataSet into the sequence writer's seam at load) and adds a standalone regression test that imports nothing from legacy and checks the written bytes directly.

A worked example (run on this branch, in a process with no legacy engine loaded — that's exactly what packages/dicomdir/test/standalone.test.js pins):

import { writeDicomDir } from "@dcmjs-org/dicomdir";

const arrayBuffer = writeDicomDir(
    [
        {
            referencedFileID: ["DICOM", "IM000001"],
            sopClassUid: "1.2.840.10008.5.1.4.1.1.4",
            sopInstanceUid: "1.2.3.4.100",
            transferSyntaxUid: "1.2.840.10008.1.2.1",
            patient: { PatientID: "998877", PatientName: "DOE^JANE" },
            study: { StudyInstanceUID: "1.2.3.4" },
            series: { SeriesInstanceUID: "1.2.3.4.5", Modality: "MR" },
            instance: { InstanceNumber: 1 }
        }
    ],
    { fileSetID: "MY_CD" }
);
// arrayBuffer is a complete DICOMDIR; write it to the media root.

And reading one back — a DICOMDIR is an ordinary Part 10 file, so any engine reader handles it; here's the streaming path (run on this branch, output verbatim):

import { fromPart10, NaturalizedListener } from "@dcmjs-org/parser";

const listener = new NaturalizedListener();
await fromPart10(arrayBuffer, listener); // or fromPart10Stream for media too big to buffer

const dir = listener.result;
dir.DirectoryRecordSequence.map(r => r.DirectoryRecordType);
// ["PATIENT", "STUDY", "SERIES", "IMAGE"]

const image = dir.DirectoryRecordSequence[3];
image.ReferencedFileID;                // ["DICOM", "IM000001"]
image.ReferencedSOPInstanceUIDInFile;  // "1.2.3.4.100"
// and the meta group confirms what it is:
// MediaStorageSOPClassUID "1.2.840.10008.1.3.10" (Media Storage Directory)

To be plain about scope: the package exports the builder and writer; there is no dedicated DICOMDIR read API in it, because reading needs nothing special — the records come back as the DirectoryRecordSequence shown above through either engine. If a convenience walker (offset-chasing the lower/next record chains for you) turns out to be wanted, it would be a small additive follow-up here.

buildDicomDirDataset is also exported for inspecting the record tree before serialization.

What's in it. Two PRs. #573 is the port: a scaffold commit (package.json + README), a verbatim v2 commit (three source files and the 16-test suite, byte-for-byte from v2.0-development's src/media/), and the hand-written rewiring onto @dcmjs-org/core. #580 is the standalone fix described above — a small core seam (setWriteDataSet, mirroring the existing DicomMessage seam) plus the no-legacy regression test. Hand-written totals are declared in each PR (~120 and ~100 lines); the ported lines are exempt per the budget convention.

Test evidence. The 17 tests in packages/dicomdir/test/ are fully synthetic — no fixtures. They prove the property that matters by checking the written bytes themselves: every nonzero offset value must land exactly on an FFFE,E000 item tag, the next/lower chains plus the first-root offset must address every record exactly once, the write must be deterministic, and the whole thing must work with no eager engine wired. Full suite on the branch tip: 861 passed / 12 skipped / 873 total (the 844-test core baseline plus these 17), on Node 22 and 24. CI from the merged PRs: #573 tests + build, #580 tests + build, lint/format.

GitHub issues. Honestly: none. I searched the tracker for DICOMDIR and found nothing but the 1.0 RFC (#517) this whole effort serves — dcmjs never had a DICOMDIR builder, so there was no backlog to fix. This is new capability, ported from the v2 rewrite.

Breaking changes. None. The package is purely additive, and the one touch to existing code — the sequence-writer seam in #580 — routes item serialization to the very function DicomMessage.write already delegates to, so bytes are identical whichever package loads first; the full regression suite agrees.

The trunk overlap, so the diff size isn't alarming. release/1.0-beta-dicomdir was cut from the tip of release/1.0-beta-core (e5f46e4), so until the core assembly #542 merges, this PR's diff shows the whole engine stack it sits on. Once #542 is in, this shrinks to just packages/dicomdir/ plus the lockfile and the seam fix. That's the same absorb-the-trunk pattern as the earlier assemblies, and it's the other reason this stays a draft.

🤖 Generated with Claude Code