@staix/vault-mem 0.3.2 → 0.4.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 +24 -0
- package/README.md +67 -15
- package/package.json +1 -1
- package/src/cli.ts +20 -4
- package/src/commands-table.ts +15 -12
- package/src/index.ts +6 -1
- package/src/log-format.ts +3 -0
- package/src/log-types.ts +5 -1
- package/src/mcp-spec.ts +68 -0
- package/src/mcp-vault.ts +27 -12
- package/src/spec-command-table.ts +15 -0
- package/src/spec-commands.ts +174 -0
- package/src/spec-freshness.ts +163 -0
- package/src/spec-git.ts +33 -0
- package/src/spec-graph.ts +19 -8
- package/src/spec-source.ts +53 -32
- package/src/spec-validate.ts +241 -0
- package/src/vault-files.ts +74 -0
- package/src/vault-index.ts +156 -38
- package/src/vault-log.ts +12 -1
- package/src/vault-stats.ts +50 -0
- package/src/write-commands.ts +27 -6
- package/src/write-operations.ts +23 -6
- package/src/write-types.ts +3 -1
- package/src/writer.ts +19 -7
package/src/spec-source.ts
CHANGED
|
@@ -1,31 +1,34 @@
|
|
|
1
|
-
import { spawnSync } from "node:child_process";
|
|
2
1
|
import { lstatSync } from "node:fs";
|
|
3
2
|
import { tmpdir } from "node:os";
|
|
4
|
-
import { isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
3
|
+
import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
5
4
|
import { absolute, type SpecSourceSpec } from "./config.ts";
|
|
6
|
-
import { realPath
|
|
5
|
+
import { realPath } from "./platform.ts";
|
|
6
|
+
import { specGit } from "./spec-git.ts";
|
|
7
|
+
import { parseFrontmatter } from "./frontmatter.ts";
|
|
7
8
|
import { VaultIndex, IndexCacheError, type IndexSourceAdapter, type SearchOptions, type SearchResult } from "./vault-index.ts";
|
|
8
9
|
|
|
9
10
|
/** Private spec input snapshot; raw sources are for library transforms, never graph results. */
|
|
10
|
-
export interface
|
|
11
|
-
id: string;
|
|
11
|
+
export interface SpecCandidate {
|
|
12
12
|
path: string;
|
|
13
13
|
hash: string;
|
|
14
14
|
source: string;
|
|
15
15
|
frontmatter: Record<string, unknown>;
|
|
16
16
|
body: string;
|
|
17
17
|
}
|
|
18
|
+
export interface SpecDocument extends SpecCandidate { id: string }
|
|
18
19
|
export interface SpecDiagnostic {
|
|
19
|
-
code: "duplicate_id" | "invalid_frontmatter" | "invalid_identity" | "skipped_path";
|
|
20
|
+
code: "duplicate_id" | "invalid_frontmatter" | "invalid_identity" | "skipped_path" | "wrong_shape";
|
|
20
21
|
path: string;
|
|
21
22
|
id?: string;
|
|
22
23
|
firstPath?: string;
|
|
24
|
+
field?: string;
|
|
23
25
|
message: string;
|
|
24
26
|
}
|
|
25
27
|
export interface SpecSnapshot {
|
|
26
28
|
root: string;
|
|
27
29
|
commonDir: string;
|
|
28
30
|
specs: SpecDocument[];
|
|
31
|
+
candidates?: SpecCandidate[];
|
|
29
32
|
diagnostics: SpecDiagnostic[];
|
|
30
33
|
}
|
|
31
34
|
|
|
@@ -36,22 +39,7 @@ interface Binding { root: string; registeredRoot: string; commonDir: string; roo
|
|
|
36
39
|
const compare = (a: string, b: string) => a < b ? -1 : a > b ? 1 : 0;
|
|
37
40
|
const pathOrder = (a: string, b: string) => compare(a.normalize("NFC"), b.normalize("NFC")) || compare(a, b);
|
|
38
41
|
function git(root: string, args: string[], env: NodeJS.ProcessEnv, maxBuffer = 65536): Buffer {
|
|
39
|
-
|
|
40
|
-
const result = spawnSync(argv[0]!, argv.slice(1), { env: memoryGitEnv({ ...env, GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" }, { repositoryIsolation: true }), timeout: 10000, maxBuffer, stdio: ["ignore", "pipe", "pipe"] });
|
|
41
|
-
if (result.error) {
|
|
42
|
-
const code = (result.error as NodeJS.ErrnoException).code;
|
|
43
|
-
if (code === "ETIMEDOUT") throw new Error("spec source: git inspection timed out after 10000 ms; retry and check for a locked repository or slow mount", { cause: result.error });
|
|
44
|
-
if (code === "ENOBUFS") {
|
|
45
|
-
const advice = args[0] === "ls-files" ? "ignore large or vendored Markdown via .gitignore and untrack already-tracked excluded files with git rm --cached before retrying" : "inspect git -C <path> rev-parse --show-toplevel and repair unexpected output before retrying";
|
|
46
|
-
throw new Error(`spec source: git output exceeded ${maxBuffer} bytes; ${advice}`, { cause: result.error });
|
|
47
|
-
}
|
|
48
|
-
throw new Error(`spec source: git could not run (${code ?? "spawn failure"}); install git or fix PATH before retrying`, { cause: result.error });
|
|
49
|
-
}
|
|
50
|
-
if (result.status !== 0) {
|
|
51
|
-
const first = result.stderr.toString("utf8").split(/\r?\n/, 1)[0]?.split(root).join("<path>").slice(0, 240) || "no diagnostic";
|
|
52
|
-
throw new Error(`spec source: git refused inspection (exit ${result.status ?? "signal"}): ${first}; inspect git -C <path> rev-parse --show-toplevel and repair the repository or ownership configuration`);
|
|
53
|
-
}
|
|
54
|
-
return result.stdout;
|
|
42
|
+
return specGit(root, args, { env, maxBuffer, discovery: args[0] === "ls-files" }).stdout;
|
|
55
43
|
}
|
|
56
44
|
function rootInfo(path: string, env: NodeJS.ProcessEnv): { root: string; commonDir: string } {
|
|
57
45
|
try { absolute(path, "spec worktree"); }
|
|
@@ -73,7 +61,7 @@ function directoryIdentity(root: string): string | undefined {
|
|
|
73
61
|
}
|
|
74
62
|
function bind(source: SpecSourceSpec, options: SpecSourceOptions): Binding {
|
|
75
63
|
const env = options.env ?? process.env, registered = rootInfo(source.path, env);
|
|
76
|
-
if (registered.root !== source.path) throw new Error("spec source: registered root is no longer canonical;
|
|
64
|
+
if (registered.root !== source.path) throw new Error("spec source: registered root is no longer canonical; restore the canonical root or preview unregistering it with vmem specs remove <id>, then confirm removal before adding the new root");
|
|
77
65
|
const selected = options.worktree === undefined ? registered : rootInfo(options.worktree, env);
|
|
78
66
|
if (selected.commonDir !== registered.commonDir) throw new Error("spec source: worktree belongs to another repository; select a worktree sharing the registered repository's git common directory");
|
|
79
67
|
const rootIdentity = directoryIdentity(selected.root);
|
|
@@ -116,13 +104,28 @@ function pathProblem(binding: Binding, path: string): string | undefined {
|
|
|
116
104
|
if (physicalRelative === ".." || physicalRelative.startsWith(`..${sep}`) || isAbsolute(physicalRelative)) return `spec source ${path}: physical path leaves the registered root; restore the original root and plain in-repository file before retrying`;
|
|
117
105
|
return undefined;
|
|
118
106
|
}
|
|
107
|
+
function namedSpec(path: string): boolean { return basename(path) === "SPEC.md"; }
|
|
108
|
+
function candidateData(path: string, data: Record<string, unknown>): boolean { return namedSpec(path) || Object.hasOwn(data, "id") || Object.hasOwn(data, "type"); }
|
|
109
|
+
function candidateProbe(path: string, reason: "oversized" | "invalid_utf8", bytes: Buffer): boolean {
|
|
110
|
+
if (namedSpec(path)) return true;
|
|
111
|
+
try {
|
|
112
|
+
const document = parseFrontmatter(bytes.toString("utf8"));
|
|
113
|
+
if (!document.frontmatter) return false;
|
|
114
|
+
// This is a conservative signal only: visible reserved keys keep the blocking encoding error.
|
|
115
|
+
// Accepted documents are still decoded strictly by the scanner.
|
|
116
|
+
return candidateData(path, document.data);
|
|
117
|
+
} catch (error) {
|
|
118
|
+
if (reason === "oversized" && error instanceof Error && error.message === "frontmatter: missing closing delimiter") throw new Error(`spec source ${path}: frontmatter exceeds the bounded candidate probe; shorten the header before validating`, { cause: error });
|
|
119
|
+
return false;
|
|
120
|
+
}
|
|
121
|
+
}
|
|
119
122
|
function adapter(binding: Binding) {
|
|
120
|
-
let specs: SpecDocument[] = [], diagnostics: SpecDiagnostic[] = [];
|
|
123
|
+
let specs: SpecDocument[] = [], candidates: SpecCandidate[] = [], diagnostics: SpecDiagnostic[] = [];
|
|
121
124
|
const seen = new Map<string, string>();
|
|
122
125
|
const source: IndexSourceAdapter = {
|
|
123
126
|
validate: () => validate(binding),
|
|
124
127
|
paths: () => {
|
|
125
|
-
specs = []; diagnostics = []; seen.clear();
|
|
128
|
+
specs = []; candidates = []; diagnostics = []; seen.clear();
|
|
126
129
|
const bytes = git(binding.root, ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "*.md"], binding.env, 8 * 1024 * 1024);
|
|
127
130
|
let output: string;
|
|
128
131
|
try { output = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes); }
|
|
@@ -141,9 +144,19 @@ function adapter(binding: Binding) {
|
|
|
141
144
|
const problem = pathProblem(binding, path);
|
|
142
145
|
if (problem !== undefined) throw new Error(problem);
|
|
143
146
|
},
|
|
144
|
-
invalid: path =>
|
|
147
|
+
invalid: path => {
|
|
148
|
+
if (!namedSpec(path)) return false;
|
|
149
|
+
diagnostics.push({ code: "invalid_frontmatter", path, message: "spec source: invalid frontmatter; repair the SPEC.md YAML before validating" });
|
|
150
|
+
return true;
|
|
151
|
+
},
|
|
152
|
+
skipFile: (path, reason, bytes) => {
|
|
153
|
+
if (candidateProbe(path, reason, bytes)) return false;
|
|
154
|
+
diagnostics.push({ code: "skipped_path", path, message: `non-candidate Markdown ${path}: ${reason === "oversized" ? "file exceeds the bounded read size" : "file is not valid UTF-8"}; split/re-encode it or exclude it via .gitignore` });
|
|
155
|
+
return true;
|
|
156
|
+
},
|
|
145
157
|
accept: (path, document, hash) => {
|
|
146
158
|
const data = document.data;
|
|
159
|
+
if (candidateData(path, data)) candidates.push({ path, hash, source: document.source, frontmatter: data, body: document.body });
|
|
147
160
|
if (!Object.hasOwn(data, "id") || !Object.hasOwn(data, "type")) return false;
|
|
148
161
|
if (typeof data.id !== "string" || !data.id.trim() || typeof data.type !== "string" || !data.type.trim()) {
|
|
149
162
|
diagnostics.push({ code: "invalid_identity", path, message: "spec source: id and type must be nonempty strings; repair the frontmatter before rebuilding" });
|
|
@@ -159,7 +172,7 @@ function adapter(binding: Binding) {
|
|
|
159
172
|
return true;
|
|
160
173
|
},
|
|
161
174
|
};
|
|
162
|
-
return { source, snapshot: (): SpecSnapshot => ({ root: binding.root, commonDir: binding.commonDir, specs: [...specs], diagnostics: [...diagnostics] }) };
|
|
175
|
+
return { source, snapshot: (): SpecSnapshot => ({ root: binding.root, commonDir: binding.commonDir, specs: [...specs], candidates: [...candidates], diagnostics: [...diagnostics] }) };
|
|
163
176
|
}
|
|
164
177
|
/** Call scan() to refresh. Search and snapshots use the last completed scan, like VaultIndex. */
|
|
165
178
|
export class SpecIndex {
|
|
@@ -183,15 +196,23 @@ export class SpecIndex {
|
|
|
183
196
|
get file(): string { return this.index.file; }
|
|
184
197
|
close(): void { this.index.close(); }
|
|
185
198
|
scan(rebuild = false): ReturnType<VaultIndex["scan"]> {
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
199
|
+
try {
|
|
200
|
+
const result = this.index.scan(rebuild);
|
|
201
|
+
this.current = this.adapter.snapshot();
|
|
202
|
+
return result;
|
|
203
|
+
} catch (error) { this.current = undefined; throw error; }
|
|
189
204
|
}
|
|
190
205
|
snapshot(): SpecSnapshot { if (!this.current) this.scan(); return this.current!; }
|
|
191
|
-
search(query: string, options: SearchOptions = {}): SpecSearchResult[] {
|
|
206
|
+
search(query: string, options: SearchOptions & { offset?: number } = {}): SpecSearchResult[] {
|
|
207
|
+
if (options.offset !== undefined && (!Number.isSafeInteger(options.offset) || options.offset < 0 || options.offset > 10000)) throw new Error("spec search offset: expected integer 0..10000; choose a bounded continuation offset");
|
|
208
|
+
return this.searchRows(query, options, false);
|
|
209
|
+
}
|
|
210
|
+
/** One bounded query materializes the matching snapshot before callers filter or page it. */
|
|
211
|
+
searchAll(query: string): SpecSearchResult[] { return this.searchRows(query, {}, true); }
|
|
212
|
+
private searchRows(query: string, options: SearchOptions & { offset?: number }, all: boolean): SpecSearchResult[] {
|
|
192
213
|
const snapshot = this.snapshot(), ids = new Map(snapshot.specs.map(spec => [spec.path, spec.id]));
|
|
193
214
|
const hashes = new Map(snapshot.specs.map(spec => [spec.path, spec.hash]));
|
|
194
|
-
return this.index.search(query, options, hashes).flatMap(hit => {
|
|
215
|
+
return this.index.search(query, options, hashes, options.offset ?? 0, all).flatMap(hit => {
|
|
195
216
|
const id = ids.get(hit.path);
|
|
196
217
|
return id === undefined ? [] : [{ ...hit, id }];
|
|
197
218
|
});
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { resolve } from "node:path";
|
|
3
|
+
import { realPath } from "./platform.ts";
|
|
4
|
+
import { extractLinks } from "./links.ts";
|
|
5
|
+
import { specReference, MAX_SPEC_INPUTS } from "./spec-graph.ts";
|
|
6
|
+
import { discoverSpecs, type SpecCandidate, type SpecDiagnostic, type SpecSnapshot } from "./spec-source.ts";
|
|
7
|
+
import { specFreshness, specMetadataIssues, type SpecFreshnessEntry } from "./spec-freshness.ts";
|
|
8
|
+
|
|
9
|
+
export interface SpecValidationIssue {
|
|
10
|
+
code: string;
|
|
11
|
+
severity: "error" | "warning";
|
|
12
|
+
path: string;
|
|
13
|
+
id?: string;
|
|
14
|
+
field?: string;
|
|
15
|
+
target?: string;
|
|
16
|
+
message: string;
|
|
17
|
+
}
|
|
18
|
+
export interface SpecValidationOptions { env?: NodeJS.ProcessEnv; requireFresh?: boolean; limit?: number; git?: boolean }
|
|
19
|
+
export interface SpecValidationReport {
|
|
20
|
+
ok: boolean;
|
|
21
|
+
errors: number;
|
|
22
|
+
warnings: number;
|
|
23
|
+
items: SpecValidationIssue[];
|
|
24
|
+
diagnostics: SpecDiagnostic[];
|
|
25
|
+
freshness: SpecFreshnessEntry[];
|
|
26
|
+
truncated: boolean;
|
|
27
|
+
}
|
|
28
|
+
export interface SpecRepoValidationOptions { env?: NodeJS.ProcessEnv; requireFresh?: boolean; limit?: number }
|
|
29
|
+
export interface SpecRepoValidation { code: 0 | 1; report: SpecValidationReport }
|
|
30
|
+
const RANK: Readonly<Record<string, number>> = { goal: 0, architecture: 1, module: 2, submodule: 3 };
|
|
31
|
+
const STATUSES = new Set(["draft", "active", "deprecated"]);
|
|
32
|
+
const MAX_OPERATIONS = 200000, MAX_ITEMS = 500, MAX_REPORT_BYTES = 128 * 1024;
|
|
33
|
+
const compare = (a: string, b: string) => a < b ? -1 : a > b ? 1 : 0;
|
|
34
|
+
const nonempty = (value: unknown): value is string => typeof value === "string" && !!value.trim();
|
|
35
|
+
const candidateId = (candidate: SpecCandidate) => nonempty(candidate.frontmatter.id) ? candidate.frontmatter.id : undefined;
|
|
36
|
+
interface ErrorOwner { kind: "old" | "new"; path: string }
|
|
37
|
+
interface Collected { records: { issue: SpecValidationIssue; key: string }[]; freshness: SpecFreshnessEntry[] }
|
|
38
|
+
|
|
39
|
+
/** Complete collection is separate from display limits, so the introduced-error gate never compares samples. */
|
|
40
|
+
function collect(snapshot: SpecSnapshot, options: SpecValidationOptions, owners?: ReadonlyMap<string, ErrorOwner>): Collected {
|
|
41
|
+
const candidates = [...(snapshot.candidates ?? snapshot.specs)].sort((a, b) => compare(a.path.normalize("NFC"), b.path.normalize("NFC")) || compare(a.path, b.path));
|
|
42
|
+
if (new Set(candidates.map(candidate => candidate.path)).size !== candidates.length) throw new Error("spec validation: duplicate candidate paths; provide one candidate record per file");
|
|
43
|
+
if (candidates.length > MAX_SPEC_INPUTS) throw new Error("spec validation: more than 10000 candidates; reduce the candidate tree before validating");
|
|
44
|
+
let operations = 0;
|
|
45
|
+
const tick = () => { if (++operations > MAX_OPERATIONS) throw new Error("spec validation: more than 200000 checks; reduce repeated links or metadata lists before validating"); };
|
|
46
|
+
const hashes = new Map<string, string>();
|
|
47
|
+
const digest = (value: string): string => {
|
|
48
|
+
let hash = hashes.get(value);
|
|
49
|
+
if (hash === undefined) { hash = createHash("sha256").update(value).digest("hex"); hashes.set(value, hash); }
|
|
50
|
+
return hash;
|
|
51
|
+
};
|
|
52
|
+
const records: Collected["records"] = [], keys = new Set<string>();
|
|
53
|
+
const addIssue = (issue: SpecValidationIssue) => {
|
|
54
|
+
tick();
|
|
55
|
+
const correspondence = owners?.get(issue.path) ?? { kind: owners === undefined ? "old" : "new", path: issue.path };
|
|
56
|
+
const owner = `${correspondence.kind}:${digest(correspondence.path)}`;
|
|
57
|
+
// Hash values independently: a long owner id is never copied once per relation/error key.
|
|
58
|
+
const key = JSON.stringify([digest(snapshot.commonDir), issue.severity, issue.code, owner, issue.field ?? "", issue.target === undefined ? "" : digest(issue.target)]);
|
|
59
|
+
if (!keys.has(key)) { keys.add(key); records.push({ issue, key }); }
|
|
60
|
+
};
|
|
61
|
+
const add = (candidate: SpecCandidate, code: string, severity: SpecValidationIssue["severity"], field: string, message: string, target?: string) => {
|
|
62
|
+
const id = candidateId(candidate);
|
|
63
|
+
addIssue({ code, severity, path: candidate.path, ...(id === undefined ? {} : { id }), field, message, ...(target === undefined ? {} : { target }) });
|
|
64
|
+
};
|
|
65
|
+
const nodes = new Map<string, SpecCandidate>(), first = new Map<string, string>();
|
|
66
|
+
for (const candidate of candidates) {
|
|
67
|
+
const id = candidateId(candidate);
|
|
68
|
+
if (id !== undefined) {
|
|
69
|
+
const previous = first.get(id);
|
|
70
|
+
if (previous !== undefined) add(candidate, "duplicate_id", "error", "id", "duplicate id; give each candidate a unique id", previous);
|
|
71
|
+
else first.set(id, candidate.path);
|
|
72
|
+
if (nonempty(candidate.frontmatter.type) && !nodes.has(id)) nodes.set(id, candidate);
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
const covers = new Map<string, Map<string, SpecCandidate>>();
|
|
76
|
+
for (const candidate of candidates) {
|
|
77
|
+
tick();
|
|
78
|
+
const data = candidate.frontmatter, id = candidateId(candidate);
|
|
79
|
+
if (options.git === false) for (const issue of specMetadataIssues(candidate)) addIssue(issue);
|
|
80
|
+
for (const field of ["id", "type", "title"] as const) {
|
|
81
|
+
if (data[field] === undefined) add(candidate, `missing_${field}`, "error", field, `required ${field} is missing; add a nonempty string field`);
|
|
82
|
+
else if (!nonempty(data[field])) add(candidate, "wrong_shape", "error", field, `${field} must be a nonempty string; correct the frontmatter field`);
|
|
83
|
+
}
|
|
84
|
+
if (nonempty(data.type) && !Object.hasOwn(RANK, data.type)) add(candidate, "unknown_type", "error", "type", "unknown type; use goal, architecture, module or submodule");
|
|
85
|
+
if (data.status !== undefined && (typeof data.status !== "string" || !STATUSES.has(data.status))) add(candidate, "unknown_status", "error", "status", "unknown status; use draft, active or deprecated");
|
|
86
|
+
if (data.parent === undefined && data.type !== "goal") add(candidate, "orphan", "warning", "parent", "non-goal spec has no parent; link it to its owning higher-level spec");
|
|
87
|
+
if (data.status === "active" && data.paths === undefined) add(candidate, "active_without_paths", "warning", "paths", "active spec has no paths; add relative Git pathspecs for its source scope");
|
|
88
|
+
const checkLink = (field: string, value: unknown, shapeField = field): string | undefined => {
|
|
89
|
+
tick();
|
|
90
|
+
const target = specReference(value);
|
|
91
|
+
if (target === undefined) { add(candidate, "wrong_shape", "error", shapeField, "link must be one id or wiki link; correct the frontmatter value"); return undefined; }
|
|
92
|
+
if (!nodes.has(target)) add(candidate, "dangling_link", "error", field, "frontmatter link names no graph node; link to an existing spec id or remove it", target);
|
|
93
|
+
return target;
|
|
94
|
+
};
|
|
95
|
+
let parent: string | undefined, replacement: string | undefined;
|
|
96
|
+
if (data.parent !== undefined) parent = checkLink("parent", data.parent);
|
|
97
|
+
if (data["superseded-by"] !== undefined) {
|
|
98
|
+
replacement = checkLink("superseded-by", data["superseded-by"]);
|
|
99
|
+
if (data.status !== "deprecated") add(candidate, "superseded_status", "error", "superseded-by", "replacement link requires deprecated status; deprecate the spec or remove the link");
|
|
100
|
+
if (replacement !== undefined && replacement === id) add(candidate, "superseded_self", "error", "superseded-by", "replacement points to this spec; link to a different replacement", replacement);
|
|
101
|
+
} else if (data.status === "deprecated") add(candidate, "deprecated_without_replacement", "warning", "superseded-by", "deprecated spec has no replacement; add a superseded-by id when one exists");
|
|
102
|
+
if (data.status === "deprecated" && replacement !== undefined && replacement !== id && nodes.get(replacement)?.frontmatter.status === "deprecated") add(candidate, "deprecated_replacement", "warning", "superseded-by", "replacement is also deprecated; link to an active replacement", replacement);
|
|
103
|
+
for (const field of ["depends-on", "references", "implements"] as const) {
|
|
104
|
+
if (data[field] === undefined) continue;
|
|
105
|
+
const values = data[field];
|
|
106
|
+
if (!Array.isArray(values)) { add(candidate, "wrong_shape", "error", field, `${field} must be a list of links; wrap the value in a list`); continue; }
|
|
107
|
+
for (let i = 0; i < values.length; i++) checkLink(field, values[i], `${field}[${i}]`);
|
|
108
|
+
}
|
|
109
|
+
if (parent !== undefined) {
|
|
110
|
+
const parentType = nodes.get(parent)?.frontmatter.type;
|
|
111
|
+
if (typeof data.type === "string" && typeof parentType === "string" && Object.hasOwn(RANK, data.type) && Object.hasOwn(RANK, parentType) && RANK[data.type]! <= RANK[parentType]!) add(candidate, "type_rank", "error", "parent", "child rank must exceed parent rank; choose a higher-level parent (levels may be skipped)", parent);
|
|
112
|
+
}
|
|
113
|
+
for (const field of ["covers", "tags"] as const) {
|
|
114
|
+
const values = data[field];
|
|
115
|
+
if (values === undefined) continue;
|
|
116
|
+
let valid = Array.isArray(values);
|
|
117
|
+
if (Array.isArray(values)) for (const value of values) { tick(); if (!nonempty(value)) valid = false; }
|
|
118
|
+
if (!valid) {
|
|
119
|
+
add(candidate, "wrong_shape", "error", field, `${field} must be a list of nonempty strings; correct the frontmatter field`);
|
|
120
|
+
continue;
|
|
121
|
+
}
|
|
122
|
+
if (field === "covers") for (const value of values as string[]) {
|
|
123
|
+
const token = value.trim();
|
|
124
|
+
let owners = covers.get(token); if (!owners) covers.set(token, owners = new Map());
|
|
125
|
+
owners.set(candidate.path, candidate);
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
for (const link of extractLinks(candidate.body)) {
|
|
129
|
+
tick();
|
|
130
|
+
if (link.target && !nodes.has(link.target)) add(candidate, "unknown_body_link", "warning", "body", "body wiki link names no graph node; correct the target id or remove the link", link.target);
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
for (const [token, owners] of covers) if (owners.size > 1) for (const candidate of owners.values()) add(candidate, "duplicate_covers", "warning", "covers", "covers token is claimed by multiple specs; choose a single owning spec", token);
|
|
134
|
+
const goals = [...nodes.values()].filter(candidate => candidate.frontmatter.type === "goal");
|
|
135
|
+
if (goals.length > 1) for (const candidate of goals) add(candidate, "multiple_goals", "warning", "type", "multiple goal roots exist; consolidate or document separate goal trees");
|
|
136
|
+
// Iterative traversal handles a 10000-node chain without overflowing the JS stack.
|
|
137
|
+
const finished = new Set<string>();
|
|
138
|
+
for (const id of nodes.keys()) {
|
|
139
|
+
if (finished.has(id)) continue;
|
|
140
|
+
const chain: string[] = [], positions = new Map<string, number>();
|
|
141
|
+
let next: string | undefined = id;
|
|
142
|
+
while (next !== undefined && nodes.has(next) && !finished.has(next) && !positions.has(next)) {
|
|
143
|
+
tick(); positions.set(next, chain.length); chain.push(next);
|
|
144
|
+
next = specReference(nodes.get(next)!.frontmatter.parent);
|
|
145
|
+
}
|
|
146
|
+
if (next !== undefined && positions.has(next)) for (const member of chain.slice(positions.get(next)!)) add(nodes.get(member)!, "parent_cycle", "error", "parent", "parent cycle detected; remove a cycle link and point to a higher-level parent", specReference(nodes.get(member)!.frontmatter.parent));
|
|
147
|
+
for (const member of chain) finished.add(member);
|
|
148
|
+
}
|
|
149
|
+
for (const diagnostic of snapshot.diagnostics) {
|
|
150
|
+
if (diagnostic.code === "invalid_frontmatter") addIssue({ code: "invalid_frontmatter", severity: "error", path: diagnostic.path, field: "frontmatter", message: diagnostic.message });
|
|
151
|
+
else if (snapshot.candidates === undefined && diagnostic.code === "duplicate_id") addIssue({ code: "duplicate_id", severity: "error", path: diagnostic.path, id: diagnostic.id, field: "id", target: diagnostic.firstPath, message: diagnostic.message });
|
|
152
|
+
else if (snapshot.candidates === undefined && diagnostic.code === "invalid_identity") addIssue({ code: "wrong_shape", severity: "error", path: diagnostic.path, field: "id/type", message: diagnostic.message });
|
|
153
|
+
}
|
|
154
|
+
if (options.requireFresh && options.git === false) throw new Error("spec validation: requireFresh needs Git inspection; enable Git checks before requiring freshness");
|
|
155
|
+
const freshness = options.git === false ? { items: [], issues: [] } : specFreshness(snapshot, { env: options.env });
|
|
156
|
+
for (const issue of freshness.issues) addIssue(issue);
|
|
157
|
+
if (options.requireFresh) for (const item of freshness.items) if (item.state === "stale") addIssue({ code: "stale", severity: "error", path: item.path, id: item.id, field: "verified-against", message: "spec source scope is stale; review its paths and refresh verified-against after verification" });
|
|
158
|
+
records.sort((a, b) => (a.issue.severity === b.issue.severity ? 0 : a.issue.severity === "error" ? -1 : 1) || compare(a.issue.path.normalize("NFC"), b.issue.path.normalize("NFC")) || compare(a.issue.path, b.issue.path) || compare(a.issue.code, b.issue.code) || compare(a.issue.field ?? "", b.issue.field ?? "") || compare(a.key, b.key));
|
|
159
|
+
return { records, freshness: freshness.items };
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** Display is count/byte bounded; oversized optional identifiers are omitted, never silently renamed. */
|
|
163
|
+
function display<T extends object>(values: readonly T[], limit: number, budget: { bytes: number; truncated: boolean }): T[] {
|
|
164
|
+
const out: T[] = [];
|
|
165
|
+
for (const original of values) {
|
|
166
|
+
if (out.length >= limit) { budget.truncated = true; break; }
|
|
167
|
+
const value = { ...original } as T & { id?: string; target?: string };
|
|
168
|
+
for (const field of ["id", "target"] as const) if (typeof value[field] === "string" && Buffer.byteLength(value[field]!) > 1024) { delete value[field]; budget.truncated = true; }
|
|
169
|
+
const bytes = Buffer.byteLength(JSON.stringify(value)) + 1;
|
|
170
|
+
if (budget.bytes + bytes > MAX_REPORT_BYTES) { budget.truncated = true; break; }
|
|
171
|
+
budget.bytes += bytes; out.push(value);
|
|
172
|
+
}
|
|
173
|
+
return out;
|
|
174
|
+
}
|
|
175
|
+
function reportLimit(value = MAX_ITEMS): number {
|
|
176
|
+
if (!Number.isSafeInteger(value) || value < 1 || value > MAX_ITEMS) throw new Error("spec validation: report limit must be 1..500; pass a smaller positive item limit");
|
|
177
|
+
return value;
|
|
178
|
+
}
|
|
179
|
+
export function validateSpecs(snapshot: SpecSnapshot, options: SpecValidationOptions = {}): SpecValidationReport {
|
|
180
|
+
const limit = reportLimit(options.limit), result = collect(snapshot, options), budget = { bytes: 1024, truncated: false };
|
|
181
|
+
const errors = result.records.filter(record => record.issue.severity === "error").length;
|
|
182
|
+
return { ok: errors === 0, errors, warnings: result.records.length - errors,
|
|
183
|
+
items: display(result.records.map(record => record.issue), limit, budget),
|
|
184
|
+
diagnostics: display(snapshot.diagnostics, limit, budget), freshness: display(result.freshness, limit, budget),
|
|
185
|
+
get truncated() { return budget.truncated; } };
|
|
186
|
+
}
|
|
187
|
+
/** Existing error identities are retained even when their display sample was truncated. */
|
|
188
|
+
export function introducedSpecErrors(current: SpecSnapshot, prospective: SpecSnapshot, options: SpecValidationOptions = {}): SpecValidationIssue[] {
|
|
189
|
+
const limit = reportLimit(options.limit);
|
|
190
|
+
const pathsById = (input: SpecSnapshot) => {
|
|
191
|
+
const paths = new Map<string, Set<string>>();
|
|
192
|
+
const add = (id: string, path: string) => { let found = paths.get(id); if (!found) paths.set(id, found = new Set()); found.add(path); };
|
|
193
|
+
for (const candidate of input.candidates ?? input.specs) { const id = candidateId(candidate); if (id !== undefined) add(id, candidate.path); }
|
|
194
|
+
if (input.candidates === undefined) for (const diagnostic of input.diagnostics) if (diagnostic.code === "duplicate_id" && diagnostic.id !== undefined) add(diagnostic.id, diagnostic.path);
|
|
195
|
+
return paths;
|
|
196
|
+
};
|
|
197
|
+
const oldIds = pathsById(current), nextIds = pathsById(prospective), owners = new Map<string, ErrorOwner>(), reserved = new Set<string>();
|
|
198
|
+
for (const candidate of prospective.candidates ?? prospective.specs) {
|
|
199
|
+
const id = candidateId(candidate), previous = id === undefined ? undefined : oldIds.get(id);
|
|
200
|
+
if (previous?.size === 1 && nextIds.get(id!)?.size === 1) {
|
|
201
|
+
const path = previous.values().next().value!;
|
|
202
|
+
owners.set(candidate.path, { kind: "old", path }); reserved.add(path);
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
const previousPaths = new Set([...(current.candidates ?? current.specs).map(candidate => candidate.path), ...current.diagnostics.map(diagnostic => diagnostic.path)]);
|
|
206
|
+
const prospectivePaths = new Set([...(prospective.candidates ?? prospective.specs).map(candidate => candidate.path), ...prospective.diagnostics.map(diagnostic => diagnostic.path)]);
|
|
207
|
+
for (const path of prospectivePaths) if (!owners.has(path)) {
|
|
208
|
+
const retained = previousPaths.has(path) && !reserved.has(path);
|
|
209
|
+
owners.set(path, { kind: retained ? "old" : "new", path });
|
|
210
|
+
if (retained) reserved.add(path);
|
|
211
|
+
}
|
|
212
|
+
// Duplicate identity belongs to the id, even when a move changes the first file in path order.
|
|
213
|
+
// Keep collection keys unchanged so validation still reports each duplicate file.
|
|
214
|
+
const comparisonKey = (input: SpecSnapshot, record: Collected["records"][number]): string =>
|
|
215
|
+
record.issue.code === "duplicate_id" && record.issue.id !== undefined
|
|
216
|
+
? JSON.stringify([createHash("sha256").update(input.commonDir).digest("hex"), "duplicate_id", createHash("sha256").update(record.issue.id).digest("hex")])
|
|
217
|
+
: record.key;
|
|
218
|
+
const old = new Map<string, number>();
|
|
219
|
+
for (const record of collect(current, options).records) if (record.issue.severity === "error") {
|
|
220
|
+
const key = comparisonKey(current, record); old.set(key, (old.get(key) ?? 0) + 1);
|
|
221
|
+
}
|
|
222
|
+
const prospectiveErrors = collect(prospective, options, owners).records.filter(record => record.issue.severity === "error");
|
|
223
|
+
// Retained owners consume existing debt before new or moved files do.
|
|
224
|
+
prospectiveErrors.sort((a, b) => Number(owners.get(b.issue.path)?.kind === "old") - Number(owners.get(a.issue.path)?.kind === "old"));
|
|
225
|
+
const next = prospectiveErrors.filter(record => {
|
|
226
|
+
const key = comparisonKey(prospective, record), count = old.get(key) ?? 0;
|
|
227
|
+
if (count === 0) return true;
|
|
228
|
+
old.set(key, count - 1); return false;
|
|
229
|
+
});
|
|
230
|
+
const result = display(next.map(record => record.issue), limit, { bytes: 1024, truncated: false });
|
|
231
|
+
if (next.length && !result.length) throw new Error("spec validation: introduced error metadata exceeds the report budget; reduce metadata before writing");
|
|
232
|
+
return result;
|
|
233
|
+
}
|
|
234
|
+
/** Registry-free CI logic; no home/config/cache creation and no authored freshness fields. */
|
|
235
|
+
export function validateSpecRepo(repo: string, options: SpecRepoValidationOptions = {}): SpecRepoValidation {
|
|
236
|
+
let root: string;
|
|
237
|
+
try { root = realPath(resolve(repo)); } catch (error) { throw new Error("spec validation: repository root is unavailable; pass an existing checkout root", { cause: error }); }
|
|
238
|
+
const snapshot = discoverSpecs({ id: "repo", path: root, write: "none", pii: "deny" }, { env: options.env });
|
|
239
|
+
const report = validateSpecs(snapshot, options);
|
|
240
|
+
return { code: report.ok ? 0 : 1, report };
|
|
241
|
+
}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import { closeSync, constants, fstatSync, lstatSync, openSync, readdirSync, readSync, realpathSync } from "node:fs";
|
|
2
|
+
import { createHash } from "node:crypto";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
import type { VaultSpec } from "./config.ts";
|
|
5
|
+
import { isDenied } from "./platform.ts";
|
|
6
|
+
import { MAX_NOTE_BYTES, MAX_READ_BYTES, MAX_RESULTS, readPage } from "./vault-index.ts";
|
|
7
|
+
|
|
8
|
+
/** Vault paths readable outside notes/: these directories and root files. Reads never lock, index or write. */
|
|
9
|
+
export const FILE_ROOTS = ["ops/", "reports/", "self/", "templates/", "AGENTS.md", "README.md"] as const;
|
|
10
|
+
const DIRS = new Set(["ops", "reports", "self", "templates"]), FILES = new Set(["AGENTS.md", "README.md"]);
|
|
11
|
+
const ROOTS = "ops/, reports/, self/, templates/, AGENTS.md or README.md";
|
|
12
|
+
function fail(message: string, code = "V04"): never { throw Object.assign(new Error(message), { code }); }
|
|
13
|
+
|
|
14
|
+
/** Checks `path` against the allowed roots and returns its location; every component must be a plain directory or file. */
|
|
15
|
+
function locate(vault: VaultSpec, denyPaths: string[], path: string, kind: "file" | "dir"): string {
|
|
16
|
+
const parts = path.split("/");
|
|
17
|
+
if (path.startsWith("/") || path.includes("\\") || path.includes("\0") || parts.some(part => !part || part === "." || part === ".."))
|
|
18
|
+
fail(`path: absolute, empty, . or .. segments are refused; pass a vault-relative path under ${ROOTS}`);
|
|
19
|
+
if (parts.some(part => part.startsWith("."))) fail(`path: dot paths such as .git are not readable through vmem; read a path under ${ROOTS}`);
|
|
20
|
+
if (parts[0] === "notes") fail("path: notes/ is read with vmem_read or vmem_read_many and listed with vmem_list");
|
|
21
|
+
if (parts[0] === "log") fail("path: the vault log is read with vmem_log_tail");
|
|
22
|
+
if (!(DIRS.has(parts[0]!) || (kind === "file" && parts.length === 1 && FILES.has(parts[0]!))))
|
|
23
|
+
fail(`path: outside the readable roots; use a path under ${ROOTS}`);
|
|
24
|
+
const root = realpathSync(vault.path);
|
|
25
|
+
if (root !== vault.path) fail(`vault ${vault.id}: registered path changed; re-register it with vmem vaults add and restart the MCP server`);
|
|
26
|
+
if (isDenied(join(root, path), denyPaths)) fail("path: denied by the built-in secret rules or registry denyPaths; nothing read", "V06");
|
|
27
|
+
let current = root;
|
|
28
|
+
for (let i = 0; i < parts.length; i++) {
|
|
29
|
+
current = join(current, parts[i]!);
|
|
30
|
+
let stat: ReturnType<typeof lstatSync>;
|
|
31
|
+
try { stat = lstatSync(current); }
|
|
32
|
+
catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") fail(`path: not found; list the parent directory with vmem_list_files`); throw error; }
|
|
33
|
+
// ponytail: every link is refused, not only links leaving the vault; matches the writer's plain-path rule.
|
|
34
|
+
if (stat.isSymbolicLink()) fail("path: symlinked components are refused because a link can leave the vault; read the link target's own vault path");
|
|
35
|
+
const last = i === parts.length - 1, wantDir = !last || kind === "dir";
|
|
36
|
+
if (wantDir ? !stat.isDirectory() : !stat.isFile()) fail(wantDir ? "path: not a directory; list its parent with vmem_list_files" : "path: not a regular file; list it with vmem_list_files");
|
|
37
|
+
}
|
|
38
|
+
return current;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** Bounded UTF-8 read with vmem_read's limits and paging: maxBytes 1..64 KiB, files up to 2 MiB, byte offsets on character boundaries. */
|
|
42
|
+
export function readVaultFile(vault: VaultSpec, denyPaths: string[], path: string, maxBytes = 16384, offset?: number) {
|
|
43
|
+
if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > MAX_READ_BYTES) fail(`max-bytes: expected integer 1..${MAX_READ_BYTES}`);
|
|
44
|
+
if (offset !== undefined && (!Number.isSafeInteger(offset) || offset < 0 || offset > MAX_NOTE_BYTES)) fail(`offset: expected integer 0..${MAX_NOTE_BYTES}`);
|
|
45
|
+
const fd = openSync(locate(vault, denyPaths, path, "file"), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
|
|
46
|
+
let bytes: Buffer;
|
|
47
|
+
try {
|
|
48
|
+
const before = fstatSync(fd);
|
|
49
|
+
if (!before.isFile()) fail("path: not a regular file; list it with vmem_list_files");
|
|
50
|
+
if (before.size > MAX_NOTE_BYTES) fail(`file: exceeds the ${MAX_NOTE_BYTES}-byte read bound; read it outside vmem or split it`, "V09");
|
|
51
|
+
const buffer = Buffer.alloc(before.size + 1); let size = 0;
|
|
52
|
+
while (size < buffer.length) { const count = readSync(fd, buffer, size, buffer.length - size, null); if (!count) break; size += count; }
|
|
53
|
+
const after = fstatSync(fd);
|
|
54
|
+
if (size !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs) fail("file: changed during read; retry once it is stable", "V09");
|
|
55
|
+
bytes = buffer.subarray(0, size);
|
|
56
|
+
} finally { closeSync(fd); }
|
|
57
|
+
const text = bytes.toString("utf8");
|
|
58
|
+
if (!Buffer.from(text).equals(bytes)) fail("file: not valid UTF-8 text; vmem_read_file reads text files only", "V01");
|
|
59
|
+
const start = offset ?? 0, page = readPage(bytes.subarray(start, start + maxBytes + 4), maxBytes, start, bytes.length);
|
|
60
|
+
return { path, sha256: createHash("sha256").update(bytes).digest("hex"), truncated: page.truncated, body: page.content,
|
|
61
|
+
...(offset !== undefined ? { offset } : {}), ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}) };
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** One directory level under an allowed root, sorted by name; dot, linked, special and denied entries are left out. */
|
|
65
|
+
export function listVaultFiles(vault: VaultSpec, denyPaths: string[], dir: string) {
|
|
66
|
+
const clean = dir.replace(/\/$/, ""), location = locate(vault, denyPaths, clean, "dir");
|
|
67
|
+
// ponytail: readdirSync loads the whole directory before the 500-entry cut; stream with opendir if vault dirs grow huge.
|
|
68
|
+
const entries = readdirSync(location, { withFileTypes: true })
|
|
69
|
+
.filter(entry => !entry.name.startsWith(".") && (entry.isFile() || entry.isDirectory()) && !isDenied(join(location, entry.name), denyPaths))
|
|
70
|
+
.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
|
|
71
|
+
return { dir: clean, truncated: entries.length > MAX_RESULTS, entries: entries.slice(0, MAX_RESULTS).map(entry => entry.isDirectory()
|
|
72
|
+
? { name: entry.name, path: `${clean}/${entry.name}`, type: "dir" as const }
|
|
73
|
+
: { name: entry.name, path: `${clean}/${entry.name}`, type: "file" as const, bytes: lstatSync(join(location, entry.name)).size }) };
|
|
74
|
+
}
|