@davidwells/extract-deps 0.0.3 → 0.0.5

package/examples/verify-basic.js

@@ -0,0 +1,43 @@
+// Basic verification of dependency graph
+const path = require('path')
+const { depGraph } = require('../src/dep-graph')
+
+const cjsFixture = path.resolve(__dirname, '../tests/fixtures/cjs-example/index.js')
+const esmFixture = path.resolve(__dirname, '../tests/fixtures/esm-fixture/index.js')
+
+console.log('Verifying CJS fixture...')
+try {
+  const graph = depGraph(cjsFixture)
+  console.log('✓ CJS fixture is valid - all imports resolve correctly')
+  console.log(`  Found ${graph.size} files in dependency graph\n`)
+} catch (error) {
+  console.error('✗ CJS fixture has errors:')
+  console.error(error.message)
+}
+
+console.log('Verifying ESM fixture...')
+try {
+  const graph = depGraph(esmFixture)
+  console.log('✓ ESM fixture is valid - all imports resolve correctly')
+  console.log(`  Found ${graph.size} files in dependency graph\n`)
+} catch (error) {
+  console.error('✗ ESM fixture has errors:')
+  console.error(error.message)
+}
+
+console.log('Verifying with throwOnFirstError option...')
+try {
+  depGraph(cjsFixture, { throwOnFirstError: true })
+  console.log('✓ Validation passed (would have thrown on first error)\n')
+} catch (error) {
+  console.error('✗ First error encountered:')
+  console.error(error.message)
+}
+
+console.log('Building graph without verification (faster)...')
+const graph = depGraph(cjsFixture, { verifyGraph: false })
+console.log(`✓ Graph built without verification - ${graph.size} files`)
+
+console.log('\nVerification only (no graph building)...')
+depGraph(cjsFixture, { buildGraph: false })
+console.log('✓ Verification passed (no graph returned)')

package/examples/verify-build-graph.js

@@ -0,0 +1,58 @@
+// Build and explore dependency graph
+const path = require('path')
+const { depGraph } = require('../src/dep-graph')
+
+const fixture = path.resolve(__dirname, '../tests/fixtures/cjs-deep-example/index.js')
+
+console.log('Building dependency graph...\n')
+
+const graph = depGraph(fixture)
+
+console.log('=== Dependency Graph ===\n')
+
+// Display the graph
+for (const [file, deps] of graph) {
+  const fileName = path.basename(file)
+  const fileDir = path.relative(__dirname, path.dirname(file))
+
+  console.log(`${fileName} (${fileDir})`)
+
+  if (deps.length === 0) {
+    console.log('  └─ (no dependencies - leaf node)\n')
+  } else {
+    deps.forEach((dep, idx) => {
+      const depName = path.basename(dep)
+      const isLast = idx === deps.length - 1
+      const prefix = isLast ? '  └─' : '  ├─'
+      console.log(`${prefix} ${depName}`)
+    })
+    console.log()
+  }
+}
+
+console.log(`\nTotal files: ${graph.size}`)
+
+// Find leaf nodes (files with no dependencies)
+const leafNodes = []
+for (const [file, deps] of graph) {
+  if (deps.length === 0) {
+    leafNodes.push(path.basename(file))
+  }
+}
+
+console.log(`Leaf nodes: ${leafNodes.join(', ')}`)
+
+// Find root nodes (files not depended on by others in the graph)
+const allDeps = new Set()
+for (const deps of graph.values()) {
+  deps.forEach(dep => allDeps.add(dep))
+}
+
+const rootNodes = []
+for (const file of graph.keys()) {
+  if (!allDeps.has(file)) {
+    rootNodes.push(path.basename(file))
+  }
+}
+
+console.log(`Root nodes: ${rootNodes.join(', ')}`)

package/examples/verify-build-order.js

