[Zaba505]

Closes #410

A new worked example, example/receivables/. It is an accounts-receivable transaction extract (recfm FB, lrecl 80), and it regenerates from a layout and one definitions file. There is no copybook anywhere in the project. Its vendor-style source copybook is a fixture outside example/, at testdata/vendor/ARTRANS.

Acceptance criteria

• A new example directory holds cpybkc.json, receivables.sexpr (a layout naming definitions files), ARTRANS.sexpr (the definitions file), the generated receivables/ and graph/, and cpybkc.gen.json. It holds no .cpy. The source copybook is testdata/vendor/ARTRANS, written the way a vendor ships one: an extensionless member, sequence numbers in columns 1–6, a release stamp in 73–80 and a do-not-modify banner.

• example/regenerate_test.go regenerates it byte for byte. This needs no new code, because the existing walks pick it up. There are two new tests:

  • TestTheReceivablesDefinitionsFileIsWhatInitWrites runs cpybkc init --copybook ../../testdata/vendor/ARTRANS from inside the example. It requires exactly the example's definitions files, byte for byte. It also requires every record form in the example's layout to be one that init's scaffold writes, character for character.
  • TestTheReceivablesLayoutResolvesAlikeFromItsCopybookAFileAndABlock names the fixture copybook in place of the file and requires the same --emit-ir descriptor. It also carries out the README's file-to-block move and its block-to-file move as written, and requires the same descriptor after each. The move back must give the committed layout and file again, less the file's header comment.

• The fixture carries 88-levels (including a multi-value one), VALUE (a 77, 88s, FILLER VALUE SPACES), SIGN LEADING SEPARATE and SIGN TRAILING SEPARATE, SYNC on two binary items (slack at offsets 13 and 22), and a 77-level. Its REDEFINES has three alternatives over ARD-BODY, so one definitions file serves five records, three of them one 01-level.

• example/receivables/README.md walks through these procedures, using the example's own files:

  • story(cli): decide how cpybkc init writes a definitions file per copybook beside the layout it scaffolds #403's copybook-to-file migration;
  • the drift procedure, with a real diff -u from a hypothetical release 3.2;
  • the file-to-block move and the block-to-file move.

  Each move shows the --emit-ir before and after, cmp'd, and identical. No inline variant is committed. To make story(resolve): a record whose definitions are written in a block in the layout resolves to the descriptor its copybook gives, with every fault pointing into the layout #409's suite actually build one for this example, internal/project/equality_test.go's inline now converts definitions-file sources into blocks as well as copybook sources. convert treats a layout naming only definitions files as converted already, and still refuses a layout naming neither.

• example/README.md gains a receivables/ row naming it as exactly what cpybkc init writes, and TestTheIndexNamesEveryExample passes. The "one manifest per example" prose names it. Its "what is asserted" section describes the two new tests.

  • README.md: the worked-examples line ("a layout, the copybooks it names") is reworded, and so is "All four projects", which is now five. The tour gains a receivables/ paragraph, and A manifest does not list copybooks points at the example.
  • The layout Mapping row (Record definitions) names story(layout): a worked example whose project ships definitions files and no copybook #410 and Record types defined in layout #394.

Judgment calls

• The layout keeps init's record forms verbatim. That includes the long derived names (ART-DETAIL-REC-ARD-INVOICE). The layout renames them for the generated code, so "the example is exactly what init writes" holds for the record forms as well as the definitions file, and the test checks both. The scaffold's ART-DETAIL-REC-ARD-BODY record is left out, because a real extract never carries the base description of a redefined run. Narrowing to the data is the layout's job, and the definitions file does not change.
• The definitions file's header names ../../testdata/vendor/ARTRANS, the path as typed from the example directory. The README's drift command is that same command, so against an unchanged copybook the diff is empty.
• The layout is receivables.sexpr, not artrans.sexpr. A layout name equal to a derived definitions-file name (case-folded) is a usage error.
• No public API changes. Only tests, docs, a fixture and generated example code are touched.

