npm - @stealthscale/vite-config-specimen - Versions diffs - 0.0.0-stage → 0.2.1 - Mend

@stealthscale/vite-config-specimen 0.0.0-stage → 0.2.1

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 (6) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Stealth Scale B.V.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# @stealthscale/vite-config-specimen
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@stealthscale/vite-config-specimen` configures the three places a specimen is read from: the
+package that holds one, the application that shows a catalogue of them, and the workspace root they
+sit under.
+## Install
+```bash
+pnpm add -D @stealthscale/vite-config-specimen
+```
+The package peers on `@stealthscale/vite-plugin-specimen`, `@stealthscale/vite-config`,
+`@stealthscale/vite-config-core` and `vite`.
+## A package that holds specimens
+Add `specimen.layers()` to whichever tier the package already builds on.
+```ts
+import * as react from "@stealthscale/vite-config-react";
+import * as specimen from "@stealthscale/vite-config-specimen";
+import * as theme from "@stealthscale/vite-config-theme";
+import { defineConfig } from "@stealthscale/vite-config/preset/web";
+export default defineConfig(import.meta.dirname, {
+  extends: [react.layers(), theme.layers(), specimen.layers()],
+});
+```
+It stops counting `**/*.specimen.tsx` towards the package's coverage. A specimen declares a page for
+the catalogue to draw rather than behaviour to assert, so it is an entry point in the way an
+application's `main` is. A package that keeps its specimens elsewhere names its own globs:
+`specimen.layers(["src/pages/**/*.specimen.tsx"])`.
+The package's example spec renders each `**/*.example.tsx` file without pressing a control, so
+`layers()` excludes those files from coverage too. Their event handlers would otherwise count as
+uncovered functions.
+## An application that shows a catalogue
+Add `specimen.catalogue()` to whichever tier the application already builds on.
+```ts
+import * as react from "@stealthscale/vite-config-react";
+import * as specimen from "@stealthscale/vite-config-specimen";
+import { defineConfig } from "@stealthscale/vite-config/preset/app";
+export default defineConfig(import.meta.dirname, {
+  extends: [
+    react.layers(),
+    specimen.catalogue({ patterns: ["../../components/*/src/**/*.specimen.tsx"] }),
+  ],
+});
+```
+`patterns` has no default. A pattern resolves against the application root, and an application that
+shows a catalogue of a workspace's components sits beside those components rather than above them.
+State `props` to have each page carry what its components accept, resolved out of their types. Left
+out, nothing loads a compiler. Every member of `Options` reaches the plugin as written, and the
+plugin's README documents what a page then gets.
+`catalogue()` adds the index plugin, and every specimen as an entry the dependency scan walks before
+the server starts. A specimen is reached through a dynamic import the scan does not follow, so
+without the entries the first page a reader opens re-optimises and reloads the catalogue.
+Naming the entries stops Vite working the entries out for itself, which is why `**/*.html` is named
+beside them.
+## The stylesheet a catalogue needs
+An application drawn on `@stealthscale/theme` states `static: "*"` in its `theme.config.ts`.
+```ts
+export default { static: "*", themes: [graphite] } satisfies Application;
+```
+The compiler extracts a value written as a JSX literal and nothing it reads from a prop. A scene
+draws its axis as `<Button variant={one}>`, so without this the compiler emits no rule for any value
+a matrix draws, and the page renders every look, size and status identically.
+Measured on the button: 21 recipe classes reach the page and 7 have rules until `static` is set. A
+product application states nothing and ships only the rules its own source asks for.
+## The workspace root
+Add `specimen.workspace()` to the root configuration.
+```ts
+import * as specimen from "@stealthscale/vite-config-specimen";
+import { defineConfig } from "./packages/vite-config/src/preset/workspace.ts";
+export default defineConfig(import.meta.dirname, { extends: [specimen.workspace()] });
+```
+The linter runs from the workspace root and reads the root's configuration and no other, so a
+relaxation stated in a package would compose, merge, and never be read.
+Four rules come off `**/*.specimen.tsx`:
+| Rule                           | Why                                                              |
+| ------------------------------ | ---------------------------------------------------------------- |
+| `no-default-export`            | A specimen is read through its default export                    |
+| Doc comments and the size caps | A specimen is as long as the scenes it takes to show a component |
+| `react/only-export-components` | The default export is a page description, not a component        |
+| `react/no-multi-comp`          | A scene is built from the components that arrange it             |
+Pass a list to cover different files: `workspace(["components/**/*.specimen.tsx"])`.
+The root also excludes `**/*.example.tsx` from coverage and turns the doc comment rules off for it.
+The catalogue shows an example file verbatim as the Source of a scene, so a doc comment would end up
+in the code a consumer copies.
+## Licence
+MIT. See [LICENSE](LICENSE).

