@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,173 @@
|
|
|
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 { parseMarkdown } from '../links/markdown.js';
|
|
15
|
+
import { buildStructure } from './structure.js';
|
|
16
|
+
const rangeOwner = Symbol('markdownLineRangeOwner');
|
|
17
|
+
/** Owner identity for the ranges each document hands out. */
|
|
18
|
+
const documentOwners = new WeakMap();
|
|
19
|
+
/**
|
|
20
|
+
* Resolve one document-owned row range to its span. A range from another
|
|
21
|
+
* document — or a plain object shaped like one — is a TypeError: row math
|
|
22
|
+
* silently applied to the wrong document is how same-named metrics drift.
|
|
23
|
+
*/
|
|
24
|
+
export function requireOwnedRange(document, range) {
|
|
25
|
+
const owner = documentOwners.get(document);
|
|
26
|
+
if (owner === undefined || typeof range !== 'object' || range === null
|
|
27
|
+
|| range[rangeOwner] !== owner) {
|
|
28
|
+
throw new TypeError('measure: line range was not created by this document');
|
|
29
|
+
}
|
|
30
|
+
return { startLine: range.startLine, endLineExclusive: range.endLineExclusive };
|
|
31
|
+
}
|
|
32
|
+
/** Split the source into physical lines without normalizing any terminator. */
|
|
33
|
+
function scanLines(source) {
|
|
34
|
+
const lines = [];
|
|
35
|
+
let start = 0;
|
|
36
|
+
while (start < source.length) {
|
|
37
|
+
let contentEnd = start;
|
|
38
|
+
while (contentEnd < source.length && source[contentEnd] !== '\n' && source[contentEnd] !== '\r')
|
|
39
|
+
contentEnd += 1;
|
|
40
|
+
if (contentEnd === source.length) {
|
|
41
|
+
lines.push({ line: lines.length + 1, startOffset: start, contentEndOffset: contentEnd, endOffset: contentEnd, ending: '' });
|
|
42
|
+
break;
|
|
43
|
+
}
|
|
44
|
+
const ending = source[contentEnd] === '\r'
|
|
45
|
+
? (source[contentEnd + 1] === '\n' ? '\r\n' : '\r')
|
|
46
|
+
: '\n';
|
|
47
|
+
const endOffset = contentEnd + ending.length;
|
|
48
|
+
lines.push({ line: lines.length + 1, startOffset: start, contentEndOffset: contentEnd, endOffset, ending });
|
|
49
|
+
start = endOffset;
|
|
50
|
+
}
|
|
51
|
+
return lines;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* The zero-width point at actual end of input: still on the last physical
|
|
55
|
+
* line when it has no terminator, on the next line's column 1 when it does.
|
|
56
|
+
*/
|
|
57
|
+
function eofPoint(source, lines) {
|
|
58
|
+
const last = lines[lines.length - 1];
|
|
59
|
+
if (last === undefined)
|
|
60
|
+
return { line: 1, column: 1, offset: 0 };
|
|
61
|
+
if (last.ending === '') {
|
|
62
|
+
return { line: last.line, column: last.contentEndOffset - last.startOffset + 1, offset: last.contentEndOffset };
|
|
63
|
+
}
|
|
64
|
+
return { line: last.line + 1, column: 1, offset: source.length };
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Shift every position in the body-local tree back onto the original
|
|
68
|
+
* source. Offsets and lines always shift; a leading U+FEFF BOM shifts
|
|
69
|
+
* only the first line's columns, because the parser consumes it as a
|
|
70
|
+
* file marker while it still occupies one column of the original line.
|
|
71
|
+
*/
|
|
72
|
+
function restorePositions(root, offsetShift, lineShift, firstColumnShift) {
|
|
73
|
+
const restorePoint = (point) => {
|
|
74
|
+
if (point.line === 1)
|
|
75
|
+
point.column += firstColumnShift;
|
|
76
|
+
point.line += lineShift;
|
|
77
|
+
point.offset = (point.offset ?? 0) + offsetShift;
|
|
78
|
+
};
|
|
79
|
+
const restore = (node) => {
|
|
80
|
+
if (node.position !== undefined) {
|
|
81
|
+
restorePoint(node.position.start);
|
|
82
|
+
restorePoint(node.position.end);
|
|
83
|
+
}
|
|
84
|
+
if ('children' in node)
|
|
85
|
+
for (const child of node.children)
|
|
86
|
+
restore(child);
|
|
87
|
+
};
|
|
88
|
+
restore(root);
|
|
89
|
+
}
|
|
90
|
+
function deepFreeze(value) {
|
|
91
|
+
if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
|
|
92
|
+
Object.freeze(value);
|
|
93
|
+
for (const key of Object.getOwnPropertyNames(value)) {
|
|
94
|
+
deepFreeze(value[key]);
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
return value;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Create the shared measurement document for one Markdown source. The
|
|
101
|
+
* body is parsed exactly once; structure facts, section partition and
|
|
102
|
+
* line counting all read that same tree. A non-string source throws
|
|
103
|
+
* TypeError; the empty string is a valid zero-line document. The empty
|
|
104
|
+
* body's tree root sits at the real end-of-input point, and line ranges
|
|
105
|
+
* of an empty body are [L+1, L+1).
|
|
106
|
+
*/
|
|
107
|
+
export function createMarkdownDocument(source, options = {}) {
|
|
108
|
+
if (typeof source !== 'string')
|
|
109
|
+
throw new TypeError('measure: source must be a string');
|
|
110
|
+
const prefixEndOffset = options.prefixEndOffset ?? 0;
|
|
111
|
+
if (!Number.isInteger(prefixEndOffset) || prefixEndOffset < 0 || prefixEndOffset > source.length) {
|
|
112
|
+
throw new RangeError(`measure: prefixEndOffset ${prefixEndOffset} is outside the source`);
|
|
113
|
+
}
|
|
114
|
+
if (prefixEndOffset !== 0 && prefixEndOffset !== source.length) {
|
|
115
|
+
const previous = source[prefixEndOffset - 1];
|
|
116
|
+
const afterTerminator = previous === '\n' || (previous === '\r' && source[prefixEndOffset] !== '\n');
|
|
117
|
+
if (!afterTerminator) {
|
|
118
|
+
throw new RangeError('measure: prefixEndOffset must end after a complete line terminator or at actual end of input');
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
const lines = scanLines(source);
|
|
122
|
+
let prefixLines = 0;
|
|
123
|
+
while (prefixLines < lines.length && lines[prefixLines].endOffset <= prefixEndOffset)
|
|
124
|
+
prefixLines += 1;
|
|
125
|
+
const bodyText = source.slice(prefixEndOffset);
|
|
126
|
+
const bomShift = bodyText.charCodeAt(0) === 0xfeff ? 1 : 0;
|
|
127
|
+
const tree = parseMarkdown(bodyText);
|
|
128
|
+
if (bodyText === '') {
|
|
129
|
+
const point = eofPoint(source, lines);
|
|
130
|
+
tree.position = { start: point, end: point };
|
|
131
|
+
}
|
|
132
|
+
else if (prefixEndOffset + bomShift > 0) {
|
|
133
|
+
restorePositions(tree, prefixEndOffset + bomShift, prefixLines, bomShift);
|
|
134
|
+
}
|
|
135
|
+
const owner = Symbol('owner');
|
|
136
|
+
const range = (span) => {
|
|
137
|
+
const { startLine, endLineExclusive } = span ?? {};
|
|
138
|
+
if (!Number.isInteger(startLine) || !Number.isInteger(endLineExclusive)
|
|
139
|
+
|| startLine < 1 || startLine > endLineExclusive || endLineExclusive > lines.length + 1) {
|
|
140
|
+
throw new RangeError(`measure: invalid line span [${startLine}, ${endLineExclusive}) for a document with ${lines.length} physical lines`);
|
|
141
|
+
}
|
|
142
|
+
return Object.freeze({ startLine, endLineExclusive, [rangeOwner]: owner });
|
|
143
|
+
};
|
|
144
|
+
const whole = range({ startLine: 1, endLineExclusive: lines.length + 1 });
|
|
145
|
+
const prefix = range({ startLine: 1, endLineExclusive: prefixLines + 1 });
|
|
146
|
+
const body = range({ startLine: prefixLines + 1, endLineExclusive: lines.length + 1 });
|
|
147
|
+
const structure = buildStructure(tree, source, lines, range);
|
|
148
|
+
const document = {
|
|
149
|
+
source,
|
|
150
|
+
lines: deepFreeze(lines),
|
|
151
|
+
whole,
|
|
152
|
+
prefix,
|
|
153
|
+
body,
|
|
154
|
+
structure,
|
|
155
|
+
tree: deepFreeze(tree),
|
|
156
|
+
range,
|
|
157
|
+
};
|
|
158
|
+
Object.freeze(document);
|
|
159
|
+
documentOwners.set(document, owner);
|
|
160
|
+
return document;
|
|
161
|
+
}
|
|
162
|
+
/** Pre-order visit over the document's shared tree; returning false prunes a node's children. Never parses again. */
|
|
163
|
+
export function visitMarkdownDocument(document, visitor) {
|
|
164
|
+
const walk = (node, ancestors) => {
|
|
165
|
+
if (visitor(node, ancestors) === false)
|
|
166
|
+
return;
|
|
167
|
+
if ('children' in node) {
|
|
168
|
+
for (const child of node.children)
|
|
169
|
+
walk(child, [...ancestors, node]);
|
|
170
|
+
}
|
|
171
|
+
};
|
|
172
|
+
walk(document.tree, []);
|
|
173
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @catheadowl/md-tools measurement face — one shared parse per document,
|
|
3
|
+
* structure facts, section partition and explicit physical-line counting
|
|
4
|
+
* over Markdown text. Deliberately free of triage policy: budgets,
|
|
5
|
+
* genres, thresholds and routing stay with consumers. Import as
|
|
6
|
+
* `@catheadowl/md-tools/measure/index.js`.
|
|
7
|
+
*
|
|
8
|
+
* Sibling modules are this entry's implementation carriers; their shipped
|
|
9
|
+
* `.d.ts` files exist for type resolution, and only what is re-exported
|
|
10
|
+
* here is the supported surface: `document.js` owns the one-parse
|
|
11
|
+
* document and its row ranges, `structure.js` projects headings, code,
|
|
12
|
+
* tables and definitions off that tree, `sections.js` partitions it, and
|
|
13
|
+
* `count.js` counts rows.
|
|
14
|
+
* @module @catheadowl/md-tools/measure
|
|
15
|
+
*/
|
|
16
|
+
export { createMarkdownDocument, visitMarkdownDocument } from './document.js';
|
|
17
|
+
export type { DeepReadonly, MarkdownDocument, MarkdownDocumentOptions, MarkdownLineRange, MarkdownLineSpan, MarkdownPhysicalLine, MarkdownPoint, MarkdownPosition, MarkdownVisitor, } from './document.js';
|
|
18
|
+
export type { MarkdownBlock, MarkdownCode, MarkdownContainer, MarkdownHeading, MarkdownStructure } from './structure.js';
|
|
19
|
+
export { partitionMarkdownSections } from './sections.js';
|
|
20
|
+
export type { MarkdownPartition, MarkdownSection, MarkdownSectionSelection } from './sections.js';
|
|
21
|
+
export { measureMarkdownLines } from './count.js';
|
|
22
|
+
export type { MarkdownLineExclusion, MarkdownLineMeasurement, MarkdownLineSelection } from './count.js';
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @catheadowl/md-tools measurement face — one shared parse per document,
|
|
3
|
+
* structure facts, section partition and explicit physical-line counting
|
|
4
|
+
* over Markdown text. Deliberately free of triage policy: budgets,
|
|
5
|
+
* genres, thresholds and routing stay with consumers. Import as
|
|
6
|
+
* `@catheadowl/md-tools/measure/index.js`.
|
|
7
|
+
*
|
|
8
|
+
* Sibling modules are this entry's implementation carriers; their shipped
|
|
9
|
+
* `.d.ts` files exist for type resolution, and only what is re-exported
|
|
10
|
+
* here is the supported surface: `document.js` owns the one-parse
|
|
11
|
+
* document and its row ranges, `structure.js` projects headings, code,
|
|
12
|
+
* tables and definitions off that tree, `sections.js` partitions it, and
|
|
13
|
+
* `count.js` counts rows.
|
|
14
|
+
* @module @catheadowl/md-tools/measure
|
|
15
|
+
*/
|
|
16
|
+
export { createMarkdownDocument, visitMarkdownDocument } from './document.js';
|
|
17
|
+
export { partitionMarkdownSections } from './sections.js';
|
|
18
|
+
export { measureMarkdownLines } from './count.js';
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Section partition over one measurement document's structure. Heading
|
|
3
|
+
* levels and scope are always explicit: every selected heading opens a
|
|
4
|
+
* section — even with an empty body — unselected deeper headings stay
|
|
5
|
+
* body content, no section accumulates another, and the preamble spans
|
|
6
|
+
* the parsed body up to the first selected heading. Nothing about file
|
|
7
|
+
* names or genres decides the selection.
|
|
8
|
+
*/
|
|
9
|
+
import type { MarkdownDocument, MarkdownLineRange } from './document.js';
|
|
10
|
+
import type { MarkdownHeading } from './structure.js';
|
|
11
|
+
export interface MarkdownSectionSelection {
|
|
12
|
+
readonly levels: readonly (1 | 2 | 3 | 4 | 5 | 6)[];
|
|
13
|
+
/**
|
|
14
|
+
* `all` selects every matching heading at any container depth, in
|
|
15
|
+
* global source order; `root` selects only headings directly under the
|
|
16
|
+
* root. Under `all`, a container heading's section body still runs to
|
|
17
|
+
* the next selected heading's first row — container end does not end
|
|
18
|
+
* the section, so a root heading after a quote closes the quoted
|
|
19
|
+
* section at its own row.
|
|
20
|
+
*/
|
|
21
|
+
readonly scope: 'all' | 'root';
|
|
22
|
+
}
|
|
23
|
+
export interface MarkdownSection {
|
|
24
|
+
readonly heading: MarkdownHeading;
|
|
25
|
+
/** Excludes every source row occupied by the opening heading; empty body stays a section. */
|
|
26
|
+
readonly body: MarkdownLineRange;
|
|
27
|
+
}
|
|
28
|
+
export interface MarkdownPartition {
|
|
29
|
+
readonly preamble: MarkdownLineRange;
|
|
30
|
+
readonly sections: readonly MarkdownSection[];
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Partition the document's body into explicit-level sections, in source
|
|
34
|
+
* order. With no selected heading the sections array is empty and the
|
|
35
|
+
* preamble covers the whole body. Duplicate levels collapse; a level
|
|
36
|
+
* outside 1..6 throws RangeError, a non-empty levels array is required.
|
|
37
|
+
*/
|
|
38
|
+
export declare function partitionMarkdownSections(document: MarkdownDocument, selection: MarkdownSectionSelection): MarkdownPartition;
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Section partition over one measurement document's structure. Heading
|
|
3
|
+
* levels and scope are always explicit: every selected heading opens a
|
|
4
|
+
* section — even with an empty body — unselected deeper headings stay
|
|
5
|
+
* body content, no section accumulates another, and the preamble spans
|
|
6
|
+
* the parsed body up to the first selected heading. Nothing about file
|
|
7
|
+
* names or genres decides the selection.
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* Partition the document's body into explicit-level sections, in source
|
|
11
|
+
* order. With no selected heading the sections array is empty and the
|
|
12
|
+
* preamble covers the whole body. Duplicate levels collapse; a level
|
|
13
|
+
* outside 1..6 throws RangeError, a non-empty levels array is required.
|
|
14
|
+
*/
|
|
15
|
+
export function partitionMarkdownSections(document, selection) {
|
|
16
|
+
const levels = [...new Set(selection.levels)];
|
|
17
|
+
if (levels.length === 0) {
|
|
18
|
+
throw new RangeError('measure: partition levels must be a non-empty subset of 1..6');
|
|
19
|
+
}
|
|
20
|
+
if (levels.some(depth => !Number.isInteger(depth) || depth < 1 || depth > 6)) {
|
|
21
|
+
throw new RangeError(`measure: partition levels must stay within 1..6, got ${JSON.stringify(selection.levels)}`);
|
|
22
|
+
}
|
|
23
|
+
if (selection.scope !== 'all' && selection.scope !== 'root') {
|
|
24
|
+
throw new TypeError(`measure: partition scope must be 'all' or 'root', got ${JSON.stringify(selection.scope)}`);
|
|
25
|
+
}
|
|
26
|
+
const wanted = new Set(levels);
|
|
27
|
+
const selected = document.structure.headings.filter(heading => wanted.has(heading.depth) && (selection.scope === 'all' || heading.containers.length === 0));
|
|
28
|
+
const sections = selected.map((heading, index) => {
|
|
29
|
+
const endLineExclusive = index + 1 < selected.length ? selected[index + 1].rows.startLine : document.lines.length + 1;
|
|
30
|
+
return Object.freeze({ heading, body: document.range({ startLine: heading.rows.endLineExclusive, endLineExclusive }) });
|
|
31
|
+
});
|
|
32
|
+
const preamble = document.range({
|
|
33
|
+
startLine: document.body.startLine,
|
|
34
|
+
endLineExclusive: selected.length === 0 ? document.body.endLineExclusive : selected[0].rows.startLine,
|
|
35
|
+
});
|
|
36
|
+
return Object.freeze({ preamble, sections: Object.freeze(sections) });
|
|
37
|
+
}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Structure facts over one measurement document's shared tree: every real
|
|
3
|
+
* heading, code block, GFM table and link definition, each with its
|
|
4
|
+
* original position, its occupied physical rows and its container
|
|
5
|
+
* ancestors. Ancestors never mask descendants and never replace the AST
|
|
6
|
+
* classification — a table inside a blockquote is a table fact whose
|
|
7
|
+
* containers name the blockquote, not a blockquote-only row.
|
|
8
|
+
*
|
|
9
|
+
* Fenced code additionally gets a source projection the parser does not
|
|
10
|
+
* hand out directly: opening/closing delimiter rows and raw payload rows.
|
|
11
|
+
* A closing row exists only where a legal closer terminates the fence —
|
|
12
|
+
* shorter, wrong-character or junk-carrying rows stay payload, and a
|
|
13
|
+
* fence left open by its container ends with the container instead of
|
|
14
|
+
* swallowing the following root-level content.
|
|
15
|
+
*/
|
|
16
|
+
import type { Nodes } from 'mdast';
|
|
17
|
+
import type { MarkdownLineRange, MarkdownLineSpan, MarkdownPhysicalLine, MarkdownPosition } from './document.js';
|
|
18
|
+
export interface MarkdownContainer {
|
|
19
|
+
readonly type: 'blockquote' | 'list' | 'listItem' | 'footnoteDefinition';
|
|
20
|
+
readonly position: MarkdownPosition;
|
|
21
|
+
}
|
|
22
|
+
export interface MarkdownBlock {
|
|
23
|
+
readonly position: MarkdownPosition;
|
|
24
|
+
readonly rows: MarkdownLineRange;
|
|
25
|
+
readonly containers: readonly MarkdownContainer[];
|
|
26
|
+
}
|
|
27
|
+
export interface MarkdownHeading extends MarkdownBlock {
|
|
28
|
+
readonly depth: 1 | 2 | 3 | 4 | 5 | 6;
|
|
29
|
+
readonly style: 'atx' | 'setext';
|
|
30
|
+
readonly text: string;
|
|
31
|
+
}
|
|
32
|
+
export interface MarkdownCode extends MarkdownBlock {
|
|
33
|
+
readonly kind: 'fenced' | 'indented';
|
|
34
|
+
/** Null for indented code. Closing delimiter is null for an unclosed fence. */
|
|
35
|
+
readonly opening: MarkdownLineRange | null;
|
|
36
|
+
readonly closing: MarkdownLineRange | null;
|
|
37
|
+
/** Raw rows within this AST code node, excluding delimiters; includes container prefixes. An unclosed container fence may end before document EOF. */
|
|
38
|
+
readonly payloadRows: MarkdownLineRange;
|
|
39
|
+
/** Parser-decoded code value, without container prefixes; not a source slice. */
|
|
40
|
+
readonly value: string;
|
|
41
|
+
readonly lang: string | null;
|
|
42
|
+
readonly meta: string | null;
|
|
43
|
+
}
|
|
44
|
+
export interface MarkdownStructure {
|
|
45
|
+
readonly headings: readonly MarkdownHeading[];
|
|
46
|
+
readonly code: readonly MarkdownCode[];
|
|
47
|
+
readonly tables: readonly MarkdownBlock[];
|
|
48
|
+
readonly definitions: readonly MarkdownBlock[];
|
|
49
|
+
}
|
|
50
|
+
type RangeFactory = (span: MarkdownLineSpan) => MarkdownLineRange;
|
|
51
|
+
/** Collect the structure facts of one shared tree, in source order, without masking ancestors. */
|
|
52
|
+
export declare function buildStructure(tree: Nodes, source: string, lines: readonly MarkdownPhysicalLine[], rangeFor: RangeFactory): MarkdownStructure;
|
|
53
|
+
export {};
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Structure facts over one measurement document's shared tree: every real
|
|
3
|
+
* heading, code block, GFM table and link definition, each with its
|
|
4
|
+
* original position, its occupied physical rows and its container
|
|
5
|
+
* ancestors. Ancestors never mask descendants and never replace the AST
|
|
6
|
+
* classification — a table inside a blockquote is a table fact whose
|
|
7
|
+
* containers name the blockquote, not a blockquote-only row.
|
|
8
|
+
*
|
|
9
|
+
* Fenced code additionally gets a source projection the parser does not
|
|
10
|
+
* hand out directly: opening/closing delimiter rows and raw payload rows.
|
|
11
|
+
* A closing row exists only where a legal closer terminates the fence —
|
|
12
|
+
* shorter, wrong-character or junk-carrying rows stay payload, and a
|
|
13
|
+
* fence left open by its container ends with the container instead of
|
|
14
|
+
* swallowing the following root-level content.
|
|
15
|
+
*/
|
|
16
|
+
import { renderedText } from '../links/markdown.js';
|
|
17
|
+
function isContainer(node) {
|
|
18
|
+
return node.type === 'blockquote' || node.type === 'list' || node.type === 'listItem' || node.type === 'footnoteDefinition';
|
|
19
|
+
}
|
|
20
|
+
function pointFact(point) {
|
|
21
|
+
return { line: point.line, column: point.column, offset: point.offset ?? 0 };
|
|
22
|
+
}
|
|
23
|
+
function positionFact(position) {
|
|
24
|
+
return { start: pointFact(position.start), end: pointFact(position.end) };
|
|
25
|
+
}
|
|
26
|
+
function containerFacts(ancestors) {
|
|
27
|
+
return Object.freeze(ancestors
|
|
28
|
+
.filter(node => isContainer(node) && node.position !== undefined)
|
|
29
|
+
.map(node => Object.freeze({ type: node.type, position: positionFact(node.position) })));
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* The physical rows a node actually occupies. An exclusive end sitting at
|
|
33
|
+
* column 1 of the next line does not claim that line, and no node claims
|
|
34
|
+
* rows past the document's real physical end.
|
|
35
|
+
*/
|
|
36
|
+
function rowsFor(position, lines, rangeFor) {
|
|
37
|
+
const endLineExclusive = position.end.column === 1 ? position.end.line : position.end.line + 1;
|
|
38
|
+
return rangeFor({ startLine: position.start.line, endLineExclusive: Math.min(endLineExclusive, lines.length + 1) });
|
|
39
|
+
}
|
|
40
|
+
function lineText(source, lines, line) {
|
|
41
|
+
const physical = lines[line - 1];
|
|
42
|
+
return physical === undefined ? '' : source.slice(physical.startOffset, physical.contentEndOffset);
|
|
43
|
+
}
|
|
44
|
+
/** Expand tabs to four-column tab stops, the way block structure reads indentation. */
|
|
45
|
+
function expandTabs(text) {
|
|
46
|
+
if (!text.includes('\t'))
|
|
47
|
+
return text;
|
|
48
|
+
let expanded = '';
|
|
49
|
+
for (const char of text) {
|
|
50
|
+
if (char === '\t')
|
|
51
|
+
expanded += ' '.repeat(4 - (expanded.length % 4));
|
|
52
|
+
else
|
|
53
|
+
expanded += char;
|
|
54
|
+
}
|
|
55
|
+
return expanded;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Content column of a list item's first row: marker plus following spaces
|
|
59
|
+
* when content shares the row, one past the bare marker when it does not.
|
|
60
|
+
* Columns follow tab stops, so the marker is measured on the expanded row.
|
|
61
|
+
*/
|
|
62
|
+
function listItemContentIndent(item, source, lines) {
|
|
63
|
+
if (item.position === undefined)
|
|
64
|
+
return 1;
|
|
65
|
+
const physical = lines[item.position.start.line - 1];
|
|
66
|
+
if (physical === undefined)
|
|
67
|
+
return 1;
|
|
68
|
+
const rowText = source.slice(physical.startOffset, physical.contentEndOffset);
|
|
69
|
+
const lead = expandTabs(rowText.slice(0, (item.position.start.offset ?? 0) - physical.startOffset));
|
|
70
|
+
const fromMarker = expandTabs(rowText).slice(lead.length);
|
|
71
|
+
const marker = /^[ ]{0,3}(?:[-+*]|[0-9]{1,9}[.)])([ ]+|$)/.exec(fromMarker);
|
|
72
|
+
if (marker === null)
|
|
73
|
+
return 1;
|
|
74
|
+
if (marker[1] === undefined)
|
|
75
|
+
return marker[0].length + 1;
|
|
76
|
+
if (marker[0].length === fromMarker.length)
|
|
77
|
+
return marker[0].replace(/[ ]+$/, '').length + 1;
|
|
78
|
+
return marker[0].length;
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Whether one row is a legal closing fence for an opening run of
|
|
82
|
+
* `fenceLength` `fenceChar` characters: the same container continuation
|
|
83
|
+
* prefixes (blockquote markers, list-item content indent), then up to
|
|
84
|
+
* three spaces, the run, and nothing but spaces or tabs. Indentation is
|
|
85
|
+
* judged with tabs expanded to tab stops — a tab-indented continuation
|
|
86
|
+
* row is as legal as a space-indented one.
|
|
87
|
+
*/
|
|
88
|
+
function isClosingFenceRow(rowText, ancestors, source, lines, fenceChar, fenceLength) {
|
|
89
|
+
let rest = expandTabs(rowText);
|
|
90
|
+
for (const ancestor of ancestors) {
|
|
91
|
+
if (ancestor.type === 'blockquote') {
|
|
92
|
+
const prefix = /^[ ]{0,3}>[ ]?/.exec(rest);
|
|
93
|
+
if (prefix === null)
|
|
94
|
+
return false;
|
|
95
|
+
rest = rest.slice(prefix[0].length);
|
|
96
|
+
}
|
|
97
|
+
else if (ancestor.type === 'listItem') {
|
|
98
|
+
const indent = ' '.repeat(listItemContentIndent(ancestor, source, lines));
|
|
99
|
+
if (!rest.startsWith(indent))
|
|
100
|
+
return false;
|
|
101
|
+
rest = rest.slice(indent.length);
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
return new RegExp(`^[ ]{0,3}${fenceChar === '`' ? '`' : '~'}{${fenceLength},}[ \t]*$`).test(rest);
|
|
105
|
+
}
|
|
106
|
+
function codeFact(node, position, source, lines, rangeFor, ancestors, rows, containers) {
|
|
107
|
+
const startOffset = position.start.offset ?? 0;
|
|
108
|
+
const fenceChar = source[startOffset];
|
|
109
|
+
const fenced = fenceChar === '`' || fenceChar === '~';
|
|
110
|
+
let opening = null;
|
|
111
|
+
let closing = null;
|
|
112
|
+
if (fenced) {
|
|
113
|
+
// The node starts at the fence character itself; an indented code node
|
|
114
|
+
// starts at its first content column instead.
|
|
115
|
+
opening = rangeFor({ startLine: rows.startLine, endLineExclusive: rows.startLine + 1 });
|
|
116
|
+
let fenceLength = 0;
|
|
117
|
+
while (source[startOffset + fenceLength] === fenceChar)
|
|
118
|
+
fenceLength += 1;
|
|
119
|
+
const lastRow = rows.endLineExclusive - 1;
|
|
120
|
+
// A closed fence always ends on its closing row, so only that row can
|
|
121
|
+
// carry the closer; an opener-only node never closes onto itself.
|
|
122
|
+
if (lastRow > rows.startLine
|
|
123
|
+
&& isClosingFenceRow(lineText(source, lines, lastRow), ancestors, source, lines, fenceChar, fenceLength)) {
|
|
124
|
+
closing = rangeFor({ startLine: lastRow, endLineExclusive: lastRow + 1 });
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
const payloadRows = fenced
|
|
128
|
+
? rangeFor({ startLine: rows.startLine + 1, endLineExclusive: closing === null ? rows.endLineExclusive : closing.startLine })
|
|
129
|
+
: rows;
|
|
130
|
+
return Object.freeze({
|
|
131
|
+
position: positionFact(position),
|
|
132
|
+
rows,
|
|
133
|
+
containers,
|
|
134
|
+
kind: fenced ? 'fenced' : 'indented',
|
|
135
|
+
opening,
|
|
136
|
+
closing,
|
|
137
|
+
payloadRows,
|
|
138
|
+
value: node.value,
|
|
139
|
+
lang: node.lang ?? null,
|
|
140
|
+
meta: node.meta ?? null,
|
|
141
|
+
});
|
|
142
|
+
}
|
|
143
|
+
/** Collect the structure facts of one shared tree, in source order, without masking ancestors. */
|
|
144
|
+
export function buildStructure(tree, source, lines, rangeFor) {
|
|
145
|
+
const headings = [];
|
|
146
|
+
const code = [];
|
|
147
|
+
const tables = [];
|
|
148
|
+
const definitions = [];
|
|
149
|
+
const walk = (node, ancestors) => {
|
|
150
|
+
if (node.position !== undefined) {
|
|
151
|
+
const containers = containerFacts(ancestors);
|
|
152
|
+
const rows = rowsFor(node.position, lines, rangeFor);
|
|
153
|
+
if (node.type === 'heading') {
|
|
154
|
+
headings.push(Object.freeze({
|
|
155
|
+
position: positionFact(node.position),
|
|
156
|
+
rows,
|
|
157
|
+
containers,
|
|
158
|
+
depth: node.depth,
|
|
159
|
+
style: node.position.end.line > node.position.start.line ? 'setext' : 'atx',
|
|
160
|
+
text: renderedText(node),
|
|
161
|
+
}));
|
|
162
|
+
}
|
|
163
|
+
else if (node.type === 'code') {
|
|
164
|
+
code.push(codeFact(node, node.position, source, lines, rangeFor, ancestors, rows, containers));
|
|
165
|
+
}
|
|
166
|
+
else if (node.type === 'table' || node.type === 'definition') {
|
|
167
|
+
const fact = Object.freeze({ position: positionFact(node.position), rows, containers });
|
|
168
|
+
if (node.type === 'table')
|
|
169
|
+
tables.push(fact);
|
|
170
|
+
else
|
|
171
|
+
definitions.push(fact);
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
if ('children' in node) {
|
|
175
|
+
for (const child of node.children)
|
|
176
|
+
walk(child, [...ancestors, node]);
|
|
177
|
+
}
|
|
178
|
+
};
|
|
179
|
+
walk(tree, []);
|
|
180
|
+
return Object.freeze({
|
|
181
|
+
headings: Object.freeze(headings),
|
|
182
|
+
code: Object.freeze(code),
|
|
183
|
+
tables: Object.freeze(tables),
|
|
184
|
+
definitions: Object.freeze(definitions),
|
|
185
|
+
});
|
|
186
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,84 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@catheadowl/md-tools",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.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 for reference rebase/check and document structure measurement.",
|
|
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
|
+
"./measure/index.js": {
|
|
24
|
+
"types": "./lib/measure/index.d.ts",
|
|
25
|
+
"default": "./lib/measure/index.js"
|
|
26
|
+
},
|
|
27
|
+
"./conformance/cases.json": "./conformance/cases.json"
|
|
28
|
+
},
|
|
29
|
+
"bin": {
|
|
30
|
+
"doc-rename": "cli/rename.mjs",
|
|
31
|
+
"doc-link": "cli/doc-link.mjs",
|
|
32
|
+
"doc-normalize": "cli/normalize.mjs"
|
|
33
|
+
},
|
|
34
|
+
"files": [
|
|
35
|
+
"lib",
|
|
36
|
+
"cli",
|
|
37
|
+
"skills",
|
|
38
|
+
"conformance",
|
|
39
|
+
"README.md",
|
|
40
|
+
"LICENSE"
|
|
41
|
+
],
|
|
42
|
+
"engines": {
|
|
43
|
+
"node": ">=18"
|
|
44
|
+
},
|
|
45
|
+
"keywords": [
|
|
46
|
+
"markdown",
|
|
47
|
+
"links",
|
|
48
|
+
"references",
|
|
49
|
+
"link-checker",
|
|
50
|
+
"rename",
|
|
51
|
+
"refactor",
|
|
52
|
+
"wikilinks",
|
|
53
|
+
"anchors",
|
|
54
|
+
"git",
|
|
55
|
+
"documentation",
|
|
56
|
+
"cli",
|
|
57
|
+
"measure",
|
|
58
|
+
"structure",
|
|
59
|
+
"sections"
|
|
60
|
+
],
|
|
61
|
+
"publishConfig": {
|
|
62
|
+
"access": "public"
|
|
63
|
+
},
|
|
64
|
+
"scripts": {
|
|
65
|
+
"build": "tsc -p tsconfig.json",
|
|
66
|
+
"typecheck": "tsc --noEmit -p tsconfig.json",
|
|
67
|
+
"test": "npm run build && node --test --test-isolation=none test/anchors.test.mjs test/markdown.test.mjs test/measure.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",
|
|
68
|
+
"prepublishOnly": "npm test",
|
|
69
|
+
"check": "node cli/doc-link.mjs",
|
|
70
|
+
"setup": "node -e \"if(parseInt(process.versions.node)<18){console.error('md-tools needs node >= 18');process.exit(1)}\" && npm run build && npm link",
|
|
71
|
+
"teardown": "npm unlink -g @catheadowl/md-tools"
|
|
72
|
+
},
|
|
73
|
+
"dependencies": {
|
|
74
|
+
"@types/mdast": "^4.0.4",
|
|
75
|
+
"mdast-util-from-markdown": "^2.0.3",
|
|
76
|
+
"mdast-util-gfm": "^3.1.0",
|
|
77
|
+
"micromark-extension-gfm": "^3.0.0",
|
|
78
|
+
"yaml": "^2.9.1"
|
|
79
|
+
},
|
|
80
|
+
"devDependencies": {
|
|
81
|
+
"@types/node": "^22.0.0",
|
|
82
|
+
"typescript": "^5.9.0"
|
|
83
|
+
}
|
|
84
|
+
}
|
|
@@ -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.2.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.
|