/// The display text

pub text: String,

/// If Some, render as a link to this doc path (e.g., "hoverable::Numbers/struct")

#[serde(default, skip_serializing_if = "Option::is_none")]

pub link: Option<String>,

/// Create a plain text part

pub fn text(s: impl Into<String>) -> Self {

Self {

text: s.into(),

link: None,

}

}

/// Create a linked part

pub fn link(text: impl Into<String>, path: impl Into<String>) -> Self {

Self {

text: text.into(),

link: Some(path.into()),

}

}

/// Absolute file URL (file:// scheme), used to compute relative path for

/// matching against SCIP document `relative_path` fields.

pub file_url: String,

/// Start byte offset in the file text.

pub byte_start: usize,

/// End byte offset in the file text.

pub byte_end: usize,

/// Unique path identifier (e.g., "std::option::Option")

pub path: String,

/// Short name of the item

pub name: String,

/// What kind of item this is

pub kind: DocItemKind,

/// The item's visibility

pub visibility: DocVisibility,

/// Parsed documentation content

pub docs: Option<DocContent>,

/// The item's signature/definition (plain text for backward compat)

pub signature: String,

/// Rich signature with embedded links (for rendering)

#[serde(default, skip_serializing_if = "Vec::is_empty")]

pub rich_signature: RichSignature,

/// Source span of the signature (for SCIP occurrence overlay, not serialized)

#[serde(skip)]

pub signature_span: Option<SignatureSpanData>,

/// SCIP scope path for this signature (set during enrich_signatures)

#[serde(default, skip_serializing_if = "Option::is_none")]

pub sig_scope: Option<String>,

/// Generic parameters, if any

pub generics: Vec<DocGenericParam>,

/// Where clause bounds, if any

pub where_bounds: Vec<String>,

/// Child items (methods, fields, variants, etc.)

pub children: Vec<DocChild>,

/// Source location for "view source" links

pub source: Option<DocSourceLoc>,

/// Full source text of the item definition (for inline "view source")

#[serde(default, skip_serializing_if = "Option::is_none")]

pub source_text: Option<String>,

/// Trait implementations for this type (structs, enums, contracts)

#[serde(default)]

pub trait_impls: Vec<DocTraitImpl>,

/// Types that implement this trait (for trait pages)

#[serde(default, skip_serializing_if = "Vec::is_empty")]

pub implementors: Vec<DocImplementor>,

/// The implementing type name

pub type_name: String,

/// Path to the type's documentation

pub type_url: String,

/// The trait name (for linking to the impl block)

pub trait_name: String,

/// The full impl signature (plain text)

pub signature: String,

/// Rich signature with embedded links

#[serde(default, skip_serializing_if = "Vec::is_empty")]

pub rich_signature: RichSignature,

/// Source span for the full impl signature (for SCIP positional linking).

/// In-memory only; not serialized to JSON.

#[serde(skip)]

pub signature_span: Option<SignatureSpanData>,

/// SCIP scope path for this implementor signature

#[serde(default, skip_serializing_if = "Option::is_none")]

pub sig_scope: Option<String>,

/// Get the URL path for this item (includes kind suffix)

pub fn url_path(&self) -> String {

format!("{}/{}", self.path, self.kind.as_str())

}

Module,

Function,

Struct,

Enum,

Trait,

Contract,

TypeAlias,

Const,

Impl,

ImplTrait,

/// A `msg` block (desugared to module internally).

Msg,

/// A variant of a `msg` block (desugared to struct internally).

MsgVariant,

pub fn as_str(&self) -> &'static str {

match self {

DocItemKind::Module => "mod",

DocItemKind::Function => "fn",

DocItemKind::Struct => "struct",

DocItemKind::Enum => "enum",

DocItemKind::Trait => "trait",

DocItemKind::Contract => "contract",

DocItemKind::TypeAlias => "type",

DocItemKind::Const => "const",

DocItemKind::Impl => "impl",

DocItemKind::ImplTrait => "impl",

DocItemKind::Msg => "msg",

DocItemKind::MsgVariant => "msg_variant",

}

}

/// Parse kind from URL suffix string

pub fn parse(s: &str) -> Option<Self> {

match s {

"mod" | "module" => Some(DocItemKind::Module),

"fn" | "function" => Some(DocItemKind::Function),

"struct" => Some(DocItemKind::Struct),

"enum" => Some(DocItemKind::Enum),

"trait" => Some(DocItemKind::Trait),

"contract" => Some(DocItemKind::Contract),

"type" => Some(DocItemKind::TypeAlias),

"const" => Some(DocItemKind::Const),

"impl" => Some(DocItemKind::Impl),

"msg" => Some(DocItemKind::Msg),

"msg_variant" => Some(DocItemKind::MsgVariant),

_ => None,

}

}

