fallow-type-aware 3.33.1 → 3.34.1

package/README.md

@@ -14,6 +14,9 @@ zero-based UTF-8 byte column, and optional owner. Results keep their semantic
 assertion separate from `complete`, `partial`, or `unavailable` status. Evidence
 and every operation-specific array are deterministic and bounded, with totals,
 omissions, reason codes, actions, and truncation reported explicitly.
+The request `evidence_limit` is at most 40. A `type-coupling` query can set its
+own `evidence_limit` of at most 10,000, because its result is one report for
+the whole project.
 
 Structural diagnostics,
 unknown identities, missing projects, unsupported syntax, dynamic behavior,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow-type-aware",
-  "version": "3.33.1",
+  "version": "3.34.1",
   "description": "Optional TypeScript-Go semantic refinement sidecar for Fallow",
   "license": "MIT",
   "repository": {

package/src/cli.mjs

@@ -2,12 +2,19 @@ import path from "node:path";
 import { createInterface } from "node:readline";
 
 import {
+  MUTANT_TYPECHECK_OPERATION,
   SESSION_ENVELOPE_TYPES,
   STATUS_OPERATION,
   WIRE_PROTOCOL_VERSION,
 } from "./generated-protocol.mjs";
 import { analyzeSemanticQueries, createSemanticSession } from "./semantic.mjs";
-import { createSemanticResponse, createStatusResponse, parseRequest } from "./protocol.mjs";
+import { checkMutants } from "./mutant-typecheck.mjs";
+import {
+  createMutantTypecheckResponse,
+  createSemanticResponse,
+  createStatusResponse,
+  parseRequest,
+} from "./protocol.mjs";
 
 const MAX_REQUEST_BYTES = 8 * 1024 * 1024;
 const [ANALYZE_ENVELOPE, SHUTDOWN_ENVELOPE] = SESSION_ENVELOPE_TYPES;
@@ -91,6 +98,9 @@ const runSession = async (input, output) => {
         throw new Error("invalid semantic session envelope");
       }
       const request = parseRequest(envelope.request);
+      if (request.operation === MUTANT_TYPECHECK_OPERATION) {
+        throw new Error("a semantic session does not accept a mutant-typecheck request");
+      }
       if (!session) {
         root = request.root;
         session = createSemanticSession(root);
@@ -145,6 +155,14 @@ export const run = async ({ input, output, args = [] }) => {
     return;
   }
   const request = parseRequest(rawRequest);
+  if (request.operation === MUTANT_TYPECHECK_OPERATION) {
+    const results = checkMutants(request);
+    writeJson(
+      output,
+      createMutantTypecheckResponse({ results, elapsedMs: performance.now() - startedAt }),
+    );
+    return;
+  }
   const result = analyzeSemanticQueries(request);
   writeJson(output, responseFor(result, performance.now() - startedAt));
 };

package/src/generated-protocol.mjs

@@ -5,6 +5,7 @@ export const TYPE_AWARE_PROTOCOL = Object.freeze({
   semantic_schema_version: 3,
   analysis_operation: "semantic-queries",
   status_operation: "status",
+  mutant_typecheck_operation: "mutant-typecheck",
   query_operations: ["symbol-use", "symbol-trace", "api-surface", "symbol-impact", "type-coupling"],
   session_envelope_types: ["analyze", "shutdown"],
   backend: {
@@ -20,6 +21,7 @@ export const WIRE_PROTOCOL_VERSION = TYPE_AWARE_PROTOCOL.wire_protocol_version;
 export const SEMANTIC_SCHEMA_VERSION = TYPE_AWARE_PROTOCOL.semantic_schema_version;
 export const ANALYSIS_OPERATION = TYPE_AWARE_PROTOCOL.analysis_operation;
 export const STATUS_OPERATION = TYPE_AWARE_PROTOCOL.status_operation;
+export const MUTANT_TYPECHECK_OPERATION = TYPE_AWARE_PROTOCOL.mutant_typecheck_operation;
 export const QUERY_OPERATIONS = Object.freeze(TYPE_AWARE_PROTOCOL.query_operations);
 export const SESSION_ENVELOPE_TYPES = Object.freeze(TYPE_AWARE_PROTOCOL.session_envelope_types);
 export const BACKEND_FAMILY = TYPE_AWARE_PROTOCOL.backend.family;

package/src/mutant-typecheck.mjs

@@ -0,0 +1,177 @@
+// Type-checks mutated source files for `fallow mutation --typecheck`.
+//
+// The check applies one mutant at a time to an in-memory copy of its file and
+// compares the error diagnostics of that file with the diagnostics of the
+// original file. A new error makes the mutant `compile-error`. The check reads
+// only the mutated file, so a mutant that breaks only another file stays
+// `compiles`. The project files on disk never change.
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import { API, DiagnosticCategory } from "typescript/unstable/sync";
+
+import { canonicalFileIdentity } from "./file-identity.mjs";
+
+const JAVASCRIPT_EXTENSIONS = new Set([".js", ".jsx", ".mjs", ".cjs"]);
+const LEADING_COMMENTS = /^(?:\s|\/\/[^\n]*|\/\*[\s\S]*?\*\/)*/u;
+const NO_CHECK_PRAGMA = /@ts-nocheck\b/u;
+const MAX_CODES = 8;
+
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+const isInferredProject = (project) =>
+  project.configFileName.split(path.sep).join("/").endsWith("/dev/null/inferred");
+
+const hasNoCheckPragma = (text) => NO_CHECK_PRAGMA.test(LEADING_COMMENTS.exec(text)?.[0] ?? "");
+
+const isChecked = (project, absolutePath, text) => {
+  if (hasNoCheckPragma(text)) return false;
+  if (!JAVASCRIPT_EXTENSIONS.has(path.extname(absolutePath).toLowerCase())) return true;
+  return project.compilerOptions?.checkJs === true;
+};
+
+const errorKey = (diagnostic) => `${diagnostic.code}\u0000${diagnostic.text}`;
+
+const fileErrors = (project, absolutePath) =>
+  [
+    ...project.program.getSyntacticDiagnostics(absolutePath),
+    ...project.program.getSemanticDiagnostics(absolutePath),
+  ].filter((diagnostic) => diagnostic.category === DiagnosticCategory.Error);
+
+const countKeys = (diagnostics) => {
+  const counts = new Map();
+  for (const diagnostic of diagnostics) {
+    const key = errorKey(diagnostic);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return counts;
+};
+
+// The codes of the errors that the mutated file has and the original file
+// does not have. Positions move with the mutation, so the comparison uses the
+// code and the message text.
+const newErrorCodes = (baseline, diagnostics) => {
+  const remaining = new Map(baseline);
+  const codes = new Set();
+  for (const diagnostic of diagnostics) {
+    const key = errorKey(diagnostic);
+    const count = remaining.get(key) ?? 0;
+    if (count > 0) remaining.set(key, count - 1);
+    else codes.add(diagnostic.code);
+  }
+  return [...codes].toSorted((left, right) => left - right).slice(0, MAX_CODES);
+};
+
+const mutatedText = (original, mutant) =>
+  Buffer.concat([
+    original.subarray(0, mutant.start),
+    Buffer.from(mutant.replacement, "utf8"),
+    original.subarray(mutant.end),
+  ]).toString("utf8");
+
+const unchecked = (file, reason) =>
+  file.mutants.map((mutant) => ({ id: mutant.id, outcome: "unchecked", reason }));
+
+const readOriginal = (file) => {
+  try {
+    return readFileSync(file.absolutePath);
+  } catch {
+    return null;
+  }
+};
+
+const defaultProjectConfig = (api, absolutePath) => {
+  const snapshot = api.updateSnapshot({ openFiles: [absolutePath] });
+  try {
+    const project = snapshot.getDefaultProjectForFile(absolutePath);
+    return project && !isInferredProject(project) ? project.configFileName : null;
+  } finally {
+    api.updateSnapshot({ closeFiles: [absolutePath] }).dispose();
+    snapshot.dispose();
+  }
+};
+
+const createOverlayApi = (root, createApi) => {
+  const overlay = new Map();
+  const api = createApi({
+    cwd: root,
+    fs: {
+      readFile: (fileName) =>
+        overlay.size === 0 ? undefined : overlay.get(canonicalFileIdentity(fileName)),
+    },
+  });
+  return { api, overlay };
+};
+
+const sourceSkipReason = (file, original) => {
+  if (original === null) return "file-missing";
+  const changed = file.sourceSha256 !== null && sha256(original) !== file.sourceSha256;
+  return changed ? "source-changed" : null;
+};
+
+const projectSkipReason = (project, file, original) => {
+  if (!project?.program.getSourceFile(file.absolutePath)) return "no-project";
+  return isChecked(project, file.absolutePath, original.toString("utf8"))
+    ? null
+    : "not-type-checked";
+};
+
+const checkMutant = (context, check, mutant) => {
+  context.overlay.set(check.identity, mutatedText(check.original, mutant));
+  const next = context.api.updateSnapshot(check.changes);
+  check.snapshot.dispose();
+  check.snapshot = next;
+  const errors = fileErrors(next.getProject(check.config), check.file.absolutePath);
+  const codes = newErrorCodes(check.baseline, errors);
+  return codes.length > 0
+    ? { id: mutant.id, outcome: "compile-error", codes }
+    : { id: mutant.id, outcome: "compiles" };
+};
+
+const checkInProject = (context, file, original, config) => {
+  const check = {
+    file,
+    original,
+    config,
+    identity: canonicalFileIdentity(file.absolutePath),
+    changes: { fileChanges: { changed: [file.absolutePath] } },
+    snapshot: context.api.updateSnapshot({ openProjects: [config] }),
+    baseline: null,
+  };
+  try {
+    const project = check.snapshot.getProject(config);
+    const reason = projectSkipReason(project, file, original);
+    if (reason !== null) return unchecked(file, reason);
+    check.baseline = countKeys(fileErrors(project, file.absolutePath));
+    return file.mutants.map((mutant) => checkMutant(context, check, mutant));
+  } finally {
+    context.overlay.delete(check.identity);
+    context.api.updateSnapshot({ ...check.changes, closeProjects: [config] }).dispose();
+    check.snapshot.dispose();
+  }
+};
+
+const checkFile = (context, file) => {
+  const original = readOriginal(file);
+  const reason = sourceSkipReason(file, original);
+  if (reason !== null) return unchecked(file, reason);
+  const config = defaultProjectConfig(context.api, file.absolutePath);
+  if (config === null) return unchecked(file, "no-project");
+  return checkInProject(context, file, original, config);
+};
+
+/** Type-checks each mutant of a parsed `mutant-typecheck` request. */
+export const checkMutants = (
+  { root, files },
+  { createApi = (options) => new API(options) } = {},
+) => {
+  if (files.length === 0) return [];
+  const context = createOverlayApi(root, createApi);
+  try {
+    return files.flatMap((file) => checkFile(context, file));
+  } finally {
+    context.api.close();
+  }
+};

package/src/protocol.mjs

@@ -7,9 +7,11 @@ import {
   ANALYSIS_OPERATION,
   BACKEND_FAMILY,
   BACKEND_VERSION,
+  MUTANT_TYPECHECK_OPERATION,
   QUERY_OPERATIONS as MANIFEST_QUERY_OPERATIONS,
   WIRE_PROTOCOL_VERSION,
 } from "./generated-protocol.mjs";
+import { canonicalFileIdentity } from "./file-identity.mjs";
 import { normalizePhaseTimings, normalizeSemanticResult } from "./response-normalization.mjs";
 
 const require = createRequire(import.meta.url);
@@ -54,7 +56,13 @@ const API_SURFACE_QUERY_KEYS = new Set([
   "include_cycles",
   "private_leak_candidates",
 ]);
-const TYPE_COUPLING_QUERY_KEYS = new Set(["id", "operation", "entry_points", "include_cycles"]);
+const TYPE_COUPLING_QUERY_KEYS = new Set([
+  "id",
+  "operation",
+  "entry_points",
+  "include_cycles",
+  "evidence_limit",
+]);
 const PRIVATE_LEAK_CANDIDATE_KEYS = new Set(["id", "path", "export_name", "type_name"]);
 const SYMBOL_KEYS = new Set([
   "path",
@@ -75,6 +83,10 @@ const MAX_QUERIES = 25_000;
 const MAX_GRAPH_QUERIES = 256;
 const MAX_PRIVATE_LEAK_CANDIDATES = 25_000;
 const MAX_EVIDENCE_PER_RESULT = 40;
+// A type-coupling result is one project-wide report, so it can carry more
+// evidence than a per-symbol result. This bound keeps the response well below
+// the native client's semantic response byte limit.
+const MAX_TYPE_COUPLING_EVIDENCE = 10_000;
 const MAX_STRING_CHARS = 4_096;
 
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -255,13 +267,31 @@ const parseFrameworkContracts = (value, field) =>
 const parseIncludeCycles = (value, field) =>
   value === undefined ? false : requireBoolean(value, field);
 
+const parseTypeCouplingEvidenceLimit = (value, field) => {
+  const limit = requireInteger(value, field, 1);
+  if (limit > MAX_TYPE_COUPLING_EVIDENCE) {
+    throw new Error(`${field} exceeds the ${MAX_TYPE_COUPLING_EVIDENCE} item limit`);
+  }
+  return limit;
+};
+
 const parseGraphQuery = (value, field, root, query) => {
   const graphQuery = {
     ...query,
     entryPoints: parseEntryPoints(value.entry_points, `${field}.entry_points`, root),
     includeCycles: parseIncludeCycles(value.include_cycles, `${field}.include_cycles`),
   };
-  if (query.operation !== "api-surface") return graphQuery;
+  if (query.operation === "type-coupling") {
+    return value.evidence_limit === undefined
+      ? graphQuery
+      : {
+          ...graphQuery,
+          evidenceLimit: parseTypeCouplingEvidenceLimit(
+            value.evidence_limit,
+            `${field}.evidence_limit`,
+          ),
+        };
+  }
   return {
     ...graphQuery,
     privateLeakCandidates: parsePrivateLeakCandidates(
@@ -375,8 +405,75 @@ const parseBatchRequest = (value) => {
   return { root, projects, queries, evidenceLimit };
 };
 
+const MUTANT_TYPECHECK_REQUEST_KEYS = new Set(["protocol_version", "operation", "root", "files"]);
+const MUTANT_FILE_KEYS = new Set(["path", "source_sha256", "mutants"]);
+const MUTANT_KEYS = new Set(["id", "start", "end", "replacement"]);
+const SHA256_HEX = /^[0-9a-f]{64}$/u;
+const MAX_MUTANTS = 25_000;
+const MAX_MUTANT_ID_CHARS = 64;
+
+const requireText = (value, field) => {
+  if (typeof value !== "string") throw new Error(`${field} must be a string`);
+  if ([...value].length > MAX_STRING_CHARS) {
+    throw new Error(`${field} exceeds the ${MAX_STRING_CHARS} character limit`);
+  }
+  return value;
+};
+
+const parseMutant = (value, field, ids) => {
+  requireObject(value, field);
+  requireExactKeys(value, MUTANT_KEYS, field);
+  const id = requireString(value.id, `${field}.id`);
+  if (id.length > MAX_MUTANT_ID_CHARS) {
+    throw new Error(`${field}.id exceeds the ${MAX_MUTANT_ID_CHARS} character limit`);
+  }
+  if (ids.has(id)) throw new Error(`duplicate mutant id ${id}`);
+  ids.add(id);
+  const start = requireInteger(value.start, `${field}.start`, 0);
+  const end = requireInteger(value.end, `${field}.end`, start);
+  return { id, start, end, replacement: requireText(value.replacement, `${field}.replacement`) };
+};
+
+const parseMutantFile = (value, field, root, ids) => {
+  requireObject(value, field);
+  requireExactKeys(value, MUTANT_FILE_KEYS, field);
+  const { candidatePath, absolutePath } = parseCandidatePath(value.path, `${field}.path`, root);
+  const sourceSha256 =
+    value.source_sha256 === undefined
+      ? null
+      : requireString(value.source_sha256, `${field}.source_sha256`);
+  if (sourceSha256 !== null && !SHA256_HEX.test(sourceSha256)) {
+    throw new Error(`${field}.source_sha256 must be a lowercase SHA-256 hex digest`);
+  }
+  return {
+    path: candidatePath,
+    absolutePath: canonicalFileIdentity(absolutePath),
+    sourceSha256,
+    mutants: requireBoundedArray(value.mutants, `${field}.mutants`, MAX_MUTANTS).map(
+      (mutant, index) => parseMutant(mutant, `${field}.mutants[${index}]`, ids),
+    ),
+  };
+};
+
+const parseMutantTypecheckRequest = (value) => {
+  requireExactKeys(value, MUTANT_TYPECHECK_REQUEST_KEYS, "request");
+  const root = parseRoot(value.root);
+  const ids = new Set();
+  const files = requireBoundedArray(value.files, "files", MAX_MUTANTS).map((file, index) =>
+    parseMutantFile(file, `files[${index}]`, root, ids),
+  );
+  if (ids.size > MAX_MUTANTS) throw new Error(`mutants exceed the ${MAX_MUTANTS} item limit`);
+  return { operation: MUTANT_TYPECHECK_OPERATION, root, files };
+};
+
 export const parseRequest = (value) => {
   requireObject(value, "request");
+  if (
+    value.protocol_version === WIRE_PROTOCOL_VERSION &&
+    value.operation === MUTANT_TYPECHECK_OPERATION
+  ) {
+    return parseMutantTypecheckRequest(value);
+  }
   if (value.protocol_version === WIRE_PROTOCOL_VERSION) {
     return parseBatchRequest(value);
   }
@@ -405,3 +502,13 @@ export const createSemanticResponse = ({
   warnings: normalizeWarnings(warnings),
   elapsed_ms: Math.max(0, Math.round(elapsedMs)),
 });
+
+export const createMutantTypecheckResponse = ({ results, elapsedMs }) => ({
+  protocol_version: WIRE_PROTOCOL_VERSION,
+  operation: MUTANT_TYPECHECK_OPERATION,
+  sidecar_version: SIDECAR_VERSION,
+  backend: BACKEND_FAMILY,
+  backend_version: BACKEND_VERSION,
+  results,
+  elapsed_ms: Math.max(0, Math.round(elapsedMs)),
+});

package/src/semantic.mjs

@@ -1891,7 +1891,7 @@ const analyzeGraphSemanticQuery = (root, query, graphStates, evidenceLimit) => {
     return analyzeApiSurface(root, query, graphStates, evidenceLimit);
   }
   return analyzeTypeCoupling(
-    { root, query, states: graphStates, evidenceLimit },
+    { root, query, states: graphStates, evidenceLimit: query.evidenceLimit ?? evidenceLimit },
     {
       boundedResult,
       discoverEntryPoints,