npm - @xmachines/docs - Versions diffs - 7.0.0 → 7.1.0 - Mend

@xmachines/docs 7.0.0 → 7.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (763) hide show

package/api/@xmachines/shared/vite-aliases/functions/xmBuildOutputFile.md CHANGED Viewed

@@ -6,7 +6,7 @@
 function xmBuildOutputFile(packageDir, sourceFile): string;
 ```
-Defined in: [vite-aliases.ts:359](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L359)
+Defined in: [vite-aliases.ts:378](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L378)
 The file in `dist/` that the build writes for one source file of a package.

package/api/@xmachines/shared/vite-aliases/functions/xmCacheDir.md CHANGED Viewed

@@ -6,7 +6,7 @@
 function xmCacheDir(importMetaUrl, name): string;
 ```
-Defined in: [vite-aliases.ts:495](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L495)
+Defined in: [vite-aliases.ts:514](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L514)
 Returns the shared Vite `cacheDir` for this workspace package.

package/api/@xmachines/shared/vite-aliases/functions/xmOptimizeDeps.md CHANGED Viewed

@@ -6,7 +6,7 @@
 function xmOptimizeDeps(include?): DepOptimizationOptions;
 ```
-Defined in: [vite-aliases.ts:448](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L448)
+Defined in: [vite-aliases.ts:467](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L467)
 Returns the standard Vite `optimizeDeps` config for browser test projects.
@@ -26,9 +26,9 @@ packages this project actually depends on.
 ## Parameters
-| Parameter | Type       | Default value | Description                                                    |
-| --------- | ---------- | ------------- | -------------------------------------------------------------- |
-| `include` | `string`[] | `[]`          | Package specifiers to pre-bundle, each declared by the caller. |
+| Parameter  | Type       | Default value | Description                                                    |
+| ---------- | ---------- | ------------- | -------------------------------------------------------------- |
+| `include?` | `string`[] | `[]`          | Package specifiers to pre-bundle, each declared by the caller. |
 ## Returns

package/api/@xmachines/shared/vite-aliases/functions/xmResolve.md CHANGED Viewed

@@ -6,7 +6,7 @@
 function xmResolve(importMetaUrl, extra?): ResolveOptions & object;
 ```
