firebase-contract 0.1.0-rc.6 → 0.1.0-rc.8

package/README.md

@@ -69,6 +69,50 @@ generators:
   (REST path with `{param}` segments dropped).
 - Entries reference declarations by name — nearest first (same yml → root).
 
+#### Output settings: `file`, `split`, `options`, `header`
+
+Every declaration (and any entry-level application) can reshape the output —
+the defaults reproduce each generator's built-in layout, so omitting them
+changes nothing:
+
+```yaml
+generators:
+  - generator: api-dto
+    out: "src/entries/{path}/dto"
+    file: "{api-name}.dto.ts"   # file-name template (default shown)
+    split: true                 # one file per api (api-dto's default)
+  - generator: api-types
+    out: "#contracts/api-types"
+    file: "{api-name}.types.ts" # override the bundled default with per-api files
+    split: true
+    options:
+      typesImport: "../types"   # where `import type { … } from '…'` points
+  - generator: typescript
+    out: "#contracts"
+    file: models.ts             # rename a single-file/barrel output
+    split: true                 # document scope: switches to typescript-split
+```
+
+- **`file`** — output file name. Api scope: a template (`{api-name}`/`{path}`
+  allowed when `split: true`). Document scope: renames the single output file,
+  or the barrel for `-split` variants.
+- **`split`** — api scope: `true` emits one file per api (the `file` template
+  must contain a placeholder), `false` bundles everything into one `file`.
+  Document scope: `true` swaps to the generator's `-split` variant
+  (`typescript` → `typescript-split`, …) and errors when none exists.
+- **`options`** — free-form string map passed through to the generator.
+  Currently: `typesImport` (api-types, task-payloads, data-connect-operations)
+  overrides the `./types` import path.
+- **`header`** — per-generator banner override: `default` for the built-in
+  AUTO-GENERATED banner, any text for a custom comment, `""` to suppress the
+  banner for this generator. Wins over the contract-level `header:` and the
+  CLI `--header` flag.
+- Defaults per generator: `api-types` → `api-types.ts` bundled, `api-validation`
+  → `api-validation.ts` bundled, `task-payloads` → `task-payloads.ts` bundled,
+  `api-dto` → `{api-name}.dto.ts` split.
+- Entry-level settings override the declaration, which overrides the
+  generator's default (same nearest-first rule as `out`).
+
 `fbc generate contract.yml` materializes **all** declared outputs across the
 whole import graph in one run. Passing `-o`/`-g` switches to single-target mode
 (`fbc generate <entry> -o <dir> -g typescript,zod`), and
@@ -88,6 +132,34 @@ fbc generate --header "Managed by fbc"   # custom text (multi-line ok)
 header: default        # or any text; the CLI --header flag wins
 ```
 
+Header text (contract `header:`, per-generator `header`, CLI `--header`)
+supports `${...}` template variables:
+
+| Variable | Value |
+| --- | --- |
+| `${rootContractPath}` | entry (root) yml path, relative to the root yml's directory |
+| `${currentContractPath}` | the yml the output is generated from |
+| `${allContractPath}` | import chain root → current, joined with ` -> ` |
+| `${generatedAt}` | date the file was **first** generated (carried over on regenerate) |
+| `${updatedAt}` | date the content **last changed** |
+
+A regenerate that produces identical content keeps both dates and reproduces
+the file byte-for-byte, so `--check` stays drift-free; when content changes,
+`generatedAt` is carried over from the existing file and only `updatedAt`
+moves. Date tokens accept an optional format — `${updatedAt:yyyy-mm-dd HH:mm:ss}`
+— with runs `yyyy`/`yy`, `MM`, `dd`, `HH`, `ss`, and `mm` meaning month before
+any hour token / minute after one (both `yyyy-mm-dd` and `HH:mm` read
+naturally). Default: `yyyy-MM-dd`.
+
+The `default` banner includes the source and dates:
+
+```
+// AUTO-GENERATED by firebase-contract. Do not edit by hand.
+// Source: ${currentContractPath}
+// Generated: ${generatedAt} / Updated: ${updatedAt}
+// Regenerate with: fbc generate
+```
+
 Comment syntax adapts per file type (`//` for TS, `#` for GraphQL/YAML-ish,
 `--` for SQL).
 
@@ -360,8 +432,8 @@ apis:                                      # https/callable, keyed by REST path
 Generator application resolves in two tiers — the section `defaults`
 (`apis:/tasks:/events:` → `defaults.generators`) and the entry's own
 `generators:` (which replaces the defaults). `apis:` keys must be REST paths
