Module generate:model

Summary

generate:model 模块定义了文档生成管线中的核心数据模型和公共操作。它负责描述页面类型、页面计划、页面身份、符号分析结果（函数、类型、变量分析）以及链接解析器、生成摘要、错误状态等关键实体。该模块公开了用于分类页面和提示类型的枚举（PageType、PromptKind），并提供了一系列查询和转换函数，例如判断符号种类、查找特定符号的分析、生成 Markdown 摘要内容、解析符号目标键、计算页面路径和构建跨文档链接解析器。这些接口共同构成了生成步骤中所有主要数据结构和逻辑的集中出入口，确保后续渲染和输出环节能够依赖一组稳定、自包含的模型定义。

Imports

• extract
• std
• support

Imported By

• generate:analysis
• generate:common
• generate:diagram
• generate:dryrun
• generate:evidence
• generate:evidence_builder
• generate:page
• generate:planner
• generate:scheduler
• generate:symbol

Types

clore::generate::FunctionAnalysis

Declaration: generate/model.cppm:81

Definition: generate/model.cppm:81

Declaration: Namespace clore::generate

结构体 clore::generate::FunctionAnalysis 将函数分析结果组织为两类数据：直接可展示的 Markdown 文本（overview_markdown 和 details_markdown）以及结构化的副作用与访问信息。has_side_effects 默认初始化为 false，与 side_effects 列表的空状态保持一致，形成一个隐式不变量：当该标志为 false 时，side_effects 应为空列表。reads_from 和 writes_to 分别记录函数读取和写入的实体，与 side_effects 共同描述函数的对外影响，但关注点不同——前者侧重数据流方向，后者侧重可观察行为的变更。usage_patterns 则独立存储函数的使用模式描述（如“参数替换”或“条件分支”），用于生成指导性文档。所有列表字段均采用 std::vector<std::string>，便于直接拼接或迭代。

Invariants

• has_side_effects should be true if and only if side_effects is non-empty; no explicit enforcement is shown
• Fields are independent but intended to be consistent with analysis data

Key Members

• overview_markdown
• details_markdown
• has_side_effects
• side_effects
• reads_from
• writes_to
• usage_patterns

Usage Patterns

• Cached and reused across namespace, module, file, and symbol documentation pages
• Populated by analysis code and consumed by documentation generation

clore::generate::GenerateError

Declaration: generate/model.cppm:69

Definition: generate/model.cppm:69

Declaration: Namespace clore::generate

The struct clore::generate::GenerateError is implemented as a trivial data type that contains a single public member message of type std::string. No custom constructors, destructors, assignment operators, or other member functions are defined, so the compiler generates the default special member functions. This minimal internal structure imposes no invariants beyond those inherent to std::string itself; the struct serves purely as a lightweight wrapper for holding a human‑readable error description without any additional logic or constraints.

Invariants

• no explicit invariants defined in evidence

Key Members

• message

Usage Patterns

• likely used as an exception type or error result in generation functions
• typically constructed with a descriptive string

clore::generate::GeneratedPage

Declaration: generate/model.cppm:55

Definition: generate/model.cppm:55

Declaration: Namespace clore::generate

clore::generate::GeneratedPage 是一个仅含三个 std::string 成员（title、relative_path、content）的聚合体，没有自定义构造函数或虚函数。所有成员均通过默认初始化被置为空字符串，因此该结构本身不维护任何运行时不变量；其语义完全由调用方通过赋值来保证。

在实现内部，GeneratedPage 充当生成流程中各阶段的轻量数据传输对象，将页面的标题、相对路径和原始内容捆绑在一起。由于不提供访问控制或成员函数，对该结构的使用完全依赖于对其字段的直接读写，这使其易于构建和传递，同时也将数据完整性责任交予使用者。

Invariants

• 所有字段默认初始化为空字符串
• 字段内容由外部填充，无内部一致性约束

Key Members

• title 字段：页面标题
• relative_path 字段：页面相对路径
• content 字段：页面内容

Usage Patterns

• 作为生成流程的输出数据单元
• 被其他模块填充后传递或存储
• 直接访问其字段以获取页面信息

clore::generate::GenerationSummary

Declaration: generate/model.cppm:61

Definition: generate/model.cppm:61

Declaration: Namespace clore::generate

clore::generate::GenerationSummary 是一个聚合类型，内部包含五个 std::size_t 计数器，所有字段均初始化为零。这些计数器分别记录生成过程中的关键指标：written_output_count 跟踪实际写入的输出文件数量；symbol_analysis_cache_hits 与 symbol_analysis_cache_misses 统计符号分析缓存的命中与未命中次数；page_prompt_cache_hits 与 page_prompt_cache_misses 统计页面提示缓存的命中与未命中次数。由于该结构体不定义任何成员函数，其不变量完全由外部使用方式保证：每个计数器应为非负值（由无符号类型天然保证），且在生成过程的累积阶段只能单调递增。所有字段的零初始化确保了任何 GenerationSummary 实例在累加操作开始前都处于一个干净、可预测的初始状态。

Invariants

• 每个计数器都是从 0 开始，只能递增
• 所有计数器均为非负整数

Key Members

• written_output_count
• symbol_analysis_cache_hits
• symbol_analysis_cache_misses
• page_prompt_cache_hits
• page_prompt_cache_misses

Usage Patterns

• 在代码生成过程中递增相应计数器
• 用于后续性能分析或调试日志
• 作为生成结果的元数据返回

clore::generate::LinkResolver

Declaration: generate/model.cppm:174

Definition: generate/model.cppm:174

Declaration: Namespace clore::generate

clore::generate::LinkResolver 内部维护四个 std::unordered_map 作为核心存储：name_to_path 对应实体名称到页面路径，namespace_to_path 对应命名空间名称到路径，module_to_path 对应模块名称到路径，page_id_to_title 对应页面 ID 到标题字符串。这些映射在构造时由外部填充，并在整个对象生命周期内保持只读状态。

