@catheadowl/doc-core
v0.1.0
Published
doc-core — the Markdown reference kernel: classify, extract, resolve, anchor-check and rebase document references over a git tree. Reference forms: Markdown links/images/definitions, wikilinks, and registered scheme:// addresses (ukp the first resident).
Maintainers
Readme
description: doc-core — a pure TypeScript kernel for Markdown references: classify, extract, resolve, anchor-check and plan byte-preserving rewrites of links, images, definitions, wikilinks and scheme addresses over a git tree
doc-core
One library that answers "what is this Markdown reference, where does it point on the tree, and does it resolve" — and plans byte-preserving rewrites when documents move. It covers the full reference alphabet: standard Markdown links / images / definitions, [[wikilinks]] (the GitHub-wiki / Obsidian form), and registered scheme addresses (ukp is the first resident; custom schemes register through a parameter). The kernel is policy-free by design: it only answers factual questions — classify, extract, resolve, anchor-check, existence, rename planning. What to do about an answer (freeze exemptions, deny rules, when to enforce) stays with the consumer and flows in through parameters.
Install
npm install @catheadowl/doc-coreNode >= 18. Whole-repo scans run against a git worktree — the file universe comes from git ls-files, so gitignored artifacts and submodule contents never enter a scan. Extraction, anchor computation and rewrite planning are pure string functions and need no git at all.
Minimal example
import { extractReferences, resolveReference } from '@catheadowl/doc-core'
import { readFileSync } from 'node:fs'
import { resolve } from 'node:path'
const root = resolve('.') // repository root (or from discoverRepositoryRoot)
const sourceFile = resolve(root, 'docs/guide.md') // absolute — targets resolve against its directory
for (const ref of extractReferences(readFileSync(sourceFile, 'utf8'))) {
const r = resolveReference(ref, sourceFile, root)
if (r.reason) console.log(`${ref.line}: ${ref.url} — ${r.reason}`)
}Whole-repo check with remedy-grade output:
import { checkRepository } from '@catheadowl/doc-core'
for (const v of checkRepository(root)) {
console.log(`${v.file}:${v.line}: ${v.url} — ${v.reason}`)
}What it does
| Capability | Entry points |
|---|---|
| Classify — what kind of URL is this? | isWindowsDriveUrl, isExternalOrAbsoluteMarkdownUrl, splitMarkdownUrlTarget |
| Extract — every reference with byte-exact spans (rewritable substrings, not re-serialized positions) | extractReferences, scanWikiLinks, markdownCodeRanges, markdownLabel |
| Resolve — does the target exist? | resolveReference (percent-decode, realpath containment, gitlink tolerance), resolveReferenceLexically (no existence gate, for post-hoc repair), enumerateWikiCandidates (returns all ranked suffix matches — the 0/1/N judgment stays with you) |
| Anchors — GitHub-compatible heading slugs | githubSlug, documentAnchors, documentAnchorPairs, anchorCache |
| Git seams — the repository as ground truth | discoverRepositoryRoot (structured not-found: not-a-git-repository / git-unavailable, never thrown), gitLsFiles, gitGrep, gitMove, gitLogRenameRecords, gitLogLastTouched |
| Schemes — one registry, recognition and resolution declared together | recognizeSchemeReference, resolveSchemeReference, registeredSchemes; ukp ships as the first resident; your own scheme registers via the resolvers parameter |
| Rename planning — move files without breaking references | planRename (all-or-nothing plan; untracked sources refuse up front), planSink, applyRenamePlan (structured RenameApplyError with code + git stderr + moved pairs), rebaseDestination / rebaseLabel (byte-preserving), stable code tables: RENAME_CONFLICT_CODES / RENAME_CONFLICT_MESSAGES |
| Whole-repo check — violations shaped for gating | checkRepository (+ check in ./gate-check.js): file:line, reason, remedy; deterministic nearest-anchor hints; frozen-dirs / frozen-trees policy flows in as data; outside a git repo it answers a structured not-applicable outcome instead of throwing |
The complete typed surface ships in the package itself: read the .d.ts files (lib/index.d.ts, lib/links/index.d.ts, lib/gate-check.d.ts). They are the API reference — this README deliberately does not duplicate one.
What it does not do
No enforcement and no judgment: the kernel never decides when to check, what to exempt, or what a finding means. Freeze policy, deny lists, wiki 0/1/N disambiguation, delivery timing (hooks, gates, CLIs) are consumer concerns. If you want the batteries-included CLI over this kernel, see @catheadowl/doc-tools on npm.
License
MIT.
