find-primordials 1.0.0

package/ignore.mjs

@@ -0,0 +1,161 @@
+
+import * as minimatchModule from 'minimatch';
+
+/**
+ * Resolve the minimatch callable across module shapes (v3 CJS default vs v10+ named export).
+ * @param {Record<string, unknown>} mod - The imported minimatch module namespace
+ * @returns {(target: string, pattern: string, options?: object) => boolean}
+ */
+export function resolveMinimatch(mod) {
+	// @ts-expect-error - interop across minimatch major versions is not statically typed
+	return mod.minimatch || mod.default || mod;
+}
+
+/* Handle both minimatch v3 (CJS default) and v10+ (named export) */
+const minimatch = resolveMinimatch(minimatchModule);
+
+/*
+ * Ignore configuration format:
+ * {
+ *   files: ['vendor/**'],              // Glob patterns - ignore entire files
+ *   types: ['spread', 'global'],       // Finding types to ignore
+ *   categories: ['RegExp'],            // Categories to ignore
+ *   names: ['test', 'exec'],           // Method/property names to ignore
+ *   rules: [                           // Fine-grained rules
+ *     { files: ['src/*.js'], types: ['instanceMethod'] },
+ *     { files: ['helpers/**'], names: ['push'] },
+ *   ]
+ * }
+ */
+
+/** @import { Finding } from '#/analyzer' */
+
+const VALID_TYPES = new Set(/** @type {const} */ ([
+	'global',
+	'instanceMethod',
+	'prototypeAccess',
+	'spread',
+	'staticMethod',
+	'staticProperty',
+]));
+
+/** @typedef {{ categories?: string[], files?: string[], names?: string[], rules?: unknown, types?: string[] }} RawIgnoreConfig */
+/** @typedef {{ categories: Set<string>, files: string[], names: Set<string>, rules: { categories: Set<string>, files: string[], names: Set<string>, types: Set<string> }[], types: Set<string> }} IgnoreConfig */
+
+/**
+ * Normalize ignore config to a consistent format
+ * @param {RawIgnoreConfig | IgnoreConfig} config
+ * @returns {null | IgnoreConfig}
+ */
+export function normalizeIgnoreConfig(config) {
+	if (!config) {
+		return null;
+	}
+
+	return {
+		categories: Array.isArray(config.categories) ? new Set(config.categories) : new Set(),
+		files: Array.isArray(config.files) ? config.files : [],
+		names: Array.isArray(config.names) ? new Set(config.names) : new Set(),
+		rules: Array.isArray(config.rules) ? config.rules.map((rule) => ({
+			categories: Array.isArray(rule.categories) ? new Set(rule.categories) : new Set(),
+			files: Array.isArray(rule.files) ? rule.files : [],
+			names: Array.isArray(rule.names) ? new Set(rule.names) : new Set(),
+			types: Array.isArray(rule.types) ? new Set(rule.types) : new Set(),
+		})) : [],
+		types: Array.isArray(config.types) ? new Set(config.types) : new Set(),
+	};
+}
+
+/**
+ * Check if a file path matches any of the glob patterns
+ * @param {string} filePath
+ * @param {string[]} patterns
+ */
+function matchesAnyPattern(filePath, patterns) {
+	for (const pattern of patterns) {
+		if (minimatch(filePath, pattern, { dot: true, matchBase: true })) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Check if a file should be ignored entirely
+ * @param {string} filePath
+ * @param {IgnoreConfig} [ignoreConfig]
+ */
+export function shouldIgnoreFile(filePath, ignoreConfig) {
+	if (!ignoreConfig || ignoreConfig.files.length === 0) {
+		return false;
+	}
+	return matchesAnyPattern(filePath, ignoreConfig.files);
+}
+
+/**
+ * Check if a finding should be ignored
+ * @param {Finding} finding
+ * @param {IgnoreConfig} [ignoreConfig]
+ */
+export function shouldIgnoreFinding(finding, ignoreConfig) {
+	if (!ignoreConfig) {
+		return false;
+	}
+
+	// Check global type filter
+	if (ignoreConfig.types.has(finding.type)) {
+		return true;
+	}
+
+	// Check global category filter
+	if (finding.category && ignoreConfig.categories.has(finding.category)) {
+		return true;
+	}
+
+	// Check global name filter
+	if (finding.name && ignoreConfig.names.has(finding.name)) {
+		return true;
+	}
+
+	// Check fine-grained rules
+	for (const rule of ignoreConfig.rules) {
+		// Rule must match file pattern (if specified) and have at least one filter
+		const fileMatches = rule.files.length === 0 || matchesAnyPattern(finding.file, rule.files);
+		const hasFilters = rule.types.size > 0 || rule.categories.size > 0 || rule.names.size > 0;
+
+		if (fileMatches && hasFilters && rule.files.length > 0) {
+			// For file-specific rules, ANY matching filter causes ignore
+			if (rule.types.has(finding.type)) {
+				return true;
+			}
+			if (finding.category && rule.categories.has(finding.category)) {
+				return true;
+			}
+			if (finding.name && rule.names.has(finding.name)) {
+				return true;
+			}
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Filter an array of findings based on ignore config
+ * @param {Finding[]} findings
+ * @param {IgnoreConfig | null} [ignoreConfig]
+ */
+export function filterFindings(findings, ignoreConfig) {
+	if (!ignoreConfig) {
+		return findings;
+	}
+	return findings.filter((finding) => !shouldIgnoreFinding(finding, ignoreConfig));
+}
+
+/**
+ * Get valid finding types for documentation/validation
+ * @returns {(typeof VALID_TYPES extends Set<infer R> ? R : never)[]}
+ */
+export function getValidTypes() {
+	return [...VALID_TYPES];
+}

package/index.d.mts

@@ -0,0 +1,201 @@
+// Type declarations for `find-primordials`.
+
+/** A source position, as ESTree records it. */
+export type SourceLocation = {
+	start: { line: number; column: number };
+	end: { line: number; column: number };
+};
+
+/**
+ * A parsed ESTree/TSESTree node: one permissive shape whose fields the predicates read
+ * after checking `type`. A node that may be absent is {@link MaybeNode}.
+ */
+export type ASTNode = {
+	type: string;
+	name: string;
+	operator: string;
+	kind: string;
+	computed: boolean;
+	shorthand: boolean;
+	object: ASTNode;
+	property: ASTNode;
+	callee: ASTNode;
+	left: ASTNode;
+	right: ASTNode;
+	test: ASTNode;
+	consequent: ASTNode;
+	alternate: ASTNode;
+	argument: ASTNode;
+	id: ASTNode;
+	init: ASTNode;
+	key: ASTNode;
+	local: ASTNode;
+	param: ASTNode;
+	arguments: ASTNode[];
+	properties: ASTNode[];
+	params: ASTNode[];
+	expressions: ASTNode[];
+	declarations: ASTNode[];
+	specifiers: ASTNode[];
+	elements: (ASTNode | null)[];
+	comments: ASTNode[];
+	value: unknown;
+	body: unknown;
+	range: [number, number];
+	loc: SourceLocation;
+};
+
+/** An {@link ASTNode} that may be absent. */
+export type MaybeNode = ASTNode | null | undefined;
+
+/** The finding kinds that have an autofix. */
+export type FixKind = 'at' | 'constructor' | 'isNaN' | 'push' | 'undefined';
+
+/** A finding type accepted in ignore configuration. */
+export type FindingType = 'global' | 'instanceMethod' | 'prototypeAccess' | 'spread' | 'staticMethod' | 'staticProperty';
+
+/** A primordial usage the analyzer reports. */
+export type Finding = {
+	type: string;
+	name: string;
+	certainty: string;
+	file: string;
+	line?: number;
+	column?: number;
+	category?: string | null;
+	possibleCategories?: string[];
+};
+
+/** A parse/read error encountered while analyzing a file. */
+export type AnalysisError = {
+	error: string;
+	file: string;
+};
+
+/** The findings and errors from analyzing one or more files. */
+export type AnalysisResult = {
+	errors: AnalysisError[];
+	findings: Finding[];
+};
+
+/** Options accepted by the analyzers. */
+export type AnalyzeOptions = {
+	includeGlobals?: boolean;
+	includeSpread?: boolean;
+	includeStatic?: boolean;
+	includeUncertain?: boolean;
+	isSafe?: boolean;
+	isSafeFile?: ((filePath: string) => boolean) | null;
+	concurrency?: number;
+};
+
+/** The result of rewriting a file. */
+export type FixResult = {
+	fixed: boolean;
+	output: string;
+	fixCount: number;
+	fixCounts: Record<FixKind, number>;
+};
+
+/** Raw ignore configuration, as authored in a config file. */
+export type RawIgnoreConfig = {
+	categories?: string[];
+	files?: string[];
+	names?: string[];
+	rules?: unknown;
+	types?: string[];
+};
+
+/** A fine-grained ignore rule within a normalized {@link IgnoreConfig}. */
+export type IgnoreRule = {
+	categories: Set<string>;
+	files: string[];
+	names: Set<string>;
+	types: Set<string>;
+};
+
+/** Normalized ignore configuration. */
+export type IgnoreConfig = {
+	categories: Set<string>;
+	files: string[];
+	names: Set<string>;
+	rules: IgnoreRule[];
+	types: Set<string>;
+};
+
+/** The slice of a TypeScript `Type` that {@link describeType} reads. */
+export type TypeLike = { flags: number };
+
+/** The slice of a TypeScript type checker that {@link describeType} reads. */
+export type TypeCheckerLike<T extends TypeLike> = {
+	typeToString: (type: T) => string;
+	isArrayType?: (type: T) => boolean;
+	isTupleType?: (type: T) => boolean;
+};
+
+// ---- analysis ----
+
+export function analyzeFile(filePath: string, options?: AnalyzeOptions): { error: string | null; findings: Finding[] };
+export function analyzeFiles(filePaths: string[], options?: AnalyzeOptions): AnalysisResult;
+export function analyzeFilesParallel(filePaths: string[], options?: AnalyzeOptions): Promise<AnalysisResult>;
+
+// ---- fixes ----
+
+export function applyFixes(filePath: string, findings: Finding[]): FixResult;
+export function applyPushFixes(filePath: string, findings: Finding[]): FixResult;
+export function applyUndefinedFixes(filePath: string, findings: Finding[]): FixResult;
+
+// ---- fix predicates (shared with the ESLint plugin's rewrites) ----
+
+export function isCalled(node: ASTNode, parent: MaybeNode): boolean;
+export function isRepeatable(node: MaybeNode): boolean;
+export function isReevaluable(node: MaybeNode): boolean;
+export function literalIndex(arg: ASTNode): number | null;
+export function startsAStatement(node: ASTNode, parent: MaybeNode): boolean;
+export function canBeArrayLiteral(args: ASTNode[]): boolean;
+export function voidNeedsParens(node: ASTNode, parent: MaybeNode): boolean;
+export function canRewriteUndefined(parent: MaybeNode): boolean;
+
+// ---- type description ----
+
+export function describeType<T extends TypeLike>(typeChecker: TypeCheckerLike<T>, type: T): string | null;
+
+// ---- formatting / grouping ----
+
+export function categoryLabel(finding: Finding): string;
+export function groupFindingsByCategory(findings: Finding[]): Record<string, Finding[]>;
+export function formatFindingAsTAP(finding: Finding, testNum: number): string;
+export function formatAsTAP(findings: Finding[], options?: { showUncertain?: boolean }): string;
+
+// ---- ignore configuration ----
+
+export function normalizeIgnoreConfig(config: RawIgnoreConfig | IgnoreConfig): IgnoreConfig | null;
+export function shouldIgnoreFile(filePath: string, ignoreConfig?: IgnoreConfig): boolean;
+export function shouldIgnoreFinding(finding: Finding, ignoreConfig?: IgnoreConfig): boolean;
+export function filterFindings(findings: Finding[], ignoreConfig?: IgnoreConfig | null): Finding[];
+export function getValidTypes(): FindingType[];
+
+// ---- file classification ----
+
+export function isTestFile(filePath: string): boolean;
+export function isConfigFile(filePath: string): boolean;
+export function isBinFile(filePath: string): boolean;
+export function isPrivatePackage(filePath: string): boolean;
+export function isUnpublishedFile(filePath: string): boolean;
+export function isSafeFile(filePath: string): boolean;
+
+/** The default file extensions the analyzers scan. */
+export const defaultExtensions: string[];
+
+// ---- primordial data (also available at `find-primordials/primordials`) ----
+
+export {
+	allGlobals,
+	allInstanceMethods,
+	allStaticMethods,
+	ambiguousInstanceMethods,
+	globalToCategory,
+	primordials,
+	typedArrayGlobals,
+} from './primordials.mjs';
+export type { PrimordialCategory } from './primordials.mjs';