An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): the export reader reports type-only exports on request, in one pass (#10365)
Cindy Zhang8b16f6d4dfdb
diff --git a/.changeset/cli-export-reader-types.md b/.changeset/cli-export-reader-types.mdnew file mode 100644index 0000000000..aa4280eee8--- /dev/null+++ b/.changeset/cli-export-reader-types.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[chore] Internal: the export reader can report type-only exports and map a module's whole public surface in one pass. No change to any command's output.++@cixzhangdiff --git a/packages/cli/foundation/discovery/module-exports.mjs b/packages/cli/foundation/discovery/module-exports.mjsindex 771d0ddbfe..4b3687bfd4 100644--- a/packages/cli/foundation/discovery/module-exports.mjs+++ b/packages/cli/foundation/discovery/module-exports.mjs@@ -198,8 +198,14 @@ function collectNodesOfType(node, type, found) {return found;}-/** @param {unknown} specifier @param {string} fromFile */-function resolveLocalModule(specifier, fromFile) {+/**+ * The file a relative import names: the path itself, then each module+ * extension, then a folder's index. Null for a bare specifier or no file.+ * @param {unknown} specifier+ * @param {string} fromFile absolute path of the importing file+ * @returns {string|null}+ */+export function resolveLocalModule(specifier, fromFile) {if (typeof specifier !== 'string' || !specifier.startsWith('.')) return null;const base = path.resolve(path.dirname(fromFile), specifier);const candidates = [@@ -347,17 +353,43 @@ export function unfollowedReexports(file) {return [...missing].sort();}-/** @param {any} declaration @param {string} exportName */-function declarationExports(declaration, exportName) {- if (!declaration || declaration.declare === true) return false;- if (['FunctionDeclaration', 'ClassDeclaration'].includes(declaration.type)) {- return declaration.id?.name === exportName;+/** Declarations that name a type, which a type-aware read also follows. */+const TYPE_DECLARATIONS = [+ 'TSInterfaceDeclaration',+ 'TSTypeAliasDeclaration',+ 'TSEnumDeclaration',+ 'TSModuleDeclaration',+ 'TSDeclareFunction',+];++/**+ * @param {any} declaration+ * @param {string} exportName+ * @param {boolean} [types] also count type declarations and `declare` ones+ */+function declarationExports(declaration, exportName, types = false) {+ return declaredNames(declaration, types).includes(exportName);+}++/**+ * The names an exported declaration binds.+ * @param {any} declaration+ * @param {boolean} [types] also count type declarations and `declare` ones+ * @returns {string[]}+ */+function declaredNames(declaration, types = false) {+ if (!declaration || (declaration.declare === true && !types)) return [];+ if (+ ['FunctionDeclaration', 'ClassDeclaration'].includes(declaration.type) ||+ (types && TYPE_DECLARATIONS.includes(declaration.type))+ ) {+ const name = declaration.id?.name;+ return typeof name === 'string' ? [name] : [];}- if (declaration.type !== 'VariableDeclaration') return false;- return declaration.declarations.some(- (/** @type {any} */ item) =>- item.id?.type === 'Identifier' && item.id.name === exportName,- );+ if (declaration.type !== 'VariableDeclaration') return [];+ return declaration.declarations+ .filter((/** @type {any} */ item) => item.id?.type === 'Identifier')+ .map((/** @type {any} */ item) => item.id.name);}/** @param {any} declaration */@@ -574,6 +606,139 @@ export function moduleExportNames(file) {return [...names].sort();}+/**+ * Every export of a module with where it is declared, in one pass: the same+ * answers as {@link moduleExportOrigin} for each name, read once per module.+ * Pass one `memo` to calls that read the same package, so a module behind+ * many barrels is read once; a memo keeps value and type reads apart, and+ * nothing is kept between memos. One difference follows ESM where+ * {@link moduleExportOrigin} does not: a name re-exported by name from a+ * module that cannot be followed is absent, never filled from `export *`.+ * @param {string} file+ * @param {{types?: boolean, memo?: Map<string, Map<string, {file: string, name: string}>>}} [options]+ * @returns {Map<string, {file: string, name: string}>}+ */+export function moduleExportOrigins(+ file,+ {types = false, memo = new Map()} = {},+) {+ return exportOriginsOf(file, {types, memo, reading: new Map()}).origins;+}++/**+ * @typedef {object} OriginsRead+ * @property {boolean} types+ * @property {Map<string, Map<string, {file: string, name: string}>>} memo+ * finished maps, keyed by read mode and file+ * @property {Map<string, {depth: number, origins: Map<string, {file: string, name: string}>}>} reading+ * the modules being read now, by memo key+ */++/**+ * One module's export map, and the shallowest module still being read that+ * it depends on (`low`). A map that depends on a module above it in an+ * `export *` cycle is incomplete until that module finishes, so only a map+ * whose `low` is its own depth goes in the memo.+ * @param {string} file+ * @param {OriginsRead} read+ * @returns {{origins: Map<string, {file: string, name: string}>, low: number}}+ */+function exportOriginsOf(file, read) {+ const key = `${read.types ? 'type' : 'value'}\0${file}`;+ const known = read.memo.get(key);+ if (known) return {origins: known, low: Infinity};+ const open = read.reading.get(key);+ // A module reached again through a cycle reads as what is known so far.+ if (open) return {origins: open.origins, low: open.depth};+ const depth = read.reading.size;+ /** @type {Map<string, {file: string, name: string}>} */+ const origins = new Map();+ let low = Infinity;+ read.reading.set(key, {depth, origins});+ /** @param {string} target */+ const originsOf = target => {+ const result = exportOriginsOf(target, read);+ low = Math.min(low, result.low);+ return result.origins;+ };+ try {+ let ast;+ try {+ if (!fs.statSync(file).isFile()) return {origins, low};+ ast = parseModule(file);+ } catch {+ return {origins, low};+ }+ const {types} = read;+ // A name the module exports by name shadows every `export *`, even when+ // its binding cannot be followed.+ const named = new Set();+ const {declarations, specifiers} = namedExportIndex(ast.program, types);+ for (const node of declarations) {+ for (const name of declaredNames(node.declaration, types)) {+ named.add(name);+ if (!origins.has(name)) origins.set(name, {file, name});+ }+ }+ for (const [exportName, entries] of specifiers) {+ named.add(exportName);+ if (origins.has(exportName)) continue;+ for (const {node, specifier} of entries) {+ const local =+ specifier.local?.name ?? specifier.local?.value ?? exportName;+ let origin = null;+ if (node.source) {+ const target = resolveModuleOrPackage(node.source.value, file);+ if (target) {+ const result = exportOriginsOf(target, read);+ low = Math.min(low, result.low);+ // A map that depends on a module still being read is partial, so+ // a name missing from it is followed on its own.+ origin =+ result.origins.get(local) ??+ (result.low < Infinity+ ? moduleExportOrigin(target, local, new Set(), {types})+ : null);+ }+ } else {+ origin = bindingOrigin(ast, file, local, new Set(), types);+ }+ if (origin) {+ origins.set(exportName, origin);+ break;+ }+ if (!node.source) break;+ }+ }+ for (const node of nodesOfType(ast.program, 'ExportDefaultDeclaration')) {+ named.add('default');+ if (origins.has('default')) break;+ const declaration = node.declaration;+ if (!types && !runtimeDefault(declaration)) continue;+ const origin =+ declaration.type === 'Identifier'+ ? bindingOrigin(ast, file, declaration.name, new Set(), types)+ : {file, name: 'default'};+ if (origin) origins.set('default', origin);+ break;+ }+ for (const node of nodesOfType(ast.program, 'ExportAllDeclaration')) {+ if ((node.exportKind === 'type' && !types) || node.exported) continue;+ const target = resolveModuleOrPackage(node.source?.value, file);+ if (!target) continue;+ for (const [name, origin] of originsOf(target)) {+ if (name !== 'default' && !named.has(name) && !origins.has(name)) {+ origins.set(name, origin);+ }+ }+ }+ return {origins, low};+ } finally {+ read.reading.delete(key);+ if (low >= depth) read.memo.set(key, origins);+ }+}+/*** @typedef {{verdict: 'exports'} | {verdict: 'lacks'} | {verdict: 'unknown', reason: string}} ExportVerdict*/@@ -926,22 +1091,25 @@ export function staticExportObject(file, exportNames) {* @type {WeakMap<object, {declarations: any[], specifiers: Map<string, Array<{node: any, specifier: any}>>}>}*/const namedExportIndexes = new WeakMap();+/** The same index with type-only exports included. */+const typedExportIndexes = new WeakMap();-/** @param {any} program */-function namedExportIndex(program) {- const cached = namedExportIndexes.get(program);+/** @param {any} program @param {boolean} [types] include type-only exports */+function namedExportIndex(program, types = false) {+ const indexes = types ? typedExportIndexes : namedExportIndexes;+ const cached = indexes.get(program);if (cached) return cached;/** @type {any[]} */const declarations = [];/** @type {Map<string, Array<{node: any, specifier: any}>>} */const specifiers = new Map();for (const node of nodesOfType(program, 'ExportNamedDeclaration')) {- if (node.exportKind === 'type') continue;+ if (node.exportKind === 'type' && !types) continue;if (node.declaration) declarations.push(node);for (const specifier of node.specifiers ?? []) {if (specifier.type !== 'ExportSpecifier' ||- specifier.exportKind === 'type'+ (specifier.exportKind === 'type' && !types)) {continue;}@@ -952,7 +1120,7 @@ function namedExportIndex(program) {}}const index = {declarations, specifiers};- namedExportIndexes.set(program, index);+ indexes.set(program, index);return index;}@@ -961,12 +1129,19 @@ function namedExportIndex(program) {* has there, without executing anything: local re-exports, renames, and* imported bindings a module exports again are followed. Two exports are the* same value when their origins are equal. Null when it cannot be proved.+ * With `types`, type-only exports and type declarations are followed too.* @param {string} file* @param {string} exportName* @param {Set<string>} [seen]+ * @param {{types?: boolean}} [options]* @returns {{file: string, name: string} | null}*/-export function moduleExportOrigin(file, exportName, seen = new Set()) {+export function moduleExportOrigin(+ file,+ exportName,+ seen = new Set(),+ {types = false} = {},+) {const identity = `${file}\0${exportName}`;if (seen.has(identity)) return null;seen.add(identity);@@ -977,9 +1152,9 @@ export function moduleExportOrigin(file, exportName, seen = new Set()) {} catch {return null;}- const {declarations, specifiers} = namedExportIndex(ast.program);+ const {declarations, specifiers} = namedExportIndex(ast.program, types);for (const node of declarations) {- if (declarationExports(node.declaration, exportName)) {+ if (declarationExports(node.declaration, exportName, types)) {return {file, name: exportName};}}@@ -987,26 +1162,30 @@ export function moduleExportOrigin(file, exportName, seen = new Set()) {const local = specifier.local?.name ?? specifier.local?.value ?? exportName;if (node.source) {const target = resolveModuleOrPackage(node.source.value, file);- const origin = target ? moduleExportOrigin(target, local, seen) : null;+ const origin = target+ ? moduleExportOrigin(target, local, seen, {types})+ : null;if (origin) return origin;continue;}- return bindingOrigin(ast, file, local, seen);+ return bindingOrigin(ast, file, local, seen, types);}if (exportName === 'default') {for (const node of nodesOfType(ast.program, 'ExportDefaultDeclaration')) {const declaration = node.declaration;- if (!runtimeDefault(declaration)) continue;+ if (!types && !runtimeDefault(declaration)) continue;if (declaration.type === 'Identifier') {- return bindingOrigin(ast, file, declaration.name, seen);+ return bindingOrigin(ast, file, declaration.name, seen, types);}return {file, name: 'default'};}}for (const node of nodesOfType(ast.program, 'ExportAllDeclaration')) {- if (node.exportKind === 'type' || node.exported) continue;+ if ((node.exportKind === 'type' && !types) || node.exported) continue;const target = resolveModuleOrPackage(node.source?.value, file);- const origin = target ? moduleExportOrigin(target, exportName, seen) : null;+ const origin = target+ ? moduleExportOrigin(target, exportName, seen, {types})+ : null;if (origin) return origin;}return null;@@ -1128,12 +1307,18 @@ function originGapReason(file, exportName, seen = new Set()) {* named exports and, through `export *` from local files and installed* packages, theirs. Unlike {@link moduleExportNames}, it never gives up on an* `export *`: what it cannot read is left out. Type-only- * exports and `default` are left out. Sorted.+ * exports are left out unless `types` asks for them; `default` always is.+ * Sorted.* @param {string} file* @param {Set<string>} [seen]+ * @param {{types?: boolean}} [options]* @returns {string[]}*/-export function followedExportNames(file, seen = new Set()) {+export function followedExportNames(+ file,+ seen = new Set(),+ {types = false} = {},+) {if (seen.has(file)) return [];seen.add(file);let ast;@@ -1146,11 +1331,14 @@ export function followedExportNames(file, seen = new Set()) {/** @type {Set<string>} */const names = new Set();for (const node of nodesOfType(ast.program, 'ExportNamedDeclaration')) {- if (node.exportKind === 'type') continue;+ if (node.exportKind === 'type' && !types) continue;const declaration = node.declaration;- if (declaration && declaration.declare !== true) {+ if (declaration && (declaration.declare !== true || types)) {if (- ['FunctionDeclaration', 'ClassDeclaration'].includes(declaration.type)+ ['FunctionDeclaration', 'ClassDeclaration'].includes(+ declaration.type,+ ) ||+ (types && TYPE_DECLARATIONS.includes(declaration.type))) {if (declaration.id?.name) names.add(declaration.id.name);} else if (declaration.type === 'VariableDeclaration') {@@ -1162,7 +1350,7 @@ export function followedExportNames(file, seen = new Set()) {for (const specifier of node.specifiers ?? []) {if (specifier.type !== 'ExportSpecifier' ||- specifier.exportKind === 'type'+ (specifier.exportKind === 'type' && !types)) {continue;}@@ -1173,10 +1361,12 @@ export function followedExportNames(file, seen = new Set()) {}}for (const node of nodesOfType(ast.program, 'ExportAllDeclaration')) {- if (node.exportKind === 'type' || node.exported) continue;+ if ((node.exportKind === 'type' && !types) || node.exported) continue;const target = resolveModuleOrPackage(node.source?.value, file);if (target) {- for (const name of followedExportNames(target, seen)) names.add(name);+ for (const name of followedExportNames(target, seen, {types})) {+ names.add(name);+ }}}return [...names].sort();@@ -1439,11 +1629,15 @@ export function elementPropOrigins(file, {sources, name, prop, unwrap}) {* @param {string} file* @param {string} local* @param {Set<string>} seen+ * @param {boolean} [types] also follow `import type`* @returns {{file: string, name: string} | null}*/-function bindingOrigin(ast, file, local, seen) {+function bindingOrigin(ast, file, local, seen, types = false) {for (const node of ast.program.body) {- if (node.type !== 'ImportDeclaration' || node.importKind === 'type') {+ if (+ node.type !== 'ImportDeclaration' ||+ (node.importKind === 'type' && !types)+ ) {continue;}for (const specifier of node.specifiers ?? []) {@@ -1452,7 +1646,9 @@ function bindingOrigin(ast, file, local, seen) {const imported =specifier.imported?.name ?? specifier.imported?.value ?? local;const target = resolveModuleOrPackage(node.source.value, file);- return target ? moduleExportOrigin(target, imported, seen) : null;+ return target+ ? moduleExportOrigin(target, imported, seen, {types})+ : null;}}return {file, name: local};diff --git a/packages/cli/foundation/discovery/module-exports.test.mjs b/packages/cli/foundation/discovery/module-exports.test.mjsindex c750b733b4..f1935b9fcb 100644--- a/packages/cli/foundation/discovery/module-exports.test.mjs+++ b/packages/cli/foundation/discovery/module-exports.test.mjs@@ -12,6 +12,7 @@ import * as path from 'node:path';import {elementPropOrigins,moduleExportOrigin,+ moduleExportOrigins,moduleExportSource,staticExportObject,} from './module-exports.mjs';@@ -276,3 +277,135 @@ describe('elementPropOrigins', () => {expect(elementPropOrigins(app, THEME)).toEqual([null]);});});++describe('moduleExportOrigins', () => {+ /** @type {string} */+ let dir;+ beforeEach(() => {+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-export-origins-'));+ const write = (name, text) => fs.writeFileSync(path.join(dir, name), text);+ write('values.ts', 'export const a = 1;\nexport function b() {}\n');+ write('types.ts', 'export interface Shape {}\nexport type Size = 1;\n');+ write(+ 'local.ts',+ "import {a as inner} from './values';\nexport {inner as renamed};\n",+ );+ write(+ 'index.ts',+ [+ "export * from './values';",+ "export type {Shape} from './types';",+ "export {renamed} from './local';",+ "export * from './types';",+ 'export const own = 2;',+ '',+ ].join('\n'),+ );+ });+ afterEach(() => {+ fs.rmSync(dir, {recursive: true, force: true});+ });++ it('gives the origin moduleExportOrigin gives for every name', () => {+ const index = path.join(dir, 'index.ts');+ for (const types of [false, true]) {+ const origins = moduleExportOrigins(index, {types});+ const names = ['a', 'b', 'renamed', 'own', 'Shape', 'Size'];+ for (const name of names) {+ expect(origins.get(name) ?? null, `${name} (types: ${types})`).toEqual(+ moduleExportOrigin(index, name, undefined, {types}),+ );+ }+ }+ });++ it('agrees through an export * cycle', () => {+ const write = (name, text) => fs.writeFileSync(path.join(dir, name), text);+ write('c.ts', 'export const w = 1;\nexport const z = 2;\n');+ write('a.ts', "export * from './b';\nexport * from './c';\n");+ write('b.ts', "export * from './a';\n");+ const cycle = path.join(dir, 'cycle.ts');+ fs.writeFileSync(cycle, "export {w} from './a';\nexport * from './b';\n");+ const origins = moduleExportOrigins(cycle);+ for (const name of ['w', 'z']) {+ expect(origins.get(name) ?? null, name).toEqual(+ moduleExportOrigin(cycle, name),+ );+ }+ expect(origins.get('z')).toEqual({file: path.join(dir, 'c.ts'), name: 'z'});+ });++ it('agrees when a named re-export reaches back into an open cycle', () => {+ const write = (name, text) => fs.writeFileSync(path.join(dir, name), text);+ write('leaf.ts', 'export const leafValue = 1;\n');+ write('mid.ts', "export * from './outer';\n");+ const outer = path.join(dir, 'outer.ts');+ fs.writeFileSync(+ outer,+ "export {leafValue as fromRoot} from './mid';\nexport * from './leaf';\n",+ );+ expect(moduleExportOrigins(outer).get('fromRoot')).toEqual({+ file: path.join(dir, 'leaf.ts'),+ name: 'leafValue',+ });+ });++ it('agrees through a cycle closed by a named re-export', () => {+ const write = (name, text) => fs.writeFileSync(path.join(dir, name), text);+ write('leaf.ts', 'export const leafValue = 1;\n');+ write('sub.ts', "export {leafValue as fromRoot} from './root';\n");+ const root = path.join(dir, 'root.ts');+ fs.writeFileSync(root, "export * from './sub';\nexport * from './leaf';\n");+ expect(moduleExportOrigins(root).get('fromRoot')).toEqual({+ file: path.join(dir, 'leaf.ts'),+ name: 'leafValue',+ });+ expect(moduleExportOrigins(root).get('fromRoot')).toEqual(+ moduleExportOrigin(root, 'fromRoot'),+ );+ });++ it('lets a named export shadow export *, even when it cannot be followed', () => {+ const write = (name, text) => fs.writeFileSync(path.join(dir, name), text);+ write('other.ts', 'export const x = 1;\n');+ const shadow = path.join(dir, 'shadow.ts');+ fs.writeFileSync(+ shadow,+ [+ "import {x} from 'not-installed-pkg';",+ 'export {x};',+ "export * from './other';",+ '',+ ].join('\n'),+ );+ expect(moduleExportOrigins(shadow).get('x') ?? null).toEqual(+ moduleExportOrigin(shadow, 'x'),+ );+ expect(moduleExportOrigins(shadow).has('x')).toBe(false);+ });++ it('keeps value and type reads apart in one memo', () => {+ const index = path.join(dir, 'index.ts');+ const memo = new Map();+ expect(moduleExportOrigins(index, {memo}).has('Shape')).toBe(false);+ expect(+ moduleExportOrigins(index, {types: true, memo}).get('Shape'),+ ).toEqual({+ file: path.join(dir, 'types.ts'),+ name: 'Shape',+ });+ });++ it('follows type-only exports only when asked', () => {+ const index = path.join(dir, 'index.ts');+ expect(moduleExportOrigins(index).has('Shape')).toBe(false);+ expect(moduleExportOrigins(index, {types: true}).get('Shape')).toEqual({+ file: path.join(dir, 'types.ts'),+ name: 'Shape',+ });+ expect(moduleExportOrigins(index).get('renamed')).toEqual({+ file: path.join(dir, 'values.ts'),+ name: 'a',+ });+ });+});