@metaobjectsdev/codegen-ts 0.23.2 → 0.24.0

package/src/reconcile-orphans.ts

@@ -0,0 +1,136 @@
+// FR-038 §8 — deletion integrity: what happens to a generated file that is no
+// longer generated.
+//
+// A requirement's stubs become orphans when the requirement is deleted. The
+// obvious move — remove them, as the FR-038 draft said for `abandoned` entries —
+// is safe only for an UNTOUCHED stub. On a filled one it eats assertions somebody
+// wrote, and the whole point of the inversion is that the body is hand-written and
+// survives regeneration.
+//
+// So: remove what the generator wrote, REFUSE what a human changed, and name it.
+// That mirrors the migrate engine refusing a primary-key move rather than emitting
+// something un-appliable (#258) — a refusal is recoverable, a deletion is not.
+//
+// Deliberately PURE: the caller supplies the readers. The decision is the part
+// worth testing, and threading a filesystem through it would make the rule harder
+// to exercise than the plumbing around it.
+
+/**
+ * A generator's opt-in to orphan reconciliation, and the namespace it applies to.
+ *
+ * Declaring this is the ONLY way in: `.gen-state/.hashes.json` records paths, not
+ * which generator produced each one, so the runner genuinely cannot work out who
+ * owns what. Deriving ownership from the output directory instead would be worse
+ * than useless — every generator in a single-target project writes to the same
+ * `outDir`, so one generator narrowing its output would delete its siblings'
+ * files. The generator has to say.
+ */
+export interface OrphanPolicy {
+  /**
+   * True when `relPathInTarget` — a path relative to this generator's own output
+   * directory, always `/`-separated — is inside the namespace this generator is
+   * the sole producer of.
+   *
+   * Be narrow. This predicate is the blast radius: every previously-generated
+   * path it accepts and this run did not re-emit is a deletion candidate.
+   */
+  readonly owns: (relPathInTarget: string) => boolean;
+  /**
+   * Delete a hand-edited orphan instead of refusing it. Default false.
+   *
+   * The seam exists because §6 requires every default to have one, not because
+   * it is advisable: the refusal already names the file and deleting it by hand
+   * is a one-line answer, whereas this flag makes the destructive outcome the
+   * automatic one.
+   */
+  readonly force?: boolean;
+}
+
+export interface OrphanDecision {
+  /** No longer emitted, on disk, and byte-identical to the snapshot we wrote.
+   *  Safe to delete — the generator is removing only its own untouched output. */
+  readonly remove: readonly string[];
+  /** No longer emitted and CHANGED since we wrote it (or with no snapshot to
+   *  compare against). Left alone and reported, never deleted. */
+  readonly refused: readonly string[];
+  /** No longer emitted and already absent from disk. Nothing to delete; the
+   *  caller should just drop the stale snapshot. */
+  readonly vanished: readonly string[];
+}
+
+export interface ReconcileOrphansArgs {
+  /** Relative paths this generator emitted on some previous run — in practice the
+   *  keys of `.gen-state/.hashes.json`. */
+  readonly previouslyGenerated: readonly string[];
+  /** Relative paths emitted on THIS run. */
+  readonly emitted: readonly string[];
+  /** Namespace guard. Orphan reconciliation is opt-in and scoped: a generator must
+   *  never delete another generator's output just because it stopped emitting its
+   *  own. */
+  readonly owns: (relPath: string) => boolean;
+  /** Whether the file is still on disk at all. */
+  readonly exists: (relPath: string) => boolean;
+  /**
+   * Whether the file is byte-for-byte what we recorded writing.
+   *
+   * MUST fail closed — false when it cannot be proven. This is deliberately the
+   * same question the write path asks (`isPristineGenerated`), of the same
+   * evidence: the committed hash manifest. Before they were unified, one feature
+   * refused to DELETE a hand-edited file while silently OVERWRITING one, which is
+   * the same uncertainty answered two opposite ways.
+   */
+  readonly isUntouched: (relPath: string) => boolean;
+}
+
+export function reconcileOrphans(args: ReconcileOrphansArgs): OrphanDecision {
+  const emitted = new Set(args.emitted);
+  const remove: string[] = [];
+  const refused: string[] = [];
+  const vanished: string[] = [];
+
+  for (const relPath of args.previouslyGenerated) {
+    if (emitted.has(relPath)) continue;
+    if (!args.owns(relPath)) continue;
+
+    if (!args.exists(relPath)) {
+      vanished.push(relPath);
+      continue;
+    }
+
+    // Fail closed: unless we can prove the file is untouched, guessing wrong
+    // deletes someone's work.
+    if (!args.isUntouched(relPath)) {
+      refused.push(relPath);
+      continue;
+    }
+
+    remove.push(relPath);
+  }
+
+  return { remove, refused, vanished };
+}
+
+/**
+ * The message shown when a hand-edited orphan is refused.
+ *
+ * It has to say what happened, why nothing was deleted, and what the two ways out
+ * are — otherwise the reasonable reaction to an unexplained refusal is to delete
+ * the file, which is the outcome the refusal exists to prevent.
+ */
+export function refusedOrphanMessage(
+  paths: readonly string[],
+  /** Which generator's namespace these came from. `orphanPolicy` is a generic
+   *  `Generator` field and `sweepOrphans`/`OrphanPolicy` are exported precisely so an
+   *  app can compose its own — so this message must not hardcode `requirement-tests`,
+   *  naming a generator the project may not even use and a cause ("the requirement was
+   *  removed") that may not apply. */
+  generatorName = "orphan cleanup",
+): string {
+  return (
+    `${generatorName}: ${paths.length} generated file(s) are no longer produced by ` +
+    `this generator but have been edited by hand, so they were NOT deleted: ` +
+    `${paths.join(", ")}. Either what produced them was removed (delete these files ` +
+    `yourself if the edits are no longer wanted) or it was renamed (move the edits ` +
+    `into the newly generated file first — regeneration cannot follow a rename).`
+  );
+}