package/dist/cyclonedx/bom.json ADDED Viewed

@@ -0,0 +1 @@

+ {"$schema":"http://cyclonedx.org/schema/bom-1.7.schema.json","bomFormat":"CycloneDX","specVersion":"1.7","version":1,"metadata":{"lifecycles":[{"phase":"build"}],"tools":{"components":[{"type":"application","name":"rolldown","version":"1.2.12"},{"type":"application","name":"vite","version":"8.3.3"},{"type":"library","name":"core","group":"@arethetypeswrong","version":"0.18.5","bom-ref":"pkg:npm/%40arethetypeswrong/core@0.18.5","author":"Andrew Branch","description":"The API behind arethetypeswrong.github.io","hashes":[{"alg":"SHA-512","content":"f72b63cc6c318e6f54cfb23d6af7dbb79be542deae93db914444b3263aabce797a58abc8e9dc184e8faf277534d96aeafe64778aa97f3f386f1e129d2480230d"}],"licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40arethetypeswrong/core@0.18.5","externalReferences":[{"url":"https://github.com/arethetypeswrong/arethetypeswrong.github.io.git#packages/core","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=20"}]},{"type":"library","name":"testing-config","group":"@stealthscale","version":"0.6.0","bom-ref":"pkg:npm/%40stealthscale/testing-config@0.6.0","description":"Lists every part of the house contract a config, plugin or library package breaks.","licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40stealthscale/testing-config@0.6.0","externalReferences":[{"url":"https://github.com/stealth-scale/scale/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs\""},{"url":"git+https://github.com/stealth-scale/scale.git#packages/testing-config","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://github.com/stealth-scale/scale/tree/main/packages/testing-config#readme","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=26.0.0"}]},{"type":"library","name":"vite-config-core","group":"@stealthscale","version":"0.4.0","bom-ref":"pkg:npm/%40stealthscale/vite-config-core@0.4.0","description":"Composes presets, contributions, removals and overrides into one Vite configuration.","licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40stealthscale/vite-config-core@0.4.0","externalReferences":[{"url":"https://github.com/stealth-scale/scale/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs\""},{"url":"git+https://github.com/stealth-scale/scale.git#packages/vite-config-core","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://github.com/stealth-scale/scale/tree/main/packages/vite-config-core#readme","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=26.0.0"}]},{"type":"library","name":"vite-config-typescript","group":"@stealthscale","version":"0.3.0","bom-ref":"pkg:npm/%40stealthscale/vite-config-typescript@0.3.0","description":"Sets the TypeScript options every stealthscale package compiles with.","licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40stealthscale/vite-config-typescript@0.3.0","externalReferences":[{"url":"https://github.com/stealth-scale/scale/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs\""},{"url":"git+https://github.com/stealth-scale/scale.git#packages/vite-config-typescript","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://github.com/stealth-scale/scale/tree/main/packages/vite-config-typescript#readme","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=26.0.0"}]},{"type":"library","name":"vite-config","group":"@stealthscale","version":"0.8.0","bom-ref":"pkg:npm/%40stealthscale/vite-config@0.8.0","description":"Configures a package from five Vite+ tiers and a named layer for every block.","licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40stealthscale/vite-config@0.8.0","externalReferences":[{"url":"https://github.com/stealth-scale/scale/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs\""},{"url":"git+https://github.com/stealth-scale/scale.git#packages/vite-config","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://github.com/stealth-scale/scale/tree/main/packages/vite-config#readme","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=26.0.0"}]},{"type":"library","name":"vite-plugin-specimen","group":"@stealthscale","version":"0.2.1","bom-ref":"pkg:npm/%40stealthscale/vite-plugin-specimen@0.2.1","description":"Indexes specimen files from their source, so a catalogue lists every page without loading one.","licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40stealthscale/vite-plugin-specimen@0.2.1","externalReferences":[{"url":"https://github.com/stealth-scale/scale/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs\""},{"url":"git+https://github.com/stealth-scale/scale.git#packages/vite-plugin-specimen","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://github.com/stealth-scale/scale/tree/main/packages/vite-plugin-specimen#readme","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=26.0.0"}]},{"type":"library","name":"node","group":"@types","version":"26.6.4","bom-ref":"pkg:npm/%40types/node@26.6.4","description":"TypeScript definitions for node","hashes":[{"alg":"SHA-512","content":"95d54f0c2ce3edfb1a199acb07436e1ee4ef25cb0d6accac040a8ca25aff720c6b2ddd716eac48af75c988f9c71c9502c63e6c345d6f9d18fd6969eb561e4972"}],"licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40types/node@26.6.4","externalReferences":[{"url":"https://github.com/DefinitelyTyped/DefinitelyTyped.git#types/node","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node","type":"website","comment":"as detected from PackageJson property \"homepage\""}]},{"type":"library","name":"coverage-v8","group":"@vitest","version":"5.0.3","bom-ref":"pkg:npm/%40vitest/coverage-v8@5.0.3","author":"Anthony Fu <anthonyfu117@hotmail.com>","description":"V8 coverage provider for Vitest","hashes":[{"alg":"SHA-512","content":"fa496ccb3ec1bd3d6f094dbc6647f39acd486bbf170f4578d54dc552d45a6b74bebceaff117bcad4ee81bd50fb9754731239ba48e351d9ac9b3af0c37fdbb499"}],"licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40vitest/coverage-v8@5.0.3","externalReferences":[{"url":"https://github.com/vitest-dev/vitest/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs.url\""},{"url":"git+https://github.com/vitest-dev/vitest.git#packages/coverage-v8","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://vitest.dev/guide/coverage","type":"website","comment":"as detected from PackageJson property \"homepage\""}]},{"type":"library","name":"vite-plus-core","group":"@voidzero-dev","version":"1.1.0","bom-ref":"pkg:npm/%40voidzero-dev/vite-plus-core@1.1.0","author":"VoidZero Inc.","description":"The Unified Toolchain for the Web","licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40voidzero-dev/vite-plus-core@1.1.0","externalReferences":[{"url":"https://github.com/voidzero-dev/vite-plus/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs.url\""},{"url":"git+https://github.com/voidzero-dev/vite-plus.git#packages/core","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://viteplus.dev/guide","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":"^20.19.0 || ^22.18.0 || >=24.11.0"}]},{"type":"library","name":"typescript","version":"7.0.2","bom-ref":"pkg:npm/typescript@7.0.2","author":"Microsoft Corp.","description":"TypeScript is a language for application scale JavaScript development","hashes":[{"alg":"SHA-512","content":"f0561abbdea8dcd28e85b8ca8bfa8dbc6fd6e63873c646dd9b9b23f406d9ff94f9b16aa7de12602df1b1dbbb11299593bf2cc23fc74b4414dfe6d05349155434"}],"licenses":[{"license":{"id":"Apache-2.0"}}],"purl":"pkg:npm/typescript@7.0.2","externalReferences":[{"url":"https://github.com/microsoft/TypeScript/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs.url\""},{"url":"https://github.com/microsoft/TypeScript.git","type":"vcs","comment":"as detected from PackageJson property \"repository.url\""},{"url":"https://www.typescriptlang.org/","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=16.20.0"}]},{"type":"library","name":"vitest","version":"5.0.3","bom-ref":"pkg:npm/vitest@5.0.3","author":"Anthony Fu <anthonyfu117@hotmail.com>","description":"Next generation testing framework powered by Vite","hashes":[{"alg":"SHA-512","content":"c4cc3ded2deb8ddb63e5d9156adee30aca96069bdc86cdd196941cb54ab0243d0a904464e34bf3d9f27bee50f05bf57387fa64d7c788b5803392876149eb378d"}],"licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/vitest@5.0.3","externalReferences":[{"url":"https://github.com/vitest-dev/vitest/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs.url\""},{"url":"git+https://github.com/vitest-dev/vitest.git#packages/vitest","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://vitest.dev","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":"^22.12.0 || ^24.0.0 || >=26.0.0"}]}]},"component":{"type":"library","name":"vite-config-specimen","group":"@stealthscale","version":"0.2.1","bom-ref":"pkg:npm/%40stealthscale/vite-config-specimen@0.2.1","description":"Configures an application that shows a catalogue, and the workspace root the specimens sit under.","licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40stealthscale/vite-config-specimen@0.2.1","externalReferences":[{"url":"https://github.com/stealth-scale/scale/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs\""},{"url":"git+https://github.com/stealth-scale/scale.git#packages/vite-config-specimen","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://github.com/stealth-scale/scale/tree/main/packages/vite-config-specimen#readme","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=26.0.0"}],"evidence":{"licenses":[{"license":{"name":"file: LICENSE","text":{"content":"TUlUIExpY2Vuc2UKCkNvcHlyaWdodCAoYykgMjAyNiBTdGVhbHRoIFNjYWxlIEIuVi4KClBlcm1pc3Npb24gaXMgaGVyZWJ5IGdyYW50ZWQsIGZyZWUgb2YgY2hhcmdlLCB0byBhbnkgcGVyc29uIG9idGFpbmluZyBhIGNvcHkKb2YgdGhpcyBzb2Z0d2FyZSBhbmQgYXNzb2NpYXRlZCBkb2N1bWVudGF0aW9uIGZpbGVzICh0aGUgIlNvZnR3YXJlIiksIHRvIGRlYWwKaW4gdGhlIFNvZnR3YXJlIHdpdGhvdXQgcmVzdHJpY3Rpb24sIGluY2x1ZGluZyB3aXRob3V0IGxpbWl0YXRpb24gdGhlIHJpZ2h0cwp0byB1c2UsIGNvcHksIG1vZGlmeSwgbWVyZ2UsIHB1Ymxpc2gsIGRpc3RyaWJ1dGUsIHN1YmxpY2Vuc2UsIGFuZC9vciBzZWxsCmNvcGllcyBvZiB0aGUgU29mdHdhcmUsIGFuZCB0byBwZXJtaXQgcGVyc29ucyB0byB3aG9tIHRoZSBTb2Z0d2FyZSBpcwpmdXJuaXNoZWQgdG8gZG8gc28sIHN1YmplY3QgdG8gdGhlIGZvbGxvd2luZyBjb25kaXRpb25zOgoKVGhlIGFib3ZlIGNvcHlyaWdodCBub3RpY2UgYW5kIHRoaXMgcGVybWlzc2lvbiBub3RpY2Ugc2hhbGwgYmUgaW5jbHVkZWQgaW4gYWxsCmNvcGllcyBvciBzdWJzdGFudGlhbCBwb3J0aW9ucyBvZiB0aGUgU29mdHdhcmUuCgpUSEUgU09GVFdBUkUgSVMgUFJPVklERUQgIkFTIElTIiwgV0lUSE9VVCBXQVJSQU5UWSBPRiBBTlkgS0lORCwgRVhQUkVTUyBPUgpJTVBMSUVELCBJTkNMVURJTkcgQlVUIE5PVCBMSU1JVEVEIFRPIFRIRSBXQVJSQU5USUVTIE9GIE1FUkNIQU5UQUJJTElUWSwKRklUTkVTUyBGT1IgQSBQQVJUSUNVTEFSIFBVUlBPU0UgQU5EIE5PTklORlJJTkdFTUVOVC4gSU4gTk8gRVZFTlQgU0hBTEwgVEhFCkFVVEhPUlMgT1IgQ09QWVJJR0hUIEhPTERFUlMgQkUgTElBQkxFIEZPUiBBTlkgQ0xBSU0sIERBTUFHRVMgT1IgT1RIRVIKTElBQklMSVRZLCBXSEVUSEVSIElOIEFOIEFDVElPTiBPRiBDT05UUkFDVCwgVE9SVCBPUiBPVEhFUldJU0UsIEFSSVNJTkcgRlJPTSwKT1VUIE9GIE9SIElOIENPTk5FQ1RJT04gV0lUSCBUSEUgU09GVFdBUkUgT1IgVEhFIFVTRSBPUiBPVEhFUiBERUFMSU5HUyBJTiBUSEUKU09GVFdBUkUuCg==","contentType":"text/plain","encoding":"base64"}}}]}},"supplier":{"name":"Stealth Scale B.V.","url":["https://stealthscale.io"]}},"components":[],"dependencies":[{"ref":"pkg:npm/%40stealthscale/vite-config-specimen@0.2.1"}]}

