dicom-synth 1.6.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.

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

@@ -40,6 +40,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
@@ -226,11 +232,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 } : {}
   };
 }
 

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++;
           }
         }

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/index.d.ts

@@ -3,5 +3,5 @@ export { type DescribeOptions, type DescribeResult, describeDirectory, } from '.
 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.6.0",
+  "version": "1.7.0",
   "description": "Toolkit for synthetic DICOM fixtures and public fixture fetch/cache.",
   "license": "Apache-2.0",
   "type": "module",