legaldown-validator 0.1.0__tar.gz

legaldown_validator-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+
+# Spec fixtures checkout used by the conformance harness in CI
+.legaldown-spec/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

legaldown_validator-0.1.0/CONFORMANCE.md

@@ -0,0 +1,71 @@
+# Conformance
+
+`legaldown-validator` implements **Level 1 — Core** of the LegalDown specification (§16.2): parse
+and validate a single document in memory.
+
+It is verified against the specification's own
+[fixtures corpus](https://github.com/ForLegalAI/LegalDown/tree/main/fixtures) — one case per
+validation rule, paired with the diagnostic a conforming validator must produce. **57 of the
+corpus's 95 rules are implemented, and every one the corpus can exercise at Core level passes.**
+
+Seven implemented rules — `amend-def-override`, `amend-term-undefined`, `amend-term-unresolvable`,
+`attachment-id-collision`, `attachment-id-duplicate`, `attachment-title-empty`, and
+`attachment-unreferenced` — have fixtures that span several files or are marked for the Full level,
+so this single-document harness skips them. They are covered by the unit tests in
+`tests/test_spec_alignment.py` instead.
+
+The specification (§16.5) requires an implementation never to silently skip a check it cannot
+perform, so the remaining rules are named here. Most of them belong to conformance levels this
+implementation does not claim — Rendering (§16.3) and Full (§16.4) — because they need to open
+files other than the document itself.
+
+## Rules not implemented
+
+| Group | Rules |
+|---|---|
+| Filesystem-dependent (Full, §16.4) | `amends-file-missing`, `attachment-file-missing`, `attachment-has-frontmatter`, `attachment-has-h1`, `attachment-anchor-duplicate`, `supersedes-file-missing`, `path-not-relative`, `path-outside-root` |
+| Includes (Full, §16.4) | `include-file-missing`, `include-not-legaldown`, `include-cycle`, `include-has-frontmatter`, `include-has-h1`, `include-anchor-duplicate`, `include-heading-skip` |
+| Bilingual sets (Full, §16.4) | `translation-file-missing`, `translation-hierarchy-mismatch`, `translation-anchor-mismatch`, `translation-def-mismatch`, `translation-language-set-mismatch`, `translation-implicit-id`, `translation-authoritative-absent` |
+| Lexer-level grammar (§11.2–11.4) | `directive-malformed`, `directive-duplicate-param`, `directive-unknown-param`, `brace-stray`, `value-curly-quote`, `raw-html`, `anchor-misplaced` |
+| Other | `frontmatter-absent`, `frontmatter-invalid-yaml` (reported by the CLI, not the validator), `anchor-lossy-slug`, `def-lossy-slug`, `definition-circular`, `definition-used-before-declaration`, `language-code-invalid`, `authoritative-not-declared`, `supersedes-title-empty` |
+
+In practice this means multi-file processing is out of scope: includes, attachment file contents,
+and bilingual document sets are not resolved or cross-checked. Single-document authoring, editing,
+and CI validation are fully covered.
+
+One id appears on both sides of that line. `attachment-file-missing` is defined as *the attachment
+`file` path exists*, which needs the filesystem and is therefore unimplemented — but the validator
+also emits that id when an attachment declares no `file` at all, which is visible in the document
+itself. The specification provides no separate id for the absent key, so a diagnostic carrying
+`attachment-file-missing` from this implementation always means the key is missing, never that the
+path failed to resolve.
+
+## Checking this yourself
+
+The conformance harness runs against a checkout of the specification repository:
+
+```bash
+git clone https://github.com/ForLegalAI/LegalDown ../LegalDown
+LEGALDOWN_FIXTURES_DIR=../LegalDown/fixtures pytest tests/conformance -q
+```
+
+Cases for the rules above are skipped by name, so the 38 `not implemented` skips reproduce this
+table one for one. The run reports 45 skips in total: the remaining seven are the implemented
+rules named above, skipped as `multi-file case` or `requires conformance level full`. CI runs this
+on every push and pull request.
+
+## Declaring conformance in code
+
+The package exports what it targets, so consumers can assert it:
+
+```python
+import legaldown
+
+legaldown.SPEC_VERSION       # "0.1"  — specification version targeted
+legaldown.CONFORMANCE_LEVEL  # "core" — conformance level claimed
+legaldown.__version__        # implementation version
+```
+
+The CLI's JSON output repeats the first and last of these on every run, as `legaldown_spec` and
+`validator_version`. The conformance level is not part of the JSON payload — read it from the
+package.

legaldown_validator-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 ForLegalAI s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The LegalDown specification itself is a separate work, published at
+https://github.com/ForLegalAI/LegalDown under Creative Commons Attribution 4.0
+International (CC BY 4.0). This implementation is an independent work that
+implements that specification; the specification permits implementations to be
+released under any license their authors choose.

legaldown_validator-0.1.0/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.5
+Name: legaldown-validator
+Version: 0.1.0
+Summary: Reference parser and validator for the LegalDown legal document format
+Project-URL: Homepage, https://github.com/ForLegalAI/legaldown-validator
+Project-URL: Repository, https://github.com/ForLegalAI/legaldown-validator
+Project-URL: Issues, https://github.com/ForLegalAI/legaldown-validator/issues
+Project-URL: Specification, https://github.com/ForLegalAI/LegalDown
+Author: ForLegalAI s.r.o.
+Maintainer: ForLegalAI s.r.o.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: contracts,document-format,legal,legaldown,legaltech,markdown,parser,validator
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Legal Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# legaldown-validator 📐
+
+### The reference implementation of [LegalDown](https://github.com/ForLegalAI/LegalDown)
+
+**Parse, validate, and serialize LegalDown documents — from the command line or from Python.**
+
+Targets specification **v0.1** · Every diagnostic carries a **stable rule id** · One dependency: PyYAML
+
+</div>
+
+---
+
+## What it does
+
+[LegalDown](https://github.com/ForLegalAI/LegalDown) is an open plain-text standard for legal
+documents. This package is the toolkit for working with those documents in code:
+
+📥 **Parses** a `.lgd` file into a typed document model — frontmatter, sections, blocks, parties,
+definitions, anchors.
+
+✅ **Validates** it against the specification's rule set (§15): broken cross-references, undefined
+terms, duplicate identifiers, malformed party metadata, bad dates and money values, and more.
+
+📤 **Serializes** the model back to LegalDown source, so you can edit documents programmatically
+and write them out again.
+
+🏷️ **Names every finding.** Each diagnostic carries the specification's stable rule id (§15.1)
+alongside its severity and message, so you can suppress one check, escalate another, or gate a
+build on exactly the rules you care about. Rule ids survive specification renumbering — they are
+the part of a diagnostic that is safe to depend on.
+
+## Install
+
+```bash
+pip install legaldown-validator
+```
+
+Python 3.11 or newer. The distribution is named `legaldown-validator`; the import name is
+`legaldown`:
+
+```python
+import legaldown
+```
+
+The package ships a `py.typed` marker, so type checkers use its annotations directly.
+
+## Quick start
+
+Given a LegalDown document:
+
+```markdown
+---
+title: Services Agreement
+document_type: contract
+sides:
+  - name: providers
+    label: Provider
+    parties:
+      - name: acme
+        label: Acme
+        type: legal_entity
+        legal_name: Acme Corporation
+  - name: clients
+    label: Client
+    parties:
+      - name: beta
+        label: Beta
+        type: legal_entity
+        legal_name: Beta Industries Inc.
+language: en
+---
+
+# Fees {#fees}
+
+{{party: beta}} shall pay {{money: 5000}} under {{ref: payment-terms}}.
+```
+
+Validate it:
+
+```bash
+legaldown validate contract.lgd
+```
+
+```
+contract.lgd: error: [ref-broken] Broken section reference: 'payment-terms'.
+contract.lgd: warning: [money-missing-currency] Money directive without currency parameter.
+
+1 error(s), 1 warning(s), 0 info(s)
+```
+
+One diagnostic per line, each prefixed with its rule id. A clean document reports
+`No issues found.` and exits `0`.
+
+Diagnostics go to **stdout**; the trailing summary and `No issues found.` go to **stderr**, so
+`legaldown validate contracts/ > report.txt` captures the findings alone. `--quiet` drops the
+summary entirely.
+
+## Command line
+
+```bash
+legaldown validate contract.lgd                      # one document
+legaldown validate contracts/                        # a whole directory, recursively
+legaldown validate --format json contract.lgd        # machine-readable output
+legaldown validate --ignore def-unreferenced doc.lgd # mute one rule
+legaldown validate --warnings-as-errors doc.lgd      # tighten a CI gate
+```
+
+| Option | Effect |
+|---|---|
+| `--format {text,json}` | Output format (default `text`) |
+| `--ignore RULE_ID` | Suppress a rule by its stable id — repeatable |
+| `--warnings-as-errors` | Report warnings at error severity |
+| `--strict` | Exit non-zero on any diagnostic, not just errors |
+| `--quiet` | Drop the trailing summary line |
+
+Directories are searched recursively for `*.lgd`, `*.legaldown`, and `*.legal.md`, and
+`legaldown --version` reports the validator version.
+
+**Exit codes:** `0` clean · `1` diagnostics found (errors, or any diagnostic under `--strict`) ·
+`2` a file could not be read.
+
+### JSON output
+
+`--format json` emits the structured shape described in §15.9 — ideal for CI annotations, editor
+integrations, and dashboards:
+
+```json
+{
+  "legaldown_spec": "0.1",
+  "validator_version": "0.1.0",
+  "diagnostics": [
+    {
+      "file": "contract.lgd",
+      "rule": "ref-broken",
+      "level": "error",
+      "message": "Broken section reference: 'payment-terms'."
+    }
+  ]
+}
+```
+
+### In CI
+
+```yaml
+- run: pip install legaldown-validator
+- run: legaldown validate contracts/ --warnings-as-errors
+```
+
+The exit code fails the job; the rule ids let you grant exceptions without turning whole checks
+off.
+
+## Python API
+
+Three functions cover the common path:
+
+```python
+from legaldown import parse_document, validate_document, serialize_document
+
+document = parse_document(open("contract.lgd").read(), filename="contract.lgd")
+result = validate_document(document)
+
+for diagnostic in result.diagnostics:
+    print(diagnostic.level, diagnostic.rule, diagnostic.message)
+
+if result.is_valid:                      # no Error-level diagnostics
+    print(serialize_document(document))
+```
+
+### Working with the result
+
+Validating a document builds the indices the checks need — section numbers, resolved definitions,
+party display text, every inline value found in the body. `ValidationResult` hands all of it back,
+so a renderer or a UI can reuse the work instead of re-deriving it:
+
+| Attribute | Contents |
+|---|---|
+| `diagnostics` | `Diagnostic(rule, level, message)` — the authoritative record |
+| `is_valid` | `True` when no Error-level diagnostic was reported |
+| `errors` / `warnings` / `infos` | Message strings by severity |
+| `rules(level=None)` | Set of rule ids present, optionally filtered by severity |
+| `sections`, `section_lookup` | Numbered section index; resolves `{{ref:}}` targets |
+| `definition_lookup`, `party_lookup`, `side_lookup`, `attachment_lookup` | Resolved display text |
+| `inline_dates`, `inline_money`, `inline_durations`, `inline_fields`, `inline_placeholders` | Field-spec values found in the body |
+
+### Reading and editing the document model
+
+`parse_document` returns a `Document` of plain dataclasses — `Metadata`, `Section`, `Block`,
+`Side`, `Party`, `Attachment` — that you can inspect, edit, and write back out:
+
+```python
+from legaldown import parse_document, serialize_document
+
+document = parse_document(source)
+document.metadata.governing_law = "Czech Republic"
+
+with open("contract.lgd", "w", encoding="utf-8") as handle:
+    handle.write(serialize_document(document))
+```
+
+`document_to_dict()` / `document_from_dict()` round-trip the model through JSON-friendly
+structures, and `render_block()` renders a single block when you are driving your own layout.
+
+One guarantee worth knowing: the parser is **faithful** — it never rewrites your input to make it
+valid, so what you authored is exactly what the validator judges. The serializer, by contrast,
+normalizes: frontmatter is re-emitted as canonical YAML and paragraphs are written as single
+lines, so expect a formatting-normalized file rather than a byte-for-byte copy.
+
+## What gets checked
+
+The full rule set with severities and examples lives in the specification (§15); this is the map:
+
+| Area | Checks include |
+|---|---|
+| **Structure** | Heading depth and skipped levels, hardcoded section numbers, missing title |
+| **Cross-references** | `{{ref:}}` targets that do not exist or point at an attachment |
+| **Anchors** | Duplicate identifiers, malformed identifiers, auto-generated collisions |
+| **Definitions** | Undefined `{{term:}}`, duplicate ids, missing quoted span, ambiguous quoting, unreferenced definitions |
+| **Parties and sides** | Unknown `{{party:}}` / `{{side:}}`, malformed or duplicate names, invalid party types, minimum party and side counts, empty representatives |
+| **Values** | Invalid dates, money without currency or with an unknown one, invalid durations and units, undeclared or reserved custom field types |
+| **Placeholders** | Malformed ids, invalid or inconsistent types, placeholders in structural fields |
+| **Attachments** | Undeclared `{{attach:}}`, duplicate or colliding ids, empty titles, unreferenced attachments |
+| **Amendments** | Terms the amended original does not define, definition overrides, empty amendment titles |
+| **Metadata** | Invalid document type, invalid dates, missing sides, issuer side requirements |
+
+Each check reports at the severity the specification assigns it — Error, Warning, or Info.
+
+## Scope
+
+This implementation claims **Level 1 — Core** (§16.2): everything above applies to a single
+document, in memory, with no filesystem access beyond reading the file you point it at. That
+covers authoring, editing, and CI validation of individual documents.
+
+It is verified against the specification's own
+[fixtures corpus](https://github.com/ForLegalAI/LegalDown/tree/main/fixtures) — every rule it
+implements passes, bar seven whose fixtures span several files and are covered by unit tests
+instead. The specification (§16.5) requires an implementation to be explicit about the
+checks it does not perform, so those are listed in
+[CONFORMANCE.md](https://github.com/ForLegalAI/legaldown-validator/blob/main/CONFORMANCE.md) rather than left to be discovered.
+
+## Development
+
+```bash
+git clone https://github.com/ForLegalAI/legaldown-validator
+cd legaldown-validator
+pip install -e ".[dev]"
+pytest
+```
+
+### Conformance suite
+
+The fixtures corpus lives in the specification repository, so point the harness at a checkout:
+
+```bash
+git clone https://github.com/ForLegalAI/LegalDown ../LegalDown
+LEGALDOWN_FIXTURES_DIR=../LegalDown/fixtures pytest tests/conformance -q
+```
+
+Cases for rules outside Core are skipped and named, so the run doubles as the coverage ledger in
+[CONFORMANCE.md](https://github.com/ForLegalAI/legaldown-validator/blob/main/CONFORMANCE.md),
+which accounts for every skip. CI runs it on every push and pull request.
+
+Bug reports and pull requests are welcome in
+[Issues](https://github.com/ForLegalAI/legaldown-validator/issues); questions about the format
+itself belong in the specification repository's
+[Discussions](https://github.com/ForLegalAI/LegalDown/discussions).
+
+## License
+
+MIT — see [LICENSE](https://github.com/ForLegalAI/legaldown-validator/blob/main/LICENSE). The LegalDown specification itself is published separately under
+CC BY 4.0; it permits implementations to choose their own license.