@activemind/scd 1.4.0

package/lib/rule-registry.js

@@ -0,0 +1,205 @@
+/**
+ * rule-registry.js
+ * Central catalogue of all Secure Code by Design rules.
+ *
+ * Normalises every rule into a consistent shape:
+ *   { id, name, severity, category, languages, matchMode, why, scenario, fix }
+ *
+ * Used by: scd rules (list/search/detail)
+ *          scd report (rule metadata in reports)
+ *          scd insights (category grouping)
+ */
+
+'use strict';
+
+// Rules bundle version – bump on rule additions/fixes (minor) or ID changes (major)
+// Independent of CLI version: scd 0.2.0 can ship with rules 1.3.0
+const RULES_VERSION = '1.2.0';
+
+const { loadRule }                                                = require('../rules/rule-loader');
+const _jsPack                                                     = require('../rules/rules-js.json');
+const JS_RULES                                                    = _jsPack.rules.filter(r => r.severity !== 'EXPOSURE').map(r => loadRule(r, 'builtin'));
+const JS_EXPOSURE                                                 = _jsPack.rules.filter(r => r.severity === 'EXPOSURE').map(r => loadRule(r, 'builtin'));
+const _tsPack                                                     = require('../rules/rules-ts.json');
+const TS_RULES                                                    = _tsPack.rules.map(r => loadRule(r, 'builtin'));
+const _pyPack                                                     = require('../rules/rules-python.json');
+const _phpPack                                                    = require('../rules/rules-php.json');
+const PY_RULES                                                    = _pyPack.rules.map(r => loadRule(r, 'builtin'));
+const PHP_RULES                                                   = _phpPack.rules.map(r => loadRule(r, 'builtin'));
+const PY_EXPOSURE                                                 = PY_RULES.filter(r => r.severity === 'EXPOSURE');
+const PHP_EXPOSURE                                                = PHP_RULES.filter(r => r.severity === 'EXPOSURE');
+const _aspxPack                                                   = require('../rules/rules-aspx.json');
+const _aspxCsPack                                                 = require('../rules/rules-aspx-cs.json');
+const ASPX_RULES                                                  = _aspxPack.rules.map(r => loadRule(r, 'builtin'));
+const ASPX_CS_RULES                                               = _aspxCsPack.rules.map(r => loadRule(r, 'builtin'));
+const _sensitivePack                                              = require('../rules/rules-sensitive-files.json');
+const _sensitiveRules                                             = _sensitivePack.rules.map(r => loadRule(r, 'builtin'));
+const SF_CONTENT                                                  = _sensitiveRules.filter(r => r.matchMode !== 'filename');
+const SF_FILENAME                                                 = _sensitiveRules.filter(r => r.matchMode === 'filename');
+const _infraPack                                                  = require('../rules/rules-infra-leakage.json');
+const ALL_INFRA_RULES                                             = _infraPack.rules.map(r => loadRule(r, 'builtin'));
+const { loadPack }                                                = require('../rules/rule-loader');
+const _secretsPack                                                = require('../rules/rules-secrets.json');
+const SECRET_RULES                                                = loadPack(_secretsPack);
+
+// ── Language tags per rule source ──────────────────────────────────────────
+
+const SOURCES = [
+  { rules: JS_RULES,     languages: ['js', 'ts', 'mjs', 'cjs', 'jsx', 'tsx'] },
+  { rules: JS_EXPOSURE,  languages: ['js', 'ts', 'mjs', 'cjs', 'jsx', 'tsx', 'html', 'php', 'py'] },
+  { rules: TS_RULES,     languages: ['ts', 'tsx'] },
+  { rules: PY_RULES,     languages: ['py'] },
+  { rules: PY_EXPOSURE,  languages: ['py'] },
+  { rules: PHP_RULES,    languages: ['php'] },
+  { rules: PHP_EXPOSURE, languages: ['php'] },
+  { rules: ASPX_RULES,   languages: ['aspx', 'ascx', 'cs'] },
+  { rules: ASPX_CS_RULES,languages: ['cs'] },
+  { rules: SF_CONTENT,   languages: null },   // fileTypes on each rule
+  { rules: SF_FILENAME,  languages: null },   // filename-match rules
+  { rules: ALL_INFRA_RULES, languages: ['all'] },
+  { rules: SECRET_RULES, languages: ['all'] },
+];
+
+// ── Severity sort order ────────────────────────────────────────────────────
+
+const SEV_ORDER = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, EXPOSURE: 3, LOW: 4 };
+
+// ── Build normalised registry ──────────────────────────────────────────────
+
+function buildRegistry() {
+  const seen = new Set();
+  const registry = [];
+
+  for (const { rules, languages } of SOURCES) {
+    if (!rules) continue;
+    for (const rule of rules) {
+      if (seen.has(rule.id)) continue;   // dedup (e.g. EXPOSURE rules appear in multiple sets)
+      seen.add(rule.id);
+
+      // Determine languages for this rule
+      let langs;
+      if (languages) {
+        langs = languages;
+      } else if (rule.fileTypes) {
+        langs = rule.fileTypes;
+      } else {
+        langs = ['all'];
+      }
+
+      registry.push({
+        id:        rule.id,
+        name:      rule.name,
+        severity:  rule.severity,
+        category:  rule.category  || 'Uncategorised',
+        languages: langs,
+        matchMode: rule.matchMode === 'filename' || rule.filenamePattern ? 'filename' : 'content',
+        why:       rule.why       || null,
+        scenario:  rule.scenario  || null,
+        fix:       rule.fix       || null,
+        checklist: rule.checklist || null,
+      });
+    }
+  }
+
+  // Sort: severity → id prefix → numeric suffix
+  registry.sort((a, b) => {
+    const sevDiff = (SEV_ORDER[a.severity] ?? 9) - (SEV_ORDER[b.severity] ?? 9);
+    if (sevDiff !== 0) return sevDiff;
+    return a.id.localeCompare(b.id, undefined, { numeric: true });
+  });
+
+  return registry;
+}
+
+// Lazy singleton
+let _registry = null;
+function getRegistry() {
+  if (!_registry) _registry = buildRegistry();
+  return _registry;
+}
+
+/**
+ * Look up a single rule by ID, including compiled pattern and antipattern.
+ * Used by export-findings (review-rules) to include rule internals in output.
+ * Returns the compiled rule object from the first matching source, or null.
+ */
+function getRuleById(id) {
+  const allSources = [
+    JS_RULES, JS_EXPOSURE,
+    TS_RULES,
+    PY_RULES, PY_EXPOSURE,
+    PHP_RULES, PHP_EXPOSURE,
+    ASPX_RULES, ASPX_CS_RULES,
+    SF_CONTENT, SF_FILENAME,
+    ALL_INFRA_RULES,
+    SECRET_RULES,
+  ];
+  for (const source of allSources) {
+    if (!Array.isArray(source)) continue;
+    const rule = source.find(r => r.id === id);
+    if (rule) return rule;
+  }
+  return null;
+}
+
+// ── Query helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Filter registry by options.
+ * @param {{ lang, severity, id, search }} opts
+ */
+function queryRules({ lang, severity, id, search } = {}) {
+  let rules = getRegistry();
+
+  if (id) {
+    return rules.filter(r => r.id.toLowerCase() === id.toLowerCase());
+  }
+
+  if (lang) {
+    const langs = lang.split(',').map(l => l.trim().toLowerCase());
+    rules = rules.filter(r =>
+      r.languages.includes('all') ||
+      r.languages.some(l => langs.includes(l.toLowerCase()))
+    );
+  }
+
+  if (severity) {
+    const sev = severity.toUpperCase();
+    rules = rules.filter(r => r.severity === sev);
+  }
+
+  if (search) {
+    const q = search.toLowerCase();
+    rules = rules.filter(r =>
+      r.id.toLowerCase().includes(q) ||
+      r.name.toLowerCase().includes(q) ||
+      r.category.toLowerCase().includes(q) ||
+      (r.why      && r.why.toLowerCase().includes(q)) ||
+      (r.fix      && r.fix.toLowerCase().includes(q))
+    );
+  }
+
+  return rules;
+}
+
+/**
+ * Stats summary across all (or filtered) rules.
+ */
+function getStats(rules) {
+  rules = rules || getRegistry();
+  const bySeverity = {};
+  const byLanguage = {};
+  const byCategory = {};
+
+  for (const r of rules) {
+    bySeverity[r.severity] = (bySeverity[r.severity] || 0) + 1;
+    for (const l of r.languages) {
+      byLanguage[l] = (byLanguage[l] || 0) + 1;
+    }
+    byCategory[r.category] = (byCategory[r.category] || 0) + 1;
+  }
+
+  return { total: rules.length, bySeverity, byLanguage, byCategory };
+}
+
+module.exports = { getRegistry, getRuleById, queryRules, getStats, SEV_ORDER, RULES_VERSION };