所有查找方法（resolve、resolve_namespace、resolve_module、resolve_page_title）均以 const 成员函数形式提供，每个方法均通过 find 在对应的映射中搜索，若找到则返回指向值的 const std::string*，否则返回 nullptr。这一设计保证了查询操作无副作用，同时通过指针而非引用来区分成功与缺失的情况。映射内容一旦填充后不再更改，因此整个结构在查询阶段满足无修改不变性。

Invariants

• Maps are populated before resolution and remain read-only during use
• Each key maps to at most one value
• A null pointer indicates an unresolvable name

Key Members

• name_to_path
• namespace_to_path
• module_to_path
• page_id_to_title
• resolve
• resolve_namespace
• resolve_module
• resolve_page_title

Usage Patterns

• Used by link generation to find relative paths for entity references
• Called during markdown output to construct cross-references
• Provides separate maps for different name categories

Member Functions

clore::generate::LinkResolver::resolve

Declaration: generate/model.cppm:180

Definition: generate/model.cppm:180

Declaration: Namespace clore::generate

Implementation

[[nodiscard]] auto resolve(const std::string& name) const -> const std::string* {
        auto it = name_to_path.find(name);
        return it != name_to_path.end() ? &it->second : nullptr;
    }

clore::generate::LinkResolver::resolve_module

Declaration: generate/model.cppm:190

Definition: generate/model.cppm:190

Declaration: Namespace clore::generate

Implementation

[[nodiscard]] auto resolve_module(const std::string& name) const -> const std::string* {
        auto it = module_to_path.find(name);
        return it != module_to_path.end() ? &it->second : nullptr;
    }

clore::generate::LinkResolver::resolve_namespace

Declaration: generate/model.cppm:185

Definition: generate/model.cppm:185

Declaration: Namespace clore::generate

Implementation

[[nodiscard]] auto resolve_namespace(const std::string& name) const -> const std::string* {
        auto it = namespace_to_path.find(name);
        return it != namespace_to_path.end() ? &it->second : nullptr;
    }

clore::generate::LinkResolver::resolve_page_title

Declaration: generate/model.cppm:195

Definition: generate/model.cppm:195

Declaration: Namespace clore::generate

Implementation

[[nodiscard]] auto resolve_page_title(const std::string& page_id) const -> const std::string* {
        auto it = page_id_to_title.find(page_id);
        return it != page_id_to_title.end() ? &it->second : nullptr;
    }

clore::generate::MarkdownFragmentResponse

Declaration: generate/model.cppm:77

Definition: generate/model.cppm:77

Declaration: Namespace clore::generate

clore::generate::MarkdownFragmentResponse 是一个聚合体，内部仅包含一个 std::string 类型的成员 markdown。该结构体没有自定义构造函数、析构函数或赋值运算符，完全依赖编译器提供的默认实现，因此其对象可以简单进行值语义的复制和移动。markdown 成员是存储响应文本的唯一数据载体，该结构体的不变性要求在于该字符串必须始终代表有效的 Markdown 内容，但这一约束由使用者保证，结构体本身不施加任何运行时检查或处理逻辑。

clore::generate::PageIdentity

Declaration: generate/model.cppm:207

Definition: generate/model.cppm:207

Declaration: Namespace clore::generate

clore::generate::PageIdentity 是一个纯数据聚合体，用于唯一标识一个待生成的文档页面。其内部由四个字段构成：page_type（枚举类型 PageType，默认值为 File）、normalized_owner_key、qualified_name 和 source_relative_path（均为 std::string），没有任何自定义构造函数或成员函数。

该结构体的核心不变量在于各字段的语义组合：qualified_name 给出页面的完全限定名称（例如模块中的路径），source_relative_path 记录源文件相对于项目根目录的位置，而 normalized_owner_key 则用于关联页面的逻辑所有者（如模块或命名空间）。page_type 控制这些字符串应如何被消费（例如 File 类型表示直接映射为输出文件，其他类型可能影响路径或标题的生成）。所有字符串均保持为空状态，直到在后续阶段中被显式赋值，从而允许 PageIdentity 先作为轻量占位符传递。

Invariants

• Fields are default-initialized
• No constraints on string contents

Key Members

• page_type
• normalized_owner_key
• qualified_name
• source_relative_path

Usage Patterns

• Carried as part of page generation metadata
• Used to uniquely identify a page within the generation system

clore::generate::PagePlan

Declaration: generate/model.cppm:39

Definition: generate/model.cppm:39

Declaration: Namespace clore::generate

clore::generate::PagePlan 是一个聚合体，其字段共同描述了一个待生成页面的计划。核心标识符 page_id 用于唯一标识该页面；page_type 指定页面的生成类型（默认为 PageType::File）；title 和 relative_path 分别提供显示名称和文件路径。页面间的依赖与关联通过 depends_on_pages 和 linked_pages 两个向量表达，前者记录生成前必须就绪的页面 ID，后者记录有向链接关系。owner_keys 标识负责该页面的所有权键，而 prompt_requests 则存储用于生成页面内容所需的提示请求序列。

结构的关键不变量在于各向量之间的语义一致性：凡出现在 depends_on_pages 或 linked_pages 中的 ID 必须在全局页面计划中可解析，且 prompt_requests 的顺序与 page_type 所隐含的生成流程相匹配。虽然 PagePlan 本身不提供验证方法，但其他生成逻辑假定这些字段的填充准确反映了页面间的有向无环图结构，以确保生成顺序正确且无循环依赖。

Invariants

• page_id 通常应唯一标识页面（默认空串可能非唯一）
• depends_on_pages 列表中的页面ID应存在且无循环依赖

Key Members

• page_id
• page_type
• title
• relative_path
• owner_keys
• depends_on_pages
• linked_pages
• prompt_requests

Usage Patterns

• 生成管线填充 PagePlan 并传递给页面生成器
• 依赖图分析读取 depends_on_pages 确定构建顺序
• 外部工具根据 page_type 和 prompt_requests 生成内容

