dexin-content 0.1.2 → 0.2.0

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'

package/package.json

@@ -1,69 +1,82 @@
-{
-  "name": "dexin-content",
-  "version": "0.1.2",
-  "description": "Structured content compilation & runtime layer — neutral Markdown → Content AST → PositiveArtifact + store/query/collection pipeline.",
-  "keywords": [
-    "markdown",
-    "content",
-    "compiler",
-    "ast",
-    "cms",
-    "remark",
-    "dexinlabs"
-  ],
-  "type": "module",
-  "license": "MIT",
-  "author": "得心实验室 <https://gitee.com/cuizhn>",
-  "repository": {
-    "type": "git",
-    "url": "git+https://gitee.com/cuizhn/dexin-content.git"
-  },
-  "homepage": "https://gitee.com/cuizhn/dexin-content#readme",
-  "bugs": {
-    "url": "https://gitee.com/cuizhn/dexin-content/issues"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "files": [
-    "index.ts",
-    "collection.ts",
-    "store.ts",
-    "query.ts",
-    "diff.ts",
-    "core/**/*.ts",
-    "README.md",
-    "LICENSE"
-  ],
-  "exports": {
-    ".": "./index.ts",
-    "./core/types": "./core/types.ts",
-    "./core/compiler": "./core/compiler.ts",
-    "./core/frontmatter": "./core/frontmatter.ts",
-    "./core/discovery": "./core/discovery.ts",
-    "./core/markdown": "./core/markdown.ts",
-    "./store": "./store.ts",
-    "./collection": "./collection.ts",
-    "./query": "./query.ts",
-    "./diff": "./diff.ts"
-  },
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "runtime:check": "tsx scripts/runtime-check.ts",
-    "pack": "npm pack --dry-run"
-  },
-  "dependencies": {
-    "yaml": "^2.5.1",
-    "remark-parse": "^11.0.0",
-    "remark-gfm": "^4.0.0",
-    "remark-math": "^6.0.0",
-    "remark-directive": "^3.0.0",
-    "unified": "^11.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@types/mdast": "^4.0.4",
-    "typescript": "^5.5.0",
-    "tsx": "^4.7.0"
-  }
-}
+{
+  "name": "dexin-content",
+  "version": "0.2.0",
+  "description": "Open content toolchain — Markdown → LessonAST/ContentPackage compiler, CLI and validator (dexinlabs ecosystem).",
+  "keywords": [
+    "markdown",
+    "content",
+    "compiler",
+    "ast",
+    "remark",
+    "dexinlabs"
+  ],
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "得心实验室 <https://gitee.com/cuizhn>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/cuizhn/dexin-content.git"
+  },
+  "homepage": "https://gitee.com/cuizhn/dexin-content#readme",
+  "bugs": {
+    "url": "https://gitee.com/cuizhn/dexin-content/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "dexin-content": "./bin/dexin-content.mjs"
+  },
+  "files": [
+    "index.ts",
+    "core/**/*.ts",
+    "cli/**/*.ts",
+    "domains/**/*.ts",
+    "bin/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./core/markdown": "./core/parser/markdown.ts",
+    ".": "./index.ts",
+    "./cli/validate": "./cli/validate.ts",
+    "./core/frontmatter": "./core/parser/frontmatter.ts",
+    "./diff": "./core/artifact/diff.ts",
+    "./cli/package": "./cli/package.ts",
+    "./collection": "./core/artifact/collection.ts",
+    "./cli/build": "./cli/build.ts",
+    "./query": "./core/artifact/query.ts",
+    "./core/compiler": "./core/compiler/compiler.ts",
+    "./core/types": "./core/types/index.ts",
+    "./store": "./core/artifact/store.ts",
+    "./cli/serve": "./cli/serve.ts",
+    "./cli/check": "./cli/check.ts",
+    "./core/discovery": "./core/compiler/discovery.ts",
+    "./core/types/lessonAST": "./core/types/lessonAST.ts",
+    "./domains/lesson": "./domains/lesson/index.ts",
+    "./domains/document": "./domains/document/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "runtime:check": "tsx scripts/runtime-check.ts",
+    "pack": "npm pack --dry-run",
+    "build": "tsx cli/build.ts",
+    "package": "tsx cli/package.ts"
+  },
+  "dependencies": {
+    "tsx": "^4.23.0",
+    "yaml": "^2.5.1",
+    "remark-parse": "^11.0.0",
+    "remark-gfm": "^4.0.0",
+    "remark-math": "^6.0.0",
+    "remark-directive": "^3.0.0",
+    "unified": "^11.0.0",
+    "remark": "^15.0.0",
+    "micromark-extension-directive": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/mdast": "^4.0.4",
+    "typescript": "^5.5.0"
+  }
+}

