@openreachtech/mentsu-npm-audit-gate 0.0.0-stage → 0.1.0

package/lib/AuditReportResponse.js

@@ -0,0 +1,343 @@
+/**
+ * Judge an `npm audit` report, deliberately letting through the advisories
+ * the caller lists, as a stopgap until a release fixes them.
+ *
+ * It fails on an advisory the list does not name, at any severity,
+ * on an advisory the list names that is no longer reported,
+ * and on an `npm audit` that answers with an error instead of a report.
+ */
+export default class AuditReportResponse {
+  /**
+   * @param {{
+   *   ignoredAdvisories: Array<NpmAuditType.IgnoredAdvisory>
+   *   report: AuditReport | null
+   * }} params - Parameters of this constructor.
+   */
+  constructor ({
+    ignoredAdvisories,
+    report,
+  }) {
+    this.ignoredAdvisories = ignoredAdvisories
+    this.report = report
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof AuditReportResponse ? X : never} T, X
+   * @param {{
+   *   ignoredAdvisories: Array<NpmAuditType.IgnoredAdvisory>
+   *   report: AuditReport | null
+   * }} params - Parameters for the factory method.
+   * @returns {InstanceType<T>} Instance of this class.
+   * @this {T}
+   * @public
+   */
+  static create ({
+    ignoredAdvisories,
+    report,
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        ignoredAdvisories,
+        report,
+      })
+    )
+  }
+
+  /**
+   * get: Name of the file listing the advisories to let through.
+   *
+   * @returns {string} File name.
+   */
+  static get ignoredAdvisoriesFileName () {
+    return 'IGNORED_ADVISORIES.js'
+  }
+
+  /**
+   * get: Pattern picking a GHSA id off the end of an advisory url.
+   *
+   * @returns {RegExp} Pattern with the named group `id`.
+   */
+  static get advisoryIdPattern () {
+    return /(?<id>GHSA(?:-[0-9a-z]{4}){3})$/u
+  }
+
+  /**
+   * Extract the GHSA id of an advisory.
+   *
+   * @param {{
+   *   advisory: AuditAdvisory
+   * }} params - Parameters.
+   * @returns {string} GHSA id, or the whole url where it carries none.
+   */
+  static extractAdvisoryId ({
+    advisory,
+  }) {
+    const matched = advisory.url.match(this.advisoryIdPattern)
+
+    return matched?.groups
+      ?.id
+      ?? advisory.url
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @returns {typeof AuditReportResponse} Constructor of this class.
+   */
+  get Ctor () {
+    return /** @type {typeof AuditReportResponse} */ (this.constructor)
+  }
+
+  /**
+   * Check whether the report can be judged.
+   *
+   * @returns {BooleanLike} Whether the report carries vulnerabilities and no error.
+   * @public
+   */
+  hasUsableReport () {
+    if (
+      !this.report
+      || this.report.error
+    ) {
+      return false
+    }
+
+    return this.report.vulnerabilities
+      ?? false
+  }
+
+  /**
+   * Build the line saying no report came back.
+   *
+   * @returns {string} Line to print.
+   * @public
+   */
+  buildNoReportMessage () {
+    const error = this.report?.error
+      ?? null
+
+    return `🤔 npm audit answered with no report, so nothing was checked: ${JSON.stringify(error)}`
+  }
+
+  /**
+   * Build the lines naming each listed advisory that is still reported.
+   *
+   * @returns {Array<string>} Lines to print.
+   * @public
+   */
+  buildIgnoredLines () {
+    return this.collectMetIgnores()
+      .flatMap(it => [
+        `⚠️ ignored: ${it.id} (${it.package}) via ${it.path}`,
+        `  reason: ${it.reason}`,
+        `  remove when: ${it.removeWhen}`,
+      ])
+  }
+
+  /**
+   * Collect the listed advisories that are still reported.
+   *
+   * @returns {Array<NpmAuditType.IgnoredAdvisory>} Advisories of the list.
+   */
+  collectMetIgnores () {
+    return this.ignoredAdvisories
+      .filter(it => this.isReported({
+        id: it.id,
+      }))
+  }
+
+  /**
+   * Check whether the report names an advisory.
+   *
+   * @param {{
+   *   id: string
+   * }} params - Parameters.
+   * @returns {BooleanLike} Whether the advisory is reported.
+   */
+  isReported ({
+    id,
+  }) {
+    return this.collectAdvisoryIds()
+      .includes(id)
+  }
+
+  /**
+   * Collect the ids of the advisories the report names, each once.
+   *
+   * @returns {Array<string>} GHSA ids in the order they first appear.
+   */
+  collectAdvisoryIds () {
+    const advisoryIds = this.collectAdvisories()
+      .map(it => this.Ctor.extractAdvisoryId({
+        advisory: it,
+      }))
+
+    return [
+      ...new Set(advisoryIds),
+    ]
+  }
+
+  /**
+   * Collect the advisories the report names, as often as it names them.
+   *
+   * @returns {Array<AuditAdvisory>} Advisories of the report.
+   */
+  collectAdvisories () {
+    const vulnerabilities = this.report?.vulnerabilities
+      ?? {}
+
+    return Object.values(vulnerabilities)
+      .flatMap(it => it.via)
+      .filter(it => typeof it === 'object')
+  }
+
+  /**
+   * Build the lines naming each failure.
+   *
+   * @returns {Array<string>} Lines to print.
+   * @public
+   */
+  buildFailureLines () {
+    return [
+      ...this.buildUnignoredLines(),
+      ...this.buildStaleLines(),
+    ]
+  }
+
+  /**
+   * Build the lines naming each reported advisory the list does not name.
+   *
+   * @returns {Array<string>} Lines to print.
+   */
+  buildUnignoredLines () {
+    return this.collectAdvisoryIds()
+      .filter(it => !this.isIgnored({
+        id: it,
+      }))
+      .map(it => this.buildUnignoredLine({
+        id: it,
+      }))
+  }
+
+  /**
+   * Check whether the list names an advisory.
+   *
+   * @param {{
+   *   id: string
+   * }} params - Parameters.
+   * @returns {BooleanLike} Whether the advisory is listed.
+   */
+  isIgnored ({
+    id,
+  }) {
+    return this.ignoredAdvisories
+      .some(it => it.id === id)
+  }
+
+  /**
+   * Build the line naming a reported advisory the list does not name.
+   *
+   * @param {{
+   *   id: string
+   * }} params - Parameters.
+   * @returns {string} Line to print.
+   */
+  buildUnignoredLine ({
+    id,
+  }) {
+    // The id comes from the report itself, so the advisory is always found.
+    const advisory = /** @type {AuditAdvisory} */ (
+      this.findAdvisory({
+        id,
+      })
+    )
+
+    return `🚨 not ignored: ${id} ${advisory.severity} ${advisory.name} ${advisory.range} — ${advisory.title}`
+  }
+
+  /**
+   * Find the advisory of an id, taking the last one the report names under it.
+   *
+   * @param {{
+   *   id: string
+   * }} params - Parameters.
+   * @returns {AuditAdvisory | null} Advisory, or null where the report names none.
+   */
+  findAdvisory ({
+    id,
+  }) {
+    return this.collectAdvisories()
+      .findLast(it => this.Ctor.extractAdvisoryId({
+        advisory: it,
+      }) === id)
+      ?? null
+  }
+
+  /**
+   * Build the lines naming each listed advisory that is no longer reported.
+   *
+   * @returns {Array<string>} Lines to print.
+   */
+  buildStaleLines () {
+    return this.ignoredAdvisories
+      .filter(it => !this.isReported({
+        id: it.id,
+      }))
+      .map(it => `🗑️ stale ignore: ${it.id} (${it.package}) is no longer reported; remove it from ${this.Ctor.ignoredAdvisoriesFileName}`)
+  }
+
+  /**
+   * Build the line summing up the check.
+   *
+   * @returns {string} Line to print.
+   * @public
+   */
+  buildSummaryLine () {
+    const advisoryCount = this.countAdvisories()
+    const metIgnoreCount = this.countMetIgnores()
+    const failureCount = this.countFailures()
+
+    return `checked ${advisoryCount} advisory(ies), ${metIgnoreCount} ignored, ${failureCount} failure(s)`
+  }
+
+  /**
+   * Count the advisories the report names, each once.
+   *
+   * @returns {number} Number of advisories.
+   */
+  countAdvisories () {
+    return this.collectAdvisoryIds().length
+  }
+
+  /**
+   * Count the listed advisories that are still reported.
+   *
+   * @returns {number} Number of advisories.
+   */
+  countMetIgnores () {
+    return this.collectMetIgnores().length
+  }
+
+  /**
+   * Count the failures.
+   *
+   * @returns {number} Number of failures.
+   * @public
+   */
+  countFailures () {
+    return this.buildFailureLines().length
+  }
+}
+
+/**
+ * @typedef {*} BooleanLike
+ */
+
+/**
+ * @import {
+ *   AuditAdvisory,
+ *   AuditReport,
+ * } from './AuditFetcher.js'
+ */

