dicom-synth 1.5.0 → 1.7.0

package/README.md

@@ -287,6 +287,33 @@ import type { StudySpec, SeriesSpec, SeriesEntrySpec } from 'dicom-synth'
 
 `GeneratedFile.relativePath` carries the layout-aware path for in-process consumers; `filename` is always the basename.
 
+### Path quirks (`pathQuirks`)
+
+Decorate written paths with edge-case names to exercise consumer file handling (e.g. the Chrome File System Access API). Quirks apply to the relative paths the layout already produces — DICOM byte content is unchanged.
+
+```json
+{
+  "studies": [{ "series": [{ "entries": [{ "type": "valid-image", "count": 3 }] }] }],
+  "layout": "hierarchical",
+  "pathQuirks": ["trailing-dot", "unicode"]
+}
+```
+
+| Quirk | Effect |
+|---|---|
+| `trailing-dot` | Appends `.` to each directory component (`study-001./series-001./…`); on flat output, to the filename |
+| `unicode` | Inserts a non-ASCII character into directory and file names |
+| `deep-nesting` | Injects extra nested directory levels before the file |
+| `long-name` | Pads the filename stem and the deepest directory component toward the 255-byte limit |
+
+Decorations are stable per path component, so a series' files still share one directory. Quirks compose; the result is deterministic and independent of the order they're listed in.
+
+> **Cross-platform:** these names are writable on POSIX (Linux/macOS, where CI runs) but Windows rewrites or rejects several (trailing dots, reserved names, long paths). The intent is to *feed* a downstream consumer (e.g. a browser), not to round-trip on Windows.
+
+```ts
+import type { PathQuirk } from 'dicom-synth'
+```
+
 ### Tag overrides (`tags`)
 
 Available on all image types.
@@ -417,6 +444,35 @@ See `examples/parametric.json` for a JSON example and `examples/convert-data-sha
 
 ---
 
+## Describe tool
+
+`describeDirectory` scans an existing DICOM tree and emits a concrete `DatasetSpec` reproducing its shape — studies/series grouped by their UIDs, per-file size as `targetSizeKb`, and modality. This closes the loop: real tree → spec → regenerate.
+
+```ts
+import { describeDirectory, writeCollectionFromSpec } from 'dicom-synth'
+
+const { spec, stats } = describeDirectory('./real-dataset')
+// stats: { dicomFiles, skipped, unknownModality }
+await writeCollectionFromSpec(spec, './reproduced')
+```
+
+- **Shape only by default** — no tags are copied; the regenerated dataset carries fresh UIDs and synthetic identifiers, so it cannot leak PHI from the source.
+- **Opt-in tag preservation** — `keepTags` copies the named tags verbatim (some datasets are valuable for testing *precisely because* of their problematic tags):
+
+  ```ts
+  describeDirectory('./real-dataset', { keepTags: ['Manufacturer', '00080060'] })
+  ```
+
+  ⚠️ Tags are copied exactly as found. If a kept tag contains PHI, handling that PHI is the **caller's responsibility** — the tool extracts only what you name.
+- Files in a series collapse into one counted entry only when modality, size, and kept tags all match, so tag/size variation is preserved rather than flattened.
+- Non-DICOM, unparseable, or ungroupable files (missing study/series UIDs) are skipped and counted. An unsupported `Modality` is emitted as the default (CT) and counted.
+
+```ts
+import type { DescribeOptions, DescribeResult } from 'dicom-synth'
+```
+
+---
+
 ## CLI
 
 ```bash
@@ -455,6 +511,24 @@ dicom-synth-generate --schema examples/default.json --out /tmp/out
 
 Schema validation errors exit with code 1 and a descriptive message.
 
+### Describe an existing tree
+
+```bash
+# Shape only (PHI-safe) — prints the DatasetSpec to stdout
+dicom-synth-describe ./real-dataset
+
+# Save to a file, and keep selected tags (caller owns any PHI in them)
+dicom-synth-describe ./real-dataset --out spec.json --keep-tags Manufacturer,00080060
+```
+
+| Flag | Effect |
+|---|---|
+| `<dir>` | DICOM tree to scan (required) |
+| `--out <path>` | Write the `DatasetSpec` JSON (default: stdout) |
+| `--keep-tags <a,b,...>` | Copy the named tags (keywords or 8-hex) verbatim; omit for shape only |
+
+Scan stats (DICOM/skipped/unsupported-modality counts) are written to stderr.
+
 ---
 
 ## Public fixtures
@@ -522,6 +596,7 @@ pnpm fetch:public-case -- pydicom-CT-small
 | `src/schema/types.ts` | All public TypeScript types (`FileSpec`, `DatasetSpec`, `ViolationClass`, etc.) |
 | `src/schema/validate.ts` | `validateDatasetSpec` / `validateParametricSpec` — validate raw JSON values against the schema |
 | `src/schema/parametric.ts` | `resolveParametricSpec` — seeded `ParametricSpec` → `DatasetSpec` resolution |
+| `src/describe/describe.ts` | `describeDirectory` — scan a DICOM tree → `DatasetSpec` |
 | `src/syntheticFixtures/generator.ts` | Internal buffer builders keyed on `FileSpec` type |
 | `src/syntheticFixtures/uid.ts` | Seeded and random UID generation |
 | `src/syntheticFixtures/violations.ts` | Post-processing violation injection |
@@ -530,6 +605,7 @@ pnpm fetch:public-case -- pydicom-CT-small
 | `src/public-fixtures/fetch.ts` | Fetch, SHA-256 verify, content-addressed cache |
 | `bin/dicom-synth-generate.mjs` | Published generate CLI (requires `pnpm build`) |
 | `bin/dicom-synth-fetch.mjs` | Published fetch CLI (requires `pnpm build`) |