Found along the way, not fixed here

cpybkc-gen-go accepts receiver=r, but then generates code that does not compile: the receiver collides with the r *codec.Reader parameter of UnmarshalCOBOL. w presumably collides with *codec.Writer the same way. isReceiverName accepts both. This example uses receiver=a. The bug probably deserves its own story.

Verification

• dagger call ci from an ordinary clone (a worktree cannot run dagger): passed.
• go test ./example/... ./internal/project/...: passed. Both new tests were mutation-checked: an edited ARTRANS.sexpr fails both.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

The changes align with the stated acceptance criteria and add thorough tests/docs; only a minor test-helper diagnostic-message clarity nit was found.

No open issues 🎉

7 files not reviewed

• example/receivables/receivables/codec.go: Generated file
• example/receivables/receivables/doc.go: Generated file
• example/receivables/receivables/file.go: Generated file
• example/receivables/receivables/file_test.go: Generated file
• example/receivables/receivables/literals.go: Generated file
• example/receivables/receivables/records.go: Generated file
• example/receivables/receivables/records_test.go: Generated file

What changed in this PR

Adds a new worked example project (example/receivables/) that intentionally ships only a layout plus definitions file(s) (no .cpy copybook), backed by a vendor-style fixture copybook in testdata/vendor/, and extends the existing test/equality machinery so the example is regenerated and checked byte-for-byte against what cpybkc init produces.

Changes:

• Add the example/receivables/ worked example (layout, definitions file, generated Go + graph outputs, and a detailed README covering migration/drift and file↔block moves).
• Extend example/regenerate_test.go with two new tests that (1) re-run init and require the committed definitions/layout record forms to match and (2) verify --emit-ir stability across copybook/file/block moves.
• Update internal/project/equality_test.go so the “inline conversion” step can inline definitions-file sources as well as copybook sources, enabling #409’s suite to cover the new example shape.

File	Description
testdata/​vendor/​ARTRANS	Adds vendor-style fixture copybook used by the receivables example tests/README.
README.md	Updates top-level docs to include and describe the new “no copybook” receivables example and adjusts counts/text accordingly.
internal/​project/​equality_test.go	Updates inlining/conversion test helpers to handle layouts that reference definitions files (not just copybooks).
example/​regenerate_test.go	Adds dedicated tests asserting receivables matches init output and that copybook/file/block sources resolve identically.
example/​receivables/​receivables/​records.go	Generated record structs for the receivables example.
example/​receivables/​receivables/​records_test.go	Generated per-record roundtrip tests for the receivables example.
example/​receivables/​receivables/​literals.go	Generated literal caching/re-expression support for discrimination under alternate encodings.
example/​receivables/​receivables/​file.go	Generated Reader/Writer implementing the automaton for the receivables file shape.
example/​receivables/​receivables/​file_test.go	Generated end-to-end file-path tests (reader/writer roundtrips) for the automaton.
example/​receivables/​receivables/​doc.go	Generated package stub file.
example/​receivables/​receivables/​codec.go	Generated Encoding() and per-record marshal/unmarshal implementations.
example/​receivables/​receivables.sexpr	New receivables layout: records bind to ARTRANS.sexpr, with renames/discriminators/sequence defined.
example/​receivables/​README.md	New example README documenting init transcription, drift procedure, and file↔block moves with --emit-ir checks.
example/​receivables/​graph/​graph.md	Generated mermaid automaton + resolved item tables for the receivables layout.
example/​receivables/​cpybkc.json	Manifest for the new example (go + graph generators).
example/​receivables/​cpybkc.gen.json	Generated-file inventory for pruning/regeneration checks.
example/​receivables/​ARTRANS.sexpr	Definitions file committed as the cpybkc init transcription target for the vendor copybook.
example/​README.md	Adds receivables to the examples index and documents the new special-case assertions for it.
docs/​layout/​SPEC.md	References the new worked example in the layout spec mapping/index.

_{Review effort: Lite}