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

package/README.ja.md

@@ -25,8 +25,8 @@ ES モジュール（`"type": "module"`）です。ESM の `import` 構文でイ
 リストの項目を検査するには、型ファイルをプロジェクトで 1 度だけ取り込みます。そのうえで、リストに `NpmAuditType.IgnoredAdvisory` を付けます。
 
 ```js
-// types/npm-audit-gate.d.ts
-import '@openreachtech/mentsu-npm-audit-gate/types/npm-audit-gate.d.ts'
+// types/env/npm-audit-gate.d.ts
+import '@openreachtech/mentsu-npm-audit-gate/types/index.d.ts'
 ```
 
 ```js
@@ -56,7 +56,40 @@ process.exitCode = alphaGate.auditAdvisories()
 
 リストに挙がっていない advisory がレポートされたとき、リストの項目がレポートされなくなったとき、`npm audit` がレポートを返さなかったときは、終了コード 1 で終わります。それ以外は 0 で終わります。
 
-`NpmAuditType` のほかの型（`Gate`、`Fetcher`、`ReportResponse`、`Logger` と、それぞれの `Ctor`）は、このパッケージの JSDoc を読むので、使うプロジェクトでは、`jsconfig.json` に `allowJs: true` と、3 以上の `maxNodeModuleJsDepth` が必要です。
+`NpmAuditType` のほかの型（クラスごとに、そのクラスの名前の型と、その `Ctor`）は、このパッケージの JSDoc を読むので、使うプロジェクトでは、`jsconfig.json` に `allowJs: true` と、3 以上の `maxNodeModuleJsDepth` が必要です。
+
+### パッケージが配布するスクリプトの実行
+
+監査を実行するスクリプトはパッケージが配布しているので、リポジトリごとにコピーを持つ必要はありません。`package.json` の script から、パスを指定して呼び出してください。
+
+通す advisory を挙げたファイルを、唯一の引数として渡します。ファイルの既定のエクスポートは配列です。
+
+```js
+// scripts/stopgap-audit/IGNORED_ADVISORIES.js
+export default [
+  {
+    id: 'GHSA-aaaa-bbbb-cccc',
+    package: 'alpha-package',
+    path: 'beta-package > alpha-package',
+    reason: 'No patched release exists, and the package is reached through a development dependency only',
+    removeWhen: 'alpha-package publishes a release outside the affected range',
+  },
+]
+```
+
+```json
+{
+  "scripts": {
+    "audit:npm": "node node_modules/@openreachtech/mentsu-npm-audit-gate/scripts/npm-audit-gate.js scripts/stopgap-audit/IGNORED_ADVISORIES.js"
+  }
+}
+```
+
+ファイルは、作業ディレクトリ基準で解決します。ファイルが無ければ、スクリプトは失敗します。
+
+終了コードは `NpmAuditGate` と同じで、リストを読み込めなかったときも 1 で終わります。
+
+このパッケージは、コマンド名を意図して宣言していません。コマンド名は、インストールした全パッケージが共有する `node_modules/.bin/` で解決されるので、同じ名前を宣言した別のパッケージに、警告なしで奪われます。パスは、このパッケージだけを指します。
 
 ## API
 

package/README.md

@@ -25,8 +25,8 @@ Write a script that hands the list to `NpmAuditGate`, and run it in the project
 To check the entries of the list, import the type file once in your project. Then annotate the list with `NpmAuditType.IgnoredAdvisory`.
 
 ```js
-// types/npm-audit-gate.d.ts
-import '@openreachtech/mentsu-npm-audit-gate/types/npm-audit-gate.d.ts'
+// types/env/npm-audit-gate.d.ts
+import '@openreachtech/mentsu-npm-audit-gate/types/index.d.ts'
 ```
 
 ```js
@@ -56,7 +56,40 @@ process.exitCode = alphaGate.auditAdvisories()
 
 The process ends with exit code 1 when an advisory the list does not name is reported, when an entry of the list is no longer reported, or when `npm audit` answers with no report. Otherwise it ends with 0.
 
