Skip to content

feat(codegen-ts): add CodeWriter and TsWriter, generators own layout (ADR-0063) - #586

Closed
dmealing wants to merge 13 commits into
mainfrom
fm/mo-writer-foundation-1-2
Closed

dmealing wants to merge 13 commits into
mainfrom
fm/mo-writer-foundation-1-2

Conversation

@dmealing

@dmealing dmealing commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

What Changed

  • Added CodeWriter and TsWriter to codegen-ts and exported both, with the engine surface and generator registry fixture updated. CodeWriter builds output in memory. It owns indentation, treats blank lines as requests (collapsed, and dropped at file start and end, after an opener and before a closer), normalizes line endings, and prints a list on one line when it fits, otherwise one item per line with a trailing comma. TsWriter adds import collection and sorting, doc comments, and a 120-column default, and accepts existing Code fragments so generators can convert one at a time. Both classes are non-final with overridable methods, so adopters can extend reference generators by subclassing. No generator is converted and generated output is unchanged.
  • Added the contract and tests. ADR-0063 (generators own layout; formatters are test oracles only; overridable methods may change between minor versions) and spec/code-writer.md describe the design. The new fixtures/writer-conformance/ corpus holds 41 JSON cases, run by writer-conformance.test.ts. writer-ts.test.ts covers TsWriter, including a subclass overriding one method.
  • Added a layout ratchet test. It parses generator source with the TypeScript compiler API and flags string and template literal parts that carry layout, join and joinCode calls with a newline separator, and repeat calls that build indentation. It resolves same-file constants, so const NL = "\n" cannot hide a violation. It has its own positive and negative cases. Its allowlist lists every unconverted generator file with a written reason, and a test fails if an allowlisted file no longer needs its entry. AGENTS.md, CHANGELOG.md and docs/CONFORMANCE.md are updated to match.
Validation

After validation

