dexin-content 0.1.1 → 0.2.0

package/core/validator/integrity.ts

@@ -0,0 +1,199 @@
+// ─────────────────────────────────────────────────────────────
+// dexin-content/runtime-check.ts — Runtime flow (B1-SPEC T5.3 / ARCH-REPORT §8)
+//
+// Reads pre-compiled artifacts from output/dexin-content/ via ContentQuery.
+// Asserts structural correctness of the read-back artifacts.
+//
+// ZERO MARKDOWN PARSING PROOF (B1-SPEC T5.3):
+//   This module imports ONLY from:
+//     - ./store        (fs/memory store + ContentIndex types; markdown-free)
+//     - ./query        (ContentQuery; markdown-free)
+//     - ./core/types   (type-only imports, erased at compile time)
+//     - node:*         (built-in modules)
+//   It does NOT import: markdown, remark, unified, core/compiler,
+//   core/frontmatter, core/markdown, domain/*, collection (which
+//   transitively imports the compiler). The runtime path reads
+//   pre-compiled artifacts from output/ and never reparses source.
+//
+//   Transitive dependency audit:
+//     store.ts  → node:fs/promises, node:path, ./core/types (types), ./diff
+//     query.ts  → ./core/types (types), ./store
+//     diff.ts   → (zero imports — pure JSON/Object operations)
+//   No markdown/remark/unified anywhere in the runtime import graph.
+//
+// grep-zero: no business vocabulary appears anywhere in this
+// module — including error messages.
+// ─────────────────────────────────────────────────────────────
+
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+
+import type { PositiveArtifact } from '../types'
+import { createFsArtifactStore, createMemoryArtifactStore, type ArtifactStore } from '../artifact/store'
+import { ContentQuery } from '../artifact/query'
+
+const __filename = fileURLToPath(import.meta.url)
+const ROOT = join(__filename, '..', '..')
+const OUTPUT_DIR = join(ROOT, 'output', 'dexin-content')
+
+// ── Helpers ──────────────────────────────────────────────
+
+let pass = 0
+let fail = 0
+const errors: string[] = []
+
+function ok (label: string): void {
+  pass++
+  console.log(`  ✅ ${label}`)
+}
+
+function ko (label: string, detail: string): void {
+  fail++
+  errors.push(`${label}: ${detail}`)
+  console.log(`  ❌ ${label}: ${detail}`)
+}
+
+function assertArtifact (label: string, doc: PositiveArtifact | null, expectDomain: string, expectId: string): void {
+  if (doc === null) { ko(label, 'returned null'); return }
+  if (doc.domain !== expectDomain) { ko(label, `domain=${doc.domain} (expected ${expectDomain})`); return }
+  if (doc.fixture !== expectId) { ko(label, `fixture=${doc.fixture} (expected ${expectId})`); return }
+  if (!doc.content?.blocks?.length) { ko(label, 'content.blocks empty or missing'); return }
+  if (!doc.identity) { ko(label, 'identity missing'); return }
+  if (!doc.meta) { ko(label, 'meta missing'); return }
+  ok(label)
+}
+
+// ── R1: byPath on legal/privacy + about ───────────────────
+
+async function checkR1 (query: ContentQuery): Promise<void> {
+  console.log('── R1: query.byPath ──')
+  const privacy = await query.byPath('/legal/privacy')
+  assertArtifact('R1 byPath(/legal/privacy)', privacy, 'document', 'legal/privacy')
+
+  const about = await query.byPath('/about')
+  assertArtifact('R1 byPath(/about)', about, 'document', 'about')
+
+  const notFound = await query.byPath('/nonexistent')
+  if (notFound !== null) ko('R1 byPath(/nonexistent)', 'should be null')
+  else ok('R1 byPath(/nonexistent) → null')
+}
+
+// ── R2: byId ─────────────────────────────────────────────
+
+async function checkR2 (query: ContentQuery): Promise<void> {
+  console.log('── R2: query.byId ──')
+  const byIdPrivacy = await query.byId('legal/privacy')
+  assertArtifact('R2 byId(legal/privacy)', byIdPrivacy, 'document', 'legal/privacy')
+
+  const byIdAbout = await query.byId('about')
+  assertArtifact('R2 byId(about)', byIdAbout, 'document', 'about')
+
+  const byIdMissing = await query.byId('does/not/exist')
+  if (byIdMissing !== null) ko('R2 byId(missing)', 'should be null')
+  else ok('R2 byId(missing) → null')
+}
+
+// ── R3: collection ───────────────────────────────────────
+
+async function checkR3 (query: ContentQuery): Promise<void> {
+  console.log('── R3: query.collection ──')
+  const legal = await query.collection('legal')
+  if (legal.length !== 1) ko('R3 collection(legal)', `len=${legal.length}`)
+  else if (legal[0].id !== 'legal/privacy') ko('R3 collection(legal)', `id=${legal[0].id}`)
+  else ok('R3 collection(legal) → 1 entry (legal/privacy)')
+
+  const about = await query.collection('about')
+  if (about.length !== 1) ko('R3 collection(about)', `len=${about.length}`)
+  else if (about[0].id !== 'about') ko('R3 collection(about)', `id=${about[0].id}`)
+  else ok('R3 collection(about) → 1 entry (about)')
+}
+
+// ── R4: list with where/sort/limit ───────────────────────
+
+async function checkR4 (query: ContentQuery): Promise<void> {
+  console.log('── R4: query.list ──')
+  const all = await query.list()
+  if (all.length !== 2) ko('R4 list()', `len=${all.length}`)
+  else ok('R4 list() → 2 entries')
+
+  const legalOnly = await query.list('legal')
+  if (legalOnly.length !== 1) ko('R4 list(legal)', `len=${legalOnly.length}`)
+  else ok('R4 list(legal) → 1 entry')
+
+  const sorted = await query.list(undefined, { sort: (a, b) => a.id.localeCompare(b.id) })
+  if (sorted.length !== 2) ko('R4 list(sort)', `len=${sorted.length}`)
+  else ok('R4 list(sort) → 2 sorted')
+
+  const limited = await query.list(undefined, { limit: 1 })
+  if (limited.length !== 1) ko('R4 list(limit=1)', `len=${limited.length}`)
+  else ok('R4 list(limit=1) → 1 entry')
+
+  const filtered = await query.list(undefined, { where: e => e.collection === 'legal' })
+  if (filtered.length !== 1) ko('R4 list(where=legal)', `len=${filtered.length}`)
+  else ok('R4 list(where=legal) → 1 entry')
+}
+
+// ── R5: no-index → throw (zero-parse invariant) ─────────
+
+async function checkR5 (): Promise<void> {
+  console.log('── R5: no-index → throw (zero-parse invariant) ──')
+  const emptyStore = createMemoryArtifactStore()
+  const query = new ContentQuery(emptyStore)
+  try {
+    await query.byPath('/legal/privacy')
+    ko('R5 byPath no-index', 'should have thrown')
+  } catch (e) {
+    const msg = (e as Error).message
+    if (msg.includes('No index')) ok('R5 byPath no-index → throws')
+    else ko('R5 byPath no-index', `wrong message: ${msg}`)
+  }
+  try {
+    await query.list()
+    ko('R5 list no-index', 'should have thrown')
+  } catch (e) {
+    const msg = (e as Error).message
+    if (msg.includes('No index')) ok('R5 list no-index → throws')
+    else ko('R5 list no-index', `wrong message: ${msg}`)
+  }
+}
+
+// ── R6: deep-equal byPath vs byId (store round-trip) ────
+
+async function checkR6 (query: ContentQuery): Promise<void> {
+  console.log('── R6: byPath vs byId deep-equal (round-trip) ──')
+  const byPath = await query.byPath('/legal/privacy')
+  const byId = await query.byId('legal/privacy')
+  if (byPath === null || byId === null) { ko('R6 deep-equal', 'one or both null'); return }
+  if (byPath.fixture !== byId.fixture) { ko('R6 deep-equal', 'fixture mismatch'); return }
+  if (byPath.domain !== byId.domain) { ko('R6 deep-equal', 'domain mismatch'); return }
+  if (byPath.content.blocks.length !== byId.content.blocks.length) { ko('R6 deep-equal', 'blocks length mismatch'); return }
+  ok('R6 byPath(/legal/privacy) deep-equal byId(legal/privacy)')
+}
+
+// ── Main ─────────────────────────────────────────────────
+
+async function main (): Promise<void> {
+  console.log('── runtime:check ──')
+  console.log(`  output dir: ${OUTPUT_DIR}`)
+
+  const store: ArtifactStore = createFsArtifactStore(OUTPUT_DIR)
+  const query = new ContentQuery(store)
+
+  await checkR1(query)
+  await checkR2(query)
+  await checkR3(query)
+  await checkR4(query)
+  await checkR5()
+  await checkR6(query)
+
+  console.log(`\n──────── runtime:check summary ────────`)
+  console.log(`${pass} pass, ${fail} fail`)
+  if (fail > 0) {
+    console.log('\nFailures:')
+    for (const e of errors) console.log(`  - ${e}`)
+    process.exit(1)
+  }
+  process.exit(0)
+}
+
+void main()