package/src/reference/barrel.ts

@@ -2,6 +2,10 @@
 // Then import it LOCALLY in metaobjects.config.ts instead of from the package:
 //   import { barrel } from "./codegen/generators/barrel.js";
 //
+// RUNTIME: this file executes under whatever runs `meta gen`, and the published CLI's
+// shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
+// reach for `Bun.*` globals here; they are undefined and take the whole run down with
+// `Bun is not defined`. Use `node:` builtins instead.
 // use-when:      you want a single `index.ts` re-exporting every generated entity module.
 // emits:         <target>/index.ts with one `export * from "./<Entity>"` per entity, alphabetical.
 // customize:     the export form (star vs named), ordering, grouping by package, what to include/exclude.

package/src/reference/entity.ts

@@ -2,6 +2,10 @@
 // Then import it LOCALLY in metaobjects.config.ts:
 //   import { entityFile } from "./codegen/generators/entity.js";
 //
+// RUNTIME: this file executes under whatever runs `meta gen`, and the published CLI's
+// shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
+// reach for `Bun.*` globals here; they are undefined and take the whole run down with
+// `Bun is not defined`. Use `node:` builtins instead.
 // use-when:      ALWAYS — this is the entity-module generator. It owns the shape of each
 //                generated <Entity>.ts (the Drizzle table, Zod schemas, inferred types,
 //                constants, filter allowlists). Start here and adapt the assembly.

package/src/reference/queries.ts

@@ -2,6 +2,10 @@
 // Then import it LOCALLY in metaobjects.config.ts:
 //   import { queriesFile } from "./codegen/generators/queries.js";
 //
+// RUNTIME: this file executes under whatever runs `meta gen`, and the published CLI's
+// shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
+// reach for `Bun.*` globals here; they are undefined and take the whole run down with
+// `Bun is not defined`. Use `node:` builtins instead.
 // use-when:      you want generated typed CRUD finders (find<E>ById, list<E>s, create/update/delete)
 //                over Drizzle. Drop it if you hand-write your data access.
 // emits:         <target>/<Entity>.queries.ts per source-backed object (any source.rdb kind,

package/src/reference/routes.ts

@@ -2,6 +2,10 @@
 // Then import it LOCALLY in metaobjects.config.ts:
 //   import { routesFile } from "./codegen/generators/routes.js";
 //
+// RUNTIME: this file executes under whatever runs `meta gen`, and the published CLI's
+// shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
+// reach for `Bun.*` globals here; they are undefined and take the whole run down with
+// `Bun is not defined`. Use `node:` builtins instead.
 // use-when:      you want generated Fastify REST routes per entity. Drop it and hand-write routes
 //                if you need bespoke endpoints — or keep it and add handlers via <Entity>.extra.ts.
 // emits:         <target>/<Entity>.routes.ts — full CRUD for write-through entities, read-only

package/src/render-engine/embedded-templates.generated.ts

