gobby_code/commands/codewiki/
mod.rs

1use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
2use std::path::{Path, PathBuf};
3
4use crate::graph::typed_query;
5use crate::index::hasher;
6use crate::models::Symbol;
7
8const DEFAULT_OUT_DIR: &str = "codewiki";
9const CODEWIKI_META_PATH: &str = "_meta/codewiki.json";
10const OWNERSHIP_META_PATH: &str = "_meta/ownership.json";
11const MAX_EDGE_LIMIT: usize = 100_000;
12/// Cache epoch for generated pages. Bumped 9 -> 10 so reused pages re-render
13/// with compact navigation-table cells: a subsystem / child-module / module
14/// summary inlined into a parent table cell is reduced to its leading paragraph
15/// (the full multi-table brief stays on the module's own page) instead of a wall
16/// of pipe-escaped pseudo-tables.
17/// Bumped 8 -> 9 for the deep-wiki narrative
18/// pass: file pages demote `## Key components` to a capped `## Reference` table
19/// with test-gated symbols collapsed into a single behavior-spec line; the
20/// architecture topology diagram stitches fixed required/degraded service-edge
21/// labels; the page prompts demand design rationale, failure/degradation
22/// behavior, and evaluator context; and the grounding pass no longer appends the
23/// trailing bare-citation dump when a page already cites inline (#895). All
24/// reused pages must regenerate into the new shape.
25/// Bumped 7 -> 8 so reused pages regenerate
26/// without the auto-generated mermaid code-graph diagrams (per-module
27/// dependency/call diagrams, repo/architecture subsystem maps), which were the
28/// sole source of `graph-truncated`/`graph-unavailable` page degradation; graph
29/// availability is now informational only and never marks a page degraded.
30/// Bumped 10 -> 11 so narrative chapters re-render under the deterministic,
31/// reading-ordered slug scheme (`code/narrative/01-introduction.md`, #900): the
32/// old alphabetical bare-slug pages become orphans that `finish`'s cache-
33/// independent GC reclaims on this first full regen.
34/// Bumped 6 -> 7 so verifier audit notes appear in frontmatter even when source
35/// hashes are unchanged. Bumped 5 -> 6 so file and module pages written in the
36/// old symbol-dump shape (API Symbols / Component ID / Lines table, full-range
37/// `<details>` provenance) cannot be reused from disk: the new shape renders a
38/// verified narrative body plus a human Key components table. (5 was the
39/// grounded verification pass; 4 the pre-verify pages.)
40// 13 (#905): curated concept/narrative pages strip a duplicate leading `# H1`
41// the model writes at the top of its body (the renderer owns the canonical
42// `# {title}`), so prior on-disk pages with two H1s re-render with one.
43// 12 (#904): repo overview links the analysis/catalog pages (feature catalog,
44// infrastructure, deprecations, dead-code candidates) from a new "Analysis &
45// catalogs" section, narrative extra chapters carry readable `NN-<title>` slugs,
46// and aggregate prose is written opus-first — so prior on-disk pages re-render.
47const CODEWIKI_RENDER_VERSION: u32 = 13;
48
49/// Default daemon feature profile for the grounded verification pass (#904):
50/// `feature_mid` (sonnet) runs the "is this claim supported by the cited
51/// source?" QA judgment, pairing with the opus-first aggregate writer (see
52/// `writer_candidate_chain` in `text/generation.rs`). File and symbol docs stay
53/// on the daemon's default low-tier profile.
54pub(crate) const DEFAULT_VERIFY_PROFILE: &str = "feature_mid";
55
56mod architecture_diagrams;
57mod build;
58mod cluster;
59mod generation;
60mod graph;
61mod io;
62mod ownership;
63mod paths;
64mod progress;
65mod prompts;
66mod relationship_facts;
67mod render;
68mod repair;
69mod reuse;
70mod run;
71mod system_model;
72mod text;
73mod truth_digest;
74mod types;
75
76// Document builders.
77#[cfg(test)]
78pub(crate) use build::build_module_docs;
79pub(crate) use build::{
80    AuditContext, FileDocPosition, build_architecture_doc, build_audit_context,
81    build_codewiki_changes_doc, build_codewiki_index_snapshot, build_curated_navigation_docs,
82    build_deprecations_doc, build_feature_catalog_doc, build_file_doc, build_hotspots_doc,
83    build_infrastructure_doc, build_module_docs_with_filter, build_onboarding_doc,
84};
85pub(crate) use truth_digest::build_truth_digest;
86// Module clustering and graph-to-file helpers.
87pub(crate) use cluster::{
88    cluster_file_modules, files_for_import_target, first_component_for_file,
89    symbols_by_file_component,
90};
91#[cfg(test)]
92pub(crate) use cluster::{common_module_for_files, find_file_root};
93// Optional FalkorDB graph queries.
94pub use generation::generate_hierarchical_docs;
95#[cfg(test)]
96pub(crate) use generation::{
97    generate_hierarchical_docs_core, generate_hierarchical_docs_with_progress,
98    generate_hierarchical_docs_with_reuse, generate_hierarchical_docs_with_verify,
99};
100pub(crate) use graph::fetch_codewiki_graph_edges;
101#[cfg(test)]
102pub(crate) use graph::{
103    codewiki_call_edges_query, codewiki_import_edges_query, import_edges_from_pairs,
104};
105pub(crate) use ownership::{OwnershipMeta, OwnershipOptions, build_ownership_doc};
106pub(crate) use progress::CodewikiProgress;
107// Markdown path and wikilink helpers.
108pub(crate) use paths::{
109    component_label, direct_child_modules, file_doc_path, file_wikilink, in_scope, inline_code,
110    is_core_file, module_ancestors, module_depth, module_doc_path, module_for_file,
111    module_is_ancestor, module_wikilink, parent_module, plural, write_markdown_table_header,
112    write_markdown_table_row,
113};
114// Cross-file relationship facts threaded into narrative prompts (#885).
115pub(crate) use relationship_facts::{RelationshipFacts, relationship_facts_for_file};
116// Deterministic, no-LLM workspace system model (#887, epic #886). Consumed by
117// the architecture diagram leaf (#891) below to seed model-derived diagrams.
118pub use system_model::{
119    Crate, Edge, RuntimeMode, ServiceBoundary, ServiceKind, SystemModel, build_system_model,
120};
121// Model-seeded architectural Mermaid diagrams for the architecture page (#891).
122#[cfg(test)]
123pub(crate) use architecture_diagrams::is_valid_mermaid;
124pub(crate) use architecture_diagrams::{render_architecture_diagrams, render_service_matrix};
125// Rendered markdown and graph-derived narrative analysis.
126pub(crate) use render::{
127    build_repo_doc, collect_subsystem_dependency_edges, render_architecture_doc,
128    render_deprecations_doc, render_feature_catalog_doc, render_file_doc, render_hotspots_doc,
129    render_infrastructure_doc, render_module_doc, render_onboarding_doc,
130};
131// Reuse of unchanged docs without regeneration.
132pub(crate) use reuse::{ReusePlan, span_files};
133#[cfg(test)]
134pub(crate) use run::{
135    git_changed_files, load_symbols_for_codewiki, should_document_file, validate_edge_limit,
136};
137pub use run::{run, run_repair};
138// Citation repair: re-anchor on-disk citations against the current index with
139// no regeneration. Public so a later leaf's `--repair-citations` flag drives it.
140pub use repair::{CitationRepairSummary, repair_citations};
141// AI and structural text helpers.
142pub(crate) use text::{
143    CitationResolver, Generation, VerifyOutcome, append_curated_source_files,
144    append_relevant_source_files, citation_list, citation_markers, collect_link_spans,
145    display_child_summary, frontmatter_with_degradation,
146    frontmatter_with_degradation_and_verify_notes_without_ranges,
147    frontmatter_with_degradation_without_ranges, ground_text, maybe_generate,
148    neutralize_symbol_purpose_links, reanchor_citations, replace_citations_with_markers,
149    resolve_text_generator, resolve_text_verifier, structural_file_summary,
150    structural_module_summary, structural_repo_summary, structural_symbol_purpose,
151    verify_with_notes, write_references, write_section,
152};
153#[cfg(test)]
154pub(crate) use text::{frontmatter, generate_with_bounded_retry};
155pub use types::{
156    AiDepth, CodewikiAiOptions, CodewikiGraphAvailability, CodewikiGraphEdge,
157    CodewikiGraphEdgeKind, CodewikiInput, CodewikiRunSummary, LeadingChunk, PromptTier, ProseDepth,
158    ProseRegister, TextGenerator, TextVerifier,
159};
160pub(crate) use types::{
161    ArchitectureDoc, ArchitectureSubsystem, BuiltDoc, CodewikiDocMeta, CodewikiFileSnapshot,
162    CodewikiGraph, CodewikiIndexSnapshot, CodewikiMeta, CodewikiSymbolSnapshot,
163    CodewikiTruthDigest, CodewikiTruthStackEntry, CodewikiTruthSuperseded, DeprecatedSymbol,
164    DeprecationIndex, DeprecationsDoc, FeatureCatalogDoc, FileDoc, FileLink, HotspotFinding,
165    HotspotNode, HotspotsDoc, InfraSection, InfrastructureDoc, ModuleDoc, ModuleLink,
166    OnboardingDoc, OnboardingEntryPoint, OnboardingStep, SourceSpan, SymbolDoc, TestIndex,
167    VerifyNote, ranked_source_excerpts, source_excerpt_for_file,
168};
169// Feature catalog row/section types (#888) are only named by the catalog's
170// drift-guard tests; the lib builds the page through `FeatureCatalogDoc`.
171#[cfg(test)]
172pub(crate) use types::FeatureBinarySection;
173
174#[cfg(test)]
175pub(crate) use io::write_incremental_doc_set_with_snapshot;
176pub(crate) use io::{DocPruneScope, DocSink, read_ownership_meta, write_ownership_meta};
177pub use io::{write_doc_set, write_incremental_doc_set};
178#[cfg(test)]
179pub(crate) use truth_digest::TRUTH_DIGEST_META_PATH;
180pub(crate) use truth_digest::write_truth_digest;
181
182#[cfg(test)]
183mod tests;
gobby_code/commands/codewiki/mod.rs

gobby_code/commands/codewiki/
mod.rs
