SQLite cache bootstrap + single-issue mirror upsert (#3)
A rebuildable local mirror of the reconciled backlog — an index over gitea's durable truth, never the source of truth (D4). This lands the core seam: - `cache/cache-v0.ts`: the 5-table schema (issues/labels/milestones/comments/ issue_events), a `CacheDriver` injected-IO interface (exec/run/get/all), and pure row<->domain mappers. `upsertIssue` mirrors one issue (+ its milestone), upsert-by-number so a re-reconcile updates in place; `readIssue` re-derives `facts` from the stored label set via extractLabelFacts, so the mirror can't drift from the label semantics. Facts are never stored. - Resolves #3's open scope: pure mappers + SQL in core (driver-agnostic), native driver in main. Tests bind node:sqlite (present in the Node 24 test runtime) to the same CacheDriver seam better-sqlite3 will fill in main. Acceptance met: upsert one reconciled issue, read back, assert estimateDays/priority/hardDeadline (+ upsert-in-place, no-milestone, and miss cases). Core suite green; typecheck clean. Follow-up (noted in the plan): the main-process better-sqlite3 adapter + snapshot-store migration — packaging-sensitive (native module), kept out of this slice so the shippable .dmg stays verified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Croissant Le Doux
159
packages/core/src/cache/cache-v0.ts
vendored
Normal file
159
packages/core/src/cache/cache-v0.ts
vendored
Normal file
@@ -0,0 +1,159 @@
|
||||
/**
|
||||
* SQLite cache, v0 (#3) — a rebuildable local mirror of the reconciled backlog.
|
||||
* It is an index over the durable truth in gitea, never the source of truth (D4):
|
||||
* delete it, resync, lose nothing. This module owns the schema + the pure
|
||||
* row<->domain mappers; the actual SQLite handle is injected as a `CacheDriver`,
|
||||
* so core stays free of any native driver (better-sqlite3 lives in main; tests
|
||||
* use node:sqlite). Facts are never stored — they are re-derived from the label
|
||||
* set on read via `extractLabelFacts`, so the mirror can't drift from the label
|
||||
* semantics.
|
||||
*/
|
||||
|
||||
import type { GiteaIssue, GiteaMilestoneRef } from '../gitea/types.js'
|
||||
import { extractLabelFacts } from '../labels/label-schema.js'
|
||||
|
||||
/**
|
||||
* The injected IO boundary: a thin synchronous SQL executor. Core writes the SQL;
|
||||
* the host binds a real driver (better-sqlite3 in the desktop main process,
|
||||
* node:sqlite in tests). Kept minimal on purpose — no ORM, no query builder.
|
||||
*/
|
||||
export interface CacheDriver {
|
||||
/** Run one or more DDL/utility statements (no params, no result). */
|
||||
exec(sql: string): void
|
||||
/** Execute a single parameterized write. */
|
||||
run(sql: string, params?: readonly unknown[]): void
|
||||
/** First row of a parameterized query, or undefined. */
|
||||
get(sql: string, params?: readonly unknown[]): Record<string, unknown> | undefined
|
||||
/** All rows of a parameterized query. */
|
||||
all(sql: string, params?: readonly unknown[]): Record<string, unknown>[]
|
||||
}
|
||||
|
||||
/** The cache schema — five tables mirroring gitea's shape. Regenerable; drop and rebuild freely. */
|
||||
export const CACHE_SCHEMA = `
|
||||
CREATE TABLE IF NOT EXISTS milestones (
|
||||
id INTEGER PRIMARY KEY,
|
||||
title TEXT NOT NULL,
|
||||
state TEXT,
|
||||
due_on TEXT
|
||||
);
|
||||
CREATE TABLE IF NOT EXISTS issues (
|
||||
number INTEGER PRIMARY KEY,
|
||||
title TEXT NOT NULL,
|
||||
body TEXT NOT NULL DEFAULT '',
|
||||
state TEXT NOT NULL,
|
||||
labels TEXT NOT NULL DEFAULT '[]', -- JSON array of label names; facts re-derived on read
|
||||
milestone_id INTEGER,
|
||||
assignee TEXT,
|
||||
assignees TEXT NOT NULL DEFAULT '[]', -- JSON array of logins
|
||||
created_at TEXT,
|
||||
updated_at TEXT,
|
||||
closed_at TEXT,
|
||||
url TEXT,
|
||||
FOREIGN KEY (milestone_id) REFERENCES milestones(id)
|
||||
);
|
||||
CREATE TABLE IF NOT EXISTS labels (
|
||||
id INTEGER PRIMARY KEY,
|
||||
name TEXT NOT NULL
|
||||
);
|
||||
CREATE TABLE IF NOT EXISTS comments (
|
||||
id INTEGER PRIMARY KEY,
|
||||
issue_number INTEGER NOT NULL,
|
||||
author TEXT,
|
||||
body TEXT NOT NULL DEFAULT '',
|
||||
created_at TEXT
|
||||
);
|
||||
CREATE TABLE IF NOT EXISTS issue_events (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
issue_number INTEGER NOT NULL,
|
||||
type TEXT NOT NULL,
|
||||
at TEXT NOT NULL
|
||||
);
|
||||
CREATE INDEX IF NOT EXISTS idx_issue_events_number ON issue_events(issue_number);
|
||||
CREATE INDEX IF NOT EXISTS idx_comments_number ON comments(issue_number);
|
||||
`
|
||||
|
||||
/** Create the schema if absent. Idempotent. */
|
||||
export function initCache(driver: CacheDriver): void {
|
||||
driver.exec(CACHE_SCHEMA)
|
||||
}
|
||||
|
||||
const UPSERT_ISSUE = `
|
||||
INSERT INTO issues (number, title, body, state, labels, milestone_id, assignee, assignees, created_at, updated_at, closed_at, url)
|
||||
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
||||
ON CONFLICT(number) DO UPDATE SET
|
||||
title = excluded.title, body = excluded.body, state = excluded.state, labels = excluded.labels,
|
||||
milestone_id = excluded.milestone_id, assignee = excluded.assignee, assignees = excluded.assignees,
|
||||
created_at = excluded.created_at, updated_at = excluded.updated_at, closed_at = excluded.closed_at, url = excluded.url
|
||||
`
|
||||
|
||||
const UPSERT_MILESTONE = `
|
||||
INSERT INTO milestones (id, title, state, due_on) VALUES (?, ?, ?, ?)
|
||||
ON CONFLICT(id) DO UPDATE SET title = excluded.title, state = excluded.state, due_on = excluded.due_on
|
||||
`
|
||||
|
||||
/**
|
||||
* Mirror one reconciled issue into the cache (and its milestone, if any). Upsert
|
||||
* by `number`, so re-reconciling the same issue updates in place — never duplicates.
|
||||
*/
|
||||
export function upsertIssue(driver: CacheDriver, issue: GiteaIssue): void {
|
||||
if (issue.milestone) {
|
||||
driver.run(UPSERT_MILESTONE, [issue.milestone.id, issue.milestone.title, null, issue.milestone.dueOn])
|
||||
}
|
||||
driver.run(UPSERT_ISSUE, [
|
||||
issue.number,
|
||||
issue.title,
|
||||
issue.body,
|
||||
issue.state,
|
||||
JSON.stringify(issue.labels),
|
||||
issue.milestone?.id ?? null,
|
||||
issue.assignee,
|
||||
JSON.stringify(issue.assignees),
|
||||
issue.createdAt,
|
||||
issue.updatedAt,
|
||||
issue.closedAt,
|
||||
issue.url,
|
||||
])
|
||||
}
|
||||
|
||||
const READ_ISSUE = `
|
||||
SELECT i.*, m.title AS m_title, m.due_on AS m_due
|
||||
FROM issues i LEFT JOIN milestones m ON m.id = i.milestone_id
|
||||
WHERE i.number = ?
|
||||
`
|
||||
|
||||
function str(v: unknown): string {
|
||||
return typeof v === 'string' ? v : ''
|
||||
}
|
||||
|
||||
/**
|
||||
* Read one mirrored issue back as a domain object, re-deriving `facts` from the
|
||||
* stored label set (so the mirror can't disagree with the label semantics).
|
||||
* Returns null when the issue isn't cached.
|
||||
*/
|
||||
export function readIssue(driver: CacheDriver, number: number): GiteaIssue | null {
|
||||
const row = driver.get(READ_ISSUE, [number])
|
||||
if (!row) return null
|
||||
|
||||
const labels = (JSON.parse(str(row.labels) || '[]') as string[]) ?? []
|
||||
const assignees = (JSON.parse(str(row.assignees) || '[]') as string[]) ?? []
|
||||
const milestone: GiteaMilestoneRef | null =
|
||||
row.milestone_id != null
|
||||
? { id: Number(row.milestone_id), title: str(row.m_title), dueOn: (row.m_due as string | null) ?? null }
|
||||
: null
|
||||
|
||||
return {
|
||||
number: Number(row.number),
|
||||
title: str(row.title),
|
||||
body: str(row.body),
|
||||
state: row.state === 'closed' ? 'closed' : 'open',
|
||||
labels,
|
||||
facts: extractLabelFacts(labels),
|
||||
milestone,
|
||||
assignee: (row.assignee as string | null) ?? null,
|
||||
assignees,
|
||||
createdAt: str(row.created_at),
|
||||
updatedAt: str(row.updated_at),
|
||||
closedAt: (row.closed_at as string | null) ?? null,
|
||||
url: str(row.url),
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user