@rkarim08/sia 1.0.0

package/src/cli/commands/export-knowledge.ts

@@ -0,0 +1,208 @@
+// Module: export-knowledge — Generate human-readable knowledge document
+//
+// Queries the graph and produces a structured markdown document organized
+// by knowledge category: decisions, conventions, bugs, solutions, concepts,
+// community structure, and documentation.
+
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { SiaDb } from "@/graph/db-interface";
+
+export interface ExportOptions {
+	projectName?: string;
+	outputPath?: string;
+	includeCommunities?: boolean;
+	includeCodeEntities?: boolean;
+}
+
+interface EntityRow {
+	id: string;
+	type: string;
+	name: string;
+	content: string;
+	summary: string | null;
+	trust_tier: number;
+	importance: number;
+	created_at: number;
+	file_paths: string | null;
+	kind: string | null;
+}
+
+async function queryByType(db: SiaDb, type: string, limit: number = 50): Promise<EntityRow[]> {
+	const result = await db.execute(
+		`SELECT id, type, name, content, summary, trust_tier, importance, created_at, file_paths, kind
+		 FROM graph_nodes
+		 WHERE type = ? AND t_valid_until IS NULL AND archived_at IS NULL
+		 ORDER BY importance DESC, created_at DESC
+		 LIMIT ?`,
+		[type, limit],
+	);
+	return result.rows as unknown as EntityRow[];
+}
+
+function formatDate(ms: number): string {
+	return new Date(ms).toISOString().split("T")[0];
+}
+
+function tierLabel(tier: number): string {
+	return tier === 1
+		? "verified"
+		: tier === 2
+			? "code-derived"
+			: tier === 3
+				? "inferred"
+				: "external";
+}
+
+function formatEntities(entities: EntityRow[], showContent: boolean = true): string {
+	if (entities.length === 0) return "*None captured yet.*\n";
+
+	return entities
+		.map((e) => {
+			const date = formatDate(e.created_at);
+			const tier = tierLabel(e.trust_tier);
+			const files = e.file_paths ? ` | Files: ${e.file_paths}` : "";
+			let text = `### ${e.name}\n`;
+			text += `*${date} | ${tier}${files}*\n\n`;
+			if (showContent && e.content) {
+				text += `${e.content.slice(0, 500)}\n`;
+			} else if (e.summary) {
+				text += `${e.summary}\n`;
+			}
+			return text;
+		})
+		.join("\n---\n\n");
+}
+
+export async function generateKnowledgeDocument(
+	db: SiaDb,
+	opts: ExportOptions = {},
+): Promise<string> {
+	const projectName = opts.projectName ?? "Project";
+
+	const decisions = await queryByType(db, "Decision");
+	const conventions = await queryByType(db, "Convention");
+	const bugs = await queryByType(db, "Bug");
+	const solutions = await queryByType(db, "Solution");
+	const concepts = await queryByType(db, "Concept");
+
+	// Count totals
+	const totalResult = await db.execute(
+		"SELECT COUNT(*) as cnt FROM graph_nodes WHERE t_valid_until IS NULL AND archived_at IS NULL",
+	);
+	const totalEntities = (totalResult.rows[0] as any).cnt;
+
+	if (totalEntities === 0) {
+		return `# ${projectName} — Knowledge Base\n\n*No knowledge captured yet. Run \`/sia-learn\` to build the knowledge graph.*\n`;
+	}
+
+	const sections: string[] = [];
+
+	// Header
+	sections.push(`# ${projectName} — Knowledge Base`);
+	sections.push(
+		`\n*Generated by SIA on ${formatDate(Date.now())} | ${totalEntities} total entities*\n`,
+	);
+	sections.push("---\n");
+
+	// Table of Contents
+	sections.push("## Table of Contents\n");
+	if (decisions.length > 0)
+		sections.push(`- [Architectural Decisions](#architectural-decisions) (${decisions.length})`);
+	if (conventions.length > 0)
+		sections.push(`- [Coding Conventions](#coding-conventions) (${conventions.length})`);
+	if (bugs.length > 0) sections.push(`- [Known Issues](#known-issues) (${bugs.length})`);
+	if (solutions.length > 0) sections.push(`- [Solutions](#solutions) (${solutions.length})`);
+	if (concepts.length > 0) sections.push(`- [Key Concepts](#key-concepts) (${concepts.length})`);
+	sections.push("");
+
+	// Decisions
+	if (decisions.length > 0) {
+		sections.push("## Architectural Decisions\n");
+		sections.push(formatEntities(decisions));
+	}
+
+	// Conventions
+	if (conventions.length > 0) {
+		sections.push("## Coding Conventions\n");
+		sections.push(formatEntities(conventions));
+	}
+
+	// Bugs
+	if (bugs.length > 0) {
+		sections.push("## Known Issues\n");
+		sections.push(formatEntities(bugs));
+	}
+
+	// Solutions
+	if (solutions.length > 0) {
+		sections.push("## Solutions\n");
+		sections.push(formatEntities(solutions));
+	}
+
+	// Concepts
+	if (concepts.length > 0) {
+		sections.push("## Key Concepts\n");
+		sections.push(formatEntities(concepts));
+	}
+
+	// Community structure
+	if (opts.includeCommunities !== false) {
+		const communities = await db.execute(
+			"SELECT id, summary, member_count FROM communities WHERE level = 2 ORDER BY member_count DESC LIMIT 10",
+		);
+		if ((communities.rows as any[]).length > 0) {
+			sections.push("## Architecture (Community Structure)\n");
+			for (const c of communities.rows as any[]) {
+				sections.push(`### Community (${c.member_count} members)`);
+				sections.push(`${c.summary ?? "No summary available"}\n`);
+			}
+		}
+	}
+
+	// Footer
+	sections.push("---\n");
+	sections.push("*This document was auto-generated by SIA's knowledge graph export.*");
+	sections.push("*Run `/sia-export-knowledge` to regenerate with the latest knowledge.*");
+
+	return sections.join("\n");
+}
+
+export async function runExportKnowledge(args: string[]): Promise<void> {
+	const { resolveRepoHash } = await import("@/capture/hook");
+	const { openGraphDb } = await import("@/graph/semantic-db");
+	const { resolveSiaHome } = await import("@/shared/config");
+
+	let outputPath = "KNOWLEDGE.md";
+	let projectName: string | undefined;
+
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === "--output" && args[i + 1]) outputPath = args[++i];
+		if (args[i] === "--name" && args[i + 1]) projectName = args[++i];
+	}
+
+	const cwd = process.cwd();
+	const repoHash = resolveRepoHash(cwd);
+	const siaHome = resolveSiaHome();
+	const db = openGraphDb(repoHash, siaHome);
+
+	try {
+		// Auto-detect project name from package.json if not provided
+		if (!projectName) {
+			try {
+				const { readFileSync } = await import("node:fs");
+				const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf-8"));
+				projectName = pkg.name;
+			} catch {
+				projectName = cwd.split("/").pop() ?? "Project";
+			}
+		}
+
+		const markdown = await generateKnowledgeDocument(db, { projectName });
+		const fullPath = join(cwd, outputPath);
+		writeFileSync(fullPath, markdown, "utf-8");
+		console.log(`Knowledge document written to ${outputPath} (${markdown.length} chars)`);
+	} finally {
+		await db.close();
+	}
+}

