@manukyalo/scopelock 2.2.0 → 3.0.0

package/src/blast.js

@@ -0,0 +1,160 @@
+'use strict';
+
+/**
+ * src/blast.js
+ *
+ * Cross-File Blast Radius Map.
+ *
+ * Given a file path, scan the entire repo for any file that imports or
+ * requires it. Returns an array of dependent file paths.
+ *
+ * Handles the following import patterns (JS/TS/Python/Go):
+ *   import ... from './path/to/file'
+ *   require('./path/to/file')
+ *   from './path/to/file' import ...   (Python)
+ *   import "./path/to/file"
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// Directories that are never part of the blast radius analysis.
+const IGNORED_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'out', 'coverage',
+  '.turbo', '.cache', '__pycache__', '.venv', 'venv', 'target',
+]);
+
+/**
+ * Recursively walk a directory and collect all files.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function walkDir(dir) {
+  const results = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') && entry.name !== '.') continue;
+    if (IGNORED_DIRS.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(full));
+    } else {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Generate all possible import path variants for a given target file.
+ * For example, given src/auth/token.ts, this yields:
+ *   ./token, ../auth/token, ../../src/auth/token, etc.
+ * We match against these from each candidate file's directory.
+ *
+ * @param {string} targetRelative  e.g. "src/auth/token.ts"
+ * @returns {string[]}  stem variants (without extension, for partial matching)
+ */
+function getTargetStems(targetRelative) {
+  const normalized = targetRelative.replace(/\\/g, '/');
+  const noExt = normalized.replace(/\.[^.]+$/, '');
+  return [normalized, noExt];
+}
+
+/**
+ * Check if a file's content contains an import/require of the target.
+ *
+ * @param {string} fileContent
+ * @param {string[]} targetStems
+ * @param {string} fileDir       Absolute directory of the importing file
+ * @param {string} repoRoot      Absolute repo root
+ * @param {string} targetAbsolute Absolute path of the target file
+ * @returns {boolean}
+ */
+function fileImportsTarget(fileContent, targetAbsolute, fileDir) {
+  // Extract all quoted string literals that look like import paths
+  const importPathRe = /(?:from|import|require)\s*\(?['"]([^'"]+)['"]\)?/g;
+  let match;
+  while ((match = importPathRe.exec(fileContent)) !== null) {
+    const importPath = match[1];
+    // Only resolve relative paths; skip node_module specifiers
+    if (!importPath.startsWith('.')) continue;
+    try {
+      const resolved = path.resolve(fileDir, importPath);
+      // Match with or without extension
+      const targetNoExt = targetAbsolute.replace(/\.[^.]+$/, '');
+      if (
+        resolved === targetAbsolute ||
+        resolved === targetNoExt ||
+        resolved + path.extname(targetAbsolute) === targetAbsolute
+      ) {
+        return true;
+      }
+    } catch {
+      // If resolution fails, skip
+    }
+  }
+  return false;
+}
+
+/**
+ * Compute the full blast radius for a given file.
+ *
+ * @param {string} targetFile  Relative or absolute path to the file.
+ * @returns {{ target: string, dependents: string[], total: number }}
+ */
+function blastRadius(targetFile) {
+  const repoRoot    = process.cwd();
+  const targetAbs   = path.resolve(repoRoot, targetFile);
+  const targetRel   = path.relative(repoRoot, targetAbs).replace(/\\/g, '/');
+  const allFiles    = walkDir(repoRoot);
+  const dependents  = [];
+
+  for (const f of allFiles) {
+    // Skip the target itself
+    if (path.resolve(f) === targetAbs) continue;
+
+    let content;
+    try {
+      content = fs.readFileSync(f, 'utf8');
+    } catch {
+      continue;
+    }
+
+    if (fileImportsTarget(content, targetAbs, path.dirname(f))) {
+      dependents.push(path.relative(repoRoot, f).replace(/\\/g, '/'));
+    }
+  }
+
+  return { target: targetRel, dependents, total: dependents.length };
+}
+
+/**
+ * Print a human-readable blast radius report to stdout.
+ *
+ * @param {string} targetFile
+ */
+function printBlastRadius(targetFile) {
+  const { target, dependents, total } = blastRadius(targetFile);
+
+  console.log(`\n💥  Blast Radius: ${target}\n`);
+
+  if (total === 0) {
+    console.log('   No other files import this file. Safe to modify.\n');
+    return;
+  }
+
+  console.log(`   ${total} file(s) directly import this file:\n`);
+  for (const dep of dependents) {
+    console.log(`   → ${dep}`);
+  }
+  console.log('');
+  console.log(`   ⚠️  Modifying '${target}' may impact all ${total} of the above file(s).`);
+  console.log(`   Run 'scopelock lock ${target}' to protect it before your session.\n`);
+}
+
+module.exports = { blastRadius, printBlastRadius };

