Skip to content

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_artifacts behaves as under Design, and tests/generation/test_templated.py passes.
  • import rn_forge.commons.generation leaves jinja2 out of sys.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_artifacts as a TemplateEngine method. It would put generation's vocabulary into text, and give the engine a dependency on the generation package for one convenience.
  • Rendering a whole template directory (every *.j2 under a prefix, .j2 stripped). 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; diff reports what differs.