refactor(scanner/extractors): simplify APIs & add fast probes with callbacks

.changeset/afraid-cows-eat.md

@@ -0,0 +1,5 @@
+---
+"@nodesecure/scanner": minor
+---
+
+Simplify extractors name & add way to inject fast probes with callbacks"

workspaces/scanner/docs/extractors.md

@@ -14,7 +14,7 @@ const payload = await from("fastify");
 const extractor = new Extractors.Payload(
   payload,
   [
-    new Extractors.Probes.ContactExtractor()
+    new Extractors.Probes.Contacts()
   ]
 );
 
@@ -31,12 +31,12 @@ Available probes include:
 
 | name | level |
 | --- | --- |
-| ContactExtractor | manifest |
-| LicensesExtractor | manifest |
-| SizeExtractor | manifest |
-| FlagsExtractor | manifest |
-| VulnerabilitiesExtractor | packument |
-| WarningsExtractor | manifest |
+| Contacts | manifest |
+| Licenses | manifest |
+| Size | manifest |
+| Flags | manifest |
+| Vulnerabilities | packument |
+| Warnings | manifest |
 
 All probes follow the same `ProbeExtractor` interface, which acts as an iterator-like contract:
 
@@ -133,4 +133,4 @@ extractor.on('manifest', (
 ) => {
   // Handle manifest-level processing
 });
-```
+```

workspaces/scanner/src/extractors/index.ts

@@ -1,20 +1,26 @@
 // Import Internal Dependencies
 import {
   Payload,
+  Callbacks,
   type ProbeExtractor,
   type PackumentProbeExtractor,
-  type ManifestProbeExtractor
+  type ManifestProbeExtractor,
+  type PackumentProbeNextCallback,
+  type ManifestProbeNextCallback
 } from "./payload.js";
 
 import * as Probes from "./probes/index.js";
 
 export const Extractors = {
   Payload,
+  Callbacks,
   Probes
 } as const;
 
 export type {
   ProbeExtractor,
   PackumentProbeExtractor,
-  ManifestProbeExtractor
+  ManifestProbeExtractor,
+  PackumentProbeNextCallback,
+  ManifestProbeNextCallback
 };

workspaces/scanner/src/extractors/payload.ts

@@ -31,6 +31,12 @@ export type ProbeExtractorManifestParent = {
   dependency: Scanner.Dependency;
 };
 
