dexin-content 0.1.2 → 0.2.1

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'

package/domains/lesson/parser.ts

@@ -0,0 +1,200 @@
+// ─────────────────────────────────────────────────────────────
+// domains/lesson/parser.ts
+//
+// Lesson domain parser — DomainParser implementation.
+//
+// Responsibilities (§6.3.5 frozen, DIFF-RULING R-06/08):
+//   a) h1 absorption: drop DocumentAST heading.level=1 nodes (they must be
+//      treated as redundant with frontmatter.title). No error.
+//   b) §6.3.5 heading downgrade table applied to all remaining headings
+//      BEFORE section grouping runs:
+//          md h1 → level 1  (dropped by rule a)
+//          md h2 → 1
+//          md h3 → 2
+//          md h4 → 3
+//          md h5 → 4
+//      The transformation here shifts md depth → lesson level using the
+//      *original* mdDepth:
+//          lesson_level = mdDepth - 1
+//      After shift any lesson level 0 means we had an md h1 → absorption.
+//   c) Section grouping: walk blocks; whenever we see LESSON-level=1 heading
+//      it opens a new SectionBlock; subsequent blocks go in that section.
+//   d) Heading depth fail-fast for h6: lesson domain allows md h5 → level 4
+//      (unlike the document domain, which rejects md h5/h6). md depth 6 is
+//      always undefined → LESSON_HEADING_DEPTH_UNDEFINED.
+//   e) Container mapping delegates to blocks.ts — which handles
+//      Hint level enum validation (L5-2) + unknown containers (L5-1).
+// ─────────────────────────────────────────────────────────────
+
+import type {
+  DomainParser,
+  ParseContext
+} from '../../core/types/index'
+import type { LessonContent, Block, HeadingBlock, SectionBlock } from '../../core/types/lessonAST'
+import {
+  mapBlocks,
+  lessonError
+} from './blocks'
+
+export const lessonParser: DomainParser = {
+  domain: 'lesson',
+  parse (content: LessonContent, ctx: ParseContext): LessonContent {
+    // 1. Heading pass: absorption + downgrade + fail-fast.
+    const afterHeading = passHeadings(content.blocks, ctx)
+
+    // 2. Section grouping by lesson-level=1 headings.
+    const sectioned = passSections(afterHeading)
+
+    // 3. Container mapping + container validation (L5-1/L5-2).
+    const { blocks, forbidden } = mapSectioned(sectioned, ctx)
+    void forbidden
+
+    return { version: 1, blocks }
+  }
+}
+
+// ── Pass 1: heading absorption / downgrade / fail-fast ──
+
+type TransformedBlock = Block
+
+function passHeadings (
+  blocks: Block[],
+  ctx: ParseContext
+): TransformedBlock[] {
+  const out: TransformedBlock[] = []
+  walkWithHeadings(blocks, ctx, out)
+  return out
+}
+
+function walkWithHeadings (
+  blocks: Block[],
+  ctx: ParseContext,
+  out: Block[],
+  depth = 0
+): void {
+  void depth
+  for (const b of blocks) {
+    if (b.type === 'heading') {
+      const docLevel = b.level
+      const hb = b as HeadingBlock
+      const mdDepth = hb.mdDepth ?? docLevel
+      if (mdDepth === 6) {
+        throw lessonError(
+          'LESSON_HEADING_DEPTH_UNDEFINED',
+          `[LESSON_HEADING_DEPTH_UNDEFINED] Heading h6 (level 6) has no mapping in §6.3.5 (only h1 absorption plus h2→level1 to h5→level4 defined). Heading depth undefined. Allowed: h1-h5. file: ${ctx.file}`,
+          ctx.file,
+          { headingDepth: 6 }
+        )
+      }
+      if (mdDepth > 6) {
+        throw lessonError(
+          'LESSON_HEADING_DEPTH_UNDEFINED',
+          `[LESSON_HEADING_DEPTH_UNDEFINED] Heading h${mdDepth} (level ${mdDepth}) has no mapping. Allowed: h1-h5. file: ${ctx.file}`,
+          ctx.file,
+          { headingDepth: mdDepth }
+        )
+      }
+
+      if (mdDepth === 1) {
+        // R-08: h1 absorption — drop the heading entirely (no error, no downgrade).
+        continue
+      }
+      // Downgrade: lesson_level = md_depth - 1. md ∈ {2,3,4,5}.
+      const lessonLevel = mdDepth - 1
+      if (lessonLevel < 1 || lessonLevel > 4) {
+        throw lessonError(
+          'LESSON_HEADING_DEPTH_UNDEFINED',
+          `[LESSON_HEADING_DEPTH_UNDEFINED] Heading h${mdDepth} → lesson level ${lessonLevel} out of range. Allowed heading levels: h1-h5. file: ${ctx.file}`,
+          ctx.file,
+          { headingDepth: mdDepth }
+        )
+      }
+      // Explicitly drop the transient mdDepth field when converting to lesson
+      // heading; never carry transient non-canonical fields downstream.
+      out.push({
+        type: 'heading',
+        level: lessonLevel as 1|2|3|4,
+        children: b.children
+      })
+      continue
+    }
+    // Non-heading: descend into block children for quote/container to
+    // downgrade any headings they embed (rare, but correct).
+    out.push(transformBlockHeadings(b, ctx))
+  }
+}
+
+function transformBlockHeadings (b: Block, ctx: ParseContext): Block {
+  switch (b.type) {
+    case 'quote': {
+      const inner: Block[] = []
+      walkWithHeadings(b.children, ctx, inner)
+      return { type:'quote', children: inner }
+    }
+    case 'container': {
+      const inner: Block[] = []
+      walkWithHeadings(b.children, ctx, inner)
+      return { type:'container', name:b.name, attrs:b.attrs, children: inner }
+    }
+    default:
+      return b
+  }
+}
+
+// ── Pass 2: Section grouping (§6.3.6 — h2→起节 = lesson level=1) ──
+
+interface SectionMarker {
+  kind: 'section'
+  titleInline: SectionBlock['title']  // original heading inlines
+  body: Block[]                        // body still in Block shape for now
+}
+interface OrphanBlock {
+  kind: 'orphan'
+  block: Block
+}
+type Grouped = SectionMarker | OrphanBlock
+
+function passSections (blocks: Block[]): Grouped[] {
+  const out: Grouped[] = []
+  let current: SectionMarker | null = null
+  for (const b of blocks) {
+    if (b.type === 'heading' && b.level === 1) {
+      current = { kind:'section', titleInline: b.children, body: [] }
+      out.push(current)
+    } else {
+      if (current) current.body.push(b)
+      else out.push({ kind:'orphan', block: b })
+    }
+  }
+  return out
+}
+
+// ── Pass 3: Final Block mapping with sections ──
+
+function mapSectioned (
+  grouped: Grouped[],
+  ctx: ParseContext
+): { blocks: Block[]; forbidden: string[] } {
+  const forbidden: string[] = []
+  const result: Block[] = []
+  for (const g of grouped) {
+    if (g.kind === 'orphan') {
+      const { blocks, forbidden: f } = mapBlocks([g.block], ctx)
+      forbidden.push(...f)
+      result.push(...blocks)
+    } else {
+      const { blocks, forbidden: f } = mapBlocks(g.body, ctx)
+      forbidden.push(...f)
+      const section: SectionBlock = {
+        type: 'section',
+        title: g.titleInline,
+        blocks
+      }
+      result.push(section)
+    }
+  }
+  return { blocks: result, forbidden }
+}
+
+// Re-export lessonError / mapBlocks for direct use by external callers.
+export { lessonError, mapBlocks }

