gemstack-ai 1.3.0 → 2.0.0

package/src/commands/verify.js

@@ -87,6 +87,16 @@ module.exports = async (flags) => {
         } else {
             logger.ok('Sección inmutable "4. Intentos fallidos" preservada.');
         }
+
+        // Cross-Audit con Git Log (Gemstack 2.0 Sprint D)
+        const { crossAuditMemoryWithGit } = require('../lib/memory-audit');
+        const memAudit = crossAuditMemoryWithGit(targetDir);
+        if (!memAudit.valid && memAudit.unrecorded_commits.length > 0) {
+            logger.warn(`Detectados commits recientes no registrados en handoff.md: ${memAudit.unrecorded_commits.map(c => c.hash).join(', ')}`);
+            totalWarnings++;
+        } else {
+            logger.ok('Memoria cruzada (handoff.md <-> git log) verificada.');
+        }
     }
 
     // 3. Consistencia de Estado Local (.gemstack/state.json)
@@ -430,6 +440,44 @@ module.exports = async (flags) => {
         logger.ok('Sin spec activa configurada para verificación de context capsule.');
     }
 
+    // 5.3 Verificación de Swarm Manifest (Upgrade E - Read-Only)
+    logger.info('--- 5.3 Verificación de Swarm Manifest & Partition Safety (Read-Only) ---');
+    if (loadedState && loadedState.active_spec) {
+        const { validateSwarmManifest } = require('../lib/swarm');
+        const swarmResult = validateSwarmManifest(targetDir, loadedState.active_spec);
+        if (swarmResult.valid) {
+            logger.ok(`Swarm manifest verificado y sin colisiones (${loadedState.active_spec}/swarm.json).`);
+        } else if (swarmResult.state === 'MISSING') {
+            logger.info(`[LEGACY] No se detectó swarm.json en "${loadedState.active_spec}" (Modo Legacy Swarm-Free).`);
+        } else {
+            for (const f of swarmResult.findings) {
+                logger.error(`[${f.code}] ${f.details || f.message}`);
+                totalErrors++;
+            }
+        }
+    } else {
+        logger.ok('Sin spec activa configurada para verificación de swarm manifest.');
+    }
+
+    // 5.4 Verificación de Visual QA Manifest & Baselines (Upgrade E - Read-Only)
+    logger.info('--- 5.4 Verificación de Visual QA Manifest & Baselines (Read-Only) ---');
+    if (loadedState && loadedState.active_spec) {
+        const { validateVisualManifest } = require('../lib/visual-qa');
+        const vqaResult = validateVisualManifest(targetDir, loadedState.active_spec);
+        if (vqaResult.valid) {
+            logger.ok(`Visual QA manifest y baselines íntegros (${loadedState.active_spec}/visual-qa.json).`);
+        } else if (vqaResult.state === 'MISSING') {
+            logger.info(`[LEGACY] No se detectó visual-qa.json en "${loadedState.active_spec}" (Modo Legacy Visual-Free).`);
+        } else {
+            for (const f of vqaResult.findings) {
+                logger.error(`[${f.code}] ${f.details || f.message}`);
+                totalErrors++;
+            }
+        }
+    } else {
+        logger.ok('Sin spec activa configurada para verificación de visual QA.');
+    }
+
     // 6. Seguridad Local y Anti-Silent Failures en Tests
     logger.info('--- 6/6 Verificación de Seguridad y Test Runners ---');
     const envPath = fssafe.resolveSafe(targetDir, '.env');

package/src/commands/visual.js