clore::generate::PagePlanSet

Declaration: generate/model.cppm:50

Definition: generate/model.cppm:50

Declaration: Namespace clore::generate

结构体 PagePlanSet 使用两个分离的内部向量来管理计划集合及其生成顺序。plans 持有实际的 PagePlan 实例，而 generation_order 存储代表计划标识符或文件路径的字符串列表。两者之间通过索引位置隐式关联：generation_order 中第 i 个条目通常对应于 plans 中第 i 个计划在生成流程中的输出顺序或优先级。成员 generation_order 的设计意图在于将语义顺序从数据结构中解耦，允许在保持顺序逻辑不变的前提下独立更新计划内容，但结构体本身并不强制要求两个向量长度一致或索引始终匹配——这种一致性由外部调用方保证是其关键的不变量。plans 的默认空初始化确保结构体可被安全默认构造。

Invariants

• The size of generation_order is equal to the size of plans if each plan has a unique identifier.
• Each string in generation_order corresponds to a key or identifier for an element in plans.

Key Members

• plans
• generation_order

Usage Patterns

• Populated during generation setup with plan data and ordering information.
• Iterated over in generation algorithms using the generation_order to determine processing sequence.
• Accessed to retrieve specific plans by their order or identifier.

clore::generate::PageType

Declaration: generate/model.cppm:9

Definition: generate/model.cppm:9

Declaration: Namespace clore::generate

内部实现上，clore::generate::PageType 是一个作用域枚举，底层类型固定为 std::uint8_t，共定义 Index、Module、Namespace、File 四个枚举值。这些值的声明顺序（Index → Module → Namespace → File）在代码库中作为默认的排序依据，用于生成阶段的页面分类和分发。该枚举不涉及自定义运算符或额外的不变量，其所有合法值均包含在此有限集合中，由代码生成器内部逻辑直接使用以选择对应的页面构建路径。

Invariants

• 底层类型为 std::uint8_t，所有枚举值在 0 到 3 之间

Key Members

• File
• Namespace
• Index
• Module

Usage Patterns

• 用于指定生成的文档页面的种类
• 可能作为 Page 类或生成函数的参数或数据成员

Member Variables

clore::generate::PageType::File

Declaration: generate/model.cppm:13

Declaration: Namespace clore::generate

Implementation

File

clore::generate::PageType::Index

Declaration: generate/model.cppm:10

Declaration: Namespace clore::generate

Implementation

Index

clore::generate::PageType::Module

Declaration: generate/model.cppm:11

Declaration: Namespace clore::generate

Implementation

Module

clore::generate::PageType::Namespace

Declaration: generate/model.cppm:12

Declaration: Namespace clore::generate

Implementation

Namespace

clore::generate::PathError

Declaration: generate/model.cppm:203

Definition: generate/model.cppm:203

Declaration: Namespace clore::generate

clore::generate::PathError 是一个轻量的值类型，仅包含一个 std::string message 成员。其内部布局与标准字符串相同，不定义任何自定义构造函数、析构函数或赋值运算符，因此为平凡可复制的聚合类型。该结构的不变量在于 message 始终应包含一条可打印的、描述具体路径错误的文本；任何非法或空的状态均视为违反预期用途，但实现层不做运行时检查。

Invariants

• message 成员的值为任意可读字符串，无格式约束

Key Members

• clore::generate::PathError::message

Usage Patterns

• 作为路径生成失败时的返回类型或异常包装

clore::generate::PromptKind

Declaration: generate/model.cppm:18

Definition: generate/model.cppm:18

Declaration: Namespace clore::generate

枚举clore::generate::PromptKind定义在模块generate/model.cppm中，底层类型为std::uint8_t，提供紧凑的内存储存。其成员（如VariableAnalysis、FunctionImplementationSummary等）隐式映射从0开始的整数值，用于在生成器实现中区分不同的prompt种类。内部设计中，该枚举主要用于switch或if-else分支，以调度对应的prompt构造逻辑；成员之间的顺序可能与处理优先级或代码生成流程相关，但无显式约束。枚举的底层类型保证了枚举值可作为小范围索引或位标志的基础，从而优化运行时路径选择。

Invariants

• All enumerators are distinct and each represents a specific prompt category.
• The underlying type is std::uint8_t, ensuring compact storage.

Key Members

• NamespaceSummary
• ModuleSummary
• ModuleArchitecture
• IndexOverview
• FunctionAnalysis
• TypeAnalysis
• VariableAnalysis
• FunctionDeclarationSummary
• FunctionImplementationSummary
• TypeDeclarationSummary
• TypeImplementationSummary

Usage Patterns

• Used to select or dispatch prompt generation logic based on the kind of code element.

Member Variables

clore::generate::PromptKind::FunctionAnalysis

Declaration: generate/model.cppm:23

Declaration: Namespace clore::generate

Implementation

FunctionAnalysis

clore::generate::PromptKind::FunctionDeclarationSummary

Declaration: generate/model.cppm:26

Declaration: Namespace clore::generate

Implementation

FunctionDeclarationSummary

clore::generate::PromptKind::FunctionImplementationSummary

Declaration: generate/model.cppm:27

Declaration: Namespace clore::generate

Implementation

FunctionImplementationSummary

clore::generate::PromptKind::IndexOverview

Declaration: generate/model.cppm:22

Declaration: Namespace clore::generate

Implementation

IndexOverview

clore::generate::PromptKind::ModuleArchitecture

Declaration: generate/model.cppm:21

Declaration: Namespace clore::generate

Implementation

ModuleArchitecture

clore::generate::PromptKind::ModuleSummary

Declaration: generate/model.cppm:20

Declaration: Namespace clore::generate

Implementation

ModuleSummary

clore::generate::PromptKind::NamespaceSummary

Declaration: generate/model.cppm:19

Declaration: Namespace clore::generate

Implementation

NamespaceSummary

clore::generate::PromptKind::TypeAnalysis

