fallow-type-aware 3.15.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,13 @@
 #!/usr/bin/env node
 
-import { run } from "./src/cli.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) });
 } catch (error) {
   const message = error instanceof Error ? error.message : String(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow-type-aware",
-  "version": "3.15.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/backend-preflight.mjs

@@ -0,0 +1,42 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import { BACKEND_VERSION } from "./generated-protocol.mjs";
+
+const REQUIRED_MAJOR = Number.parseInt(BACKEND_VERSION, 10);
+const INSTALL_HINT =
+  "run `npm ci` in tools/type-aware-sidecar so the sidecar resolves its own typescript install";
+
+/**
+ * Verify that module resolution hands the sidecar a typescript install that
+ * provides the `typescript/unstable/sync` backend entry point.
+ *
+ * The semantic modules import that entry point statically, so an incompatible
+ * resolution (for example a typescript 6 hoisted into an ancestor
+ * `node_modules`) fails at link time with a bare module path instead of the
+ * version conflict that caused it. This preflight runs before those imports
+ * and names the resolved version, its location, and the fix. Exact
+ * backend-version parity stays enforced in `protocol.mjs`.
+ *
+ * @param {string | URL} resolveFrom Module URL or file path to resolve from;
+ *   defaults to this module so the check mirrors the semantic imports.
+ */
+export const assertTypescriptBackendResolvable = (resolveFrom = import.meta.url) => {
+  const sidecarRequire = createRequire(resolveFrom);
+  let manifestPath;
+  try {
+    manifestPath = sidecarRequire.resolve("typescript/package.json");
+  } catch {
+    throw new Error(`typescript is not installed; ${INSTALL_HINT}`);
+  }
+  const { version } = sidecarRequire(manifestPath);
+  const major = Number.parseInt(version, 10);
+  if (Number.isFinite(major) && major >= REQUIRED_MAJOR) {
+    return;
+  }
+  throw new Error(
+    `resolved typescript ${version} from ${path.dirname(manifestPath)}, which lacks the ` +
+      `typescript/unstable/sync backend; fallow-type-aware needs typescript ${BACKEND_VERSION}; ` +
+      INSTALL_HINT,
+  );
+};

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-identity.mjs

@@ -12,9 +12,11 @@ import {
   isMethodDeclaration,
   isMethodSignatureDeclaration,
   isModuleDeclaration,
+  isNamespaceExport,
   isPropertyDeclaration,
   isPropertySignatureDeclaration,
   isSetAccessorDeclaration,
+  isSourceFile,
   isTypeAliasDeclaration,
   isVariableDeclaration,
 } from "typescript/unstable/ast/is";
@@ -45,7 +47,12 @@ const TYPE_ONLY_DECLARATIONS = [
   isTypeAliasDeclaration,
   isPropertySignatureDeclaration,
 ];
-const DUAL_NAMESPACE_DECLARATIONS = [isClassDeclaration, isClassExpression, isEnumDeclaration];
+const DUAL_NAMESPACE_DECLARATIONS = [
+  isClassDeclaration,
+  isClassExpression,
+  isEnumDeclaration,
+  isSourceFile,
+];
 const DECLARATION_OWNER_NODES = [isClassDeclaration, isClassExpression, isInterfaceDeclaration];
 
 const slash = (value) => value.split(path.sep).join("/");
@@ -101,6 +108,8 @@ export const ownerDeclaration = (node) => {
 
 export const isDeclaration = (node) => declarationKind(node) !== undefined;
 
+export const isExportAnchor = (node) => isExportSpecifier(node) || isNamespaceExport(node);
+
 const visit = (node, callback) => {
   callback(node);
   node.forEachChild((child) => {
@@ -151,6 +160,16 @@ const indexExportSpecifier = (index, node) => {
   );
 };
 
+const indexNamespaceExport = (index, node) => {
+  const exportedName = nodeText(node.name);
+  if (!exportedName) return;
+  [node.parent, node]
+    .flatMap((candidate) => positions(candidate))
+    .forEach((position) =>
+      indexExportPosition(index, node, { localName: exportedName, exportedName }, position),
+    );
+};
+
 const defaultModifierFor = (node) =>
   node.modifiers?.find((modifier) => modifier.getText(node.getSourceFile()) === "default");
 
@@ -197,6 +216,10 @@ const declarationIndex = (sourceFile) => {
       indexExportSpecifier(index, node);
       return;
     }
+    if (isNamespaceExport(node)) {
+      indexNamespaceExport(index, node);
+      return;
+    }
     indexDeclarationNode(index, node);
   });
   declarationIndexes.set(sourceFile, index);
@@ -205,7 +228,7 @@ const declarationIndex = (sourceFile) => {
 
 export const findDeclaration = (sourceFile, identity) => {
   const anchor = declarationIndex(sourceFile).get(anchorKey(identity));
-  if (!anchor || isExportSpecifier(anchor)) return anchor;
+  if (!anchor || isExportAnchor(anchor)) return anchor;
   return declarationNamespaces(anchor).has(identity.namespace) ? anchor : undefined;
 };
 

package/src/semantic.mjs

@@ -35,6 +35,7 @@ import {
   declarationsForSymbol,
   findDeclaration,
   isDeclaration,
+  isExportAnchor,
   isProjectSource,
   nodeText,
   ownerDeclaration,
@@ -156,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.",
@@ -165,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;
@@ -200,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) =>
@@ -680,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))
@@ -721,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 };
@@ -735,7 +758,7 @@ const selectSymbolContext = (
 
 const resolvedAnchorTarget = (project, anchor, requestedSymbol) => {
   if (!anchor) return undefined;
-  if (!isExportSpecifier(anchor)) {
+  if (!isExportAnchor(anchor)) {
     return declarationNamespaces(anchor).has(requestedSymbol.namespace)
       ? { declaration: anchor, namespace: requestedSymbol.namespace }
       : undefined;
@@ -1376,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(), []),
@@ -1546,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)),
   };
 };
 
@@ -1683,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 },
     ],
   });
@@ -1762,6 +1789,7 @@ const analyzeGraphSemanticQuery = (root, query, graphStates, evidenceLimit) => {
       missingEntryPoints,
       publicApiGraph,
       readyProjectStates,
+      unavailableProjectOmissions,
       uniqueSorted,
     },
   );
@@ -1841,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();
+};