genesis-compiler 1.7.8 → 1.8.0

package/src/index/code-indexers/ast-grep.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 
 import { fileURLToPath } from 'node:url';
 import { asDiagnostic } from '../errors.js';
+import { sha256 } from '../utils.js';
 import { runProcess } from '../process.js';
 import { parserAbortSignal, prepareCodeParsers } from './parsers.js';
 
@@ -52,6 +53,136 @@ const DEFINITIONS = Object.freeze({
   },
 });
 const CALLABLE_KINDS = new Set(Object.values(DEFINITIONS).flatMap(({ kinds }) => kinds));
+const DECLARATION_KINDS = {
+  javascript: ['class_declaration', 'class', 'interface_declaration', 'type_alias_declaration', 'enum_declaration', 'variable_declarator', 'field_definition', 'public_field_definition'],
+  python: ['class_definition', 'assignment'], java: ['class_declaration', 'interface_declaration', 'enum_declaration', 'field_declaration', 'constant_declaration'],
+  csharp: ['class_declaration', 'interface_declaration', 'struct_declaration', 'enum_declaration', 'field_declaration', 'property_declaration'],
+  cpp: ['class_specifier', 'struct_specifier', 'enum_specifier', 'declaration', 'field_declaration'], php: ['class_declaration', 'interface_declaration', 'trait_declaration', 'const_declaration', 'property_declaration'],
+  go: ['type_spec', 'const_spec', 'var_spec'], rust: ['struct_item', 'enum_item', 'trait_item', 'type_item', 'const_item', 'static_item'],
+  ruby: ['class', 'module', 'assignment'], kotlin: ['class_declaration', 'object_declaration', 'property_declaration'], shell: [],
+};
+
+function nodeRange(node, lineOffset = 0, columnOffset = 0) {
+  const range = node.range();
+  let start = range.start;
+  // Rust attributes are siblings of the item whose semantics they govern.
+  if (node.kind().endsWith('_item')) {
+    const siblings = node.parent()?.children() || [];
+    for (let index = siblings.findIndex(child => child.id() === node.id()) - 1; index >= 0; index--) {
+      const previous = siblings[index];
+      if (previous.kind() === 'attribute_item') start = previous.range().start;
+      else if (previous.kind() !== 'line_comment' && previous.kind() !== 'block_comment') break;
+    }
+  }
+  // napi ranges use UTF-16 columns, matching the editor; do not convert them as bytes.
+  const position = point => ({
+    line: point.line + lineOffset + 1,
+    column: point.column + 1 + (point.line === 0 ? columnOffset : 0),
+  });
+  return { start: position(start), end: position(range.end) };
+}
+
+function declarationNode(node) {
+  if (['arrow_function', 'function_expression'].includes(node.kind())) {
+    if (['field_definition', 'public_field_definition'].includes(node.parent()?.kind())) return node.parent();
+    return ancestor(node, ['lexical_declaration', 'variable_declaration']) || node;
+  }
+  if (['const_spec', 'var_spec', 'type_spec'].includes(node.kind())) return ancestor(node, ['const_declaration', 'var_declaration', 'type_declaration']) || node;
+  return node.parent()?.kind() === 'decorated_definition' ? node.parent() : node;
+}
+
+function declarationsInTree(root, language, source, lineOffset, columnOffset, pythonExports = null) {
+  const exportedNames = language === 'javascript' ? javascriptExportedNames(source) : pythonExports?.names;
+  const result = [];
+  for (const kind of DECLARATION_KINDS[language] || []) {
+    let nodes;
+    try { nodes = root.findAll({ rule: { kind } }); } catch { continue; }
+    for (const node of nodes) {
+      let declaredNodes = [node];
+      if (language === 'java' && ['field_declaration', 'constant_declaration'].includes(kind)) declaredNodes = node.children().filter(child => child.kind() === 'variable_declarator');
+      if (language === 'csharp' && kind === 'field_declaration') declaredNodes = node.children().find(child => child.kind() === 'variable_declaration')?.children().filter(child => child.kind() === 'variable_declarator') || [];
+      if (language === 'php' && ['const_declaration', 'property_declaration'].includes(kind)) declaredNodes = node.children().filter(child => ['const_element', 'property_element'].includes(child.kind()));
+      if (language === 'go' && ['const_spec', 'var_spec'].includes(kind)) declaredNodes = node.children().filter(child => child.kind() === 'identifier');
+      if (language === 'ruby' && kind === 'assignment' && safeField(node, 'left')?.kind() !== 'constant') continue;
+      if (language === 'python' && kind === 'assignment' && (safeField(node, 'left')?.text() === '__all__' || node.ancestors().some(parent => parent.kind() === 'function_definition'))) continue;
+      if (['variable_declarator', 'field_definition', 'public_field_definition'].includes(kind) && ['arrow_function', 'function_expression'].includes(safeField(node, 'value')?.kind())) continue;
+      const declaration = kind === 'variable_declarator' ? node.parent() : declarationNode(node);
+      const range = nodeRange(declaration, lineOffset, columnOffset);
+      for (const namedNode of declaredNodes) {
+        const name = namedNode.kind() === 'identifier' ? namedNode.text() : declaredName(namedNode);
+        if (!name) continue;
+        const prototype = language === 'cpp' && safeField(node, 'declarator')?.kind() === 'function_declarator' && ['identifier', 'field_identifier'].includes(safeField(safeField(node, 'declarator'), 'declarator')?.kind());
+        const value = ['assignment', 'variable_declarator', 'field_definition', 'public_field_definition', 'const_spec', 'var_spec', 'const_item', 'static_item', 'field_declaration', 'property_declaration', 'const_declaration', 'constant_declaration', 'declaration'].includes(kind);
+        const scope = language === 'rust' ? node.children().find(child => child.kind() === 'visibility_modifier')?.text() || 'private' : null;
+        result.push({ name, qualifiedName: [containerName(node, language), name].filter(Boolean).join(language === 'php' ? '::' : '.'), kind: prototype ? 'function' : kind.includes('class') || kind === 'class' ? 'class' : kind.includes('interface') ? 'interface' : value ? 'value' : 'type', visibility: visibility(kind === 'variable_declarator' ? node.parent() : node, name, language, exportedNames), ...(scope ? { visibilityScope: scope === 'pub' ? 'public' : scope.replace(/^pub\((.*)\)$/u, '$1') } : {}), ...range, line: range.start.line, column: range.start.column });
+      }
+    }
+  }
+  return result;
+}
+
+// These are syntax observations. Resolution belongs to the native index, and
+// unsupported/dynamic targets remain explicit rather than guessed.
+function dependencyReferences(root, language, source, lineOffset, columnOffset) {
+  const kinds = {
+    javascript: ['import_statement', 'export_statement', 'call_expression'],
+    python: ['import_statement', 'import_from_statement'], cpp: ['preproc_include'],
+    java: ['import_declaration'], csharp: ['using_directive'], go: ['import_spec'],
+    rust: ['use_declaration', 'mod_item'], php: ['namespace_use_declaration', 'include_expression', 'require_expression'],
+    ruby: ['call'], kotlin: ['import_header'], shell: ['command'],
+  }[language] || [];
+  const references = [];
+  for (const kind of kinds) {
+    let nodes;
+    try { nodes = root.findAll({ rule: { kind } }); } catch { continue; }
+    for (const node of nodes) {
+      const text = node.text();
+      let target;
+      let relationKind = 'import';
+      let typeOnly = false;
+      let exports;
+      if (language === 'javascript') {
+        if (kind === 'call_expression' && !/^(?:require|import)\s*\(/u.test(text)) continue;
+        if (kind === 'export_statement' && !/\bfrom\s+['"]/u.test(text)) continue;
+        target = text.match(/(?:\bfrom\s*|^(?:require|import)\s*\(\s*|^import\s*)['"]([^'"]+)['"]/u)?.[1];
+        if (kind === 'export_statement') relationKind = 're-export';
+        const clause = node.children().find(child => ['import_clause', 'export_clause'].includes(child.kind()));
+        const specifiers = clause?.findAll({ rule: { kind: kind === 'export_statement' ? 'export_specifier' : 'import_specifier' } }) || [];
+        if (kind === 'export_statement') {
+          exports = specifiers.map(specifier => ({ name: safeField(specifier, 'name')?.text(), alias: safeField(specifier, 'alias')?.text() || safeField(specifier, 'name')?.text() })).filter(entry => entry.name && entry.alias);
+          // Namespace exports are values, not the individual operations inside
+          // them. Leave those unresolved rather than inventing signatures.
+          if (!clause && node.children().some(child => child.kind() === '*') && !node.children().some(child => child.kind() === 'namespace_export')) exports = [{ name: '*', alias: '*' }];
+        }
+        typeOnly = node.children().some(child => child.kind() === 'type') ||
+          (specifiers.length > 0 && specifiers.every(specifier => specifier.children().some(child => child.kind() === 'type')) && !clause.children().some(child => ['identifier', 'namespace_import'].includes(child.kind()))) ||
+          (kind === 'call_expression' && /^import\s*\(/u.test(text) && node.ancestors().some(parent => ['type_alias_declaration', 'type_annotation', 'type_query'].includes(parent.kind())));
+        if (typeOnly && kind !== 'export_statement') relationKind = 'type-import';
+      } else if (language === 'python') {
+        const from = text.match(/^from\s+([.\w]+)\s+import/u);
+        if (from) target = from[1];
+        else target = text.match(/^import\s+([\w.]+)/u)?.[1];
+      } else if (language === 'cpp') {
+        target = text.match(/#\s*include\s*["<]([^">]+)[">]/u)?.[1]; relationKind = 'include';
+      } else if (language === 'go') target = text.match(/["`]([^"`]+)["`]/u)?.[1];
+      else if (language === 'ruby') {
+        if (!/^require(?:_relative)?\b/u.test(text)) continue;
+        target = text.match(/['"]([^'"]+)['"]/u)?.[1];
+        if (/^require_relative\b/u.test(text) && target && !target.startsWith('.')) target = `./${target}`;
+      } else if (language === 'shell') {
+        if (!/^(?:source|\.)\s/u.test(text)) continue;
+        target = text.match(/^(?:source|\.)\s+(?:['"]([^'"]+)['"]|([^\s;$]+))/u)?.slice(1).find(Boolean);
+        if (target?.includes('$')) target = null;
+      } else if (language === 'java' || language === 'kotlin') target = text.match(/^import\s+(?:static\s+)?([\w.*]+)/u)?.[1];
+      else if (language === 'csharp') target = text.match(/^using\s+(?:static\s+)?([\w.]+)\s*;/u)?.[1];
+      else if (language === 'rust') target = text.match(/^(?:pub\s+)?(?:use|mod)\s+([\w:]+)/u)?.[1];
+      else if (language === 'php') target = text.match(/['"]([^'"]+)['"]/u)?.[1] || text.match(/^use\s+([\w\\]+)/u)?.[1];
+      const range = nodeRange(node, lineOffset, columnOffset);
+      references.push({ specifier: target || null, kind: relationKind, typeOnly, ...(exports ? { exports } : {}), ...range, resolution: target ? 'pending' : 'unresolved', reason: target ? '' : 'Dynamic or unsupported dependency expression.' });
+    }
+  }
+  return references;
+}
 
 function safeField(node, name) {
   try { return node.field(name); } catch { return null; }
@@ -71,8 +202,13 @@ function firstDescendant(node, kinds) {
 function declaredName(node) {
   const direct = safeField(node, 'name');
   if (direct) return direct.text().trim();
+  if (node.kind() === 'field_definition') return safeField(node, 'property')?.text() || '';
+  if (node.kind() === 'assignment') return ['identifier', 'constant'].includes(safeField(node, 'left')?.kind()) ? safeField(node, 'left').text() : '';
+  if (node.kind() === 'property_declaration') return node.children().find(child => child.kind() === 'variable_declaration')?.children().find(child => child.kind() === 'simple_identifier')?.text() || '';
   const parent = node.parent();
+  if (parent?.kind() === 'export_statement' && parent.children().some(child => child.kind() === 'default')) return 'default';
   if (['arrow_function', 'function_expression'].includes(node.kind())) {
+    if (['field_definition', 'public_field_definition'].includes(parent?.kind())) return (safeField(parent, 'property') || safeField(parent, 'name'))?.text() || '';
     if (parent?.kind() === 'variable_declarator') {
       return safeField(parent, 'name')?.text().trim() || parent.child(0)?.text().trim() || '';
     }
@@ -141,7 +277,7 @@ function containerName(node, language) {
     const receiver = safeField(node, 'receiver')?.text().trim();
     if (receiver) return receiver.replace(/^\(|\)$/gu, '').replace(/^\w+\s+\*?/u, '').trim();
   }
-  const container = node.ancestors().find((candidate) => CONTAINER_KINDS.has(candidate.kind()));
+  const container = node.ancestors().find((candidate) => CONTAINER_KINDS.has(candidate.kind()) && !(language === 'python' && candidate.kind() === 'module'));
   if (!container) {
     const parentFunction = node.ancestors().find((candidate) => DEFINITIONS.javascript.kinds.includes(candidate.kind())
       || candidate.kind() === 'function_definition');
@@ -152,6 +288,7 @@ function containerName(node, language) {
       || container.text().match(/^\s*impl(?:<[^>]+>)?\s+([^\s{]+)/u)?.[1]
       || null;
   }
+  if (language === 'javascript' && container.parent()?.kind() === 'export_statement' && container.parent().children().some(child => child.kind() === 'default')) return declaredName(container);
   return safeField(container, 'name')?.text().trim()
     || container.children().find((child) => [
       'constant', 'identifier', 'name', 'simple_identifier', 'type_identifier',
@@ -160,12 +297,22 @@ function containerName(node, language) {
 }
 
 function directText(node) {
-  return node.children().slice(0, 4).map((child) => child.text()).join(' ');
+  // Access/storage modifiers are syntax, not words in bodies or annotations.
+  const keywords = new Set(['public', 'private', 'protected', 'internal', 'static']);
+  const relevant = child => child.kind().includes('modifier') || child.kind() === 'storage_class_specifier' || keywords.has(child.kind());
+  const pending = node.children().filter(relevant); const words = [];
+  while (pending.length) {
+    const child = pending.pop();
+    if (keywords.has(child.text())) words.push(child.text());
+    else pending.push(...child.children().filter(relevant));
+  }
+  return words.join(' ');
 }
 
 function cPlusPlusVisibility(node) {
+  if (node.ancestors().some(parent => parent.kind() === 'namespace_definition' && !safeField(parent, 'name'))) return 'internal';
   const classBody = ancestor(node, ['field_declaration_list']);
-  if (!classBody) return /^\s*static\b/u.test(node.text()) ? 'internal' : 'public';
+  if (!classBody) return /\bstatic\b/u.test(directText(node)) ? 'internal' : 'public';
   const classNode = ancestor(node, ['class_specifier', 'struct_specifier', 'union_specifier']);
   let current = /^\s*class\b/u.test(classNode?.text() || '') ? 'private' : 'public';
   for (const sibling of classBody.children()) {
@@ -205,16 +352,41 @@ function javascriptExportedNames(source) {
   return names;
 }
 
+function pythonExportedNames(root) {
+  let names = null; let partial = false;
+  const nodes = root.findAll({ rule: { any: [{ kind: 'assignment' }, { kind: 'augmented_assignment' }, { kind: 'call' }] } });
+  for (const node of nodes.sort((a, b) => a.range().start.index - b.range().start.index)) {
+    const parents = node.ancestors();
+    if (parents.some(parent => ['function_definition', 'class_definition', 'lambda'].includes(parent.kind()))) continue;
+    const call = node.kind() === 'call';
+    if (call ? !node.findAll({ rule: { kind: 'identifier' } }).some(identifier => identifier.text() === '__all__') : safeField(node, 'left')?.text() !== '__all__') continue;
+    const right = safeField(node, 'right');
+    const literals = right && ['list', 'tuple'].includes(right.kind()) ? right.children().filter(child => !['[', ']', '(', ')', ',', 'comment'].includes(child.kind())) : null;
+    const values = literals?.map(child => child.kind() === 'string' ? child.text().match(/^(?:r|u)?(['"])([^'"\\\r\n]*)\1$/iu)?.[2] : undefined);
+    const addition = node.kind() === 'augmented_assignment';
+    if (call || parents.some(parent => !['module', 'expression_statement'].includes(parent.kind())) || !values || values.some(value => value === undefined) || (addition && (!names || safeField(node, 'operator')?.text() !== '+='))) {
+      names = null; partial = true;
+    } else {
+      names = new Set([...(addition ? names : []), ...values]); partial = false;
+    }
+  }
+  return { names, partial };
+}
+
 function javascriptVisibility(node, name, exportedNames) {
-  if (name.startsWith('#') || /\b(?:private|protected)\s+/u.test(directText(node))) return 'internal';
-  const classNode = ancestor(node, ['class_declaration', 'class_expression']);
+  if (name.startsWith('#') || node.children().some(child => child.kind() === 'accessibility_modifier' && ['private', 'protected'].includes(child.text()))) return 'internal';
+  if (['field_definition', 'public_field_definition'].includes(node.parent()?.kind()) && node.parent().children().some(child => child.kind() === 'accessibility_modifier' && ['private', 'protected'].includes(child.text()))) return 'internal';
+  // An exported class exposes its members, not locals inside those members.
+  // An export-name match also cannot expose a shadowing nested declaration.
+  if (node.ancestors().some(parent => DEFINITIONS.javascript.kinds.includes(parent.kind()))) return 'internal';
+  const classNode = ancestor(node, ['class_declaration', 'class_expression', 'class']);
   if (classNode) {
     const className = declaredName(classNode);
     const exported = classNode.parent()?.kind() === 'export_statement' || exportedNames.has(className);
     return exported ? 'public' : 'internal';
   }
   const declaration = ['arrow_function', 'function_expression'].includes(node.kind())
-    ? ancestor(node, ['lexical_declaration', 'variable_declaration'])
+    ? ancestor(node, ['lexical_declaration', 'variable_declaration']) || node
     : node;
   return declaration?.parent()?.kind() === 'export_statement' || exportedNames.has(name)
     ? 'public'
@@ -223,27 +395,30 @@ function javascriptVisibility(node, name, exportedNames) {
 
 function visibility(node, name, language, exportedNames) {
   const head = directText(node);
+  if (node.ancestors().some(parent => CALLABLE_KINDS.has(parent.kind()) || ['lambda_expression', 'closure_expression', 'lambda_literal', 'func_literal', 'lambda', 'anonymous_method_expression'].includes(parent.kind()))) return 'internal';
   if (language === 'javascript') return javascriptVisibility(node, name, exportedNames);
   if (language === 'python') {
     const nestedFunction = node.ancestors().some((candidate) => candidate.kind() === 'function_definition');
-    return !nestedFunction && !name.startsWith('_') ? 'public' : 'internal';
+    if (nestedFunction) return 'internal';
+    const classMember = node.ancestors().some(parent => parent.kind() === 'class_definition');
+    return (exportedNames && !classMember ? exportedNames.has(name) : !name.startsWith('_')) ? 'public' : 'internal';
   }
-  if (['java', 'csharp'].includes(language)) return /\bpublic\b/u.test(head) ? 'public' : 'internal';
+  if (['java', 'csharp'].includes(language)) return /\bpublic\b/u.test(head) || (!/\b(?:private|protected|internal)\b/u.test(head) && ancestor(node, ['interface_declaration'])) ? 'public' : 'internal';
   if (language === 'cpp') return cPlusPlusVisibility(node);
   if (language === 'php') return /\b(?:private|protected)\b/u.test(head) ? 'internal' : 'public';
   if (language === 'go') return /^\p{Lu}/u.test(name) ? 'public' : 'internal';
   if (language === 'rust') return /^\s*pub(?:\([^)]*\))?\s+/u.test(node.text()) ? 'public' : 'internal';
-  if (language === 'ruby') return rubyVisibility(node);
+  if (language === 'ruby') return node.kind() === 'assignment' && safeField(node, 'left')?.kind() === 'constant' ? 'public' : rubyVisibility(node);
   if (language === 'kotlin') return /\b(?:private|protected|internal)\b/u.test(head) ? 'internal' : 'public';
   if (language === 'shell') return name.startsWith('_') ? 'internal' : 'public';
   return 'internal';
 }
 
-function callableKind(node, name) {
+function callableKind(node, name, language) {
   if (node.kind().includes('constructor') || ['__construct', '__init__', 'constructor'].includes(name)) return 'constructor';
   if (node.kind().includes('method')) return 'method';
   const owner = node.ancestors().find((candidate) => (
-    CONTAINER_KINDS.has(candidate.kind()) || CALLABLE_KINDS.has(candidate.kind())
+    !(language === 'python' && candidate.kind() === 'module') && (CONTAINER_KINDS.has(candidate.kind()) || CALLABLE_KINDS.has(candidate.kind()))
   ));
   return owner && CONTAINER_KINDS.has(owner.kind()) ? 'method' : 'function';
 }
@@ -256,20 +431,21 @@ function scriptUnits(source, filePath, definition) {
   const units = [];
   for (const match of source.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script\s*>/giu)) {
     const content = match[2] || '';
-    const contentIndex = (match.index || 0) + match[0].indexOf(content);
+    const contentIndex = (match.index || 0) + match[0].indexOf('>') + 1;
     const typescript = /\blang\s*=\s*["']tsx?["']/iu.test(match[1] || '');
     const jsx = /\blang\s*=\s*["'](?:jsx|tsx)["']/iu.test(match[1] || '');
     units.push({
       source: content,
       lineOffset: source.slice(0, contentIndex).split('\n').length - 1,
+      columnOffset: contentIndex - (source.lastIndexOf('\n', contentIndex - 1) + 1),
       parser: jsx ? 'Tsx' : typescript ? 'TypeScript' : 'JavaScript',
     });
   }
   return units;
 }
 
-function functionsInTree(root, definition, { language, lineOffset, source }) {
-  const exportedNames = language === 'javascript' ? javascriptExportedNames(source) : new Set();
+function functionsInTree(root, definition, { language, lineOffset, columnOffset, source, pythonExports = null }) {
+  const exportedNames = language === 'javascript' ? javascriptExportedNames(source) : pythonExports?.names;
   const nodes = new Map();
   for (const kind of definition.kinds) {
     for (const node of root.findAll({ rule: { kind } })) nodes.set(node.id(), node);
@@ -280,16 +456,22 @@ function functionsInTree(root, definition, { language, lineOffset, source }) {
       if (!name) return null;
       const container = containerName(node, language);
       const location = node.range().start;
+      const range = nodeRange(declarationNode(node), lineOffset, columnOffset);
       const parameters = splitParameters(parameterText(node));
       const resolvedVisibility = visibility(node, name, language, exportedNames);
+      const scope = language === 'rust' ? node.children().find(child => child.kind() === 'visibility_modifier')?.text() || 'private' : null;
       return {
         name,
         qualifiedName: [container, name].filter(Boolean).join(language === 'php' ? '::' : '.'),
-        kind: callableKind(node, name),
+        kind: callableKind(node, name, language),
         visibility: resolvedVisibility,
+        ...(language === 'javascript' && declarationNode(node).parent()?.kind() === 'export_statement' && declarationNode(node).parent().children().some(child => child.kind() === 'default') ? { exportName: 'default' } : {}),
+        ...(scope ? { visibilityScope: scope === 'pub' ? 'public' : scope.replace(/^pub\((.*)\)$/u, '$1') } : {}),
         container,
         line: location.line + lineOffset + 1,
-        column: location.column + 1,
+        column: location.column + 1 + (location.line === 0 ? columnOffset || 0 : 0),
+        start: range.start,
+        end: range.end,
         parameters,
         async: /^\s*async\b/u.test(node.text()),
         generator: /\bfunction\s*\*|\byield\b/u.test(node.text()),
@@ -304,7 +486,9 @@ function hasSupportedExtension(filePath, definition) {
 }
 
 function isCandidate(file, definition) {
-  if (file.path.split('/').some((segment) => EXCLUDED_DIRECTORIES.has(segment))) return false;
+  // Only package discovery can supply a finite, declared public entry. Normal
+  // project indexing retains its original generated/dependency exclusions.
+  if (!file.publicEntry && file.path.split('/').some((segment) => EXCLUDED_DIRECTORIES.has(segment))) return false;
   return hasSupportedExtension(file.path, definition)
     || (definition.shebang && file.mode === 0o100755 && path.posix.extname(file.path) === '');
 }
@@ -351,8 +535,14 @@ function createIndexer(id) {
           });
           continue;
         }
+        if (sha256(source) !== file.hash) {
+          diagnostics.push({ code: 'CODE_INDEX_SOURCE_CHANGED', path: file.path, message: 'The source changed during indexing or is not valid UTF-8. Refresh analysis against a stable source snapshot.' });
+          continue;
+        }
         if (!hasSupportedExtension(file.path, definition) && !definition.shebang?.test(source)) continue;
         const functions = [];
+        const symbols = [];
+        const dependencies = [];
         for (const unit of scriptUnits(source, file.path, definition)) {
           try {
             if (parserErrors[unit.parser]) {
@@ -361,11 +551,17 @@ function createIndexer(id) {
             }
             const parsed = await parseAsync(unit.parser, unit.source);
             const root = parsed.root();
+            const pythonExports = id === 'python' ? pythonExportedNames(root) : null;
+            if (pythonExports?.partial) diagnostics.push({ code: 'CODE_INDEX_PYTHON_EXPORTS_PARTIAL', path: file.path, message: 'Python __all__ is dynamic or conditional. Public naming is shown; runtime exports remain unresolved.' });
             functions.push(...functionsInTree(root, definition, {
               language: id,
               lineOffset: unit.lineOffset,
+              columnOffset: unit.columnOffset,
               source: unit.source,
+              pythonExports,
             }));
+            symbols.push(...declarationsInTree(root, id, unit.source, unit.lineOffset, unit.columnOffset, pythonExports));
+            dependencies.push(...dependencyReferences(root, id, unit.source, unit.lineOffset, unit.columnOffset));
             diagnostics.push(...syntaxDiagnostics(root, file.path, unit.lineOffset));
           } catch (error) {
             if (error.code === 'PROCESS_ABORTED') throw error;
@@ -376,6 +572,12 @@ function createIndexer(id) {
             });
           }
         }
+        // Vue SFCs expose a component as their default public interface even
+        // when <script setup> has no explicit JavaScript export declaration.
+        if (id === 'javascript' && file.path.endsWith('.vue') && source.length) {
+          const lines = source.split('\n');
+          symbols.push({ name: 'Component', qualifiedName: 'default component', exportName: 'default', kind: 'component', visibility: 'public', container: null, line: 1, column: 1, start: { line: 1, column: 1 }, end: { line: lines.length, column: lines.at(-1).length + 1 } });
+        }
         indexedFiles.push({
           path: file.path,
           language: id,
@@ -385,6 +587,8 @@ function createIndexer(id) {
           lines: source.length === 0 ? 0 : source.split('\n').length - (source.endsWith('\n') ? 1 : 0),
           hash: file.hash,
           functions,
+          symbols,
+          dependencies,
         });
       }
       return { files: indexedFiles, diagnostics };
@@ -398,7 +602,7 @@ export const astGrepCodeIndexers = new Map(
 
 // ast-grep permits one registration per process. A finite indexing child loads
 // this request's languages once and releases every native parser when it exits.
-export async function extractCodeIndexes({ indexers, files, projectRoot }) {
+export async function extractCodeIndexes({ indexers, files, projectRoot, signal }) {
   const selected = indexers.filter(id => astGrepCodeIndexers.has(id));
   const diagnostics = indexers.filter(id => !astGrepCodeIndexers.has(id)).map(id => ({
     code: 'CODE_INDEXER_UNAVAILABLE', message: `No installed code indexer exists for ${id}.`,
@@ -412,7 +616,7 @@ export async function extractCodeIndexes({ indexers, files, projectRoot }) {
   try {
     const result = await runProcess(process.execPath, [fileURLToPath(new URL('./worker.js', import.meta.url))], {
       input: JSON.stringify({ indexers: selected, files, projectRoot, registrations, errors }),
-      signal: parserAbortSignal(), timeoutMs: 180_000, code: 'CODE_INDEXER_FAILED',
+      signal: signal || parserAbortSignal(), timeoutMs: 180_000, code: 'CODE_INDEXER_FAILED',
     });
     contributions = JSON.parse(result.stdout.toString('utf8'));
   } catch (error) {

package/src/index/code-indexers/npm-packages.js

@@ -0,0 +1,200 @@
+import { lstat, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { minimatch } from 'minimatch';
+import { extractCodeIndexes } from './ast-grep.js';
+import { sha256 } from '../utils.js';
+
+const canonical = value => typeof value === 'string' && value.length > 0 && value !== '.' && !path.posix.isAbsolute(value) && path.posix.normalize(value) === value && !/[\\\0]/u.test(value) && !value.split('/').includes('..');
+const packageName = value => typeof value === 'string' && /^(?:@[a-zA-Z0-9._-]+\/)?[a-zA-Z0-9._-]+$/u.test(value) && !value.split('/').some(part => part === '.' || part === '..');
+
+// npm owns manifest and export semantics. Read direct declarations and their
+// public entry files only; never walk dependency trees or enumerate internals.
+export async function inspectNpmPackages({ projectRoot, discovery, files, indexedFiles = [], signal }) {
+  const known = new Map(files.map(file => [file.path, file]));
+  const packages = []; const inputs = []; const diagnostics = [];
+  const manifests = new Map(); const workspaceScopes = []; const byRoot = new Map();
+  async function read(relative, { indexed = false } = {}) {
+    signal?.throwIfAborted();
+    if (!canonical(relative)) return null;
+    try {
+      for (let index = 0, parts = relative.split('/'); index < parts.length; index++) if ((await lstat(path.join(projectRoot, ...parts.slice(0, index + 1)))).isSymbolicLink()) return null;
+      const bytes = await readFile(path.join(projectRoot, relative), { signal });
+      if (bytes.length > 4 * 1024 * 1024) return null;
+      if (!Buffer.from(bytes.toString('utf8'), 'utf8').equals(bytes)) return null;
+      const hash = sha256(bytes);
+      if (indexed && known.get(relative)?.hash !== hash) throw new Error(`Package declaration changed: ${relative}`);
+      if (!indexed) inputs.push({ path: relative, hash });
+      return { path: relative, hash, source: bytes.toString('utf8') };
+    } catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null; throw error; }
+  }
+  // Workspace ownership comes from each declared workspace root, including
+  // manifests in packages which do not repeat their parent's workspaces field.
+  for (const manifest of discovery.manifests) {
+    if (!known.has(manifest)) continue;
+    const input = await read(manifest, { indexed: true });
+    if (!input) { diagnostics.push({ code: 'NPM_MANIFEST_UNAVAILABLE', path: manifest, message: 'The declared dependency manifest cannot be read safely.' }); continue; }
+    let document;
+    try { document = JSON.parse(input.source); if (!document || typeof document !== 'object' || Array.isArray(document)) throw new TypeError('Manifest must be an object'); } catch { diagnostics.push({ code: 'NPM_MANIFEST_INVALID', path: manifest, message: 'The direct dependency manifest is invalid JSON.' }); continue; }
+    manifests.set(manifest, { input, document });
+    const declaration = Array.isArray(document.workspaces?.packages) ? document.workspaces.packages : document.workspaces;
+    const patterns = []; const exclusions = [];
+    for (const declared of Array.isArray(declaration) ? declaration : []) {
+      if (typeof declared !== 'string') continue;
+      const prefix = declared.match(/^!+/u)?.[0] || '';
+      const pattern = declared.slice(prefix.length).replace(/^\.\//u, '').replace(/\/$/u, '');
+      if (!canonical(pattern)) continue;
+      if (prefix.length % 2) exclusions.push(pattern);
+      else {
+        // npm lets a later positive pattern override preceding exclusions.
+        for (let index = exclusions.length - 1; index >= 0; index--) if (minimatch(pattern, exclusions[index])) exclusions.splice(index, 1);
+        patterns.push(pattern);
+      }
+    }
+    if (!patterns.length) continue;
+    const workspaces = new Map();
+    for (const candidate of known.keys()) {
+      if (!candidate.endsWith('/package.json')) continue;
+      const directory = path.posix.dirname(candidate);
+      const relative = path.posix.relative(path.posix.dirname(manifest), directory);
+      if (!patterns.some(pattern => minimatch(relative, pattern)) || exclusions.some(pattern => minimatch(relative, pattern, { dot: true }))) continue;
+      const workspace = await read(candidate, { indexed: true });
+      let definition; try { definition = workspace && JSON.parse(workspace.source); } catch { continue; }
+      if (!definition || !packageName(definition.name)) continue;
+      if (workspaces.has(definition.name)) { workspaces.set(definition.name, null); diagnostics.push({ code: 'NPM_WORKSPACE_AMBIGUOUS', path: candidate, message: `${definition.name}: multiple declared workspace roots; ownership is unresolved.` }); }
+      else workspaces.set(definition.name, directory);
+    }
+    workspaceScopes.push({ directory: path.posix.dirname(manifest), workspaces });
+  }
+  const entries = [];
+  for (const [manifest, { input, document }] of manifests) {
+    const parent = path.posix.dirname(manifest);
+    const scope = workspaceScopes.filter(entry => entry.directory === '.' || parent === entry.directory || parent.startsWith(`${entry.directory}/`)).sort((a, b) => b.directory.length - a.directory.length)[0];
+    const declarations = new Map();
+    for (const kind of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) for (const [name, requested] of Object.entries(document[kind] || {})) {
+      if (!packageName(name) || typeof requested !== 'string') continue;
+      if (!declarations.has(name)) declarations.set(name, { requested, kinds: [] });
+      declarations.get(name).kinds.push(kind);
+    }
+    for (const [name, declaration] of declarations) {
+      let root = path.posix.join(parent, discovery.packageRoot, name);
+      const ownedRoot = declaration.requested.startsWith('file:') ? path.posix.normalize(path.posix.join(parent, declaration.requested.slice(5))) : scope?.workspaces.get(name);
+      const ownedManifest = ownedRoot ? path.posix.join(ownedRoot, 'package.json') : null;
+      const owned = ownedManifest && canonical(ownedManifest) && known.has(ownedManifest);
+      let metadata = owned ? await read(ownedManifest, { indexed: true }) : null;
+      if (owned) root = ownedRoot;
+      else {
+        // npm hoists installations. Resolve the nearest safe installation inside
+        // this project; custom Stack package roots retain their exact meaning.
+        let directory = parent;
+        while (true) {
+          const candidate = path.posix.join(directory, discovery.packageRoot, name);
+          metadata = await read(`${candidate}/package.json`);
+          if (metadata) { root = candidate; break; }
+          if (directory === '.' || discovery.packageRoot !== 'node_modules') break;
+          directory = path.posix.dirname(directory);
+        }
+      }
+      const identity = `${root}:${name}`;
+      const existing = byRoot.get(identity);
+      const declared = { manifest, requested: declaration.requested, dependencyKinds: declaration.kinds };
+      if (existing) {
+        existing.declarations.push(declared); existing.evidence.push({ path: input.path, hash: input.hash });
+        existing.dependencyKinds = [...new Set([...existing.dependencyKinds, ...declaration.kinds])];
+        continue;
+      }
+      let definition;
+      try { definition = metadata ? JSON.parse(metadata.source) : null; } catch { definition = null; }
+      const record = { id: `package:npm:${identity}`, manager: 'npm', name, root, opaque: !owned, requested: declaration.requested, version: typeof definition?.version === 'string' ? definition.version : null, dependencyKinds: declaration.kinds, manifest, declarations: [declared], evidence: [{ path: input.path, hash: input.hash }], entryPoints: [], symbolCoverage: 'unsupported', metadata: metadata ? { path: metadata.path, hash: metadata.hash } : null };
+      packages.push(record); byRoot.set(identity, record);
+      if (!definition) { diagnostics.push({ code: 'NPM_INTERFACE_UNAVAILABLE', path: manifest, message: `${name}: installed public-interface metadata is unavailable.` }); continue; }
+      function targets(value) {
+        const result = []; const pending = [{ value, conditions: [] }];
+        while (pending.length && result.length < 512) {
+          signal?.throwIfAborted();
+          const entry = pending.pop();
+          if (typeof entry.value === 'string') result.push({ target: entry.value, conditions: entry.conditions });
+          else if (entry.conditions.length < 32 && entry.value && typeof entry.value === 'object') {
+            const children = Object.entries(entry.value);
+            for (let index = children.length - 1; index >= 0; index--) {
+              const [condition, child] = children[index];
+              pending.push({ value: child, conditions: [...entry.conditions, Array.isArray(entry.value) ? `fallback:${condition}` : condition] });
+            }
+          }
+        }
+        if (pending.length) diagnostics.push({ code: 'NPM_EXPORTS_PARTIAL', path: metadata.path, message: `${name}: the public export declaration exceeds inspection limits.` });
+        return result;
+      }
+      const exported = definition.exports;
+      const definitions = exported == null ? [ ['.', { default: definition.main || './index.js', ...(definition.types || definition.typings ? { types: definition.types || definition.typings } : {}) }] ]
+        : typeof exported === 'object' && !Array.isArray(exported) && Object.keys(exported).some(key => key.startsWith('.')) ? Object.entries(exported) : [['.', exported]];
+      for (const [importPath, value] of definitions) for (const entry of targets(value)) {
+        if (importPath !== '.' && !importPath.startsWith('./')) continue;
+        const relative = entry.target.replace(/^\.\//u, '');
+        const publicPath = path.posix.join(record.root, relative);
+        const point = { importPath, target: entry.target, conditions: entry.conditions, file: canonical(relative) && canonical(publicPath) ? publicPath : null, symbols: [], coverage: 'unsupported' };
+        record.entryPoints.push(point);
+        if (entry.target.includes('*') || !point.file || !/\.(?:[cm]?js|jsx|tsx?|vue)$/u.test(point.file)) continue;
+        const file = await read(point.file, { indexed: Boolean(known.has(point.file)) });
+        if (file) entries.push({ record, point, file });
+      }
+    }
+  }
+  const projectIndexes = new Map(indexedFiles.map(file => [file.path, file]));
+  const candidates = [...new Map(entries.filter(entry => projectIndexes.get(entry.file.path)?.hash !== entry.file.hash).map(entry => [entry.file.path, { path: entry.file.path, hash: entry.file.hash, mode: 0o100644, publicEntry: true }])).values()];
+  const result = candidates.length ? await extractCodeIndexes({ indexers: ['javascript'], files: candidates, projectRoot, signal }) : { contributions: [], diagnostics: [] };
+  diagnostics.push(...result.diagnostics);
+  const indexed = new Map([...projectIndexes, ...result.contributions.flatMap(contribution => contribution.files.map(file => [file.path, file]))]);
+  function publicSurface(filePath, visited = new Set()) {
+    const contribution = indexed.get(filePath);
+    if (!contribution || visited.has(filePath) || visited.size >= 32) return [];
+    const branch = new Set([...visited, filePath]);
+    const surface = [...(contribution.functions || []), ...(contribution.symbols || [])].filter(symbol => symbol.visibility === 'public').map(symbol => ({ ...symbol, sourceFile: filePath, sourceHash: contribution.hash, sourceName: symbol.name, sourceQualifiedName: symbol.qualifiedName }));
+    // Follow only already indexed project source. External packages remain
+    // opaque: neither their internals nor their transitive dependencies are read.
+    if (known.has(filePath)) for (const reference of contribution.dependencies || []) {
+      if (reference.kind !== 're-export' || !reference.specifier?.startsWith('.') || !reference.exports?.length) continue;
+      const base = path.posix.normalize(path.posix.join(path.posix.dirname(filePath), reference.specifier));
+      const target = [base, ...['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue'].map(extension => base + extension), ...['.js', '.ts', '.tsx', '.jsx'].map(extension => base + '/index' + extension)].find(candidate => known.has(candidate) && indexed.has(candidate));
+      if (!target) continue;
+      const available = publicSurface(target, branch);
+      for (const exposure of reference.exports) for (const symbol of available) {
+        const exported = symbol.exportName || symbol.name;
+        if (exposure.name === '*' ? exported === 'default' : exposure.name !== exported) continue;
+        const name = exposure.name === '*' ? symbol.name : exposure.alias;
+        surface.push({ ...symbol, name, qualifiedName: name, exportName: name });
+      }
+    }
+    const names = new Map();
+    for (const symbol of surface) {
+      const name = symbol.exportName || symbol.qualifiedName || symbol.name;
+      const previous = names.get(name);
+      if (!names.has(name)) names.set(name, [symbol]);
+      else if (!previous || previous[0].sourceFile !== symbol.sourceFile) names.set(name, null);
+      else if (!previous.some(entry => entry.start?.line === symbol.start?.line && entry.start?.column === symbol.start?.column)) previous.push(symbol);
+    }
+    return [...names.values()].filter(Boolean).flat();
+  }
+  for (const { record, point, file } of entries) {
+    const contribution = indexed.get(file.path);
+    if (!contribution) continue;
+    point.hash = file.hash; point.coverage = 'partial'; record.symbolCoverage = 'partial';
+    point.symbols = publicSurface(file.path);
+  }
+  return { packages, inputs: [...new Map(inputs.map(input => [input.path, input])).values()], diagnostics };
+}
+
+// Metadata and entry files live outside Git's inventory. Recheck those exact
+// inputs before publishing, including ancestor links; a race retains the index.
+export async function recheckNpmInputs(projectRoot, inputs, signal) {
+  for (const input of inputs) {
+    signal?.throwIfAborted();
+    try {
+      const parts = input.path.split('/');
+      for (let index = 0; index < parts.length; index++) if ((await lstat(path.join(projectRoot, ...parts.slice(0, index + 1)))).isSymbolicLink()) throw new Error('Symbolic link');
+      if (sha256(await readFile(path.join(projectRoot, input.path), { signal })) !== input.hash) throw new Error('Content changed');
+    } catch (error) {
+      signal?.throwIfAborted();
+      throw new Error(`Public package interface changed during architecture analysis: ${input.path}`, { cause: error });
+    }
+  }
+}

package/src/index/context.js

@@ -113,7 +113,7 @@ export async function contextForProjectPaths({ paths, projectRoot, stackPackages
     '',
     '## Relevant subsystems',
     '',
-    ...(['missing', 'empty'].includes(program.subsystemMap?.status) ? ['The subsystem map needs authoring. Before implementation, create genesis/subsystems.md from source, schema, and existing Program; preserve existing explanations and do not infer ownership from folders.'] : []),
+    ...(['missing', 'empty'].includes(program.subsystemMap?.status) ? ['The subsystem map needs authoring. Before implementation, create genesis/subsystems.md from source, schema, and existing Program; preserve existing explanations and require explicit directory roots and Program membership.'] : []),
     ...((program.subsystemMap?.subsystems || []).filter((entry) => targets.includes('') || modules.some((module) => module.subsystem === entry.id)).map((entry) => JSON.stringify(entry, null, 2))),
     '',
     '## Relevant Program',