no-mistakes(document): sync docs for declarative template-codegen scopes (SP-1a)

Author: dmealing

CHANGELOG.md

@@ -8,6 +8,23 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ## [Unreleased]
 
 ### Added
+- **codegen-ts — declarative Mustache template-codegen (SP-1a):** a
+  `templateGenerator` can now take its walk **declaratively** via `scope`
+  (`"perEntity" | "perPackage" | "perModel"`) + `outputPattern` instead of a
+  hand-written `walk` (the two are mutually exclusive — provide exactly one). The
+  generator derives a **neutral, structural** template data dict per unit
+  (`buildEntityTemplateData` / `buildPackageTemplateData` / `buildModelTemplateData`,
+  with types `FieldTemplateData` / `EntityTemplateData` / `IdentityTemplateData` /
+  `RelationshipTemplateData` / `PackageTemplateData` / `ModelTemplateData`) — raw
+  structural facts only, distinct from the Markdown-flavored `EntityDocData`, and
+  byte-gated as a cross-port contract by `fixtures/template-codegen-conformance/`.
+  `outputPattern` supports `{name}` / `{Name}` / `{package}` (`::` → `/`; unknown
+  placeholder throws), expandable via the exported `expandOutputPattern`. A JSON
+  **template-spec** (`parseTemplateSpec` / `templateSpecToGenerators`, types
+  `TemplateSpecEntry` / `TemplateSpecFile`, JSON Schema beside the source) is the
+  surface the C#/Python CLI ports will reuse. New package-scope engine helper
+  `perPackage(fn)` joins `perEntity` / `perModel`. All exported from the package
+  main entry `@metaobjectsdev/codegen-ts`.
 - **cli — `meta init` scaffolds owned codegen generators (ADR-0034 scaffold-and-own, step 2):**
   `meta init` now copies the four codegen reference templates (step 1) into the
   consumer repo at `codegen/generators/{entity,queries,routes,barrel}.ts` and
@@ -34,6 +51,10 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   generator-export deprecation, and the guidance rewrite are later steps.)
 
 ### Deprecated
+- **codegen-ts — `oncePerRun` scope helper (SP-1a):** renamed to `perModel` —
+  "run" is ambiguous under multi-target output (it reads as "per target"), while
+  `perModel` names the data scope (the whole model). `oncePerRun` is kept as a
+  soft-deprecated alias and still works.
 - **codegen-ts — `@metaobjectsdev/codegen-ts/generators` factory re-exports
   (ADR-0034 scaffold-and-own, step 2):** importing `entityFile` / `queriesFile` /
   `routesFile` / `barrel` from the package `/generators` export is deprecated in

docs/features/codegen-concepts.md

@@ -150,14 +150,34 @@ whole-model are just different walks.
 **The model to expose.** Three scope helpers, so the scope is declared, not buried in
 custom iteration:
 
-- **`perEntity(fn)`** — object scope. *(exists)*
-- **`perPackage(fn)`** — package scope: group matching objects by package, run `fn`
-  once per package. *(the gap — Java never had this cleanly either, so this is an
-  improvement on the predecessor, not just parity.)*
-- **`oncePerRun(fn)`** — app scope: run once over all matching objects. *(exists; an
-  `appLevel` alias can make the intent explicit.)*
+- **`perEntity(fn)`** — object scope. Runs `fn` once per matched object.
+- **`perPackage(fn)`** — package scope: group matching objects by package (packages
+  ascending, objects keeping `ctx.entities` order), run `fn` once per package. Groups
+  by `effectivePackage` so objects with a bare FQN (FR5d) still bucket correctly.
+- **`perModel(fn)`** — app scope: run once over all matching objects. (`oncePerRun`
+  is kept as a soft-deprecated alias — "run" is ambiguous under multi-target output;
+  `perModel` names the data scope.)
 
 A generator picks its scope by which helper it composes — the same way it picks
-object vs run today. Reference templates and the guidance call out the scope each
+object vs model today. Reference templates and the guidance call out the scope each
 starting point is for, so "I need a per-package service layer" maps to a clear
 pattern instead of hand-rolled grouping.
