@maat-tools/collector-ts

Provides

constants · imports

Collects TypeScript source facts.

Facts Provided

Fact	Type	Description
constants	Constant[]	Every string or numeric literal found in source files, with its value, kind, usage context, and location
imports	Import[]	Every import declaration, with the specifier normalized to a package name when crossing package boundaries

Constant

type Constant = {
	kind: 'string' | 'number';
	value: string;
	raw: string;
	context: ConstantContext; // 'import' | 'argument' | 'return' | 'condition' | 'decorator' | 'assignment'
	location: { file: string; line: number; column: number };
};

Import

type Import = {
	file: string;
	packageName: string | null;
	specifier: string; // normalized: cross-package relative paths are rewritten to the destination package name
	location: { file: string; line: number; column: number };
};

Options

type TSInput = {
	tsConfigFilePath: string | string[];
	exclude?: string[];
};

Option	Default	Meaning
tsConfigFilePath	—	Path(s) to tsconfig.json files. Accepts a single path, an array of paths, or glob patterns
exclude	['**/*.test.ts', '**/*.spec.ts']	Glob patterns for files to skip. Matched against paths relative to process.cwd()

Usage

Single project

export default defineConfig({
	collectors: [
		['@maat-tools/collector-ts', { tsConfigFilePath: './tsconfig.json' }],
	],
});

Monorepo — glob discovery

For a monorepo, pass glob patterns. The collector expands them relative to process.cwd() (the config file's directory) and deduplicates files that appear in multiple tsconfigs.

export default defineConfig({
	collectors: [
		[
			'@maat-tools/collector-ts',
			{
				tsConfigFilePath: [
					'packages/*/tsconfig.json',
					'apps/*/tsconfig.json',
				],
				exclude: [
					'**/*.test.ts',
					'**/*.spec.ts',
					'**/*.tsx',          // skip client-side React files
					'**/client/**',
				],
			},
		],
	],
});

Monorepo — explicit list

tsConfigFilePath: [
	'packages/core/tsconfig.json',
	'packages/api/tsconfig.json',
	'apps/server/tsconfig.json',
],

Notes

• All file paths in emitted facts are relative to process.cwd(), which the CLI sets to the config file's directory before collectors run.
• Cross-package relative imports (e.g. ../../pkg-b/src/index) are rewritten to the destination package name (e.g. @scope/pkg-b) so coupling rules see package-level boundaries, not filesystem paths.
• Files included in multiple tsconfigs are processed once. Deduplication is by absolute file path.
• The collector uses ts-morph under the hood. It does not type-check — it only parses the AST. Cold-start time scales with the number of source files loaded.