dexin-content 0.2.1 → 0.3.1

package/README.md

@@ -1,112 +1,120 @@
-# dexin-content
-
-得心实验室的**结构化内容编译与运行时 package**。
-
-负责与具体业务领域无关的通用内容管线：
-
-- **Compile**：将带 frontmatter 的 Markdown 编译成中性 Content AST，再经宿主注入的 `DomainParser` 产出稳定的 PositiveArtifact
-- **Store**：Artifact 与索引（ContentIndex）的 FS/Memory 抽象
-- **Query**：按 id / URL path / collection / 条件过滤对 Artifact 做只读查询
-- **Collection**：集合声明、发现、批量编译与增量变化检测
-- **Diff**：Canonical JSON 序列化与对象级差异原语（Golden/Regress 管线使用）
-
-## 目录范围
-
-dexin-content 是**通用层**：
-- `core/` 编译核心（types / compiler / markdown / frontmatter / discovery）
-- 根层 `collection.ts`、`store.ts`、`query.ts`、`diff.ts` 是稳定能力
-- `scripts/` 仓内脚本（不在发布包 files 内，仅供本地开发/测试；也不作为公开 API）
-
-宿主应用负责域扩展（DomainParser）、编排脚本与内容文件所有权，通过 `exports` 里的子路径消费本 package。
-
-## 安装
-
-> 需要 Node.js ≥ 20。Package 以 TypeScript 源码形式分发（`*.ts`），宿主应通过 `tsx`、Nuxt/Vite 等支持 TS 解析的工具链使用。
-
-```bash
-# Gitee 源（当前发布前）
-npm install git+https://gitee.com/cuizhn/dexin-content.git
-
-# 发布到 npm 后
-npm install dexin-content
-```
-
-## 公开 API 边界
-
-唯一公共 API 边界是 `package.json` 中 `exports` 字段。**只使用下列路径**：
-
-| 子路径 | 暴露内容 |
-|---|---|
-| `.` | 门面：核心类型 + `DomainParserRegistry` / `compile` + `ArtifactStore` / `ContentQuery` + `defineCollection / resolveCollections / discover / compileCollections` |
-| `./core/types` | 类型：`Inline` / `DocumentBlock` / `DocumentContent` / `DocumentIdentity` / `PositiveArtifact` / `Artifact` / `Meta` / `ParseError` / `DomainParser` / `Schema` / `ParseContext` |
-| `./core/compiler` | `compile`、`CompileInput`、`CompileResult`、`DomainParserRegistry` |
-| `./core/discovery` | `buildDocumentIdentity` / `normaliseRel` / `readSourceFile` / `sanitizeSourceText` / `mkLineEndingError` |
-| `./core/frontmatter` | `splitFrontmatter` / `parseFrontmatter` / `validateSchema` / `projectMeta` |
-| `./store` | `ArtifactStore` 接口 + `createFsArtifactStore` / `createMemoryArtifactStore` + `ContentIndex` / `IndexEntry` |
-| `./collection` | `defineCollection` / `resolveCollections` / `compileCollections` / `recompileChanged` / `createLocalSource` / `createMemorySource` / `SourceAdapter` / `ResolvedCollection` / `CollectionDefinition` |
-| `./query` | `ContentQuery` (byId / byPath / list / collection) + `QueryOptions` |
-| `./diff` | `toCanonicalJSON` / `sortKeysDeep` / `stripUnderscoreKeysGolden` / `underscorePrefixedPaths` / `firstDiff` / `shortStr` |
-
-任何未列入上表的内部路径均不保证稳定。
-
-## 快速示例
-
-```ts
-import {
-  defineCollection,
-  resolveCollections,
-  createLocalSource,
-  compileCollections,
-} from 'dexin-content/collection'
-import { createFsArtifactStore } from 'dexin-content/store'
-import { ContentQuery } from 'dexin-content/query'
-import { DomainParserRegistry } from 'dexin-content/core/compiler'
-import type {
-  DomainParser,
-  DocumentContent,
-  ParseContext,
-} from 'dexin-content/core/types'
-
-// 1) 注入你的域 parser；parser 决定中性 AST 如何映射到目标 Artifact 内容结构
-const documentParser: DomainParser = {
-  domain: 'document',
-  parse(content: DocumentContent, _ctx: ParseContext) {
-    return { version: 1, blocks: content.blocks as unknown[] }
-  },
-}
-const registry = new DomainParserRegistry()
-registry.register(documentParser)
-
-// 2) 声明集合 + 编译
-const collections = resolveCollections(
-  [defineCollection({ name: 'legal', source: 'legal', domain: 'document' })],
-  '/path/to/content/root',
-)
-const source = createLocalSource('/path/to/content/root')
-const store = createFsArtifactStore('/path/to/output/dexin-content')
-await compileCollections(source, collections, registry, store)
-
-// 3) 运行时只读查询（不解析任何 Markdown）
-const query = new ContentQuery(store)
-const entry = await query.byPath('/legal/privacy')
-```
-
-## 开发
-
-```bash
-# 依赖
-npm install
-
-# 类型检查（唯一静态门禁）
-npm run typecheck
-
-# 仓内自检测（需先 build 输出 output/dexin-content/）
-npm run runtime:check
-
-# 预发布 tarball 内容检查
-npm run pack
-```
-
-## License
-
-MIT © 得心实验室。详见 [LICENSE](./LICENSE)。
+# dexin-content
+
+得心实验室的**结构化内容编译与运行时 package**。
+
+负责与具体业务领域无关的通用内容管线：
+
+- **Compile**：将带 frontmatter 的 Markdown 编译成中性 Content AST，再经宿主注入的 `DomainParser` 产出稳定的 PositiveArtifact
+- **Store**：Artifact 与索引（ContentIndex）的 FS/Memory 抽象
+- **Query**：按 id / URL path / collection / 条件过滤对 Artifact 做只读查询
+- **Collection**：集合声明、发现、批量编译与增量变化检测
+- **Diff**：Canonical JSON 序列化与对象级差异原语（Golden/Regress 管线使用）
+
+## 为内容作者
+
+- **格式规范**：[docs/content-format.md](./docs/content-format.md) —— 目录结构、front-matter、块/容器/数学语法、错误码、自检命令、投稿 SOP（§14）
+- **示例课**：[example/](./example/README.md) —— 可直接编译通过的最小内容仓样例
+- **社区投稿**：[proposals/](./proposals/README.md) —— 课程稿件投放区，PR + 门禁校验（`npm run validate:proposals`）+ 人审后迁入私有成品仓
+
+## 目录范围
+
+dexin-content 是**通用层**：
+- `core/` 编译核心（types / compiler / parser / artifact）
+- `domains/lesson/` 内置 lesson 域 parser（其余域由宿主自行注入）
+- `cli/` flow 编排（`flowBuild` / `flowPackage` / `flowValidate` / `flowCheck` / `flowServe` 库 API；**CLI 子命令仅有 `build` 与 `help`**，其余 flow 经子路径作库消费）
+- `scripts/` 仓内脚本（不在发布包 files 内，仅供本地开发/测试；也不作为公开 API）
+
+宿主应用负责域扩展（DomainParser）、编排脚本与内容文件所有权，通过 `exports` 里的子路径消费本 package。
+
+## 安装
+
+> 需要 Node.js ≥ 20。Package 以 TypeScript 源码形式分发（`*.ts`），宿主应通过 `tsx`、Nuxt/Vite 等支持 TS 解析的工具链使用。
+
+```bash
+npm install dexin-content
+```
+
+## 公开 API 边界
+
+唯一公共 API 边界是 `package.json` 中 `exports` 字段。**只使用下列路径**：
+
+| 子路径 | 暴露内容 |
+|---|---|
+| `.` | 门面：核心类型 + `DomainParserRegistry` / `compile` + `ArtifactStore` / `ContentQuery` + `defineCollection / resolveCollections / discover / compileCollections` |
+| `./core/types` | 类型：`Inline` 家族（`TextInline` / `BoldInline` / `ItalicInline` / `CodeInline` / `LinkInline` / `FormulaInline`） / `Identity` / `DocumentIdentity` / `StructuredIdentity` / `Meta` / `PositiveArtifact` / `Artifact` / `ParseError` / `ParseContext` / `Schema` / `DomainParser` / `DomainName`（LessonAST 块类型在 `./core/types/lessonAST`） |
+| `./core/compiler` | `compile`、`CompileInput`、`CompileResult`、`DomainParserRegistry` |
+| `./core/discovery` | `buildDocumentIdentity` / `buildStructuredIdentity` / `normaliseRel` / `readSourceFile` / `IdentityKind` / `CollectionConfig` / `SourceFile` |
+| `./core/frontmatter` | `splitFrontmatter` / `parseFrontmatter` / `validateSchema` / `projectMeta` |
+| `./store` | `ArtifactStore` 接口 + `createFsArtifactStore` / `createMemoryArtifactStore` + `ContentIndex` / `IndexEntry` |
+| `./collection` | `defineCollection` / `resolveCollections` / `compileCollections` / `recompileChanged` / `createLocalSource` / `createMemorySource` / `SourceAdapter` / `ResolvedCollection` / `CollectionDefinition` |
+| `./query` | `ContentQuery` (byId / byPath / list / collection) + `QueryOptions` |
+| `./diff` | `toCanonicalJSON` / `sortKeysDeep` / `stripUnderscoreKeysGolden` / `underscorePrefixedPaths` / `firstDiff` / `shortStr` |
+| `./core/markdown` | Markdown → 中性 AST 解析（`parseDocument` 等） |
+| `./core/types/lessonAST` | LessonAST 类型与常量 |
+| `./domains/lesson` | 内置 lesson 域：`lessonParser` / `buildLessonIdentity` / `mapBlocks` |
+| `./cli/build` | `flowBuild`（目录发现 → compile → Artifact Store + index.json） |
+| `./cli/package` | `flowPackage`（按 manifest 打包 ContentPackage） |
+| `./cli/validate` | `flowValidate` |
+| `./cli/check` | `flowCheck` |
+| `./cli/serve` | `flowServe`（dev preview HTTP 服务） |
+
+任何未列入上表的内部路径均不保证稳定。
+
+## 快速示例
+
+最简用法是走 CLI（仅编译内置 lesson 域）：
+
+```bash
+# 单文件：AST 打印到 stdout，失败非零退出
+npx dexin-content build example/lessons/getting-started/hello-lesson/minimal.md --domain lesson
+
+# 整树：编译 + 按 manifest 打包 ContentPackage
+npx dexin-content build example --manifest example/content-manifest.json --out /tmp/dexin-out
+```
+
+库 API（宿主自行编排时）用内置 `lessonParser` 经 `DomainParserRegistry` 注入：
+
+```ts
+import { DomainParserRegistry, compile } from 'dexin-content/core/compiler'
+import { lessonParser } from 'dexin-content/domains/lesson'
+import { buildLessonIdentity } from 'dexin-content/domains/lesson'
+
+const registry = new DomainParserRegistry()
+registry.register(lessonParser)
+
+const result = compile(
+  {
+    fixture: 'getting-started/hello-lesson/minimal',
+    domain: 'lesson',
+    identity: buildLessonIdentity('minimal', 'getting-started', 'hello-lesson', 'lessons/getting-started/hello-lesson/minimal.md'),
+    source: '---\ntitle: 最小的一节课\norder: 1\n---\n\n## 这就是全部了\n',
+    file: 'lessons/getting-started/hello-lesson/minimal.md',
+  },
+  registry,
+)
+
+if (result.kind === 'error') throw result.error
+else console.log(result.artifact.content.blocks)
+```
+
+`compile()` 永不抛异常，失败以 `{ kind: 'error', error }` 返回。域扩展由宿主注入其它 `DomainParser`。
+
+## 开发
+
+```bash
+# 依赖
+npm install
+
+# 类型检查（唯一静态门禁）
+npm run typecheck
+
+# 仓内自检测（脚本自建临时 fixture，无需任何本地产物）
+npm run runtime:check
+
+# 预发布 tarball 内容检查
+npm run pack
+```
+
+## License
+
+Apache-2.0 © 得心实验室。详见 [LICENSE](./LICENSE)。

package/cli/build.ts

@@ -157,7 +157,7 @@ async function discoverAndCompileDocuments(
 }
 
 async function writeArtifact(outDir: string, artifact: PositiveArtifact): Promise<void> {
-  const outFile = path.join(outDir, 'lessons', artifact.fixture + '.json')
+  const outFile = path.join(outDir, 'content', artifact.fixture + '.json')
   await mkdir(path.dirname(outFile), { recursive: true })
   await writeFile(outFile, JSON.stringify(artifact, null, 2) + '\n', 'utf-8')
 }
@@ -183,6 +183,6 @@ async function walkMdFiles(dir: string): Promise<string[]> {
   }
   return out.sort()
 }
-
-
-
+
+
+