+export type PackumentProbeNextCallback = (name: string, dependency: Scanner.Dependency) => void;
+export type ManifestProbeNextCallback = (
+  spec: string,
+  dependencyVersion: Scanner.DependencyVersion,
+  parent: ProbeExtractorManifestParent) => void;
+
 export interface ProbeExtractor<Defs> {
   level: ProbeExtractorLevel;
   next(...args: any[]): void;
@@ -39,16 +45,12 @@ export interface ProbeExtractor<Defs> {
 
 export interface PackumentProbeExtractor<Defs> extends ProbeExtractor<Defs> {
   level: "packument";
-  next(name: string, dependency: Scanner.Dependency): void;
+  next: PackumentProbeNextCallback;
 }
 
 export interface ManifestProbeExtractor<Defs> extends ProbeExtractor<Defs> {
   level: "manifest";
-  next(
-    spec: string,
-    dependencyVersion: Scanner.DependencyVersion,
-    parent: ProbeExtractorManifestParent
-  ): void;
+  next: ManifestProbeNextCallback;
 }
 
 export class Payload<T extends ProbeExtractor<any>[]> extends EventEmitter {
@@ -102,3 +104,28 @@ export class Payload<T extends ProbeExtractor<any>[]> extends EventEmitter {
     ) as unknown as MergedExtractProbeResult<T>;
   }
 }
+
+export const Callbacks = {
+  packument(
+    callback: PackumentProbeNextCallback
+  ): PackumentProbeExtractor<void> {
+    return {
+      level: "packument" as const,
+      next: callback,
+      done: noop
+    };
+  },
+  manifest(
+    callback: ManifestProbeNextCallback
+  ): ManifestProbeExtractor<void> {
+    return {
+      level: "manifest" as const,
+      next: callback,
+      done: noop
+    };
+  }
+} as const;
+
+function noop() {
+  return void 0;
+}

workspaces/scanner/src/extractors/probes/ContactExtractor.class.ts

@@ -8,14 +8,14 @@ import type {
 } from "../payload.js";
 import type { DependencyVersion } from "../../types.js";
 
-export type ContactExtractorResult = {
+export type ContactsResult = {
   contacts: Record<string, number>;
 };
 
-export class ContactExtractor implements ManifestProbeExtractor<ContactExtractorResult> {
+export class Contacts implements ManifestProbeExtractor<ContactsResult> {
   level = "manifest" as const;
 
-  #contacts: ContactExtractorResult["contacts"] = Object.create(null);
+  #contacts: ContactsResult["contacts"] = Object.create(null);
   #packages: Set<string> = new Set();
 
   #addContact(

workspaces/scanner/src/extractors/probes/FlagsExtractor.class.ts

@@ -7,11 +7,11 @@ import type {
 } from "../payload.js";
 import type { DependencyVersion } from "../../types.js";
 
-export type FlagsExtractorResult = {
+export type FlagsResult = {
   flags: Record<string, number>;
 };
 
-export class FlagsExtractor implements ManifestProbeExtractor<FlagsExtractorResult> {
+export class Flags implements ManifestProbeExtractor<FlagsResult> {
   level = "manifest" as const;
 
   #flags = new FrequencySet();

workspaces/scanner/src/extractors/probes/LicensesExtractor.class.ts

@@ -4,14 +4,14 @@ import type {
 } from "../payload.js";
 import type { DependencyVersion } from "../../types.js";
 
-export type LicensesExtractorResult = {
+export type LicensesResult = {
   licenses: Record<string, number>;
 };
 
-export class LicensesExtractor implements ManifestProbeExtractor<LicensesExtractorResult> {
+export class Licenses implements ManifestProbeExtractor<LicensesResult> {
   level = "manifest" as const;
 
-  #licenses: LicensesExtractorResult["licenses"] = Object.create(null);
+  #licenses: LicensesResult["licenses"] = Object.create(null);
 
   next(
     _: string,

workspaces/scanner/src/extractors/probes/SizeExtractor.class.ts

@@ -8,19 +8,19 @@ import type {
 } from "../payload.js";
 import type { DependencyVersion } from "../../types.js";
 
-export type SizeExtractorResult = {
+export type SizeResult = {
   size: {
     all: string;
     internal: string;
     external: string;
   };
 };
 
-export interface SizeExtractorOptions {
+export interface SizeOptions {
   organizationPrefix?: string;
 }
 
-export class SizeExtractor implements ManifestProbeExtractor<SizeExtractorResult> {
+export class Size implements ManifestProbeExtractor<SizeResult> {
   level = "manifest" as const;
 
   #size = {
@@ -31,7 +31,7 @@ export class SizeExtractor implements ManifestProbeExtractor<SizeExtractorResult
   #organizationPrefix: string | null = null;
 
   constructor(
-    options: SizeExtractorOptions = {}
+    options: SizeOptions = {}
   ) {
     const { organizationPrefix = null } = options;
 

workspaces/scanner/src/extractors/probes/VulnerabilitiesExtractor.class.ts

@@ -7,11 +7,11 @@ import type {
 } from "../payload.js";
 import type { Dependency } from "../../types.js";
 
-export type VulnerabilitiesExtractorResult = {
+export type VulnerabilitiesResult = {
   vulnerabilities: StandardVulnerability[];
 };
 
-export class VulnerabilitiesExtractor implements PackumentProbeExtractor<VulnerabilitiesExtractorResult> {
+export class Vulnerabilities implements PackumentProbeExtractor<VulnerabilitiesResult> {
   level = "packument" as const;
 
   #vulnerabilities: StandardVulnerability[] = [];

workspaces/scanner/src/extractors/probes/WarningsExtractor.class.ts

@@ -13,22 +13,22 @@ import type {
 } from "../payload.js";
 import type { DependencyVersion } from "../../types.js";
 
-export type WarningsExtractorResult = {
+export type WarningsResult = {
   warnings: {
     count: number;
     groups: Record<string, Warning<WarningDefault>[]>;
     uniqueKinds: Record<WarningName, number>;
   };
 };
 
-export interface WarningsExtractorOptions {
+export interface WarningsOptions {
   /**
    * @default true
    */
   useSpecAsKey?: boolean;
 }
 
-export class WarningsExtractor implements ManifestProbeExtractor<WarningsExtractorResult> {
+export class Warnings implements ManifestProbeExtractor<WarningsResult> {
   level = "manifest" as const;
 
   #warnings: Record<string, Warning<WarningDefault>[]> = Object.create(null);
@@ -37,7 +37,7 @@ export class WarningsExtractor implements ManifestProbeExtractor<WarningsExtract
   #useSpecAsKey: boolean;
 
   constructor(
-    options: WarningsExtractorOptions = {}
+    options: WarningsOptions = {}
   ) {
     this.#useSpecAsKey = options.useSpecAsKey ?? true;
   }