@wtf/release-docs 9.0.2 → 10.0.0

package/guides/system.md

@@ -1,175 +0,0 @@
-# The system
-
-Read this page when you want to run the libraries outside semantic-release, from a CLI of your own,
-or in tests. You can also use it to change how the plugins run processes.
-
-Every function of the libraries, such as `@wtf/release-trains`, `@wtf/release-npm` and
-`@wtf/release-replace`, reaches the outside world through a `System`. The `System` type comes from
-`@wtf/release-system`, the base that the other libraries build on. A function requires a system
-from its caller and never makes one itself.
-
-The system provides files, processes, the environment, the working folder, a folder for temporary
-files, and the clock. None of the library modules names Node. Each caller passes the system that
-fits it:
-
-- A semantic-release plugin passes Node's system.
-- A CLI adapts its own files and processes to the interface, and passes that.
-- A test passes a system in memory.
-
-```ts
-import type { System } from '@wtf/release-system/system'
-
-// What a system holds.
-export type Members = keyof System // 'fs' | 'exec' | 'env' | 'cwd' | 'tmpdir' | 'now'
-```
-
-| Member   | What it is                                                                                                                             |
-| -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `fs`     | `readFile`, `writeFile`, `readdir`, `exists`, `mkdir` and `rm` for text, and `copy` byte for byte. Every path is absolute.             |
-| `exec`   | `exec(command, args, { cwd, env, input })`, which returns `{ stdout, stderr, code }`. It uses the system's `cwd` and `env` by default. |
-| `env`    | The environment that a process gets.                                                                                                   |
-| `cwd`    | The working folder.                                                                                                                    |
-| `tmpdir` | A folder for temporary files, outside the repo. A release copies and packs its packages there.                                         |
-| `now`    | The current time, which dates a changelog.                                                                                             |
-
-A non-zero exit code is not a failure of `exec` itself, and the caller decides what it means.
-`exec` rejects only when the command cannot start.
-
-Paths are POSIX paths. `@wtf/release-system/posix` joins them, without needing a system.
-
-## Use Node's system
-
-`nodeSystem` from `@wtf/release-system/node` is Node's system. It uses `node:fs/promises`,
-`node:child_process`, `process.env`, `process.cwd()`, `os.tmpdir()` and `new Date()`.
-
-It is the only library module that names Node. Only a caller that runs on Node imports it, such as
-a plugin, a build script or a test.
-
-```ts
-import { nodeSystem } from '@wtf/release-system/node'
-import { readWorkspace } from '@wtf/release-npm/workspace'
-
-const system = nodeSystem()
-export const packages = await readWorkspace(system.cwd, { system })
-```
-
-## Write a system of your own
-
-A CLI with its own files and processes adapts them to the interface, and passes the result to each
-function. This example logs each process before it runs:
-
-```ts
-import npm from '@wtf/release-npm'
-import type { System } from '@wtf/release-system/system'
-import { verifyTrain } from '@wtf/release-trains/verify'
-
-/** A system whose processes are logged before they run, over the one a CLI has. */
-export const logged = (system: System): System => ({
-  ...system,
-  exec: (command, args, options) => {
-    console.error(`$ ${command} ${args.join(' ')}`)
-    return system.exec(command, args, options)
-  }
-})
-
-export function check(system: System) {
-  return verifyTrain({
-    trains: {
-      validate: { paths: ['packages/release-validate', 'packages/semantic-release-validate'] }
-    },
-    train: 'validate',
-    ecosystems: [npm],
-    system: logged(system)
-  })
-}
-```
-
-## Change the system that the plugins use
-
-Each plugin makes Node's system for the run. It builds the system from the folder and the
-environment that semantic-release gives each step, `cwd` and `env`, which the plugin requires. It
-passes that system to every call into its library, so each process runs in that folder and with
-that environment.
-
-To replace members of that system, set the plugin's `system` option, or a `system` option at the
-root of the config. `systemOf` from `@wtf/release-system/node` merges it over Node's system. It
-merges `fs` member by member. This example stops every process of the release from asking for a
-password:
-
-```js train=trains
-// release.config.mjs
-import { systemOf } from '@wtf/release-system/node'
-import { trainTagFormat } from '@wtf/semantic-release-trains/config'
-
-const node = systemOf()
-const trains = { trains: { paths: ['packages/release-trains', 'packages/release-trains-*'] } }
-const train = process.env.RELEASE_TRAIN
-
-export default {
-  trains,
-  ecosystems: ['@wtf/semantic-release-npm/ecosystem'],
-  tagFormat: trainTagFormat(trains, train),
-  // No process of the release asks for a password.
-  system: {
-    /** @type {import('@wtf/release-system/system').Exec} */
-    exec: (command, args, options) =>
-      node.exec(command, args, {
-        ...options,
-        env: { ...(options?.env ?? node.env), GIT_TERMINAL_PROMPT: '0' }
-      })
-  },
-  plugins: [
-    ['@wtf/semantic-release-trains', { wrap: '@semantic-release/commit-analyzer' }],
-    ['@wtf/semantic-release-trains', { wrap: '@semantic-release/release-notes-generator' }],
-    '@wtf/semantic-release-npm'
-  ]
-}
-```
-
-semantic-release copies the config for each plugin. The copy keeps the functions of an object, so
-a system in a `release.config.mjs` reaches each plugin. A config written in JSON cannot hold a
-system, so the plugins then run on Node's system.
-
-## Use a system in tests
-
-A system with files in memory and scripted processes runs the libraries with no disk and no git:
-
-```ts
-import type { System } from '@wtf/release-system/system'
-import { readWorkspace } from '@wtf/release-npm/workspace'
-
-const files = new Map<string, string>([
-  ['/repo/pnpm-workspace.yaml', 'packages:\n  - packages/*\n'],
-  ['/repo/packages/release-trains/package.json', '{ "name": "@wtf/release-trains" }']
-])
-const missing = (path: string) => Promise.reject(new Error(`ENOENT ${path}`))
-
-const memory: System = {
-  cwd: '/repo',
-  tmpdir: '/tmp',
-  env: {},
-  now: () => new Date('2026-10-30'),
-  exec: async (command) => ({ stdout: '', stderr: `${command}: not here`, code: 127 }),
-  fs: {
-    readFile: async (path) => files.get(path) ?? missing(path),
-    writeFile: async (path, text) => void files.set(path, text),
-    exists: async (path) =>
-      files.has(path) || [...files.keys()].some((file) => file.startsWith(`${path}/`)),
-    readdir: async (path) => {
-      const names = new Map<string, boolean>()
-      for (const file of files.keys())
-        if (file.startsWith(`${path}/`)) {
-          const [name = '', ...rest] = file.slice(path.length + 1).split('/')
-          names.set(name, rest.length > 0)
-        }
-      return [...names].map(([name, directory]) => ({ name, directory }))
-    },
-    mkdir: async () => {},
-    rm: async (path) => void files.delete(path),
-    copy: async (from, to) => void files.set(to, files.get(from) ?? '')
-  }
-}
-
-export const names = async () =>
-  (await readWorkspace('/repo', { system: memory })).map(({ name }) => name) // ['@wtf/release-trains']
-```