opencode-swarm 6.62.0 → 6.64.0

package/dist/graph/graph-builder.d.ts

@@ -0,0 +1,39 @@
+import { type FileNode, type RepoGraph } from './types';
+/**
+ * Build a full repository graph by walking the workspace, parsing source files
+ * for imports and exported symbols, and assembling them into a `RepoGraph`.
+ *
+ * Performance:
+ *   - File scanning skips well-known build/dep directories (node_modules, dist, .git, etc.)
+ *   - Per-file parsing runs with a concurrency limit to avoid overwhelming I/O.
+ *   - Files larger than `MAX_FILE_SIZE_BYTES` are skipped (would also fail downstream extractors).
+ *
+ * Targets ~5s for a 50k LOC repo (~500 files) on commodity hardware.
+ */
+export interface BuildOptions {
+    /** Optional cap on file count to bound runtime on huge repos. */
+    maxFiles?: number;
+    /** Concurrency for per-file parsing. Defaults to 16. */
+    concurrency?: number;
+    /** Additional directory names to skip (merged with defaults). */
+    skipDirs?: string[];
+}
+/**
+ * Hard upper bound on file count if the caller does not supply one. Protects
+ * against unbounded memory growth on extremely large monorepos. Callers can
+ * pass an explicit `maxFiles` (including a larger one) to override.
+ */
+export declare const DEFAULT_MAX_FILES = 10000;
+/**
+ * Walk the workspace and return absolute paths of all supported source files.
+ * Cross-platform: emits absolute paths using the host's path separator.
+ */
+export declare function findSourceFiles(workspaceRoot: string, skipDirs?: Set<string>): string[];
+/**
+ * Build the repo graph from scratch.
+ */
+export declare function buildRepoGraph(workspaceRoot: string, options?: BuildOptions): Promise<RepoGraph>;
+/**
+ * Process a single file into a FileNode. Returns null if the file cannot be processed.
+ */
+export declare function processFile(absoluteFilePath: string, workspaceRoot: string): Promise<FileNode | null>;

package/dist/graph/graph-query.d.ts

@@ -0,0 +1,42 @@
+import type { BlastRadiusResult, FileNode, FileReference, LocalizationBlock, RepoGraph, SymbolReference } from './types';
+/**
+ * Query API for the repo graph.
+ *
+ * All functions accept normalized RELATIVE forward-slash paths and return the
+ * same. Callers responsible for normalizing input paths (helper provided).
+ */
+export declare function normalizeGraphPath(p: string): string;
+/**
+ * Files that import the given file (direct dependents).
+ */
+export declare function getImporters(graph: RepoGraph, filePath: string): FileReference[];
+/**
+ * Files this file imports (direct dependencies, resolved targets only).
+ */
+export declare function getDependencies(graph: RepoGraph, filePath: string): FileReference[];
+/**
+ * Find all importers of a specific exported symbol from a file.
+ */
+export declare function getSymbolConsumers(graph: RepoGraph, filePath: string, symbolName: string): SymbolReference[];
+/**
+ * Compute the transitive blast radius of changing one or more files.
+ *
+ * Performs a BFS over the reverse-edge index up to `maxDepth` levels.
+ */
+export declare function getBlastRadius(graph: RepoGraph, filePaths: string[], maxDepth?: number): BlastRadiusResult;
+/**
+ * Top-N most-imported files (by in-degree) — useful for surfacing
+ * architectural pillars.
+ */
+export declare function getKeyFiles(graph: RepoGraph, topN?: number): FileNode[];
+/**
+ * Build a compact localization block for a single file. This is the primary
+ * payload injected into the coder agent's pre-edit context.
+ */
+export declare function getLocalizationContext(graph: RepoGraph, filePath: string, options?: {
+    maxImporters?: number;
+    maxDeps?: number;
+    maxDepth?: number;
+}): LocalizationBlock;
+/** Reset the cached reverse index. Call this when a graph is mutated in place. */
+export declare function resetQueryCache(): void;

package/dist/graph/graph-store.d.ts

@@ -0,0 +1,27 @@
+import { type RepoGraph } from './types';
+export declare function getGraphPath(workspaceRoot: string): string;
+export declare function loadGraph(workspaceRoot: string): RepoGraph | null;
+export declare function saveGraph(workspaceRoot: string, graph: RepoGraph): void;
+/**
+ * Build the graph from scratch and persist it.
+ */
+export declare function buildAndSaveGraph(workspaceRoot: string): Promise<RepoGraph>;
+/**
+ * Apply incremental updates for a list of changed (or potentially-changed) files.
+ *
+ * For each file:
+ *   - If the file no longer exists, its node is removed.
+ *   - Otherwise its node is re-parsed and replaced.
+ *
+ * Returns the updated graph (mutated in place AND returned for convenience).
+ * Caller must call `saveGraph` to persist if desired.
+ */
+export declare function updateGraphIncremental(workspaceRoot: string, changedRelativePaths: string[], graph: RepoGraph): Promise<RepoGraph>;
+/**
+ * Determine if a stored graph is fresh enough to reuse.
+ *
+ * Default freshness window: 5 minutes. Files added/removed outside this
+ * window are not detected without an explicit incremental update — callers
+ * that care about up-to-the-second accuracy should rebuild.
+ */
+export declare function isGraphFresh(graph: RepoGraph | null, maxAgeMs?: number): boolean;

