Repository navigation
feat(codegen-ts): add CodeWriter and TsWriter layout foundation (ADR-0063) - #587
Merged
Merged
Conversation
…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.
…ratchet allowlist, counts) TsWriter reads Code from src/poet.ts (the ts-poet copy main vendored in #579), so a generator's imp() imports are collected again. The layout ratchet's allowlist gains the six main files that type layout (one unconverted helper, four JSON document writers and the vendored printer, exempt). Corpus count 41.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What Changed
CodeWriterandTsWriterto@metaobjectsdev/codegen-ts, exported from the package root and@metaobjects-ts/engine: a generator states what a line contains, the writer lays out the file in memory (indentation, blank-line requests that collapse, fit-or-break lists at 120 columns, import collection from ts-poetCodefragments) with no formatter pass. Both classes are built for subclassing — every method is public or protected so an adopter can override one step without ejecting (ADR-0063).spec/code-writer.md, the cross-portfixtures/writer-conformance/corpus (44 cases: core layout dialect + TypeScript import/doc dialect), and a layout ratchet test that keeps generator source off hand-typed layout.engine-surface.ts) so ejected generators keep importing them; no shipped generator uses the writer yet, so generated output is unchanged in this release.This work targets 1.3.0 on
main. It replaces #586, the earlier attempt based onrelease/1.2.no-mistakes runs: 2 for the writer work. The first run was on the
release/1.2branch (PR 586). This second run, onmain, passed every step; the document step's one info finding (the CLAUDE.md codegen-substrate line) was approved without a change because that line is still correct.Validation
Risk Assessment
✅ Low: Additive, well-bounded change: a new writer exported behind existing entries, an AST-based ratchet with a shrink-only allowlist, and a 41-case corpus whose expectations match the written contract; no shipped generator behavior changes and no intent criterion is contradicted.
Testing
All nine scenarios driven live against the real writer shipped in this change; every one passed with reviewer-visible artifacts (generated module, driver log, tsc log, ratchet failure log). Broad regression was already green at the target commit via the configured command and was not re-run because no source or test files were changed (the ratchet probe was injected and reverted, leaving the worktree clean). No findings — the change satisfies the intent: easy generator authoring with layout owned by the writer, formatting separated from code emission, an AST-based ratchet that genuinely stops hand-typed layout, subclass extension without eject, and poet-fragment interop restored after the rebase to main.
import typefor type-only modules, si…widthfits, one over breaks, an emoji counts as one column (15 UTF-16 units vs 14 code points)import { pgTable, text } from "drizzle-orm/pg-core";above the fragment; foreign-copy check throws "different copy" messageEvidence: Writer-generated TS module (output of the real TsWriter from the public package entry)
// Generated by my owned generator. "use client"; import type { FilterAllowlist } from "@metaobjectsdev/runtime-ts"; import { eq } from "drizzle-orm"; import { z } from "zod"; import type { Condition } from "./conditions"; import { helper } from "./helper"; /** * The filter allowlist for * the Subscriber entity. */ export const subscriberFilterAllowlist = { email: { ops: ["eq", "like"] as const, wildcard: "%@%" }, subscribedAt: { ops: ["eq", "gte", "lte"] as const }, meta: "typed by the writer", } as const satisfies FilterAllowlist; export function buildFilter( p_alphaSomething, ... p_kappaSomething, ) { combine( p_alphaSomethingValue, ...one item per line with trailing comma at 120 columns ); return z.object({ email: z.string(), eq: eq }); }Evidence: Live driver run: 28/28 behavior checks pass
Evidence: Driver script (imports the real @metaobjectsdev/codegen-ts as an owned generator does)
Evidence: tsc on the writer output — zero parse diagnostics, only unresolved synthetic modules
Evidence: Layout ratchet failing on injected hand-typed layout (names file, line, kind), before revert
+ "codegen-ts/src/naming.ts + 298:31 newline-literal "line one\nline two" + 299:14 newline-literal "\n" + 300:32 newline-join ["a", "b"].join(__NL) (fail) the layout ratchet > no generator source types layout unless its file is allowlistedPipeline
Updates from git push no-mistakes
✅ **Intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
✅ **Review** - passed
✅ No issues found.
✅ **Test** - passed
✅ No issues found.
import typefor type-only modules, si…widthfits, one over breaks, an emoji counts as one column (15 UTF-16 units vs 14 code points)import { pgTable, text } from "drizzle-orm/pg-core";above the fragment; foreign-copy check throws "different copy" messagescripts/ci-local.sh --only ts-fast --only ts-unit --strict-toolchainsbaseline broad regression: scripts/ci-local.sh --only ts-fast --only ts-unit --strict-toolchains (already run, passed at target commit; no source changes made this turn, so not re-run)live driver: bun run drive-writer.ts against the real @metaobjectsdev/codegen-ts package entry — 28 behavior checks, all pass (script + log in evidence dir)tsc --noEmit on the writer-generated module — zero parse diagnostics, only synthetic module/name resolution errorsbun test test/layout-ratchet.test.ts clean at target — 46 pass; with injected hand-typed layout probe in src/naming.ts — fails naming newline-literal (direct and constant-hidden) and newline-join; reverted, 46 pass againbun test test/writer-conformance.test.ts test/writer-ts.test.ts — 54 passengine-entry check: import { TsWriter } from "@metaobjectsdev/codegen-ts/engine" works and emits collected importsCLAUDE.md- The project CLAUDE.md "Codegen substrate" line ("the vendored ts-poet printer ... Biome for format pass") is still factually correct today because ADR-0063 converts no shipped generator, but it becomes wrong the moment the first generator converts to the writer and drops the formatter. Policy forbids adding forward-looking content to CLAUDE.md in this phase, so it is left untouched.✅ **Lint** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.