config2ts 2.9.0 → 2.10.0

package/README.md

@@ -1,181 +1,227 @@
-# config2ts
-
-convert config to ts file.
-
-# install
-
-run command: `npm install -g config2ts`
-
-# documentation
-
-Full documentation is published via GitHub Pages (this repo has Pages enabled):
-
-- English: https://livingyang.github.io/config2ts/
-- 中文: https://livingyang.github.io/config2ts/index-zh.html
-
-# usage
-
-`config2ts` supports two output modes selected by `-m, --mode`:
-
-- `single` (default): merge every table into one file (`-n`, default `csv.ts`).
-- `split`: write one `.ts` file per table plus an auto-generated `index.ts`.
-
-This repo's `config/` folder ships example outputs generated from the same source
-tables, so you can compare both layouts directly:
-
-- single mode example: [`config/total.ts`](config/total.ts)
-- split mode example: [`config/split/`](config/split/) (one file per table + `index.ts`)
-
-## single mode
-
-Merge all config tables into a single TypeScript file.
-
-```bash
-config2ts -d config -o dist -m single -n csv.ts -a public
-```
-
-- `-n` is the merged output file name (default `csv.ts`).
-- `-a` is optional; omit it to skip `assets.ts`.
-- Example output: [`config/total.ts`](config/total.ts) — all tables as `export namespace XxxCsv { ... }` in one file.
-
-## split mode
-
-Write one `.ts` file per config table (named after the source file, e.g.
-`skill.csv` → `skill.ts`) plus an auto-generated `index.ts` that re-exports every
-table and `assets.ts`. Cross-table `Ref`/`RefEnum`/`Template` references are
-resolved with `import` statements injected at the top of the referencing file, so
-every table is independently usable and tree-shakable.
-
-```bash
-config2ts -d config -o dist -m split -a public
-```
-
-- `-n` is reused as the index file name; the single-mode default `csv.ts` is
-  replaced by `index.ts` unless you pass `-n` explicitly.
-- `-a` is optional; omit it to skip `assets.ts`.
-- Example output: [`config/split/`](config/split/) — `z-base.ts`, `a-user.ts`,
-  `skill.ts`, … , `assets.ts`, and `index.ts`.
-
-Output layout under `dist`:
-
-```
-dist/
-  z-base.ts        # export namespace ZBaseCsv { ... }
-  a-user.ts        # import { ZBaseCsv } from "./z-base"; export namespace AUserCsv { ... }
-  skill.ts
-  ...
-  assets.ts        # generated only when -a is given
-  index.ts         # export * from "./z-base"; export * from "./a-user"; ...; export * from "./assets";
-```
-
-Notes:
-- Tables are emitted in topological order; a table only `import`s tables it
-  actually references, and missing/circular references print the same warnings as
-  single mode.
-
-# support type
-
-| csv field  |  typescript type  |
-| :--------: | :---------------: |
-|   Index    |      string       |
-|   String   |      string       |
-|   Number   |      number       |
-|  Boolean   |     boolean       |
-|    Enum    |       type        |
-| EnumIndex  |       type        |
-| String[]   |     string[]      |
-| Number[]   |     number[]      |
-|  Enum[]    |      type[]       |
-|    Ref     | namespace.Record  |
-| RefEnum    | namespace.type    |
-| RefEnum[]  | namespace.type[]  |
-|  Template  | namespace.Record  |
-| Template[] | namespace.Record[] |
-|   Object   |   type (Record)   |
-|  Object[]  | type[] (Record[]) |
-
-* `Number` support Infinity and NaN
-* `Enum` support empty string type
-* `Enum[]` union contains every value actually present in the data (including `""` for empty slots)
-* `EnumIndex` will generate index type, and will use `Enum` type to generate interface
-* `Ref` / `RefEnum` reference another csv's Record/enum by id: `Ref[file]` is one row (`file.Map["id"]`), `Ref[file][]` is an array of rows with comma-separated ids (`[file.Map["1"],file.Map["2"]]`, typed `File.Record[]`); use `Object[]` for inline private structures and `Ref[]` for shared, identity-bearing rows
-* `Template[file]` inherits a whole row from another table and overrides selected fields: a cell is `<baseId>|<key>:<value>,<key>:<value>` — a pipe separates the base row id from override pairs (e.g. `101|damage:150,range:8`), emitting `{ ...file.Map["101"], damage: 150, range: 8 }` typed `File.Record`; with no overrides the cell is just the id and emits a plain `file.Map["id"]` like `Ref`. Override values may be bare scalars or bracket-wrapped composites mirroring the generated TS syntax — arrays as `[v1,v2]` (e.g. `Params:[6,2.07]`, required for array-typed fields; a bare `Params:6,2.07` gets chopped by the pair comma and prints a warning) and flat objects as `{k:v,k:v}`. `Template[file][]` separates entries with `;` (the same element separator as `Object[]`), e.g. `101|damage:150;102|heal:500` emits `[{ ...file.Map["101"], damage: 150 },{ ...file.Map["102"], heal: 500 }]`. Override key typos and value-type mismatches fail at tsc compile time; overrides are flat top-level fields (no dot-path deep merge), and the target table must have an Index/EnumIndex Map
-* Merge order is resolved automatically: tables are topologically sorted so every referenced table (`Ref`/`RefEnum`/`Template`) is emitted before the tables referencing it — no filename tricks needed; tables without a dependency relation keep alphabetical order. Circular references (`a.csv -> b.csv -> a.csv`) and references to missing files print a warning
-* `Object` parse `key:value,key:value` format, auto-infer value types (number/boolean/string), generates a dedicated `type` that merges all keys
-* `Object[]` separates objects with `;` while commas still separate `key:value` pairs inside each object (same syntax as the `Object` type), e.g. `num:1,,str:a;num:2` makes `[{num:1,str:'a'},{num:2}]`, a bare `;` makes `[{},{}]`; generates a dedicated element `type` merging all keys with the field typed as `type[]`
-* Array convention: primitive arrays (`String[]`/`Number[]`/`Enum[]`/`RefEnum[...] []`) separate elements with `,` and `Object[]` separates objects with `;`; raw cell values are normalized (CRLF/CR unified to LF, whitespace trimmed); an empty cell generates `[]`; otherwise n separators make n+1 slots and every slot is kept (including interior or trailing ones) so parallel arrays stay index-aligned. Empty slots use the type's own zero value — `''` for string/enum/ref-enum, `0` for number, `{}` for empty object slots; `null` is never generated
-* Line breaks inside a cell (quote-wrapped in CSV) are preserved for `String` fields (emitted as `\n`) and act as the equivalent separator in structural fields — a line feed equals a comma between array elements / Object pairs / Template override pairs, and equals a semicolon between Object[] elements / Template[] entries (one entry per line works; a blank line is an empty slot by the n+1 rule). Scalar fields (Number/Boolean/Enum/single Ref) have no separator semantics, so a line break there prints a warning and must be removed
-* unrecognized field types fall back to `string` and print a warning (check for typos)
-
-## assets2ts
-
-Scan assets directory and generate an `assets.ts` index file with nested resource tree.
-
-- `-a, --assets <path>` set assets resource directory (optional, skip asset index if omitted)
-- Output file: `assets.ts` (alongside the merged config file)
-- File and directory names are used exactly as-is (e.g., `Direction.png` → `Direction`, `adjust-horizontal.png` → `'adjust-horizontal'`); keys with special characters are automatically quoted
-- `type` field uses file extension (lowercase), e.g. `'png'`, `'mp3'`, `'svg'`
-- Directories containing 2+ files of the same extension get a dedicated type (e.g. `PngAsset`, `Mp3Asset`) and `satisfies Record<string, XxxAsset>` annotation
-- Directories with ≤1 file or mixed extensions do not get a type annotation
-- Nested directories are supported (e.g. `public/sub/image/`)
-
-### generated example
-
-```typescript
-// Auto Generated by config2ts, DO NOT EDIT
-
-export type Mp3Asset = { path: string; type: 'mp3' };
-export type PngAsset = { path: string; type: 'png' };
-export type SvgAsset = { path: string; type: 'svg' };
-
-export const ASSETS = {
-    public: {
-        image: {
-            'adjust-horizontal': {path:'public/image/adjust-horizontal.png',type:'png'},
-            Direction: {path:'public/image/Direction.png',type:'png'}
-        } satisfies Record<string, PngAsset>,
-        music: {
-            effect1: {path:'public/music/effect1.mp3',type:'mp3'},
-            effect2: {path:'public/music/effect2.mp3',type:'mp3'}
-        } satisfies Record<string, Mp3Asset>,
-        'single-file': {
-            effect1: {path:'public/single-file/effect1.mp3',type:'mp3'}
-        }
-    }
-};
-```
-
-### usage
-
-```typescript
-import { ASSETS } from "./assets";
-
-const meta = ASSETS.public.image.Direction;
-// meta.path → 'public/image/Direction.png'
-// meta.type → 'png'
-
-const adjustMeta = ASSETS.public.image['adjust-horizontal'];
-// adjustMeta.path → 'public/image/adjust-horizontal.png'
-```
-
-## Options
-
-```
-  Options:
-
-    -h, --help             output usage information
-    -V, --version          output the version number
-    -d, --dir <path>       set convert path. default: ./
-    -o, --outDir <path>    set outDir path. default: same as -d
-    -n, --name <name>      output file name (single mode) / index file name (split mode). default: csv.ts
-    -a, --assets <path>    set assets resource directory for asset index (optional, skip asset index if omitted)
-    -m, --mode <mode>      output mode: single (merge into one file) or split (one file per table + index.ts). default: single
-```
-
-## supported file formats
-
-| format | extension |
-| :----: | :-------: |
-|  csv   |   .csv    |
-|  ini   |   .ini    |
-|  toml  |   .toml   |
+# config2ts
+
+convert config to ts file.
+
+# install
+
+run command: `npm install -g config2ts`
+
+# documentation
+
+Full documentation is published via GitHub Pages (this repo has Pages enabled):
+
+- English: https://livingyang.github.io/config2ts/#/docs/en
+- 中文: https://livingyang.github.io/config2ts/#/docs/zh
+
+Both the documentation pages and the per-feature demo cases are served by the
+Vue site in [`website/`](website/) (built into `docs/`).
+
+# usage
+
+`config2ts` supports two output modes selected by `-m, --mode`:
+
+- `single` (default): merge every table into one file (`-n`, default `csv.ts`).
+- `split`: write one `.ts` file per table plus an auto-generated `index.ts`.
+
+Every case under [`fixtures/`](fixtures/) pairs its source tables with the
+single-mode merge of those tables, so you can compare input and output directly
+(the demo site renders the same pairs):
+
+- single mode example: [`fixtures/03-cross-ref/expected.ts`](fixtures/03-cross-ref/expected.ts)
+- split mode: one file per table plus `index.ts` (layout shown below)
+
+## fixtures (single source of truth)
+
+The [`fixtures/`](fixtures/) folder holds one self-contained case directory per
+feature (`01-basic-types`, `03-cross-ref`, ...). Each case contains its source
+tables plus a committed golden file `expected.ts` generated from them. The same
+`(input.csv, expected.ts)` pairs are used by the golden-file unit tests
+([`tests/fixtures.test.ts`](tests/fixtures.test.ts)) and by the demo site, so
+documentation, tests and demos can never drift from actual tool behavior.
+
+A case may also use subdirectories: when every csv file inside a subdirectory
+shares the same header and type rows, they are merged into ONE table named
+after the directory (`fixtures/08-story/story/*.csv` → `StoryCsv`) — see
+[fixtures/08-story](fixtures/08-story) and the "Isomorphic subdirectory merge"
+section of the docs.
+
+- Regenerate golden files: `npm run fixtures:regen` (rebuilds lib, then rewrites
+  every `expected.ts`) — review the diff manually before committing; never
+  blindly rewrite a failing golden file.
+- Tests: every case is regenerated in-memory and compared byte-for-byte against
+  its golden file, and all golden files are additionally checked with `tsc`.
+- [`tests/golden/merged-formats.expected.ts`](tests/golden/merged-formats.expected.ts)
+  is a composite golden: it merges tables from several cases (CSV with refs +
+  INI + TOML) in a single call, which per-case goldens can't cover. It is
+  regenerated by the same `fixtures:regen` run.
+
+## demo site
+
+[`website/`](website/) is a Vue3 + Vite site that renders every fixture case as
+an input → output comparison page. It reads the same `fixtures/` pairs the tests
+verify via `import.meta.glob(..., { query: "?raw" })` — no copies, no codegen —
+so the demo can never drift from actual tool behavior.
+
+- Local dev: `npm run demo:dev`
+- Build: `npm run demo:build` — output goes to `docs/`, published on GitHub
+  Pages at `/config2ts/` (the site owns the Pages root; `docs/` holds only the
+  build output)
+
+## single mode
+
+Merge all config tables into a single TypeScript file.
+
+```bash
+config2ts -d fixtures/03-cross-ref -o dist -m single -n csv.ts
+```
+
+- `-n` is the merged output file name (default `csv.ts`).
+- `-a` is optional; omit it to skip `assets.ts` (e.g. `-a public` indexes this
+  repo's sample asset tree).
+- Example output: [`fixtures/03-cross-ref/expected.ts`](fixtures/03-cross-ref/expected.ts) — all tables as `export namespace XxxCsv { ... }` in one file.
+
+## split mode
+
+Write one `.ts` file per config table (named after the source file, e.g.
+`skill.csv` → `skill.ts`) plus an auto-generated `index.ts` that re-exports every
+table and `assets.ts`. Cross-table `Ref`/`RefEnum`/`Template` references are
+resolved with `import` statements injected at the top of the referencing file, so
+every table is independently usable and tree-shakable.
+
+```bash
+config2ts -d fixtures/03-cross-ref -o dist -m split -a public
+```
+
+- `-n` is reused as the index file name; the single-mode default `csv.ts` is
+  replaced by `index.ts` unless you pass `-n` explicitly.
+- `-a` is optional; omit it to skip `assets.ts`.
+- Example output: one file per table (`z-base.ts`, `a-user.ts`, `skill.ts`, …),
+  plus `assets.ts` and `index.ts` (layout below).
+
+Output layout under `dist`:
+
+```
+dist/
+  z-base.ts        # export namespace ZBaseCsv { ... }
+  a-user.ts        # import { ZBaseCsv } from "./z-base"; export namespace AUserCsv { ... }
+  skill.ts
+  ...
+  assets.ts        # generated only when -a is given
+  index.ts         # export * from "./z-base"; export * from "./a-user"; ...; export * from "./assets";
+```
+
+Notes:
+- Tables are emitted in topological order; a table only `import`s tables it
+  actually references, and missing/circular references print the same warnings as
+  single mode.
+
+# support type
+
+| csv field  |  typescript type  |
+| :--------: | :---------------: |
+|   Index    |      string       |
+|   String   |      string       |
+|   Number   |      number       |
+|  Boolean   |     boolean       |
+|    Enum    |       type        |
+| EnumIndex  |       type        |
+| String[]   |     string[]      |
+| Number[]   |     number[]      |
+|  Enum[]    |      type[]       |
+|    Ref     | namespace.Record  |
+| RefEnum    | namespace.type    |
+| RefEnum[]  | namespace.type[]  |
+|  RefTable  | namespace.Record[] |
+| RefTable[] | namespace.Record[][] |
+|  Template  | namespace.Record  |
+| Template[] | namespace.Record[] |
+|   Object   |   type (Record)   |
+|  Object[]  | type[] (Record[]) |
+
+* `Number` support Infinity and NaN
+* `Enum` support empty string type
+* `Enum[]` union contains every value actually present in the data (including `""` for empty slots)
+* `EnumIndex` will generate index type, and will use `Enum` type to generate interface
+* `Ref` / `RefEnum` reference another csv's Record/enum by id: `Ref[table]` is one row (`table.Map["id"]`), `Ref[table][]` is an array of rows with comma-separated ids (`[table.Map["1"],table.Map["2"]]`, typed `File.Record[]`); use `Object[]` for inline private structures and `Ref[]` for shared, identity-bearing rows
+* `Template[table]` inherits a whole row from another table and overrides selected fields: a cell is `<baseId>|<key>:<value>,<key>:<value>` — a pipe separates the base row id from override pairs (e.g. `101|damage:150,range:8`), emitting `{ ...table.Map["101"], damage: 150, range: 8 }` typed `File.Record`; with no overrides the cell is just the id and emits a plain `table.Map["id"]` like `Ref`. Override values may be bare scalars or bracket-wrapped composites mirroring the generated TS syntax — arrays as `[v1,v2]` (e.g. `Params:[6,2.07]`, required for array-typed fields; a bare `Params:6,2.07` gets chopped by the pair comma and prints a warning) and flat objects as `{k:v,k:v}`. `Template[table][]` separates entries with `;` (the same element separator as `Object[]`), e.g. `101|damage:150;102|heal:500` emits `[{ ...table.Map["101"], damage: 150 },{ ...table.Map["102"], heal: 500 }]`. Override key typos and value-type mismatches fail at tsc compile time; overrides are flat top-level fields (no dot-path deep merge), and the target table must have an Index/EnumIndex Map
+* Reference targets are written as **table names without the extension** (`Ref[skill]` → `skill.csv`); the full file name (`Ref[skill.csv]`) still works, and an ambiguous stem (`skill.csv` + `skill.ini`) warns and needs the full name
+* **Homogeneous subdirectories merge into one table named after the directory**: when every csv in a subdirectory shares the same header and type rows, `story/ch01.csv` … → `StoryCsv`, rows concatenated in file-name order. The merged table has no flat `List`; it exports `FileMap` grouped by member file plus `type File = "ch01" | ...` and `refTable(file: File)`; `RefTable[story]` references a whole member sub-table by file name (typed `StoryCsv.Record[]`, `File` union makes an unknown name a compile error). Member files that nothing references are allowed. See [`fixtures/08-story`](fixtures/08-story)
+* Merge order is resolved automatically: tables are topologically sorted so every referenced table (`Ref`/`RefEnum`/`Template`/`RefTable`) is emitted before the tables referencing it — no filename tricks needed; tables without a dependency relation keep alphabetical order. Circular references (`a.csv -> b.csv -> a.csv`) and references to missing files print a warning
+* `Object` parse `key:value,key:value` format, auto-infer value types (number/boolean/string), generates a dedicated `type` that merges all keys
+* `Object[]` separates objects with `;` while commas still separate `key:value` pairs inside each object (same syntax as the `Object` type), e.g. `num:1,,str:a;num:2` makes `[{num:1,str:'a'},{num:2}]`, a bare `;` makes `[{},{}]`; generates a dedicated element `type` merging all keys with the field typed as `type[]`
+* Array convention: primitive arrays (`String[]`/`Number[]`/`Enum[]`/`RefEnum[...] []`) separate elements with `,` and `Object[]` separates objects with `;`; raw cell values are normalized (CRLF/CR unified to LF, whitespace trimmed); an empty cell generates `[]`; otherwise n separators make n+1 slots and every slot is kept (including interior or trailing ones) so parallel arrays stay index-aligned. Empty slots use the type's own zero value — `''` for string/enum/ref-enum, `0` for number, `{}` for empty object slots; `null` is never generated
+* Line breaks inside a cell (quote-wrapped in CSV) are preserved for `String` fields (emitted as `\n`) and act as the equivalent separator in structural fields — a line feed equals a comma between array elements / Object pairs / Template override pairs, and equals a semicolon between Object[] elements / Template[] entries (one entry per line works; a blank line is an empty slot by the n+1 rule). Scalar fields (Number/Boolean/Enum/single Ref) have no separator semantics, so a line break there prints a warning and must be removed
+* unrecognized field types fall back to `string` and print a warning (check for typos)
+
+## assets2ts
+
+Scan assets directory and generate an `assets.ts` index file with nested resource tree.
+
+- `-a, --assets <path>` set assets resource directory (optional, skip asset index if omitted)
+- Output file: `assets.ts` (alongside the merged config file)
+- File and directory names are used exactly as-is (e.g., `Direction.png` → `Direction`, `adjust-horizontal.png` → `'adjust-horizontal'`); keys with special characters are automatically quoted
+- `type` field uses file extension (lowercase), e.g. `'png'`, `'mp3'`, `'svg'`
+- Directories containing 2+ files of the same extension get a dedicated type (e.g. `PngAsset`, `Mp3Asset`) and `satisfies Record<string, XxxAsset>` annotation
+- Directories with ≤1 file or mixed extensions do not get a type annotation
+- Nested directories are supported (e.g. `public/sub/image/`)
+
+### generated example
+
+```typescript
+// Auto Generated by config2ts, DO NOT EDIT
+
+export type Mp3Asset = { path: string; type: 'mp3' };
+export type PngAsset = { path: string; type: 'png' };
+export type SvgAsset = { path: string; type: 'svg' };
+
+export const ASSETS = {
+    public: {
+        image: {
+            'adjust-horizontal': {path:'public/image/adjust-horizontal.png',type:'png'},
+            Direction: {path:'public/image/Direction.png',type:'png'}
+        } satisfies Record<string, PngAsset>,
+        music: {
+            effect1: {path:'public/music/effect1.mp3',type:'mp3'},
+            effect2: {path:'public/music/effect2.mp3',type:'mp3'}
+        } satisfies Record<string, Mp3Asset>,
+        'single-file': {
+            effect1: {path:'public/single-file/effect1.mp3',type:'mp3'}
+        }
+    }
+};
+```
+
+### usage
+
+```typescript
+import { ASSETS } from "./assets";
+
+const meta = ASSETS.public.image.Direction;
+// meta.path → 'public/image/Direction.png'
+// meta.type → 'png'
+
+const adjustMeta = ASSETS.public.image['adjust-horizontal'];
+// adjustMeta.path → 'public/image/adjust-horizontal.png'
+```
+
+## Options
+
+```
+  Options:
+
+    -h, --help             output usage information
+    -V, --version          output the version number
+    -d, --dir <path>       set convert path. default: ./
+    -o, --outDir <path>    set outDir path. default: same as -d
+    -n, --name <name>      output file name (single mode) / index file name (split mode). default: csv.ts
+    -a, --assets <path>    set assets resource directory for asset index (optional, skip asset index if omitted)
+    -m, --mode <mode>      output mode: single (merge into one file) or split (one file per table + index.ts). default: single
+```
+
+## supported file formats
+
+| format | extension |
+| :----: | :-------: |
+|  csv   |   .csv    |
+|  ini   |   .ini    |
+|  toml  |   .toml   |

package/lib/config2ts.d.ts

@@ -1,7 +1,22 @@
-type ConvertHandler = (str: string, moduleName: string) => string;
+type ConvertHandler = (str: string, moduleName: string, subTables?: SubTableInfo[]) => string;
 export declare const Convert: Record<string, ConvertHandler>;
 export declare function assets2ts(assetsDir: string): string;
 export declare function GetTsString(filePath: string): string;
+export interface SubTableInfo {
+    name: string;
+    rowCount: number;
+}
+export interface ConvertUnit {
+    name: string;
+    ext: string;
+    content: string;
+    sourcePaths: string[];
+    refs: string[];
+    subTables?: SubTableInfo[];
+}
+export declare function resolveTableName(ref: string, names: Iterable<string>): string | null;
+export declare function collectConvertUnits(dir: string): ConvertUnit[];
+export declare function GetTsStringFromUnits(units: ConvertUnit[]): string;
 export declare function GetTsStringFromFileList(fileList: string[]): string;
 export declare function GetValidFileList(fileList: string[]): string[];
 export declare function startConvert(dir: string, outDir: string, merge: string, assetsDir?: string, mode?: "single" | "split"): void;

package/lib/config2ts.js

@@ -36,6 +36,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Convert = void 0;
 exports.assets2ts = assets2ts;
 exports.GetTsString = GetTsString;
+exports.resolveTableName = resolveTableName;
+exports.collectConvertUnits = collectConvertUnits;
+exports.GetTsStringFromUnits = GetTsStringFromUnits;
 exports.GetTsStringFromFileList = GetTsStringFromFileList;
 exports.GetValidFileList = GetValidFileList;
 exports.startConvert = startConvert;
@@ -54,6 +57,7 @@ const ObjectArrayString = "Object[]";
 const RefPrefix = "Ref[";
 const RefSuffix = "]";
 const RefEnumPrefix = "RefEnum[";
+const RefTablePrefix = "RefTable[";
 const RefEnumArraySuffix = "][]";
 const TemplatePrefix = "Template[";
 // Inside a Template cell, '|' separates the referenced base row id from the
@@ -66,18 +70,30 @@ exports.Convert = {
         const obj = toml.parse(str);
         return `export const ${moduleName} = ${json5.stringify(obj, null, 4)};`;
     },
-    csv: function (str, moduleName) {
-        return csv2ts(str, moduleName);
+    csv: function (str, moduleName, subTables) {
+        return csv2ts(str, moduleName, subTables);
     },
     toml: function (str, moduleName) {
         const obj = toml.parse(str);
         return `export const ${moduleName} = ${json5.stringify(obj, null, 4)};`;
     },
 };
-function csv2ts(csvString, moduleName) {
+function csv2ts(csvString, moduleName, subTables) {
     let convert = {};
     const refFields = [];
     const refEnumFields = [];
+    // Sub-table binding for merged subdirectories: each data row is tagged with
+    // the member file it came from, so the namespace can export a FileMap
+    // (file name -> that file's rows) in addition to the flat List.
+    const groupOffsets = [];
+    if (subTables && subTables.length > 0) {
+        let cursor = 0;
+        for (const subTable of subTables) {
+            groupOffsets.push({ name: subTable.name, start: cursor, end: cursor + subTable.rowCount });
+            cursor += subTable.rowCount;
+        }
+    }
+    const rowGroups = [];
     const result = (0, d3_dsv_1.csvParse)(csvString, function (d, i) {
         if (i === 0) {
             convert = d;
@@ -95,6 +111,11 @@ function csv2ts(csvString, moduleName) {
             return null;
         }
         else {
+            const dataRowIndex = i - 1;
+            if (groupOffsets.length > 0) {
+                const group = groupOffsets.find((g) => dataRowIndex >= g.start && dataRowIndex < g.end);
+                rowGroups[dataRowIndex] = group ? group.name : undefined;
+            }
             for (const k in d) {
                 d[k] = normalizeCell(d[k]);
                 // Line feeds are preserved on purpose for free-form String fields
@@ -174,6 +195,19 @@ function csv2ts(csvString, moduleName) {
                         d[k] = entry;
                     }
                 }
+                else if (parseRefTable(convert[k])) {
+                    const refTable = parseRefTable(convert[k]);
+                    if (refTable.isArray) {
+                        const names = splitStringArray(d[k]);
+                        d[k] = names;
+                        if (names.includes("")) {
+                            console.warn(`[config2ts] warning: ${moduleName} row ${i} field "${k}" ref-table array contains an empty file name`);
+                        }
+                    }
+                    else if (d[k] === "") {
+                        console.warn(`[config2ts] warning: ${moduleName} row ${i} field "${k}" ref-table value is empty`);
+                    }
+                }
                 else {
                     d[k] = String(d[k]);
                 }
@@ -182,6 +216,11 @@ function csv2ts(csvString, moduleName) {
         }
     });
     delete result.columns;
+    if (groupOffsets.length > 0 && rowGroups.length !== groupOffsets[groupOffsets.length - 1].end) {
+        console.warn(`[config2ts] warning: ${moduleName} sub-table row counts do not match the merged content, FileMap will not be generated`);
+        groupOffsets.length = 0;
+        rowGroups.length = 0;
+    }
     if (result.length <= 0) {
         return "";
     }
@@ -280,6 +319,11 @@ function csv2ts(csvString, moduleName) {
                 const refModuleName = changeCase.pascalCase(refEnum.refModule);
                 fieldType = refEnum.isArray ? `${refModuleName}.${refEnum.refField}[]` : `${refModuleName}.${refEnum.refField}`;
             }
+            else if (parseRefTable(convert[field])) {
+                const refTable = parseRefTable(convert[field]);
+                const refModuleName = changeCase.pascalCase(refTable.refModule);
+                fieldType = refTable.isArray ? `${refModuleName}.Record[][]` : `${refModuleName}.Record[]`;
+            }
             else if (parseTemplate(convert[field])) {
                 const template = parseTemplate(convert[field]);
                 const refModuleName = changeCase.pascalCase(template.refModule);
@@ -294,18 +338,27 @@ function csv2ts(csvString, moduleName) {
     }
     template += "    };\n\n";
     if (indexField) {
-        const filteredResult = result.filter((v) => {
-            return v[indexField] !== "";
-        });
-        for (let i = 0; i < filteredResult.length; i++) {
-            result[i] = filteredResult[i];
+        const kept = [];
+        for (let i = 0; i < result.length; i++) {
+            if (result[i][indexField] !== "") {
+                kept.push(i);
+            }
         }
-        result.length = filteredResult.length;
+        // Compact result and rowGroups in lockstep so each row keeps its sub-table
+        // tag even when empty-index rows are dropped.
+        for (let i = 0; i < kept.length; i++) {
+            result[i] = result[kept[i]];
+            rowGroups[i] = rowGroups[kept[i]];
+        }
+        result.length = kept.length;
+        rowGroups.length = kept.length;
     }
-    template += "    export const List: Record[] = [\n";
+    // Serialize every surviving row once; the same literals feed both the flat
+    // List and the per-file FileMap groups.
+    const rowStrings = [];
     for (let i = 0; i < result.length; i++) {
         const row = result[i];
-        template += "        {\n";
+        let rowString = "        {\n";
         for (const field in convert) {
             let value = row[field];
             if (parseRef(convert[field])) {
@@ -313,10 +366,21 @@ function csv2ts(csvString, moduleName) {
                 const refModuleName = changeCase.pascalCase(ref.refModule);
                 if (ref.isArray) {
                     const refs = value.map((id) => `${refModuleName}.Map[${JSON.stringify(id)}]`).join(",");
-                    template += `            ${serializeField(field)}: [${refs}],\n`;
+                    rowString += `            ${serializeField(field)}: [${refs}],\n`;
                 }
                 else {
-                    template += `            ${serializeField(field)}: ${refModuleName}.Map[${JSON.stringify(value)}],\n`;
+                    rowString += `            ${serializeField(field)}: ${refModuleName}.Map[${JSON.stringify(value)}],\n`;
+                }
+            }
+            else if (parseRefTable(convert[field])) {
+                const refTable = parseRefTable(convert[field]);
+                const refModuleName = changeCase.pascalCase(refTable.refModule);
+                if (refTable.isArray) {
+                    const names = value.map((name) => `${refModuleName}.refTable(${JSON.stringify(name)})`).join(",");
+                    rowString += `            ${serializeField(field)}: [${names}],\n`;
+                }
+                else {
+                    rowString += `            ${serializeField(field)}: ${refModuleName}.refTable(${JSON.stringify(value)}),\n`;
                 }
             }
             else if (parseTemplate(convert[field])) {
@@ -324,26 +388,65 @@ function csv2ts(csvString, moduleName) {
                 const refModuleName = changeCase.pascalCase(templateType.refModule);
                 if (templateType.isArray) {
                     const entries = value.map((entry) => serializeTemplateEntry(entry, refModuleName)).join(",");
-                    template += `            ${serializeField(field)}: [${entries}],\n`;
+                    rowString += `            ${serializeField(field)}: [${entries}],\n`;
                 }
                 else {
-                    template += `            ${serializeField(field)}: ${serializeTemplateEntry(value, refModuleName)},\n`;
+                    rowString += `            ${serializeField(field)}: ${serializeTemplateEntry(value, refModuleName)},\n`;
                 }
             }
             else {
-                template += `            ${serializeField(field)}: ${json5.stringify(value)},\n`;
+                rowString += `            ${serializeField(field)}: ${json5.stringify(value)},\n`;
             }
         }
-        template += "        }";
-        if (i < result.length - 1) {
-            template += ",";
+        rowString += "        }";
+        rowStrings.push(rowString);
+    }
+    // A merged subdirectory exposes its rows through FileMap only — a flat List
+    // would duplicate every row literal.
+    if (groupOffsets.length === 0) {
+        template += "    export const List: Record[] = [\n";
+        for (let i = 0; i < rowStrings.length; i++) {
+            template += rowStrings[i];
+            if (i < rowStrings.length - 1) {
+                template += ",";
+            }
+            template += "\n";
         }
-        template += "\n";
+        template += "    ];\n\n";
+    }
+    if (groupOffsets.length > 0) {
+        // The FileMap keys are a literal union of the member file names, so a
+        // RefTable cell that names a file which does not exist fails at tsc
+        // compile time (FileMap["ch99"] is not indexable) instead of silently
+        // producing undefined at runtime. A mapped type is used instead of
+        // `Record<File, ...>` because the namespace's own `Record` interface
+        // shadows the global utility type; it also rejects a missing group.
+        const fileNames = groupOffsets.map((group) => JSON.stringify(group.name));
+        template += `    export type File = ${fileNames.join(" | ")};\n`;
+        template += `    export const FileList: File[] = [${fileNames.join(", ")}];\n\n`;
+        template += "    export const FileMap: { [file in File]: Record[] } = {\n";
+        for (const group of groupOffsets) {
+            template += `        ${serializeField(group.name)}: [\n`;
+            for (let i = group.start; i < group.end; i++) {
+                template += rowStrings[i] + ",\n";
+            }
+            template += "        ],\n";
+        }
+        template += "    };\n\n";
+        // RefTable resolves through this accessor instead of indexing FileMap
+        // directly: indexing an unknown literal key is only an error under
+        // noImplicitAny, while passing a wrong argument to a `File` parameter is
+        // an error under every tsc flag combination.
+        template += "    export function refTable(file: File): Record[] { return FileMap[file]; }\n\n";
     }
-    template += "    ];\n\n";
     if (indexField != null) {
         template += "    export const Map: { [id: string]: Record } = {};\n";
-        template += `    for (const v of List) { Map[v.${indexField}] = v; };\n\n`;
+        if (groupOffsets.length > 0) {
+            template += `    for (const file in FileMap) { for (const v of FileMap[file]) { Map[v.${indexField}] = v; } };\n\n`;
+        }
+        else {
+            template += `    for (const v of List) { Map[v.${indexField}] = v; };\n\n`;
+        }
     }
     template += "};";
     return template;
@@ -441,6 +544,9 @@ function isKnownType(typeStr) {
     if (parseRefEnum(typeStr)) {
         return true;
     }
+    if (parseRefTable(typeStr)) {
+        return true;
+    }
     if (parseTemplate(typeStr)) {
         return true;
     }
@@ -465,6 +571,10 @@ function isStructuralType(typeStr) {
     if (refEnum && refEnum.isArray) {
         return true;
     }
+    const refTable = parseRefTable(typeStr);
+    if (refTable && refTable.isArray) {
+        return true;
+    }
     if (parseTemplate(typeStr)) {
         return true;
     }
@@ -510,6 +620,29 @@ function parseRefEnum(typeStr) {
     }
     return null;
 }
+// Parse RefTable[module] (single) and RefTable[module][] (array of sub-table
+// references). A RefTable cell holds a sub-table file name of a merged
+// subdirectory unit (the exported FileMap key) and resolves to that file's
+// row list. The prefixes are matched in full, so "RefTable[" never collides
+// with "Ref[" / "RefEnum[".
+function parseRefTable(typeStr) {
+    if (!typeStr.startsWith(RefTablePrefix)) {
+        return null;
+    }
+    let isArray = false;
+    let inner = typeStr;
+    if (typeStr.endsWith(RefEnumArraySuffix)) {
+        isArray = true;
+        inner = typeStr.slice(0, -RefEnumArraySuffix.length) + RefSuffix;
+    }
+    if (inner.startsWith(RefTablePrefix) && inner.endsWith(RefSuffix)) {
+        const refModule = inner.slice(RefTablePrefix.length, -RefSuffix.length);
+        if (refModule !== "") {
+            return { refModule, isArray };
+        }
+    }
+    return null;
+}
 // Parse Template[module] (single) and Template[module][] (array of templated
 // row references). "Template[" starts with 'T', so it never collides with the
 // "Ref[" / "RefEnum[" prefixes.
@@ -636,6 +769,13 @@ function GetFileExt(filePath) {
     const pathObject = path.parse(filePath);
     return pathObject.ext.slice(1);
 }
+// Read a config file and strip the UTF-8 BOM Excel likes to add.
+function readConfigFile(filePath) {
+    let fileString = fs.readFileSync(filePath).toString();
+    if (fileString.charAt(0) === "\uFEFF")
+        fileString = fileString.substr(1);
+    return fileString;
+}
 function scanDir(dir, basePath) {
     const node = {};
     let hasContent = false;
@@ -754,14 +894,10 @@ function assets2ts(assetsDir) {
     return template;
 }
 function GetTsString(filePath) {
-    const pathObject = path.parse(filePath);
     const handle = exports.Convert[GetFileExt(filePath)];
     if (handle) {
-        const moduleName = changeCase.pascalCase(pathObject.base);
-        let fileString = fs.readFileSync(filePath).toString();
-        if (fileString.charAt(0) === "\uFEFF")
-            fileString = fileString.substr(1);
-        return handle(fileString, moduleName);
+        const moduleName = changeCase.pascalCase(path.parse(filePath).base);
+        return handle(readConfigFile(filePath), moduleName);
     }
     else {
         return "";
@@ -770,23 +906,17 @@ function GetTsString(filePath) {
 // Collect the config file names a CSV references from its type row
 // (Ref[file], RefEnum[file.field], Template[file] and their array forms).
 // ini/toml files never reference other config tables.
-function collectCsvReferences(filePath) {
-    if (GetFileExt(filePath) !== "csv") {
-        return [];
-    }
-    let fileString = fs.readFileSync(filePath).toString();
-    if (fileString.charAt(0) === "\uFEFF") {
-        fileString = fileString.substr(1);
-    }
+function collectCsvReferencesFromContent(csvString) {
     const references = [];
-    (0, d3_dsv_1.csvParse)(fileString, function (d, i) {
+    (0, d3_dsv_1.csvParse)(csvString, function (d, i) {
         if (i === 0) {
             for (const k in d) {
                 const typeStr = d[k];
                 const ref = parseRef(typeStr);
                 const refEnum = parseRefEnum(typeStr);
+                const refTable = parseRefTable(typeStr);
                 const template = parseTemplate(typeStr);
-                const target = ref ? ref.refModule : refEnum ? refEnum.refModule : template ? template.refModule : null;
+                const target = ref ? ref.refModule : refEnum ? refEnum.refModule : refTable ? refTable.refModule : template ? template.refModule : null;
                 if (target && !references.includes(target)) {
                     references.push(target);
                 }
@@ -796,31 +926,263 @@ function collectCsvReferences(filePath) {
     });
     return references;
 }
-// Order files so every referenced table is emitted before the table that
+// Resolve a table reference to a full unit name. References are written
+// without the extension by default ("Ref[skill]" -> "skill.csv"), matching
+// how table names read in generated code (pascalCase("skill.csv") ===
+// "SkillCsv"). Exact unit names still win, so legacy refs that spell out the
+// extension ("Ref[skill.csv]") keep working; a stem shared by several units
+// (e.g. skill.csv + skill.ini) is ambiguous and reported.
+function resolveTableName(ref, names) {
+    const nameList = Array.from(names);
+    if (nameList.includes(ref)) {
+        return ref;
+    }
+    const stemMatches = nameList.filter((name) => path.parse(name).name === ref);
+    if (stemMatches.length === 1) {
+        return stemMatches[0];
+    }
+    if (stemMatches.length > 1) {
+        console.warn(`[config2ts] warning: table reference "${ref}" is ambiguous (${stemMatches.join(", ")}), write the full file name in the ref`);
+    }
+    return null;
+}
+// Rewrite the type row's table references from stem form to full unit names,
+// so downstream steps (namespace derivation, import lines, dependency
+// sorting) keep matching refs against unit names exactly. The content is only
+// re-serialized when something actually changed.
+function normalizeCsvRefs(content, allNames) {
+    if (allNames.size === 0) {
+        return content;
+    }
+    const rows = (0, d3_dsv_1.csvParseRows)(content);
+    if (rows.length < 2) {
+        return content;
+    }
+    let changed = false;
+    rows[1] = rows[1].map((cell) => {
+        const ref = parseRef(cell);
+        if (ref) {
+            const resolved = resolveTableName(ref.refModule, allNames);
+            if (resolved) {
+                changed = true;
+                return `Ref[${resolved}]` + (ref.isArray ? "[]" : "");
+            }
+            return cell;
+        }
+        const refEnum = parseRefEnum(cell);
+        if (refEnum) {
+            const resolved = resolveTableName(refEnum.refModule, allNames);
+            if (resolved) {
+                changed = true;
+                return `RefEnum[${resolved}.${refEnum.refField}]` + (refEnum.isArray ? "[]" : "");
+            }
+            return cell;
+        }
+        const refTable = parseRefTable(cell);
+        if (refTable) {
+            const resolved = resolveTableName(refTable.refModule, allNames);
+            if (resolved) {
+                changed = true;
+                return `RefTable[${resolved}]` + (refTable.isArray ? "[]" : "");
+            }
+            return cell;
+        }
+        const template = parseTemplate(cell);
+        if (template) {
+            const resolved = resolveTableName(template.refModule, allNames);
+            if (resolved) {
+                changed = true;
+                return `Template[${resolved}]` + (template.isArray ? "[]" : "");
+            }
+            return cell;
+        }
+        return cell;
+    });
+    return changed ? (0, d3_dsv_1.csvFormatRows)(rows) : content;
+}
+function makeFileUnit(filePath, allNames) {
+    const name = path.basename(filePath);
+    const ext = GetFileExt(name);
+    const content = readConfigFile(filePath);
+    const normalized = ext === "csv" && allNames ? normalizeCsvRefs(content, allNames) : content;
+    return {
+        name,
+        ext,
+        content: normalized,
+        sourcePaths: [filePath],
+        refs: ext === "csv" ? collectCsvReferencesFromContent(normalized) : [],
+    };
+}
+// A subdirectory whose convertible files are ALL csv and share identical
+// header + type rows is merged into one virtual table named after the
+// directory ("<dir>.csv" -> pascalCase -> "<Dir>Csv"). Data rows are
+// concatenated in file-name order, so per-chapter/per-language splits stay
+// manageable on disk while the runtime sees a single table.
+function tryMergeSubdir(dir, dirName, allNames) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile());
+    const files = entries
+        .map((e) => path.join(dir, e.name))
+        .filter((f) => exports.Convert[GetFileExt(f)] != null)
+        .sort();
+    if (files.length === 0) {
+        console.warn(`[config2ts] warning: directory "${dirName}" contains no convertible config files, skipped`);
+        return null;
+    }
+    const nonCsv = files.filter((f) => GetFileExt(f) !== "csv");
+    if (nonCsv.length > 0) {
+        console.warn(`[config2ts] warning: directory "${dirName}" mixes non-csv files (${nonCsv.map((f) => path.basename(f)).join(", ")}), cannot merge into one table, skipped`);
+        return null;
+    }
+    const contents = files.map(readConfigFile);
+    const headRows = contents.map((c) => (0, d3_dsv_1.csvParseRows)(c).slice(0, 2));
+    const headKey = JSON.stringify(headRows[0]);
+    const uniform = headRows.every((rows) => rows.length === 2 && JSON.stringify(rows) === headKey);
+    if (!uniform) {
+        console.warn(`[config2ts] warning: directory "${dirName}" contains csv files with different header/type rows, cannot merge into one table, skipped`);
+        return null;
+    }
+    // Keep the first file's header + type rows once; every following file
+    // contributes its data rows only.
+    const allRows = [
+        ...(0, d3_dsv_1.csvParseRows)(contents[0]),
+        ...contents.slice(1).flatMap((c) => (0, d3_dsv_1.csvParseRows)(c).slice(2)),
+    ];
+    const mergedContent = (0, d3_dsv_1.csvFormatRows)(allRows);
+    const keyType = headRows[0][1][0];
+    if (keyType === IndexStr || keyType === EnumIndexStr) {
+        const seen = new Set();
+        for (let i = 2; i < allRows.length; i++) {
+            const key = allRows[i][0];
+            if (key !== "" && seen.has(key)) {
+                console.warn(`[config2ts] warning: merged table "${dirName}" has duplicate ${keyType} key "${key}"`);
+            }
+            seen.add(key);
+        }
+    }
+    const name = dirName.endsWith(".csv") ? dirName : dirName + ".csv";
+    const subTables = files.map((f, i) => ({
+        name: path.parse(f).name,
+        rowCount: Math.max(0, (0, d3_dsv_1.csvParseRows)(contents[i]).length - 2),
+    }));
+    const mergedRefsContent = allNames ? normalizeCsvRefs(mergedContent, allNames) : mergedContent;
+    return {
+        name,
+        ext: "csv",
+        content: mergedRefsContent,
+        sourcePaths: files,
+        refs: collectCsvReferencesFromContent(mergedRefsContent),
+        subTables,
+    };
+}
+// RefTable cells must name an existing member file of the target merged
+// table. The generated FileMap is keyed by a literal union, so a wrong name
+// also fails tsc; checking here surfaces the mistake at conversion time with
+// the valid keys listed, and without needing a compile step.
+function validateRefTableValues(units) {
+    var _a;
+    const unitByName = new Map();
+    for (const unit of units) {
+        unitByName.set(unit.name, unit);
+    }
+    for (const unit of units) {
+        if (unit.ext !== "csv")
+            continue;
+        const rows = (0, d3_dsv_1.csvParseRows)(unit.content);
+        if (rows.length < 2)
+            continue;
+        const headerRow = rows[0];
+        const typeRow = rows[1];
+        for (let column = 0; column < typeRow.length; column++) {
+            const refTable = parseRefTable(typeRow[column]);
+            if (!refTable)
+                continue;
+            const target = unitByName.get(refTable.refModule);
+            if (!target)
+                continue;
+            if (!target.subTables) {
+                // The target table exists but is a plain file, so it has no FileMap /
+                // refTable() at all — the generated call would fail tsc with a
+                // confusing "property does not exist" error, so say it plainly here.
+                console.warn(`[config2ts] warning: ${unit.name} field "${headerRow[column]}" uses RefTable[${refTable.refModule}], but "${target.name}" is not a merged subdirectory table (it has no sub-tables)`);
+                continue;
+            }
+            const validKeys = new Set(target.subTables.map((subTable) => subTable.name));
+            for (let rowIndex = 2; rowIndex < rows.length; rowIndex++) {
+                const cell = normalizeCell((_a = rows[rowIndex][column]) !== null && _a !== void 0 ? _a : "");
+                const names = refTable.isArray ? splitStringArray(cell) : cell === "" ? [] : [cell];
+                for (const name of names) {
+                    if (name !== "" && !validKeys.has(name)) {
+                        // Row numbers follow the other csv warnings: the type row is 0,
+                        // so the first data row (csvParseRows index 2) is row 1.
+                        console.warn(`[config2ts] warning: ${unit.name} row ${rowIndex - 1} field "${headerRow[column]}" references sub-table "${name}" which does not exist in "${target.name}" (valid: ${Array.from(validKeys).join(", ")})`);
+                    }
+                }
+            }
+        }
+    }
+}
+// Resolve a config directory into convert units: every convertible file
+// becomes one unit; every subdirectory is merged into a single unit when its
+// csv files are homogeneous (warned and skipped otherwise). Unit names are
+// predicted first, so extension-less table refs in the type rows can be
+// resolved before dependency collection.
+function collectConvertUnits(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1));
+    const allNames = new Set();
+    for (const entry of entries) {
+        if (entry.isFile()) {
+            if (exports.Convert[GetFileExt(entry.name)] == null)
+                continue;
+            allNames.add(entry.name);
+        }
+        else if (entry.isDirectory()) {
+            allNames.add(entry.name.endsWith(".csv") ? entry.name : entry.name + ".csv");
+        }
+    }
+    const units = [];
+    const takenNames = new Set();
+    const take = function (unit) {
+        if (takenNames.has(unit.name)) {
+            console.warn(`[config2ts] warning: duplicate table name "${unit.name}", the generated namespaces will collide`);
+        }
+        takenNames.add(unit.name);
+        units.push(unit);
+    };
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isFile()) {
+            if (exports.Convert[GetFileExt(entry.name)] == null)
+                continue;
+            take(makeFileUnit(full, allNames));
+        }
+        else if (entry.isDirectory()) {
+            const merged = tryMergeSubdir(full, entry.name, allNames);
+            if (merged)
+                take(merged);
+        }
+    }
+    validateRefTableValues(units);
+    return units;
+}
+// Order units so every referenced table is emitted before the table that
 // references it (a referenced namespace must exist when the referencing
 // table's data initializes), so authors no longer need filename tricks (e.g.
-// an "!" prefix) to control order. Files without a dependency relation keep
-// their alphabetical order. References to missing files and circular
+// an "!" prefix) to control order. Units without a dependency relation keep
+// their alphabetical order. References to missing tables and circular
 // references are reported; a cycle is broken at the back edge so output is
 // still generated (the runtime data still needs the cycle fixed by hand).
-function sortFilesByReferences(fileList) {
-    const ordered = fileList.slice().sort((a, b) => {
-        const baseA = path.basename(a);
-        const baseB = path.basename(b);
-        return baseA < baseB ? -1 : baseA > baseB ? 1 : 0;
-    });
-    const fileByBase = new Map();
-    for (const filePath of ordered) {
-        fileByBase.set(path.basename(filePath), filePath);
+function sortUnitsByReferences(units) {
+    const ordered = units.slice().sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const unitByName = new Map();
+    for (const unit of ordered) {
+        unitByName.set(unit.name, unit);
     }
-    const depsByBase = new Map();
-    for (const filePath of ordered) {
-        const base = path.basename(filePath);
-        const deps = collectCsvReferences(filePath);
-        depsByBase.set(base, deps);
-        for (const dep of deps) {
-            if (!fileByBase.has(dep)) {
-                console.warn(`[config2ts] warning: ${base} references "${dep}" but no config file with that name was found in the config directory`);
+    const depsByName = new Map();
+    for (const unit of ordered) {
+        depsByName.set(unit.name, unit.refs);
+        for (const dep of unit.refs) {
+            if (!unitByName.has(dep)) {
+                console.warn(`[config2ts] warning: ${unit.name} references "${dep}" but no config file with that name was found in the config directory`);
             }
         }
     }
@@ -828,62 +1190,76 @@ function sortFilesByReferences(fileList) {
     // 0 = unvisited, 1 = visiting (on the current DFS trail), 2 = done
     const state = new Map();
     const reportedCycles = new Set();
-    function visit(base, trail) {
+    function visit(name, trail) {
         var _a, _b;
-        const current = (_a = state.get(base)) !== null && _a !== void 0 ? _a : 0;
+        const current = (_a = state.get(name)) !== null && _a !== void 0 ? _a : 0;
         if (current === 2) {
             return;
         }
         if (current === 1) {
-            const cycleStart = trail.indexOf(base);
-            const cycleKey = trail.slice(cycleStart).concat(base).join(" -> ");
+            const cycleStart = trail.indexOf(name);
+            const cycleKey = trail.slice(cycleStart).concat(name).join(" -> ");
             if (!reportedCycles.has(cycleKey)) {
                 reportedCycles.add(cycleKey);
                 console.warn(`[config2ts] warning: circular table reference detected: ${cycleKey}; tables in the cycle may reference an undefined namespace at runtime, please break the reference cycle`);
             }
             return;
         }
-        state.set(base, 1);
-        trail.push(base);
-        for (const dep of (_b = depsByBase.get(base)) !== null && _b !== void 0 ? _b : []) {
-            if (fileByBase.has(dep)) {
+        state.set(name, 1);
+        trail.push(name);
+        for (const dep of (_b = depsByName.get(name)) !== null && _b !== void 0 ? _b : []) {
+            if (unitByName.has(dep)) {
                 visit(dep, trail);
             }
         }
         trail.pop();
-        state.set(base, 2);
-        sorted.push(fileByBase.get(base));
+        state.set(name, 2);
+        sorted.push(unitByName.get(name));
     }
-    for (const filePath of ordered) {
-        visit(path.basename(filePath), []);
+    for (const unit of ordered) {
+        visit(unit.name, []);
     }
     return sorted;
 }
-function GetTsStringFromFileList(fileList) {
-    return sortFilesByReferences(fileList)
-        .map(function (filePath) {
-        return GetTsString(filePath);
-    })
+function renderUnit(unit) {
+    const moduleName = changeCase.pascalCase(unit.name);
+    // Merged subdirectories render through the sub-table-aware path so the
+    // generated namespace also exposes FileMap (file name -> rows).
+    if (unit.ext === "csv" && unit.subTables && unit.subTables.length > 0) {
+        return csv2ts(unit.content, moduleName, unit.subTables);
+    }
+    const handle = exports.Convert[unit.ext];
+    if (!handle) {
+        return "";
+    }
+    return handle(unit.content, moduleName);
+}
+function GetTsStringFromUnits(units) {
+    return sortUnitsByReferences(units)
+        .map(renderUnit)
         .join("\n\n");
 }
+function GetTsStringFromFileList(fileList) {
+    const allNames = new Set(fileList.map((filePath) => path.basename(filePath)));
+    return GetTsStringFromUnits(fileList.map((filePath) => makeFileUnit(filePath, allNames)));
+}
 function GetValidFileList(fileList) {
     return fileList.filter(function (filePath) {
         return exports.Convert[GetFileExt(filePath)] != null;
     });
 }
 // Build the `import { XxxCsv } from "./xxx";` lines a split-mode file needs so
-// its cross-table Ref/RefEnum/Template references resolve. `collectCsvReferences`
-// returns the full base filenames (e.g. "z-base.csv") of referenced tables, which
-// map 1:1 to the split output file "./z-base.ts" and to the namespace
+// its cross-table Ref/RefEnum/Template references resolve. `unit.refs` holds the
+// full base names (e.g. "z-base.csv") of referenced tables, which map 1:1 to
+// the split output file "./z-base.ts" and to the namespace
 // `pascalCase("z-base.csv")` === "ZBaseCsv".
-function buildImportLines(filePath, validBases) {
-    const base = path.basename(filePath);
-    const refs = collectCsvReferences(filePath).filter((ref) => ref !== base);
+function buildImportLines(unit, validNames) {
+    const refs = unit.refs.filter((ref) => ref !== unit.name);
     const imported = new Set();
     const lines = [];
     for (const ref of refs) {
-        if (!validBases.has(ref)) {
-            continue; // missing referenced table; already warned by sortFilesByReferences
+        if (!validNames.has(ref)) {
+            continue; // missing referenced table; already warned by sortUnitsByReferences
         }
         if (imported.has(ref)) {
             continue;
@@ -896,24 +1272,22 @@ function buildImportLines(filePath, validBases) {
     return lines.join("\n");
 }
 function startConvert(dir, outDir, merge, assetsDir, mode = "single") {
-    const fileList = fs.readdirSync(dir);
-    const fullFileList = GetValidFileList(fileList).map(function (filename) {
-        return path.join(dir, filename);
-    });
+    const units = collectConvertUnits(dir);
+    const fileCount = units.reduce((n, u) => n + u.sourcePaths.length, 0);
     if (mode === "split") {
-        const validBases = new Set(fullFileList.map((f) => path.basename(f)));
-        const orderedFiles = sortFilesByReferences(fullFileList);
+        const validNames = new Set(units.map((u) => u.name));
+        const orderedUnits = sortUnitsByReferences(units);
         const exportedNames = [];
-        for (const filePath of orderedFiles) {
-            const base = path.basename(filePath);
-            const outName = path.parse(base).name + ".ts";
-            exportedNames.push(path.parse(base).name);
-            const imports = buildImportLines(filePath, validBases);
-            const body = GetTsString(filePath);
+        for (const unit of orderedUnits) {
+            const outName = path.parse(unit.name).name + ".ts";
+            exportedNames.push(path.parse(unit.name).name);
+            const imports = buildImportLines(unit, validNames);
+            const body = renderUnit(unit);
             const content = AutoGenHeader + (imports ? imports + "\n\n" : "") + body + "\n";
             const outPath = path.join(outDir, outName);
             fs.writeFileSync(outPath, content, { encoding: "utf-8" });
-            console.log(`config2ts, ${base} -> ${outPath}`);
+            const source = unit.sourcePaths.length > 1 ? `${unit.name} (${unit.sourcePaths.length} files)` : path.basename(unit.sourcePaths[0]);
+            console.log(`config2ts, ${source} -> ${outPath}`);
         }
         let assetsExport = null;
         if (assetsDir) {
@@ -937,12 +1311,12 @@ function startConvert(dir, outDir, merge, assetsDir, mode = "single") {
         }
         const indexPath = path.join(outDir, indexName);
         fs.writeFileSync(indexPath, indexContent, { encoding: "utf-8" });
-        console.log(`config2ts, ${orderedFiles.length} config files, split mode, index: ${indexPath}`);
+        console.log(`config2ts, ${orderedUnits.length} config tables (${fileCount} files), split mode, index: ${indexPath}`);
         return;
     }
     const mergeFile = path.join(outDir, merge);
-    fs.writeFileSync(mergeFile, AutoGenHeader + GetTsStringFromFileList(fullFileList), { encoding: "utf-8" });
-    console.log(`config2ts, ${fullFileList.length} config files, merge into: ${mergeFile}`);
+    fs.writeFileSync(mergeFile, AutoGenHeader + GetTsStringFromUnits(units), { encoding: "utf-8" });
+    console.log(`config2ts, ${units.length} config tables (${fileCount} files), merge into: ${mergeFile}`);
     if (assetsDir) {
         const assetsOutput = assets2ts(assetsDir);
         if (assetsOutput) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "config2ts",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "Generate type-safe TypeScript from CSV/INI/TOML config tables — inferred types, enums, cross-table references, and a typed asset index, all from one CLI command.",
   "main": "lib/config2ts.js",
   "types": "lib/config2ts.d.ts",
@@ -13,9 +13,12 @@
   ],
   "scripts": {
     "build": "tsc",
-    "convert": "node ./bin/config2ts -n total.ts -d ./config -o ./config",
-    "test": "jest",
-    "watch-test": "node_modules/.bin/jest --watch"
+    "fixtures:regen": "npm run build && node ./scripts/regen-fixtures.js",
+    "demo:dev": "npm --prefix website run dev",
+    "demo:build": "npm --prefix website run build",
+    "pretest": "node -e \"require('fs').rmSync('.test-build',{recursive:true,force:true})\"",
+    "test": "npm run build && tsc -p tsconfig.test.json && node --test \".test-build/tests/*.test.js\"",
+    "test:coverage": "npm run build && tsc -p tsconfig.test.json && node --test --experimental-test-coverage \".test-build/tests/*.test.js\""
   },
   "repository": {
     "type": "git",
@@ -39,19 +42,7 @@
     "toml": "^4.1.2"
   },
   "devDependencies": {
-    "@types/jest": "^30.0.0",
     "@types/node": "^24.5.2",
-    "jest": "^30.5.1",
-    "ts-jest": "^29.4.12",
     "typescript": "^5.9.2"
-  },
-  "overrides": {
-    "@babel/core": "^7.29.6",
-    "browserslist": "^4.28.7",
-    "handlebars": "^4.7.9",
-    "js-yaml": "^3.14.2",
-    "minimatch@^3.0.0": "^3.1.3",
-    "picomatch@^2.0.0": "^2.3.2",
-    "brace-expansion@^1.0.0": "^1.1.16"
   }
 }