@build-script/autoindex 0.0.1

package/src/bin.ts

@@ -0,0 +1,123 @@
+import { startChokidar } from '@idlebox/chokidar';
+import { createRootLogger, logger } from '@idlebox/logger';
+import type { IgnoreFiles } from '@idlebox/typescript-surface-analyzer';
+import { channelClient } from '@mpis/client';
+import { glob } from 'glob';
+import { resolve } from 'node:path';
+import { parseArgs } from './common/cli.js';
+import { createContext } from './common/config.js';
+import { createIndex } from './common/create.js';
+import { loadTsConfigJson } from './common/tsconfig-loader.js';
+import { loadTypescript } from './common/typescript.js';
+
+createRootLogger('autoindex');
+
+let tsData: Awaited<ReturnType<typeof loadTypescript>>;
+async function loadTypescriptOnce() {
+	if (!tsData) {
+		tsData = await loadTypescript(context);
+	}
+	return tsData;
+}
+
+async function main() {
+	let outputs = '';
+	logger.stream.on('data', (data) => {
+		outputs += data.toString();
+	});
+
+	channelClient.start();
+
+	const { ts, file: tsconfigFile } = await loadTypescriptOnce();
+
+	try {
+		const { command, configFiles } = loadTsConfigJson(ts, tsconfigFile, {
+			exclude: context.excludePatterns,
+			include: context.includePatterns,
+		});
+
+		if (context.verboseMode) {
+			logger.debug('options:', command.options);
+			logger.debug('command:');
+			for (const file of command.fileNames) {
+				logger.debug('  - %s', file);
+			}
+		}
+
+		const rootDir = command.options.rootDir;
+		if (!rootDir) {
+			throw logger.fatal('无法确定rootDir，请添加tsconfig.json中的compilerOptions.rootDir设置。');
+		}
+
+		logger.debug('rootDir=%s', rootDir);
+
+		const outputFile = resolve(rootDir, context.outputFile + '.ts');
+
+		if (!outputFile.startsWith(rootDir)) {
+			throw logger.fatal(`输出文件 ${outputFile} 路径异常，离开rootDir`);
+		}
+
+		const r = await createIndex({
+			ts,
+			project: command,
+			outputFileAbs: outputFile,
+			logger,
+			absoluteImport: context.absoluteImport,
+			stripTags: context.stripTags,
+			extraExcludes: context.excludePatterns,
+		});
+
+		r.watchFiles.push(...configFiles);
+
+		channelClient.success('autoindex success', outputs);
+		return r;
+	} catch (e) {
+		channelClient.failed('autoindex failed', outputs);
+		throw e;
+	}
+}
+
+const args = await parseArgs();
+logger.debug`arguments: ${args}`;
+
+const context = await createContext(args, logger);
+
+if (!context.project) {
+	logger.log`没有任务需要执行`;
+	if (context.watchMode) {
+		setInterval(() => {
+			// x
+		}, 10000);
+	}
+
+	channelClient.success('no task to execute');
+} else if (context.watchMode) {
+	let lastExecuteIgnore: IgnoreFiles | undefined;
+	async function exec() {
+		const r = await main();
+
+		lastExecuteIgnore = r.ignores;
+
+		watcher.add(r.watchFiles);
+	}
+
+	function testAndRun(changes: readonly string[]) {
+		if (lastExecuteIgnore && lastExecuteIgnore.filter(changes).length === 0) {
+			logger.debug('%s file changes, but all ignored.', changes.length);
+			return;
+		}
+		logger.log('rebuild due to %s file changes: %s', changes.length, changes[0]);
+		return exec();
+	}
+
+	const watcher = startChokidar(testAndRun, {
+		watchingEvents: ['add', 'change', 'unlink', 'addDir'],
+	});
+
+	const content = await glob('**/', { absolute: true, cwd: context.project, ignore: ['**/node_modules/**'] });
+	watcher.add(content);
+
+	await exec();
+} else {
+	await main();
+}

package/src/common/cli.ts

