dicom-synth 1.5.0 → 1.6.0

package/README.md

@@ -417,6 +417,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 +484,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 +569,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 +578,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 +607,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/describe/describe.js

@@ -0,0 +1,378 @@
+// 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_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");
+  }
+  return {
+    ...entries.length > 0 ? { entries } : {},
+    ...studies.length > 0 ? { studies } : {},
+    ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.layout !== void 0 ? { layout: r.layout } : {}
+  };
+}
+
+// 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

@@ -808,11 +808,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 +965,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 +983,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 +1006,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 +1099,7 @@ function resolveParametricSpec(spec) {
 export {
   caseCachePath,
   defaultPublicCasesPath,
+  describeDirectory,
   fetchPublicCaseToCache,
   generateCollectionFromSpec,
   generateFile,

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,4 +1,5 @@
 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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dicom-synth",
-  "version": "1.5.0",
+  "version": "1.6.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",