{
  "markdown": "<p align=\"center\">\n  <img src=\"logo.png\" alt=\"Quire\" width=\"100%\" />\n</p>\n\n# quire-rs\n\n[![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord&logoColor=white)](https://discord.gg/6qsdhSPE)\n\nHigh-performance Rust engine for the **Filament/Quire** documentation-standard ecosystem.\n\nquire-rs turns plain Markdown into a validated, queryable, structured corpus. You define a\n**doc standard** as a *module* — a set of *archetypes* (document types like `FR`, `NFR`,\n`US`) backed by JSON Schemas and a declarative body-extraction DSL — and quire-rs parses,\nvalidates, extracts, and edits documents against it.\n\nMarkdown is canonical: documents are authored and stored as plain `.md` files. The\nrender/templating feature was removed in v0.2 — quire-rs is a *parse → validate → extract*\nengine, not a renderer. Schema is correctness; presentation lives outside the engine.\n\nThe engine is consumable three ways: as a **Rust crate**, as a **Python wheel** (PyO3),\nand as **WebAssembly**.\n\n## Features\n\n**Parsing**\n- `parse_document` → a `QuireDocument` AST: YAML frontmatter, a heading tree of\n  `QuireSection`s, byte-exact content slices, and stable Pandoc `{#blk-id}` block IDs that\n  survive edits (vs. the unstable line-based `id`).\n- `extract_frontmatter` — BOM-stripping, CRLF-tolerant, forgiving YAML extraction (malformed\n  frontmatter falls back to body, never errors).\n\n**Query API** (read-only)\n- `section` / `sections`, `parse_table` / `table_from_section`, `parse_bullet_list`,\n  `extract_diagrams` (fenced code by language, e.g. `mermaid`), full-text `search`, and\n  `concept_type` (read the routing discriminator). Regexes compiled once.\n\n**Archetypes & module loading**\n- `Registry` — an immutable, thread-safe (`Arc`) compiled index of archetypes loaded from\n  module directories (`manifest.yaml` + `schemas/`).\n- Filesystem-first discovery via `Registry::from_env` (`IX_FILAMENT_MODULES_PATH` →\n  `IX_SCHEMA_PATH` → `~/.ix/filament/modules/`), explicit `load_from` / `load_module`, or\n  in-memory `from_inline_parts` (for WASM). Tolerant vs. strict collision handling; load\n  problems surface as diagnostics/failures rather than panics.\n\n**Validation**\n- `validate` / `validate_all` — JSON Schema (Draft 2020-12) validation of a data record\n  against an archetype; `apply_patch` does merge-then-validate.\n- `validate_document` / `validate_document_in_registry` — end-to-end Markdown validation:\n  concept shape → frontmatter schema → required body-extraction asserts → per-level heading\n  uniqueness. Composed `type` + `object` validation (unknown `object:` is a warning, never\n  an error). Structured `ValidationResult { is_valid, errors, warnings }` with line numbers\n  and machine-readable `ValidationReason` codes.\n\n**Body-extraction DSL**\n- `extract` evaluates a manifest's `body_extraction` DSL into records + edges. Six locator\n  primitives (`frontmatter_field`, `section_body`, `code_block`, `table_row`, `list_item`,\n  `heading`), fallback chains, single-yield (`match`) vs. multi-yield (`iterate_over` +\n  `per_match`), an `assert` facet with `{field}` interpolation, and edge emission.\n\n**Editing (writeback)**\n- `update_section` / `update_block` — byte-splice a single section or block and return the\n  full updated Markdown; everything else stays byte-identical. No reserialization.\n\n**Authoring contracts**\n- `input_contract_for` derives a per-archetype input contract (JSON for tools) plus a\n  Markdown authoring skeleton from the schemas + body-extraction asserts.\n\n**Corpus**\n- `load_repo` / `load_repo_with` — parallel, gitignore-aware directory walk (rayon, no shared\n  mutable state) into `LoadedDocument`s.\n- `Spec` — an immutable in-memory corpus with `by_id` lookup and intra-spec reference\n  resolution; `harvest_edges`, `validate_bundle` (strict vs. permissive posture), and\n  `unlinked_references` (dangling-edge detection + autofix suggestions). Identity is read,\n  never derived: `id` is the human artifact id, `uuid` is the durable UUID7 from frontmatter.\n\n**Lint**\n- `lint_document` — declarative, advisory lint rules (`table_column_values`,\n  `section_body_pattern`, `forbidden_section`) declared in the manifest. Lint never blocks\n  validation.\n- `reader_blocks` / `check_plain_language_at` — source-located reader-visible prose and\n  accountable batch analysis for the project-owned `sentence-length`, `heading-skip`, and\n  `undefined-acronym` rules. Thresholds, applicability and vocabulary come from an explicit\n  named/versioned `PlainLanguageProfile`; the engine ships no default profile.\n\n**Diagnostics & errors**\n- `QuireError` (typed, `thiserror`-derived) and `format_violation` for actionable messages\n  with field paths and observed-value previews; non-fatal `Diagnostic`s for load/walk issues.\n\n**Bindings**\n- **Python** (`--features python`): a maturin-built `quire` wheel exposing `parse_document`,\n  `load_repo`, `validate`, `validate_document`, `extract`, `extract_frontmatter`,\n  `harvest_edges`, `input_contract`, `input_skeleton`, `validate_manifest`, plus `Spec`,\n  `Registry`, and `ExtractionContext` classes and a `QuireBaseError` exception hierarchy.\n  The GIL is released on heavy Rust work; first-party binding code is `unsafe`-free.\n- **WASM** (`--features wasm`): a filesystem-free `wasm32` build using in-memory schemas via\n  `Registry::from_inline_parts` (`resolve-file` is disabled).\n\n**Hardening**\n- `#![forbid(unsafe_code)]` by default (no first-party `unsafe`), determinism gates\n  (`BTreeMap`/`IndexMap` over `HashMap`, proptest, loom), criterion perf-regression gates,\n  cargo-fuzz targets, and `cargo-deny` license/source allowlists. MSRV 1.75.\n\n## Install & use\n\n**Rust crate** — add it as a dependency:\n\n```toml\n[dependencies]\nquire = { git = \"https://github.com/agent-ix/quire-rs\" }\n```\n\nFeature flags:\n\n| Feature        | Default | Effect                                                            |\n| -------------- | :-----: | ----------------------------------------------------------------- |\n| `resolve-file` |   ✅    | Filesystem `$ref`/schema resolution (via the `jsonschema` crate). |\n| `python`       |   ❌    | PyO3 bindings → the `quire` Python wheel.                         |\n| `wasm`         |   ❌    | `wasm32` build; disables `resolve-file`, schemas passed in-memory.|\n\n**Python wheel** (`quire`):\n\n```bash\npip install quire   # from the internal pypi.ix index\n```\n\n**WASM** — consume via the [`quire-wasm`](#related-projects) npm package, or build with\n`--features wasm` and `Registry::from_inline_parts`.\n\n## Quick start\n\nRust — validate a Markdown document against a module loaded from the environment:\n\n```rust\nuse quire::Registry;\n\nlet registry = Registry::from_env()?;\nlet archetype = registry.archetype(\"FR\").expect(\"FR archetype loaded\");\n\nlet doc = std::fs::read_to_string(\"spec/FR-001.md\")?;\nlet result = quire::validate_document_in_registry(&registry, archetype, &doc);\n\nif !result.is_valid {\n    for e in &result.errors {\n        eprintln!(\"{}: {}\", e.line.unwrap_or(0), e.message);\n    }\n}\n```\n\nPython:\n\n```python\nimport quire\n\nresult = quire.validate_document(\"FR\", \"~/.ix/filament/modules/spec-artifacts-iso\", doc_text)\nprint(result[\"errors\"], result[\"warnings\"])\n```\n\n## Usage guide\n\nSee **[docs/USAGE.md](docs/USAGE.md)** for the full guide to authoring a doc standard:\narchetypes, modules, manifests, schemas, the body-extraction DSL, document/block structure,\nvalidation flow, lint rules, input contracts, the corpus, and per-surface (Rust/Python/WASM)\nusage with an end-to-end worked example.\n\n## Development\n\n```bash\nmake ci            # fmt-check + lint + test + deny + audit-unsafe (full gate)\nmake test          # cargo test\nmake lint          # clippy with -D warnings\nmake fmt           # rustfmt\nmake build         # release build\nmake deny          # cargo-deny license/source check\nmake audit-unsafe  # every `unsafe` block has a // SAFETY: comment\n```\n\nMSRV is **1.75** (pinned in `clippy.toml` / `rust-toolchain.toml`). See `CLAUDE.md` for the\nsafety scaffolding and design conventions, and `spec/` for the normative requirements.\n\n## Related projects\n\n| Project              | Relationship to quire-rs                                                          | Published as            |\n| -------------------- | --------------------------------------------------------------------------------- | ----------------------- |\n| `quire` (TypeScript) | Reference implementation; quire-rs ports it and maintains parity.                 | `@agent-ix/quire` (npm) |\n| `quire-cli`          | Thin command-line wrapper over the engine (parse / extract / lookup / edit / validate). | `@agent-ix/quire-cli`   |\n| `quire-wasm`         | WebAssembly bindings bringing parse / extract / validate to browser & Node.       | `@agent-ix/quire-wasm`  |\n| `spec-artifacts-iso` | An archetype **module** (FR / NFR / StR / US / IT / TC / AC / CON) consumed by the engine. | `spec_artifacts_iso` (pypi.ix) |\n| `quoin`            | Spec-domain CLI; installs modules and provides agent authoring contracts.         | `@agent-ix/quoin`     |\n\n## License\n\nAGPL-3.0-or-later\n",
  "bytes": 9097,
  "sha": "8193127711c01ae04ae8d0309a2d1f9f7240ebb8aa55eae1de597469c4a6207c",
  "repo_slug": "agent-ix/quire-rs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_agent_ix_quire_rs_spec_index_md_4acedd2a/readme"
}