plasalid 0.5.8 → 0.6.0

package/dist/scanner/detectors/duplicates.js

@@ -0,0 +1,75 @@
+import { findDuplicateTransactions } from "../../db/queries/transactions.js";
+import { formatAmount } from "../../currency.js";
+/**
+ * Surface transaction pairs that look like the same posting recorded twice.
+ * One concern is emitted per duplicate group, attached to the newest member;
+ * earlier members are listed in the prompt so the user can compare side by
+ * side. Only groups that include at least one transaction from this scan run
+ * are surfaced — older-only groups would have been flagged on a prior run.
+ *
+ * Members are pruned before grouping: two transactions sharing source_file_id,
+ * date, and merchant_id are almost always two real charges (the statement
+ * legitimately lists Starbucks twice on the same day) and surface as noise.
+ */
+function detect(db, scope) {
+    if (scope.fileIds.length === 0)
+        return [];
+    const groups = findDuplicateTransactions(db);
+    if (groups.length === 0)
+        return [];
+    const inScope = transactionsInScope(db, scope.fileIds);
+    const out = [];
+    for (const rawGroup of groups) {
+        const group = dedupeSameFileSameDaySameMerchant(rawGroup);
+        if (group.length < 2)
+            continue;
+        if (!group.some(g => inScope.has(g.id)))
+            continue;
+        const sorted = [...group].sort((a, b) => a.date.localeCompare(b.date));
+        const newest = sorted[sorted.length - 1];
+        const others = sorted.slice(0, -1);
+        out.push({
+            file_id: null,
+            transaction_id: newest.id,
+            account_id: null,
+            kind: "duplicate",
+            prompt: buildPrompt(newest, others),
+            options: ["Delete this one", "Delete the older one", "Keep both", "Skip"],
+        });
+    }
+    return out;
+}
+/**
+ * Collapse same-file, same-date, same-merchant transactions to a single
+ * representative so they don't trigger a "duplicate" concern between
+ * themselves. (Across files or across dates is still flagged.)
+ */
+function dedupeSameFileSameDaySameMerchant(group) {
+    const seen = new Map();
+    for (const tx of group) {
+        if (tx.source_file_id == null) {
+            seen.set(tx.id, tx);
+            continue;
+        }
+        const key = `${tx.source_file_id}|${tx.date}|${tx.merchant_id ?? ""}`;
+        if (!seen.has(key))
+            seen.set(key, tx);
+    }
+    return Array.from(seen.values());
+}
+function buildPrompt(newest, others) {
+    const amount = formatAmount(newest.amount);
+    const lines = [
+        `${amount} on ${newest.date} (${newest.description}) — accounts: ${newest.account_names.join(", ")}`,
+        ...others.map(o => `  matches ${o.date} (${o.description}) — accounts: ${o.account_names.join(", ")}`),
+    ];
+    return `Possible duplicate transaction.\n${lines.join("\n")}`;
+}
+function transactionsInScope(db, fileIds) {
+    const placeholders = fileIds.map(() => "?").join(",");
+    const rows = db
+        .prepare(`SELECT id FROM transactions WHERE source_file_id IN (${placeholders})`)
+        .all(...fileIds);
+    return new Set(rows.map(r => r.id));
+}
+export const duplicatesDetector = { name: "duplicates", detect };

package/dist/scanner/detectors/index.d.ts

@@ -0,0 +1,18 @@
+import type Database from "libsql";
+import type { Detector, DetectorScope } from "./types.js";
+/**
+ * The ordered list of post-commit detectors the scanner runs. Order matters
+ * only for the resolver's priority sweep, not for correctness — each detector
+ * emits concerns independently of the others.
+ */
+export declare const detectors: readonly Detector[];
+export interface DetectionRunResult {
+    total: number;
+    byDetector: Record<string, number>;
+}
+/**
+ * Run every detector in order and insert any concerns they produce. Returns
+ * counts so the CLI can report "X concerns surfaced." Failure of one detector
+ * never aborts the run — it logs and the others still execute.
+ */
+export declare function runDetectors(db: Database.Database, scope: DetectorScope): DetectionRunResult;

package/dist/scanner/detectors/index.js