Declaration: generate/model.cppm:24

Declaration: Namespace clore::generate

Implementation

TypeAnalysis

clore::generate::PromptKind::TypeDeclarationSummary

Declaration: generate/model.cppm:28

Declaration: Namespace clore::generate

Implementation

TypeDeclarationSummary

clore::generate::PromptKind::TypeImplementationSummary

Declaration: generate/model.cppm:29

Declaration: Namespace clore::generate

Implementation

TypeImplementationSummary

clore::generate::PromptKind::VariableAnalysis

Declaration: generate/model.cppm:25

Declaration: Namespace clore::generate

Implementation

VariableAnalysis

clore::generate::PromptRequest

Declaration: generate/model.cppm:34

Definition: generate/model.cppm:34

Declaration: Namespace clore::generate

clore::generate::PromptRequest 是一个轻量级的数据聚合体，用于封装提示生成请求的内部表示。其两个成员 kind（类型为 PromptKind，默认初始化为 PromptKind::NamespaceSummary）和 target_key（类型为 std::string，默认为空字符串）共同定义了请求的类型与目标实体标识。结构体本身不维护显式的不变量——成员均为独立可变的公共字段，其语义正确性由调用方确保。该类型作为生成流程中的数据传输对象，在模块间传递时仅提供简单的复制语义，没有自定义构造函数、赋值运算符或析构函数，因此其生命周期完全由默认的成员初始化与值语义管理。

Invariants

• kind 总是有效的 PromptKind 值
• target_key 可为空但非空字符串表示有效目标

Key Members

• kind 成员
• target_key 成员

Usage Patterns

• 通过值传递用于生成请求
• 在生成器内部解析 kind 和 target_key
• 默认构造为 NamespaceSummary 和空键

clore::generate::RenderError

Declaration: generate/model.cppm:73

Definition: generate/model.cppm:73

Declaration: Namespace clore::generate

结构体 clore::generate::RenderError 的核心实现是一个包装了 std::string 的简单类。其唯一数据成员 message 以字符串形式存储错误描述，不施加任何内容约束——字符串可以为空或任意文本。由于没有用户声明的构造函数、析构函数或赋值运算符，编译器会隐式生成默认成员函数（默认构造、拷贝构造、移动构造、拷贝赋值、移动赋值、析构），使得该类型是平凡可复制的、可移动的，且支持值语义。不变量仅包括 message 自身的不变性（例如内部指针有效、长度一致），该不变量由 std::string 保证，而 RenderError 本身不引入额外的逻辑约束。

Invariants

• message may contain any string value

Key Members

• std::string message

Usage Patterns

• Returned by rendering functions to report errors
• Inspected by callers to obtain error details

clore::generate::SymbolAnalysisStore

Declaration: generate/model.cppm:125

Definition: generate/model.cppm:125

Declaration: Namespace clore::generate

clore::generate::SymbolAnalysisStore 是一个简单的聚合结构体，其内部仅包含三个缓存字段：FunctionAnalysisCache functions 用于存储函数分析结果，TypeAnalysisCache types 用于存储类型分析结果，VariableAnalysisCache variables 用于存储变量分析结果。这三个字段共同构成完整的符号分析存储，彼此之间没有强依赖关系，但共同记录了代码库中所有符号的静态分析数据。在实现中，该结构体通常作为分析过程中的累积器被使用，其关键不变性在于每个字段的缓存必须与其对应的符号种类保持一致，且各字段的更新不相互干扰。

Invariants

• The fields are initialized by default constructors of respective cache types
• All fields are public and can be accessed directly

Key Members

• functions
• types
• variables

Usage Patterns

• Used as a member in other structures or passed to analysis functions
• Accessed to retrieve or update analysis results for symbols

clore::generate::SymbolTargetKeyView

Declaration: generate/model.cppm:136

Definition: generate/model.cppm:136

Declaration: Namespace clore::generate

struct clore::generate::SymbolTargetKeyView 是一个纯粹的聚合体，仅由两个 std::string_view 成员 qualified_name 和 signature 组成。其核心不变性在于这两个字符串视图必须始终指向有效且稳定的字符序列（例如，由调用方管理的字符串缓冲区或静态数据），因为视图本身不拥有数据。该结构设计为轻量级“键视图”，用于在无需复制或分配内存的前提下传递或比较符号目标的完整标识信息。

该类型的实现极为简单，所有成员均为公开访问且可直接使用。关键约束在于：在 SymbolTargetKeyView 对象的使用生命周期内，底层字符串的存储必须保持有效；违反该约束将导致悬浮引用。此外，由于两个 std::string_view 成员保持默认的顺序和填充，该类型的布局与占用尺寸完全由两个指针加两个长度组成（取决于平台）。

Invariants

• qualified_name and signature are non-owning string views
• qualified_name and signature must reference valid null-terminated strings for the lifetime of the view

Key Members

• qualified_name
• signature

Usage Patterns

• Used as a lightweight key to identify symbol targets
• Passed to functions that need to reference a symbol's identity without copying strings

clore::generate::TypeAnalysis

Declaration: generate/model.cppm:91

Definition: generate/model.cppm:91

Declaration: Namespace clore::generate

结构体 clore::generate::TypeAnalysis 将类型分析的输出分解为五个字段：overview_markdown 和 details_markdown 分别存储概要性与详细性文字描述，invariants、key_members 和 usage_patterns 则以字符串向量的形式记录类型不变量、关键成员和常见用法模式。各字段之间没有显式的运行时依赖性，但设计上期望 overview_markdown 与 details_markdown 合起来构成对类型的完整说明，而向量字段的内容不应重复出现在概述或详情中。该结构体本身不维护复杂不变量，仅作为聚合容器使用，所有字段在构造后可直接修改，调用方负责保证内容的语义一致性。

Invariants

• No invariants are enforced by the type.

Key Members

• overview_markdown
• details_markdown
• invariants
• key_members
• usage_patterns

Usage Patterns

