fallow-type-aware 3.36.0 → 3.38.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -42,10 +42,12 @@ npm test
42
42
  ./fallow-type-aware.mjs < request.json
43
43
  ```
44
44
 
45
- The implementation pins `typescript@7.0.2` because `typescript/unstable/sync`
45
+ The package depends on `typescript@7.0.2` because `typescript/unstable/sync`
46
46
  is an explicitly unstable API. That backend detail is contained behind
47
- Fallow's stable, exact-version protocol. Package version, protocol version, and
48
- TypeScript backend version are validated independently. See
47
+ Fallow's stable, exact-version protocol. Package version and protocol version
48
+ must match Fallow exactly. The backend version must be in the supported range
49
+ of the protocol manifest, so a TypeScript 7 release that a package manager
50
+ override selects, or a newer tsrs, still works. See
49
51
  [`docs/type-aware-analysis.md`](../../docs/type-aware-analysis.md)
50
52
  for the Fallow integration contract, safety policy, and current limitations.
51
53
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fallow-type-aware",
3
- "version": "3.36.0",
3
+ "version": "3.38.0",
4
4
  "description": "Optional TypeScript-Go semantic refinement sidecar for Fallow",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -24,7 +24,7 @@
24
24
  "typescript": "7.0.2"
25
25
  },
26
26
  "peerDependencies": {
27
- "tsrs": "0.18.0-ts7.1.0-dev.20260929"
27
+ "tsrs": "*"
28
28
  },
29
29
  "peerDependenciesMeta": {
30
30
  "tsrs": {
@@ -41,7 +41,7 @@
41
41
  "devDependencies": {
42
42
  "@codspeed/tinybench-plugin": "5.7.1",
43
43
  "tinybench": "6.1.2",
44
- "tsrs": "0.18.0-ts7.1.0-dev.20260929",
44
+ "tsrs": "0.20.1-ts7.1.0-beta",
45
45
  "zod": "4.4.3"
46
46
  }
47
47
  }
@@ -1,10 +1,9 @@
1
1
  import { createRequire } from "node:module";
2
2
  import path from "node:path";
3
3
 
4
- import { selectBackend } from "./backend-selection.mjs";
4
+ import { selectBackend, supportedRange, supportsVersion } from "./backend-selection.mjs";
5
5
  import { BACKEND_VERSION, BACKEND_FAMILY } from "./generated-protocol.mjs";
6
6
 
7
- const REQUIRED_MAJOR = Number.parseInt(BACKEND_VERSION, 10);
8
7
  const INSTALL_HINT =
9
8
  "run `npm ci` in tools/type-aware-sidecar so the sidecar resolves its own typescript install";
10
9
 
@@ -16,11 +15,11 @@ const INSTALL_HINT =
16
15
  * resolution (for example a typescript 6 hoisted into an ancestor
17
16
  * `node_modules`) fails at link time with a bare module path instead of the
18
17
  * version conflict that caused it. This preflight runs before those imports
19
- * and names the resolved version, its location, and the fix. Exact
20
- * backend-version parity stays enforced in `protocol.mjs`.
18
+ * and names the resolved version, its location, and the fix.
21
19
  *
22
20
  * A backend that `FALLOW_TYPE_AWARE_BACKEND` selects instead of the default
23
- * must resolve at its exact pinned version.
21
+ * must resolve at a version in its supported range, so a project can reuse the
22
+ * tsrs it already installs.
24
23
  *
25
24
  * @param {string | URL} resolveFrom Module URL or file path to resolve from;
26
25
  * defaults to this module so the check mirrors the semantic imports.
@@ -43,13 +42,13 @@ export const assertTypescriptBackendResolvable = (
43
42
  throw new Error(`typescript is not installed; ${INSTALL_HINT}`);
44
43
  }
45
44
  const { version } = sidecarRequire(manifestPath);
46
- const major = Number.parseInt(version, 10);
47
- if (Number.isFinite(major) && major >= REQUIRED_MAJOR) {
45
+ if (supportsVersion(backend, version)) {
48
46
  return;
49
47
  }
50
48
  throw new Error(
51
- `resolved typescript ${version} from ${path.dirname(manifestPath)}, which lacks the ` +
52
- `typescript sync API backend; fallow-type-aware needs typescript ${BACKEND_VERSION}; ` +
49
+ `resolved typescript ${version} from ${path.dirname(manifestPath)}, which the ` +
50
+ `typescript sync API backend does not support; fallow-type-aware needs typescript ` +
51
+ `${supportedRange(backend)} (tested with ${BACKEND_VERSION}); ` +
53
52
  INSTALL_HINT,
54
53
  );
55
54
  };
@@ -63,9 +62,9 @@ const assertPinnedBackendResolvable = (sidecarRequire, backend) => {
63
62
  throw new Error(`the ${backend.family} backend is not installed; ${install}`);
64
63
  }
65
64
  const { version } = sidecarRequire(manifestPath);
66
- if (version === backend.version) return;
65
+ if (supportsVersion(backend, version)) return;
67
66
  throw new Error(
68
67
  `resolved ${backend.package} ${version} from ${path.dirname(manifestPath)}; ` +
69
- `the ${backend.family} backend needs exactly ${backend.version}; ${install}`,
68
+ `the ${backend.family} backend supports ${supportedRange(backend)}; ${install}`,
70
69
  );
71
70
  };
@@ -16,3 +16,31 @@ export const selectBackend = (env = process.env) => {
16
16
  const known = BACKENDS.map((candidate) => candidate.family).join(", ");
17
17
  throw new Error(`unknown ${BACKEND_ENV} value \`${requested}\`; expected one of: ${known}`);
