0.4.0: simpler API — load/validate/DocumentIndex, Template/Form interview, questions and assemble -i

[dvejsada]

Summary

A step-by-step simplification of the external Python API, in three parts. Every old entry point still works and warns (DeprecationWarning), to be removed in 0.5.0. The version is bumped to 0.4.0.

1. Opening a document

• load(path) opens a document (UTF-8, BOM and line endings handled) and sets Document.path; parse(text) is the string form.
• Deprecated: parse_document.

2. Validation: input and output

• validate(document, *, final=False, resolve=None). The amended original's and the LegalDown attachment files' definitions are read from beside document.path (sandboxed to its directory, one level deep, never the document itself). resolve= replaces the two importer callbacks and has the same shape as assembly's LoadFile. New shared module files.py (LoadFile, file_loader, relative_path).
• ValidationResult is diagnostics + index. The analysis moved to result.index (DocumentIndex: sections, the lookups, values, is_template, placed_markers). errors/warnings/infos are derived from diagnostics; recording methods and used_terms moved to an internal recorder.
• Deprecated: validate_document, import_definitions=, import_attachment_definitions=.

3. Assembly as an interview

• load_template(path) / parse_template(text, resolve=) read a template once. Template.form(answers) is a frozen snapshot: questions (reached, includes read where their {{include:}} is), unanswered, blocking, unused, diagnostics, ready, complete, problem(id), assemble(), as_dict().
• Question (now a frozen value) gets problem(answer), from_text(text), to_text(answer), hint and accepts.
• Template.coerce(answers) and load_answers(path).
• CLI: legaldown questions (text or JSON, --check), legaldown assemble -i (asks in the terminal; prompts on stderr) and --save-answers FILE (atomic, keeps the file's permissions, never the template itself).
• Deprecated: assemble, template_questions, needed_questions.

Behaviour changes to review

• legaldown validate now reads the amended original and attachment files beside a document, so documents with amends or attachments can gain real findings (amend-def-override, def-duplicate-id; a missing term moves from Info amend-term-unresolvable to Error amend-term-undefined). Noted in the README as "Changed in 0.4.0".
• legaldown assemble and the new Template refuse a template with Errors in the validator's template rules (§15.7.2 gives assembly a valid template); the deprecated assemble function does not. The CLI also puts the shapes of the answers file right (5000 EUR, no, trimmed text; fee: 5000 where the placeholders fix the currency), which were answer-invalid before.
• What a person types as a text answer may not hold a control character (a tab is fine) or a lone surrogate (Question.from_text); answer_problem itself is exactly §15.7.1.
• A LoadFile/resolve= loader is only asked for paths within the document's directory (§2.3), including by the deprecated assemble.
• The new API asks the questions of an included fragment where its {{include:}} is; the deprecated functions ask them after the body.
• ValidationResult and Question changes are breaking for code that read the old fields or built a result positionally (it is now keyword-only). This is a deliberate hard break, documented in the README.

Review history

Each stage was reviewed adversarially by an Opus subagent against the code, with probes (including a real pty for -i), and the findings fixed before the next stage. A final independent Opus review of the whole PR ran differential checks of legaldown validate --format json against main on every spec fixture (only the amendment cases differ, as documented), found one blocking and several important issues, and confirmed their fixes. The deprecated functions run on the old internal code paths, and tests/test_assembly.py runs every one of its tests twice, through the functions and through Template/Form, comparing ok, output, files and rule ids.

Test plan

• python -m pytest -q -W error::DeprecationWarning — 1976 passed, 14 skipped
• With the specification fixtures corpus (LEGALDOWN_FIXTURES_DIR, LegalDown v0.2) — 2409 passed, 40 skipped; the Template/Form path (ungated, and the public door with the template rules on) assembles all assembly fixtures byte for byte
• ruff check src tests
• CI: lint, tests on Python 3.11 / 3.12 / 3.13, build, specification conformance

🤖 Generated with Claude Code

https://claude.ai/code/session_013WmBAc5T7UCKVdpUmg9qxz

[dvejsada]

@claude review

---

Generated by Claude Code

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.