dexin-content 0.1.2 → 0.2.0

package/{diff.ts → core/artifact/diff.ts}

@@ -1,124 +1,125 @@
-// ─────────────────────────────────────────────────────────────
-// dexin-content/diff.ts — 共享 Canonical/Diff 原语
-//
-// 统一 CANONICALIZE 语义：
-//   * Golden 侧递归剥离 `_` 前缀键（CANONICALIZE Rule 1）
-//   * Candidate 侧 `_` 前缀键路径扫描（CANONICALIZE Rule 2）
-//   * 对象级 firstDiff（键序不敏感，首差异 JSON-path）
-//   * Canonical JSON 序列化（2 空格、键字典序、LF、末换行、
-//     Unicode 不转义、U+2028/U+2029 转义）
-// ─────────────────────────────────────────────────────────────
-
-export interface DiffResult {
-  path: string
-  expected: unknown
-  actual: unknown
-}
-
-// ── 对象与键工具 ──────────────────────────────────────────
-
-export function isPlainObject (v: unknown): v is Record<string, unknown> {
-  return !!v && typeof v === 'object' && !Array.isArray(v)
-}
-
-// ── 1) Canonical JSON 序列化 ─────────────────────────────
-//    规则：2 空格缩进 + 对象每层级键字典序 + LF 换行 + 尾部换行 +
-//          Unicode 原文保留（不 \u 转义，除 JSON 强制字符）+
-//          行分隔符 U+2028 / 段分隔符 U+2029 转义（老 JS 引擎兼容）。
-
-export function toCanonicalJSON (value: unknown): string {
-  return JSON.stringify(sortKeysDeep(value), null, 2)
-    .split('\r\n').join('\n')
-    .split('\u2028').join('\\u2028')
-    .split('\u2029').join('\\u2029') + '\n'
-}
-
-export function sortKeysDeep (v: unknown): unknown {
-  if (Array.isArray(v)) return v.map(sortKeysDeep)
-  if (isPlainObject(v)) {
-    const keys = Object.keys(v).sort()
-    const out: Record<string, unknown> = {}
-    for (const k of keys) out[k] = sortKeysDeep((v as Record<string, unknown>)[k])
-    return out
-  }
-  return v
-}
-
-// ── 2) Golden 侧 _ 键递归剥离（CANONICALIZE §3 Rule 1 v1.1） ─
-//    只剥离 Golden。Candidate 若含 _ 前缀键，属于 Rule 2 违规，
-//    应走 underscorePrefixedPaths 判 FAIL，绝不在 diff 中掩盖。
-
-export function stripUnderscoreKeysGolden (obj: unknown): unknown {
-  if (Array.isArray(obj)) return obj.map(stripUnderscoreKeysGolden)
-  if (isPlainObject(obj)) {
-    const out: Record<string, unknown> = {}
-    for (const k of Object.keys(obj)) {
-      if (k.startsWith('_')) continue
-      out[k] = stripUnderscoreKeysGolden((obj as Record<string, unknown>)[k])
-    }
-    return out
-  }
-  return obj
-}
-
-// ── 3) Candidate/B3 侧全层级 _ 前缀键扫描 ─────────────────
-//    返回 JSON-path 字符串数组（空 = 干净）。
-
-export function underscorePrefixedPaths (obj: unknown): string[] {
-  const out: string[] = []
-  walk(obj, '$')
-  return out
-  function walk (v: unknown, at: string): void {
-    if (Array.isArray(v)) {
-      for (let i = 0; i < v.length; i++) walk(v[i], `${at}[${i}]`)
-      return
-    }
-    if (isPlainObject(v)) {
-      for (const k of Object.keys(v)) {
-        if (k.startsWith('_')) out.push(`${at}.${k}`)
-        walk((v as Record<string, unknown>)[k], `${at}.${k}`)
-      }
-    }
-  }
-}
-
-// ── 4) 对象级 firstDiff（键序不敏感） ─────────────────────
-//    返回 null（相等）或首个差异（JSON-path + 两边值）。
-//    相等判定使用 Object.is —— NaN 对 NaN 视为相等。
-
-export function firstDiff (actual: unknown, expected: unknown, root: string): DiffResult | null {
-  if (isPlainObject(expected) && isPlainObject(actual)) {
-    const keys = Array.from(
-      new Set([...Object.keys(expected), ...Object.keys(actual)])
-    ).sort()
-    for (const k of keys) {
-      const e = (expected as Record<string, unknown>)[k]
-      const a = (actual as Record<string, unknown>)[k]
-      if (!(k in (expected as object))) {
-        return { path: `${root}.${k}`, expected: '<absent>', actual: shortStr(a) }
-      }
-      if (!(k in (actual as object))) {
-        return { path: `${root}.${k}`, expected: shortStr(e), actual: '<absent>' }
-      }
-      const sub = firstDiff(a, e, `${root}.${k}`)
-      if (sub) return sub
-    }
-    return null
-  }
-  if (Array.isArray(expected) && Array.isArray(actual)) {
-    if (expected.length !== actual.length) {
-      return { path: root + '.length', expected: expected.length, actual: actual.length }
-    }
-    for (let i = 0; i < expected.length; i++) {
-      const sub = firstDiff(actual[i], expected[i], `${root}[${i}]`)
-      if (sub) return sub
-    }
-    return null
-  }
-  if (Object.is(actual, expected)) return null
-  return { path: root, expected, actual }
-}
-
-export function shortStr (v: unknown): string {
-  try { return JSON.stringify(v) } catch { return String(v) }
-}
+// ─────────────────────────────────────────────────────────────
+// dexin-content/diff.ts — 共享 Canonical/Diff 原语
+//
+// 统一 run-p0.ts 与 regression.ts 的 CANONICALIZE 语义。这是 P0
+// 阶段唯一可信的：
+//   * Golden 侧递归剥离 `_` 前缀键（CANONICALIZE §3 Rule 1 v1.1）
+//   * Candidate 侧 `_` 前缀键路径扫描（CANONICALIZE §3 Rule 2 v1.1）
+//   * 对象级 firstDiff（键序不敏感，首差异 JSON-path）
+//   * Canonical JSON 序列化（2 空格、键字典序、LF、末换行、
+//     Unicode 不转义、U+2028/U+2029 转义）
+// ─────────────────────────────────────────────────────────────
+
+export interface DiffResult {
+  path: string
+  expected: unknown
+  actual: unknown
+}
+
+// ── 对象与键工具 ──────────────────────────────────────────
+
+export function isPlainObject (v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === 'object' && !Array.isArray(v)
+}
+
+// ── 1) Canonical JSON 序列化 ─────────────────────────────
+//    规则：2 空格缩进 + 对象每层级键字典序 + LF 换行 + 尾部换行 +
+//          Unicode 原文保留（不 \u 转义，除 JSON 强制字符）+
+//          行分隔符 U+2028 / 段分隔符 U+2029 转义（老 JS 引擎兼容）。
+
+export function toCanonicalJSON (value: unknown): string {
+  return JSON.stringify(sortKeysDeep(value), null, 2)
+    .split('\r\n').join('\n')
+    .split('\u2028').join('\\u2028')
+    .split('\u2029').join('\\u2029') + '\n'
+}
+
+export function sortKeysDeep (v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(sortKeysDeep)
+  if (isPlainObject(v)) {
+    const keys = Object.keys(v).sort()
+    const out: Record<string, unknown> = {}
+    for (const k of keys) out[k] = sortKeysDeep((v as Record<string, unknown>)[k])
+    return out
+  }
+  return v
+}
+
+// ── 2) Golden 侧 _ 键递归剥离（CANONICALIZE §3 Rule 1 v1.1） ─
+//    只剥离 Golden。Candidate 若含 _ 前缀键，属于 Rule 2 违规，
+//    应走 underscorePrefixedPaths 判 FAIL，绝不在 diff 中掩盖。
+
+export function stripUnderscoreKeysGolden (obj: unknown): unknown {
+  if (Array.isArray(obj)) return obj.map(stripUnderscoreKeysGolden)
+  if (isPlainObject(obj)) {
+    const out: Record<string, unknown> = {}
+    for (const k of Object.keys(obj)) {
+      if (k.startsWith('_')) continue
+      out[k] = stripUnderscoreKeysGolden((obj as Record<string, unknown>)[k])
+    }
+    return out
+  }
+  return obj
+}
+
+// ── 3) Candidate/B3 侧全层级 _ 前缀键扫描 ─────────────────
+//    返回 JSON-path 字符串数组（空 = 干净）。
+
+export function underscorePrefixedPaths (obj: unknown): string[] {
+  const out: string[] = []
+  walk(obj, '$')
+  return out
+  function walk (v: unknown, at: string): void {
+    if (Array.isArray(v)) {
+      for (let i = 0; i < v.length; i++) walk(v[i], `${at}[${i}]`)
+      return
+    }
+    if (isPlainObject(v)) {
+      for (const k of Object.keys(v)) {
+        if (k.startsWith('_')) out.push(`${at}.${k}`)
+        walk((v as Record<string, unknown>)[k], `${at}.${k}`)
+      }
+    }
+  }
+}
+
+// ── 4) 对象级 firstDiff（键序不敏感） ─────────────────────
+//    返回 null（相等）或首个差异（JSON-path + 两边值）。
+//    相等判定使用 Object.is —— NaN 对 NaN 视为相等。
+
+export function firstDiff (actual: unknown, expected: unknown, root: string): DiffResult | null {
+  if (isPlainObject(expected) && isPlainObject(actual)) {
+    const keys = Array.from(
+      new Set([...Object.keys(expected), ...Object.keys(actual)])
+    ).sort()
+    for (const k of keys) {
+      const e = (expected as Record<string, unknown>)[k]
+      const a = (actual as Record<string, unknown>)[k]
+      if (!(k in (expected as object))) {
+        return { path: `${root}.${k}`, expected: '<absent>', actual: shortStr(a) }
+      }
+      if (!(k in (actual as object))) {
+        return { path: `${root}.${k}`, expected: shortStr(e), actual: '<absent>' }
+      }
+      const sub = firstDiff(a, e, `${root}.${k}`)
+      if (sub) return sub
+    }
+    return null
+  }
+  if (Array.isArray(expected) && Array.isArray(actual)) {
+    if (expected.length !== actual.length) {
+      return { path: root + '.length', expected: expected.length, actual: actual.length }
+    }
+    for (let i = 0; i < expected.length; i++) {
+      const sub = firstDiff(actual[i], expected[i], `${root}[${i}]`)
+      if (sub) return sub
+    }
+    return null
+  }
+  if (Object.is(actual, expected)) return null
+  return { path: root, expected, actual }
+}
+
+export function shortStr (v: unknown): string {
+  try { return JSON.stringify(v) } catch { return String(v) }
+}