@@ -9,6 +9,6 @@ export const EMBEDDED_FRAMEWORK_TEMPLATES: Record<string, string> = {
   "api/agent-api.md": "{{{generatedMarker}}}\n\n# {{title}}\n\nGenerated API reference for {{project}}; call these exactly as written. {{importNote}}\n{{#hasSetup}}\n\n## Setup\n{{#setup}}\n- `{{handle}}` — {{{note}}} `{{{snippetInline}}}`\n{{/setup}}\n{{/hasSetup}}\n{{#units}}\n\n## {{node}}\n{{#groups}}\n\n`{{importHeader}}`\n{{#symbols}}\n- `{{signature}}` — {{usage}}{{#throwsMarker}} {{throwsMarker}}{{/throwsMarker}}\n{{/symbols}}\n{{/groups}}\n{{#example}}\n\nExample:\n```ts\n{{{example}}}\n```\n{{/example}}\n{{/units}}\n",
   "api/entity-api.md": "{{{generatedMarker}}}\n\n# {{node}} API\n{{#modelPageHref}}\n\n**Model / metadata:** [{{node}}]({{modelPageHref}})\n{{/modelPageHref}}\n\n> Import paths are relative to your generated-output directory.\n{{#hasSetup}}\n\n## Setup\n\nObtain the runtime handles the calls below need:\n{{#setup}}\n\n- `{{handle}}` — {{{note}}}\n\n```ts\n{{{snippet}}}\n```\n{{/setup}}\n{{/hasSetup}}\n{{#unitExample}}\n\n## Example\n\n```ts\n{{{unitExample}}}\n```\n{{/unitExample}}\n{{#sections}}\n\n## {{heading}}\n{{#symbols}}\n\n### `{{signature}}`\n\n{{usage}}\n\n```ts\n{{importLine}}\n```\n{{#hasFields}}\n\n{{fieldsCaption}}:\n\n| Field | Type | Required | Notes |\n|---|---|---|---|\n{{#fieldRows}}\n| `{{field}}` | `{{{type}}}` | {{required}} | {{notes}} |\n{{/fieldRows}}\n{{/hasFields}}\n{{#mountNote}}\n\nMount: {{{mountNote}}}\n{{/mountNote}}\n{{#throws}}\n\nThrows: {{throws}}\n{{/throws}}\n{{#example}}\n\n```ts\n{{{example}}}\n```\n{{/example}}\n{{/symbols}}\n{{/sections}}\n",
   "api/index.md": "{{{generatedMarker}}}\n\n# {{title}}\n\n{{intro}}\n{{#hasEntities}}\n\n## Entities\n\n{{#entities}}\n- [{{node}}]({{href}}) — {{summary}} ({{symbolCount}} symbol{{^one}}s{{/one}})\n{{/entities}}\n{{/hasEntities}}\n{{#hasTemplates}}\n\n## Templates\n\n{{#templates}}\n- [{{node}}]({{href}}) — {{summary}} ({{symbolCount}} symbol{{^one}}s{{/one}})\n{{/templates}}\n{{/hasTemplates}}\n",
-  "docs/entity-page.md": "{{{generatedMarker}}}\n\n# {{entity.name}}\n{{#summaryLead}}\n\n{{{.}}}\n{{/summaryLead}}\n{{#descriptionQuote}}\n\n{{{.}}}\n{{/descriptionQuote}}\n{{#apiRefs.0}}\n\n**API reference:** {{/apiRefs.0}}{{#apiRefs}}[{{label}}]({{href}}){{^last}} · {{/last}}{{/apiRefs}}{{#apiRefs.0}}\n{{/apiRefs.0}}\n\n{{{preambleHeader}}}\n{{#hasIdentities}}\n\n## Identity\n\n{{#identities}}\n- {{{bullet}}}\n{{/identities}}\n{{/hasIdentities}}\n{{#hasNeighborhoodEr}}\n\n## In context\n\n{{{neighborhoodErBlock}}}\n{{/hasNeighborhoodEr}}\n{{#fields.hasFields}}\n\n## Fields\n\n| Field | Type | Required | Column | Rules |\n|---|---|---|---|---|\n{{#fields.rows}}\n| {{{fieldCell}}} | {{{typeCell}}} | {{requiredCell}} | {{{storageCell}}} | {{{rulesCell}}} |\n{{/fields.rows}}\n{{/fields.hasFields}}\n{{#fieldDetails.hasDetails}}\n\n## Field details\n\n{{#fieldDetails.rows}}\n{{{block}}}\n\n{{/fieldDetails.rows}}\n{{/fieldDetails.hasDetails}}\n{{#hasRelationships}}\n\n## Relationships\n\n{{#relationships}}\n- {{{bullet}}}\n{{/relationships}}\n{{/hasRelationships}}\n{{#hasUsedBy}}\n\n## Used by\n\n{{#usedBy}}\n- {{{bullet}}}\n{{/usedBy}}\n{{/hasUsedBy}}\n",
+  "docs/entity-page.md": "{{{generatedMarker}}}\n\n# {{entity.name}}\n{{#summaryLead}}\n\n{{{.}}}\n{{/summaryLead}}\n{{#descriptionQuote}}\n\n{{{.}}}\n{{/descriptionQuote}}\n{{#apiRefs.0}}\n\n**API reference:** {{/apiRefs.0}}{{#apiRefs}}[{{label}}]({{href}}){{^last}} · {{/last}}{{/apiRefs}}{{#apiRefs.0}}\n{{/apiRefs.0}}\n\n{{{preambleHeader}}}\n{{#hasIdentities}}\n\n## Identity\n\n{{#identities}}\n- {{{bullet}}}\n{{/identities}}\n{{/hasIdentities}}\n{{#hasNeighborhoodEr}}\n\n## In context\n\n{{{neighborhoodErBlock}}}\n{{/hasNeighborhoodEr}}\n{{#fields.hasFields}}\n\n## Fields\n\n| Field | Type | Required | Column | Rules |\n|---|---|---|---|---|\n{{#fields.rows}}\n| {{{fieldCell}}} | {{{typeCell}}} | {{requiredCell}} | {{{storageCell}}} | {{{rulesCell}}} |\n{{/fields.rows}}\n{{/fields.hasFields}}\n{{#fieldDetails.hasDetails}}\n\n## Field details\n\n{{#fieldDetails.rows}}\n{{{block}}}\n\n{{/fieldDetails.rows}}\n{{/fieldDetails.hasDetails}}\n{{#hasRelationships}}\n\n## Relationships\n\n{{#relationships}}\n- {{{bullet}}}\n{{/relationships}}\n{{/hasRelationships}}\n{{#hasUsedBy}}\n\n## Used by\n\n{{#usedBy}}\n- {{{bullet}}}\n{{/usedBy}}\n{{/hasUsedBy}}\n{{#hasClaimedBy}}\n\n## Required by\n\n{{#claimedBy}}\n- {{{bullet}}}\n{{/claimedBy}}\n{{/hasClaimedBy}}\n",
   "docs/template-page.md": "{{{generatedMarker}}}\n\n# {{name}}\n{{#descriptionQuote}}\n\n{{{.}}}\n{{/descriptionQuote}}\n\n**Kind:** {{kind}}\n\n## Output\n{{^isEmail}}\n\n- Format: `{{format}}`\n{{/isEmail}}\n{{#isEmail}}\n\nMultipart email — rendered as the following parts:\n\n| Part | Source | Format | Escaping |\n|---|---|---|---|\n{{#parts}}\n| {{label}} | `{{ref}}` | `{{format}}` | {{#escaped}}escaped{{/escaped}}{{^escaped}}raw{{/escaped}} |\n{{/parts}}\n{{/isEmail}}\n\n## Input\n\n- Payload: [`{{payload.name}}`]({{payload.link}})\n{{#hasRequiredTags}}\n- Required fields:{{#requiredTags}} `{{.}}`{{/requiredTags}}\n{{/hasRequiredTags}}\n\n## Render contract\n\n- Every field referenced by the template is validated against the payload at generation time; an unknown field fails generation.\n{{#maxChars}}\n- Maximum length: {{.}} characters (rendering longer output fails).\n{{/maxChars}}\n{{#hasRequiredTags}}\n- Required tags must be present:{{#requiredTags}} `{{.}}`{{/requiredTags}}\n{{/hasRequiredTags}}\n\n## Source\n\n{{#sourceRefs}}\n- `{{.}}`\n{{/sourceRefs}}\n{{#templateSourceSection}}\n\n{{{.}}}\n{{/templateSourceSection}}\n\n## Capability\n\n{{capability}}\n",
 };