+| `bin/dicom-synth-describe.mjs` | Published describe CLI (requires `pnpm build`) |
 | `examples/default.json` | Default `DatasetSpec` — one each of `valid-image`, `invalid-uid-image`, `vendor-warnings-image` |
 | `examples/parametric.json` | Example `ParametricSpec` for the `--parametric` CLI path |
 | `examples/convert-data-shape.mjs` | Example converter: tree-shape JSON → `DatasetSpec` |
@@ -558,8 +634,8 @@ Git hooks: see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Future development
 
-- **Describe tool** — scan an existing DICOM tree and emit a matching `DatasetSpec` (counts, grouping, sizes, modalities; no PHI)
 - **Dimension edge-case recipes** — documented presets for geometry pathologies (1×65535 strips, high frame counts)
+- **Per-file tag variance templating** — patterned overrides like `"PatientID": "P{index}"` for shape replication
 - **Compressed transfer syntaxes** — JPEG-LS, JPEG 2000, RLE
 - **Private fixture catalogues** — same SHA-256 fetch/cache pattern for credentials-backed sources (e.g. S3)
 

package/bin/dicom-synth-describe.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describeDirectory } from '../dist/esm/index.js'
+
+function usage() {
+  console.error(
+    'Usage: dicom-synth-describe <dir> [--out <spec.json>] [--keep-tags <a,b,...>]\n' +
+      '\n' +
+      'Scans a DICOM tree and emits a DatasetSpec describing its shape\n' +
+      '(studies/series, per-file size, modality).\n' +
+      '\n' +
+      'By default only the shape is reproduced — no tags are copied.\n' +
+      '--keep-tags copies the named tags (DICOM keywords or 8-hex tags)\n' +
+      "verbatim; if a kept tag holds PHI, handling it is the caller's\n" +
+      "responsibility, not this tool's.",
+  )
+  process.exit(1)
+}
+
+const args = process.argv.slice(2)
+if (args.length === 0) usage()
+
+let dir
+let outPath
+let keepTags
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--out' && args[i + 1]) {
+    outPath = resolve(args[++i])
+  } else if (args[i] === '--keep-tags' && args[i + 1]) {
+    keepTags = args[++i]
+      .split(',')
+      .map((t) => t.trim())
+      .filter(Boolean)
+  } else if (args[i].startsWith('--')) {
+    console.error(`Unknown argument: ${args[i]}`)
+    usage()
+  } else if (dir === undefined) {
+    dir = resolve(args[i])
+  } else {
+    console.error(`Unexpected argument: ${args[i]}`)
+    usage()
+  }
+}
+
+if (dir === undefined) usage()
+
+let result
+try {
+  result = describeDirectory(dir, keepTags ? { keepTags } : {})
+} catch (err) {
+  console.error(`Error: ${err.message}`)
+  process.exit(1)
+}
+
+const json = `${JSON.stringify(result.spec, null, 2)}\n`
+if (outPath) {
+  writeFileSync(outPath, json)
+  console.error(`Wrote DatasetSpec to ${outPath}`)
+} else {
+  process.stdout.write(json)
+}
+
+const { dicomFiles, skipped, unknownModality } = result.stats
+console.error(
+  `Described ${dicomFiles} DICOM file(s); skipped ${skipped} non-DICOM/ungroupable file(s)`,
+)
+if (unknownModality > 0) {
+  console.error(
+    `  ${unknownModality} file(s) had an unsupported Modality — emitted as default (CT)`,
+  )
+}

package/dist/esm/collection/writer.js

@@ -419,6 +419,48 @@ async function generateFile(spec, options) {
     index
   };
 }
+function hashString(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+var UNICODE_TOKENS = ["\xE9", "\xFC", "\xF1", "\u65E5", "\u2122", "\u03A9"];
+var NEST_DEPTH = 8;
+var LONG_NAME_TARGET = 200;
+function applyPathQuirks(relativePath, quirks) {
+  const segments = relativePath.split("/");
+  let dirs = segments.slice(0, -1);
+  const leaf = segments[segments.length - 1];
+  const dot = leaf.lastIndexOf(".");
+  let stem = dot > 0 ? leaf.slice(0, dot) : leaf;
+  const ext = dot > 0 ? leaf.slice(dot) : "";
+  const unicode = (s) => `${s}${UNICODE_TOKENS[hashString(s) % UNICODE_TOKENS.length]}`;
+  const has = (q) => quirks.includes(q);
+  if (has("deep-nesting")) {
+    dirs = [...dirs, ...Array.from({ length: NEST_DEPTH }, (_, i) => `d${i}`)];
+  }
+  if (has("unicode")) {
+    dirs = dirs.map(unicode);
+    stem = unicode(stem);
+  }
+  if (has("long-name")) {
+    const pad = (s) => s.length < LONG_NAME_TARGET ? s + "x".repeat(LONG_NAME_TARGET - s.length) : s;
+    stem = pad(stem);
+    if (dirs.length > 0) {
+      const last = dirs.length - 1;
+      dirs = dirs.map((d, i) => i === last ? pad(d) : d);
+    }
+  }
+  let newLeaf = stem + ext;
+  if (has("trailing-dot")) {
+    if (dirs.length > 0) dirs = dirs.map((d) => `${d}.`);
+    else newLeaf += ".";
+  }
+  return { relativePath: [...dirs, newLeaf].join("/"), filename: newLeaf };
+}
 function hierarchicalName(studyOrdinal, seriesIndex, instanceNumber) {
   const pad3 = (n) => String(n).padStart(3, "0");
   const name = `${String(instanceNumber).padStart(5, "0")}.dcm`;
@@ -433,15 +475,19 @@ async function* generateCollectionFromSpec(spec) {
   const totalFiles = entryCount(flatEntries) + studyFileCount(studies);
   const padWidth = String(totalFiles).length;
   const hierarchical = spec.layout === "hierarchical";
+  const quirks = spec.pathQuirks ?? [];
+  const decorate = (file) => quirks.length === 0 ? file : { ...file, ...applyPathQuirks(file.relativePath, quirks) };
   let globalIndex = 0;
   for (const entry of flatEntries) {
     const { count = 1, ...fileSpec } = entry;
     for (let i = 0; i < count; i++) {
-      yield generateFile(fileSpec, {
-        index: globalIndex,
-        seed: spec.seed,
-        padWidth
-      });
+      yield decorate(
+        await generateFile(fileSpec, {
+          index: globalIndex,
+          seed: spec.seed,
+          padWidth
+        })
+      );
       globalIndex++;
     }
   }
@@ -473,14 +519,16 @@ async function* generateCollectionFromSpec(spec) {
                 uid: { study: studyUid, series: seriesUid }
               }
             );
-            yield hierarchical ? {
-              ...file,
-              ...hierarchicalName(
-                studyOrdinal,
-                seriesIndex,
-                instanceNumber
-              )
-            } : file;
+            yield decorate(
+              hierarchical ? {
+                ...file,
+                ...hierarchicalName(
+                  studyOrdinal,
+                  seriesIndex,
+                  instanceNumber
+                )
+              } : file
+            );
             globalIndex++;
           }
         }

