fix(javascript): centralize module syntax and separate erased type dependencies

This commit is contained in:
morluto
2026-10-13 14:39:06 +08:00
parent e1cd292aa6
commit 1b953021ea
18 changed files with 513 additions and 134 deletions
@@ -0,0 +1,60 @@
import * as t from "@babel/types";
/** Whether TypeScript explicitly erases this entire import declaration. */
export const isTypeOnlyImportDeclaration = (
node: t.ImportDeclaration,
): boolean => node.importKind === "type" || node.importKind === "typeof";
/** Whether TypeScript explicitly erases this entire export declaration. */
export const isTypeOnlyExportDeclaration = (
node: t.ExportNamedDeclaration | t.ExportAllDeclaration,
): boolean =>
node.exportKind === "type" ||
(t.isExportNamedDeclaration(node) &&
node.declaration !== null &&
(t.isTSInterfaceDeclaration(node.declaration) ||
t.isTSTypeAliasDeclaration(node.declaration) ||
t.isTSDeclareFunction(node.declaration)));
/** Whether this import binding is explicitly type-only. */
export const isTypeOnlyImportSpecifier = (node: t.ImportSpecifier): boolean =>
node.importKind === "type" || node.importKind === "typeof";
/** Whether this exported binding is explicitly type-only. */
export const isTypeOnlyExportSpecifier = (node: t.ExportSpecifier): boolean =>
node.exportKind === "type";
/** A regular import whose bindings are all erased but may retain side effects. */
export const hasOnlyInlineTypeImportSpecifiers = (
node: t.ImportDeclaration,
): boolean =>
!isTypeOnlyImportDeclaration(node) &&
node.specifiers.length > 0 &&
node.specifiers.every(
(specifier) =>
t.isImportSpecifier(specifier) && isTypeOnlyImportSpecifier(specifier),
);
/** A regular re-export whose bindings are all erased but may retain side effects. */
export const hasOnlyInlineTypeExportSpecifiers = (
node: t.ExportNamedDeclaration,
): boolean =>
!isTypeOnlyExportDeclaration(node) &&
node.source != null &&
node.specifiers.length > 0 &&
node.specifiers.every(
(specifier) =>
t.isExportSpecifier(specifier) && isTypeOnlyExportSpecifier(specifier),
);
/** Whether compiler options leave an inline type-only declaration's side effect unknown. */
export const hasUncertainTypeOnlyModuleSideEffect = (
program: t.Program,
): boolean =>
program.body.some(
(node) =>
(t.isImportDeclaration(node) &&
hasOnlyInlineTypeImportSpecifiers(node)) ||
(t.isExportNamedDeclaration(node) &&
hasOnlyInlineTypeExportSpecifiers(node)),
);
@@ -0,0 +1,6 @@
/** Relative module syntax differs from an arbitrary dot-prefixed filename. */
export const isRelativeJavaScriptModuleSpecifier = (value: string): boolean =>
value === "." ||
value === ".." ||
value.startsWith("./") ||
value.startsWith("../");
@@ -22,6 +22,11 @@ describe("TypeScript import-equals links", () => {
localName: "dependency",
exportedName: null,
}),
expect.objectContaining({
kind: "type-import",
specifier: "./types",
localName: "types",
}),
]);
});
@@ -51,6 +56,57 @@ describe("TypeScript import-equals links", () => {
});
});
describe("TypeScript type-only module links", () => {
it("retains declarations without runtime bindings or callable claims", () => {
const ir = analyzeJavaScriptSemantics(`
import type { Whole } from "./whole";
import { type Inline } from "./inline";
import { type Erased, value } from "./mixed";
export type { Reexported } from "./reexported";
export { type InlineExport } from "./inline-export";
export type LocalType = string;
export interface LocalInterface { value: string }
function hiddenFunction() { return 1; }
export type { hiddenFunction };
`);
const externalLinks = ir.moduleLinks
.filter(({ specifier }) => specifier !== null)
.map(
({ kind, specifier, importedName, exportedName }) =>
[kind, specifier, importedName, exportedName] as const,
);
expect(externalLinks).toEqual([
["type-import", "./whole", "Whole", null],
["type-import", "./inline", "Inline", null],
["type-import", "./mixed", "Erased", null],
["import", "./mixed", "value", null],
["type-import", "./reexported", "Reexported", "Reexported"],
["type-import", "./inline-export", "InlineExport", "InlineExport"],
]);
const typeLinks = ir.moduleLinks
.filter(({ kind }) => kind === "type-import")
.map(
({ specifier, localName, exportedName, callableId }) =>
[specifier, localName, exportedName, callableId] as const,
);
expect(typeLinks).toEqual([
["./whole", "Whole", null, null],
["./inline", "Inline", null, null],
["./mixed", "Erased", null, null],
["./reexported", null, "Reexported", null],
["./inline-export", null, "InlineExport", null],
[null, "LocalType", "LocalType", null],
[null, "LocalInterface", "LocalInterface", null],
[null, "hiddenFunction", "hiddenFunction", null],
]);
expect(ir.limitations).toContain(
"Compiler options are unavailable; inline type-only imports or re-exports may preserve a module side-effect dependency.",
);
});
});
describe("CommonJS dependency links", () => {
it("retains an import-equals binding and its module origin", () => {
const ir = analyzeJavaScriptSemantics(`
@@ -76,6 +132,12 @@ describe("CommonJS dependency links", () => {
importedName: null,
localName: "typed",
}),
expect.objectContaining({
kind: "type-import",
specifier: "type-only",
importedName: null,
localName: "TypeOnly",
}),
]);
expect(ir.references.filter(({ name }) => name === "typed")).toHaveLength(
1,
@@ -43,6 +43,7 @@ import {
import { semanticRequireOrigin } from "./javascriptSemanticRequireOrigin.js";
import { collectSemanticMemberMutationsSteps } from "./javascriptSemanticMemberMutations.js";
import { indexJavaScriptAmbientWritesSteps } from "./javascriptSemanticAmbientWrites.js";
import { hasUncertainTypeOnlyModuleSideEffect } from "./javascriptModuleDeclaration.js";
import {
collectSemanticReturns,
resolveSemanticModuleCallables,
@@ -200,6 +201,11 @@ export function* analyzeParsedJavaScriptSemanticsSteps(
"The parser recovered from syntax errors; affected bindings are partial.",
]
: []),
...(hasUncertainTypeOnlyModuleSideEffect(file.program)
? [
"Compiler options are unavailable; inline type-only imports or re-exports may preserve a module side-effect dependency.",
]
: []),
"Values and aliases were recovered from inert syntax only; no JavaScript was executed.",
"Return sites include only direct callable returns; nested callable returns remain separate.",
"Local call, argument, return, and closure relations are static candidates and do not prove runtime invocation.",
@@ -28,6 +28,12 @@ import {
propertyName,
semanticStaticPropertyKey,
} from "./javascriptAstValues.js";
import {
isTypeOnlyExportDeclaration,
isTypeOnlyExportSpecifier,
isTypeOnlyImportDeclaration,
isTypeOnlyImportSpecifier,
} from "./javascriptModuleDeclaration.js";
interface CollectCallableInput {
readonly node: t.Node;
@@ -75,7 +81,7 @@ export const collectSemanticModuleLink = (
addModuleLink(
state,
{
kind: "re-export",
kind: isTypeOnlyExportDeclaration(node) ? "type-import" : "re-export",
specifier: node.source.value,
importedName: "*",
localName: null,
@@ -108,12 +114,19 @@ const collectImportEquals = (
node: t.TSImportEqualsDeclaration,
state: JavaScriptSemanticAnalysisState,
): void => {
const specifier = semanticImportEqualsSpecifier(node);
const moduleReference = node.moduleReference;
const specifier =
semanticImportEqualsSpecifier(node) ??
(node.importKind === "type" &&
t.isTSExternalModuleReference(moduleReference) &&
t.isStringLiteral(moduleReference.expression)
? moduleReference.expression.value
: null);
if (specifier === null) return;
addModuleLink(
state,
{
kind: "require",
kind: node.importKind === "type" ? "type-import" : "require",
specifier,
importedName: null,
localName: node.id.name,
@@ -287,7 +300,7 @@ const collectImports = (
addModuleLink(
state,
{
kind: "import",
kind: isTypeOnlyImportDeclaration(node) ? "type-import" : "import",
specifier: node.source.value,
importedName: null,
localName: null,
@@ -300,7 +313,12 @@ const collectImports = (
addModuleLink(
state,
{
kind: "import",
kind:
isTypeOnlyImportDeclaration(node) ||
(t.isImportSpecifier(specifier) &&
isTypeOnlyImportSpecifier(specifier))
? "type-import"
: "import",
specifier: node.source.value,
importedName: t.isImportDefaultSpecifier(specifier)
? "default"
@@ -319,12 +337,13 @@ const collectNamedExports = (
node: t.ExportNamedDeclaration,
state: JavaScriptSemanticAnalysisState,
): void => {
const declarationTypeOnly = isTypeOnlyExportDeclaration(node);
if (node.declaration !== null && node.declaration !== undefined)
for (const localName of declarationNames(node.declaration))
addModuleLink(
state,
{
kind: "export",
kind: declarationTypeOnly ? "type-import" : "export",
specifier: null,
importedName: null,
localName,
@@ -342,7 +361,14 @@ const collectNamedExports = (
addModuleLink(
state,
{
kind: node.source == null ? "export" : "re-export",
kind:
declarationTypeOnly ||
(t.isExportSpecifier(specifier) &&
isTypeOnlyExportSpecifier(specifier))
? "type-import"
: node.source == null
? "export"
: "re-export",
specifier: node.source?.value ?? null,
importedName: t.isExportNamespaceSpecifier(specifier)
? "*"
@@ -745,6 +771,13 @@ const declarationNames = (declaration: t.Declaration): string[] => {
t.isIdentifier(declaration.id)
)
return [declaration.id.name];
if (
(t.isTSInterfaceDeclaration(declaration) ||
t.isTSTypeAliasDeclaration(declaration) ||
t.isTSDeclareFunction(declaration)) &&
t.isIdentifier(declaration.id)
)
return [declaration.id.name];
if (
t.isTSImportEqualsDeclaration(declaration) &&
semanticImportEqualsSpecifier(declaration) !== null
@@ -101,6 +101,7 @@ export const resolveSemanticModuleCallables = (
bindings.map(({ bindingId, provenance }) => [bindingId, provenance]),
);
return state.moduleLinks.map((link) => {
if (link.kind === "type-import") return { ...link, callableId: null };
// Named exports follow their lexical binding, including every assignment.
// A declaration's ID or a callable's display name cannot prove that link.
if (link.localName === null)
@@ -53,6 +53,11 @@ import {
import { createJavaScriptRpcScan } from "./javascriptRpcEndpoints.js";
import { semanticImportEqualsSpecifier } from "./javascriptSemanticProjection.js";
import {
hasUncertainTypeOnlyModuleSideEffect,
isTypeOnlyExportDeclaration,
isTypeOnlyImportDeclaration,
} from "./javascriptModuleDeclaration.js";
/** Parse one JavaScript artifact and recover static structure only. */
export const analyzeJavaScriptStaticSource = (
@@ -154,6 +159,11 @@ const finalizeStaticAnalysis = (
: [
"One or more static keys, expressions, or Electron boundary values were dynamic and remain unknown.",
]),
...(hasUncertainTypeOnlyModuleSideEffect(file.program)
? [
"Compiler options are unavailable; inline type-only imports or re-exports may preserve a module side-effect dependency.",
]
: []),
...(accumulator.references.some(
({ value }) =>
value.specifier !== null && ELECTRON_MODULE.test(value.specifier),
@@ -246,14 +256,20 @@ const inspectNode = (
addReference(findings, { node, kind: "require", specifier });
} else if (
(t.isImportDeclaration(node) || t.isExportAllDeclaration(node)) &&
node.source !== undefined
node.source !== undefined &&
!(t.isImportDeclaration(node) && isTypeOnlyImportDeclaration(node)) &&
!(t.isExportAllDeclaration(node) && isTypeOnlyExportDeclaration(node))
)
addReference(findings, {
node,
kind: "static-import",
specifier: node.source.value,
});
else if (t.isExportNamedDeclaration(node) && node.source != null)
else if (
t.isExportNamedDeclaration(node) &&
node.source != null &&
!isTypeOnlyExportDeclaration(node)
)
addReference(findings, {
node,
kind: "static-import",