meta.anchors.context_navigation

Clicking an anchor badge opens its anchor page. The page’s context link returns to the defining Markdown paragraph or .sage location. Context permalinks remain available independently of the anchor-page URL, so navigating to the rule’s connections does not lose access to its original specification text.

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

Implementation

Implemented crates/sage-meta/src/browser.rs:144–149

sage_meta::browser · lib:sage_meta

#![allow(unused)]
fn main() {
// {anchor}`meta.anchors.context_navigation`
// {anchor}`meta.reviews.claim_text`
pub fn render_spec_markdown(
    spec: &crate::spec::SpecIndex,
    file: &str,
    text: &str,

}

See more source ↗

Implemented crates/sage-meta/src/spec.rs:869–874

sage_meta::spec · lib:sage_meta

#![allow(unused)]
fn main() {
    // {anchor}`meta.anchors.context_navigation`
    fn chapter_replacements(
        &self,
        file: &str,
        source: &str,
    ) -> Result<Vec<(Span, String)>, Vec<Diagnostic>> {

}

See more source ↗

Implemented crates/sage-meta/src/book/anchors.rs:128–133

sage_meta::book::anchors · bin:sage-meta

#![allow(unused)]
fn main() {
    // {anchor}`meta.anchors.context_navigation`
    // {anchor}`meta.anchors.evidence_status`
    // {anchor}`meta.anchors.placeholder_status`
    fn page(&self, name: &str, url: &str) -> String {
        let mut text = format!(
            "# {}\n\n<nav class=\"anchor-breadcrumbs\" aria-label=\"Anchor namespaces\"><a href=\"{}\">All anchors</a>",

}

See more source ↗

Tests and review

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

Implemented sage_meta::generated_anchor_pages_join_namespaces_claims_implementations_tests_and_reviews

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.book.index_namespace_pages)]
#[sage::test(meta.book.index_rows)]
#[sage::test(meta.book.index_groups)]
#[sage::test(meta.book.index_status)]
#[sage::test(meta.anchors.anchor_pages)]
#[sage::test(meta.anchors.context_navigation)]
fn generated_anchor_pages_join_namespaces_claims_implementations_tests_and_reviews() {
    let fixture = Fixture::new("manual");
    fixture.doc("SUMMARY.md", "# Summary\n\n- [Design](design/README.md)\n  - [Crates](design/crates/README.md)\n  - [Meta](design/meta.md)\n  - [Anchors](design/anchor/README.md)\n  - [Handwritten](design/handwritten.md)\n");
    let definitions = "# Meta\n\n{anchor}`foo`\nThe **parent rule** with `code`.\n\n{anchor}`foo.bar`\nThe child rule.\n\n{anchor}`other.leaf`\nA rule in a sibling branch.\n";
    fixture.doc("design/meta.md", definitions);
    fixture.doc("design/anchor/README.md", "# Anchors\n");
    let source = std::fs::read_to_string(fixture.root.join("src/lib.rs")).unwrap();
    fixture.write(
        "src/lib.rs",
        &format!(
            "{source}\n{}",
            r#"
// {anchor}`meta.foo`
fn implementation() {}
#[test]
#[sage::test(meta.foo)]
fn behavior() { assert_eq!(2 + 2, 4); }
mod todo {
    // {anchor}`meta.foo`
    // TODO: Additional implementation and edge case.
    #[test]
    #[sage::test(meta.foo)]
    fn remaining() {}
}
mod not_applicable {
    // {anchor}`meta.foo.bar`<<
    // N/A: This requirement describes an editorial convention.
    #[test]
    #[sage::test(meta.foo.bar)]
    fn editorial() {}
    // >>

    // {anchor}`meta.other.leaf`
    // N/A: This sibling rule is also editorial.
    #[test]
    #[sage::test(meta.other.leaf)]
    fn sibling_editorial() {}
}
"#
        ),
    );
    for anchor in ["meta.foo", "meta.foo.bar", "meta.other.leaf"] {
        sage_meta::review::start(&fixture.root, anchor, vec![]).unwrap();
        if anchor != "meta.other.leaf" {
            sage_meta::review::record(
                &fixture.root,
                anchor,
                &sage_meta::review::ValidationOutput {
                    reviewer: "fixture".into(),
                    report: "Explicit placeholder status reviewed.\n\nLiteral <p> & report detail."
                        .into(),
                    requested_edits: if anchor == "meta.foo.bar" {
                        vec!["Clarify the editorial explanation.".into()]
                    } else {
                        vec![]
                    },
                },
            )
            .unwrap();
        }
    }
    let mut input = fixture.input("items");
    let children = input[1]["items"][0]["Chapter"]["sub_items"]
        .as_array_mut()
        .unwrap();
    children.push(json!({"Chapter":{"name":"Meta","content":definitions,"path":"design/meta.md","source_path":"design/meta.md","number":[2,3],"parent_names":["Design"],"sub_items":[]}}));
    children.push(json!({"Chapter":{"name":"Anchors","content":"# Anchors\n","path":"design/anchor/README.md","source_path":"design/anchor/README.md","number":[2,4],"parent_names":["Design"],"sub_items":[]}}));
    let output = fixture.run(&input);
    assert!(
        output.status.success(),
        "{}",
        String::from_utf8_lossy(&output.stderr)
    );
    let book: Value = serde_json::from_slice(&output.stdout).unwrap();
    let entries = chapters(book["items"].as_array().unwrap());
    let overview = entries["design/anchor/README.md"]["content"]
        .as_str()
        .unwrap();
    assert!(overview.contains("data-group=\"meta\""));
    assert!(overview.contains("data-group=\"meta.foo\""));
    assert!(overview.contains("3 anchors"));
    assert!(overview.contains("1 Implemented"));
    assert!(overview.contains("1 TODO"));
    assert!(overview.contains("2 N/A"));
    assert!(overview.contains("aria-controls=\"anchor-text-meta-foo\""));
    assert!(overview.contains("<strong>parent rule</strong>"));
    let page = entries["design/anchor/meta/foo.md"]["content"]
        .as_str()
        .unwrap();
    assert!(page.contains(
        "Explicit placeholder status reviewed.<br><br>Literal &lt;p&gt; &amp; report detail."
    ));
    assert!(!page.contains("<p>Explicit placeholder status reviewed.\n"));
    let table_rows = |content: &str| {
        content
            .split("data-anchor=\"")
            .skip(1)
            .map(|tail| tail.split('"').next().unwrap().to_owned())
            .collect::<Vec<_>>()
    };
    assert_eq!(
        table_rows(overview),
        ["meta.foo", "meta.foo.bar", "meta.other.leaf"]
    );
    for prefix in ["meta", "meta/foo", "meta/other"] {
        assert!(entries.contains_key(format!("design/anchor/{prefix}.md").as_str()));
    }
    assert_eq!(
        table_rows(
            entries["design/anchor/meta.md"]["content"]
                .as_str()
                .unwrap()
        ),
        ["meta.foo", "meta.foo.bar", "meta.other.leaf"]
    );
    assert_eq!(
        table_rows(
            entries["design/anchor/meta/other.md"]["content"]
                .as_str()
                .unwrap()
        ),
        ["meta.other.leaf"]
    );
    assert!(entries.contains_key("design/anchor/meta/other/leaf.md"));
    let leaf = entries["design/anchor/meta/foo.md"];
    assert_eq!(
        leaf["sub_items"].as_array().unwrap().len(),
        1,
        "a rule can also be a namespace"
    );
    assert!(
        leaf["source_path"].is_null(),
        "generated views have no canonical source"
    );
    let content = leaf["content"].as_str().unwrap();
    assert_eq!(table_rows(content), ["meta.foo", "meta.foo.bar"]);
    assert!(content.contains("../../meta.html#meta.foo"));
    assert!(content.contains("fn implementation()"));
    assert!(content.contains("fn behavior() { assert_eq!(2 + 2, 4); }"));
    assert!(content.contains("See more source"));
    assert!(content.contains("Review: <strong>Accepted</strong>"));
    assert!(content.contains("Additional implementation and edge case."));
    let child = entries["design/anchor/meta/foo/bar.md"]["content"]
        .as_str()
        .unwrap();
    assert!(child.contains("N/A: This requirement describes an editorial convention."));
    assert!(child.contains("Review: <strong>Changes requested</strong>"));
    assert!(child.contains("Clarify the editorial explanation."));
    let unfinished = entries["design/anchor/meta/other/leaf.md"]["content"]
        .as_str()
        .unwrap();
    assert!(unfinished.contains("Review: <strong>Unfinished</strong>"));
    assert!(content.contains("data-status=\"TODO\""));
    assert!(child.contains("data-status=\"N/A\""));
    let definition = entries["design/meta.md"]["content"].as_str().unwrap();
    assert!(definition.contains("href=\"anchor/meta/foo.html\""));
    let inventory = sage_meta::spec::SpecIndex::load_workspace(&fixture.root).unwrap();
    assert_eq!(
        inventory.anchors.len(),
        3,
        "rendered copies never become definitions"
    );
}
}

See more source ↗

Implemented sage_meta::sage_anchor_links_retain_the_containing_entity_and_exact_prose

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.anchors.context_navigation)]
fn sage_anchor_links_retain_the_containing_entity_and_exact_prose() {
    let fixture = Fixture::new("manual");
    fixture.model("demo/symbols.sage", "module crate::symbols;\nstruct Item {\n    \"\"\"\n    {anchor}`stable`\n    Every **symbol** keeps its identity.\n    \"\"\"\n    value: $support::Value,\n}\n");
    fixture.book("items");
    let data = script_data(
        &std::fs::read_to_string(fixture.asset()).unwrap(),
        "source-data",
    );
    let anchor = &data["anchors"]["crates.demo.symbols.stable"];
    assert_eq!(anchor["entity"], "demo::symbols::Item");
    assert_eq!(
        anchor["context_url"],
        "design/crates/demo/symbols.html#anchor:crates.demo.symbols.stable"
    );
    let prose = data["prose"]
        .as_object()
        .unwrap()
        .values()
        .flat_map(|file| file.as_object().unwrap().values())
        .filter_map(Value::as_str)
        .collect::<Vec<_>>()
        .join("\n");
    assert!(prose.contains("<strong>symbol</strong>"));
    assert!(prose.contains("id=\"crates.demo.symbols.stable\""));
    assert!(prose.contains("href=\"design/anchor/crates/demo/symbols/stable.html\""));
    assert!(prose.contains("target=\"_parent\""));
}
}

