@catheadowl/md-tools 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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;