package/dist/index.d.mts ADDED Viewed

@@ -0,0 +1,64 @@
+import { Contribution, Layer } from "@stealthscale/vite-config-core";
+import { Options } from "@stealthscale/vite-plugin-specimen";
+//#region src/catalogue.d.ts
+/**
+ * Returns the index layer and the crawl layers, in the order they run.
+ *
+ * @remarks
+ *   An array and not a tier, because a catalogue is an ordinary application first: it picks the
+ *   tier its framework calls for, and these layers extend it.
+ * @param stated - Where the specimens are. `Options` documents every member.
+ */
+export declare function catalogue(stated: Options): readonly Layer[];
+//#endregion
+//#region src/crawled.d.ts
+/**
+ * Appends every specimen, and the application's own HTML, to the dependency scan's entries.
+ *
+ * @remarks
+ *   A specimen is reached from the index through a dynamic import of a file outside the project
+ *   root, and the scan follows neither. Left out, the first page a reader opens discovers its
+ *   dependencies, re-optimises, and reloads the whole catalogue. Naming the entries disables Vite's
+ *   own inference, which is why the HTML is named again beside them.
+ * @param patterns - Where the specimens are, as the plugin's options state them.
+ */
+export declare function crawled(patterns: readonly string[]): readonly Contribution[];
+//#endregion
+//#region src/indexed.d.ts
+/**
+ * Appends `specimens()` to the plugins of an application that shows a catalogue.
+ *
+ * @remarks
+ *   The plugin package is loaded when the plugin is constructed and not when the layer is stated,
+ *   so reading the configuration for its metadata loads neither the plugin nor the compiler
+ *   behind it. Each composition constructs a plugin instance of its own.
+ * @param stated - Where the specimens are. `Options` documents every member.
+ */
+export declare function indexed(stated: Options): Contribution;
+//#endregion
+//#region src/layers.d.ts
+/**
+ * Returns the coverage exclusions for the specimen and example files of a package.
+ *
+ * @remarks
+ *   The function returns a layer list, not a tier, so a component package can add it to whichever
+ *   tier its framework requires. Lint exemptions are declared at the workspace root through
+ *   `workspace()`, because the linter reads only the root config.
+ * @param files - Specimen globs. Defaults to every `*.specimen.tsx` file in the package.
+ */
+export declare function layers(files?: readonly string[]): readonly Layer[];
+//#endregion
+//#region src/workspace.d.ts
+/**
+ * Returns the layers the workspace root declares for specimen and example files.
+ *
+ * @remarks
+ *   The coverage exclusions duplicate the per-package ones, because the root run counts the files
+ *   of every package. Specimen files are exempt from `no-default-export`, the doc comment rules,
+ *   `react/only-export-components` and `react/no-multi-comp`. Example files are exempt from the doc
+ *   comment rules and the dependency cap. Each layer records its reason in `because`.
+ * @param files - Specimen globs. Defaults to every `*.specimen.tsx` file in the workspace.
+ */
+export declare function workspace(files?: readonly string[]): readonly Layer[];
+//#endregion
+export type { Options };

