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

package/README.md

@@ -132,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).
 

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;AAI5E,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;AAmND;;;;;;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,iBAuDF,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';
@@ -8,6 +8,7 @@ import { validateIr } from '../validation/validate.js';
 import { createDefaultRegistry } from '../generators/index.js';
 import { toHeaderComment } from '../generators/support/header.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
@@ -206,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) {
@@ -227,6 +264,8 @@ export const generateAll = (entryPath, options = {}) => {
                 // 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);
@@ -281,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);
@@ -295,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/support/header.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/support/header.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAElD,gEAAgE;AAChE,eAAO,MAAM,cAAc,QAGf,CAAA;AAEZ,2FAA2F;AAC3F,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,MACwD,CAAA;AAEvG,mFAAmF;AACnF,eAAO,MAAM,SAAS,GAAI,SAAS,gBAAgB,GAAG,SAAS,KAAG,MAA+B,CAAA;AAEjG;;;GAGG;AACH,eAAO,MAAM,YAAY,GACvB,SAAS,gBAAgB,GAAG,SAAS,EACrC,YAAW,CAAC,MAAM,EAAE,MAAM,KAAK,MAAyB,KACvD,MAAM,EAGR,CAAA"}
+{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/support/header.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAElD,gEAAgE;AAChE,eAAO,MAAM,cAAc,QAKf,CAAA;AAEZ,2FAA2F;AAC3F,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,MACwD,CAAA;AAEvG,mFAAmF;AACnF,eAAO,MAAM,SAAS,GAAI,SAAS,gBAAgB,GAAG,SAAS,KAAG,MAA+B,CAAA;AAEjG;;;GAGG;AACH,eAAO,MAAM,YAAY,GACvB,SAAS,gBAAgB,GAAG,SAAS,EACrC,YAAW,CAAC,MAAM,EAAE,MAAM,KAAK,MAAyB,KACvD,MAAM,EAGR,CAAA"}

package/dist/lib/_internal/generators/support/header.js

@@ -1,6 +1,8 @@
 /** Default banner marking a file as generated (do-not-edit). */
 export const DEFAULT_HEADER = [
     '// AUTO-GENERATED by firebase-contract. Do not edit by hand.',
+    '// Source: ${currentContractPath}',
+    '// Generated: ${generatedAt} / Updated: ${updatedAt}',
     '// Regenerate with: fbc generate',
 ].join('\n');
 /** Turn raw header text into `//` comment lines; `default` selects the built-in banner. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firebase-contract",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
   "type": "module",
   "bin": {
     "firebase-contract": "./dist/lib/cli/index.js",