@@ -0,0 +1,118 @@
+import { createArgsReader } from '@idlebox/args';
+import { EnableLogLevel, logger } from '@idlebox/logger';
+import { findUpUntilSync } from '@idlebox/node';
+import { resolve } from 'node:path';
+
+export function printUsage() {
+	console.log(
+		`Usage: autoindex [options] <tsconfig.json>
+Options:
+  -w, --watch            监视模式
+  -d, --debug            显示调试输出
+  -C, --config           读取 config/autoindex.json 配置文件
+                         如果设置了该选项，但是配置文件不存在，则直接退出，什么也不做
+  -o, --output <file>    输出文件路径(默认: autoindex.generated，相对于tsconfig.json所在目录)
+  --exclude <pattern>    额外排除的文件或目录
+  --include <pattern>    额外包含的文件或目录
+  -a, --absolute <path>  绝对导入路径前缀
+  --skip-tag <tag>       忽略被 @tag 注释的符号
+  --no-config            忽略 "config/autoindex.json" 文件
+  -h, --help             显示帮助信息
+`.trim(),
+	);
+}
+
+export enum ConfigKind {
+	DISABLE = 'disable',
+	IMPLICIT = 'implicit',
+	EXPLICIT = 'explicit',
+}
+
+export interface ICliArgs {
+	readonly configType: ConfigKind;
+	readonly watchMode: boolean;
+	readonly debugMode: boolean;
+	readonly outputFile?: string;
+	readonly excludePatterns: string[];
+	readonly includePatterns: string[];
+	readonly absoluteImport?: string;
+	readonly skipTags: string[];
+	readonly project?: string;
+	readonly verboseMode: boolean;
+}
+
+export async function parseArgs() {
+	try {
+		return await _parseArgs();
+	} catch (e: any) {
+		printUsage();
+
+		throw logger.fatal(e.message);
+	}
+}
+async function _parseArgs(): Promise<ICliArgs> {
+	const argv = createArgsReader(process.argv.slice(2));
+
+	if (argv.flag(['-h', '--help']) > 0) {
+		printUsage();
+		process.exit(0);
+	}
+
+	const watchMode = argv.flag(['-w', '--watch']) > 0;
+	const debugMode = argv.flag(['-d', '--debug']) > 0;
+	const verboseMode = argv.flag(['-d', '--debug']) > 1;
+	const outputFile = argv.single(['-o', '--output']);
+	const excludePatterns = argv.multiple(['--exclude']);
+	const includePatterns = argv.multiple(['--include']);
+	const absoluteImport = argv.single(['-a', '--absolute']);
+	const stripTags = argv.multiple(['--skip-tag']);
+	const projVal = argv.range(0, 1)[0];
+
+	let configType = ConfigKind.IMPLICIT;
+	if (argv.flag(['--config']) > 0) {
+		configType = ConfigKind.EXPLICIT;
+	} else if (argv.flag(['--config']) < 0) {
+		configType = ConfigKind.DISABLE;
+	}
+
+	if (verboseMode) {
+		logger.enable(EnableLogLevel.verbose);
+	} else if (debugMode) {
+		logger.enable(EnableLogLevel.debug);
+	}
+
+	if (argv.unused().length) {
+		logger.fatal`未知的命令行参数: ${argv.unused().join(', ')}`;
+	}
+
+	if (absoluteImport && absoluteImport[0] !== '#') {
+		throw logger.fatal(`绝对导入路径必须以'#'开头: ${absoluteImport}`);
+	}
+
+	if (stripTags.length === 0) {
+		stripTags.push('internal');
+	}
+
+	const project = projVal ? resolve(process.cwd(), projVal) : undefined;
+
+	return {
+		configType,
+		watchMode,
+		debugMode,
+		outputFile,
+		excludePatterns,
+		includePatterns,
+		absoluteImport,
+		skipTags: stripTags,
+		project,
+		verboseMode,
+	};
+}
+
+export type ICliCtx = ReturnType<typeof parseArgs>;
+
+const _schemaFile = findUpUntilSync({ file: 'autoindex.schema.json', from: import.meta.dirname });
+if (!_schemaFile) {
+	throw new Error('missing schema file: autoindex.schema.json');
+}
+export const schemaFile = _schemaFile;

