feat(parse): emit Requires edges for AsciiDoc include:: directives

The polyglot gen path (aden-parse) dropped include:: entirely — only the legacy hand-rolled aden-graph parser handled it, and only as a no-store fallback. Port it into the canonical pipeline: the AsciiDoc extractor records include targets in a doc_includes attribute on the document's representative node, and a new additive link_include_edges pass resolves each target file (by stem) to its representative doc anchor and emits a directional Requires edge.

First step of converging the three parsing surfaces onto the polyglot aden-parse engine. Verified end-to-end: a master.adoc that include::s chapter.adoc now yields master --Requires--> chapter through real gen (edge confirmed under --edge-type Requires, absent under RelatesTo).

Author: Wave3 Test

crates/aden-cli/src/commands/generate.rs

@@ -33,6 +33,9 @@ struct EmittedSymbol {
     /// `[text](#frag)`). Linked as bidirectional `RelatesTo` edges against doc
     /// anchor fragments only.
     refs: Vec<String>,
+    /// `include::` document-composition targets (raw file paths from the
+    /// `doc_includes` attribute). Linked as directional `Requires` edges.
+    includes: Vec<String>,
     /// `edge::implements[Trait::method]` references (trait impls) — linked as
     /// `Implements` edges so blast radius reaches implementors (Wave 1).
     implements: Vec<String>,
@@ -220,6 +223,76 @@ fn extract_doc_refs(doc: &aden_core::Document) -> Vec<String> {
     extract_joined_attribute(doc, "doc_refs")
 }
 
+/// Document-composition targets, read from the `doc_includes` attribute the
+/// AsciiDoc parser fills for `include::` directives. Resolved file-wise (by
+/// stem) to directional `Requires` edges in [`link_include_edges`].
+fn extract_doc_includes(doc: &aden_core::Document) -> Vec<String> {
+    extract_joined_attribute(doc, "doc_includes")
+}
+
+/// Resolve `include::` directives (the `doc_includes` channel) into directional
+/// `Requires` edges: an including document depends on each file it pulls in.
+/// Resolution is file-wise by stem (an include names a file, not a fragment),
+/// pointing at that file's representative (first) doc node. Runs as a separate
+/// additive pass after `link_store_edges`; `put_edges_bulk` appends, so edges
+/// already written are kept.
+fn link_include_edges<S: GraphStorage>(
+    storage: &S,
+    include_records: &[(String, Vec<String>)],
+) -> Result<(), Box<dyn std::error::Error>> {
+    use aden_core::EdgeType;
+    if include_records.is_empty() {
+        return Ok(());
+    }
+    let anchors = storage.get_all_anchors()?;
+    // File stem -> declaring doc anchors (sorted/deduped for deterministic picks).
+    let mut stem_index: HashMap<&str, Vec<&str>> = HashMap::new();
+    for anchor in &anchors {
+        if let Some(file_key) = doc_anchor_file(anchor)
+            && let Some(stem) = std::path::Path::new(file_key)
+                .file_stem()
+                .and_then(|s| s.to_str())
+        {
+            stem_index.entry(stem).or_default().push(anchor.as_str());
+        }
+    }
+    for cands in stem_index.values_mut() {
+        cands.sort_unstable();
+        cands.dedup();
+    }
+    let mut edges: Vec<(String, String, EdgeType)> = Vec::new();
+    for (referrer, targets) in include_records {
+        let ref_file = doc_anchor_file(referrer);
+        for target in targets {
+            let Some(stem) = std::path::Path::new(target)
+                .file_stem()
+                .and_then(|s| s.to_str())
+            else {
+                continue;
+            };
+            let Some(cands) = stem_index.get(stem) else {
+                continue;
+            };
+            // An include points at ANOTHER document: prefer a candidate in a
+            // different file than the referrer; else the first (deterministic).
+            let target_anchor = cands
+                .iter()
+                .copied()
+                .find(|a| doc_anchor_file(a) != ref_file)
+                .or_else(|| cands.first().copied());
+            if let Some(ta) = target_anchor
+                && ta != referrer.as_str()
+            {
+                edges.push((referrer.clone(), ta.to_string(), EdgeType::Requires));
+            }
+        }
+    }
+    if !edges.is_empty() {
+        storage.put_edges_bulk(&edges)?;
+    }
+    Ok(())
+}
+
 /// Backtick prose mentions, read from the `doc_mentions` attribute the format
 /// parsers fill (Wave 2). Same division of labor as `doc_refs`: the parser
 /// knows fence/backtick state; resolution in [`link_store_edges`] is
@@ -1500,6 +1573,7 @@ fn cmd_gen_inner(
                     let callees = extract_callees(&doc_clone);
                     let uses = extract_uses(&doc_clone);
                     let refs = extract_doc_refs(&doc_clone);
+                    let includes = extract_doc_includes(&doc_clone);
                     let implements = extract_edge_macro(&doc_clone, "implements");
                     let mutates = extract_edge_macro(&doc_clone, "mutates");
                     let mentions = extract_doc_mentions(&doc_clone);
@@ -1549,6 +1623,7 @@ fn cmd_gen_inner(
                         callees,
                         uses,
                         refs,
+                        includes,
                         implements,
                         mutates,
                         mentions,
@@ -1581,6 +1656,7 @@ fn cmd_gen_inner(
         let mut link_records: Vec<(String, Vec<String>)> = Vec::new();
         let mut use_records: Vec<(String, Vec<String>)> = Vec::new();
         let mut ref_records: Vec<(String, Vec<String>)> = Vec::new();
+        let mut include_records: Vec<(String, Vec<String>)> = Vec::new();
         let mut impl_records: Vec<(String, Vec<String>)> = Vec::new();
         let mut mutates_records: Vec<(String, Vec<String>)> = Vec::new();
         let mut mention_records: Vec<(String, Vec<String>)> = Vec::new();
@@ -1672,6 +1748,9 @@ fn cmd_gen_inner(
                         if !sym.refs.is_empty() {
                             ref_records.push((sym.anchor.clone(), sym.refs));
                         }
+                        if !sym.includes.is_empty() {
+                            include_records.push((sym.anchor.clone(), sym.includes));
+                        }
                         if !sym.uses.is_empty() {
                             use_records.push((sym.anchor.clone(), sym.uses));
                         }
@@ -1792,6 +1871,13 @@ fn cmd_gen_inner(
             }
         };
 
+        // Additive second pass: include:: directives -> Requires edges. Kept
+        // separate from link_store_edges (which works from anchors only); this
+        // resolves file-wise and put_edges_bulk appends, so prior edges persist.
+        if let Err(e) = link_include_edges(&storage, &include_records) {
+            eprintln!("WARN: Failed to link include edges: {}", e);
+        }
+
         save_gen_cache(&cache_path, &cache)?;
 
         // The summary is "summary only" output: shown under --quiet/regen, but
@@ -2292,6 +2378,44 @@ mod link_tests {
     /// Prose `ref:` records resolve format-neutrally against DOC anchor
     /// fragments only — bidirectional `RelatesTo` — and must NEVER attach to a
     /// same-named code symbol (the fuzzy code path is off-limits to prose).
+    #[test]
+    fn include_records_link_requires_edges() {
+        use aden_core::{Block, Document, EdgeType, NodeType};
+        let dir = tempfile::tempdir().unwrap();
+        let storage = Storage::new(dir.path().to_str().unwrap()).unwrap();
+        let mk = |anchor: &str| Document {
+            anchor: anchor.into(),
+            node_type: NodeType::Module,
+            attributes: Default::default(),
+            blocks: vec![Block::Paragraph("body".into())],
+            source_span: None,
+            metadata: None,
+            confidence: 1.0,
+        };
+        // A master doc and a chapter it includes, each a heading-section node.
+        let master = "aden://doc/p/master.adoc/h1master";
+        let chapter = "aden://doc/p/chapter-one.adoc/h1chapter";
+        for a in [master, chapter] {
+            storage.put_document(&mk(a)).unwrap();
+        }
+        storage.flush().unwrap();
+
+        let include_records = vec![(master.to_string(), vec!["chapter-one.adoc".to_string()])];
+        link_include_edges(&storage, &include_records).unwrap();
+
+        let out = storage.get_outgoing_edges(master).unwrap();
+        assert!(
+            out.contains(&(chapter.to_string(), EdgeType::Requires)),
+            "master must Requires the included chapter doc node; got {out:?}"
+        );
+        // Directional: the chapter does not Requires the master.
+        let back = storage.get_outgoing_edges(chapter).unwrap();
+        assert!(
+            !back.iter().any(|(t, _)| t == master),
+            "include edge must be directional (master->chapter only); got {back:?}"
+        );
+    }
+
     #[test]
     fn prose_ref_records_link_doc_anchors_only() {
         use aden_core::{Block, Document, EdgeType, NodeType};
@@ -2509,6 +2633,33 @@ mod link_tests {
         );
     }
 
+    #[test]
+    fn extract_doc_includes_reads_doc_includes_attribute() {
+        use aden_core::{Block, Document, NodeType};
+        let mut attrs = std::collections::HashMap::new();
+        attrs.insert(
+            "doc_includes".to_string(),
+            "chapter-two.adoc,chapter-one.adoc,chapter-two.adoc".to_string(),
+        );
+        let doc = Document {
+            anchor: "aden://doc/p/master.adoc/h2overview".into(),
+            node_type: NodeType::Module,
+            attributes: attrs,
+            blocks: vec![Block::Paragraph("body".into())],
+            source_span: None,
+            metadata: None,
+            confidence: 1.0,
+        };
+        assert_eq!(
+            extract_doc_includes(&doc),
+            vec![
+                "chapter-one.adoc".to_string(),
+                "chapter-two.adoc".to_string()
+            ],
+            "sorted, deduped, attribute-sourced"
+        );
+    }
+
     #[test]
     fn extract_uses_reads_edge_uses_listings() {
         use aden_core::{Block, Document, NodeType};

crates/aden-parse/src/asciidoc.rs

@@ -69,6 +69,10 @@ impl crate::extractor::LanguageExtractor for AsciiDocExtractor {
         // def)` — Term-node candidates; only those inside glossary-gated
         // sections are promoted below.
         let mut term_lines: Vec<(usize, Option<String>, String, String)> = Vec::new();
+        // `include::target[]` directives (document composition). File-level, so
+        // collected once and attached to the document's representative node;
+        // resolved to `Requires` edges in the link phase.
+        let mut includes: Vec<String> = Vec::new();
 
         for (line_num, line) in body.lines().enumerate() {
             let line_num = line_num + 1;
@@ -113,6 +117,17 @@ impl crate::extractor::LanguageExtractor for AsciiDocExtractor {
             if let Some((explicit, name, def)) = parse_dlist_term(line) {
                 term_lines.push((line_num - 1, explicit, name, def));
             }
+            // `include::target[opts]` — document composition. Fence-guarded by the
+            // listing/literal skips above, so an include inside a delimited block
+            // (a code example) is not mistaken for a real directive.
+            if let Some(rest) = line.trim_start().strip_prefix("include::")
+                && let Some(br) = rest.find('[')
+            {
+                let target = rest[..br].trim();
+                if !target.is_empty() {
+                    includes.push(target.to_string());
+                }
+            }
 
             if let Some(rest) = line.strip_prefix("= ") {
                 let title = rest.trim().to_string();
@@ -226,6 +241,15 @@ impl crate::extractor::LanguageExtractor for AsciiDocExtractor {
                 if !section_refs.is_empty() {
                     attrs.insert("doc_refs".to_string(), section_refs.join(","));
                 }
+                // Includes are file-level; attach the whole file's targets to the
+                // document's representative (first) node so the link phase emits
+                // one Requires edge per included file from the document.
+                if hi == 0 && !includes.is_empty() {
+                    let mut inc = includes.clone();
+                    inc.sort();
+                    inc.dedup();
+                    attrs.insert("doc_includes".to_string(), inc.join(","));
+                }
                 // Same attribution rule for prose mentions (Wave-2 Mentions).
                 let mut section_mentions: Vec<String> = line_mentions
                     .iter()
@@ -303,6 +327,12 @@ impl crate::extractor::LanguageExtractor for AsciiDocExtractor {
             if !all_refs.is_empty() {
                 attrs.insert("doc_refs".to_string(), all_refs.join(","));
             }
+            if !includes.is_empty() {
+                let mut inc = includes.clone();
+                inc.sort();
+                inc.dedup();
+                attrs.insert("doc_includes".to_string(), inc.join(","));
+            }
             let mut all_mentions: Vec<String> =
                 line_mentions.iter().map(|(_, m)| m.clone()).collect();
             all_mentions.sort();
@@ -1025,6 +1055,58 @@ References <<_other>> here.
         );
     }
 
+    /// `include::target[]` directives must surface as a `doc_includes` attribute
+    /// on the document's representative node, so the link phase can emit a
+    /// `Requires` edge. The canonical gen path previously dropped includes.
+    #[test]
+    fn include_directive_emits_doc_includes_attribute() {
+        let ext = AsciiDocExtractor::new();
+        let src = "\
+= Master
+
+include::chapter-one.adoc[]
+
+== Overview
+
+Body.
+";
+        let docs = ext
+            .extract_documents(src, Path::new("master.adoc"))
+            .expect("extraction must succeed");
+        let with_inc = docs
+            .iter()
+            .find(|d| d.attributes.contains_key("doc_includes"))
+            .expect("a node must carry doc_includes");
+        assert_eq!(
+            with_inc.attributes.get("doc_includes").map(String::as_str),
+            Some("chapter-one.adoc"),
+        );
+    }
+
+    /// `include::` inside a delimited listing block is a code example, not a real
+    /// directive — it must NOT produce a doc_includes entry.
+    #[test]
+    fn include_inside_listing_block_is_ignored() {
+        let ext = AsciiDocExtractor::new();
+        let src = "\
+= Master
+
+----
+include::not-real.adoc[]
+----
+
+Body.
+";
+        let docs = ext
+            .extract_documents(src, Path::new("master.adoc"))
+            .expect("extraction must succeed");
+        assert!(
+            docs.iter()
+                .all(|d| !d.attributes.contains_key("doc_includes")),
+            "include inside a listing block must be ignored"
+        );
+    }
+
     /// Regression: multibyte characters (em-dashes, typographic quotes) before
     /// an `xref:` must not panic the byte-indexed scanner on a non-boundary
     /// slice (`line[i..]` with i inside a UTF-8 sequence).