@danypops/lector 0.1.0

package/src/index.ts

@@ -0,0 +1,121 @@
+export { GitRepoFetcher, type GitRepoFetcherOptions } from "./adapters/git-repo-fetcher.ts";
+export { InMemoryContentCache } from "./adapters/in-memory-content-cache.ts";
+export { InMemorySearchCache, type InMemorySearchCacheOptions } from "./adapters/in-memory-search-cache.ts";
+export { InMemorySymbolGraph } from "./adapters/in-memory-symbol-graph.ts";
+export { InMemoryWorkspace } from "./adapters/in-memory-workspace.ts";
+export { LocalFilesystemWorkspace, PathEscapesWorkspaceRoot } from "./adapters/local-filesystem-workspace.ts";
+export { LocalGit } from "./adapters/local-git.ts";
+export {
+	LanguageServerProcess,
+	LanguageServerProcessExited,
+	LanguageServerRequestTimedOut,
+} from "./adapters/lsp/language-server-process.ts";
+export { LspSymbolIndex } from "./adapters/lsp/lsp-symbol-index.ts";
+export { ReadOnlyWorkspace, WorkspaceIsReadOnly } from "./adapters/read-only-workspace.ts";
+export { RipgrepTextSearch } from "./adapters/ripgrep-text-search.ts";
+export { deriveSourceManifest, type SourceManifest, SourceManifestLimitExceeded } from "./adapters/source-manifest.ts";
+export { SqliteContentCache } from "./adapters/sqlite-content-cache.ts";
+export { SqliteSearchCache, type SqliteSearchCacheOptions } from "./adapters/sqlite-search-cache.ts";
+export { SqliteSymbolGraph } from "./adapters/sqlite-symbol-graph.ts";
+export { TieredSearchCache } from "./adapters/tiered-search-cache.ts";
+export { TreeSitterSymbolIndex } from "./adapters/tree-sitter/typescript-tree-sitter-symbol-index.ts";
+export {
+	type ConnectLectorClientOptions,
+	connectLectorClient,
+	connectLectorClientAt,
+	type LectorClient,
+	remoteErrorIs,
+} from "./client.ts";
+export { resolveLectorPaths } from "./constants.ts";
+export { buildLectorApp, type LectorDaemonOptions, serveMain, startLectorDaemon } from "./daemon.ts";
+export { assertSafeGitArgument, UnsafeGitArgument } from "./domain/assert-safe-git-argument.ts";
+export { assertSafePathSegment, UnsafePathSegment } from "./domain/assert-safe-path-segment.ts";
+export { assertSafeRepoReference } from "./domain/assert-safe-repo-reference.ts";
+export { assertSafeSearchQuery, UnsafeSearchQuery } from "./domain/assert-safe-search-query.ts";
+export {
+	BoundedJobExecutor,
+	type BoundedJobExecutorOptions,
+	JobCapacityExceeded,
+	JobExecutorClosed,
+	JobNotFound,
+	type JobPriority,
+	type JobSnapshot,
+} from "./domain/bounded-job-executor.ts";
+export type { CallHierarchyEntry, IncomingCall, OutgoingCall } from "./domain/call-hierarchy.ts";
+export type { CodeRange } from "./domain/code-range.ts";
+export { type ContentHash, contentHashOf } from "./domain/content-hash.ts";
+export type { Diagnostic, DiagnosticSeverity } from "./domain/diagnostic.ts";
+export { diagnostics } from "./domain/diagnostics.ts";
+export type { DocumentSymbolEntry } from "./domain/document-symbol.ts";
+export { documentSymbols } from "./domain/document-symbols.ts";
+export {
+	type EditOutcome,
+	type ExpectedHashEdit,
+	exactEdit,
+	StaleExpectedHash,
+} from "./domain/exact-edit.ts";
+export { findReferences } from "./domain/find-references.ts";
+export { findWorkspaceSymbols } from "./domain/find-workspace-symbols.ts";
+export type { GitDiffResult } from "./domain/git-diff-result.ts";
+export type { GitLogEntry } from "./domain/git-log-entry.ts";
+export type { GitStatusEntry, GitStatusSummary } from "./domain/git-status.ts";
+export { goToDefinition } from "./domain/go-to-definition.ts";
+export { goToImplementation } from "./domain/go-to-implementation.ts";
+export type { Hover } from "./domain/hover.ts";
+export { hoverAt } from "./domain/hover-at.ts";
+export { incomingCalls } from "./domain/incoming-calls.ts";
+export {
+	descriptorForExtension,
+	LANGUAGE_SERVER_DESCRIPTORS,
+	type LanguageServerDescriptor,
+	PYTHON_DESCRIPTOR,
+	TYPESCRIPT_DESCRIPTOR,
+} from "./domain/language-server-descriptor.ts";
+export { outgoingCalls } from "./domain/outgoing-calls.ts";
+export { type PopulateSymbolGraphResult, populateSymbolGraph } from "./domain/populate-symbol-graph.ts";
+export { prepareCallHierarchy } from "./domain/prepare-call-hierarchy.ts";
+export { raceWorkspaceQuery } from "./domain/race-workspace-query.ts";
+export { type RawRead, rawRead, WorkspaceEntryNotFound } from "./domain/raw-read.ts";
+export { reachableSymbolsFrom } from "./domain/reachable-symbols-from.ts";
+export { RepoFetchFailed, type RepoFetchResult } from "./domain/repo-fetch-result.ts";
+export type { RepoReference } from "./domain/repo-reference.ts";
+export { deriveSearchCacheKey, type SearchCacheKey } from "./domain/search-cache-key.ts";
+export { searchText } from "./domain/search-text.ts";
+export { symbolEdgesFrom } from "./domain/symbol-edges-from.ts";
+export { symbolEdgesTo } from "./domain/symbol-edges-to.ts";
+export type { SymbolGraphGeneration, WorkspaceCacheStatus } from "./domain/symbol-graph-generation.ts";
+export { deriveSymbolNodeId, type SymbolNodeId } from "./domain/symbol-node-id.ts";
+export type { TextSearchMatch, TextSearchResult } from "./domain/text-search-result.ts";
+export type { WorkspaceQueryOutcome, WorkspaceQueryStatus } from "./domain/workspace-query-outcome.ts";
+export type { WorkspaceLocation, WorkspaceSymbol } from "./domain/workspace-symbol.ts";
+export type { CodeIntelligencePort } from "./ports/code-intelligence-port.ts";
+export type { ContentCacheEntry, ContentCachePort, ContentSymbol } from "./ports/content-cache-port.ts";
+export type { GitPort } from "./ports/git-port.ts";
+export type { RepoFetcherPort } from "./ports/repo-fetcher-port.ts";
+export type { SearchCachePort } from "./ports/search-cache-port.ts";
+export type { SymbolEdgeKind, SymbolGraphPort, SymbolNode } from "./ports/symbol-graph-port.ts";
+export type { SymbolIndexPort } from "./ports/symbol-index-port.ts";
+export type { TextSearchOptions, TextSearchPort } from "./ports/text-search-port.ts";
+export type { MissingWorkspaceEntry, PresentWorkspaceEntry, WorkspaceEntry, WorkspacePort } from "./ports/workspace-port.ts";
+export {
+	type ClosableSymbolIndex,
+	CodeIntelligenceUnavailable,
+	createLectorService,
+	InvalidJobInput,
+	InvalidWorkspaceRoot,
+	JobWaitTooLong,
+	type LectorService,
+	type LectorServiceOptions,
+	NotAGitRepository,
+	OPERATION_NAMES,
+	type OperationInputs,
+	type OperationName,
+	type OperationOutputs,
+	RepoFetcherNotConfigured,
+	SymbolQueryUnavailable,
+	UnknownWorkspace,
+	UnsupportedJobOperation,
+	WorkspaceChangedDuringPopulation,
+	type WorkspaceId,
+} from "./service.ts";
+export { lectorVersion } from "./version.ts";