18
18
  };
19
+
20
+ const versionCore = (version) => {
21
+ const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+]|$)/u.exec(version);
22
+ return match ? match.slice(1).map(Number) : undefined;
23
+ };
24
+
25
+ const compareCores = (left, right) =>
26
+ left.map((part, index) => part - right[index]).find((difference) => difference !== 0) ?? 0;
27
+
28
+ /**
29
+ * Whether a resolved backend package version is in the range that the
30
+ * protocol manifest supports. Only `major.minor.patch` counts, so a tsrs build
31
+ * tag such as `-ts7.1.0-beta` or a TypeScript prerelease stays in range.
32
+ *
33
+ * @param {{ minimum_version: string, below_version: string }} backend
34
+ * @param {string} version
35
+ */
36
+ export const supportsVersion = (backend, version) => {
37
+ const core = versionCore(version);
38
+ if (!core) return false;
39
+ return (
40
+ compareCores(core, versionCore(backend.minimum_version)) >= 0 &&
41
+ compareCores(core, versionCore(backend.below_version)) < 0
42
+ );
43
+ };
44
+
45
+ /** @param {{ minimum_version: string, below_version: string }} backend */
46
+ export const supportedRange = (backend) => `>=${backend.minimum_version} <${backend.below_version}`;
package/src/backend.mjs CHANGED
@@ -1,11 +1,21 @@
1
1
  import { existsSync } from "node:fs";
2
2
  import path from "node:path";
3
3
 
4
- import { selectBackend } from "./backend-selection.mjs";
4
+ import { selectBackend, supportedRange, supportsVersion } from "./backend-selection.mjs";
5
5
 
6
- export const BACKEND = selectBackend();
6
+ const SELECTED = selectBackend();
7
+ const { version: resolvedVersion } = await import(SELECTED.package);
8
+ if (!supportsVersion(SELECTED, resolvedVersion)) {
9
+ throw new Error(
10
+ `${SELECTED.package} backend version ${resolvedVersion} is outside the supported range ${supportedRange(SELECTED)}`,
11
+ );
12
+ }
7
13
 
8
- const { version: resolvedVersion } = await import(BACKEND.package);
14
+ /**
15
+ * The selected backend. `version` is the resolved package version, which can
16
+ * differ from the tested version in the protocol manifest.
17
+ */
18
+ export const BACKEND = Object.freeze({ ...SELECTED, version: resolvedVersion });
9
19
  // TypeScript 7.1 serves the API at `typescript/sync`. TypeScript 7.0 and its
