typegraph-mcp 0.9.37 → 0.9.39

package/install-oxlint-test.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env npx tsx
+
+import * as assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+function copyDir(src: string, dest: string): void {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function runTsx(
+  toolRoot: string,
+  args: string[],
+  cwd: string
+): string {
+  return execFileSync(path.join(toolRoot, "node_modules/.bin/tsx"), args, {
+    cwd,
+    encoding: "utf-8",
+    maxBuffer: 10 * 1024 * 1024,
+    env: process.env,
+  });
+}
+
+function assertIncludes(text: string, expected: string): void {
+  assert.ok(
+    text.includes(expected),
+    `Expected output to include:\n${expected}\n\nActual output:\n${text}`
+  );
+}
+
+async function main(): Promise<void> {
+  const repoRoot = import.meta.dirname;
+  const fixtureRoot = path.join(repoRoot, ".fixtures/install-oxlint");
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "typegraph-install-oxlint-"));
+  const projectRoot = path.join(tempRoot, "project");
+
+  copyDir(fixtureRoot, projectRoot);
+  fs.mkdirSync(path.join(projectRoot, "node_modules"), { recursive: true });
+  fs.symlinkSync(
+    path.join(repoRoot, "node_modules/typescript"),
+    path.join(projectRoot, "node_modules/typescript"),
+    "dir"
+  );
+
+  try {
+    const setupOutput = runTsx(repoRoot, [path.join(repoRoot, "cli.ts"), "setup", "--yes"], projectRoot);
+    const pluginRoot = path.join(projectRoot, "plugins/typegraph-mcp");
+
+    const tsconfig = fs.readFileSync(path.join(projectRoot, "tsconfig.json"), "utf-8");
+    const oxlint = fs.readFileSync(path.join(projectRoot, ".oxlintrc.json"), "utf-8");
+
+    assertIncludes(tsconfig, '"$schema": "http://json.schemastore.org/tsconfig"');
+    assertIncludes(tsconfig, '"exclude": ["plugins/**"]');
+    assertIncludes(oxlint, '"ignorePatterns": [');
+    assertIncludes(oxlint, '"plugins/**"');
+    assert.ok(fs.existsSync(path.join(pluginRoot, "cli.ts")), "Expected installed plugin CLI");
+
+    assertIncludes(setupOutput, 'Added "plugins/**" to tsconfig.json exclude');
+    assertIncludes(setupOutput, 'Added "plugins/**" to .oxlintrc.json ignorePatterns');
+    assertIncludes(setupOutput, "Oxlint ignores plugins/ (.oxlintrc.json)");
+
+    const checkOutput = runTsx(pluginRoot, [path.join(pluginRoot, "cli.ts"), "check"], projectRoot);
+    assertIncludes(checkOutput, "Oxlint ignores plugins/ (.oxlintrc.json)");
+    assert.ok(
+      !checkOutput.includes("Lint config check (no ESLint or Oxlint config found)"),
+      `Did not expect lint config detection to be skipped:\n${checkOutput}`
+    );
+
+    console.log("");
+    console.log("typegraph-mcp Install Oxlint Test");
+    console.log("=================================");
+    console.log("  ✓ tsconfig schema URL preserved during exclude patch");
+    console.log("  ✓ tsconfig exclude patch ignores unrelated plugins text");
+    console.log("  ✓ .oxlintrc.json patched with plugins ignore");
+    console.log("  ✓ installed plugin health check recognizes Oxlint config");
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/module-graph.ts

@@ -216,7 +216,7 @@ function distToSource(resolvedPath: string, projectRoot: string): string {
   return resolvedPath;
 }
 
-function resolveImport(
+export function resolveProjectImport(
   resolver: ResolverFactory,
   fromDir: string,
   specifier: string,
@@ -287,7 +287,7 @@ function buildForwardEdges(
     const fromDir = path.dirname(filePath);
 
     for (const raw of rawImports) {
-      const target = resolveImport(resolver, fromDir, raw.specifier, projectRoot);
+      const target = resolveProjectImport(resolver, fromDir, raw.specifier, projectRoot);
       if (target) {
         edges.push({
           target,
@@ -397,7 +397,7 @@ export function updateFile(
   const fromDir = path.dirname(filePath);
   const newEdges: ImportEdge[] = [];
   for (const raw of rawImports) {
-    const target = resolveImport(resolver, fromDir, raw.specifier, projectRoot);
+    const target = resolveProjectImport(resolver, fromDir, raw.specifier, projectRoot);
     if (target) {
       newEdges.push({
         target,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typegraph-mcp",
-  "version": "0.9.37",
+  "version": "0.9.39",
   "description": "Type-aware codebase navigation for AI coding agents — 14 MCP tools powered by tsserver + oxc",
   "license": "MIT",
   "type": "module",
@@ -34,7 +34,7 @@
   "scripts": {
     "build": "tsup",
     "start": "tsx server.ts",
-    "test": "tsx smoke-test.ts",
+    "test": "tsx smoke-test.ts && tsx export-surface-test.ts && tsx install-oxlint-test.ts",
     "check": "tsx check.ts"
   },
   "dependencies": {

package/server.ts

@@ -17,9 +17,16 @@
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { parseSync } from "oxc-parser";
+import type { ResolverFactory } from "oxc-resolver";
 import { z } from "zod";
 import { TsServerClient, type NavBarItem } from "./tsserver-client.js";
-import { buildGraph, startWatcher, type ModuleGraph } from "./module-graph.js";
+import {
+  buildGraph,
+  resolveProjectImport,
+  startWatcher,
+  type ModuleGraph,
+} from "./module-graph.js";
 import {
   dependencyTree,
   dependents,
@@ -44,6 +51,7 @@ const client = new TsServerClient(projectRoot, tsconfigPath);
 
 // Module graph — initialized in main(), used by graph tools
 let moduleGraph: ModuleGraph;
+let moduleResolver: ResolverFactory;
 
 const mcpServer = new McpServer({
   name: "typegraph",
@@ -167,6 +175,347 @@ async function resolveParams(params: {
   return { error: "Either line+column or symbol must be provided" };
 }
 
+type ModuleExportRecord = {
+  symbol: string;
+  kind: string;
+  line: number;
+  type: string | null;
+  exportKind: "value" | "type";
+  isTypeOnly: boolean;
+  isNamespace: boolean;
+  source: "local" | "re-export" | "star-re-export";
+  from: string | null;
+  definedIn: string;
+  definedLine: number | null;
+};
+
+type StaticExportEntry = ReturnType<typeof parseSync>["module"]["staticExports"][number]["entries"][number];
+
+const exportKinds = new Set([
+  "function",
+  "const",
+  "class",
+  "interface",
+  "type",
+  "enum",
+  "var",
+  "let",
+  "method",
+]);
+
+function exportPriority(source: ModuleExportRecord["source"]): number {
+  switch (source) {
+    case "local":
+      return 3;
+    case "re-export":
+      return 2;
+    case "star-re-export":
+      return 1;
+  }
+}
+
+function exportKey(item: Pick<ModuleExportRecord, "symbol" | "exportKind">): string {
+  return `${item.symbol}:${item.exportKind}`;
+}
+
+function sameExportOrigin(a: ModuleExportRecord, b: ModuleExportRecord): boolean {
+  return (
+    a.symbol === b.symbol &&
+    a.exportKind === b.exportKind &&
+    a.from === b.from &&
+    a.definedIn === b.definedIn &&
+    a.definedLine === b.definedLine
+  );
+}
+
+function kindImpliesTypeOnly(kind: string): boolean {
+  return kind === "type" || kind === "interface";
+}
+
+function normalizeExportKindLabel(
+  kind: string,
+  exportKind: ModuleExportRecord["exportKind"]
+): string {
+  if (exportKind === "type" && !kindImpliesTypeOnly(kind)) {
+    return "type";
+  }
+  return kind;
+}
+
+function upsertExport(
+  map: Map<string, ModuleExportRecord>,
+  conflicts: Set<string>,
+  nextExport: ModuleExportRecord
+): void {
+  const key = exportKey(nextExport);
+  if (conflicts.has(key)) {
+    if (nextExport.source === "star-re-export") return;
+    conflicts.delete(key);
+    map.set(key, nextExport);
+    return;
+  }
+
+  const existing = map.get(key);
+  if (
+    existing &&
+    existing.source === "star-re-export" &&
+    nextExport.source === "star-re-export" &&
+    !sameExportOrigin(existing, nextExport)
+  ) {
+    map.delete(key);
+    conflicts.add(key);
+    return;
+  }
+
+  if (!existing || exportPriority(nextExport.source) > exportPriority(existing.source)) {
+    map.set(key, nextExport);
+  }
+}
+
+function offsetToLineColumn(source: string, offset: number | null | undefined): {
+  line: number;
+  column: number;
+} {
+  const safeOffset = Math.max(0, Math.min(offset ?? 0, source.length));
+  const prefix = source.slice(0, safeOffset);
+  const lines = prefix.split("\n");
+  return {
+    line: lines.length,
+    column: (lines.at(-1)?.length ?? 0) + 1,
+  };
+}
+
+function normalizeExistingPath(filePath: string): string {
+  const resolved = path.resolve(filePath);
+  try {
+    return fs.realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+const normalizedProjectRoot = normalizeExistingPath(projectRoot);
+
+function projectPath(file: string): string {
+  return path.isAbsolute(file) ? relPath(file) : file;
+}
+
+function exportSymbol(entry: StaticExportEntry): string | null {
+  if (entry.exportName.kind === "Default") return "default";
+  return entry.exportName.name ?? entry.localName.name ?? entry.importName.name;
+}
+
+function exportLookupOffset(entry: StaticExportEntry): number | null | undefined {
+  if ((entry as { moduleRequest?: { value: string } }).moduleRequest) {
+    return entry.importName.start ?? entry.exportName.start ?? entry.start;
+  }
+  if (entry.exportName.kind === "Default") {
+    return entry.localName.start ?? entry.exportName.start ?? entry.start;
+  }
+  return entry.exportName.start ?? entry.localName.start ?? entry.start;
+}
+
+async function resolveExportMetadata(
+  file: string,
+  line: number,
+  column: number,
+  fallbackKind: string
+): Promise<{
+  kind: string;
+  type: string | null;
+  definedIn: string;
+  definedLine: number | null;
+}> {
+  const defs = await client.definition(file, line, column);
+  const def = defs[0] ?? null;
+
+  let info = await client.quickinfo(file, line, column);
+  if ((!info || info.kind === "alias") && def) {
+    info = (await client.quickinfo(def.file, def.start.line, def.start.offset)) ?? info;
+  }
+
+  return {
+    kind: info?.kind ?? fallbackKind,
+    type: info?.displayString ?? null,
+    definedIn: projectPath(def?.file ?? file),
+    definedLine: def?.start.line ?? null,
+  };
+}
+
+async function getModuleExports(
+  file: string,
+  visited = new Set<string>()
+): Promise<ModuleExportRecord[]> {
+  const relFile = path.isAbsolute(file) ? relPath(file) : file;
+  const absFile = normalizeExistingPath(client.resolvePath(relFile));
+  if (visited.has(absFile)) return [];
+
+  const nextVisited = new Set(visited);
+  nextVisited.add(absFile);
+
+  const exportMap = new Map<string, ModuleExportRecord>();
+  const conflictingStarExports = new Set<string>();
+
+  let source: string;
+  try {
+    source = fs.readFileSync(absFile, "utf-8");
+  } catch {
+    return [...exportMap.values()];
+  }
+
+  let parsed: ReturnType<typeof parseSync>;
+  try {
+    parsed = parseSync(absFile, source);
+  } catch {
+    return [...exportMap.values()];
+  }
+
+  for (const exp of parsed.module.staticExports) {
+    for (const entry of exp.entries) {
+      const moduleRequest = (entry as { moduleRequest?: { value: string } }).moduleRequest;
+      if (!moduleRequest) continue;
+
+      const targetFile = resolveProjectImport(
+        moduleResolver,
+        path.dirname(absFile),
+        moduleRequest.value,
+        projectRoot
+      );
+
+      const exportLoc = offsetToLineColumn(
+        source,
+        entry.exportName.start ?? entry.localName.start ?? entry.importName.start ?? entry.start
+      );
+      const importKind = entry.importName.kind as string;
+      const exportKind = entry.exportName.kind as string;
+
+      if (importKind === "AllButDefault" && exportKind === "None") {
+        if (!targetFile) continue;
+        const nestedExports = await getModuleExports(targetFile, nextVisited);
+        for (const nested of nestedExports) {
+          if (nested.symbol === "default") continue;
+          const starExportKind: ModuleExportRecord["exportKind"] = entry.isType
+            ? "type"
+            : nested.exportKind;
+          upsertExport(exportMap, conflictingStarExports, {
+            ...nested,
+            line: exportLoc.line,
+            exportKind: starExportKind,
+            isTypeOnly: starExportKind === "type",
+            source: "star-re-export",
+            from: relPath(targetFile),
+          });
+        }
+        continue;
+      }
+
+      const symbol = exportSymbol(entry);
+      if (!symbol) continue;
+
+      const importedSymbol =
+        importKind === "Default"
+          ? "default"
+          : importKind === "Name"
+            ? entry.importName.name
+            : null;
+      const nestedMatch =
+        targetFile && importedSymbol
+          ? (await getModuleExports(targetFile, nextVisited)).find(
+              (item) => item.symbol === importedSymbol
+            ) ?? null
+          : null;
+
+      const lookupLoc = offsetToLineColumn(
+        source,
+        exportLookupOffset(entry)
+      );
+      const metadata = await resolveExportMetadata(
+        relFile,
+        lookupLoc.line,
+        lookupLoc.column,
+        importKind === "All" ? "namespace" : "alias"
+      );
+      const resolvedExportKind: ModuleExportRecord["exportKind"] =
+        entry.isType ||
+        nestedMatch?.exportKind === "type" ||
+        kindImpliesTypeOnly(nestedMatch?.kind ?? metadata.kind)
+          ? "type"
+          : "value";
+      const resolvedKind = normalizeExportKindLabel(
+        nestedMatch?.kind ?? metadata.kind,
+        resolvedExportKind
+      );
+
+      upsertExport(exportMap, conflictingStarExports, {
+        symbol,
+        kind: resolvedKind,
+        line: exportLoc.line,
+        type: nestedMatch?.type ?? metadata.type,
+        exportKind: resolvedExportKind,
+        isTypeOnly: resolvedExportKind === "type",
+        isNamespace: importKind === "All",
+        source: "re-export",
+        from: targetFile ? relPath(targetFile) : moduleRequest.value,
+        definedIn: nestedMatch?.definedIn ?? metadata.definedIn,
+        definedLine: nestedMatch?.definedLine ?? metadata.definedLine,
+      });
+      continue;
+    }
+
+    for (const entry of exp.entries) {
+      const moduleRequest = (entry as { moduleRequest?: { value: string } }).moduleRequest;
+      if (moduleRequest) continue;
+
+      const symbol = exportSymbol(entry);
+      if (!symbol) continue;
+
+      const exportLoc = offsetToLineColumn(
+        source,
+        entry.exportName.start ?? entry.localName.start ?? entry.start
+      );
+      const lookupLoc = offsetToLineColumn(source, exportLookupOffset(entry));
+      const metadata = await resolveExportMetadata(
+        relFile,
+        lookupLoc.line,
+        lookupLoc.column,
+        entry.isType ? "type" : "value"
+      );
+      const resolvedExportKind: ModuleExportRecord["exportKind"] =
+        entry.isType || kindImpliesTypeOnly(metadata.kind) ? "type" : "value";
+      const resolvedKind = normalizeExportKindLabel(metadata.kind, resolvedExportKind);
+
+      // Skip navbar/import alias noise — only keep actual exported declaration kinds.
+      if (
+        resolvedExportKind === "value" &&
+        symbol !== "default" &&
+        !exportKinds.has(resolvedKind) &&
+        resolvedKind !== "namespace" &&
+        resolvedKind !== "class"
+      ) {
+        continue;
+      }
+
+      upsertExport(exportMap, conflictingStarExports, {
+        symbol,
+        kind: resolvedKind,
+        line: exportLoc.line,
+        type: metadata.type,
+        exportKind: resolvedExportKind,
+        isTypeOnly: resolvedExportKind === "type",
+        isNamespace: false,
+        source: "local",
+        from: null,
+        definedIn: relFile,
+        definedLine: resolvedExportKind === "type" ? exportLoc.line : metadata.definedLine,
+      });
+    }
+  }
+
+  return [...exportMap.values()].sort(
+    (a, b) => a.line - b.line || a.symbol.localeCompare(b.symbol)
+  );
+}
+
 // ─── Tool 1: ts_find_symbol ─────────────────────────────────────────────────
 
 mcpServer.tool(
@@ -499,68 +848,38 @@ mcpServer.tool(
 
 mcpServer.tool(
   "ts_module_exports",
-  "List all exported symbols from a module with their resolved types. Gives an at-a-glance understanding of what a file provides.",
+  "List all exported symbols from a module with their resolved types, including re-exports when possible. Gives an at-a-glance understanding of what a file provides.",
   {
     file: z.string().describe("File to inspect"),
   },
   async ({ file }) => {
-    const bar = await client.navbar(file);
-    if (bar.length === 0) {
-      return {
-        content: [
-          {
-            type: "text" as const,
-            text: JSON.stringify({ error: `No symbols found in ${file}` }),
-          },
-        ],
-      };
-    }
-
-    // The top-level navbar item is the module itself — its children are exports
-    const moduleItem = bar.find((item) => item.kind === "module");
-    const topItems = moduleItem?.childItems ?? bar;
-
-    // Filter to meaningful declarations (skip imports, local vars, etc.)
-    const exportKinds = new Set([
-      "function",
-      "const",
-      "class",
-      "interface",
-      "type",
-      "enum",
-      "var",
-      "let",
-      "method",
-    ]);
-    const candidates = topItems.filter((item) => exportKinds.has(item.kind));
-
-    const exports: Array<{
-      symbol: string;
-      kind: string;
-      line: number;
-      type: string | null;
-    }> = [];
-
-    for (const item of candidates) {
-      if (!item.spans[0]) continue;
-      const span = item.spans[0];
-
-      // Get type info for this symbol
-      const info = await client.quickinfo(file, span.start.line, span.start.offset);
-
-      exports.push({
-        symbol: item.text,
-        kind: item.kind,
-        line: span.start.line,
-        type: info?.displayString ?? null,
-      });
-    }
+    const exports = await getModuleExports(file);
+    const localCount = exports.filter((item) => item.source === "local").length;
+    const reExportCount = exports.length - localCount;
+    const typeOnlyCount = exports.filter((item) => item.isTypeOnly).length;
+    const valueCount = exports.length - typeOnlyCount;
+    const namespaceExportCount = exports.filter((item) => item.isNamespace).length;
+    const hasLocalRuntimeExports = exports.some(
+      (item) => item.source === "local" && !item.isTypeOnly
+    );
+    const isPrimarilyBarrel = exports.length > 0 && localCount < reExportCount;
 
     return {
       content: [
         {
           type: "text" as const,
-          text: JSON.stringify({ file, exports, count: exports.length }),
+          text: JSON.stringify({
+            file,
+            exports,
+            count: exports.length,
+            localCount,
+            reExportCount,
+            typeOnlyCount,
+            valueCount,
+            namespaceExportCount,
+            hasLocalRuntimeExports,
+            isPrimarilyBarrel,
+          }),
         },
       ],
     };
@@ -571,7 +890,7 @@ mcpServer.tool(
 
 /** Convert an absolute path to project-relative */
 function relPath(absPath: string): string {
-  return path.relative(projectRoot, absPath);
+  return path.relative(normalizedProjectRoot, normalizeExistingPath(absPath));
 }
 
 /** Convert a relative or absolute path to absolute */
@@ -812,6 +1131,7 @@ async function main() {
   ]);
 
   moduleGraph = graphResult.graph;
+  moduleResolver = graphResult.resolver;
   startWatcher(projectRoot, moduleGraph, graphResult.resolver);
 
   const transport = new StdioServerTransport();

package/skills/code-exploration/SKILL.md

@@ -24,6 +24,11 @@ If you know the file:
 - Call `ts_module_exports` to see what the file provides
 - Call `ts_find_symbol` to locate a specific symbol within it
 
+If `ts_module_exports` on a top-level `index.ts` is empty or mostly re-exports:
+- Treat it as a barrel, not a dead end
+- Pivot to a composition module such as an app entrypoint, router, handler, API module, or service composition root
+- Use `ts_dependency_tree` on that composition module to get quick architectural context
+
 ### Step 2: Understand the Type
 Call `ts_type_info` on the entry point symbol. This gives you the full type signature and documentation without reading the entire file.
 
@@ -33,6 +38,8 @@ Call `ts_trace_chain` to follow the definition chain from the entry point to the
 ### Step 4: Explore the Neighborhood
 Call `ts_subgraph` with the key files discovered in step 3 to see the surrounding module structure. Use `direction: "both"` and `depth: 1` for immediate context.
 
+For a fast system-level read, `ts_dependency_tree` on the composition module often gives a better first picture than reading a barrel file's exports.
+
 ### Step 5: Deep Dive Where Needed
 Only now, read specific files at the lines identified by the tools. You have precise coordinates — no need to read entire files.
 

package/skills/deep-survey/SKILL.md

@@ -54,6 +54,8 @@ Glob: **/index.ts, **/main.ts, **/entry*.ts, **/worker*.ts, **/server.ts, **/app
 
 Exclude `node_modules/` hits. The results are your starting nodes.
 
+Prefer these composition modules over top-level barrel files for your first passes. Barrels often describe the public API surface, but entry points and composition roots reveal how the system is actually wired.
+
 ### 1b. Dependency tree from every entry point (depth 2)
 
 For each entry point, run:
@@ -121,6 +123,8 @@ Record for each:
 - **Export types** — classes, interfaces, types, constants, functions. A file that exports 8 interfaces is a contract definition. A file that exports 8 constants is a configuration. A file that exports a mix of class + error + test layer is a service module.
 - **Naming patterns** — do exports follow consistent naming (`*Service`, `*Error`, `*Test`, `*Live`)? Consistency across files is evidence of intentional patterns.
 
+If a file is a barrel and `ts_module_exports` is sparse or uninformative, do not stop there. Pivot to the concrete composition modules it fronts and use `ts_dependency_tree` or `ts_module_exports` there instead.
+
 ### 2c. Module boundaries — how coupled are directories?
 
 Identify 3-5 directories that look like they should be self-contained modules (e.g., `services/billing/`, `providers/email/`, `middleware/`).

package/skills/tool-selection/SKILL.md

@@ -29,6 +29,8 @@ Use **ts_type_info** — returns the same info as hovering in VS Code. Includes
 ### "What are all the exports of this file?"
 Use **ts_module_exports** — lists all exported symbols with their resolved types.
 
+If the file is a top-level barrel (`index.ts`, re-export hub), the result may be sparse or unhelpful for architecture discovery. For quick project insight, prefer composition modules such as entrypoints, routers, handler modules, service composition roots, or API modules that wire concrete behavior together.
+
 ### "Where is X used?"
 Use **ts_references** for all semantic references. Unlike grep, this returns only real code references, not string matches in comments or unrelated variables.
 
@@ -63,6 +65,7 @@ Use **ts_module_boundary** — analyzes incoming/outgoing edges, shared dependen
 3. **Combine tools for workflows.** Impact analysis = ts_blast_radius + ts_dependents. Refactor safety = ts_trace_chain + ts_import_cycles.
 4. **Graph queries are instant** (~0.1ms). Point queries are fast (~2-50ms). Don't hesitate to use them liberally.
 5. **First query may be slow** (~2s) as tsserver warms up. All subsequent queries are fast.
+6. **For fast architecture reads, start at composition modules, not barrels.** Barrels are useful for API shape, but entrypoints and composition roots tell you how the system is actually wired.
 
 ## Tool Reference