package/src/ports/code-intelligence-port.ts

@@ -0,0 +1,38 @@
+import type { CallHierarchyEntry, IncomingCall, OutgoingCall } from "../domain/call-hierarchy.ts";
+import type { Diagnostic } from "../domain/diagnostic.ts";
+import type { DocumentSymbolEntry } from "../domain/document-symbol.ts";
+import type { Hover } from "../domain/hover.ts";
+import type { WorkspaceLocation } from "../domain/workspace-symbol.ts";
+
+/**
+ * CodeIntelligencePort -- the role a driven adapter plays for the semantic,
+ * position-based queries a real language server (not a syntax-only parser)
+ * can honestly answer: where is this actually defined (across files, through
+ * re-exports and aliasing), what does this resolve to, what's its type/doc,
+ * what's declared in this file. Deliberately separate from SymbolIndexPort
+ * (findSymbols, a fuzzy name search both an LSP and a tree-sitter backend
+ * can serve): tree-sitter has no type system and cannot honestly resolve
+ * cross-file references or hover types, so it does not implement this port
+ * at all rather than faking a degraded answer. Backed by the same warm LSP
+ * process findSymbols already keeps alive per workspace -- not a second one.
+ */
+export interface CodeIntelligencePort {
+	/** Where the symbol at `at` is actually declared -- may cross files, may return more than one candidate. */
+	goToDefinition(at: WorkspaceLocation): Promise<WorkspaceLocation[]>;
+	/** Every concrete implementation of the interface/abstract member at `at` -- unlike goToDefinition, crosses a port/interface boundary into its real adapters. */
+	goToImplementation(at: WorkspaceLocation): Promise<WorkspaceLocation[]>;
+	/** Every project-wide usage of the symbol at `at`. */
+	findReferences(at: WorkspaceLocation, includeDeclaration: boolean): Promise<WorkspaceLocation[]>;
+	/** Type/doc information for the symbol at `at`, or undefined when the server has none. */
+	hover(at: WorkspaceLocation): Promise<Hover | undefined>;
+	/** Every symbol declared in one file, hierarchically. */
+	documentSymbols(path: string): Promise<DocumentSymbolEntry[]>;
+	/** Every diagnostic currently known for one file, as of the server's last analysis (push-based, not a live re-check). */
+	diagnostics(path: string): Promise<Diagnostic[]>;
+	/** The call-hierarchy root(s) the symbol at `at` resolves to -- usually zero or one. */
+	prepareCallHierarchy(at: WorkspaceLocation): Promise<CallHierarchyEntry[]>;
+	/** Every real caller of the symbol at `at`, project-wide. */
+	incomingCalls(at: WorkspaceLocation): Promise<IncomingCall[]>;
+	/** Every function/method the symbol at `at` itself calls. */
+	outgoingCalls(at: WorkspaceLocation): Promise<OutgoingCall[]>;
+}