package/src/cli/commands/export.ts

@@ -0,0 +1,85 @@
+// Module: export — serialize active graph to portable JSON
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { SiaDb } from "@/graph/db-interface";
+
+/** Options for graph export. */
+export interface ExportOpts {
+	/** Optional bridge.db handle for cross-repo edges */
+	bridgeDb?: SiaDb;
+	/** Repo hash for filtering bridge edges */
+	repoHash?: string;
+}
+
+/** Portable snapshot of the active graph. */
+export interface ExportData {
+	version: 1;
+	exportedAt: number;
+	entities: Record<string, unknown>[];
+	edges: Record<string, unknown>[];
+	communities: Record<string, unknown>[];
+	crossRepoEdges: Record<string, unknown>[];
+}
+
+/**
+ * Export the active graph to a portable JSON structure.
+ *
+ * 1. Active entities (not invalidated, not archived)
+ * 2. Active edges (not invalidated)
+ * 3. All communities
+ * 4. Optionally, active cross-repo edges from bridge.db
+ */
+export async function exportGraph(db: SiaDb, opts?: ExportOpts): Promise<ExportData> {
+	// 1. Active entities
+	const entitiesResult = await db.execute(
+		"SELECT * FROM graph_nodes WHERE t_valid_until IS NULL AND archived_at IS NULL",
+	);
+
+	// 2. Active edges
+	const edgesResult = await db.execute("SELECT * FROM graph_edges WHERE t_valid_until IS NULL");
+
+	// 3. All communities
+	const communitiesResult = await db.execute("SELECT * FROM communities");
+
+	// 4. Cross-repo edges (only if bridgeDb + repoHash provided)
+	let crossRepoEdges: Record<string, unknown>[] = [];
+	if (opts?.bridgeDb && opts?.repoHash) {
+		const crossResult = await opts.bridgeDb.execute(
+			"SELECT * FROM cross_repo_edges WHERE (source_repo_id = ? OR target_repo_id = ?) AND t_valid_until IS NULL",
+			[opts.repoHash, opts.repoHash],
+		);
+		crossRepoEdges = crossResult.rows;
+	}
+
+	return {
+		version: 1,
+		exportedAt: Date.now(),
+		entities: entitiesResult.rows,
+		edges: edgesResult.rows,
+		communities: communitiesResult.rows,
+		crossRepoEdges,
+	};
+}
+
+/**
+ * Export the active graph to a JSON file on disk.
+ *
+ * Creates parent directories if they don't exist.
+ * Returns the output path.
+ */
+export async function exportToFile(
+	db: SiaDb,
+	outputPath: string,
+	opts?: ExportOpts,
+): Promise<string> {
+	const data = await exportGraph(db, opts);
+
+	const dir = dirname(outputPath);
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
+
+	writeFileSync(outputPath, JSON.stringify(data, null, 2), "utf-8");
+	return outputPath;
+}

