@wtf/release-docs 9.0.2 → 10.0.0

package/api/@wtf/release/errors/functions/throwAll.md

@@ -0,0 +1,26 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/errors](../README.md) / throwAll
+
+# Function: throwAll()
+
+> **throwAll**(`errors`): `void`
+
+Defined in: [packages/release/src/errors.ts:96](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/errors.ts#L96)
+
+Throws `errors`: nothing when there are none, the one when there is one, or all of them in an
+`AggregateError`, whose message is theirs, a line each.
+
+## Parameters
+
+### errors
+
+readonly `Error`[]
+
+The faults a step found, of any count, in the order they are said.
+
+## Returns
+
+`void`

package/api/@wtf/{release-system → release}/errors/type-aliases/ErrorClass.md

@@ -2,13 +2,13 @@
 
 ***
 
-[Release trains](../../../../README.md) / [@wtf/release-system/errors](../README.md) / ErrorClass
+[Release trains](../../../../README.md) / [@wtf/release/errors](../README.md) / ErrorClass
 
 # Type Alias: ErrorClass\<E\>
 
 > **ErrorClass**\<`E`\> = new (`code`, `message`, `details`) => `E`
 
-Defined in: [packages/release-system/src/errors.ts:72](https://gitlab.com/wetryfun/release/release/-/blob/3b0e2c3c91b521977d05b801e2297d0df9e52834/packages/release-system/src/errors.ts#L72)
+Defined in: [packages/release/src/errors.ts:84](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/errors.ts#L84)
 
 A class of the errors of a package, of a code, a message and details, as `TrainsError`: what
 `errorsOf` of `./validator` makes the errors of the issues of a value of.

package/api/@wtf/release/errors/type-aliases/ReleaseErrorCode.md

@@ -0,0 +1,13 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/errors](../README.md) / ReleaseErrorCode
+
+# Type Alias: ReleaseErrorCode
+
+> **ReleaseErrorCode** = keyof *typeof* [`RELEASE_ERRORS`](../variables/RELEASE_ERRORS.md)
+
+Defined in: [packages/release/src/errors.ts:34](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/errors.ts#L34)
+
+A code of [RELEASE\_ERRORS](../variables/RELEASE_ERRORS.md).

package/api/@wtf/release/errors/variables/RELEASE_ERRORS.md

@@ -0,0 +1,35 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/errors](../README.md) / RELEASE\_ERRORS
+
+# Variable: RELEASE\_ERRORS
+
+> `const` **RELEASE\_ERRORS**: `object`
+
+Defined in: [packages/release/src/errors.ts:23](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/errors.ts#L23)
+
+The codes of the errors of this package, each with what it means.
+
+## Type Declaration
+
+### EECOSYSTEM
+
+> `readonly` **EECOSYSTEM**: `` "An ecosystem of `ecosystems` cannot be loaded, is no ecosystem, or has the name of another." `` = `` 'An ecosystem of `ecosystems` cannot be loaded, is no ecosystem, or has the name of another.' ``
+
+### EGENERATED
+
+> `readonly` **EGENERATED**: `"A folder the build generates is not there."` = `'A folder the build generates is not there.'`
+
+### EGIT
+
+> `readonly` **EGIT**: `"git failed."` = `'git failed.'`
+
+### EOPTIONS
+
+> `readonly` **EOPTIONS**: `"An option is missing, or is not one it takes, as a validator of options finds it."` = `'An option is missing, or is not one it takes, as a validator of options finds it.'`
+
+### ERELEASELINK
+
+> `readonly` **ERELEASELINK**: `"A package of a release has nothing to link it by: no page, and no file its forge keeps."` = `'A package of a release has nothing to link it by: no page, and no file its forge keeps.'`

package/api/@wtf/release/files/README.md

@@ -0,0 +1,38 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / @wtf/release/files
+
+# @wtf/release/files
+
+The files of a folder, each by its path from it, as `/` writes it, over a handle of the File
+System standard: [readFile](functions/readFile.md), [readBytes](functions/readBytes.md), [writeFile](functions/writeFile.md), [exists](functions/exists.md),
+[readDir](functions/readDir.md), [makeDir](functions/makeDir.md), [remove](functions/remove.md) and [copy](functions/copy.md). A path never leads out of the
+folder it is of. What a handle throws is a `PlatformError` of `@wtf/platform/errors`, as `at` of
+`@wtf/platform-fs/path` raises it: one of an entry not there a `SystemError` of `NotFound`.
+
+```ts
+import type { FileSystemDirectoryHandle } from '@wtf/platform/fs'
+import { readFile, writeFile } from '@wtf/release/files'
+
+export async function touch(root: FileSystemDirectoryHandle) {
+  await writeFile(root, 'notes/today.md', '# Today\n')
+  return readFile(root, 'notes/today.md')
+}
+```
+
+## Interfaces
+
+- [DirEntry](interfaces/DirEntry.md)
+
+## Functions
+
+- [copy](functions/copy.md)
+- [exists](functions/exists.md)
+- [makeDir](functions/makeDir.md)
+- [readBytes](functions/readBytes.md)
+- [readDir](functions/readDir.md)
+- [readFile](functions/readFile.md)
+- [remove](functions/remove.md)
+- [writeFile](functions/writeFile.md)

package/api/@wtf/release/files/functions/copy.md

@@ -0,0 +1,45 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/files](../README.md) / copy
+
+# Function: copy()
+
+> **copy**(`from`, `fromPath`, `to`, `toPath`): `Promise`\<`void`\>
+
+Defined in: [packages/release/src/files.ts:156](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/files.ts#L156)
+
+Copies the file or the folder `fromPath` of `from` to `toPath` of `to`, with what it holds, byte
+for byte, each folder on the way made: of one folder to another, as of the repo to a temporary
+folder.
+
+## Parameters
+
+### from
+
+`FileSystemDirectoryHandle`
+
+The folder the path to copy is of.
+
+### fromPath
+
+`string`
+
+The path of the file or the folder to copy, from `from`.
+
+### to
+
+`FileSystemDirectoryHandle`
+
+The folder the path of the copy is of: `from` itself, or another.
+
+### toPath
+
+`string`
+
+The path of the copy, from `to`, written over where it is there.
+
+## Returns
+
+`Promise`\<`void`\>

package/api/@wtf/release/files/functions/exists.md

@@ -0,0 +1,33 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/files](../README.md) / exists
+
+# Function: exists()
+
+> **exists**(`root`, `path`): `Promise`\<`boolean`\>
+
+Defined in: [packages/release/src/files.ts:88](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/files.ts#L88)
+
+Whether there is a file or a folder at `path` of `root`.
+
+## Parameters
+
+### root
+
+`FileSystemDirectoryHandle`
+
+The folder the path is of.
+
+### path
+
+`string`
+
+The path, from `root`.
+
+## Returns
+
+`Promise`\<`boolean`\>
+
+Whether there is one.

package/api/@wtf/release/files/functions/makeDir.md

@@ -0,0 +1,33 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/files](../README.md) / makeDir
+
+# Function: makeDir()
+
+> **makeDir**(`root`, `path`): `Promise`\<`FileSystemDirectoryHandle`\>
+
+Defined in: [packages/release/src/files.ts:120](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/files.ts#L120)
+
+Makes the folder `path` of `root`, and each folder on the way that is not there.
+
+## Parameters
+
+### root
+
+`FileSystemDirectoryHandle`
+
+The folder the path is of.
+
+### path
+
+`string`
+
+The path of the folder, from `root`: nothing to make where it is there.
+
+## Returns
+
+`Promise`\<`FileSystemDirectoryHandle`\>
+
+The handle of the folder.

package/api/@wtf/release/files/functions/readBytes.md

@@ -0,0 +1,33 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/files](../README.md) / readBytes
+
+# Function: readBytes()
+
+> **readBytes**(`root`, `path`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+Defined in: [packages/release/src/files.ts:49](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/files.ts#L49)
+
+The bytes of the file `path` of `root`.
+
+## Parameters
+
+### root
+
+`FileSystemDirectoryHandle`
+
+The folder the path is of.
+
+### path
+
+`string`
+
+The path of the file, from `root`.
+
+## Returns
+
+`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+The bytes of the file, whole.

package/api/@wtf/release/files/functions/readDir.md

@@ -0,0 +1,33 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/files](../README.md) / readDir
+
+# Function: readDir()
+
+> **readDir**(`root`, `path`): `Promise`\<[`DirEntry`](../interfaces/DirEntry.md)[]\>
+
+Defined in: [packages/release/src/files.ts:105](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/files.ts#L105)
+
+The entries of the folder `path` of `root`, in order of their names.
+
+## Parameters
+
+### root
+
+`FileSystemDirectoryHandle`
+
+The folder the path is of.
+
+### path
+
+`string`
+
+The path of the folder, from `root`: `.` of `root` itself.
+
+## Returns
+
+`Promise`\<[`DirEntry`](../interfaces/DirEntry.md)[]\>
+
+The entries, each of its name and whether it is a folder.

package/api/@wtf/release/files/functions/readFile.md

@@ -0,0 +1,33 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/files](../README.md) / readFile
+
+# Function: readFile()
+
+> **readFile**(`root`, `path`): `Promise`\<`string`\>
+
+Defined in: [packages/release/src/files.ts:38](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/files.ts#L38)
+
+The text of the file `path` of `root`, as UTF-8.
+
+## Parameters
+
+### root
+
+`FileSystemDirectoryHandle`
+
+The folder the path is of.
+
+### path
+
+`string`
+
+The path of the file, from `root`.
+
+## Returns
+
+`Promise`\<`string`\>
+
+The text of the file, whole.

package/api/@wtf/release/files/functions/remove.md

@@ -0,0 +1,34 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/files](../README.md) / remove
+
+# Function: remove()
+
+> **remove**(`root`, `path`): `Promise`\<`boolean`\>
+
+Defined in: [packages/release/src/files.ts:135](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/files.ts#L135)
+
+Removes the file or the folder `path` of `root`, with what it holds; nothing, where it is not
+there.
+
+## Parameters
+
+### root
+
+`FileSystemDirectoryHandle`
+
+The folder the path is of.
+
+### path
+
+`string`
+
+The path of the file or the folder, from `root`.
+
+## Returns
+
+`Promise`\<`boolean`\>
+
+Whether there was one.

package/api/@wtf/release/files/functions/writeFile.md

@@ -0,0 +1,38 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/files](../README.md) / writeFile
+
+# Function: writeFile()
+
+> **writeFile**(`root`, `path`, `data`): `Promise`\<`void`\>
+
+Defined in: [packages/release/src/files.ts:65](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/files.ts#L65)
+
+Writes `data` into the file `path` of `root`, whole, and each folder on the way where it is not
+there: its writable takes the file's place as it closes, so a failure leaves the file as it was.
+
+## Parameters
+
+### root
+
+`FileSystemDirectoryHandle`
+
+The folder the path is of.
+
+### path
+
+`string`
+
+The path of the file, from `root`, written over where it is there.
+
+### data
+
+`string` \| `Uint8Array`\<`ArrayBufferLike`\>
+
+The text of the file, as UTF-8, or its bytes.
+
+## Returns
+
+`Promise`\<`void`\>

package/api/@wtf/release/files/interfaces/DirEntry.md

@@ -0,0 +1,27 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/files](../README.md) / DirEntry
+
+# Interface: DirEntry
+
+Defined in: [packages/release/src/files.ts:26](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/files.ts#L26)
+
+An entry of a folder: its name, and whether it is a folder itself.
+
+## Properties
+
+### directory
+
+> `readonly` **directory**: `boolean`
+
+Defined in: [packages/release/src/files.ts:28](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/files.ts#L28)
+
+***
+
+### name
+
+> `readonly` **name**: `string`
+
+Defined in: [packages/release/src/files.ts:27](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/files.ts#L27)

package/api/@wtf/release/forge/README.md

@@ -0,0 +1,49 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / @wtf/release/forge
+
+# @wtf/release/forge
+
+Forges, and the links of a release: an ecosystem says what it published ([Released](interfaces/Released.md)); the
+forge of the run ([Forge](interfaces/Forge.md)), as GitLab or GitHub, says where a package on its own registries
+lives, and keeps a file of a package of no page; and [linksOf](functions/linksOf.md) gives the link of each
+package of a release, by the first of these it has:
+
+1. its page, where its ecosystem knows it, as of a public registry: npm's, crates.io's, Maven
+   Central's, the Go proxy's;
+2. its page of the forge, as the forge's `pageOf` gives it: of a registry of the forge, or of its
+   folder at its tag;
+3. its file, kept by the forge's `upload`, where it has one.
+
+A forge of no `upload` links a package of no page by nothing, which is an error.
+
+```ts
+import { type Forge, linksOf } from '@wtf/release/forge'
+
+// A forge that knows no page of its own, and keeps no file.
+const none: Forge = {
+  name: 'none',
+  runOf: () => ({ url: 'https://forge.example/acme/core', api: 'https://forge.example/api', project: 'acme/core' }),
+  pageOf: async () => undefined
+}
+const run = none.runOf({})!
+await linksOf(run, none, [
+  { ecosystem: 'npm', name: '@acme/core', version: '1.2.0', page: 'https://www.npmjs.com/package/@acme/core/v/1.2.0' }
+])
+// [{ label: '@acme/core', url: 'https://www.npmjs.com/package/@acme/core/v/1.2.0', type: 'package' }]
+```
+
+## Interfaces
+
+- [Forge](interfaces/Forge.md)
+- [ForgeRun](interfaces/ForgeRun.md)
+- [LinksOptions](interfaces/LinksOptions.md)
+- [PackageRegistry](interfaces/PackageRegistry.md)
+- [Released](interfaces/Released.md)
+- [ReleaseLink](interfaces/ReleaseLink.md)
+
+## Functions
+
+- [linksOf](functions/linksOf.md)

package/api/@wtf/release/forge/functions/linksOf.md

@@ -0,0 +1,49 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/forge](../README.md) / linksOf
+
+# Function: linksOf()
+
+> **linksOf**(`run`, `forge`, `released`, `options?`): `Promise`\<[`ReleaseLink`](../interfaces/ReleaseLink.md)[]\>
+
+Defined in: [packages/release/src/forge.ts:164](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/forge.ts#L164)
+
+The link of each package of `released` from the release of the run on its forge, by the first
+rule it has (see the module): its page; the forge's page of it; its file, kept by the forge. Each
+link is named by its package: of two of one name, by the name and the ecosystem. Throws,
+together, `ERELEASELINK` of each package of none, and each `ReleaseError` of the forge; anything
+else the forge throws, as it is.
+
+## Parameters
+
+### run
+
+[`ForgeRun`](../interfaces/ForgeRun.md)
+
+The run of the release on the forge.
+
+### forge
+
+[`Forge`](../interfaces/Forge.md)
+
+The forge of the run.
+
+### released
+
+readonly [`Released`](../interfaces/Released.md)[]
+
+The packages of the release, of every ecosystem.
+
+### options?
+
+[`LinksOptions`](../interfaces/LinksOptions.md) = `{}`
+
+The tag of the release, and where each link is said.
+
+## Returns
+
+`Promise`\<[`ReleaseLink`](../interfaces/ReleaseLink.md)[]\>
+
+The links, in the order of the packages.

package/api/@wtf/release/forge/interfaces/Forge.md

@@ -0,0 +1,113 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/forge](../README.md) / Forge
+
+# Interface: Forge
+
+Defined in: [packages/release/src/forge.ts:77](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/forge.ts#L77)
+
+A forge: where a repo lives, its registries, and the releases of its tags.
+
+## Properties
+
+### name
+
+> `readonly` **name**: `string`
+
+Defined in: [packages/release/src/forge.ts:79](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/forge.ts#L79)
+
+Its name, as `gitlab` or `github`.
+
+## Methods
+
+### pageOf()
+
+> **pageOf**(`run`, `released`): `Promise`\<`string` \| `undefined`\>
+
+Defined in: [packages/release/src/forge.ts:95](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/forge.ts#L95)
+
+The page of a package on the forge, where it has one: of a registry of the forge, or of the
+package's folder at its tag.
+
+#### Parameters
+
+##### run
+
+[`ForgeRun`](ForgeRun.md)
+
+The run of the release.
+
+##### released
+
+[`Released`](Released.md)
+
+The package, of the tag of the release where it has none of its own.
+
+#### Returns
+
+`Promise`\<`string` \| `undefined`\>
+
+The URL of the page, or `undefined` where the forge has none.
+
+***
+
+### runOf()
+
+> **runOf**(`env`): [`ForgeRun`](ForgeRun.md) \| `undefined`
+
+Defined in: [packages/release/src/forge.ts:86](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/forge.ts#L86)
+
+The run of the environment, by the forge's own variables of its CI: none outside its CI.
+
+#### Parameters
+
+##### env
+
+`Readonly`\<`Record`\<`string`, `string` \| `undefined`\>\>
+
+The environment of the run.
+
+#### Returns
+
+[`ForgeRun`](ForgeRun.md) \| `undefined`
+
+The run, or `undefined` of an environment of no run of the forge.
+
+***
+
+### upload()?
+
+> `optional` **upload**(`run`, `file`, `released`): `Promise`\<`string`\>
+
+Defined in: [packages/release/src/forge.ts:105](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/forge.ts#L105)
+
+Keeps a file of a package of no page, as a generic package (GitLab) or an asset of the release
+(GitHub).
+
+#### Parameters
+
+##### run
+
+[`ForgeRun`](ForgeRun.md)
+
+The run of the release.
+
+##### file
+
+`string`
+
+The absolute path of the file.
+
+##### released
+
+[`Released`](Released.md)
+
+The package.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The URL of the file kept.