package/dist/graph/import-extractor.d.ts

@@ -0,0 +1,44 @@
+import type { ImportEdge } from './types';
+/**
+ * Extract import edges from a source file.
+ *
+ * Uses regex-based parsing (the same proven approach as `src/tools/imports.ts`
+ * and `src/tools/co-change-analyzer.ts`). Tree-sitter is intentionally not used
+ * here because:
+ *   1. The existing regex patterns are battle-tested across the codebase.
+ *   2. Import statements have stable, simple syntax that regex handles reliably.
+ *   3. Avoiding the per-file Tree-sitter parse keeps full-graph builds fast
+ *      enough to be interactive (target: <5s for 50k LOC).
+ *
+ * Supported languages:
+ *   - TypeScript / JavaScript (.ts/.tsx/.js/.jsx/.mjs/.cjs) — ES modules + CJS require
+ *   - Python (.py) — `import x` and `from x import y`
+ *   - Go (.go) — `import "path"` and `import (...)` blocks
+ *   - Rust (.rs) — `use path::module`
+ *
+ * Only RELATIVE imports are tracked as graph edges. External package imports
+ * (e.g. 'react', 'fmt', 'std::fs') are skipped — they are not part of the
+ * intra-repo dependency graph.
+ */
+export interface ExtractImportsOptions {
+    /** Absolute path to the source file (used for relative resolution). */
+    absoluteFilePath: string;
+    /** Absolute workspace root (used for relative path computation). */
+    workspaceRoot: string;
+    /** Optional pre-read content; if omitted the file is read from disk. */
+    content?: string;
+}
+/** Source file extensions we know how to scan. */
+export declare const SOURCE_EXTENSIONS: readonly [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".go", ".rs"];
+export declare function getLanguageFromExtension(ext: string): string | null;
+/**
+ * Extract import edges for a single file. Returns an empty array when the
+ * language is unsupported or the file cannot be parsed.
+ *
+ * Resolution strategy for edge.target:
+ *   - TS/JS: probe extensions (.ts, .tsx, .js, .jsx, .mjs, .cjs, /index.*).
+ *   - Python: probe .py and /__init__.py for relative imports only.
+ *   - Go/Rust: target left empty (intra-repo resolution requires module/crate
+ *     metadata that is out of scope for Phase 1). The raw module is preserved.
+ */
+export declare function extractImports(opts: ExtractImportsOptions): ImportEdge[];

package/dist/graph/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Repo graph: structural codebase awareness for swarm agents.
+ *
+ * Public surface:
+ *   - Types (RepoGraph, FileNode, ImportEdge, ExportedSymbol, ...)
+ *   - Builders (buildRepoGraph, processFile, findSourceFiles)
+ *   - Store (loadGraph, saveGraph, buildAndSaveGraph, updateGraphIncremental, isGraphFresh, getGraphPath)
+ *   - Query (getImporters, getDependencies, getSymbolConsumers, getBlastRadius,
+ *            getKeyFiles, getLocalizationContext, normalizeGraphPath, resetQueryCache)
+ */
+export { type BuildOptions, buildRepoGraph, findSourceFiles, processFile, } from './graph-builder';
+export { getBlastRadius, getDependencies, getImporters, getKeyFiles, getLocalizationContext, getSymbolConsumers, normalizeGraphPath, resetQueryCache, } from './graph-query';
+export { buildAndSaveGraph, getGraphPath, isGraphFresh, loadGraph, saveGraph, updateGraphIncremental, } from './graph-store';
+export { extractImports, getLanguageFromExtension, SOURCE_EXTENSIONS, } from './import-extractor';
+export { extractExportedSymbols } from './symbol-extractor';
+export * from './types';

package/dist/graph/symbol-extractor.d.ts

@@ -0,0 +1,17 @@
+import type { ExportedSymbol } from './types';
+/**
+ * Extract exported symbols from a single file.
+ *
+ * Reuses the proven regex-based extractors from `src/tools/symbols.ts`
+ * (`extractTSSymbols` / `extractPythonSymbols`) and maps their internal
+ * SymbolInfo shape to our `ExportedSymbol` type.
+ *
+ * For Go and Rust, exported-symbol extraction is best-effort (out of scope
+ * for Phase 1) — empty arrays are returned. The graph still tracks file-level
+ * import edges for these languages.
+ */
+/**
+ * @param relativeFilePath - file path relative to workspace root (forward-slash)
+ * @param workspaceRoot - absolute workspace root
+ */
+export declare function extractExportedSymbols(relativeFilePath: string, workspaceRoot: string): ExportedSymbol[];