package/dist/index.mjs ADDED Viewed

@@ -0,0 +1,235 @@
+import { contribute, located, named } from "@stealthscale/vite-config-core";
+import { deps, lint, test } from "@stealthscale/vite-config";
+//#region src/specimens.ts
+/**
+* Names the files every layer of this package treats as specimens, and renames a contribution a
+* layer borrows from the base configuration after this package.
+*/
+/**
+* The files the linter and the runner treat as specimens, unless a caller names others.
+*/
+const SPECIMENS = ["**/*.specimen.tsx"];
+/**
+* Renames a contribution borrowed from the base configuration, so its layer name identifies this
+* package and the call a consumer wrote.
+*
+* @param contribution - The contribution as the base configuration built it.
+* @param from - The base call's name, as it opens the contribution's name.
+* @param to - This package's name for it.
+* @returns The contribution under the new name.
+*/
+function renamed(contribution, from, to) {
+	return named(contribution.name.replace(from, to), contribution);
+}
+//#endregion
+//#region src/crawled.ts
+/**
+* Adds the specimens to the entries the dependency scan walks before a server starts serving.
+*/
+/**
+* Appends every specimen, and the application's own HTML, to the dependency scan's entries.
+*
+* @remarks
+*   A specimen is reached from the index through a dynamic import of a file outside the project
+*   root, and the scan follows neither. Left out, the first page a reader opens discovers its
+*   dependencies, re-optimises, and reloads the whole catalogue. Naming the entries disables Vite's
+*   own inference, which is why the HTML is named again beside them.
+* @param patterns - Where the specimens are, as the plugin's options state them.
+*/
+function crawled(patterns) {
+	return deps.crawl({
+		because: "a specimen is reached through a dynamic import the dependency scan does not follow, so its dependencies would be discovered by the first page opened and cost a reload",
+		files: ["**/*.html", ...patterns]
+	}).map((contribution) => renamed(contribution, "deps.crawl", "specimen.crawled"));
+}
+//#endregion
+//#region src/loaded.ts
+/**
+* Defers loading the specimen plugin until a plugin is constructed, rather than when the
+* configuration is read.
+*
+* @remarks
+*   Vite bundles a configuration file before running it, and the bundler resolves every import it
+*   can see, a dynamic import with a literal specifier included. If the plugin package has not
+*   been built yet, that resolution fails and the configuration cannot be read at all, not even to
+*   build the task graph that would build the package. Holding the specifier in a variable puts it
+*   out of the bundler's reach, so Node resolves it at call time, relative to this module wherever
+*   it ends up running from.
+*/
+/**
+* The plugin package specifier, held in a variable so the bundler cannot resolve it statically.
+*/
+const PLUGIN = "@stealthscale/vite-plugin-specimen";
+/**
+* Imports the specimen plugin package.
+*
+* @throws {@link Error} When the plugin package has not been built yet.
+*/
+function loaded() {
+	return import(located(PLUGIN, import.meta.url));
+}
+//#endregion
+//#region src/indexed.ts
+/**
+* Adds the specimen plugin to the plugins a tier already built.
+*/
+/**
+* The configuration key the plugin joins.
+*/
+const AT = "plugins";
+/**
+* Appends `specimens()` to the plugins of an application that shows a catalogue.
+*
+* @remarks
+*   The plugin package is loaded when the plugin is constructed and not when the layer is stated,
+*   so reading the configuration for its metadata loads neither the plugin nor the compiler
+*   behind it. Each composition constructs a plugin instance of its own.
+* @param stated - Where the specimens are. `Options` documents every member.
+*/
+function indexed(stated) {
+	return contribute({
+		at: AT,
+		because: "a catalogue lists every page before it loads one, which needs each specimen's metadata parsed out of the source rather than read off a module that has run",
+		itemOf: async () => (await loaded()).specimens(stated),
+		name: "specimen.indexed"
+	});
+}
+//#endregion
+//#region src/catalogue.ts
+/**
+* Returns the index layer and the crawl layers, in the order they run.
+*
+* @remarks
+*   An array and not a tier, because a catalogue is an ordinary application first: it picks the
+*   tier its framework calls for, and these layers extend it.
+* @param stated - Where the specimens are. `Options` documents every member.
+*/
+function catalogue(stated) {
+	return [indexed(stated), ...crawled(stated.patterns)];
+}
+//#endregion
+//#region src/examples.ts
+/**
+* Exempts example files from coverage, from the doc comment rules and from the dependency cap.
+*
+* @remarks
+*   Example files are the code consumers copy, and the catalogue shows them verbatim, so doc
+*   comments would end up in the copied code. The example spec of each package renders its examples
+*   without interacting with them, so event handlers would count as uncovered functions. An example
+*   of a whole screen imports every package the screen is built from.
+*/
+/**
+* Glob matching example files.
+*/
+const EXAMPLES = ["**/*.example.tsx"];
+/**
+* Returns the coverage exclusion for example files.
+*
+* @param files - Example globs. Defaults to {@link EXAMPLES}.
+*/
+function unmeasured(files = EXAMPLES) {
+	return test.omit({
+		because: "an example is the code a consumer copies, and its specification renders it without pressing a control",
+		files
+	}).map((contribution) => renamed(contribution, "test.omit", "specimen.example.uncounted"));
+}
+/**
+* Returns the lint layer that disables the doc comment rules for example files.
+*
+* @param files - Example globs. Defaults to {@link EXAMPLES}.
+*/
+function undescribed(files = EXAMPLES) {
+	return named("specimen.example.undocumented", lint.undocumented(files));
+}
+/**
+* Returns the lint layer that disables the dependency cap for example files.
+*
+* @remarks
+*   An example of an application shell renders a whole screen, and each region of the screen comes
+*   from its own package. Its dependency count is the number of packages the screen is built from,
+*   and one module per package would move the composition out of the file the catalogue shows.
+*   Only `import/max-dependencies` comes off.
+* @param files - Example globs. Defaults to {@link EXAMPLES}.
+*/
+function uncapped(files = EXAMPLES) {
+	return named("specimen.example.composed", lint.relax({
+		because: "an example renders a whole screen from the packages it is built from, and the catalogue shows the one file",
+		files: [...files],
+		rules: { "import/max-dependencies": "off" }
+	}));
+}
+//#endregion
+//#region src/uncounted.ts
+/**
+* Stops counting the specimens a package holds towards its coverage.
+*/
+/**
+* Stops counting each specimen towards the coverage its package is held to.
+*
+* @remarks
+*   A specimen is an entry point the catalogue loads, like the `main` of an application, and it
+*   declares a page rather than behaviour to assert. Counted, every specimen would sit at nothing
+*   until somebody wrote a specification for a page description.
+* @param files - Which files are specimens. Defaults to any `*.specimen.tsx` in the package.
+*/
+function uncounted(files = SPECIMENS) {
+	return test.omit({
+		because: "a specimen declares a page for the catalogue to draw rather than behaviour to assert, so it is an entry point in the way an application's main is",
+		files
+	}).map((contribution) => renamed(contribution, "test.omit", "specimen.uncounted"));
+}
+//#endregion
+//#region src/layers.ts
+/**
+* Returns the coverage exclusions for the specimen and example files of a package.
+*
+* @remarks
+*   The function returns a layer list, not a tier, so a component package can add it to whichever
+*   tier its framework requires. Lint exemptions are declared at the workspace root through
+*   `workspace()`, because the linter reads only the root config.
+* @param files - Specimen globs. Defaults to every `*.specimen.tsx` file in the package.
+*/
+function layers(files = SPECIMENS) {
+	return [...uncounted(files), ...unmeasured()];
+}
+//#endregion
+//#region src/workspace.ts
+/**
+* Lint and coverage layers the workspace root declares for specimen and example files.
+*
+* @remarks
+*   The layers belong in the root config, not in the catalogue application. The linter reads only
+*   the root config, so a relaxation declared elsewhere is merged but never applied.
+*/
+/**
+* Returns the layers the workspace root declares for specimen and example files.
+*
+* @remarks
+*   The coverage exclusions duplicate the per-package ones, because the root run counts the files
+*   of every package. Specimen files are exempt from `no-default-export`, the doc comment rules,
+*   `react/only-export-components` and `react/no-multi-comp`. Example files are exempt from the doc
+*   comment rules and the dependency cap. Each layer records its reason in `because`.
+* @param files - Specimen globs. Defaults to every `*.specimen.tsx` file in the workspace.
+*/
+function workspace(files = SPECIMENS) {
+	return [
+		...uncounted(files),
+		named("specimen.exported", lint.defaultExported(files)),
+		named("specimen.undocumented", lint.undocumented(files)),
+		named("specimen.described", lint.relax({
+			because: "a specimen's default export is a page description rather than a component, and the rule is a fast refresh convention that reads it as an anonymous one",
+			files: [...files],
+			rules: { "react/only-export-components": "off" }
+		})),
+		named("specimen.composed", lint.relax({
+			because: "a scene is built from the small components that arrange it, each drawn once beside the caption explaining it, and splitting them into files of their own puts every piece further from the picture it is part of",
+			files: [...files],
+			rules: { "react/no-multi-comp": "off" }
+		})),
+		...unmeasured(),
+		undescribed(),
+		uncapped()
+	];
+}
+//#endregion
+export { catalogue, crawled, indexed, layers, workspace };