package/index.ts

@@ -2,11 +2,60 @@
 // Re-exports core types and interfaces for host consumption.
 // Domain parsers are injected by the host via DomainParserRegistry.
 
-export type { DomainName, DocumentIdentity, Schema, Artifact, ParseError, DomainParser, ParseContext, DocumentContent, DocumentBlock } from './core/types'
-export { DomainParserRegistry, compile } from './core/compiler'
-export type { ArtifactStore } from './store'
-export { createFsArtifactStore, createMemoryArtifactStore } from './store'
-export type { CollectionDefinition, SourceAdapter, ResolvedCollection } from './collection'
-export { defineCollection, resolveCollections, discover, compileCollections } from './collection'
-export type { ContentQuery as ContentQueryType } from './query'
-export { ContentQuery } from './query'
+export type {
+  DomainName, DocumentIdentity, Schema, Artifact, ParseError,
+  DomainParser, ParseContext,
+  Meta, Identity, StructuredIdentity, TEX_INLINE_TYPE
+} from './core/types/index'
+
+// LessonAST 类型
+export type {
+  LessonContent, Block, BlockType,
+  ParagraphBlock, HeadingBlock, QuoteBlock, HintBlock,
+  DefinitionBlock, ExampleBlock, QuestionBlock,
+  ImageBlock, CodeBlock, FormulaBlock, ListBlock,
+  TableBlock, TableCell, SectionBlock, DividerBlock,
+  ContainerBlock, ExerciseContent,
+  Inline, TextInline, BoldInline, ItalicInline,
+  CodeInline, LinkInline, FormulaInline, MathInline,
+  BaseBlock
+} from './core/types/lessonAST'
+
+export {
+  BLOCK_TYPES, HINT_LEVELS, HEADING_LEVELS
+} from './core/types/lessonAST'
+
+export { DomainParserRegistry, compile } from './core/compiler/compiler'
+export type { CompileInput, CompileResult } from './core/compiler/compiler'
+export { normaliseRel, buildDocumentIdentity as buildDocPageIdentity, readSourceFile } from './core/compiler/discovery'
+export { splitFrontmatter, parseFrontmatter, validateSchema } from './core/parser/frontmatter'
+export { parseDocument } from './core/parser/markdown'
+
+export type { ArtifactStore, ContentIndex, IndexEntry } from './core/artifact/store'
+export { createFsArtifactStore, createMemoryArtifactStore } from './core/artifact/store'
+
+export type { CollectionDefinition, SourceAdapter, ResolvedCollection } from './core/artifact/collection'
+export { defineCollection, resolveCollections, discover, compileCollections } from './core/artifact/collection'
+
+export type { ContentQuery as ContentQueryType } from './core/artifact/query'
+export { ContentQuery } from './core/artifact/query'
+
+export { toCanonicalJSON, firstDiff, sortKeysDeep, stripUnderscoreKeysGolden } from './core/artifact/diff'
+
+// Lesson domain
+export { lessonParser } from './domains/lesson/parser'
+export { buildLessonIdentity } from './domains/lesson/identity'
+export { mapBlocks, lessonError, KNOWN_CONTAINERS } from './domains/lesson/blocks'
+
+// Document domain
+export { documentParser } from './domains/document/parser'
+export { buildDocumentIdentity as buildDocumentPageIdentity } from './domains/document/identity'
+
+// CLI
+export type { FlowBuildInput, FlowBuildResult } from './cli/build'
+export { flowBuild } from './cli/build'
+export type { FlowManifest, OutLesson, OutPage, OutPackage } from './cli/package'
+export { flowPackage } from './cli/package'
+export { flowValidate } from './cli/validate'
+export { flowCheck } from './cli/check'
+export { flowServe } from './cli/serve'