feat(scan): add risk analysis

Author: zaldih

src/cli/cli.controller.ts

@@ -34,7 +34,7 @@ import colors from 'colors';
 import { homedir } from 'os';
 import path from 'path';
 import openExplorer from 'open-file-explorer';
-import { ScanOptions, Npkill } from '@core/index.js';
+import { ScanFoundFolder, Npkill } from '@core/index.js';
 import { LoggerService } from '@core/services/logger.service.js';
 import { ScanStatus } from '@core/interfaces/search-status.model.js';
 import { FileService } from '@core/services/files/files.service.js';
@@ -375,25 +375,27 @@ export class CliController {
 
     const params = this.prepareListDirParams();
     const { rootPath } = params;
-    const isExcludedDangerousDirectory = (path: string): boolean =>
-      this.config.excludeHiddenDirectories &&
-      this.fileService.isDangerous(path);
+    const isExcludedDangerousDirectory = (
+      scanResult: ScanFoundFolder,
+    ): boolean =>
+      Boolean(
+        this.config.excludeHiddenDirectories &&
+          scanResult.riskAnalysis?.isSensitive,
+      );
 
     this.searchStart = Date.now();
-    const results$ = this.npkill
-      .startScan$(rootPath, params)
-      .pipe(map((folder) => folder.path));
+    const results$ = this.npkill.startScan$(rootPath, params);
     const nonExcludedResults$ = results$.pipe(
       filter((path) => !isExcludedDangerousDirectory(path)),
     );
 
     nonExcludedResults$
       .pipe(
-        map<string, CliScanFoundFolder>((path) => ({
+        map<ScanFoundFolder, CliScanFoundFolder>(({ path, riskAnalysis }) => ({
           path,
           size: 0,
           modificationTime: -1,
-          isDangerous: this.fileService.isDangerous(path),
+          isDangerous: riskAnalysis?.isSensitive || false,
           status: 'live',
         })),
         tap((nodeFolder) => {

src/core/interfaces/file-service.interface.ts

@@ -1,5 +1,5 @@
 import { FileWorkerService } from '@core/services/files/files.worker.service.js';
-import { GetNewestFileResult } from '@core/interfaces';
+import { GetNewestFileResult, RiskAnalysis } from '@core/interfaces';
 import { ScanOptions } from './folder.interface.js';
 import { Observable } from 'rxjs';
 
@@ -15,7 +15,7 @@ export interface IFileService {
   convertGBToMB: (gb: number) => number;
   getFileContent: (path: string) => string;
   isSafeToDelete: (path: string, targetFolder: string) => boolean;
-  isDangerous: (path: string) => boolean;
+  isDangerous: (path: string) => RiskAnalysis;
   getRecentModificationInDir: (
     path: string,
   ) => Promise<GetNewestFileResult | null>;

src/core/interfaces/folder.interface.ts

@@ -1,13 +1,20 @@
 export type SizeUnit = 'bytes' | 'kb' | 'mb' | 'gb';
 
+export interface RiskAnalysis {
+  isSensitive: boolean;
+  reason?: string;
+}
+
 export interface ScanFoundFolder {
   path: string;
+  riskAnalysis?: RiskAnalysis;
 }
 
 export interface ScanOptions {
   target: string;
   exclude?: string[];
   sortBy?: 'path' | 'size' | 'last-mod';
+  performRiskAnalysis?: boolean; // Default: true
   // maxConcurrentScans?: number; // Need to implement this.
 }
 

src/core/npkill.ts

@@ -52,7 +52,19 @@ export class Npkill implements NpkillInterface {
       }),
       mergeMap((dataFolder) => from(splitData(dataFolder))),
       filter((path) => path !== ''),
-      map((path) => ({ path })),
+      map((path) => {
+        if (
+          options.performRiskAnalysis !== undefined &&
+          !options.performRiskAnalysis
+        ) {
+          return { path };
+        }
+        const riskAnalysis = fileService.isDangerous(path);
+        return {
+          path,
+          riskAnalysis,
+        };
+      }),
       tap((nodeFolder) =>
         this.logger.info(`Folder found: ${String(nodeFolder.path)}`),
       ),

src/core/services/files/files.service.ts

@@ -4,6 +4,7 @@ import {
   IFileService,
   IFileStat,
   GetNewestFileResult,
+  RiskAnalysis,
 } from '@core/index.js';
 import fs, { accessSync, readFileSync, Stats, statSync } from 'fs';
 import { readdir, stat } from 'fs/promises';
@@ -87,7 +88,7 @@ export abstract class FileService implements IFileService {
    * application-specific data or configurations that should not be tampered with. Deleting node_modules
    * from these locations could potentially disrupt the normal operation of these applications.
    */
-  isDangerous(originalPath: string): boolean {
+  isDangerous(originalPath: string): RiskAnalysis {
     const absolutePath = path.resolve(originalPath);
     const normalizedPath = absolutePath.replace(/\\/g, '/').toLowerCase();
 
@@ -104,31 +105,44 @@ export abstract class FileService implements IFileService {
 
     if (isInHome) {
       if (/\/\.config(\/|$)/.test(normalizedPath)) {
-        return true;
+        return {
+          isSensitive: true,
+          reason: 'Contains user configuration data (~/.config)',
+        };
       }
       if (/\/\.local\/share(\/|$)/.test(normalizedPath)) {
-        return true;
-      }
-      if (/\/\.(cache|npm|pnpm)(\/|$)/.test(normalizedPath)) {
-        return false;
+        return {
+          isSensitive: true,
+          reason: 'User data folder (~/.local/share)',
+        };
       }
+      if (/\/\.(cache|npm|pnpm)(\/|$)/.test(normalizedPath))
+        return { isSensitive: false };
     }
 
+    // macOs
     if (/\/applications\/[^/]+\.app\//.test(normalizedPath)) {
-      return true;
+      return { isSensitive: true, reason: 'Inside macOS .app package' };
     }
 
+    // Windows
     if (normalizedPath.includes('/appdata/roaming')) {
-      return true;
+      return {
+        isSensitive: true,
+        reason: 'Inside Windows AppData Roaming folder',
+      };
     }
     if (normalizedPath.includes('/appdata/local')) {
       if (/\/\.(cache|npm|pnpm)(\/|$)/.test(normalizedPath)) {
-        return false;
+        return { isSensitive: false };
       }
-      return true;
+      return {
+        isSensitive: true,
+        reason: 'Inside Windows AppData Local folder',
+      };
     }
     if (/program files( \(x86\))?\//.test(normalizedPath)) {
-      return true;
+      return { isSensitive: true, reason: 'Inside Program Files folder' };
     }
 
     const segments = normalizedPath.split('/');
@@ -141,10 +155,10 @@ export abstract class FileService implements IFileService {
     );
 
     if (hasUnsafeHiddenFolder) {
-      return true;
+      return { isSensitive: true, reason: 'Contains unsafe hidden folder' };
     }
 
-    return false;
+    return { isSensitive: false };
   }
 
   async getRecentModificationInDir(

tests/core/services/files/files.service.test.ts

@@ -167,28 +167,33 @@ describe('File Service', () => {
 
       test('safe relative path', () => {
         mockCwd('/safe/path');
-        expect(fileService.isDangerous('../project/node_modules')).toBe(false);
+        expect(
+          fileService.isDangerous('../project/node_modules').isSensitive,
+        ).toBe(false);
       });
 
       test('hidden relative path', () => {
         mockCwd('/home/user/projects');
-        expect(fileService.isDangerous('../.config/secret')).toBe(true);
+        expect(fileService.isDangerous('../.config/secret').isSensitive).toBe(
+          true,
+        );
       });
 
       test('node_modules in ~/.cache', () => {
         expect(
-          fileService.isDangerous('/home/user/.cache/project/node_modules'),
+          fileService.isDangerous('/home/user/.cache/project/node_modules')
+            .isSensitive,
         ).toBe(false);
       });
 
       test('parent relative path (..)', () => {
         mockCwd('/home/user');
-        expect(fileService.isDangerous('..')).toBe(false);
+        expect(fileService.isDangerous('..').isSensitive).toBe(false);
       });
 
       test('current relative path (.)', () => {
         mockCwd('/home/user');
-        expect(fileService.isDangerous('.')).toBe(false);
+        expect(fileService.isDangerous('.').isSensitive).toBe(false);
       });
     });
 
@@ -200,25 +205,29 @@ describe('File Service', () => {
 
       test('safe relative path', () => {
         mockCwd('D:\\safe\\path');
-        expect(fileService.isDangerous('..\\project\\node_modules')).toBe(
-          false,
-        );
+        expect(
+          fileService.isDangerous('..\\project\\node_modules').isSensitive,
+        ).toBe(false);
       });
 
       test('AppData relative path', () => {
         mockCwd('C:\\Users\\user\\Documents');
-        expect(fileService.isDangerous('..\\AppData\\Roaming\\app')).toBe(true);
+        expect(
+          fileService.isDangerous('..\\AppData\\Roaming\\app').isSensitive,
+        ).toBe(true);
       });
 
       test('Program Files (x86)', () => {
         expect(
-          fileService.isDangerous('C:\\Program Files (x86)\\app\\node_modules'),
+          fileService.isDangerous('C:\\Program Files (x86)\\app\\node_modules')
+            .isSensitive,
         ).toBe(true);
       });
 
       test('network paths', () => {
         expect(
-          fileService.isDangerous('\\\\network\\share\\.hidden\\node_modules'),
+          fileService.isDangerous('\\\\network\\share\\.hidden\\node_modules')
+            .isSensitive,
         ).toBe(true);
       });
     });
@@ -227,31 +236,33 @@ describe('File Service', () => {
       test('no home directory', () => {
         delete process.env.HOME;
         delete process.env.USERPROFILE;
-        expect(fileService.isDangerous('/some/path')).toBe(false);
+        expect(fileService.isDangerous('/some/path').isSensitive).toBe(false);
       });
 
       test('whitelisted hidden segments', () => {
         expect(
-          fileService.isDangerous('/tmp/.cache/project/node_modules'),
+          fileService.isDangerous('/tmp/.cache/project/node_modules')
+            .isSensitive,
+        ).toBe(false);
+        expect(
+          fileService.isDangerous('/tmp/.npm/project/node_modules').isSensitive,
         ).toBe(false);
-        expect(fileService.isDangerous('/tmp/.npm/project/node_modules')).toBe(
-          false,
-        );
       });
 
       test('macOS application bundle', () => {
         expect(
           fileService.isDangerous(
             '/Applications/MyApp.app/Contents/node_modules',
-          ),
+          ).isSensitive,
         ).toBe(true);
       });
 
       test('Windows-style path on POSIX', () => {
         process.env.HOME = '/home/user';
-        expect(fileService.isDangerous('/home/user/AppData/Local/.cache')).toBe(
-          false,
-        );
+        expect(
+          fileService.isDangerous('/home/user/AppData/Local/.cache')
+            .isSensitive,
+        ).toBe(false);
       });
     });
   });