markrefs

Markdown 交叉引用解析与校验（最小核心）：名字→路径、目标存在性、重复声明。

与消费方解耦：本包不依赖任何宿主（零运行时依赖）；skillnomad 等消费者以 dependency 引用已发布版本。

只对 markdown 负责——不做业务语义判断：名字与 scope 对 markrefs 都是不透明字符串；位置只以 file[:line[:col]] 表达；输入是声明式引用（RefDecl）与注入式名字表（KeyMap），核心不解析任何载体。

安装

npx markrefs check --keys keys.json --refs refs.json
# 或
npm install -g markrefs

CLI 用法

markrefs check --keys keys.json --refs refs.json [--strict] [--format text|json]

• 退出码：0＝无 error（--strict 下无 warn）；1＝有 error（--strict 下含 warn）；2＝用法/输入错误。
• 输入：keys.json 为 { "entries": [{ "name", "path", "scope?", "site?" }] }；refs.json 为 { "refs": [{ "site", "name?|path?", "fragment?", "dynamic?", "wildcard?" }] }。

规则

| ruleId | 触发 | 级别 | |---|---|---| | missing-key | 引用的名字不在表中 | error | | missing-target | 解析出的路径在文件系统不存在 | error | | duplicate-key | 同一名字、同 scope 两条定义 | error（跨 scope＝warn） | | duplicate-path | 同 scope 两名指向同一路径 | warn | | duplicate-decl | 同一声明源文件内、同一 path#fragment 两次 | error |

片段（#xxx）当前只透传（不解释语义）；孤儿检查（入口可达性＋豁免）留待后续版本。

库用法

import { resolve, validate } from 'markrefs';

const keys = { entries: [{ name: 'alpha', path: 'docs/a.md' }] };
resolve({ site: 'src/x.ts:1', name: 'alpha' }, keys); // -> { path: 'docs/a.md', key: 'alpha' }

const diagnostics = validate(
  [{ site: 'src/x.ts:1', name: 'alpha' }],
  keys,
  { exists: () => true },
);

许可

MIT