@metaobjectsdev/codegen-ts 0.23.2 → 0.24.0

package/src/overwrite-policy.ts

@@ -14,14 +14,23 @@
 //      (current, .gen-state snapshot, fresh tmpfile). Exit 0 → clean merge,
 //      advance .gen-state to fresh content. Exit > 0 → leave conflict markers
 //      in the output file, do NOT advance .gen-state; status "conflict".
-//   4. If .gen-state/<relPath> is absent but the file exists ("first-time
-//      regen on an existing file") → write-if-different against the existing
-//      file as the baseline (no merge, no clobber). The `baseline: "fresh"`
-//      flag opts into "overwrite from fresh and re-baseline".
+//   4. If the .gen-state BODY is absent but the file exists, consult the
+//      committed hash manifest: identical fresh content → "unchanged"; the file
+//      still hashes to what we recorded writing → safe to overwrite; anything
+//      else (edited, or no record at all) → "refused", naming the file. The
+//      `baseline: "fresh"` flag opts into "overwrite from fresh and re-baseline".
 //
 // Integrity (caveat 2 from the spike): we keep a sha-256 of each canonical
-// snapshot at `.gen-state/.hashes.json`. On load, mismatch → fall back to
-// first-time semantics and warn naming the file so the user can investigate.
+// snapshot at `.gen-state/.hashes.json`.
+//
+// THE MANIFEST IS COMMITTED; THE BODIES ARE NOT. That split is what makes step 4
+// possible. A hash per path is small and reviewable, where a second full copy of
+// all generated output is neither — and a hash is already sufficient to tell
+// "nobody touched this" from "somebody edited this", which is the only thing
+// steps 4 and the orphan-delete path need to know. The cost, stated: without a
+// body there is no base to merge against, so a diverged file on a fresh clone is
+// REFUSED rather than merged. That is a smaller loss than it sounds, because the
+// behaviour it replaces was a silent overwrite.
 
 import {
   existsSync,
@@ -29,6 +38,7 @@ import {
   writeFileSync,
   mkdirSync,
   copyFileSync,
+  rmSync,
 } from "node:fs";
 import { dirname, join, isAbsolute, relative, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
@@ -42,7 +52,13 @@ export type WriteStatus =
   | "merged"
   | "conflict"
   | "refused"
-  | "skipped";
+  | "skipped"
+  /** FR-038 §8 — deleted because it was generated by a previous run, is no longer
+   *  generated, and was never edited by hand. Reported as a file outcome rather
+   *  than a warning because a deletion is exactly as consequential as a write,
+   *  and a run summary that lists writes but hides deletions is how a silent
+   *  deletion happens. */
+  | "removed";
 
 /**
  * "overwrite" — default; three-way merge if .gen-state exists, else write-if-
@@ -75,8 +91,9 @@ export interface DecideAndWriteOpts {
 export interface WriteResult {
   path: string;
   status: WriteStatus;
-  /** Present when status is "conflict" — human-readable hint identifying the
-   *  file the user must resolve. */
+  /** Present when status is "conflict" or "refused" — human-readable reason,
+   *  naming what the user must do. A refusal nobody can act on gets the file
+   *  deleted by hand, which is the outcome refusing exists to prevent. */
   conflictHint?: string;
 }
 
@@ -105,7 +122,128 @@ function loadHashes(genStateDir: string): HashesFile {
 
 function saveHashes(genStateDir: string, hashes: HashesFile): void {
   mkdirSync(genStateDir, { recursive: true });
-  writeFileSync(join(genStateDir, HASHES_FILE), JSON.stringify(hashes, null, 2) + "\n");
+  // Keys SORTED, because this file is committed. Insertion order would make the
+  // diff — and any merge conflict between two people who both regenerated —
+  // depend on which entity happened to generate first, which is noise nobody can
+  // review.
+  const sorted: HashesFile = {};
+  for (const key of Object.keys(hashes).sort()) sorted[key] = hashes[key]!;
+  writeFileSync(join(genStateDir, HASHES_FILE), JSON.stringify(sorted, null, 2) + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// FR-038 §8 — readers for orphan reconciliation.
+//
+// `.hashes.json`'s key set is the ONLY record of what a previous run wrote, so
+// it is also the only way to notice that a file we used to generate is no longer
+// generated. These three functions expose that record without widening the write
+// path: nothing here decides anything (see reconcile-orphans.ts) and nothing here
+// touches an output file (see orphan-sweep.ts).
+// ---------------------------------------------------------------------------
+
+/**
+ * Every snapshot key recorded under `genStateDir` — in a runner-driven project,
+ * the project-relative path of every file some previous `meta gen` wrote.
+ *
+ * Empty for a gen-state directory that does not exist yet, which is what makes a
+ * first run, an ephemeral test run and `verify --codegen`'s throwaway root all
+ * reconcile nothing.
+ */
+export function listGeneratedPaths(genStateDir: string): string[] {
+  return Object.keys(loadHashes(genStateDir));
+}
+
+/**
+ * sha-256 of `content`, hex — the same function that produces `.hashes.json`.
+ *
+ * Exported so a caller can ask the one question the manifest exists to answer
+ * ("is this file byte-for-byte what we recorded writing?") without needing the
+ * snapshot body, which is what makes the answer available on a fresh clone.
+ */
+export function contentHash(content: string): string {
+  return sha256(content);
+}
+
+/**
+ * The hash we recorded when we last wrote `relPath`, or undefined if we have no
+ * record of ever writing it.
+ *
+ * This is the COMMITTED half of `.gen-state`. The snapshot bodies stay ignored —
+ * they are a second full copy of all generated output — but a hash per path is
+ * small enough to commit and review, and it is sufficient to distinguish "nobody
+ * touched this" from "somebody edited this", which is the only distinction the
+ * overwrite and delete decisions actually need.
+ */
+export function readGeneratedHash(
+  genStateDir: string,
+  relPath: string,
+): string | undefined {
+  return loadHashes(genStateDir)[relPath];
+}
+
+/**
+ * True when the file at `relPath` is byte-for-byte what we recorded writing.
+ *
+ * FAILS CLOSED: with no recorded hash we cannot prove anything, so the answer is
+ * false. Both the write path and the orphan-delete path ask this one question of
+ * this one piece of evidence — before this existed they answered the same
+ * uncertainty in opposite directions inside a single feature, refusing to DELETE
+ * a hand-edited file while silently OVERWRITING one.
+ */
+export function isPristineGenerated(
+  genStateDir: string,
+  relPath: string,
+  current: string,
+): boolean {
+  const recorded = readGeneratedHash(genStateDir, relPath);
+  return recorded !== undefined && recorded === sha256(current);
+}
+
+/**
+ * The snapshot of what we last wrote to `relPath`, or undefined when there is no
+ * trustworthy one.
+ *
+ * HASH-CHECKED on purpose. A caller comparing this against the file on disk is
+ * asking "is the output still exactly what I wrote?" — and a snapshot that fails
+ * its own hash cannot answer that. Returning the stale text would let a
+ * reconciling caller conclude "untouched" and delete a file it cannot vouch for,
+ * so a tampered snapshot reads as absent and the caller fails closed.
+ */
+export function readGeneratedSnapshot(
+  genStateDir: string,
+  relPath: string,
+): string | undefined {
+  return readSnapshotChecked(genStateDir, relPath)?.text;
+}
+
+/**
+ * Drop both halves of the record for paths this run no longer generates — each
+ * snapshot file and its `.hashes.json` entry.
+ *
+ * BOTH halves, or the next run sees the path again in `listGeneratedPaths` and
+ * re-decides an orphan that has already been dealt with. A no-op for a path that was
+ * never generated.
+ *
+ * Batched deliberately: one manifest read and one write for the whole set. A per-path
+ * variant re-reads, re-sorts and rewrites the entire manifest every call, so clearing k
+ * orphans rewrote it k times — on a project with hundreds of generated files that makes
+ * bookkeeping the dominant cost of `meta gen`, for an identical result.
+ */
+export function forgetGeneratedPaths(
+  genStateDir: string,
+  relPaths: Iterable<string>,
+): void {
+  const hashes = loadHashes(genStateDir);
+  let changed = false;
+  for (const relPath of relPaths) {
+    const snapshot = snapshotPath(genStateDir, relPath);
+    if (existsSync(snapshot)) rmSync(snapshot, { force: true });
+    if (relPath in hashes) {
+      delete hashes[relPath];
+      changed = true;
+    }
+  }
+  if (changed) saveHashes(genStateDir, hashes);
 }
 
 const ENGINE_FILE = ".engine.json";
@@ -274,6 +412,159 @@ function defaultOutputRelPath(outputPath: string): string {
   return sha256(resolve(outputPath)).slice(0, 32);
 }
 
+/** Where this call's gen-state lives. Shared by the write path and the preview so
+ *  the two cannot resolve it differently — a preview that consults a different
+ *  manifest than the write would be the same disagreement-between-two-answers bug
+ *  this whole change exists to remove. */
+function resolveGenStateDir(opts: DecideAndWriteOpts): string {
+  if (opts.genStateDir === undefined) return join(tmpdir(), "meta-gen-state-fallback");
+  return isAbsolute(opts.genStateDir) ? opts.genStateDir : resolve(opts.genStateDir);
+}
+
+/** True when this project has a hash manifest at all — as opposed to a manifest
+ *  that simply has no entry for some path.
+ *
+ *  The distinction drives the upgrade message: a project with NO manifest predates
+ *  the manifest being committed, so its refusals are one fixable configuration
+ *  problem rather than N independent hand edits, and it deserves one instruction
+ *  instead of a wall of per-file warnings. */
+export function hasHashManifest(genStateDir: string): boolean {
+  return existsSync(join(genStateDir, HASHES_FILE));
+}
+
+/** Normalize the legacy `MergeStrategy` string shorthand into an options object. */
+function normalizeOpts(
+  optsOrStrategy: DecideAndWriteOpts | MergeStrategy,
+): DecideAndWriteOpts {
+  return typeof optsOrStrategy === "string" ? { strategy: optsOrStrategy } : optsOrStrategy;
+}
+
+/**
+ * The single decision tree `decideAndWrite` and `previewWriteStatus` both classify
+ * through — the fix for the risk named at the top of this file. Two functions that
+ * each re-derive "which case applies" from scratch can drift out of step in their
+ * branch ORDER, and when they do, the preview lies. Every branch that decides WHICH
+ * case an input falls into lives here, exactly once. `decideAndWrite` executes the
+ * case (the write, the merge, the snapshot advance — see its own comments for the
+ * "how"); `previewWriteStatus` maps the case straight to a `WriteStatus` with no
+ * side effects. Neither function repeats the ordering, so neither can disagree with
+ * the other about it.
+ */
+type WriteCase =
+  | { kind: "new" }
+  | { kind: "skip" }
+  | { kind: "no-snapshot-fresh-unchanged" }
+  | { kind: "no-snapshot-fresh-overwrite" }
+  | { kind: "no-snapshot-unchanged" }
+  | { kind: "no-snapshot-pristine-overwrite" }
+  | { kind: "no-snapshot-refused"; hasRecord: boolean }
+  | { kind: "snapshot-unchanged" }
+  | { kind: "snapshot-merge-required"; snapshotText: string };
+
+function classifyWrite(
+  path: string,
+  content: string,
+  opts: DecideAndWriteOpts,
+): WriteCase {
+  // First-time write — file doesn't exist.
+  if (!existsSync(path)) return { kind: "new" };
+
+  if ((opts.strategy ?? "overwrite") === "skip-existing") return { kind: "skip" };
+
+  // File exists. Load the canonical snapshot if any.
+  const genStateDir = resolveGenStateDir(opts);
+  const relPath = opts.outputRelPath ?? defaultOutputRelPath(path);
+  const snapshot = readSnapshotChecked(genStateDir, relPath);
+  const current = readFileSync(path, "utf-8");
+
+  // First-time regen on a pre-existing file (no snapshot) — caveat 3. `baseline`
+  // only ever applies here: BaselineMode's own doc comment says so ("When
+  // .gen-state is absent but the file exists"), and a snapshot body — handled
+  // below — always gets the real three-way merge regardless of baseline.
+  if (snapshot === undefined) {
+    if ((opts.baseline ?? "default") === "fresh") {
+      // Opt-in escape hatch: overwrite and seed the snapshot from fresh.
+      return current === content
+        ? { kind: "no-snapshot-fresh-unchanged" }
+        : { kind: "no-snapshot-fresh-overwrite" };
+    }
+
+    // No snapshot BODY. That is the normal state, not an edge case: the bodies
+    // are gitignored, so every fresh clone and every CI runner arrives here.
+    //
+    // Previously this branch wrote the fresh content unconditionally, which meant
+    // the documented promise that hand edits survive regeneration was false in
+    // precisely the situation adopters spend most of their time in — and the CLI
+    // labelled the replacement `NEW`.
+    //
+    // The committed hash manifest answers the only question that matters. Note
+    // this is the SAME question, asked of the same evidence, as the orphan-delete
+    // path: see `isPristineGenerated`.
+    if (current === content) return { kind: "no-snapshot-unchanged" };
+
+    if (isPristineGenerated(genStateDir, relPath, current)) {
+      // Byte-for-byte what we last wrote, so replacing it loses nothing. This is
+      // the common fresh-clone case (a formatter or engine bump moved the output)
+      // and it must not refuse, or a clean checkout would stall on every file.
+      return { kind: "no-snapshot-pristine-overwrite" };
+    }
+
+    // Either somebody edited it (hash mismatch) or we have no record of writing
+    // it at all (no hash). Both are unprovable, so fail closed.
+    return {
+      kind: "no-snapshot-refused",
+      hasRecord: readGeneratedHash(genStateDir, relPath) !== undefined,
+    };
+  }
+
+  // Snapshot exists — a real three-way merge decides this one.
+  // Fast path: nothing changed.
+  if (current === content && snapshot.text === content) {
+    return { kind: "snapshot-unchanged" };
+  }
+  return { kind: "snapshot-merge-required", snapshotText: snapshot.text };
+}
+
+/**
+ * What `decideAndWrite` WOULD do, touching nothing. Backs `meta gen --dry-run`.
+ *
+ * Exact for every outcome the hash manifest decides, because those are pure
+ * comparisons — `classifyWrite` above is the single source for which one applies.
+ * Deliberately COARSE in one place: with a snapshot body present the result depends
+ * on whether `git merge-file` comes back clean or conflicted, which cannot be known
+ * without performing the merge — so that case reports `overwrite`, meaning "this
+ * file will be rewritten", which is true either way.
+ *
+ * The reason this exists as its own function rather than a flag on
+ * `decideAndWrite`: a preview must be incapable of writing, and the cheapest way to
+ * guarantee that is to give it no write in its body at all — mapping a `WriteCase`
+ * to a status touches no file and no manifest.
+ */
+export function previewWriteStatus(
+  path: string,
+  content: string,
+  optsOrStrategy: DecideAndWriteOpts | MergeStrategy = {},
+): WriteStatus {
+  const kase = classifyWrite(path, content, normalizeOpts(optsOrStrategy));
+  switch (kase.kind) {
+    case "new":
+      return "new";
+    case "skip":
+      return "skipped";
+    case "no-snapshot-fresh-unchanged":
+    case "no-snapshot-unchanged":
+    case "snapshot-unchanged":
+      return "unchanged";
+    case "no-snapshot-fresh-overwrite":
+    case "no-snapshot-pristine-overwrite":
+      return "overwrite";
+    case "no-snapshot-refused":
+      return "refused";
+    case "snapshot-merge-required":
+      return "overwrite";
+  }
+}
+
 /**
  * The main entry point. Backward-compatible with the rc.11 signature: passing
  * a `MergeStrategy` string as the third argument continues to work; passing
@@ -284,99 +575,81 @@ export function decideAndWrite(
   content: string,
   optsOrStrategy: DecideAndWriteOpts | MergeStrategy = {},
 ): WriteResult {
-  const opts: DecideAndWriteOpts =
-    typeof optsOrStrategy === "string"
-      ? { strategy: optsOrStrategy }
-      : optsOrStrategy;
-  const strategy: MergeStrategy = opts.strategy ?? "overwrite";
-  const baseline: BaselineMode = opts.baseline ?? "default";
-  const genStateDir =
-    opts.genStateDir !== undefined
-      ? (isAbsolute(opts.genStateDir)
-          ? opts.genStateDir
-          : resolve(opts.genStateDir))
-      : join(tmpdir(), "meta-gen-state-fallback");
+  const opts = normalizeOpts(optsOrStrategy);
+  const genStateDir = resolveGenStateDir(opts);
   const relPath = opts.outputRelPath ?? defaultOutputRelPath(path);
+  const kase = classifyWrite(path, content, opts);
 
-  // 1. First-time write — file doesn't exist.
-  if (!existsSync(path)) {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, content);
-    advanceSnapshot(genStateDir, relPath, content);
-    return { path, status: "new" };
-  }
-
-  if (strategy === "skip-existing") {
-    return { path, status: "skipped" };
-  }
+  switch (kase.kind) {
+    case "new":
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, content);
+      advanceSnapshot(genStateDir, relPath, content);
+      return { path, status: "new" };
 
-  // 2. File exists. Load the canonical snapshot if any.
-  const snapshot = readSnapshotChecked(genStateDir, relPath);
+    case "skip":
+      return { path, status: "skipped" };
 
-  // 3. First-time regen on a pre-existing file (no snapshot).
-  if (snapshot === undefined) {
-    const current = readFileSync(path, "utf-8");
+    case "no-snapshot-fresh-unchanged":
+    case "no-snapshot-unchanged":
+      // Identical content needs no write, in either mode — just seed/advance the
+      // snapshot so the file is recognisable as ours next time.
+      advanceSnapshot(genStateDir, relPath, content);
+      return { path, status: "unchanged" };
 
-    if (baseline === "fresh") {
-      // Opt-in escape hatch: overwrite and seed the snapshot from fresh.
-      if (current === content) {
-        advanceSnapshot(genStateDir, relPath, content);
-        return { path, status: "unchanged" };
-      }
+    case "no-snapshot-fresh-overwrite":
+    case "no-snapshot-pristine-overwrite":
       writeFileSync(path, content);
       advanceSnapshot(genStateDir, relPath, content);
       return { path, status: "overwrite" };
-    }
 
-    // Default: write-if-different. The EXISTING file is treated as the
-    // canonical baseline so subsequent runs do real three-way merges. If
-    // fresh output is identical, just seed the snapshot. If different, write
-    // the fresh content + seed snapshot — there's no marker policy left to
-    // refuse on, but this is the contract documented in the runbook (no
-    // marker check; users with hand-written files should never have the
-    // codegen output path colliding with them).
-    if (current === content) {
-      advanceSnapshot(genStateDir, relPath, current);
+    case "no-snapshot-refused":
+      // Deliberately does NOT advance the snapshot or the hash: a refusal that
+      // records the current content would make the file look pristine next run and
+      // turn this into a silent overwrite one run later.
+      return {
+        path,
+        status: "refused",
+        conflictHint: kase.hasRecord
+          ? "this file has been edited since it was generated — it was NOT " +
+            "overwritten. Move your edits into a non-generated file, or re-run " +
+            "with --baseline=fresh to discard them and adopt fresh output."
+          : "no record of generating this file, and its content differs from fresh " +
+            "output — it was NOT overwritten. Move it aside, or re-run with " +
+            "--baseline=fresh to overwrite it and adopt fresh output as the baseline.",
+      };
+
+    case "snapshot-unchanged":
       return { path, status: "unchanged" };
-    }
-    writeFileSync(path, content);
-    advanceSnapshot(genStateDir, relPath, content);
-    return { path, status: "overwrite" };
-  }
 
-  // 4. Snapshot exists — real three-way merge.
-  const current = readFileSync(path, "utf-8");
+    case "snapshot-merge-required": {
+      const baseTmp = writeTmpfile(kase.snapshotText);
+      const freshTmp = writeTmpfile(content);
 
-  // Fast path: nothing changed.
-  if (current === content && snapshot.text === content) {
-    return { path, status: "unchanged" };
-  }
-
-  const baseTmp = writeTmpfile(snapshot.text);
-  const freshTmp = writeTmpfile(content);
+      const outcome = runGitMergeFile(path, baseTmp, freshTmp);
 
-  const outcome = runGitMergeFile(path, baseTmp, freshTmp);
+      if (outcome.exitCode === 0) {
+        // Clean merge — advance the canonical snapshot to fresh.
+        advanceSnapshot(genStateDir, relPath, content);
+        // Distinguish "user had no changes vs canonical" from "merge integrated
+        // edits". The fresh-equals-snapshot case is `snapshot-unchanged` above —
+        // so if the merged result equals fresh we report a plain overwrite,
+        // otherwise it's a merge that pulled in user edits.
+        return {
+          path,
+          status: outcome.mergedContent === content ? "overwrite" : "merged",
+        };
+      }
 
-  if (outcome.exitCode === 0) {
-    // Clean merge — advance the canonical snapshot to fresh.
-    advanceSnapshot(genStateDir, relPath, content);
-    // Distinguish "user had no changes vs canonical" from "merge integrated
-    // edits". The fresh equals snapshot case happened above (fast path) — so
-    // if outcome.mergedContent equals fresh we report a plain overwrite,
-    // otherwise it's a merge that pulled in user edits.
-    if (outcome.mergedContent === content) {
-      return { path, status: "overwrite" };
+      // Conflict — do NOT advance the snapshot. The output now contains diff3
+      // markers from git merge-file.
+      return {
+        path,
+        status: "conflict",
+        conflictHint:
+          "merge conflict — resolve `<<<<<<<` markers and re-run `meta gen` to " +
+          "advance the canonical state.",
+      };
     }
-    return { path, status: "merged" };
   }
-
-  // Conflict — do NOT advance the snapshot. The output now contains diff3
-  // markers from git merge-file.
-  return {
-    path,
-    status: "conflict",
-    conflictHint:
-      "merge conflict — resolve `<<<<<<<` markers and re-run `meta gen` to " +
-      "advance the canonical state.",
-  };
 }

package/src/projection/build-projection-views.ts

@@ -53,6 +53,14 @@ export interface ExpectedView {
   name: string;
   schema?: string;
   sql: string;
+  /**
+   * `resolutionKey()` of the object that declared this view — the projection, or the
+   * write-through entity hosting its own read view. migrate-ts records it as
+   * PROVENANCE (never onto the view descriptor, never into the committed snapshot) so
+   * a per-command `migrate.scope` can decide ownership on the declaring FQN rather
+   * than on the physical view name, which no naming strategy can reverse.
+   */
+  fqn: string;
   /**
    * Physical tables this view reads (base + every joined table). The migrate-ts
    * diff uses this to recreate the view when one of its source tables undergoes a
@@ -199,6 +207,7 @@ function emitViewFor(
     sql: body,
     dependsOn,
     columns,
+    fqn: host.resolutionKey(),
     ...(schema !== undefined ? { schema } : {}),
   });
 }
@@ -240,6 +249,7 @@ function emitSqlView(
     name: source.physicalName, // FR-016 four-step physical name
     sql: source.sqlBody!, // verbatim — never parsed, never re-wrapped
     dependsOn,
+    fqn: host.resolutionKey(),
     // columns OMITTED → "unknown" → gated drop+create fail-safe.
     ...(schema !== undefined ? { schema } : {}),
   });