@@ -0,0 +1,113 @@
+// Calculate build order using topological sort
+const path = require('path')
+const { depGraph } = require('../src/dep-graph')
+
+/**
+ * Calculate build order using topological sort (Kahn's algorithm)
+ * @param {Map<string, string[]>} graph - Dependency graph
+ * @returns {string[]} - Files in build order (dependencies first)
+ */
+function calculateBuildOrder(graph) {
+  // Calculate in-degree (number of dependencies) for each file
+  const inDegree = new Map()
+  for (const [file, deps] of graph) {
+    inDegree.set(file, deps.length)
+  }
+
+  // Queue of files with no dependencies (can be built first)
+  const queue = []
+  for (const [file, degree] of inDegree) {
+    if (degree === 0) {
+      queue.push(file)
+    }
+  }
+
+  const buildOrder = []
+
+  while (queue.length > 0) {
+    const file = queue.shift()
+    buildOrder.push(file)
+
+    // Find all files that depend on this file and decrement their in-degree
+    for (const [dependent, deps] of graph) {
+      if (deps.includes(file)) {
+        const newDegree = inDegree.get(dependent) - 1
+        inDegree.set(dependent, newDegree)
+        if (newDegree === 0) {
+          queue.push(dependent)
+        }
+      }
+    }
+  }
+
+  return buildOrder
+}
+
+/**
+ * Group files by build level (parallel build opportunities)
+ * @param {Map<string, string[]>} graph - Dependency graph
+ * @returns {Array<string[]>} - Array of levels, each containing files that can be built in parallel
+ */
+function calculateBuildLevels(graph) {
+  const inDegree = new Map()
+  for (const [file, deps] of graph) {
+    inDegree.set(file, deps.length)
+  }
+
+  const levels = []
+  const processed = new Set()
+
+  while (processed.size < graph.size) {
+    const currentLevel = []
+
+    for (const [file, degree] of inDegree) {
+      if (degree === 0 && !processed.has(file)) {
+        currentLevel.push(file)
+      }
+    }
+
+    if (currentLevel.length === 0) break
+
+    levels.push(currentLevel)
+
+    for (const file of currentLevel) {
+      processed.add(file)
+      for (const [dependent, deps] of graph) {
+        if (deps.includes(file)) {
+          inDegree.set(dependent, inDegree.get(dependent) - 1)
+        }
+      }
+    }
+  }
+
+  return levels
+}
+
+const fixture = path.resolve(__dirname, '../tests/fixtures/cjs-deep-example/index.js')
+const graph = depGraph(fixture)
+
+console.log('=== Build Order Analysis ===\n')
+
+// Sequential build order
+const buildOrder = calculateBuildOrder(graph)
+console.log('Sequential build order (dependencies first):\n')
+buildOrder.forEach((file, index) => {
+  console.log(`${index + 1}. ${path.basename(file)}`)
+})
+
+console.log('\n=== Parallel Build Opportunities ===\n')
+
+// Parallel build levels
+const levels = calculateBuildLevels(graph)
+console.log('Files grouped by build level (same level can build in parallel):\n')
+
+levels.forEach((level, index) => {
+  console.log(`Level ${index + 1}: (${level.length} file${level.length === 1 ? '' : 's'})`)
+  level.forEach(file => {
+    console.log(`  - ${path.basename(file)}`)
+  })
+  console.log()
+})
+
+console.log(`Total build levels: ${levels.length}`)
+console.log(`Maximum parallelism: ${Math.max(...levels.map(l => l.length))} files`)

package/examples/verify-find-dependents.js

