source-config.ts

Source configuration, path extraction, and file filtering.

Provides ModuleSourceOptions configuration management and functions that operate on source files using those options: path extraction, source detection, dependency filtering, and file collection.

@see source.ts for pure file type predicates (isTypescript, isSvelte, etc.) @see analyze.ts for consumers (analyze, analyzeFromFiles)

Declarations
#

9 declarations

view source

createSourceOptions
#

source-config.ts view source

(projectRoot: string, overrides?: Partial<SourceOptionsDefaults> | undefined): ModuleSourceOptions

Create complete, normalized, validated source options from project root and optional overrides.

Merges overrides with DEFAULT_SOURCE_OPTIONS, then normalizes via normalizeSourceOptions — so the returned object always has an absolute projectRoot, slash-stripped path entries, and an explicit sourceRoot (auto-derived for multi-path layouts). Throws on validation failure.

projectRoot

path to project root (typically process.cwd()); resolved to absolute

type string

overrides?

optional overrides for default options

type Partial<SourceOptionsDefaults> | undefined
optional

returns

ModuleSourceOptions

throws

  • Error - if validation fails (empty `sourcePaths`, or `sourceRoot` not a prefix of all `sourcePaths`)

examples

// Standard SvelteKit library const options = createSourceOptions(process.cwd());
// Multiple source directories const options = createSourceOptions(process.cwd(), { sourcePaths: ['src/lib', 'src/routes'], sourceRoot: 'src', });
// Custom exclusions const options = createSourceOptions(process.cwd(), { exclude: ['**\/*.test.ts', '**\/*.internal.ts'], });

DEFAULT_SOURCE_OPTIONS
#

source-config.ts view source

SourceOptionsDefaults

Default partial options for standard SvelteKit library structure.

Does not include projectRoot — use createSourceOptions to create complete options with your project root.

exclude is the single source of truth for filtering: globs applied at both discovery time (by globFiles/discoverFromExports) and analysis time (by isSource() against project-root-relative paths).

see also

  • ``createSourceOptions`` for the typical way to build complete options

extractDependencies
#

source-config.ts view source

(sourceFile: SourceFileInfo & { dependents?: readonly string[] | undefined; }, options: ModuleSourceOptions): { dependencies: string[]; dependents: string[]; }

Extract dependencies and dependents for a module from source file info.

Filters to only include source modules (excludes external packages, node_modules, tests). Returns sorted arrays of module paths (relative to sourceRoot) for deterministic output.

Native paths in sourceFile.dependencies/dependents are accepted — isSource and extractPath posixify their inputs, so direct callers with hand-built input need not pre-normalize.

Accepts SourceFileInfo plus an optional dependents field — the public input type carries only dependencies (caller-supplied opt-in), while dependents is computed downstream by computeDependents and flows through as an enriched shape.

sourceFile

the source file info to extract dependencies from

type SourceFileInfo & { dependents?: readonly string[] | undefined; }

options

module source options for filtering and path extraction

type ModuleSourceOptions

returns

{ dependencies: string[]; dependents: string[]; }

sorted arrays of module paths (relative to sourceRoot) for dependencies and dependents

extractPath
#

source-config.ts view source

(sourceId: string, options: ModuleSourceOptions): string

Extract module path relative to source root from absolute source ID.

Uses proper path semantics: strips projectRoot/sourceRoot/ prefix.

sourceId

absolute path to the source file

type string

options

module source options for path extraction

type ModuleSourceOptions

returns

string

examples

const options = createSourceOptions('/home/user/project'); extractPath('/home/user/project/src/lib/foo.ts', options) // => 'foo.ts' extractPath('/home/user/project/src/lib/nested/bar.svelte', options) // => 'nested/bar.svelte'
const options = createSourceOptions('/home/user/project', { sourcePaths: ['src/lib', 'src/routes'], sourceRoot: 'src', }); extractPath('/home/user/project/src/lib/foo.ts', options) // => 'lib/foo.ts' extractPath('/home/user/project/src/routes/page.svelte', options) // => 'routes/page.svelte'

getSourceRoot
#

source-config.ts view source

(options: ModuleSourceOptions): string

Get the effective sourceRoot from options.

Returns sourceRoot if provided, otherwise: - Single sourcePath: returns that path - Multiple sourcePaths: derives the longest common directory prefix

options

type ModuleSourceOptions

returns

string

the effective source root path

isSource
#

source-config.ts view source

(path: string, options: ModuleSourceOptions): boolean

Check if a path is an analyzable source file.

Combines all filtering: source directory paths, exclude globs, and analyzer availability. This is the single check for whether a file should be included in library analysis.

Uses proper path semantics with startsWith matching against projectRoot/sourcePath/. No heuristics needed — nested directories are correctly excluded by the prefix check.

