docuvia 1.0.0

package/dist/migrations/0001_init.sql

@@ -0,0 +1,155 @@
+-- 0001_init.sql
+-- Local-SQLite knowledge-graph schema (ported from old Docuvia's
+-- lib/core/src/constants/schema.sql, plus the FTS5 virtual tables/triggers
+-- from lib/core/src/services/sqlite-fts.ts folded into the same migration so
+-- GraphStore.open() is the single place that guarantees full schema readiness).
+--
+-- Table shapes match old schema.sql's columns/types exactly. NOT NULL/DEFAULT
+-- are applied wherever old schema.sql declared a DEFAULT (matching the
+-- lib/db Drizzle sqlite schema's nullability, which the raw DDL never
+-- formally captured) so the hand-written row types in ./types.ts can encode
+-- accurate nullability instead of guessing.
+
+CREATE TABLE IF NOT EXISTS projects (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL,
+  repo_url TEXT NOT NULL,
+  description TEXT,
+  status TEXT NOT NULL DEFAULT 'active',
+  vcs_type TEXT NOT NULL DEFAULT 'git',
+  svn_url TEXT,
+  last_git_ingested_at TEXT,
+  last_svn_revision INTEGER,
+  last_ast_ingested_at TEXT,
+  owner_id INTEGER NOT NULL DEFAULT 1,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS project_files (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_id INTEGER NOT NULL,
+  file_path TEXT NOT NULL,
+  content_hash TEXT,
+  last_parsed_at TEXT DEFAULT CURRENT_TIMESTAMP,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(project_id, file_path)
+);
+CREATE INDEX IF NOT EXISTS project_files_project_id_idx ON project_files(project_id);
+
+CREATE TABLE IF NOT EXISTS l1_tags (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL UNIQUE,
+  slug TEXT NOT NULL,
+  category TEXT NOT NULL DEFAULT 'Feature',
+  is_anchored INTEGER NOT NULL DEFAULT 0,
+  usage_count INTEGER NOT NULL DEFAULT 0,
+  description TEXT,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS l2_nodes (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_id INTEGER NOT NULL,
+  name TEXT NOT NULL,
+  type TEXT NOT NULL DEFAULT 'module',
+  is_system INTEGER NOT NULL DEFAULT 0,
+  description TEXT,
+  ai_generated INTEGER NOT NULL DEFAULT 1,
+  needs_review INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  last_verified_at TEXT DEFAULT CURRENT_TIMESTAMP,
+  path_patterns TEXT,
+  reindex_required INTEGER NOT NULL DEFAULT 0,
+  is_bootstrap_confirmed INTEGER NOT NULL DEFAULT 0,
+  content_hash TEXT,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS l2_nodes_project_id_idx ON l2_nodes(project_id);
+CREATE INDEX IF NOT EXISTS l2_nodes_name_idx ON l2_nodes(name);
+CREATE INDEX IF NOT EXISTS l2_nodes_content_hash_idx ON l2_nodes(content_hash);
+
+CREATE TABLE IF NOT EXISTS node_links (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  source_node_id INTEGER NOT NULL,
+  target_node_id INTEGER NOT NULL,
+  link_type TEXT NOT NULL DEFAULT 'depends_on',
+  commit_sha TEXT,
+  diff_summary TEXT,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS node_links_source_node_idx ON node_links(source_node_id);
+CREATE INDEX IF NOT EXISTS node_links_target_node_idx ON node_links(target_node_id);
+
+CREATE TABLE IF NOT EXISTS l2_node_l1_tags (
+  l2_node_id INTEGER NOT NULL,
+  l1_tag_id INTEGER NOT NULL,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS l2_node_l1_tags_l2_node_idx ON l2_node_l1_tags(l2_node_id);
+CREATE INDEX IF NOT EXISTS l2_node_l1_tags_l1_tag_idx ON l2_node_l1_tags(l1_tag_id);
+
+CREATE TABLE IF NOT EXISTS l3_nodes (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  l2_node_id INTEGER NOT NULL,
+  title TEXT NOT NULL,
+  content TEXT,
+  node_type TEXT NOT NULL DEFAULT 'change',
+  source_commits TEXT NOT NULL DEFAULT '[]',
+  commit_hash TEXT,
+  ai_generated INTEGER NOT NULL DEFAULT 1,
+  confidence REAL,
+  noise_score REAL,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  last_verified_at TEXT DEFAULT CURRENT_TIMESTAMP,
+  occurrence_count INTEGER NOT NULL DEFAULT 1,
+  introduced_in_commit TEXT,
+  verified_until_commit TEXT,
+  validity_status TEXT NOT NULL DEFAULT 'pending',
+  source TEXT NOT NULL DEFAULT 'commit',
+  content_hash TEXT
+);
+CREATE INDEX IF NOT EXISTS l3_nodes_l2_node_id_idx ON l3_nodes(l2_node_id);
+CREATE INDEX IF NOT EXISTS l3_nodes_content_hash_idx ON l3_nodes(content_hash);
+
+-- FTS5 keyword indexes for the local-first natural-language fallback (ADR-029),
+-- ported from lib/core/src/services/sqlite-fts.ts. External-content indexes
+-- over l2_nodes / l3_nodes, kept in sync by triggers so ordinary writes to the
+-- content tables require no separate "ensure FTS" step.
+CREATE VIRTUAL TABLE IF NOT EXISTS l2_nodes_fts USING fts5(
+  name, description, path_patterns,
+  content='l2_nodes', content_rowid='id'
+);
+CREATE TRIGGER IF NOT EXISTS l2_nodes_fts_ai AFTER INSERT ON l2_nodes BEGIN
+  INSERT INTO l2_nodes_fts(rowid, name, description, path_patterns)
+  VALUES (new.id, new.name, new.description, new.path_patterns);
+END;
+CREATE TRIGGER IF NOT EXISTS l2_nodes_fts_ad AFTER DELETE ON l2_nodes BEGIN
+  INSERT INTO l2_nodes_fts(l2_nodes_fts, rowid, name, description, path_patterns)
+  VALUES ('delete', old.id, old.name, old.description, old.path_patterns);
+END;
+CREATE TRIGGER IF NOT EXISTS l2_nodes_fts_au AFTER UPDATE ON l2_nodes BEGIN
+  INSERT INTO l2_nodes_fts(l2_nodes_fts, rowid, name, description, path_patterns)
+  VALUES ('delete', old.id, old.name, old.description, old.path_patterns);
+  INSERT INTO l2_nodes_fts(rowid, name, description, path_patterns)
+  VALUES (new.id, new.name, new.description, new.path_patterns);
+END;
+
+CREATE VIRTUAL TABLE IF NOT EXISTS l3_nodes_fts USING fts5(
+  title, content,
+  content='l3_nodes', content_rowid='id'
+);
+CREATE TRIGGER IF NOT EXISTS l3_nodes_fts_ai AFTER INSERT ON l3_nodes BEGIN
+  INSERT INTO l3_nodes_fts(rowid, title, content)
+  VALUES (new.id, new.title, new.content);
+END;
+CREATE TRIGGER IF NOT EXISTS l3_nodes_fts_ad AFTER DELETE ON l3_nodes BEGIN
+  INSERT INTO l3_nodes_fts(l3_nodes_fts, rowid, title, content)
+  VALUES ('delete', old.id, old.title, old.content);
+END;
+CREATE TRIGGER IF NOT EXISTS l3_nodes_fts_au AFTER UPDATE ON l3_nodes BEGIN
+  INSERT INTO l3_nodes_fts(l3_nodes_fts, rowid, title, content)
+  VALUES ('delete', old.id, old.title, old.content);
+  INSERT INTO l3_nodes_fts(rowid, title, content)
+  VALUES (new.id, new.title, new.content);
+END;

package/dist/migrations/0002_l2_node_key.sql

@@ -0,0 +1,9 @@
+-- 0002_l2_node_key.sql
+-- STOR-005: deterministic, path-keyed node identity, separate from the SQLite AUTOINCREMENT
+-- rowid. `node_key` is `<file_path>` for file nodes and `<file_path>#<symbolName>` for
+-- function/class nodes — stable across machines and across a clean + re-analyze cycle, so
+-- `nodes.jsonl`/`edges.jsonl` exports produce clean, deterministic diffs instead of exporting
+-- effectively-random rowids.
+
+ALTER TABLE l2_nodes ADD COLUMN node_key TEXT;
+CREATE UNIQUE INDEX IF NOT EXISTS l2_nodes_project_id_node_key_idx ON l2_nodes(project_id, node_key);

package/dist/migrations/0003_docuvia_meta.sql

@@ -0,0 +1,10 @@
+-- 0003_docuvia_meta.sql
+-- STOR-002: small key/value store, currently used to remember the knowledge-branch tip sha
+-- local.db was last hydrated from, so read commands can cheaply detect staleness without
+-- re-parsing JSONL on every call. Disposable like the rest of local.db — Git remains the source
+-- of truth this is rebuilt from.
+
+CREATE TABLE IF NOT EXISTS docuvia_meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);

package/dist/migrations/0004_l3_provenance.sql

@@ -0,0 +1,11 @@
+-- 0004_l3_provenance.sql
+-- phase1-decision-integration.md §3a / PLAT-007 Tier C point 1: `analyze <targetPath>`'s LLM
+-- decision-extraction results are persisted to `l3_nodes` instead of print-only. Two additive
+-- provenance columns beyond what 0001_init.sql already carries (commit_hash, source_commits,
+-- confidence, content_hash, validity_status, source): the extraction model and the source file
+-- list. `ALTER TABLE ... ADD COLUMN` only -- no table rebuild, no backfill (pre-existing rows
+-- keep NULL for both).
+
+ALTER TABLE l3_nodes ADD COLUMN extraction_model TEXT;
+-- JSON array of workspace-relative source file paths the decision was extracted from.
+ALTER TABLE l3_nodes ADD COLUMN source_files TEXT;

package/dist/migrations/0005_l3_initial_source_commits.sql

@@ -0,0 +1,10 @@
+-- 0005_l3_initial_source_commits.sql
+-- phase2-l3-distribution.md L3DIST-002/003: `snapshot`'s L3 card renderer packs a JSON snapshot
+-- of `source_commits` frozen at the row's first insert, never the current (mutable, growing on
+-- every re-analysis) `source_commits` value -- otherwise re-running `snapshot` with no new
+-- decision content would still produce a different git blob every time occurrence tracking
+-- appended a commit sha, defeating the idempotency §5b relies on. `ALTER TABLE ... ADD COLUMN`
+-- only -- no table rebuild, no backfill (pre-existing rows keep NULL; the L3 card renderer falls
+-- back to `source_commits` for those).
+
+ALTER TABLE l3_nodes ADD COLUMN initial_source_commits TEXT;

package/dist/migrations/0006_tier_b_file_status.sql

@@ -0,0 +1,10 @@
+-- 0006_tier_b_file_status.sql
+-- docs/cli-test-analysis/typescript-cli-benchmark.md §5.3/§5.7 items 1-2 (Tier B full-resync gap):
+-- `project_files` already tracks each file's last Tier A parse (`last_parsed_at`); this adds the
+-- Tier B analogue so `query`/`impact` can distinguish "this file's calls have never been computed
+-- by Tier B" from "confirmed zero calls". Additive `ALTER TABLE ... ADD COLUMN` only, matching
+-- 0004/0005's precedent -- pre-existing rows keep NULL, which is exactly "never processed" (there
+-- is no historical record to backfill: no per-file Tier B timestamp existed before this migration).
+
+ALTER TABLE project_files ADD COLUMN last_tier_b_processed_at TEXT;
+ALTER TABLE project_files ADD COLUMN last_tier_b_commit_sha TEXT;

package/dist/migrations/0007_fts_porter_stemming.sql

@@ -0,0 +1,33 @@
+-- 0007_fts_porter_stemming.sql
+-- docs/gitbook/analysis/roadmap-and-open-items.md item 25 ("query"'s FTS ranking has no
+-- synonym/token-expansion step): the default FTS5 tokenizer (unicode61) does exact token
+-- matching with no stemming, so a directory named "commands" (plural) and a query keyword
+-- "command" (singular) are two different tokens that never match each other -- confirmed against
+-- this repo's own data: `"query" AND "command"` matched 0 l2_nodes rows even though
+-- artifacts/cli/src/commands/query.ts obviously matches both concepts. Switching to
+-- tokenize='porter unicode61' folds English plurals/suffixes to a common stem
+-- ("commands"/"command" -> "command", "query"/"queries" -> "queri") at both index and query time
+-- (SQLite applies a table's configured tokenizer to MATCH text too), closing that gap with no
+-- application-code change to how queries are issued.
+--
+-- FTS5 virtual tables can't ALTER their tokenizer in place -- drop and recreate, then rebuild the
+-- index from the existing content tables (l2_nodes/l3_nodes), exactly like `withFtsSyncSuspended`
+-- already does for bulk loads (graph-repo.ts). The AFTER INSERT/DELETE/UPDATE triggers live on
+-- l2_nodes/l3_nodes (not on the virtual tables) and reference l2_nodes_fts/l3_nodes_fts only by
+-- name in their body, so they keep working unchanged once the virtual tables are recreated below.
+
+DROP TABLE IF EXISTS l2_nodes_fts;
+CREATE VIRTUAL TABLE l2_nodes_fts USING fts5(
+  name, description, path_patterns,
+  content='l2_nodes', content_rowid='id',
+  tokenize='porter unicode61'
+);
+INSERT INTO l2_nodes_fts(l2_nodes_fts) VALUES('rebuild');
+
+DROP TABLE IF EXISTS l3_nodes_fts;
+CREATE VIRTUAL TABLE l3_nodes_fts USING fts5(
+  title, content,
+  content='l3_nodes', content_rowid='id',
+  tokenize='porter unicode61'
+);
+INSERT INTO l3_nodes_fts(l3_nodes_fts) VALUES('rebuild');

package/dist/migrations/0008_ast_call_sites.sql

@@ -0,0 +1,18 @@
+-- 0008_ast_call_sites.sql
+-- issue #11 plan A, Slice 3 (docs/gitbook/analysis/forward-tier-b-edge-resolution-plan.md):
+-- Tier A's ast-worker.ts computes each call site's source position (Slice 1) but never
+-- persisted it -- this table is the missing read-back surface Tier B's forward resolution
+-- pass seeds itself from. One row per call site (not one row per resolved edge -- unlike
+-- node_links, a row here exists whether or not ScopeResolver could resolve the target
+-- locally, since unresolved cross-file calls are exactly what Tier B needs to see).
+
+CREATE TABLE IF NOT EXISTS ast_call_sites (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_id INTEGER NOT NULL,
+  file_path TEXT NOT NULL,
+  target_function TEXT NOT NULL,
+  start_line INTEGER NOT NULL,
+  start_column INTEGER NOT NULL,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS ast_call_sites_project_file_idx ON ast_call_sites(project_id, file_path);

package/dist/migrations/0009_l2_node_key_lookup_index.sql

@@ -0,0 +1,12 @@
+-- 0009_l2_node_key_lookup_index.sql
+-- IMPT/perf: `findNodeIdByNodeKey`/Tier B edge application resolves an l2_node by its STOR-005
+-- `node_key` alone (`SELECT id FROM l2_nodes WHERE node_key = ?`) -- a query SQLite cannot satisfy
+-- with the existing composite `(project_id, node_key)` unique index, whose leading column makes
+-- every such lookup a full covering-index SCAN over every row in the table. On a large repo
+-- (vscode: ~293k nodes) that made `applyResolvedEdges` insert edges at ~20/sec during an
+-- uncapped `--lsp-timeout=0` batch. A standalone single-column `node_key` index turns the lookup
+-- into a SEARCH. Redundant with (not a replacement for) the composite unique index -- keys stay
+-- unique *per project*, the composite still enforces that; this index is purely the lookup
+-- accelerator.
+
+CREATE INDEX IF NOT EXISTS l2_nodes_node_key_idx ON l2_nodes(node_key);

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "docuvia",
+  "version": "1.0.0",
+  "description": "Codebase Knowledge Evolver — maintains a local knowledge graph of your workspace: modules, dependencies, blast radius, and recorded architectural decisions.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "docuvia": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dyphn1/Docuvia.git",
+    "directory": "artifacts/cli"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "tag": "beta"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --fileParallelism false",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "catalog:",
+    "execa": "^9.6.1",
+    "pino-pretty": "^13",
+    "tsup": "^8.5.1",
+    "tsx": "catalog:",
+    "vitest": "^1.6.1"
+  },
+  "dependencies": {
+    "@inquirer/checkbox": "^5.2.1",
+    "@inquirer/prompts": "^8.5.2",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@workspace/contracts": "workspace:^",
+    "@workspace/core": "workspace:^",
+    "@workspace/git-local": "workspace:^",
+    "@workspace/llm-api": "workspace:^",
+    "@workspace/remote-api": "workspace:^",
+    "@workspace/schema": "workspace:^",
+    "@workspace/ui-core": "workspace:^",
+    "better-sqlite3": "^12.11.1",
+    "dotenv": "^17.4.2",
+    "ora": "^9.4.1",
+    "picocolors": "^1.1.1",
+    "pino": "^9.14.0",
+    "tree-sitter-wasms": "^0.1.13",
+    "web-tree-sitter": "^0.25.9",
+    "zod": "^3.24.1"
+  }
+}