package/{query.ts → core/artifact/query.ts}

@@ -1,56 +1,56 @@
-// ─────────────────────────────────────────────────────────────
-// dexin-content/query.ts
-//
-// Runtime query — read-only over Artifact store.
-//
-// Query NEVER parses Markdown. No index → throw. byPath/byId
-// return PositiveArtifact (with content.blocks); collection/list
-// return IndexEntry[] (metadata + routing only).
-//
-// grep-zero: no business vocabulary appears anywhere in this
-// module — including error messages.
-// ─────────────────────────────────────────────────────────────
-
-import type { PositiveArtifact } from './core/types'
-import type { ArtifactStore, IndexEntry } from './store'
-
-export interface QueryOptions {
-  where?: (entry: IndexEntry) => boolean
-  sort?: (a: IndexEntry, b: IndexEntry) => number
-  limit?: number
-}
-
-export class ContentQuery {
-  constructor (private store: ArtifactStore) {}
-
-  /** List all entries (optionally filtered to one collection). */
-  async list (collection?: string, opts: QueryOptions = {}): Promise<IndexEntry[]> {
-    const index = await this.store.readIndex()
-    if (!index) throw new Error('[Query] No index — run compile first (runtime never reparses source).')
-    let rows = collection ? index.entries.filter(e => e.collection === collection) : [...index.entries]
-    if (opts.where) rows = rows.filter(opts.where)
-    if (opts.sort) rows.sort(opts.sort)
-    if (opts.limit != null) rows = rows.slice(0, opts.limit)
-    return rows
-  }
-
-  /** Fetch single doc by URL path. Returns null if not found. */
-  async byPath (path: string): Promise<PositiveArtifact | null> {
-    const norm = path.replace(/\/+$/, '') || '/'
-    const index = await this.store.readIndex()
-    if (!index) throw new Error('[Query] No index — run compile first.')
-    const entry = index.entries.find(e => e.path === norm)
-    if (!entry) return null
-    return this.store.readDoc(entry.id)
-  }
-
-  /** Fetch single doc by stable id (= PositiveArtifact.id). */
-  async byId (id: string): Promise<PositiveArtifact | null> {
-    return this.store.readDoc(id)
-  }
-
-  /** List metadata entries for a collection (host runtime usage). */
-  async collection (name: string, opts: QueryOptions = {}): Promise<IndexEntry[]> {
-    return this.list(name, opts)
-  }
-}
+// ─────────────────────────────────────────────────────────────
+// dexin-content/query.ts
+//
+// Runtime query — read-only over Artifact store (API-FREEZE §3.6).
+//
+// Query NEVER parses Markdown. No index → throw. byPath/byId
+// return PositiveArtifact (with content.blocks); collection/list
+// return IndexEntry[] (metadata + routing only).
+//
+// grep-zero: no business vocabulary appears anywhere in this
+// module — including error messages.
+// ─────────────────────────────────────────────────────────────
+
+import type { PositiveArtifact } from '../types'
+import type { ArtifactStore, IndexEntry } from './store'
+
+export interface QueryOptions {
+  where?: (entry: IndexEntry) => boolean
+  sort?: (a: IndexEntry, b: IndexEntry) => number
+  limit?: number
+}
+
+export class ContentQuery {
+  constructor (private store: ArtifactStore) {}
+
+  /** List all entries (optionally filtered to one collection). */
+  async list (collection?: string, opts: QueryOptions = {}): Promise<IndexEntry[]> {
+    const index = await this.store.readIndex()
+    if (!index) throw new Error('[Query] No index — run compile first (runtime never reparses source).')
+    let rows = collection ? index.entries.filter(e => e.collection === collection) : [...index.entries]
+    if (opts.where) rows = rows.filter(opts.where)
+    if (opts.sort) rows.sort(opts.sort)
+    if (opts.limit != null) rows = rows.slice(0, opts.limit)
+    return rows
+  }
+
+  /** Fetch single doc by URL path. Returns null if not found. */
+  async byPath (path: string): Promise<PositiveArtifact | null> {
+    const norm = path.replace(/\/+$/, '') || '/'
+    const index = await this.store.readIndex()
+    if (!index) throw new Error('[Query] No index — run compile first.')
+    const entry = index.entries.find(e => e.path === norm)
+    if (!entry) return null
+    return this.store.readDoc(entry.id)
+  }
+
+  /** Fetch single doc by stable id (= PositiveArtifact.fixture). */
+  async byId (id: string): Promise<PositiveArtifact | null> {
+    return this.store.readDoc(id)
+  }
+
+  /** List metadata entries for a collection (host runtime usage). */
+  async collection (name: string, opts: QueryOptions = {}): Promise<IndexEntry[]> {
+    return this.list(name, opts)
+  }
+}

