F18.2 — Templated artifacts and plan diffs
| State | Closed |
| Parent | E18 |
| Iteration | Release 6 |
| Start Date | 2026-10-25 |
| Closed Date | 2026-10-25 |
| Predecessors | F18.1 |
| Source | Owner request, 2026-10-24 |
Stories: 2 Closed
| Story | State | Depends on |
|---|---|---|
S18.2.1 — TemplateArtifact and render_artifacts |
Closed | — |
S18.2.2 — disk_content and diff |
Closed | — |
A generator describes its artifacts as a table of path, ownership, template and
condition, and the generation engine renders them. It does not write
Artifact(path, kind, engine.render(template, context)) once per file. A
preview, whether a CLI's diff command or a web page's "what will change"
screen, asks the engine for a unified diff of each planned change, instead of
reimplementing how the engine reads a file or a block body from disk.
Context
kiln rendered about twenty-five artifacts across eight modules, each building
Artifacts by hand around engine.render, and its diff command carried a
line-for-line copy of the engine's private _disk_content.
Design
The feature shipped as designed. TemplateArtifact and render_artifacts live
in rn_forge.commons.generation.templated, which needs the templates extra
and is not re-exported by the generation facade, so
import rn_forge.commons.generation loads no Jinja; it is the one module
F18.1's generation-core-renders-nothing contract leaves free to import
rn_forge.commons.text. disk_content (the former private _disk_content) and
diff are in generation.plan and exported by the facade. The
rn-forge-commons generation guide (Rendering artifacts from templates,
Previewing a plan) and API reference document them.
S18.2.1 — TemplateArtifact and render_artifacts
State: Closed
Acceptance:
render_artifactsbehaves as under Design, andtests/generation/test_templated.pypasses.import rn_forge.commons.generationleavesjinja2out ofsys.modules.
S18.2.2 — disk_content and diff
State: Closed
Acceptance: generation.diff and generation.disk_content behave as under
Design, and TestDiff passes.
Acceptance
set -euo pipefail
cd packages/rn-forge-commons
uv run pytest -q tests/generation # S18.2.1 S18.2.2
uv run python -c 'import sys, rn_forge.commons.generation; assert "jinja2" not in sys.modules' # S18.2.1
uv run python -c 'from rn_forge.commons.generation import diff, disk_content' # S18.2.2
(cd ../.. && uv run lint-imports) # S18.2.1
uv run pyright && uv run --group docs mkdocs build --strict # S18.2.1 S18.2.2
Considered and rejected
render_artifactsas aTemplateEnginemethod. It would putgeneration's vocabulary intotext, and give the engine a dependency on the generation package for one convenience.- Rendering a whole template directory (every
*.j2under a prefix,.j2stripped). kiln's generators choose files per archetype, so a directory walk would still need the same table of conditions. - Filtering seeded artifacts inside
diff. Whether a preview shows seeded files is a caller's policy;diffreports what differs.