@catheadowl/md-tools 0.0.0-stage → 0.2.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 +94 -2
- package/cli/config.mjs +86 -0
- package/cli/doc-link.mjs +145 -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 +87 -0
- package/lib/gate-check.js +233 -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 +33 -0
- package/lib/links/cli.js +86 -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 +127 -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 +145 -0
- package/lib/links/resolve.js +297 -0
- package/lib/links/scheme.d.ts +115 -0
- package/lib/links/scheme.js +209 -0
- package/lib/links/textual.d.ts +26 -0
- package/lib/links/textual.js +144 -0
- package/lib/measure/count.d.ts +47 -0
- package/lib/measure/count.js +91 -0
- package/lib/measure/document.d.ts +105 -0
- package/lib/measure/document.js +173 -0
- package/lib/measure/index.d.ts +22 -0
- package/lib/measure/index.js +18 -0
- package/lib/measure/sections.d.ts +38 -0
- package/lib/measure/sections.js +37 -0
- package/lib/measure/structure.d.ts +53 -0
- package/lib/measure/structure.js +186 -0
- package/package.json +82 -4
- package/skills/md-tools/SKILL.md +42 -0
- package/skills/md-tools/references/freeze.md +17 -0
- package/skills/md-tools/references/payload.md +28 -0
|
@@ -0,0 +1,209 @@
|
|
|
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`. win32 launches through the shell (`win32Shell` — npm
|
|
150
|
+
* bin shims are script wrappers, not executables; args here are fixed
|
|
151
|
+
* literals, the opt-in's contract), so a missing ukp there answers as a
|
|
152
|
+
* non-zero exit rather than a failed spawn — same classification. Every
|
|
153
|
+
* failure mode — no ukp on PATH, a failed spawn, non-zero exit, unparseable
|
|
154
|
+
* output — is registry-unavailable, which downgrades resolution to a
|
|
155
|
+
* warning: a missing machine contract must not fail a repo.
|
|
156
|
+
*/
|
|
157
|
+
export function fetchUkpRegistry() {
|
|
158
|
+
if (ukpRegistrySnapshot === undefined) {
|
|
159
|
+
ukpRegistrySnapshot = probeUkpRegistry();
|
|
160
|
+
}
|
|
161
|
+
return ukpRegistrySnapshot;
|
|
162
|
+
}
|
|
163
|
+
function probeUkpRegistry() {
|
|
164
|
+
let captured;
|
|
165
|
+
try {
|
|
166
|
+
captured = captureCliExit('ukp', ['list', '--json', '-g'], 'ukp-list', { win32Shell: true });
|
|
167
|
+
}
|
|
168
|
+
catch (error) {
|
|
169
|
+
return { status: 'unavailable', reason: `ukp CLI could not be launched (${error instanceof Error ? error.message : String(error)})` };
|
|
170
|
+
}
|
|
171
|
+
if (captured.status !== 0) {
|
|
172
|
+
const hint = captured.stderr.split(/\r?\n/)[0]?.trim() ?? '';
|
|
173
|
+
return { status: 'unavailable', reason: `ukp list --json -g exited ${captured.status}${hint === '' ? '' : `: ${hint}`}` };
|
|
174
|
+
}
|
|
175
|
+
return parseUkpListJson(captured.stdout);
|
|
176
|
+
}
|
|
177
|
+
/**
|
|
178
|
+
* ukp resolution, two tiers: endpoint existence is a registry lookup; path
|
|
179
|
+
* existence is an fs check against the binding root — never a content read.
|
|
180
|
+
* Remote (ssh) endpoints verify endpoint existence only; their paths are not
|
|
181
|
+
* locally checkable. A bare endpoint reference (`ukp://name`) has no path
|
|
182
|
+
* tier at all. Exposed against a caller-supplied snapshot so replay tests
|
|
183
|
+
* (and consumers re-judging a captured registry) never spawn.
|
|
184
|
+
*/
|
|
185
|
+
export function resolveUkpWith(address, registry) {
|
|
186
|
+
if (registry.status === 'unavailable') {
|
|
187
|
+
return { status: 'degraded', reason: registry.reason };
|
|
188
|
+
}
|
|
189
|
+
const separator = address.indexOf('/');
|
|
190
|
+
const endpoint = separator === -1 ? address : address.slice(0, separator);
|
|
191
|
+
const rest = separator === -1 ? '' : address.slice(separator + 1);
|
|
192
|
+
const record = registry.endpoints.get(endpoint);
|
|
193
|
+
if (record === undefined)
|
|
194
|
+
return { status: 'unknown-endpoint', endpoint };
|
|
195
|
+
if (record.remote)
|
|
196
|
+
return { status: 'ok' };
|
|
197
|
+
const root = record.location;
|
|
198
|
+
if (!existsSync(root))
|
|
199
|
+
return { status: 'dead-binding', endpoint };
|
|
200
|
+
if (rest === '' || existsSync(resolve(root, rest)))
|
|
201
|
+
return { status: 'ok' };
|
|
202
|
+
return { status: 'missing-path', endpoint, path: rest };
|
|
203
|
+
}
|
|
204
|
+
function resolveUkp(address) {
|
|
205
|
+
return resolveUkpWith(address, fetchUkpRegistry());
|
|
206
|
+
}
|
|
207
|
+
function isRecord(value) {
|
|
208
|
+
return value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
209
|
+
}
|
|
@@ -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
|
+
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Physical-line counting over one measurement document. Range, blankness
|
|
3
|
+
* and exclusions are all explicit — there is no budget and no file-type
|
|
4
|
+
* default. Blankness is judged on the original physical rows with their
|
|
5
|
+
* container prefixes still in place, so a row holding only `>` counts as
|
|
6
|
+
* non-empty here even when its decoded content is not; consumers choose
|
|
7
|
+
* which axis they are counting. Exclusions remove the whole physical rows
|
|
8
|
+
* a structure occupies — a row shared by a list marker and a fence
|
|
9
|
+
* opener loses both. The result returns the count together with the
|
|
10
|
+
* ordered maximal included runs that sum to it, so every number can be
|
|
11
|
+
* explained row by row.
|
|
12
|
+
*/
|
|
13
|
+
import type { MarkdownDocument, MarkdownLineRange } from './document.js';
|
|
14
|
+
/**
|
|
15
|
+
* Whole-row exclusion families; overlapping families union, and a row
|
|
16
|
+
* shared by a list marker and a fence opener is removed once, for both.
|
|
17
|
+
* `fencedCode` removes delimiter rows together with payload rows;
|
|
18
|
+
* `fenceDelimiters` removes only the actual opening and closing rows of
|
|
19
|
+
* fenced code, leaving payload rows counted; `prefix` removes the rows
|
|
20
|
+
* the caller-claimed prefix covers. All families apply at every AST
|
|
21
|
+
* depth, inside containers included.
|
|
22
|
+
*/
|
|
23
|
+
export type MarkdownLineExclusion = 'prefix' | 'headings' | 'tables' | 'fencedCode' | 'fenceDelimiters' | 'indentedCode' | 'definitions';
|
|
24
|
+
export interface MarkdownLineSelection {
|
|
25
|
+
readonly range: MarkdownLineRange;
|
|
26
|
+
/**
|
|
27
|
+
* Judged on the original physical rows, container prefixes still in
|
|
28
|
+
* place. `none` counts every physical row. `space-tab` treats a row as
|
|
29
|
+
* blank when its content is empty or only U+0020/U+0009. `js-trim`
|
|
30
|
+
* treats a row as blank when ECMAScript's trim would empty it — the
|
|
31
|
+
* wider whitespace set, NBSP included.
|
|
32
|
+
*/
|
|
33
|
+
readonly blankness: 'none' | 'space-tab' | 'js-trim';
|
|
34
|
+
readonly exclude: readonly MarkdownLineExclusion[];
|
|
35
|
+
}
|
|
36
|
+
export interface MarkdownLineMeasurement {
|
|
37
|
+
readonly count: number;
|
|
38
|
+
/** Ordered maximal runs of included physical rows; explain count without duplicate rows. */
|
|
39
|
+
readonly included: readonly MarkdownLineRange[];
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Count the physical rows of one document-owned range under explicit
|
|
43
|
+
* blankness and exclusion rules. An unknown blankness or exclusion value
|
|
44
|
+
* throws TypeError; a foreign or malformed range throws TypeError via
|
|
45
|
+
* the document's ownership check.
|
|
46
|
+
*/
|
|
47
|
+
export declare function measureMarkdownLines(document: MarkdownDocument, selection: MarkdownLineSelection): MarkdownLineMeasurement;
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Physical-line counting over one measurement document. Range, blankness
|
|
3
|
+
* and exclusions are all explicit — there is no budget and no file-type
|
|
4
|
+
* default. Blankness is judged on the original physical rows with their
|
|
5
|
+
* container prefixes still in place, so a row holding only `>` counts as
|
|
6
|
+
* non-empty here even when its decoded content is not; consumers choose
|
|
7
|
+
* which axis they are counting. Exclusions remove the whole physical rows
|
|
8
|
+
* a structure occupies — a row shared by a list marker and a fence
|
|
9
|
+
* opener loses both. The result returns the count together with the
|
|
10
|
+
* ordered maximal included runs that sum to it, so every number can be
|
|
11
|
+
* explained row by row.
|
|
12
|
+
*/
|
|
13
|
+
import { requireOwnedRange } from './document.js';
|
|
14
|
+
const EXCLUSIONS = [
|
|
15
|
+
'prefix', 'headings', 'tables', 'fencedCode', 'fenceDelimiters', 'indentedCode', 'definitions',
|
|
16
|
+
];
|
|
17
|
+
const BLANKNESS = ['none', 'space-tab', 'js-trim'];
|
|
18
|
+
/** Every row range one exclusion family touches, at any AST depth. */
|
|
19
|
+
function excludedRows(document, exclusion) {
|
|
20
|
+
const { structure } = document;
|
|
21
|
+
switch (exclusion) {
|
|
22
|
+
case 'prefix': return [document.prefix];
|
|
23
|
+
case 'headings': return structure.headings.map(fact => fact.rows);
|
|
24
|
+
case 'tables': return structure.tables.map(fact => fact.rows);
|
|
25
|
+
case 'fencedCode': return structure.code.filter(fact => fact.kind === 'fenced').map(fact => fact.rows);
|
|
26
|
+
case 'indentedCode': return structure.code.filter(fact => fact.kind === 'indented').map(fact => fact.rows);
|
|
27
|
+
case 'definitions': return structure.definitions.map(fact => fact.rows);
|
|
28
|
+
case 'fenceDelimiters': {
|
|
29
|
+
const delimiters = [];
|
|
30
|
+
for (const fact of structure.code) {
|
|
31
|
+
if (fact.kind !== 'fenced')
|
|
32
|
+
continue;
|
|
33
|
+
if (fact.opening !== null)
|
|
34
|
+
delimiters.push(fact.opening);
|
|
35
|
+
if (fact.closing !== null)
|
|
36
|
+
delimiters.push(fact.closing);
|
|
37
|
+
}
|
|
38
|
+
return delimiters;
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Count the physical rows of one document-owned range under explicit
|
|
44
|
+
* blankness and exclusion rules. An unknown blankness or exclusion value
|
|
45
|
+
* throws TypeError; a foreign or malformed range throws TypeError via
|
|
46
|
+
* the document's ownership check.
|
|
47
|
+
*/
|
|
48
|
+
export function measureMarkdownLines(document, selection) {
|
|
49
|
+
const span = requireOwnedRange(document, selection.range);
|
|
50
|
+
if (!BLANKNESS.includes(selection.blankness)) {
|
|
51
|
+
throw new TypeError(`measure: blankness must be one of ${JSON.stringify(BLANKNESS)}, got ${JSON.stringify(selection.blankness)}`);
|
|
52
|
+
}
|
|
53
|
+
for (const exclusion of selection.exclude) {
|
|
54
|
+
if (!EXCLUSIONS.includes(exclusion)) {
|
|
55
|
+
throw new TypeError(`measure: unknown line exclusion ${JSON.stringify(exclusion)}`);
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
const excluded = new Set();
|
|
59
|
+
for (const exclusion of selection.exclude) {
|
|
60
|
+
for (const rows of excludedRows(document, exclusion)) {
|
|
61
|
+
for (let line = Math.max(rows.startLine, span.startLine); line < Math.min(rows.endLineExclusive, span.endLineExclusive); line++) {
|
|
62
|
+
excluded.add(line);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
const included = [];
|
|
67
|
+
let count = 0;
|
|
68
|
+
let runStart = null;
|
|
69
|
+
const closeRun = (endLineExclusive) => {
|
|
70
|
+
if (runStart !== null) {
|
|
71
|
+
included.push(document.range({ startLine: runStart, endLineExclusive }));
|
|
72
|
+
runStart = null;
|
|
73
|
+
}
|
|
74
|
+
};
|
|
75
|
+
for (let line = span.startLine; line < span.endLineExclusive; line++) {
|
|
76
|
+
const physical = document.lines[line - 1];
|
|
77
|
+
const content = physical === undefined ? '' : document.source.slice(physical.startOffset, physical.contentEndOffset);
|
|
78
|
+
const blank = selection.blankness === 'space-tab' ? /^[ \t]*$/.test(content)
|
|
79
|
+
: selection.blankness === 'js-trim' ? content.trim() === ''
|
|
80
|
+
: false;
|
|
81
|
+
if (excluded.has(line) || blank) {
|
|
82
|
+
closeRun(line);
|
|
83
|
+
continue;
|
|
84
|
+
}
|
|
85
|
+
count += 1;
|
|
86
|
+
if (runStart === null)
|
|
87
|
+
runStart = line;
|
|
88
|
+
}
|
|
89
|
+
closeRun(span.endLineExclusive);
|
|
90
|
+
return Object.freeze({ count, included: Object.freeze(included) });
|
|
91
|
+
}
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Measurement document — the single parse every measurement consumer
|
|
3
|
+
* shares. `createMarkdownDocument` keeps the original source string,
|
|
4
|
+
* scans its physical lines (LF, CRLF and CR each end one line; CRLF is a
|
|
5
|
+
* single terminator; a trailing terminator never creates an extra line),
|
|
6
|
+
* claims a caller-recognized leading prefix, parses the remaining body
|
|
7
|
+
* once and restores every tree position to original-source coordinates:
|
|
8
|
+
* UTF-16 offsets from 0, 1-based line/column, exclusive ends.
|
|
9
|
+
*
|
|
10
|
+
* Row ranges are document-owned: `range` validates the boundaries and
|
|
11
|
+
* brands the result, and a range handed to another document is a
|
|
12
|
+
* TypeError, never a silently accepted look-alike span.
|
|
13
|
+
*/
|
|
14
|
+
import type { Nodes, Root } from 'mdast';
|
|
15
|
+
import type { MarkdownStructure } from './structure.js';
|
|
16
|
+
/** Recursively readonly view of a shared, frozen tree. */
|
|
17
|
+
export type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends readonly unknown[] ? {
|
|
18
|
+
readonly [K in keyof T]: DeepReadonly<T[K]>;
|
|
19
|
+
} : T extends object ? {
|
|
20
|
+
readonly [K in keyof T]: DeepReadonly<T[K]>;
|
|
21
|
+
} : T;
|
|
22
|
+
export interface MarkdownPoint {
|
|
23
|
+
readonly line: number;
|
|
24
|
+
readonly column: number;
|
|
25
|
+
/** Original JavaScript string index in UTF-16 code units. */
|
|
26
|
+
readonly offset: number;
|
|
27
|
+
}
|
|
28
|
+
export interface MarkdownPosition {
|
|
29
|
+
readonly start: MarkdownPoint;
|
|
30
|
+
/** Exclusive endpoint; may be the parser's point after the last physical line. */
|
|
31
|
+
readonly end: MarkdownPoint;
|
|
32
|
+
}
|
|
33
|
+
export interface MarkdownLineSpan {
|
|
34
|
+
/** One-based inclusive physical line boundary. */
|
|
35
|
+
readonly startLine: number;
|
|
36
|
+
/** One-based exclusive boundary, at most physicalLineCount + 1. */
|
|
37
|
+
readonly endLineExclusive: number;
|
|
38
|
+
}
|
|
39
|
+
declare const rangeOwner: unique symbol;
|
|
40
|
+
/** Created only through the owning document; foreign-document use is an error. */
|
|
41
|
+
export interface MarkdownLineRange extends MarkdownLineSpan {
|
|
42
|
+
readonly [rangeOwner]: unknown;
|
|
43
|
+
}
|
|
44
|
+
export interface MarkdownPhysicalLine {
|
|
45
|
+
/** One-based line number, matching the tree coordinate system. */
|
|
46
|
+
readonly line: number;
|
|
47
|
+
readonly startOffset: number;
|
|
48
|
+
/** Excludes the line terminator. */
|
|
49
|
+
readonly contentEndOffset: number;
|
|
50
|
+
/** Includes the line terminator, when present. */
|
|
51
|
+
readonly endOffset: number;
|
|
52
|
+
readonly ending: '' | '\n' | '\r\n' | '\r';
|
|
53
|
+
}
|
|
54
|
+
export interface MarkdownDocumentOptions {
|
|
55
|
+
/**
|
|
56
|
+
* Caller-recognized leading prefix [0, offset) in UTF-16 code units:
|
|
57
|
+
* frontmatter the caller recognized, never parsed here. Must end after
|
|
58
|
+
* a complete line terminator or at actual end of input — a mid-line or
|
|
59
|
+
* CRLF-splitting offset is a RangeError, as is a non-integer, negative
|
|
60
|
+
* or out-of-source offset. `source` itself stays the full original
|
|
61
|
+
* string, BOM included; a leading U+FEFF rides on the source axis and
|
|
62
|
+
* shifts offsets and first-line columns of the restored tree, while the
|
|
63
|
+
* parser consumes it as a file marker with no syntax effect.
|
|
64
|
+
*/
|
|
65
|
+
readonly prefixEndOffset?: number;
|
|
66
|
+
}
|
|
67
|
+
export interface MarkdownDocument {
|
|
68
|
+
readonly source: string;
|
|
69
|
+
/** Every physical line, 1-based in the `line` field, in source order. */
|
|
70
|
+
readonly lines: readonly MarkdownPhysicalLine[];
|
|
71
|
+
/** All physical rows, prefix rows included. */
|
|
72
|
+
readonly whole: MarkdownLineRange;
|
|
73
|
+
/** The rows after the prefix; an empty prefix leaves it equal to `whole`. */
|
|
74
|
+
readonly body: MarkdownLineRange;
|
|
75
|
+
/** The rows the claimed prefix covers; empty when no prefix is claimed. */
|
|
76
|
+
readonly prefix: MarkdownLineRange;
|
|
77
|
+
readonly structure: MarkdownStructure;
|
|
78
|
+
/** Same tree on every access, with original-source coordinates. */
|
|
79
|
+
readonly tree: DeepReadonly<Root>;
|
|
80
|
+
/**
|
|
81
|
+
* Validates integral boundaries and creates a document-owned row range.
|
|
82
|
+
* A non-integer, reversed or out-of-bounds span throws RangeError; a
|
|
83
|
+
* range created by another document throws TypeError.
|
|
84
|
+
*/
|
|
85
|
+
range(span: MarkdownLineSpan): MarkdownLineRange;
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Resolve one document-owned row range to its span. A range from another
|
|
89
|
+
* document — or a plain object shaped like one — is a TypeError: row math
|
|
90
|
+
* silently applied to the wrong document is how same-named metrics drift.
|
|
91
|
+
*/
|
|
92
|
+
export declare function requireOwnedRange(document: MarkdownDocument, range: MarkdownLineRange): MarkdownLineSpan;
|
|
93
|
+
/**
|
|
94
|
+
* Create the shared measurement document for one Markdown source. The
|
|
95
|
+
* body is parsed exactly once; structure facts, section partition and
|
|
96
|
+
* line counting all read that same tree. A non-string source throws
|
|
97
|
+
* TypeError; the empty string is a valid zero-line document. The empty
|
|
98
|
+
* body's tree root sits at the real end-of-input point, and line ranges
|
|
99
|
+
* of an empty body are [L+1, L+1).
|
|
100
|
+
*/
|
|
101
|
+
export declare function createMarkdownDocument(source: string, options?: MarkdownDocumentOptions): MarkdownDocument;
|
|
102
|
+
export type MarkdownVisitor = (node: DeepReadonly<Nodes>, ancestors: readonly DeepReadonly<Nodes>[]) => false | void;
|
|
103
|
+
/** Pre-order visit over the document's shared tree; returning false prunes a node's children. Never parses again. */
|
|
104
|
+
export declare function visitMarkdownDocument(document: MarkdownDocument, visitor: MarkdownVisitor): void;
|
|
105
|
+
export {};
|