@duckmind/dm-linux-x64 0.63.9 → 0.64.2

package/extensions/dm-lens/clients/dispatch/runners/ast-grep-napi.js

@@ -0,0 +1,728 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  incrementDegradationCount,
+  recordDegradationOnce
+} from "../../degradation-ledger.js";
+import {
+  loadAstGrepNapi
+} from "../../deps/ast-grep-napi.js";
+import { minimatch } from "../../deps/minimatch.js";
+import { logLatency } from "../../latency-logger.js";
+import { hasAuxiliaryLspPublishedForRoot } from "../../lsp/index.js";
+import {
+  clearPendingAuxiliaryCoverage,
+  hasPendingAuxiliaryCoverage,
+  recordNapiFallbackCoverage
+} from "../../lsp/pending-aux-coverage.js";
+import {
+  getAstGrepRuleSources
+} from "../../sgconfig.js";
+import { hasEslintConfig } from "../../tool-policy.js";
+import { enabledAuxiliaryLspServerIds } from "../auxiliary-lsp.js";
+import { classifyDefect } from "../diagnostic-taxonomy.js";
+import { PRIORITY } from "../priorities.js";
+import {
+  calculateRuleComplexity,
+  isOverlyBroadPattern,
+  isStructuredRule,
+  loadYamlRules,
+  loadYamlRulesFresh,
+  MAX_BLOCKING_RULE_COMPLEXITY
+} from "./yaml-rule-parser.js";
+const defaultUnsupportedLanguageLog = new Set;
+const UNSUPPORTED_RULE_ID_SAMPLE_SIZE = 5;
+export function resetAstGrepUnsupportedLanguageLog() {
+  defaultUnsupportedLanguageLog.clear();
+}
+let sg;
+let sgLoadPromise;
+let sgSessionHold = false;
+let sgHoldReason;
+const TRANSIENT_ERRNO_ALLOWLIST = new Set([
+  "EMFILE",
+  "EBUSY",
+  "EAGAIN",
+  "EPERM",
+  "ETXTBSY"
+]);
+const KNOWN_GENUINE_NATIVE_LOAD_MESSAGES = [
+  /cannot find native binding/i,
+  /failed to load native binding/i
+];
+function collectErrorChain(err) {
+  const codes = [];
+  const messages = [];
+  let current = err;
+  const seen = new Set;
+  while (current !== undefined && current !== null && !seen.has(current)) {
+    seen.add(current);
+    if (current instanceof Error) {
+      messages.push(current.message);
+      const code = current.code;
+      if (typeof code === "string")
+        codes.push(code);
+      current = current.cause;
+    } else {
+      messages.push(String(current));
+      break;
+    }
+  }
+  return { codes, messages };
+}
+function classifyAstGrepLoadFailure(err) {
+  const { codes, messages } = collectErrorChain(err);
+  const hasKnownGenuineMessage = messages.some((message) => KNOWN_GENUINE_NATIVE_LOAD_MESSAGES.some((pattern) => pattern.test(message)));
+  if (hasKnownGenuineMessage)
+    return "genuine";
+  const hasTransientErrno = codes.some((code) => TRANSIENT_ERRNO_ALLOWLIST.has(code));
+  return hasTransientErrno ? "transient" : "genuine";
+}
+function recordAstGrepUnavailableOnce(reason) {
+  recordDegradationOnce({
+    kind: "ast-grep-napi-unavailable",
+    subject: "ast-grep-napi",
+    reason: reason === "genuine" ? "native addon failed to load (durable for this session)" : "native addon load hit a transient error (durable for this session — see sgSessionHold doc)"
+  });
+}
+export async function loadSg() {
+  if (sg)
+    return sg;
+  if (sgLoadPromise)
+    return sgLoadPromise;
+  if (sgSessionHold) {
+    recordAstGrepUnavailableOnce(sgHoldReason ?? "genuine");
+    return;
+  }
+  const task = (async () => {
+    try {
+      const loaded = await loadAstGrepNapi();
+      sg = loaded;
+      return loaded;
+    } catch (err) {
+      const reason = classifyAstGrepLoadFailure(err);
+      sgSessionHold = true;
+      sgHoldReason = reason;
+      recordAstGrepUnavailableOnce(reason);
+      return;
+    }
+  })();
+  sgLoadPromise = task;
+  task.finally(() => {
+    if (sgLoadPromise === task)
+      sgLoadPromise = undefined;
+  });
+  return task;
+}
+export function resetAstGrepNapiLoadState() {
+  sgSessionHold = false;
+  sgHoldReason = undefined;
+}
+const NAPI_LANGUAGE_BINDINGS = [
+  {
+    ruleLanguage: "typescript",
+    napiExport: "ts",
+    extensions: [".ts", ".mts", ".cts"]
+  },
+  { ruleLanguage: "tsx", napiExport: "tsx", extensions: [".tsx"] },
+  {
+    ruleLanguage: "javascript",
+    napiExport: "js",
+    extensions: [".js", ".jsx", ".mjs", ".cjs"]
+  },
+  { ruleLanguage: "css", napiExport: "css", extensions: [".css"] },
+  { ruleLanguage: "html", napiExport: "html", extensions: [".html", ".htm"] }
+];
+const BINDING_BY_EXTENSION = new Map(NAPI_LANGUAGE_BINDINGS.flatMap((binding) => binding.extensions.map((ext) => [ext, binding])));
+const SUPPORTED_RULE_LANGUAGES = NAPI_LANGUAGE_BINDINGS.map((binding) => binding.ruleLanguage);
+export const AST_GREP_LSP_ONLY_RULE_LANGUAGES = [
+  "c",
+  "cpp",
+  "csharp",
+  "go",
+  "java",
+  "kotlin",
+  "php",
+  "python",
+  "ruby",
+  "rust",
+  "scala",
+  "swift"
+];
+const LSP_ONLY_RULE_LANGUAGES = new Set(AST_GREP_LSP_ONLY_RULE_LANGUAGES);
+export function deliveryRouteForRuleLanguage(ruleLanguage) {
+  if (SUPPORTED_RULE_LANGUAGES.includes(ruleLanguage))
+    return "napi";
+  return LSP_ONLY_RULE_LANGUAGES.has(ruleLanguage) ? "ast-grep-lsp-cli" : "unclassified";
+}
+function skipRouteFor(key) {
+  return key.startsWith("mismatch:") ? "napi" : deliveryRouteForRuleLanguage(key);
+}
+const MAX_MATCHES_PER_RULE = 10;
+const MAX_TOTAL_DIAGNOSTICS = 50;
+const LINTER_OVERLAP = new Set([
+  "getter-return",
+  "no-array-constructor",
+  "no-async-promise-executor",
+  "no-await-in-loop",
+  "no-case-declarations",
+  "no-compare-neg-zero",
+  "no-cond-assign",
+  "no-constant-condition",
+  "no-constructor-return",
+  "no-dupe-args",
+  "no-dupe-keys",
+  "no-extra-boolean-cast",
+  "no-new-symbol",
+  "no-new-wrappers",
+  "no-prototype-builtins"
+]);
+const NON_SUPPRESSIBLE = new Set([
+  "empty-catch",
+  "no-discarded-error",
+  "unchecked-throwing-call"
+]);
+function defaultFixSuggestion(defectClass, ruleId) {
+  if (defectClass === "silent-error") {
+    return "Handle the error path explicitly: log context and rethrow or return a typed error result.";
+  }
+  if (defectClass === "secrets") {
+    return "Remove hardcoded secret material and load values from env/secret manager.";
+  }
+  if (defectClass === "injection") {
+    return "Avoid dynamic execution/interpolation here; use parameterized APIs or strict allowlists.";
+  }
+  if (defectClass === "async-misuse") {
+    return "Make async flow explicit: await consistently and handle rejection/error paths.";
+  }
+  if (ruleId.includes("unsafe") || ruleId.includes("security")) {
+    return "Refactor to a safer API usage with explicit validation and bounded behavior.";
+  }
+  return "Refactor this pattern to the safer equivalent used in the codebase.";
+}
+function explicitRuleFixSuggestion(rule) {
+  const raw = (rule.fix ?? rule.note ?? "").trim();
+  if (!raw)
+    return;
+  const oneLine = raw.replace(/\s+/g, " ").trim();
+  return oneLine.length > 240 ? `${oneLine.slice(0, 237)}...` : oneLine;
+}
+function normalizeRuleId(ruleId) {
+  return ruleId.replace(/-js$/, "");
+}
+function relativeForIgnoreGlob(filePath, root) {
+  const rel = path.relative(root, filePath);
+  return (rel.startsWith("..") ? filePath : rel).split(path.sep).join("/");
+}
+function matchesRuleIgnores(filePath, root, patterns) {
+  if (!patterns || patterns.length === 0)
+    return false;
+  const rel = relativeForIgnoreGlob(filePath, root);
+  return patterns.some((pattern) => minimatch(rel, pattern, { dot: true }));
+}
+export function canHandle(filePath) {
+  return BINDING_BY_EXTENSION.has(path.extname(filePath).toLowerCase());
+}
+export function ruleLanguageForFile(filePath) {
+  return BINDING_BY_EXTENSION.get(path.extname(filePath).toLowerCase())?.ruleLanguage;
+}
+export function getLang(filePath, sgModule) {
+  const binding = BINDING_BY_EXTENSION.get(path.extname(filePath).toLowerCase());
+  if (!binding)
+    return;
+  const lang = sgModule[binding.napiExport];
+  if (!lang) {
+    recordDegradationOnce({
+      kind: "ast-grep-napi-language-unavailable",
+      subject: binding.ruleLanguage,
+      reason: `@ast-grep/napi exposes no "${binding.napiExport}" grammar; every ${binding.ruleLanguage} rule is skipped in-process this session`
+    });
+  }
+  return lang;
+}
+export const MAX_SCRIPT_BODIES_EVALUATED = 64;
+export const MAX_SCRIPT_BODY_BYTES_EVALUATED = 128 * 1024;
+function computeLineStartsUtf16(content) {
+  const starts = [0];
+  for (let i = 0;i < content.length; i++) {
+    if (content.charCodeAt(i) === 10)
+      starts.push(i + 1);
+  }
+  return starts;
+}
+function filePositionForIndex(lineStarts, index) {
+  let lo = 0;
+  let hi = lineStarts.length - 1;
+  while (lo < hi) {
+    const mid = lo + hi + 1 >> 1;
+    if (lineStarts[mid] <= index)
+      lo = mid;
+    else
+      hi = mid - 1;
+  }
+  return { line: lo, column: index - lineStarts[lo] };
+}
+export function collectHtmlScriptInjections(htmlRoot, sgModule) {
+  const addon = sgModule;
+  if (!addon.js) {
+    return {
+      injections: [],
+      scriptElementCount: 0,
+      bodiesEvaluated: 0,
+      truncatedBodies: 0,
+      parseFailures: 0,
+      missingJsGrammar: true,
+      htmlScanFailure: false
+    };
+  }
+  let scripts;
+  try {
+    scripts = htmlRoot.findAll({ rule: { kind: "script_element" } });
+  } catch {
+    return {
+      injections: [],
+      scriptElementCount: 0,
+      bodiesEvaluated: 0,
+      truncatedBodies: 0,
+      parseFailures: 0,
+      missingJsGrammar: false,
+      htmlScanFailure: true
+    };
+  }
+  let scriptElementCount = 0;
+  const candidates = [];
+  for (const element of scripts) {
+    scriptElementCount += 1;
+    let raw;
+    for (const child of element.children()) {
+      if (child.kind() === "raw_text") {
+        raw = child;
+        break;
+      }
+    }
+    if (!raw)
+      continue;
+    const body = raw.text();
+    if (!body.trim())
+      continue;
+    candidates.push({
+      body,
+      startIndex: raw.range().start.index
+    });
+  }
+  let budgetedBytes = 0;
+  const selected = [];
+  let truncatedBodies = 0;
+  for (const candidate of candidates) {
+    const bytes = Buffer.byteLength(candidate.body, "utf8");
+    if (selected.length >= MAX_SCRIPT_BODIES_EVALUATED || budgetedBytes + bytes > MAX_SCRIPT_BODY_BYTES_EVALUATED) {
+      truncatedBodies += 1;
+      continue;
+    }
+    selected.push(candidate);
+    budgetedBytes += bytes;
+  }
+  const injections = [];
+  let parseFailures = 0;
+  for (const candidate of selected) {
+    try {
+      const root = addon.js.parse(candidate.body).root();
+      injections.push({
+        body: candidate.body,
+        startIndex: candidate.startIndex,
+        root
+      });
+    } catch {
+      parseFailures += 1;
+    }
+  }
+  return {
+    injections,
+    scriptElementCount,
+    bodiesEvaluated: selected.length,
+    truncatedBodies,
+    parseFailures,
+    missingJsGrammar: false,
+    htmlScanFailure: false
+  };
+}
+function emitHtmlScriptDegradations(filePath, result) {
+  if (result.missingJsGrammar) {
+    recordDegradationOnce({
+      kind: "ast-grep-napi-html-js-grammar-missing",
+      subject: filePath,
+      reason: "addon exposes no js grammar; embedded <script> coverage dropped"
+    });
+  }
+  if (result.htmlScanFailure) {
+    recordDegradationOnce({
+      kind: "ast-grep-napi-html-script-scan-failed",
+      subject: filePath,
+      reason: "script_element enumeration failed; embedded <script> coverage dropped"
+    });
+  }
+  if (result.parseFailures > 0) {
+    incrementDegradationCount({
+      kind: "ast-grep-napi-html-script-parse-failed",
+      subject: filePath,
+      reason: `${result.parseFailures} of ${result.bodiesEvaluated} script bodies refused to parse as JS`,
+      metadata: {
+        scriptElementCount: result.scriptElementCount,
+        parseFailures: result.parseFailures
+      }
+    });
+  }
+  if (result.truncatedBodies > 0) {
+    incrementDegradationCount({
+      kind: "ast-grep-napi-html-script-budget",
+      subject: filePath,
+      reason: `script budget truncated coverage: ${result.bodiesEvaluated}/${result.scriptElementCount} bodies evaluated, ${result.truncatedBodies} dropped`,
+      metadata: {
+        scriptElementCount: result.scriptElementCount,
+        bodiesEvaluated: result.bodiesEvaluated,
+        truncatedBodies: result.truncatedBodies
+      }
+    });
+  }
+}
+function duplicateRuleIds(rules) {
+  const counts = new Map;
+  for (const rule of rules) {
+    counts.set(rule.id, (counts.get(rule.id) ?? 0) + 1);
+  }
+  return Array.from(counts).filter(([, count]) => count > 1).map(([id]) => id).sort((a, b) => a.localeCompare(b));
+}
+function appendDuplicateRuleDiagnostics(diagnostics, seenRuleIds, duplicateIds, source, filePath, maxTotalDiagnostics) {
+  const sourceLabel = `${source.origin} ${source.tier} rules`;
+  for (const ruleId of duplicateIds) {
+    diagnostics.push({
+      id: `ast-grep-napi-config-duplicate-${source.origin}-${source.tier}-${ruleId}`,
+      message: `Duplicate ast-grep rule id "${ruleId}" in ${sourceLabel}`,
+      filePath,
+      line: 1,
+      column: 1,
+      severity: "error",
+      semantic: "blocking",
+      tool: "ast-grep-napi",
+      rule: ruleId,
+      defectClass: "correctness",
+      fixable: false,
+      autoFixAvailable: false,
+      fixSuggestion: `Give every rule in ${sourceLabel} a unique id`
+    });
+    seenRuleIds.add(ruleId);
+    if (diagnostics.length >= maxTotalDiagnostics)
+      return true;
+  }
+  return false;
+}
+const DIAGNOSTIC_SEVERITY_TIERS = new Set([
+  "error",
+  "warning",
+  "info",
+  "hint"
+]);
+export function normalizeRuleSeverity(raw) {
+  const tier = raw;
+  return tier && DIAGNOSTIC_SEVERITY_TIERS.has(tier) ? tier : "warning";
+}
+export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}) {
+  const maxMatchesPerRule = options.maxMatchesPerRule ?? MAX_MATCHES_PER_RULE;
+  const maxTotalDiagnostics = options.maxTotalDiagnostics ?? MAX_TOTAL_DIAGNOSTICS;
+  const blockingOnly = options.blockingOnly === true;
+  const log = options.log;
+  const unsupportedLanguageLog = options.unsupportedLanguageLog ?? defaultUnsupportedLanguageLog;
+  const diagnostics = [];
+  const seenRuleIds = new Set;
+  const suppressLinterOverlap = kind === "jsts" && hasEslintConfig(cwd);
+  const fileLang = ruleLanguageForFile(filePath);
+  const htmlCollection = fileLang === "html" && options.content !== undefined && options.sgModule !== undefined ? collectHtmlScriptInjections(rootNode, options.sgModule) : {
+    injections: [],
+    scriptElementCount: 0,
+    bodiesEvaluated: 0,
+    truncatedBodies: 0,
+    parseFailures: 0,
+    missingJsGrammar: false,
+    htmlScanFailure: false
+  };
+  const htmlInjections = htmlCollection.injections;
+  emitHtmlScriptDegradations(filePath, htmlCollection);
+  const fileLineStarts = htmlInjections.length > 0 && options.content !== undefined ? computeLineStartsUtf16(options.content) : [];
+  const newlyUnsupported = new Map;
+  const flushUnsupportedRuleSkips = () => {
+    if (newlyUnsupported.size === 0)
+      return;
+    const firstSeenLanguages = Array.from(newlyUnsupported.entries()).filter(([language]) => !unsupportedLanguageLog.has(language));
+    for (const [language] of firstSeenLanguages) {
+      unsupportedLanguageLog.add(language);
+    }
+    if (firstSeenLanguages.length === 0) {
+      newlyUnsupported.clear();
+      return;
+    }
+    for (const [language] of firstSeenLanguages)
+      unsupportedLanguageLog.add(language);
+    logLatency({
+      type: "phase",
+      phase: "astgrep_napi_unsupported_rules_skipped",
+      filePath,
+      durationMs: 0,
+      metadata: {
+        skippedByLanguage: Object.fromEntries(firstSeenLanguages.map(([language, ruleIds]) => [
+          language,
+          {
+            count: ruleIds.length,
+            ruleIds: ruleIds.slice(0, UNSUPPORTED_RULE_ID_SAMPLE_SIZE),
+            route: skipRouteFor(language),
+            ...fileLang === "html" ? { htmlInlineScriptCount: htmlInjections.length } : {}
+          }
+        ]))
+      }
+    });
+    newlyUnsupported.clear();
+  };
+  const ignoreRoot = options.projectRoot ?? cwd;
+  const ruleSources = getAstGrepRuleSources(ignoreRoot);
+  for (const source of ruleSources) {
+    let rules;
+    try {
+      const loader = source.origin === "project" ? loadYamlRulesFresh : loadYamlRules;
+      rules = loader(source.dir);
+    } catch {
+      continue;
+    }
+    const duplicates = duplicateRuleIds(rules);
+    if (appendDuplicateRuleDiagnostics(diagnostics, seenRuleIds, duplicates, source, filePath, maxTotalDiagnostics)) {
+      flushUnsupportedRuleSkips();
+      return diagnostics;
+    }
+    const duplicateSet = new Set(duplicates);
+    for (const rule of rules) {
+      if (duplicateSet.has(rule.id))
+        continue;
+      if (seenRuleIds.has(rule.id))
+        continue;
+      seenRuleIds.add(rule.id);
+      if (blockingOnly && rule.severity !== "error")
+        continue;
+      if (matchesRuleIgnores(filePath, ignoreRoot, rule.ignores))
+        continue;
+      if (suppressLinterOverlap && LINTER_OVERLAP.has(normalizeRuleId(rule.id)) && !NON_SUPPRESSIBLE.has(normalizeRuleId(rule.id))) {
+        continue;
+      }
+      if (rule.rule && isOverlyBroadPattern(rule.rule.pattern) && !isStructuredRule(rule)) {
+        continue;
+      }
+      const lang = rule.language?.toLowerCase();
+      if (lang && !SUPPORTED_RULE_LANGUAGES.includes(lang)) {
+        if (!unsupportedLanguageLog.has(lang)) {
+          const ids = newlyUnsupported.get(lang) ?? [];
+          ids.push(rule.id);
+          newlyUnsupported.set(lang, ids);
+        }
+        continue;
+      }
+      const runsInsideHtmlScript = fileLang === "html" && lang === "javascript" && htmlInjections.length > 0;
+      if (lang && fileLang && lang !== fileLang) {
+        const runsAsTsOnTsx = fileLang === "tsx" && lang === "typescript";
+        if (!runsAsTsOnTsx && !runsInsideHtmlScript) {
+          const key = `mismatch:${lang}->${fileLang}`;
+          if (!unsupportedLanguageLog.has(key)) {
+            const ids = newlyUnsupported.get(key) ?? [];
+            ids.push(rule.id);
+            newlyUnsupported.set(key, ids);
+          }
+          continue;
+        }
+      }
+      if (blockingOnly && rule.rule) {
+        const complexity = calculateRuleComplexity(rule.rule);
+        if (complexity > MAX_BLOCKING_RULE_COMPLEXITY) {
+          continue;
+        }
+      }
+      if (!rule.rule)
+        continue;
+      try {
+        const scopes = runsInsideHtmlScript ? htmlInjections.map((injection) => ({
+          root: injection.root,
+          position(match) {
+            const start = match.range().start;
+            return filePositionForIndex(fileLineStarts, injection.startIndex + start.index);
+          }
+        })) : [
+          {
+            root: rootNode,
+            position(match) {
+              const start = match.range().start;
+              return { line: start.line, column: start.column };
+            }
+          }
+        ];
+        const nativeConfig = { rule: rule.rule };
+        if (rule.constraints)
+          nativeConfig.constraints = rule.constraints;
+        if (rule.utils)
+          nativeConfig.utils = rule.utils;
+        const collected = [];
+        let rejectLogged = false;
+        for (const scope of scopes) {
+          let found;
+          try {
+            found = scope.root.findAll(nativeConfig);
+          } catch (err) {
+            if (!rejectLogged) {
+              rejectLogged = true;
+              log?.(`ast-grep-napi: rule "${rule.id}" rejected by native engine (${err instanceof Error ? err.message : String(err)})`);
+            }
+            continue;
+          }
+          for (const match of found) {
+            if (collected.length >= maxMatchesPerRule)
+              break;
+            collected.push({ match, position: scope.position(match) });
+          }
+          if (collected.length >= maxMatchesPerRule)
+            break;
+        }
+        for (const { position } of collected) {
+          if (diagnostics.length >= maxTotalDiagnostics)
+            break;
+          const severity = normalizeRuleSeverity(rule.severity);
+          const semantic = severity === "error" ? "blocking" : "warning";
+          const defectClass = classifyDefect(rule.id, "ast-grep-napi", rule.message || rule.id);
+          const ruleFix = explicitRuleFixSuggestion(rule);
+          diagnostics.push({
+            id: `ast-grep-napi-${position.line}-${rule.id}`,
+            message: `[${rule.metadata?.category || "slop"}] ${rule.message || rule.id}`,
+            filePath,
+            line: position.line + 1,
+            column: position.column + 1,
+            severity,
+            semantic,
+            tool: "ast-grep-napi",
+            rule: rule.id,
+            defectClass,
+            fixable: !!ruleFix,
+            autoFixAvailable: false,
+            fixKind: ruleFix ? "suggestion" : undefined,
+            fixSuggestion: semantic === "blocking" ? ruleFix ?? defaultFixSuggestion(defectClass, rule.id) : ruleFix
+          });
+        }
+        if (diagnostics.length >= maxTotalDiagnostics)
+          break;
+      } catch {}
+    }
+  }
+  flushUnsupportedRuleSkips();
+  return diagnostics;
+}
+const astGrepNapiRunner = {
+  id: "ast-grep-napi",
+  appliesTo: ["jsts", "css", "html"],
+  priority: PRIORITY.SPECIALIZED_ANALYSIS,
+  skipTestFiles: true,
+  async run(ctx) {
+    if (!canHandle(ctx.filePath)) {
+      return { status: "skipped", diagnostics: [], semantic: "none" };
+    }
+    const astGrepLspEnabled = enabledAuxiliaryLspServerIds((f) => ctx.pi?.getFlag?.(f)).includes("ast-grep");
+    const astGrepLspPublished = astGrepLspEnabled ? await hasAuxiliaryLspPublishedForRoot("ast-grep", ctx.filePath) : false;
+    if (astGrepLspEnabled && astGrepLspPublished) {
+      if (hasPendingAuxiliaryCoverage(ctx.filePath, "ast-grep")) {
+        incrementDegradationCount({
+          kind: "aux-runner-findings-lost",
+          subject: "ast-grep",
+          reason: `Gate B skipped napi for ${ctx.filePath}: a pending late-auxiliary pair from an EARLIER touch is still undelivered while a prior publication satisfies the per-file gate`
+        });
+      }
+      return { status: "skipped", diagnostics: [], semantic: "none" };
+    }
+    const sgModule = await loadSg();
+    if (!sgModule) {
+      return { status: "skipped", diagnostics: [], semantic: "none" };
+    }
+    if (!fs.existsSync(ctx.filePath)) {
+      return { status: "skipped", diagnostics: [], semantic: "none" };
+    }
+    const lang = getLang(ctx.filePath, sgModule);
+    if (!lang) {
+      return { status: "skipped", diagnostics: [], semantic: "none" };
+    }
+    let stats;
+    try {
+      stats = fs.statSync(ctx.filePath);
+    } catch {
+      return { status: "skipped", diagnostics: [], semantic: "none" };
+    }
+    if (stats.size > 1024 * 1024) {
+      return { status: "skipped", diagnostics: [], semantic: "none" };
+    }
+    let content;
+    const contentFromFacts = ctx.facts.getFileFact(ctx.filePath, "file.content");
+    if (contentFromFacts !== undefined && contentFromFacts !== null) {
+      content = contentFromFacts;
+    } else {
+      try {
+        content = fs.readFileSync(ctx.filePath, "utf-8");
+      } catch {
+        return { status: "skipped", diagnostics: [], semantic: "none" };
+      }
+    }
+    let root;
+    try {
+      root = lang.parse(content);
+    } catch {
+      return { status: "skipped", diagnostics: [], semantic: "none" };
+    }
+    let rootNode;
+    try {
+      rootNode = root.root();
+    } catch {
+      return { status: "skipped", diagnostics: [], semantic: "none" };
+    }
+    const runningAsLspSubstitute = astGrepLspEnabled && !astGrepLspPublished;
+    if (runningAsLspSubstitute) {
+      recordNapiFallbackCoverage(ctx.filePath);
+      clearPendingAuxiliaryCoverage(ctx.filePath, "ast-grep");
+    }
+    const diagnostics = evaluateAstGrepRules(ctx.filePath, rootNode, ctx.cwd, ctx.kind, {
+      blockingOnly: runningAsLspSubstitute ? false : ctx.blockingOnly,
+      projectRoot: ctx.projectRoot,
+      log: (message) => ctx.log(message),
+      content,
+      sgModule
+    });
+    if (runningAsLspSubstitute) {
+      const bySeverity = {};
+      for (const d of diagnostics) {
+        bySeverity[d.severity] = (bySeverity[d.severity] ?? 0) + 1;
+      }
+      logLatency({
+        type: "phase",
+        phase: "astgrep_napi_substitute_floor",
+        filePath: ctx.filePath,
+        durationMs: 0,
+        metadata: {
+          floor: "lsp-equivalent",
+          ctxBlockingOnly: ctx.blockingOnly === true,
+          diagnosticCount: diagnostics.length,
+          bySeverity
+        }
+      });
+    }
+    const hasBlocking = diagnostics.some((d) => d.semantic === "blocking");
+    let semantic = "none";
+    if (hasBlocking) {
+      semantic = "blocking";
+    } else if (diagnostics.length > 0) {
+      semantic = "warning";
+    }
+    return {
+      status: hasBlocking ? "failed" : "succeeded",
+      diagnostics,
+      semantic
+    };
+  }
+};
+export default astGrepNapiRunner;