This PR took one no-mistakes run. These commits came after it:

  • Merged release/1.2, which brings in feat(codegen): skip gen when nothing changed, in every port #585 (gen skip, ADR-0062). The conflicts in CHANGELOG.md and spec/decisions/README.md were both-sides additions and kept both. no-mistakes axi triage --post-merge judged the resolution docs-only, so no new run was needed.
  • Cherry-picked b6dec3694 from the merge fast-path lane as 019f921a4. It is tests only, with no production lines: an unedited file never spawns git merge-file and its hash advances, and a thrown merge leaves no temp file (codegen-ts/test/overwrite-policy/merge-fastpath.test.ts).
  • Exempted codegen-ts/src/model-hash.ts (from feat(codegen): skip gen when nothing changed, in every port #585) in the layout ratchet's allowlist. It joins sorted lines with a newline to build the text the gen skip key hashes. That text is never written to a file, so like overwrite-policy.ts it is exempt, not an unconverted generator. The ratchet caught it on the merge, as intended.
  • Corpus count is now 36. Both branches had moved it from 34 to 35, so after the merge docs/CONFORMANCE.md, AGENTS.md and the site payload say 36.

scripts/ci-local.sh --quick was run after the merge. Every gate passed except the site payload one, which was only the stale count. After the count commit, that gate (bun test scripts/site and build-site-payload.ts --check) passed, and the pre-push build and typecheck were clean.

Risk Assessment

✅ Low: The fix round is a small, correct reorder of the line-break check in put() plus one matching fixture case and a case-count doc update. No generator uses the writer yet, so no generated output changes.

Testing

I ran the real writer through a driver script, and ran the real ratchet against deliberately bad generator source. The scripts/ci-local.sh baseline had already passed before I started. - TsWriter (live): one realistic TS file mixing ts-poet Code fragments and collected imports came out sorted, had no trailing whitespace, and ended in a single newline. It compiled with no syntax diagnostics, and a long call broke one argument per line with trailing commas. - Error codes (live): line("a;\n"), "a;\r\n", "\n", a bare \r and an interior newline all throw ERR_WRITER_NEWLINE_IN_LINE. Unclosed block, unbalanced close and import conflict also throw their documented codes. - Subclassing (live): a subclass overriding writeHeader and another overriding fits both changed the output, as the extension-by-subclassing requirement asks. - Ratchet (live): analyzeSource caught a newline hidden behind a chain of constants and an indentation .repeat. It ignored comments and writer-based code. I appended hand-typed layout to a clean generator file (src/reference/callable.ts) and the real ratchet test failed, naming the file and lines. After I reverted, it passed again and the worktree is clean. - Regression: codegen-ts bun test passed (3000 tests, 0 failures). scripts/ci-local.sh --quick passed (ts build and typecheck, TypeScript conformance, ts unit suites, hygiene gates, mutation on changed files). - Not run: the C#, Java, Kotlin and Python lanes of the flagless ci-local.sh. The change is TypeScript-only and converts no generator. A mixed call(..., [props()]) that is too long for one line prints as z.object( then { on its own line, rather than z.object({. This follows spec/code-writer.md as written and is not a defect, but you may want a "hug" rule later; I raised it as an info finding.

  • Live validation: ✅ go - 7 of 7 scenarios driven live against the product
Scenario Result Live Evidence
TsWriter writes a realistic TS file (collected imports, ts-poet Code fragment, long call wrapped one-per-line) that compiles ✅ pass live drive-output.txt
line() refuses trailing and interior line breaks with ERR_WRITER_NEWLINE_IN_LINE (the review-1 fix) ✅ pass live drive-output.txt
An adopter subclass overrides one writer method (writeHeader, fits) and the output changes ✅ pass live drive-output.txt
Writer misuse (unclosed block, unbalanced close, import conflict) fails with the documented error codes ✅ pass live drive-output.txt
Layout ratchet catches a newline hidden behind constants and ignores comments and clean writer code ✅ pass live ratchet-output.txt
The real ratchet test fails when a non-allowlisted generator file gains hand-typed layout ✅ pass live ratchet-injected-fail.txt
Writer conformance corpus (41 cases) and writer unit tests pass; engine surface and registry list the writer modules ✅ pass live codegen-ts-suite.txt
Evidence: writer live driver output
// generated

import type { Kysely } from "kysely";
import { z } from "zod";
import { Foo } from "./foo.js";

export const customerSchema = z.object(
  {
    id: z.string().uuid(),
    name: z.string().min(1).max(200),
    email: z.string().email().max(320).optional().nullable().default(null),
    createdAt: z.coerce.date(),
  },
);

export function build(db: Kysely<unknown>) {
  const names = ["alpha", "bravo", "charlie"];

  const x = Foo(1);
  return run(
    db,
    argumentNumber0,
    argumentNumber1,
    argumentNumber2,
    argumentNumber3,
    argumentNumber4,
    argumentNumber5,
    argumentNumber6,
    argumentNumber7,
    argumentNumber8,
    argumentNumber9,
    argumentNumber10,
    argumentNumber11,
    argumentNumber12,
    argumentNumber13,
  );
}

{
  "endsWithOneNewline": true,
  "maxWidth": 75,
  "noTrailingWs": true,
  "syntaxDiagnostics": 0,
  "line:\"a;\\n\"": "ERR_WRITER_NEWLINE_IN_LINE",
  "line:\"a;\\r\\n\"": "ERR_WRITER_NEWLINE_IN_LINE",
  "line:\"\\n\"": "ERR_WRITER_NEWLINE_IN_LINE",
  "line:\"a;\\rb\"": "ERR_WRITER_NEWLINE_IN_LINE",
  "line:\"a;\\nb;\"": "ERR_WRITER_NEWLINE_IN_LINE",
  "subclass": "// custom header\n\nexport const a = 1;\n",
  "subclassFits": "f([aaaaaaaaaa, bbbbbbbbbb])\n",
  "unclosed": "ERR_WRITER_UNCLOSED_BLOCK",
  "unbalanced": "ERR_WRITER_UNBALANCED_CLOSE",
  "conflict": "ERR_WRITER_IMPORT_CONFLICT"
}
Evidence: ratchet analyzer driver output
indirect [["newline-literal",1],["newline-join",3]]
commentOnly []
cleanWriter []
indentRepeat [["indent-literal",1],["indent-repeat",1]]
Evidence: ratchet failing on injected hand-typed layout
202 |       "Write these lines through TsWriter (src/writer/) instead of typing line breaks or indentation. " +
203 |         "A file is never added to the allowlist: it only shrinks.",
204 |     ).toEqual([]);
            ^
error: Write these lines through TsWriter (src/writer/) instead of typing line breaks or indentation. A file is never added to the allowlist: it only shrinks.

- []
+ [
+   
+ "codegen-ts/src/reference/callable.ts
+   73:14 newline-literal "\n"
+   74:40 newline-join r.join(NL_X)"
+ ,
+ ]

- Expected  - 1
+ Received  + 7

      at <anonymous> ({run-worktree}/server/typescript/packages/codegen-ts/test/layout-ratchet.test.ts:204:7)
(fail) the layout ratchet > no generator source types layout unless its file is allowlisted [0.38ms]

 45 pass
 1 fail
 275 expect() calls
Ran 46 tests across 1 file. [279.00ms]
Evidence: codegen-ts full suite

test/format.test.ts:
[codegen-ts] Biome formatter: 2 diagnostics; first: expected `,` but instead found `'x'`

 3000 pass
 0 fail
 2 snapshots, 12581 expect() calls
Ran 3000 tests across 296 files. [57.99s]
Evidence: ci-local --quick
metaobjects local CI  (mode: quick — TS + drift gates only)

── ▶ leak-scan (security) ──────────────────────────────────────────────
leak-scan: clean
── ✓ leak-scan (security) (0s)

