@staix/vault-mem 0.5.0 → 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 +66 -0
- package/README.md +140 -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-source.ts +46 -0
- package/src/ui/inbox-worker.ts +8 -0
- package/src/ui/inbox.ts +152 -0
- package/src/ui/panel.js +26 -5
- package/src/ui/plugin.ts +42 -65
- 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/amem/seam.ts
CHANGED
|
@@ -50,19 +50,19 @@ export async function openAmem(options: AmemOptions = {}): Promise<AmemSeam> {
|
|
|
50
50
|
};
|
|
51
51
|
}
|
|
52
52
|
export interface MineAmemRecord { source: "curated" | "capture"; kind: string; at: string; text: string; project: string }
|
|
53
|
-
export interface MineAmemRead { records: MineAmemRecord[]; projects: string[]; screened: number; truncatedCapture: number; unreadable: number }
|
|
53
|
+
export interface MineAmemRead { records: MineAmemRecord[]; projects: string[]; screened: number; truncatedCapture: number; unreadable: number; malformedRecord: number }
|
|
54
54
|
const MINE_KINDS = new Set(["decision", "finding", "contract", "fail"]);
|
|
55
|
-
const MINE_EVENTS = new Set(["UserPromptSubmit", "observation", "summary"]);
|
|
55
|
+
const MINE_EVENTS = new Set(["UserPromptSubmit", "observation", "summary", "Recap", "Compact", "Record"]);
|
|
56
56
|
/**
|
|
57
57
|
* Skill mining input, read-only: curated entries (screened by amem's standalone policy plus the vault's piiPatterns) and
|
|
58
|
-
* capture rows (events UserPromptSubmit/observation/summary) of every active project, or one. Opens nothing that does not
|
|
58
|
+
* capture rows (events UserPromptSubmit/observation/summary/Recap/Compact/Record) of every active project, or one. Opens nothing that does not
|
|
59
59
|
* exist: an absent home, a capture-only shard or an unsplit home without curated logs yields no rows, never a new store.
|
|
60
60
|
*/
|
|
61
61
|
export async function readAmemForMining(options: { env?: NodeJS.ProcessEnv; project?: string; since: string; piiPatterns?: string[]; maxCaptureRows?: number }): Promise<MineAmemRead> {
|
|
62
62
|
const amem = await import("@staix/agent-mem");
|
|
63
63
|
const { existsSync } = await import("node:fs"), { basename, join } = await import("node:path");
|
|
64
64
|
const base = amem.memoryHome(options.env ?? process.env), maxRows = options.maxCaptureRows ?? 20000;
|
|
65
|
-
const out: MineAmemRead = { records: [], projects: [], screened: 0, truncatedCapture: 0, unreadable: 0 };
|
|
65
|
+
const out: MineAmemRead = { records: [], projects: [], screened: 0, truncatedCapture: 0, unreadable: 0, malformedRecord: 0 };
|
|
66
66
|
if (!existsSync(base)) return out;
|
|
67
67
|
const policy = amem.createStandalonePolicy({ ...(options.piiPatterns?.length ? { piiPatterns: [...options.piiPatterns] } : {}) });
|
|
68
68
|
const state = amem.lifecycleResolver(base);
|
|
@@ -95,8 +95,17 @@ export async function readAmemForMining(options: { env?: NodeJS.ProcessEnv; proj
|
|
|
95
95
|
capture = new amem.CaptureStore({ memoryDir: base, project: shard.key, machine: basename(dir), readOnly: true, recentReadRows: true, maxReadRows: maxRows });
|
|
96
96
|
if (capture.recentReadTruncated) out.truncatedCapture++;
|
|
97
97
|
for (const row of capture.rows({ limit: maxRows })) {
|
|
98
|
-
if (!MINE_EVENTS.has(row.event) || row.at < options.since
|
|
99
|
-
|
|
98
|
+
if (!MINE_EVENTS.has(row.event) || row.at < options.since) continue;
|
|
99
|
+
if (row.event === "Record") {
|
|
100
|
+
const parsed = amem.parseRecordLines(row.excerpt);
|
|
101
|
+
if (parsed.incomplete || !parsed.records.length || Object.keys(parsed.drops).length) { out.malformedRecord++; continue; }
|
|
102
|
+
for (const record of parsed.records) {
|
|
103
|
+
// Anchors enter the same matching, screening, masking and byte bounds as the authored text.
|
|
104
|
+
out.records.push({ source: "capture", kind: record.kind, at: row.at, text: [record.text, ...record.anchors].join("\n"), project: shard.key });
|
|
105
|
+
}
|
|
106
|
+
continue;
|
|
107
|
+
}
|
|
108
|
+
if (row.excerpt.trim()) out.records.push({ source: "capture", kind: row.event, at: row.at, text: row.excerpt, project: shard.key });
|
|
100
109
|
}
|
|
101
110
|
} catch { out.unreadable++; }
|
|
102
111
|
finally { capture?.close(); }
|
package/src/analysis-commands.ts
CHANGED
|
@@ -26,7 +26,7 @@ export function runAnalysisCommand(command: string, args: string[], home: string
|
|
|
26
26
|
if (command === "lint") {
|
|
27
27
|
if (positional.length !== 1) throw new Error("lint: requires one vault id");
|
|
28
28
|
if (flags.has("--write")) { const result = writeAnalysisReports(home,{vault:positional[0]!,kind:"lint",note:values["--note"],dryRun:flags.has("--dry-run")},env); return {text:flags.has("--json") ? JSON.stringify(result) : analysisWriteText(result,text,{kind:"lint",dryRun:flags.has("--dry-run")}),code:result.ok && (result.summary as {errors?:number}).errors === 0 ? 0 : 1}; }
|
|
29
|
-
const {snapshot} = analysisInput(home,positional[0]
|
|
29
|
+
const {snapshot} = analysisInput(home,positional[0]!,{hints:true});
|
|
30
30
|
const details = lintDetails(snapshot,values["--note"]), report = details.report;
|
|
31
31
|
return {text:flags.has("--json") ? JSON.stringify(report) : lintText(details,text,{vault:positional[0]!,note:values["--note"]}),code:report.errors ? 1 : 0};
|
|
32
32
|
}
|
package/src/analysis-input.ts
CHANGED
|
@@ -7,11 +7,23 @@ import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdir
|
|
|
7
7
|
import { dirname, join, resolve } from "node:path";
|
|
8
8
|
import { effectiveDomains, type VaultSpec, type VmemConfig } from "./config.ts";
|
|
9
9
|
import type { AnalysisSnapshot } from "./analysis-types.ts";
|
|
10
|
+
import { deadLinkScan } from "./vault-lint.ts";
|
|
11
|
+
import type { TitleSuggestion } from "./links.ts";
|
|
10
12
|
import { canonicalPath, isDenied } from "./platform.ts";
|
|
11
13
|
import { loadRegistry } from "./registry.ts";
|
|
12
14
|
import { VaultIndex } from "./vault-index.ts";
|
|
15
|
+
/** Largest auxiliary input one read takes, and the default bound of `analysisRead` and `analysisReadWithSize`. */
|
|
16
|
+
export const MAX_AUX_BYTES = 2 * 1024 * 1024;
|
|
13
17
|
/** Read bounded auxiliary inputs without following links. Never read note files here. */
|
|
14
|
-
export function analysisRead(file: string, maximum =
|
|
18
|
+
export function analysisRead(file: string, maximum = MAX_AUX_BYTES): string | null {
|
|
19
|
+
return analysisReadWithSize(file, maximum)?.text ?? null;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* The same bounded read, also reporting the byte size the file has on disk. `text` decodes lossily: an invalid byte
|
|
23
|
+
* becomes U+FFFD, so a byte count taken from the string overstates a file that is not UTF-8. Anything counting bytes
|
|
24
|
+
* of a file must use `bytes`. A file larger than `maximum` is refused from its fstat size, before any of it is read.
|
|
25
|
+
*/
|
|
26
|
+
export function analysisReadWithSize(file: string, maximum = MAX_AUX_BYTES): { text: string; bytes: number } | null {
|
|
15
27
|
let fd: number;
|
|
16
28
|
try {
|
|
17
29
|
if (realpathSync(dirname(file)) !== dirname(file)) throw new Error("analysis: linked input directory");
|
|
@@ -25,13 +37,13 @@ export function analysisRead(file: string, maximum = 2 * 1024 * 1024): string |
|
|
|
25
37
|
while (size < bytes.length) { const n = readSync(fd, bytes, size, bytes.length-size, null); size += n; if (!n) break; }
|
|
26
38
|
const after = fstatSync(fd);
|
|
27
39
|
if (size !== before.size || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error("analysis: input changed during read");
|
|
28
|
-
return bytes.subarray(0,size).toString("utf8");
|
|
40
|
+
return { text: bytes.subarray(0,size).toString("utf8"), bytes: size };
|
|
29
41
|
} finally { closeSync(fd); }
|
|
30
42
|
}
|
|
31
43
|
function permitted(file: string, config: VmemConfig): void {
|
|
32
44
|
if (isDenied(canonicalPath(file), config.denyPaths ?? [])) throw new Error("analysis: input path is denied");
|
|
33
45
|
}
|
|
34
|
-
export function analysisInput(home: string, id: string, options: { today?: string; memory?: boolean; expectedVault?: VaultSpec } = {}): { snapshot: AnalysisSnapshot; vault: VaultSpec; config: VmemConfig; identity: {dev:number;ino:number} } {
|
|
46
|
+
export function analysisInput(home: string, id: string, options: { today?: string; memory?: boolean; expectedVault?: VaultSpec; hints?: boolean } = {}): { snapshot: AnalysisSnapshot; vault: VaultSpec; config: VmemConfig; identity: {dev:number;ino:number} } {
|
|
35
47
|
const config = loadRegistry(home), vault = config.vaults.find(v => v.id === id);
|
|
36
48
|
if (!vault) throw new Error("analysis: unknown vault id");
|
|
37
49
|
if (options.expectedVault && JSON.stringify(options.expectedVault) !== JSON.stringify(vault)) throw new Error("analysis: startup vault binding changed; restart MCP");
|
|
@@ -78,6 +90,15 @@ export function analysisInput(home: string, id: string, options: { today?: strin
|
|
|
78
90
|
if(found.length)warnings[note.path]=found;
|
|
79
91
|
}catch{ /* Invalid frontmatter remains visible to L02; do not infer missing source paths. */ }
|
|
80
92
|
if(Object.keys(warnings).length)snapshot.sourceWarnings=warnings;
|
|
93
|
+
if(options.hints){
|
|
94
|
+
// A null prototype keeps the link text `__proto__` a stored key: on a plain object it would set the prototype,
|
|
95
|
+
// drop the hint and leave the object answering inherited members.
|
|
96
|
+
const hints:Record<string,TitleSuggestion>=Object.create(null),scan=deadLinkScan(snapshot.notes);
|
|
97
|
+
for(const text of scan.texts){const hint=index.suggestTitle(text);if(hint)hints[text]=hint;}
|
|
98
|
+
if(Object.keys(hints).length)snapshot.linkHints=hints;
|
|
99
|
+
// Past the bound an unlooked-up text must not read as a miss, so the snapshot carries what the pass attempted.
|
|
100
|
+
if(scan.skipped)snapshot.linkHintBound={cap:scan.cap,attempted:scan.texts,skipped:scan.skipped};
|
|
101
|
+
}
|
|
81
102
|
return {vault,config,identity:{dev:Number(identity.dev),ino:Number(identity.ino)},snapshot};
|
|
82
103
|
}
|
|
83
104
|
finally { index.close(); }
|
package/src/analysis-reports.ts
CHANGED
|
@@ -28,7 +28,7 @@ function trend(snapshot: AnalysisSnapshot, nodes: number, edges: number, communi
|
|
|
28
28
|
return lines.join("\n")+"\n";
|
|
29
29
|
}
|
|
30
30
|
export function writeAnalysisReports(home: string, request: AnalysisRequest, env: NodeJS.ProcessEnv = process.env) {
|
|
31
|
-
const {snapshot,vault,config,identity} = analysisInput(home,request.vault,{today:request.today,expectedVault:request.expectedVault});
|
|
31
|
+
const {snapshot,vault,config,identity} = analysisInput(home,request.vault,{today:request.today,expectedVault:request.expectedVault,...(request.kind === "lint" ? {hints:true} : {})});
|
|
32
32
|
if (request.workspace && request.kind !== "graph") throw new Error("workspace is only supported for graph build");
|
|
33
33
|
const work = request.workspace ? workspaceInput(snapshot,vault,config) : undefined;
|
|
34
34
|
const binding = {vault,denyPaths:config.denyPaths ?? [],piiPatterns:config.piiPatterns ?? [],dev:Number(identity.dev),ino:Number(identity.ino)};
|
package/src/analysis-types.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { TitleSuggestion } from "./links.ts";
|
|
1
2
|
/** Private provider input. Never serialize a snapshot into CLI/MCP results or public evidence. */
|
|
2
3
|
export interface AnalysisSnapshot {
|
|
3
4
|
/** Effective selected-vault domain set; standalone snapshots default to the built-ins. */
|
|
@@ -10,8 +11,19 @@ export interface AnalysisSnapshot {
|
|
|
10
11
|
reports: Record<string, string>;
|
|
11
12
|
/** Bounded auxiliary source-path existence warnings captured outside the pure lint transform. */
|
|
12
13
|
sourceWarnings?: Record<string,string[]>;
|
|
14
|
+
/**
|
|
15
|
+
* At most one title hint per dead link text, captured with an open index outside the pure lint transform.
|
|
16
|
+
* Link text is arbitrary (`__proto__` included), so a producer stores it in a null-prototype record and a reader
|
|
17
|
+
* takes own keys only; `lintVault` accepts snapshots other callers built as plain records.
|
|
18
|
+
*/
|
|
19
|
+
linkHints?: Record<string, TitleSuggestion>;
|
|
20
|
+
/**
|
|
21
|
+
* Set only when the hint pass hit its text bound: the bound, the texts it attempted and how many it left out. A dead
|
|
22
|
+
* link text outside `attempted` was never looked up, so a reader reports "not computed" and never a miss.
|
|
23
|
+
*/
|
|
24
|
+
linkHintBound?: { cap: number; attempted: readonly string[]; skipped: number };
|
|
13
25
|
}
|
|
14
|
-
export type LintCode = "L01" | "L02" | "L03" | "L09" | "L10" | "L11" | "L12" | "L13" | "L14";
|
|
26
|
+
export type LintCode = "L01" | "L02" | "L03" | "L09" | "L10" | "L11" | "L12" | "L13" | "L14" | "L15";
|
|
15
27
|
export interface LintReport {
|
|
16
28
|
findings: Record<LintCode, string[]>;
|
|
17
29
|
errors: number;
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
import { join } from "node:path";
|
|
2
|
+
import type { CanonTableSpec, VaultSpec } from "./config.ts";
|
|
3
|
+
import { parseFrontmatter } from "./frontmatter.ts";
|
|
4
|
+
import { proseLines } from "./links.ts";
|
|
5
|
+
import { canonicalPath, isDenied } from "./platform.ts";
|
|
6
|
+
import { MAX_NOTE_BYTES } from "./vault-index.ts";
|
|
7
|
+
|
|
8
|
+
export interface CanonRowMatch { path: string; line: number; key: string; row: string }
|
|
9
|
+
interface IndexedRow { path: string; line: number; row: string; keys: string[] }
|
|
10
|
+
interface KeyRow { row: number; key: string; length: number; alias: number }
|
|
11
|
+
interface Pattern { length: number; rows: KeyRow[] }
|
|
12
|
+
interface State { next: Map<string, number>; fail: number; output: number; patterns: number[] }
|
|
13
|
+
interface Automaton { states: State[]; patterns: Pattern[] }
|
|
14
|
+
export interface CanonRowIndex { readonly rows: readonly IndexedRow[]; readonly warnings: readonly string[]; readonly exact: Automaton; readonly latin: Automaton }
|
|
15
|
+
const TABLES = 16, TOTAL_BYTES = 8 * 1024 * 1024, ROWS = 20000, KEYS = 40000, KEY_BYTES = 256 * 1024;
|
|
16
|
+
const token = (character: string | undefined) => character !== undefined && /[\p{L}\p{N}\p{M}_]/u.test(character);
|
|
17
|
+
const latin = (key: string) => /\p{Script=Latin}/u.test(key);
|
|
18
|
+
const foldLatin = (value: string) => value.replace(/\p{Script=Latin}/gu, character => character.toLowerCase());
|
|
19
|
+
const state = (): State => ({ next: new Map(), fail: 0, output: 0, patterns: [] });
|
|
20
|
+
|
|
21
|
+
/** Split only actual table pipes, keeping escaped pipes, wiki aliases and code spans in their cells. */
|
|
22
|
+
function cells(line: string): string[] | undefined {
|
|
23
|
+
if (line.length > 32768 || !line.includes("|")) return undefined;
|
|
24
|
+
const result: string[] = []; let cell = "", wiki = false, code = 0, pipes = 0;
|
|
25
|
+
for (let i = 0; i < line.length; i++) {
|
|
26
|
+
const character = line[i]!;
|
|
27
|
+
if (character === "\\" && i + 1 < line.length) { cell += line[++i]!; continue; }
|
|
28
|
+
if (character === "`") {
|
|
29
|
+
let end = i + 1; while (line[end] === "`") end++;
|
|
30
|
+
const size = end - i; if (!code) code = size; else if (code === size) code = 0;
|
|
31
|
+
cell += line.slice(i, end); i = end - 1; continue;
|
|
32
|
+
}
|
|
33
|
+
if (!code && line.slice(i, i + 2) === "[[") { wiki = true; cell += "[["; i++; continue; }
|
|
34
|
+
if (!code && wiki && line.slice(i, i + 2) === "]]") { wiki = false; cell += "]]"; i++; continue; }
|
|
35
|
+
if (character === "|" && !code && !wiki) { result.push(cell.trim()); cell = ""; pipes++; }
|
|
36
|
+
else cell += character;
|
|
37
|
+
if (result.length > 64) return undefined;
|
|
38
|
+
}
|
|
39
|
+
if (!pipes || wiki || code) return undefined;
|
|
40
|
+
result.push(cell.trim());
|
|
41
|
+
if (line.trimStart().startsWith("|")) result.shift();
|
|
42
|
+
if (line.trimEnd().endsWith("|") && result.at(-1) === "") result.pop();
|
|
43
|
+
return result.length ? result : undefined;
|
|
44
|
+
}
|
|
45
|
+
// One or more hyphens per cell with optional alignment colons, the GFM delimiter row; `|-|-|` is a valid table.
|
|
46
|
+
const separator = (row: string[]) => row.every(cell => /^:?-+:?$/.test(cell.trim()));
|
|
47
|
+
function aliases(cell: string): string[] {
|
|
48
|
+
if (cell.length > 2048) return [];
|
|
49
|
+
const plain = cell.replace(/\[\[([^\]]+)\]\]/g, (_, address: string) => {
|
|
50
|
+
const [target = "", label] = address.split("|");
|
|
51
|
+
const key = target.split("#")[0]!;
|
|
52
|
+
return label ? `${key} / ${label}` : key;
|
|
53
|
+
}).replace(/\*\*|`+/g, "");
|
|
54
|
+
const parts: string[] = [];
|
|
55
|
+
const base = plain.replace(/\(([^()]*)\)/g, (_, inner: string) => { parts.push(inner); return " "; });
|
|
56
|
+
const found = new Set<string>();
|
|
57
|
+
for (const part of [base, ...parts]) for (const value of part.split(/\s+\/\s+|,/)) {
|
|
58
|
+
const key = value.trim().replace(/\s+/g, " ");
|
|
59
|
+
const size = [...key].length;
|
|
60
|
+
if (size >= 2 && size <= 256 && !/[\p{Cc}]/u.test(key)) found.add(key);
|
|
61
|
+
if (found.size === 16) return [...found];
|
|
62
|
+
}
|
|
63
|
+
return [...found];
|
|
64
|
+
}
|
|
65
|
+
function tableRows(path: string, source: string, keyColumn: number, maximum: number): { rows: IndexedRow[]; tables: number } {
|
|
66
|
+
const document = parseFrontmatter(source), lines = proseLines(document.body);
|
|
67
|
+
const offset = document.frontmatter?.split("\n").length ?? 1;
|
|
68
|
+
const result: IndexedRow[] = []; let columns = 0, tables = 0;
|
|
69
|
+
for (let i = 0; i < lines.length && result.length < maximum; i++) {
|
|
70
|
+
const row = cells(lines[i]!);
|
|
71
|
+
if (!row) { columns = 0; continue; }
|
|
72
|
+
const next = cells(lines[i + 1] ?? "");
|
|
73
|
+
// A header row with a delimiter row under it is one recognizable table, whether or not it yields keyed rows.
|
|
74
|
+
if (next && next.length === row.length && separator(next)) { columns = row.length; tables++; i++; continue; }
|
|
75
|
+
if (!columns || separator(row) || keyColumn > columns || keyColumn > row.length) continue;
|
|
76
|
+
const keys = aliases(row[keyColumn - 1]!);
|
|
77
|
+
if (keys.length) result.push({ path, line: offset + i, row: [...lines[i]!.trim()].slice(0, 200).join(""), keys });
|
|
78
|
+
}
|
|
79
|
+
return { rows: result, tables };
|
|
80
|
+
}
|
|
81
|
+
function automaton(rows: readonly IndexedRow[], folded: boolean): Automaton {
|
|
82
|
+
const states = [state()], patterns: Pattern[] = [], byKey = new Map<string, number>();
|
|
83
|
+
for (const [row, entry] of rows.entries()) for (const [alias, key] of entry.keys.entries()) {
|
|
84
|
+
if (latin(key) !== folded) continue;
|
|
85
|
+
const value = folded ? foldLatin(key) : key;
|
|
86
|
+
const existing = byKey.get(value);
|
|
87
|
+
const reference = { row, key, length: [...key].length, alias };
|
|
88
|
+
if (existing !== undefined) { patterns[existing]!.rows.push(reference); continue; }
|
|
89
|
+
let at = 0;
|
|
90
|
+
for (const character of value) {
|
|
91
|
+
let next = states[at]!.next.get(character);
|
|
92
|
+
if (next === undefined) { next = states.length; states[at]!.next.set(character, next); states.push(state()); }
|
|
93
|
+
at = next;
|
|
94
|
+
}
|
|
95
|
+
const id = patterns.length; byKey.set(value, id); patterns.push({ length: [...value].length, rows: [reference] }); states[at]!.patterns.push(id);
|
|
96
|
+
}
|
|
97
|
+
const queue = [...states[0]!.next.values()];
|
|
98
|
+
for (let i = 0; i < queue.length; i++) {
|
|
99
|
+
const at = queue[i]!;
|
|
100
|
+
for (const [character, next] of states[at]!.next) {
|
|
101
|
+
let fallback = states[at]!.fail;
|
|
102
|
+
while (fallback && !states[fallback]!.next.has(character)) fallback = states[fallback]!.fail;
|
|
103
|
+
states[next]!.fail = states[fallback]!.next.get(character) ?? 0;
|
|
104
|
+
const failed = states[next]!.fail;
|
|
105
|
+
states[next]!.output = states[failed]!.patterns.length ? failed : states[failed]!.output;
|
|
106
|
+
queue.push(next);
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
return { states, patterns };
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/** Parse bounded configured inputs only. Missing or malformed advisory tables never block promotion. */
|
|
113
|
+
export function indexCanonRows(tables: readonly CanonTableSpec[], read: (path: string, maximum: number) => string | undefined): CanonRowIndex {
|
|
114
|
+
const rows: IndexedRow[] = [], warnings = new Set<string>(); let remaining = TOTAL_BYTES, keys = 0, keyBytes = 0;
|
|
115
|
+
const warn = (path: string, cause: string) => warnings.add(`canonTables: ${path} not read (${cause}); check the configured note, permissions and denyPaths, repair the header or reduce configured tables, then retry preview`);
|
|
116
|
+
for (const table of tables.slice(0, TABLES)) {
|
|
117
|
+
if (remaining <= 0 || rows.length >= ROWS || keys >= KEYS || keyBytes >= KEY_BYTES) { warn(table.path, "aggregate read or row-index budget exhausted"); continue; }
|
|
118
|
+
const maximum = Math.min(MAX_NOTE_BYTES, remaining); let source: string | undefined;
|
|
119
|
+
try { source = read(table.path, maximum); }
|
|
120
|
+
catch (error) {
|
|
121
|
+
const code = (error as { code?: unknown })?.code;
|
|
122
|
+
warn(table.path, code === "CANON_DENIED" ? "denied by path policy" : code === "V09" ? "note exceeds remaining read budget" : code === "EACCES" || code === "EPERM" ? "permission denied" : "reader unavailable");
|
|
123
|
+
continue;
|
|
124
|
+
}
|
|
125
|
+
if (typeof source !== "string") { warn(table.path, "note missing or unavailable in the current index"); continue; }
|
|
126
|
+
const bytes = Buffer.byteLength(source); remaining -= Math.min(bytes, maximum);
|
|
127
|
+
if (bytes > maximum || !Number.isInteger(table.keyColumn ?? 1) || (table.keyColumn ?? 1) < 1) { warn(table.path, "note exceeds read budget or keyColumn is invalid"); continue; }
|
|
128
|
+
try {
|
|
129
|
+
const capacity = ROWS - rows.length, { rows: parsed, tables } = tableRows(table.path, source, table.keyColumn ?? 1, capacity);
|
|
130
|
+
// An empty result is explained rather than silent: the note was readable but holds no table GFM would accept.
|
|
131
|
+
if (!tables) warnings.add(`canonTables: ${table.path} has no recognizable Markdown table; it contributes no rows, and a table needs a header row and a separator row of one or more hyphens per cell; check the note and the configured keyColumn, then retry preview`);
|
|
132
|
+
let limited = parsed.length === capacity;
|
|
133
|
+
for (const row of parsed) {
|
|
134
|
+
const kept: string[] = [];
|
|
135
|
+
for (const key of row.keys) {
|
|
136
|
+
const size = Buffer.byteLength(key);
|
|
137
|
+
if (keys >= KEYS || keyBytes + size > KEY_BYTES) { limited = true; break; }
|
|
138
|
+
keys++; keyBytes += size; kept.push(key);
|
|
139
|
+
}
|
|
140
|
+
if (kept.length) rows.push({ ...row, keys: kept });
|
|
141
|
+
}
|
|
142
|
+
if (limited) warnings.add(`canonTables: ${table.path} index budget reached; additional rows or aliases may be omitted; split the table or reduce configured tables and retry preview`);
|
|
143
|
+
} catch { warn(table.path, "frontmatter is not parseable"); }
|
|
144
|
+
}
|
|
145
|
+
return { rows, warnings: [...warnings], exact: automaton(rows, false), latin: automaton(rows, true) };
|
|
146
|
+
}
|
|
147
|
+
function find(machine: Automaton, text: string, best: Map<number, KeyRow>): void {
|
|
148
|
+
if (!machine.patterns.length) return;
|
|
149
|
+
const input = [...text], seen = new Set<number>(); let at = 0;
|
|
150
|
+
for (let i = 0; i < input.length; i++) {
|
|
151
|
+
const character = input[i]!;
|
|
152
|
+
while (at && !machine.states[at]!.next.has(character)) at = machine.states[at]!.fail;
|
|
153
|
+
at = machine.states[at]!.next.get(character) ?? 0;
|
|
154
|
+
if (token(input[i + 1])) continue;
|
|
155
|
+
for (let output = at; output; output = machine.states[output]!.output) for (const id of machine.states[output]!.patterns) {
|
|
156
|
+
if (seen.has(id)) continue;
|
|
157
|
+
const pattern = machine.patterns[id]!, start = i + 1 - pattern.length;
|
|
158
|
+
if (token(input[start - 1]) || token(input[i + 1])) continue;
|
|
159
|
+
seen.add(id);
|
|
160
|
+
for (const row of pattern.rows) {
|
|
161
|
+
const previous = best.get(row.row);
|
|
162
|
+
if (!previous || row.length > previous.length || row.length === previous.length && row.alias < previous.alias) best.set(row.row, row);
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
if (seen.size === machine.patterns.length) return;
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
/** Whole-token matching is linear in draft length; repeated mentions do not duplicate rows. */
|
|
169
|
+
export function matchCanonRows(index: CanonRowIndex, draft: string): CanonRowMatch[] {
|
|
170
|
+
if (typeof draft !== "string" || Buffer.byteLength(draft) > MAX_NOTE_BYTES) return [];
|
|
171
|
+
const best = new Map<number, KeyRow>();
|
|
172
|
+
find(index.exact, draft, best); find(index.latin, foldLatin(draft), best);
|
|
173
|
+
const seen = new Set<string>();
|
|
174
|
+
return [...best.values()].sort((a, b) => b.length - a.length || a.row - b.row).filter(match => {
|
|
175
|
+
const row = index.rows[match.row]!, identity = JSON.stringify([row.path, row.line]);
|
|
176
|
+
if (seen.has(identity)) return false;
|
|
177
|
+
seen.add(identity); return true;
|
|
178
|
+
}).slice(0, 5).map(match => {
|
|
179
|
+
const row = index.rows[match.row]!; return { path: row.path, line: row.line, key: match.key, row: row.row };
|
|
180
|
+
});
|
|
181
|
+
}
|
|
182
|
+
/** Reuse an already-open vault index; never rescan or read an arbitrary filesystem path. */
|
|
183
|
+
export function canonRowsForVault(index: { noteSource(path: string, maxBytes: number): string | undefined }, vault: VaultSpec, denyPaths: readonly string[]): CanonRowIndex {
|
|
184
|
+
const denied = [...denyPaths];
|
|
185
|
+
return indexCanonRows(vault.canonTables ?? [], (path, maximum) => {
|
|
186
|
+
const file = join(vault.path, path);
|
|
187
|
+
if (isDenied(file, denied) || isDenied(canonicalPath(file), denied)) throw Object.assign(new Error("canonical table denied"), { code: "CANON_DENIED" });
|
|
188
|
+
return index.noteSource(path, maximum);
|
|
189
|
+
});
|
|
190
|
+
}
|
package/src/cli-output.ts
CHANGED
|
@@ -8,6 +8,7 @@ import type { PiiMatrix, PiiRow } from "./pii.ts";
|
|
|
8
8
|
import { effectivePii, type RecoveryReport } from "./registry.ts";
|
|
9
9
|
import type { SetupReport } from "./setup.ts";
|
|
10
10
|
import { blocks, clean, fields, heading, issueTable, nextCommand, paint, paragraph, plural, shellWord, table, tone, type CellInput, type TextOptions } from "./text-output.ts";
|
|
11
|
+
import { MAX_RATIO_NOTES } from "./vault-index.ts";
|
|
11
12
|
import type { VaultStats } from "./vault-stats.ts";
|
|
12
13
|
|
|
13
14
|
type Check = { ok: boolean; issue?: string };
|
|
@@ -58,11 +59,24 @@ export function renderDoctor(r: StatusResult, o: TextOptions): string {
|
|
|
58
59
|
|
|
59
60
|
export function renderStats(r: VaultStats, o: TextOptions): string {
|
|
60
61
|
const counts = (record: Record<string, number>) => fields(Object.entries(record).sort(([a, x], [b, y]) => y - x || a.localeCompare(b)), o);
|
|
61
|
-
const block = (name: string, body: string) => body ? `${heading(name, o)}\n${body}` : undefined;
|
|
62
|
+
const block = (name: string, body: string | undefined) => body ? `${heading(name, o)}\n${body}` : undefined;
|
|
63
|
+
const size = r.size.total, ratio = r.ratio;
|
|
64
|
+
const notFile = ratio.skippedNonFile ? `, ${ratio.skippedNonFile} not a file` : "";
|
|
65
|
+
// No ratio can be printed either because nothing was readable or because every readable source was empty.
|
|
66
|
+
const noRatio = ratio.sources ? "no cited source had a nonzero size" : "no note cites a readable workspace file";
|
|
67
|
+
const ratioBody = ratio.notes
|
|
68
|
+
? fields([["notes", plural(ratio.notes, "note")], ["sources", plural(ratio.sources, "file")], ["median", ratio.median ?? ""], ["p90", ratio.p90 ?? ""],
|
|
69
|
+
["over 1", plural(ratio.overOne, "note")], ["skipped", `${plural(ratio.skipped, "source reference")}${notFile}`],
|
|
70
|
+
["empty", ratio.emptySourceNotes ? `${plural(ratio.emptySourceNotes, "note")} with only empty sources` : ""],
|
|
71
|
+
["truncated", ratio.truncatedNotes ? `${plural(ratio.truncatedNotes, "note")} past the ${MAX_RATIO_NOTES}-note cap` : ""],
|
|
72
|
+
["largest", ratio.largest.map(entry => `${entry.path} ${entry.ratio}`).join("; ")]], o)
|
|
73
|
+
: paragraph(`${noRatio}${ratio.skipped ? `; ${plural(ratio.skipped, "source reference")} skipped` : ""}${ratio.emptySourceNotes ? `; ${plural(ratio.emptySourceNotes, "note")} with only empty sources` : ""}${ratio.truncatedNotes ? `; ${plural(ratio.truncatedNotes, "note")} past the ${MAX_RATIO_NOTES}-note cap` : ""}`, o);
|
|
62
74
|
const log = r.log.total === null ? paragraph("unreadable; see the issues below", o, "fail", " ")
|
|
63
75
|
: fields([["total", r.log.total], ...Object.entries(r.log.byType ?? {}).filter(([, n]) => n > 0).sort(([a, x], [b, y]) => y - x || a.localeCompare(b))], o);
|
|
64
76
|
return blocks(`${heading(r.vault, o)} ${plural(r.notes.total, "note")} as of ${r.asOf}`,
|
|
65
77
|
block("Notes by type", counts(r.notes.byType)), block("Notes by domain", counts(r.notes.byDomain)), block("Notes by status", counts(r.notes.byStatus)),
|
|
78
|
+
block("Note size", size.notes ? fields([["total", `${plural(size.bytes, "byte")}, ${plural(size.words, "word")}`]], o) : undefined),
|
|
79
|
+
block("Note-to-source ratio", ratioBody),
|
|
66
80
|
block("Modified", fields([["last 7 days", r.modified.last7Days], ["last 30 days", r.modified.last30Days]], o)),
|
|
67
81
|
block(`Log since ${r.log.since} (${plural(r.log.days, "day")})`, log),
|
|
68
82
|
r.log.warnings.map(w => paragraph(`warning: ${w}`, o, "warn")).join("\n"), issueTable(r.log.issues, o));
|
package/src/cli.ts
CHANGED
|
@@ -212,7 +212,7 @@ export async function runMcp(env: NodeJS.ProcessEnv = process.env): Promise<void
|
|
|
212
212
|
import("./promote.ts"), import("./org-promote.ts"), import("./skills-mine.ts"), import("./amem/seam.ts")]);
|
|
213
213
|
await seam.preloadAmem();
|
|
214
214
|
const server = createVaultMcp(resolveHome(env).home, env);
|
|
215
|
-
await serveMcp({ tools: server.tools, handlers: server.handlers, name: "vmem", version });
|
|
215
|
+
await serveMcp({ tools: server.tools, handlers: server.handlers, name: "vmem", version, instructions: server.instructions });
|
|
216
216
|
}
|
|
217
217
|
/** Async commands. Only `promote-from-amem` and `skills mine` load the agent-mem seam, and only when they run. */
|
|
218
218
|
export async function runAsync(argv: string[], env: NodeJS.ProcessEnv = process.env, io: { stdinIsTTY?: boolean; stdout?: Stdout } = {}): Promise<{ text: string; code: number }> {
|
package/src/commands-table.ts
CHANGED
|
@@ -7,12 +7,15 @@ const SPEC_HELP: Record<SpecCommand, string> = {
|
|
|
7
7
|
graph: "read a bounded slice of the spec graph",
|
|
8
8
|
grep: "search specs by terms or literal text with metadata filters",
|
|
9
9
|
validate: "validate specs and report errors, warnings and freshness",
|
|
10
|
+
update: "update spec frontmatter with validation, policy and expected SHA guards",
|
|
11
|
+
create: "create a screened, validated spec with ordered metadata and type headings",
|
|
12
|
+
delete: "preview backlinks and children, then confirm a spec deletion with its fingerprint",
|
|
10
13
|
};
|
|
11
14
|
/** Help sections in print order; every COMMANDS entry names one. */
|
|
12
15
|
export const HELP_SECTIONS = ["Registry", "Read", "Write", "Log", "Analysis", "Promotion and sync", "Design specs", "Setup"] as const;
|
|
13
16
|
interface CommandEntry { name: string; usage: string; mutates: boolean | string; section: typeof HELP_SECTIONS[number]; description: string }
|
|
14
17
|
export const COMMANDS = [
|
|
15
|
-
...SPEC_COMMANDS.map(item => ({ name: `spec ${item.command}`, usage: item.usage, mutates:
|
|
18
|
+
...SPEC_COMMANDS.map(item => ({ name: `spec ${item.command}`, usage: item.usage, mutates: ["create", "update", "delete"].includes(item.command), section: "Design specs" as const, description: SPEC_HELP[item.command] })),
|
|
16
19
|
{ name: "lint", usage: "lint <vault> [--note PATH] [--write] [--dry-run] [--json]", mutates: "write", section: "Analysis", description: "lint links, schema, filenames and the log; --write saves a screened report" },
|
|
17
20
|
{ name: "graph build", usage: "graph build <vault> [--workspace] [--dry-run] [--json]", mutates: true, section: "Analysis", description: "build the vault graph, or the workspace graph with --workspace, under reports/" },
|
|
18
21
|
{ name: "graph neighbors", usage: "graph neighbors <vault> <stem> [--hops 1..2] [--limit 1..500] [--relation REL] [--json]", mutates: false, section: "Analysis", description: "read a note's graph neighborhood up to two hops, optionally over one link relation" },
|
|
@@ -37,6 +40,7 @@ export const COMMANDS = [
|
|
|
37
40
|
{ name: "frontmatter", usage: "frontmatter <vault> <note> [--set JSON] [--unset key,key] [--expected-sha SHA] [--log JSON] [--dry-run] [--json]", mutates: true, section: "Write", description: "set or unset frontmatter keys of a note" },
|
|
38
41
|
{ name: "link", usage: "link <vault> <from> <to> --relation R [--context TEXT] [--one-way] [--log JSON] [--dry-run] [--json]", mutates: true, section: "Write", description: "add a typed link between two notes, both ways unless --one-way" },
|
|
39
42
|
{ name: "supersede", usage: "supersede <vault> <old> <next> [--log JSON] [--dry-run] [--json]", mutates: true, section: "Write", description: "mark a note superseded by a newer one and link them" },
|
|
43
|
+
{ name: "merge", usage: "merge <vault> <keep> <absorb> [--confirm --fingerprint SHA] [--log JSON] [--dry-run] [--json]", mutates: "confirm", section: "Write", description: "preview merged content and inbound links, then confirm to merge notes and supersede the absorbed note" },
|
|
40
44
|
{ name: "move", usage: "move <vault> <from> <to> [--confirm --fingerprint SHA] [--log JSON] [--dry-run] [--json]", mutates: "confirm", section: "Write", description: "preview, then confirm with the fingerprint, a note move that rewrites links" },
|
|
41
45
|
{ name: "delete", usage: "delete <vault> <note> [--confirm --fingerprint SHA] [--log JSON] [--dry-run] [--json]", mutates: "confirm", section: "Write", description: "preview backlinks, then confirm with the fingerprint, a note deletion" },
|
|
42
46
|
{ name: "tidy", usage: "tidy <vault> [--connections] [--escapes] [--enums] [--keys] [--sources] [--topics] [--secrets] [--log] [--all] [--map file] [--confirm --fingerprint SHA] [--dry-run] [--json]", mutates: "confirm", section: "Write", description: "preview, then confirm with the fingerprint, migration tidy of notes and the log" },
|
|
@@ -52,7 +56,7 @@ export const COMMANDS = [
|
|
|
52
56
|
{ name: "setup", usage: "setup <claude|codex|kimi|pi|qwen|jcode|agy|all> [--root PATH] [--apply|--undo] [--json]", mutates: "apply", section: "Setup", description: "preview, apply or undo the vmem MCP entry in agent hosts" },
|
|
53
57
|
{ name: "manifest", usage: "manifest [--json]", mutates: false, section: "Setup", description: "print the package version, MCP tools and command names" },
|
|
54
58
|
{ name: "completion", usage: "completion <bash|zsh|fish>", mutates: false, section: "Setup", description: "print a shell completion script built from this table" },
|
|
55
|
-
{ name: "stats", usage: "stats <vault> [--days 1..3650] [--json]", mutates: false, section: "Read", description: "count notes by type, domain and status, recent edits and log events" },
|
|
59
|
+
{ name: "stats", usage: "stats <vault> [--days 1..3650] [--json]", mutates: false, section: "Read", description: "count notes by type, domain and status, note size and note-to-source ratio, recent edits and log events" },
|
|
56
60
|
] as const satisfies readonly CommandEntry[];
|
|
57
61
|
const RELATIONS = ["supports", "contradicts", "extends", "applies-to", "context-for"] as const;
|
|
58
62
|
const LOG_EVENT_TYPES = ["INGEST", "ROUTE", "EXTRACT", "CONNECT", "DIGEST", "LEARN", "LINT", "TASK", "GRAPH", "SYNC", "RETHINK", "SOURCE"] as const;
|
package/src/config.ts
CHANGED
|
@@ -3,6 +3,8 @@ import { isAbsolute, join } from "node:path";
|
|
|
3
3
|
|
|
4
4
|
export const CONFIG_FILE = "vmem.config.json";
|
|
5
5
|
export const MAX_CONFIG_BYTES = 64 * 1024;
|
|
6
|
+
/** A flat note table; keyColumn is 1-based and bounded to 1..64. */
|
|
7
|
+
export interface CanonTableSpec { path: string; keyColumn?: number }
|
|
6
8
|
export interface VaultSpec {
|
|
7
9
|
id: string;
|
|
8
10
|
path: string;
|
|
@@ -12,6 +14,12 @@ export interface VaultSpec {
|
|
|
12
14
|
remote?: string;
|
|
13
15
|
registry?: string;
|
|
14
16
|
domains?: string[];
|
|
17
|
+
canonTables?: CanonTableSpec[];
|
|
18
|
+
}
|
|
19
|
+
/** Advisory canonical tables do not participate in mutation identity or policy. */
|
|
20
|
+
export function mutationVault(vault: VaultSpec): Omit<VaultSpec, "canonTables"> {
|
|
21
|
+
const { canonTables: _, ...mutation } = vault;
|
|
22
|
+
return mutation;
|
|
15
23
|
}
|
|
16
24
|
/** Canonical built-ins; vault declarations add ids without replacing these. */
|
|
17
25
|
export const BUILTIN_DOMAINS: readonly string[] = Object.freeze(["research", "projects", "teaching", "operations", "people", "ai-practice"]);
|
|
@@ -36,9 +44,9 @@ export interface PiiSpec { email?: PiiCell; phone?: PiiCell; custom?: PiiCell; p
|
|
|
36
44
|
* The config format this build writes. A build that adds a key bumps it. A config whose `version` is newer
|
|
37
45
|
* than this build is read tolerantly: unknown keys are kept as they are and written back unchanged, so an
|
|
38
46
|
* older vmem can share a config with a newer one. At or below this version unknown keys stay errors (typos).
|
|
39
|
-
* An absent `version` means 1. Registry writes add format 2
|
|
47
|
+
* An absent `version` means 1. Registry writes add format 2 for `specs`, 3 for vault `domains`, and 4 for vault `canonTables`; otherwise they keep the existing version field.
|
|
40
48
|
*/
|
|
41
|
-
export const CONFIG_VERSION =
|
|
49
|
+
export const CONFIG_VERSION = 4;
|
|
42
50
|
export interface SpecSourceSpec { id: string; path: string; write: "mcp" | "cli" | "none"; pii: "allow" | "deny" }
|
|
43
51
|
export interface VmemConfig { version?: number; home?: string; vaults: VaultSpec[]; specs?: SpecSourceSpec[]; denyPaths?: string[]; piiPatterns?: string[] }
|
|
44
52
|
const controls = /[\x00-\x1f\x7f]/;
|
|
@@ -127,8 +135,27 @@ export function unenforceablePii(vault: VaultSpec): string | undefined {
|
|
|
127
135
|
const members = piiExtensions(vault.pii);
|
|
128
136
|
return members.length ? `vault ${vault.id}: PII policy has members this vmem cannot enforce (${members.slice(0, 8).join(", ")}); write with the newer vmem that wrote the policy` : undefined;
|
|
129
137
|
}
|
|
138
|
+
function parseCanonTables(value: unknown, tolerant: boolean): CanonTableSpec[] {
|
|
139
|
+
try {
|
|
140
|
+
if (!Array.isArray(value) || value.length > 16) throw new Error("vault.canonTables: expected at most 16 table entries");
|
|
141
|
+
const seen = new Set<string>();
|
|
142
|
+
return value.map(item => {
|
|
143
|
+
const keys = ["path", "keyColumn"], raw = object(item, keys, "vault.canonTables entry", tolerant);
|
|
144
|
+
const path = raw.path;
|
|
145
|
+
if (typeof path !== "string" || Buffer.byteLength(path) > 256 || !/^notes\/[^/]+\.md$/.test(path) || path.slice(6).startsWith(".") || path.includes("\\") || /[\p{Cc}]/u.test(path)) throw new Error("vault.canonTables.path: expected a literal flat notes/<name>.md path of at most 256 bytes without traversal, dot paths, backslashes or control characters");
|
|
146
|
+
const keyColumn = raw.keyColumn;
|
|
147
|
+
if (keyColumn !== undefined && (typeof keyColumn !== "number" || !Number.isInteger(keyColumn) || keyColumn < 1 || keyColumn > 64)) throw new Error("vault.canonTables.keyColumn: expected a 1-based integer column from 1 to 64");
|
|
148
|
+
const identity = JSON.stringify([path, keyColumn ?? 1]);
|
|
149
|
+
if (seen.has(identity)) throw new Error("vault.canonTables: duplicate path and key column; keep one entry per path and key column");
|
|
150
|
+
seen.add(identity);
|
|
151
|
+
return { ...unknown(raw, keys, tolerant), path, ...(keyColumn !== undefined ? { keyColumn } : {}) };
|
|
152
|
+
});
|
|
153
|
+
} catch (error) {
|
|
154
|
+
throw new Error(`${error instanceof Error ? error.message : "vault.canonTables: invalid table entries"}; fix canonTables in vmem.config.json`);
|
|
155
|
+
}
|
|
156
|
+
}
|
|
130
157
|
export function parseVault(value: unknown, tolerant = false): VaultSpec {
|
|
131
|
-
const keys = ["id", "path", "kind", "write", "pii", "remote", "registry", "domains"], v = object(value, keys, "vault", tolerant);
|
|
158
|
+
const keys = ["id", "path", "kind", "write", "pii", "remote", "registry", "domains", "canonTables"], v = object(value, keys, "vault", tolerant);
|
|
132
159
|
const id = string(v.id, "vault.id");
|
|
133
160
|
if (!/^[a-z][a-z0-9-]{0,31}$/.test(id)) throw new Error("vault.id: invalid id");
|
|
134
161
|
if (v.kind !== "personal" && v.kind !== "org") throw new Error("vault.kind: expected personal or org");
|
|
@@ -143,6 +170,7 @@ export function parseVault(value: unknown, tolerant = false): VaultSpec {
|
|
|
143
170
|
}
|
|
144
171
|
result.domains = [...v.domains];
|
|
145
172
|
}
|
|
173
|
+
if (v.canonTables !== undefined) result.canonTables = parseCanonTables(v.canonTables, tolerant);
|
|
146
174
|
return result;
|
|
147
175
|
}
|
|
148
176
|
/** Spec sources have their own registry shape; they are not vaults. */
|
package/src/frontmatter.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { isDeepStrictEqual } from "node:util";
|
|
2
|
-
import { parseYamlWithQuotedEscapes } from "./yaml-quoted.ts";
|
|
2
|
+
import { parseYamlWithQuotedEscapes, type YamlReference } from "./yaml-quoted.ts";
|
|
3
3
|
|
|
4
4
|
interface FieldSpan { key: string; start: number; end: number }
|
|
5
5
|
export interface FrontmatterDocument {
|
|
@@ -9,6 +9,12 @@ export interface FrontmatterDocument {
|
|
|
9
9
|
/** Original delimiters and YAML, including their original line endings. */
|
|
10
10
|
readonly frontmatter: string | null;
|
|
11
11
|
}
|
|
12
|
+
const referenceGraphs = new WeakMap<FrontmatterDocument, readonly YamlReference[]>();
|
|
13
|
+
/** Actual header reference tokens and their prior anchor bindings, excluding scalar/comment text. */
|
|
14
|
+
export function frontmatterReferences(document: FrontmatterDocument): readonly YamlReference[] {
|
|
15
|
+
if (document.frontmatter === null) return [];
|
|
16
|
+
return referenceGraphs.get(document) ?? referenceGraphs.get(parseFrontmatter(document.source)) ?? [];
|
|
17
|
+
}
|
|
12
18
|
interface ParsedDocument extends FrontmatterDocument {
|
|
13
19
|
start: number;
|
|
14
20
|
end: number;
|
|
@@ -99,8 +105,8 @@ export function parseFrontmatter(source: string): FrontmatterDocument {
|
|
|
99
105
|
const match = closing.exec(source);
|
|
100
106
|
if (!match) throw new Error("frontmatter: missing closing delimiter");
|
|
101
107
|
const yaml = source.slice(start, match.index);
|
|
102
|
-
let value: unknown;
|
|
103
|
-
try { value = parseYamlWithQuotedEscapes(yaml); }
|
|
108
|
+
let value: unknown; const references: YamlReference[] = [];
|
|
109
|
+
try { value = parseYamlWithQuotedEscapes(yaml, references); }
|
|
104
110
|
catch { throw new Error("frontmatter: invalid YAML"); }
|
|
105
111
|
if (value === null || value === undefined) value = {};
|
|
106
112
|
if (!mapping(value)) throw new Error("frontmatter: expected mapping");
|
|
@@ -109,6 +115,7 @@ export function parseFrontmatter(source: string): FrontmatterDocument {
|
|
|
109
115
|
source, body: source.slice(end), data: value, frontmatter: source.slice(0, end),
|
|
110
116
|
start, end: match.index, newline: opening[0].endsWith("\r\n") ? "\r\n" : "\n", fields: fieldSpans(yaml),
|
|
111
117
|
};
|
|
118
|
+
referenceGraphs.set(document, references);
|
|
112
119
|
return document;
|
|
113
120
|
}
|
|
114
121
|
|
package/src/links.ts
CHANGED
|
@@ -15,6 +15,16 @@ export interface ResolvedLink extends Link {
|
|
|
15
15
|
resolved: string | null;
|
|
16
16
|
reason: "missing-note" | "ambiguous-note" | "missing-heading" | "missing-block" | null;
|
|
17
17
|
}
|
|
18
|
+
/**
|
|
19
|
+
* The one existing note a dead link most likely meant, from the title search. A hint only: nothing rewrites the
|
|
20
|
+
* link, and `score` is the positive title bm25, so a larger value is a closer title.
|
|
21
|
+
*/
|
|
22
|
+
export interface TitleSuggestion { path: string; title: string; score: number }
|
|
23
|
+
/**
|
|
24
|
+
* A link as a reader is told about it: a dead one carries the one title hint it was offered, and a text past the hint
|
|
25
|
+
* bound or with no matching title carries `null`. Computed from the link's raw text, never its reported target.
|
|
26
|
+
*/
|
|
27
|
+
export type SuggestedLink = ResolvedLink & { suggested?: TitleSuggestion | null };
|
|
18
28
|
export function normalizeTarget(value: string): string { return value.normalize("NFC").toLowerCase(); }
|
|
19
29
|
/** Preserve line positions while hiding fenced code, including unclosed fences. */
|
|
20
30
|
export function proseLines(body: string): string[] {
|
|
@@ -62,6 +72,8 @@ function maskInlineCode(body: string): string {
|
|
|
62
72
|
parts.push(body.slice(offset));
|
|
63
73
|
return parts.join("");
|
|
64
74
|
}
|
|
75
|
+
/** Visible Markdown lines for structural edits; hide fences and matched multiline inline code. */
|
|
76
|
+
export function visibleProseLines(body: string): string[] { return maskInlineCode(proseLines(body).join("\n")).split("\n"); }
|
|
65
77
|
export function extractLinks(body: string): Link[] {
|
|
66
78
|
const links: Link[] = [];
|
|
67
79
|
for (const [index, line] of maskInlineCode(proseLines(body).join("\n")).split("\n").entries()) {
|
|
@@ -100,7 +112,7 @@ export function rewriteLinkTargets(body: string, replace: (target: string) => st
|
|
|
100
112
|
export function noteKey(value: string): string {
|
|
101
113
|
return normalizeTarget(value.replace(/^\.\//, "").replace(/^notes\//i, "").replace(/\.md$/i, ""));
|
|
102
114
|
}
|
|
103
|
-
function anchorIndex(body: string): { headings: Set<string>; blocks: Set<string> } {
|
|
115
|
+
export function anchorIndex(body: string): { headings: Set<string>; blocks: Set<string> } {
|
|
104
116
|
const lines = proseLines(body), headings = new Set<string>(), blocks = new Set<string>();
|
|
105
117
|
for (let i = 0; i < lines.length; i++) {
|
|
106
118
|
const line = lines[i]!, atx = /^ {0,3}#{1,6}([ \t]+.*|)$/.exec(line);
|