• Used as a container for caching analysis results across documentation pages.
• Each field corresponds to a section of generated documentation, consumed by documentation templates.

clore::generate::VariableAnalysis

Declaration: generate/model.cppm:99

Definition: generate/model.cppm:99

Declaration: Namespace clore::generate

clore::generate::VariableAnalysis 是一个纯数据聚合体，用于封装对单个变量的分析结果。其内部结构由两组字段组成：一组描述变量的用途，包括 overview_markdown 与 details_markdown 分别存储概要和详细说明，以及 usage_patterns 向量记录各类使用模式；另一组描述变量的变异状态，包括布尔标志 is_mutated（默认 false）和 mutation_sources 向量。一个关键的不变量是，当 is_mutated 为 true 时，mutation_sources 必须非空，反之亦然，以此保证变异信息的完整性。各字段均以默认初始化或空向量开始，等待外部填充。

Functions

clore::generate::analysis_details_markdown

Declaration: generate/model.cppm:157

Definition: generate/model.cppm:373

Declaration: Namespace clore::generate

该函数是 analysis_markdown 的一个特化封装，通过提供一个字段访问器来提取对应分析对象的 details_markdown 成员。它将符号标识符 symbol 和 SymbolAnalysisStore 传递给 analysis_markdown，并传入一个 lambda 表达式，该表达式接受函数分析、类型分析或变量分析的引用，返回指向其 details_markdown 字段的指针。内部控制流完全委托给 analysis_markdown：后者根据符号的类型（由 is_function_kind、is_type_kind、is_variable_kind 等判定）在存储中查找对应的分析记录（通过 find_function_analysis、find_type_analysis、find_variable_analysis），然后调用传入的字段访问器获取所需字符串。整个处理不涉及复杂算法，其核心依赖是 analysis_markdown 泛型实现以及各分析结构体（FunctionAnalysis、TypeAnalysis、VariableAnalysis）中名为 details_markdown 的 std::string 成员。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• analyses (const SymbolAnalysisStore&)
• symbol (const extract::SymbolInfo&)
• analysis_markdown reads from the analyses store

Usage Patterns

• Used to obtain the details markdown for a symbol during page generation
• Called by page rendering functions to include detailed analysis content

clore::generate::analysis_markdown

Declaration: generate/model.cppm:342

Definition: generate/model.cppm:342

Declaration: Namespace clore::generate

函数 clore::generate::analysis_markdown 通过符号种类分发查询逻辑：首先调用 make_symbol_target_key 从输入的 extract::SymbolInfo 构造目标键，随后依次检查 is_function_kind、is_type_kind、is_variable_kind 以确定符号类别，并分别委托给 find_function_analysis、find_type_analysis 或 find_variable_analysis 在 SymbolAnalysisStore 中查找对应的分析结构。若找到分析对象，则调用模板参数 FieldAccessor 可调用对象（例如 lambda 或函数指针）提取所需字段（如 FunctionAnalysis::overview_markdown），返回指向结果字符串的指针；否则返回 nullptr。

该函数的核心依赖包括 SymbolAnalysisStore 及其相关的查找函数、make_symbol_target_key 以及符号类别判定函数。所有查找均基于同一目标键，且访问器与具体分析结构（FunctionAnalysis、TypeAnalysis、VariableAnalysis）的成员类型相匹配，由调用方通过模板参数注入，从而支持灵活的字段提取。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• the SymbolAnalysisStore object analyses
• the extract::SymbolInfo object symbol (specifically symbol.kind)
• the analysis objects obtained via find_function_analysis, find_type_analysis, find_variable_analysis

Usage Patterns

• Used to extract specific markdown fields from analysis data for symbol documentation generation.

clore::generate::analysis_overview_markdown

Declaration: generate/model.cppm:154

Definition: generate/model.cppm:366

Declaration: Namespace clore::generate

函数 clore::generate::analysis_overview_markdown 是一个轻量包装，内部完全委托给通用函数 clore::generate::analysis_markdown。它接收 clore::generate::SymbolAnalysisStore 引用和符号标识，并传入一个 lambda 访问器，该访问器从具体的分析结构（如 clore::generate::FunctionAnalysis、clore::generate::VariableAnalysis 或 clore::generate::TypeAnalysis）中提取 overview_markdown 字段的地址。analysis_markdown 内部根据符号类型（通过 clore::generate::is_function_kind、clore::generate::is_variable_kind、clore::generate::is_type_kind 判断）查找对应的分析（调用 clore::generate::find_function_analysis、clore::generate::find_variable_analysis 或 clore::generate::find_type_analysis），若找到则应用访问器返回 std::string 指针，否则返回空指针。该函数不包含额外逻辑，完全依赖 analysis_markdown 的符号类型分发和通用字段提取机制。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• SymbolAnalysisStore parameter analyses
• extract::SymbolInfo parameter symbol

Usage Patterns

• Used to obtain the overview portion of a symbol's analysis for rendering.

clore::generate::build_link_resolver

Declaration: generate/model.cppm:201

Definition: generate/model.cppm:471

Declaration: Namespace clore::generate

函数的核心是为每个页面计划生成名称到路径的映射，构建一个 clore::generate::LinkResolver。它遍历 plan_set.plans，首先将每个 plan.page_id 与 plan.title 填入 resolver.page_id_to_title。接着处理 plan.owner_keys：对每个 key，使用 emplace 写入 resolver.name_to_path，确保在模块与命名空间共享相同名称时首次注册的路径优先；若 plan.page_type 是 PageType::Namespace 则同时写入 resolver.namespace_to_path，若是 PageType::Module 则写入 resolver.module_to_path，这两个映射直接赋值因而允许针对同类型的覆盖。最后，如果 plan.page_id 包含冒号 :，则提取冒号后的后缀，并对其重复上述三组映射的插入操作（同样区分页面类型），从而支持对 page_id 中嵌套名称的寻址。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• plan_set.plans
• plan.page_id
• plan.title
• plan.owner_keys
• plan.relative_path
• plan.page_type

