@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,257 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Stable machine identifiers for every whole-plan refusal this kernel can
|
|
3
|
+
* emit. Contract identifiers, additive-only: a code is never renamed, never
|
|
4
|
+
* reused for a different meaning, and never derived from wording. Consumers
|
|
5
|
+
* that branch on the conflict kind (remedy attachment, description
|
|
6
|
+
* enumeration, output routing) must branch on the code, never on the reason
|
|
7
|
+
* text.
|
|
8
|
+
*/
|
|
9
|
+
export declare const RENAME_CONFLICT_CODES: readonly ["repo-root", "outside-repo", "old-path-missing", "old-path-untracked", "new-path-exists", "self-nesting", "no-rename-evidence", "sink-source-not-directory", "sink-no-children"];
|
|
10
|
+
/** One conflict kind of `RENAME_CONFLICT_CODES` — the closed union consumers map over. */
|
|
11
|
+
export type RenameConflictCode = (typeof RENAME_CONFLICT_CODES)[number];
|
|
12
|
+
/**
|
|
13
|
+
* Surface-neutral wording for each conflict code — the single source of the
|
|
14
|
+
* `reason` string every refusal carries. Model-facing projections may quote
|
|
15
|
+
* these verbatim; they must not re-derive competing wording for the same
|
|
16
|
+
* fact. Consumers keying a map over the codes stay complete by construction:
|
|
17
|
+
* a new code with no table entry fails to compile.
|
|
18
|
+
*/
|
|
19
|
+
export declare const RENAME_CONFLICT_MESSAGES: Readonly<Record<RenameConflictCode, string>>;
|
|
20
|
+
/**
|
|
21
|
+
* Conflict reason when git cannot witness that the (old, new) pair already
|
|
22
|
+
* completed — oldPath missing without evidence, or a self-nesting pair whose
|
|
23
|
+
* old path still stands while what sits under new is indistinguishable from
|
|
24
|
+
* a copy (D1: refuse with a remedy hint, never guess or restore). The remedy
|
|
25
|
+
* wording belongs to the plugin output layer; this lib only emits the
|
|
26
|
+
* structured reason. Alias of the message-table entry for consumers already
|
|
27
|
+
* branching on the constant.
|
|
28
|
+
*/
|
|
29
|
+
export declare const REASON_NO_RENAME_EVIDENCE: string;
|
|
30
|
+
/** Document-relative href from a source file's directory to an absolute target. */
|
|
31
|
+
export declare function rebaseHref(fromFile: string, toAbs: string): string;
|
|
32
|
+
/** One reference left untouched, with why (informational, never blocks apply). */
|
|
33
|
+
export interface RenameSkip {
|
|
34
|
+
file: string;
|
|
35
|
+
line: number;
|
|
36
|
+
url: string;
|
|
37
|
+
reason: string;
|
|
38
|
+
}
|
|
39
|
+
/** One label rewritten because it mirrored the reference's own destination. */
|
|
40
|
+
export interface RenameRelabel {
|
|
41
|
+
file: string;
|
|
42
|
+
line: number;
|
|
43
|
+
/** Label text before the rewrite. */
|
|
44
|
+
from: string;
|
|
45
|
+
/** The same rendering recomputed on the new destination. */
|
|
46
|
+
to: string;
|
|
47
|
+
}
|
|
48
|
+
/** One blocking issue: makes `certain` false, forbids apply. */
|
|
49
|
+
export interface RenameConflict {
|
|
50
|
+
/** Stable machine identifier of the conflict kind (`RENAME_CONFLICT_CODES`) — branch on this, never on `reason` text. */
|
|
51
|
+
code: RenameConflictCode;
|
|
52
|
+
file: string;
|
|
53
|
+
line: number;
|
|
54
|
+
url: string;
|
|
55
|
+
reason: string;
|
|
56
|
+
/**
|
|
57
|
+
* Informational history evidence (selected refusals only — see
|
|
58
|
+
* `RENAME_HISTORY_EVIDENCE_SHAPES`). Never a verdict: the default window
|
|
59
|
+
* is unchanged and records are listed verbatim, ambiguity included.
|
|
60
|
+
*/
|
|
61
|
+
historyEvidence?: RenameHistoryEvidence;
|
|
62
|
+
}
|
|
63
|
+
/** One rename record from git history, carried on refusal payloads (informational). */
|
|
64
|
+
export interface RenameHistoryRecord {
|
|
65
|
+
/** Commit that performed the rename (full hash). */
|
|
66
|
+
commit: string;
|
|
67
|
+
/** Repo-root-relative old side of the rename. */
|
|
68
|
+
oldPath: string;
|
|
69
|
+
/** Repo-root-relative new side of the rename. */
|
|
70
|
+
newPath: string;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* History evidence attached to selected refusals — one `git log` probe's
|
|
74
|
+
* findings, informational only: the default window is unchanged, records are
|
|
75
|
+
* listed verbatim (ambiguity included, never adjudicated). Each refusal
|
|
76
|
+
* branch fills only the field it probed.
|
|
77
|
+
*/
|
|
78
|
+
export interface RenameHistoryEvidence {
|
|
79
|
+
/**
|
|
80
|
+
* Direct rename records between the pair (`git log -M --diff-filter=R`;
|
|
81
|
+
* both pair sides must be under the pathspec — single-side pathspecs never
|
|
82
|
+
* surface R entries). Attached by the no-evidence refusal.
|
|
83
|
+
*/
|
|
84
|
+
records?: RenameHistoryRecord[];
|
|
85
|
+
/**
|
|
86
|
+
* Whether the old path has any git history at all. Attached by the plain
|
|
87
|
+
* old-path-missing refusal: `false` means the old path was never tracked —
|
|
88
|
+
* the strongest typo signal the payload can carry.
|
|
89
|
+
*/
|
|
90
|
+
everTracked?: boolean;
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* The history-evidence probe shapes, in the order the refusal branches attach
|
|
94
|
+
* them — the informational payload's schema manifest (surface-neutral
|
|
95
|
+
* summaries; model-facing descriptions project these instead of re-deriving
|
|
96
|
+
* the probe conditions).
|
|
97
|
+
*/
|
|
98
|
+
export declare const RENAME_HISTORY_EVIDENCE_SHAPES: ReadonlyArray<{
|
|
99
|
+
shape: 'pair-rename-records' | 'old-path-history';
|
|
100
|
+
summary: string;
|
|
101
|
+
}>;
|
|
102
|
+
/** One planned move: absolute old → new. A multi-pair plan (sink) applies every pair in one transaction. */
|
|
103
|
+
export interface RenamePair {
|
|
104
|
+
oldPath: string;
|
|
105
|
+
newPath: string;
|
|
106
|
+
}
|
|
107
|
+
/** One textual occurrence rewritten (the opt-in `textual` half; auditable like a relabel). */
|
|
108
|
+
export interface RenameTextual {
|
|
109
|
+
file: string;
|
|
110
|
+
line: number;
|
|
111
|
+
from: string;
|
|
112
|
+
to: string;
|
|
113
|
+
}
|
|
114
|
+
export interface RenamePlan {
|
|
115
|
+
/** Git worktree root (repo root) — the plan carries it so apply needs no re-discovery. */
|
|
116
|
+
root: string;
|
|
117
|
+
/** Absolute old path (file or directory; the sink aggregate for multi-pair plans). */
|
|
118
|
+
oldPath: string;
|
|
119
|
+
/** Absolute new path (file or directory; the sink aggregate for multi-pair plans). */
|
|
120
|
+
newPath: string;
|
|
121
|
+
/** Every planned move — one entry for a plain rename, one per child for a sink. */
|
|
122
|
+
pairs: RenamePair[];
|
|
123
|
+
/** Absolute post-move path → fully rewritten content (out-link + in-link + textual edits). */
|
|
124
|
+
editsByFile: Map<string, string>;
|
|
125
|
+
skips: RenameSkip[];
|
|
126
|
+
/**
|
|
127
|
+
* Labels rewritten alongside a destination (mirror labels only — see
|
|
128
|
+
* `relabelFor`). Reported so the cosmetic half of the edit is auditable;
|
|
129
|
+
* never a conflict, and never a skip (a skipped reference keeps its label).
|
|
130
|
+
*/
|
|
131
|
+
relabels: RenameRelabel[];
|
|
132
|
+
/** Textual occurrences rewritten (opt-in `textual` plans only; see `textual.ts`). */
|
|
133
|
+
textuals: RenameTextual[];
|
|
134
|
+
conflicts: RenameConflict[];
|
|
135
|
+
/**
|
|
136
|
+
* Post-hoc repair: the move already happened under git's witness, so apply
|
|
137
|
+
* rewrites links only — no `git mv`, and the apply result reports
|
|
138
|
+
* `moved: false` (D4).
|
|
139
|
+
*/
|
|
140
|
+
linkOnly: boolean;
|
|
141
|
+
}
|
|
142
|
+
export interface RenamePlanResult {
|
|
143
|
+
/** True when the plan is conflict-free and safe to apply. */
|
|
144
|
+
certain: boolean;
|
|
145
|
+
plan: RenamePlan;
|
|
146
|
+
}
|
|
147
|
+
export interface PlanRenameOptions {
|
|
148
|
+
/**
|
|
149
|
+
* Frozen (read-only by repo policy) source files, by absolute path. A frozen
|
|
150
|
+
* file still MOVES with its subtree, but its content is never rewritten:
|
|
151
|
+
* each reference that the plan would otherwise edit becomes a skip
|
|
152
|
+
* (reported, never touched). The one exception is the file's own archival
|
|
153
|
+
* move — a non-frozen source moving INTO a frozen directory is fully
|
|
154
|
+
* rewritten (freeze is judged at the pre-move position). Policy-free
|
|
155
|
+
* mechanism: the carrier constructs the predicate (e.g. from a
|
|
156
|
+
* `frozen-dirs` gate option); absent predicate = nothing is frozen.
|
|
157
|
+
*/
|
|
158
|
+
isFrozen?: (absFile: string) => boolean;
|
|
159
|
+
/**
|
|
160
|
+
* Opt-in textual rebase: non-link renderings of the
|
|
161
|
+
* moved path — tree-diagram lines in code blocks, code spans, heading path
|
|
162
|
+
* strings — join the plan (zone and match sets closed; see `textual.ts`).
|
|
163
|
+
* Default off: old paths in historical records are true statements.
|
|
164
|
+
*/
|
|
165
|
+
textual?: boolean;
|
|
166
|
+
/**
|
|
167
|
+
* Opt-in asserted repair: the caller declares the (old, new) pair already
|
|
168
|
+
* completed on out-of-band evidence (e.g. a rename record from history) —
|
|
169
|
+
* the assertion replaces the git witness and the same pair plans the
|
|
170
|
+
* link-only repair on the declared pair's projection. Default off: without
|
|
171
|
+
* git's witness the plan refuses whole. Policy-free mechanism: the carrier
|
|
172
|
+
* decides when an assertion is justified — the same authority the pending
|
|
173
|
+
* mode grants every caller pair.
|
|
174
|
+
*/
|
|
175
|
+
replay?: boolean;
|
|
176
|
+
}
|
|
177
|
+
export interface RenameApplyResult {
|
|
178
|
+
moved: boolean;
|
|
179
|
+
/** Root-relative paths whose content was rewritten (in-link + out-link). */
|
|
180
|
+
edited: string[];
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* The label a rewrite must carry: when `label` is one of `MIRRORED_LABELS` of
|
|
184
|
+
* the reference's current destination, the same rendering recomputed on the new
|
|
185
|
+
* destination — the mirror relation is re-derived, not guessed at.
|
|
186
|
+
*
|
|
187
|
+
* `undefined` means "leave the label alone", for three deterministic reasons:
|
|
188
|
+
* no rendering matched (author prose), a matched rendering of the new
|
|
189
|
+
* destination already equals the label (a pure move — the mirror still holds,
|
|
190
|
+
* so zero bytes change), or every matched rendering of the new destination is
|
|
191
|
+
* unrepresentable inside `[...]`.
|
|
192
|
+
*
|
|
193
|
+
* Several renderings can match only where the authored destination was a bare
|
|
194
|
+
* filename (identity and last segment then read the same); the earliest entry
|
|
195
|
+
* wins, so the label keeps the author's own shape — `[a](a.md)` follows the
|
|
196
|
+
* target's new NAME with no extension, `[a.md](a.md)` with one, and neither
|
|
197
|
+
* turns into a path.
|
|
198
|
+
* @param label - the authored label text (brackets excluded).
|
|
199
|
+
* @param oldPath - the reference's current destination path (suffix stripped).
|
|
200
|
+
* @param newPath - the rebased destination path.
|
|
201
|
+
*/
|
|
202
|
+
export declare function relabelFor(label: string, oldPath: string, newPath: string): string | undefined;
|
|
203
|
+
/**
|
|
204
|
+
* The git shapes that can witness "this rename already happened" (post-hoc
|
|
205
|
+
* repair evidence), in the order the evidence gate checks them — the two
|
|
206
|
+
* worktree-tier shapes first, the HEAD-tree shape only when the worktree
|
|
207
|
+
* shows nothing. Surface-neutral wording: model-facing descriptions project
|
|
208
|
+
* these summaries instead of re-deriving the witness conditions.
|
|
209
|
+
*/
|
|
210
|
+
export declare const POSTHOC_WITNESS_SHAPES: ReadonlyArray<{
|
|
211
|
+
shape: 'staged-rename-record' | 'deleted-record-with-shifted-counterpart' | 'head-tree-entry';
|
|
212
|
+
summary: string;
|
|
213
|
+
}>;
|
|
214
|
+
/**
|
|
215
|
+
* Plan an explicit rename without writing anything — the one-pair case of the
|
|
216
|
+
* joint planning core. See `planPairs` for the contract.
|
|
217
|
+
*/
|
|
218
|
+
export declare function planRename(root: string, oldPath: string, newPath: string, options?: PlanRenameOptions): RenamePlanResult;
|
|
219
|
+
/**
|
|
220
|
+
* Plan a one-level sink: `<dir>/*` moves to
|
|
221
|
+
* `<dir>/<sub>/*` as ONE transaction — internally every child becomes a pair
|
|
222
|
+
* and `planPairs` computes every href against the final positions (links
|
|
223
|
+
* between co-moved siblings keep their relative geometry). The aggregate
|
|
224
|
+
* old/new on the plan is (dir, dir/sub) for reporting; repair of an already
|
|
225
|
+
* completed sink stays the single self-nesting pair — planRename(dir, dir/sub)
|
|
226
|
+
* — because git witnessed the completed geometry, not the per-child staging.
|
|
227
|
+
*/
|
|
228
|
+
export declare function planSink(root: string, dir: string, sub: string, options?: PlanRenameOptions): RenamePlanResult;
|
|
229
|
+
/**
|
|
230
|
+
* The physical move failed at apply time — the typed, catchable contract for
|
|
231
|
+
* every `git mv` failure. Plan-time refusals are conflicts (nothing written);
|
|
232
|
+
* this is the apply tier: the plan was certain, the world changed underneath
|
|
233
|
+
* it (a source untracked between plan and apply, a permission, an exotic index
|
|
234
|
+
* state). `movedPairs` reports exactly which pairs did move before the failure
|
|
235
|
+
* — non-empty means the worktree IS half-changed, and honesty demands saying
|
|
236
|
+
* which half moved. Consumers branch on `code`, relay `gitMessage`, and never
|
|
237
|
+
* surface the raw spawn text.
|
|
238
|
+
*/
|
|
239
|
+
export declare class RenameApplyError extends Error {
|
|
240
|
+
readonly code: 'git-move-failed';
|
|
241
|
+
/** The pair whose move failed. */
|
|
242
|
+
readonly pair: RenamePair;
|
|
243
|
+
/** git's own message (captured stderr, e.g. `fatal: not under version control, source=…`). */
|
|
244
|
+
readonly gitMessage: string;
|
|
245
|
+
/** Pairs already moved before the failure, in move order. */
|
|
246
|
+
readonly movedPairs: RenamePair[];
|
|
247
|
+
constructor(pair: RenamePair, gitMessage: string, movedPairs: RenamePair[]);
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
250
|
+
* Apply a certain plan: `git mv` every pair (staging the moves), then write
|
|
251
|
+
* every edit to its post-move path. A link-only (post-hoc) plan skips the
|
|
252
|
+
* moves — the files are already in place — and reports `moved: false`.
|
|
253
|
+
* Refuses to run while conflicts remain — the caller must only call this when
|
|
254
|
+
* `certain` is true ("工作树绝不半改"). A `git mv` failure throws
|
|
255
|
+
* `RenameApplyError` (see the class for the apply-tier contract).
|
|
256
|
+
*/
|
|
257
|
+
export declare function applyRenamePlan(plan: RenamePlan): RenameApplyResult;
|