pub fn display_name(&self) -> &'static str {

match self {

DocItemKind::Module => "Module",

DocItemKind::Function => "Function",

DocItemKind::Struct => "Struct",

DocItemKind::Enum => "Enum",

DocItemKind::Trait => "Trait",

DocItemKind::Contract => "Contract",

DocItemKind::TypeAlias => "Type Alias",

DocItemKind::Const => "Constant",

DocItemKind::Impl => "Implementation",

DocItemKind::ImplTrait => "Trait Implementation",

DocItemKind::Msg => "Message",

DocItemKind::MsgVariant => "Message Variant",

}

}

/// Plural display name for section headers

pub fn plural_name(&self) -> &'static str {

match self {

DocItemKind::Module => "Modules",

DocItemKind::Function => "Functions",

DocItemKind::Struct => "Structs",

DocItemKind::Enum => "Enums",

DocItemKind::Trait => "Traits",

DocItemKind::Contract => "Contracts",

DocItemKind::TypeAlias => "Type Aliases",

DocItemKind::Const => "Constants",

DocItemKind::Impl => "Implementations",

DocItemKind::ImplTrait => "Trait Implementations",

DocItemKind::Msg => "Messages",

DocItemKind::MsgVariant => "Message Variants",

}

}

/// Display order for sidebar grouping (lower = first)

pub fn display_order(&self) -> u8 {

match self {

DocItemKind::Module => 0,

DocItemKind::Msg => 1,

DocItemKind::Trait => 2,

DocItemKind::Contract => 3,

DocItemKind::Struct => 4,

DocItemKind::Enum => 5,

DocItemKind::TypeAlias => 6,

DocItemKind::Function => 7,

DocItemKind::Const => 8,

DocItemKind::Impl => 9,

DocItemKind::ImplTrait => 10,

DocItemKind::MsgVariant => 11,

}

}

/// The main summary (first paragraph)

pub summary: String,

/// Full documentation body (markdown)

pub body: String,

/// Extracted sections like # Examples, # Panics, etc.

pub sections: Vec<DocSection>,

pub fn from_raw(raw: &str) -> Self {

let trimmed = raw.trim();

// Split into summary (first paragraph) and body

let (summary, body) = if let Some(idx) = trimmed.find("\n\n") {

(trimmed[..idx].to_string(), trimmed.to_string())

} else {

(trimmed.to_string(), trimmed.to_string())

};

// Extract known sections

let sections = Self::extract_sections(trimmed);

DocContent {

summary,

body,

sections,

}

}

fn extract_sections(text: &str) -> Vec<DocSection> {

let mut sections = Vec::new();

let mut current_section: Option<(String, String)> = None;

for line in text.lines() {

if let Some(header) = line.strip_prefix("# ") {

// Save previous section if any

if let Some((name, content)) = current_section.take() {

sections.push(DocSection {

name,

content: content.trim().to_string(),

});

}

// Start new section

let name = header.trim().to_string();

current_section = Some((name, String::new()));

} else if let Some((_, ref mut content)) = current_section {

content.push_str(line);

content.push('\n');

}

}

// Save final section

if let Some((name, content)) = current_section {

sections.push(DocSection {

name,

content: content.trim().to_string(),

});

}

sections

}

pub name: String,

pub bounds: Vec<String>,

pub default: Option<String>,

pub kind: DocChildKind,

pub name: String,

pub docs: Option<DocContent>,

pub signature: String,

/// Rich signature with embedded links

#[serde(default, skip_serializing_if = "Vec::is_empty")]

pub rich_signature: RichSignature,

/// Source span of the signature (for SCIP occurrence overlay, not serialized)

#[serde(skip)]

pub signature_span: Option<SignatureSpanData>,

/// SCIP scope path for this signature

#[serde(default, skip_serializing_if = "Option::is_none")]

pub sig_scope: Option<String>,

pub visibility: DocVisibility,

Field,

Variant,

Method,

AssocType,

AssocConst,

/// A contract `init(...)` block.

Init,

/// A single arm of a contract `recv Msg { Variant ... }` block.

RecvHandler,

pub fn display_name(&self) -> &'static str {

match self {

DocChildKind::Field => "Field",

DocChildKind::Variant => "Variant",

DocChildKind::Method => "Method",

DocChildKind::AssocType => "Associated Type",

DocChildKind::AssocConst => "Associated Constant",

DocChildKind::Init => "Initializer",

DocChildKind::RecvHandler => "Handler",

}

}