package/domains/document/identity.ts

@@ -0,0 +1,27 @@
+/**
+ * DocumentIdentity — dexinlabs-specific identity builder for document content.
+ *
+ * Maps page slugs to DocumentIdentity shape with collection='pages'.
+ *
+ * This keeps dexin-content generic while allowing dexinlabs to maintain
+ * its document/page organization.
+ */
+import type { DocumentIdentity } from '../../core/types/index'
+
+/**
+ * Build a DocumentIdentity for a page file.
+ *
+ * @param slug - Page identifier (e.g., 'about', 'privacy')
+ * @param relPath - Relative path from content root (e.g., 'pages/about.md')
+ */
+export function buildDocumentIdentity(
+  slug: string,
+  relPath: string
+): DocumentIdentity {
+  return {
+    id: slug,
+    path: `/${slug}`,
+    file: relPath,
+    collection: 'pages'
+  }
+}

package/domains/document/index.ts

@@ -0,0 +1,5 @@
+/**
+ * document-domain barrel
+ */
+export { documentParser } from './parser'
+export { buildDocumentIdentity } from './identity'

package/domains/document/parser.ts

@@ -0,0 +1,105 @@
+// ─────────────────────────────────────────────────────────────
+// domains/document/parser.ts
+//
+// Document domain parser. Identity behaviour defined in §6.3.15 frozen.
+//
+// Content behaviour:
+//   * Heading = straight docAST heading (h1→1, h2→2, h3→3, h4→4; no
+//     absorption, no downgrade).
+//   * md h5/h6 → DOC_HEADING_DEPTH_UNDEFINED (6.3.10 frozen: ERROR)。
+//   * No section grouping (6.3.11 frozen).
+//   * ContainerBlock (6.3.12) stays neutral (never re-mapped to domain blocks).
+//   * Plain blocks pass through unchanged from DocumentAST.
+//   * `mdDepth` 属 transient 辅助注解：clone/render 路径显式剔除。
+// ─────────────────────────────────────────────────────────────
+
+import type {
+  DomainParser,
+  ParseContext,
+  ParseError
+} from '../../core/types/index'
+import type { LessonContent, Block, HeadingBlock } from '../../core/types/lessonAST'
+
+export const documentParser: DomainParser = {
+  domain: 'document',
+  parse (content: LessonContent, ctx: ParseContext): LessonContent {
+    // Pre-pass: document-domain heading depth fail-fast (6.3.10).
+    walkAndEnforceHeadingDepth(content.blocks, ctx)
+
+    // Deep-copy structural nodes so future mutations to docAST do not leak.
+    return { version: 1, blocks: cloneBlocks(content.blocks) }
+  }
+}
+
+function walkAndEnforceHeadingDepth (blocks: Block[], ctx: ParseContext): void {
+  for (const b of blocks) {
+    if (b.type === 'heading') {
+      const mdDepth = (b as HeadingBlock).mdDepth ?? b.level
+      if (mdDepth > 4) {
+        const err = new Error(
+          `[DOC_HEADING_DEPTH_UNDEFINED] Document domain only supports h1–h4. ` +
+          `Encountered h${mdDepth} (heading level ${mdDepth}): no mapping defined per 6.3.10 frozen table. ` +
+          `Allowed heading markdown depths: 1–4. Silently capping to level 4 is forbidden (information loss). ` +
+          `file: ${ctx.file}`
+        ) as ParseError & Error
+        err.code = 'DOC_HEADING_DEPTH_UNDEFINED'
+        err.file = ctx.file
+        err.loc = { headingDepth: mdDepth, allowed: 'h1-h4' }
+        throw err
+      }
+    }
+    if (b.type === 'quote') walkAndEnforceHeadingDepth(b.children, ctx)
+    if (b.type === 'container') walkAndEnforceHeadingDepth(b.children, ctx)
+  }
+}
+
+function cloneBlocks (xs: Block[]): Block[] {
+  return xs.map(b => {
+    switch (b.type) {
+      case 'paragraph': return { type:'paragraph', children: cloneInlineArr(b.children) }
+      case 'heading': {
+        // Drop transient mdDepth — canonical output never contains it.
+        return { type:'heading', level: b.level, children: cloneInlineArr(b.children) }
+      }
+      case 'quote':     return { type:'quote',     children: cloneBlocks(b.children) }
+      case 'divider':   return { type:'divider' }
+      case 'list':      return {
+        type:'list', ordered: b.ordered,
+        items: b.items.map(row => row.map(cloneInline))
+      }
+      case 'table':     return {
+        type:'table',
+        headers: b.headers.map(c => c.map(cloneInline)),
+        rows:    b.rows.map(r => r.map(c => c.map(cloneInline)))
+      }
+      case 'image':     return { type:'image', src:b.src, alt:b.alt, caption:b.caption }
+      case 'code':      return { type:'code',  language: b.language, code: b.code }
+      case 'formula':   return { type:'formula', latex: b.latex, display: b.display }
+      case 'container': return {
+        type:'container',
+        name: b.name,
+        attrs: { ...b.attrs },
+        children: cloneBlocks(b.children)
+      }
+      default:
+        // hint/definition/example/question/section — domain-specific, not expected here
+        return b
+    }
+  })
+}
+
+function cloneInlineArr (xs: any[]): any[] {
+  return xs.map(cloneInline)
+}
+
+function cloneInline (i: any): any {
+  switch (i.type) {
+    case 'text':   return { type:'text', value: i.value }
+    case 'code':   return { type:'code', value: i.value }
+    case 'math':   return { type:'math', latex: i.latex }
+    case 'bold':   return { type:'bold', children: cloneInlineArr(i.children) }
+    case 'italic': return { type:'italic', children: cloneInlineArr(i.children) }
+    case 'link':   return { type:'link', url: i.url, children: cloneInlineArr(i.children) }
+    default:        return { ...i }
+  }
+}