package/lib/EXIT_CODE.js

@@ -0,0 +1,14 @@
+/**
+ * Exit codes a process running `NpmAuditGate` ends with.
+ *
+ * @type {{
+ *   SUCCESS: number
+ *   FAILURE: number
+ * }}
+ */
+const EXIT_CODE = {
+  SUCCESS: 0,
+  FAILURE: 1,
+}
+
+export default EXIT_CODE

package/lib/IgnoredAdvisoriesLoader.js

@@ -0,0 +1,96 @@
+import nodeUrl from 'node:url'
+
+/**
+ * Load the advisories a repository lets through, from the file it keeps them in.
+ *
+ * The file is the only thing an instance holds, and its path is absolute.
+ */
+export default class IgnoredAdvisoriesLoader {
+  /**
+   * @param {{
+   *   ignoredAdvisoriesFilePath: string
+   * }} params - Parameters of this constructor.
+   */
+  constructor ({
+    ignoredAdvisoriesFilePath,
+  }) {
+    this.ignoredAdvisoriesFilePath = ignoredAdvisoriesFilePath
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof IgnoredAdvisoriesLoader ? X : never} T, X
+   * @param {{
+   *   ignoredAdvisoriesFilePath: string
+   * }} params - Parameters for the factory method.
+   * @returns {InstanceType<T>} Instance of this class.
+   * @this {T}
+   * @public
+   */
+  static create ({
+    ignoredAdvisoriesFilePath,
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        ignoredAdvisoriesFilePath,
+      })
+    )
+  }
+
+  /**
+   * get: `node:url` module.
+   *
+   * @returns {typeof nodeUrl} `node:url` module.
+   */
+  static get nodeUrl () {
+    return nodeUrl
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @returns {typeof IgnoredAdvisoriesLoader} Constructor of this class.
+   */
+  get Ctor () {
+    return /** @type {typeof IgnoredAdvisoriesLoader} */ (this.constructor)
+  }
+
+  /**
+   * Load the ignored advisories.
+   *
+   * @returns {Promise<Array<NpmAuditType.IgnoredAdvisory> | null>} Advisories, or null when the file cannot be loaded or its default export is not an array.
+   * @public
+   */
+  async loadAdvisories () {
+    try {
+      const url = this.Ctor.nodeUrl.pathToFileURL(this.ignoredAdvisoriesFilePath)
+
+      const exported = await this.invokeImport({
+        href: url.href,
+      })
+
+      if (!Array.isArray(exported.default)) {
+        return null
+      }
+
+      return exported.default
+    } catch (error) {
+      return null
+    }
+  }
+
+  /**
+   * Import a module by the href of its URL.
+   *
+   * @param {{
+   *   href: string
+   * }} params - Parameters.
+   * @returns {Promise<{ default?: * }>} Module namespace.
+   */
+  async invokeImport ({
+    href,
+  }) {
+    return import(href)
+  }
+}