+
+### Declarative template scopes
+
+A `templateGenerator` can take the scope walk declaratively instead of a hand-written
+`walk` — pass `scope` (`"perEntity" | "perPackage" | "perModel"`) plus an
+`outputPattern`, and the generator derives the neutral template data dict per unit and
+names each file via the pattern. `walk` and `scope` are mutually exclusive — provide
+exactly one. The `outputPattern` placeholders are `{name}`, `{Name}`, and `{package}`
+(an unknown placeholder throws); `{package}` resolves through `effectivePackage` and
+renders `::`-separated segments as nested path directories.
+
+```ts
+templateGenerator({
+  name: "entity-doc",
+  scope: "perEntity",
+  outputPattern: "{package}/{Name}.md",
+  template: "entity-doc",
+});
+```

docs/features/codegen-data-shapes.md

@@ -68,6 +68,44 @@ trivial and cross-port walkers don't have to re-derive the rules.
 file into your project; the project's `templates/` directory takes precedence
 over the framework defaults. Same for any partial under `templates/docs/`.
 
+### Neutral structural shapes → `EntityTemplateData` / `PackageTemplateData` / `ModelTemplateData`
+
+The declarative template scopes (`scope: "perEntity" | "perPackage" | "perModel"`
+on `templateGenerator`) feed a **neutral, structural** data dict — deliberately
+distinct from the Markdown-flavored `EntityDocData` above. It carries raw
+structural facts only, so a consumer's template can emit any language's code from
+it. The field names are a byte-gated **cross-port contract** (the
+`fixtures/template-codegen-conformance/` corpus locks them) — change them only via
+the spec.
+
+```ts
+interface FieldTemplateData {
+  name: string;
+  type: string;            // neutral subtype: "string" | "int" | "currency" | "enum" | ...
+  required: boolean;
+  isArray: boolean;        // arrayness is carried here, NOT appended to `type`
+  maxLength?: number;
+  enumValues?: string[];   // present only for field.enum
+}
+interface IdentityTemplateData { kind: string; fields: string[]; }
+interface RelationshipTemplateData { name: string; cardinality: string; targetRef: string; }
+interface EntityTemplateData {
+  name: string;
+  package: string;         // effective package (`::`-separated), "" when none
+  fields: FieldTemplateData[];
+  identities: IdentityTemplateData[];
+  relationships: RelationshipTemplateData[];
+}
+interface PackageTemplateData { package: string; entities: EntityTemplateData[]; }
+interface ModelTemplateData { packages: PackageTemplateData[]; }   // packages ascending
+```
+
+These types and their builders (`buildEntityTemplateData`,
+`buildPackageTemplateData`, `buildModelTemplateData`) are exported from the package
+**main entry** (`@metaobjectsdev/codegen-ts`), alongside `expandOutputPattern` and
+the JSON template-spec parser (`parseTemplateSpec`, `templateSpecToGenerators`).
+Abstract objects are excluded from every scope (they emit no instance artifact).
+
 ### Section-presence flags (`hasX`)
 
 Mustache cleanly iterates an array (`{{#identities}}...{{/identities}}`) but

server/typescript/packages/codegen-ts/README.md

@@ -86,7 +86,8 @@ from the **owned local copies** that `meta init` scaffolds into
 `codegen/generators/` (ADR-0034 scaffold-and-own). Importing them from
 `@metaobjectsdev/codegen-ts/generators` still works but is **deprecated** — own a
 copy instead; the package export will be removed in a future major. The engine and
-primitives (`runGen`, `perEntity`, `oncePerRun`, `RenderContext`, the loader and
+primitives (`runGen`, the scope helpers `perEntity` / `perPackage` / `perModel`
+(`oncePerRun` is a soft-deprecated alias of `perModel`), `RenderContext`, the loader and
 render helpers) remain the stable, versioned import from `@metaobjectsdev/codegen-ts`,
 and an owned generator imports them from there.