package/src/ports/content-cache-port.ts

@@ -0,0 +1,52 @@
+import type { ContentHash } from "../domain/content-hash.ts";
+
+/**
+ * A symbol as derivable purely from content -- deliberately NOT WorkspaceSymbol:
+ * WorkspaceSymbol.location.path is a property of which *path* currently holds
+ * this content, not a property of the content itself. Doc 38db976d states two
+ * different files with byte-identical content share one cache entry; if this
+ * type carried a path, the second file to query a shared hash would get back
+ * the *first* file's path attached to its own symbols -- a real, silent
+ * correctness bug this type exists specifically to make impossible. Callers
+ * reattach the current path when turning a ContentSymbol back into a
+ * WorkspaceSymbol for a specific query.
+ */
+export interface ContentSymbol {
+	readonly name: string;
+	readonly kind: string;
+	readonly line: number;
+	readonly character: number;
+	readonly containerName?: string;
+}
+
+/**
+ * One shared, content-addressed cache entry. May hold any subset of the
+ * lenses derived from the same immutable content -- raw bytes, extracted
+ * symbols, and (later) whatever else is derived from that content -- never
+ * two independently-invalidated entries for the same hash.
+ */
+export interface ContentCacheEntry {
+	readonly rawContent?: string;
+	readonly symbols?: readonly ContentSymbol[];
+}
+
+/**
+ * ContentCachePort -- the one store both the filesystem lens (raw text) and
+ * the code-intelligence lens (parsed symbols) read and write, keyed by
+ * ContentHash. Populated incrementally: whichever lens touches a hash first
+ * creates the entry with just that lens present; a later put for the other
+ * lens on the *same* hash adds to the existing entry rather than replacing
+ * it -- this is what makes bidirectional warming possible by construction,
+ * not by hand-wiring each pair of operations to know about each other.
+ *
+ * Content-addressed, so there is no invalidation method: a hash's entry
+ * never becomes wrong (the content it was computed from cannot change
+ * without producing a different hash). What can change is which hash a
+ * *path* currently points to -- that mapping lives above this port, not in
+ * it (see WorkspacePort).
+ */
+export interface ContentCachePort {
+	get(hash: ContentHash): Promise<ContentCacheEntry | undefined>;
+	putRawContent(hash: ContentHash, content: string): Promise<void>;
+	putSymbols(hash: ContentHash, symbols: readonly ContentSymbol[]): Promise<void>;
+}