@@ -0,0 +1,39 @@
+import { recordConcern } from "../../db/queries/concerns.js";
+import { duplicatesDetector } from "./duplicates.js";
+import { correlationsDetector } from "./correlations.js";
+import { recurrencesDetector } from "./recurrences.js";
+import { similarAccountsDetector } from "./similarities.js";
+/**
+ * The ordered list of post-commit detectors the scanner runs. Order matters
+ * only for the resolver's priority sweep, not for correctness — each detector
+ * emits concerns independently of the others.
+ */
+export const detectors = [
+    duplicatesDetector,
+    correlationsDetector,
+    recurrencesDetector,
+    similarAccountsDetector,
+];
+/**
+ * Run every detector in order and insert any concerns they produce. Returns
+ * counts so the CLI can report "X concerns surfaced." Failure of one detector
+ * never aborts the run — it logs and the others still execute.
+ */
+export function runDetectors(db, scope) {
+    const byDetector = {};
+    let total = 0;
+    for (const detector of detectors) {
+        try {
+            const concerns = detector.detect(db, scope);
+            for (const c of concerns)
+                recordConcern(db, c);
+            byDetector[detector.name] = concerns.length;
+            total += concerns.length;
+        }
+        catch (err) {
+            byDetector[detector.name] = 0;
+            console.error(`[detector ${detector.name}] ${err?.message ?? err}`);
+        }
+    }
+    return { total, byDetector };
+}

package/dist/scanner/detectors/recurrences.d.ts

@@ -0,0 +1,2 @@
+import type { Detector } from "./types.js";
+export declare const recurrencesDetector: Detector;

package/dist/scanner/detectors/recurrences.js

@@ -0,0 +1,49 @@
+import { findRecurrenceCandidates } from "../../db/queries/recurrences.js";
+import { formatAmount } from "../../currency.js";
+/**
+ * Surface recurrence candidates whose latest sighting landed in this scan run.
+ * One concern per candidate, attached to the most recent transaction in the
+ * group. Skips candidates whose median interval is "irregular" — those are
+ * unlikely to be real subscriptions and surfacing them just creates noise.
+ */
+function detect(db, scope) {
+    if (scope.fileIds.length === 0)
+        return [];
+    const candidates = findRecurrenceCandidates(db);
+    if (candidates.length === 0)
+        return [];
+    const inScope = transactionsInScope(db, scope.fileIds);
+    const out = [];
+    for (const candidate of candidates) {
+        if (candidate.implied_frequency === "irregular")
+            continue;
+        const latest = candidate.transactions[candidate.transactions.length - 1];
+        if (!inScope.has(latest.id))
+            continue;
+        out.push({
+            file_id: null,
+            transaction_id: latest.id,
+            account_id: candidate.account_id,
+            kind: "recurrence_candidate",
+            prompt: buildPrompt(candidate, latest),
+            options: ["Link as recurring", "Not recurring", "Skip"],
+        });
+    }
+    return out;
+}
+function buildPrompt(candidate, latest) {
+    const amount = formatAmount(candidate.amount, candidate.currency);
+    const occurrences = candidate.transactions.length;
+    return [
+        `Possible ${candidate.implied_frequency} recurrence on ${candidate.account_name}: ${amount} (${occurrences} sightings, median ${candidate.median_days_between} days apart).`,
+        `Latest: ${latest.date} — ${latest.description}`,
+    ].join("\n");
+}
+function transactionsInScope(db, fileIds) {
+    const placeholders = fileIds.map(() => "?").join(",");
+    const rows = db
+        .prepare(`SELECT id FROM transactions WHERE source_file_id IN (${placeholders})`)
+        .all(...fileIds);
+    return new Set(rows.map(r => r.id));
+}
+export const recurrencesDetector = { name: "recurrences", detect };

package/dist/scanner/detectors/similar_accounts.d.ts

@@ -0,0 +1,2 @@
+import type { Detector } from "./types.js";
+export declare const similarAccountsDetector: Detector;

package/dist/scanner/detectors/similar_accounts.js

