@dotdotgod/cli 0.6.1 → 0.6.3

package/README.md

@@ -4,13 +4,13 @@
 
 Command-line tools for dotdotgod project memory.
 
-Use this package when you want to initialize a docs-first project scaffold, validate project-memory docs, build a local graph/cache, search shared documentation locally, expand project references, or ask what should be checked after a file changes.
+Use this package when you want to initialize a docs-first project scaffold, validate project-memory docs, build a local graph/cache, search full documentation and code outlines locally, expand project references, or ask what should be checked after a file changes.
 
 These commands support dotdotgod's project-memory loop with initialization, documentation query, validation, and impact analysis for shells, scripts, CI, and agents that use the CLI directly.
 
 ## What Changes
 
-- **Repository knowledge becomes navigable memory.** Local multilingual query finds focused documentation evidence and keeps the cache under `.dotdotgod/`.
+- **Repository knowledge becomes navigable memory.** Hybrid query finds full-document and code-outline/comment evidence and keeps the cache under `.dotdotgod/`.
 - **Project references become actionable context.** `resolve` and `expand` connect explicit `[[...]]` references and high-signal natural-language requests to maintained files; `--with-impact` adds related evidence.
 - **Changes carry their verification neighborhood.** Multi-file graph impact combines structural, traceability, package, and optional semantic evidence while preserving a per-file explanation.
 - **Large repositories reveal natural domains.** `graph communities` groups the maintained project graph to help teams inspect documentation and source boundaries.
@@ -43,9 +43,9 @@ dotdotgod graph serve . --changed <path>
 ## What It Does
 
 - `init` creates `AGENTS.md`, thin agent entrypoints, docs indexes, active-plan space, archive map, local cache ignores, and the complete editable default config.
-- `validate` checks the dotdotgod docs/project-memory structure, local links, traceability blocks, config validity, and optional index freshness.
-- `index` builds `.dotdotgod/manifest.json` and compact graph shards from maintained project files.
-- `query` locally embeds shared Markdown with `Xenova/multilingual-e5-small`, incrementally stores vectors under `.dotdotgod/vectors/`, and returns the best-ranked chunk from each relevant Markdown file.
+- `validate` checks docs/project-memory rules; `--check-index` also checks graph and outline freshness without parsing, embedding or repair.
+- `index` builds graph shards and `.dotdotgod/outlines.json` with source hashes, declarations, comments and exact ranges.
+- `query` defaults to hybrid vector/keyword search over full Markdown and code outlines/comments, not implementation bodies. Use `--scope docs|code|all`, `--search hybrid|keyword|vector` and `--limit 30`. Keyword mode works without embeddings; hybrid reports vector failures and retains keyword results. Remote code-metadata embedding requires `--allow-code-embedding`. Local E5 remains the default when its optional runtime is installed. Tree-sitter coverage and boundaries: [CODE_OUTLINES.md](../../docs/spec/cli/CODE_OUTLINES.md).
 - `resolve` and `expand` map explicit or high-signal prompt references to project files and can include related impact evidence.
 - `graph impact` ranks likely related specs, tests, docs, commands, and source files for one or more changed paths, with a combined ranking and per-file top five. Non-seed scores use fixed weighted PPR connection `80` plus memory policy `20`. A bounded request-local multilingual vector overlay participates in PPR when the query cache is available; vector preparation failures degrade to structural-only results.
 - `graph serve` starts a local read-only explorer rooted at one or more changed files. It keeps only connected shared structural nodes, lays them out by minimum structural hop, and supports persisted instant, layer, or one-by-one reveal modes.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dotdotgod/cli",
-  "version": "0.6.1",
-  "description": "CLI for dotdotgod validation, local documentation search, and graph indexing.",
+  "version": "0.6.3",
+  "description": "CLI for dotdotgod validation, hybrid document/code-outline search, and graph indexing.",
   "type": "module",
   "license": "Elastic-2.0",
   "publishConfig": {
@@ -29,8 +29,10 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@vscode/tree-sitter-wasm": "0.3.1",
     "d3": "^7.9.0",
     "graphology": "^0.26.0",
+    "ignore": "7.0.5",
     "leiden-ts": "^0.1.0",
     "sigma": "^3.0.3"
   },

package/src/cli/usage.mjs

@@ -33,9 +33,9 @@ Create dotdotgod.config.json from a bundled or user template. Without --template
   dotdotgod status <root> [--json]`;
     case 'query':
       return `Usage:
-  dotdotgod query <root> <query> [--limit n] [--json]
+  dotdotgod query <root> <query> [--limit n] [--scope docs|code|all] [--search hybrid|keyword|vector] [--allow-code-embedding] [--json]
 