package/dist/esm/describe/describe.js

@@ -0,0 +1,393 @@
+// src/describe/describe.ts
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// src/loadDcmjs.ts
+import dcmjsDefaultImport, * as dcmjsNamespace from "dcmjs";
+function loadDcmjs() {
+  if (dcmjsNamespace.data?.DicomDict) {
+    return dcmjsNamespace;
+  }
+  const d = dcmjsDefaultImport;
+  if (d?.data?.DicomDict) {
+    return d;
+  }
+  if (d?.default?.data?.DicomDict) {
+    return d.default;
+  }
+  throw new Error(
+    "dcmjs failed to load (missing data.DicomDict). Install dcmjs >= 0.29."
+  );
+}
+var dcmjs = loadDcmjs();
+
+// src/schema/validate.ts
+var TYPE_CAPABILITIES = {
+  "valid-image": { image: true },
+  "invalid-uid-image": { image: true },
+  "vendor-warnings-image": { image: true },
+  "fake-signature": { image: false },
+  "non-dicom": { image: false },
+  dicomdir: { image: false }
+};
+var VALID_MODALITIES = {
+  CT: true,
+  PT: true,
+  MR: true,
+  CR: true
+};
+var VALID_LAYOUTS = {
+  flat: true,
+  hierarchical: true
+};
+var VALID_PATH_QUIRKS = {
+  "trailing-dot": true,
+  unicode: true,
+  "deep-nesting": true,
+  "long-name": true
+};
+var VALID_TRANSFER_SYNTAXES = {
+  "explicit-vr-little-endian": true,
+  "implicit-vr-little-endian": true
+};
+var MAX_PIXEL_BYTES = 512 * 1024 * 1024;
+var VALID_VIOLATIONS = {
+  "uid-too-long": true,
+  "non-conformant-uid": true,
+  "missing-meta-header": true,
+  "malformed-sq-delimiter": true,
+  "vr-max-length-exceeded": true,
+  "missing-type1-tag": true
+};
+var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
+var KEYWORD_RE = /^[A-Z][A-Za-z0-9]*$/;
+function validatePositiveInt(value, path) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw new Error(
+      `${path}: must be a positive integer; got ${JSON.stringify(value)}`
+    );
+  }
+}
+function validateSeed(value, path) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(
+      `${path}: must be a finite number; got ${JSON.stringify(value)}`
+    );
+  }
+}
+function validateSizeKbLimit(kb, path) {
+  if (kb * 1024 > MAX_PIXEL_BYTES) {
+    throw new Error(`${path}: exceeds the 512 MB limit`);
+  }
+}
+function validateEnum(value, valid, path) {
+  if (typeof value !== "string" || !Object.hasOwn(valid, value)) {
+    throw new Error(
+      `${path}: must be one of ${Object.keys(valid).join(", ")}; got ${JSON.stringify(value)}`
+    );
+  }
+}
+function validateTagKey(key, path) {
+  if (!HEX_TAG_RE.test(key) && !KEYWORD_RE.test(key)) {
+    throw new Error(
+      `${path}: invalid tag key "${key}" \u2014 must be a DICOM keyword name (e.g. "Modality") or an 8-hex-char tag (e.g. "00080060")`
+    );
+  }
+}
+function validateEntry(entry, path) {
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const e = entry;
+  validateEnum(e.type, TYPE_CAPABILITIES, `${path}.type`);
+  const type = e.type;
+  const caps = TYPE_CAPABILITIES[type];
+  if ("count" in e) validatePositiveInt(e.count, `${path}.count`);
+  for (const field of [
+    "modality",
+    "rows",
+    "columns",
+    "frames",
+    "targetSizeKb",
+    "tags",
+    "violations",
+    "transferSyntax"
+  ]) {
+    if (!caps.image && field in e)
+      throw new Error(`${path}.${field}: not supported for type "${type}"`);
+  }
+  if ("transferSyntax" in e) {
+    validateEnum(
+      e.transferSyntax,
+      VALID_TRANSFER_SYNTAXES,
+      `${path}.transferSyntax`
+    );
+  }
+  if ("modality" in e) {
+    validateEnum(e.modality, VALID_MODALITIES, `${path}.modality`);
+  }
+  if ("tags" in e) validateTags(e.tags, `${path}.tags`);
+  if ("violations" in e) {
+    if (!Array.isArray(e.violations)) {
+      throw new Error(`${path}.violations: must be an array`);
+    }
+    for (const [i, v] of e.violations.entries()) {
+      validateEnum(v, VALID_VIOLATIONS, `${path}.violations[${i}]`);
+    }
+  }
+  const hasDims = "rows" in e || "columns" in e || "frames" in e;
+  if ("targetSizeKb" in e) {
+    if (hasDims) {
+      throw new Error(
+        `${path}: targetSizeKb cannot be combined with rows/columns/frames \u2014 use one sizing mechanism`
+      );
+    }
+    validatePositiveInt(e.targetSizeKb, `${path}.targetSizeKb`);
+    validateSizeKbLimit(e.targetSizeKb, `${path}.targetSizeKb`);
+  } else if (hasDims) {
+    if (!("rows" in e) || !("columns" in e)) {
+      throw new Error(`${path}: rows and columns must be provided together`);
+    }
+    validatePositiveInt(e.rows, `${path}.rows`);
+    validatePositiveInt(e.columns, `${path}.columns`);
+    if ("frames" in e) validatePositiveInt(e.frames, `${path}.frames`);
+    const rows = e.rows;
+    const columns = e.columns;
+    const frames = typeof e.frames === "number" ? e.frames : 1;
+    if (rows * columns * frames * 2 > MAX_PIXEL_BYTES) {
+      throw new Error(
+        `${path}: pixel data (${rows}\xD7${columns}\xD7${frames}\xD72 bytes) exceeds the 512 MB limit`
+      );
+    }
+  }
+  return e;
+}
+function validateTags(tags, path) {
+  if (typeof tags !== "object" || tags === null || Array.isArray(tags)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  for (const key of Object.keys(tags)) {
+    validateTagKey(key, path);
+  }
+}
+function validateSeries(series, path) {
+  if (typeof series !== "object" || series === null || Array.isArray(series)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const s = series;
+  if (!Array.isArray(s.entries) || s.entries.length === 0) {
+    throw new Error(`${path}.entries: must be a non-empty array`);
+  }
+  for (let i = 0; i < s.entries.length; i++) {
+    const e = validateEntry(s.entries[i], `${path}.entries[${i}]`);
+    if (!TYPE_CAPABILITIES[e.type].image) {
+      throw new Error(
+        `${path}.entries[${i}].type: "${e.type}" cannot be used inside a series \u2014 only image-generating types can be grouped`
+      );
+    }
+  }
+  if ("tags" in s) validateTags(s.tags, `${path}.tags`);
+  return s;
+}
+function validateStudy(study, path) {
+  if (typeof study !== "object" || study === null || Array.isArray(study)) {
+    throw new Error(`${path}: must be an object`);
+  }
+  const st = study;
+  if (!Array.isArray(st.series) || st.series.length === 0) {
+    throw new Error(`${path}.series: must be a non-empty array`);
+  }
+  for (let i = 0; i < st.series.length; i++) {
+    validateSeries(st.series[i], `${path}.series[${i}]`);
+  }
+  if ("count" in st) validatePositiveInt(st.count, `${path}.count`);
+  if ("tags" in st) validateTags(st.tags, `${path}.tags`);
+  return st;
+}
+function validateDatasetSpec(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error("DatasetSpec: must be a JSON object");
+  }
+  const r = raw;
+  if ("entries" in r && !Array.isArray(r.entries)) {
+    throw new Error("DatasetSpec.entries: must be an array");
+  }
+  if ("studies" in r && !Array.isArray(r.studies)) {
+    throw new Error("DatasetSpec.studies: must be an array");
+  }
+  const rawEntries = r.entries ?? [];
+  const rawStudies = r.studies ?? [];
+  if (rawEntries.length === 0 && rawStudies.length === 0) {
+    throw new Error(
+      'DatasetSpec: must contain at least one of "entries" or "studies" (non-empty)'
+    );
+  }
+  const entries = rawEntries.map(
+    (entry, i) => validateEntry(entry, `entries[${i}]`)
+  );
+  const studies = rawStudies.map(
+    (study, i) => validateStudy(study, `studies[${i}]`)
+  );
+  if ("seed" in r) validateSeed(r.seed, "DatasetSpec.seed");
+  if ("layout" in r) {
+    validateEnum(r.layout, VALID_LAYOUTS, "DatasetSpec.layout");
+  }
+  if ("pathQuirks" in r) {
+    if (!Array.isArray(r.pathQuirks)) {
+      throw new Error("DatasetSpec.pathQuirks: must be an array");
+    }
+    for (const [i, q] of r.pathQuirks.entries()) {
+      validateEnum(q, VALID_PATH_QUIRKS, `DatasetSpec.pathQuirks[${i}]`);
+    }
+  }
+  return {
+    ...entries.length > 0 ? { entries } : {},
+    ...studies.length > 0 ? { studies } : {},
+    ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.layout !== void 0 ? { layout: r.layout } : {},
+    ...r.pathQuirks !== void 0 ? { pathQuirks: r.pathQuirks } : {}
+  };
+}
+
+// src/describe/describe.ts
+var dcmjsAny = dcmjs;
+var HEX_TAG_RE2 = /^[0-9a-fA-F]{8}$/;
+var SUPPORTED_MODALITIES = /* @__PURE__ */ new Set(["CT", "PT", "MR", "CR"]);
+function buildHexToKeyword() {
+  const map = /* @__PURE__ */ new Map();
+  const nm = dcmjsAny.data.DicomMetaDictionary.nameMap;
+  if (!nm) return map;
+  for (const [keyword, info] of Object.entries(nm)) {
+    if (info?.tag) {
+      const hex = info.tag.replace(/[(,)]/g, "").toUpperCase();
+      if (hex.length === 8) map.set(hex, keyword);
+    }
+  }
+  return map;
+}
+function resolveKeepTags(keepTags) {
+  const nameMap = dcmjsAny.data.DicomMetaDictionary.nameMap;
+  let hexToKeyword;
+  return keepTags.map((tag) => {
+    if (HEX_TAG_RE2.test(tag)) {
+      hexToKeyword ?? (hexToKeyword = buildHexToKeyword());
+      const keyword = hexToKeyword.get(tag.toUpperCase());
+      if (!keyword) {
+        throw new Error(`describe: unknown hex tag "${tag}"`);
+      }
+      return keyword;
+    }
+    if (nameMap && !Object.hasOwn(nameMap, tag)) {
+      throw new Error(`describe: unknown tag keyword "${tag}"`);
+    }
+    return tag;
+  });
+}
+function* walkFiles(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkFiles(path);
+    } else if (entry.isFile()) {
+      yield path;
+    }
+  }
+}
+function parseFile(path) {
+  try {
+    const buf = readFileSync(path);
+    const ab = buf.buffer.slice(
+      buf.byteOffset,
+      buf.byteOffset + buf.byteLength
+    );
+    const parsed = dcmjsAny.data.DicomMessage.readFile(ab);
+    const record = dcmjsAny.data.DicomMetaDictionary.naturalizeDataset(
+      parsed.dict
+    );
+    return { record, size: buf.byteLength };
+  } catch {
+    return null;
+  }
+}
+function extractTags(record, keepKeywords) {
+  const tags = {};
+  let found = false;
+  for (const keyword of keepKeywords) {
+    const value = record[keyword];
+    if (value !== void 0) {
+      tags[keyword] = value;
+      found = true;
+    }
+  }
+  return found ? tags : void 0;
+}
+function describeDirectory(dir, options = {}) {
+  const keepKeywords = options.keepTags ? resolveKeepTags(options.keepTags) : [];
+  const studies = /* @__PURE__ */ new Map();
+  const stats = { dicomFiles: 0, skipped: 0, unknownModality: 0 };
+  for (const path of [...walkFiles(dir)].sort()) {
+    const parsed = parseFile(path);
+    const studyUid = parsed?.record.StudyInstanceUID;
+    const seriesUid = parsed?.record.SeriesInstanceUID;
+    if (!parsed || typeof studyUid !== "string" || typeof seriesUid !== "string") {
+      stats.skipped++;
+      continue;
+    }
+    const { record } = parsed;
+    stats.dicomFiles++;
+    let modality;
+    if (typeof record.Modality === "string") {
+      if (SUPPORTED_MODALITIES.has(record.Modality)) {
+        modality = record.Modality;
+      } else {
+        stats.unknownModality++;
+      }
+    }
+    const sizeKb = Math.max(1, Math.round(parsed.size / 1024));
+    const tags = keepKeywords.length ? extractTags(record, keepKeywords) : void 0;
+    let study = studies.get(studyUid);
+    if (!study) {
+      study = /* @__PURE__ */ new Map();
+      studies.set(studyUid, study);
+    }
+    let series = study.get(seriesUid);
+    if (!series) {
+      series = /* @__PURE__ */ new Map();
+      study.set(seriesUid, series);
+    }
+    const collapseKey = JSON.stringify([modality ?? null, sizeKb, tags ?? null]);
+    const existing = series.get(collapseKey);
+    if (existing) {
+      existing.count++;
+    } else {
+      series.set(collapseKey, {
+        modality,
+        targetSizeKb: sizeKb,
+        tags,
+        count: 1
+      });
+    }
+  }
+  const studySpecs = [...studies.values()].map((study) => {
+    const seriesSpecs = [...study.values()].map((series) => {
+      const entries = [...series.values()].map((acc) => ({
+        type: "valid-image",
+        ...acc.modality !== void 0 ? { modality: acc.modality } : {},
+        targetSizeKb: acc.targetSizeKb,
+        ...acc.tags !== void 0 ? { tags: acc.tags } : {},
+        ...acc.count > 1 ? { count: acc.count } : {}
+      }));
+      return { entries };
+    });
+    return { series: seriesSpecs };
+  });
+  if (studySpecs.length === 0) {
+    throw new Error(`describe: no DICOM series found in ${dir}`);
+  }
+  const spec = { studies: studySpecs, layout: "hierarchical" };
+  validateDatasetSpec(spec);
+  return { spec, stats };
+}
+export {
+  describeDirectory
+};

