wachiman 1.16.0 → 1.17.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/README.md +12 -0
- package/package.json +1 -1
- package/skills/wachiman-loop/SKILL.md +43 -0
- package/src/cli.ts +37 -6
- package/src/config.ts +21 -2
- package/src/connectors/local-git.ts +82 -1
- package/src/connectors/working-tree.ts +23 -1
- package/src/engine.ts +848 -127
- package/src/formats.ts +44 -3
- package/src/help.ts +121 -6
- package/src/history/command.ts +5 -5
- package/src/history/match.ts +24 -4
- package/src/history/store.ts +1 -1
- package/src/history/types.ts +7 -2
- package/src/init/agents.ts +135 -0
- package/src/init/args.ts +4 -2
- package/src/init/json.ts +82 -0
- package/src/init/options.ts +15 -5
- package/src/init/render.ts +3 -1
- package/src/init/run.ts +172 -18
- package/src/init/settings.ts +10 -0
- package/src/json-schema.ts +8 -0
- package/src/ledger.ts +2 -2
- package/src/local.ts +37 -9
- package/src/loop/command.ts +24 -2
- package/src/memory/candidates.ts +425 -0
- package/src/memory/capture.ts +298 -0
- package/src/memory/command.ts +195 -0
- package/src/memory/entries.ts +213 -0
- package/src/memory/hygiene.ts +291 -0
- package/src/memory/inspect.ts +74 -0
- package/src/memory/load.ts +283 -0
- package/src/memory/mute.ts +259 -0
- package/src/memory/personal.ts +253 -0
- package/src/memory/proposal.ts +92 -0
- package/src/memory/propose.ts +414 -0
- package/src/memory/remember.ts +187 -0
- package/src/memory/report.ts +250 -0
- package/src/memory/settings.ts +20 -0
- package/src/pr-template/install.ts +23 -0
- package/src/precision.ts +10 -2
- package/src/priority.ts +106 -0
- package/src/repo-settings.ts +166 -3
- package/src/risk.ts +38 -9
- package/src/sinks/common.ts +12 -6
- package/src/sinks/markdown.ts +3 -0
- package/src/sinks/terminal.ts +3 -0
- package/src/store/figures.ts +5 -4
- package/src/store/html.ts +1 -1
- package/src/verify.ts +20 -2
- package/templates/wachiman-review-caller.yml +7 -7
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The entries of repository memory (ADR 0056): the Markdown format, its parser and the entry id.
|
|
3
|
+
*
|
|
4
|
+
* A memory file is ordinary Markdown. Headings, prose and tables are free text; an entry is a
|
|
5
|
+
* `###` heading followed by `- field: value` lines:
|
|
6
|
+
*
|
|
7
|
+
* ### 4c1e9a2 ADR wording edits do not need a status or date bump
|
|
8
|
+
*
|
|
9
|
+
* - kind: exception
|
|
10
|
+
* - scope: docs/adr/**
|
|
11
|
+
* - rule: Only a change to the Decision section requires updating the status line.
|
|
12
|
+
* - why: ADRs version themselves when a decision changes.
|
|
13
|
+
* - holds while: src/gateway.ts (optional)
|
|
14
|
+
* - evidence:
|
|
15
|
+
* - 2026-11-18 operator instruction, pull request 709
|
|
16
|
+
* - added: 2026-11-18
|
|
17
|
+
*
|
|
18
|
+
* A value continues on following lines indented by two spaces. The parser never throws: every
|
|
19
|
+
* defect is a `MemoryProblem` with its file and line, which `wachiman memory check` prints. An
|
|
20
|
+
* entry with a defect is still returned when its fields can be read, so a review loads what it can.
|
|
21
|
+
*/
|
|
22
|
+
import { createHash } from "node:crypto";
|
|
23
|
+
|
|
24
|
+
export type MemoryKind = "convention" | "exception";
|
|
25
|
+
|
|
26
|
+
export interface MemoryEntry {
|
|
27
|
+
/** Seven hex characters: the digest of `kind`, `scope`, `rule`, `why` and `holds while` (`entryId`). */
|
|
28
|
+
id: string;
|
|
29
|
+
title: string;
|
|
30
|
+
kind: MemoryKind;
|
|
31
|
+
/** A path glob, or several separated by commas. */
|
|
32
|
+
scope: string;
|
|
33
|
+
rule: string;
|
|
34
|
+
why: string;
|
|
35
|
+
/** The paths a fact the reason depends on lives in; absent for a preference. */
|
|
36
|
+
holdsWhile?: string;
|
|
37
|
+
evidence: string[];
|
|
38
|
+
/** `YYYY-MM-DD`. */
|
|
39
|
+
added: string;
|
|
40
|
+
/** The file name inside `.wachiman/memory/`, and the line of the heading. */
|
|
41
|
+
file: string;
|
|
42
|
+
line: number;
|
|
43
|
+
/** Set by a review on an entry that came from the developer's personal memory; never read from a file. */
|
|
44
|
+
personal?: true;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export interface MemoryProblem {
|
|
48
|
+
file: string;
|
|
49
|
+
line: number;
|
|
50
|
+
message: string;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** The part of an entry its id is made from. Evidence and the date are not part of it, so adding evidence keeps the id. */
|
|
54
|
+
export interface EntryIdentity {
|
|
55
|
+
kind: string;
|
|
56
|
+
scope: string;
|
|
57
|
+
rule: string;
|
|
58
|
+
why: string;
|
|
59
|
+
holdsWhile?: string;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
const squash = (text: string) => text.replace(/\s+/g, " ").trim();
|
|
63
|
+
|
|
64
|
+
/** The id of an entry: seven hex characters of a SHA-256 over its normalised identity fields. */
|
|
65
|
+
export function entryId(entry: EntryIdentity): string {
|
|
66
|
+
const material = JSON.stringify([entry.kind, entry.scope, entry.rule, entry.why, entry.holdsWhile ?? ""].map(squash));
|
|
67
|
+
return createHash("sha256").update(material).digest("hex").slice(0, 7);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
const HEADING = /^###\s+([0-9a-f]{7})\s+(\S.*)$/;
|
|
71
|
+
const ANY_HEADING = /^#{1,6}\s/;
|
|
72
|
+
const FIELD = /^- ([a-z][a-z ]*):\s*(.*)$/;
|
|
73
|
+
const FIELDS = ["kind", "scope", "rule", "why", "holds while", "evidence", "added"] as const;
|
|
74
|
+
const DATE = /^\d{4}-\d{2}-\d{2}$/;
|
|
75
|
+
|
|
76
|
+
interface Draft {
|
|
77
|
+
heading: { id: string; title: string; line: number };
|
|
78
|
+
values: Map<string, { text: string; line: number }>;
|
|
79
|
+
evidence: string[];
|
|
80
|
+
current?: string;
|
|
81
|
+
/** A blank line came after the last field line: what follows may be free prose or a table. */
|
|
82
|
+
afterBlank?: boolean;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Every entry of one memory file and every defect found in it. */
|
|
86
|
+
export function parseMemoryFile(file: string, content: string): { entries: MemoryEntry[]; problems: MemoryProblem[] } {
|
|
87
|
+
const entries: MemoryEntry[] = [];
|
|
88
|
+
const problems: MemoryProblem[] = [];
|
|
89
|
+
const problem = (line: number, message: string) => problems.push({ file, line, message });
|
|
90
|
+
let draft: Draft | undefined;
|
|
91
|
+
|
|
92
|
+
const finish = () => {
|
|
93
|
+
if (!draft) return;
|
|
94
|
+
const d = draft;
|
|
95
|
+
draft = undefined;
|
|
96
|
+
const text = (name: string) => d.values.get(name)?.text;
|
|
97
|
+
const need = (name: string) => {
|
|
98
|
+
if (text(name) === undefined || text(name) === "") {
|
|
99
|
+
problem(d.heading.line, `missing ${name}`);
|
|
100
|
+
return undefined;
|
|
101
|
+
}
|
|
102
|
+
return text(name);
|
|
103
|
+
};
|
|
104
|
+
const kind = need("kind");
|
|
105
|
+
const scope = need("scope");
|
|
106
|
+
const rule = need("rule");
|
|
107
|
+
const why = need("why");
|
|
108
|
+
const added = need("added");
|
|
109
|
+
if (d.evidence.length === 0) problem(d.heading.line, "missing evidence");
|
|
110
|
+
if (kind !== undefined && kind !== "convention" && kind !== "exception") {
|
|
111
|
+
problem(d.values.get("kind")!.line, `kind must be "convention" or "exception", got "${kind}"`);
|
|
112
|
+
}
|
|
113
|
+
if (added !== undefined && !DATE.test(added)) {
|
|
114
|
+
problem(d.values.get("added")!.line, `added must be a date like 2026-11-18, got "${added}"`);
|
|
115
|
+
}
|
|
116
|
+
if (kind === undefined || scope === undefined || rule === undefined || why === undefined || added === undefined) return;
|
|
117
|
+
const holdsWhile = text("holds while");
|
|
118
|
+
const id = entryId({ kind, scope, rule, why, ...(holdsWhile ? { holdsWhile } : {}) });
|
|
119
|
+
if (id !== d.heading.id) problem(d.heading.line, `entry id ${d.heading.id} does not match its digest ${id}`);
|
|
120
|
+
if (kind !== "convention" && kind !== "exception") return;
|
|
121
|
+
entries.push({
|
|
122
|
+
id: d.heading.id,
|
|
123
|
+
title: d.heading.title.trim(),
|
|
124
|
+
kind,
|
|
125
|
+
scope,
|
|
126
|
+
rule,
|
|
127
|
+
why,
|
|
128
|
+
...(holdsWhile ? { holdsWhile } : {}),
|
|
129
|
+
evidence: d.evidence,
|
|
130
|
+
added,
|
|
131
|
+
file,
|
|
132
|
+
line: d.heading.line,
|
|
133
|
+
});
|
|
134
|
+
};
|
|
135
|
+
|
|
136
|
+
// Lines inside a fenced code block (``` or ~~~) are example text, never entries or headings.
|
|
137
|
+
let fence: string | undefined;
|
|
138
|
+
content.split(/\r?\n/).forEach((raw, i) => {
|
|
139
|
+
const line = i + 1;
|
|
140
|
+
const opener = /^ {0,3}(`{3,}|~{3,})/.exec(raw);
|
|
141
|
+
if (fence !== undefined) {
|
|
142
|
+
if (opener && opener[1][0] === fence[0] && opener[1].length >= fence.length && raw.trim() === opener[1]) fence = undefined;
|
|
143
|
+
return;
|
|
144
|
+
}
|
|
145
|
+
if (opener) {
|
|
146
|
+
fence = opener[1];
|
|
147
|
+
return;
|
|
148
|
+
}
|
|
149
|
+
if (ANY_HEADING.test(raw)) {
|
|
150
|
+
finish();
|
|
151
|
+
if (raw.startsWith("### ")) {
|
|
152
|
+
const m = HEADING.exec(raw);
|
|
153
|
+
if (m) draft = { heading: { id: m[1], title: m[2], line }, values: new Map(), evidence: [] };
|
|
154
|
+
else problem(line, "entry heading must be `### <id> <title>` with a 7-character hex id");
|
|
155
|
+
}
|
|
156
|
+
return;
|
|
157
|
+
}
|
|
158
|
+
if (!draft) return;
|
|
159
|
+
if (raw.trim() === "") {
|
|
160
|
+
draft.afterBlank = true;
|
|
161
|
+
return;
|
|
162
|
+
}
|
|
163
|
+
const field = FIELD.exec(raw);
|
|
164
|
+
if (field) {
|
|
165
|
+
const name = field[1];
|
|
166
|
+
if (!(FIELDS as readonly string[]).includes(name)) {
|
|
167
|
+
problem(line, `unknown field "${name}"`);
|
|
168
|
+
draft.current = undefined;
|
|
169
|
+
return;
|
|
170
|
+
}
|
|
171
|
+
draft.current = name;
|
|
172
|
+
draft.afterBlank = false;
|
|
173
|
+
if (draft.values.has(name)) problem(line, `field "${name}" appears twice`);
|
|
174
|
+
draft.values.set(name, { text: field[2].trim(), line });
|
|
175
|
+
return;
|
|
176
|
+
}
|
|
177
|
+
if (/^ {2}\S/.test(raw) && draft.current !== undefined) {
|
|
178
|
+
const body = raw.trim();
|
|
179
|
+
if (draft.current === "evidence") {
|
|
180
|
+
if (body.startsWith("- ")) draft.evidence.push(body.slice(2).trim());
|
|
181
|
+
else if (draft.evidence.length > 0) draft.evidence[draft.evidence.length - 1] += ` ${body}`;
|
|
182
|
+
else problem(line, "evidence items start with `- `");
|
|
183
|
+
} else {
|
|
184
|
+
const prior = draft.values.get(draft.current)!;
|
|
185
|
+
prior.text = `${prior.text} ${body}`.trim();
|
|
186
|
+
}
|
|
187
|
+
return;
|
|
188
|
+
}
|
|
189
|
+
// After a blank line, free prose or a table is allowed; a stray line glued to the fields is a defect.
|
|
190
|
+
if (!draft.afterBlank) problem(line, "unexpected line inside an entry");
|
|
191
|
+
});
|
|
192
|
+
finish();
|
|
193
|
+
return { entries, problems };
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
export interface IndexRow {
|
|
197
|
+
glob: string;
|
|
198
|
+
file: string;
|
|
199
|
+
line: number;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/** The rows of `index.md` that map a glob to an area file: table rows whose second cell names a `.md` file. */
|
|
203
|
+
export function parseIndexMap(content: string): IndexRow[] {
|
|
204
|
+
const rows: IndexRow[] = [];
|
|
205
|
+
content.split(/\r?\n/).forEach((raw, i) => {
|
|
206
|
+
const t = raw.trim();
|
|
207
|
+
if (!t.startsWith("|")) return;
|
|
208
|
+
const cells = t.replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim().replace(/^`+|`+$/g, "").trim());
|
|
209
|
+
if (cells.length < 2 || !/\.md$/.test(cells[1]) || cells[0] === "") return;
|
|
210
|
+
rows.push({ glob: cells[0], file: cells[1], line: i + 1 });
|
|
211
|
+
});
|
|
212
|
+
return rows;
|
|
213
|
+
}
|
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Memory hygiene (spec decision 12, ADR 0056 decision 9): Wachiman points at likely problems and
|
|
3
|
+
* never applies a change. Everything here is deterministic: no model is called.
|
|
4
|
+
*
|
|
5
|
+
* - Likely duplicates: two entries of the same kind whose scopes overlap and whose rule text is
|
|
6
|
+
* near-identical (`similarity` at or above `DUPLICATE_THRESHOLD`). Likely contradictions are not
|
|
7
|
+
* detected: telling that two rules disagree needs a model.
|
|
8
|
+
* - Archive suggestions: an entry whose last recorded use (or, with none recorded, its `added` date) is
|
|
9
|
+
* older than `memory.archive_after_days`. Uses are recorded only on the laptop (`recordMemoryUse`).
|
|
10
|
+
* When the record itself is missing or unreadable, the use of every entry is unknown and none is suggested.
|
|
11
|
+
* - `archiveEntry` is the one function that moves text, and only on the developer's explicit command.
|
|
12
|
+
*/
|
|
13
|
+
import { randomBytes } from "node:crypto";
|
|
14
|
+
import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs";
|
|
15
|
+
import { basename, dirname, join } from "node:path";
|
|
16
|
+
import { historyRoot } from "../history/store";
|
|
17
|
+
import { parseMemoryFile, type MemoryEntry } from "./entries";
|
|
18
|
+
import { ARCHIVE_FILE, globsOf, matchesGlob, type MemoryLoad } from "./load";
|
|
19
|
+
|
|
20
|
+
/** Jaccard overlap of the normalised word sets at or above which two rules are called near-identical. */
|
|
21
|
+
export const DUPLICATE_THRESHOLD = 0.8;
|
|
22
|
+
|
|
23
|
+
const tokens = (text: string): Set<string> => new Set(text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []);
|
|
24
|
+
|
|
25
|
+
/** Size of the intersection over the size of the union of the two rules' lowercase word sets; 1 for two empty rules. */
|
|
26
|
+
export function similarity(a: string, b: string): number {
|
|
27
|
+
const x = tokens(a);
|
|
28
|
+
const y = tokens(b);
|
|
29
|
+
if (x.size === 0 && y.size === 0) return 1;
|
|
30
|
+
let shared = 0;
|
|
31
|
+
for (const t of x) if (y.has(t)) shared++;
|
|
32
|
+
return shared / (x.size + y.size - shared);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** The literal directory segments of a glob before its first wildcard segment. */
|
|
36
|
+
const literalPrefix = (glob: string): string[] => {
|
|
37
|
+
const out: string[] = [];
|
|
38
|
+
for (const s of glob.split("/")) {
|
|
39
|
+
if (/[*?[\]{}!]/.test(s)) break;
|
|
40
|
+
out.push(s);
|
|
41
|
+
}
|
|
42
|
+
return out;
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Whether two scopes can reach the same path, judged from their literal prefixes: one prefix
|
|
47
|
+
* contains the other (`src/**` and `src/api/*.ts` overlap, `src/**` and `docs/**` do not).
|
|
48
|
+
* Conservative on purpose: it may say two scopes overlap when no real path matches both.
|
|
49
|
+
*/
|
|
50
|
+
export function scopesOverlap(a: string, b: string): boolean {
|
|
51
|
+
return globsOf(a).some((x) =>
|
|
52
|
+
globsOf(b).some((y) => {
|
|
53
|
+
const p = literalPrefix(x);
|
|
54
|
+
const q = literalPrefix(y);
|
|
55
|
+
const n = Math.min(p.length, q.length);
|
|
56
|
+
return p.slice(0, n).every((s, i) => s === q[i]);
|
|
57
|
+
}),
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
export interface DuplicatePair {
|
|
62
|
+
a: MemoryEntry;
|
|
63
|
+
b: MemoryEntry;
|
|
64
|
+
similarity: number;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** Pairs of live entries (not those in `archive.md`) of the same kind with overlapping scopes and near-identical rules. */
|
|
68
|
+
export function findDuplicates(entries: MemoryEntry[]): DuplicatePair[] {
|
|
69
|
+
const live = entries.filter((e) => e.file !== ARCHIVE_FILE);
|
|
70
|
+
const pairs: DuplicatePair[] = [];
|
|
71
|
+
for (let i = 0; i < live.length; i++) {
|
|
72
|
+
for (let j = i + 1; j < live.length; j++) {
|
|
73
|
+
const a = live[i];
|
|
74
|
+
const b = live[j];
|
|
75
|
+
if (a.id === b.id || a.kind !== b.kind || !scopesOverlap(a.scope, b.scope)) continue;
|
|
76
|
+
const s = similarity(a.rule, b.rule);
|
|
77
|
+
if (s >= DUPLICATE_THRESHOLD) pairs.push({ a, b, similarity: s });
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
return pairs;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
const DAY_MS = 86_400_000;
|
|
84
|
+
const daysBetween = (from: string, to: string) => Math.floor((Date.parse(`${to}T00:00:00Z`) - Date.parse(`${from}T00:00:00Z`)) / DAY_MS);
|
|
85
|
+
|
|
86
|
+
export interface ArchiveSuggestion {
|
|
87
|
+
entry: MemoryEntry;
|
|
88
|
+
/** The date the age is counted from: the last recorded use, else the later of the `added` date and when recording began. */
|
|
89
|
+
since: string;
|
|
90
|
+
/** Whether a use was recorded on or after the entry's added date; false means no use is recorded, not that none happened off this laptop. */
|
|
91
|
+
usedEver: boolean;
|
|
92
|
+
days: number;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** Live entries whose last use is more than `afterDays` days before `today`, oldest first. `recordingSince` is the date the record began (see `MemoryUse`). */
|
|
96
|
+
export function archiveSuggestions(entries: MemoryEntry[], lastUse: Record<string, string>, afterDays: number, today: string, recordingSince?: string): ArchiveSuggestion[] {
|
|
97
|
+
return entries
|
|
98
|
+
.filter((e) => e.file !== ARCHIVE_FILE)
|
|
99
|
+
.map((entry) => {
|
|
100
|
+
const used = lastUse[entry.id];
|
|
101
|
+
// A use dated before the entry was added cannot be a use of this entry (an id reused after an archive and re-add): it counts for nothing.
|
|
102
|
+
const usedSince = used !== undefined && used >= entry.added;
|
|
103
|
+
// With no use recorded, the entry is measured from when it was added or when the laptop began recording, whichever is later: before that the record cannot tell.
|
|
104
|
+
const unusedSince = recordingSince !== undefined && recordingSince > entry.added ? recordingSince : entry.added;
|
|
105
|
+
const since = usedSince ? used : unusedSince;
|
|
106
|
+
return { entry, since, usedEver: usedSince, days: daysBetween(since, today) };
|
|
107
|
+
})
|
|
108
|
+
.filter((s) => s.days > afterDays)
|
|
109
|
+
.sort((a, b) => b.days - a.days || a.entry.id.localeCompare(b.entry.id));
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
// ---- Last use: a small local record, per repository, under the Wachiman home. ----
|
|
113
|
+
|
|
114
|
+
export const MEMORY_USE_FORMAT = "wachiman.memory-use/1";
|
|
115
|
+
const ID = /^[0-9a-f]{7}$/;
|
|
116
|
+
const DATE = /^\d{4}-\d{2}-\d{2}$/;
|
|
117
|
+
|
|
118
|
+
/** `<home>/history/<repo key>/memory-use.json`: the local history store; it never exists in Actions. */
|
|
119
|
+
export const memoryUsePath = (home: string, key: string) => join(historyRoot(home), key, "memory-use.json");
|
|
120
|
+
|
|
121
|
+
interface UseRecord {
|
|
122
|
+
used: Record<string, string>;
|
|
123
|
+
/** The date of the first recording; absent in a record written without one. */
|
|
124
|
+
since?: string;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** The parsed record, empty when the file is missing; throws when it exists but cannot be read or is not this format. */
|
|
128
|
+
function loadMemoryUse(home: string, key: string): UseRecord {
|
|
129
|
+
const path = memoryUsePath(home, key);
|
|
130
|
+
if (!existsSync(path)) return { used: {} };
|
|
131
|
+
let parsed: any;
|
|
132
|
+
try {
|
|
133
|
+
parsed = JSON.parse(readFileSync(path, "utf8"));
|
|
134
|
+
} catch (error) {
|
|
135
|
+
throw new Error(`${path} could not be read (${error instanceof Error ? error.message : error})`);
|
|
136
|
+
}
|
|
137
|
+
if (parsed?.format !== MEMORY_USE_FORMAT || typeof parsed.used !== "object" || parsed.used === null) {
|
|
138
|
+
throw new Error(`${path} is not a ${MEMORY_USE_FORMAT} record`);
|
|
139
|
+
}
|
|
140
|
+
const used = Object.fromEntries(Object.entries(parsed.used).filter(([id, d]) => ID.test(id) && typeof d === "string" && DATE.test(d))) as Record<string, string>;
|
|
141
|
+
return { used, ...(typeof parsed.since === "string" && DATE.test(parsed.since) ? { since: parsed.since } : {}) };
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** What the laptop knows about use: the dates by entry id, or why it knows nothing (no record, or one that cannot be read). */
|
|
145
|
+
export type MemoryUse = { known: true; used: Record<string, string>; since?: string } | { known: false; reason: string };
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* The record of last use. A missing or unreadable record is `known: false`, never an empty record:
|
|
149
|
+
* "no record" must not be read as "no entry was ever used".
|
|
150
|
+
*/
|
|
151
|
+
export function readMemoryUse(home: string, key: string): MemoryUse {
|
|
152
|
+
const path = memoryUsePath(home, key);
|
|
153
|
+
if (!existsSync(path)) return { known: false, reason: `no use record at ${path}: no laptop review with history on has loaded memory yet` };
|
|
154
|
+
try {
|
|
155
|
+
return { known: true, ...loadMemoryUse(home, key) };
|
|
156
|
+
} catch (error) {
|
|
157
|
+
return { known: false, reason: error instanceof Error ? error.message : String(error) };
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Writes `text` to `path` through a new, randomly named temporary file in the same directory, then renames it over `path`.
|
|
163
|
+
* The temporary file is created exclusively (it never opens an existing path, so a symbolic link planted at a guessable
|
|
164
|
+
* name is not followed) and the rename replaces `path` itself, even when `path` is a symbolic link, instead of writing through it.
|
|
165
|
+
*/
|
|
166
|
+
export function writeFileAtomically(path: string, text: string, mode: number): void {
|
|
167
|
+
const tmp = join(dirname(path), `.${basename(path)}.${process.pid}-${randomBytes(6).toString("hex")}.tmp`);
|
|
168
|
+
const fd = openSync(tmp, "wx", mode);
|
|
169
|
+
try {
|
|
170
|
+
try {
|
|
171
|
+
writeSync(fd, text);
|
|
172
|
+
fsyncSync(fd);
|
|
173
|
+
} finally {
|
|
174
|
+
closeSync(fd);
|
|
175
|
+
}
|
|
176
|
+
chmodSync(tmp, mode);
|
|
177
|
+
renameSync(tmp, path);
|
|
178
|
+
} catch (error) {
|
|
179
|
+
try {
|
|
180
|
+
unlinkSync(tmp);
|
|
181
|
+
} catch {
|
|
182
|
+
// already gone
|
|
183
|
+
}
|
|
184
|
+
throw error;
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* Records that these entries were used on `date`; a later date replaces an earlier one, never the reverse.
|
|
190
|
+
* With no ids it still creates the record when absent: a review that loaded memory and used nothing is
|
|
191
|
+
* knowledge ("not used"), unlike having no record at all ("unknown").
|
|
192
|
+
* Throws, writing nothing, when an existing record cannot be read or is another format: it is never overwritten.
|
|
193
|
+
*/
|
|
194
|
+
export function recordMemoryUse(home: string, key: string, ids: string[], date: string): void {
|
|
195
|
+
let record: UseRecord;
|
|
196
|
+
try {
|
|
197
|
+
record = loadMemoryUse(home, key);
|
|
198
|
+
} catch (error) {
|
|
199
|
+
throw new Error(`${error instanceof Error ? error.message : error}; it was left as it is`);
|
|
200
|
+
}
|
|
201
|
+
const used = record.used;
|
|
202
|
+
for (const id of ids) if (!used[id] || used[id] < date) used[id] = date;
|
|
203
|
+
const since = record.since !== undefined && record.since < date ? record.since : date;
|
|
204
|
+
const path = memoryUsePath(home, key);
|
|
205
|
+
for (const dir of [dirname(dirname(path)), dirname(path)]) {
|
|
206
|
+
if (existsSync(dir)) continue;
|
|
207
|
+
mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
208
|
+
chmodSync(dir, 0o700);
|
|
209
|
+
}
|
|
210
|
+
writeFileAtomically(path, `${JSON.stringify({ format: MEMORY_USE_FORMAT, since, used }, null, 2)}\n`, 0o600);
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/**
|
|
214
|
+
* The entries a review used: every loaded convention whose scope matches a changed path (it was in
|
|
215
|
+
* the prompt for that diff), and every exception that muted a finding.
|
|
216
|
+
*/
|
|
217
|
+
export function entriesUsed(memory: MemoryLoad | undefined, changedPaths: string[], muted: { entry: string }[]): string[] {
|
|
218
|
+
const ids = new Set<string>(muted.map((m) => m.entry));
|
|
219
|
+
for (const e of memory?.entries ?? []) {
|
|
220
|
+
if (e.kind === "convention" && changedPaths.some((p) => matchesGlob(e.scope, p))) ids.add(e.id);
|
|
221
|
+
}
|
|
222
|
+
return [...ids];
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
// ---- Archiving ----
|
|
226
|
+
|
|
227
|
+
export type ArchiveResult = { ok: true; from: string; files: Record<string, string> } | { ok: false; reason: string };
|
|
228
|
+
|
|
229
|
+
const ANY_HEADING = /^#{1,6}\s/;
|
|
230
|
+
const FIELD = /^- [a-z][a-z ]*:/;
|
|
231
|
+
const FENCE_OPENER = /^ {0,3}(`{3,}|~{3,})/;
|
|
232
|
+
|
|
233
|
+
/**
|
|
234
|
+
* The index of the last line that belongs to the entry whose heading is at `start`: the heading, its
|
|
235
|
+
* `- field:` lines and their indented continuations. It stops at the next heading, as the entry parser does,
|
|
236
|
+
* and skips fenced code blocks the way the parser does (a `#` line inside a fence is not a heading). Free prose or
|
|
237
|
+
* a table after the fields, up to the next heading, is not part of the entry and is not returned.
|
|
238
|
+
*/
|
|
239
|
+
function lastEntryLine(rows: string[], start: number): number {
|
|
240
|
+
let last = start;
|
|
241
|
+
let fence: string | undefined;
|
|
242
|
+
let seenField = false;
|
|
243
|
+
for (let i = start + 1; i < rows.length; i++) {
|
|
244
|
+
const raw = rows[i];
|
|
245
|
+
const opener = FENCE_OPENER.exec(raw);
|
|
246
|
+
if (fence !== undefined) {
|
|
247
|
+
if (opener && opener[1][0] === fence[0] && opener[1].length >= fence.length && raw.trim() === opener[1]) fence = undefined;
|
|
248
|
+
continue;
|
|
249
|
+
}
|
|
250
|
+
if (opener) {
|
|
251
|
+
fence = opener[1];
|
|
252
|
+
continue;
|
|
253
|
+
}
|
|
254
|
+
if (ANY_HEADING.test(raw)) break;
|
|
255
|
+
if (FIELD.test(raw)) {
|
|
256
|
+
seenField = true;
|
|
257
|
+
last = i;
|
|
258
|
+
} else if (seenField && /^ {2}\S/.test(raw)) last = i;
|
|
259
|
+
}
|
|
260
|
+
return last;
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
/**
|
|
264
|
+
* The memory files after entry `id` moves from its file to `archive.md`. The entry's own lines are moved
|
|
265
|
+
* as they are written; nothing else is rewritten or removed. Pure: the caller writes the files.
|
|
266
|
+
*/
|
|
267
|
+
export function archiveEntry(current: Record<string, string>, id: string): ArchiveResult {
|
|
268
|
+
const archived = current[ARCHIVE_FILE] !== undefined && parseMemoryFile(ARCHIVE_FILE, current[ARCHIVE_FILE]).entries.some((e) => e.id === id);
|
|
269
|
+
for (const [name, text] of Object.entries(current)) {
|
|
270
|
+
if (name === ARCHIVE_FILE) continue;
|
|
271
|
+
const entry = parseMemoryFile(name, text).entries.find((e) => e.id === id);
|
|
272
|
+
if (!entry) continue;
|
|
273
|
+
const rows = text.split("\n");
|
|
274
|
+
const start = entry.line - 1;
|
|
275
|
+
const contentEnd = lastEntryLine(rows, start) + 1;
|
|
276
|
+
const block = `${rows.slice(start, contentEnd).join("\n")}\n`;
|
|
277
|
+
// Only the entry's own lines go, with the one blank line that separated it; the rest of the file keeps every byte.
|
|
278
|
+
let rest: string;
|
|
279
|
+
if (rows.slice(contentEnd).every((r) => r.trim() === "")) {
|
|
280
|
+
const from = start > 0 && rows[start - 1].trim() === "" ? start - 1 : start;
|
|
281
|
+
rest = [...rows.slice(0, from), ...(text.endsWith("\n") ? [""] : [])].join("\n");
|
|
282
|
+
} else {
|
|
283
|
+
const cut = rows[contentEnd].trim() === "" ? contentEnd + 1 : contentEnd;
|
|
284
|
+
rest = [...rows.slice(0, start), ...rows.slice(cut)].join("\n");
|
|
285
|
+
}
|
|
286
|
+
const archive = current[ARCHIVE_FILE];
|
|
287
|
+
const next = archive === undefined ? `# Wachiman memory archive\n\nEntries moved here are never loaded by a review.\n\n${block}` : `${archive.replace(/\n*$/, "\n")}\n${block}`;
|
|
288
|
+
return { ok: true, from: name, files: { [name]: rest, [ARCHIVE_FILE]: next } };
|
|
289
|
+
}
|
|
290
|
+
return { ok: false, reason: archived ? `entry ${id} is already in ${ARCHIVE_FILE}.` : `no entry ${id} in .wachiman/memory/.` };
|
|
291
|
+
}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
/** The pure check behind `wachiman memory check`, also used by `memory propose` on the result it is about to commit. Kept apart from `command.ts` so neither imports the other. */
|
|
2
|
+
import { resolveMemorySettings, type RepoSettings } from "../repo-settings";
|
|
3
|
+
import { parseIndexMap, parseMemoryFile, type MemoryProblem } from "./entries";
|
|
4
|
+
import { ARCHIVE_FILE, globsOf, INDEX_FILE, lineCount, matchesGlob, MEMORY_DIR } from "./load";
|
|
5
|
+
|
|
6
|
+
export interface CheckInput {
|
|
7
|
+
/** The text of every file directly in `.wachiman/memory/`, by name. */
|
|
8
|
+
files: Record<string, string>;
|
|
9
|
+
/** Every file of the repository (tracked, and untracked but not ignored), as `/`-separated paths. */
|
|
10
|
+
repoFiles: string[];
|
|
11
|
+
settings: RepoSettings | undefined;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export interface CheckResult {
|
|
15
|
+
problems: MemoryProblem[];
|
|
16
|
+
notices: string[];
|
|
17
|
+
entries: number;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export function inspectMemory(input: CheckInput): CheckResult {
|
|
21
|
+
const { files, repoFiles } = input;
|
|
22
|
+
const resolved = resolveMemorySettings(input.settings);
|
|
23
|
+
const budget = resolved.settings;
|
|
24
|
+
const problems: MemoryProblem[] = [];
|
|
25
|
+
const add = (file: string, line: number, message: string) => problems.push({ file, line, message });
|
|
26
|
+
const names = Object.keys(files).sort();
|
|
27
|
+
const matchesSome = (glob: string) => repoFiles.some((p) => matchesGlob(glob, p));
|
|
28
|
+
let entryCount = 0;
|
|
29
|
+
|
|
30
|
+
for (const name of names) {
|
|
31
|
+
const parsed = parseMemoryFile(name, files[name]);
|
|
32
|
+
problems.push(...parsed.problems);
|
|
33
|
+
entryCount += parsed.entries.length;
|
|
34
|
+
// An archived entry is never loaded, so a scope that matches no file is expected there: archiving is the way to clear that problem.
|
|
35
|
+
for (const entry of name === ARCHIVE_FILE ? [] : parsed.entries) {
|
|
36
|
+
for (const glob of globsOf(entry.scope)) {
|
|
37
|
+
if (!matchesSome(glob)) add(name, entry.line, `scope \`${glob}\` of entry matches no file in the repository`);
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
const indexText = files[INDEX_FILE];
|
|
43
|
+
if (indexText === undefined) {
|
|
44
|
+
if (names.length > 0) add(INDEX_FILE, 1, "is missing: without it no review loads any memory");
|
|
45
|
+
} else {
|
|
46
|
+
const rows = parseIndexMap(indexText);
|
|
47
|
+
const listed = new Set<string>();
|
|
48
|
+
for (const row of rows) {
|
|
49
|
+
listed.add(row.file);
|
|
50
|
+
if (!(row.file in files) || row.file === INDEX_FILE) add(INDEX_FILE, row.line, `maps to \`${row.file}\`, which is not in ${MEMORY_DIR}/`);
|
|
51
|
+
for (const glob of globsOf(row.glob)) {
|
|
52
|
+
if (!matchesSome(glob)) add(INDEX_FILE, row.line, `glob \`${glob}\` matches no file in the repository`);
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
for (const name of names) {
|
|
56
|
+
if (name !== INDEX_FILE && name !== ARCHIVE_FILE && !listed.has(name)) add(name, 1, "is not listed in index.md, so no review loads it");
|
|
57
|
+
}
|
|
58
|
+
const indexLines = lineCount(indexText);
|
|
59
|
+
if (indexLines > budget.maxIndexLines) add(INDEX_FILE, budget.maxIndexLines + 1, `has ${indexLines} lines, over memory.max_index_lines (${budget.maxIndexLines})`);
|
|
60
|
+
if (indexLines > budget.maxLoadedLines) {
|
|
61
|
+
add(INDEX_FILE, budget.maxLoadedLines + 1, `has ${indexLines} lines, over memory.max_loaded_lines (${budget.maxLoadedLines}): a review loads only its first ${budget.maxLoadedLines}`);
|
|
62
|
+
}
|
|
63
|
+
for (const name of names) {
|
|
64
|
+
if (name === INDEX_FILE || name === ARCHIVE_FILE) continue;
|
|
65
|
+
const n = lineCount(files[name]);
|
|
66
|
+
if (indexLines + n > budget.maxLoadedLines) {
|
|
67
|
+
add(name, 1, `has ${n} lines; with index.md's ${indexLines} it exceeds memory.max_loaded_lines (${budget.maxLoadedLines}), so no review can load it`);
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
problems.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
|
|
73
|
+
return { problems, notices: resolved.notices, entries: entryCount };
|
|
74
|
+
}
|