package/src/requirement-walk.ts

@@ -0,0 +1,124 @@
+// FR-038 — walking `requirement.*` nodes and projecting them for downstream filters.
+//
+// WHY A WALK RATHER THAN ctx.matches: the `Generator` contract is entity-shaped —
+// `GenContext.entities` is `MetaObject[]` and `filter` is
+// `(entity: MetaObject) => boolean` — so a requirement-driven generator cannot use
+// it and must walk `loadedRoot` itself. Generalising `Generator` over any node kind
+// is the principled fix and is deliberately out of scope: it is a core contract
+// change touching every existing generator in five ports.
+//
+// WHY A PROJECTION rather than the raw node: an application's filter is app-owned
+// policy (FR-038 §5), and handing it a `MetaData` would bind adopter code to
+// metamodel internals and export the ADR-0039 own-vs-resolving accessor trap. The
+// projection is additive — it can grow, but it never hands out the node.
+
+import { TYPE_REQUIREMENT, resolveClaim } from "@metaobjectsdev/metadata";
+import type { MetaData, MetaRequirement } from "@metaobjectsdev/metadata";
+
+/** The shape an app's `filter` receives. Never the node itself. */
+export interface RequirementView {
+  /** "functional" | "architectural" — the check-polarity axis. */
+  readonly subType: string;
+  /** 1 solution · 2 segment · 3 service · 4 object · 5 member. Undefined on an
+   *  unlevelled architectural requirement (the original flat policy form). */
+  readonly level: number | undefined;
+  readonly status: string | undefined;
+  /** Dotted path from the root through nesting ancestors — hierarchy is nesting. */
+  readonly path: string;
+  /** DISTINCT `type.subType` concerns among the resolved targets. */
+  readonly implementedByTypes: readonly string[];
+}
+
+export interface ResolvedClaim {
+  /** The reference exactly as authored, for the doc comment. */
+  readonly ref: string;
+  readonly node: MetaData;
+  readonly concern: string;
+}
+
+export interface WalkedRequirement {
+  readonly node: MetaRequirement;
+  readonly view: RequirementView;
+  readonly targets: readonly ResolvedClaim[];
+}
+
+/** `<type>.<subType>` — the key a renderer map is looked up by. */
+export function concernOf(node: MetaData): string {
+  return `${node.type}.${node.subType}`;
+}
+
+/**
+ * The concern key for a requirement that resolves NO targets.
+ *
+ * Doubles as the catch-all renderer key, deliberately: a requirement with nothing
+ * to fan out over falls through to whatever the app registered as its default.
+ */
+export const NO_CONCERN = "*";
+
+/**
+ * Depth-first walk of every `requirement.*` node, nested ones included.
+ *
+ * Unresolvable `@implementedBy` references are skipped rather than thrown on —
+ * resolution severity is `meta verify`'s job (it depends on `@status`, which is why
+ * it cannot live in the loader), and codegen must not fail a build over a
+ * diagnostic another command owns.
+ */
+export function walkRequirements(root: MetaData): WalkedRequirement[] {
+  const out: WalkedRequirement[] = [];
+
+  const visit = (node: MetaData, prefix: string): void => {
+    if (node.type !== TYPE_REQUIREMENT) return;
+    const path = prefix === "" ? node.name : `${prefix}.${node.name}`;
+    const req = node as MetaRequirement;
+    // Same referrer-package basis the CLI's checks use, so a bare reference binds
+    // package-locally under the ADR-0042 contract.
+    const referrerPkg = node.package ?? node.fileDefaultPackage ?? "";
+
+    const targets: ResolvedClaim[] = [];
+    for (const ref of req.implementedBy()) {
+      const target = resolveClaim(root, ref, referrerPkg);
+      if (target === undefined) continue;
+      targets.push({ ref, node: target, concern: concernOf(target) });
+    }
+
+    out.push({
+      node: req,
+      view: {
+        subType: node.subType,
+        level: req.level(),
+        status: req.status(),
+        path,
+        implementedByTypes: [...new Set(targets.map((t) => t.concern))],
+      },
+      targets,
+    });
+
+    for (const child of node.children()) visit(child, path);
+  };
+
+  for (const child of root.children()) visit(child, "");
+  return out;
+}
+
+/**
+ * Group a requirement's targets by distinct concern — the fan-out unit.
+ *
+ * One entry per distinct `type.subType`, NOT one per target: a single architectural
+ * requirement claimed by 123 entities must emit one stub, not 123, which is the
+ * hostile-first-contact outcome FR-038 §10 exists to avoid.
+ *
+ * A requirement resolving NO targets still yields exactly ONE group. That is not a
+ * degenerate case: `REQUIREMENT_LINK_FLOOR_LEVEL` forbids `@implementedBy` below L4,
+ * so every L1–L3 requirement resolves nothing — and an application that chooses to
+ * cover L3 would otherwise get silence instead of a stub.
+ */
+export function groupByConcern(w: WalkedRequirement): Map<string, ResolvedClaim[]> {
+  const groups = new Map<string, ResolvedClaim[]>();
+  for (const t of w.targets) {
+    const existing = groups.get(t.concern);
+    if (existing === undefined) groups.set(t.concern, [t]);
+    else existing.push(t);
+  }
+  if (groups.size === 0) groups.set(NO_CONCERN, []);
+  return groups;
+}