.notc 声明模块与 Package / Plugin 扩展

动机

• 内容函数的名称、参数契约和内容级别依赖内置定义，外部函数无法通过配置成为合法的文档节点；内置与扩展需要共同的定义和注册路径。

• .not 中的 #foo(args)[children] 是 Markup 调用语法，现有“Code 模式”的表述混淆了调用参数的词法状态与独立 Code 语言。

• 扩展 content function 需要声明签名与提供呈现实现；package、项目配置和组件资源之间需要明确的装配关系，避免文档或项目重复描述插件签名。

变更总览

架构

首个目标是打通扩展 content function 的分析与 Web Component 显示：lib.notc 提供类型签名，JS 组件提供呈现，项目通过 Notist.toml 装配。第一阶段只实现函数声明，不引入函数体执行或 WASM 插件加载。

flowchart LR
    NC["lib.notc"] --> MC["Module CST / AST"]
    MC --> DM["DefinitionModule"]
    BI["core 原生 builtin 定义"] --> DM
    DM --> REG["共同校验与 Registry"]

    NS[".not / Markdown"] --> EX["文档 Expr"]
    EX --> RS["Resolve / Shape"]
    REG --> RS
    RS --> IT["Item 内容树"]

    PT["components/ 中的组件实现"] --> HR["HTML Registry"]
    IT --> HTML["HTML renderer"]
    HR --> HTML
    HTML --> OUT["HTML + diagnostics + used_components"]
    OUT --> HOST["host 装配 JS / CSS"]

例如，安装 Mermaid package 后，项目可使用 #mermaid.diagram("graph TD; A-->B")。分析器按声明检查参数并保留调用；HTML renderer 输出组件元素，host 安装其 module，组件内部 DOM 不进入文档 IR。

声明、共同注册、配置文档分析、扩展 IR、包加载、HTML 组件与资源 host、CLI / LSP / Web 预览均已实现。当前接口见 Code Syntax、Content Function Extensions 与 HTML Rendering 文档。

定义与内容模型

core 的新增表示是定义信息，不是第二套可执行语言 IR：

struct DefinitionModule {
    functions: Vec<FunctionDef>,
}

FunctionDef 包含稳定身份、参数类型与绑定规则、默认值、children 契约和结果类别。语法 AST 中的类型引用和默认值在声明分析时转换为这些语义对象；源文件位置用于声明诊断，运行时不持有 CST。

内置通过原生 API 构造同样的定义，外部通过 .notc lowering 构造定义，随后进入同一个声明校验器和 Registry。名称解析、默认值、类型和值域检查以及内容类别判定不能按定义来源分成两套路径。

包中有非法声明时，编辑器仍可展示恢复后的 AST 和诊断，但该包不能部分安装到正式环境。跨包绑定及结构引用在装配时验证，全部通过后提交。源文件内容错误仍采用文档管线的恢复策略。

声明不进入文档 Expr，也不物化为 Item。当前文档管线继续处理调用；未来函数体和表达式求值需要自己的 Code IR，届时再增加。

parse_document(source) // .not，返回 Document CST
parse_module(source)   // .notc，返回 Module CST

fn diagram(source: String, theme: String = "default") -> Content;

fn panel(title?: String)[children: Content] -> Content;

fn badge(label: String)[children: InlineContent] -> InlineContent;

project/
├── Notist.toml
├── document.not
└── packages/
    └── mermaid/
        ├── lib.notc
        └── components/
            ├── badge.js
            └── diagram/
                ├── index.js
                └── assets/

[dependencies]
mermaid = { path = "./packages/mermaid" }

// components/diagram/index.js
export default class Diagram extends HTMLElement {
  // 参数读取、呈现和生命周期实现。
}

import Diagram from "./packages/mermaid/components/diagram/index.js";
customElements.define("mermaid-diagram", Diagram);

#mermaid.diagram("graph TD; A-->B")

<mermaid-diagram
  notist-source="graph TD; A--&gt;B"
  notist-theme="default"
></mermaid-diagram>

关键设计决策

1. Markup / Code 分开：.not 包含调用语法，.notc 承担独立 Code 文法；lexer 的内部词法状态不作为语言切换。

2. 同 crate、双入口：notist-syntax 提供 Document 与 Module parser，共享基础词法、字面量和无损 CST 基础设施。

3. 声明先行：第一版 .notc 以 lib.notc 为入口，只声明内容函数签名；默认值是字面量，函数没有执行体。

4. 定义与调用分开：FunctionDef / DefinitionModule 进入注册表；文档 Expr / Item 保留公开调用结构，声明不成为 Content 节点。

5. 共同注册路径：原生 builtin 与 .notc 声明构造同样的定义，使用同一个校验器、Registry 与调用检查逻辑。

6. 包路径与 Prelude：内置包 notist 的函数进入 prelude；外部调用使用 package::function。组件标签使用包名和声明名，语法糖使用规范内置身份。

7. 单模块与约定装配：一个 package 只有 lib.notc 这一个 Code 模块；项目 Notist.toml 引入依赖，标签与组件资源使用固定约定。

8. children 保持单一挂载：普通参数只包含 Value，children 渲染为 light DOM，由组件 slot 展示；组件内部 DOM 不展开成 IR。

9. 类别在分析时确定：签名参与 Resolve / Shape，最终 Item 保存调用类别，消费者无需重新加载插件来判断块／行内。

10. 资源由 host 装配：renderer 返回实际组件使用记录；host 安装和去重 JS / CSS。纯分析与片段渲染 API 不自动读取项目或下载资源。

任务拆解

