Skip to content

F18.1 — Templates, generation and state move to commons

State Closed
Parent E18
Iteration Release 6
Start Date 2026-10-25
Closed Date 2026-10-25
Predecessors —
Source Owner decision, 2026-10-24 (ADR-0002, rule 3 as amended)

Stories: 3 Closed

Story State Depends on
S18.1.1 — Move the template engine, with autoescape, cached and brace-safe errors Closed —
S18.1.2 — Move the generation engine and StateStore Closed S18.1.1
S18.1.3 — Import boundaries that can break Closed S18.1.2

Rendering templates and owning generated files move from rn-forge-tooling to rn-forge-commons, so an application that writes files from templates gets the whole capability without the CLI and installer layers:

  • TemplateEngine moves to rn_forge.commons.text.templates, behind a templates extra.
  • The generation engine (artifacts, plan, apply) moves to rn_forge.commons.generation, which the facade does not import.
  • StateStore moves to rn_forge.commons.fs.state.

Tooling keeps the lifecycle verbs and install mechanics. The engine gains autoescape and a process-wide cached constructor, and stops crashing on a Jinja error containing a brace. The import contracts that guard these modules are written so they can actually break.

Context

ADR-0002's rule 3 named "file-generating" layers as tooling. On 2026-10-24 the owner dropped that word. A web application that generates files from templates wants plan, diff, atomic apply with rollback, and drift detection, as much as a developer tool does. Nothing in those signatures is CLI or installer policy, so rule 1 places them in commons.

The move costs no new dependency: generation and state import only the standard library and commons. The facade must not import generation or text, because it imports eagerly and a re-export would load the generation engine, Jinja and markdown-it for every commons user, including kiln's doctor checks. The contracts name sibling source modules because import-linter 2.15 never breaks a forbidden contract whose forbidden module sits inside its source package (checked 2026-10-24); the root .importlinter header records the rule, and a subprocess test covers the package __init__ modules, which no contract can. TemplateEngine.cached exists because a jinja2.Environment compiles each template once and kiln wrapped the constructor in functools.cache in ten modules. Errors are brace-safe because AppException formats its message with str.format, so a Jinja message containing a brace raised ValueError.

Design

The feature shipped as designed. The rn-forge-commons generation guide (docs/guides/generation.md), text guide (docs/guides/text.md) and API reference document the result; the root .importlinter holds the contracts.

Moves

TemplateEngine moved to rn_forge.commons.text.templates, the generation package to rn_forge.commons.generation and StateStore to rn_forge.commons.fs.state, with their tests and docs, using git mv. Class and function names did not change.

Template engine changes (text/templates.py)

autoescape (default False) was added, TemplateEngine.cached returns one shared engine per set of hashable arguments, and a Jinja error raises RenderError("{}", exc).

Facades

The commons facade re-exports StateStore and imports neither generation nor text; tooling dropped RenderError, StateStore and TemplateEngine.

Manifests

Commons gained the templates extra (jinja2), and tooling dropped jinja2.

Import contracts (root .importlinter)

commons-is-runtime-neutral was replaced, and commons-core-has-no-extras, generation-core-renders-nothing and a corrected data-core-has-no-adapter were added, each naming sibling source modules.

Facade import tests

Subprocess tests in commons and data assert that importing the facade loads no generation, text, Jinja, Markdown or pandas module.

Docs

The root README, the workspace architecture page, the tooling and commons guides and the extras table were updated for the move.

Changelogs ([Unreleased])

The commons, tooling and data changelogs record the added modules and extra, the brace fix, the breaking removal from tooling and the corrected contract.

New tests (beside the moved ones)

tests/text/test_templates.py gained tests for autoescape, cached and brace-safe errors.

S18.1.1 — Move the template engine, with autoescape, cached and brace-safe errors

State: Closed

Acceptance:

  • The template rows of Moves, the engine changes, the manifests and the template docs and changelog lines hold.
  • tests/text/test_templates.py passes.

S18.1.2 — Move the generation engine and StateStore

State: Closed · Depends on: S18.1.1

Acceptance:

  • The generation and state rows of Moves, the facades and the remaining docs and changelog lines hold.
  • The moved tests pass unchanged except for their imports.
  • Tooling's remaining tests pass.

S18.1.3 — Import boundaries that can break

State: Closed · Depends on: S18.1.2

Acceptance:

  • The contracts and facade tests under Design hold, and lint-imports keeps every contract.
  • Each new or rewritten contract is shown to break, by hand, once, before merging: add from rn_forge.commons.generation import Plan to rn_forge/commons/fs/paths.py, and import rn_forge.data.pandas to rn_forge/data/excel.py. lint-imports must report both contracts BROKEN; then revert the lines. Record the run in the commit message.

Acceptance

set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }
uv run pytest -q packages/rn-forge-commons/tests/text/test_templates.py       # S18.1.1
test ! -e packages/rn-forge-tooling/src/rn_forge/tooling/templates.py         # S18.1.1
absent '^\s*"jinja2' packages/rn-forge-tooling/pyproject.toml                   # S18.1.1
uv run pytest -q packages/rn-forge-commons/tests/generation packages/rn-forge-commons/tests/fs/test_state.py  # S18.1.2
test ! -e packages/rn-forge-tooling/src/rn_forge/tooling/generation           # S18.1.2
test ! -e packages/rn-forge-tooling/src/rn_forge/tooling/state.py             # S18.1.2
absent 'rn_forge\.tooling\.(templates|generation|state)' packages README.md docs/architecture docs/guides \
  --glob '!**/CHANGELOG.md' --glob '!**/changelog.md'                          # S18.1.1 S18.1.2
uv run pytest -q packages/rn-forge-tooling                                    # S18.1.2
uv run pytest -q packages/rn-forge-commons/tests/test_facade.py packages/rn-forge-data/tests/test_facade.py  # S18.1.3
uv run lint-imports && uv run pyright                                         # S18.1.1–S18.1.3
(cd packages/rn-forge-commons && uv run --group docs mkdocs build --strict)   # S18.1.1 S18.1.2
(cd packages/rn-forge-tooling && uv run --group docs mkdocs build --strict)   # S18.1.1 S18.1.2
uv run --group docs mkdocs build --strict                                     # S18.1.1 S18.1.2

The by-hand BROKEN check in S18.1.3 is not scripted.

Considered and rejected

  • Keep rn_forge.tooling.* aliases for one release. ADR-0002 rule 5 forbids them, and kiln, the only consumer, moves its imports in one change.
  • Put generation behind an extra. It needs no third-party package. Keeping it out of the facade is what keeps it off a commons user's import path, and the facade test proves it.
  • Re-export generation from the facade. The facade imports eagerly. Every commons user, a web worker included, would load the engine to get a Finding.
  • A package of its own (rn-forge-generation). It fails ADR-0011's first test: it has no dependency set of its own.
  • StateStore under generation. It is a generic locked JSON key-to-entry store with no generation vocabulary in its signature, so fs holds it.