package/src/ports/git-port.ts

@@ -0,0 +1,23 @@
+import type { GitDiffResult } from "../domain/git-diff-result.ts";
+import type { GitLogEntry } from "../domain/git-log-entry.ts";
+import type { GitStatusSummary } from "../domain/git-status.ts";
+
+/**
+ * GitPort -- the role a driven adapter plays for read-only git queries
+ * against a workspace's repository. Deliberately read-only: Lector's git
+ * layer never constructs a caller-influenced `-c` config override or
+ * mutating flag (clone/push/merge), the exact surface simple-git's own
+ * history shows is where git CLI injection CVEs live. A workspace with no
+ * `.git` directory is a real, expected case (not every registered
+ * workspace is a git repository), not an error condition callers must
+ * special-case per operation.
+ */
+export interface GitPort {
+	/** Undefined when the workspace root is not inside a git repository. */
+	isGitRepository(): Promise<boolean>;
+	status(): Promise<GitStatusSummary>;
+	/** Most recent commits first, bounded to maxCount. */
+	log(maxCount: number): Promise<readonly GitLogEntry[]>;
+	/** Diff against `ref` (defaults to HEAD) of the current working tree, bounded to maxBytes. */
+	diff(ref: string | undefined, maxBytes: number): Promise<GitDiffResult>;
+}

package/src/ports/repo-fetcher-port.ts

@@ -0,0 +1,11 @@
+import type { RepoFetchResult } from "../domain/repo-fetch-result.ts";
+import type { RepoReference } from "../domain/repo-reference.ts";
+
+/**
+ * RepoFetcherPort -- ensures a shallow local clone of an external repo exists, content-addressed
+ * by (host, owner, repo, ref). A caller never mutates a returned checkout; it's a foreign
+ * directory to read and analyze, not one the caller owns.
+ */
+export interface RepoFetcherPort {
+	fetch(reference: RepoReference): Promise<RepoFetchResult>;
+}

package/src/ports/search-cache-port.ts

@@ -0,0 +1,15 @@
+import type { SearchCacheKey } from "../domain/search-cache-key.ts";
+import type { TextSearchResult } from "../domain/text-search-result.ts";
+
+/**
+ * SearchCachePort -- caches searchText results by (workspaceId, query, options), a genuinely
+ * different shape from ContentCachePort's per-content-hash keying: a search result isn't
+ * derived from one file's content, it's derived from a query run against a whole workspace at
+ * a point in time, so it needs its own TTL rather than ContentCachePort's "never invalidates"
+ * contract (which only holds because content-addressing makes invalidation structurally
+ * impossible to need -- that reasoning doesn't apply here).
+ */
+export interface SearchCachePort {
+	get(key: SearchCacheKey): Promise<TextSearchResult | undefined>;
+	set(key: SearchCacheKey, result: TextSearchResult): Promise<void>;
+}

package/src/ports/symbol-graph-port.ts