-Search shared project documentation with the resolved local or remote embedding provider.`;
+Search full documentation and code outlines/comments. Default: hybrid docs+code. Remote code metadata requires explicit consent.`;
     case 'embedding':
       return `Usage:
   dotdotgod embedding status [<root>] [--json]

package/src/commands/query.mjs

@@ -5,17 +5,22 @@ import { collectDocumentationChunks } from '../query/chunks.mjs';
 import { resolveEmbedder } from '../query/embedder.mjs';
 import { isValidNormalizedVectorValues, profileFingerprint, readVectorCache, writeVectorCache } from '../query/store.mjs';
 
+import { projectCorpus, keywordCandidates, fuseCandidates, attachRelationships, assertCodeEmbeddingConsent } from '../query/hybrid.mjs';
+
 const DEFAULT_LIMIT = 30;
 const MAX_LIMIT = 100;
 const EMBED_BATCH_SIZE = 16;
 
 export function parseQueryOptions(argv) {
-  const options = { root: '.', query: '', limit: DEFAULT_LIMIT, json: false };
+  const options = { root: '.', query: '', limit: DEFAULT_LIMIT, json: false, scope: 'all', search: 'hybrid', allowCodeEmbedding: false };
   let rootSet = false;
   const queryParts = [];
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--json') options.json = true;
+    else if (arg === '--scope') { options.scope = argv[++i]; if (!['docs', 'code', 'all'].includes(options.scope)) usage('--scope must be docs, code or all.', 'query'); }
+    else if (arg === '--search') { options.search = argv[++i]; if (!['hybrid', 'keyword', 'vector'].includes(options.search)) usage('--search must be hybrid, keyword or vector.', 'query'); }
+    else if (arg === '--allow-code-embedding') options.allowCodeEmbedding = true;
     else if (arg === '--limit') { const value = Number(argv[++i]); if (!Number.isInteger(value) || value < 1 || value > MAX_LIMIT) usage(`--limit must be an integer from 1 to ${MAX_LIMIT}.`, 'query'); options.limit = value; }
     else if (arg.startsWith('-')) usage(`Unknown option: ${arg}`, 'query');
     else if (!rootSet) { options.root = resolve(arg); rootSet = true; }
@@ -63,7 +68,7 @@ export async function buildVectorIndex(root, embedOrOptions = {}) {
   const resolved = await resolveEmbedder(root, options);
   const config = readMemoryConfig(root);
   const exclude = config.load?.documentationSummary?.exclude ?? ['docs/plan', 'docs/archive'];
-  const chunks = collectDocumentationChunks(root, exclude, config.documentation?.root ?? 'docs');
+  const chunks = options.chunks ?? collectDocumentationChunks(root, exclude, config.documentation?.root ?? 'docs');
   const cached = readVectorCache(root, resolved.identity);
   const cachedOffsets = new Map((cached?.chunks ?? []).map((chunk, index) => [chunk.fingerprint, index]));
   const rows = new Array(chunks.length);
@@ -95,14 +100,41 @@ export async function queryDocumentation(root, query, options = {}) {
   return { ok: true, command: 'query', root, query, provider: index.embedding.profile.provider, model: index.embedding.profile.model, embeddingSource: index.embedding.source, dimensions, limit, index: index.manifest, results };
 }
 
+export async function queryProject(root, query, options = {}) {
+  const scope = options.scope ?? 'all';
+  const search = options.search ?? 'hybrid';
+  const limit = options.limit ?? DEFAULT_LIMIT;
+  const corpus = await projectCorpus(root, scope);
+  const keyword = search === 'vector' ? [] : keywordCandidates(query, corpus.chunks);
+  let vector = []; let index; let vectorError;
+  if (search !== 'keyword' && corpus.chunks.length) {
+    try {
+      assertCodeEmbeddingConsent(root, options, corpus.chunks);
+      index = await buildVectorIndex(root, { ...options, chunks: corpus.chunks });
+      const [queryVector] = await index.embedding.embed([`query: ${query}`]);
+      vector = index.chunks.map((chunk, position) => ({ ...chunk, vectorScore: cosineScore(queryVector, index.vectors, position * index.manifest.dimensions, index.manifest.dimensions) }))
+        .sort((a, b) => b.vectorScore - a.vectorScore || a.id.localeCompare(b.id));
+    } catch (error) {
+      if (search === 'vector') throw error;
+      vectorError = error instanceof Error ? error.message : String(error);
+    }
+  }
+  const results = attachRelationships(fuseCandidates(keyword, vector, limit), corpus.outlines).map(({ passage, ...result }) => result);
+  return { ok: true, command: 'query', root, query, scope, search, limit,
+    provider: index?.embedding.profile.provider ?? null, model: index?.embedding.profile.model ?? null,
+    embeddingSource: index?.embedding.source ?? 'not-used', dimensions: index?.manifest.dimensions ?? null,
+    index: index?.manifest ?? null, outlines: corpus.outlines ? { refresh: corpus.outlines.refresh, indexedFiles: corpus.outlines.files.length, diagnostics: corpus.outlines.files.filter((file) => file.status !== 'parsed').map(({ path, status }) => ({ path, status })) } : null,
+    warnings: [...(vectorError ? [`Vector retrieval unavailable; keyword results only: ${vectorError}`] : []), ...(corpus.outlines?.files.filter((file) => file.status !== 'parsed').map((file) => `Outline ${file.status}: ${file.path}`) ?? [])], results };
+}
+
 function formatQueryResult(payload) {
-  const lines = [`dotdotgod query: ${payload.query}`, `- embedding: ${payload.provider}/${payload.model} (${payload.embeddingSource})`, `- results: ${payload.results.length}`];
-  payload.results.forEach((result, index) => { lines.push(`${index + 1}. ${result.path}${result.heading ? ` — ${result.heading}` : ''} (${result.score.toFixed(3)})`); const excerpt = result.text.replace(/\s+/g, ' ').trim().slice(0, 240); if (excerpt) lines.push(`   ${excerpt}${result.text.length > 240 ? '…' : ''}`); });
+  const lines = [`dotdotgod query: ${payload.query}`, `- embedding: ${payload.provider ? `${payload.provider}/${payload.model}` : 'not used'} (${payload.embeddingSource})`, `- results: ${payload.results.length}`, ...(payload.warnings ?? [])];
+  payload.results.forEach((result, index) => { lines.push(`${index + 1}. ${result.path}${result.startLine ? `:${result.startLine}–${result.endLine}` : ''}${result.heading ? ` — ${result.heading}` : ''} (${result.score.toFixed(3)})`); const excerpt = result.text.replace(/\s+/g, ' ').trim().slice(0, 240); if (excerpt) lines.push(`   ${excerpt}${result.text.length > 240 ? '…' : ''}`); });
   return lines.join('\n');
 }
 
 export async function runQuery(argv) {
   const options = parseQueryOptions(argv);
-  try { const payload = await queryDocumentation(options.root, options.query, options); console.log(options.json ? JSON.stringify(payload, null, 2) : formatQueryResult(payload)); }
+  try { const payload = await queryProject(options.root, options.query, options); console.log(options.json ? JSON.stringify(payload, null, 2) : formatQueryResult(payload)); }
   catch (error) { const message = `dotdotgod query failed: ${error instanceof Error ? error.message : String(error)}`; if (options.json) console.log(JSON.stringify({ ok: false, command: 'query', root: options.root, query: options.query, error: message }, null, 2)); else console.error(message); process.exitCode = 1; }
 }

package/src/core.mjs

@@ -35,7 +35,7 @@ export { buildVectorImpactOverlay, VECTOR_RELATION_WEIGHT } from './impact/vecto
 export { formatCompactImpactOutput, formatYmlGraphImpactError, formatYmlImpactOutput } from './impact/format.mjs';
 export { runConfig } from './commands/config.mjs';
 export { runMap } from './commands/map.mjs';
-export { buildVectorIndex, cosineScore, parseQueryOptions, queryDocumentation, rankVectorFiles, runQuery } from './commands/query.mjs';
+export { buildVectorIndex, cosineScore, parseQueryOptions, queryDocumentation, queryProject, rankVectorFiles, runQuery } from './commands/query.mjs';
 export { runEmbedding } from './commands/embedding.mjs';
 export { EmbeddingRuntimeMissingError, embeddingRuntimeRoot, embeddingRuntimeStatus, installEmbeddingRuntime, resolvePersistentTransformers } from './query/embedding-runtime.mjs';
 export { chunkMarkdown, collectDocumentationChunks, collectDocumentationMarkdown, textFingerprint } from './query/chunks.mjs';
@@ -55,7 +55,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   if (hasHelpToken(args)) usage('', helpCommandFromArgs([command, ...args]));
   if (command === 'validate') runValidate(args);
   else if (command === 'init') runInit(args, usage);
-  else if (command === 'index') runIndex(args);
+  else if (command === 'index') await runIndex(args);
   else if (command === 'config') runConfig(args);
   else if (command === 'status') runStatus(args);
   else if (command === 'query') await runQuery(args);

package/src/index/cache.mjs

@@ -7,6 +7,9 @@ import { addEdge, addNode, compactGraph, expandGraph, graphStats, jsonSize, shar
 import { cacheFile, collectIndexFiles, fingerprint } from './files.mjs';
 import { CACHE_VERSION } from './constants.mjs';
 import { buildGraph } from '../graph/extract.mjs';
+import { buildOutlines, readOutlines } from '../symbols/store.mjs';
+import { outlinePolicy } from '../symbols/discovery.mjs';
+import { addOutlineGraph } from '../symbols/graph.mjs';
 
 function collectFingerprints(root, config = readMemoryConfig(root)) {
   return collectIndexFiles(root, config).map((file) => {
@@ -44,7 +47,17 @@ export function buildIndex(root, previous = readIndex(root)) {
   const fullRebuild = !previous?.graph || previous.version !== CACHE_VERSION;
   const refreshReason = !previous ? 'missing' : previous.version !== CACHE_VERSION ? 'schema-mismatch' : removedPaths.length > 0 ? 'content-removed' : changedPaths.length > 0 ? 'content-changed' : 'fresh';
   const rawGraph = fullRebuild ? buildGraph(root, files.map((file) => join(root, file.path)), memoryConfig) : mergeIncrementalGraph(previous.graph, buildGraph(root, changedFiles, memoryConfig), changedPaths);
-  const graph = rawGraph;
+  const graph = { nodes: rawGraph.nodes.filter((node) => !['symbol', 'unresolved_import'].includes(node.type)), edges: rawGraph.edges.filter((edge) => !['declares_symbol', 'contains_symbol', 'imports'].includes(edge.relation)) };
+  const outlines = readOutlines(root);
+  let outlinePolicyMatches = false;
+  if (outlines) {
+    try { outlinePolicyMatches = outlines.policy === outlinePolicy(root); }
+    catch { /* Outline runtime unavailable: preserve the existing structural graph path. */ }
+  }
+  if (outlinePolicyMatches) {
+    const hashes = new Map(files.map((file) => [file.path, file.sha256]));
+    addOutlineGraph(graph, { files: outlines.files.filter((file) => hashes.get(file.path) === file.hash && file.status === 'parsed') });
+  }
   const archiveBodiesIncluded = (memoryConfig.areas ?? []).some((area) => area.id === 'archive-body' && area.includeBodiesByDefault !== false);
   return { version: CACHE_VERSION, schemaVersion: CACHE_VERSION, generatedAt: new Date().toISOString(), archiveBodiesIncluded, memoryConfig: memoryConfigSummary(memoryConfig), files, graph, stats: graphStats(graph), incremental: { enabled: true, fullRebuild, changedFiles: changedPaths.length, refreshReason, elapsedMs: Date.now() - startedAt } };
 }
@@ -92,11 +105,12 @@ export function getStatus(root) {
   return { ok, status: ok ? 'fresh' : 'stale', cachePath: rel(root, cacheFile(root)), indexedFiles: index.files?.length ?? 0, currentFiles: currentFiles.length, staleFiles: staleFiles.length, examples: staleFiles.slice(0, 10), archiveBodiesIncluded: index.archiveBodiesIncluded === true, schemaVersion, expectedSchemaVersion: CACHE_VERSION, schemaOk, reason, graph: graphStats(index.graph ?? { nodes: [], edges: [] }) };
 }
 
-export function runIndex(argv) {
+export async function runIndex(argv) {
   const options = parseCommon(argv);
+  const outlines = await buildOutlines(options.root);
   const index = buildIndex(options.root);
   const manifest = writeIndex(options.root, index);
-  const result = { ok: true, cachePath: rel(options.root, cacheFile(options.root)), schemaVersion: CACHE_VERSION, indexedFiles: index.files.length, nodes: index.graph.nodes.length, edges: index.graph.edges.length, indexSizeBytes: manifest.indexSizeBytes, shards: manifest.graph.shards, incremental: index.incremental, archiveBodiesIncluded: index.archiveBodiesIncluded === true, memoryConfig: index.memoryConfig };
+  const result = { ok: true, cachePath: rel(options.root, cacheFile(options.root)), schemaVersion: CACHE_VERSION, indexedFiles: index.files.length, outlines: { refresh: outlines.refresh, unsupported: outlines.files.filter((file) => file.status === 'unsupported').map((file) => file.path), partial: outlines.files.filter((file) => file.status === 'partial').map((file) => file.path) }, nodes: index.graph.nodes.length, edges: index.graph.edges.length, indexSizeBytes: manifest.indexSizeBytes, shards: manifest.graph.shards, incremental: index.incremental, archiveBodiesIncluded: index.archiveBodiesIncluded === true, memoryConfig: index.memoryConfig };
   if (options.json) console.log(JSON.stringify(result, null, 2));
   else console.log(`✅ index written (${result.indexedFiles} files, ${result.nodes} nodes, ${result.edges} edges, ${(result.indexSizeBytes / 1024).toFixed(1)} KiB, cache: ${result.cachePath})`);
 }

package/src/query/hybrid.mjs

@@ -0,0 +1,62 @@
+import { collectDocumentationChunks } from './chunks.mjs';
+import { readMemoryConfig } from '../memory/config.mjs';
+import { resolveEmbeddingProfile } from './embedding-config.mjs';
+import { buildOutlines, outlineChunks } from '../symbols/store.mjs';
+import { addOutlineGraph } from '../symbols/graph.mjs';
+
+export const resultKey = (chunk) => chunk.kind === 'symbol' ? chunk.id : chunk.path;
+const terms = (text) => [...new Set(text.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean))];
+export function keywordCandidates(query, chunks) {
+  const words = terms(query);
+  if (!words.length) return [];
+  const literal = query.toLowerCase();
+  return chunks.map((chunk) => {
+    const names = `${chunk.qualifiedName ?? ''} ${chunk.heading ?? ''} ${chunk.path}`.toLowerCase();
+    const body = `${chunk.signature ?? ''} ${chunk.documentation ?? chunk.text}`.toLowerCase();
+    const haystack = new Set(terms(`${names} ${body}`));
+    const matched = words.filter((word) => haystack.has(word)).length;
+    const exact = chunk.qualifiedName?.toLowerCase() === literal || chunk.name?.toLowerCase() === literal;
+    return { ...chunk, exactNameMatch: Boolean(exact), keywordScore: exact ? 3 : matched / words.length + (names.includes(literal) ? 0.5 : body.includes(literal) ? 0.25 : 0) };
+  }).filter((chunk) => chunk.keywordScore > 0).sort((a, b) => b.keywordScore - a.keywordScore || a.id.localeCompare(b.id));
+}
+export function fuseCandidates(keyword, vector, limit) {
+  const candidates = new Map();
+  for (const [channel, rows] of [['keyword', keyword], ['vector', vector]]) {
+    const seenIds = new Set(); let rank = 0;
+    rows.forEach((chunk) => {
+      if (seenIds.has(chunk.id)) return;
+      seenIds.add(chunk.id); rank += 1;
+      const existing = candidates.get(chunk.id) ?? { ...chunk, score: 0, retrieval: [] };
+      existing.score += 1 / (60 + rank);
+      existing.retrieval.push(channel);
+      if (chunk.vectorScore !== undefined) existing.vectorScore = chunk.vectorScore;
+      if (chunk.keywordScore !== undefined) existing.keywordScore = chunk.keywordScore;
+      candidates.set(chunk.id, existing);
+    });
+  }
+  const seen = new Set();
+  return [...candidates.values()].sort((a, b) => Number(b.exactNameMatch ?? false) - Number(a.exactNameMatch ?? false) || b.score - a.score || a.id.localeCompare(b.id)).filter((chunk) => {
+    const key = resultKey(chunk);
+    if (seen.has(key)) return false;
+    seen.add(key); return true;
+  }).slice(0, limit);
+}
+export async function projectCorpus(root, scope) {
+  const config = readMemoryConfig(root);
+  const docs = scope === 'code' ? [] : collectDocumentationChunks(root, config.load?.documentationSummary?.exclude, config.documentation?.root ?? 'docs').map((chunk) => ({ ...chunk, kind: 'document' }));
+  const outlines = scope === 'docs' ? null : await buildOutlines(root);
+  return { chunks: [...docs, ...(outlines ? outlineChunks(outlines) : [])], outlines };
+}
+export function assertCodeEmbeddingConsent(root, options, chunks) {
+  if (!chunks.some((chunk) => chunk.kind === 'symbol')) return;
+  const profile = options.profile ?? resolveEmbeddingProfile(root).profile;
+  if (profile.provider !== 'local' && options.allowCodeEmbedding !== true) throw new Error('Remote code-metadata embedding requires --allow-code-embedding; use --search keyword or --scope docs instead.');
+}
+export function attachRelationships(results, outlines) {
+  if (!outlines) return results;
+  const graph = addOutlineGraph({ nodes: [], edges: [] }, outlines);
+  return results.map((result) => {
+    const relationships = graph.edges.filter((edge) => edge.source === result.id || edge.target === result.id || (edge.source === `file:${result.path}` && edge.relation === 'imports'));
+    return { ...result, relationshipCount: relationships.length, relationships: relationships.slice(0, 10) };
+  });
+}

package/src/symbols/discovery.mjs

@@ -0,0 +1,55 @@
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { extname, join, relative, isAbsolute } from 'node:path';
+import ignore from 'ignore';
+import { collectIndexFiles, fingerprint } from '../index/files.mjs';
+import { readMemoryConfig, isSecretLikePathPattern } from '../memory/config.mjs';
+import { textFingerprint } from '../query/chunks.mjs';
+import { EXTRACTOR_ID, DECLARATIONS, LANGUAGE_EXTENSIONS, languageForPath, SOURCE_EXTENSIONS } from './languages.mjs';
+import { parserIdentity } from './runtime.mjs';
+
+function inside(root, file) {
+  if (!lstatSync(file).isFile()) return false;
+  const path = relative(realpathSync(root), realpathSync(file));
+  return !path.startsWith('..') && !isAbsolute(path);
+}
+function ignoreRules(root, directory, cache) {
+  if (!cache.has(directory)) {
+    const file = join(root, directory, '.gitignore');
+    cache.set(directory, ignore().add(existsSync(file) && inside(root, file) ? readFileSync(file, 'utf8') : ''));
+  }
+  return cache.get(directory);
+}
+function ignored(root, path, cache) {
+  const parts = path.split('/');
+  let excluded = false;
+  for (let depth = 0; depth < parts.length; depth += 1) {
+    const directory = parts.slice(0, depth).join('/');
+    const remaining = parts.slice(depth).join('/');
+    const rules = ignoreRules(root, directory, cache);
+    // An ignored directory cannot be re-included by a rule inside it.
+    for (let end = 1; end < parts.length - depth; end += 1) {
+      if (rules.ignores(parts.slice(depth, depth + end).join('/') + '/')) return true;
+    }
+    const result = rules.test(remaining);
+    if (result.ignored) excluded = true;
+    else if (result.unignored) excluded = false;
+  }
+  return excluded;
+}
+export function sourceFiles(root) {
+  const cache = new Map();
+  return collectIndexFiles(root).filter((file) => {
+    const path = relative(root, file).replaceAll('\\', '/');
+    if (!SOURCE_EXTENSIONS.has(extname(path)) || path.split('/').some((part) => part.startsWith('.')) || isSecretLikePathPattern(path)) return false;
+    if (!inside(root, file) || ignored(root, path, cache)) return false;
+    return !/^#![^\n]*\n\/\/ Generated|^\/\/ Generated|@generated/m.test(readFileSync(file, 'utf8').slice(0, 256));
+  }).map((file) => {
+    const source = readFileSync(file, 'utf8');
+    return { path: relative(root, file).replaceAll('\\', '/'), hash: fingerprint(file), language: languageForPath(file), sourceLength: source.length, lineCount: source.split('\n').length };
+  });
+}
+export function outlinePolicy(root) {
+  const config = readMemoryConfig(root);
+  const ignores = collectIndexFiles(root).filter((file) => file.endsWith('/.gitignore') && inside(root, file)).map((file) => [relative(root, file), fingerprint(file)]);
+  return textFingerprint(JSON.stringify({ areas: config.areas, ignores, extractor: EXTRACTOR_ID, declarations: DECLARATIONS, extensions: LANGUAGE_EXTENSIONS, parser: parserIdentity() }));
+}

package/src/symbols/graph.mjs

@@ -0,0 +1,28 @@
+import { dirname, posix } from 'node:path';
+import { addEdge, addNode } from '../graph/store.mjs';
+
+function importTarget(file, specifier, paths) {
+  if (!specifier.startsWith('.')) return null;
+  const base = posix.normalize(posix.join(dirname(file).replaceAll('\\', '/'), specifier));
+  if (base.startsWith('../')) return null;
+  const stem = base.replace(/\.(js|jsx|mjs|cjs)$/, '');
+  const candidates = [base, ...['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py'].map((extension) => `${stem}${extension}`), ...['.ts', '.js', '.py'].map((extension) => `${base}/index${extension}`)];
+  return candidates.find((path) => paths.has(path)) ?? null;
+}
+export function addOutlineGraph(graph, index) {
+  const paths = new Set(index.files.map((file) => file.path));
+  for (const file of index.files) {
+    const source = `file:${file.path}`;
+    for (const symbol of file.symbols) {
+      addNode(graph, symbol.id, 'symbol', { ...symbol, sourceHash: file.hash });
+      addEdge(graph, symbol.ownerId ?? source, symbol.id, symbol.ownerId ? 'contains_symbol' : 'declares_symbol', { confidence: 'PARSED', path: file.path });
+    }
+    for (const item of file.imports) {
+      const resolved = importTarget(file.path, item.specifier, paths);
+      const target = resolved ? `file:${resolved}` : `import:${file.path}#${item.specifier}`;
+      if (!resolved) addNode(graph, target, 'unresolved_import', { path: file.path, specifier: item.specifier });
+      addEdge(graph, source, target, 'imports', { ...item, resolved: Boolean(resolved), confidence: resolved ? 'RESOLVED_RELATIVE_FILE' : 'SYNTAX_ONLY', path: file.path });
+    }
+  }
+  return graph;
+}