@@ -0,0 +1,64 @@
+import { findSimilarAccounts } from "../../db/queries/account_balance.js";
+/**
+ * Flag pairs of accounts whose names are near-identical (Levenshtein ≥ 0.85).
+ * Runs whenever a scan committed at least one transaction — the assumption is
+ * that the scanner may have created a new account this run, so it's worth a
+ * fresh similarity sweep. Idempotent against existing open concerns: a pair
+ * already flagged is not flagged again. The resolver applies "Merge A into B"
+ * via merge_accounts.
+ */
+function detect(db, scope) {
+    if (scope.fileIds.length === 0)
+        return [];
+    const pairs = findSimilarAccounts(db);
+    if (pairs.length === 0)
+        return [];
+    const alreadyFlagged = loadAlreadyFlaggedAccountPairs(db);
+    const out = [];
+    for (const pair of pairs) {
+        const key = pairKey(pair.a.id, pair.b.id);
+        if (alreadyFlagged.has(key))
+            continue;
+        out.push({
+            file_id: null,
+            transaction_id: null,
+            account_id: pair.a.id,
+            kind: "similar_accounts",
+            prompt: `These two accounts look like the same thing (similarity ${pair.similarity}):\n  ${pair.a.id} — ${pair.a.name}\n  ${pair.b.id} — ${pair.b.name}`,
+            options: [`Merge ${pair.b.id} into ${pair.a.id}`, `Merge ${pair.a.id} into ${pair.b.id}`, "Keep separate", "Skip"],
+        });
+    }
+    return out;
+}
+/**
+ * Open `similar_accounts` concerns embed the other account's id in their
+ * options strings ("Merge X into Y"). Parse those out so we don't re-flag a
+ * pair the user has already seen but not yet answered.
+ */
+function loadAlreadyFlaggedAccountPairs(db) {
+    const rows = db
+        .prepare(`SELECT account_id, options_json FROM concerns
+       WHERE resolved_at IS NULL AND kind = 'similar_accounts' AND account_id IS NOT NULL`)
+        .all();
+    const out = new Set();
+    for (const row of rows) {
+        if (!row.options_json)
+            continue;
+        try {
+            const options = JSON.parse(row.options_json);
+            for (const opt of options) {
+                const match = opt.match(/Merge (\S+) into (\S+)/);
+                if (match)
+                    out.add(pairKey(match[1], match[2]));
+            }
+        }
+        catch {
+            // skip malformed options_json
+        }
+    }
+    return out;
+}
+function pairKey(a, b) {
+    return [a, b].sort().join("|");
+}
+export const similarAccountsDetector = { name: "similar_accounts", detect };

package/dist/scanner/detectors/similarities.d.ts

@@ -0,0 +1,2 @@
+import type { Detector } from "./types.js";
+export declare const similarAccountsDetector: Detector;

package/dist/scanner/detectors/similarities.js

@@ -0,0 +1,73 @@
+import { findSimilarAccounts } from "../../db/queries/account-balance.js";
+/**
+ * Flag pairs of accounts whose names are near-identical (Levenshtein ≥ 0.85).
+ * Runs whenever a scan committed at least one transaction — the assumption is
+ * that the scanner may have created a new account this run, so it's worth a
+ * fresh similarity sweep. Idempotent against existing open concerns: a pair
+ * already flagged is not flagged again. The resolver applies "Merge A into B"
+ * via merge_accounts.
+ */
+function detect(db, scope) {
+    if (scope.fileIds.length === 0)
+        return [];
+    const pairs = findSimilarAccounts(db);
+    if (pairs.length === 0)
+        return [];
+    const alreadyFlagged = loadAlreadyFlaggedAccountPairs(db);
+    const out = [];
+    for (const pair of pairs) {
+        const key = pairKey(pair.a.id, pair.b.id);
+        if (alreadyFlagged.has(key))
+            continue;
+        out.push({
+            file_id: null,
+            transaction_id: null,
+            account_id: pair.a.id,
+            kind: "similar_accounts",
+            prompt: `These two accounts look like the same thing (similarity ${pair.similarity}):\n  ${pair.a.id} — ${pair.a.name}\n  ${pair.b.id} — ${pair.b.name}`,
+            options: [
+                `Merge ${pair.b.id} into ${pair.a.id}`,
+                `Merge ${pair.a.id} into ${pair.b.id}`,
+                "Keep separate",
+                "Skip",
+            ],
+        });
+    }
+    return out;
+}
+/**
+ * `similar_accounts` concerns (open OR resolved) embed the other account's id
+ * in their options strings ("Merge X into Y"). Parse those out so we don't
+ * re-flag a pair the user has already seen — including pairs they've already
+ * answered "Keep separate" on a prior run.
+ */
+function loadAlreadyFlaggedAccountPairs(db) {
+    const rows = db
+        .prepare(`SELECT account_id, options_json FROM concerns
+       WHERE kind = 'similar_accounts' AND account_id IS NOT NULL`)
+        .all();
+    const out = new Set();
+    for (const row of rows) {
+        if (!row.options_json)
+            continue;
+        try {
+            const options = JSON.parse(row.options_json);
+            for (const opt of options) {
+                const match = opt.match(/Merge (\S+) into (\S+)/);
+                if (match)
+                    out.add(pairKey(match[1], match[2]));
+            }
+        }
+        catch {
+            // skip malformed options_json
+        }
+    }
+    return out;
+}
+function pairKey(a, b) {
+    return [a, b].sort().join("|");
+}
+export const similarAccountsDetector = {
+    name: "similar_accounts",
+    detect,
+};

