@ctxo/lang-go 0.7.0 → 0.8.0-alpha.0

package/README.md

@@ -0,0 +1,70 @@
+# @ctxo/lang-go
+
+Go language plugin for [Ctxo](https://github.com/alperhankendi/Ctxo). Ships
+two analysis tiers selected at runtime:
+
+| Tier | Engine | Activated when |
+|---|---|---|
+| **Full** | `ctxo-go-analyzer` binary (Go stdlib + `x/tools` SSA + CHA) | Go ≥ 1.22 on PATH **and** the bundled analyzer source builds successfully |
+| **Syntax** | `tree-sitter-go` | Go toolchain absent; binary build fails; or analyzer cannot locate `go.mod` / `go.work` |
+
+The composite picks at `initialize()` and forwards every `extractSymbols` /
+`extractEdges` call to the active layer. `extractComplexity` is always served
+by tree-sitter — the analyzer intentionally emits empty complexity arrays so
+the two layers compose cleanly.
+
+## What full-tier adds over tree-sitter
+
+- **Cross-package symbol-id resolution.** `pkg/a` calling `pkg/b.Do()` produces
+  an edge whose target is `pkg/b/file.go::Do::function`, not a synthetic
+  placeholder. Every `get_blast_radius`, `find_importers`, and `get_logic_slice`
+  query that crosses a package boundary now returns real results.
+- **`implements` edges.** Go's structural typing means interface satisfaction
+  is invisible to a syntactic parser; the analyzer pairs every concrete type
+  against every interface and emits an edge when `types.Implements(T, I)` or
+  `types.Implements(*T, I)` is true.
+- **`extends` edges for embedding.** Anonymous fields (struct embedding) and
+  embedded interface members produce explicit hierarchy edges so
+  `get_class_hierarchy` works on Go.
+- **Generics with `typeArgs` metadata.** `List[int]` and `List[string]` both
+  produce a `uses` edge to the unconstructed `List` symbol; the type
+  arguments are preserved on edge metadata for future query precision.
+  See [ADR-013 §4 Q4](../../docs/architecture/ADR/adr-013-go-full-tier-via-ctxo-go-analyzer-binary.md#open-question-decisions-resolved-2026-04-13).
+- **Dead-code detection via CHA reachability.** Unreachable functions and
+  methods are emitted in a single `dead` record. A reflect-safe pass marks
+  methods of any type touched by `reflect.TypeOf` / `reflect.ValueOf` /
+  `reflect.New` or `json.Marshal` / `Unmarshal` / `NewDecoder` / `NewEncoder`
+  as live to prevent false positives.
+
+## How the binary is built
+
+On first use, `GoAnalyzerAdapter.initialize()` hashes the analyzer source +
+`go version` and runs `go build -trimpath -o
+~/.cache/ctxo/lang-go-analyzer/<hash-goVersion>/ctxo-go-analyzer[.exe]`.
+Subsequent runs reuse the cached binary. No build happens during `npm install`
+to keep package installs sandbox-safe (ADR-013 §4 Q2).
+
+If `go` is not on PATH, build fails, or no `go.mod`/`go.work` is found, the
+plugin transparently falls back to tree-sitter and `ctxo doctor` surfaces the
+missing toolchain.
+
+## Limitations (v0.8.0-alpha.0)
+
+- **Library mode is approximate.** Without a `main.main` to anchor RTA-style
+  reachability, every exported function/method becomes a root. This
+  over-approximates liveness — fewer false dead-code reports, but symbols
+  that nothing actually consumes still look live.
+- **Generic types skipped from `implements` / `extends` enumeration.** Pairing
+  generic named types is unstable in current `go/types`; we revisit when the
+  upstream API stabilizes.
+- **Closures and reflective construction.** Functions passed to stdlib
+  callbacks (`sort.Slice(..., func(i,j) bool {...})`) follow a CHA edge so
+  they ARE reachable; constructed-via-reflection types are kept alive only
+  for the explicit reflect/json call sites listed above.
+
+## Architecture and rationale
+
+See [ADR-013](../../docs/architecture/ADR/adr-013-go-full-tier-via-ctxo-go-analyzer-binary.md)
+for the full decision record (alternative options considered, library
+choices, open question resolutions). Mirrors the C# pattern from
+[ADR-007](../../docs/architecture/ADR/adr-007-csharp-roslyn-lsp.md).

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ILanguageAdapter, SymbolKind, SymbolNode, GraphEdge, ComplexityMetrics, CtxoLanguagePlugin } from '@ctxo/plugin-api';
 import Parser, { Tree, SyntaxNode } from 'tree-sitter';
 
-type Language = Parameters<InstanceType<typeof Parser>['setLanguage']>[0];
+type Language = Parameters<InstanceType<typeof Parser>['setLanguage']>[0] | object;
 
 declare abstract class TreeSitterAdapter implements ILanguageAdapter {
     abstract readonly extensions: readonly string[];
@@ -38,6 +38,73 @@ declare class GoAdapter extends TreeSitterAdapter {
     private findFirstExportedSymbolId;
 }
 
+/**
+ * Full-tier Go adapter. Owns the analyzer binary lifecycle and an
+ * in-memory cache of batch results keyed by project-relative file path.
+ *
+ * Caching strategy: the first extractSymbols/extractEdges call after
+ * initialize() triggers a single batch analysis run. Subsequent calls
+ * read from cache. This keeps the ILanguageAdapter contract intact
+ * (per-file methods) while the binary runs once per index.
+ */
+declare class GoAnalyzerAdapter implements ILanguageAdapter {
+    readonly extensions: readonly [".go"];
+    readonly tier: "full";
+    private moduleRoot;
+    private binaryPath;
+    private modulePathPrefix;
+    private cache;
+    private deadSymbolIds;
+    private hasMain;
+    private timedOut;
+    private batchPromise;
+    private initialized;
+    isSupported(filePath: string): boolean;
+    isReady(): boolean;
+    initialize(rootDir: string): Promise<void>;
+    /**
+     * Returns the dead-symbol set emitted by the last batch run. Empty until
+     * extractSymbols/Edges has been called at least once. Consumed by cli's
+     * find_dead_code MCP tool via the composite delegate.
+     */
+    getDeadSymbolIds(): Set<string>;
+    /** True when the analyzer ran in binary mode (precise dead-code). */
+    reachabilityHasMain(): boolean;
+    /** True when reach analysis exceeded the deadline (degraded precision). */
+    reachabilityTimedOut(): boolean;
+    extractSymbols(filePath: string, _source: string): Promise<SymbolNode[]>;
+    extractEdges(filePath: string, _source: string): Promise<GraphEdge[]>;
+    extractComplexity(_filePath: string, _source: string): Promise<ComplexityMetrics[]>;
+    dispose(): Promise<void>;
+    private ensureBatch;
+    private runBatch;
+    private absorbBatch;
+    private normalizePath;
+    private buildPathRewriter;
+}
+
+/**
+ * Picks between the full-tier ctxo-go-analyzer and the syntax-tier
+ * tree-sitter adapter at initialize() time. Symbols and edges come from
+ * whichever delegate is active; complexity is ALWAYS sourced from
+ * tree-sitter because the binary intentionally emits empty complexity.
+ */
+declare class GoCompositeAdapter implements ILanguageAdapter {
+    private analyzer;
+    private treeSitter;
+    constructor();
+    initialize(rootDir: string): Promise<void>;
+    dispose(): Promise<void>;
+    extractSymbols(filePath: string, source: string): Promise<SymbolNode[]>;
+    extractEdges(filePath: string, source: string): Promise<GraphEdge[]>;
+    extractComplexity(filePath: string, source: string): Promise<ComplexityMetrics[]>;
+    isSupported(filePath: string): boolean;
+    setSymbolRegistry(registry: Map<string, SymbolKind>): void;
+    /** Exposed for cli optimizations. Null when running in syntax tier. */
+    getAnalyzerDelegate(): GoAnalyzerAdapter | null;
+    getTier(): 'full' | 'syntax' | 'unavailable';
+}
+
 declare const plugin: CtxoLanguagePlugin;
 
-export { GoAdapter, TreeSitterAdapter, plugin as default, plugin };
+export { GoAdapter, GoAnalyzerAdapter, GoCompositeAdapter, TreeSitterAdapter, plugin as default, plugin };