-(`/...`) with an `operationId`; tasks and Pub/Sub events live in their own
-sections.
+(`/...` or `METHOD /...` so the same route can appear once per verb) with an
+`operationId`; tasks and Pub/Sub events live in their own sections.
 
 For `createCatalog` this yields `CreateCatalogTaskData`, `CreateCatalogTaskPayload =
 RetryTaskPayload<CreateCatalogTaskData>`, and `CREATE_CATALOG_MAX_ATTEMPTS`, plus the
@@ -516,7 +588,7 @@ project:
 | `firestore-split`        | document | `firestore/<collection>.ts` + `firestore.ts` barrel | one file per projection; `_meta_` under `firestore/_/`; DC-schema `.pick()` reuse; `FIRESTORE_DATABASES` constants in the barrel |
 | `api-types`              | api | `api-types.ts`                | endpoint request/response types                        |
 | `api-validation`         | api | `api-validation.ts`           | endpoint request-validation Zod                        |
-| `api-dto`                | api | `api-dtos.ts`                 | class-validator DTO classes                            |
+| `api-dto`                | api | `<operation>.dto.ts` per api  | class-validator DTO classes (NestJS `dto/` convention) |
 | `task-payloads`          | api | `task-payloads.ts`            | envelopes + `*TaskData`/`*TaskPayload` + constants     |
 | `sql-migrations`         | document | `migrations/constraints.sql`  | composite FK / CHECK / index SQL                       |
 | `id-codecs`              | document | `id-codecs.ts` (+ `id-core.ts`) | typed per-entity id encode/decode wrappers; emits the Sqids primitives when `project.idCodec` is set |

package/dist/lib/_internal/compiler/compiler.d.ts

@@ -4,6 +4,7 @@ import { RawContract } from '../parser/raw-document.js';
 import { ModuleLoader } from '../resolver/module-loader.js';
 import { GeneratedFile, GeneratorContext } from '../generators/generator.js';
 import { GeneratorRegistry } from '../generators/registry.js';