package/lib/scan-cache.js

@@ -0,0 +1,171 @@
+/**
+ * scan-cache.js
+ * Saves and loads scan data.
+ *
+ * Each scan is saved as an individual file in:
+ *   ~/.scd/repos/{repoId}/scans/{scanId}.json
+ *
+ * last-scan.json is kept as a copy of the latest scan for backwards
+ * compatibility with scd report (no flags needed for the common case).
+ *
+ * Scan files are never overwritten — a new scanId is generated per run.
+ * Deep analysis results are stored alongside findings in the same file.
+ */
+
+'use strict';
+const { RESET, DIM } = require('./output-constants');
+
+const fs           = require('fs');
+const store        = require('./store');
+const { validateScan } = require('./scan-schema');
+
+// ── Scan ID ────────────────────────────────────────────────────────────────
+
+/**
+ * Generate a short random scan ID.
+ * Format: s-{8 hex chars}  e.g. s-a3f9b2c1
+ *
+ * Deliberately not date/time-based — avoids timezone confusion.
+ * The actual scan timestamp lives in the file's scanDate field.
+ * Same ID is used as session_id on the server for full traceability.
+ */
+function makeScanId() {
+  const crypto = require('crypto');
+  return 's-' + crypto.randomBytes(4).toString('hex');
+}
+
+
+// ── Build exclusions summary for scan JSON ─────────────────────────────────
+
+/**
+ * Build the exclusions field for the scan JSON payload.
+ * Combines file exclusion metadata (from scanner-manual) with rule exclusion
+ * counts (from scanner-full._ruleExclusionCounts).
+ *
+ * Returns null if no exclusions were active.
+ */
+function buildExclusionsSummary(scopeExclusions, findings) {
+  if (!scopeExclusions) return null;
+
+  const ruleExclusionCounts = findings?._ruleExclusionCounts || {};
+
+  const ruleExcludes = (scopeExclusions.rule_excludes || []).map(e => ({
+    rule:              e.rule,
+    files:             e.files || null,
+    findings_excluded: ruleExclusionCounts[e.rule] || 0,
+    source:            e._source || 'repo',
+    reason:            e.reason  || null,
+    added_by:          e.added_by || null,
+    added_at:          e.added_at || null,
+  }));
+
+  const fileExcludes = (scopeExclusions.file_excludes || []).map(e => ({
+    pattern:        e.pattern,
+    files_excluded: scopeExclusions.files_excluded || 0,
+    source:         e._source || 'repo',
+    reason:         e.reason  || null,
+    added_by:       e.added_by || null,
+    added_at:       e.added_at || null,
+  }));
+
+  return {
+    files_excluded: scopeExclusions.files_excluded || 0,
+    file_excludes:  fileExcludes,
+    rule_excludes:  ruleExcludes,
+  };
+}
+
+// ── Save ───────────────────────────────────────────────────────────────────
+
+/**
+ * Save scan results to the per-repo scans directory.
+ * Accepts an optional scanId — if not provided, generates a new one.
+ * Always returns the scanId used (pass it to logScan for consistency).
+ */
+function saveCache(repoRoot, data, scanId) {
+  try {
+    const id       = scanId || makeScanId();
+    const scanDate = data.scanDate || new Date();
+
+    store.updateMeta(repoRoot, {
+      findingCount:  (data.findings || []).length,
+      criticalCount: (data.findings || []).filter(f => f.severity === 'CRITICAL').length,
+    });
+
+    const { getMachineFingerprint } = require('./store');
+    const os = require('os');
+
+    const payload = {
+      scanId:          id,
+      scanDate:        scanDate instanceof Date ? scanDate.toISOString() : scanDate,
+      installation_id: getMachineFingerprint(),
+      hostname:        os.hostname(),
+      target:          data.target      || '.',
+      totalFiles:      data.totalFiles  || 0,
+      skipped:         data.skipped     || [],
+      findings:            (data.findings            || []).filter(f => f.ruleId),
+      suppressed_findings: (data.suppressed_findings || []).filter(f => f.ruleId),
+      deepResults:     data.deepResults || null,
+      hasDeep:         !!(data.deepResults && data.deepResults.length > 0),
+      repoRoot:        data.repoRoot    || null,
+      scanMode:        data.scanMode    || 'full',
+      exclusions:      buildExclusionsSummary(data.scopeExclusions, data.findings),
+    };
+
+    validateScan(payload, 'saveCache');
+
+    const json = JSON.stringify(payload, null, 2);
+
+    // Save as individual scan file (never overwritten)
+    fs.writeFileSync(store.scanPath(repoRoot, id), json, { encoding: 'utf8', mode: 0o600 });
+
+    // Keep last-scan.json as a copy for backwards compatibility
+    fs.writeFileSync(store.scanCachePath(repoRoot), json, { encoding: 'utf8', mode: 0o600 });
+
+    return id;
+  } catch (err) {
+    console.error(`${DIM}[sc] Scan save warning: ${err.message}${RESET}`);
+    return null;
+  }
+}
+
+// ── Load ───────────────────────────────────────────────────────────────────
+
+function loadCache(repoRoot) {
+  const cachePath = store.scanCachePath(repoRoot);
+  if (!fs.existsSync(cachePath)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+    if (!Array.isArray(data.findings)) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+function loadScan(repoRoot, scanId) {
+  const scanFile = store.scanPath(repoRoot, scanId);
+  if (!fs.existsSync(scanFile)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(scanFile, 'utf8'));
+    if (!Array.isArray(data.findings)) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+// ── Human-readable age ─────────────────────────────────────────────────────
+
+function cacheAge(isoDate) {
+  const diff  = Date.now() - new Date(isoDate).getTime();
+  const mins  = Math.floor(diff / 60000);
+  const hours = Math.floor(mins  / 60);
+  const days  = Math.floor(hours / 24);
+  if (days  > 0) return `${days} day${days   > 1 ? 's' : ''} ago`;
+  if (hours > 0) return `${hours} hour${hours > 1 ? 's' : ''} ago`;
+  if (mins  > 0) return `${mins} minute${mins > 1 ? 's' : ''} ago`;
+  return 'just now';
+}
+
+module.exports = { saveCache, loadCache, loadScan, cacheAge, makeScanId };

package/lib/scan-context.js

@@ -0,0 +1,312 @@
+'use strict';
+const { RESET, BOLD, DIM, RED, YELLOW, CYAN } = require('./output-constants');
+
+/**
+ * lib/scan-context.js
+ *
+ * Resolves the correct repository context for a manual scan.
+ *
+ * Problem: scd scan always used CWD as repo context, regardless of where
+ * the scan target was. Scanning a file outside the current repo would
+ * contaminate the wrong repo with findings, or create a spurious new repo
+ * entry in the scd store.
+ *
+ * Solution: determine context from the target, not CWD. If the target is
+ * outside any known git repo, prompt the user rather than silently
+ * creating a bad repo entry.
+ *
+ * Non-interactive use:
+ * - No TTY detected: automatically scans without logging (pipeline-safe default).
+ * - --log-to none:    always skip logging, no prompt.
+ * - --log-to current: log to CWD repo, no prompt (for cron/scheduled tasks).
+ * - --log-to target:  log to target repo, no prompt (for cron/scheduled tasks).
+ */
+
+const path        = require('path');
+const fs          = require('fs');
+const { execSync } = require('child_process');
+const readline    = require('readline');
+
+/**
+ * Find the git root for a given path (file or directory).
+ * Returns null if the path is not inside a git repo.
+ */
+function findGitRoot(targetPath) {
+  try {
+    const dir = fs.existsSync(targetPath) && fs.statSync(targetPath).isDirectory()
+      ? targetPath
+      : path.dirname(targetPath);
+
+    return execSync('git rev-parse --show-toplevel', {
+      cwd: dir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ask the user a question and return their answer.
+ */
+function prompt(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(question, answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Resolve the repo context for a manual scan.
+ *
+ * @param {string[]} targetList  — resolved absolute paths of scan targets
+ * @param {string}   cwdRepoRoot — git root of CWD (may be null)
+ * @param {object}   opts
+ * @param {string}   opts.logTo  — 'none' | 'current' | 'target' | undefined
+ *
+ * @returns {Promise<{
+ *   repoRoot: string|null,    — the repo root to use for logging/config
+ *   skipLogging: boolean,     — if true: no audit log, no server push
+ *   cancelled: boolean,       — if true: user chose to cancel
+ * }>}
+ */
+async function resolveTargetContext(targetList, cwdRepoRoot, { logTo } = {}) {
+  // ── Non-interactive / --log-to handling ──────────────────────────────────
+  // Resolved before any prompts or git root discovery so pipelines exit fast.
+  const isInteractive = !!process.stdin.isTTY;
+
+  if (logTo === 'none') {
+    return { repoRoot: null, skipLogging: true, cancelled: false };
+  }
+
+  if (logTo === 'current') {
+    if (!cwdRepoRoot) {
+      process.stderr.write(`${RED}  --log-to current: current directory is not a known scd repo.${RESET}\n`);
+      process.stderr.write(`  Run ${CYAN}scd init${RESET} first, or use ${CYAN}--log-to none${RESET}.\n\n`);
+      process.exit(1);
+    }
+    return { repoRoot: cwdRepoRoot, skipLogging: false, cancelled: false };
+  }
+
+  if (!isInteractive && !logTo) {
+    // No TTY and no explicit --log-to: pipeline-safe default — scan without logging.
+    // Use --log-to current|target to log results from a non-interactive context.
+    process.stderr.write(`${DIM}ℹ Non-interactive mode: scanning without logging. Use --log-to current|target to log results.${RESET}\n`);
+    return { repoRoot: null, skipLogging: true, cancelled: false };
+  }
+  // ── end non-interactive handling ─────────────────────────────────────────
+
+  // Find git roots for all targets
+  const targetRoots = new Set();
+  for (const t of targetList) {
+    const root = findGitRoot(path.resolve(t));
+    if (root) targetRoots.add(root);
+  }
+
+  // Case A: all targets share the same git root as CWD — normal flow
+  if (cwdRepoRoot && targetRoots.size === 1 && targetRoots.has(cwdRepoRoot)) {
+    return { repoRoot: cwdRepoRoot, skipLogging: false, cancelled: false };
+  }
+
+  // Case B: targets are inside a different (but known) git repo
+  // e.g. scd scan ~/other-project/file.js from inside ~/my-project
+  if (targetRoots.size === 1) {
+    const targetRoot = [...targetRoots][0];
+    if (targetRoot !== cwdRepoRoot) {
+
+      // --log-to target: use target repo, no prompt
+      if (logTo === 'target') {
+        return { repoRoot: targetRoot, skipLogging: false, cancelled: false };
+      }
+
+      console.log(`\n${YELLOW}⚠️  Scan target is in a different repository than your current directory.${RESET}`);
+      console.log(`${DIM}  CWD repo:    ${cwdRepoRoot || '(none)'}${RESET}`);
+      console.log(`${DIM}  Target repo: ${targetRoot}${RESET}\n`);
+
+      const cwdName    = cwdRepoRoot ? path.basename(cwdRepoRoot) : null;
+      const targetName = path.basename(targetRoot);
+
+      console.log(`  How would you like to proceed?\n`);
+      console.log(`  ${CYAN}[1]${RESET} Log results to target repo ${DIM}(${targetName} — recommended)${RESET}`);
+      if (cwdRepoRoot) {
+        console.log(`  ${CYAN}[2]${RESET} Log results to current repo ${DIM}(${cwdName})${RESET}`);
+        console.log(`  ${CYAN}[3]${RESET} Scan without logging ${DIM}(results shown only, nothing saved)${RESET}`);
+        console.log(`  ${CYAN}[4]${RESET} Cancel`);
+      } else {
+        console.log(`  ${CYAN}[2]${RESET} Scan without logging ${DIM}(results shown only, nothing saved)${RESET}`);
+        console.log(`  ${CYAN}[3]${RESET} Cancel`);
+      }
+
+      const choice = (await prompt(`\n  Choice [1]: `)).trim() || '1';
+
+      const cancelChoice = cwdRepoRoot ? '4' : '3';
+      const noLogChoice  = cwdRepoRoot ? '3' : '2';
+
+      if (choice === cancelChoice || choice.toLowerCase() === 'cancel' || choice.toLowerCase() === 'q') {
+        return { repoRoot: null, skipLogging: true, cancelled: true };
+      }
+      if (choice === noLogChoice) {
+        return { repoRoot: null, skipLogging: true, cancelled: false };
+      }
+      if (choice === '2' && cwdRepoRoot) {
+        console.log(`${DIM}  Logging results to current repo: ${cwdName}${RESET}\n`);
+        return { repoRoot: cwdRepoRoot, skipLogging: false, cancelled: false };
+      }
+      // Default / choice 1: use target repo
+      return { repoRoot: targetRoot, skipLogging: false, cancelled: false };
+    }
+  }
+
+  // Case C: targets span multiple git repos — warn and use CWD if available
+  if (targetRoots.size > 1) {
+    console.log(`\n${YELLOW}⚠️  Scan targets span multiple repositories.${RESET}`);
+    console.log(`${DIM}  Results will be logged to the current repo context.${RESET}\n`);
+    return { repoRoot: cwdRepoRoot, skipLogging: !cwdRepoRoot, cancelled: false };
+  }
+
+  // Case D: target is outside any git repo
+
+  const targetDisplay = targetList.length === 1
+    ? path.resolve(targetList[0])
+    : `${targetList.length} targets`;
+
+  // --log-to target: no git repo found for target — warn and fall back to none
+  if (logTo === 'target') {
+    process.stderr.write(`${YELLOW}  --log-to target: scan target is outside any git repo. Scanning without logging.${RESET}\n`);
+    return { repoRoot: null, skipLogging: true, cancelled: false };
+  }
+
+  console.log(`\n${YELLOW}⚠️  Scan target is outside any known repository.${RESET}`);
+  console.log(`${DIM}  Target: ${targetDisplay}${RESET}`);
+  console.log(`${DIM}  CWD:    ${process.cwd()}${cwdRepoRoot ? '' : ' (no scd repo)'}${RESET}\n`);
+
+  console.log(`  How would you like to proceed?\n`);
+  console.log(`  ${CYAN}[1]${RESET} Scan without logging ${DIM}(results shown only, nothing saved)${RESET}`);
+  if (cwdRepoRoot) {
+    console.log(`  ${CYAN}[2]${RESET} Log results to current repo ${DIM}(${path.basename(cwdRepoRoot)})${RESET}`);
+    console.log(`  ${CYAN}[3]${RESET} Cancel`);
+  } else {
+    console.log(`  ${CYAN}[2]${RESET} Cancel`);
+  }
+
+  const maxChoice = cwdRepoRoot ? 3 : 2;
+  const cancelChoice = cwdRepoRoot ? '3' : '2';
+
+  const answer = await prompt(`\n  Choice [1]: `);
+  const choice = answer === '' ? '1' : answer;
+
+  if (choice === cancelChoice || choice === 'cancel' || choice === 'q') {
+    return { repoRoot: null, skipLogging: true, cancelled: true };
+  }
+
+  if (choice === '2' && cwdRepoRoot) {
+    // Log to CWD repo
+    return { repoRoot: cwdRepoRoot, skipLogging: false, cancelled: false };
+  }
+
+  // Default / choice 1: scan without logging
+  return { repoRoot: null, skipLogging: true, cancelled: false };
+}
+
+/**
+ * Read all known scd repo paths from ~/.scd/repos/{repoId}/meta.json.
+ * Returns array of { repoId, name, localPath } for repos with a known localPath.
+ */
+function getKnownRepoPaths() {
+  try {
+    const os        = require('os');
+    const reposDir  = path.join(os.homedir(), '.scd', 'repos');
+    if (!fs.existsSync(reposDir)) return [];
+
+    return fs.readdirSync(reposDir)
+      .map(id => {
+        try {
+          const meta = JSON.parse(fs.readFileSync(path.join(reposDir, id, 'meta.json'), 'utf8'));
+          return meta.localPath ? { repoId: id, name: meta.name || id, localPath: meta.localPath } : null;
+        } catch { return null; }
+      })
+      .filter(Boolean);
+  } catch { return []; }
+}
+
+/**
+ * Check if repoRoot overlaps with any known scd repo (parent or child).
+ * Returns array of overlapping repos: { repoId, name, localPath, relation }
+ * where relation is 'parent' or 'child'.
+ */
+function findOverlappingRepos(repoRoot, excludeRepoId = null) {
+  const known   = getKnownRepoPaths();
+  const absRoot = path.resolve(repoRoot);
+  const sep     = path.sep;
+
+  return known
+    .filter(r => r.repoId !== excludeRepoId)
+    .filter(r => {
+      const absKnown = path.resolve(r.localPath);
+      if (absKnown === absRoot) return false; // same repo — skip
+
+      const rootWithSep  = absRoot.endsWith(sep)  ? absRoot  : absRoot  + sep;
+      const knownWithSep = absKnown.endsWith(sep) ? absKnown : absKnown + sep;
+
+      const isChild  = absKnown.startsWith(rootWithSep);   // known is inside current
+      const isParent = absRoot.startsWith(knownWithSep);   // current is inside known
+
+      if (isChild)  { r.relation = 'child';  return true; }
+      if (isParent) { r.relation = 'parent'; return true; }
+      return false;
+    });
+}
+
+/**
+ * Warn the user if the resolved repoRoot overlaps with another known scd repo.
+ * Returns { proceed: bool, skipLogging: bool, cancelled: bool }.
+ *
+ * For hook mode (interactive=false): warn but always proceed — hooks can't prompt.
+ * For non-interactive mode (no TTY): warn but always proceed — same as hook mode.
+ */
+async function checkRepoOverlap(repoRoot, { interactive = true, repoId = null } = {}) {
+  const overlaps = findOverlappingRepos(repoRoot, repoId);
+  if (overlaps.length === 0) return { proceed: true, skipLogging: false, cancelled: false };
+
+  const children = overlaps.filter(r => r.relation === 'child');
+  const parents  = overlaps.filter(r => r.relation === 'parent');
+
+  console.log(`\n${YELLOW}⚠️  This repo overlaps with another scd repository.${RESET}`);
+  console.log(`${DIM}  Current scan: ${repoRoot}${RESET}`);
+
+  for (const r of parents)  console.log(`${DIM}  Parent repo:  ${r.localPath} (${r.name})${RESET}`);
+  for (const r of children) console.log(`${DIM}  Child repo:   ${r.localPath} (${r.name})${RESET}`);
+
+  if (children.length > 0) {
+    console.log(`\n${DIM}  Scanning from here will include files already tracked in the child repo,${RESET}`);
+    console.log(`${DIM}  potentially duplicating findings in scd-server.${RESET}`);
+  }
+  if (parents.length > 0) {
+    console.log(`\n${DIM}  This repo is nested inside another scd repo — findings may appear twice.${RESET}`);
+  }
+
+  // Hook mode or no TTY — can't prompt, warn and proceed
+  if (!interactive || !process.stdin.isTTY) {
+    console.log(`${YELLOW}  Continuing scan (non-interactive — cannot prompt).${RESET}\n`);
+    return { proceed: true, skipLogging: false, cancelled: false };
+  }
+
+  console.log(`\n  How would you like to proceed?\n`);
+  console.log(`  ${CYAN}[1]${RESET} Continue anyway`);
+  console.log(`  ${CYAN}[2]${RESET} Scan without logging ${DIM}(results shown only, nothing saved)${RESET}`);
+  console.log(`  ${CYAN}[3]${RESET} Cancel`);
+
+  const choice = (await prompt(`\n  Choice [1]: `)).trim() || '1';
+
+  if (choice === '3' || choice.toLowerCase() === 'cancel') {
+    return { proceed: false, skipLogging: true, cancelled: true };
+  }
+  if (choice === '2') {
+    return { proceed: true, skipLogging: true, cancelled: false };
+  }
+  return { proceed: true, skipLogging: false, cancelled: false };
+}
+
+module.exports = { resolveTargetContext, findGitRoot, checkRepoOverlap, findOverlappingRepos };