package/lib/NpmAuditGate.js

@@ -0,0 +1,179 @@
+import AuditFetcher from './AuditFetcher.js'
+import AuditReportResponse from './AuditReportResponse.js'
+import EXIT_CODE from './EXIT_CODE.js'
+import ProcessLogger from './ProcessLogger.js'
+
+/**
+ * Fetch an `npm audit` report, judge it against the advisories
+ * the caller lists, and print the outcome.
+ */
+export default class NpmAuditGate {
+  /**
+   * @param {{
+   *   ignoredAdvisories: Array<NpmAuditType.IgnoredAdvisory>
+   *   auditFetcher: AuditFetcher
+   *   processLogger: ProcessLogger
+   * }} params - Parameters of this constructor.
+   */
+  constructor ({
+    ignoredAdvisories,
+    auditFetcher,
+    processLogger,
+  }) {
+    this.ignoredAdvisories = ignoredAdvisories
+    this.auditFetcher = auditFetcher
+    this.processLogger = processLogger
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof NpmAuditGate ? X : never} T, X
+   * @param {{
+   *   ignoredAdvisories: Array<NpmAuditType.IgnoredAdvisory>
+   *   auditFetcher?: AuditFetcher
+   *   processLogger?: ProcessLogger
+   * }} params - Parameters for the factory method.
+   * @returns {InstanceType<T>} Instance of this class.
+   * @this {T}
+   * @public
+   */
+  static create ({
+    ignoredAdvisories,
+    auditFetcher = this.createAuditFetcher(),
+    processLogger = this.createProcessLogger(),
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        ignoredAdvisories,
+        auditFetcher,
+        processLogger,
+      })
+    )
+  }
+
+  /**
+   * get: Constructor of `AuditFetcher`.
+   *
+   * @returns {typeof AuditFetcher} Constructor of `AuditFetcher`.
+   */
+  static get AuditFetcherCtor () {
+    return AuditFetcher
+  }
+
+  /**
+   * get: Constructor of `AuditReportResponse`.
+   *
+   * @returns {typeof AuditReportResponse} Constructor of `AuditReportResponse`.
+   */
+  static get AuditReportResponseCtor () {
+    return AuditReportResponse
+  }
+
+  /**
+   * get: Constructor of `ProcessLogger`.
+   *
+   * @returns {typeof ProcessLogger} Constructor of `ProcessLogger`.
+   */
+  static get ProcessLoggerCtor () {
+    return ProcessLogger
+  }
+
+  /**
+   * Create an `AuditFetcher`.
+   *
+   * @returns {AuditFetcher} Instance of `AuditFetcher`.
+   */
+  static createAuditFetcher () {
+    return this.AuditFetcherCtor.create()
+  }
+
+  /**
+   * Create an `AuditReportResponse`.
+   *
+   * @param {{
+   *   ignoredAdvisories: Array<NpmAuditType.IgnoredAdvisory>
+   *   report: AuditReport | null
+   * }} params - Parameters.
+   * @returns {AuditReportResponse} Instance of `AuditReportResponse`.
+   */
+  static createAuditReportResponse ({
+    ignoredAdvisories,
+    report,
+  }) {
+    return this.AuditReportResponseCtor.create({
+      ignoredAdvisories,
+      report,
+    })
+  }
+
+  /**
+   * Create a `ProcessLogger`.
+   *
+   * @returns {ProcessLogger} Instance of `ProcessLogger`.
+   */
+  static createProcessLogger () {
+    return this.ProcessLoggerCtor.create()
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @returns {typeof NpmAuditGate} Constructor of this class.
+   */
+  get Ctor () {
+    return /** @type {typeof NpmAuditGate} */ (this.constructor)
+  }
+
+  /**
+   * Fetch the report, judge it against the list, and print the outcome.
+   *
+   * @returns {number} Exit code: `EXIT_CODE.SUCCESS` when nothing fails, otherwise `EXIT_CODE.FAILURE`.
+   * @public
+   */
+  auditAdvisories () {
+    const report = this.auditFetcher.fetchReport()
+    const auditReportResponse = this.Ctor.createAuditReportResponse({
+      ignoredAdvisories: this.ignoredAdvisories,
+      report,
+    })
+
+    if (!auditReportResponse.hasUsableReport()) {
+      this.processLogger.logError({
+        text: `${auditReportResponse.buildNoReportMessage()}\n`,
+      })
+
+      return EXIT_CODE.FAILURE
+    }
+
+    auditReportResponse.buildIgnoredLines()
+      .forEach(it => {
+        this.processLogger.logMessage({
+          text: `${it}\n`,
+        })
+      })
+    auditReportResponse.buildFailureLines()
+      .forEach(it => {
+        this.processLogger.logError({
+          text: `${it}\n`,
+        })
+      })
+    this.processLogger.logMessage({
+      text: `${auditReportResponse.buildSummaryLine()}\n`,
+    })
+
+    return auditReportResponse.countFailures() === 0
+      ? EXIT_CODE.SUCCESS
+      : EXIT_CODE.FAILURE
+  }
+}
+
+/**
+ * @typedef {*} BooleanLike
+ */
+
+/**
+ * @import {
+ *   AuditReport,
+ * } from './AuditFetcher.js'
+ */