── ▶ pom-version parity ──────────────────────────────────────────────
check-pom-versions: ✓ 3 parent + 1 property pom(s) match reactor 8.2.2
── ✓ pom-version parity (0s)

── ▶ bun-version parity ──────────────────────────────────────────────
check-bun-version: bun 1.3.14 matches the workflow pin.
── ✓ bun-version parity (0s)

── ▶ uv.lock version parity ──────────────────────────────────────────────
check-uv-lock-version: uv.lock agrees with pyproject.toml (1.2.1)
── ✓ uv.lock version parity (0s)

── ▶ publish-intent parity ──────────────────────────────────────────────
publish-intent parity: OK (lockstep 1.2.2; 2 declared source-only)
── ✓ publish-intent parity (1s)

── ▶ publish-set parity ──────────────────────────────────────────────
   1. @metaobjectsdev/metadata  (server/typescript/packages/metadata)
   2. @metaobjectsdev/render  (server/typescript/packages/render)
   3. @metaobjectsdev/docs-site  (server/typescript/packages/docs-site)
   4. @metaobjectsdev/migrate-ts  (server/typescript/packages/migrate-ts)
   5. @metaobjectsdev/codegen-ts  (server/typescript/packages/codegen-ts)
   6. @metaobjectsdev/runtime-ts  (server/typescript/packages/runtime-ts)
   7. @metaobjectsdev/sdk  (server/typescript/packages/sdk)
   8. @metaobjectsdev/runtime-web  (client/web/packages/runtime-web)
   9. @metaobjectsdev/codegen-ts-react  (server/typescript/packages/codegen-ts-react)
  10. @metaobjectsdev/codegen-ts-tanstack  (server/typescript/packages/codegen-ts-tanstack)
  11. @metaobjectsdev/react  (client/web/packages/react)
  12. @metaobjectsdev/tanstack  (client/web/packages/tanstack)
  13. @metaobjectsdev/cli  (server/typescript/packages/cli)
  14. @metaobjectsdev/ai-runtime  (server/typescript/packages/ai-runtime)