@@ -0,0 +1,74 @@
+// Find all files that depend on a specific file
+const path = require('path')
+const { depGraph } = require('../src/dep-graph')
+
+/**
+ * Find all files that directly depend on a target file
+ * @param {Map<string, string[]>} graph - Dependency graph
+ * @param {string} targetFile - File to find dependents for
+ * @returns {string[]} - Array of files that depend on targetFile
+ */
+function findDirectDependents(graph, targetFile) {
+  const dependents = []
+  for (const [file, deps] of graph) {
+    if (deps.includes(targetFile)) {
+      dependents.push(file)
+    }
+  }
+  return dependents
+}
+
+/**
+ * Find all files that transitively depend on a target file
+ * @param {Map<string, string[]>} graph - Dependency graph
+ * @param {string} targetFile - File to find dependents for
+ * @returns {Set<string>} - Set of all files that depend on targetFile (directly or indirectly)
+ */
+function findAllDependents(graph, targetFile) {
+  const allDependents = new Set()
+  const queue = [targetFile]
+
+  while (queue.length > 0) {
+    const current = queue.shift()
+    const directDependents = findDirectDependents(graph, current)
+
+    for (const dependent of directDependents) {
+      if (!allDependents.has(dependent)) {
+        allDependents.add(dependent)
+        queue.push(dependent)
+      }
+    }
+  }
+
+  return allDependents
+}
+
+const fixture = path.resolve(__dirname, '../tests/fixtures/cjs-deep-example/index.js')
+const graph = depGraph(fixture)
+
+// Find a commonly used file
+const targetFile = Array.from(graph.keys()).find(key => key.includes('d-three.js'))
+
+if (targetFile) {
+  console.log(`Analyzing dependencies for: ${path.basename(targetFile)}\n`)
+
+  const directDeps = findDirectDependents(graph, targetFile)
+  console.log('Direct dependents:')
+  if (directDeps.length === 0) {
+    console.log('  (none)')
+  } else {
+    directDeps.forEach(dep => {
+      console.log(`  - ${path.basename(dep)}`)
+    })
+  }
+
+  const allDeps = findAllDependents(graph, targetFile)
+  console.log(`\nAll dependents (transitive): ${allDeps.size}`)
+  if (allDeps.size > 0) {
+    Array.from(allDeps).forEach(dep => {
+      console.log(`  - ${path.basename(dep)}`)
+    })
+  }
+
+  console.log(`\nImpact: Changing this file affects ${allDeps.size} other file(s)`)
+}

package/examples/verify-impact-analysis.js

@@ -0,0 +1,97 @@
+// Analyze impact of changing files in the dependency graph
+const path = require('path')
+const { depGraph } = require('../src/dep-graph')
+
+/**
+ * Calculate impact metrics for each file in the graph
+ * @param {Map<string, string[]>} graph - Dependency graph
+ * @returns {Map<string, object>} - Map of file paths to impact metrics
+ */
+function analyzeImpact(graph) {
+  const impact = new Map()
+
+  for (const file of graph.keys()) {
+    // Count direct dependencies
+    const directDeps = graph.get(file).length
+
+    // Count direct dependents
+    let directDependents = 0
+    for (const [_, deps] of graph) {
+      if (deps.includes(file)) {
+        directDependents++
+      }
+    }
+
+    // Calculate transitive dependents
+    const transitiveDependents = new Set()
+    const queue = [file]
+    const visited = new Set([file])
+
+    while (queue.length > 0) {
+      const current = queue.shift()
+      for (const [f, deps] of graph) {
+        if (deps.includes(current) && !visited.has(f)) {
+          visited.add(f)
+          transitiveDependents.add(f)
+          queue.push(f)
+        }
+      }
+    }
+
+    impact.set(file, {
+      directDeps,
+      directDependents,
+      transitiveDependents: transitiveDependents.size,
+      isLeaf: directDeps === 0,
+      isRoot: directDependents === 0
+    })
+  }
+
+  return impact
+}
+
+const fixture = path.resolve(__dirname, '../tests/fixtures/cjs-deep-example/index.js')
+const graph = depGraph(fixture)
+
+console.log('=== Dependency Impact Analysis ===\n')
+
+const impact = analyzeImpact(graph)
+
+// Sort files by impact (most dependents first)
+const sortedFiles = Array.from(impact.entries())
+  .sort((a, b) => b[1].transitiveDependents - a[1].transitiveDependents)
+
+console.log('Files sorted by impact (files that affect the most others):\n')
+
+sortedFiles.forEach(([file, metrics], index) => {
+  const fileName = path.basename(file)
+  const impactLevel = metrics.transitiveDependents > 3 ? '🔴 HIGH' :
+                       metrics.transitiveDependents > 1 ? '🟡 MEDIUM' :
+                       '🟢 LOW'
+
+  console.log(`${index + 1}. ${fileName}`)
+  console.log(`   Impact: ${impactLevel}`)
+  console.log(`   Direct dependencies: ${metrics.directDeps}`)
+  console.log(`   Direct dependents: ${metrics.directDependents}`)
+  console.log(`   Total files affected: ${metrics.transitiveDependents}`)
+
+  if (metrics.isLeaf) {
+    console.log(`   Type: Leaf node (no dependencies)`)
+  }
+  if (metrics.isRoot) {
+    console.log(`   Type: Root node (nothing depends on it)`)
+  }
+
+  console.log()
+})
+
+console.log('=== Summary ===')
+console.log(`Total files: ${graph.size}`)
+
+const leafNodes = Array.from(impact.values()).filter(m => m.isLeaf).length
+const rootNodes = Array.from(impact.values()).filter(m => m.isRoot).length
+const highImpact = sortedFiles.filter(([_, m]) => m.transitiveDependents > 3).length
+
+console.log(`Leaf nodes: ${leafNodes}`)
+console.log(`Root nodes: ${rootNodes}`)
+console.log(`High impact files: ${highImpact}`)

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@davidwells/extract-deps",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Get imports and requires from a codebase without AST",
   "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./dep-graph": "./src/dep-graph.js"
