jhste-skills 0.1.0

package/cli/guard/scanners/data-boundary-locality.mjs

@@ -0,0 +1,125 @@
+import {
+  hasPersistenceRead,
+  hasPersistenceWrite,
+  localWindow,
+  maskCommentsAndStrings,
+} from './utils.mjs';
+
+const scopeToken = /\b(userId|user\.id|accountId|orgId|tenantId|ownerId|workspaceId|teamId|projectId)\b/i;
+const loopPattern = /(forEach\s*\(|for\s*\([^)]*;|for\s*\(\s*const\s+.+\s+of\s+|\.map\s*\(|while\s*\()/i;
+
+function callWindow(maskedText, index, after = 900) {
+  const source = String(maskedText || '');
+  const open = source.indexOf('(', Number(index || 0));
+  if (open < 0 || open - Number(index || 0) > 120) return localWindow(source, index, 0, after);
+  let depth = 0;
+  const endLimit = Math.min(source.length, Number(index || 0) + after);
+  for (let cursor = open; cursor < endLimit; cursor += 1) {
+    if (source[cursor] === '(') depth += 1;
+    if (source[cursor] === ')') {
+      depth -= 1;
+      if (depth === 0) return source.slice(Number(index || 0), cursor + 1);
+    }
+  }
+  return localWindow(source, index, 0, after);
+}
+
+function statementWindow(text, index, before = 900, after = 900) {
+  const source = String(text || '');
+  const masked = maskCommentsAndStrings(source);
+  const anchor = Number(index || 0);
+  const min = Math.max(0, anchor - before);
+  let start = min;
+  for (let cursor = anchor - 1; cursor >= min; cursor -= 1) {
+    if (/[;{}]/u.test(masked[cursor])) {
+      start = cursor + 1;
+      break;
+    }
+  }
+  const max = Math.min(source.length, anchor + after);
+  let end = max;
+  for (let cursor = anchor; cursor < max; cursor += 1) {
+    if (masked[cursor] === ';') {
+      end = cursor + 1;
+      break;
+    }
+  }
+  return source.slice(start, end);
+}
+
+function collectPersistenceAccesses(text, { reads = true, writes = true } = {}) {
+  const source = String(text || '');
+  const masked = maskCommentsAndStrings(source);
+  const accesses = [];
+  const addMaskedCalls = (pattern) => {
+    for (const match of masked.matchAll(pattern)) {
+      accesses.push({
+        index: match.index || 0,
+        window: callWindow(masked, match.index || 0),
+      });
+    }
+  };
+  const addTextWindows = (pattern, before = 40, after = 700) => {
+    for (const match of source.matchAll(pattern)) {
+      accesses.push({
+        index: match.index || 0,
+        window: localWindow(source, match.index || 0, before, after),
+      });
+    }
+  };
+
+  if (reads) addMaskedCalls(/\bprisma\.\w+\.(find(?:Unique|First|Many)?|aggregate|count)\s*\(/gi);
+  if (writes) addMaskedCalls(/\bprisma\.\w+\.(create|update|delete|upsert)\s*\(/gi);
+  if (reads) addTextWindows(/\bSELECT\b[\s\S]{0,180}\bFROM\b/gi);
+  if (writes) addTextWindows(/\b(UPDATE\s+\w+\s+SET|DELETE\s+FROM|INSERT\s+INTO)\b/gi);
+  if (reads || writes) {
+    addMaskedCalls(/\b(pool|client|db|database)\.(query|execute|select|from|update|delete|insert)\b/gi);
+  }
+  return accesses;
+}
+
+function accessHasScopedPredicate(window) {
+  const codeWindow = maskCommentsAndStrings(window);
+  return ((/\bwhere\s*:/.test(codeWindow) && scopeToken.test(codeWindow))
+    || (/\bWHERE\b/i.test(window) && scopeToken.test(window)));
+}
+
+function hasScopedPersistencePredicate(text) {
+  return collectPersistenceAccesses(text).some((access) => accessHasScopedPredicate(access.window));
+}
+
+function hasPersistenceForOptions(text, { reads = true, writes = true } = {}) {
+  return (reads && hasPersistenceRead(text)) || (writes && hasPersistenceWrite(text));
+}
+
+export function hasUnscopedPersistenceAccess(text, options) {
+  const accesses = collectPersistenceAccesses(text, options);
+  if (accesses.length === 0) return hasPersistenceForOptions(text, options) && !hasScopedPersistencePredicate(text);
+  return accesses.some((access) => !accessHasScopedPredicate(access.window));
+}
+
+function hasWriteSafetyMarker(text) {
+  return /\b(transaction|batch|Promise\.allSettled|idempotenc|dedup|dedupe|upsert|ON CONFLICT|on conflict)\b/i.test(maskCommentsAndStrings(text));
+}
+
+function collectPersistenceWrites(text) {
+  return collectPersistenceAccesses(text, { reads: false, writes: true });
+}
+
+function writeStatementHasSafety(text, index) {
+  return hasWriteSafetyMarker(statementWindow(text, index));
+}
+
+export function hasLoopedWriteWithoutSafety(text) {
+  const masked = maskCommentsAndStrings(text);
+  return collectPersistenceWrites(text).some((access) => {
+    const nearby = localWindow(masked, access.index, 360, 160);
+    return loopPattern.test(nearby) && !writeStatementHasSafety(text, access.index);
+  });
+}
+
+export function hasWriteWithoutLocalSafety(text) {
+  const writes = collectPersistenceWrites(text);
+  if (writes.length === 0) return hasPersistenceWrite(text) && !hasWriteSafetyMarker(text);
+  return writes.some((access) => !writeStatementHasSafety(text, access.index));
+}

package/cli/guard/scanners/data-boundary.mjs

@@ -0,0 +1,237 @@
+import {
+  hasAuthContext,
+  hasMutationHandler,
+  hasPersistenceAccess,
+  hasPersistenceWrite,
+  hasReadHandler,
+  isCrawlerProducerPath,
+  isRouteLikePath,
+  isScriptPipelinePath,
+  isSourceCodePath,
+  lineAt,
+  violation,
+} from './utils.mjs';
+import {
+  hasLoopedWriteWithoutSafety,
+  hasUnscopedPersistenceAccess,
+  hasWriteWithoutLocalSafety,
+} from './data-boundary-locality.mjs';
+
+export function scanAuthzDataIsolation(relPath, text) {
+  if (!isRouteLikePath(relPath)) return [];
+  const out = [];
+  const hasDbAccess = hasPersistenceAccess(text);
+  const authContextVisible = hasAuthContext(text);
+  const unscopedAccessVisible = hasUnscopedPersistenceAccess(text);
+  const unscopedReadVisible = hasUnscopedPersistenceAccess(text, { reads: true, writes: false });
+  if (hasDbAccess && authContextVisible && unscopedAccessVisible && !hasReadHandler(text)) {
+    out.push(violation({
+      ruleId: 'authz.scope_not_visible',
+      severity: 'warning',
+      relPath,
+      symbol: 'authz-scope',
+      message: 'Route uses auth context and persistence but no obvious owner or tenant filter is visible; review data isolation before ship.',
+      confidence: 'low',
+    }));
+  }
+  if (hasDbAccess && hasReadHandler(text) && !authContextVisible) {
+    out.push(violation({
+      ruleId: 'authz.read_without_auth_context',
+      severity: 'warning',
+      relPath,
+      symbol: 'authz-read',
+      message: 'Read path touches persistence without obvious auth or permission context; confirm whether the route is intentionally public.',
+      confidence: 'low',
+    }));
+  }
+  if (hasDbAccess && hasReadHandler(text) && authContextVisible && unscopedReadVisible) {
+    out.push(violation({
+      ruleId: 'authz.read_scope_not_visible',
+      severity: 'warning',
+      relPath,
+      symbol: 'authz-read-scope',
+      message: 'Read path uses auth context and persistence but no obvious owner or tenant filter is visible; review data isolation before ship.',
+      confidence: 'low',
+    }));
+  }
+  if (hasDbAccess && hasMutationHandler(text) && !authContextVisible) {
+    out.push(violation({
+      ruleId: 'authz.mutation_without_auth_context',
+      severity: 'warning',
+      relPath,
+      symbol: 'authz-mutation',
+      message: 'Mutation path touches persistence without obvious auth or permission context; confirm whether the route is intentionally public.',
+      confidence: 'low',
+    }));
+  }
+  return out;
+}
+
+export function scanWriteSafety(relPath, text) {
+  const out = [];
+  const hasWrite = hasPersistenceWrite(text);
+  const unsafeLoopedWrite = hasLoopedWriteWithoutSafety(text);
+  const unsafeWrite = hasWriteWithoutLocalSafety(text);
+  const writeSafetyPath = isRouteLikePath(relPath)
+    || isScriptPipelinePath(relPath)
+    || /(^|\/)(repositories?|queries|db|database|migrations?)\//i.test(relPath);
+  if (writeSafetyPath
+    && hasWrite
+    && unsafeLoopedWrite) {
+    out.push(violation({
+      ruleId: 'write.loop_without_transaction',
+      severity: 'warning',
+      relPath,
+      symbol: 'write-loop',
+      message: 'Repeated writes appear inside a loop without an obvious transaction, batch, or dedupe strategy; review write safety before ship.',
+      confidence: 'low',
+    }));
+  }
+  if (isRouteLikePath(relPath)
+    && hasMutationHandler(text)
+    && hasWrite
+    && unsafeWrite) {
+    out.push(violation({
+      ruleId: 'write.mutation_retry_safety',
+      severity: 'warning',
+      relPath,
+      symbol: 'mutation-retry-safety',
+      message: 'Mutation route has no obvious idempotency, dedupe, or transaction marker; review duplicate execution and partial-write risk.',
+      confidence: 'low',
+    }));
+  }
+  return out;
+}
+
+export function scanApiContractCompatibility(relPath, text) {
+  if (!isRouteLikePath(relPath)) return [];
+  const out = [];
+  if (/\b(request\.json\(|req\.body\b|params\.[A-Za-z_$]|\bsearchParams\.get\(|new URLSearchParams\b)/.test(text)
+    && !/\b(safeParse|parseAsync|schema|z\.object|validate|validator|assert)\b/.test(text)) {
+    out.push(violation({
+      ruleId: 'contract.boundary_without_schema',
+      severity: 'warning',
+      relPath,
+      symbol: 'boundary-without-schema',
+      message: 'Route reads request body, params, or search params without an obvious schema or validator; review contract compatibility before ship.',
+      confidence: 'medium',
+    }));
+  }
+  if (/\b(Response\.json|NextResponse\.json|res\.json)\(\s*await\s+(?:prisma|db|client|pool)|\breturn\s+(?:await\s+)?(?:prisma|db|client|pool)\./.test(text)) {
+    out.push(violation({
+      ruleId: 'contract.raw_storage_response',
+      severity: 'warning',
+      relPath,
+      symbol: 'raw-storage-response',
+      message: 'Route appears to expose storage-shaped data directly; review DTO mapping and caller compatibility before ship.',
+      confidence: 'low',
+      relatedKey: 'raw-storage-response',
+    }));
+  }
+  return out;
+}
+
+export function scanSqlParameterBinding(relPath, text) {
+  if (!isSourceCodePath(relPath)) return [];
+  const out = [];
+  const rawSqlTemplate = /(?:(\b(?:sql|Prisma\.sql|db\.sql|pgSql))\s*)?`[^`]*(?:SELECT\s+[\s\S]{0,120}\s+FROM|INSERT\s+INTO|UPDATE\s+[A-Za-z_][\w.]*\s+SET|DELETE\s+FROM)[^`]*\$\{[^`]+`/gis;
+  const rawSqlConcat = /(?:query|execute)\s*\(\s*['"][^'"]*(?:SELECT\s+[\s\S]{0,120}\s+FROM|INSERT\s+INTO|UPDATE\s+[A-Za-z_][\w.]*\s+SET|DELETE\s+FROM)[^'"]*['"]\s*\+/isu;
+  const pythonFStringSql = /f["'][^"']*(?:SELECT\s+[\s\S]{0,120}\s+FROM|INSERT\s+INTO|UPDATE\s+[A-Za-z_][\w.]*\s+SET|DELETE\s+FROM)[^"']*\{[^"']+["']/isu;
+  const unsafeTemplate = [...text.matchAll(rawSqlTemplate)].some((match) => !match[1]);
+  const assembledQueryNames = new Set();
+  for (const match of text.matchAll(/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:`[^`]*(?:SELECT\s+[\s\S]{0,120}\s+FROM|INSERT\s+INTO|UPDATE\s+[A-Za-z_][\w.]*\s+SET|DELETE\s+FROM)[^`]*\$\{[^`]+`|['"][^'"]*(?:SELECT\s+[\s\S]{0,120}\s+FROM|INSERT\s+INTO|UPDATE\s+[A-Za-z_][\w.]*\s+SET|DELETE\s+FROM)[^'"]*['"]\s*\+)/gis)) {
+    assembledQueryNames.add(match[1]);
+  }
+  const assembledQueryExecuted = [...assembledQueryNames].some((name) => new RegExp(`\\b(?:query|execute)\\s*\\(\\s*${name}\\b`).test(text));
+  if (unsafeTemplate || rawSqlConcat.test(text) || pythonFStringSql.test(text) || assembledQueryExecuted) {
+    out.push(violation({
+      ruleId: 'sql.raw_interpolation',
+      severity: assembledQueryExecuted && !unsafeTemplate ? 'warning' : 'error',
+      relPath,
+      symbol: assembledQueryExecuted ? 'assembled-query-interpolation' : 'raw-sql-interpolation',
+      message: assembledQueryExecuted
+        ? 'SQL-like query string appears assembled before execution; verify placeholders are used instead of raw interpolation.'
+        : 'SQL-like string interpolation detected; use placeholders and pass values separately.',
+      confidence: assembledQueryExecuted && !unsafeTemplate ? 'medium' : 'high',
+    }));
+  }
+  return out;
+}
+
+export function scanPublicSafeError(relPath, text) {
+  if (!isRouteLikePath(relPath)) return [];
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  lines.forEach((line, index) => {
+    if (/\b(Response\.json|NextResponse\.json|res\.json)\b/.test(line)
+      && /\b(stack|error\.message|err\.message|cause|details)\b/i.test(line)) {
+      out.push(violation({
+        ruleId: 'error.public_raw_details',
+        severity: 'warning',
+        relPath,
+        line: index + 1,
+        symbol: 'public-error-details',
+        message: 'Public response appears to include raw error details; map to a stable public code and keep diagnostics internal.',
+        confidence: 'medium',
+      }));
+    }
+  });
+  for (const match of text.matchAll(/\b(Response\.json|NextResponse\.json|res\.json)\s*\(([\s\S]{0,360})\)/gu)) {
+    const expression = match[0];
+    if (!/\n/.test(expression)) continue;
+    if (/\b(stack|error\.message|err\.message|cause|details)\b/i.test(expression)) {
+      out.push(violation({
+        ruleId: 'error.public_raw_details',
+        severity: 'warning',
+        relPath,
+        line: lineAt(text, match.index || 0),
+        symbol: 'public-error-details',
+        message: 'Public response appears to include raw error details; map to a stable public code and keep diagnostics internal.',
+        confidence: 'medium',
+      }));
+    }
+  }
+  return out;
+}
+
+export function scanDbRowValidation(relPath, text) {
+  if (!isRouteLikePath(relPath)) return [];
+  const directStorageResponse = /\b(Response\.json|NextResponse\.json|res\.json)\(\s*await\s+(?:prisma|db|client|pool)\b/su;
+  const rawVariables = [...text.matchAll(/\bconst\s+([A-Za-z_$][\w$]*)\s*=\s*await\s+(?:prisma|db|client|pool)\b/gsu)].map((match) => match[1]);
+  const responseExpressions = [...text.matchAll(/\b(?:Response\.json|NextResponse\.json|res\.json)\(([\s\S]{0,300})\)/gu)].map((match) => match[1] || '');
+  const rawVariableReturned = rawVariables.some((name) => responseExpressions.some((expr) => new RegExp(`\\b${name}\\b`).test(expr)));
+  if (!directStorageResponse.test(text) && !rawVariableReturned) return [];
+  return [violation({
+    ruleId: 'database.raw_row_public_response',
+    severity: 'warning',
+    relPath,
+    symbol: 'raw-row-response',
+    message: 'Route appears to return storage-shaped data directly; validate or map rows before public DTO output.',
+    confidence: 'low',
+    relatedKey: 'raw-storage-response',
+  })];
+}
+
+export function scanThinApiRoute(relPath, text) {
+  if (!isRouteLikePath(relPath) || !hasPersistenceAccess(text)) return [];
+  return [violation({
+    ruleId: 'route.direct_db_access',
+    severity: 'warning',
+    relPath,
+    symbol: 'route-db-access',
+    message: 'Route/controller appears to contain direct persistence access; review whether auth, validation, usecase, repository, and response seams are thin enough.',
+    confidence: 'low',
+  })];
+}
+
+export function scanCrawlerProducerBoundary(relPath, text) {
+  if (!isCrawlerProducerPath(relPath) || !hasPersistenceWrite(text)) return [];
+  return [violation({
+    ruleId: 'crawler.producer_direct_persistence',
+    severity: 'warning',
+    relPath,
+    symbol: 'crawler-direct-write',
+    message: 'Crawler/automation producer appears to write directly to persistence; review artifact handoff and consumer-side validation before ship.',
+    confidence: 'low',
+  })];
+}

package/cli/guard/scanners/external-input.mjs

@@ -0,0 +1,74 @@
+import { localWindow, maskCommentsAndStrings } from './utils.mjs';
+
+export function hasValidationMarker(text) {
+  return /\b(safeParse|parseAsync|schema\.parse|schema\.safeParse|z\.object|validate|validator|assert|parseEnv|requiredEnv|validated|sanitize)\b/i.test(text);
+}
+
+function hasLocalValidation(text, index, before = 360, after = 720) {
+  return hasValidationMarker(localWindow(maskCommentsAndStrings(text), index, before, after));
+}
+
+export function externalInputValidationFindings(relPath, text) {
+  const out = [];
+  const markerText = maskCommentsAndStrings(text);
+  for (const match of markerText.matchAll(/\bJSON\.parse\s*\(/g)) {
+    const before = localWindow(markerText, match.index || 0, 260, 20);
+    if (/\b(readFileSync|readFile)\s*\(/.test(before) && !hasLocalValidation(text, match.index || 0)) {
+      out.push({
+        ruleId: 'input.file_parse_unvalidated',
+        severity: 'warning',
+        relPath,
+        line: undefined,
+        symbol: 'file-json-parse',
+        message: 'File input appears parsed without an obvious schema/validator; validate before trusting file contents.',
+        confidence: 'low',
+      });
+      break;
+    }
+  }
+  for (const match of markerText.matchAll(/\.json\s*\(\s*\)/g)) {
+    const window = localWindow(text, match.index || 0, 420, 260);
+    if (/\bfetch\s*\(\s*['"]https?:\/\//.test(window) && !hasLocalValidation(text, match.index || 0)) {
+      out.push({
+        ruleId: 'input.third_party_json_unvalidated',
+        severity: 'warning',
+        relPath,
+        symbol: 'third-party-json',
+        message: 'Third-party fetch JSON appears used without an obvious schema/validator; validate response shape before trusting it.',
+        confidence: 'low',
+      });
+      break;
+    }
+  }
+  for (const match of markerText.matchAll(/\bconst\s+([A-Za-z_$][\w$]*)\s*=\s*await\s+(?:request|req)\.json\s*\(/g)) {
+    const bodyVar = match[1];
+    if (hasLocalValidation(text, match.index || 0, 40, 720)) continue;
+    const after = localWindow(markerText, match.index || 0, 0, 1100);
+    const directUse = new RegExp(`\\b(?:create|update|upsert|delete|save|mutate|service\\.[A-Za-z_$][\\w$]*|usecase\\.[A-Za-z_$][\\w$]*)\\s*\\(\\s*${bodyVar}\\b`).test(after);
+    if (directUse) {
+      out.push({
+        ruleId: 'input.request_body_direct_use',
+        severity: 'warning',
+        relPath,
+        symbol: 'request-body-direct-use',
+        message: 'Request body appears passed directly into a mutation/service call without an obvious schema/validator.',
+        confidence: 'low',
+      });
+      break;
+    }
+  }
+  for (const match of markerText.matchAll(/\bexport\s+(?:const|let|var)\s+[A-Za-z_$][\w$]*\s*=\s*(?:\{[\s\S]{0,240})?process\.env\.[A-Z0-9_]+\b/g)) {
+    if (!hasLocalValidation(text, match.index || 0)) {
+      out.push({
+        ruleId: 'input.env_export_unvalidated',
+        severity: 'warning',
+        relPath,
+        symbol: 'env-export-unvalidated',
+        message: 'Environment-derived config appears exported without an obvious validation/fallback boundary.',
+        confidence: 'low',
+      });
+      break;
+    }
+  }
+  return out;
+}

package/cli/guard/scanners/index.mjs

@@ -0,0 +1,136 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { effectiveRuleMode } from '../../profile.mjs';
+import { FINDING_METADATA } from '../registry.mjs';
+import { externalInputValidationFindings } from './external-input.mjs';
+import {
+  scanBroadExceptionAdvisory,
+  scanFileSizeAdvisory,
+  scanResponsibilityBudget,
+  scanSecretLogging,
+  scanSilentFailures,
+  scanTypeEscapeAdvisory,
+  scanWorkflowSecurity,
+} from './code-health.mjs';
+import {
+  scanApiContractCompatibility,
+  scanAuthzDataIsolation,
+  scanCrawlerProducerBoundary,
+  scanDbRowValidation,
+  scanPublicSafeError,
+  scanSqlParameterBinding,
+  scanThinApiRoute,
+  scanWriteSafety,
+} from './data-boundary.mjs';
+import {
+  scanClientServerBoundary,
+  scanPerformanceDuplicateFetch,
+  scanRuntimeEnvSafety,
+  scanSideEffectBoundary,
+  scanStateSafety,
+} from './ui-runtime.mjs';
+import { scanSingleResponsibility } from './single-responsibility.mjs';
+import { isSourceCodePath, violation } from './utils.mjs';
+
+const ACTIVE_PROFILE_MODES = new Set(['advisory', 'changed-files', 'baseline-new-only', 'strict']);
+
+export { violation } from './utils.mjs';
+
+function scanExternalInputValidation(relPath, text) {
+  if (!isSourceCodePath(relPath)) return [];
+  return externalInputValidationFindings(relPath, text).map((item) => violation(item));
+}
+
+export const SCANNER_REGISTRY = [
+  { id: 'scanSilentFailures', families: ['no_silent_failure'], scan: ({ relPath, text }) => scanSilentFailures(relPath, text) },
+  { id: 'scanSecretLogging', families: ['no_secret_logging'], scan: ({ relPath, text }) => scanSecretLogging(relPath, text) },
+  { id: 'scanClientServerBoundary', families: ['component_responsibility'], scan: ({ relPath, text }) => scanClientServerBoundary(relPath, text) },
+  { id: 'scanWorkflowSecurity', families: ['workflow_security'], scan: ({ relPath, text }) => scanWorkflowSecurity(relPath, text) },
+  { id: 'scanExternalInputValidation', families: ['external_input_validation'], scan: ({ relPath, text }) => scanExternalInputValidation(relPath, text) },
+  { id: 'scanFileSizeAdvisory', families: ['file_size_advisory'], scan: ({ relPath, text, settings }) => scanFileSizeAdvisory(relPath, text, settings.fileSize) },
+  { id: 'scanResponsibilityBudget', families: ['responsibility_budget'], scan: ({ relPath, text, settings }) => scanResponsibilityBudget(relPath, text, settings.responsibilityBudget) },
+  { id: 'scanSingleResponsibility', families: ['single_responsibility_advisory'], scan: ({ relPath, text, settings }) => scanSingleResponsibility(relPath, text, settings.singleResponsibility) },
+  { id: 'scanStateSafety', families: ['null_state_safety'], scan: ({ relPath, text }) => scanStateSafety(relPath, text) },
+  { id: 'scanAuthzDataIsolation', families: ['authz_data_isolation'], scan: ({ relPath, text }) => scanAuthzDataIsolation(relPath, text) },
+  { id: 'scanRuntimeEnvSafety', families: ['build_runtime_env_safety'], scan: ({ relPath, text }) => scanRuntimeEnvSafety(relPath, text) },
+  { id: 'scanWriteSafety', families: ['write_safety_idempotency'], scan: ({ relPath, text }) => scanWriteSafety(relPath, text) },
+  { id: 'scanApiContractCompatibility', families: ['api_contract_compatibility'], scan: ({ relPath, text }) => scanApiContractCompatibility(relPath, text) },
+  { id: 'scanPerformanceDuplicateFetch', families: ['performance_duplicate_fetch'], scan: ({ relPath, text }) => scanPerformanceDuplicateFetch(relPath, text) },
+  { id: 'scanSqlParameterBinding', families: ['sql_parameter_binding'], scan: ({ relPath, text }) => scanSqlParameterBinding(relPath, text) },
+  { id: 'scanPublicSafeError', families: ['public_safe_error'], scan: ({ relPath, text }) => scanPublicSafeError(relPath, text) },
+  { id: 'scanDbRowValidation', families: ['db_row_validation'], scan: ({ relPath, text }) => scanDbRowValidation(relPath, text) },
+  { id: 'scanThinApiRoute', families: ['thin_api_route'], scan: ({ relPath, text }) => scanThinApiRoute(relPath, text) },
+  { id: 'scanTypeEscapeAdvisory', families: ['type_escape_advisory'], scan: ({ relPath, text }) => scanTypeEscapeAdvisory(relPath, text) },
+  { id: 'scanSideEffectBoundary', families: ['side_effect_boundary'], scan: ({ relPath, text }) => scanSideEffectBoundary(relPath, text) },
+  { id: 'scanCrawlerProducerBoundary', families: ['crawler_producer_boundary'], scan: ({ relPath, text }) => scanCrawlerProducerBoundary(relPath, text) },
+  { id: 'scanBroadExceptionAdvisory', families: ['broad_exception_advisory'], scan: ({ relPath, text }) => scanBroadExceptionAdvisory(relPath, text) },
+];
+
+export function validateScannerRegistry() {
+  const errors = [];
+  const seen = new Set();
+  for (const scanner of SCANNER_REGISTRY) {
+    if (!scanner?.id || typeof scanner.scan !== 'function' || !Array.isArray(scanner.families)) {
+      errors.push(`Invalid scanner registry entry: ${JSON.stringify(scanner?.id || scanner)}`);
+      continue;
+    }
+    if (seen.has(scanner.id)) errors.push(`Duplicate scanner registry id: ${scanner.id}`);
+    seen.add(scanner.id);
+  }
+  for (const [findingId, metadata] of Object.entries(FINDING_METADATA)) {
+    if (!seen.has(metadata.scanner)) errors.push(`Finding ${findingId} references missing scanner registry id ${metadata.scanner}`);
+  }
+  return errors;
+}
+
+const registryErrors = validateScannerRegistry();
+if (registryErrors.length) {
+  throw new Error(`Invalid guard scanner registry:\n${registryErrors.map((error) => `- ${error}`).join('\n')}`);
+}
+
+function decorateViolation(item, profile) {
+  const metadata = FINDING_METADATA[item.rule_id] || { family: item.rule_id, pack: 'core', scanner: item.source || 'unknown' };
+  const effectiveMode = effectiveRuleMode(profile, metadata);
+  return {
+    ...item,
+    rule_family: metadata.family,
+    scanner_id: metadata.scanner,
+    effective_mode: effectiveMode,
+  };
+}
+
+function isModeActiveForScope(mode, scope) {
+  if (mode === 'changed-files' && scope === 'all') return false;
+  return ACTIVE_PROFILE_MODES.has(mode);
+}
+
+function applyProfileModes(violations, profile, { scope } = {}) {
+  return violations
+    .map((item) => decorateViolation(item, profile))
+    .filter((item) => isModeActiveForScope(item.effective_mode, scope));
+}
+
+export function scanText(relPath, text, settings = {}) {
+  const raw = SCANNER_REGISTRY.flatMap((scanner) => scanner.scan({ relPath, text, settings }));
+  if (settings.applyProfile === false) return raw.map((item) => decorateViolation(item, settings.profile || {}));
+  return applyProfileModes(raw, settings.profile || {}, { scope: settings.scope });
+}
+
+export function scanFile(repoRoot, relPath, settings = {}) {
+  const full = path.join(repoRoot, relPath);
+  let text;
+  try {
+    text = fs.readFileSync(full, 'utf8');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      violations: [],
+      failure: {
+        code: 'guard.scan.file_read',
+        message: `Failed to read ${relPath}`,
+        details: [message],
+      },
+    };
+  }
+  return { violations: scanText(relPath, text, settings), failure: null };
+}