package/src/common/config.ts

@@ -0,0 +1,105 @@
+import { NotFoundError, ProjectConfig } from '@build-script/rushstack-config-loader';
+import type { IMyLogger } from '@idlebox/logger';
+import { findUpUntilSync } from '@idlebox/node';
+import { resolve } from 'node:path';
+import { ConfigKind, schemaFile, type ICliArgs } from './cli.js';
+
+interface IConfigFile {
+	project?: string;
+	output?: string;
+	include?: string[];
+	exclude?: string[];
+	stripTags?: string[];
+	absolute?: string;
+}
+
+export interface IContext {
+	watchMode: boolean;
+	debugMode: boolean;
+	outputFile: string;
+	excludePatterns: string[];
+	includePatterns: string[];
+	absoluteImport: undefined | string;
+	stripTags: string[];
+	project: string;
+	verboseMode: boolean;
+}
+
+async function loadConfigFile(configType: ConfigKind, context: Partial<IContext>, logger: IMyLogger) {
+	if (configType === ConfigKind.DISABLE) {
+		logger.debug`由于命令行参数，跳过配置文件: config/autoindex.json`;
+		return;
+	}
+
+	logger.debug`即将加载配置文件: config/autoindex.json`;
+	logger.verbose`使用schema文件: ${schemaFile}`;
+
+	const packageJsonFile = findUpUntilSync({ file: 'package.json', from: context.project ?? process.cwd() });
+	if (!packageJsonFile) {
+		throw logger.fatal`无法找到项目根目录，请确保在正确的目录下运行。`;
+	}
+	logger.debug`项目package: ${packageJsonFile}`;
+	const projectRoot = resolve(packageJsonFile, '..');
+
+	const config = new ProjectConfig(projectRoot, undefined, logger);
+
+	try {
+		const configFileData = config.loadSingleJson<IConfigFile>('autoindex', schemaFile);
+		logger.verbose`内容: ${configFileData}`;
+
+		if (!context.project) {
+			if (!configFileData.project) {
+				throw logger.fatal`配置文件中未指定项目路径，必须传入参数`;
+			}
+			context.project = configFileData.project;
+		}
+
+		if (!context.absoluteImport && configFileData.absolute) context.absoluteImport = configFileData.absolute;
+
+		if (!context.outputFile && configFileData.output) context.outputFile = configFileData.output;
+
+		if (!context.includePatterns) context.includePatterns = [];
+		if (configFileData.include?.length) context.includePatterns.push(...configFileData.include);
+
+		if (!context.excludePatterns) context.excludePatterns = [];
+		if (configFileData.exclude?.length) context.excludePatterns.push(...configFileData.exclude);
+
+		if (!context.stripTags) context.stripTags = [];
+		if (configFileData.stripTags?.length) context.stripTags.push(...configFileData.stripTags);
+	} catch (e: unknown) {
+		if (e instanceof NotFoundError) {
+			logger.verbose`由于文件不存在，未使用配置文件（${e.message}）`;
+		} else {
+			throw e;
+		}
+	}
+}
+
+export async function createContext(args: ICliArgs, logger: IMyLogger): Promise<IContext> {
+	const context: Partial<IContext> = {
+		watchMode: args.watchMode,
+		debugMode: args.debugMode,
+		outputFile: args.outputFile,
+		excludePatterns: args.excludePatterns,
+		includePatterns: args.includePatterns,
+		absoluteImport: undefined,
+		stripTags: args.skipTags,
+		project: args.project,
+		verboseMode: args.verboseMode,
+	};
+
+	await loadConfigFile(args.configType, context, logger);
+
+	if (!context.outputFile) {
+		context.outputFile = './autoindex.generated';
+	}
+	if (!context.project) {
+		if (args.configType === ConfigKind.IMPLICIT) {
+			// 如果是隐式配置，则必须在命令行中指定项目路径
+			logger.fatal`未指定项目路径，需要额外参数或在配置文件中指定`;
+		}
+	}
+
+	logger.verbose`最终配置: ${context}`;
+	return context as IContext;
+}

