@rahmantech/knl-view 0.2.0 → 0.3.0

package/README.md

@@ -398,7 +398,7 @@ Each file also defines **symbol nodes**, extracted from the same parse:
   per source file that has symbols; override the location with `labelDir`
   in the project config. Labels are regenerated and pruned on every sync.
 
-#### Supported Languages (v0.2.0)
+#### Supported Languages (v0.3.0)
 
 Tree-sitter WASM grammars run in-memory within Node.js without requiring host compilers:
 
@@ -443,6 +443,22 @@ record with a normal save and relinks its edges. Sync reports
 never silent. The read-only HTTP endpoint answers the same queries:
 `GET /api/sources/trace?target=<id>&direction=in|out|both&hops=N`.
 
+### External Modules Graph (On-Demand Module Boundary)
+
+AI agents can parse, index, and trace third-party dependencies on-demand into dedicated global AnchorDB models (`modules-npm`, `modules-go`, `modules-cargo`, `modules-pypi`) without polluting the local project graph or re-syncing across projects:
+
+```sh
+# Build & sync external module graph on-demand
+knl-view modules build-graph npm::express
+knl-view modules build-graph go::github.com/gin-gonic/gin
+
+# Trace definitions and call hierarchy within the module
+knl-view modules trace npm::express Router --hops=1
+
+# List locally indexed modules in ~/.knlview/modules
+knl-view modules list
+```
+
 ### CLI Query
 
 ```sh

package/bin/knl-view.js

@@ -22,6 +22,17 @@ import {
 import { readProjectConfig, readGlobalConfig, projectSlug, anchordbClientOptions, resolveModel, resolveSettings, knlGlobalDir, globalConfigPath } from '../server/config.js'
 import { createAnchorWireClient, mirrorStillValid } from '../server/graph/anchordb_client.js'
 import { syncSourcesToAnchorDB, traceSources, purgeArchivedRecords } from '../server/graph/sources.js'
+import {
+  parseModuleSpecifier,
+  buildModuleGraph,
+  syncModuleToAnchorDB,
+  traceModuleSymbol
+} from '../server/graph/modules_builder.js'
+import {
+  readModulesCatalog,
+  defaultEcosystemModel,
+  detectProjectManifests
+} from '../server/graph/modules_catalog.js'
 import { readModelRegistry, registerModel, generateModelName, modelRegistryPath } from '../server/models_registry.js'
 import {
   latestRelease,
@@ -97,6 +108,11 @@ Commands:
                             "sources" model via the REST collector
   sources trace --target=<path>  File lineage over the sources graph
                             (--hops, --direction in|out|both)
+  modules build-graph <target>  Build & sync external module graph into global
+                            AnchorDB model (modules-<eco>) on-demand
+                            Target: <eco>::<module_name> (e.g. npm::express)
+  modules trace <target> [sym]  Trace calls/definitions for an external module/symbol
+  modules list [ecosystem]  List locally indexed modules from ~/.knlview/modules
   setup                   Bootstrap project in one command (scaffold base, skill, and models)
 
 Options:
@@ -112,6 +128,7 @@ Options:
                           (default: both; see README "Two-way lineage")
   --target <id>           Target node id for the subgraph query
   --hops <number>         Graph trace hop radius (default: 2)
+  --force                 Rebuild external module graph even if already indexed
   --init                  Scaffold a new base via the wizard (does not start the server)
   --structure <layout>    Layout for non-interactive --init:
                           standard | empty | custom (default: standard)
@@ -146,6 +163,7 @@ try {
       target: { type: 'string' },
       direction: { type: 'string' },
       hops: { type: 'string', default: '2' },
+      force: { type: 'boolean', default: false },
       init: { type: 'boolean', default: false },
       structure: { type: 'string', default: 'standard' },
       folders: { type: 'string', default: '' },
@@ -245,6 +263,18 @@ if (sourcesSub) {
   process.exit(0)
 }
 
+// The "modules" command: on-demand external boundary graph in global AnchorDB
+// modules models (modules-npm, modules-go, modules-cargo, modules-pypi).
+const modulesSub = positionals?.[0] === 'modules' ? positionals?.[1] : null
+if (modulesSub) {
+  try {
+    await runModulesCommand(modulesSub, positionals?.slice(2), { values, settings })
+  } catch (err) {
+    fail(`Modules command failed: ${err.message}`)
+  }
+  process.exit(0)
+}
+
 // Register the project's whole models map to the global registry (updating
 // path/timestamp when this project owns them) and warn about names claimed
 // by other projects. This local registration needs no server connection.
@@ -1247,6 +1277,132 @@ async function runSourcesCollector(base, model, { quiet }) {
   }
 }
 
+// The "modules" subcommands: on-demand external boundary graph in global
+// AnchorDB modules models (modules-npm, modules-go, modules-cargo, modules-pypi).
+async function runModulesCommand(sub, args, { values, settings }) {
+  if (sub === 'list') {
+    const ecoFilter = args?.[0]?.toLowerCase()
+    const ecosystems = ecoFilter ? [ecoFilter] : ['npm', 'go', 'cargo', 'pypi']
+    const all = {}
+    for (const eco of ecosystems) {
+      all[eco] = await readModulesCatalog(eco)
+    }
+    process.stdout.write(JSON.stringify(all, null, 2) + '\n')
+    return
+  }
+
+  if (sub === 'build-graph' || sub === 'build') {
+    const target = args?.[0] || values.target
+    if (!target) {
+      fail('Target is required:\n  knl-view modules build-graph <ecosystem>::<module_name> [--force]')
+    }
+    const parsed = parseModuleSpecifier(target)
+    if (!parsed) {
+      fail(`Invalid module target "${target}".\nExpected format: <ecosystem>::<module_name> (e.g. npm::express, go::github.com/gin-gonic/gin)`)
+    }
+    const { ecosystem, moduleName } = parsed
+
+    if (!settings.anchordb) {
+      fail('External modules graphs live in AnchorDB, which is not configured.\n' +
+        'Run "knl-view install anchordb" first (optional layer).')
+    }
+
+    const model = defaultEcosystemModel(ecosystem)
+    const base = anchordbClientOptions(settings.anchordb)
+
+    if (!values.force) {
+      const catalog = await readModulesCatalog(ecosystem)
+      const manifestVersions = await detectProjectManifests(process.cwd())
+      const expectedVersion = manifestVersions[ecosystem]?.[moduleName]
+      if (expectedVersion) {
+        const key = `${moduleName}@${expectedVersion}`
+        if (catalog[key]?.syncedAt) {
+          process.stdout.write(`module ${ecosystem}::${key} is already synced in model ${model} (${catalog[key].symbols.length} symbols). Use --force to rebuild.\n`)
+          return
+        }
+      }
+    }
+
+    process.stdout.write(`building graph for ${ecosystem}::${moduleName} ...\n`)
+    const moduleGraph = await buildModuleGraph(ecosystem, moduleName, { projectRoot: process.cwd() })
+
+    const client = await createAnchorWireClient({ ...base, model })
+    try {
+      const result = await syncModuleToAnchorDB(client, moduleGraph)
+      process.stdout.write(`module synced: ${ecosystem}::${moduleGraph.name}@${moduleGraph.version} -> model "${model}" (${result.symbols} symbols, ${result.edges} edges, +${result.linked} linked)\n`)
+    } finally {
+      client.close()
+    }
+    return
+  }
+
+  if (sub === 'trace') {
+    const rawTarget = args?.[0] || values.target
+    if (!rawTarget) {
+      fail('Target is required:\n  knl-view modules trace <ecosystem>::<module_name> [symbol] [--hops=2] [--direction=in|out|both]')
+    }
+
+    let ecosystem, symbolId
+    if (rawTarget.startsWith('ext:')) {
+      const m = rawTarget.match(/^ext:([a-z]+)\//)
+      if (!m) fail(`Cannot determine ecosystem from node ID "${rawTarget}".`)
+      ecosystem = m[1]
+      symbolId = rawTarget
+    } else {
+      const parsed = parseModuleSpecifier(rawTarget)
+      if (!parsed) {
+        fail(`Invalid module target "${rawTarget}".\nExpected format: <ecosystem>::<module_name> [symbol]`)
+      }
+      ecosystem = parsed.ecosystem
+      const catalog = await readModulesCatalog(ecosystem)
+      const subSymbol = args?.[1]
+      const entryKey = Object.keys(catalog).find((k) => k.startsWith(parsed.moduleName + '@') || k === parsed.moduleName)
+      if (!entryKey) {
+        fail(`Module "${rawTarget}" is not indexed in catalog ~/.knlview/modules/${ecosystem}.json.\nRun "knl-view modules build-graph ${rawTarget}" first.`)
+      }
+      const entry = catalog[entryKey]
+      symbolId = subSymbol ? `${entry.nodeId}#${subSymbol}` : entry.nodeId
+    }
+
+    if (!settings.anchordb) {
+      fail('The modules graph lives in AnchorDB, which is not configured.\n' +
+        'Run "knl-view install anchordb" first.')
+    }
+
+    const model = defaultEcosystemModel(ecosystem)
+    const base = anchordbClientOptions(settings.anchordb)
+    const client = await createAnchorWireClient({ ...base, model })
+    try {
+      let direction = 'both'
+      if (values.direction !== undefined) {
+        if (!['in', 'out', 'both'].includes(values.direction)) {
+          fail(`--direction must be in, out, or both, got "${values.direction}".`)
+        }
+        direction = values.direction
+      }
+      const hops = Number.parseInt(values.hops || '2', 10)
+      const maxHops = Number.isInteger(hops) && hops > 0 ? hops : 2
+      const results = await traceModuleSymbol(client, symbolId, { direction, maxHops })
+      process.stdout.write(JSON.stringify({
+        center: symbolId,
+        model,
+        direction,
+        maxHops,
+        trace: results
+      }, null, 2) + '\n')
+    } finally {
+      client.close()
+    }
+    return
+  }
+
+  fail('Unknown modules subcommand.\n' +
+    'Usage:\n' +
+    '  knl-view modules build-graph <ecosystem>::<module_name> [--force]\n' +
+    '  knl-view modules trace <ecosystem>::<module_name> [symbol] [--hops=2] [--direction=in|out|both]\n' +
+    '  knl-view modules list [ecosystem]')
+}
+
 function fail(message) {
   process.stderr.write(`knl-view: ${message}\n`)
   process.exit(1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rahmantech/knl-view",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local viewer for .knowledges knowledge bases: a CLI and a web app, with an optional AnchorDB graph layer.",
   "type": "module",
   "license": "Apache-2.0",

package/server/graph/modules_builder.js

@@ -0,0 +1,290 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { GraphNode } from './model.js'
+import { SYNTAX_LANGUAGES, extractCode } from './syntax.js'
+import { desiredSourceEdgeKeys } from './sources.js'
+import {
+  resolveModuleLocation,
+  formatExternalPackageNodeId,
+  formatExternalSymbolNodeId,
+  defaultEcosystemModel,
+  updateModulesCatalog
+} from './modules_catalog.js'
+
+const MODULE_DEFAULT_IGNORES = [
+  'node_modules',
+  '.git',
+  '.github',
+  'test',
+  'tests',
+  '__tests__',
+  'docs',
+  'doc',
+  'example',
+  'examples',
+  'fixtures',
+  'coverage'
+]
+
+/**
+ * Scan source files of an external module directory.
+ */
+export async function scanModuleFiles(moduleDir, ecosystem) {
+  const files = {}
+  const walk = async (dirAbs, rel) => {
+    let entries
+    try {
+      entries = await fs.readdir(dirAbs, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name
+      if (entry.isDirectory()) {
+        if (MODULE_DEFAULT_IGNORES.includes(entry.name.toLowerCase())) continue
+        await walk(path.join(dirAbs, entry.name), childRel)
+        continue
+      }
+      if (!entry.isFile()) continue
+      const ext = path.extname(entry.name).toLowerCase()
+      if (!SYNTAX_LANGUAGES[ext]) continue
+      if (ecosystem === 'go' && entry.name.endsWith('_test.go')) continue
+      if (ecosystem === 'pypi' && entry.name.startsWith('test_')) continue
+      files[childRel] = path.join(dirAbs, entry.name)
+    }
+  }
+  await walk(moduleDir, '')
+  return files
+}
+
+/**
+ * Parse an eco::name string into components: { ecosystem, moduleName }
+ */
+export function parseModuleSpecifier(target) {
+  if (!target || typeof target !== 'string') return null
+  const idx = target.indexOf('::')
+  if (idx <= 0) return null
+  const ecosystem = target.slice(0, idx).toLowerCase()
+  const moduleName = target.slice(idx + 2)
+  if (!moduleName) return null
+  return { ecosystem, moduleName }
+}
+
+/**
+ * Build graph for an external module from disk using Tree-Sitter.
+ */
+export async function buildModuleGraph(ecosystem, moduleName, options = {}) {
+  const resolved = options.location
+    ? { location: options.location, version: options.version || '0.0.0', name: moduleName, ecosystem }
+    : await resolveModuleLocation(ecosystem, moduleName, options)
+
+  if (!resolved || !resolved.location) {
+    throw new Error(`Could not resolve module directory for ${ecosystem}::${moduleName} on disk. Ensure it is installed.`)
+  }
+
+  const { location, version } = resolved
+  const model = defaultEcosystemModel(ecosystem)
+  const moduleNodeId = formatExternalPackageNodeId(ecosystem, moduleName, version)
+
+  const files = await scanModuleFiles(location, ecosystem)
+  const symbolNodes = []
+  const symbolNamesSet = new Set()
+  const edges = []
+  const symbolIndex = new Map() // name -> [id, ...]
+  const fileSymbolsMap = new Map()
+
+  for (const [rel, abs] of Object.entries(files)) {
+    const ext = path.extname(rel).toLowerCase()
+    let content
+    try {
+      content = await fs.readFile(abs, 'utf8')
+    } catch {
+      continue
+    }
+
+    let extracted
+    try {
+      extracted = await extractCode(ext, content)
+    } catch {
+      continue
+    }
+
+    const nameCounts = new Map()
+    for (const sym of extracted.symbols || []) {
+      nameCounts.set(sym.name, (nameCounts.get(sym.name) || 0) + 1)
+    }
+
+    const currentFileSymbols = []
+    for (const sym of extracted.symbols || []) {
+      const symId = nameCounts.get(sym.name) > 1
+        ? formatExternalSymbolNodeId(ecosystem, moduleName, version, `${sym.name}@${sym.line}`)
+        : formatExternalSymbolNodeId(ecosystem, moduleName, version, sym.name)
+
+      symbolNamesSet.add(sym.name)
+      currentFileSymbols.push({ ...sym, id: symId })
+      symbolIndex.set(sym.name, [...(symbolIndex.get(sym.name) || []), symId])
+
+      edges.push({ from: moduleNodeId, to: symId, type: 'defines' })
+      symbolNodes.push(new GraphNode({
+        id: symId,
+        title: sym.name,
+        type: 'symbol',
+        metadata: { kind: sym.kind, line: sym.line }
+      }))
+    }
+
+    fileSymbolsMap.set(rel, { symbols: currentFileSymbols, calls: extracted.calls || [] })
+  }
+
+  // Internal calls between symbols inside the module
+  for (const [, { symbols, calls }] of fileSymbolsMap.entries()) {
+    for (const call of calls) {
+      let owner = null
+      for (const sym of symbols) {
+        const start = sym.line - 1
+        const end = start + sym.lines
+        if (call.row >= start && call.row < end) {
+          if (!owner || sym.lines < owner.lines) owner = sym
+        }
+      }
+      if (!owner) continue
+      const targetMatches = symbolIndex.get(call.name) || []
+      if (targetMatches.length === 1 && targetMatches[0] !== owner.id) {
+        edges.push({ from: owner.id, to: targetMatches[0], type: 'calls' })
+      }
+    }
+  }
+
+  const moduleNode = new GraphNode({
+    id: moduleNodeId,
+    title: `${moduleName}@${version}`,
+    type: 'module',
+    metadata: { ecosystem, name: moduleName, version }
+  })
+
+  return {
+    moduleNode,
+    symbolNodes,
+    edges,
+    symbols: [...symbolNamesSet].sort(),
+    name: moduleName,
+    version,
+    ecosystem,
+    model,
+    location
+  }
+}
+
+/**
+ * Sync the constructed module graph to AnchorDB in model modules-<ecosystem>.
+ */
+export async function syncModuleToAnchorDB(client, moduleGraph, options = {}) {
+  if (!client || !moduleGraph) return { linked: 0, saved: 0, failed: 0 }
+
+  const desired = desiredSourceEdgeKeys(moduleGraph.edges)
+  let linked = 0
+  let failed = 0
+
+  for (const key of desired) {
+    const [from, type, to] = key.split('\0')
+    try {
+      await client.link(from, type, to, 1.0)
+      linked += 1
+    } catch {
+      failed += 1
+    }
+  }
+
+  const pending = [
+    { name: moduleGraph.moduleNode.id, props: { ...moduleGraph.moduleNode.metadata, tombstone: 0 } },
+    ...moduleGraph.symbolNodes.map((s) => ({ name: s.id, props: { ...s.metadata, tombstone: 0 } }))
+  ]
+
+  let saved = 0
+  if (typeof client.saveBatch === 'function') {
+    try {
+      await client.saveBatch(pending)
+      saved = pending.length
+    } catch {
+      for (const item of pending) {
+        try {
+          await client.saveWithID(item.name, item.props)
+          saved += 1
+        } catch {
+          failed += 1
+        }
+      }
+    }
+  } else {
+    for (const item of pending) {
+      try {
+        await client.saveWithID(item.name, item.props)
+        saved += 1
+      } catch {
+        failed += 1
+      }
+    }
+  }
+
+  await updateModulesCatalog(moduleGraph.ecosystem, {
+    [`${moduleGraph.name}@${moduleGraph.version}`]: {
+      name: moduleGraph.name,
+      version: moduleGraph.version,
+      ecosystem: moduleGraph.ecosystem,
+      model: moduleGraph.model,
+      nodeId: moduleGraph.moduleNode.id,
+      symbols: moduleGraph.symbols
+    }
+  }, options)
+
+  return {
+    linked,
+    saved,
+    failed,
+    symbols: moduleGraph.symbols.length,
+    edges: moduleGraph.edges.length,
+    model: moduleGraph.model
+  }
+}
+
+/**
+ * Trace lineage for a module or symbol in its ecosystem model.
+ */
+export async function traceModuleSymbol(client, targetId, { direction = 'both', maxHops = 2 } = {}) {
+  const forwardRelations = targetId.includes('#') ? ['calls'] : ['defines']
+  const backwardRelations = targetId.includes('#') ? ['called_by', 'defined_in'] : []
+
+  const rels = []
+  if (direction === 'out' || direction === 'both') rels.push(...forwardRelations)
+  if (direction === 'in' || direction === 'both') rels.push(...backwardRelations)
+
+  const visited = new Map() // id -> hop
+  visited.set(targetId, 0)
+  let frontier = [targetId]
+
+  for (let hop = 1; hop <= maxHops && frontier.length; hop++) {
+    const nextFrontier = []
+    for (const current of frontier) {
+      for (const rel of rels) {
+        let rows = []
+        try {
+          rows = await client.causalChain([current], rel, 100)
+        } catch {
+          continue
+        }
+        for (const r of rows || []) {
+          if (!r?.word || visited.has(r.word)) continue
+          visited.set(r.word, hop)
+          nextFrontier.push(r.word)
+        }
+      }
+    }
+    frontier = nextFrontier
+  }
+
+  const results = []
+  for (const [id, hop] of visited.entries()) {
+    if (id !== targetId) results.push({ id, hop })
+  }
+  return results.sort((a, b) => a.hop - b.hop || a.id.localeCompare(b.id))
+}

package/server/graph/modules_catalog.js

@@ -0,0 +1,288 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { knlGlobalDir } from '../config.js'
+
+/**
+ * Returns the path to the global modules catalog directory (~/.knlview/modules).
+ */
+export function modulesCatalogDir(home = null, options = {}) {
+  const base = knlGlobalDir(home, options)
+  return path.join(base, 'modules')
+}
+
+/**
+ * Default global AnchorDB model name for an ecosystem.
+ */
+export function defaultEcosystemModel(ecosystem) {
+  return `modules-${ecosystem}`
+}
+
+export function formatModuleKey(pkgName, version) {
+  return `${pkgName}@${version}`
+}
+
+export function formatExternalPackageNodeId(ecosystem, pkgName, version) {
+  return `ext:${ecosystem}/${pkgName}@${version}`
+}
+
+export function formatExternalSymbolNodeId(ecosystem, pkgName, version, symbol) {
+  return `ext:${ecosystem}/${pkgName}@${version}#${symbol}`
+}
+
+/**
+ * Read the catalog for a specific ecosystem ('npm', 'go', 'cargo', 'pypi').
+ */
+export async function readModulesCatalog(ecosystem, options = {}) {
+  const dir = modulesCatalogDir(options.home, options)
+  const file = path.join(dir, `${ecosystem}.json`)
+  try {
+    const raw = await fs.readFile(file, 'utf8')
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Check if a module version is already indexed in the catalog.
+ */
+export async function isModuleSynced(ecosystem, pkgName, version, options = {}) {
+  const catalog = await readModulesCatalog(ecosystem, options)
+  const key = formatModuleKey(pkgName, version)
+  return Boolean(catalog[key]?.syncedAt)
+}
+
+/**
+ * Record discovered modules and symbols to ~/.knlview/modules/<ecosystem>.json.
+ */
+export async function updateModulesCatalog(ecosystem, entries, options = {}) {
+  if (!entries || !Object.keys(entries).length) return
+  const dir = modulesCatalogDir(options.home, options)
+  const file = path.join(dir, `${ecosystem}.json`)
+  try {
+    await fs.mkdir(dir, { recursive: true })
+    const existing = await readModulesCatalog(ecosystem, options)
+    for (const [key, item] of Object.entries(entries)) {
+      const prev = existing[key] || {
+        name: item.name,
+        version: item.version,
+        ecosystem,
+        model: item.model || defaultEcosystemModel(ecosystem),
+        nodeId: item.nodeId || formatExternalPackageNodeId(ecosystem, item.name, item.version),
+        symbols: []
+      }
+      const symSet = new Set([...(prev.symbols || []), ...(item.symbols || [])])
+      existing[key] = {
+        name: item.name,
+        version: item.version,
+        ecosystem,
+        model: item.model || prev.model || defaultEcosystemModel(ecosystem),
+        nodeId: item.nodeId || prev.nodeId || formatExternalPackageNodeId(ecosystem, item.name, item.version),
+        symbols: [...symSet].sort(),
+        syncedAt: item.syncedAt || prev.syncedAt || Date.now()
+      }
+    }
+    await fs.writeFile(file, JSON.stringify(existing, null, 2) + '\n', 'utf8')
+  } catch {
+    // Fail gracefully: catalog is an informational index, never fatal.
+  }
+}
+
+/**
+ * Detect project dependency versions from on-disk manifests:
+ * package.json, go.mod, Cargo.toml, requirements.txt.
+ */
+export async function detectProjectManifests(rootAbs) {
+  const manifests = {
+    npm: {},
+    go: {},
+    cargo: {},
+    pypi: {}
+  }
+
+  // 1. npm (package.json)
+  try {
+    const pkgRaw = await fs.readFile(path.join(rootAbs, 'package.json'), 'utf8')
+    const pkg = JSON.parse(pkgRaw)
+    const all = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies }
+    for (const [name, ver] of Object.entries(all)) {
+      if (typeof ver === 'string') {
+        manifests.npm[name] = ver.replace(/^[\^~>=<]/, '').trim() || 'latest'
+      }
+    }
+  } catch {}
+
+  // 2. Go (go.mod)
+  try {
+    const text = await fs.readFile(path.join(rootAbs, 'go.mod'), 'utf8')
+    const singleMatch = text.matchAll(/^require\s+([^\s()]+)\s+([^\s()]+)/gm)
+    for (const m of singleMatch) manifests.go[m[1]] = m[2]
+    const blockMatch = text.match(/require\s*\(([\s\S]*?)\)/m)
+    if (blockMatch) {
+      for (const line of blockMatch[1].split('\n')) {
+        const parts = line.trim().split(/\s+/)
+        if (parts.length >= 2 && !parts[0].startsWith('//')) {
+          manifests.go[parts[0]] = parts[1]
+        }
+      }
+    }
+  } catch {}
+
+  // 3. Rust (Cargo.toml)
+  try {
+    const text = await fs.readFile(path.join(rootAbs, 'Cargo.toml'), 'utf8')
+    let inDeps = false
+    for (const line of text.split('\n')) {
+      const trimmed = line.trim()
+      if (
+        trimmed.startsWith('[dependencies]') ||
+        trimmed.startsWith('[dev-dependencies]') ||
+        trimmed.startsWith('[build-dependencies]')
+      ) {
+        inDeps = true
+        continue
+      }
+      if (trimmed.startsWith('[')) {
+        inDeps = false
+        continue
+      }
+      if (inDeps && trimmed && !trimmed.startsWith('#')) {
+        const eqIdx = trimmed.indexOf('=')
+        if (eqIdx > 0) {
+          const name = trimmed.slice(0, eqIdx).trim()
+          const val = trimmed.slice(eqIdx + 1).trim()
+          let ver = 'unknown'
+          const strMatch = val.match(/^"([^"]+)"/)
+          if (strMatch) ver = strMatch[1]
+          const objMatch = val.match(/version\s*=\s*"([^"]+)"/)
+          if (objMatch) ver = objMatch[1]
+          manifests.cargo[name] = ver
+        }
+      }
+    }
+  } catch {}
+
+  // 4. Python (requirements.txt)
+  try {
+    const reqText = await fs.readFile(path.join(rootAbs, 'requirements.txt'), 'utf8')
+    for (const line of reqText.split('\n')) {
+      const trimmed = line.trim()
+      if (!trimmed || trimmed.startsWith('#')) continue
+      const m = trimmed.match(/^([a-zA-Z0-9_.-]+)(?:[=<>~!\s]*([a-zA-Z0-9_.-]+))?/)
+      if (m) manifests.pypi[m[1].toLowerCase()] = m[2] || 'unknown'
+    }
+  } catch {}
+
+  return manifests
+}
+
+/**
+ * Resolve the directory of an installed external module on disk.
+ * Supports npm (node_modules), Go (GOPATH/pkg/mod or vendor), Cargo (cargo cache or vendor),
+ * and Python (venv site-packages).
+ */
+export async function resolveModuleLocation(ecosystem, moduleName, options = {}) {
+  const root = path.resolve(options.projectRoot || process.cwd())
+  const manifests = options.manifests || await detectProjectManifests(root)
+
+  if (ecosystem === 'npm') {
+    // 1. Check node_modules in projectRoot and walk up if necessary
+    let curr = root
+    let foundDir = null
+    while (true) {
+      const candidate = path.join(curr, 'node_modules', moduleName)
+      try {
+        const stat = await fs.stat(candidate)
+        if (stat.isDirectory()) {
+          foundDir = candidate
+          break
+        }
+      } catch {}
+      const parent = path.dirname(curr)
+      if (parent === curr) break
+      curr = parent
+    }
+
+    let version = manifests.npm[moduleName] || 'unknown'
+    if (foundDir) {
+      try {
+        const pkgText = await fs.readFile(path.join(foundDir, 'package.json'), 'utf8')
+        const pkg = JSON.parse(pkgText)
+        if (pkg.version) version = pkg.version
+      } catch {}
+      return { location: foundDir, version, name: moduleName, ecosystem }
+    }
+  } else if (ecosystem === 'go') {
+    // 1. Check local vendor
+    const vendorDir = path.join(root, 'vendor', moduleName)
+    try {
+      const stat = await fs.stat(vendorDir)
+      if (stat.isDirectory()) {
+        return { location: vendorDir, version: manifests.go[moduleName] || 'vendor', name: moduleName, ecosystem }
+      }
+    } catch {}
+
+    // 2. Check GOPATH
+    const gopath = process.env.GOPATH || path.join(options.home || process.env.HOME || '', 'go')
+    const version = manifests.go[moduleName]
+    if (version) {
+      const modDir = path.join(gopath, 'pkg', 'mod', `${moduleName}@${version}`)
+      try {
+        const stat = await fs.stat(modDir)
+        if (stat.isDirectory()) {
+          return { location: modDir, version, name: moduleName, ecosystem }
+        }
+      } catch {}
+    }
+  } else if (ecosystem === 'cargo') {
+    // 1. Check local vendor
+    const vendorDir = path.join(root, 'vendor', moduleName)
+    try {
+      const stat = await fs.stat(vendorDir)
+      if (stat.isDirectory()) {
+        return { location: vendorDir, version: manifests.cargo[moduleName] || 'vendor', name: moduleName, ecosystem }
+      }
+    } catch {}
+
+    // 2. Check cargo registry cache (~/.cargo/registry/src)
+    const cargoHome = process.env.CARGO_HOME || path.join(options.home || process.env.HOME || '', '.cargo')
+    const regSrc = path.join(cargoHome, 'registry', 'src')
+    const version = manifests.cargo[moduleName]
+    try {
+      const registries = await fs.readdir(regSrc)
+      for (const reg of registries) {
+        const targetPrefix = version ? `${moduleName}-${version}` : `${moduleName}-`
+        const regDir = path.join(regSrc, reg)
+        const entries = await fs.readdir(regDir)
+        const match = entries.find((e) => version ? e === targetPrefix : e.startsWith(targetPrefix))
+        if (match) {
+          const location = path.join(regDir, match)
+          const matchedVersion = version || match.slice(moduleName.length + 1)
+          return { location, version: matchedVersion, name: moduleName, ecosystem }
+        }
+      }
+    } catch {}
+  } else if (ecosystem === 'pypi') {
+    const version = manifests.pypi[moduleName.toLowerCase()] || 'unknown'
+    // 1. Check .venv and venv site-packages
+    const venvDirs = ['.venv', 'venv']
+    for (const venv of venvDirs) {
+      const libDir = path.join(root, venv, 'lib')
+      try {
+        const pyDirs = await fs.readdir(libDir)
+        for (const py of pyDirs) {
+          const sp = path.join(libDir, py, 'site-packages', moduleName)
+          try {
+            const stat = await fs.stat(sp)
+            if (stat.isDirectory()) {
+              return { location: sp, version, name: moduleName, ecosystem }
+            }
+          } catch {}
+        }
+      } catch {}
+    }
+  }
+
+  return null
+}

package/server/graph/syntax.js

@@ -78,12 +78,14 @@ function firstDescendant(node, type) {
 function specsFromTree(grammar, tree) {
   const specs = []
   const names = []
+  const bindings = []
   const visit = (node) => {
     if (grammar === 'javascript' || grammar === 'typescript' || grammar === 'tsx') {
       if (node.type === 'import_statement' || node.type === 'export_statement') {
         const source = node.childForFieldName('source')
         const fragment = source && firstDescendant(source, 'string_fragment')
-        if (fragment) specs.push(fragment.text)
+        const specText = fragment ? fragment.text : null
+        if (specText) specs.push(specText)
         // Local binding names a qualified call may be addressed through:
         // the default import, the namespace alias, and each named import.
         for (let i = 0; i < node.childCount; i++) {
@@ -91,17 +93,25 @@ function specsFromTree(grammar, tree) {
           if (clause.type !== 'import_clause') continue
           for (let j = 0; j < clause.childCount; j++) {
             const part = clause.child(j)
-            if (part.type === 'identifier') names.push(part.text)
-            else if (part.type === 'namespace_import') {
+            if (part.type === 'identifier') {
+              names.push(part.text)
+              if (specText) bindings.push({ name: part.text, spec: specText })
+            } else if (part.type === 'namespace_import') {
               for (let k = 0; k < part.childCount; k++) {
-                if (part.child(k).type === 'identifier') names.push(part.child(k).text)
+                if (part.child(k).type === 'identifier') {
+                  names.push(part.child(k).text)
+                  if (specText) bindings.push({ name: part.child(k).text, spec: specText })
+                }
               }
             } else if (part.type === 'named_imports') {
               for (let k = 0; k < part.childCount; k++) {
                 const specifier = part.child(k)
                 if (specifier.type !== 'import_specifier') continue
                 const alias = specifier.childForFieldName('alias') || specifier.childForFieldName('name')
-                if (alias) names.push(alias.text)
+                if (alias) {
+                  names.push(alias.text)
+                  if (specText) bindings.push({ name: alias.text, spec: specText })
+                }
               }
             }
           }
@@ -111,7 +121,8 @@ function specsFromTree(grammar, tree) {
         if (fn && (fn.text === 'require' || fn.text === 'import')) {
           const args = node.childForFieldName('arguments')
           const fragment = args && firstDescendant(args, 'string_fragment')
-          if (fragment) specs.push(fragment.text)
+          const specText = fragment ? fragment.text : null
+          if (specText) specs.push(specText)
           // `const x = require('y')` / `const x = await import('y')`: the
           // declarator name is the binding: the visit starts above it, so
           // walk down from any enclosing declarator via field lookup here.
@@ -119,7 +130,10 @@ function specsFromTree(grammar, tree) {
           while (parent && parent.type === 'await_expression') parent = parent.parent
           if (parent && parent.type === 'variable_declarator') {
             const name = parent.childForFieldName('name')
-            if (name) names.push(name.text)
+            if (name) {
+              names.push(name.text)
+              if (specText) bindings.push({ name: name.text, spec: specText })
+            }
           }
         }
       }
@@ -133,8 +147,9 @@ function specsFromTree(grammar, tree) {
           // The name a qualified call uses: the declared alias, or the last
           // path segment (Go's convention when no alias is given).
           const alias = node.childForFieldName('name')
-          if (alias) names.push(alias.text)
-          else names.push(path.slice(path.lastIndexOf('/') + 1))
+          const name = alias ? alias.text : path.slice(path.lastIndexOf('/') + 1)
+          names.push(name)
+          bindings.push({ name, spec: path })
         }
       }
     } else if (grammar === 'python') {
@@ -144,12 +159,18 @@ function specsFromTree(grammar, tree) {
           if (c.type === 'dotted_name') {
             specs.push(c.text)
             const firstId = c.child(0)
-            if (firstId) names.push(firstId.text)
+            if (firstId) {
+              names.push(firstId.text)
+              bindings.push({ name: firstId.text, spec: c.text })
+            }
           } else if (c.type === 'aliased_import') {
             const name = c.childForFieldName('name')
             const alias = c.childForFieldName('alias')
             if (name) specs.push(name.text)
-            if (alias) names.push(alias.text)
+            if (alias) {
+              names.push(alias.text)
+              bindings.push({ name: alias.text, spec: name ? name.text : alias.text })
+            }
           }
         }
       } else if (node.type === 'import_from_statement') {
@@ -167,10 +188,14 @@ function specsFromTree(grammar, tree) {
           if (c.type === 'dotted_name') {
             names.push(c.text)
             if (modText) specs.push(modText + '.' + c.text)
+            bindings.push({ name: c.text, spec: modText || c.text })
           } else if (c.type === 'aliased_import') {
             const name = c.childForFieldName('name')
             const alias = c.childForFieldName('alias')
-            if (alias) names.push(alias.text)
+            if (alias) {
+              names.push(alias.text)
+              bindings.push({ name: alias.text, spec: modText || (name ? name.text : alias.text) })
+            }
             if (name && modText) specs.push(modText + '.' + name.text)
           }
         }
@@ -182,6 +207,7 @@ function specsFromTree(grammar, tree) {
           if (name) {
             specs.push('./' + name.text)
             names.push(name.text)
+            bindings.push({ name: name.text, spec: './' + name.text })
           }
         }
       } else if (node.type === 'use_declaration') {
@@ -204,16 +230,27 @@ function specsFromTree(grammar, tree) {
             const aliasNode = n.childForFieldName('alias')
             const full = (prefix ? prefix + '::' : '') + (pathNode ? pathNode.text : '')
             specs.push(full)
-            if (aliasNode) names.push(aliasNode.text)
+            const alias = aliasNode ? aliasNode.text : null
+            if (alias) {
+              names.push(alias)
+              const crateName = full.split('::')[0]
+              bindings.push({ name: alias, spec: crateName, full })
+            }
           } else if (n.type === 'scoped_identifier') {
             const full = (prefix ? prefix + '::' : '') + n.text
             specs.push(full)
             const name = n.childForFieldName('name')
-            if (name) names.push(name.text)
+            if (name) {
+              names.push(name.text)
+              const crateName = full.split('::')[0]
+              bindings.push({ name: name.text, spec: crateName, full })
+            }
           } else if (n.type === 'identifier') {
             const full = (prefix ? prefix + '::' : '') + n.text
             specs.push(full)
             names.push(n.text)
+            const crateName = full.split('::')[0]
+            bindings.push({ name: n.text, spec: crateName, full })
           }
         }
         extractRustUse(node.childForFieldName('argument'))
@@ -222,7 +259,7 @@ function specsFromTree(grammar, tree) {
     for (let i = 0; i < node.childCount; i++) visit(node.child(i))
   }
   visit(tree.rootNode)
-  return { specs, names }
+  return { specs, names, bindings }
 }
 
 /**
@@ -262,9 +299,9 @@ export async function extractCode(ext, content) {
   const parser = parserFor(grammar, lang)
   const tree = parser.parse(content)
   try {
-    const { specs: imports, names: importNames } = specsFromTree(grammar, tree)
+    const { specs: imports, names: importNames, bindings: importBindings } = specsFromTree(grammar, tree)
     const { symbols, calls } = structureFromTree(grammar, tree)
-    return { imports, importNames, symbols, calls }
+    return { imports, importNames, importBindings, symbols, calls }
   } finally {
     tree.delete()
   }

package/server/scaffold.js

@@ -366,6 +366,12 @@ file or symbol is tombstoned (attribute \`tombstone = 2\`) after its
 edges are unlinked; if it comes back, the tombstone lifts and the edges
 are relinked.
 
+External modules graph (third-party dependencies): stored in global AnchorDB
+models per ecosystem (\`modules-npm\`, \`modules-go\`, \`modules-cargo\`, \`modules-pypi\`)
+and cataloged in \`~/.knlview/modules/<eco>.json\`. Built on-demand via
+\`knl-view modules build-graph <eco>::<name>\`, avoiding polluting project models.
+Traceable via \`knl-view modules trace <eco>::<name> [symbol]\`.
+
 Decision history skill: recording architectural decisions is delegated
 to the separate decision-history skill (its decision block format is its
 own domain; this skill never writes decision blocks). If it is not
@@ -454,6 +460,10 @@ this.
 - Before renaming a symbol or moving it to another file: remember its
   record id contains the old name/path. Sync tombstones the stale record
   and creates the new one; trace by the new id afterwards.
+- Before reading raw third-party library source files:
+  run \`knl-view modules build-graph <eco>::<module>\` (e.g. \`npm::express\`, \`go::github.com/gin-gonic/gin\`)
+  to index it on-demand into global AnchorDB model \`modules-<eco>\`, then trace
+  its methods with \`knl-view modules trace <eco>::<module> [symbol]\` to save context tokens.
 - A new architectural decision: trigger the decision-history skill
   (install it first if missing; see "Decision history skill" above).
   The decision block format is that skill's domain; this skill never