See more source ↗

Implemented sage_meta::badges_open_rule_pages_and_keep_definition_permalinks_after_expansion

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.anchors.context_navigation)]
fn badges_open_rule_pages_and_keep_definition_permalinks_after_expansion() {
    let fixture = BookFixture::new("- [Rules](design/meta/rules.md)\n");
    fixture.write(
        "design/meta/rules.md",
        "{anchor}`claim` A precise claim.\n\nSee {spec}`meta.rules.claim`.\n",
    );
    let index = fixture.load();
    let rendered = index.render_chapter("design/meta/rules.md", "Expanded preprocessor content.\n\n{anchor}`claim` A precise claim.\n\nSee {spec}`meta.rules.claim`.\n").unwrap();
    assert!(rendered.contains("id=\"meta.rules.claim\" href=\"../anchor/meta/rules/claim.html\""));
    assert!(rendered.contains("class=\"spec-reference\" href=\"../anchor/meta/rules/claim.html\""));
    assert!(rendered.starts_with("Expanded preprocessor content."));
    assert_eq!(
        index.anchors["meta.rules.claim"].context_url,
        "design/meta/rules.html#meta.rules.claim"
    );
}
}

See more source ↗

Implemented sage_meta::sage_prose_rules_have_precise_spans_model_owners_and_cross_source_references

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