flowchart TD
    P0["P0：文法、定义与配置契约"] --> P1["P1：双语法入口与声明 lowering"]
    P1 --> P2["P2：共同定义校验与 Registry"]
    P2 --> P3["P3：文档管线与 IR 消费端迁移"]
    P2 --> P4["P4：Package 依赖装配"]
    P3 --> P5["P5：HTML 组件与资源记录"]
    P4 --> P6["P6：CLI / LSP / 预览与端到端示例"]
    P5 --> P6

1. [x] 正式语法与 parser：在 notist-syntax 增加持续 Code 的词法入口与 Module parser，增加声明／参数／类型节点和 AST；Markup 调用增加 :: 路径及 Path 节点。整理调用词法的命名，提取共享扫描、字面量解析与值转换，保留现有无损 CST 行为。

2. [x] 定义模型与共同注册：在 core 增加 FunctionDef、DefinitionModule、声明校验与 Registry，将内置名称、参数和类别规则迁入共同路径；.notc lowering 放在连接 syntax 与 core 的分析层，core 不依赖 parser。

3. [x] 文档管线接入：Resolve 使用环境注册表，Shape 使用解析后的调用类别，最终 IR 表达合法外部身份。适配查询、dump、serde 和各消费端。

4. [x] package 装配：读取项目 Notist.toml 的 dependencies 和各目录的 lib.notc，处理本地来源与包归属，聚合带来源文件的诊断，建立不可变环境。配置或声明失败不进行部分安装。

5. [x] HTML 组件：增加目标注册、属性编码、组件依赖记录与 host 资源装配；用一个本地容器组件验证参数和嵌套 children，再接入 Mermaid 示例。

6. [x] 工具与文档：CLI、LSP、Web 预览共用装配结果；分别提供文档分析与模块分析入口。更新语法文档、内置签名说明、依赖与组件约定和调用示例。

第一阶段结束时，必须能从真实 package 的声明入口走到文档中的合法调用和页面显示。

验收

• .notc 无损解析；错误声明不会吞掉后续声明；未知类型、重复参数、非法默认值等诊断定位到 lib.notc。

• 原生定义与同等 .notc 定义进入相同校验与注册路径，调用绑定和诊断一致。

• 项目配置启用插件后，限定调用不再产生 unknown constructor；内置简写与 notist 限定调用身份一致，外部同名函数在各包中分别解析。位置与具名参数、默认值、children 接受性和块／行内重组符合签名。

• package 加载失败不会留下部分注册；Notist.toml 与 lib.notc 的错误保留各自来源位置。

• 最终 IR、遍历、查询和序列化完整保留函数身份、内容类别与公开树结构。

• HTML 标签带包名前缀，同名函数的组件分别注册；参数转义正确，false、空字符串、省略值、大整数和复杂值不会混淆；children 顺序与身份保持。

• 静态页面与 Web 预览能加载组件；嵌套组件资源被记录并去重，组件重连不会重复创建 shadow root。

• 默认前端和内置内容函数保留现有行为，已有 corpus 与相关测试通过。第一阶段不引入插件执行引擎。

实施与验收结果

• core / 连接层：内置和源码定义共用绑定与 Registry；配置环境参与 Resolve / Shape，合法扩展保留身份和类别，查询、dump、debug JSON 与 serde 已适配。

• package：Project 提供纯源码装配与本地文件 loader，支持最近配置、显式配置、来源诊断及编辑器覆盖，失败不返回部分环境。

• HTML：HtmlRegistry 统一绑定内置与组件，协议 v1 保留标量与复杂值，RenderResult 记录实际使用组件；host 复制目录资源并生成去重注册入口。

• 工具：CLI 提供 html 构建及 .notc 检查 / CST / JSON；LSP 使用相同 loader，支持声明符号、hover、限定调用跳转和未保存声明的诊断刷新；Web 提供显式配置装配、组件 iframe 预览与模块检查。

• 示例：嵌套 panel、简单 badge 和 Mermaid 已走通声明 → 调用 → IR → 静态 HTML / Web 预览；当前入口为 Vault 组件示例文档。

• 验证：workspace 全特性测试、WASM 构建、文档检查与 JS 协议测试通过；CLI / LSP 进程测试覆盖装配与恢复。Chromium 验证静态页面、Mermaid SVG、i64 精度、shadow root 复用及 Web 预览，未产生页面异常。

浏览器示例使用固定版本 Mermaid CDN 资源；离线分发由 package 提供本地浏览器依赖。第一阶段仍只有一个 lib.notc，没有 Code 求值、WASM 插件执行、传递依赖或远程包解析。

记录在案的边角

• .notc 声明的 token、trivia、类型引用与同步恢复规则已定义正式文法；高级值域、结构契约及动态返回类别的源码表达需另外设计。

• HTML 名称与协议按 v1 统一编码和校验，不使用 Value.to_string() 传递复杂值。

• 函数身份与调用类别的 IR 调整涉及 Ctor、query、dump 和 serde，公共接口及序列化迁移已在当前设计中说明。

• lib.notc、项目 Notist.toml 与文档调用的诊断分别保留来源文件和范围；配置失败与文档恢复不能混同。

• 包名与函数名组成标签时使用确定性编码，并检查拼接与编码碰撞；当前环境同一包名只对应一个来源。依赖键改名时，限定调用和 host 生成的标签一起改变，组件文件仍按局部声明名定位。

复杂 scripting、函数体、表达式及多模块需求出现后，再设计对应的 Code IR、模块与执行模型；第一阶段不预设子模块、入口切换或模块发现。WASM 可以作为后续的验证或执行后端，再接入共同定义与注册路径。远程 package 获取、依赖版本解析、锁文件和发布仓库也可独立增加。

这些扩展不能改变第一阶段的基本契约：内容函数在文档中保留公开调用结构，签名负责分析，目标实现负责呈现。