@@ -0,0 +1,82 @@
+/**
+ * Gemstack Visual QA Command Handler (Upgrade E)
+ *
+ * Implements "gemstack vqa validate" and "gemstack vqa promote" subcommands.
+ * Read-only validation and explicit baseline promotion.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const logger = require('../lib/logger');
+const fssafe = require('../lib/filesystem-safe');
+const { readState } = require('../lib/state');
+const { validateVisualManifest, promoteVisualBaseline } = require('../lib/visual-qa');
+
+async function visualCommand(args = [], flags = {}) {
+  const subcommand = args[0] || 'validate';
+  const targetDir = flags.target ? path.resolve(flags.target) : process.cwd();
+
+  let state;
+  try {
+    state = readState(targetDir);
+  } catch (e) {
+    logger.error(`Error loading .gemstack/state.json: ${e.message}`);
+    process.exit(1);
+  }
+
+  const activeSpec = state.active_spec;
+  if (!activeSpec) {
+    if (flags.json) {
+      console.log(JSON.stringify({ status: 'NO_ACTIVE_SPEC', message: 'No active feature spec set.' }));
+    } else {
+      logger.info('Sin spec activa pendiente. Opera en modo legacy.');
+    }
+    return;
+  }
+
+  if (subcommand === 'validate') {
+    const res = validateVisualManifest(targetDir, activeSpec);
+    if (flags.json) {
+      console.log(JSON.stringify(res, null, 2));
+      return;
+    }
+
+    if (res.state === 'MISSING') {
+      logger.info(`[LEGACY] No se detectó visual-qa.json en "${activeSpec}".`);
+      return;
+    }
+
+    if (res.valid) {
+      logger.ok(`Visual QA manifest validado con éxito: ${activeSpec}/visual-qa.json.`);
+    } else {
+      for (const f of res.findings) {
+        logger.error(`[${f.code}] ${f.details}`);
+      }
+      process.exit(1);
+    }
+  } else if (subcommand === 'promote') {
+    const scenarioId = args[1];
+    const liveImagePath = args[2];
+
+    if (!scenarioId || !liveImagePath) {
+      logger.error('Usage: gemstack vqa promote <scenario-id> <live-image-path>');
+      process.exit(1);
+    }
+
+    try {
+      const res = promoteVisualBaseline(targetDir, activeSpec, scenarioId, liveImagePath);
+      logger.ok(`Baseline promoted for scenario "${scenarioId}". Updated ${activeSpec}/visual-qa.json.`);
+      if (flags.json) {
+        console.log(JSON.stringify(res, null, 2));
+      }
+    } catch (err) {
+      logger.error(`Failed to promote baseline: ${err.message}`);
+      process.exit(1);
+    }
+  } else {
+    logger.error(`Unknown visual subcommand: "${subcommand}". Use "validate" or "promote".`);
+    process.exit(1);
+  }
+}
+
+module.exports = visualCommand;

package/src/lib/backup.js

@@ -5,12 +5,12 @@ const logger = require('./logger');
 
 module.exports = {
     backupFile: (targetDir, relativeFilePath, dryRun, sessionTimestamp) => {
-        const fullPath = fssafe.resolveSafe(targetDir, relativeFilePath);
+        const fullPath = fssafe.resolveSafeStrict(targetDir, relativeFilePath);
         if (!fs.existsSync(fullPath)) return;
 
         const timestamp = sessionTimestamp || new Date().toISOString().replace(/[:.]/g, '-');
-        const backupDir = fssafe.resolveSafe(targetDir, `.gemstack/backups/${timestamp}`);
-        const backupDest = fssafe.resolveSafe(backupDir, relativeFilePath);
+        const backupDir = fssafe.resolveSafeStrict(targetDir, `.gemstack/backups/${timestamp}`);
+        const backupDest = fssafe.resolveSafeStrict(backupDir, relativeFilePath);
 
         logger.info(`Backup: ${relativeFilePath}`);
         if (!dryRun) {

package/src/lib/closure-context.js

@@ -220,7 +220,7 @@ function parseTaskMetadata(tasksContent) {
   const lines = normalized.split('\n');
   const tasks = [];
 
-  const taskHeaderRegex = /^[*-]\s+\[[ xX]\]\s+\*\*(T\d+):\s*(.*?)\*\*/;
+  const taskHeaderRegex = /^[*-]\s+\[[ xX]\]\s+\*\*([A-Za-z0-9_-]+):\s*(.*?)\*\*/;
   let currentTask = null;
 
   for (const line of lines) {
@@ -343,6 +343,14 @@ function resolveRelevantFiles(rootPath, featureDir, planBindings, taskList, plan
   if (fs.existsSync(path.join(rootPath, featureCapsule))) filesSet.add(featureCapsule);
   if (fs.existsSync(path.join(rootPath, '.gemstack/context-capsule.json'))) filesSet.add('.gemstack/context-capsule.json');
 
+  const featureSwarm = (relFeature + '/swarm.json').replace(/^\.\//, '');
+  if (fs.existsSync(path.join(rootPath, featureSwarm))) filesSet.add(featureSwarm);
+  if (fs.existsSync(path.join(rootPath, '.gemstack/swarm.json'))) filesSet.add('.gemstack/swarm.json');
+
+  const featureVqa = (relFeature + '/visual-qa.json').replace(/^\.\//, '');
+  if (fs.existsSync(path.join(rootPath, featureVqa))) filesSet.add(featureVqa);
+  if (fs.existsSync(path.join(rootPath, '.gemstack/visual-qa.json'))) filesSet.add('.gemstack/visual-qa.json');
+
   for (const b of (planBindings || [])) {
     if (b.file && fs.existsSync(path.join(rootPath, b.file))) {
       filesSet.add(b.file);

package/src/lib/context-fatigue.js

@@ -0,0 +1,165 @@
+'use strict';
+
+/**
+ * Context Fatigue & Noise Pruning Engine (Gemstack 2.0 Sprint D)
+ * Monitors accumulated token load, detects redundancy, and prunes ephemeral noise.
+ */
+
+const DEFAULT_TOKEN_THRESHOLD = 16000;
+const DEFAULT_REDUNDANCY_THRESHOLD = 0.4;
+
+/**
+ * Fast conservative token estimation (~4 characters per token).
+ * @param {string} text 
+ * @returns {number}
+ */
+function estimateTokens(text) {
+  if (!text || typeof text !== 'string') return 0;
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Calculates redundancy ratio based on repeated content blocks and duplicate messages.
+ * @param {Array<string|object>} messages 
+ * @returns {number} Float between 0.0 and 1.0
+ */
+function computeRedundancyRatio(messages) {
+  if (!Array.isArray(messages) || messages.length <= 1) return 0;
+
+  const texts = messages.map(m => (typeof m === 'string' ? m : (m.content || m.text || JSON.stringify(m))));
+  const totalLength = texts.reduce((acc, t) => acc + t.length, 0);
+  if (totalLength === 0) return 0;
+
+  const seen = new Set();
+  let duplicateLength = 0;
+
+  for (const t of texts) {
+    const trimmed = t.trim();
+    if (seen.has(trimmed)) {
+      duplicateLength += trimmed.length;
+    } else {
+      seen.add(trimmed);
+    }
+  }
+
+  return Number((duplicateLength / totalLength).toFixed(4));
+}
+
+/**
+ * Detects whether the current context window suffers from token fatigue or high redundancy.
+ * @param {Array<string|object>} messages 
+ * @param {object} options - { tokenThreshold?: number, redundancyThreshold?: number }
+ * @returns {{ fatigue: boolean, total_tokens: number, token_limit: number, redundancy_ratio: number, reason?: string }}
+ */
+function detectContextFatigue(messages, options = {}) {
+  const tokenThreshold = options.tokenThreshold || DEFAULT_TOKEN_THRESHOLD;
+  const redundancyThreshold = options.redundancyThreshold || DEFAULT_REDUNDANCY_THRESHOLD;
+
+  if (!Array.isArray(messages)) {
+    return {
+      fatigue: false,
+      total_tokens: 0,
+      token_limit: tokenThreshold,
+      redundancy_ratio: 0
+    };
+  }
+
+  const texts = messages.map(m => (typeof m === 'string' ? m : (m.content || m.text || JSON.stringify(m))));
+  const totalTokens = texts.reduce((acc, t) => acc + estimateTokens(t), 0);
+  const redundancyRatio = computeRedundancyRatio(messages);
+
+  let fatigue = false;
+  const reasons = [];
+
+  if (totalTokens > tokenThreshold) {
+    fatigue = true;
+    reasons.push(`Token count (${totalTokens}) exceeds threshold (${tokenThreshold})`);
+  }
+
+  if (redundancyRatio > redundancyThreshold) {
+    fatigue = true;
+    reasons.push(`Redundancy ratio (${(redundancyRatio * 100).toFixed(1)}%) exceeds limit (${(redundancyThreshold * 100).toFixed(1)}%)`);
+  }
+
+  return {
+    fatigue,
+    total_tokens: totalTokens,
+    token_limit: tokenThreshold,
+    redundancy_ratio: redundancyRatio,
+    reason: reasons.length > 0 ? reasons.join('; ') : undefined
+  };
+}
+
+/**
+ * Deterministically prunes ephemeral noise, duplicated tool outputs, and redundant dialogue.
+ * Guarantees preservation of architectural contracts, state definitions, and critical decisions.
+ * @param {Array<string|object>} messages 
+ * @param {object} options - { retainTail?: number }
+ * @returns {Array<string|object>} Pruned message array
+ */
+function pruneContextNoise(messages, options = {}) {
+  if (!Array.isArray(messages) || messages.length === 0) return [];
+  const retainTail = options.retainTail || 3;
+
+  const isContractOrState = (text) => {
+    return (
+      text.includes('gemstack-contracts') ||
+      text.includes('gemstack-inherited-contracts') ||
+      text.includes('gemstack-test-matrix') ||
+      text.includes('phase_hashes') ||
+      text.includes('handoff.md') ||
+      text.includes('### Intentos fallidos') ||
+      text.includes('4. Intentos fallidos')
+    );
+  };
+
+  const isEphemeralNoise = (text) => {
+    const trimmed = text.trim();
+    if (trimmed.length < 5) return true;
+    if (/^(ok|done|entendido|continuando|esperando|running)(?:\.{1,3})?$/i.test(trimmed)) return true;
+    return false;
+  };
+
+  const seenHashes = new Set();
+  const pruned = [];
+
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    const text = typeof m === 'string' ? m : (m.content || m.text || JSON.stringify(m));
+
+    // Always preserve contracts, invariants and state
+    if (isContractOrState(text)) {
+      pruned.push(m);
+      continue;
+    }
+
+    // Always preserve recent tail messages
+    if (i >= messages.length - retainTail) {
+      pruned.push(m);
+      continue;
+    }
+
+    // Skip pure ephemeral chit-chat
+    if (isEphemeralNoise(text)) {
+      continue;
+    }
+
+    // De-duplicate identical intermediate messages
+    const trimmed = text.trim();
+    if (seenHashes.has(trimmed)) {
+      continue;
+    }
+    seenHashes.add(trimmed);
+
+    pruned.push(m);
+  }
+
+  return pruned;
+}
+
+module.exports = {
+  estimateTokens,
+  computeRedundancyRatio,
+  detectContextFatigue,
+  pruneContextNoise
+};

package/src/lib/contract-amendments.js

@@ -0,0 +1,109 @@
+'use strict';
+
+/**
+ * Formal Contract Amendment Engine (Gemstack 2.0 Sprint C)
+ * Replaces silent contract mutations with signed, auditable amendment records.
+ */
+
+const crypto = require('crypto');
+
+const REQUIRED_AMENDMENT_FIELDS = ['amendment_id', 'contract_id', 'version', 'reason', 'approved_by', 'signature'];
+
+/**
+ * Computes deterministic signature for an amendment.
+ * @param {object} amendment - { amendment_id, contract_id, version, reason, approved_by }
+ * @param {string|null} secret - Optional HMAC secret
+ * @returns {string} Hex-encoded SHA-256 or HMAC-SHA256 digest
+ */
+function computeAmendmentSignature(amendment, secret = null) {
+  if (!amendment || typeof amendment !== 'object') {
+    throw new Error('Amendment must be an object');
+  }
+
+  const payload = [
+    String(amendment.amendment_id || ''),
+    String(amendment.contract_id || ''),
+    String(amendment.version || ''),
+    String(amendment.reason || '').trim(),
+    String(amendment.approved_by || '').trim()
+  ].join('|');
+
+  if (secret && typeof secret === 'string' && secret.length > 0) {
+    return crypto.createHmac('sha256', secret).update(payload).digest('hex');
+  }
+
+  return crypto.createHash('sha256').update(payload).digest('hex');
+}
+
+/**
+ * Validates that any changes from upstreamContracts to currentContracts are justified by signed amendments.
+ * @param {Array<object>} upstreamContracts 
+ * @param {Array<object>} currentContracts 
+ * @param {Array<object>} amendments 
+ * @param {object} options - { secret?: string }
+ * @returns {{ valid: boolean, code?: string, error?: string, verified_amendments?: number }}
+ */
+function validateContractAmendments(upstreamContracts = [], currentContracts = [], amendments = [], options = {}) {
+  const upstreamMap = new Map((upstreamContracts || []).map(c => [c.id, c]));
+  const currentMap = new Map((currentContracts || []).map(c => [c.id, c]));
+  const amendmentList = Array.isArray(amendments) ? amendments : [];
+  const amendmentMap = new Map(amendmentList.map(a => [a.contract_id, a]));
+
+  // 1. Detect modified or removed contracts
+  const changedContractIds = [];
+
+  for (const [id, upstream] of upstreamMap.entries()) {
+    if (!currentMap.has(id)) {
+      changedContractIds.push({ id, type: 'REMOVED', upstream });
+    } else {
+      const current = currentMap.get(id);
+      if (JSON.stringify(upstream) !== JSON.stringify(current)) {
+        changedContractIds.push({ id, type: 'MODIFIED', upstream, current });
+      }
+    }
+  }
+
+  // 2. Ensure each changed contract has a valid, signed amendment
+  for (const changed of changedContractIds) {
+    if (!amendmentMap.has(changed.id)) {
+      return {
+        valid: false,
+        code: 'UNAUTHORIZED_CONTRACT_MUTATION',
+        error: `El contrato congelado "${changed.id}" fue ${changed.type === 'REMOVED' ? 'eliminado' : 'modificado'} sin un registro formal de enmienda.`
+      };
+    }
+  }
+
+  // 3. Verify each declared amendment
+  for (const a of amendmentList) {
+    for (const field of REQUIRED_AMENDMENT_FIELDS) {
+      if (!a[field] && a[field] !== 0) {
+        return {
+          valid: false,
+          code: 'AMENDMENT_MALFORMED',
+          error: `Enmienda "${a.amendment_id || 'UNKNOWN'}" carece del campo obligatorio "${field}".`
+        };
+      }
+    }
+
+    const expectedSig = computeAmendmentSignature(a, options.secret);
+    if (a.signature !== expectedSig) {
+      return {
+        valid: false,
+        code: 'AMENDMENT_SIGNATURE_INVALID',
+        error: `Firma criptográfica inválida para la enmienda "${a.amendment_id}" del contrato "${a.contract_id}".`
+      };
+    }
+  }
+
+  return {
+    valid: true,
+    verified_amendments: amendmentList.length
+  };
+}
+
+module.exports = {
+  REQUIRED_AMENDMENT_FIELDS,
+  computeAmendmentSignature,
+  validateContractAmendments
+};

package/src/lib/dependency-audit.js

@@ -0,0 +1,202 @@
+'use strict';
+
+/**
+ * Offline Dependency Auditor (Gemstack 2.0 Sprint D)
+ * Detects orphan dependencies, undeclared imports, and circular local import cycles offline.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const fssafe = require('./filesystem-safe');
+
+const NODE_BUILTINS = new Set([
+  'assert', 'async_hooks', 'buffer', 'child_process', 'cluster', 'console',
+  'constants', 'crypto', 'dgram', 'diagnostics_channel', 'dns', 'domain',
+  'events', 'fs', 'fs/promises', 'http', 'http2', 'https', 'inspector',
+  'module', 'net', 'os', 'path', 'path/posix', 'path/win32', 'perf_hooks',
+  'process', 'punycode', 'querystring', 'readline', 'repl', 'stream',
+  'stream/promises', 'stream/consumers', 'stream/web', 'string_decoder',
+  'test', 'timers', 'timers/promises', 'tls', 'trace_events', 'tty',
+  'url', 'util', 'util/types', 'v8', 'vm', 'wasi', 'worker_threads', 'zlib'
+]);
+
+function isNodeBuiltin(moduleName) {
+  if (moduleName.startsWith('node:')) return true;
+  return NODE_BUILTINS.has(moduleName);
+}
+
+/**
+ * Extracts import/require targets from file content.
+ * @param {string} content 
+ * @returns {Array<string>} List of required/imported module specifiers
+ */
+function extractImportsFromContent(content) {
+  const imports = [];
+  // Match require('...')
+  const requireRegex = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+  let match;
+  while ((match = requireRegex.exec(content)) !== null) {
+    imports.push(match[1]);
+  }
+
+  // Match import ... from '...' or import('...')
+  const importRegex = /(?:import\s+(?:[\s\S]*?from\s+)?|import\s*\()\s*['"]([^'"]+)['"]/g;
+  while ((match = importRegex.exec(content)) !== null) {
+    imports.push(match[1]);
+  }
+
+  return imports;
+}
+
+/**
+ * Resolves package name from import specifier.
+ * E.g., 'express' -> 'express', '@scope/pkg/sub' -> '@scope/pkg'
+ */
+function getPackageName(specifier) {
+  if (specifier.startsWith('@')) {
+    const parts = specifier.split('/');
+    return parts.slice(0, 2).join('/');
+  }
+  return specifier.split('/')[0];
+}
+
+/**
+ * Scans directory recursively for JavaScript/TypeScript files.
+ */
+function collectSourceFiles(dir, files = []) {
+  if (!fs.existsSync(dir)) return files;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== 'node_modules' && entry.name !== '.git') {
+        collectSourceFiles(fullPath, files);
+      }
+    } else if (entry.isFile() && /\.(js|mjs|cjs|ts)$/.test(entry.name)) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+/**
+ * Detects circular dependency cycles using depth-first search.
+ */
+function findCircularCycles(dependencyGraph) {
+  const cycles = [];
+  const visited = new Set();
+  const recursionStack = [];
+
+  function dfs(node) {
+    visited.add(node);
+    recursionStack.push(node);
+
+    const neighbors = dependencyGraph.get(node) || [];
+    for (const neighbor of neighbors) {
+      if (!visited.has(neighbor)) {
+        dfs(neighbor);
+      } else {
+        const cycleStartIndex = recursionStack.indexOf(neighbor);
+        if (cycleStartIndex !== -1) {
+          const cyclePath = [...recursionStack.slice(cycleStartIndex), neighbor];
+          cycles.push(cyclePath);
+        }
+      }
+    }
+
+    recursionStack.pop();
+  }
+
+  for (const node of dependencyGraph.keys()) {
+    if (!visited.has(node)) {
+      dfs(node);
+    }
+  }
+
+  return cycles;
+}
+
+/**
+ * Audits project dependencies and local module cycles completely offline.
+ * @param {string} targetDir - Directory containing package.json and src/
+ * @returns {{ orphans: string[], undeclared: string[], circularCycles: string[][], is_clean: boolean }}
+ */
+function auditDependencies(targetDir) {
+  const pkgPath = fssafe.resolveSafe(targetDir, 'package.json');
+  let dependencies = {};
+  let devDependencies = {};
+
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      dependencies = pkg.dependencies || {};
+      devDependencies = pkg.devDependencies || {};
+    } catch (_) {}
+  }
+
+  const srcDir = fssafe.resolveSafe(targetDir, 'src');
+  const sourceFiles = collectSourceFiles(srcDir);
+
+  const usedPackages = new Set();
+  const dependencyGraph = new Map();
+
+  for (const filePath of sourceFiles) {
+    const normFile = filePath.replace(/\\/g, '/');
+    dependencyGraph.set(normFile, []);
+
+    let content = '';
+    try {
+      content = fs.readFileSync(filePath, 'utf8');
+    } catch (_) {
+      continue;
+    }
+
+    const imports = extractImportsFromContent(content);
+    for (const imp of imports) {
+      if (imp.startsWith('.')) {
+        // Local relative import
+        const resolvedPath = path.resolve(path.dirname(filePath), imp);
+        const candidates = [
+          resolvedPath,
+          resolvedPath + '.js',
+          resolvedPath + '.mjs',
+          path.join(resolvedPath, 'index.js')
+        ];
+        const match = candidates.find(c => fs.existsSync(c) && fs.statSync(c).isFile());
+        if (match) {
+          const normNeighbor = match.replace(/\\/g, '/');
+          dependencyGraph.get(normFile).push(normNeighbor);
+        }
+      } else if (!isNodeBuiltin(imp)) {
+        // External package
+        const pkgName = getPackageName(imp);
+        usedPackages.add(pkgName);
+      }
+    }
+  }
+
+  // 1. Detect orphans (in dependencies but not used in src)
+  const orphans = Object.keys(dependencies).filter(dep => !usedPackages.has(dep));
+
+  // 2. Detect undeclared (used in src but missing from dependencies & devDependencies)
+  const allDeclared = new Set([...Object.keys(dependencies), ...Object.keys(devDependencies)]);
+  const undeclared = Array.from(usedPackages).filter(dep => !allDeclared.has(dep));
+
+  // 3. Detect circular cycles
+  const circularCycles = findCircularCycles(dependencyGraph);
+
+  return {
+    orphans,
+    undeclared,
+    circularCycles,
+    is_clean: orphans.length === 0 && undeclared.length === 0 && circularCycles.length === 0
+  };
+}
+
+module.exports = {
+  isNodeBuiltin,
+  extractImportsFromContent,
+  auditDependencies,
+  findCircularCycles
+};