10
20
  // 7.1 dev builds serve it at `typescript/unstable/sync`.
11
21
  const importApi = async (subpath) => {
@@ -21,12 +31,6 @@ export const ast = await importApi("ast/is");
21
31
  export const { SyntaxKind } = await importApi("ast");
22
32
  const { serverFS } = await importApi("fs");
23
33
 
24
- if (resolvedVersion !== BACKEND.version) {
25
- throw new Error(
26
- `${BACKEND.package} backend version ${resolvedVersion} does not match protocol ${BACKEND.version}`,
27
- );
28
- }
29
-
30
34
  /**
31
35
  * The value a `readFile` callback returns to read the file from disk.
32
36
  * TypeScript 7.0 reads from disk on `undefined`. TypeScript 7.1 treats
@@ -11,13 +11,17 @@ export const TYPE_AWARE_PROTOCOL = Object.freeze({
11
11
  backend: {
12
12
  family: "typescript-go",
13
13
  version: "7.0.2",
14
+ minimum_version: "7.0.0",
15
+ below_version: "8.0.0",
14
16
  package: "typescript",
15
17
  },
16
18
  experimental_backends: [
17
19
  {
18
20
  family: "tsrs",
19
21
  package: "tsrs",
20
- version: "0.18.0-ts7.1.0-dev.20260929",
22
+ version: "0.20.1-ts7.1.0-beta",
23
+ minimum_version: "0.18.0",
24
+ below_version: "1.0.0",
21
25
  },
22
26
  ],
23
27
  sidecar: {
@@ -0,0 +1,32 @@
1
+ import { existsSync } from "node:fs";
2
+ import path from "node:path";
3
+
4
+ /** Source extensions accepted by the semantic backend, including declaration-file suffixes. */
5
+ export const MODULE_SOURCE_EXTENSIONS = [
6
+ ".ts",
7
+ ".tsx",
8
+ ".mts",
9
+ ".cts",
10
+ ".js",
11
+ ".jsx",
12
+ ".mjs",
13
+ ".cjs",
14
+ ];
15
+
16
+ /** Whether the backend can parse the query's source without a component transform. */
17
+ export const isSupportedSemanticQuery = (query) =>
18
+ !query.symbol ||
19
+ MODULE_SOURCE_EXTENSIONS.includes(path.extname(query.symbol.absolutePath).toLowerCase());
20
+
21
+ /** Component files must stay out of openFiles because the backend cannot infer their script kind. */
22
+ export const semanticOpenFiles = (queries) =>
23
+ queries
24
+ .filter((query) => query.symbol && isSupportedSemanticQuery(query))
25
+ .map((query) => query.symbol.absolutePath);
26
+
27
+ /** Resolve explicit projects or the conventional root project. */
28
+ export const semanticOpenProjects = (root, projects) => {
29
+ if (projects.length > 0) return projects.map((project) => project.absolutePath);
30
+ const conventionalProject = path.join(root, "tsconfig.json");
31
+ return existsSync(conventionalProject) ? [conventionalProject] : [];
32
+ };
package/src/semantic.mjs CHANGED
@@ -48,6 +48,12 @@ import {
48
48
  targetName,
49
49
  } from "./symbol-targets.mjs";
50
50
  import { analyzeTypeCoupling } from "./type-coupling.mjs";
51
+ import {
52
+ MODULE_SOURCE_EXTENSIONS,
53
+ isSupportedSemanticQuery,
54
+ semanticOpenFiles,
55
+ semanticOpenProjects,
56
+ } from "./semantic-input.mjs";
51
57
 
52
58
  const { SignatureKind, SymbolFlags } = sync;
53
59
  const {
@@ -493,8 +499,6 @@ const importTypeSpecifier = (node) => {
493
499
  return literal && isStringLiteralLikeNode(literal) ? literal : undefined;
494
500
  };
495
501
 
496
- const MODULE_SOURCE_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
497
-
498
502
  const lexicalModuleIdentityForText = (project, sourceFile, specifierText) => {
499
503
  if (!specifierText?.startsWith(".")) return undefined;
500
504
  const resolved = path.resolve(path.dirname(sourceFile.fileName), specifierText);
@@ -748,11 +752,11 @@ const selectSymbolContext = (
748
752
  query,
749
753
  allowDefaultFallback,
750
754
  ) => {
751
- if (!DECLARATION_KINDS.has(query.symbol.declarationKind)) {
755
+ if (!isSupportedSemanticQuery(query) || !DECLARATION_KINDS.has(query.symbol.declarationKind)) {
752
756
  return symbolResolutionError(
753
757
  query,
754
758
  "unsupported-syntax",
755
- "Use a supported declaration kind or retain the syntactic finding.",
759
+ "Use a supported TypeScript or JavaScript declaration or retain the syntactic finding.",
756
760
  );
757
761
  }
758
762
  let owners = owningProjectContexts(statesByProject, query.symbol.absolutePath);
@@ -1403,16 +1407,16 @@ const signatureTypes = (project, type, anchor) =>
1403
1407
 
1404
1408
  const checkerTypeChildren = (project, type, anchor, hasNamedDeclaration) => {
1405
1409
  if (type.isTypeParameter()) {
1406
- const constraint = safeCheckerValue(
1407
- () => project.checker.getConstraintOfTypeParameter(type),
1408
- undefined,
1409
- );
1410
+ const constraint = safeCheckerValue(() => project.checker.getConstraintOfTypeParameter(type));
1410
1411
  return constraint ? [constraint] : [];
1411
1412
  }
1412
1413
  const structural = [
1413
1414
  ...(type.getTypes() ?? []),
1414
1415
  ...safeCheckerValue(() => type.getAliasTypeArguments(), []),
1415
- ...safeCheckerValue(() => project.checker.getTypeArguments(type), []),
1416
+ // On tsrs, this call panics to stderr for a type that is not a reference.
1417
+ ...(type.isTypeReference()
1418
+ ? safeCheckerValue(() => project.checker.getTypeArguments(type), [])
1419
+ : []),
1416
1420
  ].filter(Boolean);
1417
1421
  if (hasNamedDeclaration) return structural;
1418
1422
  const direct = [...structural, ...signatureTypes(project, type, anchor)];
@@ -1725,8 +1729,10 @@ const emptySemanticAnalysis = (queries) => ({
1725
1729
  results: queries.map((query) =>
1726
1730
  unavailable(
1727
1731
  query,
1728
- "no-project",
1729
- "Pass an explicit tsconfig with --type-aware-project and retry.",
1732
+ isSupportedSemanticQuery(query) ? "no-project" : "unsupported-syntax",
1733
+ isSupportedSemanticQuery(query)
1734
+ ? "Pass an explicit tsconfig with --type-aware-project and retry."
1735
+ : "Use a supported TypeScript or JavaScript declaration or retain the syntactic finding.",
1730
1736
  ),
1731
1737
  ),
1732
1738
  phaseTimings: { project_setup: 0, diagnostics: 0, semantic_queries: 0 },
@@ -1956,15 +1962,6 @@ const emptyRequestedAnalysis = () => ({
1956
1962
  warnings: [],
1957
1963
  });
1958
1964
 
1959
- const semanticOpenFiles = (queries) =>
1960
- queries.filter((query) => query.symbol).map((query) => query.symbol.absolutePath);
1961
-
1962
- const semanticOpenProjects = (root, projects) => {
1963
- if (projects.length > 0) return projects.map((project) => project.absolutePath);
1964
- const conventionalProject = path.join(root, "tsconfig.json");
1965
- return existsSync(conventionalProject) ? [conventionalProject] : [];
1966
- };
1967
-
1968
1965
  const semanticProjectSelection = (snapshot, openProjects, openFiles, allowDefaultFallback) => {
1969
1966
  const explicitProjects = openProjects
1970
1967
  .map((project) => snapshot.getProject(project))
@@ -2,8 +2,8 @@ import path from "node:path";
2
2
 
3
3
  import { ast } from "./backend.mjs";
4
4
 
5
- import { canonicalFileIdentity } from "./file-identity.mjs";
6
5
  import {
6
+ declarationsForSymbol,
7
7
  projectSourceFiles,
8
8
  relativePath,
9
9
  semanticQueryIdentity,
@@ -29,22 +29,14 @@ const isModuleEdgeDeclaration = (node) => isImportDeclaration(node) || isExportD
29
29
  const moduleSpecifier = (node) => {
30
30
  if (!isModuleEdgeDeclaration(node)) return undefined;
31
31
  if (!node.moduleSpecifier) return undefined;
32
- return isStringLiteralLikeNode(node.moduleSpecifier) ? node.moduleSpecifier.text : null;
32
+ return isStringLiteralLikeNode(node.moduleSpecifier) ? node.moduleSpecifier : undefined;
33
33
  };
34
34
 
35
- const resolveLocalModule = (sourceFile, specifier, files) => {
36
- if (!specifier?.startsWith(".")) return undefined;
37
- const base = path.resolve(path.dirname(sourceFile.fileName), specifier);
38
- const candidates = [
39
- base,
40
- `${base}.ts`,
41
- `${base}.tsx`,
42
- `${base}.js`,
43
- `${base}.jsx`,
44
- path.join(base, "index.ts"),
45
- path.join(base, "index.tsx"),
46
- ];
47
- return candidates.map(canonicalFileIdentity).find((candidate) => files.has(candidate));
35
+ const resolveProjectModule = (project, specifier, files) => {
36
+ const symbol = project.checker.getSymbolAtLocation(specifier);
37
+ return declarationsForSymbol(project, symbol)
38
+ .map((declaration) => sourceFileIdentity(declaration.getSourceFile()))
39
+ .find((identity) => files.has(identity));
48
40
  };
49
41
 
50
42
  const addReverseModuleEdge = (reverse, provider, consumer) => {
@@ -53,9 +45,9 @@ const addReverseModuleEdge = (reverse, provider, consumer) => {
53
45
  reverse.set(provider, consumers);
54
46
  };
55
47
 
56
- const recordModuleEdge = (reverse, sourceFile, consumer, files, specifier) => {
48
+ const recordModuleEdge = (project, reverse, consumer, files, specifier) => {
57
49
  if (specifier === undefined) return;
58
- const provider = resolveLocalModule(sourceFile, specifier, files);
50
+ const provider = resolveProjectModule(project, specifier, files);
59
51
  if (provider) addReverseModuleEdge(reverse, provider, consumer);
60
52
  };
61
53
 
@@ -68,11 +60,11 @@ const hasUnresolvedDynamicImport = (node, sourceFile) => {
68
60
  return !argument || !isStringLiteralLikeNode(argument);
69
61
  };
70
62
 
71
- const scanModuleSource = (sourceFile, files, reverse) => {
63
+ const scanModuleSource = (project, sourceFile, files, reverse) => {
72
64
  const consumer = sourceFileIdentity(sourceFile);
73
65
  let hasDynamicBehavior = false;
74
66
  visit(sourceFile, (node) => {
75
- recordModuleEdge(reverse, sourceFile, consumer, files, moduleSpecifier(node));
67
+ recordModuleEdge(project, reverse, consumer, files, moduleSpecifier(node));
76
68
  hasDynamicBehavior ||= hasUnresolvedDynamicImport(node, sourceFile);
77
69
  });
78
70
  return hasDynamicBehavior;
@@ -84,7 +76,7 @@ const moduleGraph = (project) => {
84
76
  const reverse = new Map();
85
77
  let hasDynamicBehavior = false;
86
78
  for (const sourceFile of sources) {
87
- const sourceHasDynamicBehavior = scanModuleSource(sourceFile, files, reverse);
79
+ const sourceHasDynamicBehavior = scanModuleSource(project, sourceFile, files, reverse);
88
80
  hasDynamicBehavior ||= sourceHasDynamicBehavior;
89
81
  }
90
82
  return { reverse, hasDynamicBehavior };