package/src/common/create.ts

@@ -0,0 +1,168 @@
+import { camelCase, ucfirst } from '@idlebox/common';
+import type { IMyLogger } from '@idlebox/logger';
+import { ensureParentExists, relativePath, writeFileIfChange } from '@idlebox/node';
+import {
+	ExportKind,
+	IgnoreFiles,
+	TypescriptProject,
+	type IIdentifierResult,
+} from '@idlebox/typescript-surface-analyzer';
+import { basename, dirname } from 'node:path';
+import type TypeScriptApi from 'typescript';
+
+export function idToString(ts: typeof TypeScriptApi, id: TypeScriptApi.StringLiteral | TypeScriptApi.Identifier) {
+	if (ts.isIdentifier(id)) {
+		return id.escapedText.toString();
+	}
+	return id.text;
+}
+
+export interface ICreateIndexContext {
+	absoluteImport?: string;
+	stripTags?: readonly string[];
+	extraExcludes?: readonly string[];
+	ts: typeof TypeScriptApi;
+	project: TypeScriptApi.ParsedCommandLine;
+	outputFileAbs: string;
+	logger: IMyLogger;
+	verbose?: boolean;
+}
+
+export function createStandaloneIgnore(logger: IMyLogger, outputFileAbs: string, extraExcludes?: readonly string[]) {
+	const ignores = new IgnoreFiles(logger);
+	applyIgnores(ignores, outputFileAbs, extraExcludes);
+	return ignores;
+}
+
+function applyIgnores(ignores: IgnoreFiles, outputFileAbs: string, extraExcludes?: readonly string[]) {
+	ignores.add(function ignoreIndexItSelf(f: string) {
+		return f === outputFileAbs;
+	});
+	ignores.add('**/*.test.ts');
+	ignores.add('**/*.test.tsx');
+	ignores.add('**/*.test.d/**');
+	ignores.add('**/node_modules/**');
+	if (extraExcludes) {
+		for (const exclude of extraExcludes) {
+			ignores.add(exclude);
+		}
+	}
+}
+
+interface IRet {
+	watchFiles: string[];
+	ignores: IgnoreFiles;
+}
+
+export async function createIndex({
+	logger,
+	outputFileAbs,
+	project,
+	ts,
+	absoluteImport,
+	extraExcludes = [],
+	stripTags = ['internal'],
+}: ICreateIndexContext): Promise<IRet> {
+	if (!project.options.rootDir || !project.options.configFilePath) {
+		logger.error('%o', project.options);
+		throw new Error(`missing rootDir and {internal}configFilePath`);
+	}
+	if (!project.options.rootDir) {
+		logger.error('%o', project.options);
+		throw new Error(`missing rootDir: ${project.options.configFilePath}`);
+	}
+
+	const p = new TypescriptProject(ts, project, logger);
+	logger.log('creating index file: %s', outputFileAbs);
+	applyIgnores(p.additionalIgnores, outputFileAbs, extraExcludes);
+
+	const list = p.execute(stripTags);
+
+	const indexDir = `./${relativePath(
+		project.options.rootDir || dirname(project.options.configFilePath as string),
+		dirname(outputFileAbs),
+	)
+		.split('/')
+		.filter((e) => e && e !== '.')
+		.map(() => '..')
+		.join('/')}`;
+	logger.debug('rootDir: %s', project.options.rootDir);
+	logger.debug('configFilePath: %s', project.options.configFilePath);
+	logger.debug('index dir: %s', indexDir);
+	const header = ['// DO NOT EDIT THIS FILE', '// @ts-ignore', '/* eslint-disable */'];
+	const content = [];
+	const input_files = [];
+	for (const file of list) {
+		if (file.absolutePath === outputFileAbs) {
+			throw new Error(`override output file: ${outputFileAbs} (are you import xxx from ${basename(outputFileAbs)}?)`);
+		}
+
+		const path = importSpec(absoluteImport ?? indexDir, file.relativePath);
+		content.push(`/* ${file.relativePath} */`);
+
+		if (file.identifiers) {
+			content.push('\t// Identifiers');
+			for (const def of file.identifiers.values()) {
+				if (def.reference) {
+					if (!def.reference.id && def.reference.type === 'file') {
+						// 从本包另一个文件export，并且没有改名（x as y）
+						continue;
+					}
+				}
+				content.push(`\texport ${typeTag(def)}{ ${idToString(ts, def.id)} } from "${path}";`);
+			}
+		}
+		if (file.references.length) {
+			content.push('\t// References');
+			for (const { reference } of file.references) {
+				if (reference.type === 'file') {
+					content.push(`\texport * from "${importSpec(indexDir, reference.relativeFromRoot)}";`);
+				} else {
+					content.push(`\texport * from "${reference.name}";`);
+				}
+			}
+		}
+		if (file.defaultExport) {
+			content.push('\t// Default');
+			let id = '';
+			if (file.defaultExport.id) {
+				id = idToString(ts, file.defaultExport.id);
+			} else {
+				id = camelCase(file.relativePath);
+				if (file.defaultExport.kind === ExportKind.Class || file.defaultExport.kind === ExportKind.Type) {
+					id = ucfirst(id);
+				}
+			}
+			content.push(`\texport { default as ${id} } from "${path}";`);
+		}
+
+		input_files.push(file.absolutePath);
+	}
+
+	await ensureParentExists(outputFileAbs);
+	const r = await writeFileIfChange(outputFileAbs, `${header.join('\n')}\n\n${content.join('\n')}`);
+
+	if (r) {
+		logger.log('index create ok.');
+	} else {
+		logger.log('index create ok. (unchange)');
+	}
+
+	return {
+		watchFiles: input_files,
+		ignores: p.additionalIgnores,
+	};
+}
+
+const tsExt = /\.tsx?$/;
+const prefxUneedDot = /^\.\/\.\.\//;
+function importSpec(indexDir: string, target: string) {
+	return `${indexDir}/${target.replace(tsExt, '.js')}`.replace(/\/\//g, '/').replace(prefxUneedDot, '../');
+}
+
+function typeTag(def: IIdentifierResult) {
+	if (def.kind === ExportKind.Type) {
+		return 'type ';
+	}
+	return '';
+}

package/src/common/tsconfig-loader.ts

@@ -0,0 +1,119 @@
+import type { IMyLogger } from '@idlebox/logger';
+import { isModuleResolutionError } from '@idlebox/node';
+import { parse, stringify } from 'comment-json';
+import { createRequire } from 'node:module';
+import { normalize, resolve } from 'node:path';
+import type TypeScriptApi from 'typescript';
+
+export interface ILoadedConfigFile {
+	readonly command: TypeScriptApi.ParsedCommandLine;
+	readonly configFiles: readonly string[];
+}
+
+interface ILoadTsConfigJsonOptions {
+	exclude?: string[];
+	include?: string[];
+}
+
+export function loadTsConfigJson(
+	ts: typeof TypeScriptApi,
+	tsconfigJson: string,
+	options: ILoadTsConfigJsonOptions = {},
+): ILoadedConfigFile {
+	const { exclude, include } = options;
+
+	const readFiles: string[] = [];
+	function readFile(file: string, encoding?: string) {
+		readFiles.push(file);
+		const text = ts.sys.readFile(file, encoding);
+		if (!text) throw new Error(`failed read file: ${file}`);
+		const json = ts.parseConfigFileTextToJson(file, text);
+		if (json.error) {
+			return text;
+		}
+		if (Array.isArray(json.config?.exclude)) {
+			json.config.exclude = json.config.exclude.filter((l: string) => {
+				return !l.endsWith('.generated.ts');
+			});
+		}
+		return JSON.stringify(json.config);
+	}
+
+	const myFormatDiagnosticsHost: TypeScriptApi.FormatDiagnosticsHost = {
+		getCurrentDirectory: ts.sys.getCurrentDirectory,
+		getCanonicalFileName: normalize,
+		getNewLine(): string {
+			return ts.sys.newLine;
+		},
+	};
+
+	const host: TypeScriptApi.ParseConfigFileHost = {
+		onUnRecoverableConfigFileDiagnostic(diagnostic: TypeScriptApi.Diagnostic) {
+			throw new Error(ts.formatDiagnostic(diagnostic, myFormatDiagnosticsHost).trim());
+		},
+		useCaseSensitiveFileNames: true,
+		readDirectory: ts.sys.readDirectory,
+		getCurrentDirectory: ts.sys.getCurrentDirectory,
+		fileExists: ts.sys.fileExists,
+		readFile: ts.sys.readFile,
+	};
+
+	let config_patched = true;
+	if (exclude?.length || include?.length) {
+		config_patched = false;
+		Object.assign(host, {
+			readFile(file: string, encoding?: string) {
+				let text = readFile(file, encoding);
+				if (file === tsconfigJson) {
+					const content: any = parse(text);
+					if (exclude?.length) {
+						if (!content.exclude) content.exclude = [];
+						content.exclude.push(...exclude);
+					}
+					if (include?.length) {
+						if (!content.include) content.include = [];
+						content.include.push(...include);
+					}
+					text = stringify(content, null, 2);
+					config_patched = true;
+				}
+				return text;
+			},
+		});
+	}
+
+	const command = ts.getParsedCommandLineOfConfigFile(tsconfigJson, {}, host);
+
+	if (!command) {
+		throw new Error('fatal error, can not continue');
+	}
+
+	if (!config_patched) {
+		throw new Error(
+			`tsconfig.json file "${tsconfigJson}" has not been patched with exclude/include options, please report issue.`,
+		);
+	}
+
+	if (!command.options.rootDir) {
+		command.options.rootDir = resolve(tsconfigJson, '..');
+	}
+
+	return { command, configFiles: readFiles };
+}
+
+function interop(v: any) {
+	return v.default ?? v;
+}
+
+export async function getTypescript(tsconfigFile: string, logger?: IMyLogger): Promise<typeof TypeScriptApi> {
+	const require = createRequire(tsconfigFile);
+	try {
+		return require('typescript');
+	} catch (e) {
+		if (isModuleResolutionError(e)) {
+			logger?.error('typescript not found in target project, using bundled one.');
+			return interop(await import('typescript'));
+		}
+		throw e;
+	}
+}

package/src/common/typescript.ts

@@ -0,0 +1,26 @@
+import { logger } from '@idlebox/logger';
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type TypeScriptApi from 'typescript';
+import type { IContext } from './config.js';
+import { getTypescript } from './tsconfig-loader.js';
+
+export async function loadTypescript(context: IContext) {
+	let tsconfigFile: string = context.project;
+	if (statSync(tsconfigFile).isDirectory()) {
+		tsconfigFile = resolve(tsconfigFile, 'tsconfig.json');
+		if (!existsSync(tsconfigFile)) {
+			throw logger.fatal(`missing "tsconfig.json" in: ${tsconfigFile}`);
+		}
+	} else if (!existsSync(tsconfigFile)) {
+		throw logger.fatal(`missing tsconfig: ${tsconfigFile}`);
+	}
+
+	const ts: typeof TypeScriptApi = await getTypescript(tsconfigFile, logger);
+	logger.log('typescript version: %s', ts.version);
+
+	return {
+		ts,
+		file: tsconfigFile,
+	} as const;
+}

package/src/plugin.ts

@@ -0,0 +1 @@
+throw new Error('not implemented');

package/src/tsconfig.json

@@ -0,0 +1,9 @@
+{
+	"extends": "@internal/local-rig/profiles/default/tsconfig.json",
+	"compilerOptions": {
+		"typeRoots": ["../node_modules/@types", "../node_modules"],
+		"outDir": "../lib",
+		"rootDir": "./",
+		"types": ["node"]
+	}
+}