package/core/discovery.ts

@@ -1,110 +0,0 @@
-// ─────────────────────────────────────────────────────────────
-// dexin-content/core/discovery.ts
-// Source adapter + collection routing + identity derivation helpers.
-//
-// Document path convention → DocumentIdentity:
-//   id   = relPath minus .md, minus trailing `/index`
-//   path = '/' + id
-//   file = relPath WITH .md extension
-//   + auxiliary fields: collection, (optionally) index_file:true
-//
-// Hosts needing domain-specific identity shapes define their own types
-// and construct CompileInput identities themselves; core only knows the
-// document convention.
-// ─────────────────────────────────────────────────────────────
-
-import path from 'node:path'
-import { readFileSync, existsSync, statSync } from 'node:fs'
-import type { DocumentIdentity, ParseError } from './types'
-
-// ── Shared BOM / CRLF sanitisation primitives ─────────────
-//    Used by both sync (readSourceFile) and async (createLocalSource.read)
-//    IO entry points to guarantee byte-identical failure behaviour.
-
-/**
- * Build a LINE_ENDING_CONTAMINATION ParseError for a given relative path.
- * Caller supplies a short remediation hint matching its context.
- */
-export function mkLineEndingError (
-  relPath: string,
-  hint: string = 'Normalize to LF before processing.'
-): ParseError & Error {
-  const err = new Error(
-    `[LINE_ENDING_CONTAMINATION] Source file '${relPath}' contains CRLF line endings. ` +
-    hint
-  ) as ParseError & Error
-  err.code = 'LINE_ENDING_CONTAMINATION'
-  err.file = relPath
-  return err
-}
-
-/**
- * Strip a leading UTF-8 BOM (U+FEFF) if present and guard against CRLF
- * contamination. Returns the cleaned source string; throws with
- * LINE_ENDING_CONTAMINATION code on CR presence.
- *
- * This is intentionally a pure string-in / string-out (or throw) helper so
- * both sync and async IO paths share one canonical sanitisation.
- */
-export function sanitizeSourceText (raw: string, relPath: string): string {
-  const source = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw
-  if (source.includes('\r')) throw mkLineEndingError(relPath)
-  return source
-}
-
-/**
- * Normalise a relative path to forward slashes and strip any leading `./`.
- */
-export function normaliseRel (p: string): string {
-  let out = p.split(path.sep).join('/')
-  while (out.startsWith('./')) out = out.slice(2)
-  return out
-}
-
-/**
- * Build DocumentIdentity from a `.md` file path relative
- * to the collection source root.
- */
-export function buildDocumentIdentity (
-  relPath: string,
-  collection: string
-): DocumentIdentity {
-  const norm = normaliseRel(relPath)
-  const file = norm
-
-  let id = file.endsWith('.md') ? file.slice(0, -'.md'.length) : file
-  if (id.endsWith('.markdown')) id = id.slice(0, -'.markdown'.length)
-
-  const isIndex = id.endsWith('/index') || id === 'index'
-  if (isIndex) {
-    if (id === 'index') id = ''
-    else id = id.slice(0, -'/index'.length)
-  }
-
-  const pathUrl = '/' + id
-  const identity: DocumentIdentity = {
-    id,
-    path: pathUrl,
-    file,
-    collection
-  }
-  if (isIndex) identity.index_file = true
-  return identity
-}
-
-/** Read a single UTF-8 file and pair it with its relative path. */
-export interface SourceFile {
-  absPath: string
-  relPath: string
-  source: string
-}
-
-export function readSourceFile (absPath: string, sourceRoot: string): SourceFile {
-  if (!existsSync(absPath) || !statSync(absPath).isFile()) {
-    throw new Error(`[discovery] Not a file or missing: ${absPath}`)
-  }
-  const raw = readFileSync(absPath, 'utf8')
-  const rel = normaliseRel(path.relative(sourceRoot, absPath))
-  const source = sanitizeSourceText(raw, rel)
-  return { absPath, relPath: rel, source }
-}