Crate rto_spec 

House-style ADR/blueprint/site-page parsing and roteiro check drift detection.

An ADR becomes an adr node with adr_section children; its [[path#Symbol]] wiki-links and @rto:<id> source annotations become authored edges into the derived code graph. check::run validates those links against the graph and fails on drift (a link to a missing symbol, or a @rto: annotation to an unknown or superseded ADR).

SitePage is the same treatment for the public website: a document that declares itself published becomes a site_page node whose links are drift-checked like an ADR’s, so roteiro.dev stops being the one documentation surface outside the gate. See site for why publication is a frontmatter marker rather than a directory.

Structs

AdrDoc

A fully-parsed ADR: metadata, section structure, and authored links.

AdrMeta

Metadata for one ADR, as read from its frontmatter.

Annotation

A @rto:<id> annotation found in a source file.

AuthoredDocs

The authored layer plus the site pages — everything one tree’s classify pass yields.

AuthoredLayer

The authored documents found in one tree, ready for crate::check::run or crate::check::validate.

BlueprintDoc

A fully-parsed blueprint: title, section structure, and authored links.

CheckReport

The outcome of a run: how much authored content was checked and any drift found.

CheckedAgainst

Which graph the verdict describes, so a reader can tell what was compared.

DocVersion

A two-component ADR document version, e.g. 1.10.

GraphifyImport

The result of importing a Graphify graph: the facts to apply and a report.

ImportReport

An auditable summary of a Graphify import.

InlineVersionRef

One (Update, vX.Y…) note found in an ADR body.

LatAnnotation

A @lat: backlink found in a source file: a code→lat reference carried in a [[…]] wiki-link on a comment line.

LatImport

The result of importing a lat.md directory: the authored facts and a report.

LatReport

An auditable summary of a lat.md import.

Section

One ## section of an ADR body.

SitePage

A fully-parsed site page: what the site publishes, and the authored links the check validates.

SpecContext

Graph-grounded context for a topic: the related symbols (with neighbourhood), related docs/ADRs, and the set of ADRs that govern any matched symbol.

SymbolContext

A code symbol related to the topic, with the slice of its graph neighbourhood that grounds authoring: what defines it, what it calls / is called by, and the authored ADRs/sections that govern it.

ToolCheck

The tool-surface check result.

Validation

The outcome of a read-only validate: the report, plus the authored edges the valid links and annotations would weave into the graph.

VersionFacts

Every claim an ADR makes about its own version, gathered so crate::check::validate can cross-check them against each other.

Violation

A single authored-layer drift finding.

WikiLink

A [[path#Symbol]] (or [[path]]) authored link found in an ADR, resolved to the graph node key it should point at.

Enums

AdrStatus

ADR lifecycle states, exactly as the house style defines them.

Gate

The gate verdict, as a value rather than an exit code.

ImportError

Errors raised while importing.

ParseError

Errors raised while parsing ADR metadata.

SiteParseError

Why a document that declared itself a site page could not be parsed as one.

ViolationKind

The category of an authored-layer drift.

Constants

GRAPHIFY_REF

src_ref stamped on every edge imported from Graphify, so it can be told apart from other inferred edges (e.g. the embedding layer’s).

LAT_REF

src_ref stamped on every edge imported from lat.md, so it can be told apart from other authored edges (ADRs) and re-derived authoritatively on re-import.

SITE_PAGE_FIELD

The frontmatter field that declares a document published, and carries its slug. Its presence is the whole classification rule.

SPEC_SCHEMA

Versioned schema tag for authoring outputs, so agents can depend on the shape.

TOOL_CHECK_SCHEMA

Schema tag for the tool-surface check document.

Functions

apply_drafts

Splice generated prose back into a scaffold: each _TODO…_ line under a heading present in drafts (as (heading, prose)) is replaced by that prose. Headings without a draft, and all other lines, are left unchanged.

authored_blobs

Which files in source’s tree carry the authored layer.

authored_docs

Read and parse everything the authored classification yields from source’s tree: the file set from authored_blobs, the bytes from Repo::read_source, and the classification from authored_docs_from.

authored_docs_from

Classify and parse the authored layer out of blobs, reading each blob’s bytes with read.

authored_layer

Read and parse the authored layer from source’s tree, discarding the site pages — see authored_layer_from.

authored_layer_from

Classify and parse the authored layer out of blobs, reading each blob’s bytes with read — discarding the site pages.

context

Assemble graph-grounded SpecContext for topic, keeping up to limit symbols and up to limit docs (most relevant first).

draft_prompt

Build a grounded generation prompt (a plain-text user message) for the heading section of an artifact about topic, using hint as guidance and ctx as the real symbols/ADRs the model may reference. The prompt constrains the model to the grounded facts so drafts stay honest.

draft_targets

The placeholder sections of a scaffold a generator should fill: (heading, hint) for each _TODO…_ line, in document order. hint is the guidance text after _TODO: (empty for a bare _TODO._).

import_graphify

Import a Graphify node-link JSON graph into Roteiro facts.

import_lat

Import a lat.md directory. files are (repo-relative path, content) pairs for the markdown under lat.md/. Cross-file section links are resolved against the set of files provided.

import_lat_backlinks

Resolve @lat: backlinks against the lat file set, returning authored references edges (file:<path> → lat section, stamped LAT_REF) and the number that named no known lat file. Only lat-section references resolve here; a backlink to a non-lat target is dropped (and counted unresolved).

is_blueprint

Whether a markdown file is a house-style blueprint: it lives under docs/blueprint/docs/blueprints, or its first H1 carries the — Technical Implementation Plan marker. Callers apply this only to non-ADR markdown (ADRs are recognised first).

is_site_page

Whether a markdown document declares itself published: its frontmatter carries a non-empty MARKER_FIELD.

parse_adr

Parse an ADR markdown document at rel_path.

parse_blueprint

Parse a house-style blueprint markdown document at rel_path. Infallible: with no frontmatter there is nothing that can fail to parse (an empty or heading-less file yields a titled node with no sections/links).

parse_site_page

Parse a house-style site page at rel_path.

resolve_lat_ref

A lat reference (in a [[…]] link or a @lat: annotation) resolved to the graph node key it targets, if it names a known lat file.

run

Apply the authored layer to store and validate it against the derived graph, returning a CheckReport.

run_layer

run over a whole AuthoredDocs, including its site pages. See validate_layer for why both entry points exist.

scaffold_adr

Generate a house-style ADR skeleton for topic, grounded in ctx: correct frontmatter (id adr_id, Draft), the house section headings with placeholders, a clarify interview checklist, and a build-plan outline. The [[…]] links it emits — affected symbols and related ADRs — are drawn from the graph, so they resolve and the scaffold is roteiro check-clean by construction. date is YYYY-MM-DD (the caller supplies today’s date).

scaffold_blueprint

Generate a house-style blueprint (technical implementation plan) skeleton for topic, grounded in ctx. Blueprints have no YAML frontmatter: an — Technical Implementation Plan H1, a grounding intro citing related ADRs and affected code, a Status blockquote, then numbered sections (scope → crate placement → design → testing → phased build order → risks) plus a clarify interview. Grounded [[…]] links resolve against real nodes.

scan_annotations

Find every @rto:<id> annotation on a comment line in text, tagged with rel_path.

scan_lat_annotations

Find every @lat: backlink in text, tagged with rel_path. Recognition is restricted to comment lines (as with @rto:) so example tokens in string literals are not mistaken for real backlinks, and the reference must be a [[…]] wiki-link so a lat name containing spaces is delimited unambiguously. A single comment may carry several (// @lat: [[a#x]] [[b#y]]).

site_nav

The site navigation order: every page, sorted by site-order then slug.

tool_check

Run roteiro check’s drift validation read-only against store, with the authored layer read from the committed HEAD tree of the repository at root.

validate

Validate the authored layer against the derived graph without writing anything, returning the report and the edges a writing caller should weave.

validate_layer

validate over a whole AuthoredDocs — the same verdict, plus the site pages the three-slice form has no parameter for.

Type Aliases

BlobReader

Yields a blob’s authored bytes, or None when the tree has no such file (a worktree deletion, which the caller drops).