agent-recall-core 3.4.39 → 3.4.41
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/dist/helpers/auto-name.d.ts +2 -1
- package/dist/helpers/auto-name.d.ts.map +1 -1
- package/dist/helpers/auto-name.js +45 -6
- package/dist/helpers/auto-name.js.map +1 -1
- package/dist/helpers/journal-files.d.ts +29 -1
- package/dist/helpers/journal-files.d.ts.map +1 -1
- package/dist/helpers/journal-files.js +124 -33
- package/dist/helpers/journal-files.js.map +1 -1
- package/dist/helpers/journal-sig-theme.d.ts +18 -0
- package/dist/helpers/journal-sig-theme.d.ts.map +1 -1
- package/dist/helpers/journal-sig-theme.js +45 -4
- package/dist/helpers/journal-sig-theme.js.map +1 -1
- package/dist/index.d.ts +11 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +15 -0
- package/dist/index.js.map +1 -1
- package/dist/storage/archive-write.d.ts.map +1 -1
- package/dist/storage/archive-write.js +7 -1
- package/dist/storage/archive-write.js.map +1 -1
- package/dist/storage/blind-spots-store.d.ts +9 -1
- package/dist/storage/blind-spots-store.d.ts.map +1 -1
- package/dist/storage/blind-spots-store.js +9 -2
- package/dist/storage/blind-spots-store.js.map +1 -1
- package/dist/storage/corrections.d.ts +47 -3
- package/dist/storage/corrections.d.ts.map +1 -1
- package/dist/storage/corrections.js +53 -6
- package/dist/storage/corrections.js.map +1 -1
- package/dist/storage/extraction.d.ts +136 -0
- package/dist/storage/extraction.d.ts.map +1 -0
- package/dist/storage/extraction.js +368 -0
- package/dist/storage/extraction.js.map +1 -0
- package/dist/storage/fs-utils.d.ts +21 -0
- package/dist/storage/fs-utils.d.ts.map +1 -1
- package/dist/storage/fs-utils.js +86 -0
- package/dist/storage/fs-utils.js.map +1 -1
- package/dist/storage/hook-health.d.ts +50 -0
- package/dist/storage/hook-health.d.ts.map +1 -0
- package/dist/storage/hook-health.js +183 -0
- package/dist/storage/hook-health.js.map +1 -0
- package/dist/storage/hygiene.d.ts +111 -0
- package/dist/storage/hygiene.d.ts.map +1 -0
- package/dist/storage/hygiene.js +422 -0
- package/dist/storage/hygiene.js.map +1 -0
- package/dist/storage/memory-protocol.d.ts.map +1 -1
- package/dist/storage/memory-protocol.js +4 -1
- package/dist/storage/memory-protocol.js.map +1 -1
- package/dist/storage/paths.d.ts +23 -4
- package/dist/storage/paths.d.ts.map +1 -1
- package/dist/storage/paths.js +26 -9
- package/dist/storage/paths.js.map +1 -1
- package/dist/storage/recency-index.d.ts +79 -0
- package/dist/storage/recency-index.d.ts.map +1 -0
- package/dist/storage/recency-index.js +204 -0
- package/dist/storage/recency-index.js.map +1 -0
- package/dist/storage/session-card.d.ts +74 -0
- package/dist/storage/session-card.d.ts.map +1 -0
- package/dist/storage/session-card.js +219 -0
- package/dist/storage/session-card.js.map +1 -0
- package/dist/storage/store-manifest.d.ts +31 -0
- package/dist/storage/store-manifest.d.ts.map +1 -0
- package/dist/storage/store-manifest.js +108 -0
- package/dist/storage/store-manifest.js.map +1 -0
- package/dist/supabase/recall-backend.d.ts +1 -1
- package/dist/supabase/recall-backend.d.ts.map +1 -1
- package/dist/supabase/recall-backend.js.map +1 -1
- package/dist/supabase/sync.d.ts.map +1 -1
- package/dist/supabase/sync.js +13 -2
- package/dist/supabase/sync.js.map +1 -1
- package/dist/tools-logic/drill-down.d.ts +9 -2
- package/dist/tools-logic/drill-down.d.ts.map +1 -1
- package/dist/tools-logic/drill-down.js +32 -1
- package/dist/tools-logic/drill-down.js.map +1 -1
- package/dist/tools-logic/journal-search.d.ts.map +1 -1
- package/dist/tools-logic/journal-search.js +7 -1
- package/dist/tools-logic/journal-search.js.map +1 -1
- package/dist/tools-logic/predict-correction.d.ts +10 -0
- package/dist/tools-logic/predict-correction.d.ts.map +1 -1
- package/dist/tools-logic/predict-correction.js +6 -2
- package/dist/tools-logic/predict-correction.js.map +1 -1
- package/dist/tools-logic/recognition-builder.d.ts +9 -0
- package/dist/tools-logic/recognition-builder.d.ts.map +1 -1
- package/dist/tools-logic/recognition-builder.js +5 -3
- package/dist/tools-logic/recognition-builder.js.map +1 -1
- package/dist/tools-logic/resurrect.d.ts +106 -0
- package/dist/tools-logic/resurrect.d.ts.map +1 -0
- package/dist/tools-logic/resurrect.js +561 -0
- package/dist/tools-logic/resurrect.js.map +1 -0
- package/dist/tools-logic/session-start-lite.d.ts +6 -0
- package/dist/tools-logic/session-start-lite.d.ts.map +1 -1
- package/dist/tools-logic/session-start-lite.js +15 -0
- package/dist/tools-logic/session-start-lite.js.map +1 -1
- package/dist/tools-logic/session-start.d.ts +17 -0
- package/dist/tools-logic/session-start.d.ts.map +1 -1
- package/dist/tools-logic/session-start.js +87 -5
- package/dist/tools-logic/session-start.js.map +1 -1
- package/dist/tools-logic/smart-recall.d.ts +9 -4
- package/dist/tools-logic/smart-recall.d.ts.map +1 -1
- package/dist/tools-logic/smart-recall.js +170 -4
- package/dist/tools-logic/smart-recall.js.map +1 -1
- package/dist/types.d.ts +1 -1
- package/dist/types.js +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* hook-health.ts — F5, fail-loud hook health (continuity wave, 2026-07-31).
|
|
3
|
+
*
|
|
4
|
+
* WHY: every hook catch block in the CLI is stderr-only today (index.ts:
|
|
5
|
+
* 932-935, 1079-1082, 1163-1165, 1184-1186) — a hook that silently fails
|
|
6
|
+
* leaves zero persistent trace, so a broken hook can run for weeks before
|
|
7
|
+
* anyone notices a session went unrecorded. This module is the storage layer
|
|
8
|
+
* a future CLI catch-block wiring (Wave-2 integrator) reports failures into.
|
|
9
|
+
*
|
|
10
|
+
* Pattern: same shape as supabase/sync.ts's logSyncError (append + roll@500)
|
|
11
|
+
* and storage/lifecycle-telemetry.ts (best-effort, AR_ROOT-aware, never
|
|
12
|
+
* throws into the caller). Two files:
|
|
13
|
+
* - hook-health.jsonl — append-only failure log, rolled to the last 500
|
|
14
|
+
* lines once it grows past that (same cap/roll contract as sync-errors).
|
|
15
|
+
* - hook-health.json — a small derived STATE snapshot a renderer can read
|
|
16
|
+
* in O(1) without re-parsing the whole JSONL: {last_failure, failures_24h}.
|
|
17
|
+
*
|
|
18
|
+
* Both paths are resolved via getRoot() (AGENT_RECALL_ROOT / setRoot()
|
|
19
|
+
* override-aware) — never os.homedir() directly. This is the same root-fix
|
|
20
|
+
* this wave applied to sync.ts's logSyncError for the identical reason: a
|
|
21
|
+
* hardcoded home-dir path would let test suites pollute the real user's
|
|
22
|
+
* store the same way sync-errors.log did.
|
|
23
|
+
*/
|
|
24
|
+
import * as fs from "node:fs";
|
|
25
|
+
import * as path from "node:path";
|
|
26
|
+
import { getRoot } from "../types.js";
|
|
27
|
+
import { ensureDir, writeJsonAtomic } from "./fs-utils.js";
|
|
28
|
+
const ROLL_LIMIT = 500;
|
|
29
|
+
const WINDOW_MS = 24 * 60 * 60 * 1000; // 24h
|
|
30
|
+
const MESSAGE_CAP = 500; // chars — a hook failure message is a log line, not a dump
|
|
31
|
+
function hookHealthJsonlPath() {
|
|
32
|
+
return path.join(getRoot(), "hook-health.jsonl");
|
|
33
|
+
}
|
|
34
|
+
function hookHealthJsonPath() {
|
|
35
|
+
return path.join(getRoot(), "hook-health.json");
|
|
36
|
+
}
|
|
37
|
+
/** Best-effort string form of an unknown error value. Never throws. */
|
|
38
|
+
function messageOf(err) {
|
|
39
|
+
try {
|
|
40
|
+
if (err instanceof Error)
|
|
41
|
+
return err.message;
|
|
42
|
+
if (typeof err === "string")
|
|
43
|
+
return err;
|
|
44
|
+
return JSON.stringify(err);
|
|
45
|
+
}
|
|
46
|
+
catch {
|
|
47
|
+
return String(err);
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Roll `p` down to its last ROLL_LIMIT non-empty lines once it exceeds that
|
|
52
|
+
* count — same tmp+rename atomic-ish pattern as sync.ts's logSyncError cap.
|
|
53
|
+
* Best-effort: any read/write failure here is swallowed by the caller.
|
|
54
|
+
*/
|
|
55
|
+
function rollJsonl(p) {
|
|
56
|
+
let content;
|
|
57
|
+
try {
|
|
58
|
+
content = fs.readFileSync(p, "utf-8");
|
|
59
|
+
}
|
|
60
|
+
catch {
|
|
61
|
+
return; // file doesn't exist yet (or unreadable) — nothing to roll
|
|
62
|
+
}
|
|
63
|
+
const lines = content.split("\n").filter(Boolean);
|
|
64
|
+
if (lines.length <= ROLL_LIMIT)
|
|
65
|
+
return;
|
|
66
|
+
const trimmed = lines.slice(-ROLL_LIMIT).join("\n") + "\n";
|
|
67
|
+
const tmp = p + ".tmp." + process.pid;
|
|
68
|
+
fs.writeFileSync(tmp, trimmed, "utf-8");
|
|
69
|
+
fs.renameSync(tmp, p);
|
|
70
|
+
}
|
|
71
|
+
/** Parse every well-formed row out of the JSONL file. Skips malformed lines. */
|
|
72
|
+
function readAllRows(p) {
|
|
73
|
+
let content;
|
|
74
|
+
try {
|
|
75
|
+
content = fs.readFileSync(p, "utf-8");
|
|
76
|
+
}
|
|
77
|
+
catch {
|
|
78
|
+
return [];
|
|
79
|
+
}
|
|
80
|
+
const rows = [];
|
|
81
|
+
for (const line of content.split("\n")) {
|
|
82
|
+
const trimmed = line.trim();
|
|
83
|
+
if (!trimmed)
|
|
84
|
+
continue;
|
|
85
|
+
try {
|
|
86
|
+
const row = JSON.parse(trimmed);
|
|
87
|
+
if (row && typeof row.ts === "string" && typeof row.hook === "string" && typeof row.message === "string") {
|
|
88
|
+
rows.push({ ts: row.ts, hook: row.hook, message: row.message });
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
catch {
|
|
92
|
+
// skip malformed line — one bad row must never break the whole read
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
return rows;
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* Count rows whose `ts` falls strictly within the last 24h of `now`.
|
|
99
|
+
*
|
|
100
|
+
* Date logic vs TODAY (Worker Done-Definition #4): a row timestamped in the
|
|
101
|
+
* FUTURE (clock skew, malformed input, or a hostile/buggy caller) must NOT
|
|
102
|
+
* count as "within the last 24h" — it is not in the past at all. Guard with
|
|
103
|
+
* `t <= now` in addition to the window bound, otherwise a future-dated row
|
|
104
|
+
* would render as recent (and even keep counting as "24h fresh" for the next
|
|
105
|
+
* WINDOW_MS milliseconds after `now` catches up to it).
|
|
106
|
+
*/
|
|
107
|
+
function countWithin24h(rows, now) {
|
|
108
|
+
let count = 0;
|
|
109
|
+
for (const row of rows) {
|
|
110
|
+
const t = Date.parse(row.ts);
|
|
111
|
+
if (!Number.isFinite(t))
|
|
112
|
+
continue;
|
|
113
|
+
if (t > now)
|
|
114
|
+
continue; // future-dated — never counted as recent
|
|
115
|
+
if (now - t <= WINDOW_MS)
|
|
116
|
+
count++;
|
|
117
|
+
}
|
|
118
|
+
return count;
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* Record one hook failure. Best-effort: NEVER throws into the caller — a
|
|
122
|
+
* failure to record a failure must not compound into a second failure.
|
|
123
|
+
*/
|
|
124
|
+
export function recordHookFailure(hook, err) {
|
|
125
|
+
try {
|
|
126
|
+
const root = getRoot();
|
|
127
|
+
ensureDir(root);
|
|
128
|
+
const jsonlPath = hookHealthJsonlPath();
|
|
129
|
+
const row = {
|
|
130
|
+
ts: new Date().toISOString(),
|
|
131
|
+
hook,
|
|
132
|
+
message: messageOf(err).slice(0, MESSAGE_CAP),
|
|
133
|
+
};
|
|
134
|
+
fs.appendFileSync(jsonlPath, JSON.stringify(row) + "\n", "utf-8");
|
|
135
|
+
rollJsonl(jsonlPath);
|
|
136
|
+
// Recompute failures_24h from the (now-rolled) log so the derived state
|
|
137
|
+
// file always reflects what's actually on disk, not a running counter
|
|
138
|
+
// that could drift from it across process restarts.
|
|
139
|
+
const rows = readAllRows(jsonlPath);
|
|
140
|
+
const state = {
|
|
141
|
+
last_failure: row,
|
|
142
|
+
failures_24h: countWithin24h(rows, Date.now()),
|
|
143
|
+
};
|
|
144
|
+
writeJsonAtomic(hookHealthJsonPath(), state);
|
|
145
|
+
}
|
|
146
|
+
catch {
|
|
147
|
+
// NEVER throw — hook health recording must not break the hook it reports on.
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
/**
|
|
151
|
+
* Read the derived hook health state for renderers (Wave-2's `ar health` /
|
|
152
|
+
* hook-start ⚠️ line). Never throws — returns a zeroed/empty state on any
|
|
153
|
+
* read error (missing file, corrupt JSON) so a renderer never needs its own
|
|
154
|
+
* try/catch around this call.
|
|
155
|
+
*/
|
|
156
|
+
export function readHookHealth() {
|
|
157
|
+
try {
|
|
158
|
+
const p = hookHealthJsonPath();
|
|
159
|
+
if (!fs.existsSync(p)) {
|
|
160
|
+
return { last_failure: null, failures_24h: 0 };
|
|
161
|
+
}
|
|
162
|
+
const raw = fs.readFileSync(p, "utf-8");
|
|
163
|
+
const parsed = JSON.parse(raw);
|
|
164
|
+
const lastFailure = parsed.last_failure;
|
|
165
|
+
const validLastFailure = lastFailure &&
|
|
166
|
+
typeof lastFailure === "object" &&
|
|
167
|
+
typeof lastFailure.ts === "string" &&
|
|
168
|
+
typeof lastFailure.hook === "string" &&
|
|
169
|
+
typeof lastFailure.message === "string"
|
|
170
|
+
? { ts: lastFailure.ts, hook: lastFailure.hook, message: lastFailure.message }
|
|
171
|
+
: null;
|
|
172
|
+
return {
|
|
173
|
+
last_failure: validLastFailure,
|
|
174
|
+
failures_24h: typeof parsed.failures_24h === "number" && Number.isFinite(parsed.failures_24h)
|
|
175
|
+
? parsed.failures_24h
|
|
176
|
+
: 0,
|
|
177
|
+
};
|
|
178
|
+
}
|
|
179
|
+
catch {
|
|
180
|
+
return { last_failure: null, failures_24h: 0 };
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
//# sourceMappingURL=hook-health.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"hook-health.js","sourceRoot":"","sources":["../../src/storage/hook-health.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* hygiene.ts — DETECTION-ONLY store trash audit ("ar hygiene").
|
|
3
|
+
*
|
|
4
|
+
* Sibling to store-doctor.ts, but a different axis:
|
|
5
|
+
* - store-doctor = STRUCTURAL integrity (index drift, stale locks, stalled
|
|
6
|
+
* consolidation seam, orphaned markers, ledger divergence).
|
|
7
|
+
* - hygiene = STORE TRASH (junk project dirs, unbounded counter files,
|
|
8
|
+
* recurring-theme epidemics, case-fold forks, stale derived caches,
|
|
9
|
+
* leaked-secret-shaped strings, missing materialized indexes, reserved-
|
|
10
|
+
* word slug collisions).
|
|
11
|
+
*
|
|
12
|
+
* HARD INVARIANTS (owner-approved 2026-07-27):
|
|
13
|
+
* 1. Scan != clean. `runHygieneScan` NEVER deletes, renames, or quarantines
|
|
14
|
+
* anything — findings only. No mkdir, no unlink, no rename, no write of
|
|
15
|
+
* any kind. Only fs reads (existsSync/readdirSync/readFileSync/statSync).
|
|
16
|
+
* 2. The ONLY write this module ever performs is its own baseline file
|
|
17
|
+
* (`hygiene-baseline.json`), and ONLY via the explicit `updateBaseline`
|
|
18
|
+
* call — never as a side effect of scanning or of `applyBaseline`.
|
|
19
|
+
* 3. Each check runs independently try/caught inside `runHygieneScan` — one
|
|
20
|
+
* failing check (unreadable dir, permissions, malformed file) degrades
|
|
21
|
+
* that check to zero findings; it never kills the whole scan.
|
|
22
|
+
* 4. `runHygieneScan(root)` is PURE with respect to global state: unlike
|
|
23
|
+
* store-doctor.ts (which reads the process-global root via getRoot()),
|
|
24
|
+
* every path here is built from the explicit `root` parameter. This is
|
|
25
|
+
* deliberate — it lets tests exercise the scanner against a temp
|
|
26
|
+
* directory without mutating (or restoring) any global root state.
|
|
27
|
+
*
|
|
28
|
+
* Baseline: without one, every pre-existing finding (e.g. ~985 stray counter
|
|
29
|
+
* files) would resurface on every run and drown out anything NEW. The first
|
|
30
|
+
* invocation of `ar hygiene --baseline-update` snapshots every current
|
|
31
|
+
* finding's `stable_id`; subsequent bare `ar hygiene` runs report only
|
|
32
|
+
* findings whose `stable_id` is NOT in that snapshot ("fresh"), plus a
|
|
33
|
+
* one-line count of how many are already known.
|
|
34
|
+
*/
|
|
35
|
+
export type HygieneSeverity = "red" | "yellow";
|
|
36
|
+
export type HygieneGrade = "clean" | "yellow" | "red";
|
|
37
|
+
export interface HygieneFinding {
|
|
38
|
+
/** Stable machine name of the check that produced this finding. */
|
|
39
|
+
check: string;
|
|
40
|
+
severity: HygieneSeverity;
|
|
41
|
+
/**
|
|
42
|
+
* A locator for the finding. Usually a store-root-relative path
|
|
43
|
+
* ("projects/<slug>", "foo-cache.json#L12"), but for an AGGREGATE finding
|
|
44
|
+
* (counter-accumulation) this is a symbolic glob ".ambient-counter-*"
|
|
45
|
+
* rather than a real filesystem path — it never varies with which specific
|
|
46
|
+
* files exist, so the finding's identity stays stable across baseline runs.
|
|
47
|
+
*/
|
|
48
|
+
path: string;
|
|
49
|
+
/** Human-readable evidence. NEVER contains raw secret text (see check f). */
|
|
50
|
+
evidence: string;
|
|
51
|
+
/** sha256(check + ":" + path).slice(0, 16) — baseline identity. */
|
|
52
|
+
stable_id: string;
|
|
53
|
+
/** What an agent should do about this finding. Never instructs auto-delete. */
|
|
54
|
+
agent_instruction: string;
|
|
55
|
+
}
|
|
56
|
+
export interface HygieneScanResult {
|
|
57
|
+
findings: HygieneFinding[];
|
|
58
|
+
grade: HygieneGrade;
|
|
59
|
+
/** Number of findings per check name (0 for a check that found nothing). */
|
|
60
|
+
counts: Record<string, number>;
|
|
61
|
+
}
|
|
62
|
+
export interface HygieneBaseline {
|
|
63
|
+
created_at: string;
|
|
64
|
+
/** Sorted, de-duplicated stable_ids known at the time of the last update. */
|
|
65
|
+
stable_ids: string[];
|
|
66
|
+
}
|
|
67
|
+
export interface ApplyBaselineResult {
|
|
68
|
+
/** Findings whose stable_id is NOT in the baseline — report prominently. */
|
|
69
|
+
fresh: HygieneFinding[];
|
|
70
|
+
/** Findings whose stable_id IS in the baseline — report as a one-line count. */
|
|
71
|
+
known: HygieneFinding[];
|
|
72
|
+
}
|
|
73
|
+
/** The baseline file lives at the store root, alongside `projects/`. */
|
|
74
|
+
export declare const HYGIENE_BASELINE_FILENAME = "hygiene-baseline.json";
|
|
75
|
+
export declare function hygieneBaselinePath(root: string): string;
|
|
76
|
+
/**
|
|
77
|
+
* Pure mapping from case-variant fork groups (as returned by
|
|
78
|
+
* `listCaseVariantForks`) to HygieneFinding objects. Extracted for fs-free
|
|
79
|
+
* testability — real case-variant sibling directories cannot be fabricated on
|
|
80
|
+
* a case-insensitive-but-case-preserving filesystem (macOS APFS default: a
|
|
81
|
+
* second `mkdirSync("agentrecall")` silently collides with an existing
|
|
82
|
+
* "AgentRecall"). Same constraint documented on `pickProjectDirEntry` in
|
|
83
|
+
* paths.ts; same fix (test the pure mapping directly). Not part of the
|
|
84
|
+
* public core barrel — internal/test-only export.
|
|
85
|
+
*/
|
|
86
|
+
export declare function caseFoldForksToFindings(forks: Array<{
|
|
87
|
+
project: string;
|
|
88
|
+
variants: string[];
|
|
89
|
+
}>): HygieneFinding[];
|
|
90
|
+
/**
|
|
91
|
+
* Run every hygiene check against `root`. READ-ONLY: never writes, never
|
|
92
|
+
* mkdirs, never renames, never acquires a lock. Each check is independently
|
|
93
|
+
* try/caught — one failing check degrades to zero findings for that check,
|
|
94
|
+
* never throws out of the scan as a whole.
|
|
95
|
+
*/
|
|
96
|
+
export declare function runHygieneScan(root: string): HygieneScanResult;
|
|
97
|
+
/**
|
|
98
|
+
* Partition `findings` into `fresh` (stable_id NOT in the baseline) and
|
|
99
|
+
* `known` (stable_id IS in the baseline). READ-ONLY — only reads the
|
|
100
|
+
* baseline file; never writes it. Missing/malformed baseline degrades to
|
|
101
|
+
* "everything is fresh" (the honest first-run state).
|
|
102
|
+
*/
|
|
103
|
+
export declare function applyBaseline(findings: HygieneFinding[], baselinePath: string): ApplyBaselineResult;
|
|
104
|
+
/**
|
|
105
|
+
* Snapshot every current finding's stable_id into the baseline file. This is
|
|
106
|
+
* the ONLY write this module ever performs, and it only happens when a
|
|
107
|
+
* caller explicitly invokes this function (CLI: `ar hygiene --baseline-update`).
|
|
108
|
+
* Atomic (tmp + rename), mode 0600.
|
|
109
|
+
*/
|
|
110
|
+
export declare function updateBaseline(findings: HygieneFinding[], baselinePath: string): HygieneBaseline;
|
|
111
|
+
//# sourceMappingURL=hygiene.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"hygiene.d.ts","sourceRoot":"","sources":["../../src/storage/hygiene.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAqBH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,QAAQ,CAAC;AAC/C,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,gFAAgF;IAChF,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB;AAMD,wEAAwE;AACxE,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AAEjE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAsND;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,GACpD,cAAc,EAAE,CAUlB;AAwJD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CA8B9D;AAiBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG,mBAAmB,CASnG;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,cAAc,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG,eAAe,CAQhG"}
|