-Defined in: [vite-aliases.ts:333](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L333)
+Defined in: [vite-aliases.ts:352](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L352)
 Full Vite `resolve` config for @xmachines/* workspace packages.

package/api/@xmachines/shared/vite-aliases/functions/xmSvelteRunes.md CHANGED Viewed

@@ -6,7 +6,7 @@
 function xmSvelteRunes(): object;
 ```
-Defined in: [vite-aliases.ts:474](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L474)
+Defined in: [vite-aliases.ts:493](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L493)
 Svelte plugin options that enforce runes mode for workspace sources only.
@@ -33,6 +33,6 @@ one and change the other.
 `object`
-| Name                      | Type                                                    | Defined in                                                                                                                  |
-| ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:475](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L475) |
+| Name                      | Type                                                    | Defined in                                                                                                                       |
+| ------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:494](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L494) |

package/api/@xmachines/shared/vite-aliases/functions/xmTestTarget.md CHANGED Viewed

@@ -6,7 +6,7 @@
 function xmTestTarget(env?): XmTestTarget;
 ```
-Defined in: [vite-aliases.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L25)
+Defined in: [vite-aliases.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L25)
 Reads the test target from the `XM_TEST_TARGET` environment variable.
@@ -19,7 +19,7 @@ the suite against the source and report the result as a run against the build.
 | Parameter | Type         | Default value | Description                                            |
 | --------- | ------------ | ------------- | ------------------------------------------------------ |
-| `env`     | `ProcessEnv` | `process.env` | The environment to read. The default is `process.env`. |
+| `env?`    | `ProcessEnv` | `process.env` | The environment to read. The default is `process.env`. |
 ## Returns

package/api/@xmachines/shared/vite-aliases/type-aliases/XmTestTarget.md CHANGED Viewed

@@ -6,7 +6,7 @@
 type XmTestTarget = "source" | "dist";
 ```
-Defined in: [vite-aliases.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L13)
+Defined in: [vite-aliases.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vite-aliases.ts#L13)
 The code that a test run loads for each published `@xmachines/*` package.

package/api/@xmachines/shared/vitest/functions/defineXmBrowserConfig.md CHANGED Viewed

@@ -6,7 +6,7 @@
 function defineXmBrowserConfig(importMetaUrl, overrides, options?): UserConfig;
 ```
-Defined in: [vitest.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vitest.ts#L224)
+Defined in: [vitest.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vitest.ts#L230)
 Create a Vitest browser-mode config with XMachines workspace defaults.
@@ -33,7 +33,7 @@ Playwright defaults. Plugins stay per-package arguments (`plugins: [vue()]`).
 | --------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `importMetaUrl` | `string`                                                            | Pass `import.meta.url` from the calling config file.                                                                                                 |
 | `overrides`     | `UserConfig`                                                        | Package/project-specific Vitest config overrides. `overrides.test.name` is required — it names the project and keys the shared Vite cache directory. |
-| `options`       | [`XmBrowserConfigOptions`](../interfaces/XmBrowserConfigOptions.md) | Browser-specific knobs, see [XmBrowserConfigOptions](../interfaces/XmBrowserConfigOptions.md).                                                       |
+| `options?`      | [`XmBrowserConfigOptions`](../interfaces/XmBrowserConfigOptions.md) | Browser-specific knobs, see [XmBrowserConfigOptions](../interfaces/XmBrowserConfigOptions.md).                                                       |
 ## Returns

package/api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md CHANGED Viewed

@@ -6,7 +6,7 @@
 function defineXmVitestConfig(importMetaUrl, overrides): UserConfig;
 ```
-Defined in: [vitest.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vitest.ts#L76)
+Defined in: [vitest.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vitest.ts#L76)
 Create a Vitest config with XMachines workspace defaults.

package/api/@xmachines/shared/vitest/interfaces/XmBrowserConfigOptions.md CHANGED Viewed

@@ -2,15 +2,15 @@
 # Interface: XmBrowserConfigOptions
-Defined in: [vitest.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vitest.ts#L174)
+Defined in: [vitest.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vitest.ts#L180)
 Options for [defineXmBrowserConfig](../functions/defineXmBrowserConfig.md) that live outside the plain
 Vitest config overrides.
 ## Properties
-| Property                                           | Type                                     | Description                                                                                                                                                                                                                                                                                                                 | Defined in                                                                                                      |
-| -------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vitest.ts#L182) |
-| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vitest.ts#L189) |
-| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:195](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vitest.ts#L195) |
+| Property                                           | Type                                     | Description                                                                                                                                                                                                                                                                                                                 | Defined in                                                                                                           |
+| -------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:188](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vitest.ts#L188) |
+| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:195](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vitest.ts#L195) |
+| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:201](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/shared/config/vitest.ts#L201) |

package/contributing/configuration.md CHANGED Viewed

@@ -20,33 +20,6 @@ The dev container currently defines no workspace-specific environment variables;
 **Defined in:** the `test:dist` and `test:browser:dist` scripts of the root `package.json`. **Read by:** `xmTestTarget` of [`@xmachines/shared/vite-aliases`](../api/@xmachines/shared/README.md), which every config helper of that package calls. Do not set it by hand: run `pnpm run test:dist`. See [testing.md](testing.md#tests-on-the-build-output).
-### CI / Release Pipeline Variable
-| Variable            | Required | Default                      | Description                                                                                                                                                                         |
-| ------------------- | -------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `SEMREL_SKIP_STEPS` | Optional | `""` (empty — run all steps) | A single RegExp string matched against every semantic-release plugin step ID. Use `\|` for alternation to skip multiple steps. Set via the GitLab "Run pipeline" UI or API trigger. |
-**Defined in:** `.gitlab-ci.yml`, consumed by `release.config.mjs`.
-**Examples:**
-A step ID is the name of the plugin, and a name that the entry declares extends it: `@semantic-release/exec:build`.
-```bash
-# Skip one prepare step
-SEMREL_SKIP_STEPS="@semantic-release/exec:build$"
-# Skip every prepare step
-SEMREL_SKIP_STEPS="@semantic-release/exec"
-# Leave CHANGELOG.md alone
-SEMREL_SKIP_STEPS="@semantic-release/changelog"
-```
-A pattern that removes `@semantic-release/git` throws instead of running: semantic-release would still tag and push, and the tag would then name a commit that carries no version bump.
-The variable reaches the publish never. `scripts/publish-release.mjs` runs on the tag pipeline, outside semantic-release — see [deployment.md](deployment.md).
 ---
 ## Configuration Files
@@ -420,40 +393,42 @@ Provides the helpers used in all `vitest.config.ts` and `vite.config.ts` files:
 **Location:** `/release.config.mjs`
 **Tool:** [semantic-release](https://semantic-release.gitbook.io/) via `@semantic-release/*` plugins
-Defines the release branches and plugin chain used by the GitLab CI semantic-release job.
+Defines the trains, the release branches, and the plugins of each run: the run of a branch, of the `semantic-release` job of a train, and the run of a tag, of the `publish-release` job. The `to-be-continuous` semantic-release component turns it into `.releaserc.json` and installs each plugin it names, so it is literals: no import of a plugin, no top-level await.
 **Release branches:**
 | Branch  | Channel   | Pre-release |
 | ------- | --------- | ----------- |
 | `main`  | (default) | No          |
+| `next`  | `next`    | `next`      |
 | `rc`    | `rc`      | `rc`        |
 | `beta`  | `beta`    | `true`      |
 | `alpha` | `alpha`   | `alpha`     |
 | `pre`   | `pre`     | `pre`       |
-Only `main` is a protected branch today. That works because `GITLAB_TOKEN` — which the release needs, since `CI_JOB_TOKEN` can push neither the release commit nor the tag — is an _unprotected_ group variable and so reaches every one of these refs. If it is ever made protected, each of these branches has to be protected too, or the release fails in verify-conditions with `EGITNOPERMISSION` rather than at the registry.
+`GITLAB_TOKEN`, which the release needs (`CI_JOB_TOKEN` can push neither the release commit nor the tag, and creates no GitLab release), is a _protected_ group variable: it reaches only protected branches and protected tags. Every release branch is protected, `main` and the prerelease branches alike, and so are the tags of the trains, `core-v*`, `play-v*` and `docs-v*`. A release branch added to this table has to be protected too, or its release fails in verify-conditions with `EGITNOPERMISSION`.
+**Trains:** `core` (`packages/core`), `play` (`packages/play`, `packages/play-*`) and `docs` (`packages/docs`, with every file of `core` and `play` counting for it too). The build files of the root and `packages/shared` count for every train.
-**Tag format:** `v${version}`
+**Tag format:** `<train>-v${version}`, as `play-v7.1.0`.
-**Plugin order:**
+**Plugin order of a branch's run:**
-1. `@semantic-release/commit-analyzer` — determines version bump from conventional commits
-2. `@semantic-release/release-notes-generator` — builds release notes
-3. `@semantic-release/changelog` — writes `CHANGELOG.md`
-4. `@semantic-release/exec` steps (in order):
+1. `@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator`, each wrapped by an entry of `@wtf/semantic-release-trains` (`wrap`) — the version bump and the notes, of the train's commits alone; each entry of the trains plugin also checks the trains
+2. `@semantic-release/changelog` — writes the `CHANGELOG.md` of the train's first path
+3. `@wtf/semantic-release-replace` — writes the version into the badge of each README of the train, by the `badge` template at the root of the config
+4. Of `docs` alone, `@semantic-release/exec` steps (in order):
     - `corepack` — `corepack enable`
     - `install` — `pnpm install --frozen-lockfile`
-    - `set-workspace-versions` — updates all `package.json` files to the new version
     - `build` — `pnpm run build`
-    - `typedoc` — `pnpm --filter @xmachines/docs run typedoc`
+    - `typedoc` — `pnpm --filter @xmachines/docs run typedoc --gitRevision docs-v${nextRelease.version}`
     - `format-docs` — `pnpm --filter @xmachines/docs run format`
-    - `stage-generated-docs` — `git add -A packages/docs/api packages/docs/examples/@xmachines packages/docs/examples/README.md`, so a page that TypeDoc deleted leaves git too
-5. `@semantic-release/git` — commits the changelog, the manifests, the READMEs and the generated docs (`api/`, `examples/@xmachines/` and the demo lists of `examples/README.md`), then pushes the commit and the tag
-The list ends there. semantic-release publishes nothing and creates no GitLab release: `scripts/publish-release.mjs` does both, on the pipeline of the tag. [deployment.md](deployment.md) states the whole sequence and the reason.
+    then an entry of `@wtf/semantic-release-trains` of `generated: true`, which stages the trees that TypeDoc writes, so a page that TypeDoc deleted leaves git too
+5. `@semantic-release/git` — commits the changelog, the READMEs of the train, and of `docs` the generated docs (`api/`, `examples/@xmachines/` and the demo lists of `examples/README.md`), then pushes the commit and the tag
-Any step above can be skipped with the `SEMREL_SKIP_STEPS` CI variable, which the CI / Release Pipeline Variable section at the top of this page states.
+**Plugin order of a tag's run:** the notes generator on the train; `@wtf/semantic-release-trains-publish`, which packs, smoke-tests and publishes the train's packages and packs its demos; `@semantic-release/gitlab`, the GitLab release with the tarballs. [deployment.md](deployment.md) states the whole sequence and the reason.
 ---
@@ -487,15 +462,14 @@ The only environment-specific distinction is between **local development** (dev
 ## Required vs Optional Settings Summary
-| Config                                                                     | Required to Work                        | Optional / Has Default        |
-| -------------------------------------------------------------------------- | --------------------------------------- | ----------------------------- |
-| `SEMREL_SKIP_STEPS`                                                        | No                                      | Default: `""` (run all steps) |
-| Root `tsconfig.json` `references`                                          | Yes — the whole build order             | —                             |
-| Per-package `references`                                                   | No — TypeScript drops them on `extends` | —                             |
-| Per-package `composite: true`                                              | Yes — required for project references   | —                             |
-| [`@xmachines/shared/tsconfig`](../api/@xmachines/shared/README.md) extends | Yes — all packages must extend it       | —                             |
-| [`@xmachines/shared/oxlint`](../api/@xmachines/shared/README.md) extends   | Yes — all packages must extend it       | —                             |
-| [`@xmachines/shared/oxfmt`](../api/@xmachines/shared/README.md) extends    | Yes — all packages must extend it       | —                             |
+| Config                                                                     | Required to Work                        | Optional / Has Default |
+| -------------------------------------------------------------------------- | --------------------------------------- | ---------------------- |
+| Root `tsconfig.json` `references`                                          | Yes — the whole build order             | —                      |
+| Per-package `references`                                                   | No — TypeScript drops them on `extends` | —                      |
+| Per-package `composite: true`                                              | Yes — required for project references   | —                      |
+| [`@xmachines/shared/tsconfig`](../api/@xmachines/shared/README.md) extends | Yes — all packages must extend it       | —                      |
+| [`@xmachines/shared/oxlint`](../api/@xmachines/shared/README.md) extends   | Yes — all packages must extend it       | —                      |
+| [`@xmachines/shared/oxfmt`](../api/@xmachines/shared/README.md) extends    | Yes — all packages must extend it       | —                      |
 ---