/// Plural display name for section headers

pub fn plural_name(&self) -> &'static str {

match self {

DocChildKind::Field => "Fields",

DocChildKind::Variant => "Variants",

DocChildKind::Method => "Methods",

DocChildKind::AssocType => "Associated Types",

DocChildKind::AssocConst => "Associated Constants",

DocChildKind::Init => "Initializer",

DocChildKind::RecvHandler => "Message Handlers",

}

}

/// Display order for grouping (lower = first)

pub fn display_order(&self) -> u8 {

match self {

DocChildKind::Variant => 0,

DocChildKind::Field => 1,

DocChildKind::Init => 2,

DocChildKind::RecvHandler => 3,

DocChildKind::AssocType => 4,

DocChildKind::AssocConst => 5,

DocChildKind::Method => 6,

}

}

/// Anchor prefix for linking (rustdoc-style)

pub fn anchor_prefix(&self) -> &'static str {

match self {

DocChildKind::Field => "field",

DocChildKind::Variant => "variant",

DocChildKind::Method => "tymethod",

DocChildKind::AssocType => "associatedtype",

DocChildKind::AssocConst => "associatedconstant",

DocChildKind::Init => "init",

DocChildKind::RecvHandler => "handler",

}

}

/// Absolute file path — used only in-memory by LSP for "goto source".

/// Never serialized to JSON (avoids leaking machine paths into static output).

#[serde(skip)]

pub file: String,

/// Relative display path (shown in UI)

pub display_file: String,

pub line: u32,

pub column: u32,

/// The name of the trait being implemented (e.g., "Clone"). Empty for inherent impls.

pub trait_name: String,

/// URL path to the impl item's documentation

pub impl_url: String,

/// The full signature of the impl (e.g., "impl Clone for MyStruct")

pub signature: String,

/// Rich signature with embedded links

#[serde(default, skip_serializing_if = "Vec::is_empty")]

pub rich_signature: RichSignature,

/// Source span of the signature (for SCIP occurrence overlay, not serialized)

#[serde(skip)]

pub signature_span: Option<SignatureSpanData>,

/// SCIP scope path for this impl signature

#[serde(default, skip_serializing_if = "Option::is_none")]

pub sig_scope: Option<String>,

/// Methods defined in this impl block (displayed inline on type pages)

#[serde(default)]

pub methods: Vec<DocImplMethod>,

/// Method name

pub name: String,

/// Method signature (e.g., "pub fn foo(&self) -> u32")

pub signature: String,

/// Rich signature with embedded links

#[serde(default, skip_serializing_if = "Vec::is_empty")]

pub rich_signature: RichSignature,

/// Source span of the signature (for SCIP occurrence overlay, not serialized)

#[serde(skip)]

pub signature_span: Option<SignatureSpanData>,

/// SCIP scope path for this method signature

#[serde(default, skip_serializing_if = "Option::is_none")]

pub sig_scope: Option<String>,

/// Parsed documentation content

pub docs: Option<DocContent>,

/// All documented items, keyed by path

pub items: Vec<DocItem>,

/// Module hierarchy for navigation

pub modules: Vec<DocModuleTree>,

/// Builtin library modules (core, std), rendered separately in sidebar

#[serde(default, skip_serializing_if = "Vec::is_empty")]

pub builtin_modules: Vec<DocModuleTree>,

pub fn new() -> Self {

Self::default()

}

pub fn add_item(&mut self, item: DocItem) {

self.items.push(item);

}

/// Find an item by its path (without kind suffix)

pub fn find_by_path(&self, path: &str) -> Option<&DocItem> {

self.items.iter().find(|item| item.path == path)

}

/// Find an item by path and kind

pub fn find_by_path_and_kind(&self, path: &str, kind: DocItemKind) -> Option<&DocItem> {

self.items

.iter()

.find(|item| item.path == path && item.kind == kind)

}

/// Parse a URL path (potentially with kind suffix) and find the item.

/// URL format: "path::to::item" or "path::to::item/kind"

/// Returns the item if found, handling both formats.

pub fn find_by_url(&self, url_path: &str) -> Option<&DocItem> {

// Try to parse kind suffix (e.g., "lib::foo/fn" -> path="lib::foo", kind="fn")

if let Some((path, kind_str)) = url_path.rsplit_once('/')

&& let Some(kind) = DocItemKind::parse(kind_str)

{

// URL has valid kind suffix - find by path and kind

return self.find_by_path_and_kind(path, kind);

}

// No valid kind suffix - find by path alone (may be ambiguous)

self.find_by_path(url_path)

}