package/domains/lesson/blocks.ts

@@ -0,0 +1,205 @@
+// ─────────────────────────────────────────────────────────────
+// domains/lesson/blocks.ts
+//
+// LessonAST v1 Block-level mapping (§6.3.3 frozen).
+//
+// * Plain blocks (paragraph / heading / quote / divider / list / table /
+//   image / code / formula) are structurally shared with DocumentAST.
+// * ContainerBlock directives → LessonAST domain blocks.
+// * Unknown container name → LESSON_UNKNOWN_CONTAINER (§2.4 L5-1).
+// * Hint level enum invalid → LESSON_INVALID_HINT_LEVEL (§2.4 L5-2).
+//
+// This module is pure: given a Block array (already downgraded &
+// de-h1'd by parser.ts section/grouping pass), map each node to
+// LessonAST Block shape.
+// ─────────────────────────────────────────────────────────────
+
+import type {
+  Inline,
+  TextInline,
+  BoldInline,
+  ItalicInline,
+  CodeInline,
+  LinkInline,
+  FormulaInline,
+  ParseContext,
+  ParseError
+} from '../../core/types/index'
+
+import type {
+  Block,
+  HintBlock,
+  HeadingBlock,
+  QuestionBlock,
+  ContainerBlock
+} from '../../core/types/lessonAST'
+
+export const LESSON_HINT_LEVELS: ReadonlyArray<HintBlock['level']> = [
+  'info','tip','warning','danger','reflect'
+]
+
+// The ONLY containers recognised by the lesson domain.
+export const KNOWN_CONTAINERS = new Set([
+  'hint','definition','example','question'
+])
+
+export interface MapOutput {
+  blocks: Block[]
+  /** Forbidden-behaviour tags observed during mapping. */
+  forbidden: string[]
+}
+
+export function mapBlocks (
+  docBlocks: Block[],
+  ctx: ParseContext
+): MapOutput {
+  const forbidden: string[] = []
+  const blocks: Block[] = []
+  for (const b of docBlocks) blocks.push(mapOne(b, ctx, forbidden))
+  return { blocks, forbidden }
+}
+
+// ── Individual mapping ───────────────────────────────────
+
+function mapOne (
+  b: Block,
+  ctx: ParseContext,
+  forbidden: string[]
+): Block {
+  switch (b.type) {
+    case 'paragraph': return { type:'paragraph', children: cloneInlines(b.children) }
+    case 'heading':   return { type:'heading',   level:b.level, children: cloneInlines(b.children) }
+    case 'quote':     return { type:'quote',     children: mapInner(b.children, ctx, forbidden) }
+    case 'divider':   return { type:'divider' }
+    case 'list':      return {
+      type:'list',
+      ordered: b.ordered,
+      items: b.items.map(item => item.map(it => cloneInline(it)))
+    }
+    case 'table':     return {
+      type:'table',
+      headers: b.headers.map(c => c.map(it => cloneInline(it))),
+      rows: b.rows.map(row => row.map(c => c.map(it => cloneInline(it))))
+    }
+    case 'image':     return { type:'image', src:b.src, alt:b.alt, caption:b.caption }
+    case 'code':      return { type:'code',  language:b.language, code:b.code }
+    case 'formula':   return { type:'formula', latex:b.latex, display:b.display }
+    case 'container': return mapContainer(b, ctx, forbidden)
+    case 'hint':
+    case 'definition':
+    case 'example':
+    case 'question':
+    case 'section':
+      // Already domain-specific blocks — pass through
+      return b
+  }
+}
+
+function mapInner (
+  inner: Block[],
+  ctx: ParseContext,
+  forbidden: string[]
+): Block[] {
+  return inner.map(x => mapOne(x, ctx, forbidden))
+}
+
+function mapContainer (
+  node: ContainerBlock,
+  ctx: ParseContext,
+  forbidden: string[]
+): Block {
+  const name = node.name
+  if (!KNOWN_CONTAINERS.has(name)) {
+    forbidden.push('treat_as_paragraph')
+    forbidden.push('silently_drop')
+    forbidden.push('return_null')
+    throw lessonError(
+      'LESSON_UNKNOWN_CONTAINER',
+      `[LESSON_UNKNOWN_CONTAINER] Unknown container '${name}' — lesson domain only allows hint/definition/example/question. Container name: ${name}. file: ${ctx.file}`,
+      ctx.file,
+      { container: name }
+    )
+  }
+  switch (name) {
+    case 'definition': {
+      const term = node.attrs['term'] ?? ''
+      return {
+        type:'definition',
+        term,
+        children: mapInner(node.children, ctx, forbidden)
+      }
+    }
+    case 'hint': {
+      const level = node.attrs['level'] ?? node.attrs['name'] ?? ''
+      const allowedStr = LESSON_HINT_LEVELS.join('|')
+      if (!(LESSON_HINT_LEVELS as readonly string[]).includes(level)) {
+        forbidden.push('accept_invalid_enum')
+        throw lessonError(
+          'LESSON_INVALID_HINT_LEVEL',
+          `[LESSON_INVALID_HINT_LEVEL] Invalid level '${level}' for hint container. Allowed values: ${allowedStr}. level: ${level}, hint. file: ${ctx.file}`,
+          ctx.file,
+          { container: 'hint', invalidEnumValue: level, allowed: allowedStr }
+        )
+      }
+      return {
+        type:'hint',
+        level: level as HintBlock['level'],
+        children: mapInner(node.children, ctx, forbidden)
+      }
+    }
+    case 'example': {
+      const title = node.attrs['title']
+      return {
+        type:'example',
+        title: title === undefined ? undefined : (title === '' ? undefined : title),
+        children: mapInner(node.children, ctx, forbidden)
+      }
+    }
+    case 'question': {
+      const hint = node.attrs['hint']
+      const prompt = mapInner(node.children, ctx, forbidden)
+      const q: QuestionBlock = { type:'question', prompt }
+      if (hint !== undefined && hint !== '') q.hint = hint
+      return q
+    }
+  }
+  // unreachable
+  throw lessonError(
+    'LESSON_UNKNOWN_CONTAINER',
+    `[LESSON_UNKNOWN_CONTAINER] Unknown container '${name}'. file: ${ctx.file}`,
+    ctx.file,
+    { container: name }
+  )
+}
+
+// ── Inline cloning ──
+
+function cloneInline (i: Inline): Inline {
+  switch (i.type) {
+    case 'text':   return { type:'text', value:(i as TextInline).value }
+    case 'code':   return { type:'code', value:(i as CodeInline).value }
+    case 'math':   return { type:'math', latex:(i as FormulaInline).latex }
+    case 'bold':   return { type:'bold', children: cloneInlines((i as BoldInline).children) }
+    case 'italic': return { type:'italic', children: cloneInlines((i as ItalicInline).children) }
+    case 'link':   return { type:'link', url:(i as LinkInline).url, children: cloneInlines((i as LinkInline).children) }
+    default:
+      return i
+  }
+}
+function cloneInlines (xs: Inline[]): Inline[] { return xs.map(cloneInline) }
+
+// ── Error helper ─────────────────────────────────────────
+
+export function lessonError (
+  code: string,
+  message: string,
+  file: string,
+  loc?: ParseError['loc']
+): ParseError & Error {
+  const e = new Error(message) as ParseError & Error
+  e.code = code
+  e.message = message
+  e.file = file
+  if (loc) e.loc = loc
+  return e
+}

