feat: allow users to save purls in csv format (#102)

* feat: allow purls to be outputted in csv format

* fix: ensure only sbom flags are passed to command

Previously, all flags from the 'parent' commands were getting
passed to the sbom commands. This threw an error if the parent
command, e.g. 'report purls', has a command that doesn't exist
in the sbom command.

* feat: improve csv output formatting

* chore: add purls.svc tests

Author: edezekiel

.gitignore

@@ -7,9 +7,10 @@
 node_modules
 oclif.manifest.json
 
-
-
 yarn.lock
 pnpm-lock.yaml
 
-**/tsconfig.tsbuildinfo
+**/tsconfig.tsbuildinfo
+
+# cli-generated files
+nes.**.**

README.md

@@ -383,15 +383,14 @@ Generate a list of purls from a sbom
 
 ```
 USAGE
-  $ hd report purls [--json] [-f <value>] [-d <value>] [-s]
+  $ hd report purls [-f <value>] [-d <value>] [-s] [-o json|csv]
 
 FLAGS
-  -d, --dir=<value>   The directory to scan in order to create a cyclonedx sbom
-  -f, --file=<value>  The file path of an existing cyclonedx sbom to scan for EOL
-  -s, --save          Save the list of purls as nes.purls.json
-
-GLOBAL FLAGS
-  --json  Format output as json.
+  -d, --dir=<value>      The directory to scan in order to create a cyclonedx sbom
+  -f, --file=<value>     The file path of an existing cyclonedx sbom to scan for EOL
+  -o, --output=<option>  [default: json] The output format of the list of purls
+                         <options: json|csv>
+  -s, --save             Save the list of purls as nes.purls.<output>
 
 DESCRIPTION
   Generate a list of purls from a sbom
@@ -402,6 +401,8 @@ EXAMPLES
   $ hd report purls --file=path/to/sbom.json
 
   $ hd report purls --dir=./my-project --save
+
+  $ hd report purls --dir=./my-project --save --output=csv
 ```
 
 _See code: [src/commands/report/purls.ts](https://github.com/herodevs/cli/blob/v2.0.0/src/commands/report/purls.ts)_

package.json

@@ -11,6 +11,8 @@
     "build": "shx rm -rf dist && tsc -b",
     "ci": "biome ci",
     "ci:fix": "biome check --write",
+    "clean": "shx rm -rf dist && npm run clean:files && shx rm -rf node_modules",
+    "clean:files": "shx rm -f nes.purls.csv nes.purls.json nes.sbom.json",
     "dev": "npm run build && ./bin/dev.js",
     "format": "biome format --write",
     "lint": "biome lint --write",

src/commands/report/purls.ts

@@ -2,7 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { Command, Flags, ux } from '@oclif/core';
 
-import { type Sbom, extractPurls } from '../../service/eol/eol.svc.ts';
+import type { Sbom } from '../../service/eol/eol.svc.ts';
+import { extractPurls, getPurlOutput } from '../../service/purls.svc.ts';
 import SbomScan from '../scan/sbom.ts';
 
 export default class ReportPurls extends Command {
@@ -12,6 +13,7 @@ export default class ReportPurls extends Command {
     '<%= config.bin %> <%= command.id %> --dir=./my-project',
     '<%= config.bin %> <%= command.id %> --file=path/to/sbom.json',
     '<%= config.bin %> <%= command.id %> --dir=./my-project --save',
+    '<%= config.bin %> <%= command.id %> --save --output=csv',
   ];
   static override flags = {
     file: Flags.string({
@@ -25,16 +27,23 @@ export default class ReportPurls extends Command {
     save: Flags.boolean({
       char: 's',
       default: false,
-      description: 'Save the list of purls as nes.purls.json',
+      description: 'Save the list of purls as nes.purls.<output>',
+    }),
+    output: Flags.string({
+      char: 'o',
+      options: ['json', 'csv'],
+      default: 'json',
+      description: 'The format of the saved file (when using --save)',
     }),
   };
 
   public async run(): Promise<string[]> {
     const { flags } = await this.parse(ReportPurls);
-    const { dir: _dirFlag, file: _fileFlag, save } = flags;
+    const { dir: _dirFlag, file: _fileFlag, save, output } = flags;
 
-    // Load the SBOM
-    const sbomCommand = new SbomScan(this.argv, this.config);
+    // Load the SBOM: Only pass the file, dir, and save flags to SbomScan
+    const sbomArgs = SbomScan.getSbomArgs(flags);
+    const sbomCommand = new SbomScan(sbomArgs, this.config);
     const sbom: Sbom = await sbomCommand.run();
 
     // Extract purls from SBOM
@@ -50,9 +59,11 @@ export default class ReportPurls extends Command {
 
     // Save if requested
     if (save) {
-      const outputPath = path.join(_dirFlag || process.cwd(), 'nes.purls.json');
       try {
-        fs.writeFileSync(outputPath, JSON.stringify(purls, null, 2));
+        const outputPath = path.join(_dirFlag || process.cwd(), `nes.purls.${output}`);
+        const purlOutput = getPurlOutput(purls, output);
+        fs.writeFileSync(outputPath, purlOutput);
+
         this.log(`\nPurls saved to ${outputPath}`);
       } catch (error: unknown) {
         const errorMessage = error && typeof error === 'object' && 'message' in error ? error.message : 'Unknown error';

src/commands/scan/eol.ts

@@ -32,8 +32,9 @@ export default class ScanEol extends Command {
     const { flags } = await this.parse(ScanEol);
     const { dir: _dirFlag, file: _fileFlag } = flags;
 
-    // Load the SBOM
-    const sbomCommand = new SbomScan(this.argv, this.config);
+    // Load the SBOM: Only pass the file, dir, and save flags to SbomScan
+    const sbomArgs = SbomScan.getSbomArgs(flags);
+    const sbomCommand = new SbomScan(sbomArgs, this.config);
     const sbom: Sbom = await sbomCommand.run();
 
     // Scan the SBOM for EOL information

src/commands/scan/sbom.ts

@@ -27,6 +27,18 @@ export default class ScanSbom extends Command {
     }),
   };
 
+  static getSbomArgs(flags: Record<string, string>): string[] {
+    const { dir, file, save } = flags ?? {};
+
+    const sbomArgs = [];
+
+    if (file) sbomArgs.push('--file', file);
+    if (dir) sbomArgs.push('--dir', dir);
+    if (save) sbomArgs.push('--save');
+
+    return sbomArgs;
+  }
+
   getScanOptions() {
     // intentionally provided for mocking
     return {};

src/service/eol/eol.svc.ts

@@ -3,6 +3,7 @@ import { getDaysEolFromEolAt, getStatusFromComponent } from '../line.ts';
 import type { Line } from '../line.ts';
 import type { ComponentStatus, ScanResult } from '../nes/modules/sbom.ts';
 import { NesApolloClient } from '../nes/nes.client.ts';
+import { extractPurls } from '../purls.svc.ts';
 import { createBomFromDir } from './cdx.svc.ts';
 import type { Sbom, ScanOptions } from './eol.types.ts';
 
@@ -43,14 +44,6 @@ export async function scanForEol(sbom: Sbom) {
   return { purls, scan };
 }
 
-/**
- * Translate an SBOM to a list of purls for api request.
- */
-export async function extractPurls(sbom: Sbom): Promise<string[]> {
-  const { components: comps } = sbom;
-  return comps.map((c) => c.purl) ?? [];
-}
-
 /**
  * Uses the purls from the sbom to run the scan.
  */

src/service/purls.svc.ts

@@ -0,0 +1,33 @@
+import type { Sbom } from './eol/eol.types.ts';
+
+/**
+ * Formats a value for CSV output by wrapping it in quotes if it contains commas.
+ * This ensures that values containing commas aren't split into multiple columns
+ * when the CSV is opened in a spreadsheet application.
+ */
+export function formatCsvValue(value: string): string {
+  // If the value contains a comma, wrap it in quotes to preserve it as a single cell
+  return value.includes(',') ? `"${value}"` : value;
+}
+
+/**
+ * Converts an array of PURLs into either CSV or JSON format.
+ * For CSV output, adds a header row with "purl" and formats values to preserve commas.
+ * For JSON output, returns a properly indented JSON string.
+ */
+export function getPurlOutput(purls: string[], output: string): string {
+  switch (output) {
+    case 'csv':
+      return ['purl', ...purls].map(formatCsvValue).join('\n');
+    default:
+      return JSON.stringify(purls, null, 2);
+  }
+}
+
+/**
+ * Translate an SBOM to a list of purls for api request.
+ */
+export async function extractPurls(sbom: Sbom): Promise<string[]> {
+  const { components: comps } = sbom;
+  return comps.map((c) => c.purl) ?? [];
+}

test/commands/scan/eol.test.ts

@@ -5,11 +5,11 @@ import { afterEach, beforeEach, describe, it } from 'node:test';
 import { runCommand } from '@oclif/test';
 import * as sinon from 'sinon';
 
-import { default as EolScan } from '../../../src/commands/scan/eol.ts';
 import { default as SbomScan } from '../../../src/commands/scan/sbom.ts';
-import { type Sbom, cdxgen, extractPurls, prepareRows } from '../../../src/service/eol/eol.svc.ts';
+import { type Sbom, cdxgen, prepareRows } from '../../../src/service/eol/eol.svc.ts';
 import type { CdxCreator } from '../../../src/service/eol/eol.types.ts';
 import { type ScanResponseReport, type ScanResult, buildScanResult } from '../../../src/service/nes/modules/sbom.ts';
+import { extractPurls } from '../../../src/service/purls.svc.ts';
 import { FetchMock } from '../../utils/mocks/fetch.mock.ts';
 import { InquirerMock } from '../../utils/mocks/ui.mock.ts';
 

test/service/line.test.ts

@@ -108,7 +108,6 @@ describe('line', () => {
         status: 'EOL',
         daysEol: 30,
         info: { isEol: true, eolAt: new Date() },
-        evidence: '',
       };
       const result = formatLine(line, 0, context);
       assert(result.name.includes('['));
@@ -123,7 +122,6 @@ describe('line', () => {
         status: 'OK',
         daysEol: null,
         info: { isEol: false, eolAt: null },
-        evidence: '',
       };
       const result = formatLine(line, 0, context);
       assert(result.name.includes('OK'));
@@ -136,7 +134,6 @@ describe('line', () => {
         status: 'LTS',
         daysEol: 30,
         info: { isEol: false, eolAt: new Date() },
-        evidence: '',
       };
       const result = formatLine(line, 0, context);
       assert(result.name.includes('LTS'));

test/service/purls.svc.test.ts

@@ -0,0 +1,51 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { formatCsvValue, getPurlOutput } from '../../src/service/purls.svc.ts';
+
+describe('getPurlOutput', () => {
+  describe('json output', () => {
+    it('should format purls as JSON with proper indentation', () => {
+      const purls = ['pkg:npm/[email protected]', 'pkg:npm/[email protected]'];
+      const result = getPurlOutput(purls, 'json');
+      const expected = JSON.stringify(purls, null, 2);
+      assert.strictEqual(result, expected);
+    });
+
+    it('should handle empty array', () => {
+      const purls: string[] = [];
+      const result = getPurlOutput(purls, 'json');
+      assert.strictEqual(result, '[]');
+    });
+  });
+
+  describe('csv output', () => {
+    it('should format purls with header', () => {
+      const purls = ['pkg:npm/[email protected]', 'pkg:npm/[email protected]'];
+      const result = getPurlOutput(purls, 'csv');
+      const expected = 'purl\npkg:npm/[email protected]\npkg:npm/[email protected]';
+      assert.strictEqual(result, expected);
+    });
+
+    it('should handle empty array', () => {
+      const purls: string[] = [];
+      const result = getPurlOutput(purls, 'csv');
+      assert.strictEqual(result, 'purl');
+    });
+  });
+});
+
+describe('formatCsvValue', () => {
+  it('should return value unchanged when no commas present', () => {
+    const value = 'pkg:npm/[email protected]';
+    assert.strictEqual(formatCsvValue(value), value);
+  });
+
+  it('should wrap value in quotes when comma present', () => {
+    const value = 'pkg:npm/[email protected],beta';
+    assert.strictEqual(formatCsvValue(value), '"pkg:npm/[email protected],beta"');
+  });
+
+  it('should handle empty string', () => {
+    assert.strictEqual(formatCsvValue(''), '');
+  });
+});