/// Find all items with a given path (for disambiguation)

pub fn find_all_by_path(&self, path: &str) -> Vec<&DocItem> {

self.items.iter().filter(|item| item.path == path).collect()

}

/// Build a searchable index of items

pub fn search(&self, query: &str) -> Vec<&DocItem> {

let query_lower = query.to_lowercase();

self.items

.iter()

.filter(|item| {

item.name.to_lowercase().contains(&query_lower)

|| item.path.to_lowercase().contains(&query_lower)

})

.collect()

}

/// Link trait implementations to their target types and implementors to traits.

/// `links` is a list of (target_type_path, DocTraitImpl) pairs extracted

/// from the HIR using semantic helpers.

pub fn link_trait_impls(&mut self, links: Vec<(String, DocTraitImpl)>) {

// Build lookup maps keyed by full path to avoid collisions between

// same-named types in different modules (e.g. a::Foo vs b::Foo).

// Maps own their strings so we can mutably borrow self.items later.

let type_items: std::collections::HashMap<String, (String, DocItemKind)> = self

.items

.iter()

.filter(|item| {

matches!(

item.kind,

DocItemKind::Struct | DocItemKind::Enum | DocItemKind::Contract

)

})

.map(|item| (item.path.clone(), (item.path.clone(), item.kind)))

.collect();

let trait_items: std::collections::HashMap<String, String> = self

.items

.iter()

.filter(|item| item.kind == DocItemKind::Trait)

.map(|item| (item.path.clone(), item.path.clone()))

.collect();

/// Look up a type by path: try exact path first, then fall back to

/// simple-name scan (for unqualified paths from older extractors).

fn lookup_type(

map: &std::collections::HashMap<String, (String, DocItemKind)>,

target: &str,

) -> Option<(String, String)> {

if let Some((path, kind)) = map.get(target) {

return Some((path.clone(), kind.as_str().to_string()));

}

// Simple-name fallback when target has no `::`

if !target.contains("::") {

for (path, kind) in map.values() {

let simple = extract_simple_type_name(path);

if simple == target {

return Some((path.clone(), kind.as_str().to_string()));

}

}

}

None

}

/// Look up a trait by path: try exact path first, then simple-name scan.

fn lookup_trait(

map: &std::collections::HashMap<String, String>,

target: &str,

) -> Option<String> {

if let Some(path) = map.get(target) {

return Some(path.clone());

}

if !target.contains("::") {

for path in map.values() {

let simple = extract_simple_type_name(path);

if simple == target {

return Some(path.clone());

}

}

}

None

}

// First pass: collect implementors for each trait (keyed by trait path)

let mut trait_implementors: std::collections::HashMap<String, Vec<DocImplementor>> =

std::collections::HashMap::new();

for (target_type, trait_impl) in &links {

// Skip inherent impls (empty trait_name)

if trait_impl.trait_name.is_empty() {

continue;

}

let trait_simple_name = extract_simple_type_name(&trait_impl.trait_name);

let type_simple_name = extract_simple_type_name(target_type);

// Look up the actual type item to get the correct path and kind

let (type_path, type_kind_suffix) =

if let Some((path, kind)) = lookup_type(&type_items, target_type) {

(path, kind)

} else {

// Fallback to the target_type path with struct suffix

(target_type.clone(), "struct".to_string())

};

// Look up the actual trait to get the correct path

let trait_path = lookup_trait(&trait_items, &trait_impl.trait_name)

.unwrap_or_else(|| trait_impl.trait_name.clone());

// Build rich signature: "impl Trait for Type"

let rich_signature = vec![

SignaturePart::text("impl "),

SignaturePart::link(&trait_simple_name, format!("{}/trait", trait_path)),

SignaturePart::text(" for "),

SignaturePart::link(

&type_simple_name,

format!("{}/{}", type_path, type_kind_suffix),

),

];

// Create implementor entry with correct URL and rich signature

let implementor = DocImplementor {

type_name: type_simple_name.clone(),

type_url: format!("{}/{}", type_path, type_kind_suffix),

trait_name: trait_simple_name.clone(),

signature: trait_impl.signature.clone(),

rich_signature,

signature_span: trait_impl.signature_span.clone(),

sig_scope: None,

};

// Key by trait path (not simple name) to avoid cross-module collisions

let trait_key = trait_path.to_string();

trait_implementors

.entry(trait_key)

.or_default()

.push(implementor);

}

// Second pass: link trait impls to types and implementors to traits

for (target_type, mut trait_impl) in links {

let target_simple_name = extract_simple_type_name(&target_type);

let trait_simple_name = extract_simple_type_name(&trait_impl.trait_name);

for item in &mut self.items {

// Link trait impls to types (structs, enums, contracts)

let is_type = matches!(

item.kind,

DocItemKind::Struct | DocItemKind::Enum | DocItemKind::Contract

);

if is_type {

// Prefer exact canonical path match; only fall back to

// simple-name matching when the caller didn't provide a

// fully qualified path (e.g. from older extractors).

let matches = item.path == target_type

|| (!target_type.contains("::")

&& (item.name == target_simple_name

|| item.path.ends_with(&format!("::{}", target_simple_name))));

if matches {

// Build rich signature for this trait impl if it's a trait impl (not inherent)

if !trait_impl.trait_name.is_empty() && trait_impl.rich_signature.is_empty()

{

// Look up the trait URL

let trait_url = lookup_trait(&trait_items, &trait_impl.trait_name)

.map(|p| format!("{}/trait", p))

.unwrap_or_else(|| format!("{}/trait", trait_impl.trait_name));

// Use the target item's path and kind for the type URL

let type_url = format!("{}/{}", item.path, item.kind.as_str());

trait_impl.rich_signature = vec![

SignaturePart::text("impl "),

SignaturePart::link(&trait_simple_name, trait_url),

SignaturePart::text(" for "),

SignaturePart::link(&target_simple_name, type_url),

];

}

item.trait_impls.push(trait_impl.clone());

}

}

// Link implementors to traits

if item.kind == DocItemKind::Trait && !trait_impl.trait_name.is_empty() {

let trait_matches = item.path == trait_impl.trait_name

|| item.name == trait_simple_name

|| item.path.ends_with(&format!("::{}", trait_simple_name));

// Look up by item's full path first, then by simple name

let impls = trait_implementors

.get(item.path.as_str())

.or_else(|| trait_implementors.get(&trait_simple_name));

if trait_matches && let Some(impls) = impls {

// Only add if not already present (dedup by type_url, not name)

for imp in impls {

if !item.implementors.iter().any(|i| i.type_url == imp.type_url) {

item.implementors.push(imp.clone());

}

}

}

}

}

}

}

