@staix/vault-mem 0.5.1 → 0.6.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/CHANGELOG.md +60 -0
- package/README.md +138 -23
- package/package.json +5 -4
- package/src/amem/seam.ts +15 -6
- package/src/analysis-commands.ts +1 -1
- package/src/analysis-input.ts +24 -3
- package/src/analysis-reports.ts +1 -1
- package/src/analysis-types.ts +13 -1
- package/src/canon-tables.ts +190 -0
- package/src/cli-output.ts +15 -1
- package/src/cli.ts +1 -1
- package/src/commands-table.ts +6 -2
- package/src/config.ts +31 -3
- package/src/frontmatter.ts +10 -3
- package/src/links.ts +13 -1
- package/src/mcp-spec.ts +19 -11
- package/src/mcp-vault.ts +14 -9
- package/src/mcp.ts +4 -2
- package/src/org-promote.ts +29 -12
- package/src/promote.ts +24 -12
- package/src/read-commands.ts +1 -2
- package/src/read-output.ts +7 -5
- package/src/registry.ts +1 -0
- package/src/skills-mine.ts +5 -4
- package/src/spec-command-table.ts +10 -1
- package/src/spec-commands.ts +7 -3
- package/src/spec-gitlinks.ts +106 -0
- package/src/spec-output.ts +30 -0
- package/src/spec-source.ts +9 -3
- package/src/spec-validate.ts +6 -3
- package/src/spec-write.ts +469 -0
- package/src/ui/inbox.ts +28 -10
- package/src/ui/panel.js +26 -5
- package/src/ui/plugin.ts +38 -12
- package/src/ui/snapshot-cache.ts +123 -0
- package/src/vault-index.ts +109 -19
- package/src/vault-lint.ts +53 -5
- package/src/vault-log.ts +3 -2
- package/src/vault-stats.ts +110 -5
- package/src/write-commands.ts +4 -3
- package/src/write-files.ts +63 -0
- package/src/write-operations.ts +175 -25
- package/src/write-output.ts +20 -9
- package/src/write-types.ts +8 -1
- package/src/write-validation.ts +46 -17
- package/src/writer.ts +137 -41
- package/src/yaml-quoted.ts +12 -2
package/src/ui/panel.js
CHANGED
|
@@ -84,9 +84,17 @@ export default (host) => {
|
|
|
84
84
|
const meta = Object.fromEntries(Object.entries(values).map(([k, v]) => [k, v.trim()]).filter(([, v]) => v));
|
|
85
85
|
host.action({ action: "promote-from-amem", id: picked.id, project: picked.project, ...meta, ...vaultParam() });
|
|
86
86
|
})) : null;
|
|
87
|
+
// `reset` only says the page token was stale: the reply can land on the page holding the selected candidate.
|
|
88
|
+
// The returned page index decides whether an earlier page exists; an unavailable reply has none, so there a
|
|
89
|
+
// stale page param can still be cleared.
|
|
90
|
+
const pageIndex = Number(String(s.page ?? "").split(":")[1]);
|
|
91
|
+
const showFirst = Number.isSafeInteger(pageIndex) ? pageIndex > 0 : Boolean(params.page);
|
|
87
92
|
return [s.unavailable ? ui.notice(s.unavailable, "err") : null, form,
|
|
88
|
-
|
|
89
|
-
...(
|
|
93
|
+
s.nextPage || showFirst ? h("div", { class: "vmem-bar" },
|
|
94
|
+
...(showFirst ? [ui.button("First page", () => go("promote"))] : []),
|
|
95
|
+
...(s.nextPage ? [ui.button("Next page", () => go("promote", { page: s.nextPage }))] : [])) : null,
|
|
96
|
+
ui.rows(all, (c) => ui.row({ title: c.title || c.kind, sub: `${c.kind} · ${c.project} · ${new Date(c.at).toLocaleString()}`, onOpen: () => go("promote", { id: c.id, project: c.project, page: s.page }),
|
|
97
|
+
...(s.selected === c.id ? { chip: { text: "selected", tone: "neutral" } } : { verbs: [ui.button("Select", () => go("promote", { id: c.id, project: c.project, page: s.page }))] }) }))
|
|
90
98
|
?? ui.empty("No promotion candidates", "Durable agent memories appear here when agent-mem marks them for the vault.")];
|
|
91
99
|
},
|
|
92
100
|
lint(s) {
|
|
@@ -106,8 +114,9 @@ export default (host) => {
|
|
|
106
114
|
},
|
|
107
115
|
};
|
|
108
116
|
|
|
109
|
-
let last = "";
|
|
110
|
-
|
|
117
|
+
let last = "", savedView = "", savedSnapshot;
|
|
118
|
+
const viewKey = () => JSON.stringify([panel, params]);
|
|
119
|
+
const render = (snap) => {
|
|
111
120
|
const sig = JSON.stringify([panel, snap]);
|
|
112
121
|
if (sig === last) return; // unchanged poll: keep focus and scroll
|
|
113
122
|
last = sig;
|
|
@@ -118,9 +127,21 @@ export default (host) => {
|
|
|
118
127
|
root.replaceChildren(...(views[panel]?.(snap) ?? [ui.empty("Unknown panel")]).filter(Boolean));
|
|
119
128
|
for (const el of root.querySelectorAll("input[name], select[name]")) if (values.has(el.name)) el[el.type === "checkbox" ? "checked" : "value"] = values.get(el.name);
|
|
120
129
|
if (focused) root.querySelector(`[name="${focused}"]`)?.focus();
|
|
130
|
+
};
|
|
131
|
+
host.onSnapshot((snap) => {
|
|
132
|
+
if (snap.changed === false) {
|
|
133
|
+
if (last === "" && savedView === viewKey() && savedSnapshot) render(savedSnapshot);
|
|
134
|
+
return;
|
|
135
|
+
}
|
|
136
|
+
savedView = viewKey(); savedSnapshot = snap;
|
|
137
|
+
render(snap);
|
|
121
138
|
});
|
|
122
139
|
return {
|
|
123
|
-
show(id, p = {}) {
|
|
140
|
+
show(id, p = {}) {
|
|
141
|
+
panel = id; params = p; last = ""; root.replaceChildren();
|
|
142
|
+
// Some shells suppress unchanged replies before invoking onSnapshot. Restore on show too.
|
|
143
|
+
if (savedView === viewKey() && savedSnapshot) render(savedSnapshot);
|
|
144
|
+
},
|
|
124
145
|
hide() {},
|
|
125
146
|
destroy() { root.remove(); },
|
|
126
147
|
};
|
package/src/ui/plugin.ts
CHANGED
|
@@ -10,6 +10,7 @@ import { createVaultMcp } from "../mcp-vault.ts";
|
|
|
10
10
|
import { validArguments } from "../mcp.ts";
|
|
11
11
|
import { listPromotionCandidates } from "../promote.ts";
|
|
12
12
|
import { loadRegistry } from "../registry.ts";
|
|
13
|
+
import { createSnapshotRevision, createPromoteSnapshot, nextSnapshotCursor } from "./snapshot-cache.ts";
|
|
13
14
|
import { createInboxSnapshot } from "./inbox.ts";
|
|
14
15
|
import { lintVault } from "../vault-lint.ts";
|
|
15
16
|
import { readLogSince } from "../vault-log.ts";
|
|
@@ -133,16 +134,18 @@ export const plugin: ConsolePlugin = {
|
|
|
133
134
|
return report;
|
|
134
135
|
};
|
|
135
136
|
const projectOf = new Map<string, string>();
|
|
137
|
+
const revision = createSnapshotRevision(home, mcp.vaults);
|
|
136
138
|
const candidates = async () => {
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
}
|
|
142
|
-
catch (error) { ctx.log(`vmem: promotion candidates unavailable: ${error instanceof Error ? error.message : String(error)}`); return { projects: [], unavailable: "agent-mem candidates are unavailable; see System" }; }
|
|
139
|
+
const { projects } = await listPromotionCandidates({ allProjects: true, limit: 50, piiPatterns: loadRegistry(home).piiPatterns });
|
|
140
|
+
projectOf.clear();
|
|
141
|
+
for (const p of projects) for (const c of p.candidates) projectOf.set(c.id, c.project);
|
|
142
|
+
return { projects };
|
|
143
143
|
};
|
|
144
144
|
|
|
145
|
-
const
|
|
145
|
+
const promote = createPromoteSnapshot(revision.current, candidates);
|
|
146
|
+
const inbox = createInboxSnapshot(home, mcp.vaults, ctx.log, undefined, revision.current);
|
|
147
|
+
// One cursor for the whole Promote failure: a fresh one per failed scan would rebuild the panel every poll.
|
|
148
|
+
let promoteErrorCursor: number | undefined;
|
|
146
149
|
|
|
147
150
|
/** One two-step operation: preview, and with the console's confirmation recompute and write only on the same fingerprint. */
|
|
148
151
|
async function twoStep(tool: string, args: Args | string, confirmed: boolean, fingerprint: string | undefined, describe: (preview: Args) => { verb: string; preview: string[]; changes: Change[]; warnings: string[] }): Promise<ActionResult> {
|
|
@@ -154,7 +157,7 @@ export const plugin: ConsolePlugin = {
|
|
|
154
157
|
return { ok: false, needsConfirm: true, fingerprint: preview.fingerprint, verb: d.verb, preview: d.preview, changes: d.changes, ...(d.warnings.length ? { warnings: d.warnings } : {}) };
|
|
155
158
|
}
|
|
156
159
|
const done = await call(tool, { ...args, confirm: true, fingerprint });
|
|
157
|
-
if (done.applied === true) { lintCache.clear(); inbox.invalidate(); }
|
|
160
|
+
if (done.applied === true) { lintCache.clear(); revision.invalidate(); inbox.invalidate(); }
|
|
158
161
|
return confirmedOutcome(done, describe(preview).verb);
|
|
159
162
|
}
|
|
160
163
|
|
|
@@ -164,7 +167,10 @@ export const plugin: ConsolePlugin = {
|
|
|
164
167
|
async snapshot(input) {
|
|
165
168
|
const args = input as Args;
|
|
166
169
|
switch (input.panel) {
|
|
167
|
-
case "inbox":
|
|
170
|
+
case "inbox": {
|
|
171
|
+
const result = await inbox.snapshot();
|
|
172
|
+
return args.after === result.cursor ? { changed: false, cursor: result.cursor } : result;
|
|
173
|
+
}
|
|
168
174
|
case "search": {
|
|
169
175
|
const q = str(args.q);
|
|
170
176
|
if (!q) return { hits: [], total: 0 };
|
|
@@ -197,7 +203,20 @@ export const plugin: ConsolePlugin = {
|
|
|
197
203
|
const promotable = vaultOf(args)?.id === mcp.defaultVault && vaultOf(args)?.kind === "personal";
|
|
198
204
|
return { note, links, orgVaults: promotable ? mcp.vaults.filter(v => v.kind === "org").map(v => v.id) : [] };
|
|
199
205
|
}
|
|
200
|
-
case "promote":
|
|
206
|
+
case "promote": {
|
|
207
|
+
try {
|
|
208
|
+
const result = await promote.snapshot(args);
|
|
209
|
+
promoteErrorCursor = undefined;
|
|
210
|
+
return result;
|
|
211
|
+
} catch (error) {
|
|
212
|
+
ctx.log(`vmem: promotion snapshot unavailable: ${error instanceof Error ? error.message : String(error)}`);
|
|
213
|
+
promoteErrorCursor ??= nextSnapshotCursor();
|
|
214
|
+
// The shell keeps that one cursor: a matching `after` suppresses the unchanged error view.
|
|
215
|
+
return args.after === promoteErrorCursor
|
|
216
|
+
? { changed: false, cursor: promoteErrorCursor }
|
|
217
|
+
: { projects: [], unavailable: "Promotion candidates are unavailable; see System", cursor: promoteErrorCursor };
|
|
218
|
+
}
|
|
219
|
+
}
|
|
201
220
|
case "lint": {
|
|
202
221
|
const vault = vaultOf(args);
|
|
203
222
|
if (!vault) return { findings: [] };
|
|
@@ -251,8 +270,15 @@ export const plugin: ConsolePlugin = {
|
|
|
251
270
|
case "promote-from-amem": {
|
|
252
271
|
const id = (str(args.id) ?? "").replace(/^mem:/, "");
|
|
253
272
|
if (!/^[0-9a-f-]{32,36}$/i.test(id)) return { ok: false, error: "a memory id is required" };
|
|
254
|
-
|
|
255
|
-
|
|
273
|
+
let project = str(args.project) ?? projectOf.get(id);
|
|
274
|
+
if (!project) {
|
|
275
|
+
try { await candidates(); }
|
|
276
|
+
catch (error) {
|
|
277
|
+
ctx.log(`vmem: promotion candidates unavailable: ${error instanceof Error ? error.message : String(error)}`);
|
|
278
|
+
return { ok: false, error: "Promotion candidates are unavailable; see System" };
|
|
279
|
+
}
|
|
280
|
+
project = projectOf.get(id);
|
|
281
|
+
}
|
|
256
282
|
return twoStep("vmem_promote_from_amem", forward("vmem_promote_from_amem", args, { id, ...(project ? { project } : {}) }), confirmed, fingerprint, p => {
|
|
257
283
|
const dupes = Array.isArray(p.possibleDuplicates) ? p.possibleDuplicates as string[] : [];
|
|
258
284
|
// Linking an existing note writes no vault file; it records the link in agent-mem only.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
|
|
2
|
+
import { createHash } from "node:crypto";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
import type { VaultSpec } from "../config.ts";
|
|
5
|
+
import { CONFIG_FILE } from "../config.ts";
|
|
6
|
+
import type { listPromotionCandidates } from "../promote.ts";
|
|
7
|
+
|
|
8
|
+
type Candidates = Awaited<ReturnType<typeof listPromotionCandidates>>;
|
|
9
|
+
type Candidate = Candidates["projects"][number]["candidates"][number];
|
|
10
|
+
const PAGE_BYTES = 32 * 1024;
|
|
11
|
+
// Each of the 64 accepted selection characters can occupy six bytes after JSON escaping.
|
|
12
|
+
const SELECTED_BYTES = 64 * 6 + 2;
|
|
13
|
+
let sequence = Date.now();
|
|
14
|
+
export const nextSnapshotCursor = () => ++sequence;
|
|
15
|
+
|
|
16
|
+
/** Receipt metadata can share a timestamp across writes on coarse filesystems. Include a bounded
|
|
17
|
+
* log tail (or the entire size-limited registry) so same-size rewrites still invalidate. */
|
|
18
|
+
function revisionStamp(file: string, budget: number): string {
|
|
19
|
+
let fd: number | undefined;
|
|
20
|
+
try {
|
|
21
|
+
fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
|
|
22
|
+
const s = fstatSync(fd, { bigint: true });
|
|
23
|
+
const metadata = `${s.dev}:${s.ino}:${s.size}:${s.mtimeNs}:${s.ctimeNs}`;
|
|
24
|
+
if (!s.isFile()) return metadata;
|
|
25
|
+
const size = Number(s.size);
|
|
26
|
+
if (!Number.isSafeInteger(size)) throw new Error("revision source is too large");
|
|
27
|
+
if (budget > 256 && size > budget) throw new Error("registry exceeds its revision read budget");
|
|
28
|
+
const bytes = Buffer.alloc(Math.min(budget, size));
|
|
29
|
+
const count = readSync(fd, bytes, 0, bytes.length, Math.max(0, size - bytes.length));
|
|
30
|
+
return `${metadata}:${createHash("sha256").update(bytes.subarray(0, count)).digest("hex")}`;
|
|
31
|
+
} catch (error) {
|
|
32
|
+
if ((error as NodeJS.ErrnoException).code === "ENOENT") return "missing";
|
|
33
|
+
// A broken source must not prevent healthy vaults or unrelated panels from opening.
|
|
34
|
+
// Recovery changes this stamp back to file evidence and invalidates the cache.
|
|
35
|
+
return `error:${(error as NodeJS.ErrnoException).code ?? "UNREADABLE"}`;
|
|
36
|
+
} finally { if (fd !== undefined) closeSync(fd); }
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** A vmem write appends a receipt to its vault log. Check bounded receipt evidence, never scan notes or open Git/SQLite.
|
|
40
|
+
* Configuration changes also invalidate policy-screened candidates. An explicit invalidation covers an
|
|
41
|
+
* applied console write whose follow-up log failed, including link-only agent-mem promotions. */
|
|
42
|
+
export function createSnapshotRevision(home: string, vaults: VaultSpec[]) {
|
|
43
|
+
const files = [{ file: join(home, CONFIG_FILE), budget: 64 * 1024 }, ...vaults.map(vault => ({ file: join(vault.path, "log"), budget: 256 }))];
|
|
44
|
+
let previous = "", cursor = nextSnapshotCursor();
|
|
45
|
+
return {
|
|
46
|
+
current(): number {
|
|
47
|
+
const stamp = files.map(({ file, budget }) => revisionStamp(file, budget)).join("|");
|
|
48
|
+
if (stamp !== previous) { previous = stamp; cursor = nextSnapshotCursor(); }
|
|
49
|
+
return cursor;
|
|
50
|
+
},
|
|
51
|
+
invalidate() { cursor = nextSnapshotCursor(); },
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Retain only the brief candidate metadata, and prepare byte-bounded pages once per revision.
|
|
56
|
+
* `cursor` identifies the page (including selection), `nextPage` is navigation, and `after` is conditional polling. */
|
|
57
|
+
export function createPromoteSnapshot(revision: () => number, load: () => Promise<Candidates>, now: () => number = Date.now) {
|
|
58
|
+
let cached: { revision: number; generation: number; digest: string; at: number; pages: Candidate[][] } | undefined;
|
|
59
|
+
let flight: Promise<void> | undefined;
|
|
60
|
+
const cursors = new Map<string, number>();
|
|
61
|
+
function response(rows: Candidate[], selected: string | null, cursor: number, page: string, nextPage?: string) {
|
|
62
|
+
const projects: Candidates["projects"] = [];
|
|
63
|
+
for (const row of rows) {
|
|
64
|
+
let project = projects.find(p => p.project === row.project);
|
|
65
|
+
if (!project) { project = { project: row.project, candidates: [] }; projects.push(project); }
|
|
66
|
+
project.candidates.push(row);
|
|
67
|
+
}
|
|
68
|
+
return { projects, selected, cursor, page, ...(nextPage ? { nextPage } : {}) };
|
|
69
|
+
}
|
|
70
|
+
return {
|
|
71
|
+
async snapshot(args: Record<string, unknown>): Promise<Record<string, unknown>> {
|
|
72
|
+
// A concurrent write may move the revision while the scan runs. Never label that scan as the new revision.
|
|
73
|
+
let attempts = 0;
|
|
74
|
+
while (!cached || cached.revision !== revision() || now() - cached.at >= 60_000) {
|
|
75
|
+
// Bound retries under sustained writes, retaining the last completed pages at their old revision.
|
|
76
|
+
if (++attempts > 2 && cached) break;
|
|
77
|
+
if (!flight) {
|
|
78
|
+
const started = revision();
|
|
79
|
+
flight = (async () => {
|
|
80
|
+
const result = await load();
|
|
81
|
+
const pages: Candidate[][] = [[]];
|
|
82
|
+
for (const project of result.projects) for (const item of project.candidates) {
|
|
83
|
+
const candidate = { ...item, title: item.title === null ? null : [...item.title].slice(0, 160).join("") };
|
|
84
|
+
const rows = pages.at(-1)!;
|
|
85
|
+
// Reserve enough envelope space for cursors, page tokens, and selection/reset metadata.
|
|
86
|
+
if (Buffer.byteLength(JSON.stringify(response([...rows, candidate], null, Number.MAX_SAFE_INTEGER, "x".repeat(80), "x".repeat(80)))) + SELECTED_BYTES > PAGE_BYTES - 256) {
|
|
87
|
+
if (rows.length === 0) throw new Error(`promotion candidate ${candidate.id.slice(0, 64)} in project ${candidate.project.slice(0, 160)} exceeds the 32 KiB page budget; inspect and shorten its agent-mem project or candidate metadata, then retry`);
|
|
88
|
+
pages.push([]);
|
|
89
|
+
if (Buffer.byteLength(JSON.stringify(response([candidate], null, Number.MAX_SAFE_INTEGER, "x".repeat(80), "x".repeat(80)))) + SELECTED_BYTES > PAGE_BYTES - 256) throw new Error(`promotion candidate ${candidate.id.slice(0, 64)} in project ${candidate.project.slice(0, 160)} exceeds the 32 KiB page budget; inspect and shorten its agent-mem project or candidate metadata, then retry`);
|
|
90
|
+
}
|
|
91
|
+
pages.at(-1)!.push(candidate);
|
|
92
|
+
}
|
|
93
|
+
const digest = createHash("sha256").update(JSON.stringify(pages)).digest("hex");
|
|
94
|
+
const identical = cached?.digest === digest;
|
|
95
|
+
cached = { revision: started, generation: identical ? cached!.generation : nextSnapshotCursor(), digest, at: now(), pages };
|
|
96
|
+
if (!identical) cursors.clear();
|
|
97
|
+
})().catch(error => {
|
|
98
|
+
// An error view replaces the last good view. Recovery must send full rows even when identical.
|
|
99
|
+
cursors.clear();
|
|
100
|
+
throw error;
|
|
101
|
+
}).finally(() => { flight = undefined; });
|
|
102
|
+
}
|
|
103
|
+
await flight;
|
|
104
|
+
}
|
|
105
|
+
const { pages, generation: rev } = cached;
|
|
106
|
+
const selected = typeof args.id === "string" && args.id.length <= 64 ? args.id : null;
|
|
107
|
+
const token = typeof args.page === "string" ? /^(\d+):(\d+)$/.exec(args.page) : null;
|
|
108
|
+
const validPage = token !== null && Number(token[1]) === rev && Number.isSafeInteger(Number(token[2])) && Number(token[2]) < pages.length;
|
|
109
|
+
const reset = args.page !== undefined && !validPage;
|
|
110
|
+
let index = validPage ? Number(token[2]) : 0;
|
|
111
|
+
if (!validPage && selected) index = Math.max(0, pages.findIndex(rows => rows.some(row => row.id === selected)));
|
|
112
|
+
const key = `${index}:${selected ?? ""}`;
|
|
113
|
+
let cursor = cursors.get(key);
|
|
114
|
+
if (cursor === undefined) {
|
|
115
|
+
// A bounded set of view cursors avoids growing with arbitrary selection inputs.
|
|
116
|
+
if (cursors.size >= 256) cursors.delete(cursors.keys().next().value!);
|
|
117
|
+
cursor = nextSnapshotCursor(); cursors.set(key, cursor);
|
|
118
|
+
}
|
|
119
|
+
if (args.after === cursor) return { changed: false, cursor };
|
|
120
|
+
return { ...response(pages[index]!, selected, cursor, `${rev}:${index}`, index + 1 < pages.length ? `${rev}:${index + 1}` : undefined), ...(reset ? { reset: true } : {}) };
|
|
121
|
+
},
|
|
122
|
+
};
|
|
123
|
+
}
|
package/src/vault-index.ts
CHANGED
|
@@ -6,7 +6,7 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
|
|
|
6
6
|
import type { AnalysisSnapshot } from "./analysis-types.ts";
|
|
7
7
|
import type { VaultSpec, SpecSourceSpec } from "./config.ts";
|
|
8
8
|
import { parseFrontmatter, type FrontmatterDocument } from "./frontmatter.ts";
|
|
9
|
-
import { normalizeTarget, noteKey, proseLines, resolveLinks, type LinkNote, type ResolvedLink } from "./links.ts";
|
|
9
|
+
import { normalizeTarget, noteKey, proseLines, resolveLinks, type LinkNote, type ResolvedLink, type SuggestedLink, type TitleSuggestion } from "./links.ts";
|
|
10
10
|
|
|
11
11
|
export const MAX_NOTE_BYTES = 2 * 1024 * 1024;
|
|
12
12
|
export const MAX_RESULTS = 500;
|
|
@@ -16,8 +16,12 @@ export const MAX_RESULTS = 500;
|
|
|
16
16
|
* share the unversioned `<digest>.sqlite`; the first run of a newer version builds its own file once.
|
|
17
17
|
*/
|
|
18
18
|
export const LINK_RESOLUTION = 2;
|
|
19
|
-
/**
|
|
20
|
-
|
|
19
|
+
/**
|
|
20
|
+
* Bump when tables, FTS columns or the indexed text change. Named per value like LINK_RESOLUTION. 2 = CJK bigram
|
|
21
|
+
* table; 3 = reference identifiers in FTS; 4 = arXiv ids in the FTS text of reference notes, so a schema-3 cache
|
|
22
|
+
* built before that rebuilds once instead of answering without the id.
|
|
23
|
+
*/
|
|
24
|
+
export const INDEX_SCHEMA = 4;
|
|
21
25
|
const indexName = (root: string) => `${digest(root)}-links${LINK_RESOLUTION}-schema${INDEX_SCHEMA}.sqlite`;
|
|
22
26
|
/**
|
|
23
27
|
* unicode61 keeps each Hangul/CJK run as one token, so `사업단` misses `사업단은`. A side table holds the
|
|
@@ -51,6 +55,13 @@ export function splitTerms(words: string[]): { tokens: string[]; runs: string[]
|
|
|
51
55
|
return { tokens, runs };
|
|
52
56
|
}
|
|
53
57
|
export const MAX_READ_BYTES = 64 * 1024;
|
|
58
|
+
/** A hint must beat this: a term that appears in most titles scores at or below zero, and one shared common word stays under it. */
|
|
59
|
+
export const MIN_SUGGESTION_SCORE = 0.5;
|
|
60
|
+
/**
|
|
61
|
+
* A link's target, label, heading and block are reported within this many bytes of their raw text, and a hint is
|
|
62
|
+
* looked up for at most the same bound, so a reported row and the hint for it never judge different text.
|
|
63
|
+
*/
|
|
64
|
+
const LINK_TEXT_BYTES = 1024;
|
|
54
65
|
export interface IndexedNote extends LinkNote { hash: string; description: string; type: string; domain: string }
|
|
55
66
|
export interface NoteReadResult {
|
|
56
67
|
path: string;
|
|
@@ -163,6 +174,14 @@ export interface IndexSourceAdapter {
|
|
|
163
174
|
}
|
|
164
175
|
export class IndexCacheError extends Error {}
|
|
165
176
|
export interface IndexOptions { memory?: boolean; adapter?: IndexSourceAdapter; reuseCache?: boolean }
|
|
177
|
+
/** Whitespace-separated tokens of a note source, frontmatter included; 0 for an empty source. */
|
|
178
|
+
const wordCount = (source: string) => { const trimmed = source.trim(); return trimmed ? trimmed.split(/\s+/u).length : 0; };
|
|
179
|
+
/** Note text size in bytes and words, with the number of notes that contributed. */
|
|
180
|
+
export interface NoteSize { notes: number; bytes: number; words: number }
|
|
181
|
+
/** One note that declares frontmatter `source`, with the byte size the ratio compares to its sources. */
|
|
182
|
+
export interface SourcedNote { path: string; bytes: number; source: unknown }
|
|
183
|
+
/** The ratio pass reads at most this many notes that declare a source, in path order. */
|
|
184
|
+
export const MAX_RATIO_NOTES = 10000;
|
|
166
185
|
/** Derived cache only. No vault or application configuration files are written. */
|
|
167
186
|
export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
|
|
168
187
|
private readonly db: Database;
|
|
@@ -242,10 +261,13 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
|
|
|
242
261
|
}
|
|
243
262
|
close(): void { this.db.close(); }
|
|
244
263
|
// ponytail: grams stores its bigram text (about 2.3x the CJK bytes); contentless with stable rowids would save it.
|
|
245
|
-
/**
|
|
264
|
+
/**
|
|
265
|
+
* Keep the stored body and link/analysis input unchanged; identifiers join only the FTS text. The arXiv id goes in
|
|
266
|
+
* without its `vN` version suffix, since a caller holding `2502.04321` cannot tokenize the suffixed form.
|
|
267
|
+
*/
|
|
246
268
|
private searchBody(body: string, data: Record<string, unknown>): string {
|
|
247
269
|
if (this.adapter || data.type !== "reference") return body;
|
|
248
|
-
const identifiers = [text(data.doi), text(data.citekey)].filter(Boolean);
|
|
270
|
+
const identifiers = [text(data.doi), text(data.citekey), text(data.arxiv_id).replace(/v\d+$/, "")].filter(Boolean);
|
|
249
271
|
return identifiers.length ? body + "\n" + identifiers.join("\n") : body;
|
|
250
272
|
}
|
|
251
273
|
private indexText(path: string, title: string, description: string, body: string): void {
|
|
@@ -419,6 +441,45 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
|
|
|
419
441
|
.slice(snapshot ? snapshotOffset : 0, (snapshot ? snapshotOffset : 0) + (snapshot && allSnapshotRows ? 10000 : limit))
|
|
420
442
|
.map(({ sourceHash: _, ...row }) => ({ ...row, title: boundedText(row.title, 512).content, snippet: boundedText(row.snippet, 1024).content, type: boundedText(row.type, 256).content, domain: boundedText(row.domain, 256).content }));
|
|
421
443
|
}
|
|
444
|
+
/**
|
|
445
|
+
* The one indexed title closest to a dead link's text, or undefined when no title matches or the best match is at
|
|
446
|
+
* or below `minimum`. Same literal AND terms as `search`, matched in the title column only, because a hint should
|
|
447
|
+
* name a note whose title actually carries the link text. A title must carry every part of the text: a CJK run
|
|
448
|
+
* matches through the bigram table and a Latin term through unicode61, and the two scores are summed, because a part
|
|
449
|
+
* that many titles share scores near zero on its own and would otherwise hide a title that carries the whole text.
|
|
450
|
+
* The score is positive bm25, rounded to three decimals, so a larger value is a closer title. A hint is never an
|
|
451
|
+
* error: raw text past `LINK_TEXT_BYTES`, or text FTS5 cannot parse, returns undefined instead of throwing. The bound
|
|
452
|
+
* is read on the raw text, before normalization and never on the truncated target a row displays, so `links` and
|
|
453
|
+
* `lint` name the same hint for the same dead link. Read-only.
|
|
454
|
+
*/
|
|
455
|
+
suggestTitle(text: string, minimum = MIN_SUGGESTION_SCORE): TitleSuggestion | undefined {
|
|
456
|
+
if (Buffer.byteLength(text) > LINK_TEXT_BYTES) return undefined;
|
|
457
|
+
// Link text is note content, so it can carry a control character. unicode61 already indexes one as a separator,
|
|
458
|
+
// and U+0000 kept inside a quoted term ends the string in SQLite and makes FTS5 throw "unterminated string".
|
|
459
|
+
const query = text.replace(/\p{Cc}/gu, " ").trim();
|
|
460
|
+
if (!query) return undefined;
|
|
461
|
+
const { tokens, runs } = splitTerms(query.split(/\s+/));
|
|
462
|
+
if (!tokens.length && !runs.length) return undefined;
|
|
463
|
+
const gramQuery = `{title} : (${runs.map(gramPhrase).join(" AND ")})`, tokenQuery = `{title} : (${tokens.join(" AND ")})`;
|
|
464
|
+
let row: TitleSuggestion | null | undefined;
|
|
465
|
+
try {
|
|
466
|
+
row = runs.length && tokens.length
|
|
467
|
+
? this.db.query<TitleSuggestion, string[]>(`SELECT n.path, n.title, g.score + f.score AS score
|
|
468
|
+
FROM (SELECT path, -bm25(grams,0,5,2,1) AS score FROM grams WHERE grams MATCH ?) g
|
|
469
|
+
JOIN (SELECT path, -bm25(fts,0,5,2,1) AS score FROM fts WHERE fts MATCH ?) f ON f.path = g.path
|
|
470
|
+
JOIN notes n ON n.path = g.path ORDER BY score DESC, n.path LIMIT 1`).get(gramQuery, tokenQuery)
|
|
471
|
+
: runs.length
|
|
472
|
+
? this.db.query<TitleSuggestion, string[]>(`SELECT n.path, n.title, -bm25(grams,0,5,2,1) AS score FROM grams JOIN notes n ON n.path=grams.path
|
|
473
|
+
WHERE grams MATCH ? ORDER BY score DESC, n.path LIMIT 1`).get(gramQuery)
|
|
474
|
+
: this.db.query<TitleSuggestion, string[]>(`SELECT n.path, n.title, -bm25(fts,0,5,2,1) AS score FROM fts JOIN notes n ON n.path=fts.path
|
|
475
|
+
WHERE fts MATCH ? ORDER BY score DESC, n.path LIMIT 1`).get(tokenQuery);
|
|
476
|
+
} catch {
|
|
477
|
+
// A hint is advisory: text FTS5 still cannot parse yields no suggestion instead of failing links and lint.
|
|
478
|
+
return undefined;
|
|
479
|
+
}
|
|
480
|
+
if (!row || !(row.score > minimum)) return undefined;
|
|
481
|
+
return { path: row.path, title: boundedText(row.title, 512).content, score: Math.round(row.score * 1000) / 1000 };
|
|
482
|
+
}
|
|
422
483
|
private find(target: string): string {
|
|
423
484
|
if (!target || Buffer.byteLength(target) > 1024) throw new Error("note: expected target <=1024 bytes");
|
|
424
485
|
const key = normalizeTarget(target.replace(/^notes\//i, "").replace(/\.md$/i, ""));
|
|
@@ -435,6 +496,14 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
|
|
|
435
496
|
if (notes.length !== 1) throw new Error(notes.length ? "note: ambiguous target" : "note: unknown target");
|
|
436
497
|
return notes[0]!.path;
|
|
437
498
|
}
|
|
499
|
+
/** Literal indexed-note source, with the byte bound checked before returning/decoding it. */
|
|
500
|
+
noteSource(path: string, maximum = MAX_NOTE_BYTES): string | undefined {
|
|
501
|
+
if (!Number.isInteger(maximum) || maximum < 1 || maximum > MAX_NOTE_BYTES) throw new Error(`note source maximum: expected 1..${MAX_NOTE_BYTES} bytes; choose a bound within the note reader limit`);
|
|
502
|
+
const literal = path.startsWith("notes/") ? path.slice(6) : path;
|
|
503
|
+
const row = this.db.query<{ source: string | null }, [number, string]>("SELECT CASE WHEN length(CAST(source AS BLOB))<=? THEN source ELSE NULL END AS source FROM notes WHERE path=?").get(maximum, literal);
|
|
504
|
+
if (row?.source === null) throw Object.assign(new Error(`note source exceeds the ${maximum}-byte remaining read budget; split the note or reduce configured tables before retrying`), { code: "V09" });
|
|
505
|
+
return row?.source;
|
|
506
|
+
}
|
|
438
507
|
show(target: string, maxBytes = 16384, section?: string, offset?: number): NoteReadResult {
|
|
439
508
|
if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > MAX_READ_BYTES) throw new Error(`max-bytes: expected integer 1..${MAX_READ_BYTES}`);
|
|
440
509
|
if (section !== undefined && (typeof section !== "string" || !section.trim() || /[\r\n]/.test(section) || Buffer.byteLength(section) > 1024)) throw new Error("section: expected one exact H2 heading <=1024 bytes");
|
|
@@ -450,7 +519,8 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
|
|
|
450
519
|
if (!page.truncated) return { path, hash: note.hash, ...page, ...metadata };
|
|
451
520
|
}
|
|
452
521
|
// Only the derived source is loaded; section discovery never rescans a note file.
|
|
453
|
-
const source = this.
|
|
522
|
+
const source = this.noteSource(path);
|
|
523
|
+
if (source === undefined) throw new Error("note: source disappeared or exceeded the read bound during paging; refresh and reread the note");
|
|
454
524
|
const body = parseFrontmatter(source).body, sections = h2Sections(body);
|
|
455
525
|
if (section !== undefined) {
|
|
456
526
|
const found = sections.filter(item => item.name === section);
|
|
@@ -480,10 +550,15 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
|
|
|
480
550
|
return { notes, total, ...(rows.length > max ? { nextCursor: notes.at(-1)!.path } : {}) };
|
|
481
551
|
}
|
|
482
552
|
/**
|
|
483
|
-
* Note counts by type, domain and frontmatter `status` ("(none)" when empty),
|
|
484
|
-
* after each cutoff (epoch ms)
|
|
553
|
+
* Note counts by type, domain and frontmatter `status` ("(none)" when empty), how many notes have an mtime at or
|
|
554
|
+
* after each cutoff (epoch ms), note text size in bytes and words by type and domain, and the notes that declare a
|
|
555
|
+
* frontmatter `source` (at most `sourcedLimit`, in path order) as the input of the note-to-source ratio, with
|
|
556
|
+
* `truncatedSourced` counting the sourced notes that cap kept out. Streams rows; returns no note text.
|
|
485
557
|
*/
|
|
486
|
-
noteStats(cutoffs: readonly number[]
|
|
558
|
+
noteStats(cutoffs: readonly number[], sourcedLimit = MAX_RATIO_NOTES): {
|
|
559
|
+
total: number; byType: Record<string, number>; byDomain: Record<string, number>; byStatus: Record<string, number>; modified: number[];
|
|
560
|
+
size: { total: NoteSize; byType: Record<string, NoteSize>; byDomain: Record<string, NoteSize> }; sourced: SourcedNote[]; truncatedSourced: number;
|
|
561
|
+
} {
|
|
487
562
|
const add = (map: Map<string, number>, value: string, count = 1) => { const key = value ? boundedText(value, 256).content : "(none)"; map.set(key, (map.get(key) ?? 0) + count); };
|
|
488
563
|
const sorted = (map: Map<string, number>) => Object.fromEntries([...map].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
|
|
489
564
|
const grouped = (column: "type" | "domain") => {
|
|
@@ -491,21 +566,32 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
|
|
|
491
566
|
for (const row of this.db.query<{ value: string; count: number }, []>(`SELECT ${column} AS value, count(*) AS count FROM notes GROUP BY ${column}`).all()) add(map, row.value, row.count);
|
|
492
567
|
return sorted(map);
|
|
493
568
|
};
|
|
494
|
-
|
|
495
|
-
const
|
|
496
|
-
|
|
497
|
-
|
|
569
|
+
const size = { total: { notes: 0, bytes: 0, words: 0 }, byType: new Map<string, NoteSize>(), byDomain: new Map<string, NoteSize>() };
|
|
570
|
+
const grow = (map: Map<string, NoteSize>, value: string, bytes: number, words: number) => {
|
|
571
|
+
const key = value ? boundedText(value, 256).content : "(none)", item = map.get(key) ?? { notes: 0, bytes: 0, words: 0 };
|
|
572
|
+
map.set(key, { notes: item.notes + 1, bytes: item.bytes + bytes, words: item.words + words });
|
|
573
|
+
};
|
|
574
|
+
const sortedSize = (map: Map<string, NoteSize>) => Object.fromEntries([...map].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
|
|
575
|
+
// Status, size and `source` are not columns: stream each stored source once, parsing only its frontmatter.
|
|
576
|
+
const byStatus = new Map<string, number>(), modified = cutoffs.map(() => 0), sourced: SourcedNote[] = [];
|
|
577
|
+
let total = 0, truncatedSourced = 0;
|
|
578
|
+
const rows = this.db.prepare<{ metadata: string; source: string; path: string; type: string; domain: string }, []>("SELECT metadata,source,path,type,domain FROM notes ORDER BY path");
|
|
498
579
|
try {
|
|
499
580
|
for (const row of rows.iterate()) {
|
|
500
581
|
total++;
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
582
|
+
const bytes = Buffer.byteLength(row.source), words = wordCount(row.source);
|
|
583
|
+
size.total = { notes: size.total.notes + 1, bytes: size.total.bytes + bytes, words: size.total.words + words };
|
|
584
|
+
grow(size.byType, row.type, bytes, words); grow(size.byDomain, row.domain, bytes, words);
|
|
585
|
+
let data: Record<string, unknown> = {};
|
|
586
|
+
try { data = parseFrontmatter(row.source).data; } catch { /* counted as (none) and skipped by the ratio pass */ }
|
|
587
|
+
add(byStatus, text(data.status));
|
|
588
|
+
if (data.source !== undefined) { if (sourced.length < sourcedLimit) sourced.push({ path: row.path, bytes, source: data.source }); else truncatedSourced++; }
|
|
504
589
|
const mtime = stampMtime(row.metadata);
|
|
505
590
|
cutoffs.forEach((cutoff, i) => { if (mtime !== null && mtime >= cutoff) modified[i]!++; });
|
|
506
591
|
}
|
|
507
592
|
} finally { rows.finalize(); }
|
|
508
|
-
return { total, byType: grouped("type"), byDomain: grouped("domain"), byStatus: sorted(byStatus), modified
|
|
593
|
+
return { total, byType: grouped("type"), byDomain: grouped("domain"), byStatus: sorted(byStatus), modified,
|
|
594
|
+
size: { total: size.total, byType: sortedSize(size.byType), byDomain: sortedSize(size.byDomain) }, sourced, truncatedSourced };
|
|
509
595
|
}
|
|
510
596
|
/** Links that resolve to the target note, ordered by source. */
|
|
511
597
|
backlinks(target: string, limit = 50): ResolvedLink[] {
|
|
@@ -553,8 +639,12 @@ export class VaultIndex<Source extends VaultSpec | SpecSourceSpec = VaultSpec> {
|
|
|
553
639
|
} finally { rows.finalize(); }
|
|
554
640
|
return out;
|
|
555
641
|
}
|
|
556
|
-
links(target: string, limit = 50):
|
|
642
|
+
links(target: string, limit = 50): SuggestedLink[] {
|
|
557
643
|
const path = this.find(target);
|
|
558
|
-
return this.db.query<{ data: string }, [string, number]>("SELECT data FROM links WHERE source=? ORDER BY ordinal LIMIT ?").all(path, resultLimit(limit)).map(row => JSON.parse(row.data) as ResolvedLink).map(link => ({
|
|
644
|
+
return this.db.query<{ data: string }, [string, number]>("SELECT data FROM links WHERE source=? ORDER BY ordinal LIMIT ?").all(path, resultLimit(limit)).map(row => JSON.parse(row.data) as ResolvedLink).map(link => ({
|
|
645
|
+
...link, target: boundedText(link.target, LINK_TEXT_BYTES).content, label: link.label === null ? null : boundedText(link.label, LINK_TEXT_BYTES).content, heading: link.heading === null ? null : boundedText(link.heading, LINK_TEXT_BYTES).content, block: link.block === null ? null : boundedText(link.block, LINK_TEXT_BYTES).content,
|
|
646
|
+
// The hint reads the raw text, never the bounded `target` above: a link past the bound has to miss here and in
|
|
647
|
+
// lint alike, or one surface names a suggestion the other, reading the whole text, cannot.
|
|
648
|
+
...(link.resolved === null ? { suggested: this.suggestTitle(link.target) ?? null } : {}) }));
|
|
559
649
|
}
|
|
560
650
|
}
|
package/src/vault-lint.ts
CHANGED
|
@@ -9,8 +9,10 @@ const LEGACY = new Set("CREATE UPDATE MIGRATE REFACTOR MERGE MOVE RELOCATE RENAM
|
|
|
9
9
|
const CODE_TITLES: Record<LintCode, string> = {
|
|
10
10
|
L01: "L01 — dead wiki-link", L02: "L02 — 필수 frontmatter / 허용값", L03: "L03 — orphan",
|
|
11
11
|
L09: "L09 — 로그 포맷", L10: "L10 — project 값", L11: "L11 — graph report staleness", L12: "L12 — island community", L13: "L13 — filename", L14: "L14 — source paths",
|
|
12
|
+
L15: "L15 — proven confidence의 source",
|
|
12
13
|
};
|
|
13
14
|
const truth = yamlTruthy;
|
|
15
|
+
const emptySource = (value: unknown) => !truth(value) || typeof value === "string" && !value.trim();
|
|
14
16
|
/** Python scalar formatting matters to per-code diagnostic parity. */
|
|
15
17
|
function py(x: unknown): string {
|
|
16
18
|
const scalar = scalarText(x); if (scalar !== undefined) return scalar;
|
|
@@ -37,6 +39,43 @@ function links(value: unknown): string[] {
|
|
|
37
39
|
return values.flatMap(v => typeof v === "string" ? [...v.matchAll(/\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]/g)].map(m => m[1]!.trim()) : []);
|
|
38
40
|
}
|
|
39
41
|
const stem = (s: string) => s.trim().replace(/\.md$/, "").split("/").at(-1)!;
|
|
42
|
+
/** Wiki-link texts L01 checks in one note, in the order it reports them: body links, then the link fields. */
|
|
43
|
+
function noteLinkTexts(source: string): string[] {
|
|
44
|
+
const { fm, body } = legacyDocument(source);
|
|
45
|
+
return [...links(body), ...FIELDS.flatMap(field => links(fm?.[field]))];
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* A snapshot record entry read as data only. Link text and note path reach these lookups unchanged, and a plain
|
|
49
|
+
* object answers `constructor`, `toString` or `__proto__` from `Object.prototype`; a snapshot another caller built
|
|
50
|
+
* can still be a plain record, so inherited members must never resolve as a hint or as warnings.
|
|
51
|
+
*/
|
|
52
|
+
function ownValue<T>(record: Record<string, T> | undefined, key: string): T | undefined {
|
|
53
|
+
return record !== undefined && Object.hasOwn(record, key) ? record[key] : undefined;
|
|
54
|
+
}
|
|
55
|
+
/** Unique dead link texts one lint run computes hints for; past it the report says so instead of reading as a miss. */
|
|
56
|
+
export const DEAD_LINK_HINT_CAP = 1000;
|
|
57
|
+
/**
|
|
58
|
+
* The dead link texts a snapshot can be hinted for, deduplicated in note and link order and capped at `maximum`.
|
|
59
|
+
* Captured while the index is open (src/analysis-input.ts), because the lookup needs the title search and
|
|
60
|
+
* `lintDetails` stays a pure transform.
|
|
61
|
+
*/
|
|
62
|
+
export function deadLinkTexts(notes: readonly { path: string; source: string }[], maximum = DEAD_LINK_HINT_CAP): string[] {
|
|
63
|
+
const stems = new Set(notes.map(note => note.path.replace(/^notes\//, "").slice(0, -3))), texts = new Set<string>();
|
|
64
|
+
for (const note of notes) {
|
|
65
|
+
for (const text of noteLinkTexts(note.source)) if (!stems.has(stem(text))) texts.add(text);
|
|
66
|
+
if (texts.size >= maximum) break;
|
|
67
|
+
}
|
|
68
|
+
return [...texts].slice(0, maximum);
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* The texts a hint pass attempts, the bound it worked within and how many unique texts that bound left out. Counting
|
|
72
|
+
* the remainder needs the whole traversal, because a reader that knows only the cap cannot tell an attempted miss from
|
|
73
|
+
* a dead link whose hint was never computed.
|
|
74
|
+
*/
|
|
75
|
+
export function deadLinkScan(notes: readonly { path: string; source: string }[], maximum = DEAD_LINK_HINT_CAP): { texts: string[]; cap: number; skipped: number } {
|
|
76
|
+
const all = deadLinkTexts(notes, Number.POSITIVE_INFINITY), texts = all.slice(0, maximum);
|
|
77
|
+
return { texts, cap: maximum, skipped: all.length - texts.length };
|
|
78
|
+
}
|
|
40
79
|
function graphChecks(snapshot: AnalysisSnapshot): { l11: string[]; l12: string[]; info: string } {
|
|
41
80
|
const l11: string[] = [], l12: string[] = [], names = Object.keys(snapshot.reports).filter(s => /^graph-report-.*\.md$/.test(s)).sort();
|
|
42
81
|
const latest = names.at(-1);
|
|
@@ -74,19 +113,26 @@ function graphChecks(snapshot: AnalysisSnapshot): { l11: string[]; l12: string[]
|
|
|
74
113
|
export function lintVault(snapshot: AnalysisSnapshot, only?: string): LintReport { return lintDetails(snapshot, only).report; }
|
|
75
114
|
/** The report plus what only its markdown carries: the note count, check titles and per-check info lines, for the CLI text view. */
|
|
76
115
|
export function lintDetails(snapshot: AnalysisSnapshot, only?: string): { report: LintReport; notes: number; titles: Record<LintCode, string>; info: Partial<Record<LintCode, string>> } {
|
|
77
|
-
const findings: Record<LintCode,string[]> = {L01:[],L02:[],L03:[],L09:[],L10:[],L11:[],L12:[],L13:[],L14:[]};
|
|
116
|
+
const findings: Record<LintCode,string[]> = {L01:[],L02:[],L03:[],L09:[],L10:[],L11:[],L12:[],L13:[],L14:[],L15:[]};
|
|
78
117
|
const notes = [...snapshot.notes].sort((a,b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0).map(n => ({...n,...legacyDocument(n.source),stem: n.path.replace(/^notes\//, "").slice(0,-3)}));
|
|
79
118
|
const stems = new Set(notes.map(n => n.stem)), inlinks = new Map(notes.map(n => [n.stem,0]));
|
|
119
|
+
// A text the hint pass never reached was not looked up, so its line must not read as a title that merely did not match.
|
|
120
|
+
const bound = snapshot.linkHintBound, attempted = bound ? new Set(bound.attempted) : undefined;
|
|
80
121
|
let superseded = 0;
|
|
81
122
|
for (const note of notes) {
|
|
82
123
|
const rel = `notes/${note.stem}.md`, prefix = `\`${rel}\`: `, fm = note.fm;
|
|
83
|
-
for(const message of snapshot.sourceWarnings
|
|
124
|
+
for (const message of ownValue(snapshot.sourceWarnings, note.path) ?? []) findings.L14.push(prefix+message);
|
|
84
125
|
const allLinks: [string,string][] = links(note.body).map(t => ["body",t]);
|
|
85
126
|
if (fm) for (const field of FIELDS) for (const t of links(fm[field])) allLinks.push([field,t]);
|
|
86
127
|
for (const [field,t] of allLinks) {
|
|
87
128
|
const target = stem(t);
|
|
88
129
|
if (stems.has(target)) { if (target !== note.stem) inlinks.set(target,inlinks.get(target)!+1); }
|
|
89
|
-
else
|
|
130
|
+
else {
|
|
131
|
+
const hint = ownValue(snapshot.linkHints, t);
|
|
132
|
+
const suffix = hint ? ` — suggested \`${hint.path}\` (score ${hint.score.toFixed(3)})`
|
|
133
|
+
: bound && !attempted!.has(t) ? ` — hint not computed (cap ${bound.cap})` : "";
|
|
134
|
+
findings.L01.push(prefix + `\`[[${t}]]\` (${field}) → 대상 노트 없음` + suffix);
|
|
135
|
+
}
|
|
90
136
|
}
|
|
91
137
|
if (fm === null) { findings.L02.push(prefix + "frontmatter 없음/파싱 실패"); continue; }
|
|
92
138
|
if (fm.status === "superseded") superseded++;
|
|
@@ -97,6 +143,7 @@ export function lintDetails(snapshot: AnalysisSnapshot, only?: string): { report
|
|
|
97
143
|
if (fm.type === "moc") { if (!truth(fm.description)) findings.L02.push(prefix + "`type: moc` 노트는 `description` 필수"); }
|
|
98
144
|
else if (!truth(fm.topics)) findings.L02.push(prefix + "`topics` 없음/빈 배열");
|
|
99
145
|
for (const [key,allowed] of [["confidence",CONFIDENCE],["status",STATUS]] as const) if (fm[key] !== undefined && fm[key] !== null && !allowed.includes(py(fm[key]))) findings.L02.push(prefix + `\`${key}: ${py(fm[key])}\` 허용값 아님 (${allowed.join(" | ")})${key === "status" ? " (status는 노트 생애주기이지 사업 진행 상태가 아님 — 작업 상태는 본문에)" : ""}`);
|
|
146
|
+
if (py(fm.confidence) === "proven" && emptySource(fm.source)) findings.L15.push(prefix + "`confidence: proven`에 `source` 없음 — 근거(memory id·URL·workspace 경로)를 추가하거나 confidence를 낮추기");
|
|
100
147
|
const project = fm.project;
|
|
101
148
|
if (typeof project === "string" && project.trim()) {
|
|
102
149
|
const targets = links(project);
|
|
@@ -120,11 +167,12 @@ export function lintDetails(snapshot: AnalysisSnapshot, only?: string): { report
|
|
|
120
167
|
}
|
|
121
168
|
if (data > 20000) findings.L09.push(`log ${data} 라인 > 20000 — 수동 아카이브 권장`);
|
|
122
169
|
const graph = graphChecks(snapshot); findings.L11 = graph.l11; findings.L12 = graph.l12;
|
|
123
|
-
if (only) for (const code of ["L01","L02","L03","L10","L13","L14"] as const) findings[code] = findings[code].filter(s => s.startsWith(`\`${only}\``));
|
|
170
|
+
if (only) for (const code of ["L01","L02","L03","L10","L13","L14","L15"] as const) findings[code] = findings[code].filter(s => s.startsWith(`\`${only}\``));
|
|
124
171
|
const errors = findings.L01.length + findings.L02.length + findings.L13.length;
|
|
125
|
-
const warnings = findings.L03.length + findings.L09.length + findings.L10.length + findings.L11.length + findings.L12.length + findings.L14.length;
|
|
172
|
+
const warnings = findings.L03.length + findings.L09.length + findings.L10.length + findings.L11.length + findings.L12.length + findings.L14.length + findings.L15.length;
|
|
126
173
|
const summary = `SUMMARY errors=${errors} warnings=${warnings}`;
|
|
127
174
|
const extra: Partial<Record<LintCode,string>> = {
|
|
175
|
+
L01: bound ? `정보: 힌트 상한 ${bound.cap}개 텍스트 초과 — ${bound.skipped}개 dead link 텍스트는 힌트 미계산 (미탐 아님)` : "",
|
|
128
176
|
L02: `정보: \`status: superseded\` ${superseded}건${superseded === 0 ? " — supersede 프로토콜 미가동" : ""}`,
|
|
129
177
|
L03: "hub MOC `notes/index.md`는 설계상 예외",
|
|
130
178
|
L09: snapshot.log === null ? "정보: log 없음" : `정보: ${legacy ? `legacy TYPE ${legacy}건 (정규화표 등재), 최종 사용 ${last}, 신규 발생 없음` : "legacy TYPE 0건"}`,
|
package/src/vault-log.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { mutationVault } from "./config.ts";
|
|
1
2
|
import { compileLogFilter } from "./log-filter.ts";
|
|
2
3
|
import { closeSync, constants, fstatSync, fsyncSync, ftruncateSync, lstatSync, openSync, readSync, realpathSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
|
|
3
4
|
import { join } from "node:path";
|
|
@@ -87,7 +88,7 @@ export function logBinding(vault: VaultSpec, config: VmemConfig): LogBinding {
|
|
|
87
88
|
/** True when the registered vault still equals the binding: spec, path policy and root identity. Never throws. */
|
|
88
89
|
export function matchesBinding(config: VmemConfig, id: string, binding: LogBinding): boolean {
|
|
89
90
|
const vault = config.vaults.find(v => v.id === id);
|
|
90
|
-
if (!vault || JSON.stringify(vault) !== JSON.stringify(binding.vault) || JSON.stringify(config.denyPaths ?? []) !== JSON.stringify(binding.denyPaths) || JSON.stringify(config.piiPatterns ?? []) !== JSON.stringify(binding.piiPatterns)) return false;
|
|
91
|
+
if (!vault || JSON.stringify(mutationVault(vault)) !== JSON.stringify(mutationVault(binding.vault)) || JSON.stringify(config.denyPaths ?? []) !== JSON.stringify(binding.denyPaths) || JSON.stringify(config.piiPatterns ?? []) !== JSON.stringify(binding.piiPatterns)) return false;
|
|
91
92
|
try { const identity = lstatSync(vault.path); return Number(identity.dev) === binding.dev && Number(identity.ino) === binding.ino; } catch { return false; }
|
|
92
93
|
}
|
|
93
94
|
export function appendLog(home: string, request: LogRequest, options: { env?: NodeJS.ProcessEnv; now?: Date; binding?: LogBinding } = {}): LogReceipt {
|
|
@@ -108,7 +109,7 @@ export function appendLog(home: string, request: LogRequest, options: { env?: No
|
|
|
108
109
|
const rootIdentity = lstatSync(ctx.vault.path);
|
|
109
110
|
if (options.binding) {
|
|
110
111
|
const bound = options.binding;
|
|
111
|
-
if (JSON.stringify(ctx.vault) !== JSON.stringify(bound.vault) || rootIdentity.dev !== bound.dev || rootIdentity.ino !== bound.ino || JSON.stringify(ctx.config.denyPaths ?? []) !== JSON.stringify(bound.denyPaths) || JSON.stringify(ctx.config.piiPatterns ?? []) !== JSON.stringify(bound.piiPatterns)) refuse("LOG_DRIFT", "vault identity or policy changed after mutation; log not appended");
|
|
112
|
+
if (JSON.stringify(mutationVault(ctx.vault)) !== JSON.stringify(mutationVault(bound.vault)) || rootIdentity.dev !== bound.dev || rootIdentity.ino !== bound.ino || JSON.stringify(ctx.config.denyPaths ?? []) !== JSON.stringify(bound.denyPaths) || JSON.stringify(ctx.config.piiPatterns ?? []) !== JSON.stringify(bound.piiPatterns)) refuse("LOG_DRIFT", "vault identity or policy changed after mutation; log not appended");
|
|
112
113
|
}
|
|
113
114
|
const formatted = formatLogEvent(request.event, { ...ctx, env: options.env ?? process.env, now: options.now });
|
|
114
115
|
if (!formatted.line || formatted.issues.some(issue => issue.severity === "error")) { result.issues.push(...formatted.issues); return result; }
|