#![allow(unused)]
fn main() {
#[test]
#[sage::test(meta.anchors.canonical_sources)]
#[sage::test(meta.anchors.context_navigation)]
#[sage::test(meta.anchors.content.source_end)]
#[sage::test(meta.reviews.claim_text)]
#[sage::test(meta.anchors.unique_names)]
fn sage_prose_rules_have_precise_spans_model_owners_and_cross_source_references() {
    let fixture =
        BookFixture::new("- [Meta](design/meta.md)\n- [Crates](design/crates/README.md)\n");
    fixture.write(
        "design/meta.md",
        "{anchor}`rule` A rule refers to {spec}`crates.demo.nodes.member`.\n",
    );
    fixture.write("design/crates/README.md", "# Crates\n");
    fixture.write(
        "design/crates/demo/crate.sage",
        "crate demo { \"\"\"Demo.\"\"\" module nodes; }",
    );
    let sage = r#"module crate::nodes;
struct Value {
    """
    {anchor}`value`
    A value with **meaning**.

    Précise values survive edits.

    - Keep the cached value.

    ```text
        Preserve relative indentation.
    ```
    """
    """
    {anchor}`member`
    Fields obey {spec}`meta.rule`.
    """
    number: Value,
}
class Node {
    """A node."""
    query value() -> Value {
        """
        {anchor}`query`
        Query results have stable identity.
        """
        envelope {}
    }
}
"#;
    fixture.write("design/crates/demo/nodes.sage", sage);
    let index = fixture.load();
    assert!(index.diagnostics.is_empty(), "{:?}", index.diagnostics);
    let value = &index.anchors["crates.demo.nodes.value"];
    assert_eq!(value.entity.as_deref(), Some("demo::nodes::Value"));
    assert_eq!(
        value.content,
        "A value with **meaning**.\n\nPrécise values survive edits.\n\n- Keep the cached value.\n\n```text\n    Preserve relative indentation.\n```"
    );
    assert_eq!(&sage[value.span.start..value.span.end], "{anchor}`value`");
    assert_eq!(
        &sage[value.content_span.start..value.content_span.end],
        "A value with **meaning**.\n\n    Précise values survive edits.\n\n    - Keep the cached value.\n\n    ```text\n        Preserve relative indentation.\n    ```"
    );
    let rust = sage_meta::correspondence::CorrespondenceIndex::from_sources(&[]).unwrap();
    let inputs = sage_meta::review::inventory(&index, &rust).unwrap();
    assert_eq!(
        inputs["crates.demo.nodes.value"].fragments.iter().find(|fragment| matches!(&fragment.selector, sage_meta::review::Selector::Claim { anchor_id } if anchor_id == "crates.demo.nodes.value")).unwrap().contents.join("\n"),
        "A value with **meaning**.\n\nPrécise values survive edits.\n\n- Keep the cached value.\n\n```text\n    Preserve relative indentation.\n```"
    );
    assert_eq!(
        index.anchors["crates.demo.nodes.member"].entity.as_deref(),
        Some("demo::nodes::Value::number")
    );
    assert_eq!(
        index.anchors["crates.demo.nodes.member"].content,
        "Fields obey {spec}`meta.rule`."
    );
    assert_eq!(
        index.anchors["crates.demo.nodes.query"].entity.as_deref(),
        Some("demo::nodes::Node::value")
    );
    let query = &index.anchors["crates.demo.nodes.query"];
    assert_eq!(query.content, "Query results have stable identity.");
    assert_eq!(
        &sage[query.content_span.start..query.content_span.end],
        query.content
    );
    assert_eq!(
        value.context_url,
        "design/crates/demo/nodes.html#anchor:crates.demo.nodes.value"
    );
    assert_eq!(index.references.len(), 2);
    for reference in &index.references {
        assert_eq!(
            &index.sources[&reference.file][reference.span.start..reference.span.end],
            format!("{{spec}}`{}`", reference.name)
        );
    }
}
}

