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 +5 -3
- package/package.json +3 -3
- package/src/backend-preflight.mjs +10 -11
- package/src/backend-selection.mjs +28 -0
- package/src/backend.mjs +13 -9
- package/src/generated-protocol.mjs +5 -1
- package/src/semantic-input.mjs +32 -0
- package/src/semantic.mjs +17 -20
- package/src/symbol-impact.mjs +12 -20
package/README.md
CHANGED
|
@@ -42,10 +42,12 @@ npm test
|
|
|
42
42
|
./fallow-type-aware.mjs < request.json
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
-
The
|
|
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
|
|
48
|
-
|
|
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.
|
|
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": "
|
|
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.
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
|
52
|
-
`typescript sync API backend; fallow-type-aware needs typescript
|
|
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 (
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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))
|
package/src/symbol-impact.mjs
CHANGED
|
@@ -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
|
|
32
|
+
return isStringLiteralLikeNode(node.moduleSpecifier) ? node.moduleSpecifier : undefined;
|
|
33
33
|
};
|
|
34
34
|
|
|
35
|
-
const
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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 = (
|
|
48
|
+
const recordModuleEdge = (project, reverse, consumer, files, specifier) => {
|
|
57
49
|
if (specifier === undefined) return;
|
|
58
|
-
const provider =
|
|
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(
|
|
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 };
|