meta.anchors.region_balance

A region opener without a closing delimiter, or a closing delimiter without an open region, is an error. Delimiters in string literals do not open or close regions. Region boundaries are determined from source comments, independently of the five-line previews used for point references.

The existing // ANCHOR: name / // ANCHOR_END: name convention remains independent: it delimits explanatory excerpts for mdBook/ezanchor. Canonical implementation entries require only the specification comment syntax above.

Read in specification context · design/meta/anchors.md

Implementation

Implemented crates/sage-meta/src/evidence.rs:109–114

sage_meta::evidence · lib:sage_meta

#![allow(unused)]
fn main() {
            // {anchor}`meta.anchors.region_balance`
            if let Some(index) = open.pop() {
                let site = &mut pending[index].1;
                site.end_line = lines.number(comment.span.start);
                site.span.end = lines.end(site.end_line);
            } else {

}

See more source ↗

Tests and review

Indexed tests and the implementation-completeness and test-adequacy review; no test run is implied.

Implemented sage_meta::mdbook_excerpt_markers_neither_define_nor_close_canonical_regions

crates/sage-meta/tests/evidence.rs · test:evidence

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.anchors.region_balance)]
fn mdbook_excerpt_markers_neither_define_nor_close_canonical_regions() {
    // Split fixture-only excerpt markers so the book's source scanner ignores them.
    let unrelated = index(concat!(
        "// AN",
        "CHOR: example.unclosed\n// AN",
        "CHOR_END: example.other\n"
    ));
    assert!(unrelated.implementations.is_empty());
    assert!(unrelated.diagnostics.is_empty());

    let source = concat!(
        "// {anchor}`example.rule`<<\n// AN",
        "CHOR: explanatory\nconst VALUE: u32 = 4;\n// AN",
        "CHOR_END: explanatory\nconst STILL_INSIDE: u32 = 4;\n",
        "const PAST_POINT_PREVIEW: u32 = 4;\nconst LAST: u32 = 4;\n// >>\n"
    );
    let rust = index(source);
    assert!(rust.diagnostics.is_empty(), "{:?}", rust.diagnostics);
    assert_eq!(rust.implementations.len(), 1);
    let sites = &rust.implementations["example.rule"];
    assert_eq!(sites.len(), 1);
    assert_eq!(sites[0].excerpt, source);
    assert!(sites[0].excerpt.lines().count() > 6);
    assert!(sites[0].excerpt.contains("STILL_INSIDE"));
    assert!(sites[0].excerpt.ends_with("// >>\n"));
}
}

See more source ↗

Implemented sage_meta::unmatched_regions_fail_and_strings_or_trailing_comments_do_not_close_them

crates/sage-meta/tests/evidence.rs · test:evidence

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.anchors.region_balance)]
fn unmatched_regions_fail_and_strings_or_trailing_comments_do_not_close_them() {
    for (source, expected) in [
        ("// >>\n", "closer has no opening"),
        ("// {anchor}`example.open`<<\n", "opener has no closing"),
        (
            "// {anchor}`example.open`<<\nconst TEXT: &str = \"// >>\";\n",
            "opener has no closing",
        ),
        (
            "// {anchor}`example.open`<<\nconst X: u32 = 0; // >>\n",
            "opener has no closing",
        ),
    ] {
        let rust = index(source);
        assert_eq!(
            rust.diagnostics.len(),
            1,
            "{source}: {:?}",
            rust.diagnostics
        );
        assert!(rust.diagnostics[0].message.contains(expected));
        assert_eq!(rust.diagnostics[0].file, "src/lib.rs");
    }
    let rust = index(
        "// {anchor}`example.open`<<\n// >>\nconst TEXT: &str = r#\"// {anchor}`example.fake`<<\"#;\n",
    );
    assert!(rust.diagnostics.is_empty());
    assert_eq!(rust.implementations.len(), 1);
}
}

See more source ↗

Review: Accepted · Codex anchor_094 final reviewer for region_balance.

Fresh source review of meta.anchors.region_balance. Requirements are errors for unmatched openers/closers, ignoring delimiter-looking string literals, deriving regions from source comments independently of point-preview length, and keeping mdBook/ezanchor ANCHOR/ANCHOR_END conventions independent from canonical specification-comment entries. Inspected the ordinary evidence.rs association, its complete scanner/stack helpers, both ordinary annotated tests and the captured index fixture/inventory dispatch.

index_source maintains an open stack of pending region-entry indexes. A valid marker with << pushes its pending site. An actual standalone comment whose trimmed text is >> pops that stack and extends the matching site's span through the closing line; an empty stack produces the closer-has-no-opening Diagnostic at that comment. Remaining stack entries at end of source each produce opener-has-no-closing diagnostics at the opener. Stack membership is changed only by these recognized canonical comments. The region branch initially sets its end line to its opening line and later uses the real closer; the separate point branch computes line+5 and does not push the stack. Thus the five-line preview cannot end a region or consume its delimiters. marker recognizes only the {anchor}`name` syntax, with an exact << tail for regions; unrelated ANCHOR/ANCHOR_END comments neither define canonical sites nor close them.

line_comments obtains Rust token literal spans recursively, skips those ranges before scanning comment delimiters, handles nested block comments and excludes doc-comment forms. Consequently ordinary and raw string contents cannot open or close a canonical region. Comment::standalone requires only whitespace before the comment on its physical line, so a trailing // >> after code is not a closer. Lines provides source byte/line conversions for the original excerpt. Captured CorrespondenceIndex::from_sources parses actual Rust and implementation_entries forwards the indexed source to this scanner; the test helper is setup only.

Complete tests: unmatched_regions_fail_and_strings_or_trailing_comments_do_not_close_them asserts exactly one correctly named diagnostic in src/lib.rs for an orphan closer, an unclosed opener, an apparent closer inside an ordinary string and a trailing-comment closer after code. Its successful balanced-region fixture additionally includes a raw-string fake opener and asserts no diagnostics and one real implementation entry, detecting accidental region creation from literal text. mdbook_excerpt_markers_neither_define_nor_close_canonical_regions first checks unrelated legacy markers yield neither entries nor diagnostics, including mismatched legacy names. Its canonical region encloses a balanced legacy excerpt and continues beyond the point-preview length; it asserts a single implementation, no diagnostics, exact full-source excerpt, more than six lines, retained text after the legacy close and the canonical closing delimiter at the end. This directly tests the independent conventions and source-driven extent. A regression sharing legacy marker state, accepting a string delimiter or truncating at five following lines would fail these assertions.

Both tests are substantive ordinary evidence; there are no TODO/N/A entries. All claim requirements are covered and source inspection found no concrete violation. No source files were edited and no test/build suites were rerun in this review; centrally reported execution is separate. Only review preparation/capture/record commands were executed. No edits are requested.

Browse meta anchors

116 anchors

Anchor Implementation Tests

meta (116) 102 Implemented24 TODO 103 Implemented36 TODO

meta.anchors (22) 22 Implemented 21 Implemented12 TODO

anchor_pages Implemented ImplementedTODO

Every specification anchor has a stable page identifying the rule and showing its definition, context, implementation entries, and tests/evidence. The page includes Rust excerpts and access to surrounding source, and exposes each entry’s placeholder status and explanation. Multiple sites remain individually inspectable rather than being reduced to a single coverage badge.

Symposiun AGentic Environment (SAGE)

meta.anchors.region_balance

Implementation

Tests and review