+import { HeaderPathVars } from './header-vars.js';
 export interface CompileOptions {
     /** Override module loading (defaults to the file system). */
     loader?: ModuleLoader;
@@ -29,6 +30,10 @@ export interface GenerateOptions extends CompileOptions {
     /** When true, write the generated files to disk. */
     write?: boolean;
     context?: GeneratorContext;
+    /** Header `${...}` path values; defaults to entry-only (root = current = entry). */
+    headerVars?: HeaderPathVars;
+    /** Clock for `${generatedAt}`/`${updatedAt}` stamping (tests); defaults to now. */
+    now?: Date;
 }
 export interface GenerateTargetResult {
     /** The contract file that declared this target. */
@@ -54,6 +59,7 @@ export declare const generateAll: (entryPath: string, options?: {
     write?: boolean;
     context?: GeneratorContext;
     loader?: ModuleLoader;
+    now?: Date;
 }) => GenerateAllResult;
 export interface FileDrift {
     /** Files whose on-disk content differs from the generated content. */

package/dist/lib/_internal/compiler/compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../../../src/lib/_internal/compiler/compiler.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAoB,MAAM,mBAAmB,CAAA;AAEhE,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAA;AAChC,OAAO,EAAU,WAAW,EAAqC,MAAM,2BAA2B,CAAA;AAElG,OAAO,EAAkB,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAG3E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAG5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAE7D,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,EAAE,CAAA;IACN,SAAS,EAAE,WAAW,EAAE,CAAA;IACxB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,WAAW,MAAM,EAAE,UAAS,cAAmB,KAAG,aAUzE,CAAA;AAED,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,MAAM,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,iBAAiB,CAAA;IAC5B,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,gBAAgB,CAAA;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,KAAK,EAAE,aAAa,EAAE,CAAA;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,oBAAoB,EAAE,CAAA;IAC/B,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,EAAE,EAAE,OAAO,CAAA;CACZ;AAwJD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,UAAS;IAAE,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAAO,KACjH,iBA0CF,CAAA;AAED,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,aAAa,EAAE,KAAG,SAUlD,CAAA;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,EAAE,CAAA;IACN,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,oFAAoF;IACpF,KAAK,EAAE,aAAa,EAAE,CAAA;IACtB,0DAA0D;IAC1D,EAAE,EAAE,OAAO,CAAA;CACZ;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,SAAS,eAAe,KAAG,cAuCtE,CAAA"}
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../../../src/lib/_internal/compiler/compiler.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAoB,MAAM,mBAAmB,CAAA;AAEhE,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAA;AAChC,OAAO,EAAU,WAAW,EAAqC,MAAM,2BAA2B,CAAA;AAElG,OAAO,EAAkB,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAG3E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAI5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,EAEL,cAAc,EAGf,MAAM,kBAAkB,CAAA;AAEzB,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,EAAE,CAAA;IACN,SAAS,EAAE,WAAW,EAAE,CAAA;IACxB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,WAAW,MAAM,EAAE,UAAS,cAAmB,KAAG,aAUzE,CAAA;AAED,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,MAAM,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,iBAAiB,CAAA;IAC5B,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,gBAAgB,CAAA;IAC1B,oFAAoF;IACpF,UAAU,CAAC,EAAE,cAAc,CAAA;IAC3B,mFAAmF;IACnF,GAAG,CAAC,EAAE,IAAI,CAAA;CACX;AAED,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,KAAK,EAAE,aAAa,EAAE,CAAA;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,oBAAoB,EAAE,CAAA;IAC/B,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,EAAE,EAAE,OAAO,CAAA;CACZ;AAmND;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,UAAS;IACP,QAAQ,CAAC,EAAE,iBAAiB,CAAA;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,gBAAgB,CAAA;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,GAAG,CAAC,EAAE,IAAI,CAAA;CACN,KACL,iBA0FF,CAAA;AAED,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,aAAa,EAAE,KAAG,SAUlD,CAAA;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,EAAE,CAAA;IACN,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,oFAAoF;IACpF,KAAK,EAAE,aAAa,EAAE,CAAA;IACtB,0DAA0D;IAC1D,EAAE,EAAE,OAAO,CAAA;CACZ;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,SAAS,eAAe,KAAG,cAgEtE,CAAA"}

package/dist/lib/_internal/compiler/compiler.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { error, hasErrors } from '../diagnostics.js';
 import { buildIr } from '../ir/build-ir.js';
 import { resolveImports } from '../resolver/import-resolver.js';
@@ -7,7 +7,8 @@ import { createFsLoader } from '../resolver/module-loader.js';
 import { validateIr } from '../validation/validate.js';
 import { createDefaultRegistry } from '../generators/index.js';
 import { toHeaderComment } from '../generators/support/header.js';
-import { kebabCase } from '../generators/support/naming.js';
+import { API_PLACEHOLDER_RE, expandApiPlaceholders } from '../generators/support/templates.js';
+import { expandHeaderPathVars, hasDateTokens, resolveDateTokens, } from './header-vars.js';
 /**
  * Run the front end of the pipeline: resolve imports, build the IR, and run
  * semantic validation. Generators are intentionally not involved here — the CLI
@@ -25,7 +26,6 @@ export const compile = (entryPath, options = {}) => {
         diagnostics: [...importDiagnostics, ...buildDiagnostics, ...validationDiagnostics],
     };
 };
-const OUT_PLACEHOLDER_RE = /\{(api-name|path)\}/;
 /** `apis:/tasks:/events:` section a raw api belongs to (drives the section defaults lookup). */
 const sectionOf = (api) => {
     if (api.kind === 'task')
@@ -34,25 +34,16 @@ const sectionOf = (api) => {
         return 'events';
     return 'apis';
 };
-/** Drop `{param}` segments from a REST path and join the rest (`/ai-models/{id}` → `ai-models`). */
-const pathSegments = (apiPath) => apiPath
-    .split('/')
-    .filter(segment => segment.length > 0 && !(segment.startsWith('{') && segment.endsWith('}')))
-    .join('/');
 const expandOutTemplate = (template, api, diagnostics, source) => {
-    if (!OUT_PLACEHOLDER_RE.test(template))
+    if (!API_PLACEHOLDER_RE.test(template))
         return template;
     if (!api) {
         diagnostics.push(error('INVALID_OUT_TEMPLATE', `"${template}" uses api placeholders but the generator is document-scoped (${source})`));
         return undefined;
     }
-    let out = template.replaceAll('{api-name}', kebabCase(api.name));
-    if (out.includes('{path}')) {
-        if (!api.path) {
-            diagnostics.push(error('INVALID_OUT_TEMPLATE', `"${template}" uses {path} but api "${api.name}" has no REST path (${source})`));
-            return undefined;
-        }
-        out = out.replaceAll('{path}', pathSegments(api.path));
+    const out = expandApiPlaceholders(template, api);
+    if (out === undefined) {
+        diagnostics.push(error('INVALID_OUT_TEMPLATE', `"${template}" uses {path} but api "${api.name}" has no REST path (${source})`));
     }
     return out;
 };
@@ -101,6 +92,30 @@ const buildGeneratorJobs = (doc, rootDoc, registry, diagnostics) => {
                 diagnostics.push(error('UNKNOWN_GENERATOR_DECL', `Api "${apiName}" applies generator "${use.generator}" but no declaration with an "out" was found (${doc.filePath})`));
                 continue;
             }
+            // Output settings resolve nearest-first: entry use → declaration → the
+            // generator's built-in default (applied by the generator itself).
+            const generator = registry.get(use.generator);
+            const output = {};
+            const file = use.file ?? decl?.file;
+            const split = use.split ?? decl?.split ?? generator?.defaultOutput?.split;
+            const options = use.options ?? decl?.options;
+            const header = use.header ?? decl?.header;
+            if (file !== undefined)
+                output.file = file;
+            if (split !== undefined)
+                output.split = split;
+            if (options !== undefined)
+                output.options = options;
+            // Split mode needs a per-api file name; bundled mode cannot expand one.
+            const effectiveFile = file ?? generator?.defaultOutput?.file;
+            if (effectiveFile !== undefined && split === false && API_PLACEHOLDER_RE.test(effectiveFile)) {
+                diagnostics.push(error('INVALID_OUT_TEMPLATE', `file "${effectiveFile}" uses api placeholders but split is false for generator "${use.generator}" — set a plain file name (${doc.filePath})`));
+                continue;
+            }
+            if (effectiveFile !== undefined && split === true && !API_PLACEHOLDER_RE.test(effectiveFile)) {
+                diagnostics.push(error('INVALID_OUT_TEMPLATE', `split is true for generator "${use.generator}" but file "${effectiveFile}" has no {api-name}/{path} placeholder, so per-api files would overwrite each other (${doc.filePath})`));
+                continue;
+            }
             const api = { name: apiName, ...(rawApi.path !== undefined ? { path: rawApi.path } : {}) };
             const expanded = expandOutTemplate(template, api, diagnostics, doc.filePath);
             if (expanded === undefined)
@@ -108,13 +123,15 @@ const buildGeneratorJobs = (doc, rootDoc, registry, diagnostics) => {
             const outDir = resolveOutDir(expanded, doc, rootDoc, diagnostics);
             if (outDir === undefined)
                 continue;
-            const key = `${use.generator}\u0000${outDir}`;
+            const key = [use.generator, outDir, file ?? '', String(split ?? ''), JSON.stringify(options ?? null), header ?? '\u0001'].join('\u0000');
             const existing = grouped.get(key);
             if (existing) {
                 existing.apiNames?.push(apiName);
             }
             else {
-                const job = { source: doc.filePath, generatorName: use.generator, outDir, apiNames: [apiName] };
+                const job = { source: doc.filePath, generatorName: use.generator, outDir, apiNames: [apiName], output };
+                if (header !== undefined)
+                    job.header = header;
                 grouped.set(key, job);
                 jobs.push(job);
             }
@@ -128,13 +145,47 @@ const buildGeneratorJobs = (doc, rootDoc, registry, diagnostics) => {
         }
         if ((generator.scope ?? 'document') === 'api')
             continue; // applied via entries, not by declaration
+        // Document-scoped `split` toggles between a generator and its `-split`
+        // variant (e.g. typescript ⇄ typescript-split) instead of reshaping output.
+        let generatorName = decl.generator;
+        if (decl.split === true && !generatorName.endsWith('-split')) {
+            const splitName = `${generatorName}-split`;
+            if (registry.get(splitName)) {
+                generatorName = splitName;
+            }
+            else {
+                diagnostics.push(error('UNSUPPORTED_SPLIT', `Generator "${decl.generator}" has no split variant (${doc.filePath})`));
+                continue;
+            }
+        }
+        else if (decl.split === false && generatorName.endsWith('-split')) {
+            const baseName = generatorName.slice(0, -'-split'.length);
+            if (registry.get(baseName))
+                generatorName = baseName;
+        }
+        const output = {};
+        if (decl.file !== undefined) {
+            if (API_PLACEHOLDER_RE.test(decl.file)) {
+                diagnostics.push(error('INVALID_OUT_TEMPLATE', `file "${decl.file}" uses api placeholders but generator "${decl.generator}" is document-scoped (${doc.filePath})`));
+                continue;
+            }
+            output.file = decl.file;
+        }
+        if (decl.options !== undefined)
+            output.options = decl.options;
         const expanded = expandOutTemplate(decl.out, undefined, diagnostics, doc.filePath);
         if (expanded === undefined)
             continue;
         const outDir = resolveOutDir(expanded, doc, rootDoc, diagnostics);
         if (outDir === undefined)
             continue;
-        jobs.push({ source: doc.filePath, generatorName: decl.generator, outDir });
+        jobs.push({
+            source: doc.filePath,
+            generatorName,
+            outDir,
+            ...(Object.keys(output).length > 0 ? { output } : {}),
+            ...(decl.header !== undefined ? { header: decl.header } : {}),
+        });
     }
     return jobs;
 };
@@ -156,6 +207,42 @@ export const generateAll = (entryPath, options = {}) => {
     const registry = options.registry ?? createDefaultRegistry();
     // Import order puts dependencies first, so the entry (root) document is last.
     const rootDoc = documents[documents.length - 1];
+    const loader = options.loader ?? createFsLoader();
+    const rootDir = dirname(rootDoc.filePath);
+    const relToRoot = (path) => relative(rootDir, path);
+    /** Shortest import chain root → target (BFS over resolved import edges). */
+    const importChain = (targetDoc) => {
+        if (targetDoc.filePath === rootDoc.filePath)
+            return [rootDoc.filePath];
+        const byPath = new Map(documents.map(document => [document.filePath, document]));
+        const queue = [[rootDoc.filePath]];
+        const seen = new Set([rootDoc.filePath]);
+        while (queue.length > 0) {
+            const chain = queue.shift();
+            const doc = byPath.get(chain[chain.length - 1]);
+            for (const specifier of doc?.imports ?? []) {
+                let importId;
+                try {
+                    importId = loader.resolveId(specifier, doc?.filePath ?? '');
+                }
+                catch {
+                    continue;
+                }
+                if (importId === targetDoc.filePath)
+                    return [...chain, importId];
+                if (!seen.has(importId) && byPath.has(importId)) {
+                    seen.add(importId);
+                    queue.push([...chain, importId]);
+                }
+            }
+        }
+        return [rootDoc.filePath, targetDoc.filePath];
+    };
+    const headerVarsFor = (doc) => ({
+        rootContractPath: relToRoot(rootDoc.filePath),
+        currentContractPath: relToRoot(doc.filePath),
+        allContractPath: importChain(doc).map(relToRoot).join(' -> '),
+    });
     const mergeDiagnostics = (incoming) => {
         // Per-target compiles revisit shared imports; keep only new diagnostics.
         for (const diagnostic of incoming) {
@@ -164,13 +251,21 @@ export const generateAll = (entryPath, options = {}) => {
             }
         }
     };
-    const runTarget = (doc, outDir, generators, apiNames) => {
+    const runTarget = (doc, outDir, generators, apiNames, output, header) => {
         const result = generate(doc.filePath, {
             outDir,
             generators,
             registry,
             write: options.write,
-            context: { ...options.context, ...(apiNames ? { apiNames } : {}) },
+            context: {
+                ...options.context,
+                ...(apiNames ? { apiNames } : {}),
+                ...(output ? { output } : {}),
+                // Per-generator header beats the CLI/contract-level one ('' disables it).
+                ...(header !== undefined ? { header: toHeaderComment(header) } : {}),
+            },
+            headerVars: headerVarsFor(doc),
+            ...(options.now ? { now: options.now } : {}),
             ...(options.loader ? { loader: options.loader } : {}),
         });
         mergeDiagnostics(result.diagnostics);
@@ -182,7 +277,7 @@ export const generateAll = (entryPath, options = {}) => {
         // Declaration/application DSL (`generators:` + section defaults / entry `generators:`).
         const jobDiagnostics = [];
         for (const job of buildGeneratorJobs(doc, rootDoc, registry, jobDiagnostics)) {
-            runTarget(doc, job.outDir, [job.generatorName], job.apiNames);
+            runTarget(doc, job.outDir, [job.generatorName], job.apiNames, job.output, job.header);
         }
         mergeDiagnostics(jobDiagnostics);
         if (hasErrors(jobDiagnostics))
@@ -225,6 +320,15 @@ export const generate = (entryPath, options) => {
     if (context.header === undefined && ir.header !== undefined) {
         context.header = toHeaderComment(ir.header);
     }
+    if (context.header !== undefined) {
+        const entryName = relative(dirname(entryPath), entryPath);
+        const vars = options.headerVars ?? {
+            rootContractPath: entryName,
+            currentContractPath: entryName,
+            allContractPath: entryName,
+        };
+        context.header = expandHeaderPathVars(context.header, vars);
+    }
     const files = [];
     for (const name of names) {
         const generator = registry.get(name);
@@ -239,11 +343,20 @@ export const generate = (entryPath, options) => {
     if (hasErrors(collected)) {
         return { ir, diagnostics: collected, files: [], ok: false };
     }
+    // `${generatedAt}`/`${updatedAt}` resolve against what is on disk so an
+    // unchanged regenerate reproduces the file byte-for-byte (keeps --check green).
+    const now = options.now ?? new Date();
+    const resolved = files.map(file => hasDateTokens(file.content)
+        ? {
+            ...file,
+            content: resolveDateTokens(file.content, existsSync(file.path) ? readFileSync(file.path, 'utf8') : undefined, now),
+        }
+        : file);
     if (options.write) {
-        for (const file of files) {
+        for (const file of resolved) {
             mkdirSync(dirname(file.path), { recursive: true });
             writeFileSync(file.path, file.content, 'utf8');
         }
     }
-    return { ir, diagnostics: collected, files, ok: true };
+    return { ir, diagnostics: collected, files: resolved, ok: true };
 };

package/dist/lib/_internal/compiler/header-vars.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `${...}` template variables available in header text (contract `header:`,
+ * per-generator `header`, CLI `--header`):
+ *
+ * - `${rootContractPath}`    — entry (root) yml, relative to the root yml's dir
+ * - `${currentContractPath}` — the yml the output is generated from
+ * - `${allContractPath}`     — import chain root → current, joined with ` -> `
+ * - `${generatedAt}`         — date the file was first generated (kept stable)
+ * - `${updatedAt}`           — date the content last changed (a regenerate that
+ *                              produces identical content keeps both dates, so
+ *                              `--check` stays drift-free)
+ *
+ * Date tokens accept an optional format: `${updatedAt:yyyy-mm-dd HH:mm:ss}`.
+ * Format runs: `yyyy`/`yy` year, `MM` month, `dd` day, `HH` hour, `mm` month
+ * before any hour token / minute after one (so both `yyyy-mm-dd` and `HH:mm`
+ * read naturally), `ss` second. The default format is `yyyy-MM-dd`.
+ *
+ * Path variables are expanded before generators run; date variables survive
+ * into the rendered content and are resolved per file against what is already
+ * on disk (see {@link resolveDateTokens}).
+ */
+export interface HeaderPathVars {
+    rootContractPath: string;
+    currentContractPath: string;
+    allContractPath: string;
+}
+export declare const expandHeaderPathVars: (header: string, vars: HeaderPathVars) => string;
+export declare const DEFAULT_DATE_FORMAT = "yyyy-MM-dd";
+export declare const hasDateTokens: (content: string) => boolean;
+/** Render `now` with a format string (see the module doc for the token set). */
+export declare const formatDate: (format: string, now: Date) => string;
+/**
+ * Resolve `${generatedAt}` / `${updatedAt}` in freshly rendered content against
+ * the previously written file:
+ *
+ * - unchanged content (modulo the dates themselves) → both dates carried over
+ * - changed or new content → `updatedAt` = now; `generatedAt` recovered from
+ *   the existing file's matching header line when possible, else now
+ */
+export declare const resolveDateTokens: (content: string, existing: string | undefined, now: Date) => string;
+//# sourceMappingURL=header-vars.d.ts.map

package/dist/lib/_internal/compiler/header-vars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header-vars.d.ts","sourceRoot":"","sources":["../../../../src/lib/_internal/compiler/header-vars.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,cAAc;IAC7B,gBAAgB,EAAE,MAAM,CAAA;IACxB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,eAAO,MAAM,oBAAoB,GAAI,QAAQ,MAAM,EAAE,MAAM,cAAc,KAAG,MAIjB,CAAA;AAE3D,eAAO,MAAM,mBAAmB,eAAe,CAAA;AAM/C,eAAO,MAAM,aAAa,GAAI,SAAS,MAAM,KAAG,OAAsC,CAAA;AAMtF,gFAAgF;AAChF,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,EAAE,KAAK,IAAI,KAAG,MAwBtD,CAAA;AAyBD;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,GAAG,SAAS,EAAE,KAAK,IAAI,KAAG,MA4B5F,CAAA"}

package/dist/lib/_internal/compiler/header-vars.js

@@ -0,0 +1,117 @@
+/**
+ * `${...}` template variables available in header text (contract `header:`,
+ * per-generator `header`, CLI `--header`):
+ *
+ * - `${rootContractPath}`    — entry (root) yml, relative to the root yml's dir
+ * - `${currentContractPath}` — the yml the output is generated from
+ * - `${allContractPath}`     — import chain root → current, joined with ` -> `
+ * - `${generatedAt}`         — date the file was first generated (kept stable)
+ * - `${updatedAt}`           — date the content last changed (a regenerate that
+ *                              produces identical content keeps both dates, so
+ *                              `--check` stays drift-free)
+ *
+ * Date tokens accept an optional format: `${updatedAt:yyyy-mm-dd HH:mm:ss}`.
+ * Format runs: `yyyy`/`yy` year, `MM` month, `dd` day, `HH` hour, `mm` month
+ * before any hour token / minute after one (so both `yyyy-mm-dd` and `HH:mm`
+ * read naturally), `ss` second. The default format is `yyyy-MM-dd`.
+ *
+ * Path variables are expanded before generators run; date variables survive
+ * into the rendered content and are resolved per file against what is already
+ * on disk (see {@link resolveDateTokens}).
+ */
+export const expandHeaderPathVars = (header, vars) => header
+    .replaceAll('${rootContractPath}', vars.rootContractPath)
+    .replaceAll('${currentContractPath}', vars.currentContractPath)
+    .replaceAll('${allContractPath}', vars.allContractPath);
+export const DEFAULT_DATE_FORMAT = 'yyyy-MM-dd';
+const DATE_TOKEN_RE = /\$\{(generatedAt|updatedAt)(?::([^}]+))?\}/;
+const DATE_TOKEN_ALL_RE = /\$\{(generatedAt|updatedAt)(?::([^}]+))?\}/g;
+const FORMAT_RUN_RE = /y+|[Mm]+|[Dd]+|[Hh]+|s+/g;
+export const hasDateTokens = (content) => DATE_TOKEN_RE.test(content);
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const pad = (value, width) => String(value).padStart(width, '0');
+/** Render `now` with a format string (see the module doc for the token set). */
+export const formatDate = (format, now) => {
+    let hourSeen = false;
+    let monthDone = false;
+    return format.replace(FORMAT_RUN_RE, run => {
+        const char = run[0];
+        const width = run.length;
+        if (char === 'y') {
+            return width <= 2 ? String(now.getFullYear()).slice(-2) : pad(now.getFullYear(), width);
+        }
+        if (char === 'M' || char === 'm') {
+            const isMonth = char === 'M' || (!monthDone && !hourSeen);
+            if (isMonth) {
+                monthDone = true;
+                return pad(now.getMonth() + 1, width);
+            }
+            return pad(now.getMinutes(), width);
+        }
+        if (char === 'D' || char === 'd')
+            return pad(now.getDate(), width);
+        if (char === 'H' || char === 'h') {
+            hourSeen = true;
+            return pad(now.getHours(), width);
+        }
+        return pad(now.getSeconds(), width);
+    });
+};
+/** Regex source matching any value rendered with `format` (digits per run, rest literal). */
+const formatToPattern = (format) => {
+    let out = '';
+    let last = 0;
+    for (const match of format.matchAll(FORMAT_RUN_RE)) {
+        out += escapeRegExp(format.slice(last, match.index)) + String.raw `\d{${match[0].length}}`;
+        last = match.index + match[0].length;
+    }
+    return out + escapeRegExp(format.slice(last));
+};
+/** Escaped-template → regex source with one capture per date token; records token order. */
+const toDatePattern = (template, tokens) => {
+    let out = '';
+    let last = 0;
+    for (const match of template.matchAll(DATE_TOKEN_ALL_RE)) {
+        tokens.push(match[1]);
+        out += escapeRegExp(template.slice(last, match.index)) + `(${formatToPattern(match[2] ?? DEFAULT_DATE_FORMAT)})`;
+        last = match.index + match[0].length;
+    }
+    return out + escapeRegExp(template.slice(last));
+};
+/**
+ * Resolve `${generatedAt}` / `${updatedAt}` in freshly rendered content against
+ * the previously written file:
+ *
+ * - unchanged content (modulo the dates themselves) → both dates carried over
+ * - changed or new content → `updatedAt` = now; `generatedAt` recovered from
+ *   the existing file's matching header line when possible, else now
+ */
+export const resolveDateTokens = (content, existing, now) => {
+    if (!hasDateTokens(content))
+        return content;
+    if (existing !== undefined) {
+        const tokens = [];
+        const full = new RegExp(`^${toDatePattern(content, tokens)}$`);
+        const match = existing.match(full);
+        if (match) {
+            let index = 0;
+            return content.replace(DATE_TOKEN_ALL_RE, () => match[++index]);
+        }
+    }
+    let generatedAt;
+    if (existing !== undefined) {
+        const generatedLine = content.split('\n').find(line => /\$\{generatedAt(?::[^}]+)?\}/.test(line));
+        if (generatedLine !== undefined) {
+            const lineTokens = [];
+            const lineMatch = existing.match(new RegExp(toDatePattern(generatedLine, lineTokens)));
+            if (lineMatch) {
+                generatedAt = lineMatch[lineTokens.indexOf('generatedAt') + 1];
+            }
+        }
+    }
+    return content.replace(DATE_TOKEN_ALL_RE, (_, name, format) => {
+        if (name === 'generatedAt' && generatedAt !== undefined)
+            return generatedAt;
+        return formatDate(format ?? DEFAULT_DATE_FORMAT, now);
+    });
+};

package/dist/lib/_internal/generators/api/api-dto-generator.d.ts

@@ -1,8 +1,3 @@
 import { Generator } from '../generator.js';
-/**
- * Generates class-validator DTO classes for API endpoint requests, mirroring the
- * hand-written NestJS DTOs (decorators derived from field type +
- * constraints). Complements the Zod request schemas for a NestJS ValidationPipe.
- */
 export declare const createApiDtoGenerator: () => Generator;
 //# sourceMappingURL=api-dto-generator.d.ts.map

package/dist/lib/_internal/generators/api/api-dto-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-dto-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/api/api-dto-generator.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,SAAS,EAAgC,MAAM,iBAAiB,CAAA;AA0GxF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,QAAO,SAmBvC,CAAA"}
+{"version":3,"file":"api-dto-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/api/api-dto-generator.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,SAAS,EAAgC,MAAM,iBAAiB,CAAA;AAoHxF,eAAO,MAAM,qBAAqB,QAAO,SAuBvC,CAAA"}

package/dist/lib/_internal/generators/api/api-dto-generator.js

@@ -3,6 +3,7 @@ import { pascalCase, singleQuote } from '../support/naming.js';
 import { isRelation, relationFkName } from '../support/relations.js';
 import { selectApis } from '../generator.js';
 import { headerBlocks } from '../support/header.js';
+import { emitApiFiles, resolveOutput } from '../support/templates.js';
 const SCALAR_TS = {
     string: 'string',
     int: 'number',
@@ -126,23 +127,30 @@ const renderDto = (ir, api, used) => {
  * hand-written NestJS DTOs (decorators derived from field type +
  * constraints). Complements the Zod request schemas for a NestJS ValidationPipe.
  */
+// Default mirrors the NestJS convention: one `dto/create-thing.dto.ts` per
+// endpoint next to its controller (the out template decides the directory).
+const DEFAULT_OUTPUT = { file: '{api-name}.dto.ts', split: true };
 export const createApiDtoGenerator = () => ({
     name: 'api-dto',
     scope: 'api',
     description: 'class-validator DTO classes for API requests',
+    defaultOutput: DEFAULT_OUTPUT,
     generate(ir, context) {
-        // DTO は HTTP リクエストボディ用 — task / pubsub のペイロードは task-payloads が担う。
+        // DTOs cover HTTP request bodies — task / pubsub payloads belong to task-payloads.
         const httpApis = selectApis(ir.apis, context).filter(api => api.kind === 'https' || api.kind === 'callable');
-        if (httpApis.length === 0) {
-            return [];
-        }
-        const used = new Set();
-        const dtoBlocks = httpApis.map(api => renderDto(ir, api, used));
-        const blocks = [...headerBlocks(context)];
-        if (used.size > 0) {
-            blocks.push(`import { ${[...used].sort().join(', ')} } from 'class-validator'`);
-        }
-        blocks.push(...dtoBlocks);
-        return [{ path: 'api-dtos.ts', content: `${blocks.join('\n\n')}\n` }];
+        const output = resolveOutput(context, DEFAULT_OUTPUT);
+        return emitApiFiles(httpApis, output, subset => {
+            if (subset.length === 0) {
+                return undefined;
+            }
+            const used = new Set();
+            const dtos = subset.map(api => renderDto(ir, api, used));
+            const blocks = [...headerBlocks(context)];
+            if (used.size > 0) {
+                blocks.push(`import { ${[...used].sort().join(', ')} } from 'class-validator'`);
+            }
+            blocks.push(...dtos);
+            return `${blocks.join('\n\n')}\n`;
+        });
     },
 });

package/dist/lib/_internal/generators/api/api-types-generator.d.ts

@@ -1,8 +1,3 @@
 import { Generator } from '../generator.js';
-/**
- * Generates request/response TypeScript types for each API endpoint. A payload
- * can reference an existing model or declare inline fields; a void response maps
- * to `void`. This mirrors the shared producer/consumer contract pattern.
- */
 export declare const createApiTypesGenerator: () => Generator;
 //# sourceMappingURL=api-types-generator.d.ts.map

package/dist/lib/_internal/generators/api/api-types-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-types-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/api/api-types-generator.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,SAAS,EAAgC,MAAM,iBAAiB,CAAA;AA8ExF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAO,SA0BzC,CAAA"}
+{"version":3,"file":"api-types-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/api/api-types-generator.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,SAAS,EAAgC,MAAM,iBAAiB,CAAA;AAsFxF,eAAO,MAAM,uBAAuB,QAAO,SA+BzC,CAAA"}