@tttinkl/codemaps-parser

Pure-TS, zero-IO Markdown → AST parser for codemaps — task-driven call-path-slice documentation files (.codemaps/<slug>.md).

The parser is the canonical schema definition for the codemaps-skill project. Both @tttinkl/codemaps-viewer and the VS Code extension consume the same AST.

Install

pnpm add @tttinkl/codemaps-parser
# or: npm i @tttinkl/codemaps-parser

Requires Node ≥ 20.

Usage

import { parseCodemap, CodemapError } from '@tttinkl/codemaps-parser'
import { readFileSync } from 'node:fs'

const md = readFileSync('.codemaps/login-flow.md', 'utf8')

try {
  const cm = parseCodemap(md)
  console.log(cm.frontmatter.title, '—', cm.sections.length, 'flow sections')
} catch (err) {
  if (err instanceof CodemapError) {
    // err.line / err.column are 1-based whole-document coordinates;
    // err.hint is a remediation suggestion when available.
    console.error(`${err.line}:${err.column}: ${err.message}`)
    if (err.hint) console.error(`hint: ${err.hint}`)
  } else {
    throw err
  }
}

API

• parseCodemap(md: string): Codemap — parses a v0.1.3 codemap markdown document. Alias: parse.
• CodemapError — thrown on schema violations. Carries optional line / column (1-based) and hint.
• Types re-exported: Codemap, Frontmatter, FlowSection, TreeNode, NodeType, InlineRef, PathRef.
• Helpers: parsePathRef, buildFlowSteps.

Schema

The schema (v0.1.3) is documented at the project root in schema-design.md. The parser tests in test/parser.test.ts are the executable specification.

Three node classes:

• code — has section-local id (1a / 2c), pathRef, and a fenced code block (1–5 lines).
• pointer — has pathRef, no id, no code.
• group — pure structural label, optional pathRef.

License

MIT © lisilu