package/src/symbols/languages.mjs

@@ -0,0 +1,29 @@
+import { extname } from 'node:path';
+
+// Explicit capability matrix, not a claim that every Tree-sitter grammar yields outlines.
+export const LANGUAGE_EXTENSIONS = {
+  javascript: ['.js', '.jsx', '.mjs', '.cjs'], typescript: ['.ts'], tsx: ['.tsx'],
+  python: ['.py', '.pyw'], go: ['.go'], rust: ['.rs'], java: ['.java'],
+  ruby: ['.rb'], php: ['.php'], 'c-sharp': ['.cs'], cpp: ['.cpp', '.cc', '.cxx', '.hpp'],
+  bash: ['.sh', '.bash'], powershell: ['.ps1'],
+};
+export const SOURCE_EXTENSIONS = new Set([
+  ...Object.values(LANGUAGE_EXTENSIONS).flat(), '.c', '.h', '.kt', '.kts', '.swift',
+  '.scala', '.clj', '.cljs', '.ex', '.exs', '.erl', '.hrl', '.lua', '.pl', '.pm', '.r', '.R', '.sql', '.m', '.mm', '.zsh', '.fish',
+]);
+export const EXTRACTOR_ID = 'outline-v3:vscode-tree-sitter-wasm-0.3.1';
+export function languageForPath(path) {
+  return Object.entries(LANGUAGE_EXTENSIONS).find(([, extensions]) => extensions.includes(extname(path)))?.[0] ?? null;
+}
+export const DECLARATIONS = {
+  function_declaration: 'function', generator_function_declaration: 'function',
+  function_definition: 'function', function_item: 'function', function_signature_item: 'function', function_signature: 'function',
+  method_definition: 'method', method_declaration: 'method', method_signature: 'method', method: 'method', singleton_method: 'method',
+  constructor_declaration: 'constructor', destructor_declaration: 'destructor',
+  class_declaration: 'class', class_definition: 'class', class: 'class', class_specifier: 'class', struct_specifier: 'struct',
+  interface_declaration: 'interface', interface_definition: 'interface', trait_item: 'trait',
+  struct_item: 'struct', enum_item: 'enum', enum_declaration: 'enum', record_declaration: 'class',
+  namespace_definition: 'namespace', mod_item: 'module', module: 'module',
+  function_statement: 'function',
+};
+export const COMMENT_TYPES = new Set(['comment', 'line_comment', 'block_comment']);