See more source ↗

TODO sage_meta::todo::anchor_pages_and_definition_context_links

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

#![allow(unused)]
fn main() {
#[test]
    #[sage::test(meta.anchors.context_navigation)]
    fn anchor_pages_and_definition_context_links() {
        // TODO: Add browser-driven badge-to-anchor-to-context round trips for
        // Markdown and Sage definitions, verifying permalink preservation and
        // scrolling to the exact definition. Rendered-link assertions alone
        // do not exercise this interactive navigation.
    }
}

See more source ↗

Review: Accepted · final_quality.

Fresh final marker followup of meta.anchors.context_navigation. Preserved previous input/output, started fresh and checked the complete claim, three implementation associations, four ordinary tests and one TODO test. Recaptured all prior helpers: book Fixture/chapter/script-data ranges, spec BookFixture, and browser.js anchor routing/selection ranges. Compared every fragment by path/selector and both metadata collections. The only delta is an implementation_references comment in spec.rs; all claim, implementation behavior, tests, helper captures and association metadata are unchanged, with no removed fragments. I reassessed this isolated marker against the complete prior accounting below.

The three ordinary implementations cover chapter replacements, safe prose rendering and anchor-page generation. spec.rs chapter_replacements gives the definition badge its canonical id and a separate href to the generated anchor page; reference links also target that page. add_chapter_text records a distinct context_url to the defining Markdown chapter/anchor or Sage chapter/anchor: route, preserving entity ownership. Reparsing supplied rendered chapter text keeps badges correct after preprocessor prefix changes. book/anchors.rs page renders a relative context link back to that stored destination. browser.rs render_spec_markdown protects roles while rendering/rebasing their links and targets the parent book shell. Captured browser.js resolves an anchor's entity, renders that entity route and selects/highlights/scrolls the canonical marker. Thus viewing rule connections does not replace the independent definition permalink. Source inspection of this path is not live browser execution.