-The other types of `NpmAuditType` (`Gate`, `Fetcher`, `ReportResponse`, `Logger` and their `Ctor`) read the JSDoc of this package, so a project that uses them needs `allowJs: true` and `maxNodeModuleJsDepth` of 3 or more in its `jsconfig.json`.
+The other types of `NpmAuditType` (one for each class, named after it, and its `Ctor`) read the JSDoc of this package, so a project that uses them needs `allowJs: true` and `maxNodeModuleJsDepth` of 3 or more in its `jsconfig.json`.
+
+### Running the script shipped with the package
+
+The package ships the script that runs the audit, so a repository does not need to carry a copy of it. Call it by its path from a script of `package.json`.
+
+Pass the file that lists the ignored advisories as the only argument. Its default export is the array.
+
+```js
+// scripts/stopgap-audit/IGNORED_ADVISORIES.js
+export default [
+  {
+    id: 'GHSA-aaaa-bbbb-cccc',
+    package: 'alpha-package',
+    path: 'beta-package > alpha-package',
+    reason: 'No patched release exists, and the package is reached through a development dependency only',
+    removeWhen: 'alpha-package publishes a release outside the affected range',
+  },
+]
+```
+
+```json
+{
+  "scripts": {
+    "audit:npm": "node node_modules/@openreachtech/mentsu-npm-audit-gate/scripts/npm-audit-gate.js scripts/stopgap-audit/IGNORED_ADVISORIES.js"
+  }
+}
+```
+
+The file is resolved against the working directory, and the script fails when it is missing.
+
+It ends with the same exit codes as `NpmAuditGate`, and with 1 as well when the list cannot be loaded.
+
+The package declares no command name on purpose. A command name is resolved through `node_modules/.bin/`, which every installed package shares, and another package that declares the same name takes it over without any warning. The path names this package alone.
 
 ## API
 

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/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
+  }
+}

package/lib/globals/root-path.js

@@ -0,0 +1,7 @@
+import {
+  RootPath,
+} from '@openreachtech/mentsu-rootpath'
+
+const rootPath = RootPath.create()
+
+export default rootPath

package/lib/index.js

@@ -1,5 +1,8 @@
 export { default as AuditFetcher } from './AuditFetcher.js'
 export { default as AuditReportResponse } from './AuditReportResponse.js'
-export { default as EXIT_CODE } from './EXIT_CODE.js'
+export { default as IgnoredAdvisoriesLoader } from './IgnoredAdvisoriesLoader.js'
 export { default as NpmAuditGate } from './NpmAuditGate.js'
+export { default as ProcessArgumentsResolver } from './ProcessArgumentsResolver.js'
 export { default as ProcessLogger } from './ProcessLogger.js'