Writes To

• resolver.page_id_to_title
• resolver.name_to_path
• resolver.namespace_to_path
• resolver.module_to_path

Usage Patterns

• Called during page generation setup to create a resolver for linking symbols to page paths
• Used to populate a LinkResolver that enables module, namespace, and generic name resolution

clore::generate::compute_page_path

Declaration: generate/model.cppm:214

Definition: generate/model.cppm:576

Declaration: Namespace clore::generate

函数 clore::generate::compute_page_path 根据 PageIdentity 的 page_type 字段分派路径生成逻辑。对于 PageType::Index 直接返回静态常量 kIndexPath；对于 PageType::Module，通过 split_qualified 按 . 拆分 qualified_name，处理可选的 : 分区后缀，以 kModulePrefix 为根，对每个部件调用 normalize_name，最后追加 index.md 或分区名 .md；对于 PageType::Namespace，按 :: 拆分后以 kNamespacePrefix 为根，同样归一化各部件并以 index.md 结尾；对于 PageType::File，则从 source_relative_path 中移除文件扩展名，拼接 kFilePrefix 前缀后加上 .md 后缀。所有分支得到的路径字符串先经过 sanitize_path_chars 清理非法字符，再通过 validate_path_component 验证合法性，若验证失败则返回 PathError 表示错误。该函数依赖 split_qualified、normalize_name、join_path、sanitize_path_chars、validate_path_component 等内部辅助函数及模块级常量，其控制流完全由 page_type 枚举决定。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• PageIdentity parameter identity (fields page_type, qualified_name, source_relative_path)

Writes To

• Returns an std::expected<std::string, PathError> containing the computed path string

Usage Patterns

• Used to determine output file path for a documentation page
• Called during page generation to map identities to filesystem locations

clore::generate::find_function_analysis

Declaration: generate/model.cppm:145

Definition: generate/model.cppm:323

Declaration: Namespace clore::generate

clore::generate::find_function_analysis 在 analyses.functions（一个以符号目标键为键、FunctionAnalysis 实例为值的映射）上执行一次查找：它使用提供的 symbol_target_key 调用 find，并检查返回的迭代器是否等于 end；如果找到，函数返回指向该映射条目的 const FunctionAnalysis*，否则返回 nullptr。该实现完全依赖于 SymbolAnalysisStore 的内部映射结构，不涉及其他外部依赖或复杂的控制流。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• analyses.functions (map of symbol target keys to FunctionAnalysis)
• symbol_target_key parameter

Usage Patterns

• Used by code generation routines to retrieve a stored function analysis for further processing.

clore::generate::find_type_analysis

Declaration: generate/model.cppm:148

Definition: generate/model.cppm:329

Declaration: Namespace clore::generate

该函数通过直接的映射查找实现。它接收对 SymbolAnalysisStore 的引用 analyses 和一个 std::string_view 类型的 symbol_target_key 作为参数。内部控制流仅包含一条查找语句：调用 analyses.types.find(symbol_target_key)，其中 analyses.types 是一个将符号目标键映射到 TypeAnalysis 对象的关联容器。若 find 返回有效的迭代器（即键存在于映射中），函数返回指向该 TypeAnalysis 对象的指针；否则返回 nullptr。

核心依赖为 SymbolAnalysisStore 的 types 成员以及 TypeAnalysis 类型本身。该实现无额外循环或分支，完全依赖底层容器的查找操作，因而在平均情况下具有常数时间复杂度。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• analyses.types (the map of symbol target keys to TypeAnalysis)

Usage Patterns

• Look up type analysis for a given symbol target key
• Retrieve cached analysis data for a type

clore::generate::find_variable_analysis

Declaration: generate/model.cppm:151

Definition: generate/model.cppm:335

Declaration: Namespace clore::generate

该函数通过直接查询 SymbolAnalysisStore::variables 关联容器实现查找操作。它接受一个 symbol_target_key 字符串视图，调用 analyses.variables.find 以 $O(1)$ 平均复杂度定位对应的 VariableAnalysis 对象；若迭代器 it 未到达 analyses.variables.end()，则返回 &it->second，否则返回 nullptr 表示未命中。整个函数依赖 SymbolAnalysisStore 存储结构及 std::unordered_map（或等价容器）的查找接口，不涉及额外状态或复杂控制流。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• analyses.variables (member of SymbolAnalysisStore)
• symbol_target_key (parameter)

Usage Patterns

• retrieving a variable analysis for a given symbol key
• querying analysis results
• accessed by documentation generation functions

clore::generate::is_function_kind

Declaration: generate/model.cppm:162

Definition: generate/model.cppm:393

Declaration: Namespace clore::generate

该函数通过一个 switch 语句区分传入的 extract::SymbolKind 枚举值，仅当为 extract::SymbolKind::Function 或 extract::SymbolKind::Method 时返回 true，其余情况返回 false。内部逻辑完全基于控制流的枚举分支，不涉及外部数据结构或复杂计算。其直接依赖是 extract::SymbolKind 枚举（在 extract 命名空间下定义），该枚举由代码库的符号提取模块提供，用于表示待分析符号的种类。在文档生成流程中，is_function_kind 作为符号分类谓词，用于判断当前分析的符号是否属于函数或方法范畴，从而决定后续是否进入函数专用分析路径（如 FunctionAnalysis 结构体的填充与 FunctionImplementationSummary 等提示请求的生成）。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• Parameter kind of type extract::SymbolKind

Usage Patterns

• Used to filter symbols in generation logic
• Classifies symbol kinds as function-like

clore::generate::is_page_level_symbol

Declaration: generate/model.cppm:166

Definition: generate/model.cppm:405

Declaration: Namespace clore::generate

