ng-checkup 0.0.0-stage → 0.2.0

package/dist/config.d.ts

@@ -0,0 +1,47 @@
+/** The file `ng-checkup` reads from the analysed root when no `--config` is given. */
+export declare const CONFIG_FILE = "ng-checkup.config.json";
+/**
+ * What `ng-checkup.config.json` may set. Every key is optional and every one
+ * has a command-line flag that overrides it, so a config file only ever
+ * supplies defaults: a developer running `npx ng-checkup --report x.md` gets
+ * exactly that, whatever the file says.
+ */
+export interface CheckupConfig {
+    /** Report files to write, relative to the config file's directory. */
+    reports?: string[];
+    /** As `--fail-on`. */
+    failOn?: 'fair' | 'poor';
+    /** As `--max-examples`. */
+    maxExamples?: number;
+    /** As `--offline`. */
+    offline?: boolean;
+    /**
+     * Paths left out of the analysis, relative to the root: `src/legacy`,
+     * `**\/generated`, `apps/*\/e2e`. A pattern matches a file or a directory and
+     * everything below it; `*` stops at `/`, `**` does not.
+     */
+    ignore?: string[];
+}
+/**
+ * Reads and validates the config file.
+ *
+ * @param explicitPath A path given with `--config`. It must exist; the default
+ *   file may be absent, which simply means no config.
+ * @returns The parsed config and the directory its relative paths resolve
+ *   against, or an empty config when there is no file.
+ * @throws An `Error` whose message is meant for the user on malformed JSON,
+ *   an unknown key or a value of the wrong type. A typo such as `failon`
+ *   fails loudly instead of being silently ignored, which would leave CI
+ *   passing on a threshold nobody set.
+ */
+export declare function loadConfig(root: string, explicitPath?: string): {
+    config: CheckupConfig;
+    directory: string;
+    path?: string;
+};
+/**
+ * Compiles `ignore` patterns into one predicate over report paths (relative
+ * to the root, `/`-separated). Undefined when there are no patterns, so the
+ * file walk can skip the check entirely.
+ */
+export declare function ignoreMatcher(patterns: string[] | undefined): ((relativePath: string) => boolean) | undefined;