package/dist/esm/index.js

@@ -63,6 +63,12 @@ var VALID_LAYOUTS = {
   flat: true,
   hierarchical: true
 };
+var VALID_PATH_QUIRKS = {
+  "trailing-dot": true,
+  unicode: true,
+  "deep-nesting": true,
+  "long-name": true
+};
 var VALID_TRANSFER_SYNTAXES = {
   "explicit-vr-little-endian": true,
   "implicit-vr-little-endian": true
@@ -249,11 +255,20 @@ function validateDatasetSpec(raw) {
   if ("layout" in r) {
     validateEnum(r.layout, VALID_LAYOUTS, "DatasetSpec.layout");
   }
+  if ("pathQuirks" in r) {
+    if (!Array.isArray(r.pathQuirks)) {
+      throw new Error("DatasetSpec.pathQuirks: must be an array");
+    }
+    for (const [i, q] of r.pathQuirks.entries()) {
+      validateEnum(q, VALID_PATH_QUIRKS, `DatasetSpec.pathQuirks[${i}]`);
+    }
+  }
   return {
     ...entries.length > 0 ? { entries } : {},
     ...studies.length > 0 ? { studies } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
-    ...r.layout !== void 0 ? { layout: r.layout } : {}
+    ...r.layout !== void 0 ? { layout: r.layout } : {},
+    ...r.pathQuirks !== void 0 ? { pathQuirks: r.pathQuirks } : {}
   };
 }
 function validateRange(value, path) {
@@ -720,6 +735,48 @@ async function generateFile(spec, options) {
     index
   };
 }
+function hashString(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+var UNICODE_TOKENS = ["\xE9", "\xFC", "\xF1", "\u65E5", "\u2122", "\u03A9"];
+var NEST_DEPTH = 8;
+var LONG_NAME_TARGET = 200;
+function applyPathQuirks(relativePath, quirks) {
+  const segments = relativePath.split("/");
+  let dirs = segments.slice(0, -1);
+  const leaf = segments[segments.length - 1];
+  const dot = leaf.lastIndexOf(".");
+  let stem = dot > 0 ? leaf.slice(0, dot) : leaf;
+  const ext = dot > 0 ? leaf.slice(dot) : "";
+  const unicode = (s) => `${s}${UNICODE_TOKENS[hashString(s) % UNICODE_TOKENS.length]}`;
+  const has = (q) => quirks.includes(q);
+  if (has("deep-nesting")) {
+    dirs = [...dirs, ...Array.from({ length: NEST_DEPTH }, (_, i) => `d${i}`)];
+  }
+  if (has("unicode")) {
+    dirs = dirs.map(unicode);
+    stem = unicode(stem);
+  }
+  if (has("long-name")) {
+    const pad = (s) => s.length < LONG_NAME_TARGET ? s + "x".repeat(LONG_NAME_TARGET - s.length) : s;
+    stem = pad(stem);
+    if (dirs.length > 0) {
+      const last = dirs.length - 1;
+      dirs = dirs.map((d, i) => i === last ? pad(d) : d);
+    }
+  }
+  let newLeaf = stem + ext;
+  if (has("trailing-dot")) {
+    if (dirs.length > 0) dirs = dirs.map((d) => `${d}.`);
+    else newLeaf += ".";
+  }
+  return { relativePath: [...dirs, newLeaf].join("/"), filename: newLeaf };
+}
 function hierarchicalName(studyOrdinal, seriesIndex, instanceNumber) {
   const pad3 = (n) => String(n).padStart(3, "0");
   const name = `${String(instanceNumber).padStart(5, "0")}.dcm`;
@@ -734,15 +791,19 @@ async function* generateCollectionFromSpec(spec) {
   const totalFiles = entryCount(flatEntries) + studyFileCount(studies);
   const padWidth = String(totalFiles).length;
   const hierarchical = spec.layout === "hierarchical";
+  const quirks = spec.pathQuirks ?? [];
+  const decorate = (file) => quirks.length === 0 ? file : { ...file, ...applyPathQuirks(file.relativePath, quirks) };
   let globalIndex = 0;
   for (const entry of flatEntries) {
     const { count = 1, ...fileSpec } = entry;
     for (let i = 0; i < count; i++) {
-      yield generateFile(fileSpec, {
-        index: globalIndex,
-        seed: spec.seed,
-        padWidth
-      });
+      yield decorate(
+        await generateFile(fileSpec, {
+          index: globalIndex,
+          seed: spec.seed,
+          padWidth
+        })
+      );
       globalIndex++;
     }
   }
@@ -774,14 +835,16 @@ async function* generateCollectionFromSpec(spec) {
                 uid: { study: studyUid, series: seriesUid }
               }
             );
-            yield hierarchical ? {
-              ...file,
-              ...hierarchicalName(
-                studyOrdinal,
-                seriesIndex,
-                instanceNumber
-              )
-            } : file;
+            yield decorate(
+              hierarchical ? {
+                ...file,
+                ...hierarchicalName(
+                  studyOrdinal,
+                  seriesIndex,
+                  instanceNumber
+                )
+              } : file
+            );
             globalIndex++;
           }
         }
@@ -808,11 +871,153 @@ async function writeCollectionFromSpec(spec, outDir) {
   return manifest;
 }
 
+// src/describe/describe.ts
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+var dcmjsAny2 = dcmjs;
+var HEX_TAG_RE2 = /^[0-9a-fA-F]{8}$/;
+var SUPPORTED_MODALITIES = /* @__PURE__ */ new Set(["CT", "PT", "MR", "CR"]);
+function buildHexToKeyword() {
+  const map = /* @__PURE__ */ new Map();
+  const nm = dcmjsAny2.data.DicomMetaDictionary.nameMap;
+  if (!nm) return map;
+  for (const [keyword, info] of Object.entries(nm)) {
+    if (info?.tag) {
+      const hex = info.tag.replace(/[(,)]/g, "").toUpperCase();
+      if (hex.length === 8) map.set(hex, keyword);
+    }
+  }
+  return map;
+}
+function resolveKeepTags(keepTags) {
+  const nameMap = dcmjsAny2.data.DicomMetaDictionary.nameMap;
+  let hexToKeyword;
+  return keepTags.map((tag) => {
+    if (HEX_TAG_RE2.test(tag)) {
+      hexToKeyword ?? (hexToKeyword = buildHexToKeyword());
+      const keyword = hexToKeyword.get(tag.toUpperCase());
+      if (!keyword) {
+        throw new Error(`describe: unknown hex tag "${tag}"`);
+      }
+      return keyword;
+    }
+    if (nameMap && !Object.hasOwn(nameMap, tag)) {
+      throw new Error(`describe: unknown tag keyword "${tag}"`);
+    }
+    return tag;
+  });
+}
+function* walkFiles(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkFiles(path);
+    } else if (entry.isFile()) {
+      yield path;
+    }
+  }
+}
+function parseFile(path) {
+  try {
+    const buf = readFileSync(path);
+    const ab = buf.buffer.slice(
+      buf.byteOffset,
+      buf.byteOffset + buf.byteLength
+    );
+    const parsed = dcmjsAny2.data.DicomMessage.readFile(ab);
+    const record = dcmjsAny2.data.DicomMetaDictionary.naturalizeDataset(
+      parsed.dict
+    );
+    return { record, size: buf.byteLength };
+  } catch {
+    return null;
+  }
+}
+function extractTags(record, keepKeywords) {
+  const tags = {};
+  let found = false;
+  for (const keyword of keepKeywords) {
+    const value = record[keyword];
+    if (value !== void 0) {
+      tags[keyword] = value;
+      found = true;
+    }
+  }
+  return found ? tags : void 0;
+}
+function describeDirectory(dir, options = {}) {
+  const keepKeywords = options.keepTags ? resolveKeepTags(options.keepTags) : [];
+  const studies = /* @__PURE__ */ new Map();
+  const stats = { dicomFiles: 0, skipped: 0, unknownModality: 0 };
+  for (const path of [...walkFiles(dir)].sort()) {
+    const parsed = parseFile(path);
+    const studyUid = parsed?.record.StudyInstanceUID;
+    const seriesUid = parsed?.record.SeriesInstanceUID;
+    if (!parsed || typeof studyUid !== "string" || typeof seriesUid !== "string") {
+      stats.skipped++;
+      continue;
+    }
+    const { record } = parsed;
+    stats.dicomFiles++;
+    let modality;
+    if (typeof record.Modality === "string") {
+      if (SUPPORTED_MODALITIES.has(record.Modality)) {
+        modality = record.Modality;
+      } else {
+        stats.unknownModality++;
+      }
+    }
+    const sizeKb = Math.max(1, Math.round(parsed.size / 1024));
+    const tags = keepKeywords.length ? extractTags(record, keepKeywords) : void 0;
+    let study = studies.get(studyUid);
+    if (!study) {
+      study = /* @__PURE__ */ new Map();
+      studies.set(studyUid, study);
+    }
+    let series = study.get(seriesUid);
+    if (!series) {
+      series = /* @__PURE__ */ new Map();
+      study.set(seriesUid, series);
+    }
+    const collapseKey = JSON.stringify([modality ?? null, sizeKb, tags ?? null]);
+    const existing = series.get(collapseKey);
+    if (existing) {
+      existing.count++;
+    } else {
+      series.set(collapseKey, {
+        modality,
+        targetSizeKb: sizeKb,
+        tags,
+        count: 1
+      });
+    }
+  }
+  const studySpecs = [...studies.values()].map((study) => {
+    const seriesSpecs = [...study.values()].map((series) => {
+      const entries = [...series.values()].map((acc) => ({
+        type: "valid-image",
+        ...acc.modality !== void 0 ? { modality: acc.modality } : {},
+        targetSizeKb: acc.targetSizeKb,
+        ...acc.tags !== void 0 ? { tags: acc.tags } : {},
+        ...acc.count > 1 ? { count: acc.count } : {}
+      }));
+      return { entries };
+    });
+    return { series: seriesSpecs };
+  });
+  if (studySpecs.length === 0) {
+    throw new Error(`describe: no DICOM series found in ${dir}`);
+  }
+  const spec = { studies: studySpecs, layout: "hierarchical" };
+  validateDatasetSpec(spec);
+  return { spec, stats };
+}
+
 // src/public-fixtures/catalog.ts