package/src/symbols/parser.mjs

@@ -0,0 +1,127 @@
+import { dirname, join } from 'node:path';
+import { parserEntry, loadParserApi } from './runtime.mjs';
+import { createHash } from 'node:crypto';
+import { COMMENT_TYPES, DECLARATIONS } from './languages.mjs';
+
+let runtime;
+const languages = new Map();
+async function parserFor(language) {
+  if (!runtime) runtime = (async () => {
+    const entry = parserEntry();
+    const api = loadParserApi();
+    await api.Parser.init();
+    return { api, directory: dirname(entry) };
+  })();
+  const { api, directory } = await runtime;
+  if (!languages.has(language)) languages.set(language, api.Language.load(join(directory, `tree-sitter-${language}.wasm`)));
+  const loaded = await languages.get(language);
+  const parser = new api.Parser();
+  parser.setLanguage(loaded);
+  return parser;
+}
+const field = (node, name) => node.childForFieldName(name);
+const lastLine = (node) => Math.max(node.startPosition.row + 1, node.endPosition.row + (node.endPosition.column ? 1 : 0));
+const hash = (text) => createHash('sha256').update(text).digest('hex').slice(0, 16);
+
+function declaredName(node) {
+  const name = field(node, 'name') ?? node.namedChildren.find((child) => child.type === 'function_name');
+  if (name) return name.text;
+  const declarator = field(node, 'declarator');
+  if (declarator) return declaredName(declarator) || (['identifier', 'field_identifier'].includes(declarator.type) ? declarator.text : '');
+  return '';
+}
+function declarationHeader(node, source, end) {
+  const cuts = [];
+  function visit(child) {
+    const body = field(child, 'body');
+    if (body && body.startIndex < end && body.endIndex <= end) { cuts.push([body.startIndex, body.endIndex]); return; }
+    for (const nested of child.namedChildren) if (nested.startIndex < end) visit(nested);
+  }
+  visit(node);
+  let header = source.slice(node.startIndex, end);
+  for (const [start, finish] of cuts.sort((a, b) => b[0] - a[0])) header = header.slice(0, start - node.startIndex) + '…' + header.slice(finish - node.startIndex);
+  return header.trim();
+}
+function documentation(node, body, language, source) {
+  if (language === 'python') {
+    const first = body?.namedChildren[0];
+    const string = first?.type === 'expression_statement' ? first.namedChildren[0] : null;
+    const literals = string?.type === 'concatenated_string' ? string.namedChildren : string ? [string] : [];
+    const valid = literals.length && literals.every((literal) => literal.type === 'string' && /^[rRuU]*['"]/.test(literal.text));
+    return valid ? { text: string.text, startLine: string.startPosition.row + 1 } : { text: '' };
+  }
+  let anchor = node;
+  while (anchor.parent && (['export_statement', 'decorated_definition'].includes(anchor.parent.type) || (['lexical_declaration', 'variable_declaration'].includes(anchor.parent.type) && !anchor.previousNamedSibling) || (language === 'powershell' && anchor.parent.type === 'statement_list' && !anchor.previousNamedSibling))) anchor = anchor.parent;
+  const comments = [];
+  let previous = anchor.previousNamedSibling;
+  let start = anchor.startIndex;
+  while (previous && source.slice(previous.endIndex, start).trim() === '') {
+    if (COMMENT_TYPES.has(previous.type)) comments.unshift(previous);
+    else if (!(language === 'rust' && previous.type === 'attribute_item')) break;
+    start = previous.startIndex;
+    previous = previous.previousNamedSibling;
+  }
+  const markers = ['javascript', 'typescript', 'tsx', 'java', 'php'].includes(language) ? /^\/\*\*/
+    : language === 'rust' ? /^(\/\/\/(?!\/)|\/\*\*)/
+    : ['cpp', 'c-sharp'].includes(language) ? /^(\/\*\*|\/\/\/|\/\/!|\/\*!)/ : null;
+  const docs = markers ? comments.filter((comment) => markers.test(comment.text)) : comments;
+  return { text: docs.map((comment) => comment.text).join('\n'), startLine: docs[0] ? docs[0].startPosition.row + 1 : undefined };
+}
+
+export async function extractSymbols(path, source, language) {
+  const parser = await parserFor(language);
+  let tree;
+  try {
+    tree = parser.parse(source);
+    if (!tree) throw new Error('Parser returned no syntax tree');
+    const symbols = [];
+    const imports = [];
+    const occurrences = new Map();
+    function walk(node, owner = null) {
+      let kind = DECLARATIONS[node.type];
+      let declaration = node;
+      let body = field(node, 'body') ?? (language === 'powershell' ? node.namedChildren.find((child) => child.type === 'script_block') : null);
+      if (['variable_declarator', 'public_field_definition'].includes(node.type)) {
+        const value = field(node, 'value');
+        if (value && ['arrow_function', 'function_expression', 'generator_function'].includes(value.type)) {
+          kind = 'function'; body = field(value, 'body');
+        }
+      }
+      if (node.type === 'type_spec' && ['struct_type', 'interface_type'].includes(field(node, 'type')?.type)) {
+        kind = 'class'; body = field(node, 'type').namedChildren.find((child) => child.type.endsWith('_list'));
+      }
+      if (node.type === 'impl_item') {
+        const type = field(node, 'type');
+        if (type) owner = symbols.find((symbol) => symbol.qualifiedName === type.text && ['struct', 'class'].includes(symbol.kind)) ?? { qualifiedName: type.text, id: null, kind: 'struct' };
+      }
+      if (kind === 'function' && owner && ['class', 'struct', 'interface', 'trait'].includes(owner.kind)) kind = 'method';
+      const name = kind ? declaredName(declaration) : '';
+      if (kind && name) {
+        const qualifiedName = owner ? `${owner.qualifiedName}.${name}` : name;
+        const signature = declarationHeader(declaration, source, body?.startIndex ?? declaration.endIndex);
+        const key = `${path}#${qualifiedName}:${kind}:${hash(signature)}`;
+        const occurrence = occurrences.get(key) ?? 0;
+        occurrences.set(key, occurrence + 1);
+        const doc = documentation(declaration, body, language, source);
+        const symbol = {
+          id: `symbol:${key}:${occurrence}`, kind, name, qualifiedName, ownerId: owner?.id ?? null,
+          language, path, signature, documentation: doc.text,
+          startLine: Math.min(doc.startLine ?? Infinity, declaration.startPosition.row + 1),
+          declarationStartLine: declaration.startPosition.row + 1, endLine: lastLine(declaration),
+          bodyStartLine: body ? body.startPosition.row + 1 : null, bodyEndLine: body ? lastLine(body) : null,
+          declarationStartOffset: declaration.startIndex, declarationEndOffset: declaration.endIndex,
+          bodyStartOffset: body?.startIndex ?? null, bodyEndOffset: body?.endIndex ?? null,
+        };
+        symbols.push(symbol);
+        owner = symbol;
+      }
+      if (['import_statement', 'export_statement', 'import_from_statement', 'use_declaration', 'include_directive', 'preproc_include'].includes(node.type)) {
+        const target = field(node, 'source') ?? field(node, 'module_name') ?? field(node, 'path') ?? field(node, 'argument');
+        if (target) imports.push({ specifier: target.text.replace(/^['"]|['"]$/g, ''), line: node.startPosition.row + 1, syntax: node.type });
+      }
+      for (const child of node.namedChildren) walk(child, owner);
+    }
+    walk(tree.rootNode);
+    return { symbols, imports, status: tree.rootNode.hasError ? 'partial' : 'parsed' };
+  } finally { tree?.delete(); parser.delete(); }
+}

package/src/symbols/runtime.mjs

@@ -0,0 +1,23 @@
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { LANGUAGE_EXTENSIONS } from './languages.mjs';
+
+const require = createRequire(import.meta.url);
+export function parserEntry() {
+  const bundled = fileURLToPath(new URL('./parsers/tree-sitter.cjs', import.meta.url));
+  return existsSync(bundled) ? bundled : require.resolve('@vscode/tree-sitter-wasm');
+}
+let identity;
+export function parserIdentity() {
+  if (!identity) {
+    const entry = parserEntry();
+    const hash = createHash('sha256').update(readFileSync(entry));
+    for (const name of ['tree-sitter.wasm', ...Object.keys(LANGUAGE_EXTENSIONS).map((language) => `tree-sitter-${language}.wasm`)]) hash.update(name).update(readFileSync(join(dirname(entry), name)));
+    identity = hash.digest('hex');
+  }
+  return identity;
+}
+export function loadParserApi() { return require(parserEntry()); }

package/src/symbols/store.mjs

@@ -0,0 +1,92 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { fingerprint } from '../index/files.mjs';
+import { sourceFiles, outlinePolicy as policy } from './discovery.mjs';
+export { sourceFiles } from './discovery.mjs';
+import { textFingerprint } from '../query/chunks.mjs';
+import { EXTRACTOR_ID, languageForPath } from './languages.mjs';
+
+export const OUTLINE_SCHEMA = 1;
+export const outlinePath = (root) => join(root, '.dotdotgod', 'outlines.json');
+function assertCachePath(root) {
+  for (const path of [dirname(outlinePath(root)), outlinePath(root)]) {
+    let stat;
+    try { stat = lstatSync(path); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (stat?.isSymbolicLink()) throw new Error(`Outline cache must not use symlinks: ${path}`);
+  }
+}
+export function readOutlines(root) {
+  try {
+    assertCachePath(root);
+    const index = JSON.parse(readFileSync(outlinePath(root), 'utf8'));
+    if (index.schema !== OUTLINE_SCHEMA || index.extractor !== EXTRACTOR_ID || !Array.isArray(index.files)) return null;
+    const paths = new Set(); const ids = new Set();
+    for (const file of index.files) {
+      if (typeof file.path !== 'string' || file.path.startsWith('/') || file.path.split('/').includes('..') || paths.has(file.path) || !/^[a-f0-9]{64}$/.test(file.hash)) return null;
+      if (!Number.isInteger(file.sourceLength) || file.sourceLength < 0 || !Number.isInteger(file.lineCount) || file.lineCount < 1) return null;
+      if (file.language !== languageForPath(file.path) || ((file.language === null) !== (file.status === 'unsupported'))) return null;
+      paths.add(file.path);
+      if (!['parsed', 'partial', 'unsupported', 'failed'].includes(file.status) || !Array.isArray(file.symbols) || !Array.isArray(file.imports)) return null;
+      if (file.imports.some((item) => typeof item.specifier !== 'string' || !Number.isInteger(item.line) || item.line < 1)) return null;
+      for (const symbol of file.symbols) {
+        if (symbol.path !== file.path || typeof symbol.id !== 'string' || !symbol.id.startsWith(`symbol:${file.path}#`) || ids.has(symbol.id) || typeof symbol.signature !== 'string' || typeof symbol.documentation !== 'string') return null;
+        if (!Number.isInteger(symbol.startLine) || !Number.isInteger(symbol.endLine) || symbol.startLine < 1 || symbol.endLine < symbol.startLine || symbol.endLine > file.lineCount) return null;
+        if (typeof symbol.name !== 'string' || typeof symbol.qualifiedName !== 'string' || !Number.isInteger(symbol.declarationStartLine) || symbol.declarationStartLine < symbol.startLine || symbol.declarationStartLine > symbol.endLine) return null;
+        if ((symbol.bodyStartLine === null) !== (symbol.bodyEndLine === null)) return null;
+        if (symbol.bodyStartLine !== null && (!Number.isInteger(symbol.bodyStartLine) || !Number.isInteger(symbol.bodyEndLine) || symbol.bodyStartLine < symbol.declarationStartLine || symbol.bodyEndLine > symbol.endLine || symbol.bodyEndLine < symbol.bodyStartLine)) return null;
+        if (!Number.isInteger(symbol.declarationStartOffset) || !Number.isInteger(symbol.declarationEndOffset) || symbol.declarationStartOffset < 0 || symbol.declarationEndOffset < symbol.declarationStartOffset || symbol.declarationEndOffset > file.sourceLength) return null;
+        if ((symbol.bodyStartOffset === null) !== (symbol.bodyEndOffset === null)) return null;
+        if (symbol.bodyStartOffset !== null && (!Number.isInteger(symbol.bodyStartOffset) || !Number.isInteger(symbol.bodyEndOffset) || symbol.bodyStartOffset < symbol.declarationStartOffset || symbol.bodyEndOffset > symbol.declarationEndOffset || symbol.bodyEndOffset < symbol.bodyStartOffset)) return null;
+        ids.add(symbol.id);
+      }
+    }
+    for (const file of index.files) for (const symbol of file.symbols) if (symbol.ownerId !== null && !ids.has(symbol.ownerId)) return null;
+    return index;
+  } catch { return null; }
+}
+export function outlineStatus(root) {
+  assertCachePath(root);
+  const files = sourceFiles(root);
+  const index = readOutlines(root);
+  if (!index) return { ok: files.length === 0 && !existsSync(outlinePath(root)), reason: existsSync(outlinePath(root)) ? 'missing-or-invalid' : 'missing', paths: files.map((file) => file.path) };
+  const old = new Map(index.files.map((file) => [file.path, file]));
+  const current = new Set(files.map((file) => file.path));
+  const changed = files.filter((file) => old.get(file.path)?.hash !== file.hash || old.get(file.path)?.sourceLength !== file.sourceLength || old.get(file.path)?.lineCount !== file.lineCount).map((file) => file.path);
+  const removed = [...old.keys()].filter((path) => !current.has(path));
+  const failures = index.files.filter((file) => ['failed', 'partial'].includes(file.status)).map((file) => file.path);
+  const policyOk = index.policy === policy(root);
+  return { ok: policyOk && !changed.length && !removed.length && !failures.length, reason: !policyOk ? 'policy-changed' : failures.length ? 'extraction-incomplete' : changed.length || removed.length ? 'source-changed' : 'fresh', paths: [...new Set([...changed, ...removed, ...failures])], unsupported: index.files.filter((file) => file.status === 'unsupported').map((file) => file.path) };
+}
+export async function buildOutlines(root) {
+  assertCachePath(root);
+  const files = sourceFiles(root);
+  const old = readOutlines(root);
+  const previous = new Map(old?.policy === policy(root) ? old.files.map((file) => [file.path, file]) : []);
+  let parsed = 0; let reused = 0;
+  const records = [];
+  for (const file of files) {
+    const cached = previous.get(file.path);
+    if (cached?.hash === file.hash && ['parsed', 'unsupported'].includes(cached.status)) { records.push(cached); reused += 1; continue; }
+    if (!file.language) { records.push({ ...file, status: 'unsupported', symbols: [], imports: [] }); continue; }
+    const { extractSymbols } = await import('./parser.mjs');
+    const source = readFileSync(join(root, file.path), 'utf8');
+    const extracted = await extractSymbols(file.path, source, file.language);
+    if (fingerprint(join(root, file.path)) !== file.hash) throw new Error(`Source changed during outline extraction: ${file.path}`);
+    records.push({ ...file, ...extracted }); parsed += 1;
+  }
+  const index = { schema: OUTLINE_SCHEMA, extractor: EXTRACTOR_ID, policy: policy(root), files: records, refresh: { parsed, reused } };
+  const target = outlinePath(root);
+  mkdirSync(dirname(target), { recursive: true });
+  const temporary = `${target}.tmp-${process.pid}-${randomUUID()}`;
+  writeFileSync(temporary, JSON.stringify(index), { flag: 'wx' }); renameSync(temporary, target);
+  return index;
+}
+export function outlineChunks(index) {
+  // ponytail: one passage per symbol; split long comments if provider input limits dominate.
+  return index.files.flatMap((file) => file.symbols.map((symbol) => {
+    const text = `${symbol.signature}\n${symbol.documentation}`.trim();
+    const passage = `Path: ${file.path}\nSymbol: ${symbol.qualifiedName}\nKind: ${symbol.kind}\n\n${text}`;
+    return { ...symbol, kind: 'symbol', symbolKind: symbol.kind, heading: symbol.qualifiedName, text, passage, sourceHash: file.hash, fingerprint: textFingerprint(passage) };
+  }));
+}

package/src/validate/run.mjs

@@ -9,6 +9,7 @@ import { cacheFile, collectIndexFiles, fingerprint } from '../index/files.mjs';
 import { CACHE_DIR, CACHE_VERSION } from '../index/constants.mjs';
 import { readIndex } from '../index/cache.mjs';
 import { sharedLocalReferences } from './references.mjs';
+import { outlineStatus, outlinePath } from '../symbols/store.mjs';
 
 export function runValidate(argv) {
   const options = { root: '.', includeLocalMemory: false, checkIndex: false, maxLines: null, maxChars: null, linkCheck: true, json: false };
@@ -173,6 +174,11 @@ export function runValidate(argv) {
     }
   }
   if (options.checkIndex) {
+    let outlines;
+    try { outlines = outlineStatus(root); }
+    catch (error) { outlines = { ok: false, reason: `inspection-unavailable: ${error instanceof Error ? error.message : String(error)}`, paths: [] }; }
+    if (!outlines.ok) addError(outlinePath(root), 'OUTLINE_INDEX_STALE', `Outline index: ${outlines.reason}${outlines.paths.length ? ` (${outlines.paths.join(', ')})` : ''}`, null, 'run `dotdotgod index <root>` to refresh outlines and graph metadata; validation does not parse, embed or repair.');
+    for (const path of outlines.unsupported ?? []) addWarning(join(root, path), 'OUTLINE_LANGUAGE_UNSUPPORTED', 'Source language is not supported by the current outline extraction matrix.');
     const index = readIndex(root);
     if (!index) addError(cacheFile(root), 'INDEX_MISSING', 'Expected .dotdotgod index cache.', null, 'run `dotdotgod index <root>` to build the graph index.');
     else {