package/dist/config.js

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { extname, join, resolve } from 'node:path';
+/** The file `ng-checkup` reads from the analysed root when no `--config` is given. */
+export const CONFIG_FILE = 'ng-checkup.config.json';
+/** Keys the file may contain. `$schema` is accepted so editors can attach one later. */
+const KNOWN_KEYS = new Set(['$schema', 'reports', 'failOn', 'maxExamples', 'offline', 'ignore']);
+/**
+ * Reads and validates the config file.
+ *
+ * @param explicitPath A path given with `--config`. It must exist; the default
+ *   file may be absent, which simply means no config.
+ * @returns The parsed config and the directory its relative paths resolve
+ *   against, or an empty config when there is no file.
+ * @throws An `Error` whose message is meant for the user on malformed JSON,
+ *   an unknown key or a value of the wrong type. A typo such as `failon`
+ *   fails loudly instead of being silently ignored, which would leave CI
+ *   passing on a threshold nobody set.
+ */
+export function loadConfig(root, explicitPath) {
+    const path = explicitPath ? resolve(explicitPath) : join(root, CONFIG_FILE);
+    if (!existsSync(path)) {
+        if (explicitPath)
+            throw new Error(`Config file not found: ${path}`);
+        return { config: {}, directory: root };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        throw new Error(`${path} must contain a JSON object`);
+    const record = raw;
+    const unknown = Object.keys(record).filter((key) => !KNOWN_KEYS.has(key));
+    if (unknown.length > 0)
+        throw new Error(`${path}: unknown ${unknown.length === 1 ? 'key' : 'keys'} ${unknown.join(', ')}. Allowed: ${[...KNOWN_KEYS].filter((key) => key !== '$schema').join(', ')}`);
+    const config = {};
+    if (record['reports'] !== undefined) {
+        const reports = record['reports'];
+        if (!Array.isArray(reports) || !reports.every((entry) => typeof entry === 'string'))
+            throw new Error(`${path}: reports must be an array of file names`);
+        for (const report of reports) {
+            if (!['.html', '.htm', '.md', '.json'].includes(extname(report).toLowerCase()))
+                throw new Error(`${path}: unknown report format for ${report}, use .html, .md or .json`);
+        }
+        config.reports = reports;
+    }
+    if (record['failOn'] !== undefined) {
+        if (record['failOn'] !== 'fair' && record['failOn'] !== 'poor')
+            throw new Error(`${path}: failOn must be "poor" or "fair"`);
+        config.failOn = record['failOn'];
+    }
+    if (record['maxExamples'] !== undefined) {
+        const value = record['maxExamples'];
+        if (typeof value !== 'number' || !Number.isInteger(value) || value < 0)
+            throw new Error(`${path}: maxExamples must be a whole number`);
+        config.maxExamples = value;
+    }
+    if (record['offline'] !== undefined) {
+        if (typeof record['offline'] !== 'boolean')
+            throw new Error(`${path}: offline must be true or false`);
+        config.offline = record['offline'];
+    }
+    if (record['ignore'] !== undefined) {
+        const ignore = record['ignore'];
+        if (!Array.isArray(ignore) || !ignore.every((entry) => typeof entry === 'string'))
+            throw new Error(`${path}: ignore must be an array of paths`);
+        config.ignore = ignore;
+    }
+    return { config, directory: resolve(path, '..'), path };
+}
+/**
+ * Compiles `ignore` patterns into one predicate over report paths (relative
+ * to the root, `/`-separated). Undefined when there are no patterns, so the
+ * file walk can skip the check entirely.
+ */
+export function ignoreMatcher(patterns) {
+    const cleaned = (patterns ?? []).map((pattern) => pattern.trim().replace(/^\.\//, '').replace(/\/+$/, '')).filter(Boolean);
+    if (cleaned.length === 0)
+        return undefined;
+    const expressions = cleaned.map((pattern) => {
+        const source = pattern
+            .split(/(\*\*\/?|\*|\?)/)
+            .map((part) => (part === '**/' ? '(?:.*/)?' : part === '**' ? '.*' : part === '*' ? '[^/]*' : part === '?' ? '[^/]' : part.replace(/[.+^${}()|[\]\\]/g, '\\$&')))
+            .join('');
+        // A pattern matches the path itself or anything below it.
+        return new RegExp(`^${source}(?:/.*)?$`);
+    });
+    return (relativePath) => expressions.some((expression) => expression.test(relativePath));
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/deprecations.d.ts

@@ -0,0 +1,30 @@
+/** What a `@deprecated` tag says. */
+export interface DeprecationInfo {
+    /** The version the tag names, such as `20.0` or `20.2`, when the tag starts with one. */
+    since?: string;
+    /** The tag's text after the version, trimmed. Can be empty: some tags give no reason. */
+    message: string;
+}
+/** The deprecated exports of one import path, such as `@angular/common` or `@angular/common/http`. */
+export interface EntryDeprecations {
+    /** Exported name to its deprecation. */
+    symbols: Map<string, DeprecationInfo>;
+    /** `Owner.member` to its deprecation, for enum members and static class members. */
+    members: Map<string, DeprecationInfo>;
+}
+/** Import path to its deprecated exports. */
+export type DeprecationIndex = Map<string, EntryDeprecations>;
+/**
+ * Builds the deprecation index from the analysed repository's own `node_modules`.
+ *
+ * Reading the installed `.d.ts` files rather than shipping a hand-kept list is
+ * what keeps the report truthful: it names exactly what the installed version
+ * marks, with the version and reason Angular itself wrote. A hand-kept list
+ * drifts the moment a release adds or lifts a deprecation (Angular 22, for
+ * example, deprecates `ChangeDetectionStrategy.Default` in favour of `Eager`,
+ * because OnPush became the default).
+ *
+ * Returns an empty index when dependencies are not installed; the deprecations
+ * check then grades `info` and says why.
+ */
+export declare function buildDeprecationIndex(root: string): DeprecationIndex;

package/dist/deprecations.js

@@ -0,0 +1,279 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import ts from 'typescript';
+import { asRecord, readJson } from './workspace.js';
+/**
+ * Package scopes whose type definitions are indexed. Both publish their public
+ * API as bundled `.d.ts` files with `@deprecated` tags kept, and both are where
+ * an Angular upgrade breaks things.
+ */
+const INDEXED_SCOPES = ['@angular', '@ngrx'];
+/**
+ * Builds the deprecation index from the analysed repository's own `node_modules`.
+ *
+ * Reading the installed `.d.ts` files rather than shipping a hand-kept list is
+ * what keeps the report truthful: it names exactly what the installed version
+ * marks, with the version and reason Angular itself wrote. A hand-kept list
+ * drifts the moment a release adds or lifts a deprecation (Angular 22, for
+ * example, deprecates `ChangeDetectionStrategy.Default` in favour of `Eager`,
+ * because OnPush became the default).
+ *
+ * Returns an empty index when dependencies are not installed; the deprecations
+ * check then grades `info` and says why.
+ */
+export function buildDeprecationIndex(root) {
+    const index = new Map();
+    for (const scope of INDEXED_SCOPES) {
+        const scopeDirectory = join(root, 'node_modules', scope);
+        if (!existsSync(scopeDirectory))
+            continue;
+        for (const packageName of safeReaddir(scopeDirectory)) {
+            const packageDirectory = join(scopeDirectory, packageName);
+            for (const [entry, typesPath] of typeEntriesOf(packageDirectory)) {
+                const specifier = entry === '.' ? `${scope}/${packageName}` : `${scope}/${packageName}/${entry.slice(2)}`;
+                const deprecations = new DtsReader().exportsOf(typesPath);
+                if (deprecations.symbols.size > 0 || deprecations.members.size > 0)
+                    index.set(specifier, deprecations);
+            }
+        }
+    }
+    return index;
+}
+/**
+ * Each public entry point of a package with its type definition file.
+ *
+ * Reads `exports` (Angular 13+ and every NgRx release that matters), skipping
+ * wildcard and non-code entries. A package without an `exports` map uses the
+ * older layout, where every secondary entry point (`@angular/core/testing`,
+ * `@angular/common/http`) is a folder with its own `package.json` naming its
+ * `typings`; those are found by `legacyEntriesOf`.
+ */
+function typeEntriesOf(packageDirectory) {
+    const packageJson = readJson(join(packageDirectory, 'package.json'));
+    if (!packageJson)
+        return [];
+    const entries = [];
+    for (const [entry, target] of Object.entries(asRecord(packageJson['exports']))) {
+        if (entry.includes('*') || entry === './package.json' || !entry.startsWith('.'))
+            continue;
+        const types = asRecord(target)['types'] ?? asRecord(target)['typings'];
+        if (typeof types === 'string' && types.endsWith('.d.ts'))
+            entries.push([entry, resolve(packageDirectory, types)]);
+    }
+    if (entries.length === 0)
+        entries.push(...legacyEntriesOf(packageDirectory, '.', 0));
+    return entries.filter(([, path]) => existsSync(path));
+}
+/**
+ * Folders that never hold an entry point in the pre-`exports` layout: build
+ * formats, schematics and nested dependencies. Skipping them keeps the walk to
+ * a few dozen directories per package.
+ */
+const NON_ENTRY_DIRECTORIES = new Set(['node_modules', 'schematics', 'bundles', 'esm5', 'esm2015', 'esm2020', 'fesm5', 'fesm2015', 'fesm2020', 'src', 'locales', 'third_party', 'migrations']);
+/**
+ * Entry points of a package in the pre-`exports` layout (Angular 12 and
+ * older): this folder's `package.json` `typings`, then each subfolder's, up to
+ * three levels deep (`@angular/common/http/testing` is the deepest Angular has).
+ *
+ * @param entry The entry as an `exports` key would spell it: `.`, `./testing`.
+ */
+function legacyEntriesOf(directory, entry, depth) {
+    const entries = [];
+    const packageJson = readJson(join(directory, 'package.json'));
+    const types = packageJson?.['types'] ?? packageJson?.['typings'];
+    if (typeof types === 'string')
+        entries.push([entry, resolve(directory, types)]);
+    if (depth >= 3)
+        return entries;
+    for (const name of safeReaddir(directory)) {
+        if (NON_ENTRY_DIRECTORIES.has(name) || name.startsWith('.'))
+            continue;
+        const child = join(directory, name);
+        if (!existsSync(join(child, 'package.json')))
+            continue;
+        entries.push(...legacyEntriesOf(child, `${entry}/${name}`, depth + 1));
+    }
+    return entries;
+}
+/**
+ * Reads deprecations out of a bundle of `.d.ts` files, following re-exports
+ * between them.
+ *
+ * Angular 20+ ships each entry point as a thin `.d.ts` that re-exports from
+ * shared chunks, often under a different name (`export { a as NgIf } from
+ * './_common_module-chunk.js'`), so the deprecation sits on a declaration in
+ * one file and the public name lives in another. One reader instance memoises
+ * per file, which matters because many entry points share the same chunks.
+ */
+class DtsReader {
+    cache = new Map();
+    /** The deprecated names `path` exports, under the names it exports them as. */
+    exportsOf(path, depth = 0) {
+        const cached = this.cache.get(path);
+        if (cached)
+            return cached;
+        const result = { symbols: new Map(), members: new Map() };
+        // Set before recursing, so a re-export cycle between chunks ends here instead of overflowing.
+        this.cache.set(path, result);
+        if (depth > 8 || !existsSync(path))
+            return result;
+        const source = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true);
+        const local = localDeprecations(source);
+        /** Names imported from sibling chunks, which a later `export { x }` may re-export. */
+        const importedFrom = new Map();
+        const exportAs = (from, original, exported) => {
+            const symbol = from.symbols.get(original);
+            if (symbol)
+                result.symbols.set(exported, symbol);
+            for (const [member, info] of from.members) {
+                if (member.startsWith(`${original}.`))
+                    result.members.set(`${exported}${member.slice(original.length)}`, info);
+            }
+        };
+        for (const statement of source.statements) {
+            if (ts.isImportDeclaration(statement) && ts.isStringLiteralLike(statement.moduleSpecifier) && statement.moduleSpecifier.text.startsWith('.')) {
+                const file = siblingDts(path, statement.moduleSpecifier.text);
+                const named = statement.importClause?.namedBindings;
+                if (named && ts.isNamedImports(named)) {
+                    for (const element of named.elements)
+                        importedFrom.set(element.name.text, { file, name: (element.propertyName ?? element.name).text });
+                }
+                continue;
+            }
+            if (ts.isExportDeclaration(statement)) {
+                const moduleSpecifier = statement.moduleSpecifier;
+                const target = moduleSpecifier && ts.isStringLiteralLike(moduleSpecifier) && moduleSpecifier.text.startsWith('.') ? this.exportsOf(siblingDts(path, moduleSpecifier.text), depth + 1) : undefined;
+                const clause = statement.exportClause;
+                if (!clause) {
+                    // `export * from './x.js'`: everything x exports, under the same names.
+                    if (target) {
+                        for (const [name, info] of target.symbols)
+                            result.symbols.set(name, info);
+                        for (const [name, info] of target.members)
+                            result.members.set(name, info);
+                    }
+                    continue;
+                }
+                if (!ts.isNamedExports(clause))
+                    continue;
+                for (const element of clause.elements) {
+                    const original = (element.propertyName ?? element.name).text;
+                    const exported = element.name.text;
+                    if (target) {
+                        exportAs(target, original, exported);
+                    }
+                    else if (local.symbols.has(original) || [...local.members.keys()].some((key) => key.startsWith(`${original}.`))) {
+                        exportAs(local, original, exported);
+                    }
+                    else {
+                        const imported = importedFrom.get(original);
+                        if (imported)
+                            exportAs(this.exportsOf(imported.file, depth + 1), imported.name, exported);
+                    }
+                }
+                continue;
+            }
+            // `export declare class X` and friends, exported under their own name.
+            if (ts.canHaveModifiers(statement) && ts.getModifiers(statement)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+                for (const name of declaredNames(statement))
+                    exportAs(local, name, name);
+            }
+        }
+        return result;
+    }
+}
+/**
+ * Deprecated top-level declarations of one file, by their local name, plus
+ * deprecated enum members and static class members.
+ *
+ * A name counts as deprecated only when **every** declaration of it carries the
+ * tag. Overloaded functions often deprecate one signature (an old parameter
+ * shape) while the function itself is fine, and an interface merged with a
+ * const (how Angular declares decorators) can deprecate one half. Flagging those
+ * would accuse every caller of using a deprecated API.
+ */
+function localDeprecations(source) {
+    const declarations = new Map();
+    const members = new Map();
+    for (const statement of source.statements) {
+        const info = deprecationOf(statement);
+        for (const name of declaredNames(statement)) {
+            const list = declarations.get(name) ?? [];
+            list.push(info);
+            declarations.set(name, list);
+        }
+        if (ts.isEnumDeclaration(statement)) {
+            for (const member of statement.members) {
+                const memberInfo = deprecationOf(member);
+                if (memberInfo && ts.isIdentifier(member.name))
+                    members.set(`${statement.name.text}.${member.name.text}`, memberInfo);
+            }
+        }
+        if (ts.isClassDeclaration(statement) && statement.name) {
+            const byMember = new Map();
+            for (const member of statement.members) {
+                const isStatic = ts.canHaveModifiers(member) && ts.getModifiers(member)?.some((modifier) => modifier.kind === ts.SyntaxKind.StaticKeyword);
+                if (!isStatic || !member.name || !ts.isIdentifier(member.name))
+                    continue;
+                const list = byMember.get(member.name.text) ?? [];
+                list.push(deprecationOf(member));
+                byMember.set(member.name.text, list);
+            }
+            for (const [name, list] of byMember) {
+                const first = list[0];
+                if (first && list.every(Boolean))
+                    members.set(`${statement.name.text}.${name}`, first);
+            }
+        }
+    }
+    const symbols = new Map();
+    for (const [name, list] of declarations) {
+        // `ɵ` marks Angular's private API. Its deprecations are internal bookkeeping, not upgrade advice.
+        if (name.startsWith('ɵ'))
+            continue;
+        const first = list[0];
+        if (first && list.every(Boolean))
+            symbols.set(name, first);
+    }
+    return { symbols, members };
+}
+/** The names a top-level statement declares. Empty for anything that declares none. */
+function declaredNames(statement) {
+    if (ts.isVariableStatement(statement)) {
+        return statement.declarationList.declarations.flatMap((declaration) => (ts.isIdentifier(declaration.name) ? [declaration.name.text] : []));
+    }
+    if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement) || ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isEnumDeclaration(statement)) &&
+        statement.name) {
+        return [statement.name.text];
+    }
+    return [];
+}
+/** The node's `@deprecated` tag, parsed, or undefined when it has none. */
+function deprecationOf(node) {
+    const tag = ts.getJSDocDeprecatedTag(node);
+    if (!tag)
+        return undefined;
+    const text = (ts.getTextOfJSDocComment(tag.comment) ?? '').replace(/\s+/g, ' ').trim();
+    // Angular writes the version three ways: `20.0 Use …`, `from v19.0.0, use …`, `since v17`.
+    const version = /^(?:(?:from|since|in)\s+)?v?(\d+(?:\.\d+){0,2})\b[:.,]?\s*/i.exec(text);
+    return version ? { since: version[1], message: text.slice(version[0].length) } : { since: undefined, message: text };
+}
+/** `./_chunk.js` next to `from`, as the `.d.ts` that types it. */
+function siblingDts(from, specifier) {
+    const base = resolve(dirname(from), specifier);
+    if (base.endsWith('.d.ts'))
+        return base;
+    if (base.endsWith('.js') || base.endsWith('.mjs'))
+        return base.replace(/\.m?js$/, '.d.ts');
+    return existsSync(`${base}.d.ts`) ? `${base}.d.ts` : join(base, 'index.d.ts');
+}
+/** `readdirSync` that treats an unreadable directory as empty. */
+function safeReaddir(directory) {
+    try {
+        return readdirSync(directory);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=deprecations.js.map

package/dist/deprecations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecations.js","sourceRoot":"","sources":["../src/deprecations.ts"],"names":[],"mappings":"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"}

package/dist/files.d.ts

@@ -0,0 +1,33 @@
+/** Everything `collectFiles` found, as absolute paths. */
+export interface CollectedFiles {
+    /** `.ts` files, without `.d.ts` declaration files. */
+    typescript: string[];
+    /** `.html` files, which in an Angular repository are almost all component templates. */
+    html: string[];
+    /** Every `project.json`, which is how an Nx workspace describes its projects. */
+    projectJsons: string[];
+}
+/**
+ * Walks `root` once and sorts the files an analysis needs by kind.
+ *
+ * One walk serves the whole run, so a large monorepo is read from disk once.
+ * The result is sorted, which keeps report output stable between runs on the
+ * same tree. An unreadable directory is skipped rather than failing the run,
+ * since a permissions problem in one corner says nothing about the code.
+ *
+ * @param isIgnored The config file's `ignore` patterns as a predicate over
+ *   report paths. An ignored directory is not descended into at all, which is
+ *   what makes ignoring a large generated folder cheap.
+ */
+export declare function collectFiles(root: string, isIgnored?: (relativePath: string) => boolean): CollectedFiles;
+/**
+ * The form every report uses for a path: relative to the analysed root, with
+ * `/` separators on every platform, so a report generated on Windows reads the
+ * same as one generated on macOS.
+ */
+export declare function toReportPath(root: string, absolute: string): string;
+/**
+ * True for unit-test files. Angular CLI and Nx both name them `*.spec.ts`;
+ * `*.test.ts` covers Jest and Vitest setups that follow the other convention.
+ */
+export declare function isSpecFile(path: string): boolean;

package/dist/files.js

@@ -0,0 +1,98 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+/**
+ * Directory names never descended into.
+ *
+ * Build output, caches and dependencies hold generated code that would swamp
+ * every count (one `dist` folder can double the `any` total), and none of it is
+ * code the team maintains. Hidden directories are skipped by a separate rule in
+ * `walk`, which is what keeps `.git`, `.angular`, `.nx` and editor folders out.
+ */
+const SKIPPED_DIRECTORIES = new Set(['node_modules', 'dist', 'coverage', 'out-tsc', 'tmp', 'bazel-out']);
+/**
+ * Files above this size are skipped as generated. A hand-written Angular source
+ * file is far below it, while a checked-in API client or a bundled vendor file
+ * is not, and parsing one can cost more than the rest of the repository.
+ */
+const MAX_FILE_BYTES = 1_000_000;
+/**
+ * Walks `root` once and sorts the files an analysis needs by kind.
+ *
+ * One walk serves the whole run, so a large monorepo is read from disk once.
+ * The result is sorted, which keeps report output stable between runs on the
+ * same tree. An unreadable directory is skipped rather than failing the run,
+ * since a permissions problem in one corner says nothing about the code.
+ *
+ * @param isIgnored The config file's `ignore` patterns as a predicate over
+ *   report paths. An ignored directory is not descended into at all, which is
+ *   what makes ignoring a large generated folder cheap.
+ */
+export function collectFiles(root, isIgnored) {
+    const result = { typescript: [], html: [], projectJsons: [] };
+    walk(root, root, result, isIgnored);
+    result.typescript.sort();
+    result.html.sort();
+    result.projectJsons.sort();
+    return result;
+}
+/**
+ * The recursive half of `collectFiles`. Mutates `into`.
+ */
+function walk(root, directory, into, isIgnored) {
+    let entries;
+    try {
+        entries = readdirSync(directory, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const path = join(directory, entry.name);
+        if (isIgnored?.(toReportPath(root, path)))
+            continue;
+        if (entry.isDirectory()) {
+            if (entry.name.startsWith('.') || SKIPPED_DIRECTORIES.has(entry.name))
+                continue;
+            walk(root, path, into, isIgnored);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        if (entry.name === 'project.json') {
+            into.projectJsons.push(path);
+        }
+        else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
+            if (isWithinSizeLimit(path))
+                into.typescript.push(path);
+        }
+        else if (entry.name.endsWith('.html')) {
+            if (isWithinSizeLimit(path))
+                into.html.push(path);
+        }
+    }
+}
+/** False for files `MAX_FILE_BYTES` treats as generated, and for files that vanished mid-walk. */
+function isWithinSizeLimit(path) {
+    try {
+        return statSync(path).size <= MAX_FILE_BYTES;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The form every report uses for a path: relative to the analysed root, with
+ * `/` separators on every platform, so a report generated on Windows reads the
+ * same as one generated on macOS.
+ */
+export function toReportPath(root, absolute) {
+    return relative(root, absolute).split(sep).join('/');
+}
+/**
+ * True for unit-test files. Angular CLI and Nx both name them `*.spec.ts`;
+ * `*.test.ts` covers Jest and Vitest setups that follow the other convention.
+ */
+export function isSpecFile(path) {
+    return /\.(spec|test)\.ts$/.test(path);
+}
+//# sourceMappingURL=files.js.map

package/dist/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC;AAEzG;;;;GAIG;AACH,MAAM,cAAc,GAAG,SAAS,CAAC;AAYjC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,SAA6C;IACtF,MAAM,MAAM,GAAmB,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;IAC9E,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IACpC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;IACzB,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACnB,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;IAC3B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,SAAS,IAAI,CAAC,IAAY,EAAE,SAAiB,EAAE,IAAoB,EAAE,SAA6C;IAChH,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,SAAS,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAAE,SAAS;QACpD,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,mBAAmB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;gBAAE,SAAS;YAChF,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;YAClC,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;YAAE,SAAS;QAC9B,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YAClC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACvE,IAAI,iBAAiB,CAAC,IAAI,CAAC;gBAAE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1D,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACxC,IAAI,iBAAiB,CAAC,IAAI,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;AACH,CAAC;AAED,kGAAkG;AAClG,SAAS,iBAAiB,CAAC,IAAY;IACrC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,cAAc,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,QAAgB;IACzD,OAAO,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC"}