@metaobjectsdev/codegen-ts 0.23.2 → 0.24.0

package/dist/reconcile-orphans.js

@@ -0,0 +1,61 @@
+// 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.
+export function reconcileOrphans(args) {
+    const emitted = new Set(args.emitted);
+    const remove = [];
+    const refused = [];
+    const vanished = [];
+    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, 
+/** 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") {
+    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).`);
+}
+//# sourceMappingURL=reconcile-orphans.js.map

package/dist/reconcile-orphans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile-orphans.js","sourceRoot":"","sources":["../src/reconcile-orphans.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,oBAAoB;AACpB,EAAE;AACF,4EAA4E;AAC5E,iFAAiF;AACjF,kFAAkF;AAClF,mFAAmF;AACnF,yBAAyB;AACzB,EAAE;AACF,iFAAiF;AACjF,mFAAmF;AACnF,+EAA+E;AAC/E,EAAE;AACF,+EAA+E;AAC/E,kFAAkF;AAClF,2CAA2C;AAqE3C,MAAM,UAAU,gBAAgB,CAAC,IAA0B;IACzD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC/C,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,SAAS;QACnC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,SAAS;QAElC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1B,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACvB,SAAS;QACX,CAAC;QAED,yEAAyE;QACzE,0BAA0B;QAC1B,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/B,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACtB,SAAS;QACX,CAAC;QAED,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AACvC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAwB;AACxB;;;;oCAIoC;AACpC,aAAa,GAAG,gBAAgB;IAEhC,OAAO,CACL,GAAG,aAAa,KAAK,KAAK,CAAC,MAAM,+CAA+C;QAChF,yEAAyE;QACzE,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,8DAA8D;QACjF,gFAAgF;QAChF,6EAA6E,CAC9E,CAAC;AACJ,CAAC"}

package/dist/render-engine/embedded-templates.generated.js

@@ -9,7 +9,7 @@ export const EMBEDDED_FRAMEWORK_TEMPLATES = {
     "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",
 };
 //# sourceMappingURL=embedded-templates.generated.js.map

package/dist/render-engine/embedded-templates.generated.js.map

@@ -1 +1 @@
-{"version":3,"file":"embedded-templates.generated.js","sourceRoot":"","sources":["../../src/render-engine/embedded-templates.generated.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,iGAAiG;AACjG,EAAE;AACF,8DAA8D;AAC9D,oEAAoE;AACpE,wEAAwE;AACxE,sDAAsD;AACtD,MAAM,CAAC,MAAM,4BAA4B,GAA2B;IAClE,kBAAkB,EAAE,+fAA+f;IACnhB,mBAAmB,EAAE,88BAA88B;IACn+B,cAAc,EAAE,gYAAgY;IAChZ,qBAAqB,EAAE,wnCAAwnC;IAC/oC,uBAAuB,EAAE,woCAAwoC;CAClqC,CAAC"}
+{"version":3,"file":"embedded-templates.generated.js","sourceRoot":"","sources":["../../src/render-engine/embedded-templates.generated.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,iGAAiG;AACjG,EAAE;AACF,8DAA8D;AAC9D,oEAAoE;AACpE,wEAAwE;AACxE,sDAAsD;AACtD,MAAM,CAAC,MAAM,4BAA4B,GAA2B;IAClE,kBAAkB,EAAE,+fAA+f;IACnhB,mBAAmB,EAAE,88BAA88B;IACn+B,cAAc,EAAE,gYAAgY;IAChZ,qBAAqB,EAAE,kuCAAkuC;IACzvC,uBAAuB,EAAE,woCAAwoC;CAClqC,CAAC"}

package/dist/requirement-walk.d.ts

@@ -0,0 +1,57 @@
+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 declare function concernOf(node: MetaData): string;
+/**
+ * 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 declare 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 declare function walkRequirements(root: MetaData): WalkedRequirement[];
+/**
+ * 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 declare function groupByConcern(w: WalkedRequirement): Map<string, ResolvedClaim[]>;
+//# sourceMappingURL=requirement-walk.d.ts.map

package/dist/requirement-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement-walk.d.ts","sourceRoot":"","sources":["../src/requirement-walk.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE1E,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;gFAC4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAED,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAEhD;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,MAAM,CAAC;AAE9B;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,iBAAiB,EAAE,CAmCpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CASjF"}

package/dist/requirement-walk.js

@@ -0,0 +1,94 @@
+// 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";
+/** `<type>.<subType>` — the key a renderer map is looked up by. */
+export function concernOf(node) {
+    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) {
+    const out = [];
+    const visit = (node, prefix) => {
+        if (node.type !== TYPE_REQUIREMENT)
+            return;
+        const path = prefix === "" ? node.name : `${prefix}.${node.name}`;
+        const req = node;
+        // 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 = [];
+        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) {
+    const groups = new Map();
+    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;
+}
+//# sourceMappingURL=requirement-walk.js.map

package/dist/requirement-walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement-walk.js","sourceRoot":"","sources":["../src/requirement-walk.ts"],"names":[],"mappings":"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"}

package/dist/runner.d.ts

@@ -30,6 +30,41 @@ export interface RunGenOpts {
      * `--dry-run`, and watching it reappear.
      */
     dryRun?: boolean;
+    /**
+     * Output scope — an object is generated only when this predicate returns true
+     * for its fully-qualified name (`obj.resolutionKey()`, `<package>::<name>`).
+     * Intersects with `entityFilter`: both must pass. Absent ⇒ every object is
+     * in scope (byte-identical to a project with no `scope` declared).
+     *
+     * The collection metadata always loads in FULL regardless of this predicate —
+     * scope filters OUTPUT, never input (design §4.3). So an in-scope object may
+     * reference an out-of-scope one (an FK target, a relationship `@objectRef`, a
+     * projection's base) and resolve perfectly at load time, while the code
+     * emitted FOR the in-scope object still imports/names a symbol that was never
+     * generated. This is left silent by design, not auto-widened: the adopter
+     * declared the scope precisely because something else (another consumer,
+     * another codegen run) owns those objects, and the reference is real. Warning
+     * on it correctly would require walking every reference kind (identity.reference,
+     * every relationship.* @objectRef, projection extends bases, field.object
+     * @objectRef) FQN-resolved against the SAME scope — genuinely new machinery,
+     * not a fit for the existing `warnings: string[]` channel at this seam. If an
+     * adopter hits it, the failure is a plain compiler error in the generated
+     * code (an unresolved import) — loud, at build time, not silent at runtime.
+     *
+     * Deliberately a PLAIN PREDICATE, not the `include`/`exclude` pattern strings
+     * `@metaobjectsdev/sdk`'s `scope.ts` compiles. `codegen-ts` must not depend on
+     * `@metaobjectsdev/sdk` — the dependency runs the other way (`cli` depends on
+     * both) — so it cannot import `matchesScope`/`CompiledScope` itself. The
+     * design's "package patterns, never a predicate function" rule (§4.3 of the
+     * metadata-source-resolution design doc) governs CONFIG SURFACES that must
+     * port identically to a `pom.xml` / `metaobjects.config.yaml` in every
+     * language port; it says nothing about internal plumbing between two
+     * TypeScript packages in this one repo. Do not "fix" this into a config
+     * shape — `cli`'s `gen`/`verify` commands are the only callers, and a
+     * `Collection` already exposes exactly this predicate as `inScope`, which
+     * they pass straight through.
+     */
+    scope?: (fqn: string) => boolean;
 }
 export interface RunGenResult {
     files: WriteResult[];

package/dist/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,0BAA0B,CAAC;AAMrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAMpE,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAU/B,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;4BAEwB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;oDACgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;qBAEiB;IACjB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;gDAC4C;IAC5C,SAAS,EAAE,WAAW,EAAE,CAAC;CAC1B;AAkBD,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,CA0UpE"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,0BAA0B,CAAC;AAMrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAQpE,OAAO,EAOL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,uBAAuB,CAAC;AAU/B,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;4BAEwB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;oDACgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;qBAEiB;IACjB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;gDAC4C;IAC5C,SAAS,EAAE,WAAW,EAAE,CAAC;CAC1B;AAkBD,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,CAghBpE"}

package/dist/runner.js

@@ -10,7 +10,9 @@ import { normalizeConfig, DEFAULT_TARGET_NAME } from "./metaobjects-config.js";
 import { buildPkMap } from "./pk-resolver.js";
 import { buildRelationMap } from "./relation-resolver.js";
 import { makeRenderContext } from "./render-context.js";
-import { decideAndWrite, loadEngineVersion, saveEngineVersion, } from "./overwrite-policy.js";
+import { sweepOrphans } from "./orphan-sweep.js";
+import { refusedOrphanMessage } from "./reconcile-orphans.js";
+import { decideAndWrite, previewWriteStatus, hasHashManifest, listGeneratedPaths, loadEngineVersion, saveEngineVersion, } from "./overwrite-policy.js";
 /** JS-identifier-shape only. Prevents filesystem traversal when metadata comes
  *  from untrusted sources (e.g. MCP). Mirrors the guard in legacy generate.ts. */
 const VALID_ENTITY_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -58,6 +60,10 @@ export async function runGen(opts) {
     // since the last gen, note it (generated output may legitimately differ). Purely
     // informational — the version file is separate from `.hashes.json` and never
     // affects the merge. Only fires when a prior stamp exists AND differs.
+    // Captured BEFORE any write, because the first write creates the manifest — read
+    // it afterwards and every project looks migrated.
+    const hadHashManifest = hasHashManifest(genStateDir);
+    const relativeForDisplay = (p) => projectRoot !== undefined ? relative(projectRoot, p) : p;
     const hasPersistentGenState = opts.projectRoot !== undefined || opts.genStateDir !== undefined;
     const installedEngine = hasPersistentGenState ? engineVersion() : undefined;
     const recordedEngine = hasPersistentGenState ? loadEngineVersion(genStateDir) : undefined;
@@ -76,16 +82,49 @@ export async function runGen(opts) {
         throw new Error("runGen: opts.metadata must be a loaded MetaRoot.");
     }
     const root = opts.metadata;
-    // 1. Resolve entities (filter + safety check).
+    // 1. Resolve entities (entityFilter + scope + safety check). This is the
+    // single choke point for entity selection — scope INTERSECTS entityFilter
+    // (an object must pass both), matched against the object's
+    // fully-qualified name (resolutionKey(), never the bare name — two
+    // packages may declare the same short name).
     const allObjects = root.objects();
     const entityFilter = opts.entityFilter;
-    const filtered = entityFilter
+    const afterEntityFilter = entityFilter
         ? allObjects.filter((o) => entityFilter.includes(o.name))
         : allObjects;
+    const scope = opts.scope;
+    const filtered = scope
+        ? afterEntityFilter.filter((o) => scope(o.resolutionKey()))
+        : afterEntityFilter;
     if (filtered.length === 0) {
-        const reason = opts.entityFilter
-            ? "no object children match the provided entityFilter"
-            : "root has no object children";
+        // Name the REAL cause. When `scope` is absent, this is byte-identical to
+        // the pre-scope two-way branch (kept as its own arm, rather than folded
+        // into the scope-aware logic below, so an unscoped project's warning text
+        // — including its quirky edge case: an empty root with entityFilter set
+        // still blames entityFilter — is untouched). Only when `scope` is
+        // present does a THIRD reason become reachable: "root has no object
+        // children" for a scoped-out model, or "...entityFilter" for a scope
+        // that admitted everything entityFilter then excluded, are both false
+        // statements that send the reader to the wrong file.
+        let reason;
+        if (scope === undefined) {
+            // Byte-identical to the pre-scope branch, quirk included: an EMPTY root
+            // with an entityFilter set still blames the filter. Wrong, and untouched
+            // — changing what an unscoped project reads is a behaviour change, and
+            // this is a shape change.
+            reason = entityFilter
+                ? "no object children match the provided entityFilter"
+                : "root has no object children";
+        }
+        else if (allObjects.length === 0) {
+            reason = "root has no object children";
+        }
+        else if (afterEntityFilter.length === 0) {
+            reason = "no object children match the provided entityFilter";
+        }
+        else {
+            reason = "no object children match the configured scope";
+        }
         warnings.push(`No entities to generate — ${reason}.`);
         return { files: [], warnings, conflicts: [] };
     }
@@ -146,12 +185,25 @@ export async function runGen(opts) {
         targetOf(g);
     const entityGen = config.generators.find((g) => g.emitsEntityModule);
     const entityModuleTarget = entityGen ? targetOf(entityGen) : targets[DEFAULT_TARGET_NAME];
-    const needsCrossTarget = config.generators.some((g) => (g.target ?? DEFAULT_TARGET_NAME) !== entityModuleTarget.name);
-    if (needsCrossTarget && entityModuleTarget.importBase === undefined) {
-        throw new Error(`Target "${entityModuleTarget.name}" holds the entity modules that other ` +
-            `targets import, but has no importBase. Set importBase on it (e.g. ` +
-            `"@your-pkg/database/generated").`);
-    }
+    // NO eager importBase check here, deliberately.
+    //
+    // There used to be one: "any generator on a non-entity target ⇒ the entity
+    // target must have importBase". It asked the wrong question — target placement,
+    // not whether anything actually imports across targets — so it convicted every
+    // multi-target project whose second target imports nothing, and the only way
+    // out was to set a value that is provably inert. An adopter hit this with a
+    // requirement-test target that imports no entity modules at all.
+    //
+    // `crossTargetEntityPath` (import-path.ts) is the SOLE consumer of importBase
+    // and already throws when it is missing, naming the resolution that needed it —
+    // and every cross-target entry point (`entityModuleSpecifier`,
+    // `barrelModuleSpecifier`) routes through it. That throw happens inside phase 4,
+    // before the write phase, and the runner tags it with the generator name, so
+    // the diagnostic is strictly better than the one removed here.
+    //
+    // The trade, stated: a generator whose cross-target import is CONDITIONAL now
+    // fails when a model change first makes it real, rather than at config time.
+    // That is the correct moment — it is also the only moment the answer is known.
     // 3. Build shared render state once.
     const pkMap = buildPkMap(root);
     const relationMap = buildRelationMap(root);
@@ -193,6 +245,10 @@ export async function runGen(opts) {
     const includeHonoRoutes = config.generators.some((g) => g.emitsHonoRoutes === true);
     // 4. Run each generator with a per-target render context; collect with full path.
     const emitted = [];
+    // FR-038 §8 — generators that opted into orphan reconciliation, paired with the
+    // directory their policy's relative paths are measured from. Collected here
+    // because `writeOutDir` is resolved per generator inside this loop.
+    const orphanJobs = [];
     for (const generator of config.generators) {
         // ADR-0025: `meta docs` is the single docs door. A `meta gen` config that
         // still lists a deprecated doc generator is warned + skipped, not run — the
@@ -213,6 +269,13 @@ export async function runGen(opts) {
         const writeOutDir = projectRoot !== undefined && !isAbsolute(selfTarget.outDir)
             ? resolve(projectRoot, selfTarget.outDir)
             : selfTarget.outDir;
+        if (generator.orphanPolicy !== undefined) {
+            orphanJobs.push({
+                generatorName: generator.name,
+                writeOutDir,
+                policy: generator.orphanPolicy,
+            });
+        }
         const renderContext = makeRenderContext({
             dialect: config.dialect,
             loadedRoot: root,
@@ -282,17 +345,147 @@ export async function runGen(opts) {
     // 5. Write phase.
     const writes = [];
     const conflicts = [];
+    // FR-038 §8 — reconcile files a previous run generated that this run does not.
+    //
+    // Gated on a real `projectRoot` for a load-bearing reason, not caution: without
+    // one, `decideAndWrite` keys each snapshot by a hash of its absolute path
+    // instead of a project-relative path, so gen-state holds no path to resolve and
+    // reconciliation has nothing to reason about. That gate is also what keeps
+    // `verify --codegen` inert — it runs against a throwaway root whose gen-state is
+    // empty — and what keeps programmatic/test callers from ever deleting a file.
+    // Refusals are reported ONE of two ways, and which one matters more than the
+    // wording. A project with no manifest at all predates the manifest being
+    // committed: every refusal in it has the SAME single cause and the same one-line
+    // fix, so N per-file warnings would be a wall that buries the instruction — the
+    // hostile-first-contact outcome that gets a tool switched off. A project that DOES
+    // have a manifest is refusing because specific files were edited, and there the
+    // per-file naming is the actionable part.
+    //
+    // Self-extinguishing: once the manifest is committed, the aggregate never fires
+    // again.
+    const MAX_NAMED = 5;
+    const reportRefusals = () => {
+        const refused = writes.filter((w) => w.status === "refused");
+        if (refused.length === 0)
+            return;
+        if (!hadHashManifest) {
+            const names = refused.slice(0, MAX_NAMED).map((w) => relativeForDisplay(w.path));
+            const more = refused.length > MAX_NAMED ? `, and ${refused.length - MAX_NAMED} more` : "";
+            warnings.push(`Refused to overwrite ${refused.length} existing file(s), and this project has ` +
+                `no codegen hash manifest — so 'meta gen' cannot tell your edits from its own ` +
+                `stale output, and it will not guess. This is the expected first run for a ` +
+                `project created before the manifest was committed. ` +
+                `ONE-TIME FIX: commit '.metaobjects/.gen-state/.hashes.json' (un-ignore it in ` +
+                `.metaobjects/.gitignore with '.gen-state/*' + '!.gen-state/.hashes.json'), ` +
+                `then re-run. To adopt fresh output and DISCARD any hand edits in these files ` +
+                `instead, re-run with --baseline=fresh. Files: ${names.join(", ")}${more}.`);
+            return;
+        }
+        for (const w of refused) {
+            warnings.push(`Refused to overwrite ${w.path}: ${w.conflictHint ?? "content differs and could not be verified as generated."}`);
+        }
+    };
+    const sweep = (dryRun) => {
+        if (projectRoot === undefined || orphanJobs.length === 0)
+            return;
+        // NEVER reconcile a PARTIAL run. `meta gen <entity>` narrows the object set, so
+        // `emitted` is a subset of the full output BY CONSTRUCTION — every path belonging
+        // to an unselected entity looks exactly like an orphan, and the untouched ones get
+        // deleted. The shipped `requirementTests()` escapes only by accident (it walks
+        // `ctx.loadedRoot` and ignores `ctx.matches`); any app generator that honours
+        // `ctx.matches` — the documented, encouraged composition — would wipe every
+        // non-selected entity's output on a routine filtered run.
+        //
+        // The runner is the ONLY layer that knows the run was partial: a generator sees a
+        // narrowed entity list and cannot tell it from a model that genuinely has one
+        // entity. So the guard has to live here.
+        if (opts.entityFilter !== undefined && opts.entityFilter.length > 0) {
+            // Say it only when something was ACTUALLY withheld. With no previously-generated
+            // path outside this run's own output there are no orphan candidates at all, so
+            // the sweep provably no-ops and there is nothing to report. `meta gen <entity>`
+            // is a routine command; warning on every one of them teaches the reader to skim
+            // the message, which is how the real one gets skimmed too.
+            //
+            // Note the manifest is NOT empty here even on a first run — the writes above have
+            // already recorded this run's own paths in it — so the emitted set has to come
+            // out before counting. Computing the candidate set is safe on a filtered run;
+            // what must never happen is ACTING on it.
+            //
+            // A non-empty candidate set is the FLOOR, not proof that a specific file would
+            // have been removed: whether one falls inside an opting-in generator's namespace
+            // is the reconcile's answer, and running that is the thing being skipped.
+            const emittedRel = new Set(emitted.map((f) => relative(projectRoot, f.fullPath)));
+            const withheld = listGeneratedPaths(genStateDir).filter((p) => !emittedRel.has(p));
+            if (withheld.length > 0) {
+                warnings.push(`Skipped orphan cleanup: this run generated only ${opts.entityFilter.join(", ")}, ` +
+                    `so it cannot tell a file belonging to an unselected entity from one that is no ` +
+                    `longer generated. Run 'meta gen' with no entity filter to reconcile deletions.`);
+            }
+            return;
+        }
+        const result = sweepOrphans({
+            genStateDir,
+            projectRoot,
+            emittedRelPaths: emitted.map((f) => relative(projectRoot, f.fullPath)),
+            jobs: orphanJobs,
+            dryRun,
+        });
+        // Both kinds are the same file outcome — gone. What differs is what it cost,
+        // which is what the warning below is for.
+        for (const relPath of [...result.removed, ...result.forced]) {
+            writes.push({ path: join(projectRoot, relPath), status: "removed" });
+        }
+        if (result.refused.length > 0) {
+            // Grouped by the generator that refused, so each message names a generator the
+            // project actually registered. `orphanPolicy` is generic and apps are encouraged
+            // to compose their own, so one blanket message naming `requirement-tests` would
+            // be wrong for precisely the users the seam exists for.
+            const byGenerator = new Map();
+            for (const relPath of result.refused) {
+                const owner = result.refusedBy.get(relPath) ?? "orphan cleanup";
+                const list = byGenerator.get(owner);
+                if (list === undefined)
+                    byGenerator.set(owner, [relPath]);
+                else
+                    list.push(relPath);
+            }
+            for (const [owner, paths] of byGenerator) {
+                warnings.push(refusedOrphanMessage(paths, owner));
+            }
+        }
+        if (result.forced.length > 0) {
+            warnings.push(`Deleted ${result.forced.length} hand-edited generated file(s) because a ` +
+                `generator's orphanPolicy sets force: ${result.forced.join(", ")}. ` +
+                `Hand-written content in them is gone — recover from version control.`);
+        }
+    };
     // --dry-run: report what WOULD be written and touch nothing — no output files
     // and no .gen-state/ snapshot (writing the snapshot would silently re-baseline
     // the merge base, so a later real run could skip a genuinely-needed write).
     if (opts.dryRun === true) {
         for (const file of emitted) {
-            // Report the outcome faithfully rather than a placeholder: a path that does
-            // not exist yet would be created ("new"), one that does would be rewritten.
-            // Merge/conflict outcomes can't be known without doing the merge, so this
-            // deliberately reports the coarser truth instead of guessing.
-            writes.push({ path: file.fullPath, status: existsSync(file.fullPath) ? "overwrite" : "new" });
+            // Ask the same policy the real run asks, in a read-only mode. This used to be
+            // `existsSync(...) ? "overwrite" : "new"`, which previewed a hand-edited file
+            // as "overwrite" while the real run refused it — the one case the preview most
+            // needs to be right about. A merge outcome is still coarse (see
+            // previewWriteStatus), because clean-vs-conflicted is unknowable without merging.
+            const policyOpts = {
+                strategy,
+                genStateDir,
+                baseline,
+            };
+            if (projectRoot !== undefined) {
+                policyOpts.outputRelPath = relative(projectRoot, file.fullPath);
+            }
+            writes.push({
+                path: file.fullPath,
+                status: previewWriteStatus(file.fullPath, file.content, policyOpts),
+            });
         }
+        reportRefusals();
+        // A preview that hides a pending deletion is worse than no preview at all, so
+        // the sweep still runs — in decide-and-report mode, touching nothing.
+        sweep(true);
         return { files: writes, warnings, conflicts };
     }
     for (const file of emitted) {
@@ -315,11 +508,14 @@ export async function runGen(opts) {
             warnings.push(`Merge conflict in ${file.fullPath}: resolve diff3 markers and re-run ` +
                 `'meta gen' to advance the canonical state.`);
         }
-        if (result.status === "refused") {
-            warnings.push(`Refused to overwrite ${file.fullPath}: file exists without @generated header. ` +
-                `Move to a different outDir, delete the file, or add the header to opt in.`);
-        }
+        // Refusals are reported together after the loop (see reportRefusals) so a
+        // whole-project cause can be stated once instead of once per file.
     }
+    reportRefusals();
+    // Sweep AFTER the writes: writing is the primary job, and a deletion that runs
+    // first would be unrecoverable if a later write threw. Ordering cannot change
+    // the decision — a path this run emitted is never an orphan either way.
+    sweep(false);
     // #232 — stamp the engine version that produced this snapshot, so the NEXT gen can
     // detect an engine change. Written after a successful run only.
     if (installedEngine !== undefined)