@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.
Files changed (48) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +94 -2
  3. package/cli/config.mjs +86 -0
  4. package/cli/doc-link.mjs +145 -0
  5. package/cli/kernel.mjs +86 -0
  6. package/cli/normalize.mjs +91 -0
  7. package/cli/rename.mjs +390 -0
  8. package/conformance/cases.json +55 -0
  9. package/lib/gate-check.d.ts +87 -0
  10. package/lib/gate-check.js +233 -0
  11. package/lib/index.d.ts +8 -0
  12. package/lib/index.js +8 -0
  13. package/lib/links/anchors.d.ts +43 -0
  14. package/lib/links/anchors.js +93 -0
  15. package/lib/links/cli.d.ts +33 -0
  16. package/lib/links/cli.js +86 -0
  17. package/lib/links/git.d.ts +156 -0
  18. package/lib/links/git.js +329 -0
  19. package/lib/links/index.d.ts +33 -0
  20. package/lib/links/index.js +25 -0
  21. package/lib/links/markdown.d.ts +127 -0
  22. package/lib/links/markdown.js +253 -0
  23. package/lib/links/normalize.d.ts +40 -0
  24. package/lib/links/normalize.js +102 -0
  25. package/lib/links/rebase.d.ts +24 -0
  26. package/lib/links/rebase.js +44 -0
  27. package/lib/links/rename.d.ts +257 -0
  28. package/lib/links/rename.js +864 -0
  29. package/lib/links/resolve.d.ts +145 -0
  30. package/lib/links/resolve.js +297 -0
  31. package/lib/links/scheme.d.ts +115 -0
  32. package/lib/links/scheme.js +209 -0
  33. package/lib/links/textual.d.ts +26 -0
  34. package/lib/links/textual.js +144 -0
  35. package/lib/measure/count.d.ts +47 -0
  36. package/lib/measure/count.js +91 -0
  37. package/lib/measure/document.d.ts +105 -0
  38. package/lib/measure/document.js +173 -0
  39. package/lib/measure/index.d.ts +22 -0
  40. package/lib/measure/index.js +18 -0
  41. package/lib/measure/sections.d.ts +38 -0
  42. package/lib/measure/sections.js +37 -0
  43. package/lib/measure/structure.d.ts +53 -0
  44. package/lib/measure/structure.js +186 -0
  45. package/package.json +82 -4
  46. package/skills/md-tools/SKILL.md +42 -0
  47. package/skills/md-tools/references/freeze.md +17 -0
  48. 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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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.