package/dist/scanner/detectors/types.d.ts

@@ -0,0 +1,16 @@
+import type Database from "libsql";
+import type { RecordConcernInput } from "../../db/queries/concerns.js";
+/**
+ * Scope passed to every detector by the scanner's Phase 5. Detectors emit
+ * concerns for transactions whose `source_file_id` is in `fileIds` (or for
+ * cross-pair findings where at least one side lives in that set). Detectors
+ * are free to read the wider DB for context — the scope is a filter for what
+ * to surface, not a limit on what to read.
+ */
+export interface DetectorScope {
+    readonly fileIds: readonly string[];
+}
+export interface Detector {
+    readonly name: string;
+    detect(db: Database.Database, scope: DetectorScope): RecordConcernInput[];
+}

package/dist/scanner/detectors/types.js

@@ -0,0 +1 @@
+export {};

package/dist/scanner/inspectors/correlations.d.ts

@@ -0,0 +1,2 @@
+import type { Inspector } from "./types.js";
+export declare const correlationsInspector: Inspector;

package/dist/scanner/inspectors/correlations.js

@@ -0,0 +1,47 @@
+import { findCorrelatedTransactions } from "../../db/queries/transactions.js";
+import { formatAmount } from "../../currency.js";
+/**
+ * Cross-account correlation: a single money movement that landed on two
+ * different accounts (e.g. transfer from bank to card recorded once per
+ * statement). One unknown per pair, attached to the newer side. Only pairs
+ * with at least one side in `fileIds` are surfaced.
+ */
+function inspect(db, scope) {
+    if (scope.fileIds.length === 0)
+        return [];
+    const pairs = findCorrelatedTransactions(db);
+    if (pairs.length === 0)
+        return [];
+    const inScope = transactionsInScope(db, scope.fileIds);
+    const out = [];
+    for (const pair of pairs) {
+        if (!inScope.has(pair.a.id) && !inScope.has(pair.b.id))
+            continue;
+        const [older, newer] = pair.a.date <= pair.b.date ? [pair.a, pair.b] : [pair.b, pair.a];
+        out.push({
+            file_id: null,
+            transaction_id: newer.id,
+            account_id: null,
+            kind: "correlation",
+            prompt: buildPrompt(pair, older, newer),
+            options: ["Merge into one transaction", "Keep separate (these are two real events)", "Skip"],
+        });
+    }
+    return out;
+}
+function buildPrompt(pair, older, newer) {
+    const amount = formatAmount(pair.amount, pair.currency);
+    return [
+        `Possible cross-account correlation (${amount}, ${pair.day_gap} day(s) apart).`,
+        `  ${newer.date} — ${newer.description} — ${newer.account_names.join(", ")}`,
+        `  ${older.date} — ${older.description} — ${older.account_names.join(", ")}`,
+    ].join("\n");
+}
+function transactionsInScope(db, fileIds) {
+    const placeholders = fileIds.map(() => "?").join(",");
+    const rows = db
+        .prepare(`SELECT id FROM transactions WHERE source_file_id IN (${placeholders})`)
+        .all(...fileIds);
+    return new Set(rows.map(r => r.id));
+}
+export const correlationsInspector = { name: "correlations", inspect };