package/package.json CHANGED Viewed

@@ -1,6 +1,63 @@
 {
   "name": "@stealthscale/vite-config-specimen",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "description": "Configures an application that shows a catalogue, and the workspace root the specimens sit under.",
+  "keywords": [
+    "catalogue",
+    "specimen",
+    "vite-config"
+  ],
+  "homepage": "https://github.com/stealth-scale/scale/tree/main/packages/vite-config-specimen#readme",
+  "bugs": "https://github.com/stealth-scale/scale/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stealth-scale/scale.git",
+    "directory": "packages/vite-config-specimen"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#*": "./src/*"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "^0.18",
+    "@stealthscale/testing-config": "^0.6.0",
+    "@stealthscale/vite-config": "^0.8.0",
+    "@stealthscale/vite-config-core": "^0.4.0",
+    "@stealthscale/vite-config-typescript": "^0.3.0",
+    "@stealthscale/vite-plugin-specimen": "^0.2.1",
+    "@types/node": "^26.6",
+    "@vitest/coverage-v8": "5.0.3",
+    "publint": "^0.3",
+    "typescript": "^7.0",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vitest": "5.0.3"
+  },
+  "peerDependencies": {
+    "@stealthscale/vite-config": "^0.8.0",
+    "@stealthscale/vite-config-core": "^0.4.0",
+    "@stealthscale/vite-plugin-specimen": "^0.2.1",
+    "vite": "^8.3"
+  },
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "check": "vp check",
+    "test": "vp test"
+  }
 }