@craftpipe/contextpack 1.0.0

package/lib/validator.js

@@ -0,0 +1,561 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * lib/validator.js
+ * Validates bundle integrity; checks for missing files, circular dependencies,
+ * and symbol conflicts; returns a structured validation report with categorized
+ * warnings and errors.
+ */
+
+/**
+ * Severity levels for validation issues
+ */
+const SEVERITY = {
+  ERROR: 'error',
+  WARNING: 'warning',
+  INFO: 'info',
+};
+
+/**
+ * Create a validation issue object
+ * @param {string} severity - One of 'error', 'warning', 'info'
+ * @param {string} code - Short machine-readable code for the issue
+ * @param {string} message - Human-readable description
+ * @param {object} [meta] - Optional additional metadata
+ * @returns {object} Issue object
+ */
+function createIssue(severity, code, message, meta) {
+  return {
+    severity,
+    code,
+    message,
+    meta: meta || {},
+  };
+}
+
+/**
+ * Create an empty validation report
+ * @returns {object} Empty report structure
+ */
+function createReport() {
+  return {
+    valid: true,
+    errors: [],
+    warnings: [],
+    infos: [],
+    summary: {
+      errorCount: 0,
+      warningCount: 0,
+      infoCount: 0,
+    },
+  };
+}
+
+/**
+ * Add an issue to the report and update summary counts
+ * @param {object} report - The validation report to mutate
+ * @param {object} issue - The issue to add
+ */
+function addIssue(report, issue) {
+  if (!report || !issue) return;
+
+  switch (issue.severity) {
+    case SEVERITY.ERROR:
+      report.errors.push(issue);
+      report.summary.errorCount += 1;
+      report.valid = false;
+      break;
+    case SEVERITY.WARNING:
+      report.warnings.push(issue);
+      report.summary.warningCount += 1;
+      break;
+    case SEVERITY.INFO:
+      report.infos.push(issue);
+      report.summary.infoCount += 1;
+      break;
+    default:
+      report.warnings.push(issue);
+      report.summary.warningCount += 1;
+  }
+}
+
+/**
+ * Validate that required top-level fields exist in the bundle
+ * @param {object} bundle - The bundle to validate
+ * @param {object} report - The report to add issues to
+ */
+function validateBundleStructure(bundle, report) {
+  const requiredFields = ['fileSummaries', 'symbolIndex', 'dependencyMap', 'metadata'];
+
+  for (const field of requiredFields) {
+    if (!(field in bundle)) {
+      addIssue(report, createIssue(
+        SEVERITY.ERROR,
+        'MISSING_FIELD',
+        `Bundle is missing required field: "${field}"`,
+        { field }
+      ));
+    }
+  }
+
+  if ('metadata' in bundle) {
+    const metadata = bundle.metadata || {};
+    if (!metadata.projectDir) {
+      addIssue(report, createIssue(
+        SEVERITY.WARNING,
+        'MISSING_METADATA_PROJECT_DIR',
+        'Bundle metadata is missing "projectDir"',
+        {}
+      ));
+    }
+    if (!metadata.createdAt) {
+      addIssue(report, createIssue(
+        SEVERITY.INFO,
+        'MISSING_METADATA_CREATED_AT',
+        'Bundle metadata is missing "createdAt" timestamp',
+        {}
+      ));
+    }
+    if (metadata.error) {
+      addIssue(report, createIssue(
+        SEVERITY.ERROR,
+        'BUNDLE_CREATION_ERROR',
+        `Bundle was created with an error: ${metadata.error}`,
+        { error: metadata.error }
+      ));
+    }
+  }
+}
+
+/**
+ * Validate fileSummaries array for missing or malformed entries
+ * @param {object} bundle - The bundle to validate
+ * @param {object} report - The report to add issues to
+ */
+function validateFileSummaries(bundle, report) {
+  const fileSummaries = bundle.fileSummaries;
+
+  if (!Array.isArray(fileSummaries)) {
+    addIssue(report, createIssue(
+      SEVERITY.ERROR,
+      'INVALID_FILE_SUMMARIES',
+      '"fileSummaries" must be an array',
+      {}
+    ));
+    return;
+  }
+
+  if (fileSummaries.length === 0) {
+    addIssue(report, createIssue(
+      SEVERITY.WARNING,
+      'EMPTY_FILE_SUMMARIES',
+      'Bundle contains no file summaries',
+      {}
+    ));
+    return;
+  }
+
+  const seenPaths = new Set();
+
+  fileSummaries.forEach(function (entry, index) {
+    if (!entry || typeof entry !== 'object') {
+      addIssue(report, createIssue(
+        SEVERITY.ERROR,
+        'INVALID_FILE_SUMMARY_ENTRY',
+        `fileSummaries[${index}] is not a valid object`,
+        { index }
+      ));
+      return;
+    }
+
+    if (!entry.path || typeof entry.path !== 'string') {
+      addIssue(report, createIssue(
+        SEVERITY.ERROR,
+        'MISSING_FILE_PATH',
+        `fileSummaries[${index}] is missing a valid "path" field`,
+        { index }
+      ));
+    } else {
+      if (seenPaths.has(entry.path)) {
+        addIssue(report, createIssue(
+          SEVERITY.WARNING,
+          'DUPLICATE_FILE_PATH',
+          `Duplicate file path detected in fileSummaries: "${entry.path}"`,
+          { path: entry.path, index }
+        ));
+      } else {
+        seenPaths.add(entry.path);
+      }
+    }
+
+    if (entry.size !== undefined && (typeof entry.size !== 'number' || entry.size < 0)) {
+      addIssue(report, createIssue(
+        SEVERITY.WARNING,
+        'INVALID_FILE_SIZE',
+        `fileSummaries[${index}] has an invalid "size" value: ${entry.size}`,
+        { index, path: entry.path || null, size: entry.size }
+      ));
+    }
+  });
+}
+
+/**
+ * Validate the symbolIndex for structural integrity
+ * @param {object} bundle - The bundle to validate
+ * @param {object} report - The report to add issues to
+ */
+function validateSymbolIndex(bundle, report) {
+  const symbolIndex = bundle.symbolIndex;
+
+  if (symbolIndex === null || symbolIndex === undefined) {
+    addIssue(report, createIssue(
+      SEVERITY.WARNING,
+      'NULL_SYMBOL_INDEX',
+      '"symbolIndex" is null or undefined',
+      {}
+    ));
+    return;
+  }
+
+  if (typeof symbolIndex !== 'object' || Array.isArray(symbolIndex)) {
+    addIssue(report, createIssue(
+      SEVERITY.ERROR,
+      'INVALID_SYMBOL_INDEX',
+      '"symbolIndex" must be a plain object',
+      {}
+    ));
+    return;
+  }
+
+  const filePaths = Object.keys(symbolIndex);
+
+  if (filePaths.length === 0) {
+    addIssue(report, createIssue(
+      SEVERITY.INFO,
+      'EMPTY_SYMBOL_INDEX',
+      '"symbolIndex" contains no entries',
+      {}
+    ));
+    return;
+  }
+
+  for (const filePath of filePaths) {
+    const entry = symbolIndex[filePath];
+    if (!entry || typeof entry !== 'object') {
+      addIssue(report, createIssue(
+        SEVERITY.WARNING,
+        'INVALID_SYMBOL_ENTRY',
+        `symbolIndex entry for "${filePath}" is not a valid object`,
+        { filePath }
+      ));
+      continue;
+    }
+
+    if (entry.symbols !== undefined && !Array.isArray(entry.symbols)) {
+      addIssue(report, createIssue(
+        SEVERITY.WARNING,
+        'INVALID_SYMBOLS_FIELD',
+        `symbolIndex["${filePath}"].symbols must be an array`,
+        { filePath }
+      ));
+    }
+  }
+}
+
+/**
+ * Validate the dependencyMap for structural integrity and missing referenced files
+ * @param {object} bundle - The bundle to validate
+ * @param {object} report - The report to add issues to
+ * @param {Set} knownPaths - Set of known file paths from fileSummaries
+ */
+function validateDependencyMap(bundle, report, knownPaths) {
+  const dependencyMap = bundle.dependencyMap;
+
+  if (dependencyMap === null || dependencyMap === undefined) {
+    addIssue(report, createIssue(
+      SEVERITY.WARNING,
+      'NULL_DEPENDENCY_MAP',
+      '"dependencyMap" is null or undefined',
+      {}
+    ));
+    return;
+  }
+
+  if (typeof dependencyMap !== 'object' || Array.isArray(dependencyMap)) {
+    addIssue(report, createIssue(
+      SEVERITY.ERROR,
+      'INVALID_DEPENDENCY_MAP',
+      '"dependencyMap" must be a plain object',
+      {}
+    ));
+    return;
+  }
+
+  const depKeys = Object.keys(dependencyMap);
+
+  for (const filePath of depKeys) {
+    const deps = dependencyMap[filePath];
+
+    if (!Array.isArray(deps)) {
+      addIssue(report, createIssue(
+        SEVERITY.WARNING,
+        'INVALID_DEPENDENCY_ENTRY',
+        `dependencyMap["${filePath}"] must be an array of dependency paths`,
+        { filePath }
+      ));
+      continue;
+    }
+
+    for (const dep of deps) {
+      if (typeof dep !== 'string') {
+        addIssue(report, createIssue(
+          SEVERITY.WARNING,
+          'INVALID_DEPENDENCY_VALUE',
+          `dependencyMap["${filePath}"] contains a non-string dependency value`,
+          { filePath, dep }
+        ));
+        continue;
+      }
+
+      // Only flag missing files for relative/local dependencies (not node_modules)
+      const isLocalDep = dep.startsWith('.') || dep.startsWith('/');
+      if (isLocalDep && knownPaths.size > 0 && !knownPaths.has(dep)) {
+        // Normalize and try again
+        const normalized = dep.replace(/\\/g, '/');
+        if (!knownPaths.has(normalized)) {
+          addIssue(report, createIssue(
+            SEVERITY.WARNING,
+            'MISSING_DEPENDENCY_FILE',
+            `File "${filePath}" depends on "${dep}" which is not present in the bundle`,
+            { filePath, dependency: dep }
+          ));
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Detect circular dependencies in a dependency graph using DFS
+ * @param {object} dependencyMap - Map of file -> array of dependencies
+ * @returns {Array<string[]>} Array of cycles, each cycle is an array of file paths forming the loop
+ */
+function checkCircularDependencies(dependencyMap) {
+  if (!dependencyMap || typeof dependencyMap !== 'object' || Array.isArray(dependencyMap)) {
+    return [];
+  }
+
+  const cycles = [];
+  const visited = new Set();
+  const inStack = new Set();
+  const stackPath = [];
+
+  /**
+   * DFS visit function
+   * @param {string} node - Current node
+   */
+  function dfs(node) {
+    if (inStack.has(node)) {
+      // Found a cycle — extract the cycle portion from stackPath
+      const cycleStart = stackPath.indexOf(node);
+      if (cycleStart !== -1) {
+        const cycle = stackPath.slice(cycleStart).concat(node);
+        // Deduplicate cycles by canonical form
+        const cycleKey = cycle.slice().sort().join('|');
+        const alreadyFound = cycles.some(function (existing) {
+          return existing.slice().sort().join('|') === cycleKey;
+        });
+        if (!alreadyFound) {
+          cycles.push(cycle);
+        }
+      }
+      return;
+    }
+
+    if (visited.has(node)) {
+      return;
+    }
+
+    visited.add(node);
+    inStack.add(node);
+    stackPath.push(node);
+
+    const deps = dependencyMap[node];
+    if (Array.isArray(deps)) {
+      for (const dep of deps) {
+        if (typeof dep === 'string') {
+          dfs(dep);
+        }
+      }
+    }
+
+    stackPath.pop();
+    inStack.delete(node);
+  }
+
+  const allNodes = Object.keys(dependencyMap);
+  for (const node of allNodes) {
+    if (!visited.has(node)) {
+      dfs(node);
+    }
+  }
+
+  return cycles;
+}
+
+/**
+ * Detect symbol conflicts across files in the symbol index.
+ * A conflict occurs when the same symbol name is exported from multiple files.
+ * @param {object} symbolIndex - Map of filePath -> { symbols: string[] }
+ * @returns {Array<object>} Array of conflict objects { symbol, files }
+ */
+function checkSymbolConflicts(symbolIndex) {
+  if (!symbolIndex || typeof symbolIndex !== 'object' || Array.isArray(symbolIndex)) {
+    return [];
+  }
+
+  // Build a map of symbol name -> array of files that export it
+  const symbolToFiles = {};
+
+  const filePaths = Object.keys(symbolIndex);
+
+  for (const filePath of filePaths) {
+    const entry = symbolIndex[filePath];
+    if (!entry || typeof entry !== 'object') continue;
+
+    const symbols = entry.symbols;
+    if (!Array.isArray(symbols)) continue;
+
+    for (const sym of symbols) {
+      let symbolName = null;
+
+      if (typeof sym === 'string') {
+        symbolName = sym;
+      } else if (sym && typeof sym === 'object' && typeof sym.name === 'string') {
+        symbolName = sym.name;
+      }
+
+      if (!symbolName) continue;
+
+      if (!symbolToFiles[symbolName]) {
+        symbolToFiles[symbolName] = [];
+      }
+      if (!symbolToFiles[symbolName].includes(filePath)) {
+        symbolToFiles[symbolName].push(filePath);
+      }
+    }
+  }
+
+  // Collect conflicts (symbol exported from more than one file)
+  const conflicts = [];
+
+  for (const symbolName of Object.keys(symbolToFiles)) {
+    const files = symbolToFiles[symbolName];
+    if (files.length > 1) {
+      conflicts.push({
+        symbol: symbolName,
+        files: files.slice(),
+      });
+    }
+  }
+
+  return conflicts;
+}
+
+/**
+ * Validate a context bundle for integrity issues including missing files,
+ * circular dependencies, and symbol conflicts.
+ *
+ * @param {object} bundle - The bundle object produced by createBundle()
+ * @param {object} [options] - Optional validation options
+ * @param {boolean} [options.checkCircular=true] - Whether to check for circular dependencies
+ * @param {boolean} [options.checkConflicts=true] - Whether to check for symbol conflicts
+ * @param {boolean} [options.checkMissingFiles=true] - Whether to check for missing dependency files
+ * @returns {object} Validation report with { valid, errors, warnings, infos, summary }
+ */
+function validateBundle(bundle, options) {
+  const opts = options || {};
+  const {
+    checkCircular = true,
+    checkConflicts = true,
+    checkMissingFiles = true,
+  } = opts;
+
+  const report = createReport();
+
+  // Handle null/undefined bundle
+  if (!bundle || typeof bundle !== 'object') {
+    addIssue(report, createIssue(
+      SEVERITY.ERROR,
+      'INVALID_BUNDLE',
+      'Bundle must be a non-null object',
+      {}
+    ));
+    return report;
+  }
+
+  // 1. Validate top-level structure
+  validateBundleStructure(bundle, report);
+
+  // 2. Validate fileSummaries
+  if ('fileSummaries' in bundle) {
+    validateFileSummaries(bundle, report);
+  }
+
+  // 3. Validate symbolIndex
+  if ('symbolIndex' in bundle) {
+    validateSymbolIndex(bundle, report);
+  }
+
+  // Build a set of known paths from fileSummaries for cross-reference checks
+  const knownPaths = new Set();
+  if (Array.isArray(bundle.fileSummaries)) {
+    for (const entry of bundle.fileSummaries) {
+      if (entry && typeof entry.path === 'string') {
+        knownPaths.add(entry.path);
+        knownPaths.add(entry.path.replace(/\\/g, '/'));
+      }
+    }
+  }
+
+  // 4. Validate dependencyMap
+  if ('dependencyMap' in bundle) {
+    validateDependencyMap(bundle, report, checkMissingFiles ? knownPaths : new Set());
+  }
+
+  // 5. Check for circular dependencies
+  if (checkCircular && bundle.dependencyMap && typeof bundle.dependencyMap === 'object') {
+    const cycles = checkCircularDependencies(bundle.dependencyMap);
+    for (const cycle of cycles) {
+      addIssue(report, createIssue(
+        SEVERITY.ERROR,
+        'CIRCULAR_DEPENDENCY',
+        `Circular dependency detected: ${cycle.join(' -> ')}`,
+        { cycle }
+      ));
+    }
+  }
+
+  // 6. Check for symbol conflicts
+  if (checkConflicts && bundle.symbolIndex && typeof bundle.symbolIndex === 'object') {
+    const conflicts = checkSymbolConflicts(bundle.symbolIndex);
+    for (const conflict of conflicts) {
+      addIssue(report, createIssue(
+        SEVERITY.WARNING,
+        'SYMBOL_CONFLICT',
+        `Symbol "${conflict.symbol}" is exported from multiple files: ${conflict.files.join(', ')}`,
+        { symbol: conflict.symbol, files: conflict.files }
+      ));
+    }
+  }
+
+  return report;
+}
+
+module.exports = {
+  validateBundle,
+  checkCircularDependencies,
+  checkSymbolConflicts,
+};

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@craftpipe/contextpack",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.2"
+  }
+}

package/tests/analyzer.test.mjs

@@ -0,0 +1,128 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import analyzerModule from '../lib/analyzer.js';
+
+const { analyzeFile, analyzeProject, extractSymbols, buildDependencyGraph } = analyzerModule;
+
+vi.mock('fs', async (importOriginal) => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    readFileSync: vi.fn(() => 'const foo = () => {};\nfunction bar() {}\nmodule.exports = { foo, bar };'),
+    existsSync: vi.fn(() => true),
+    statSync: vi.fn(() => ({ size: 100, isDirectory: () => false, isFile: () => true })),
+    readdirSync: vi.fn(() => []),
+  };
+});
+
+describe('analyzeFile', () => {
+  it('is a function', () => {
+    expect(typeof analyzeFile).toBe('function');
+  });
+
+  it('does not throw when called with a valid path string', () => {
+    expect(() => analyzeFile('/fake/path/file.js')).not.toThrow();
+  });
+
+  it('does not throw when called with null', () => {
+    expect(() => analyzeFile(null)).not.toThrow();
+  });
+
+  it('does not throw when called with undefined', () => {
+    expect(() => analyzeFile(undefined)).not.toThrow();
+  });
+
+  it('does not throw when called with an empty string', () => {
+    expect(() => analyzeFile('')).not.toThrow();
+  });
+
+  it('returns a value', () => {
+    const result = analyzeFile('/fake/path/file.js');
+    expect(result).toBeDefined();
+  });
+
+  it('returns an object or null', () => {
+    const result = analyzeFile('/fake/path/file.js');
+    expect(result === null || typeof result === 'object').toBe(true);
+  });
+});
+
+describe('analyzeProject', () => {
+  it('is a function', () => {
+    expect(typeof analyzeProject).toBe('function');
+  });
+
+  it('does not throw when called with a valid path string', () => {
+    expect(() => analyzeProject('/fake/project')).not.toThrow();
+  });
+
+  it('does not throw when called with null', () => {
+    expect(() => analyzeProject(null)).not.toThrow();
+  });
+
+  it('does not throw when called with undefined', () => {
+    expect(() => analyzeProject(undefined)).not.toThrow();
+  });
+
+  it('does not throw when called with options', () => {
+    expect(() => analyzeProject('/fake/project', { include: ['**/*.js'], exclude: [] })).not.toThrow();
+  });
+
+  it('returns a value', () => {
+    const result = analyzeProject('/fake/project');
+    expect(result).toBeDefined();
+  });
+});
+
+describe('extractSymbols', () => {
+  it('is a function', () => {
+    expect(typeof extractSymbols).toBe('function');
+  });
+
+  it('does not throw when called with a file path', () => {
+    expect(() => extractSymbols('/fake/path/file.js')).not.toThrow();
+  });
+
+  it('does not throw when called with null', () => {
+    expect(() => extractSymbols(null)).not.toThrow();
+  });
+
+  it('does not throw when called with undefined', () => {
+    expect(() => extractSymbols(undefined)).not.toThrow();
+  });
+
+  it('does not throw when called with source content string', () => {
+    expect(() => extractSymbols('/fake/file.js', 'function hello() {}')).not.toThrow();
+  });
+
+  it('returns a value', () => {
+    const result = extractSymbols('/fake/path/file.js');
+    expect(result).toBeDefined();
+  });
+});
+
+describe('buildDependencyGraph', () => {
+  it('is a function', () => {
+    expect(typeof buildDependencyGraph).toBe('function');
+  });
+
+  it('does not throw when called with an empty array', () => {
+    expect(() => buildDependencyGraph([])).not.toThrow();
+  });
+
+  it('does not throw when called with null', () => {
+    expect(() => buildDependencyGraph(null)).not.toThrow();
+  });
+
+  it('does not throw when called with undefined', () => {
+    expect(() => buildDependencyGraph(undefined)).not.toThrow();
+  });
+
+  it('does not throw when called with an array of file paths', () => {
+    expect(() => buildDependencyGraph(['/fake/a.js', '/fake/b.js'])).not.toThrow();
+  });
+
+  it('returns a value', () => {
+    const result = buildDependencyGraph([]);
+    expect(result).toBeDefined();
+  });
+});