npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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).

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-core

Node >= 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.