All four ordinary tests retain meaningful assertions. generated_anchor_pages_join_namespaces_claims_implementations_tests_and_reviews runs real preprocessing and checks both the definition-to-anchor-page href and generated-page-to-Markdown-context href. sage_anchor_links_retain_the_containing_entity_and_exact_prose checks explorer data entity identity, exact Sage context URL, formatted prose, canonical marker id, anchor-page href and _parent targeting. badges_open_rule_pages_and_keep_definition_permalinks_after_expansion verifies badge/reference destinations and definition id after injected prefix content, while asserting the independent stored Markdown context URL. sage_prose_rules_have_precise_spans_model_owners_and_cross_source_references verifies original source spans, bounded content, declaration/field/method owners and Sage context URL, grounding the return destination in the defining prose. Captured helpers construct actual source/model files and invoke production preprocessing/inventory.

The sole TODO anchor_pages_and_definition_context_links has no behavior assertions and explicitly reserves browser-driven badge-to-anchor-to-context round trips for Markdown and Sage, permalink preservation and exact-definition scrolling. Its prerequisite is interactive generated-book/browser testing that checks the resulting location and selection. Rendered-link assertions and source inspection do not discharge this deferred end-to-end coverage. There are no N/A entries. The full claim remains supported by current link/context mechanisms with that visible test deferral; the marker-only delta adds no new gap.

No source edits, formatting, tests or workspace build were performed. Executed review start/read, capture comparison and record only. No requested edits.

Browse meta anchors

116 anchors