package/dist/scanner/inspectors/duplicates.d.ts

@@ -0,0 +1,2 @@
+import type { Inspector } from "./types.js";
+export declare const duplicatesInspector: Inspector;

package/dist/scanner/inspectors/duplicates.js

@@ -0,0 +1,75 @@
+import { findDuplicateTransactions } from "../../db/queries/transactions.js";
+import { formatAmount } from "../../currency.js";
+/**
+ * Surface transaction pairs that look like the same posting recorded twice.
+ * One unknown is emitted per duplicate group, attached to the newest member;
+ * earlier members are listed in the prompt so the user can compare side by
+ * side. Only groups that include at least one transaction from this scan run
+ * are surfaced — older-only groups would have been flagged on a prior run.
+ *
+ * Members are pruned before grouping: two transactions sharing source_file_id,
+ * date, and merchant_id are almost always two real charges (the statement
+ * legitimately lists Starbucks twice on the same day) and surface as noise.
+ */
+function inspect(db, scope) {
+    if (scope.fileIds.length === 0)
+        return [];
+    const groups = findDuplicateTransactions(db);
+    if (groups.length === 0)
+        return [];
+    const inScope = transactionsInScope(db, scope.fileIds);
+    const out = [];
+    for (const rawGroup of groups) {
+        const group = dedupeSameFileSameDaySameMerchant(rawGroup);
+        if (group.length < 2)
+            continue;
+        if (!group.some(g => inScope.has(g.id)))
+            continue;
+        const sorted = [...group].sort((a, b) => a.date.localeCompare(b.date));
+        const newest = sorted[sorted.length - 1];
+        const others = sorted.slice(0, -1);
+        out.push({
+            file_id: null,
+            transaction_id: newest.id,
+            account_id: null,
+            kind: "duplicate",
+            prompt: buildPrompt(newest, others),
+            options: ["Delete this one", "Delete the older one", "Keep both", "Skip"],
+        });
+    }
+    return out;
+}
+/**
+ * Collapse same-file, same-date, same-merchant transactions to a single
+ * representative so they don't trigger a "duplicate" unknown between
+ * themselves. (Across files or across dates is still flagged.)
+ */
+function dedupeSameFileSameDaySameMerchant(group) {
+    const seen = new Map();
+    for (const tx of group) {
+        if (tx.source_file_id == null) {
+            seen.set(tx.id, tx);
+            continue;
+        }
+        const key = `${tx.source_file_id}|${tx.date}|${tx.merchant_id ?? ""}`;
+        if (!seen.has(key))
+            seen.set(key, tx);
+    }
+    return Array.from(seen.values());
+}
+function buildPrompt(newest, others) {
+    const amount = formatAmount(newest.amount);
+    const lines = [
+        `${amount} on ${newest.date} (${newest.description}) — accounts: ${newest.account_names.join(", ")}`,
+        ...others.map(o => `  matches ${o.date} (${o.description}) — accounts: ${o.account_names.join(", ")}`),
+    ];
+    return `Possible duplicate transaction.\n${lines.join("\n")}`;
+}
+function transactionsInScope(db, fileIds) {
+    const placeholders = fileIds.map(() => "?").join(",");
+    const rows = db
+        .prepare(`SELECT id FROM transactions WHERE source_file_id IN (${placeholders})`)
+        .all(...fileIds);
+    return new Set(rows.map(r => r.id));
+}
+export const duplicatesInspector = { name: "duplicates", inspect };

package/dist/scanner/inspectors/index.d.ts

@@ -0,0 +1,19 @@
+import type Database from "libsql";
+import type { Inspector, InspectorScope } from "./types.js";
+export type { Inspector, InspectorScope } from "./types.js";
+/**
+ * The ordered list of post-commit inspectors the scanner runs. Order matters
+ * only for the resolver's priority sweep, not for correctness — each inspector
+ * emits unknowns independently of the others.
+ */
+export declare const inspectors: readonly Inspector[];
+export interface InspectionRunResult {
+    total: number;
+    byInspector: Record<string, number>;
+}
+/**
+ * Run every inspector in order and insert any unknowns they produce. Returns
+ * counts so the CLI can report "X unknowns surfaced." Failure of one inspector
+ * never aborts the run — it logs and the others still execute.
+ */
+export declare function runInspectors(db: Database.Database, scope: InspectorScope): InspectionRunResult;

