@ngockhoale/ukit 3.5.2 → 3.5.4
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 +38 -90
- package/README.md +1 -0
- package/manifests/documentation.yaml +12 -1
- package/manifests/platform.full.yaml +12 -0
- package/package.json +34 -1
- package/src/cli/commands/doctor.js +55 -2
- package/src/cli/commands/indexTools.js +10 -4
- package/src/cli/commands/memory.js +107 -8
- package/src/core/memory/episodes.js +106 -7
- package/src/core/memory/memoryCheck.js +241 -0
- package/src/core/memory/memoryCheckRun.js +27 -0
- package/src/core/memory/memoryHit.js +2 -0
- package/src/core/memory/mutateMemory.js +46 -1
- package/src/core/memory/observations.js +192 -0
- package/src/core/memory/projectIdentity.js +9 -2
- package/src/core/memory/recallEngine.js +204 -9
- package/src/core/memory/records.js +23 -0
- package/src/core/memory/registryPrune.js +230 -0
- package/src/core/memory/retrieval.js +12 -3
- package/src/core/memory/writeGate.js +137 -0
- package/src/core/runtimeConfig.js +12 -2
- package/src/index/buildIndex.js +26 -0
- package/src/index/paths.js +3 -1
- package/src/index/queryIndex.js +372 -26
- package/src/index/resolveContext.js +1 -1
- package/template_project/.claude/hooks/edit-hint.mjs +64 -17
- package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
- package/template_project/.claude/hooks/session-episode.sh +9 -4
- package/template_project/.claude/settings.json +2 -2
- package/template_project/.claude/ukit/index/edit-graph.mjs +141 -11
- package/template_project/.claude/ukit/index/lib/index-core.mjs +400 -27
- package/template_project/.claude/ukit/index/query-index.mjs +14 -3
- package/template_project/.claude/ukit/index/resolve-context.mjs +1 -1
- package/template_project/.claude/ukit/index/route-task.mjs +8 -2
- package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
- package/template_project/.claude/ukit/runtime/memory-lanes.mjs +44 -22
- package/template_project/.claude/ukit/runtime/memory-recall.mjs +204 -9
- package/template_project/.claude/ukit/runtime/memory-validity.mjs +259 -0
- package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
- package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
- package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
- package/template_project/ukit/storage/config.json +4 -2
- package/src/core/agentRuntime/completionGate.js +0 -179
- package/src/core/agentRuntime/context.js +0 -571
- package/src/core/agentRuntime/qualityComparison.js +0 -112
- package/src/core/agentRuntime/resourcePolicy.js +0 -78
- package/src/core/agentRuntime/runtimeSupport.js +0 -255
- package/src/core/codeintel/manifest.js +0 -176
- package/src/core/experiments/deliberation.js +0 -327
- package/src/core/experiments/dynamicWorkflow.js +0 -507
- package/src/core/handoffDocValidator.js +0 -154
- package/src/core/memory/deltaOverlays.js +0 -493
- package/src/core/memory/learningCandidates.js +0 -347
- package/src/core/observability/emit/sessionBoot.js +0 -407
- package/src/core/observability/evaluation/experimentPlan.js +0 -95
- package/src/core/observability/evaluation/perturbation.js +0 -273
- package/src/core/observability/evaluation/replay.js +0 -149
- package/src/core/observability/evaluation/scorecard.js +0 -465
- package/src/core/observability/schema/compatibility.js +0 -180
- package/src/core/observability/support/renderer.js +0 -130
- package/src/core/reviewPanelAggregate.js +0 -204
- package/src/core/taskBudgetValidator.js +0 -251
- package/src/core/taskProgressGuard.js +0 -227
- package/src/decision/reviewVerdict.js +0 -339
- package/src/decision/runtimeFilter.js +0 -150
- package/src/decision/runtimeScheduler.js +0 -239
- package/src/diagnostics/classifyHang.js +0 -246
- package/src/diagnostics/ompStallSnapshot.js +0 -199
- package/src/index/contextPack.js +0 -285
- package/src/index/impactContext.js +0 -360
- package/src/index/reviewPolicy.js +0 -368
- package/src/index/sensitivePath.js +0 -21
- package/src/render/instructionRenderer.js +0 -290
- package/src/skill/auditSkill.js +0 -140
- package/template_project/instructions/overlays/repo.md +0 -9
|
@@ -1,78 +0,0 @@
|
|
|
1
|
-
// Deterministic resource-pressure policy for runtime event emission (G6 / TASK-002).
|
|
2
|
-
// Pure module: no I/O, no runtimeConfig reads, no adapter/context imports.
|
|
3
|
-
// Maps {cpuPressure, eventClass, queueDepth} to a frozen ResourceDecision —
|
|
4
|
-
// {action:'emit'|'coalesce'|'defer', maxDeferMs?, reason:string}.
|
|
5
|
-
//
|
|
6
|
-
// DR-FR09 invariant: terminal, failure, permission and user-input events are
|
|
7
|
-
// NEVER dropped or deferred — they always `emit` under any pressure or queue
|
|
8
|
-
// depth. Only `progress`-class observations may be coalesced/deferred, and
|
|
9
|
-
// deferral is always bounded (maxDeferMs) — there is no 'drop' action.
|
|
10
|
-
// Unknown event class or malformed input resolves `emit` (fail open for
|
|
11
|
-
// correctness, not throughput); this function never throws.
|
|
12
|
-
|
|
13
|
-
export const RESOURCE_ACTIONS = Object.freeze(['emit', 'coalesce', 'defer']);
|
|
14
|
-
|
|
15
|
-
export const EVENT_CLASSES = Object.freeze([
|
|
16
|
-
'terminal',
|
|
17
|
-
'failure',
|
|
18
|
-
'permission',
|
|
19
|
-
'user-input',
|
|
20
|
-
'progress',
|
|
21
|
-
]);
|
|
22
|
-
|
|
23
|
-
export const PRESSURE_LEVELS = Object.freeze(['normal', 'elevated', 'critical']);
|
|
24
|
-
|
|
25
|
-
// Bounded deferral ceilings (literal config values, ms). Coalescing may batch
|
|
26
|
-
// for up to this window; deferral may postpone emission by up to this window.
|
|
27
|
-
const MAX_DEFER_MS = Object.freeze({ elevated: 500, critical: 2000 });
|
|
28
|
-
|
|
29
|
-
// Queue depth below which pressure alone does not justify deferral — coalesce
|
|
30
|
-
// is the cheaper backpressure signal and is preferred first.
|
|
31
|
-
const DEFER_QUEUE_DEPTH = 8;
|
|
32
|
-
|
|
33
|
-
const CRITICAL_CLASSES = new Set(['terminal', 'failure', 'permission', 'user-input']);
|
|
34
|
-
const PRESSURE_SET = new Set(PRESSURE_LEVELS);
|
|
35
|
-
|
|
36
|
-
const freeze = (action, reason, extra) =>
|
|
37
|
-
Object.freeze({ action, reason, ...extra });
|
|
38
|
-
|
|
39
|
-
/**
|
|
40
|
-
* selectResourcePolicy({cpuPressure, eventClass, queueDepth}) → frozen
|
|
41
|
-
* ResourceDecision. Never throws; never returns `drop`.
|
|
42
|
-
*/
|
|
43
|
-
export function selectResourcePolicy(input) {
|
|
44
|
-
if (input === null || typeof input !== 'object' || Array.isArray(input)) {
|
|
45
|
-
return freeze('emit', 'malformed');
|
|
46
|
-
}
|
|
47
|
-
|
|
48
|
-
const { cpuPressure, eventClass, queueDepth } = input;
|
|
49
|
-
|
|
50
|
-
if (typeof eventClass !== 'string' || !EVENT_CLASSES.includes(eventClass)) {
|
|
51
|
-
// Any non-string or unrecognized class — including missing fields on a
|
|
52
|
-
// structurally valid object — fails open.
|
|
53
|
-
if (typeof eventClass === 'string' && eventClass.length > 0) {
|
|
54
|
-
return freeze('emit', 'class:unknown');
|
|
55
|
-
}
|
|
56
|
-
return freeze('emit', 'malformed');
|
|
57
|
-
}
|
|
58
|
-
|
|
59
|
-
// DR-FR09: critical classes always emit, regardless of pressure/depth.
|
|
60
|
-
if (CRITICAL_CLASSES.has(eventClass)) {
|
|
61
|
-
return freeze('emit', 'class:critical');
|
|
62
|
-
}
|
|
63
|
-
|
|
64
|
-
// eventClass === 'progress' from here.
|
|
65
|
-
if (!PRESSURE_SET.has(cpuPressure) || typeof queueDepth !== 'number' || !Number.isFinite(queueDepth) || queueDepth < 0) {
|
|
66
|
-
return freeze('emit', 'malformed');
|
|
67
|
-
}
|
|
68
|
-
|
|
69
|
-
if (cpuPressure === 'normal') {
|
|
70
|
-
return freeze('emit', 'pressure:normal');
|
|
71
|
-
}
|
|
72
|
-
|
|
73
|
-
const maxDeferMs = MAX_DEFER_MS[cpuPressure];
|
|
74
|
-
if (cpuPressure === 'critical' || queueDepth >= DEFER_QUEUE_DEPTH) {
|
|
75
|
-
return freeze('defer', 'pressure:defer', { maxDeferMs });
|
|
76
|
-
}
|
|
77
|
-
return freeze('coalesce', 'pressure:coalesce', { maxDeferMs });
|
|
78
|
-
}
|
|
@@ -1,255 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* agentRuntime/runtimeSupport.js — decision-first-runtime G7 (DR-10),
|
|
3
|
-
* SPEC §2 G7-FR03, §4, §5.
|
|
4
|
-
*
|
|
5
|
-
* buildRuntimeSupportRecords(dir, opts?)
|
|
6
|
-
* → { version, records[], coverage, redaction_version }
|
|
7
|
-
*
|
|
8
|
-
* Pure reader over the eventStore journals: each operation becomes one
|
|
9
|
-
* bounded support record carrying counts/codes/timings/artifact digests
|
|
10
|
-
* ONLY. `safePayload` strings are never copied into records — the only
|
|
11
|
-
* payload-derived values are state names, typed codes (safePayload.code /
|
|
12
|
-
* resolution / exit_code), and artifact sha256 digests. Every record is
|
|
13
|
-
* passed through sanitizeForSupport (default-deny, second privacy
|
|
14
|
-
* boundary): rejections are drop-and-count, never repaired, never
|
|
15
|
-
* bypassed.
|
|
16
|
-
*
|
|
17
|
-
* Invariants:
|
|
18
|
-
* - operationIds are pseudonymized per call (bundle-local salted
|
|
19
|
-
* sha256, projector.js convention) — raw IDs never appear in output.
|
|
20
|
-
* - no writes to journals/runtime storage; no config reads.
|
|
21
|
-
* - corrupt journals and unreadable dirs degrade to typed coverage —
|
|
22
|
-
* never throw raw, never fabricate records.
|
|
23
|
-
* - bounds: maxRecords / maxBytes caps are drop-and-count.
|
|
24
|
-
*/
|
|
25
|
-
|
|
26
|
-
import { promises as fs } from 'node:fs';
|
|
27
|
-
import path from 'node:path';
|
|
28
|
-
import crypto from 'node:crypto';
|
|
29
|
-
|
|
30
|
-
import { readJournal } from './eventStore.js';
|
|
31
|
-
import { listHostAdapters } from './adapters.js';
|
|
32
|
-
import { sanitizeForSupport } from '../observability/privacy/sanitizeForSupport.js';
|
|
33
|
-
import { REDACTION_VERSION } from '../observability/privacy/allowlist.js';
|
|
34
|
-
|
|
35
|
-
export const SUPPORT_RECORDS_VERSION = 'ukit-runtime-support/1';
|
|
36
|
-
|
|
37
|
-
const JOURNAL_DIR = 'events';
|
|
38
|
-
|
|
39
|
-
export const DEFAULT_CAPS = Object.freeze({
|
|
40
|
-
maxRecords: 2000,
|
|
41
|
-
maxBytes: 8 * 1024 * 1024,
|
|
42
|
-
});
|
|
43
|
-
|
|
44
|
-
function sha256Hex(input) {
|
|
45
|
-
return crypto.createHash('sha256').update(input).digest('hex');
|
|
46
|
-
}
|
|
47
|
-
|
|
48
|
-
/** Bundle-local pseudonym: deterministic within one call, salted per call. */
|
|
49
|
-
function pseudonymizer(salt) {
|
|
50
|
-
const cache = new Map();
|
|
51
|
-
return (value) => {
|
|
52
|
-
let pseudo = cache.get(value);
|
|
53
|
-
if (!pseudo) {
|
|
54
|
-
pseudo = `ref-${sha256Hex(`${salt}:${value}`).slice(0, 16)}`;
|
|
55
|
-
cache.set(value, pseudo);
|
|
56
|
-
}
|
|
57
|
-
return pseudo;
|
|
58
|
-
};
|
|
59
|
-
}
|
|
60
|
-
|
|
61
|
-
async function listOperationIds(dir) {
|
|
62
|
-
let names;
|
|
63
|
-
try {
|
|
64
|
-
names = await fs.readdir(path.join(dir, JOURNAL_DIR));
|
|
65
|
-
} catch {
|
|
66
|
-
return [];
|
|
67
|
-
}
|
|
68
|
-
return names
|
|
69
|
-
.filter((n) => n.endsWith('.jsonl'))
|
|
70
|
-
.map((n) => n.slice(0, -'.jsonl'.length))
|
|
71
|
-
.sort();
|
|
72
|
-
}
|
|
73
|
-
|
|
74
|
-
/**
|
|
75
|
-
* Artifact digest refs only — `path` (a raw filesystem path) is never
|
|
76
|
-
* emitted. Object refs contribute `{name: stream, fingerprint: sha256}`;
|
|
77
|
-
* opaque string refs contribute a salted digest pseudonym.
|
|
78
|
-
*/
|
|
79
|
-
function artifactDigests(events, pseudo) {
|
|
80
|
-
const out = [];
|
|
81
|
-
for (const event of events) {
|
|
82
|
-
for (const ref of event.artifactRefs ?? []) {
|
|
83
|
-
if (ref && typeof ref === 'object' && typeof ref.sha256 === 'string') {
|
|
84
|
-
out.push({
|
|
85
|
-
name: typeof ref.stream === 'string' ? ref.stream : 'artifact',
|
|
86
|
-
fingerprint: ref.sha256,
|
|
87
|
-
});
|
|
88
|
-
} else if (typeof ref === 'string' && ref.length > 0) {
|
|
89
|
-
out.push({ name: 'artifact', fingerprint: sha256Hex(`ref:${ref}`).slice(0, 32) });
|
|
90
|
-
}
|
|
91
|
-
}
|
|
92
|
-
}
|
|
93
|
-
return out.slice(0, 32);
|
|
94
|
-
}
|
|
95
|
-
|
|
96
|
-
/**
|
|
97
|
-
* Summarize one operation journal into a support-view payload.
|
|
98
|
-
* Counts/codes/timings/digests only — no safePayload strings are copied
|
|
99
|
-
* except state names and typed code fields, which the support gate then
|
|
100
|
-
* re-verifies (default-deny).
|
|
101
|
-
*/
|
|
102
|
-
function summarize(events, pseudo) {
|
|
103
|
-
let status = 'unknown';
|
|
104
|
-
let firstAt = NaN;
|
|
105
|
-
let lastAt = NaN;
|
|
106
|
-
const typeCounts = new Map();
|
|
107
|
-
const errorCodes = new Set();
|
|
108
|
-
const reasonCodes = new Set();
|
|
109
|
-
|
|
110
|
-
for (const event of events) {
|
|
111
|
-
typeCounts.set(event.eventType, (typeCounts.get(event.eventType) ?? 0) + 1);
|
|
112
|
-
const t = Date.parse(event.observedAt);
|
|
113
|
-
if (!Number.isNaN(t)) {
|
|
114
|
-
if (Number.isNaN(firstAt) || t < firstAt) firstAt = t;
|
|
115
|
-
if (Number.isNaN(lastAt) || t > lastAt) lastAt = t;
|
|
116
|
-
}
|
|
117
|
-
const sp = event.safePayload;
|
|
118
|
-
if (sp && typeof sp === 'object') {
|
|
119
|
-
if (event.eventType === 'operation.transition' && typeof sp.to === 'string') {
|
|
120
|
-
status = sp.to;
|
|
121
|
-
}
|
|
122
|
-
if (typeof sp.code === 'string') errorCodes.add(sp.code);
|
|
123
|
-
if (typeof sp.resolution === 'string') reasonCodes.add(sp.resolution);
|
|
124
|
-
if (Number.isFinite(sp.exit_code) && sp.exit_code !== 0) {
|
|
125
|
-
errorCodes.add(`exit_${sp.exit_code}`);
|
|
126
|
-
}
|
|
127
|
-
}
|
|
128
|
-
}
|
|
129
|
-
|
|
130
|
-
const payload = {
|
|
131
|
-
status,
|
|
132
|
-
count: events.length,
|
|
133
|
-
duration_ms: Number.isNaN(firstAt) ? 0 : Math.max(0, lastAt - firstAt),
|
|
134
|
-
type: [...typeCounts.entries()]
|
|
135
|
-
.sort(([a], [b]) => a.localeCompare(b))
|
|
136
|
-
.map(([name, count]) => ({ name, count })),
|
|
137
|
-
error_code: [...errorCodes].sort(),
|
|
138
|
-
reason_code: [...reasonCodes].sort(),
|
|
139
|
-
fingerprint: artifactDigests(events, pseudo),
|
|
140
|
-
};
|
|
141
|
-
return payload;
|
|
142
|
-
}
|
|
143
|
-
|
|
144
|
-
/**
|
|
145
|
-
* Build privacy-sanitized support records for every operation journal
|
|
146
|
-
* under `dir/events/`.
|
|
147
|
-
*
|
|
148
|
-
* @param {string} dir eventStore root
|
|
149
|
-
* @param {object} [opts]
|
|
150
|
-
* @param {string} [opts.salt] pseudonym salt (default: random per call)
|
|
151
|
-
* @param {number} [opts.maxRecords] cap on emitted records (drop-and-count)
|
|
152
|
-
* @param {number} [opts.maxBytes] cap on total serialized record bytes
|
|
153
|
-
* @param {(text:string)=>{hasSecret:boolean}} [opts.scanner] gate scanner
|
|
154
|
-
* @returns {Promise<{version:string, records:object[],
|
|
155
|
-
* coverage:{read:number, rejected_records:number,
|
|
156
|
-
* rejection_reasons:object, dropped_records:number},
|
|
157
|
-
* redaction_version:string}>}
|
|
158
|
-
*/
|
|
159
|
-
export async function buildRuntimeSupportRecords(dir, opts = {}) {
|
|
160
|
-
const salt = typeof opts.salt === 'string' && opts.salt.length > 0
|
|
161
|
-
? opts.salt
|
|
162
|
-
: crypto.randomBytes(16).toString('hex');
|
|
163
|
-
const maxRecords = Number.isInteger(opts.maxRecords) && opts.maxRecords >= 0
|
|
164
|
-
? opts.maxRecords
|
|
165
|
-
: DEFAULT_CAPS.maxRecords;
|
|
166
|
-
const maxBytes = Number.isInteger(opts.maxBytes) && opts.maxBytes > 0
|
|
167
|
-
? opts.maxBytes
|
|
168
|
-
: DEFAULT_CAPS.maxBytes;
|
|
169
|
-
const gate = typeof opts.scanner === 'function'
|
|
170
|
-
? (rec) => sanitizeForSupport(rec, { scanner: opts.scanner })
|
|
171
|
-
: (rec) => sanitizeForSupport(rec);
|
|
172
|
-
const pseudo = pseudonymizer(salt);
|
|
173
|
-
|
|
174
|
-
const coverage = {
|
|
175
|
-
read: 0,
|
|
176
|
-
rejected_records: 0,
|
|
177
|
-
rejection_reasons: {},
|
|
178
|
-
dropped_records: 0,
|
|
179
|
-
};
|
|
180
|
-
const reject = (reason) => {
|
|
181
|
-
coverage.rejected_records += 1;
|
|
182
|
-
coverage.rejection_reasons[reason] =
|
|
183
|
-
(coverage.rejection_reasons[reason] ?? 0) + 1;
|
|
184
|
-
};
|
|
185
|
-
|
|
186
|
-
const records = [];
|
|
187
|
-
let bytes = 0;
|
|
188
|
-
let capped = false;
|
|
189
|
-
|
|
190
|
-
for (const operationId of await listOperationIds(dir)) {
|
|
191
|
-
coverage.read += 1;
|
|
192
|
-
|
|
193
|
-
const events = [];
|
|
194
|
-
try {
|
|
195
|
-
for await (const event of readJournal(dir, operationId)) {
|
|
196
|
-
events.push(event);
|
|
197
|
-
}
|
|
198
|
-
} catch (err) {
|
|
199
|
-
// typed store errors only; never propagate raw
|
|
200
|
-
reject(typeof err?.code === 'string' ? err.code : 'journal_unreadable');
|
|
201
|
-
continue;
|
|
202
|
-
}
|
|
203
|
-
|
|
204
|
-
const record = {
|
|
205
|
-
record_type: 'operation_summary',
|
|
206
|
-
semantic_name: 'agentRuntime.operation.summary',
|
|
207
|
-
schema_version: '1',
|
|
208
|
-
record_id: pseudo(operationId),
|
|
209
|
-
sequence: events.length > 0 ? events[events.length - 1].seq : 0,
|
|
210
|
-
privacy_class: 'internal',
|
|
211
|
-
payload: summarize(events, pseudo),
|
|
212
|
-
origin: 'agentRuntime.eventStore',
|
|
213
|
-
redaction_version: REDACTION_VERSION,
|
|
214
|
-
};
|
|
215
|
-
|
|
216
|
-
const verdict = gate(record);
|
|
217
|
-
if (!verdict.ok) {
|
|
218
|
-
reject(verdict.reason);
|
|
219
|
-
continue;
|
|
220
|
-
}
|
|
221
|
-
|
|
222
|
-
const size = Buffer.byteLength(JSON.stringify(verdict.record), 'utf8');
|
|
223
|
-
if (capped || records.length >= maxRecords || bytes + size > maxBytes) {
|
|
224
|
-
capped = true;
|
|
225
|
-
coverage.dropped_records += 1;
|
|
226
|
-
continue;
|
|
227
|
-
}
|
|
228
|
-
records.push(verdict.record);
|
|
229
|
-
bytes += size;
|
|
230
|
-
}
|
|
231
|
-
|
|
232
|
-
return {
|
|
233
|
-
version: SUPPORT_RECORDS_VERSION,
|
|
234
|
-
records,
|
|
235
|
-
coverage,
|
|
236
|
-
redaction_version: REDACTION_VERSION,
|
|
237
|
-
};
|
|
238
|
-
}
|
|
239
|
-
|
|
240
|
-
/**
|
|
241
|
-
* V-02 (AGENT_VM_RUNTIME_PLAN item V2): per-host capability map for the
|
|
242
|
-
* owned-runner lanes. Pure delegation to `listHostAdapters` — every lane
|
|
243
|
-
* reports `{supported, reason, completionApi, primitives}` honestly:
|
|
244
|
-
* 'supported' only with declared live host E2E, 'unsupported-probe'
|
|
245
|
-
* when primitives exist but live evidence is missing, 'unsupported'
|
|
246
|
-
* with a typed reason otherwise. No journal reads, no fs writes.
|
|
247
|
-
*
|
|
248
|
-
* @param {object} [opts] forwarded to probeHostAdapter (spawnImpl,
|
|
249
|
-
* killImpl, probeImpl, platform, liveHostE2E)
|
|
250
|
-
* @returns {{[host:string]: {supported:string, reason:string|null,
|
|
251
|
-
* completionApi:string|null, primitives:object}}}
|
|
252
|
-
*/
|
|
253
|
-
export function buildHostCapabilityMap(opts = {}) {
|
|
254
|
-
return listHostAdapters(opts);
|
|
255
|
-
}
|
|
@@ -1,176 +0,0 @@
|
|
|
1
|
-
import fs from 'node:fs/promises';
|
|
2
|
-
import path from 'node:path';
|
|
3
|
-
import crypto from 'node:crypto';
|
|
4
|
-
|
|
5
|
-
import { getIndexDir } from '../../index/paths.js';
|
|
6
|
-
|
|
7
|
-
// Manifest scanner (SPEC §1) — walks the project, records a sha1 per file, and
|
|
8
|
-
// caches the result at `getIndexDir()/manifest.json`. The cache is validated on
|
|
9
|
-
// (path, mtime, size) so an unchanged tree never re-hashes, and any mtime/size
|
|
10
|
-
// drift forces a full rescan.
|
|
11
|
-
|
|
12
|
-
const HARD_EXCLUDES = new Set(['.git', '.cache', 'node_modules']);
|
|
13
|
-
const MANIFEST_CACHE = 'manifest.json';
|
|
14
|
-
|
|
15
|
-
const IGNORED_BASENAMES = new Set(['.DS_Store']);
|
|
16
|
-
|
|
17
|
-
function sha1(content) {
|
|
18
|
-
return crypto.createHash('sha1').update(content).digest('hex');
|
|
19
|
-
}
|
|
20
|
-
|
|
21
|
-
// Minimal .gitignore subset: blank lines and `#` comments skipped, `!` negation
|
|
22
|
-
// unsupported (documented — negations are rare in-repo and the safe failure mode
|
|
23
|
-
// is scanning a file that should be ignored, never dropping a needed one).
|
|
24
|
-
// Supported: `name` (basename match anywhere), `dir/` (directory), `/path`
|
|
25
|
-
// (root-anchored), `*` single-segment wildcard.
|
|
26
|
-
function parseGitignore(content) {
|
|
27
|
-
return String(content ?? '')
|
|
28
|
-
.split(/\r?\n/)
|
|
29
|
-
.map((line) => line.trim())
|
|
30
|
-
.filter((line) => line.length > 0 && !line.startsWith('#') && !line.startsWith('!'));
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
function gitignorePatternToRegExp(pattern) {
|
|
34
|
-
let anchored = false;
|
|
35
|
-
let dirOnly = false;
|
|
36
|
-
let body = pattern;
|
|
37
|
-
if (body.endsWith('/')) {
|
|
38
|
-
dirOnly = true;
|
|
39
|
-
body = body.slice(0, -1);
|
|
40
|
-
}
|
|
41
|
-
if (body.startsWith('/')) {
|
|
42
|
-
anchored = true;
|
|
43
|
-
body = body.slice(1);
|
|
44
|
-
}
|
|
45
|
-
const escaped = body
|
|
46
|
-
.split('*')
|
|
47
|
-
.map((part) => part.replace(/[.+^${}()|[\]\\]/g, '\\$&'))
|
|
48
|
-
.join('[^/]*');
|
|
49
|
-
if (anchored || body.includes('/')) {
|
|
50
|
-
return { re: new RegExp(`^${escaped}(?:/.*)?$`), dirOnly };
|
|
51
|
-
}
|
|
52
|
-
return { re: new RegExp(`(?:^|/)${escaped}(?:/.*)?$`), dirOnly };
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
function loadIgnoreMatchers(rootDir, extraIgnore) {
|
|
56
|
-
return fs.readFile(path.join(rootDir, '.gitignore'), 'utf8')
|
|
57
|
-
.then((content) => [...parseGitignore(content), ...(extraIgnore ?? [])])
|
|
58
|
-
.then((patterns) => patterns.map(gitignorePatternToRegExp))
|
|
59
|
-
.catch(() => (extraIgnore ?? []).map(gitignorePatternToRegExp));
|
|
60
|
-
}
|
|
61
|
-
|
|
62
|
-
function isIgnored(relPath, isDir, matchers) {
|
|
63
|
-
return matchers.some(({ re, dirOnly }) => (!dirOnly || isDir) && re.test(relPath));
|
|
64
|
-
}
|
|
65
|
-
|
|
66
|
-
async function walk(rootDir, matchers, options) {
|
|
67
|
-
const results = [];
|
|
68
|
-
const stack = [''];
|
|
69
|
-
while (stack.length > 0) {
|
|
70
|
-
const relDir = stack.pop();
|
|
71
|
-
const absDir = path.join(rootDir, relDir);
|
|
72
|
-
let entries;
|
|
73
|
-
try {
|
|
74
|
-
entries = await fs.readdir(absDir, { withFileTypes: true });
|
|
75
|
-
} catch {
|
|
76
|
-
continue;
|
|
77
|
-
}
|
|
78
|
-
for (const entry of entries) {
|
|
79
|
-
const relPath = relDir ? `${relDir}/${entry.name}` : entry.name;
|
|
80
|
-
if (entry.isDirectory()) {
|
|
81
|
-
if (HARD_EXCLUDES.has(entry.name)) {
|
|
82
|
-
continue;
|
|
83
|
-
}
|
|
84
|
-
if (isIgnored(relPath, true, matchers)) {
|
|
85
|
-
continue;
|
|
86
|
-
}
|
|
87
|
-
stack.push(relPath);
|
|
88
|
-
} else if (entry.isFile()) {
|
|
89
|
-
if (IGNORED_BASENAMES.has(entry.name)) {
|
|
90
|
-
continue;
|
|
91
|
-
}
|
|
92
|
-
if (isIgnored(relPath, false, matchers)) {
|
|
93
|
-
continue;
|
|
94
|
-
}
|
|
95
|
-
if (options?.filter && !options.filter(relPath)) {
|
|
96
|
-
continue;
|
|
97
|
-
}
|
|
98
|
-
try {
|
|
99
|
-
const stat = await fs.stat(path.join(rootDir, relPath));
|
|
100
|
-
results.push({ path: relPath, mtime: stat.mtimeMs, size: stat.size });
|
|
101
|
-
} catch {
|
|
102
|
-
// Vanished mid-walk — skip.
|
|
103
|
-
}
|
|
104
|
-
}
|
|
105
|
-
}
|
|
106
|
-
}
|
|
107
|
-
results.sort((a, b) => a.path.localeCompare(b.path));
|
|
108
|
-
return results;
|
|
109
|
-
}
|
|
110
|
-
|
|
111
|
-
async function readCachedManifest(rootDir) {
|
|
112
|
-
try {
|
|
113
|
-
const raw = await fs.readFile(path.join(getIndexDir(rootDir), MANIFEST_CACHE), 'utf8');
|
|
114
|
-
const parsed = JSON.parse(raw);
|
|
115
|
-
if (!parsed || !Array.isArray(parsed.files)) {
|
|
116
|
-
return null;
|
|
117
|
-
}
|
|
118
|
-
return parsed;
|
|
119
|
-
} catch {
|
|
120
|
-
return null;
|
|
121
|
-
}
|
|
122
|
-
}
|
|
123
|
-
|
|
124
|
-
function snapshotMatches(cachedFiles, scannedFiles) {
|
|
125
|
-
if (!Array.isArray(cachedFiles) || cachedFiles.length !== scannedFiles.length) {
|
|
126
|
-
return false;
|
|
127
|
-
}
|
|
128
|
-
const byPath = new Map(cachedFiles.map((f) => [f.path, f]));
|
|
129
|
-
return scannedFiles.every((entry) => {
|
|
130
|
-
const cached = byPath.get(entry.path);
|
|
131
|
-
return cached && cached.mtime === entry.mtime && cached.size === entry.size
|
|
132
|
-
&& typeof cached.sha1 === 'string';
|
|
133
|
-
});
|
|
134
|
-
}
|
|
135
|
-
|
|
136
|
-
/**
|
|
137
|
-
* scanManifest(projectRoot, { ignore, filter }) →
|
|
138
|
-
* { files: [{ path, sha1, mtime, size }], generatedAt, fromCache }
|
|
139
|
-
*
|
|
140
|
-
* `ignore` adds .gitignore-style patterns on top of the repo .gitignore.
|
|
141
|
-
* `filter(relPath)` optionally keeps a subset of scanned files.
|
|
142
|
-
* Never throws on a missing/unreadable tree — returns an empty manifest.
|
|
143
|
-
*/
|
|
144
|
-
export async function scanManifest(projectRoot, { ignore, filter } = {}) {
|
|
145
|
-
const rootDir = path.resolve(projectRoot ?? process.cwd());
|
|
146
|
-
const matchers = await loadIgnoreMatchers(rootDir, ignore);
|
|
147
|
-
const scanned = await walk(rootDir, matchers, { filter });
|
|
148
|
-
|
|
149
|
-
const cached = await readCachedManifest(rootDir);
|
|
150
|
-
if (cached && snapshotMatches(cached.files, scanned)) {
|
|
151
|
-
return { files: cached.files, generatedAt: cached.generatedAt, fromCache: true };
|
|
152
|
-
}
|
|
153
|
-
|
|
154
|
-
const files = await Promise.all(scanned.map(async (entry) => {
|
|
155
|
-
let fileSha = null;
|
|
156
|
-
try {
|
|
157
|
-
const content = await fs.readFile(path.join(rootDir, entry.path));
|
|
158
|
-
fileSha = sha1(content);
|
|
159
|
-
} catch {
|
|
160
|
-
fileSha = null;
|
|
161
|
-
}
|
|
162
|
-
return { path: entry.path, sha1: fileSha, mtime: entry.mtime, size: entry.size };
|
|
163
|
-
}));
|
|
164
|
-
|
|
165
|
-
const manifest = { files, generatedAt: new Date().toISOString() };
|
|
166
|
-
try {
|
|
167
|
-
await fs.mkdir(getIndexDir(rootDir), { recursive: true });
|
|
168
|
-
await fs.writeFile(
|
|
169
|
-
path.join(getIndexDir(rootDir), MANIFEST_CACHE),
|
|
170
|
-
JSON.stringify({ files, generatedAt: manifest.generatedAt }, null, 2),
|
|
171
|
-
);
|
|
172
|
-
} catch {
|
|
173
|
-
// Cache write failure must not fail the scan.
|
|
174
|
-
}
|
|
175
|
-
return { ...manifest, fromCache: false };
|
|
176
|
-
}
|