lattice-graph 0.1.0

package/src/output/text.ts

@@ -0,0 +1,265 @@
+import type { BoundaryEntry, EventConnection, FlowEntry } from "../graph/queries.ts";
+import type { Node } from "../types/graph.ts";
+
+/** Formats a node reference as "name (file:line)". */
+function nodeRef(node: Node): string {
+	return `${node.name} (${node.file}:${node.lineStart})`;
+}
+
+/** Tree node for flow visualization. */
+type FlowTreeNode = {
+	readonly node: Node;
+	readonly boundary: string | undefined;
+	readonly emits: string | undefined;
+	readonly children: readonly FlowTreeNode[];
+};
+
+/** Context data for the `lattice context` command. */
+type ContextData = {
+	readonly node: Node;
+	readonly flows: readonly string[];
+	readonly callers: readonly Node[];
+	readonly callees: readonly Node[];
+	readonly boundary: string | undefined;
+};
+
+/** Impact data for the `lattice impact` command. */
+type ImpactData = {
+	readonly directCallers: readonly Node[];
+	readonly transitiveCallers: readonly Node[];
+	readonly affectedFlows: readonly string[];
+	readonly affectedTests: readonly Node[];
+};
+
+/**
+ * Formats the overview output showing all flows, boundaries, and events.
+ *
+ * @param flows - All flow entry points
+ * @param boundaries - All boundary-tagged nodes
+ * @param events - All event connections
+ * @returns Compact text output
+ */
+function formatOverview(
+	flows: readonly FlowEntry[],
+	boundaries: readonly BoundaryEntry[],
+	events: readonly EventConnection[],
+): string {
+	const lines: string[] = [];
+
+	lines.push("Flows:");
+	for (const flow of flows) {
+		const route = flow.node.metadata?.route;
+		const routeStr = route ? `→ ${route} ` : "→ ";
+		lines.push(`  ${flow.value.padEnd(20)} ${routeStr}(${flow.node.file}:${flow.node.lineStart})`);
+	}
+
+	lines.push("");
+	lines.push("Boundaries:");
+	const boundaryGroups = groupBy(boundaries, (b) => b.value);
+	for (const [name, entries] of boundaryGroups) {
+		const files = new Set(entries.map((e) => e.node.file));
+		lines.push(
+			`  ${name.padEnd(20)} → ${entries.length} function${entries.length !== 1 ? "s" : ""} across ${files.size} file${files.size !== 1 ? "s" : ""}`,
+		);
+	}
+
+	lines.push("");
+	lines.push("Events:");
+	for (const event of events) {
+		lines.push(
+			`  ${event.eventName.padEnd(20)} → emitted by ${event.emitterName}, handled by ${event.handlerName}`,
+		);
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Formats a flow call tree with boundary markers and event annotations.
+ *
+ * @param tree - Root node of the flow tree
+ * @returns Indented tree output
+ */
+function formatFlowTree(tree: FlowTreeNode): string {
+	const lines: string[] = [];
+	formatTreeNode(tree, lines, 0);
+	return lines.join("\n");
+}
+
+/** Recursively formats a tree node with indentation. */
+function formatTreeNode(node: FlowTreeNode, lines: string[], depth: number): void {
+	const indent = depth === 0 ? "" : `${"  ".repeat(depth)}→ `;
+	const boundary = node.boundary ? ` [${node.boundary}]` : "";
+	const emits = node.emits ? ` emits ${node.emits}` : "";
+	lines.push(`${indent}${nodeRef(node.node)}${boundary}${emits}`);
+
+	for (const child of node.children) {
+		formatTreeNode(child, lines, depth + 1);
+	}
+}
+
+/**
+ * Formats a symbol's context: signature, flows, callers, callees, boundary.
+ *
+ * @param data - Context data for the symbol
+ * @returns Compact text output
+ */
+function formatContext(data: ContextData): string {
+	const lines: string[] = [];
+
+	lines.push(`${data.node.name} (${data.node.file}:${data.node.lineStart})`);
+
+	if (data.node.signature) {
+		lines.push(`  signature: ${data.node.signature}`);
+	}
+
+	if (data.flows.length > 0) {
+		lines.push(`  flows: ${data.flows.join(", ")} (derived)`);
+	}
+
+	if (data.callers.length > 0) {
+		lines.push("");
+		lines.push("  callers:");
+		for (const caller of data.callers) {
+			lines.push(`    ← ${nodeRef(caller)}`);
+		}
+	}
+
+	if (data.callees.length > 0) {
+		lines.push("");
+		lines.push("  callees:");
+		for (const callee of data.callees) {
+			lines.push(`    → ${nodeRef(callee)}`);
+		}
+	}
+
+	if (data.boundary) {
+		lines.push("");
+		lines.push(`  boundary: ${data.boundary}`);
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Formats impact analysis: direct callers, transitive callers, affected flows, tests.
+ *
+ * @param data - Impact analysis data
+ * @returns Compact text output
+ */
+function formatImpact(data: ImpactData): string {
+	const lines: string[] = [];
+
+	lines.push("Direct callers:");
+	for (const caller of data.directCallers) {
+		lines.push(`  ← ${nodeRef(caller)}`);
+	}
+
+	if (data.transitiveCallers.length > 0) {
+		lines.push("");
+		lines.push("Transitive callers:");
+		for (const caller of data.transitiveCallers) {
+			lines.push(`  ← ${nodeRef(caller)}`);
+		}
+	}
+
+	if (data.affectedFlows.length > 0) {
+		lines.push("");
+		lines.push(`Affected flows: ${data.affectedFlows.join(", ")}`);
+	}
+
+	if (data.affectedTests.length > 0) {
+		lines.push("");
+		lines.push("Tests:");
+		for (const test of data.affectedTests) {
+			lines.push(`  ${test.id}`);
+		}
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Formats a list of callers.
+ *
+ * @param callers - Nodes that call the target
+ * @returns Compact text output
+ */
+function formatCallers(callers: readonly Node[]): string {
+	return callers.map((c) => `← ${nodeRef(c)}`).join("\n");
+}
+
+/**
+ * Formats a list of callees.
+ *
+ * @param callees - Nodes that the target calls
+ * @returns Compact text output
+ */
+function formatCallees(callees: readonly Node[]): string {
+	return callees.map((c) => `→ ${nodeRef(c)}`).join("\n");
+}
+
+/**
+ * Formats boundaries grouped by system name.
+ *
+ * @param entries - All boundary entries
+ * @returns Compact text output
+ */
+function formatBoundaries(entries: readonly BoundaryEntry[]): string {
+	const lines: string[] = [];
+	const groups = groupBy(entries, (e) => e.value);
+
+	for (const [name, group] of groups) {
+		lines.push(`${name}:`);
+		for (const entry of group) {
+			lines.push(`  ${nodeRef(entry.node)}`);
+		}
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Formats event connections.
+ *
+ * @param events - All event connections
+ * @returns Compact text output
+ */
+function formatEvents(events: readonly EventConnection[]): string {
+	const lines: string[] = [];
+	for (const event of events) {
+		lines.push(
+			`${event.eventName} → emitted by ${event.emitterName}, handled by ${event.handlerName}`,
+		);
+	}
+	return lines.join("\n");
+}
+
+/** Groups an array by a key function. */
+function groupBy<T>(items: readonly T[], keyFn: (item: T) => string): Map<string, T[]> {
+	const groups = new Map<string, T[]>();
+	for (const item of items) {
+		const key = keyFn(item);
+		const existing = groups.get(key);
+		if (existing) {
+			existing.push(item);
+		} else {
+			groups.set(key, [item]);
+		}
+	}
+	return groups;
+}
+
+export {
+	type ContextData,
+	type FlowTreeNode,
+	formatBoundaries,
+	formatCallees,
+	formatCallers,
+	formatContext,
+	formatEvents,
+	formatFlowTree,
+	formatImpact,
+	formatOverview,
+	type ImpactData,
+};

package/src/types/config.ts

@@ -0,0 +1,32 @@
+/** Configuration for a Python language section. */
+type PythonConfig = {
+	readonly sourceRoots: readonly string[];
+	readonly testPaths: readonly string[];
+	readonly frameworks: readonly string[];
+};
+
+/** Configuration for a TypeScript language section. */
+type TypeScriptConfig = {
+	readonly sourceRoots: readonly string[];
+	readonly testPaths: readonly string[];
+	readonly tsconfig: string | undefined;
+	readonly frameworks: readonly string[];
+};
+
+/** Lint-specific configuration. */
+type LintConfig = {
+	readonly strict: boolean;
+	readonly ignore: readonly string[];
+};
+
+/** Top-level Lattice configuration parsed from lattice.toml. */
+type LatticeConfig = {
+	readonly languages: readonly string[];
+	readonly root: string;
+	readonly exclude: readonly string[];
+	readonly python: PythonConfig | undefined;
+	readonly typescript: TypeScriptConfig | undefined;
+	readonly lint: LintConfig;
+};
+
+export type { LatticeConfig, LintConfig, PythonConfig, TypeScriptConfig };

package/src/types/graph.ts

@@ -0,0 +1,87 @@
+/** Valid kinds for graph nodes. */
+const NODE_KINDS = ["function", "method", "class", "type", "module"] as const;
+type NodeKind = (typeof NODE_KINDS)[number];
+
+/** Valid kinds for graph edges. */
+const EDGE_KINDS = ["calls", "imports", "implements", "contains", "event"] as const;
+type EdgeKind = (typeof EDGE_KINDS)[number];
+
+/** Valid kinds for lattice tags. */
+const TAG_KINDS = ["flow", "boundary", "emits", "handles"] as const;
+type TagKind = (typeof TAG_KINDS)[number];
+
+/** Certainty level of an edge relationship. */
+const CERTAINTY_LEVELS = ["certain", "uncertain"] as const;
+type Certainty = (typeof CERTAINTY_LEVELS)[number];
+
+/** Reasons an extractor may fail to resolve a reference. */
+const UNRESOLVED_REASONS = [
+	"dynamic_dispatch",
+	"unknown_module",
+	"computed_property",
+	"untyped_call",
+] as const;
+type UnresolvedReason = (typeof UNRESOLVED_REASONS)[number];
+
+/** A symbol in the codebase (function, class, method, type, module). */
+type Node = {
+	readonly id: string;
+	readonly kind: NodeKind;
+	readonly name: string;
+	readonly file: string;
+	readonly lineStart: number;
+	readonly lineEnd: number;
+	readonly language: string;
+	readonly signature: string | undefined;
+	readonly isTest: boolean;
+	readonly metadata: Record<string, string> | undefined;
+};
+
+/** A directed relationship between two nodes. */
+type Edge = {
+	readonly sourceId: string;
+	readonly targetId: string;
+	readonly kind: EdgeKind;
+	readonly certainty: Certainty;
+};
+
+/** A lattice annotation on a node. */
+type Tag = {
+	readonly nodeId: string;
+	readonly kind: TagKind;
+	readonly value: string;
+};
+
+/** A reference that could not be resolved during extraction. */
+type UnresolvedReference = {
+	readonly file: string;
+	readonly line: number;
+	readonly expression: string;
+	readonly reason: UnresolvedReason;
+};
+
+/** The complete output of extracting a single file. */
+type ExtractionResult = {
+	readonly nodes: readonly Node[];
+	readonly edges: readonly Edge[];
+	readonly tags: readonly Tag[];
+	readonly unresolved: readonly UnresolvedReference[];
+};
+
+export {
+	CERTAINTY_LEVELS,
+	type Certainty,
+	EDGE_KINDS,
+	type Edge,
+	type EdgeKind,
+	type ExtractionResult,
+	NODE_KINDS,
+	type Node,
+	type NodeKind,
+	TAG_KINDS,
+	type Tag,
+	type TagKind,
+	UNRESOLVED_REASONS,
+	type UnresolvedReason,
+	type UnresolvedReference,
+};

package/src/types/lint.ts

@@ -0,0 +1,21 @@
+/** Severity levels for lint issues. */
+const LINT_SEVERITIES = ["error", "warning", "info"] as const;
+type LintSeverity = (typeof LINT_SEVERITIES)[number];
+
+/** A single lint issue found in the codebase. */
+type LintIssue = {
+	readonly severity: LintSeverity;
+	readonly file: string;
+	readonly line: number;
+	readonly symbol: string;
+	readonly message: string;
+};
+
+/** Aggregate result of running all lint checks. */
+type LintResult = {
+	readonly issues: readonly LintIssue[];
+	readonly coverage: { readonly tagged: number; readonly total: number };
+	readonly unresolvedCount: number;
+};
+
+export type { LintIssue, LintResult, LintSeverity };

package/src/types/result.ts

@@ -0,0 +1,58 @@
+/** Represents a successful result containing data of type T. */
+type Ok<T> = { readonly ok: true; readonly data: T };
+
+/** Represents a failed result containing an error of type E. */
+type Err<E> = { readonly ok: false; readonly error: E };
+
+/**
+ * Discriminated union representing either success or failure.
+ * Used throughout the codebase instead of exceptions for error handling.
+ */
+type Result<T, E> = Ok<T> | Err<E>;
+
+/** Creates a successful Result wrapping the given data. */
+function ok<T>(data: T): Ok<T> {
+	return { ok: true, data };
+}
+
+/** Creates a failed Result wrapping the given error. */
+function err<E>(error: E): Err<E> {
+	return { ok: false, error };
+}
+
+/** Type guard that narrows a Result to Ok. */
+function isOk<T, E>(result: Result<T, E>): result is Ok<T> {
+	return result.ok;
+}
+
+/** Type guard that narrows a Result to Err. */
+function isErr<T, E>(result: Result<T, E>): result is Err<E> {
+	return !result.ok;
+}
+
+/**
+ * Extracts the data from an Ok result or throws on Err.
+ * Only use at program boundaries — prefer pattern matching elsewhere.
+ *
+ * @param result - The result to unwrap
+ * @returns The data inside the Ok variant
+ * @throws Error if the result is Err
+ */
+function unwrap<T, E>(result: Result<T, E>): T {
+	if (result.ok) return result.data;
+	throw new Error(`Unwrap called on Err: ${String(result.error)}`);
+}
+
+/**
+ * Transforms the data inside an Ok result, passes Err through unchanged.
+ *
+ * @param result - The result to transform
+ * @param fn - Transformation function applied to the Ok data
+ * @returns A new Result with the transformed data or the original error
+ */
+function mapResult<T, U, E>(result: Result<T, E>, fn: (data: T) => U): Result<U, E> {
+	if (result.ok) return ok(fn(result.data));
+	return result;
+}
+
+export { type Err, err, isErr, isOk, mapResult, type Ok, ok, type Result, unwrap };