package/src/git.js

@@ -1,166 +1,167 @@
-'use strict';
-
-/**
- * src/git.js
- *
- * Scope violation checker — V2.
- *
- * Two tiers of enforcement:
- *   1. File-level:     Any changed file whose manifest status is 'locked' → violation.
- *   2. Function-level: Any changed file that has locked functions →
- *                      parse the diff for changed line numbers, re-extract
- *                      function boundaries from the current file, and flag
- *                      any changed line that falls inside a locked function.
- *
- * Exits 1 if any violation found. Wireable as a pre-commit hook.
- */
-
-const { execSync }      = require('child_process');
-const { getManifest }   = require('./manifest');
-const { getChangedLines } = require('./diff');
-const { extractFunctions } = require('./parser');
-const { detectSecret }  = require('./secrets');
-
-function check(args = []) {
-  const requireTests = args.includes('--require-tests');
-  const manifest = getManifest();
-  let diffOutput;
-
-  try {
-    diffOutput = execSync('git diff HEAD --name-only', {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-  } catch (err) {
-    console.error('git error — are you inside a git repository with at least one commit?');
-    console.error(err.message);
-    process.exit(1);
-  }
-
-  const changedFiles = diffOutput
-    .split('\n')
-    .map(f => f.trim())
-    .filter(f => f.length > 0);
-
-  if (changedFiles.length === 0) {
-    console.log('✅ Scope check passed — no changes detected.');
-    return;
-  }
-
-  const violations = [];
-  
-  // ── Tier -1: Test Coverage Gate ───────────────────────────────────────────
-  if (requireTests) {
-    const hasSourceChanges = changedFiles.some(f => 
-      !f.includes('.test.') && !f.includes('.spec.') && !f.includes('/test/') && !f.includes('/__tests__/') &&
-      (f.endsWith('.js') || f.endsWith('.ts') || f.endsWith('.py') || f.endsWith('.go') || f.endsWith('.rs'))
-    );
-    const hasTestChanges = changedFiles.some(f => 
-      f.includes('.test.') || f.includes('.spec.') || f.includes('/test/') || f.includes('/__tests__/')
-    );
-    if (hasSourceChanges && !hasTestChanges) {
-      violations.push({
-        type: 'test-gate',
-        file: 'N/A',
-        message: 'TEST GATE VIOLATION: Source logic was modified, but no tests were added or updated. You must write tests to pass `--require-tests`.'
-      });
-    }
-  }
-
-  for (const file of changedFiles) {
-    const normalizedFile = file.replace(/\\/g, '/');
-    const entry          = manifest.files[normalizedFile];
-
-    const changedLines = getChangedLines(normalizedFile);
-
-    // ── Tier 0: Secret Sentinel ─────────────────────────────────────────────
-    if (changedLines.size > 0) {
-      // Check if this file has explicitly allowed secrets
-      const hasOverride = manifest.allowedSecrets && manifest.allowedSecrets[normalizedFile];
-      if (!hasOverride) {
-        for (const [lineNum, content] of changedLines.entries()) {
-          const secretType = detectSecret(content);
-          if (secretType) {
-            violations.push({
-              type: 'secret',
-              file: normalizedFile,
-              message: `SECRET LEAK [${secretType}] detected in '${normalizedFile}' on line ${lineNum}.`,
-            });
-            break; // One secret violation per file is enough
-          }
-        }
-      }
-    }
-
-    // ── Tier 1: File-level lock ─────────────────────────────────────────────
-    if (entry && entry.status === 'locked') {
-      violations.push({
-        type: 'file',
-        file: normalizedFile,
-        message: `File '${normalizedFile}' is LOCKED.`,
-      });
-      continue; // No need to check functions if the whole file is locked
-    }
-
-    // ── Tier 2: Function-level lock ─────────────────────────────────────────
-    if (!entry || !entry.functions) continue;
-
-    const lockedFunctions = Object.entries(entry.functions)
-      .filter(([, fnData]) => fnData.status === 'locked')
-      .map(([name]) => name);
-
-    if (lockedFunctions.length === 0) continue;
-
-    // Re-extract function boundaries from the current on-disk file
-    const currentFunctions = extractFunctions(normalizedFile);
-
-    for (const lockedFnName of lockedFunctions) {
-      const fn = currentFunctions.find(f => f.name === lockedFnName);
-      if (!fn) {
-        // Function was deleted or renamed — this itself is a violation
-        violations.push({
-          type:    'function-missing',
-          file:    normalizedFile,
-          fn:      lockedFnName,
-          message: `Locked function '${lockedFnName}' in '${normalizedFile}' was removed or renamed.`,
-        });
-        continue;
-      }
-
-      // Check if any changed line falls within the function's boundaries
-      for (const line of changedLines.keys()) {
-        if (line >= fn.startLine && line <= fn.endLine) {
-          violations.push({
-            type: 'function',
-            file: normalizedFile,
-            fn:   lockedFnName,
-            message:
-              `Locked function '${lockedFnName}' in '${normalizedFile}' was modified ` +
-              `(changed line ${line} is inside [${fn.startLine}–${fn.endLine}]).`,
-          });
-          break; // One violation per function is enough
-        }
-      }
-    }
-  }
-
-  // ── Report ────────────────────────────────────────────────────────────────
-  if (violations.length === 0) {
-    console.log('✅ Scope check passed — no locked files or functions were modified.');
-    return;
-  }
-
-  console.error(`\n❌ Scope violations detected:\n`);
-  for (const v of violations) {
-    console.error(`   VIOLATION: ${v.message}`);
-  }
-  console.error(
-    `\n${violations.length} violation(s) found.\n` +
-    `  • Revert unintentional changes with: git restore <file>\n` +
-    `  • Explicitly unlock with:            scopelock unlock <file>[:<function>] "<reason>"`
-  );
-
-  process.exit(1);
-}
-
-module.exports = { check };
+'use strict';
+
+/**
+ * src/git.js
+ *
+ * Scope violation checker — V2.
+ *
+ * Two tiers of enforcement:
+ *   1. File-level:     Any changed file whose manifest status is 'locked' → violation.
+ *   2. Function-level: Any changed file that has locked functions →
+ *                      parse the diff for changed line numbers, re-extract
+ *                      function boundaries from the current file, and flag
+ *                      any changed line that falls inside a locked function.
+ *
+ * Exits 1 if any violation found. Wireable as a pre-commit hook.
+ */
+
+const { execSync }      = require('child_process');
+const { getManifest }   = require('./manifest');
+const { getChangedLines } = require('./diff');
+const { extractFunctions } = require('./parser');
+const { detectSecret }  = require('./secrets');
+
+function guard(args = []) {
+  const requireTests = args.includes('--tests');
+  const manifest = getManifest();
+  let diffOutput;
+
+  try {
+    diffOutput = execSync('git diff HEAD --name-only', {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch (err) {
+    console.error('git error — are you inside a git repository with at least one commit?');
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  const changedFiles = diffOutput
+    .split('\n')
+    .map(f => f.trim())
+    .filter(f => f.length > 0);
+
+  if (changedFiles.length === 0) {
+    console.log('✅ Scope guard passed — no changes detected.');
+    return;
+  }
+
+  const violations = [];
+  
+  // ── Tier -1: Test Coverage Gate ───────────────────────────────────────────
+  if (requireTests) {
+    const hasSourceChanges = changedFiles.some(f => 
+      !f.includes('.test.') && !f.includes('.spec.') && !f.includes('/test/') && !f.includes('/__tests__/') &&
+      (f.endsWith('.js') || f.endsWith('.ts') || f.endsWith('.py') || f.endsWith('.go') || f.endsWith('.rs'))
+    );
+    const hasTestChanges = changedFiles.some(f => 
+      f.includes('.test.') || f.includes('.spec.') || f.includes('/test/') || f.includes('/__tests__/')
+    );
+    if (hasSourceChanges && !hasTestChanges) {
+      violations.push({
+        type: 'test-gate',
+        file: 'N/A',
+        message: 'TEST GATE VIOLATION: Source logic was modified, but no tests were added or updated. You must write tests to pass `--tests`.'
+      });
+    }
+  }
+
+  for (const file of changedFiles) {
+    const normalizedFile = file.replace(/\\/g, '/');
+    const entry          = manifest.files[normalizedFile];
+
+    const changedLines = getChangedLines(normalizedFile);
+
+    // ── Tier 0: Secret Sentinel ─────────────────────────────────────────────
+    if (changedLines.size > 0) {
+      // Check if this file has explicitly allowed secrets
+      const hasOverride = manifest.allowedSecrets && manifest.allowedSecrets[normalizedFile];
+      if (!hasOverride) {
+        for (const [lineNum, content] of changedLines.entries()) {
+          const secretType = detectSecret(content);
+          if (secretType) {
+            violations.push({
+              type: 'secret',
+              file: normalizedFile,
+              message: `SECRET LEAK [${secretType}] detected in '${normalizedFile}' on line ${lineNum}.`,
+            });
+            break; // One secret violation per file is enough
+          }
+        }
+      }
+    }
+
+    // ── Tier 1: File-level lock ─────────────────────────────────────────────
+    if (entry && (entry.status === 'locked' || entry.status === 'sealed')) {
+      const label = entry.status === 'sealed' ? 'SEALED' : 'LOCKED';
+      violations.push({
+        type: 'file',
+        file: normalizedFile,
+        message: `File '${normalizedFile}' is ${label}.`,
+      });
+      continue; // No need to check functions if the whole file is locked
+    }
+
+    // ── Tier 2: Function-level lock ─────────────────────────────────────────
+    if (!entry || !entry.functions) continue;
+
+    const lockedFunctions = Object.entries(entry.functions)
+      .filter(([, fnData]) => fnData.status === 'locked')
+      .map(([name]) => name);
+
+    if (lockedFunctions.length === 0) continue;
+
+    // Re-extract function boundaries from the current on-disk file
+    const currentFunctions = extractFunctions(normalizedFile);
+
+    for (const lockedFnName of lockedFunctions) {
+      const fn = currentFunctions.find(f => f.name === lockedFnName);
+      if (!fn) {
+        // Function was deleted or renamed — this itself is a violation
+        violations.push({
+          type:    'function-missing',
+          file:    normalizedFile,
+          fn:      lockedFnName,
+          message: `Locked function '${lockedFnName}' in '${normalizedFile}' was removed or renamed.`,
+        });
+        continue;
+      }
+
+      // Check if any changed line falls within the function's boundaries
+      for (const line of changedLines.keys()) {
+        if (line >= fn.startLine && line <= fn.endLine) {
+          violations.push({
+            type: 'function',
+            file: normalizedFile,
+            fn:   lockedFnName,
+            message:
+              `Locked function '${lockedFnName}' in '${normalizedFile}' was modified ` +
+              `(changed line ${line} is inside [${fn.startLine}–${fn.endLine}]).`,
+          });
+          break; // One violation per function is enough
+        }
+      }
+    }
+  }
+
+  // ── Report ────────────────────────────────────────────────────────────────
+  if (violations.length === 0) {
+    console.log('✅ Scope guard passed — no locked files or functions were modified.');
+    return;
+  }
+
+  console.error(`\n❌ Scope violations detected:\n`);
+  for (const v of violations) {
+    console.error(`   VIOLATION: ${v.message}`);
+  }
+  console.error(
+    `\n${violations.length} violation(s) found.\n` +
+    `  • Revert unintentional changes with: git restore <file>\n` +
+    `  • Explicitly unlock with:            scopelock unlock <file>[:<function>] "<reason>"`
+  );
+
+  process.exit(1);
+}
+
+module.exports = { guard };

package/src/manifest.js

@@ -177,6 +177,63 @@ function lock(target, reason = 'manually locked') {
   }
 }
 
+/**
+ * Seal a file — permanent, override-resistant production path lock.
+ * Cannot be removed by 'unlock'. Requires 'unseal' with a human-approved ticket.
+ *
+ * @param {string} file   File path
+ * @param {string} reason Mandatory reason string
+ */
+function seal(file, reason) {
+  const relativePath = file.replace(/\\/g, '/');
+  const manifest = getManifest();
+  ensureFileEntry(manifest, relativePath);
+  const entry = manifest.files[relativePath];
+
+  entry.status = 'sealed';
+  entry.history.push({
+    timestamp: new Date().toISOString(),
+    action:    'sealed',
+    reason,
+  });
+  saveManifest(manifest);
+  console.log(`🔐 SEALED ${relativePath}. Only 'scopelock unseal' with a human-approved ticket can release this.`);
+}
+
+/**
+ * Remove a seal from a file. Requires an explicit human-approved ticket string.
+ * This is the only command that can override a 'sealed' file.
+ *
+ * @param {string} file     File path
+ * @param {string} ticket   Human-approved ticket (e.g. "JIRA-123" or "PR-456")
+ * @param {string} reason   Mandatory reason string
+ */
+function unseal(file, ticket, reason) {
+  if (!ticket || !reason) {
+    console.error('Usage: scopelock unseal <file> --human-approved=<ticket> <reason>');
+    process.exit(1);
+  }
+  const relativePath = file.replace(/\\/g, '/');
+  const manifest = getManifest();
+  ensureFileEntry(manifest, relativePath);
+  const entry = manifest.files[relativePath];
+
+  if (entry.status !== 'sealed') {
+    console.error(`'${relativePath}' is not sealed. Use 'scopelock unlock' instead.`);
+    process.exit(1);
+  }
+
+  entry.status = 'active';
+  entry.history.push({
+    timestamp:     new Date().toISOString(),
+    action:        'unsealed',
+    humanApproved: ticket,
+    reason,
+  });
+  saveManifest(manifest);
+  console.log(`🔓 UNSEALED ${relativePath}. Ticket: ${ticket}. Reason: ${reason}`);
+}
+
 /**
  * Unlock a file or a specific function.
  *
@@ -206,6 +263,15 @@ function unlock(target, reason) {
     saveManifest(manifest);
     console.log(`🔓 Unlocked function '${funcName}' in ${relativePath}. Reason: ${reason}`);
   } else {
+    // Guard against bypassing a seal with a normal unlock
+    if (entry.status === 'sealed') {
+      console.error(
+        `❌ '${relativePath}' is SEALED and cannot be unlocked with 'scopelock unlock'.\n` +
+        `   This path is a protected production route.\n` +
+        `   Use: scopelock unseal ${relativePath} --human-approved=<ticket> <reason>`
+      );
+      process.exit(1);
+    }
     entry.status = 'active';
     entry.history.push(historyEntry);
     saveManifest(manifest);
@@ -220,9 +286,10 @@ function status() {
   const manifest = getManifest();
   const files    = Object.entries(manifest.files);
 
-  const locked   = files.filter(([, v]) => v.status === 'locked');
-  const active   = files.filter(([, v]) => v.status === 'active');
-  const unscoped = files.filter(([, v]) => v.status === 'unscoped');
+  const sealed      = files.filter(([, v]) => v.status === 'sealed');
+  const locked      = files.filter(([, v]) => v.status === 'locked');
+  const active      = files.filter(([, v]) => v.status === 'active');
+  const unscoped    = files.filter(([, v]) => v.status === 'unscoped');
 
   // Count locked functions across all files
   let lockedFnCount = 0;
@@ -232,10 +299,16 @@ function status() {
   }
 
   console.log(`\n📋  scopelock status\n`);
+  console.log(`  🛡️   sealed    — ${sealed.length} file(s)`);
   console.log(`  🔒  locked    — ${locked.length} file(s), ${lockedFnCount} function(s)`);
   console.log(`  ✏️   active    — ${active.length} file(s)`);
   console.log(`  ⬜  unscoped  — ${unscoped.length} file(s)\n`);
 
+  if (sealed.length > 0) {
+    console.log('\nSealed files:');
+    sealed.forEach(([f]) => console.log(`  ${f}`));
+  }
+
   if (locked.length > 0) {
     console.log(`Locked files:`);
     for (const [filePath, data] of locked) {
@@ -268,30 +341,20 @@ function status() {
 }
 
 /**
- * Allow a secret to be committed in a specific file.
+ * Trust a file to contain a mock secret, bypassing the Secret Sentinel.
  *
- * @param {string} file  "<file>"
- * @param {string} reason  Mandatory reason string.
+ * @param {string} file
+ * @param {string} reason
  */
-function allowSecret(file, reason) {
+function trust(file, reason) {
   const relativePath = file.replace(/\\/g, '/');
   const manifest = getManifest();
-  
-  if (!manifest.allowedSecrets) {
-    manifest.allowedSecrets = {};
-  }
-  
-  if (!manifest.allowedSecrets[relativePath]) {
-    manifest.allowedSecrets[relativePath] = [];
-  }
-  
-  manifest.allowedSecrets[relativePath].push({
+  manifest.allowedSecrets[relativePath] = {
     timestamp: new Date().toISOString(),
-    reason
-  });
-  
+    reason,
+  };
   saveManifest(manifest);
   console.log(`⚠️  Secret Sentinel bypassed for ${relativePath}. Reason: ${reason}`);
 }
 
-module.exports = { init, lock, unlock, allowSecret, status, getManifest, saveManifest };
+module.exports = { init, lock, unlock, seal, unseal, trust, status, getManifest, saveManifest };