chore: add debug for unknown purls (#91)

* chore: add warning for unknown purls

This commit adds a debug in cases where a generated sbom has a purl,
but the NES/XEOL database does not have any information.

This commit also improves typing in several ways that makes
it easier to trace why scan details might be missing in the first place:

- Use an actual Map when building scan results
- set ScanResultComponent.status to optional to match current api
- create ComponentStatus type union
- replace optional Line properties with defined properties where feasible

Author: edezekiel

.vscode/settings.json

@@ -1,4 +1,4 @@
 {
-  "cSpell.words": ["mycommand", "prerun"],
+  "cSpell.words": ["mycommand", "prerun", "XEOL"],
   "typescript.tsdk": "node_modules/typescript/lib"
 }

src/hooks/prerun/CommandContextHook.ts

@@ -3,9 +3,10 @@ import type { Hook } from '@oclif/core';
 import { initOclifLog, log } from '../../utils/log.util.ts';
 
 const hook: Hook<'prerun'> = async (opts) => {
-  initOclifLog(opts.context.log, opts.context.log);
+  initOclifLog(opts.context.log, opts.context.log, opts.context.debug);
   log.info = opts.context.log || log.info;
   log.warn = opts.context.log || log.warn;
+  log.debug = opts.context.debug || log.debug;
 };
 
 export default hook;

src/service/eol/eol.svc.ts

@@ -1,7 +1,7 @@
 import { log } from '../../utils/log.util.ts';
-import { daysBetween } from '../../utils/misc.ts';
+import { daysBetween } from '../line.ts';
 import type { Line } from '../line.ts';
-import type { ScanResult, ScanResultComponent } from '../nes/modules/sbom.ts';
+import type { ComponentStatus, ScanResult } from '../nes/modules/sbom.ts';
 import { NesApolloClient } from '../nes/nes.client.ts';
 import { createBomFromDir } from './cdx.svc.ts';
 import type { Sbom, SbomEntry, SbomMap as SbomModel, ScanOptions } from './eol.types.ts';
@@ -62,22 +62,30 @@ export async function submitScan(model: SbomModel): Promise<ScanResult> {
  * processing and/or rendering.
  */
 export async function prepareRows({ components, purls }: SbomModel, scan: ScanResult): Promise<Line[]> {
-  let lines = purls.map((purl) => {
+  let lines: Line[] = purls.map((purl) => {
     const { evidence } = components[purl];
     const occ = evidence?.occurrences?.map((o) => o.location).join('\n\t - ');
     const occurrences = SHOW_OCCURRENCES && Boolean(occ) ? `\t - ${occ}\n` : '';
 
-    const details = scan?.components[purl];
-    const info: ScanResultComponent['info'] = details?.info || {
-      eolAt: undefined,
-      isEol: false,
-      isUnsafe: false,
-    };
+    const details = scan.components.get(purl);
+
+    if (!details) {
+      // In this case, the purl string is in the generated sbom, but the NES/XEOL api has no data
+      log.debug(`Unknown status: ${purl}.`);
+    }
+
+    const info = details
+      ? details.info
+      : {
+          eolAt: null,
+          isEol: false,
+          isUnsafe: false,
+        };
 
     info.eolAt = typeof info.eolAt === 'string' && info.eolAt ? new Date(info.eolAt) : info.eolAt;
 
     const daysEol = info.eolAt ? daysBetween(new Date(), info.eolAt) : undefined;
-    let status: 'EOL' | 'LTS' | 'OK' = 'OK';
+    let status: ComponentStatus = 'OK';
 
     // TODO: extract this logic into the Line.ts file somehow, so that there is a unified Line model
     if (daysEol === undefined) {

src/service/eol/eol.types.ts

@@ -24,5 +24,3 @@ export interface ScanOptions {
   cdxgen?: CdxGenOptions;
 }
 export type CdxCreator = (dir: string, opts: CdxGenOptions) => Promise<{ bomJson: Sbom }>;
-
-export type SbomScan<T> = <SB>(sbom: SB) => Promise<T>;

src/service/line.ts

@@ -1,22 +1,22 @@
 import { ux } from '@oclif/core';
-import type { ScanResultComponent } from './nes/modules/sbom.ts';
+import type { ComponentStatus, ScanResultComponent } from './nes/modules/sbom.ts';
 
 export interface Line {
-  daysEol?: number;
+  daysEol: number | undefined;
   purl: ScanResultComponent['purl'];
-  info?: {
-    eolAt?: Date;
+  info: {
+    eolAt: Date | null;
     isEol: boolean;
   };
-  status: ScanResultComponent['status'];
+  status: ComponentStatus;
 }
 
 export function daysBetween(date1: Date, date2: Date) {
   const msPerDay = 1000 * 60 * 60 * 24 + 15; // milliseconds in a day plus 15 ms
   return Math.round((date2.getTime() - date1.getTime()) / msPerDay);
 }
 
-export function getMessageAndStatus(status: string, eolAt?: Date) {
+export function getMessageAndStatus(status: string, eolAt: Date | null) {
   let msg = '';
   let stat = '';
 
@@ -47,9 +47,7 @@ export function getMessageAndStatus(status: string, eolAt?: Date) {
 }
 
 export function formatLine(l: Line, idx: number, ctx: { longest: number; total: number }) {
-  let { info, purl, status } = l;
-
-  info = info || { eolAt: new Date(), isEol: false };
+  const { info, purl, status } = l;
 
   if (info.isEol && status !== 'EOL') {
     throw new Error(`isEol is true but status is not EOL: ${purl}`);

src/service/nes/modules/sbom.test.ts

@@ -1,7 +1,8 @@
 import { ok } from 'node:assert';
+import { describe, it } from 'node:test';
 
-import type { ApolloHelper } from '../nes.client';
-import { type ScanResult, SbomScanner as sbomScanner } from './sbom';
+import type { ApolloHelper } from '../nes.client.ts';
+import { type ScanResult, type ScanResultComponent, SbomScanner as sbomScanner } from './sbom.ts';
 
 describe('SBOM Scanner', () => {
   it('parses response and creates components record', async () => {
@@ -29,7 +30,7 @@ describe('SBOM Scanner', () => {
   });
 });
 
-const STATUS_OK = { isEol: false, isUnsafe: false };
+const STATUS_OK = { eolAt: null, isEol: false, isUnsafe: false };
 
 const DATE_MS = 1000 * 60 * 60 * 24;
 const STATUS_EOL = () => ({
@@ -38,29 +39,29 @@ const STATUS_EOL = () => ({
   isUnsafe: false,
 });
 
+const components = new Map<string, ScanResultComponent>();
+components.set('pkg:npm/[email protected]', {
+  info: STATUS_EOL(),
+  purl: 'pkg:npm/[email protected]',
+  status: 'EOL',
+});
+components.set('pkg:npm/[email protected]', {
+  info: STATUS_OK,
+  purl: 'pkg:npm/[email protected]',
+  status: 'OK',
+});
 const mocked = {
   success: {
     insights: {
       scan: {
         eol: {
-          components: {
-            'pkg:npm/[email protected]': {
-              info: STATUS_EOL(),
-              purl: 'pkg:npm/[email protected]',
-              status: 'EOL',
-            },
-            'pkg:npm/[email protected]': {
-              info: STATUS_OK,
-              purl: 'pkg:npm/[email protected]',
-              status: 'OK',
-            },
-          },
+          components,
           diagnostics: {
             __mock: true,
           },
           message: 'Your scan was completed successfully!',
           success: true,
-        } as ScanResult,
+        } satisfies ScanResult,
       },
     },
   },

src/service/nes/modules/sbom.ts

@@ -4,11 +4,17 @@ import { log } from '../../../utils/log.util.ts';
 import type { SbomMap } from '../../eol/eol.types.ts';
 import type { ApolloHelper } from '../nes.client.ts';
 
-export const buildScanResult = (scan: ScanResponseReport): ScanResult => ({
-  components: Object.fromEntries(scan.components.map((c) => [c.purl, c])),
-  message: scan.message,
-  success: true,
-});
+export const buildScanResult = (scan: ScanResponseReport): ScanResult => {
+  const components = new Map<string, ScanResultComponent>();
+  for (const c of scan.components) {
+    components.set(c.purl, c);
+  }
+  return {
+    components,
+    message: scan.message,
+    success: true,
+  };
+};
 
 export const SbomScanner =
   (client: ApolloHelper) =>
@@ -25,11 +31,7 @@ export const SbomScanner =
     }
 
     const result = buildScanResult(scan);
-    // const result: ScanResult = {
-    //   components: Object.fromEntries(scan.components.map((c) => [c.purl, c])),
-    //   message: scan.message,
-    //   success: true
-    // }
+
     return result;
   };
 
@@ -50,19 +52,22 @@ export interface ScanResponseReport {
   success: boolean;
 }
 export interface ScanResult {
-  components: Record<string, ScanResultComponent>;
+  components: Map<string, ScanResultComponent>;
   diagnostics?: Record<string, unknown>;
   message: string;
   success: boolean;
 }
+
+export type ComponentStatus = 'EOL' | 'LTS' | 'OK';
+
 export interface ScanResultComponent {
-  info?: {
-    eolAt?: Date;
+  info: {
+    eolAt: Date | null;
     isEol: boolean;
     isUnsafe: boolean;
   };
   purl: string;
-  status: 'EOL' | 'LTS' | 'OK';
+  status?: ComponentStatus;
 }
 
 const M_SCAN = {

src/utils/log.util.ts

@@ -9,12 +9,17 @@ export const log = {
   warn: (_message?: unknown, ...args: unknown[]) => {
     console.warn('[default_warn]', ...args);
   },
+  debug: (_message?: unknown, ...args: unknown[]) => {
+    console.debug('[default_debug]', ...args);
+  },
 };
 
 export const initOclifLog = (
   info: (message?: unknown, ...args: unknown[]) => void,
   warn: (message?: unknown, ...args: unknown[]) => void,
+  debug: (message?: unknown, ...args: unknown[]) => void,
 ) => {
   log.info = info;
   log.warn = warn;
+  log.debug = debug;
 };

src/utils/misc.ts

@@ -34,18 +34,18 @@ describe('line', () => {
     });
 
     it('should format OK status', () => {
-      const { stat, msg } = getMessageAndStatus('OK');
+      const { stat, msg } = getMessageAndStatus('OK', null);
       assert(stat.includes('OK'));
       assert.equal(msg, '');
     });
 
     it('should handle missing eolAt date', () => {
-      const { msg } = getMessageAndStatus('EOL');
-      assert(msg.includes('unknown') && msg.includes('days ago'));
+      const { msg } = getMessageAndStatus('EOL', null);
+      assert(msg.includes("EOL'd") && msg.includes('unknown') && msg.includes('days ago'));
     });
 
     it('should throw on unknown status', () => {
-      assert.throws(() => getMessageAndStatus('INVALID'), /Unknown status: INVALID/);
+      assert.throws(() => getMessageAndStatus('INVALID', null), /Unknown status: INVALID/);
     });
   });
 
@@ -56,6 +56,7 @@ describe('line', () => {
       const line: Line = {
         purl: 'pkg:npm/[email protected]',
         status: 'EOL',
+        daysEol: 30,
         info: { isEol: true, eolAt: new Date() },
       };
       const result = formatLine(line, 0, context);
@@ -69,7 +70,8 @@ describe('line', () => {
       const line: Line = {
         purl: 'pkg:npm/[email protected]',
         status: 'OK',
-        info: { isEol: true },
+        daysEol: undefined,
+        info: { isEol: true, eolAt: null },
       };
       assert.throws(() => formatLine(line, 0, context), /isEol is true but status is not EOL/);
     });
@@ -78,6 +80,8 @@ describe('line', () => {
       const line: Line = {
         purl: 'pkg:npm/[email protected]',
         status: 'OK',
+        daysEol: undefined,
+        info: { isEol: false, eolAt: null },
       };
       const result = formatLine(line, 0, context);
       assert(result.name.includes('OK'));