publish set: OK (lockstep 1.2.2; 14 packages, tier-ordered, closed over sibling deps)
ok:   happy path: private + off-lockstep excluded, order [metadata, render, docs-site, cli]
ok:   untiered member: threw on "publish order undeclared"
ok:   unclosed set: threw on "not closed over its own runtime dependencies"
ok:   inverted tier order: threw on "publishes a dependency AFTER its dependent"
ok:   regression: docs-site (#2) publishes before cli (#12) in the real tree
ok:   regression: docs-site has a declared tier

publish-set tests: all passed
── ✓ publish-set parity (0s)

── ▶ no committed pre-release version ──────────────────────────────────────────────
check-no-prerelease-versions: ✓ no pre-release version in any version declaration
── ✓ no committed pre-release version (0s)

── ▶ script-name hook collisions ──────────────────────────────────────────────
script-name-hooks: ✓ 10 root scripts, no lifecycle-hook collisions
── ✓ script-name hook collisions (0s)

── ▶ ci lane selection ──────────────────────────────────────────────
ok:   [server/typescript/packages/cli/src/x.ts] -> 'ts'
ok:   [client/web/packages/react/src/y.tsx] -> 'ts'
ok:   [server/java/metadata/src/main/java/A.java] -> 'java'
ok:   [server/java/codegen-kotlin/src/main/kotlin/B.kt] -> 'java'
ok:   [server/python/src/metaobjects/loader.py] -> 'python'
ok:   [server/csharp/MetaObjects/Loader.cs] -> 'csharp'
ok:   [fixtures/conformance/foo/meta.json] -> 'ts java python csharp'
ok:   [spec/metamodel.md] -> 'ts java python csharp'
ok:   [scripts/ci-local.sh] -> 'ts java python csharp'
ok:   [.github/workflows/local-ci.yml] -> 'ts java python csharp'
ok:   [agent-context/skills/x.md] -> 'ts java python csharp'
ok:   [weird-new-toplevel/file.txt] -> 'ts java python csharp'
ok:   [docs/features/cli.md] -> ''
ok:   [README.md CHANGELOG.md] -> ''
ok:   [server/typescript/a.ts server/python/b.py] -> 'ts python'
ok:   [docs/x.md fixtures/y.json] -> 'ts java python csharp'
ALL PASS
ok:   union all -> 'ts java python csharp'
ok:   union reorders to canonical -> 'ts java python csharp'
ok:   union deduplicates -> 'ts java'
ok:   union single -> 'python'
ok:   union empty -> ''
ok:   union drops unknown tokens -> 'ts'
ok:   every lane green -> nothing to re-run -> ''
ok:   docs-only run skips a red java -> java still not green -> 'java'
ok:   one red ts lane selects the whole ts port -> 'ts'
ok:   skipped is walked past to the real verdict -> ''
ok:   cancelled is not green -> 'csharp'
ok:   a lane with no verdict in the window is not green -> 'python'
ok:   no history at all -> everything -> 'ts java python csharp'
ok:   every port-testing job in .github/workflows/local-ci.yml is mapped by lane_port -> ''
ok:   every lane in lane_port exists as a job in .github/workflows/local-ci.yml -> ''
all checks passed
── ✓ ci lane selection (0s)

── ▶ extract field kinds ──────────────────────────────────────────────
extract FieldKind: 4 ports agree on [STRING, INT, LONG, DOUBLE, BOOLEAN, ENUM, OBJECT] (1 sanctioned deviation(s): csharp)
── ✓ extract field kinds (0s)

── ▶ no-magic gate wired (5 ports) ──────────────────────────────────────────────
no-magic gate coverage: 5 ports wired; 13 shapes tracked, 0 known gaps
── ✓ no-magic gate wired (5 ports) (0s)

── ▶ test-file references resolve ──────────────────────────────────────────────
test-file references: 32 named, all resolve
── ✓ test-file references resolve (0s)

── ▶ metamodel-version bump ──────────────────────────────────────────────
  metamodel-version: none change since v1.2.2; declared 1.2 — ok.
ok:   no change classifies as nothing
ok:   a removed subtype is BREAKING
ok:   an added subtype is ADDITIVE
ok:   a removed attr is BREAKING
ok:   an added OPTIONAL attr is ADDITIVE
ok:   an added REQUIRED attr is BREAKING
ok:   optional → required is BREAKING
ok:   required → optional is ADDITIVE
ok:   a changed valueType is BREAKING
ok:   a changed isArray is BREAKING
ok:   an enum member REMOVED is BREAKING
ok:   an enum member ADDED is ADDITIVE
ok:   an OPEN attr becoming a closed enum is BREAKING
ok:   a closed enum OPENING is ADDITIVE
ok:   a removed child rule is BREAKING
ok:   an added OPTIONAL child rule is ADDITIVE
ok:   an added MANDATORY child rule is BREAKING
ok:   raising min is BREAKING
ok:   lowering min is ADDITIVE
ok:   capping an unbounded max is BREAKING
ok:   lifting a cap is ADDITIVE
ok:   lowering a finite max is BREAKING
ok:   a removed commonAttr is BREAKING
ok:   a changed default subtype is BREAKING (it changes what an unqualified declaration MEANS)
ok:   a removed default subtype is BREAKING
ok:   an added default subtype is ADDITIVE
ok:   a type description change is PROSE ONLY
ok:   a `rules` change is PROSE ONLY — this is exactly #210, and why prose only warns
ok:   an attr description change is PROSE ONLY
ok:   no change requires no bump
ok:   additive requires a minor
ok:   post-1.0 br

... [303155 bytes truncated] ...

n it

 1871 pass
 8 skip
 0 fail
 1 snapshots, 8145 expect() calls
Ran 1879 tests across 198 files. [128.08s]
── ✓ conformance: typescript (3m52s)

── ▶ ts unit suites ──────────────────────────────────────────────
bun install v1.3.14 (0d9b296a)

Checked 691 installs across 720 packages (no changes) [18.00ms]
@metaobjectsdev/metadata build: Exited with code 0
@metaobjectsdev/runtime-web build: Exited with code 0
@metaobjectsdev/angular build: Exited with code 0
@metaobjectsdev/tanstack build: Exited with code 0
@metaobjectsdev/react build: Exited with code 0
@metaobjectsdev/sdk bundle-agent-context: bundled agent-context → {run-worktree}/server/typescript/packages/sdk/agent-context
@metaobjectsdev/sdk bundle-agent-context: Exited with code 0
bun test v1.3.14 (0d9b296a)

test/registry-coverage.test.ts:

[registry-coverage] subtypes: 53/65 exercised (81.5%), 12 UNTESTED
[registry-coverage] untested subtypes:
  attr.boolean
  attr.class
  attr.double
  attr.expression
  attr.filter
  attr.int
  attr.intMap
  attr.long
  validator.atLeastOne
  validator.comparison
  validator.presentIff
  validator.requiredWhen
[registry-coverage] exercised subtypes with untested attrs: 27

 3806 pass
 0 fail
 11342 expect() calls
Ran 3806 tests across 193 files. [7.57s]
bun test v1.3.14 (0d9b296a)

 472 pass
 0 fail
 1747 expect() calls
Ran 472 tests across 25 files. [150.00ms]
bun test v1.3.14 (0d9b296a)

 867 pass
 14 skip
 0 fail
 2126 expect() calls
Ran 881 tests across 62 files. [3.55s]
bun test v1.3.14 (0d9b296a)

 156 pass
 0 fail
 702 expect() calls
Ran 156 tests across 29 files. [2.85s]
bun test v1.3.14 (0d9b296a)

 61 pass
 0 fail
 191 expect() calls
Ran 61 tests across 15 files. [806.00ms]
bun test v1.3.14 (0d9b296a)

 23 pass
 0 fail
 90 expect() calls
Ran 23 tests across 3 files. [492.00ms]
bun test v1.3.14 (0d9b296a)

 396 pass
 0 fail
 1021 expect() calls
Ran 396 tests across 37 files. [735.00ms]
bun test v1.3.14 (0d9b296a)

 21 pass
 0 fail
 71 expect() calls
Ran 21 tests across 6 files. [57.00ms]
bun test v1.3.14 (0d9b296a)

 58 pass
 0 fail
 123 expect() calls
Ran 58 tests across 11 files. [118.00ms]
bun test v1.3.14 (0d9b296a)

 59 pass
 0 fail
 1 snapshots, 426 expect() calls
Ran 59 tests across 20 files. [660.00ms]
bun test v1.3.14 (0d9b296a)

 105 pass
 0 fail
 194 expect() calls
Ran 105 tests across 9 files. [152.00ms]
bun test v1.3.14 (0d9b296a)

 21 pass
 0 fail
 38 expect() calls
Ran 21 tests across 4 files. [682.00ms]
bun test v1.3.14 (0d9b296a)

 49 pass
 0 fail
 76 expect() calls
Ran 49 tests across 6 files. [584.00ms]
bun test v1.3.14 (0d9b296a)

 21 pass
 0 fail
 35 expect() calls
Ran 21 tests across 4 files. [362.00ms]
── ✓ ts unit suites (23s)

── ▶ completeness-gate (mutation, changed files) ──────────────────────────────────────────────

  ⊘ SKIP mutation: none of the 6 files in stryker.conf.mjs 'mutate' changed since origin/release/1.2 (merge base 10f1f447448b).
    The full pass runs in the flagless run's mutation lane, in --only mutation, and in conformance.yml.
── ✓ completeness-gate (mutation, changed files) (0s)

── ▶ doc-template drift ──────────────────────────────────────────────
synced: {run-worktree}/templates/docs/entity-page.md.mustache -> {run-worktree}/server/typescript/packages/codegen-ts/templates/docs/entity-page.md.mustache
synced: {run-worktree}/templates/docs/template-page.md.mustache -> {run-worktree}/server/typescript/packages/codegen-ts/templates/docs/template-page.md.mustache
synced: {run-worktree}/templates/api/agent-api.md.mustache -> {run-worktree}/server/typescript/packages/codegen-ts/templates/api/agent-api.md.mustache
synced: {run-worktree}/templates/api/entity-api.md.mustache -> {run-worktree}/server/typescript/packages/codegen-ts/templates/api/entity-api.md.mustache
synced: {run-worktree}/templates/api/index.md.mustache -> {run-worktree}/server/typescript/packages/codegen-ts/templates/api/index.md.mustache
generated {run-worktree}/server/typescript/packages/codegen-ts/src/render-engine/embedded-templates.generated.ts (5 template(s): api/agent-api.md, api/entity-api.md, api/index.md, docs/entity-page.md, docs/template-page.md)
doc templates synced from canonical root: {run-worktree}/templates (docs api)
── ✓ doc-template drift (0s)

── ▶ embedded-library drift ──────────────────────────────────────────────
wrote 6 embedded library file(s) + 2 manifest(s) to server/typescript/packages/metadata/src/library/embedded-library.generated.ts, server/java/metadata/src/main/java/com/metaobjects/library/EmbeddedLibrary.java and server/csharp/MetaObjects/Library/EmbeddedLibrary.cs
── ✓ embedded-library drift (0s)

── ⊘ --quick: SKIPPING the other-language ports (csharp/java/python/kotlin),
        the full Java reactor, the docker integration suite and the cube live
        check. Run the full `scripts/ci-local.sh` (no flag) before opening/merging
        a PR or tagging.

══════════════════════ SUMMARY ══════════════════════
  ✓ leak-scan (security)
  ✓ pom-version parity
  ✓ bun-version parity
  ✓ uv.lock version parity
  ✓ publish-intent parity  (1s)
  ✓ publish-set parity
  ✓ no committed pre-release version
  ✓ script-name hook collisions
  ✓ ci lane selection
  ✓ extract field kinds
  ✓ no-magic gate wired (5 ports)
  ✓ test-file references resolve
  ✓ metamodel-version bump
  ✓ positioning claims
  ✓ hosted assess prompt builds
  ✓ migration guides vs registry
  ✓ dependencies installed
  ✓ peer-range bounds
  ✓ owned template copies current
  ✓ reference templates lint  (1s)
  ✓ shipped doc examples load
  ✓ no retired $apiPrefix
  ✓ site payload is true  (22s)
  ✓ site reference is fresh  (1s)
  ✓ release tag gate  (10s)
  ✓ scripts/ typecheck  (3s)
  ✓ requirements ledger verifies  (2s)
  ✓ requirements cover vocabulary
  ✓ metamodel scaffolder  (1s)
  ✓ requirement harness
  ✓ fixture-lint
  ✓ ts build + typecheck  (17s)
  ✓ conformance: typescript  (3m52s)
  ✓ ts unit suites  (23s)
  ✓ completeness-gate (mutation, changed files)
  ✓ doc-template drift
  ✓ embedded-library drift
  ⊘ csharp/java/python/kotlin conformance (--quick)
  ⊘ java-reactor (--quick)
  ⊘ integration-tests (--quick)
  ⊘ cube-model live check (--quick)
── slowest steps ──
     3m52s  conformance: typescript
       23s  ts unit suites
       22s  site payload is true
       17s  ts build + typecheck
       10s  release tag gate
        3s  scripts/ typecheck
        2s  requirements ledger verifies
        1s  metamodel scaffolder
        1s  publish-intent parity
        1s  reference templates lint
        1s  site reference is fresh
  total wall time: 5m13s
══════════════════════════════════════════════════════
LOCAL CI PASSED (with 4 skipped — see ⊘ above).
  • Outcome: ⚠️ 1 info across 1 run (44m52s)

Pipeline

Updates from git push no-mistakes

✅ **Intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed ✅
  • ⚠️ server/typescript/packages/codegen-ts/src/writer/code-writer.ts:227 - put() tests for a line break only after flat(piece).trimEnd(). A trailing line break is stripped before the ERR_WRITER_NEWLINE_IN_LINE check. So w.line(&#34;a;\n&#34;), w.line(&#34;a;\r\n&#34;) and w.line(&#34;\n&#34;) do not throw: the first two write a;, and the last becomes a blank-line request. spec/code-writer.md says line text containing a line break (\n, \r\n or \r) is ERR_WRITER_NEWLINE_IN_LINE, with no trailing exception. The common hand-typed form, a template literal ending in \n, passes silently instead of being refused. The other ports' writers will implement the spec as written, so they would throw on input this one accepts. The existing case error-newline-in-line only covers an interior break (&#34;a;\nb;&#34;), so the gap is untested. Fix: run ANY_LINE_BREAK.test on the untrimmed flat(piece) before trimEnd(), and add a fixture case with a trailing newline. The same check also covers TsWriter.code/piece input routed through line() (src/writer/ts-writer.ts:129-140), since it all goes through put.

🔧 Fix applied.
✅ Re-checked - no issues remain.

⚠️ **Test** - 1 info
  • ℹ️ A call() whose only argument is a props() literal that is too long for one line prints as z.object( then { on its own line, instead of the idiomatic z.object({. This follows the spec as written (the last list breaks one item per line), so it is not a defect. If the later conversions should read as a formatter would write them, a hug rule for a sole object or array argument would fix it.
  • Live validation: ✅ go - 7 of 7 scenarios driven live against the product
Scenario Result Live Evidence
TsWriter writes a realistic TS file (collected imports, ts-poet Code fragment, long call wrapped one-per-line) that compiles ✅ pass live drive-output.txt
line() refuses trailing and interior line breaks with ERR_WRITER_NEWLINE_IN_LINE (the review-1 fix) ✅ pass live drive-output.txt
An adopter subclass overrides one writer method (writeHeader, fits) and the output changes ✅ pass live drive-output.txt
Writer misuse (unclosed block, unbalanced close, import conflict) fails with the documented error codes ✅ pass live drive-output.txt
Layout ratchet catches a newline hidden behind constants and ignores comments and clean writer code ✅ pass live ratchet-output.txt
The real ratchet test fails when a non-allowlisted generator file gains hand-typed layout ✅ pass live ratchet-injected-fail.txt
Writer conformance corpus (41 cases) and writer unit tests pass; engine surface and registry list the writer modules ✅ pass live codegen-ts-suite.txt
  • scripts/ci-local.sh --only ts-fast --only ts-unit --strict-toolchains
  • bun test in server/typescript/packages/codegen-ts, for writer-conformance, writer-ts and layout-ratchet tests (100 pass)
  • bun &lt;evidence&gt;/drive.ts: live TsWriter/CodeWriter driver for output shape, newline refusal, error codes, subclass overrides
  • bun &lt;evidence&gt;/ratchet-drive.ts: analyzeSource on constant indirection, comments, writer code, indentation repeat
  • Injected hand-typed layout into src/reference/callable.ts and ran bun test test/layout-ratchet.test.ts: it failed as intended. Reverted, passed again.
  • bun test in server/typescript/packages/codegen-ts (3000 pass, 0 fail)
  • scripts/ci-local.sh --quick (exit 0)
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

… routes (#566)

* fix(python): generated routes hand the repository only the validated input (1.2.1)

The generated FastAPI create, PATCH and PUT handlers validated the body against
<Entity>Create / <Entity>Patch and then passed the RAW body to the repository.
Pydantic ignores undeclared keys and the input models leave out server-owned
fields, so a client-sent id, a readOnly field and a made-up field such as
isAdmin all reached the write. Security fix.

Each handler (plain and TPH per-subtype) now rebinds dto to the keys the input
model validated, at every depth, before any repository call, as the TypeScript
routes do. Undeclared and non-settable keys are dropped silently, never 400'd,
so a client sending an extra harmless field keeps working; values stay the
body's own, so repositories see the same value types as in 1.2.0.

Python package version 1.2.1 only; CHANGELOG entry under Security.
Regression gate: tests/integration/test_generated_router_validated_input.py.

* no-mistakes(document): python routes pass only validated input

* no-mistakes(lint): regenerate showcase site payload for PyPI 1.2.1
…2.x security) (#568)

* fix: generated create routes store only client-settable fields (1.2.x security)

Python 1.2.1 stopped its generated routes from handing raw request input to
the repository. The same audit found related create-path holes in 1.2.0 in
the other four ports; this closes each in its own idiom. Server-owned values
are dropped silently, never answered with 400.

- Java (codegen-spring): create strips a generated id, readOnly and derived
  fields; a TPH per-subtype create also strips the body discriminator and
  sibling-subtype fields.
- Kotlin (codegen-kotlin): create skips readOnly/derived columns; a TPH
  per-subtype create writes only the route subtype's own columns.
- C# (MetaObjects.Codegen): every readOnly property shape gets a private
  setter; create resets a generated id, the TPH discriminator and M:N
  navigations before Add.
- TypeScript (codegen-ts): the update schema omits primary-key fields, so
  PUT/PATCH can no longer re-key a row with an assigned key.

Proof: new shared api-contract scenarios (core + TPH input-server-owned,
TPH foreign discriminator) and a readOnly `role` field in secret-fields, run
in every port's generated lane and the reference lanes; a new `unset`
assertion key in all five harnesses. In-memory test repositories now store
what they are handed, so the scenarios fail on the 1.2.0 generators.

Proposed versions (not published): npm 1.2.2, NuGet 1.2.2, Maven 8.2.2;
PyPI unchanged at 1.2.1. metamodelVersion unchanged.

* fix: keep a @required readOnly field creatable in C# and Java generated create

Pre-gate review follow-ups to the 1.2.x create-input patch:

- C#: the required-key check skips readOnly fields (the private setter
  never binds them), and create validation ignores a violation naming
  only a @required readOnly member, as Java's SERVER_OWNED_ON_CREATE does.
- Java: the create-validation server-owned set covers every DTO component,
  so a nulled readOnly or derived value-object column no longer 400s.
- TypeScript: drop the now-dead PK guard in the update-schema nullable arm
  and list the PK rule in updateSchemaFields' doc comment.

* no-mistakes(review): apply reviewer inline fixes

* no-mistakes(review): Kotlin readOnly create fix + C# reset skip

* no-mistakes(document): docs: finish stale corpus counts from input fix
…ases from release branches (#578)

* fix(csharp): a frozen node's memoized reads are safe across threads

MetaData.Cached stored derived reads in a plain Dictionary. A loaded model
is shared across threads, so two concurrent first reads of one node could
corrupt it, and every later read then threw "Operations that change
non-concurrent collections must have exclusive access". The cache is now a
ConcurrentDictionary; a racing first read keeps the first stored value.

Brought onto release/1.2 from main's fix (a266a51) for the 1.2.2 patch.

* feat(release): cut a patch from a release/<major>.<minor> maintenance branch

release.mjs and finish-release.mjs refused any branch but main, so a patch
on a line main has moved past could not go through its own guarded scripts.
Both now accept release/<major>.<minor> as well (one shared rule in
scripts/lib/release-branch.mjs): the version must be on that branch's own
line, every push goes to that branch, and finish-release's sync check
compares HEAD with origin/<branch>. Every other gate is unchanged.

docs/RELEASING.md gains the maintenance-branch section, including that the
site deploys from the newest vN.N.N tag wherever it was cut.

* no-mistakes(review): gate latest-regression before npm publish; clean unpushed-branch die

* no-mistakes(review): refuse an rc of an already-shipped version

* no-mistakes(document): docs: fix RELEASING.md main-only release claims
The ts-fast lane (and so --quick, --only ts and the no-mistakes Test step)
ran the full Stryker pass over all six metadata files on every run: 10-45
minutes of CPU per gate round on a loaded host, most of that step's wall time.

The step now diffs the stryker.conf.mjs `mutate` list against the merge base
with the base branch (MO_CI_MUTATION_BASE, else origin/$GITHUB_BASE_REF, else
whichever of origin/main and origin/release/* HEAD is closest to) and runs
`stryker run --mutate` on only the changed files. When none changed it prints
a SKIP naming the base. When no base resolves, or stryker.conf.mjs itself
changed, it says so and runs the full pass. Thresholds and concurrency are
unchanged; the list stays in stryker.conf.mjs only.

The full pass stays: the flagless run's mutation lane, a new
`--only mutation` section for release prep and on demand, and conformance.yml
(tags, nightly, dispatch) via MO_CI_MUTATION_SCOPE=full. Stryker's sandbox goes
under DEV_SCRATCH when that names a directory, and is removed afterwards.
…chet (ADR-0063)

Generators own their layout; formatters become test oracles only (ADR-0063).
This change lands the foundation and converts no generator, so generated
output is unchanged.

- spec/code-writer.md: the shared writer contract (lines and blocks,
  blank-line requests, snippets, fit-or-break lists, output form, and the
  TypeScript dialect's import collection).
- fixtures/writer-conformance/: 40 cases (30 core, 10 TypeScript), the 35th
  shared corpus.
- CodeWriter and TsWriter (codegen-ts/src/writer/), at 120 columns, exported
  from the package root and the engine entry and listed in
  eject.engineSurface. TsWriter accepts ts-poet Code fragments and collects
  their imports, so generators can convert one function at a time.
- Layout ratchet: an AST walk (ts.createSourceFile) over generator source
  that flags newline and indentation literals, newline joins and repeat-built
  indentation, resolving same-file constants. It has its own catch/pass
  cases. The allowlist names all 74 unconverted files with reasons, fails on
  stale entries and may only shrink against the merge base.
…classing (ADR-0063)

CodeWriter and TsWriter keep no private members: their steps are protected
methods (piece, breakAt, fits, writeHeader, writeImports, writeImport,
orderModules), so a subclass overrides one and keeps the rest. ADR-0063 item 7
and spec/code-writer.md state that reference generators take the same shape,
one overridable method per piece of output, and that these methods are not a
stability contract. A test shows a subclass overriding orderModules.
* feat(codegen): skip gen when nothing changed, in every port (ADR-0062)

- gen builds a key from the loaded model (each root node in canonical effective
  form, rolled up per package) plus the generators' identity (built engine code,
  config, owned generators, templates, declared extra inputs, project config,
  output-changing flags), before anything renders. When it matches the last
  successful run and every generated file still holds that run's bytes, gen
  renders and writes nothing. --force (Maven: -Dmetaobjects.force=true) turns it
  off; a generator that cannot declare its inputs opts out (cache: false or the
  port's equivalent).
- verify --codegen always renders in CI; locally it may answer "no drift" from
  the key and the manifest, --full forces a render. When it renders, every port
  compares in memory: no rendered temp tree (Java/Kotlin now capture through
  GeneratedFileWriter).
- The hash manifest is loaded once and written once per run, only when it
  changed (TypeScript, Python, C#). Identical bytes are never rewritten in any
  port. Python gen no longer reports unchanged files as written.
- TypeScript runs git merge-file only for a file edited by hand, and deletes its
  temporaries in a finally, under $DEV_SCRATCH when set.
- fixtures/codegen-skip-conformance/cases.json: 25 shared cases run by every port.

* test(python): non-prompt targets rewrite nothing and save no manifest when unchanged

Two targets, four generators: a forced run over unchanged output keeps every
mtime and saves no manifest; a first run saves it once. Also corrects a stale
comment in verify --codegen, which renders in memory.

* no-mistakes(review): apply reviewer inline fixes

* no-mistakes(review): Track unrecorded outputs in the skip key

* no-mistakes(review): Track outside-root outputs in TS skip key

* no-mistakes(review): Store no skip key after refused orphan sweep

* no-mistakes(review): Hash YAML sources when docs-site is wired

* no-mistakes(document): document gen skip and in-memory verify

* no-mistakes(document): document gen skip in llms mirror

* no-mistakes(lint): Update corpora count to 35 in site payload and AGENTS.md

* test(agent-context): regenerate conformance expected copies

The skill references in agent-context/ now describe verify --codegen as
rendering in memory. Refresh the byte-for-byte expected mirrors to match.
…oundation-1-2

# Conflicts:
#	CHANGELOG.md
#	spec/decisions/README.md
…and a thrown merge leaves no temp file

#585 added the fast path and per-merge temp cleanup; these decideAndWrite-level
tests pin the two cases it left untested: an unedited file regenerates with
META_GEN_GIT pointing at a missing binary (so any spawn would throw) and advances
its snapshot and hash, and a merge that throws GitMissingError leaves nothing in
mergeTempDir(). Clean merge and conflict are re-asserted at the same level.
…t ratchet

release/1.2 brought in src/model-hash.ts (ADR-0062), which joins sorted lines
with a newline to feed sha256. That text is hash input, never a file, so it is
exempt like overwrite-policy.ts rather than an unconverted generator.
…d corpora)

Both branches moved the corpus count from 34 to 35, so the merge kept 35.
With both corpora present the count is 36.
@dmealing

Copy link
Copy Markdown
Member Author

This work moved to #587, which targets 1.3.0 on main. This PR stays as the record of the earlier attempt on release/1.2 and is being closed. Its branch is kept.

@dmealing dmealing closed this Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant