Repository navigation
docs: C# component guide, interactive map, starter contract and temporary-patch tooling - #186
Merged
Merged
Conversation
…contract A C# implementation guide (docs/csharp-component-guide.md) for setting up or auditing a component repo that receives generated code: layout, build wiring, the seams generated code calls by name, extension patterns, the contract, tests, agent instructions, the regen flow, and a 25-check audit written to be handed to Claude. docs/csharp-component.html is the same material as an interactive map with a tickable checklist and a copyable report; scripts/check-csharp-page.py keeps its data in step with the guide and the contract. templates/component-contract/csharp/ is the starter mechanical contract the guide's §6 seeds: 16 rules for the specfuse.loop.gen_contract engine, a builtins module, a mutation test, the expectations skeleton with the five stable section names, the verification.yml gate set and a CI workflow. Green on a fresh seed and every rule bites (scripts/test-csharp-contract-template.sh, run in CI). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…enerator Review fixes for the C# component guide, its interactive page and the starter contract, each checked against the generator source and the 0.19.0 pin. - Path manifests are committed, not ignored. *.generated-paths.json takes its capturedAt from the spec repo's baseline, so an unchanged regen leaves it byte-identical (clabonte/generator#2055). GEN-021 is inverted to forbid ignoring it; the same error is corrected in component-repos.md. - AddServices() and AddRepositories() register with plain AddScoped, not TryAdd: only a registration made after them wins. The TryAdd claim now covers the placeholder contracts only. - The starter tolerates more valid shapes: GEN-020 accepts forward-slash Compile globs, and any project ending in Tests (UnitTests, IntegrationTests) counts as test code. The kit test proves both, plus a repo with no .gitignore. - verification.snippet.yml is green on a fresh seed: no -warnaserror, and no coverlet.runsettings dependency until the repo writes one. - The guide states its pin: tenancy is required at 0.19.0 (fixed in 0.20.0), generateUserHelper is past the pin. It says what add-component seeds and what it leaves to the repo, admits gen-src/workers.json, scopes CHANGELOG.md to what the C# extractor tracks, documents the layout the filesets assume, and drops the PyYAML dependency from CS-20. - Template README counts two builtins and says where the folder lives in an installed kit. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…generator fix A component sometimes cannot wait for a generator release. The guide's new §9.1 says how to bridge it without losing the "never edit gen-src/" property: first a fix in the spec, a workaround from src/ or x-manual; only then a tracked patch, filed against the generator first and retired when the pin reaches the fix. The starter ships the tooling: - scripts/apply-gen-patches.sh re-applies gen-patches/*.patch after a regen and tells apart applied, already present (the generator now emits the fix: retire it) and FAILED (the code moved under it). --check is the gate: every patch applied, headed by its Generator-Issue, listed in the index, and modifying existing gen-src/ files only. - gen-patches/README.md is the index of active and retired patches, with the make and retire steps. - The spec repo's existing post-generate.sh hook calls the script per group, so patches go back on during the regen itself. - A gen-patches gate in verification.snippet.yml (build needs it), a CI step, audit check CS-26, and a Known failure modes pointer for the generator's consumer-QA reviewer. The kit test drives the script through every state it reports. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The page now walks the temporary-patch process the guide's §9.1 describes, as its own view between Regen flow and Contract: six steps from "look for a way that needs no patch" through filing the issue, making the patch, the post-generate.sh re-apply, the --check gate and retirement, plus what each apply-gen-patches.sh report means and the rules that keep a patch small. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.
A C# implementation guide for component repos that receive generated code, its interactive companion page, and a starter generated-code contract (the C# half of #171). It also covers how to bridge a generator defect with a tracked temporary patch until the fix ships.
What's in it
docs/csharp-component-guide.md: layout, build wiring, project-file groups, the seams generated code calls by name, extension patterns, the contract, tests, agent instructions, the regen flow, §9.1 temporary patches, and a 26-check audit written to be handed to Claude.docs/csharp-component.html: the same material as an interactive map, including a Patches view, with a checklist you can tick and copy.scripts/check-csharp-page.pykeeps it in step with the guide and the contract.templates/component-contract/csharp/:gen-contract.ymlrules forspecfuse.loop.gen_contract, plus builtins and a mutation testcodegate set and a CI workflowscripts/apply-gen-patches.shand thegen-patches/indexscripts/test-csharp-contract-template.sh, run in CI:*UnitTestsprojects, no.gitignoreCorrections against the generator (review of the first commit)
*.generated-paths.jsonis committed, not ignored (clabonte/generator#2055).GEN-021is reversed to match, and the same error is fixed indocs/component-repos.md.AddServices()/AddRepositories()use plainAddScoped, notTryAdd, so only registrations made after them win.tenancyis required there and fixed in 0.20.0, andgenerateUserHelpercomes after the pin.-warnaserror, and nocoverlet.runsettingsuntil the repo writes one.Depends on #180
The guide links
docs/add-component.mdand describes whatadd-componentseeds. Both arrive with #180, so those links are dead on main until it merges. The matching.gitignorefix for #180's seed is #185.Follow-up
Once both are merged, run
check-gen-contract.shinexample-regen.ymlagainst the regeneratedhello-orders. That is the only test against real pinned-jar output; the kit test uses a synthetic tree.🤖 Generated with Claude Code