该函数通过依次检查符号的 lexical_parent_kind 是否为命名空间或未知，排除匿名命名空间中的符号（检查 enclosing_namespace 和 lexical_parent_name 是否包含 (anonymous namespace)），并递归检查其直接父符号是否为类型或函数（通过 is_type_kind 和 is_function_kind）来确定符号是否应被视作页面级（page-level）符号。内部流程依赖 extract::lookup_symbol 解析父符号，并依赖来自 SymbolKind 枚举的常量进行种类判断。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• sym.lexical_parent_kind
• sym.enclosing_namespace
• sym.lexical_parent_name
• sym.parent
• model (via extract::lookup_symbol)
• result of extract::lookup_symbol's kind field

Usage Patterns

• called during page generation to filter symbols for page creation
• used in render_page_bundle or similar pipelines

clore::generate::is_page_summary_prompt

Declaration: generate/model.cppm:133

Definition: generate/model.cppm:297

Declaration: Namespace clore::generate

函数 clore::generate::is_page_summary_prompt 的实现基于一个简单的分支判断：它将传入参数 kind 与枚举类 clore::generate::PromptKind 中的两个成员 NamespaceSummary 和 ModuleSummary 进行相等性比较。该检查为短路或（||），因此只要任一匹配即返回 true，反之返回 false。没有循环、递归或状态更改，控制流为恒定时间的一次性判定。

该函数依赖于 PromptKind 枚举的定义，但不依赖任何其他运行时数据或外部状态。在代码库中，它常用于过滤提示请求集合，以区分生成页面级摘要提示（如命名空间或模块概览）与符号级别分析提示（如函数分析、类型分析等），从而在调度生成任务或计算生成摘要结构时进行条件分支。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• kind parameter

Usage Patterns

• Used to classify prompt kinds for conditional logic in page generation.

clore::generate::is_symbol_analysis_prompt

Declaration: generate/model.cppm:134

Definition: generate/model.cppm:301

Declaration: Namespace clore::generate

函数 clore::generate::is_symbol_analysis_prompt 的实现采用单一比较序列：它将传入的 kind 与三个 PromptKind 枚举成员（FunctionAnalysis、TypeAnalysis 和 VariableAnalysis）逐一进行相等性检查，并将三次比较的结果进行逻辑或，返回最终的布尔值。内部控制流线性且无分支，完全依赖于 PromptKind 枚举类型的定义。该函数不涉及外部状态或复杂依赖，仅使用调用方传入的参数和枚举字面量。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• kind parameter

Usage Patterns

• Used to classify prompt kinds into symbol analysis categories
• Conditional dispatch in prompt generation or evidence building

clore::generate::is_type_kind

Declaration: generate/model.cppm:160

Definition: generate/model.cppm:380

Declaration: Namespace clore::generate

函数 clore::generate::is_type_kind 通过一个 switch 语句直接检查传入的 extract::SymbolKind 枚举值是否属于一组预定义的类型相关种类。这些种类包括 extract::SymbolKind::Class、extract::SymbolKind::Struct、extract::SymbolKind::Enum、extract::SymbolKind::Union、extract::SymbolKind::Concept、extract::SymbolKind::Template 和 extract::SymbolKind::TypeAlias。若 kind 匹配其中任何一个，函数返回 true；对于所有其他枚举值（包括可能的未来新增值），通过 default 分支返回 false。

该函数的内部控制流线性且无分支，不存在循环或递归调用。其唯一的外部依赖是 extract::SymbolKind 枚举类型的定义。该函数不访问任何全局状态或调用其他辅助函数，纯粹根据输入参数的值进行静态分支判断。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• kind parameter

Usage Patterns

• Used in code generation logic to filter or categorize symbols by kind.
• Likely called by build_evidence_for_type_* functions to determine if a symbol is a type.

clore::generate::is_variable_kind

Declaration: generate/model.cppm:164

Definition: generate/model.cppm:401

Declaration: Namespace clore::generate

函数 clore::generate::is_variable_kind 是一个简单的谓词，用于检查传入的 extract::SymbolKind 枚举值是否属于变量或枚举成员类别。其实现仅包含一个返回逻辑表达式的语句：比较 kind 与 extract::SymbolKind::Variable 和 extract::SymbolKind::EnumMember 的相等性，两者只要满足其一即返回 true，否则返回 false。该函数不依赖任何外部状态或复杂控制流，仅依赖 extract::SymbolKind 枚举定义。在代码生成流程中，它常被作为快速分类工具，用于判断给定符号是否应当被当作变量分析对象处理。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• kind parameter

Usage Patterns

• used to filter symbols by variable-like kinds
• used in predicate checks for symbol classification

clore::generate::make_source_relative

Declaration: generate/model.cppm:169

Definition: generate/model.cppm:432

Declaration: Namespace clore::generate

函数首先对空输入进行快速短路处理，若 path 或 project_root 为空则直接返回原始 path。否则，以换行符拼接 project_root 和 path 构造缓存键，并通过 source_relative_cache() 获取全局的 SourceRelativeCache 实例。在共享锁保护下查询 relative_by_key 映射；若命中则立即返回缓存的相对路径。未命中时，将两个路径经 std::filesystem::path::lexically_normal 规范化后，调用 lexically_relative 计算相对关系。若结果为空或原始路径以 ".." 起始（表示无法相对化或路径逃逸），则回退到原始 path；否则采用 generic_string 格式的规范化结果。最后在唯一锁保护下将新映射存入缓存并返回。该函数的唯一外部依赖是匿名命名空间内的 source_relative_cache 函数，它提供了线程安全的静态缓存容器。

Side Effects

• Writes to a global static cache
• Allocates strings for cache entries

Reads From

• parameter path
• parameter project_root
• global cache source_relative_cache().relative_by_key

Writes To

• global cache source_relative_cache().relative_by_key

Usage Patterns

• Called by page generation functions to make paths relative for output
• Used when building link targets or source locations

clore::generate::make_symbol_target_key

Declaration: generate/model.cppm:141

Definition: generate/model.cppm:306

Declaration: Namespace clore::generate