+
+export { default as EXIT_CODE } from './EXIT_CODE.js'

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "@openreachtech/mentsu-npm-audit-gate",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Gate that checks the result of npm audit",
   "type": "module",
   "main": "lib/index.js",
   "files": [
     "lib/",
+    "scripts/",
+    "!scripts/stopgap-audit/IGNORED_ADVISORIES.js",
     "types/",
     "!types/env/**"
   ],
   "types": "./types/index.d.ts",
   "scripts": {
+    "audit:npm": "node scripts/npm-audit-gate.js scripts/stopgap-audit/IGNORED_ADVISORIES.js",
     "l": "npm run lint",
     "lint": "eslint .",
     "test": "export NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\"; export NODE_ENV=development; jest"
@@ -30,22 +33,22 @@
     "npm": ">=11.17.0"
   },
   "dependencies": {
+    "@openreachtech/mentsu-rootpath": "^1.1.3"
   },
   "devDependencies": {
     "@openreachtech/eslint-config": "^4.5.0",
     "@openreachtech/jest-constructor-spy": "^1.1.2",
     "@openreachtech/jest-deep-containing": "^1.0.2",
     "@openreachtech/jest-expect-each": "^1.0.3",
-    "@openreachtech/mentsu-rootpath": "^1.1.3",
-    "@openreachtech/renchan-env": "^1.0.6",
+    "@openreachtech/renchan-env": "^1.1.0",
     "@types/jest": "^30.0.0",
     "eslint": "^9.39.5",
     "jest": "^30.5.2"
   },
   "overrides": {
-    "brace-expansion@1": "^1.1.21",
     "brace-expansion@5": "^5.0.12",
-    "glob": "^13.0.6"
+    "glob": "^14.0.2",
+    "minimatch": "^11.0.4"
   },
   "allowScripts": {
     "@parcel/watcher": false,

package/scripts/npm-audit-gate.js

@@ -0,0 +1,31 @@
+import rootPath from '../lib/globals/root-path.js'
+
+import IgnoredAdvisoriesLoader from '../lib/IgnoredAdvisoriesLoader.js'
+import NpmAuditGate from '../lib/NpmAuditGate.js'
+import ProcessArgumentsResolver from '../lib/ProcessArgumentsResolver.js'
+
+const argumentsResolver = ProcessArgumentsResolver.create({
+  rawArguments: process.argv,
+})
+
+const ignoredAdvisoriesPath = argumentsResolver.extractIgnoredAdvisoriesFilePathArgument()
+
+if (ignoredAdvisoriesPath === null) {
+  throw new Error('An argument that specifies the ignored advisories is required')
+}
+
+const loader = IgnoredAdvisoriesLoader.create({
+  ignoredAdvisoriesFilePath: rootPath.to(ignoredAdvisoriesPath),
+})
+
+const ignoredAdvisories = await loader.loadAdvisories()
+
+if (ignoredAdvisories === null) {
+  throw new Error(`Failed to load the ignored advisories: ${ignoredAdvisoriesPath}`)
+}
+
+const gate = NpmAuditGate.create({
+  ignoredAdvisories,
+})
+
+process.exitCode = gate.auditAdvisories()

package/types/index.d.ts

@@ -1,5 +1,49 @@
+import type AuditFetcherActual from '../lib/AuditFetcher.js'
+import type AuditReportResponseActual from '../lib/AuditReportResponse.js'
+import type IgnoredAdvisoriesLoaderActual from '../lib/IgnoredAdvisoriesLoader.js'
+import type NpmAuditGateActual from '../lib/NpmAuditGate.js'
+import type ProcessArgumentsResolverActual from '../lib/ProcessArgumentsResolver.js'
+import type ProcessLoggerActual from '../lib/ProcessLogger.js'
+
+import type EXIT_CODE_ACTUAL from '../lib/EXIT_CODE.js'
+
 export { default as AuditFetcher } from '../lib/AuditFetcher.js'
 export { default as AuditReportResponse } from '../lib/AuditReportResponse.js'
-export { default as EXIT_CODE } from '../lib/EXIT_CODE.js'
+export { default as IgnoredAdvisoriesLoader } from '../lib/IgnoredAdvisoriesLoader.js'
 export { default as NpmAuditGate } from '../lib/NpmAuditGate.js'
+export { default as ProcessArgumentsResolver } from '../lib/ProcessArgumentsResolver.js'
 export { default as ProcessLogger } from '../lib/ProcessLogger.js'
+
+export { default as EXIT_CODE } from '../lib/EXIT_CODE.js'
+
+declare global {
+  namespace NpmAuditType {
+    type AuditFetcher = AuditFetcherActual
+    type AuditFetcherCtor = typeof AuditFetcherActual
+
+    type AuditReportResponse = AuditReportResponseActual
+    type AuditReportResponseCtor = typeof AuditReportResponseActual
+
+    type IgnoredAdvisoriesLoader = IgnoredAdvisoriesLoaderActual
+    type IgnoredAdvisoriesLoaderCtor = typeof IgnoredAdvisoriesLoaderActual
+
+    type NpmAuditGate = NpmAuditGateActual
+    type NpmAuditGateCtor = typeof NpmAuditGateActual
+
+    type ProcessArgumentsResolver = ProcessArgumentsResolverActual
+    type ProcessArgumentsResolverCtor = typeof ProcessArgumentsResolverActual
+
+    type ProcessLogger = ProcessLoggerActual
+    type ProcessLoggerCtor = typeof ProcessLoggerActual
+
+    type EXIT_CODE = typeof EXIT_CODE_ACTUAL
+
+    type IgnoredAdvisory = {
+      id: string
+      package: string
+      path: string
+      reason: string
+      removeWhen: string
+    }
+  }
+}

package/types/npm-audit-gate.d.ts

@@ -1,28 +0,0 @@
-import type AuditFetcher from '../lib/AuditFetcher.js'
-import type AuditReportResponse from '../lib/AuditReportResponse.js'
-import type NpmAuditGate from '../lib/NpmAuditGate.js'
-import type ProcessLogger from '../lib/ProcessLogger.js'
-
-declare global {
-  namespace NpmAuditType {
-    type Gate = NpmAuditGate
-    type GateCtor = typeof NpmAuditGate
-
-    type Fetcher = AuditFetcher
-    type FetcherCtor = typeof AuditFetcher
-
-    type ReportResponse = AuditReportResponse
-    type ReportResponseCtor = typeof AuditReportResponse
-
-    type Logger = ProcessLogger
-    type LoggerCtor = typeof ProcessLogger
-
-    type IgnoredAdvisory = {
-      id: string
-      package: string
-      path: string
-      reason: string
-      removeWhen: string
-    }
-  }
-}