Specification anchors and declared coverage
AnchorImplementationTests
meta (116)102 Implemented24 TODO103 Implemented36 TODO
meta.anchors (22)22 Implemented21 Implemented12 TODO
anchor_pagesImplementedImplementedTODO
book_explorerImplementedImplementedTODO
canonical_sourcesImplementedImplementedTODO
meta.anchors.content (7)7 Implemented7 Implemented
blocksImplementedImplemented
explicit_endImplementedImplemented
headingImplementedImplemented
literal_syntaxImplementedImplemented
next_anchorImplementedImplemented
source_endImplementedImplemented
unmatched_endImplementedImplemented
context_navigationImplementedImplementedTODO
evidence_statusImplementedImplementedTODO
explorer_navigationImplementedTODO
implementation_coverageImplementedImplementedTODO
implementation_referencesImplementedImplementedTODO
placeholder_statusImplementedImplementedTODO
point_excerptsImplementedImplementedTODO
region_balanceImplementedImplemented
region_excerptsImplementedImplementedTODO
test_coverageImplementedImplemented
test_referencesImplementedImplemented
unique_namesImplementedImplementedTODO
meta.book (21)10 Implemented18 TODO12 Implemented18 TODO
anchor_movesImplementedTODOImplementedTODO
authorityImplementedTODOImplementedTODO
browser_deliveryTODOImplementedTODO
browser_dependenciesTODOTODO
browser_rust_sourceTODOTODO
browser_searchTODOTODO
browser_serveTODOTODO
browser_structureTODOTODO
chapter_namesImplementedTODOImplementedTODO
crate_ownershipImplementedImplemented
crates_landingImplementedImplemented
entity_linksTODOTODO
index_groupsImplementedTODOImplementedTODO
index_namespace_pagesImplementedImplemented
index_rowsImplementedTODOImplementedTODO
index_statusImplementedTODOImplementedTODO
rfd_changesTODOTODO
sage_chaptersTODOImplementedTODO
self_descriptionTODOTODO
shared_modelImplementedTODOImplementedTODO
source_rolesTODOTODO
meta.contracts (4)4 Implemented3 TODO4 Implemented3 TODO
cache_invocationsImplementedTODOImplementedTODO
correspondenceImplementedImplemented
observation_coverageImplementedTODOImplementedTODO
validated_sessionImplementedTODOImplementedTODO
meta.language (39)39 Implemented39 Implemented
meta.language.calls (2)2 Implemented2 Implemented
declaredImplementedImplemented
forbiddenImplementedImplemented
meta.language.classes (3)3 Implemented3 Implemented
abstract_completeImplementedImplemented
override_signatureImplementedImplemented
single_inheritanceImplementedImplemented
meta.language.contexts (1)1 Implemented1 Implemented
inheritanceImplementedImplemented
meta.language.envelopes (7)7 Implemented7 Implemented
class_callsImplementedImplemented
createsImplementedImplemented
direct_callsImplementedImplemented
leafImplementedImplemented
permissionsImplementedImplemented
readsImplementedImplemented
receiver_callsImplementedImplemented
meta.language.fields (2)2 Implemented2 Implemented
context_stateImplementedImplemented
kindsImplementedImplemented
meta.language.methods (2)2 Implemented2 Implemented
kindsImplementedImplemented
proseImplementedImplemented
meta.language.model (3)3 Implemented3 Implemented
forbidden_pathsImplementedImplemented
inherited_prohibitionsImplementedImplemented
virtual_dispatchImplementedImplemented
meta.language.types (19)19 Implemented19 Implemented
argument_arityImplementedImplemented
declaration_proseImplementedImplemented
enum_variantsImplementedImplemented
field_proseImplementedImplemented
generic_parametersImplementedImplemented
member_commasImplementedImplemented
name_resolutionImplementedImplemented
opaque_representationImplementedImplemented
preludeImplementedImplemented
qualified_namesImplementedImplemented
recursive_valuesImplementedImplemented
struct_fieldsImplementedImplemented
tuplesImplementedImplemented
type_expressionsImplementedImplemented
unique_fieldsImplementedImplemented
unique_parametersImplementedImplemented
unique_variantsImplementedImplemented
unknown_namesImplementedImplemented
variant_proseImplementedImplemented
meta.reviews (27)27 Implemented27 Implemented
claim_textImplementedImplemented
complete_test_setImplementedImplemented
decisionsImplementedImplemented
fragment_associationsImplementedImplemented
fragment_formatImplementedImplemented
fragment_freshnessImplementedImplemented
gateImplementedImplemented
input_formatImplementedImplemented
input_fragmentsImplementedImplemented
output_formatImplementedImplemented
preparationImplementedImplemented
record_requiredImplementedImplemented
recorded_readsImplementedImplemented
recordingImplementedImplemented
review_delegationImplementedImplemented
review_diagnosticsImplementedImplemented
review_instructionsImplementedImplemented
review_scopeImplementedImplemented
selector_claimImplementedImplemented
selector_line_rangeImplementedImplemented
selector_testImplementedImplemented
selector_whole_fileImplementedImplemented
source_representationImplementedImplemented
stalenessImplementedImplemented
summary_formatImplementedImplemented
test_sourceImplementedImplemented
validation_layoutImplementedImplemented
meta.validation (3)3 TODO3 TODO
claim_specific_evidenceTODOTODO
independent_inspectionTODOTODO
review_packetsTODOTODO