+  },
   "types": "types/index.d.ts",
   "author": "David Wells",
   "license": "MIT",

package/src/dep-graph.js

@@ -0,0 +1,277 @@
+// Build dependency graph and optionally verify imports
+const path = require('path')
+const fs = require('fs')
+const { extractDeps } = require('./index')
+
+function fsExistsSync(path) {
+  try {
+    fs.accessSync(path, fs.constants.F_OK)
+    return true
+  } catch (error) {
+    return false
+  }
+}
+
+/**
+ * Resolve a relative import to an actual file path
+ * @param {string} baseDir - Directory containing the importing file
+ * @param {string} importPath - The relative import path
+ * @returns {string|null} - Resolved file path or null if not found
+ */
+function resolveImportPath(baseDir, importPath) {
+  const possibleExtensions = ['.js', '.mjs', '.ts', '.json', '']
+
+  // Try direct file resolution
+  for (const ext of possibleExtensions) {
+    const testPath = path.resolve(baseDir, importPath + ext)
+    if (fsExistsSync(testPath)) {
+      return testPath
+    }
+  }
+
+  // Try directory with index file
+  const indexExtensions = ['/index.js', '/index.mjs', '/index.ts']
+  for (const indexExt of indexExtensions) {
+    const testPath = path.resolve(baseDir, importPath + indexExt)
+    if (fsExistsSync(testPath)) {
+      return testPath
+    }
+  }
+
+  return null
+}
+
+/**
+ * Verify that imported values are exported from a file
+ * @param {object} dep - Dependency object with import info
+ * @param {object} targetDeps - Extracted deps from the target file
+ * @param {string} targetPath - Path to the target file
+ * @param {string} sourcePath - Path to the file doing the importing
+ * @param {Array<Error>} errors - Array to collect errors
+ * @param {boolean} throwOnFirstError - Whether to throw immediately on first error
+ */
+function verifyImportedValuesExist(dep, targetDeps, targetPath, sourcePath, errors, throwOnFirstError) {
+  // Check if this is a destructured import
+  if (dep.definitions && dep.definitions.expectsDestructuring && dep.definitions.destructuredParameters) {
+    const importedNames = dep.definitions.destructuredParameters.map(p => p.name.replace(/,$/, ''))
+
+    // Check CommonJS exports
+    const exportedNames = new Set()
+    if (targetDeps.moduleExports && targetDeps.moduleExports.length > 0) {
+      for (const exp of targetDeps.moduleExports) {
+        if (exp.exportType === 'named') {
+          exportedNames.add(exp.exportName)
+        } else if (exp.exportType === 'default' && exp.keys) {
+          exp.keys.forEach(key => exportedNames.add(key))
+        }
+      }
+    }
+
+    // Check ESM exports
+    if (targetDeps.exports && targetDeps.exports.length > 0) {
+      for (const exp of targetDeps.exports) {
+        const exportedName = exp.exportAlias || exp.exportName
+        if (exportedName) {
+          exportedNames.add(exportedName)
+        }
+      }
+    }
+
+    // Verify each imported name is exported
+    for (const importedName of importedNames) {
+      if (!exportedNames.has(importedName)) {
+        const error = new Error(
+          `Import not found: "${importedName}" is not exported from "${targetPath}".\n` +
+          `Import statement: ${dep.line}\n` +
+          `Importing from: ${sourcePath}\n` +
+          `Available exports: ${Array.from(exportedNames).join(', ') || 'none'}`
+        )
+        if (throwOnFirstError) {
+          throw error
+        }
+        errors.push(error)
+      }
+    }
+  }
+  // For non-destructured imports, just verify there's a default export
+  else {
+    const hasDefaultExport =
+      (targetDeps.moduleExports && targetDeps.moduleExports.length > 0) ||
+      (targetDeps.exports && targetDeps.exports.some(exp => exp.exportType === 'default'))
+
+    if (!hasDefaultExport) {
+      const error = new Error(
+        `Import not found: "${targetPath}" does not have a default export.\n` +
+        `Import statement: ${dep.line}\n` +
+        `Importing from: ${sourcePath}`
+      )
+      if (throwOnFirstError) {
+        throw error
+      }
+      errors.push(error)
+    }
+  }
+}
+
+/**
+ * Recursively build dependency graph and optionally validate imports
+ * @param {string} filePath - File to process
+ * @param {Array<Error>} errors - Array to collect errors
+ * @param {boolean} throwOnFirstError - Whether to throw immediately on first error
+ * @param {boolean} verify - Whether to verify imports/exports
+ * @param {Map<string, string[]>|null} graph - Optional map to collect dependency graph
+ * @param {Set} visited - Set of already-visited file paths to avoid cycles
+ */
+function buildGraphRecursively(filePath, errors, throwOnFirstError, verify, graph = null, visited = new Set()) {
+  // Avoid infinite loops
+  const normalizedPath = fs.realpathSync(filePath)
+  if (visited.has(normalizedPath)) {
+    return
+  }
+  visited.add(normalizedPath)
+
+  // Initialize graph entry for this file if building graph
+  if (graph !== null && !graph.has(normalizedPath)) {
+    graph.set(normalizedPath, [])
+  }
+
+  // Read and extract deps from this file
+  const content = fs.readFileSync(filePath, 'utf8')
+  const deps = extractDeps(content)
+
+  // Collect all relative dependencies
+  const relativeDeps = []
+  if (deps.requires && deps.requires.length > 0) {
+    relativeDeps.push(...deps.requires.filter(req => req.isRelative))
+  }
+  if (deps.imports && deps.imports.length > 0) {
+    relativeDeps.push(...deps.imports.filter(imp => imp.isRelative))
+  }
+
+  // Process each relative dependency
+  const fileDir = path.dirname(filePath)
+  for (const dep of relativeDeps) {
+    const { from, line } = dep
+
+    // Resolve the import path
+    const resolvedPath = resolveImportPath(fileDir, from)
+
+    if (!resolvedPath) {
+      const error = new Error(
+        `"${line}" could not be resolved in ${filePath}\n\n` +
+        `Fix by ensuring "${path.resolve(fileDir, from)}" exists and is valid.`
+      )
+      if (throwOnFirstError) {
+        throw error
+      }
+      errors.push(error)
+      continue
+    }
+
+    // Add edge to graph if building
+    if (graph !== null) {
+      const normalizedResolvedPath = fs.realpathSync(resolvedPath)
+      graph.get(normalizedPath).push(normalizedResolvedPath)
+    }
+
+    // Verify imports if verification is enabled
+    if (verify) {
+      // Extract deps from the imported file
+      const targetContent = fs.readFileSync(resolvedPath, 'utf8')
+      const targetDeps = extractDeps(targetContent)
+
+      // Verify the imported values are exported
+      verifyImportedValuesExist(dep, targetDeps, resolvedPath, filePath, errors, throwOnFirstError)
+    }
+
+    // Recursively process the imported file
+    buildGraphRecursively(resolvedPath, errors, throwOnFirstError, verify, graph, visited)
+  }
+}
+
+/**
+ * Build dependency graph for a file and its dependencies
+ * @param {string} filePath - File to analyze
+ * @param {object} options - Options
+ * @param {boolean} [options.buildGraph] - If true, build and return dependency graph. Default: true
+ * @param {boolean} [options.verifyGraph] - If true, verify imports/exports. Default: true
+ * @param {boolean} [options.throwOnFirstError] - If true, throw immediately on first error. Default: false
+ * @returns {Map<string, string[]>|undefined} - Dependency graph where keys are file paths and values are arrays of dependency paths. Returns undefined if buildGraph is false.
+ */
+function depGraph(filePath, options = {}) {
+  const { buildGraph = true, verifyGraph = true, throwOnFirstError = false } = options
+  const errors = []
+  const graph = buildGraph ? new Map() : null
+
+  buildGraphRecursively(filePath, errors, throwOnFirstError, verifyGraph, graph)
+
+  if (errors.length > 0) {
+    const errorMessage = errors.map((err, idx) => `Error ${idx + 1}:\n${err.message}`).join('\n\n')
+    throw new Error(`Found ${errors.length} validation error${errors.length === 1 ? '' : 's'}:\n\n${errorMessage}`)
+  }
+
+  if (buildGraph) {
+    return graph
+  }
+}
+
+
+/**
+ * Get all dependency file paths in build order (dependencies first), deduplicated
+ * @param {string} filePath - Entry file path
+ * @param {object} options - Options to pass to depGraph
+ * @returns {string[]} - Array of unique dependency file paths in topological order
+ */
+function resolveDepPaths(filePath, options = {}) {
+  const graph = depGraph(filePath, options)
+
+  // Calculate in-degree (number of dependencies) for each file
+  const inDegree = new Map()
+  for (const [file, deps] of graph) {
+    inDegree.set(file, deps.length)
+  }
+
+  // Queue of files with no dependencies (can be processed first)
+  const queue = []
+  for (const [file, degree] of inDegree) {
+    if (degree === 0) {
+      queue.push(file)
+    }
+  }
+
+  const buildOrder = []
+
+  while (queue.length > 0) {
+    const file = queue.shift()
+    buildOrder.push(file)
+
+    // Find all files that depend on this file and decrement their in-degree
+    for (const [dependent, deps] of graph) {
+      if (deps.includes(file)) {
+        const newDegree = inDegree.get(dependent) - 1
+        inDegree.set(dependent, newDegree)
+        if (newDegree === 0) {
+          queue.push(dependent)
+        }
+      }
+    }
+  }
+
+  return buildOrder
+}
+
+
+if (require.main === module) {
+  const entry = path.resolve(__dirname, '../tests/fixtures/cjs-deep-example/index.js')
+  const graph = depGraph(entry)
+  console.log('graph', graph)
+  const depPaths = Array.from(graph.values()).flat()
+  console.log('depPaths', depPaths)
+  const depPathsProper = resolveDepPaths(entry)
+  console.log('depPathsProper', depPathsProper)
+}
+
+module.exports = {
+  depGraph,
+  resolveDepPaths
+}