package/dist/scanner/inspectors/index.js

@@ -0,0 +1,39 @@
+import { recordUnknown } from "../../db/queries/unknowns.js";
+import { duplicatesInspector } from "./duplicates.js";
+import { correlationsInspector } from "./correlations.js";
+import { recurrencesInspector } from "./recurrences.js";
+import { similarAccountsInspector } from "./similarities.js";
+/**
+ * The ordered list of post-commit inspectors the scanner runs. Order matters
+ * only for the resolver's priority sweep, not for correctness — each inspector
+ * emits unknowns independently of the others.
+ */
+export const inspectors = [
+    duplicatesInspector,
+    correlationsInspector,
+    recurrencesInspector,
+    similarAccountsInspector,
+];
+/**
+ * Run every inspector in order and insert any unknowns they produce. Returns
+ * counts so the CLI can report "X unknowns surfaced." Failure of one inspector
+ * never aborts the run — it logs and the others still execute.
+ */
+export function runInspectors(db, scope) {
+    const byInspector = {};
+    let total = 0;
+    for (const inspector of inspectors) {
+        try {
+            const unknowns = inspector.inspect(db, scope);
+            for (const u of unknowns)
+                recordUnknown(db, u);
+            byInspector[inspector.name] = unknowns.length;
+            total += unknowns.length;
+        }
+        catch (err) {
+            byInspector[inspector.name] = 0;
+            console.error(`[inspector ${inspector.name}] ${err?.message ?? err}`);
+        }
+    }
+    return { total, byInspector };
+}

package/dist/scanner/inspectors/recurrences.d.ts

@@ -0,0 +1,2 @@
+import type { Inspector } from "./types.js";
+export declare const recurrencesInspector: Inspector;

package/dist/scanner/inspectors/recurrences.js

@@ -0,0 +1,49 @@
+import { findRecurrenceCandidates } from "../../db/queries/recurrences.js";
+import { formatAmount } from "../../currency.js";
+/**
+ * Surface recurrence candidates whose latest sighting landed in this scan run.
+ * One unknown per candidate, attached to the most recent transaction in the
+ * group. Skips candidates whose median interval is "irregular" — those are
+ * unlikely to be real subscriptions and surfacing them just creates noise.
+ */
+function inspect(db, scope) {
+    if (scope.fileIds.length === 0)
+        return [];
+    const candidates = findRecurrenceCandidates(db);
+    if (candidates.length === 0)
+        return [];
+    const inScope = transactionsInScope(db, scope.fileIds);
+    const out = [];
+    for (const candidate of candidates) {
+        if (candidate.implied_frequency === "irregular")
+            continue;
+        const latest = candidate.transactions[candidate.transactions.length - 1];
+        if (!inScope.has(latest.id))
+            continue;
+        out.push({
+            file_id: null,
+            transaction_id: latest.id,
+            account_id: candidate.account_id,
+            kind: "recurrence_candidate",
+            prompt: buildPrompt(candidate, latest),
+            options: ["Link as recurring", "Not recurring", "Skip"],
+        });
+    }
+    return out;
+}
+function buildPrompt(candidate, latest) {
+    const amount = formatAmount(candidate.amount, candidate.currency);
+    const occurrences = candidate.transactions.length;
+    return [
+        `Possible ${candidate.implied_frequency} recurrence on ${candidate.account_name}: ${amount} (${occurrences} sightings, median ${candidate.median_days_between} days apart).`,
+        `Latest: ${latest.date} — ${latest.description}`,
+    ].join("\n");
+}
+function transactionsInScope(db, fileIds) {
+    const placeholders = fileIds.map(() => "?").join(",");
+    const rows = db
+        .prepare(`SELECT id FROM transactions WHERE source_file_id IN (${placeholders})`)
+        .all(...fileIds);
+    return new Set(rows.map(r => r.id));
+}
+export const recurrencesInspector = { name: "recurrences", inspect };

package/dist/scanner/inspectors/similarities.d.ts

@@ -0,0 +1,2 @@
+import type { Inspector } from "./types.js";
+export declare const similarAccountsInspector: Inspector;