Order is sourceDir-then-exclude: the prefix check guarantees the path lives under projectRoot before relativization, so relative() always produces a clean glob-shaped string for the matcher. Files outside projectRoot (rare; would require monorepo path mapping) short-circuit at the prefix check before reaching the matcher.

path

full absolute path to check

type string

options

module source options for filtering

type ModuleSourceOptions

returns

boolean

true if the path is an analyzable source file

examples

const options = createSourceOptions('/home/user/project'); isSource('/home/user/project/src/lib/foo.ts', options) // => true isSource('/home/user/project/src/lib/styles.css', options) // => true isSource('/home/user/project/src/lib/data.json', options) // => true isSource('/home/user/project/src/lib/foo.test.ts', options) // => false (excluded) isSource('/home/user/project/src/fixtures/mini/src/lib/bar.ts', options) // => false (wrong prefix)

ModuleSourceOptions
#

source-config.ts view source

ModuleSourceOptions

Configuration for module source detection and path extraction.

Uses proper path semantics with projectRoot as the base for all path operations. Paths are matched using startsWith rather than substring search, which correctly handles nested directories without special heuristics.

examples

const options = createSourceOptions(process.cwd(), { sourcePaths: ['src/lib', 'src/routes'], sourceRoot: 'src', });

projectRoot

Path to the project root directory.

All sourcePaths are relative to this. Typically process.cwd(). Normalized (resolved to absolute, posixified to forward slashes, trailing slash stripped) by normalizeSourceOptions, which returns a new options object. Internal callers (isSource, extractPath) assume this is already POSIX form — construct via createSourceOptions / normalizeSourceOptions rather than building ModuleSourceOptions literals by hand on Windows.

type string

sourcePaths

Source directory paths to include, relative to projectRoot.

Normalized (leading/trailing slashes stripped) by normalizeSourceOptions, which returns a new options object.

type Array<string>

sourceRoot

Source root for extracting relative module paths, relative to projectRoot.

Normalized (leading/trailing slashes stripped; '.' collapsed to '') by normalizeSourceOptions, which returns a new options object.

When omitted: - Single sourcePath: defaults to that path - Multiple sourcePaths: auto-derived as the longest common directory prefix (or '' when paths share no common prefix — produces project-relative module paths)

type string

exclude

Glob patterns to exclude from analysis, relative to projectRoot.

Applied at both stages of the pipeline: - Discovery time by globFiles/discoverFromExports, preventing matched files from being loaded. - Analysis time by isSource() against relative(projectRoot, absolutePath), catching files that enter through TypeScript import resolution (e.g., a source file imports a test helper).

analyzeFromFiles accepts a top-level exclude shortcut that merges into this field.

Compiled to a matcher once per options object via picomatch and cached by reference; mutating this array post-isSource-call has no effect — pass through normalizeSourceOptions (which returns a fresh object) or otherwise build a new options object to apply changes.

type Array<string>

getAnalyzerType

Determine which analyzer to use for a file path.

Called for files in source directories. Return an AnalyzerType or null to skip: - 'typescript' — TypeScript/JS files analyzed via TypeScript compiler API - 'svelte' — Svelte components analyzed via svelte2tsx + TypeScript compiler API - 'css' — CSS files included as modules with no declarations - 'json' — JSON files included as modules with no declarations - null — skip the file

type (path: string) => AnalyzerType | null

normalizeSourceOptions
#

source-config.ts view source

(options: ModuleSourceOptions): ModuleSourceOptions

Normalize and validate ModuleSourceOptions, returning a new options object.

Normalization: - projectRoot resolved to absolute via path.resolve (relative paths resolve against cwd) - Trailing slash stripped from projectRoot - Leading/trailing slashes stripped from sourcePaths entries - Leading/trailing slashes stripped from sourceRoot (if provided) - sourceRoot of '.' is normalized to '' (project root sentinel)

Validation (after normalization): 1. sourcePaths has at least one entry 2. sourceRoot (if provided and non-empty) is a prefix of all sourcePaths

When sourceRoot is omitted and multiple sourcePaths are provided, sourceRoot is auto-derived as their longest common path prefix. If the paths share no common prefix, the derived root is '' and extractPath produces project-relative module paths.

Returns a fresh object — the input is not mutated. Re-normalization produces a fresh identity, which naturally invalidates the excludeMatcherCache (keyed by options-object identity) without a separate "rebuild a fresh object" rule.

options

type ModuleSourceOptions

returns

ModuleSourceOptions

a new ModuleSourceOptions with normalized fields

throws

  • Error - if validation fails

examples

// Normalization: slashes stripped, relative projectRoot resolved const normalized = normalizeSourceOptions({projectRoot: '.', sourcePaths: ['/src/lib/'], ...}); // normalized.projectRoot is now absolute, normalized.sourcePaths is ['src/lib']

SourceOptionsDefaults
#

Depends on
#

Imported by
#