fallow-type-aware 3.16.0 → 3.17.0

package/README.md

@@ -25,6 +25,13 @@ and SHA-256 declaration guard, but Fallow owns the final decision and fix
 policy. The sidecar does not emit TypeScript compiler diagnostics as Fallow
 findings and does not implement generic typed lint rules.
 
+The raw TypeScript-Go host cannot currently expose Svelte virtual-module named
+exports. If source code imports or re-exports such a name and checker resolution
+has no declaration target, the sidecar returns
+`svelte-virtual-module-exports` instead of claiming complete evidence. Run
+`svelte-check` for framework diagnostics; Fallow stays fail-closed until a
+supported host seam can preserve virtual source identity and mappings.
+
 ## Run locally
 
 ```sh

package/fallow-type-aware.mjs

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 
-import { assertTypescriptBackendResolvable } from "./src/backend-preflight.mjs";
+import { installWindowsChildProcessPolicy } from "./src/windows-child-process.mjs";
+
+installWindowsChildProcessPolicy();
 
 try {
+  const { assertTypescriptBackendResolvable } = await import("./src/backend-preflight.mjs");
   assertTypescriptBackendResolvable();
   const { run } = await import("./src/cli.mjs");
   await run({ input: process.stdin, output: process.stdout, args: process.argv.slice(2) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow-type-aware",
-  "version": "3.16.0",
+  "version": "3.17.0",
   "description": "Optional TypeScript-Go semantic refinement sidecar for Fallow",
   "license": "MIT",
   "repository": {
@@ -32,6 +32,7 @@
   },
   "devDependencies": {
     "@codspeed/tinybench-plugin": "5.7.1",
-    "tinybench": "6.1.2"
+    "tinybench": "6.1.2",
+    "zod": "4.4.3"
   }
 }

package/src/generated-protocol.mjs

@@ -1,8 +1,8 @@
 // Generated from crates/api/type-aware-protocol.json. Do not edit.
 export const TYPE_AWARE_PROTOCOL = Object.freeze({
   schema_version: 1,
-  wire_protocol_version: 6,
-  semantic_schema_version: 2,
+  wire_protocol_version: 7,
+  semantic_schema_version: 3,
   analysis_operation: "semantic-queries",
   status_operation: "status",
   query_operations: ["symbol-use", "symbol-trace", "api-surface", "symbol-impact", "type-coupling"],

package/src/project-state.mjs

@@ -2,18 +2,107 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 
+import { SymbolFlags } from "typescript/unstable/sync";
+import {
+  isExportDeclaration,
+  isImportDeclaration,
+  isNamedExports,
+  isNamedImports,
+} from "typescript/unstable/ast/is";
+
 import { canonicalFileIdentity } from "./file-identity.mjs";
-import { relativePath } from "./semantic-identity.mjs";
+import { projectSourceFiles, relativePath } from "./semantic-identity.mjs";
 
 const INFERRED_PROJECT = "<inferred>";
 const compareText = (left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right));
 const slash = (value) => value.split(path.sep).join("/");
 
-const blockingDiagnosticCount = (project) =>
-  project.program.getConfigFileParsingDiagnostics().length +
-  project.program.getProgramDiagnostics().length +
-  project.program.getSyntacticDiagnostics().length +
-  project.program.getBindDiagnostics().length;
+const structuralDiagnostics = (project) => [
+  ...project.program.getConfigFileParsingDiagnostics(),
+  ...project.program.getProgramDiagnostics(),
+  ...project.program.getSyntacticDiagnostics(),
+  ...project.program.getBindDiagnostics(),
+];
+
+const isProjectLocalDiagnostic = (project, diagnostic) => {
+  if (!diagnostic.fileName) return true;
+  const sourceFile = project.program.getSourceFile(diagnostic.fileName);
+  if (!sourceFile) return true;
+  return (
+    !project.program.isSourceFileDefaultLibrary(sourceFile) &&
+    !project.program.isSourceFileFromExternalLibrary(sourceFile)
+  );
+};
+
+const isSvelteSpecifier = (node) =>
+  typeof node.moduleSpecifier?.text === "string" && node.moduleSpecifier.text.endsWith(".svelte");
+
+const isUnknownAlias = (checker, specifier) => {
+  const symbol = checker.getSymbolAtLocation(specifier.name);
+  if (!symbol) return true;
+  return checker.isUnknownSymbol(checker.getAliasedSymbol(symbol));
+};
+
+const concreteExportSymbol = (checker, symbol) => {
+  const target =
+    (symbol.flags & SymbolFlags.Alias) === 0 ? symbol : checker.getAliasedSymbol(symbol);
+  return !checker.isUnknownSymbol(target) && (target.declarations?.length ?? 0) > 0;
+};
+
+const hasProvableNamedExports = (project, declaration) => {
+  const moduleSymbol = project.checker.getSymbolAtLocation(declaration.moduleSpecifier);
+  if (!moduleSymbol) return false;
+  const hasConcreteModuleDeclaration = moduleSymbol.declarations?.some((moduleDeclaration) => {
+    const declarationPath =
+      moduleDeclaration.path ??
+      moduleDeclaration.fileName ??
+      moduleDeclaration.getSourceFile?.().fileName ??
+      "";
+    return declarationPath.endsWith(".d.svelte") || declarationPath.endsWith(".d.svelte.ts");
+  });
+  if (!hasConcreteModuleDeclaration) return false;
+  const namedExports = project.checker
+    .getExportsOfModule(moduleSymbol)
+    .filter((symbol) => symbol.name !== "default");
+  return namedExports.every((symbol) => concreteExportSymbol(project.checker, symbol));
+};
+
+const svelteDeclarationHasGap = (project, node) => {
+  if (!isSvelteSpecifier(node)) return false;
+  if (isImportDeclaration(node)) {
+    const bindings = node.importClause?.namedBindings;
+    return (
+      bindings !== undefined &&
+      isNamedImports(bindings) &&
+      bindings.elements.some((item) => isUnknownAlias(project.checker, item))
+    );
+  }
+  if (!isExportDeclaration(node)) return false;
+  if (!node.exportClause) return !hasProvableNamedExports(project, node);
+  if (!isNamedExports(node.exportClause)) return !hasProvableNamedExports(project, node);
+  return node.exportClause.elements.some((item) => isUnknownAlias(project.checker, item));
+};
+
+const sourceHasSvelteVirtualModuleGap = (project, sourceFile) => {
+  let gap = false;
+  const visit = (node) => {
+    if (gap) return;
+    gap = svelteDeclarationHasGap(project, node);
+    if (gap) return;
+    node.forEachChild((child) => {
+      visit(child);
+      return undefined;
+    });
+  };
+  visit(sourceFile);
+  return gap;
+};
+
+const hasSvelteVirtualModuleGap = (project) =>
+  projectSourceFiles(project).some(
+    (sourceFile) =>
+      sourceFile.text.includes(".svelte") && sourceHasSvelteVirtualModuleGap(project, sourceFile),
+  );
 
 const configPath = (root, project) => {
   const normalized = slash(project.configFileName);
@@ -173,15 +262,27 @@ const effectiveProjectConfigHash = (root, project) => {
 };
 
 export const projectState = (root, project, source) => {
-  const diagnosticCount = blockingDiagnosticCount(project);
+  const diagnostics = structuralDiagnostics(project);
+  const localDiagnosticCount = diagnostics.filter((diagnostic) =>
+    isProjectLocalDiagnostic(project, diagnostic),
+  ).length;
+  const hasLocalDiagnostics = localDiagnosticCount > 0;
+  const svelteVirtualModuleGap = !hasLocalDiagnostics && hasSvelteVirtualModuleGap(project);
+  const reasonCode = hasLocalDiagnostics
+    ? "blocking-diagnostics"
+    : svelteVirtualModuleGap
+      ? "svelte-virtual-module-exports"
+      : diagnostics.length > 0
+        ? "blocking-diagnostics"
+        : null;
   return {
     project,
     config: configPath(root, project),
     effective_config_hash: effectiveProjectConfigHash(root, project),
     source,
-    status: diagnosticCount === 0 ? "complete" : "unavailable",
-    reason_code: diagnosticCount === 0 ? null : "blocking-diagnostics",
-    blocking_diagnostic_count: diagnosticCount,
+    status: reasonCode === null ? "complete" : "unavailable",
+    reason_code: reasonCode,
+    blocking_diagnostic_count: reasonCode === "blocking-diagnostics" ? diagnostics.length : 0,
     source_file_count: project.program.getSourceFileNames().length,
     program_reused: false,
     candidate_count: 0,

package/src/semantic.mjs

@@ -157,6 +157,10 @@ const REASON_ACTIONS = new Map([
     "blocking-diagnostics",
     "Repair structural TypeScript diagnostics in every selected project and retry.",
   ],
+  [
+    "svelte-virtual-module-exports",
+    "Run svelte-check for framework diagnostics. See https://docs.fallow.tools/analysis/type-aware#svelte-virtual-module-exports for supported Svelte project setup.",
+  ],
   [
     "unknown-entry-point",
     "Refresh the package entry points or pass project-relative source entry points.",
@@ -166,21 +170,22 @@ const DEFAULT_REASON_ACTION =
   "Narrow the query to a specific symbol, entry point, or healthy TypeScript project and retry.";
 const REASON_PRIORITY = new Map([
   ["blocking-diagnostics", 0],
-  ["incomplete-project-coverage", 1],
-  ["framework-contract-provenance", 2],
-  ["ambiguous-project", 3],
-  ["unknown-symbol", 4],
-  ["unknown-entry-point", 5],
-  ["decorated-declaration", 6],
-  ["optional-contract", 7],
-  ["accessor-pair", 8],
-  ["overload-set", 9],
-  ["attached-comment", 10],
-  ["abstract-declaration", 11],
-  ["dynamic-member-access", 12],
-  ["virtual-dispatch", 13],
-  ["dynamic-behavior", 14],
-  ["evidence-limit", 15],
+  ["svelte-virtual-module-exports", 1],
+  ["incomplete-project-coverage", 2],
+  ["framework-contract-provenance", 3],
+  ["ambiguous-project", 4],
+  ["unknown-symbol", 5],
+  ["unknown-entry-point", 6],
+  ["decorated-declaration", 7],
+  ["optional-contract", 8],
+  ["accessor-pair", 9],
+  ["overload-set", 10],
+  ["attached-comment", 11],
+  ["abstract-declaration", 12],
+  ["dynamic-member-access", 13],
+  ["virtual-dispatch", 14],
+  ["dynamic-behavior", 15],
+  ["evidence-limit", 16],
 ]);
 
 const actionForReason = (reasonCode) => REASON_ACTIONS.get(reasonCode) ?? DEFAULT_REASON_ACTION;
@@ -201,6 +206,22 @@ const combineOmissions = (omissions) => {
   return [...counts].map(([reason_code, count]) => ({ reason_code, count }));
 };
 
+const projectStateReason = (state) => state.reason_code ?? "blocking-diagnostics";
+
+const unavailableProjectOmissions = (states) =>
+  combineOmissions(
+    states
+      .filter((state) => state.status !== "complete")
+      .map((state) => ({ reason_code: projectStateReason(state), count: 1 })),
+  );
+
+const unavailableProjectReason = (states) => {
+  if (states.length === 0) return "no-project";
+  return (
+    unavailableProjectOmissions(states).toSorted(compareOmissions)[0]?.reason_code ?? "no-project"
+  );
+};
+
 const resultStatus = (partial) => (partial ? "partial" : "complete");
 const resultReason = (omissions) => (omissions.length > 0 ? omissions[0].reason_code : null);
 const resultActions = (omissions) =>
@@ -681,8 +702,6 @@ const symbolResolutionError = (query, reasonCode, action) => ({
 });
 
 const isCompleteProjectState = (state) => state?.status === "complete";
-const selectedProjectName = (state) => state?.config ?? "the selected project";
-
 const owningProjectContexts = (statesByProject, absolutePath) =>
   [...statesByProject.entries()]
     .filter(([project]) => project.program.getSourceFile(absolutePath))
@@ -722,13 +741,16 @@ const selectSymbolContext = (
   }
   const completeOwners = owners.filter(({ state }) => isCompleteProjectState(state));
   if (completeOwners.length === 0) {
-    return {
-      ...owners[0],
-      ...symbolResolutionError(
-        query,
-        "blocking-diagnostics",
-        `Repair structural diagnostics in ${selectedProjectName(owners[0].state)} and retry.`,
+    const selectedOwner = [...owners].toSorted((left, right) =>
+      compareOmissions(
+        { reason_code: projectStateReason(left.state) },
+        { reason_code: projectStateReason(right.state) },
       ),
+    )[0];
+    const reasonCode = projectStateReason(selectedOwner.state);
+    return {
+      ...selectedOwner,
+      ...symbolResolutionError(query, reasonCode, actionForReason(reasonCode)),
     };
   }
   return { owners, completeOwners };
@@ -1377,6 +1399,13 @@ const signatureTypes = (project, type, anchor) =>
   );
 
 const checkerTypeChildren = (project, type, anchor, hasNamedDeclaration) => {
+  if (type.isTypeParameter()) {
+    const constraint = safeCheckerValue(
+      () => project.checker.getConstraintOfTypeParameter(type),
+      undefined,
+    );
+    return constraint ? [constraint] : [];
+  }
   const structural = [
     ...(type.getTypes() ?? []),
     ...safeCheckerValue(() => type.getAliasTypeArguments(), []),
@@ -1547,12 +1576,9 @@ const graphProjects = (snapshot, explicitProjects) =>
 const readyProjectStates = (query, states) => {
   const ready = states.filter((state) => state.status === "complete");
   if (ready.length > 0) return { ready };
+  const reasonCode = unavailableProjectReason(states);
   return {
-    error: unavailable(
-      query,
-      states.length === 0 ? "no-project" : "blocking-diagnostics",
-      "Pass a healthy tsconfig containing the package entry points and retry.",
-    ),
+    error: unavailable(query, reasonCode, actionForReason(reasonCode)),
   };
 };
 
@@ -1684,7 +1710,7 @@ const analyzeApiSurface = (root, query, states, evidenceLimit) => {
         reason_code: "evidence-limit",
         count: omissionCount,
       },
-      { reason_code: "blocking-diagnostics", count: unavailableProjectCount },
+      ...unavailableProjectOmissions(states),
       { reason_code: "unknown-entry-point", count: missingEntryPointCount },
     ],
   });
@@ -1763,6 +1789,7 @@ const analyzeGraphSemanticQuery = (root, query, graphStates, evidenceLimit) => {
       missingEntryPoints,
       publicApiGraph,
       readyProjectStates,
+      unavailableProjectOmissions,
       uniqueSorted,
     },
   );
@@ -1842,6 +1869,7 @@ const recordAbstainedProjectOutcome = (state, result) => {
     "no-project",
     "ambiguous-project",
     "blocking-diagnostics",
+    "svelte-virtual-module-exports",
     "unknown-symbol",
     "incomplete-project-coverage",
   ]);

package/src/type-coupling.mjs

@@ -118,7 +118,6 @@ export const analyzeTypeCoupling = ({ root, query, states, evidenceLimit }, serv
   const highCouplingThreshold = percentile(degrees, 0.9);
   const topContributors = topCouplingContributors(perFile);
   const cycles = query.includeCycles ? findCycles(edges) : [];
-  const unavailableProjectCount = states.length - readiness.ready.length;
   const missingEntryPointCount = services.missingEntryPoints(query, resolvedEntryPoints);
   const nestedFileOmissionCount = nestedCouplingOmissionCount(perFile, evidenceLimit);
   const boundFile = (entry) => boundCoupledFile(entry, evidenceLimit);
@@ -159,7 +158,7 @@ export const analyzeTypeCoupling = ({ root, query, states, evidenceLimit }, serv
           Math.max(0, cycles.length - evidenceLimit) +
           nestedFileOmissionCount,
       },
-      { reason_code: "blocking-diagnostics", count: unavailableProjectCount },
+      ...services.unavailableProjectOmissions(states),
       { reason_code: "unknown-entry-point", count: missingEntryPointCount },
     ],
   });

package/src/windows-child-process.mjs

@@ -0,0 +1,25 @@
+import childProcess from "node:child_process";
+import { syncBuiltinESMExports } from "node:module";
+
+const INSTALL_MARKER = Symbol.for("fallow.type-aware.windows-child-process-policy");
+
+const hiddenOptions = (options) => ({ ...options, windowsHide: true });
+
+/** Keep TypeScript-Go child processes hidden when the sidecar runs on Windows. */
+export const installWindowsChildProcessPolicy = ({
+  childProcess: processApi = childProcess,
+  platform = process.platform,
+  syncBuiltinESMExports: syncExports = syncBuiltinESMExports,
+} = {}) => {
+  if (platform !== "win32" || processApi[INSTALL_MARKER] === true) return;
+
+  const originalSpawn = processApi.spawn;
+  processApi.spawn = function spawnHidden(command, args, options) {
+    if (Array.isArray(args)) {
+      return originalSpawn.call(this, command, args, hiddenOptions(options));
+    }
+    return originalSpawn.call(this, command, hiddenOptions(args));
+  };
+  Object.defineProperty(processApi, INSTALL_MARKER, { value: true });
+  syncExports();
+};