package/domains/lesson/identity.ts

@@ -0,0 +1,40 @@
+/**
+ * LessonIdentity — dexinlabs-specific identity builder for lesson content.
+ *
+ * Maps lesson path slugs (topic/chapter/lesson) to DocumentIdentity shape
+ * with host-specific extension fields via index signature.
+ *
+ * This keeps dexin-content generic while allowing dexinlabs to maintain
+ * its hierarchical lesson structure.
+ */
+import type { DocumentIdentity } from '../../core/types/index'
+
+export interface LessonIdentityFields {
+  slug: string
+  topic_slug: string
+  chapter_slug: string
+}
+
+/**
+ * Build a DocumentIdentity for a lesson file, extending it with
+ * dexinlabs-specific fields via the [k:string]:unknown index signature.
+ */
+export function buildLessonIdentity(
+  lessonSlug: string,
+  topicSlug: string,
+  chapterSlug: string,
+  relPath: string
+): DocumentIdentity & LessonIdentityFields {
+  const id = `${topicSlug}/${chapterSlug}/${lessonSlug}`
+  const path = `/${id}`
+
+  return {
+    id,
+    path,
+    file: relPath,
+    collection: 'lessons',
+    slug: lessonSlug,
+    topic_slug: topicSlug,
+    chapter_slug: chapterSlug
+  }
+}

package/domains/lesson/index.ts

@@ -0,0 +1,7 @@
+/**
+ * lesson-domain barrel
+ */
+export { lessonParser } from './parser'
+export { lessonError, mapBlocks, KNOWN_CONTAINERS, LESSON_HINT_LEVELS } from './blocks'
+export { buildLessonIdentity } from './identity'
+export type { LessonIdentityFields } from './identity'