@catheadowl/md-tools 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +76 -2
- package/cli/config.mjs +86 -0
- package/cli/doc-link.mjs +139 -0
- package/cli/kernel.mjs +86 -0
- package/cli/normalize.mjs +91 -0
- package/cli/rename.mjs +390 -0
- package/conformance/cases.json +55 -0
- package/lib/gate-check.d.ts +83 -0
- package/lib/gate-check.js +212 -0
- package/lib/index.d.ts +8 -0
- package/lib/index.js +8 -0
- package/lib/links/anchors.d.ts +43 -0
- package/lib/links/anchors.js +93 -0
- package/lib/links/cli.d.ts +20 -0
- package/lib/links/cli.js +72 -0
- package/lib/links/git.d.ts +156 -0
- package/lib/links/git.js +329 -0
- package/lib/links/index.d.ts +33 -0
- package/lib/links/index.js +25 -0
- package/lib/links/markdown.d.ts +125 -0
- package/lib/links/markdown.js +253 -0
- package/lib/links/normalize.d.ts +40 -0
- package/lib/links/normalize.js +102 -0
- package/lib/links/rebase.d.ts +24 -0
- package/lib/links/rebase.js +44 -0
- package/lib/links/rename.d.ts +257 -0
- package/lib/links/rename.js +864 -0
- package/lib/links/resolve.d.ts +143 -0
- package/lib/links/resolve.js +295 -0
- package/lib/links/scheme.d.ts +112 -0
- package/lib/links/scheme.js +206 -0
- package/lib/links/textual.d.ts +26 -0
- package/lib/links/textual.js +144 -0
- package/package.json +75 -4
- package/skills/md-tools/SKILL.md +42 -0
- package/skills/md-tools/references/freeze.md +16 -0
- package/skills/md-tools/references/payload.md +28 -0
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Scheme seam (self-written): the registered-scheme plane for
|
|
3
|
+
* `scheme://address` references. A scheme becomes a reference only by
|
|
4
|
+
* registration, and recognition, shape parsing, and resolution are declared
|
|
5
|
+
* at ONE registry point — a recognized scheme can never drift from its
|
|
6
|
+
* resolver (a recognition set and a resolver map declared in two places is a
|
|
7
|
+
* pair that can silently split; one object cannot). Everything else
|
|
8
|
+
* scheme-shaped stays a non-reference.
|
|
9
|
+
*
|
|
10
|
+
* The address contract is verbatim fidelity: fragment stripped, percent
|
|
11
|
+
* escapes decoded, malformed escapes kept exactly as written (they name
|
|
12
|
+
* nothing anyone meant — the raw text flows into the resolver's existence
|
|
13
|
+
* check and reports missing, fail-closed). Query, if any, stays in the
|
|
14
|
+
* address; interpreting it is the resident scheme's own contract. That
|
|
15
|
+
* fidelity is why parsing is a hand-rolled split rather than WHATWG `URL`:
|
|
16
|
+
* a URL parser silently folds dot segments and re-encodes the address
|
|
17
|
+
* (spaces, non-ASCII), destroying byte fidelity, and validates none of the
|
|
18
|
+
* malformed escapes this seam must fail closed on.
|
|
19
|
+
*
|
|
20
|
+
* ukp is the first resident. Its resolver runs the `ukp` CLI through the
|
|
21
|
+
* shared capture primitives (`cli.ts`, the git seam's temp-file spawn law)
|
|
22
|
+
* and degrades on any registry failure — warn, never error.
|
|
23
|
+
*/
|
|
24
|
+
import { existsSync } from 'node:fs';
|
|
25
|
+
import { resolve } from 'node:path';
|
|
26
|
+
import { captureCliExit } from './cli.js';
|
|
27
|
+
// Two letters or more before `://` — a single letter + ':' + separator is the
|
|
28
|
+
// Windows drive family, which the local-path plane keeps (no single-letter
|
|
29
|
+
// scheme exists in the IANA registry).
|
|
30
|
+
const SCHEME_SHAPED = /^([a-zA-Z][a-zA-Z0-9+.-]+):\/\/(.*)$/;
|
|
31
|
+
/**
|
|
32
|
+
* Recognize a registered `scheme://address` reference, or null. Null covers
|
|
33
|
+
* both non-scheme shapes and schemes no registry declared: an unregistered
|
|
34
|
+
* scheme-shaped URL is not a reference at all. The optional `resolvers`
|
|
35
|
+
* overlay registers local schemes for this call — policy flows in as a
|
|
36
|
+
* parameter, kernel residents and the overlay merge.
|
|
37
|
+
*/
|
|
38
|
+
export function recognizeSchemeReference(url, options = {}) {
|
|
39
|
+
const match = SCHEME_SHAPED.exec(url);
|
|
40
|
+
if (match === null)
|
|
41
|
+
return null;
|
|
42
|
+
const scheme = match[1].toLowerCase();
|
|
43
|
+
if (lookupResolver(scheme, options) === undefined)
|
|
44
|
+
return null;
|
|
45
|
+
const address = decodeAddressPart(match[2].split('#')[0]);
|
|
46
|
+
return { scheme, address };
|
|
47
|
+
}
|
|
48
|
+
/** Scheme names with a kernel-registered resolver, sorted. */
|
|
49
|
+
export function registeredSchemes() {
|
|
50
|
+
return Object.keys(KERNEL_SCHEMES).sort();
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Resolve one scheme address. A scheme without a resolver (never possible
|
|
54
|
+
* for kernel residents; reachable when a caller resolves a name its
|
|
55
|
+
* parameter overlay does not actually carry) returns `{ status:
|
|
56
|
+
* 'no-resolver' }` — a loud shape, never silence.
|
|
57
|
+
*/
|
|
58
|
+
export function resolveSchemeReference(scheme, address, options = {}) {
|
|
59
|
+
const resolver = lookupResolver(scheme.toLowerCase(), options);
|
|
60
|
+
if (resolver === undefined)
|
|
61
|
+
return { status: 'no-resolver' };
|
|
62
|
+
return resolver(address);
|
|
63
|
+
}
|
|
64
|
+
function lookupResolver(scheme, options) {
|
|
65
|
+
return options.resolvers?.[scheme] ?? KERNEL_SCHEMES[scheme];
|
|
66
|
+
}
|
|
67
|
+
// Percent-decode before resolution — a renderer-correct address (`my%20doc`
|
|
68
|
+
// meaning `my doc`) must resolve. Malformed escapes name nothing anyone
|
|
69
|
+
// meant; the raw text flows into the resolver's existence check and reports
|
|
70
|
+
// missing (fail-closed).
|
|
71
|
+
function decodeAddressPart(raw) {
|
|
72
|
+
try {
|
|
73
|
+
return decodeURIComponent(raw);
|
|
74
|
+
}
|
|
75
|
+
catch {
|
|
76
|
+
return raw;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* The kernel registry — the one declaration point. A scheme is recognized
|
|
81
|
+
* exactly when it has a resolver here, so recognition and resolution cannot
|
|
82
|
+
* drift apart. Ecosystem schemes land as entries here together with corpus
|
|
83
|
+
* cases; consumer-local schemes register through the `resolvers` parameter
|
|
84
|
+
* instead. New resident = one entry + its resolver + corpus cases.
|
|
85
|
+
*/
|
|
86
|
+
const KERNEL_SCHEMES = {
|
|
87
|
+
ukp: resolveUkp,
|
|
88
|
+
};
|
|
89
|
+
/**
|
|
90
|
+
* Parse `ukp list --json` stdout into a registry snapshot. Tolerant of the
|
|
91
|
+
* envelope form (`{schema, command, endpoints: [...]}` with a structured
|
|
92
|
+
* `location` and `kind`-marked remoteness) and of contract-minimal forms
|
|
93
|
+
* (flat top-level array, flat `location` string, boolean `remote`) so
|
|
94
|
+
* earlier and later ukp builds both parse. Output that parses but carries
|
|
95
|
+
* no endpoint array is unavailability, not an empty registry — an empty
|
|
96
|
+
* registry is not a shape the CLI produces.
|
|
97
|
+
*/
|
|
98
|
+
export function parseUkpListJson(stdout) {
|
|
99
|
+
let doc;
|
|
100
|
+
try {
|
|
101
|
+
doc = JSON.parse(stdout);
|
|
102
|
+
}
|
|
103
|
+
catch (error) {
|
|
104
|
+
return { status: 'unavailable', reason: `ukp list --json output is not JSON (${error instanceof Error ? error.message : String(error)})` };
|
|
105
|
+
}
|
|
106
|
+
const records = Array.isArray(doc)
|
|
107
|
+
? doc
|
|
108
|
+
: isRecord(doc) && Array.isArray(doc.endpoints)
|
|
109
|
+
? doc.endpoints
|
|
110
|
+
: [];
|
|
111
|
+
if (records.length === 0 && !Array.isArray(doc)) {
|
|
112
|
+
return { status: 'unavailable', reason: 'ukp list --json output carries no endpoint array (contract drift)' };
|
|
113
|
+
}
|
|
114
|
+
const endpoints = new Map();
|
|
115
|
+
for (const record of records) {
|
|
116
|
+
if (!isRecord(record))
|
|
117
|
+
continue;
|
|
118
|
+
const name = record.name;
|
|
119
|
+
if (typeof name !== 'string' || name.trim() === '')
|
|
120
|
+
continue;
|
|
121
|
+
let locationRaw = null;
|
|
122
|
+
if (typeof record.location === 'string' && record.location.trim() !== '') {
|
|
123
|
+
locationRaw = record.location.trim();
|
|
124
|
+
}
|
|
125
|
+
else if (isRecord(record.location) && typeof record.location.path === 'string' && record.location.path.trim() !== '') {
|
|
126
|
+
locationRaw = record.location.path.trim();
|
|
127
|
+
}
|
|
128
|
+
const remote = typeof record.remote === 'boolean'
|
|
129
|
+
? record.remote
|
|
130
|
+
: typeof record.kind === 'string'
|
|
131
|
+
? record.kind === 'remote'
|
|
132
|
+
: locationRaw === null || locationRaw.includes('://');
|
|
133
|
+
endpoints.set(name, {
|
|
134
|
+
name,
|
|
135
|
+
location: remote ? null : locationRaw.replaceAll('\\', '/'),
|
|
136
|
+
remote,
|
|
137
|
+
});
|
|
138
|
+
}
|
|
139
|
+
return { status: 'available', endpoints };
|
|
140
|
+
}
|
|
141
|
+
let ukpRegistrySnapshot;
|
|
142
|
+
/**
|
|
143
|
+
* Live fetch: one `ukp list --json -g` per process, memoized — resolution
|
|
144
|
+
* never spawns per reference. `-g` reads the whole registry, not the
|
|
145
|
+
* workspace-scoped view: whether a reference dangles is a whole-registry
|
|
146
|
+
* question, since a document may legitimately point at an endpoint outside
|
|
147
|
+
* the current workspace scope, and resolution must not inherit that scope.
|
|
148
|
+
* Builds predating the flag answer non-zero and land in the degrade path,
|
|
149
|
+
* same as no `--json`. Every failure mode — no ukp on PATH, a failed spawn,
|
|
150
|
+
* non-zero exit, unparseable output — is registry-unavailable, which
|
|
151
|
+
* downgrades resolution to a warning: a missing machine contract must not
|
|
152
|
+
* fail a repo.
|
|
153
|
+
*/
|
|
154
|
+
export function fetchUkpRegistry() {
|
|
155
|
+
if (ukpRegistrySnapshot === undefined) {
|
|
156
|
+
ukpRegistrySnapshot = probeUkpRegistry();
|
|
157
|
+
}
|
|
158
|
+
return ukpRegistrySnapshot;
|
|
159
|
+
}
|
|
160
|
+
function probeUkpRegistry() {
|
|
161
|
+
let captured;
|
|
162
|
+
try {
|
|
163
|
+
captured = captureCliExit('ukp', ['list', '--json', '-g'], 'ukp-list');
|
|
164
|
+
}
|
|
165
|
+
catch (error) {
|
|
166
|
+
return { status: 'unavailable', reason: `ukp CLI could not be launched (${error instanceof Error ? error.message : String(error)})` };
|
|
167
|
+
}
|
|
168
|
+
if (captured.status !== 0) {
|
|
169
|
+
const hint = captured.stderr.split(/\r?\n/)[0]?.trim() ?? '';
|
|
170
|
+
return { status: 'unavailable', reason: `ukp list --json -g exited ${captured.status}${hint === '' ? '' : `: ${hint}`}` };
|
|
171
|
+
}
|
|
172
|
+
return parseUkpListJson(captured.stdout);
|
|
173
|
+
}
|
|
174
|
+
/**
|
|
175
|
+
* ukp resolution, two tiers: endpoint existence is a registry lookup; path
|
|
176
|
+
* existence is an fs check against the binding root — never a content read.
|
|
177
|
+
* Remote (ssh) endpoints verify endpoint existence only; their paths are not
|
|
178
|
+
* locally checkable. A bare endpoint reference (`ukp://name`) has no path
|
|
179
|
+
* tier at all. Exposed against a caller-supplied snapshot so replay tests
|
|
180
|
+
* (and consumers re-judging a captured registry) never spawn.
|
|
181
|
+
*/
|
|
182
|
+
export function resolveUkpWith(address, registry) {
|
|
183
|
+
if (registry.status === 'unavailable') {
|
|
184
|
+
return { status: 'degraded', reason: registry.reason };
|
|
185
|
+
}
|
|
186
|
+
const separator = address.indexOf('/');
|
|
187
|
+
const endpoint = separator === -1 ? address : address.slice(0, separator);
|
|
188
|
+
const rest = separator === -1 ? '' : address.slice(separator + 1);
|
|
189
|
+
const record = registry.endpoints.get(endpoint);
|
|
190
|
+
if (record === undefined)
|
|
191
|
+
return { status: 'unknown-endpoint', endpoint };
|
|
192
|
+
if (record.remote)
|
|
193
|
+
return { status: 'ok' };
|
|
194
|
+
const root = record.location;
|
|
195
|
+
if (!existsSync(root))
|
|
196
|
+
return { status: 'dead-binding', endpoint };
|
|
197
|
+
if (rest === '' || existsSync(resolve(root, rest)))
|
|
198
|
+
return { status: 'ok' };
|
|
199
|
+
return { status: 'missing-path', endpoint, path: rest };
|
|
200
|
+
}
|
|
201
|
+
function resolveUkp(address) {
|
|
202
|
+
return resolveUkpWith(address, fetchUkpRegistry());
|
|
203
|
+
}
|
|
204
|
+
function isRecord(value) {
|
|
205
|
+
return value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
206
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/** One moved pair's repo-root-relative posix form. */
|
|
2
|
+
export interface TextualShift {
|
|
3
|
+
from: string;
|
|
4
|
+
to: string;
|
|
5
|
+
}
|
|
6
|
+
/** One textual occurrence located byte-exactly, same contract as a link rewrite. */
|
|
7
|
+
export interface TextualEdit {
|
|
8
|
+
/** Byte offset of the matched token start in the source. */
|
|
9
|
+
start: number;
|
|
10
|
+
/** Exclusive byte offset of the token end. */
|
|
11
|
+
end: number;
|
|
12
|
+
/** 1-based source line. */
|
|
13
|
+
line: number;
|
|
14
|
+
/** The matched token exactly as authored. */
|
|
15
|
+
from: string;
|
|
16
|
+
/** The full replacement text for [start, end). */
|
|
17
|
+
replacement: string;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Every textual occurrence of the shifted paths in `source`, in document
|
|
21
|
+
* order. Edits never overlap each other (distinct AST zones), never overlap a
|
|
22
|
+
* link destination or label (those live in link-syntax nodes the zone walk
|
|
23
|
+
* does not enter), and are byte-exact — the apply pass splices [start, end)
|
|
24
|
+
* with `replacement` and touches nothing else.
|
|
25
|
+
*/
|
|
26
|
+
export declare function scanTextualOccurrences(source: string, shifts: readonly TextualShift[]): TextualEdit[];
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Textual occurrence seam: non-link renderings of a moved
|
|
3
|
+
* path — tree-diagram lines in code blocks, inline code spans, heading path
|
|
4
|
+
* strings — ride the same plan-then-apply as links (the opt-in `textual`
|
|
5
|
+
* half of a rename plan).
|
|
6
|
+
*
|
|
7
|
+
* Closed zone set, on purpose. Code blocks, code spans, and the direct text
|
|
8
|
+
* children of headings are where a path string is a NAME (a tree node, a
|
|
9
|
+
* mention-as-identifier); body prose is never scanned — a path inside a
|
|
10
|
+
* sentence is author voice, and the closed set is exactly what a dry-run
|
|
11
|
+
* lists, so a human audits the boundary line by line.
|
|
12
|
+
*
|
|
13
|
+
* Closed match set: a token matches when it equals a moved pair's
|
|
14
|
+
* repo-root-relative path, equals that path plus a trailing `/` (a tree node),
|
|
15
|
+
* or extends it (`old/…` — only the prefix is rewritten, the suffix rides
|
|
16
|
+
* along). One leading `./` and one trailing `.` are tolerated around the token
|
|
17
|
+
* and preserved verbatim. Everything else — bare file names, prose words that
|
|
18
|
+
* happen to equal a moved directory's name — does not match: false negatives
|
|
19
|
+
* stay honest (the plan lists what changes), false rewrites would not.
|
|
20
|
+
*/
|
|
21
|
+
import { parseMarkdown, visitMarkdown } from './markdown.js';
|
|
22
|
+
/** Path-shaped token: the charset of repo-relative paths plus the tolerated decorations. */
|
|
23
|
+
const TOKEN = /[A-Za-z0-9_.\-/]+/g;
|
|
24
|
+
/**
|
|
25
|
+
* Match one token against the shifts; `undefined` = not an occurrence of any
|
|
26
|
+
* moved path. The tolerated `./` lead and `.` tail are stripped for the
|
|
27
|
+
* comparison and re-attached to the replacement.
|
|
28
|
+
*/
|
|
29
|
+
function matchToken(token, shifts) {
|
|
30
|
+
let body = token;
|
|
31
|
+
let lead = '';
|
|
32
|
+
let tail = '';
|
|
33
|
+
if (body.startsWith('./')) {
|
|
34
|
+
lead = './';
|
|
35
|
+
body = body.slice(2);
|
|
36
|
+
}
|
|
37
|
+
if (body.endsWith('.')) {
|
|
38
|
+
tail = '.';
|
|
39
|
+
body = body.slice(0, -1);
|
|
40
|
+
}
|
|
41
|
+
if (body === '')
|
|
42
|
+
return undefined;
|
|
43
|
+
for (const { from, to } of shifts) {
|
|
44
|
+
// `from` itself, a tree node `from/`, or any extension `from/…`: the prefix
|
|
45
|
+
// is rewritten, the suffix rides along unchanged.
|
|
46
|
+
if (body === from || body.startsWith(`${from}/`)) {
|
|
47
|
+
return { to: lead + to + body.slice(from.length) + tail };
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
return undefined;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Every textual occurrence of the shifted paths in `source`, in document
|
|
54
|
+
* order. Edits never overlap each other (distinct AST zones), never overlap a
|
|
55
|
+
* link destination or label (those live in link-syntax nodes the zone walk
|
|
56
|
+
* does not enter), and are byte-exact — the apply pass splices [start, end)
|
|
57
|
+
* with `replacement` and touches nothing else.
|
|
58
|
+
*/
|
|
59
|
+
export function scanTextualOccurrences(source, shifts) {
|
|
60
|
+
if (shifts.length === 0)
|
|
61
|
+
return [];
|
|
62
|
+
const edits = [];
|
|
63
|
+
const tree = parseMarkdown(source);
|
|
64
|
+
const lineStarts = [0];
|
|
65
|
+
for (let i = source.indexOf('\n'); i !== -1; i = source.indexOf('\n', i + 1))
|
|
66
|
+
lineStarts.push(i + 1);
|
|
67
|
+
const lineOf = (offset) => {
|
|
68
|
+
let low = 0;
|
|
69
|
+
let high = lineStarts.length - 1;
|
|
70
|
+
while (low < high) {
|
|
71
|
+
const mid = (low + high + 1) >> 1;
|
|
72
|
+
if (lineStarts[mid] <= offset)
|
|
73
|
+
low = mid;
|
|
74
|
+
else
|
|
75
|
+
high = mid - 1;
|
|
76
|
+
}
|
|
77
|
+
return low + 1;
|
|
78
|
+
};
|
|
79
|
+
const scanRange = (start, end) => {
|
|
80
|
+
TOKEN.lastIndex = 0;
|
|
81
|
+
for (const match of source.slice(start, end).matchAll(TOKEN)) {
|
|
82
|
+
const hit = matchToken(match[0], shifts);
|
|
83
|
+
if (hit === undefined)
|
|
84
|
+
continue;
|
|
85
|
+
const tokenStart = start + match.index;
|
|
86
|
+
edits.push({
|
|
87
|
+
start: tokenStart,
|
|
88
|
+
end: tokenStart + match[0].length,
|
|
89
|
+
line: lineOf(tokenStart),
|
|
90
|
+
from: match[0],
|
|
91
|
+
replacement: hit.to,
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
};
|
|
95
|
+
visitMarkdown(tree, (node) => {
|
|
96
|
+
const position = node.position;
|
|
97
|
+
if (position === undefined)
|
|
98
|
+
return;
|
|
99
|
+
if (node.type === 'code') {
|
|
100
|
+
// Fenced blocks: content spans the lines strictly between the fences;
|
|
101
|
+
// indented code starts on the node's own first line.
|
|
102
|
+
const openingRaw = source.slice(lineStarts[position.start.line - 1] + position.start.column - 1);
|
|
103
|
+
const openingFence = openingRaw.startsWith('```') || openingRaw.startsWith('~~~');
|
|
104
|
+
const firstLine = openingFence ? position.start.line + 1 : position.start.line;
|
|
105
|
+
const lastLine = openingFence ? position.end.line - 1 : position.end.line;
|
|
106
|
+
for (let line = firstLine; line <= lastLine; line += 1) {
|
|
107
|
+
const start = lineStarts[line - 1];
|
|
108
|
+
const end = line < lineStarts.length ? lineStarts[line] - 1 : source.length;
|
|
109
|
+
if (start < end)
|
|
110
|
+
scanRange(start, end);
|
|
111
|
+
}
|
|
112
|
+
return;
|
|
113
|
+
}
|
|
114
|
+
if (node.type === 'inlineCode') {
|
|
115
|
+
const start = position.start.offset;
|
|
116
|
+
const end = position.end.offset;
|
|
117
|
+
if (start === undefined || end === undefined)
|
|
118
|
+
return;
|
|
119
|
+
const raw = source.slice(start, end);
|
|
120
|
+
const open = /^`+/.exec(raw);
|
|
121
|
+
const close = /`+$/.exec(raw);
|
|
122
|
+
if (open === null || close === null)
|
|
123
|
+
return;
|
|
124
|
+
const contentStart = start + open[0].length;
|
|
125
|
+
const contentEnd = end - close[0].length;
|
|
126
|
+
if (contentStart < contentEnd)
|
|
127
|
+
scanRange(contentStart, contentEnd);
|
|
128
|
+
return;
|
|
129
|
+
}
|
|
130
|
+
if (node.type === 'heading') {
|
|
131
|
+
// Direct text children only: a link's label inside a heading is the link
|
|
132
|
+
// pass's business (mirror law), and a code span inside a heading is
|
|
133
|
+
// caught as its own inlineCode zone — no range is ever scanned twice.
|
|
134
|
+
for (const child of node.children) {
|
|
135
|
+
const childStart = child.position?.start.offset;
|
|
136
|
+
const childEnd = child.position?.end.offset;
|
|
137
|
+
if (child.type === 'text' && childStart !== undefined && childEnd !== undefined) {
|
|
138
|
+
scanRange(childStart, childEnd);
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
});
|
|
143
|
+
return edits;
|
|
144
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,77 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@catheadowl/md-tools",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Markdown reference toolchain for git repositories — doc-rename moves files with every reference rebased, doc-link checks links and anchors, doc-normalize migrates link style; the engine ships as an importable library.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"packageManager": "pnpm@12.8.1",
|
|
8
|
+
"main": "./lib/index.js",
|
|
9
|
+
"types": "./lib/index.d.ts",
|
|
10
|
+
"exports": {
|
|
11
|
+
".": {
|
|
12
|
+
"types": "./lib/index.d.ts",
|
|
13
|
+
"default": "./lib/index.js"
|
|
14
|
+
},
|
|
15
|
+
"./gate-check.js": {
|
|
16
|
+
"types": "./lib/gate-check.d.ts",
|
|
17
|
+
"default": "./lib/gate-check.js"
|
|
18
|
+
},
|
|
19
|
+
"./links/index.js": {
|
|
20
|
+
"types": "./lib/links/index.d.ts",
|
|
21
|
+
"default": "./lib/links/index.js"
|
|
22
|
+
},
|
|
23
|
+
"./conformance/cases.json": "./conformance/cases.json"
|
|
24
|
+
},
|
|
25
|
+
"bin": {
|
|
26
|
+
"doc-rename": "cli/rename.mjs",
|
|
27
|
+
"doc-link": "cli/doc-link.mjs",
|
|
28
|
+
"doc-normalize": "cli/normalize.mjs"
|
|
29
|
+
},
|
|
30
|
+
"files": [
|
|
31
|
+
"lib",
|
|
32
|
+
"cli",
|
|
33
|
+
"skills",
|
|
34
|
+
"conformance",
|
|
35
|
+
"README.md",
|
|
36
|
+
"LICENSE"
|
|
37
|
+
],
|
|
38
|
+
"engines": {
|
|
39
|
+
"node": ">=18"
|
|
40
|
+
},
|
|
41
|
+
"keywords": [
|
|
42
|
+
"markdown",
|
|
43
|
+
"links",
|
|
44
|
+
"references",
|
|
45
|
+
"link-checker",
|
|
46
|
+
"rename",
|
|
47
|
+
"refactor",
|
|
48
|
+
"wikilinks",
|
|
49
|
+
"anchors",
|
|
50
|
+
"git",
|
|
51
|
+
"documentation",
|
|
52
|
+
"cli"
|
|
53
|
+
],
|
|
54
|
+
"publishConfig": {
|
|
55
|
+
"access": "public"
|
|
56
|
+
},
|
|
57
|
+
"scripts": {
|
|
58
|
+
"build": "tsc -p tsconfig.json",
|
|
59
|
+
"typecheck": "tsc --noEmit -p tsconfig.json",
|
|
60
|
+
"test": "npm run build && node --test --test-isolation=none test/anchors.test.mjs test/markdown.test.mjs test/resolve.test.mjs test/rebase.test.mjs test/rename.test.mjs test/rename-posthoc.test.mjs test/rename-manifest.test.mjs test/normalize.test.mjs test/git-cache.test.mjs test/spawn-count.test.mjs test/gate-check.test.mjs test/conformance.test.mjs test/wiki.test.mjs test/scheme.test.mjs test/source-hygiene.test.mjs && node --test test/cli.test.mjs test/skills.test.mjs test/publish-hygiene.test.mjs",
|
|
61
|
+
"prepublishOnly": "npm test",
|
|
62
|
+
"check": "node cli/doc-link.mjs",
|
|
63
|
+
"setup": "node -e \"if(parseInt(process.versions.node)<18){console.error('md-tools needs node >= 18');process.exit(1)}\" && npm run build && npm link",
|
|
64
|
+
"teardown": "npm unlink -g @catheadowl/md-tools"
|
|
65
|
+
},
|
|
66
|
+
"dependencies": {
|
|
67
|
+
"@types/mdast": "^4.0.4",
|
|
68
|
+
"mdast-util-from-markdown": "^2.0.3",
|
|
69
|
+
"mdast-util-gfm": "^3.1.0",
|
|
70
|
+
"micromark-extension-gfm": "^3.0.0",
|
|
71
|
+
"yaml": "^2.9.1"
|
|
72
|
+
},
|
|
73
|
+
"devDependencies": {
|
|
74
|
+
"@types/node": "^22.0.0",
|
|
75
|
+
"typescript": "^5.9.0"
|
|
76
|
+
}
|
|
77
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: md-tools
|
|
3
|
+
description: Markdown link toolchain for git repos — move files with reference rebasing (doc-rename), link/anchor integrity check (doc-link), /-prefixed link migration (doc-normalize).
|
|
4
|
+
metadata:
|
|
5
|
+
author: catheadowl
|
|
6
|
+
version: "0.1.0"
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# md-tools
|
|
10
|
+
|
|
11
|
+
Three global CLIs over one shared engine. Run inside any git repository — paths
|
|
12
|
+
resolve from the current directory, the repo root is discovered via git.
|
|
13
|
+
|
|
14
|
+
| Task | Command |
|
|
15
|
+
|---|---|
|
|
16
|
+
| Move/rename a file or directory, rebasing every Markdown reference to it (atomic; a completed move with git evidence repairs links only) | `doc-rename <oldPath> <newPath>` |
|
|
17
|
+
| Check every internal link and heading anchor resolves (read-only, violations with file:line + remedy) | `doc-link` |
|
|
18
|
+
| Rewrite `/`-prefixed internal links to document-relative (one-time migration) | `doc-normalize [--fix]` |
|
|
19
|
+
|
|
20
|
+
The commands ship with the npm package `@catheadowl/md-tools` — if they are
|
|
21
|
+
not on PATH, install it first: `npm install -g @catheadowl/md-tools` (Node >= 18,
|
|
22
|
+
git on PATH).
|
|
23
|
+
|
|
24
|
+
Preview with `--dry-run` (`--json` for machine-readable output). Declared
|
|
25
|
+
freeze policy (`manifest.yml` + `archived: true` = frozen history, picked up
|
|
26
|
+
automatically): details in [references/freeze.md](references/freeze.md).
|
|
27
|
+
|
|
28
|
+
This skill is only the entry point — flags, semantics, and exit codes are
|
|
29
|
+
canonical in each command's `--help` and its CLI header comments. Run
|
|
30
|
+
`--help` instead of re-deriving behavior.
|
|
31
|
+
|
|
32
|
+
**Payload.** The directory containing this file is the whole install unit —
|
|
33
|
+
copy or link the subtree as-is (never SKILL.md alone); the package never
|
|
34
|
+
writes an agent directory. Install/refresh reconciliation contract (version
|
|
35
|
+
stamps, tool-owned vs operator-reserved keys, conflict handling):
|
|
36
|
+
[references/payload.md](references/payload.md).
|
|
37
|
+
|
|
38
|
+
**Scope.** Use for Markdown moves/renames or link-style migration inside a git
|
|
39
|
+
repo; run doc-link after those writes, or when an explicit link audit is asked
|
|
40
|
+
for. Not for external-URL checking (out of scope by design), non-Markdown
|
|
41
|
+
reference graphs, or non-git directories — the CLIs refuse there cleanly with
|
|
42
|
+
exit 2.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: md-tools declared freeze policy — manifest.yml archived declarations as the single policy source; narrow read pinning, replace-not-union flags, and fail-loud behavior for broken carriers
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Declared freeze policy (details)
|
|
6
|
+
|
|
7
|
+
Any directory whose `manifest.yml` declares `archived: true` is frozen history. Picked up automatically — no flags, no extra file.
|
|
8
|
+
|
|
9
|
+
- `doc-link` exempts frozen files as *sources*: their out-links are still checked, because frozen content is read-only by policy, so its rotting out-links are noise, not findings.
|
|
10
|
+
- `doc-rename` treats frozen files as read-only.
|
|
11
|
+
|
|
12
|
+
The read is narrowly pinned: only `manifest.yml`, a YAML mapping, `schema_version: 1`, and a boolean `archived` are recognized — anything else is ignored.
|
|
13
|
+
|
|
14
|
+
A declaration that is unparseable, not a mapping, wrong schema, or a non-boolean `archived` fails loudly: one-line diagnosis naming the file, exit 1. A broken carrier of the frozen fact must not silently drop the policy.
|
|
15
|
+
|
|
16
|
+
`--frozen <dirName>` (repeatable) **replaces** the declared policy for one run (not a union). `--no-manifest-freeze` skips manifest reading entirely. Repos without manifests need zero configuration.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: md-tools skill payload contract — the install unit, version stamps, refresh reconciliation and conflict handling (canonical home; the SKILL.md face carries only the short core)
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Payload & reconciliation (details)
|
|
6
|
+
|
|
7
|
+
This file is the canonical home of the payload contract; the SKILL.md face
|
|
8
|
+
carries only the short core pointing here. It rides along on every copy of
|
|
9
|
+
the subtree. Tool-owned frontmatter keys of this payload: `name`,
|
|
10
|
+
`description` (an author extending the tool-owned set declares it here, not
|
|
11
|
+
in frontmatter comments — frontmatter stays pure keys).
|
|
12
|
+
|
|
13
|
+
**Payload & reconciliation.** The skill root — the directory containing
|
|
14
|
+
SKILL.md — is the whole install unit: copy or link the subtree as-is;
|
|
15
|
+
sibling files (e.g. `references/`) ride along. Method and destination are
|
|
16
|
+
the installing agent's choice; the package never writes an agent directory.
|
|
17
|
+
When installing a copy, stamp it with the shipped tree's version (frontmatter
|
|
18
|
+
`metadata.payload-version`; update the stamp on refresh). On refresh,
|
|
19
|
+
everything in the subtree follows the shipped tree — body, files, and
|
|
20
|
+
tool-owned frontmatter (`name`, `description`, plus any keys the author
|
|
21
|
+
declares tool-owned) — except operator-reserved frontmatter keys (invocation
|
|
22
|
+
policy such as `disable-model-invocation`, and every key not declared
|
|
23
|
+
tool-owned), which belong to the host and survive refresh. A tool-owned key
|
|
24
|
+
that differs while `metadata.payload-version` equals the shipped tree's
|
|
25
|
+
version was changed locally: ask the operator; if you cannot ask (unattended
|
|
26
|
+
dispatch), stop and report without writing. After an upgrade, re-locate the
|
|
27
|
+
shipped tree (the package README records the path) and compare before
|
|
28
|
+
reconciling.
|