package/lib/ProcessArgumentsResolver.js

@@ -0,0 +1,67 @@
+/**
+ * Resolve the arguments the current process was started with.
+ */
+export default class ProcessArgumentsResolver {
+  /**
+   * @param {{
+   *   actualArguments: Array<string>
+   * }} params - Parameters of this constructor.
+   */
+  constructor ({
+    actualArguments,
+  }) {
+    this.actualArguments = actualArguments
+  }
+
+  /**
+   * Factory method.
+   *
+   * The actual arguments are those that follow the script, so the executable and the script are left out.
+   *
+   * @template {X extends typeof ProcessArgumentsResolver ? X : never} T, X
+   * @param {{
+   *   rawArguments: Array<string>
+   * }} params - Parameters for the factory method.
+   * @returns {InstanceType<T>} Instance of this class.
+   * @this {T}
+   * @public
+   */
+  static create ({
+    rawArguments,
+  }) {
+    const actualArguments = rawArguments.slice(2)
+
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        actualArguments,
+      })
+    )
+  }
+
+  /**
+   * Extract the argument that names the file listing the ignored advisories.
+   *
+   * @returns {string | null} Argument, or null when it is not given.
+   * @public
+   */
+  extractIgnoredAdvisoriesFilePathArgument () {
+    return this.extractArgumentByIndex({
+      index: 0,
+    })
+  }
+
+  /**
+   * Extract the argument at an index.
+   *
+   * @param {{
+   *   index: number
+   * }} params - Parameters.
+   * @returns {string | null} Argument, or null when there is none at the index.
+   */
+  extractArgumentByIndex ({
+    index,
+  }) {
+    return this.actualArguments.at(index)
+      ?? null
+  }
+}