deslop-js 0.9.5 → 0.9.6

package/README.md

@@ -89,6 +89,7 @@ const result = await analyze(config);
 result.unusedFiles; // files unreachable from any entry point
 result.unusedExports; // exported symbols never imported
 result.unusedDependencies; // package.json deps not imported anywhere
+result.skippedDependencies; // declared deps conservatively excluded from unused-dependency analysis
 result.circularDependencies; // import cycles
 
 // redundancy / DRY findings (syntactic, on by default)
@@ -136,6 +137,11 @@ result.totalExports;
 result.analysisTimeMs;
 ```
 
+`skippedDependencies` makes conservative unused-dependency exemptions explicit. It includes
+packages matched by the framework/tooling name allowlist and installed packages that provide a
+binary, because those uses can occur outside source imports and package scripts. A clean
+`unusedDependencies` result is not a verdict for those packages.
+
 ## Programmatic Options
 
 `defineConfig` accepts a required `rootDir` and optional overrides:

package/dist/index.cjs

@@ -7986,7 +7986,10 @@ const detectStalePackages = (graph, config, summaryCache) => {
 		const content = (0, node_fs.readFileSync)(packageJsonPath, "utf-8");
 		packageJson = JSON.parse(content);
 	} catch {
-		return [];
+		return {
+			unusedDependencies: [],
+			skippedDependencies: []
+		};
 	}
 	const dependencies = packageJson.dependencies ?? {};
 	const devDependencies = packageJson.devDependencies ?? {};
@@ -7994,7 +7997,12 @@ const detectStalePackages = (graph, config, summaryCache) => {
 	for (const dependencyName of Object.keys(dependencies)) declaredDependencies.set(dependencyName, false);
 	for (const dependencyName of Object.keys(devDependencies)) declaredDependencies.set(dependencyName, true);
 	const declaredNames = new Set(declaredDependencies.keys());
-	const usedPackageNames = collectUsedPackages(graph);
+	const observedPackageNames = collectUsedPackages(graph);
+	const usedPackageNames = new Set(observedPackageNames);
+	const markPackageUsed = (packageName) => {
+		observedPackageNames.add(packageName);
+		usedPackageNames.add(packageName);
+	};
 	const monorepoRoot = findMonorepoRoot(config.rootDir);
 	const nodeModulesSearchRoots = monorepoRoot && monorepoRoot !== config.rootDir ? [config.rootDir, monorepoRoot] : [config.rootDir];
 	const allPackageJsonPaths = discoverAllPackageJsonPaths(config.rootDir, summaryCache);
@@ -8006,29 +8014,29 @@ const detectStalePackages = (graph, config, summaryCache) => {
 	for (const packageName of packagesProvidingBinary) usedPackageNames.add(packageName);
 	for (const workspacePackageJsonPath of allPackageJsonPaths) {
 		const scriptReferenced = collectScriptReferencedPackages(workspacePackageJsonPath, declaredNames, binToPackage);
-		for (const packageName of scriptReferenced) usedPackageNames.add(packageName);
+		for (const packageName of scriptReferenced) markPackageUsed(packageName);
 		const packageJsonConfigReferenced = collectPackageJsonConfigReferences(workspacePackageJsonPath, declaredNames);
-		for (const packageName of packageJsonConfigReferenced) usedPackageNames.add(packageName);
+		for (const packageName of packageJsonConfigReferenced) markPackageUsed(packageName);
 	}
 	const nxProjectReferenced = collectNxProjectJsonReferences(config.rootDir, declaredNames, binToPackage, summaryCache);
-	for (const packageName of nxProjectReferenced) usedPackageNames.add(packageName);
+	for (const packageName of nxProjectReferenced) markPackageUsed(packageName);
 	const configSearchRoots = monorepoRoot && monorepoRoot !== config.rootDir ? [config.rootDir, monorepoRoot] : [config.rootDir];
 	for (const configSearchRoot of configSearchRoots) {
 		const configReferenced = collectConfigReferencedPackages(configSearchRoot, graph, declaredNames, summaryCache);
-		for (const packageName of configReferenced) usedPackageNames.add(packageName);
+		for (const packageName of configReferenced) markPackageUsed(packageName);
 		const tsconfigReferenced = collectTsconfigReferencedPackages(configSearchRoot, summaryCache);
-		for (const packageName of tsconfigReferenced) usedPackageNames.add(packageName);
+		for (const packageName of tsconfigReferenced) markPackageUsed(packageName);
 		const { packageNames: expoPluginPackageNames } = extractExpoConfigPluginEntries(configSearchRoot, {
 			...dependencies,
 			...devDependencies
 		});
-		for (const packageName of expoPluginPackageNames) if (declaredNames.has(packageName)) usedPackageNames.add(packageName);
+		for (const packageName of expoPluginPackageNames) if (declaredNames.has(packageName)) markPackageUsed(packageName);
 	}
 	if (hasJsxFiles(graph)) {
-		if (declaredNames.has("react")) usedPackageNames.add("react");
-		if (declaredNames.has("react-dom")) usedPackageNames.add("react-dom");
-		if (declaredNames.has("react-native")) usedPackageNames.add("react-native");
-		if (declaredNames.has("react-native-web")) usedPackageNames.add("react-native-web");
+		if (declaredNames.has("react")) markPackageUsed("react");
+		if (declaredNames.has("react-dom")) markPackageUsed("react-dom");
+		if (declaredNames.has("react-native")) markPackageUsed("react-native");
+		if (declaredNames.has("react-native-web")) markPackageUsed("react-native-web");
 	}
 	if (declaredNames.has("react-dom")) {
 		if ([
@@ -8043,26 +8051,37 @@ const detectStalePackages = (graph, config, summaryCache) => {
 			"@tanstack/react-router",
 			"@tanstack/react-start",
 			"react-app-rewired"
-		].some((framework) => declaredNames.has(framework) || usedPackageNames.has(framework))) usedPackageNames.add("react-dom");
+		].some((framework) => declaredNames.has(framework) || usedPackageNames.has(framework))) markPackageUsed("react-dom");
 	}
-	if (declaredNames.has("astro") && declaredNames.has("sharp")) usedPackageNames.add("sharp");
+	if (declaredNames.has("astro") && declaredNames.has("sharp")) markPackageUsed("sharp");
 	if (declaredNames.has("react") && declaredNames.has("react-dom")) {
 		const packageJsonPath = (0, node_path.resolve)(config.rootDir, "package.json");
 		try {
 			const content = (0, node_fs.readFileSync)(packageJsonPath, "utf-8");
 			const peerDeps = JSON.parse(content).peerDependencies ?? {};
-			if ("react" in peerDeps && declaredDependencies.get("react") === true) usedPackageNames.add("react");
-			if ("react-dom" in peerDeps && declaredDependencies.get("react-dom") === true) usedPackageNames.add("react-dom");
+			if ("react" in peerDeps && declaredDependencies.get("react") === true) markPackageUsed("react");
+			if ("react-dom" in peerDeps && declaredDependencies.get("react-dom") === true) markPackageUsed("react-dom");
 		} catch {}
 	}
 	const peerSatisfied = collectPeerSatisfiedPackages(nodeModulesSearchRoots, declaredNames, usedPackageNames);
 	for (const packageName of peerSatisfied) usedPackageNames.add(packageName);
 	const overrideMappings = collectOverrideMappings(configSearchRoots, allPackageJsonPaths, monorepoRoot);
 	for (const { fromPackage, toPackage } of overrideMappings) {
-		if (declaredNames.has(toPackage)) usedPackageNames.add(toPackage);
-		if (usedPackageNames.has(fromPackage) && declaredNames.has(toPackage)) usedPackageNames.add(toPackage);
+		if (declaredNames.has(toPackage)) markPackageUsed(toPackage);
+		if (usedPackageNames.has(fromPackage) && declaredNames.has(toPackage)) markPackageUsed(toPackage);
 	}
 	const candidateUnused = /* @__PURE__ */ new Set();
+	const skippedDependenciesByName = /* @__PURE__ */ new Map();
+	const recordSkippedDependency = (dependencyName, reason) => {
+		const reasons = skippedDependenciesByName.get(dependencyName) ?? /* @__PURE__ */ new Set();
+		reasons.add(reason);
+		skippedDependenciesByName.set(dependencyName, reasons);
+	};
+	for (const [dependencyName] of declaredDependencies) {
+		if (observedPackageNames.has(dependencyName) || peerSatisfied.has(dependencyName)) continue;
+		if (isAlwaysConsideredUsed(dependencyName)) recordSkippedDependency(dependencyName, "allowlisted-name");
+		if (packagesProvidingBinary.has(dependencyName)) recordSkippedDependency(dependencyName, "provides-binary");
+	}
 	for (const [dependencyName] of declaredDependencies) {
 		if (isAlwaysConsideredUsed(dependencyName)) continue;
 		if (usedPackageNames.has(dependencyName)) continue;
@@ -8071,7 +8090,7 @@ const detectStalePackages = (graph, config, summaryCache) => {
 	if (candidateUnused.size > 0) {
 		const sourceFileRescued = scanSourceFilesForPackageImports(config.rootDir, candidateUnused, summaryCache);
 		for (const packageName of sourceFileRescued) {
-			usedPackageNames.add(packageName);
+			markPackageUsed(packageName);
 			candidateUnused.delete(packageName);
 		}
 	}
@@ -8085,7 +8104,14 @@ const detectStalePackages = (graph, config, summaryCache) => {
 			reason: `"${dependencyName}" is declared in ${dependencySection} but is never imported or referenced by any source file, script, or config — remove it from package.json if it is genuinely unused`
 		});
 	}
-	return unusedDependencies;
+	return {
+		unusedDependencies,
+		skippedDependencies: [...skippedDependenciesByName.entries()].sort(([leftName], [rightName]) => leftName.localeCompare(rightName)).map(([name, reasons]) => ({
+			name,
+			isDevDependency: declaredDependencies.get(name) ?? false,
+			reasons: [...reasons].sort()
+		}))
+	};
 };
 const collectUsedPackages = (graph) => {
 	const usedPackages = /* @__PURE__ */ new Set();
@@ -12477,7 +12503,11 @@ const generateReport = (graph, config, summaryCache) => {
 	}
 	const unusedFiles = safeReportDetector("detectOrphanFiles", () => detectOrphanFiles(graph), [], errorSink);
 	const unusedExports = safeReportDetector("detectDeadExports", () => detectDeadExports(graph, config), [], errorSink);
-	const unusedDependencies = safeReportDetector("detectStalePackages", () => detectStalePackages(graph, config, summaryCache), [], errorSink);
+	const stalePackageReport = safeReportDetector("detectStalePackages", () => detectStalePackages(graph, config, summaryCache), {
+		unusedDependencies: [],
+		skippedDependencies: []
+	}, errorSink);
+	const unusedDependencies = stalePackageReport.unusedDependencies;
 	const circularDependencies = safeReportDetector("detectCycles", () => detectCycles(graph), [], errorSink);
 	const syntacticRedundantAliases = config.reportRedundancy ? [...safeReportDetector("detectRedundantAliases", () => detectRedundantAliases(graph), [], errorSink), ...safeReportDetector("detectUselessAliasedReExports", () => detectUselessAliasedReExports(graph), [], errorSink)] : [];
 	const duplicateExports = config.reportRedundancy ? safeReportDetector("detectDuplicateExports", () => detectDuplicateExports(graph), [], errorSink) : [];
@@ -12536,6 +12566,7 @@ const generateReport = (graph, config, summaryCache) => {
 		unusedFiles,
 		unusedExports,
 		unusedDependencies,
+		skippedDependencies: stalePackageReport.skippedDependencies,
 		circularDependencies,
 		unusedTypes: semanticResult.unusedTypes,
 		misclassifiedDependencies: semanticResult.misclassifiedDependencies,

package/dist/index.d.cts

@@ -49,6 +49,12 @@ interface UnusedDependency {
   isDevDependency: boolean;
   reason: string;
 }
+type SkippedDependencyReason = "allowlisted-name" | "provides-binary";
+interface SkippedDependency {
+  name: string;
+  isDevDependency: boolean;
+  reasons: SkippedDependencyReason[];
+}
 interface CircularDependency {
   files: string[];
 }
@@ -369,6 +375,8 @@ interface ScanResult {
   unusedFiles: UnusedFile[];
   unusedExports: UnusedExport[];
   unusedDependencies: UnusedDependency[];
+  /** Declared dependencies conservatively excluded from unused-dependency analysis. */
+  skippedDependencies?: SkippedDependency[];
   circularDependencies: CircularDependency[];
   unusedTypes: UnusedType[];
   misclassifiedDependencies: MisclassifiedDependency[];
@@ -465,4 +473,4 @@ declare const defineConfig: (options: Partial<DeslopConfig> & {
 }) => DeslopConfig;
 declare const analyze: (config: DeslopConfig) => Promise<ScanResult>;
 //#endregion
-export { type CircularDependency, type ClassMemberKind, type CommonjsInEsm, type CommonjsInEsmKind, type ComplexityConfig, type CrossFileDuplicateExport, type CrossFileDuplicateExportLocation, type DependencyDeclaredAs, type DeslopConfig, type DeslopError, type DeslopErrorCode, type DeslopErrorModule, type DeslopErrorSeverity, type DuplicateBlock, type DuplicateBlockCluster, type DuplicateBlockDetectionMode, type DuplicateBlockOccurrence, type DuplicateBlockRefactoringHint, type DuplicateBlockRefactoringKind, type DuplicateBlocksConfig, type DuplicateConstant, type DuplicateConstantOccurrence, type DuplicateExport, type DuplicateExportOccurrence, type DuplicateImport, type DuplicateImportOccurrence, type DuplicateInlineType, type DuplicateTypeDefinition, type DuplicateTypeDefinitionInstance, type FeatureFlag, type FeatureFlagKind, type FeatureFlagsConfig, type FunctionComplexity, type IdentityWrapper, type InlineTypeContext, type InlineTypeOccurrence, type LazyImportAtTopLevel, type LazyImportKind, type MisclassifiedDependency, type PrivateTypeLeak, type ReExportCycle, type ReExportCycleKind, type RedundantAlias, type RedundantAliasKind, type RedundantTypePattern, type RedundantTypePatternKind, type ScanResult, type SemanticConfidence, type SemanticConfig, type ShadowedDirectoryPair, type SimplifiableExpression, type SimplifiableExpressionKind, type SimplifiableFunction, type SimplifiableFunctionKind, type TypeScriptEscapeHatch, type TypeScriptEscapeHatchKind, type UnnecessaryAssertion, type UnnecessaryAssertionKind, type UnusedClassMember, type UnusedDependency, type UnusedEnumMember, type UnusedExport, type UnusedFile, type UnusedType, type UnusedTypeKind, analyze, defineConfig };
+export { type CircularDependency, type ClassMemberKind, type CommonjsInEsm, type CommonjsInEsmKind, type ComplexityConfig, type CrossFileDuplicateExport, type CrossFileDuplicateExportLocation, type DependencyDeclaredAs, type DeslopConfig, type DeslopError, type DeslopErrorCode, type DeslopErrorModule, type DeslopErrorSeverity, type DuplicateBlock, type DuplicateBlockCluster, type DuplicateBlockDetectionMode, type DuplicateBlockOccurrence, type DuplicateBlockRefactoringHint, type DuplicateBlockRefactoringKind, type DuplicateBlocksConfig, type DuplicateConstant, type DuplicateConstantOccurrence, type DuplicateExport, type DuplicateExportOccurrence, type DuplicateImport, type DuplicateImportOccurrence, type DuplicateInlineType, type DuplicateTypeDefinition, type DuplicateTypeDefinitionInstance, type FeatureFlag, type FeatureFlagKind, type FeatureFlagsConfig, type FunctionComplexity, type IdentityWrapper, type InlineTypeContext, type InlineTypeOccurrence, type LazyImportAtTopLevel, type LazyImportKind, type MisclassifiedDependency, type PrivateTypeLeak, type ReExportCycle, type ReExportCycleKind, type RedundantAlias, type RedundantAliasKind, type RedundantTypePattern, type RedundantTypePatternKind, type ScanResult, type SemanticConfidence, type SemanticConfig, type ShadowedDirectoryPair, type SimplifiableExpression, type SimplifiableExpressionKind, type SimplifiableFunction, type SimplifiableFunctionKind, type SkippedDependency, type SkippedDependencyReason, type TypeScriptEscapeHatch, type TypeScriptEscapeHatchKind, type UnnecessaryAssertion, type UnnecessaryAssertionKind, type UnusedClassMember, type UnusedDependency, type UnusedEnumMember, type UnusedExport, type UnusedFile, type UnusedType, type UnusedTypeKind, analyze, defineConfig };

package/dist/index.d.mts

@@ -49,6 +49,12 @@ interface UnusedDependency {
   isDevDependency: boolean;
   reason: string;
 }
+type SkippedDependencyReason = "allowlisted-name" | "provides-binary";
+interface SkippedDependency {
+  name: string;
+  isDevDependency: boolean;
+  reasons: SkippedDependencyReason[];
+}
 interface CircularDependency {
   files: string[];
 }
@@ -369,6 +375,8 @@ interface ScanResult {
   unusedFiles: UnusedFile[];
   unusedExports: UnusedExport[];
   unusedDependencies: UnusedDependency[];
+  /** Declared dependencies conservatively excluded from unused-dependency analysis. */
+  skippedDependencies?: SkippedDependency[];
   circularDependencies: CircularDependency[];
   unusedTypes: UnusedType[];
   misclassifiedDependencies: MisclassifiedDependency[];
@@ -465,4 +473,4 @@ declare const defineConfig: (options: Partial<DeslopConfig> & {
 }) => DeslopConfig;
 declare const analyze: (config: DeslopConfig) => Promise<ScanResult>;
 //#endregion
-export { type CircularDependency, type ClassMemberKind, type CommonjsInEsm, type CommonjsInEsmKind, type ComplexityConfig, type CrossFileDuplicateExport, type CrossFileDuplicateExportLocation, type DependencyDeclaredAs, type DeslopConfig, type DeslopError, type DeslopErrorCode, type DeslopErrorModule, type DeslopErrorSeverity, type DuplicateBlock, type DuplicateBlockCluster, type DuplicateBlockDetectionMode, type DuplicateBlockOccurrence, type DuplicateBlockRefactoringHint, type DuplicateBlockRefactoringKind, type DuplicateBlocksConfig, type DuplicateConstant, type DuplicateConstantOccurrence, type DuplicateExport, type DuplicateExportOccurrence, type DuplicateImport, type DuplicateImportOccurrence, type DuplicateInlineType, type DuplicateTypeDefinition, type DuplicateTypeDefinitionInstance, type FeatureFlag, type FeatureFlagKind, type FeatureFlagsConfig, type FunctionComplexity, type IdentityWrapper, type InlineTypeContext, type InlineTypeOccurrence, type LazyImportAtTopLevel, type LazyImportKind, type MisclassifiedDependency, type PrivateTypeLeak, type ReExportCycle, type ReExportCycleKind, type RedundantAlias, type RedundantAliasKind, type RedundantTypePattern, type RedundantTypePatternKind, type ScanResult, type SemanticConfidence, type SemanticConfig, type ShadowedDirectoryPair, type SimplifiableExpression, type SimplifiableExpressionKind, type SimplifiableFunction, type SimplifiableFunctionKind, type TypeScriptEscapeHatch, type TypeScriptEscapeHatchKind, type UnnecessaryAssertion, type UnnecessaryAssertionKind, type UnusedClassMember, type UnusedDependency, type UnusedEnumMember, type UnusedExport, type UnusedFile, type UnusedType, type UnusedTypeKind, analyze, defineConfig };
+export { type CircularDependency, type ClassMemberKind, type CommonjsInEsm, type CommonjsInEsmKind, type ComplexityConfig, type CrossFileDuplicateExport, type CrossFileDuplicateExportLocation, type DependencyDeclaredAs, type DeslopConfig, type DeslopError, type DeslopErrorCode, type DeslopErrorModule, type DeslopErrorSeverity, type DuplicateBlock, type DuplicateBlockCluster, type DuplicateBlockDetectionMode, type DuplicateBlockOccurrence, type DuplicateBlockRefactoringHint, type DuplicateBlockRefactoringKind, type DuplicateBlocksConfig, type DuplicateConstant, type DuplicateConstantOccurrence, type DuplicateExport, type DuplicateExportOccurrence, type DuplicateImport, type DuplicateImportOccurrence, type DuplicateInlineType, type DuplicateTypeDefinition, type DuplicateTypeDefinitionInstance, type FeatureFlag, type FeatureFlagKind, type FeatureFlagsConfig, type FunctionComplexity, type IdentityWrapper, type InlineTypeContext, type InlineTypeOccurrence, type LazyImportAtTopLevel, type LazyImportKind, type MisclassifiedDependency, type PrivateTypeLeak, type ReExportCycle, type ReExportCycleKind, type RedundantAlias, type RedundantAliasKind, type RedundantTypePattern, type RedundantTypePatternKind, type ScanResult, type SemanticConfidence, type SemanticConfig, type ShadowedDirectoryPair, type SimplifiableExpression, type SimplifiableExpressionKind, type SimplifiableFunction, type SimplifiableFunctionKind, type SkippedDependency, type SkippedDependencyReason, type TypeScriptEscapeHatch, type TypeScriptEscapeHatchKind, type UnnecessaryAssertion, type UnnecessaryAssertionKind, type UnusedClassMember, type UnusedDependency, type UnusedEnumMember, type UnusedExport, type UnusedFile, type UnusedType, type UnusedTypeKind, analyze, defineConfig };

package/dist/index.mjs

@@ -7953,7 +7953,10 @@ const detectStalePackages = (graph, config, summaryCache) => {
 		const content = readFileSync(packageJsonPath, "utf-8");
 		packageJson = JSON.parse(content);
 	} catch {
-		return [];
+		return {
+			unusedDependencies: [],
+			skippedDependencies: []
+		};
 	}
 	const dependencies = packageJson.dependencies ?? {};
 	const devDependencies = packageJson.devDependencies ?? {};
@@ -7961,7 +7964,12 @@ const detectStalePackages = (graph, config, summaryCache) => {
 	for (const dependencyName of Object.keys(dependencies)) declaredDependencies.set(dependencyName, false);
 	for (const dependencyName of Object.keys(devDependencies)) declaredDependencies.set(dependencyName, true);
 	const declaredNames = new Set(declaredDependencies.keys());
-	const usedPackageNames = collectUsedPackages(graph);
+	const observedPackageNames = collectUsedPackages(graph);
+	const usedPackageNames = new Set(observedPackageNames);
+	const markPackageUsed = (packageName) => {
+		observedPackageNames.add(packageName);
+		usedPackageNames.add(packageName);
+	};
 	const monorepoRoot = findMonorepoRoot(config.rootDir);
 	const nodeModulesSearchRoots = monorepoRoot && monorepoRoot !== config.rootDir ? [config.rootDir, monorepoRoot] : [config.rootDir];
 	const allPackageJsonPaths = discoverAllPackageJsonPaths(config.rootDir, summaryCache);
@@ -7973,29 +7981,29 @@ const detectStalePackages = (graph, config, summaryCache) => {
 	for (const packageName of packagesProvidingBinary) usedPackageNames.add(packageName);
 	for (const workspacePackageJsonPath of allPackageJsonPaths) {
 		const scriptReferenced = collectScriptReferencedPackages(workspacePackageJsonPath, declaredNames, binToPackage);
-		for (const packageName of scriptReferenced) usedPackageNames.add(packageName);
+		for (const packageName of scriptReferenced) markPackageUsed(packageName);
 		const packageJsonConfigReferenced = collectPackageJsonConfigReferences(workspacePackageJsonPath, declaredNames);
-		for (const packageName of packageJsonConfigReferenced) usedPackageNames.add(packageName);
+		for (const packageName of packageJsonConfigReferenced) markPackageUsed(packageName);
 	}
 	const nxProjectReferenced = collectNxProjectJsonReferences(config.rootDir, declaredNames, binToPackage, summaryCache);
-	for (const packageName of nxProjectReferenced) usedPackageNames.add(packageName);
+	for (const packageName of nxProjectReferenced) markPackageUsed(packageName);
 	const configSearchRoots = monorepoRoot && monorepoRoot !== config.rootDir ? [config.rootDir, monorepoRoot] : [config.rootDir];
 	for (const configSearchRoot of configSearchRoots) {
 		const configReferenced = collectConfigReferencedPackages(configSearchRoot, graph, declaredNames, summaryCache);
-		for (const packageName of configReferenced) usedPackageNames.add(packageName);
+		for (const packageName of configReferenced) markPackageUsed(packageName);
 		const tsconfigReferenced = collectTsconfigReferencedPackages(configSearchRoot, summaryCache);
-		for (const packageName of tsconfigReferenced) usedPackageNames.add(packageName);
+		for (const packageName of tsconfigReferenced) markPackageUsed(packageName);
 		const { packageNames: expoPluginPackageNames } = extractExpoConfigPluginEntries(configSearchRoot, {
 			...dependencies,
 			...devDependencies
 		});
-		for (const packageName of expoPluginPackageNames) if (declaredNames.has(packageName)) usedPackageNames.add(packageName);
+		for (const packageName of expoPluginPackageNames) if (declaredNames.has(packageName)) markPackageUsed(packageName);
 	}
 	if (hasJsxFiles(graph)) {
-		if (declaredNames.has("react")) usedPackageNames.add("react");
-		if (declaredNames.has("react-dom")) usedPackageNames.add("react-dom");
-		if (declaredNames.has("react-native")) usedPackageNames.add("react-native");
-		if (declaredNames.has("react-native-web")) usedPackageNames.add("react-native-web");
+		if (declaredNames.has("react")) markPackageUsed("react");
+		if (declaredNames.has("react-dom")) markPackageUsed("react-dom");
+		if (declaredNames.has("react-native")) markPackageUsed("react-native");
+		if (declaredNames.has("react-native-web")) markPackageUsed("react-native-web");
 	}
 	if (declaredNames.has("react-dom")) {
 		if ([
@@ -8010,26 +8018,37 @@ const detectStalePackages = (graph, config, summaryCache) => {
 			"@tanstack/react-router",
 			"@tanstack/react-start",
 			"react-app-rewired"
-		].some((framework) => declaredNames.has(framework) || usedPackageNames.has(framework))) usedPackageNames.add("react-dom");
+		].some((framework) => declaredNames.has(framework) || usedPackageNames.has(framework))) markPackageUsed("react-dom");
 	}
-	if (declaredNames.has("astro") && declaredNames.has("sharp")) usedPackageNames.add("sharp");
+	if (declaredNames.has("astro") && declaredNames.has("sharp")) markPackageUsed("sharp");
 	if (declaredNames.has("react") && declaredNames.has("react-dom")) {
 		const packageJsonPath = resolve(config.rootDir, "package.json");
 		try {
 			const content = readFileSync(packageJsonPath, "utf-8");
 			const peerDeps = JSON.parse(content).peerDependencies ?? {};
-			if ("react" in peerDeps && declaredDependencies.get("react") === true) usedPackageNames.add("react");
-			if ("react-dom" in peerDeps && declaredDependencies.get("react-dom") === true) usedPackageNames.add("react-dom");
+			if ("react" in peerDeps && declaredDependencies.get("react") === true) markPackageUsed("react");
+			if ("react-dom" in peerDeps && declaredDependencies.get("react-dom") === true) markPackageUsed("react-dom");
 		} catch {}
 	}
 	const peerSatisfied = collectPeerSatisfiedPackages(nodeModulesSearchRoots, declaredNames, usedPackageNames);
 	for (const packageName of peerSatisfied) usedPackageNames.add(packageName);
 	const overrideMappings = collectOverrideMappings(configSearchRoots, allPackageJsonPaths, monorepoRoot);
 	for (const { fromPackage, toPackage } of overrideMappings) {
-		if (declaredNames.has(toPackage)) usedPackageNames.add(toPackage);
-		if (usedPackageNames.has(fromPackage) && declaredNames.has(toPackage)) usedPackageNames.add(toPackage);
+		if (declaredNames.has(toPackage)) markPackageUsed(toPackage);
+		if (usedPackageNames.has(fromPackage) && declaredNames.has(toPackage)) markPackageUsed(toPackage);
 	}
 	const candidateUnused = /* @__PURE__ */ new Set();
+	const skippedDependenciesByName = /* @__PURE__ */ new Map();
+	const recordSkippedDependency = (dependencyName, reason) => {
+		const reasons = skippedDependenciesByName.get(dependencyName) ?? /* @__PURE__ */ new Set();
+		reasons.add(reason);
+		skippedDependenciesByName.set(dependencyName, reasons);
+	};
+	for (const [dependencyName] of declaredDependencies) {
+		if (observedPackageNames.has(dependencyName) || peerSatisfied.has(dependencyName)) continue;
+		if (isAlwaysConsideredUsed(dependencyName)) recordSkippedDependency(dependencyName, "allowlisted-name");
+		if (packagesProvidingBinary.has(dependencyName)) recordSkippedDependency(dependencyName, "provides-binary");
+	}
 	for (const [dependencyName] of declaredDependencies) {
 		if (isAlwaysConsideredUsed(dependencyName)) continue;
 		if (usedPackageNames.has(dependencyName)) continue;
@@ -8038,7 +8057,7 @@ const detectStalePackages = (graph, config, summaryCache) => {
 	if (candidateUnused.size > 0) {
 		const sourceFileRescued = scanSourceFilesForPackageImports(config.rootDir, candidateUnused, summaryCache);
 		for (const packageName of sourceFileRescued) {
-			usedPackageNames.add(packageName);
+			markPackageUsed(packageName);
 			candidateUnused.delete(packageName);
 		}
 	}
@@ -8052,7 +8071,14 @@ const detectStalePackages = (graph, config, summaryCache) => {
 			reason: `"${dependencyName}" is declared in ${dependencySection} but is never imported or referenced by any source file, script, or config — remove it from package.json if it is genuinely unused`
 		});
 	}
-	return unusedDependencies;
+	return {
+		unusedDependencies,
+		skippedDependencies: [...skippedDependenciesByName.entries()].sort(([leftName], [rightName]) => leftName.localeCompare(rightName)).map(([name, reasons]) => ({
+			name,
+			isDevDependency: declaredDependencies.get(name) ?? false,
+			reasons: [...reasons].sort()
+		}))
+	};
 };
 const collectUsedPackages = (graph) => {
 	const usedPackages = /* @__PURE__ */ new Set();
@@ -12444,7 +12470,11 @@ const generateReport = (graph, config, summaryCache) => {
 	}
 	const unusedFiles = safeReportDetector("detectOrphanFiles", () => detectOrphanFiles(graph), [], errorSink);
 	const unusedExports = safeReportDetector("detectDeadExports", () => detectDeadExports(graph, config), [], errorSink);
-	const unusedDependencies = safeReportDetector("detectStalePackages", () => detectStalePackages(graph, config, summaryCache), [], errorSink);
+	const stalePackageReport = safeReportDetector("detectStalePackages", () => detectStalePackages(graph, config, summaryCache), {
+		unusedDependencies: [],
+		skippedDependencies: []
+	}, errorSink);
+	const unusedDependencies = stalePackageReport.unusedDependencies;
 	const circularDependencies = safeReportDetector("detectCycles", () => detectCycles(graph), [], errorSink);
 	const syntacticRedundantAliases = config.reportRedundancy ? [...safeReportDetector("detectRedundantAliases", () => detectRedundantAliases(graph), [], errorSink), ...safeReportDetector("detectUselessAliasedReExports", () => detectUselessAliasedReExports(graph), [], errorSink)] : [];
 	const duplicateExports = config.reportRedundancy ? safeReportDetector("detectDuplicateExports", () => detectDuplicateExports(graph), [], errorSink) : [];
@@ -12503,6 +12533,7 @@ const generateReport = (graph, config, summaryCache) => {
 		unusedFiles,
 		unusedExports,
 		unusedDependencies,
+		skippedDependencies: stalePackageReport.skippedDependencies,
 		circularDependencies,
 		unusedTypes: semanticResult.unusedTypes,
 		misclassifiedDependencies: semanticResult.misclassifiedDependencies,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deslop-js",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "description": "Remove AI slop from JavaScript code.",
   "keywords": [
     "dead-code",