Context for AI

Appearance

Code Extraction ​

Parsers produce facts, not knowledge ​

Parser packages read code and interface definitions and emit deterministic structural facts: symbols, source spans, imports and exports, routes, contracts. They never create Candidates, write knowledge/ or control Review. The selected Indexer interprets those facts together with the readable source and writes reader-oriented articles.

mermaid
flowchart LR
  code["Pinned module"] --> parsers["Parsers"]
  parsers --> facts["Structural facts"]
  facts --> indexer["Code Indexer"]
  code --> indexer
  indexer --> art["Articles"]

Available parsers ​

PackageStructural facts
@c4a/extract-tsTypeScript/JavaScript symbols, exports, imports, calls and React Router routes
@c4a/extract-goGo declarations, imports, calls and common HTTP routes
@c4a/extract-rushRush projects, tags, entries, dependencies and owner boundaries
@c4a/extract-thriftThrift services, methods and declared data types
@c4a/extract-protoProtobuf messages, fields and service definitions
@c4a/extract-mdxMarkdown/MDX structure, component references, examples and source spans
@c4a/extract-contractSupported structured API contract declarations (OpenAPI, GraphQL)
@c4a/extract-styleStylesheet declarations and selectors
@c4a/extract-sqlSupported SQL schema declarations
@c4a/extractThe shared extraction protocol, plugin runner, scanner and snapshot records

All of them ship inside @c4a/context-cli.

Smallest parser set first ​

Parsing is an Indexer implementation detail, not a separate phase in src/index.ts. The order is:

  1. identify the target boundary and the reader's questions;
  2. let the Indexer inspect language, manifests, entries, routes and contracts;
  3. use the smallest parser set that covers those questions;
  4. keep parser output as facts and write articles from facts plus readable source.

During planning, the Code Indexer does not run a full-repository parse just to learn whether a feature exists; deep extraction belongs to writing a selected topic.

When a technology is not supported ​

Distinguish a parser limitation from missing writing guidance. Configuration can select supported behavior, but instructions and templates cannot create missing structural facts. The workflow reports the capability gap and the smallest supported step; when a technology is useful across projects, a reusable parser is preferred over a project-local pipeline.

代码抽取 ​

解析器产出事实，而不是知识 ​

解析器包读取代码和接口定义，输出确定性的结构性事实：符号、源码范围、导入与导出、路由、契约。它们从不创建候选、写入 knowledge/ 或控制审核。选定的 Indexer 结合这些事实和可读的源码进行解读，撰写面向读者的文章。

mermaid
flowchart LR
  code["固定版本的模块"] --> parsers["解析器"]
  parsers --> facts["结构性事实"]
  facts --> indexer["Code Indexer"]
  code --> indexer
  indexer --> art["文章"]

可用的解析器 ​

包结构性事实
@c4a/extract-tsTypeScript/JavaScript 符号、导出、导入、调用以及 React Router 路由
@c4a/extract-goGo 声明、导入、调用以及常见 HTTP 路由
@c4a/extract-rushRush 项目、标签、入口、依赖和归属边界
@c4a/extract-thriftThrift 服务、方法和声明的数据类型
@c4a/extract-protoProtobuf 消息、字段和服务定义
@c4a/extract-mdxMarkdown/MDX 结构、组件引用、示例和源码范围
@c4a/extract-contract支持的结构化 API 契约声明（OpenAPI、GraphQL）
@c4a/extract-style样式表声明和选择器
@c4a/extract-sql支持的 SQL schema 声明
@c4a/extract共享的抽取协议、插件运行器、扫描器和快照记录

它们都随 @c4a/context-cli 一起发布。

优先使用最小的解析器集合 ​

解析是 Indexer 的实现细节，而不是 src/index.ts 中的独立阶段。顺序如下：

  1. 确定目标边界和读者的问题；
  2. 让 Indexer 检查语言、清单文件、入口、路由和契约；
  3. 使用能覆盖这些问题的最小解析器集合；
  4. 把解析器输出作为事实，基于事实和可读源码撰写文章。

在计划阶段，Code Indexer 不会为了确认某个功能是否存在而对整个仓库做解析；深度抽取属于撰写选定主题时的工作。

当某种技术尚不支持时 ​

要区分解析器能力的限制和写作指引的缺失。配置可以选择已支持的行为，但说明和模板无法创造缺失的结构性事实。工作流会报告能力缺口以及可行的最小支持步骤；当某种技术在多个项目中都有用时，优先开发可复用的解析器，而不是项目本地的处理流水线。