@@ -0,0 +1,35 @@
+import type { SymbolGraphGeneration } from "../domain/symbol-graph-generation.ts";
+import type { SymbolNodeId } from "../domain/symbol-node-id.ts";
+import type { WorkspaceLocation } from "../domain/workspace-symbol.ts";
+
+/** A node's own identity and declaration -- what's shown, not derived relationships. */
+export interface SymbolNode {
+	readonly id: SymbolNodeId;
+	readonly name: string;
+	readonly kind: string;
+	readonly location: WorkspaceLocation;
+}
+
+export type SymbolEdgeKind = "calls" | "references" | "contains";
+
+/**
+ * SymbolGraphPort -- a persisted, queryable graph of symbol relationships,
+ * populated by a batch indexing pass rather than answered live per query,
+ * so multi-hop questions (transitive callers, reachability) don't require
+ * chaining many sequential LSP calls. maxDepth is required: an unbounded
+ * traversal has no place in a bounded-resource daemon.
+ */
+export interface SymbolGraphPort {
+	addNode(node: SymbolNode): Promise<void>;
+	getNode(id: SymbolNodeId): Promise<SymbolNode | undefined>;
+	addEdge(from: SymbolNodeId, to: SymbolNodeId, kind: SymbolEdgeKind): Promise<void>;
+	/** Direct out-edges from `id` -- who/what `id` points to. */
+	edgesFrom(id: SymbolNodeId, kind?: SymbolEdgeKind): Promise<readonly SymbolNodeId[]>;
+	/** Direct in-edges to `id` -- who/what points to `id`. */
+	edgesTo(id: SymbolNodeId, kind?: SymbolEdgeKind): Promise<readonly SymbolNodeId[]>;
+	/** Every node reachable from `id` by following out-edges, up to `maxDepth` hops, excluding `id` itself. */
+	reachableFrom(id: SymbolNodeId, options: { maxDepth: number; kind?: SymbolEdgeKind }): Promise<readonly SymbolNodeId[]>;
+	getGeneration(): Promise<SymbolGraphGeneration | undefined>;
+	setGeneration(generation: SymbolGraphGeneration): Promise<void>;
+	close(): Promise<void>;
+}

package/src/ports/symbol-index-port.ts

@@ -0,0 +1,11 @@
+import type { WorkspaceSymbol } from "../domain/workspace-symbol.ts";
+
+/**
+ * SymbolIndexPort -- the role a driven adapter plays for symbol queries:
+ * given a fuzzy query string, return matching workspace symbols. Implemented
+ * by an LSP-backed adapter and a tree-sitter-backed adapter; both satisfy
+ * this same interface.
+ */
+export interface SymbolIndexPort {
+	findSymbols(query: string): Promise<WorkspaceSymbol[]>;
+}

package/src/ports/text-search-port.ts

@@ -0,0 +1,12 @@
+import type { TextSearchResult } from "../domain/text-search-result.ts";
+
+export interface TextSearchOptions {
+	readonly maxMatches: number;
+	/** Bound on the total bytes of matched line text returned, not on bytes scanned. */
+	readonly maxBytes: number;
+}
+
+/** TextSearchPort -- multi-file text/regex search scoped to one workspace root. */
+export interface TextSearchPort {
+	search(rootPath: string, query: string, options: TextSearchOptions): Promise<TextSearchResult>;
+}

package/src/ports/workspace-port.ts

@@ -0,0 +1,35 @@
+import type { ContentHash } from "../domain/content-hash.ts";
+
+/** A workspace entry that does not (yet) exist. Distinguished from empty content. */
+export interface MissingWorkspaceEntry {
+	readonly exists: false;
+}
+
+/** A workspace entry that exists, with its raw content. */
+export interface PresentWorkspaceEntry {
+	readonly exists: true;
+	readonly content: string;
+}
+
+export type WorkspaceEntry = MissingWorkspaceEntry | PresentWorkspaceEntry;
+
+/**
+ * WorkspacePort — the role a driven adapter plays for Lector's core: give the
+ * domain raw access to one workspace's entries, and apply an expected-hash-
+ * guarded edit atomically. `writeEntry` must reject a stale `expectedHash`
+ * (see StaleExpectedHash) rather than silently overwrite.
+ *
+ * Implemented by InMemoryWorkspace for the walking skeleton and contract
+ * tests, and later by a local-filesystem adapter for real workspaces.
+ */
+export interface WorkspacePort {
+	readEntry(path: string): Promise<WorkspaceEntry>;
+
+	/**
+	 * @param expectedHash The hash the caller last observed at `path`, or
+	 *   `null` to assert the path does not yet exist.
+	 * @throws StaleExpectedHash when the entry's current hash does not match
+	 *   `expectedHash`.
+	 */
+	writeEntry(path: string, expectedHash: ContentHash | null, content: string): Promise<{ previousHash: ContentHash | null; newHash: ContentHash }>;
+}