-import { readFileSync } from "node:fs";
-import { dirname as dirname2, join } from "node:path";
+import { readFileSync as readFileSync2 } from "node:fs";
+import { dirname as dirname2, join as join2 } from "node:path";
 import { fileURLToPath } from "node:url";
-var bundledCatalogPath = join(
+var bundledCatalogPath = join2(
   dirname2(fileURLToPath(import.meta.url)),
   "../../data/public-cases.json"
 );
@@ -823,7 +1028,7 @@ function loadDefaultCases() {
   return loadCasesFromJson(defaultPublicCasesPath());
 }
 function loadCasesFromJson(casesJsonPath) {
-  const j = JSON.parse(readFileSync(casesJsonPath, "utf8"));
+  const j = JSON.parse(readFileSync2(casesJsonPath, "utf8"));
   if (!Array.isArray(j.cases)) {
     throw new Error(
       `Invalid catalog in ${casesJsonPath}: expected "cases" array`
@@ -841,12 +1046,12 @@ function loadCaseById(casesJsonPath, id) {
 
 // src/public-fixtures/fetch.ts
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync as mkdirSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir } from "node:os";
-import { join as join2 } from "node:path";
-var DEFAULT_CACHE_ROOT = join2(homedir(), ".cache", "dicom-synth-testcases");
+import { join as join3 } from "node:path";
+var DEFAULT_CACHE_ROOT = join3(homedir(), ".cache", "dicom-synth-testcases");
 function caseCachePath(sha256, root = DEFAULT_CACHE_ROOT) {
-  return join2(root, sha256, "file.dcm");
+  return join3(root, sha256, "file.dcm");
 }
 function verifySha256(buffer, expected) {
   const h = createHash("sha256").update(buffer).digest("hex");
@@ -864,11 +1069,11 @@ async function fetchPublicCaseToCache(record, cacheRoot = DEFAULT_CACHE_ROOT) {
   }
   const dest = caseCachePath(record.sha256, cacheRoot);
   if (existsSync(dest)) {
-    const buf2 = readFileSync2(dest);
+    const buf2 = readFileSync3(dest);
     verifySha256(buf2, record.sha256);
     return dest;
   }
-  mkdirSync3(join2(cacheRoot, record.sha256), { recursive: true });
+  mkdirSync3(join3(cacheRoot, record.sha256), { recursive: true });
   const res = await fetch(record.source.url);
   if (!res.ok) {
     throw new Error(
@@ -957,6 +1162,7 @@ function resolveParametricSpec(spec) {
 export {
   caseCachePath,
   defaultPublicCasesPath,
+  describeDirectory,
   fetchPublicCaseToCache,
   generateCollectionFromSpec,
   generateFile,

package/dist/esm/schema/validate.js

@@ -17,6 +17,12 @@ var VALID_LAYOUTS = {
   flat: true,
   hierarchical: true
 };
+var VALID_PATH_QUIRKS = {
+  "trailing-dot": true,
+  unicode: true,
+  "deep-nesting": true,
+  "long-name": true
+};
 var VALID_TRANSFER_SYNTAXES = {
   "explicit-vr-little-endian": true,
   "implicit-vr-little-endian": true
@@ -203,11 +209,20 @@ function validateDatasetSpec(raw) {
   if ("layout" in r) {
     validateEnum(r.layout, VALID_LAYOUTS, "DatasetSpec.layout");
   }
+  if ("pathQuirks" in r) {
+    if (!Array.isArray(r.pathQuirks)) {
+      throw new Error("DatasetSpec.pathQuirks: must be an array");
+    }
+    for (const [i, q] of r.pathQuirks.entries()) {
+      validateEnum(q, VALID_PATH_QUIRKS, `DatasetSpec.pathQuirks[${i}]`);
+    }
+  }
   return {
     ...entries.length > 0 ? { entries } : {},
     ...studies.length > 0 ? { studies } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
-    ...r.layout !== void 0 ? { layout: r.layout } : {}
+    ...r.layout !== void 0 ? { layout: r.layout } : {},
+    ...r.pathQuirks !== void 0 ? { pathQuirks: r.pathQuirks } : {}
   };
 }
 function validateRange(value, path) {

package/dist/types/describe/describe.d.ts

@@ -0,0 +1,13 @@
+import type { DatasetSpec } from '../schema/types.js';
+export type DescribeOptions = {
+    keepTags?: string[];
+};
+export type DescribeResult = {
+    spec: DatasetSpec;
+    stats: {
+        dicomFiles: number;
+        skipped: number;
+        unknownModality: number;
+    };
+};
+export declare function describeDirectory(dir: string, options?: DescribeOptions): DescribeResult;

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
 export { type CollectionManifest, type GeneratedFile, generateCollectionFromSpec, generateFile, writeCollectionFromSpec, } from './collection/writer.js';
+export { type DescribeOptions, type DescribeResult, describeDirectory, } from './describe/describe.js';
 export { defaultPublicCasesPath, loadCaseById, loadCasesFromJson, loadDefaultCases, type PublicCaseRecord, type PublicCaseSource, } from './public-fixtures/catalog.js';
 export { caseCachePath, fetchPublicCaseToCache, verifySha256, } from './public-fixtures/fetch.js';
 export { resolveParametricSpec } from './schema/parametric.js';
-export type { DatasetLayout, DatasetSpec, DicomdirSpec, DicomTagOverrides, FakeSignatureSpec, FileSpec, ImageSpec, InvalidUidImageSpec, Modality, NonDicomSpec, ParametricEdgeCase, ParametricSpec, ParametricStudies, Range, SeriesEntrySpec, SeriesSpec, StudySpec, TransferSyntax, ValidImageSpec, VendorWarningsImageSpec, ViolationClass, } from './schema/types.js';
+export type { DatasetLayout, DatasetSpec, DicomdirSpec, DicomTagOverrides, FakeSignatureSpec, FileSpec, ImageSpec, InvalidUidImageSpec, Modality, NonDicomSpec, ParametricEdgeCase, ParametricSpec, ParametricStudies, PathQuirk, Range, SeriesEntrySpec, SeriesSpec, StudySpec, TransferSyntax, ValidImageSpec, VendorWarningsImageSpec, ViolationClass, } from './schema/types.js';
 export { validateDatasetSpec, validateParametricSpec, } from './schema/validate.js';

package/dist/types/schema/types.d.ts

@@ -55,11 +55,13 @@ export type StudySpec = {
     count?: number;
 };
 export type DatasetLayout = 'flat' | 'hierarchical';
+export type PathQuirk = 'trailing-dot' | 'unicode' | 'deep-nesting' | 'long-name';
 export type DatasetSpec = {
     entries?: EntrySpec[];
     studies?: StudySpec[];
     seed?: number;
     layout?: DatasetLayout;
+    pathQuirks?: PathQuirk[];
 };
 export type Range = number | {
     min: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dicom-synth",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Toolkit for synthetic DICOM fixtures and public fixture fetch/cache.",
   "license": "Apache-2.0",
   "type": "module",
@@ -23,7 +23,8 @@
   "types": "dist/types/index.d.ts",
   "bin": {
     "dicom-synth-generate": "./bin/dicom-synth-generate.mjs",
-    "dicom-synth-fetch": "./bin/dicom-synth-fetch.mjs"
+    "dicom-synth-fetch": "./bin/dicom-synth-fetch.mjs",
+    "dicom-synth-describe": "./bin/dicom-synth-describe.mjs"
   },
   "exports": {
     ".": {
@@ -82,7 +83,7 @@
     "@typescript-eslint/eslint-plugin": "^8.46.1",
     "@typescript-eslint/parser": "^8.46.1",
     "dcmjs": "^0.51.1",
-    "esbuild": "^0.25.9",
+    "esbuild": "^0.28.1",
     "eslint": "^9.38.0",
     "globals": "^16.4.0",
     "husky": "^9.1.7",