package/src/cli/commands/freshness.ts

@@ -0,0 +1,164 @@
+// Module: freshness — CLI freshness report command
+
+import type { SiaDb } from "@/graph/db-interface";
+import { getNativeModuleStatus } from "@/native/bridge";
+
+export interface FreshnessReport {
+	totalNodes: number;
+	freshNodes: number;
+	staleNodes: number;
+	rottenNodes: number;
+	pendingRevalidation: number;
+	avgConfidenceByTier: Record<string, number>;
+	lastDeepValidation: number | null;
+	indexCoverage: number; // percentage of nodes with source mappings
+	nativeModuleStatus: string; // "native" | "wasm" | "typescript"
+}
+
+// Confidence thresholds for freshness classification
+const FRESH_THRESHOLD = 0.7;
+const ROTTEN_THRESHOLD = 0.3;
+
+/**
+ * Generate a freshness report for the graph.
+ */
+export async function generateFreshnessReport(db: SiaDb): Promise<FreshnessReport> {
+	// 1. Total node count
+	const { rows: totalRows } = await db.execute("SELECT COUNT(*) AS cnt FROM graph_nodes");
+	const totalNodes = (totalRows[0]?.cnt as number) ?? 0;
+
+	// 2. Active node count (not archived, not invalidated)
+	const { rows: activeRows } = await db.execute(
+		"SELECT COUNT(*) AS cnt FROM graph_nodes WHERE archived_at IS NULL AND t_valid_until IS NULL",
+	);
+	const activeNodes = (activeRows[0]?.cnt as number) ?? 0;
+
+	// 3. Fresh nodes: confidence > FRESH_THRESHOLD (active only)
+	const { rows: freshRows } = await db.execute(
+		"SELECT COUNT(*) AS cnt FROM graph_nodes WHERE archived_at IS NULL AND t_valid_until IS NULL AND confidence > ?",
+		[FRESH_THRESHOLD],
+	);
+	const freshNodes = (freshRows[0]?.cnt as number) ?? 0;
+
+	// 4. Rotten nodes: confidence < ROTTEN_THRESHOLD (active only)
+	const { rows: rottenRows } = await db.execute(
+		"SELECT COUNT(*) AS cnt FROM graph_nodes WHERE archived_at IS NULL AND t_valid_until IS NULL AND confidence < ?",
+		[ROTTEN_THRESHOLD],
+	);
+	const rottenNodes = (rottenRows[0]?.cnt as number) ?? 0;
+
+	// 5. Stale nodes: between thresholds
+	const staleNodes = activeNodes - freshNodes - rottenNodes;
+
+	// 6. Pending revalidation: invalidated but not yet replaced
+	const { rows: pendingRows } = await db.execute(
+		"SELECT COUNT(*) AS cnt FROM graph_nodes WHERE t_valid_until IS NOT NULL AND archived_at IS NULL",
+	);
+	const pendingRevalidation = (pendingRows[0]?.cnt as number) ?? 0;
+
+	// 7. Average confidence by trust tier
+	const { rows: tierRows } = await db.execute(
+		"SELECT trust_tier, AVG(confidence) AS avg_conf FROM graph_nodes WHERE archived_at IS NULL AND t_valid_until IS NULL GROUP BY trust_tier",
+	);
+	const avgConfidenceByTier: Record<string, number> = {};
+	for (const row of tierRows) {
+		const tier = String(row.trust_tier as number);
+		avgConfidenceByTier[tier] = Math.round((row.avg_conf as number) * 100) / 100;
+	}
+
+	// 8. Index coverage: percentage of active nodes with at least one source mapping
+	let indexCoverage = 0;
+	if (totalNodes > 0) {
+		const { rows: mappedRows } = await db.execute(
+			"SELECT COUNT(DISTINCT node_id) AS cnt FROM source_deps",
+		);
+		const mappedNodes = (mappedRows[0]?.cnt as number) ?? 0;
+		indexCoverage = Math.round((mappedNodes / totalNodes) * 100 * 10) / 10;
+	}
+
+	// 9. Last deep validation: not persisted in DB yet — return null
+	const lastDeepValidation: number | null = null;
+
+	// 10. Native module status
+	const nativeModuleStatus = getNativeModuleStatus();
+
+	return {
+		totalNodes,
+		freshNodes,
+		staleNodes,
+		rottenNodes,
+		pendingRevalidation,
+		avgConfidenceByTier,
+		lastDeepValidation,
+		indexCoverage,
+		nativeModuleStatus,
+	};
+}
+
+/**
+ * Format the report as human-readable output for CLI.
+ */
+export function formatFreshnessReport(report: FreshnessReport): string {
+	const lines: string[] = [];
+
+	const sep = "──────────────────────────────";
+
+	lines.push("Sia Graph Freshness Report");
+	lines.push(sep);
+
+	// Node counts
+	const total = report.totalNodes;
+	const freshPct = total > 0 ? ((report.freshNodes / total) * 100).toFixed(1) : "0.0";
+	const stalePct = total > 0 ? ((report.staleNodes / total) * 100).toFixed(1) : "0.0";
+	const rottenPct = total > 0 ? ((report.rottenNodes / total) * 100).toFixed(1) : "0.0";
+
+	lines.push(`Total nodes:          ${formatNumber(total)}`);
+	lines.push(`  Fresh:              ${formatNumber(report.freshNodes)} (${freshPct}%)`);
+	lines.push(`  Stale:              ${formatNumber(report.staleNodes)} (${stalePct}%)`);
+	lines.push(`  Rotten:             ${formatNumber(report.rottenNodes)} (${rottenPct}%)`);
+	lines.push("");
+
+	// Confidence by trust tier
+	const tierNames: Record<string, string> = {
+		"1": "Tier 1 (User)",
+		"2": "Tier 2 (AST)",
+		"3": "Tier 3 (LLM)",
+		"4": "Tier 4 (External)",
+	};
+
+	const tierKeys = Object.keys(report.avgConfidenceByTier).sort();
+	if (tierKeys.length > 0) {
+		lines.push("Confidence by Trust Tier:");
+		for (const tier of tierKeys) {
+			const name = tierNames[tier] ?? `Tier ${tier}`;
+			const conf = report.avgConfidenceByTier[tier]?.toFixed(2) ?? "N/A";
+			lines.push(`  ${name.padEnd(22)} ${conf}`);
+		}
+		lines.push("");
+	}
+
+	// Index coverage
+	lines.push(
+		`Index Coverage:        ${report.indexCoverage.toFixed(1)}% (nodes with source mappings)`,
+	);
+
+	// Native module
+	lines.push(`Native Module:         ${report.nativeModuleStatus}`);
+
+	// Last deep validation
+	const lastVal =
+		report.lastDeepValidation !== null
+			? new Date(report.lastDeepValidation).toISOString().replace("T", " ").slice(0, 19)
+			: "never";
+	lines.push(`Last Deep Validation:  ${lastVal}`);
+
+	return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function formatNumber(n: number): string {
+	return n.toLocaleString("en-US");
+}

package/src/cli/commands/graph.ts

@@ -0,0 +1,51 @@
+// Module: graph — CLI command to generate knowledge graph visualization
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import type { SiaDb } from "@/graph/db-interface";
+import { renderGraphHtml } from "@/visualization/graph-renderer";
+import { type ExtractOpts, extractSubgraph } from "@/visualization/subgraph-extract";
+
+export interface GraphCommandOpts {
+	output?: string;
+	scope?: string;
+	nodeType?: string;
+	maxNodes?: number;
+}
+
+/**
+ * Generate a knowledge graph visualization as a self-contained HTML file.
+ *
+ * 1. Extracts a subgraph according to the provided options.
+ * 2. Renders the subgraph as a self-contained HTML document with D3.js.
+ * 3. Writes the HTML to the output path.
+ * 4. Returns the absolute path of the written file.
+ */
+export async function generateGraphVisualization(
+	db: SiaDb,
+	opts?: GraphCommandOpts,
+): Promise<string> {
+	const extractOpts: ExtractOpts = {
+		scope: opts?.scope,
+		nodeType: opts?.nodeType,
+		maxNodes: opts?.maxNodes,
+	};
+
+	const data = await extractSubgraph(db, extractOpts);
+
+	// Build a descriptive title from the options
+	let title = "Sia Knowledge Graph";
+	if (opts?.scope) {
+		title = `Sia Graph — ${opts.scope}`;
+	} else if (opts?.nodeType) {
+		title = `Sia Graph — ${opts.nodeType} entities`;
+	}
+
+	const html = renderGraphHtml(data, title);
+
+	const outputPath = resolve(opts?.output ?? "./sia-graph.html");
+	mkdirSync(dirname(outputPath), { recursive: true });
+	writeFileSync(outputPath, html, "utf-8");
+
+	return outputPath;
+}

package/src/cli/commands/history.ts

@@ -0,0 +1,139 @@
+// Module: history — Temporal exploration of the knowledge graph
+//
+// Usage:
+//   sia history                          Show last 7 days of knowledge
+//   sia history --since 2026-03-01      Since a specific date
+//   sia history --types Decision,Bug    Filter by entity type
+//   sia history --file src/auth/login.ts  Filter by file
+
+import type { SiaDb } from "@/graph/db-interface";
+
+export interface HistoryOptions {
+	since?: number;
+	until?: number;
+	types?: string[];
+	file?: string;
+	limit?: number;
+}
+
+export interface HistoryResult {
+	entities: Array<{
+		id: string;
+		type: string;
+		name: string;
+		summary: string | null;
+		kind: string | null;
+		created_at: number;
+		trust_tier: number;
+	}>;
+	timeRange: { since: number; until: number };
+}
+
+export async function getHistory(db: SiaDb, opts: HistoryOptions = {}): Promise<HistoryResult> {
+	const since = opts.since ?? Date.now() - 7 * 86400000; // default 7 days
+	const until = opts.until ?? Date.now();
+	const limit = opts.limit ?? 50;
+
+	let query = `SELECT id, type, name, summary, kind, created_at, trust_tier, file_paths
+		FROM graph_nodes
+		WHERE created_at >= ? AND created_at <= ?
+		AND t_valid_until IS NULL AND archived_at IS NULL`;
+	const params: unknown[] = [since, until];
+
+	if (opts.types && opts.types.length > 0) {
+		const placeholders = opts.types.map(() => "?").join(", ");
+		query += ` AND type IN (${placeholders})`;
+		params.push(...opts.types);
+	}
+
+	if (opts.file) {
+		query += " AND file_paths LIKE ?";
+		params.push(`%${opts.file}%`);
+	}
+
+	query += " ORDER BY created_at DESC LIMIT ?";
+	params.push(limit);
+
+	const result = await db.execute(query, params);
+
+	return {
+		entities: result.rows as HistoryResult["entities"],
+		timeRange: { since, until },
+	};
+}
+
+export function formatHistory(history: HistoryResult): string {
+	const lines: string[] = [];
+	const sinceDate = new Date(history.timeRange.since).toISOString().split("T")[0];
+	const untilDate = new Date(history.timeRange.until).toISOString().split("T")[0];
+
+	lines.push(`=== SIA Knowledge History (${sinceDate} to ${untilDate}) ===\n`);
+
+	if (history.entities.length === 0) {
+		lines.push("No knowledge captured in this time range.");
+		return lines.join("\n");
+	}
+
+	// Group by date
+	const byDate = new Map<string, typeof history.entities>();
+	for (const entity of history.entities) {
+		const date = new Date(entity.created_at).toISOString().split("T")[0];
+		if (!byDate.has(date)) byDate.set(date, []);
+		byDate.get(date)?.push(entity);
+	}
+
+	for (const [date, entities] of byDate) {
+		lines.push(`--- ${date} (${entities.length} entities) ---`);
+		for (const e of entities) {
+			const tierLabel =
+				e.trust_tier === 1
+					? "user"
+					: e.trust_tier === 2
+						? "code"
+						: e.trust_tier === 3
+							? "llm"
+							: "ext";
+			lines.push(`  [${e.type}] ${e.name} (tier:${tierLabel})`);
+			if (e.summary) lines.push(`    ${e.summary.slice(0, 100)}`);
+		}
+		lines.push("");
+	}
+
+	lines.push(`Total: ${history.entities.length} entities`);
+	return lines.join("\n");
+}
+
+export async function runHistory(args: string[]): Promise<void> {
+	const { resolveRepoHash } = await import("@/capture/hook");
+	const { openGraphDb } = await import("@/graph/semantic-db");
+	const { resolveSiaHome } = await import("@/shared/config");
+
+	const opts: HistoryOptions = {};
+
+	// Parse args
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === "--since" && args[i + 1]) {
+			opts.since = new Date(args[++i]).getTime();
+		} else if (args[i] === "--until" && args[i + 1]) {
+			opts.until = new Date(args[++i]).getTime();
+		} else if (args[i] === "--types" && args[i + 1]) {
+			opts.types = args[++i].split(",");
+		} else if (args[i] === "--file" && args[i + 1]) {
+			opts.file = args[++i];
+		} else if (args[i] === "--limit" && args[i + 1]) {
+			opts.limit = parseInt(args[++i], 10);
+		}
+	}
+
+	const cwd = process.cwd();
+	const repoHash = resolveRepoHash(cwd);
+	const siaHome = resolveSiaHome();
+	const db = openGraphDb(repoHash, siaHome);
+
+	try {
+		const history = await getHistory(db, opts);
+		console.log(formatHistory(history));
+	} finally {
+		await db.close();
+	}
+}