let without_generics = type_str.split('<').next().unwrap_or(type_str);

without_generics

.rsplit("::")

.next()

.unwrap_or(without_generics)

.trim()

.to_string()

pub name: String,

pub path: String,

pub children: Vec<DocModuleTree>,

/// Direct items in this module (non-module children)

pub items: Vec<DocModuleItem>,

/// Get the URL path for this module (includes kind suffix)

pub fn url_path(&self) -> String {

format!("{}/mod", self.path)

}

pub name: String,

pub path: String,

pub kind: DocItemKind,

/// Brief summary (first sentence of docs)

#[serde(default, skip_serializing_if = "Option::is_none")]

pub summary: Option<String>,

/// Get the URL path for this item (includes kind suffix)

pub fn url_path(&self) -> String {

format!("{}/{}", self.path, self.kind.as_str())

}

use super::*;

fn sample_index() -> DocIndex {

let mut index = DocIndex::new();

index.add_item(DocItem {

path: "mylib::Point".into(),

name: "Point".into(),

kind: DocItemKind::Struct,

visibility: DocVisibility::Public,

docs: Some(DocContent::from_raw("A 2D point.\n\nUsed for coordinates.")),

signature: "pub struct Point".into(),

rich_signature: vec![],

signature_span: None,

sig_scope: None,

generics: vec![DocGenericParam {

name: "T".into(),

bounds: vec![],

default: None,

}],

where_bounds: vec![],

children: vec![DocChild {

kind: DocChildKind::Field,

name: "x".into(),

docs: Some(DocContent::from_raw("The x coordinate")),

signature: "x: u256".into(),

rich_signature: vec![],

signature_span: None,

sig_scope: None,

visibility: DocVisibility::Public,

}],

source: Some(DocSourceLoc {

file: "/src/lib.fe".into(),

display_file: "lib.fe".into(),

line: 1,

column: 0,

}),

source_text: None,

trait_impls: vec![],

implementors: vec![],

});

index.add_item(DocItem {

path: "mylib::Color".into(),

name: "Color".into(),

kind: DocItemKind::Enum,

visibility: DocVisibility::Public,

docs: None,

signature: "pub enum Color".into(),

rich_signature: vec![],

signature_span: None,

sig_scope: None,

generics: vec![],

where_bounds: vec![],

children: vec![

DocChild {

kind: DocChildKind::Variant,

name: "Red".into(),

docs: None,

signature: "Red".into(),