package/{store.ts → core/artifact/store.ts}

@@ -1,128 +1,128 @@
-// ─────────────────────────────────────────────────────────────
-// dexin-content/store.ts
-//
-// Artifact storage abstraction.
-//
-// The stored Doc shape IS the formal-layer PositiveArtifact
-// (core/types.ts contract). No second Doc alias is introduced;
-// the Store reads/writes the exact shape the compiler emits.
-//
-// The Index (ContentIndex / IndexEntry) is the routing overlay layer:
-//   IndexEntry.id maps to PositiveArtifact.id.
-//   IndexEntry.path/file/collection are path-derived routing info
-//   independent of the domain-specific identity inside the Artifact.
-//
-// grep-zero: no business vocabulary appears anywhere in this
-// module — including error messages.
-// ─────────────────────────────────────────────────────────────
-
-import { mkdir, writeFile, readFile, access } from 'node:fs/promises'
-import { dirname } from 'node:path'
-import type { PositiveArtifact, Meta } from './core/types'
-import { toCanonicalJSON } from './diff'
-
-// ── Index types ──
-
-export interface IndexEntry {
-  /** Stable doc id; equals PositiveArtifact.id. */
-  id: string
-  /** URL semantic path: '/' + id. */
-  path: string
-  /** Owning collection name. */
-  collection: string
-  /** Domain tag (consistent with Artifact.domain). */
-  domain: string
-  /** Physical path relative to content root, INCLUDING .md. */
-  file: string
-  /** Scalar-only frontmatter projection. */
-  meta: Meta
-  /** First 12 hex chars of body md5 (change detection). */
-  checksum: string
-}
-
-export interface ContentIndex {
-  generator: 'dexin-content'
-  builtAt: string
-  entries: IndexEntry[]
-}
-
-// ── Store interface ──
-
-export interface ArtifactStore {
-  writeIndex(index: ContentIndex): Promise<void>
-  writeDoc(doc: PositiveArtifact): Promise<void>
-  readIndex(): Promise<ContentIndex | null>
-  readDoc(id: string): Promise<PositiveArtifact | null>
-}
-
-// ── File-system store ──
-
-export interface FsOps {
-  mkdir(p: string): Promise<void>
-  writeFile(p: string, data: string): Promise<void>
-  readFile(p: string): Promise<string>
-  exists(p: string): Promise<boolean>
-}
-
-const defaultFsOps: FsOps = {
-  async mkdir (p) { await mkdir(p, { recursive: true }) },
-  async writeFile (p, data) { await writeFile(p, data, 'utf8') },
-  async readFile (p) { return readFile(p, 'utf8') },
-  async exists (p) { try { await access(p); return true } catch { return false } }
-}
-
-/**
- * File-system Artifact Store.
- * Layout: <baseDir>/index.json + <baseDir>/docs/<id>.json
- * Docs are serialised via toCanonicalJSON (2-space, key-lexicographic,
- * LF, trailing newline) to match the canonical Artifact form.
- */
-export function createFsArtifactStore (
-  baseDir: string,
-  fsOps: FsOps = defaultFsOps
-): ArtifactStore {
-  const idxPath = () => `${baseDir}/index.json`
-  const docPath = (id: string) => `${baseDir}/docs/${id}.json`
-
-  return {
-    async writeIndex (index) {
-      await fsOps.mkdir(baseDir)
-      await fsOps.writeFile(idxPath(), toCanonicalJSON(index))
-    },
-
-    async writeDoc (doc) {
-      const p = docPath(doc.id)
-      await fsOps.mkdir(dirname(p))
-      await fsOps.writeFile(p, toCanonicalJSON(doc))
-    },
-
-    async readIndex () {
-      if (!(await fsOps.exists(idxPath()))) return null
-      return JSON.parse(await fsOps.readFile(idxPath())) as ContentIndex
-    },
-
-    async readDoc (id) {
-      if (!(await fsOps.exists(docPath(id)))) return null
-      return JSON.parse(await fsOps.readFile(docPath(id))) as PositiveArtifact
-    }
-  }
-}
-
-// ── Memory store (Dev / test) ──
-
-export interface MemoryStore extends ArtifactStore {
-  snapshot(): { index: ContentIndex | null; docs: Map<string, PositiveArtifact> }
-}
-
-export function createMemoryArtifactStore (): MemoryStore {
-  let index: ContentIndex | null = null
-  const docs = new Map<string, PositiveArtifact>()
-
-  return {
-    async writeIndex (i) { index = i },
-    async writeDoc (d) { docs.set(d.id, d) },
-    async readIndex () { return index },
-    async readDoc (id) { return docs.get(id) ?? null },
-    snapshot () { return { index, docs } }
-  }
-}
+// ─────────────────────────────────────────────────────────────
+// dexin-content/store.ts
+//
+// Artifact storage abstraction (API-FREEZE §3.5).
+//
+// The stored Doc shape IS the formal-layer PositiveArtifact
+// (core/types.ts frozen form). No second Doc alias is introduced;
+// the Store reads/writes the exact shape golden expected freezes.
+//
+// The Index (ContentIndex / IndexEntry) is the routing overlay layer:
+//   IndexEntry.id maps to PositiveArtifact.fixture.
+//   IndexEntry.path/file/collection are path-derived routing info
+//   independent of the domain-specific identity inside the Artifact.
+//
+// grep-zero: no business vocabulary appears anywhere in this
+// module — including error messages.
+// ─────────────────────────────────────────────────────────────
+
+import { mkdir, writeFile, readFile, access } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import type { PositiveArtifact, Meta } from '../types'
+import { toCanonicalJSON } from './diff'
+
+// ── Index types (prototype shape, API-FREEZE §2.2) ──
+
+export interface IndexEntry {
+  /** Stable doc id; equals PositiveArtifact.fixture. */
+  id: string
+  /** URL semantic path: '/' + id. */
+  path: string
+  /** Owning collection name. */
+  collection: string
+  /** Domain tag (consistent with Artifact.domain). */
+  domain: string
+  /** Physical path relative to content root, INCLUDING .md. */
+  file: string
+  /** Scalar-only frontmatter projection. */
+  meta: Meta
+  /** First 12 hex chars of body md5 (change detection). */
+  checksum: string
+}
+
+export interface ContentIndex {
+  generator: 'dexin-content'
+  builtAt: string
+  entries: IndexEntry[]
+}
+
+// ── Store interface ──
+
+export interface ArtifactStore {
+  writeIndex(index: ContentIndex): Promise<void>
+  writeDoc(doc: PositiveArtifact): Promise<void>
+  readIndex(): Promise<ContentIndex | null>
+  readDoc(id: string): Promise<PositiveArtifact | null>
+}
+
+// ── File-system store ──
+
+export interface FsOps {
+  mkdir(p: string): Promise<void>
+  writeFile(p: string, data: string): Promise<void>
+  readFile(p: string): Promise<string>
+  exists(p: string): Promise<boolean>
+}
+
+const defaultFsOps: FsOps = {
+  async mkdir (p) { await mkdir(p, { recursive: true }) },
+  async writeFile (p, data) { await writeFile(p, data, 'utf8') },
+  async readFile (p) { return readFile(p, 'utf8') },
+  async exists (p) { try { await access(p); return true } catch { return false } }
+}
+
+/**
+ * File-system Artifact Store.
+ * Layout: <baseDir>/index.json + <baseDir>/lessons/<id>.json
+ * Docs are serialised via toCanonicalJSON (2-space, key-lexicographic,
+ * LF, trailing newline) to match golden candidate form.
+ */
+export function createFsArtifactStore (
+  baseDir: string,
+  fsOps: FsOps = defaultFsOps
+): ArtifactStore {
+  const idxPath = () => `${baseDir}/index.json`
+  const docPath = (id: string) => `${baseDir}/lessons/${id}.json`
+
+  return {
+    async writeIndex (index) {
+      await fsOps.mkdir(baseDir)
+      await fsOps.writeFile(idxPath(), toCanonicalJSON(index))
+    },
+
+    async writeDoc (doc) {
+      const p = docPath(doc.fixture)
+      await fsOps.mkdir(dirname(p))
+      await fsOps.writeFile(p, toCanonicalJSON(doc))
+    },
+
+    async readIndex () {
+      if (!(await fsOps.exists(idxPath()))) return null
+      return JSON.parse(await fsOps.readFile(idxPath())) as ContentIndex
+    },
+
+    async readDoc (id) {
+      if (!(await fsOps.exists(docPath(id)))) return null
+      return JSON.parse(await fsOps.readFile(docPath(id))) as PositiveArtifact
+    }
+  }
+}
+
+// ── Memory store (Dev / test) ──
+
+export interface MemoryStore extends ArtifactStore {
+  snapshot(): { index: ContentIndex | null; docs: Map<string, PositiveArtifact> }
+}
+
+export function createMemoryArtifactStore (): MemoryStore {
+  let index: ContentIndex | null = null
+  const docs = new Map<string, PositiveArtifact>()
+
+  return {
+    async writeIndex (i) { index = i },
+    async writeDoc (d) { docs.set(d.fixture, d) },
+    async readIndex () { return index },
+    async readDoc (id) { return docs.get(id) ?? null },
+    snapshot () { return { index, docs } }
+  }
+}