函数 clore::generate::make_symbol_target_key 使用长度前缀编码构造符号的目标键。它从 extract::SymbolInfo 对象读取 symbol.qualified_name 及其长度 symbol.qualified_name.size()，通过 std::format 以冒号分隔拼接出初始字符串，再追加 symbol.signature。这种设计使得生成的键可以通过 clore::generate::parse_symbol_target_key 安全地反解析为 clore::generate::SymbolTargetKeyView，从而支持后续的符号查询与页面规划。该实现不涉及分支或循环，仅依赖 std::format 进行格式化，保持了构造过程的简洁与高效。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• symbol.qualified_name
• symbol.signature

Usage Patterns

• Used to generate target keys for symbols during page building
• Called when constructing link targets and symbol references

clore::generate::page_type_name

Declaration: generate/model.cppm:16

Definition: generate/model.cppm:263

Declaration: Namespace clore::generate

该函数接受一个 PageType 枚举值，通过 switch 语句将其映射到对应的 std::string_view 字面量。内部控件流仅包含对四个枚举成员——PageType::Index、PageType::Module、PageType::Namespace、PageType::File——的分支，每个分支返回一个预定义的字符串。默认情况下，返回 "unknown"。该函数不依赖任何外部状态或复杂算法，仅依赖于 PageType 枚举的定义。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• parameter type of type PageType

Usage Patterns

• Used wherever a string representation of a page type is needed, such as in page generation or naming.

clore::generate::parse_symbol_target_key

Declaration: generate/model.cppm:143

Definition: generate/model.cppm:312

Declaration: Namespace clore::generate

该函数首先尝试调用内部辅助函数 parse_length_prefixed_symbol_target_key 对输入的 target_key 进行解析；若该函数返回有效值（即 std::optional 包含结果），则直接返回解析后的 SymbolTargetKeyView。否则，作为一个回退路径，函数构造一个 SymbolTargetKeyView，将原始 target_key 整体赋给 qualified_name 字段，并将 signature 字段置为空字符串。这种设计使得调用者无需区分键的格式——对于可能携带签名信息的长度前缀格式，解析更精确；对于仅包含限定名称的简单形式，也能正确构造视图。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• target_key parameter

Usage Patterns

• Used to convert a std::string_view symbol target key into a structured view
• Called when processing symbol references that may include signatures

clore::generate::prompt_kind_name

Declaration: generate/model.cppm:32

Definition: generate/model.cppm:273

Declaration: Namespace clore::generate

该函数通过一个 switch 语句将枚举 PromptKind 的各个成员直接映射到对应的字符串字面量。每个 case 分支返回一个硬编码的名称，例如 PromptKind::NamespaceSummary 映射到 "namespace_summary"，PromptKind::FunctionAnalysis 映射到 "function_analysis"，以此类推，覆盖了枚举中定义的所有分析摘要与实现摘要类型。内部逻辑不依赖其他函数、数据或外部状态，仅基于输入的 kind 进行单一分派。当传入的值不匹配任何枚举成员时，函数返回默认字符串 "unknown_prompt" 作为回退。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• parameter kind of type PromptKind

Usage Patterns

• used in prompt building and identification functions
• called when generating prompt names for different analysis kinds

clore::generate::prompt_request_key

Declaration: generate/model.cppm:131

Definition: generate/model.cppm:290

Declaration: Namespace clore::generate

该函数根据 request.target_key 是否为空决定返回值的结构。若为空，则直接调用 prompt_kind_name(request.kind) 并将结果转换为字符串；否则，将 prompt_kind_name(request.kind) 与冒号及 request.target_key 拼接后返回。整个函数依赖 PromptRequest 结构体的 kind 和 target_key 成员，以及 prompt_kind_name 函数提供的枚举到名称的映射，无其他外部依赖或复杂控制流。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• request.kind
• request.target_key
• result of prompt_kind_name(request.kind)

Usage Patterns

• used as a cache key for prompt requests
• used to index or group prompts by kind and target

clore::generate::validate_no_path_conflicts

Declaration: generate/model.cppm:216

Definition: generate/model.cppm:644

Declaration: Namespace clore::generate

该函数通过维护一个从路径字符串到标识符字符串的 std::unordered_map（名为 seen）来检测重复输出路径。对于输入向量中的每个 (path, id) 对，它尝试使用 emplace 将路径作为键插入到 seen 中。如果插入成功（inserted 为 true），说明该路径在此前没有被记录过；如果插入失败（inserted 为 false），则说明该路径已被先前的某个标识符所占用，此时函数立即返回一个 std::unexpected 包装的 clore::generate::PathError，其 message 字段通过 std::format 生成，内容同时包含冲突的二者标识符以及重复的路径。当所有路径都成功完成插入后，函数返回一个空的 std::expected 表示无冲突。该实现不依赖任何外部分析数据，仅借助标准库容器和格式化设施完成线性扫描与冲突报告。

Side Effects

No observable side effects are evident from the extracted code.

Reads From

• path_to_id parameter (const std::vector<std::pair<std::string, std::string>>&)

Usage Patterns

• Used to ensure unique output paths before generating pages
• Called during page generation to prevent path collisions

Internal Structure

generate:model 模块为文档生成管线提供了核心数据模型与中间表示。它定义并组合了页面计划（PagePlan、PagePlanSet）、符号分析结果（FunctionAnalysis、TypeAnalysis、VariableAnalysis 及容器 SymbolAnalysisStore）、链接解析器（LinkResolver）以及输出页面结构（GeneratedPage、PageIdentity）等关键类型，同时配套枚举（PageType、PromptKind）和查询函数（如 is_page_level_symbol、find_*_analysis）以支撑后续渲染与路径决策。模块依赖底层的 support 模块（提供 UTF‑8 处理、文件读写、路径规范化等工具）和上游的 extract 模块（符号提取结果），并通过匿名命名空间封装了路径计算（如 join_path、source_relative_cache）与键解析（如 parse_symbol_target_key）等内部实现细节，确保公开接口的简洁性与实现层的隔离。

Related Pages

• Module extract
• Module support