package/dist/graph/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Repo graph data structures.
+ *
+ * The graph captures structural relationships between source files
+ * (imports/exports) so agents can reason about blast radius before editing.
+ *
+ * All paths are RELATIVE to the workspace root and FORWARD-SLASH normalized
+ * for cross-platform comparison.
+ */
+export type ImportType = 'named' | 'default' | 'namespace' | 'sideeffect' | 'require';
+export interface ImportEdge {
+    /** Importing file (relative, forward-slash). */
+    source: string;
+    /** Resolved imported file (relative, forward-slash). May be empty for unresolved imports. */
+    target: string;
+    /** Raw module specifier as written in the source (e.g. '../utils/path-security'). */
+    rawModule: string;
+    /** Named imports brought in (empty for sideeffect/namespace/default). */
+    importedSymbols: string[];
+    /** What kind of import statement this is. */
+    importType: ImportType;
+    /** 1-indexed line number where the import appears. */
+    line: number;
+}
+export type SymbolKind = 'function' | 'class' | 'interface' | 'type' | 'enum' | 'const' | 'variable' | 'method' | 'property';
+export interface ExportedSymbol {
+    name: string;
+    kind: SymbolKind;
+    signature?: string;
+    line: number;
+}
+export interface FileNode {
+    /** Relative, forward-slash path. */
+    path: string;
+    /** Detected language id (e.g. 'typescript', 'python', 'go', 'rust'). */
+    language: string;
+    /** Symbols this file exports (or top-level definitions for languages without explicit exports). */
+    exports: ExportedSymbol[];
+    /** Outgoing import edges from this file. */
+    imports: ImportEdge[];
+    /** mtime of the source file (ms epoch) for incremental updates. */
+    mtimeMs: number;
+}
+export interface RepoGraph {
+    /** Schema version for migration. */
+    version: number;
+    /** ISO timestamp when this graph was built. */
+    buildTimestamp: string;
+    /** Workspace root used at build time (absolute, for diagnostics only). */
+    rootDir: string;
+    /** Files keyed by their relative forward-slash path. */
+    files: Record<string, FileNode>;
+}
+export interface FileReference {
+    file: string;
+    line?: number;
+    importType?: ImportType;
+}
+export interface SymbolReference {
+    file: string;
+    line: number;
+    importedAs: string;
+}
+export interface BlastRadiusResult {
+    target: string[];
+    directDependents: string[];
+    transitiveDependents: string[];
+    depthReached: number;
+    totalDependents: number;
+    riskLevel: 'low' | 'medium' | 'high' | 'critical';
+}
+export interface LocalizationBlock {
+    target: string;
+    importerCount: number;
+    importers: FileReference[];
+    dependencyCount: number;
+    dependencies: FileReference[];
+    exportedSymbolsUsedExternally: string[];
+    blastRadius: BlastRadiusResult;
+    /** Compact human/LLM-readable summary suitable for context injection. */
+    summary: string;
+}
+export declare const REPO_GRAPH_SCHEMA_VERSION = 1;
+export declare const REPO_GRAPH_FILENAME = "repo-graph.json";

package/dist/hooks/repo-graph-injection.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Repo graph context injection for the system-enhancer hook.
+ *
+ * Produces compact text blocks that surface structural information
+ * (importers, dependents, blast radius) for the file the agent is about
+ * to edit. Designed to fit within the system-enhancer's per-block budget
+ * (~300-500 chars).
+ *
+ * Failure mode: silent. If no graph exists (`.swarm/repo-graph.json`
+ * absent or invalid), this module returns `null` for every helper —
+ * the agent simply doesn't get the extra context. The graph is built
+ * on-demand by the agent calling `repo_map` with action="build".
+ *
+ * Caching: the loaded graph is cached per-directory in module scope to
+ * avoid re-reading the JSON on every system prompt construction. The
+ * cache is bypassed if the file's mtime advances.
+ */
+import { type RepoGraph } from '../graph';
+/**
+ * Load the repo graph for `directory`, using a per-directory cache that
+ * invalidates on file mtime change. Returns null if no graph exists.
+ *
+ * Exported only for tests; production callers use the buildXxxBlock helpers below.
+ */
+export declare function getCachedGraph(directory: string): RepoGraph | null;
+/** Test-only: clear the per-directory cache. */
+export declare function resetGraphInjectionCache(): void;
+/**
+ * Build a localization block for a target file. Used by the coder agent
+ * to surface importers/dependencies/blast-radius before editing.
+ *
+ * Returns null when:
+ *   - No graph exists.
+ *   - The target isn't tracked in the graph (file too new, language unsupported).
+ */
+export declare function buildCoderLocalizationBlock(directory: string, targetFile: string): string | null;
+/**
+ * Build a blast-radius block for a list of changed files. Used by the
+ * reviewer agent to spot-check whether unseen consumers might break.
+ *
+ * Returns null when no graph exists or when none of the files are in the
+ * graph. The result is bounded to the top 8 dependents to stay within
+ * the per-block context budget.
+ */
+export declare function buildReviewerBlastRadiusBlock(directory: string, changedFiles: string[]): string | null;