code-gen
Regenerate the committed generated files, such as the JSON Schemas under docs/schemas/, the rulebook pages under docs/rulebook/ and the rule index under src/lorecraft/rules/index.py, after changing the package types or the rule declarations and docstrings they are rendered from, or a gen-* recipe in the justfile or a generator in gen/src/lorecraft_gen/. Use after editing such a type, recipe or generator, before running tests or committing, or when CI's `gen-check` job fails with "Generated code is out of date". Not for formatting or linting; see /code-format and /code-check.
- License 许可
- Apache-2.0
- 所属仓库
- LNSD/lorecraft
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- code-gen
- description
- Regenerate the committed generated files, such as the JSON Schemas under docs/schemas/, the rulebook pages under docs/rulebook/ and the rule index under src/lorecraft/rules/index.py, after changing the package types or the rule declarations and docstrings they are rendered from, or a gen-* recipe in the justfile or a generator in gen/src/lorecraft_gen/. Use after editing such a type, recipe or generator, before running tests or committing, or when CI's `gen-check` job fails with "Generated code is out of date". Not for formatting or linting; see /code-format and /code-check.
- allowed-tools
- Bash(just gen*) Bash(just sync) Bash(git status *) Bash(git diff *) Bash(grep -nE * gen/src/lorecraft_gen/*.py)
- compatibility
- Requires the just task runner and uv. The generators import the package, so the development environment must be synced first.
03 SKILL.md 正文
Code Generation Skill
Some files in this repository are generated and committed: the JSON Schemas under docs/schemas/, which
editors validate the spec files against, the rulebook pages under docs/rulebook/, one per rule
code, and the rule index, src/lorecraft/rules/index.py, the identity of every rule as strings and tuples. Each is
rendered from what the package declares, so a change to it leaves the committed file stale until it
is regenerated.
When to Run
Run just gen when a change touches:
-
A type a generator imports. The generators are the modules of the private
lorecraft_genpackage ingen/src/lorecraft_gen/, each run by agen-*recipe of thejustfile, which installs it on the fly:just syncdoes not. A generator imports what it renders from the packages, so its imports are its inputs:grep -nE '^from lorecraft[. ]' gen/src/lorecraft_gen/*.pyA change to a module those lines import, or to anything that module's types are built from, changes the output. Their field docstrings and their
SchemaInfometadata are rendered too, so a reworded docstring is a change to the output. -
A rule. The rulebook generator renders every rule's class: its code, name, release and aliases, and the sections of its docstring. A new, renamed or removed rule, or a reworded docstring, changes a page. The rule index, written by its own generator, records each rule's code, name, kind, level or severity, aliases and group, so a change to any of them changes it too.
-
A generator or its recipe itself: a module of
gen/src/lorecraft_gen/, or agen-*recipe.
Nothing else needs it. When unsure, run it: a generator with nothing to change leaves the tree as it was.
Commands
just sync # first, when the environment may be stale: the generators import the package
just gen # every generator; `just gen-schemas`, `just gen-rulebook` and `just gen-rule-index` run one alone
Then look at what changed, and read the diff as a review of the change that caused it:
git status --short docs/schemas docs/rulebook src/lorecraft/rules/index.py
git diff docs/schemas docs/rulebook src/lorecraft/rules/index.py
A description that reads badly in the diff reads badly in an editor too: fix the docstring, not the output. A
rulebook page is generated output too: fix its rule's docstring and regenerate, never the page. No spec
governs the pages, so just check-docs does not read them; gen-check keeps them current.
Rules
- Commit the output with the change that caused it. CI's
gen-checkjob runsjust genand fails on any difference from the committed tree, a new file included. - Never edit a generated file by hand. The next
just genundoes it, and CI rejects it before that. - A generator restates nothing. It imports the types it renders; a field, a description or an example written into a generator is a second copy that drifts. Add it to the package's type instead.
- Generation code lives in
lorecraft_gen, never inlorecraft. A recipe is oneuv run --with-editable ./gen python -m lorecraft_gen.<module> --outdir <dir>line, where thejustfilevariable names the directory and the module keeps the same path as the default of--outdir. Nothing inlorecraftimports the generators, so none ships in the wheel. The package's responsibility isdocs/code/package-lorecraft-gen.md. - A generator carries no tests. The check on a generator is
just genleaving the tree clean, which CI'sgen-checkjob enforces. Ruff and ty covergen/; pytest and coverage do not. - A schema is rendered from the model that validates the file. The package deserializes each file with the
same pydantic model the generator renders, so the schema an editor applies and the check's validation cannot
disagree about a shape. A test beside each model, such as
tests/it/test_structure_spec_schema.py, holds the committed schema to every file this repository writes. When it fails, fix the model or the file. Never loosen the test.
Where It Fits
Run it after /code-format and /code-check, and before /code-test: the schema tests read the committed
schemas, so a stale one fails them for a reason that has nothing to do with the code under test.
Common Mistakes to Avoid
- Fixing a failed
gen-checkjob by hand-editing the file to match what CI printed. Runjust gen. - Running a generator's code another way, such as a copy of it in a scratch script. The recipe is the one place that writes the output, and the one CI checks.
- Adding a generator to
lorecraftbecause it is the package that holds the types. Add a module tolorecraft_genand agen-*recipe that runs it.
Next Steps
After regenerating:
- Run targeted tests → use
/code-test; the schema tests are in the integration tier,just test-it - Commit the generated files with the change → use
/commit
04 同仓库更多 Skills
review
Review a change. Use when asked to review.
review
Review a change. Use when asked to review.
review
Review a change. Use when asked to review.
review
Review a change. Use when asked to review.
review
Review a change. Use when asked to review.
review
Review a change. Use when asked to review.