@leyman/configs 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jacob Ley
+
+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

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+<div style="text-align:center">
 
-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.
+# @leyman/configs
+
+Strict shared configs for TypeScript ESM packages: tsconfig bases per Node.js support floor, SWC, c8 at 100% coverage, Biome and Vitest, each consumed by extending or pointing at the installed file.
+
+[![npm package](https://badge.fury.io/js/@leyman%2Fconfigs.svg)](https://www.npmjs.com/package/@leyman/configs)
+[![License](https://img.shields.io/npm/l/@leyman/configs.svg)](https://github.com/JacobLey/leyman/blob/main/leyman/configs/LICENSE)
+
+</div>
+
+- **A tsconfig per support floor** — `tsconfig.node-22.json` and `tsconfig.node-24.json` hold only the `lib` and `target` that Node.js version has, so using a newer API is a compile error, not a crash for users on the oldest supported version.
+- **Strict type checking** — `strict`, `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`, `noImplicitOverride` and more, with declarations emitted for project references.
+- **Tests checked as consumers see them** — `tsconfig.test.json` type-checks tests without emitting, against the package's built declarations.
+- **100% coverage** — c8 fails below 100% of lines, statements, functions and branches.
+- **One formatter config** — Biome formats TypeScript, JSON, Markdown and YAML; linting is left to ESLint ([`@leyman/eslint-config`](https://www.npmjs.com/package/@leyman/eslint-config)).
+
+It is the config of the [leyman](https://github.com/JacobLey/leyman) monorepo, published as-is. Expect it to be strict and to change: see [Versioning](#versioning).
+
+## Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [Files](#files)
+- [Versioning](#versioning)
+
+## Install
+
+```sh
+npm i -D @leyman/configs
+```
+
+The configs are written for TypeScript 6 or newer (the `ES2025` libs), Biome 2.6, c8 12, `@swc/core` 1.16 and Vitest 5. Install the tools you use; none is a dependency.
+
+## Usage
+
+Each package that uses a config installs this package, so its tools find the files in its own `node_modules`.
+
+### TypeScript
+
+`tsconfig.json` extends the config of the package's support floor, the major version of `engines.node`:
+
+```json
+{
+  "extends": "@leyman/configs/tsconfig.node-22.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo"
+  },
+  "include": ["src"]
+}
+```
+
+A package that isn't published, and so has no floor, extends `@leyman/configs/tsconfig.build.json`, which targets `ESNext`. Install `@types/node` with the floor's major version as well, so Node.js's own APIs are held to the floor too.
+
+`test/tsconfig.json` extends the test config and references the package:
+
+```json
+{
+  "extends": "@leyman/configs/tsconfig.test.json",
+  "references": [{ "path": ".." }]
+}
+```
+
+### Biome
+
+`biome.json` extends it:
+
+```json
+{
+  "extends": ["@leyman/configs/biome.base.json"]
+}
+```
+
+Biome resolves the package from the directory of `biome.json`, so the package must be installed there. In a monorepo whose root installs no packages, extend the file by its path instead.
+
+### c8
+
+`.c8rc.json` extends it:
+
+```json
+{
+  "extends": "@leyman/configs/c8rc.json"
+}
+```
+
+Or pass it to c8 directly: `c8 -c node_modules/@leyman/configs/c8rc.json`.
+
+### SWC and Vitest
+
+Neither extends a config from a package, so pass the installed file:
+
+```sh
+swc src -d dist --config-file node_modules/@leyman/configs/swcrc.jsonc
+vitest run --config node_modules/@leyman/configs/vitest.config.js --root .
+```
+
+## Files
+
+| File                    | What it is                                                                                                                                                                                                                                                                  |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tsconfig.build.json`   | Strict compiler options for source, `ESNext`, with `composite` and declarations only (SWC emits the JavaScript). Excludes declarations under `dist`, `coverage` and `nyc`.                                                                                                  |
+| `tsconfig.node-22.json` | `tsconfig.build.json` limited to Node.js 22: `ES2024`, plus the Set methods, iterator helpers and `Array.fromAsync` it has.                                                                                                                                                 |
+| `tsconfig.node-24.json` | `tsconfig.build.json` limited to Node.js 24: `ES2025`, plus `Array.fromAsync`, `using` with `DisposableStack`, and `Error.isError`.                                                                                                                                         |
+| `tsconfig.test.json`    | `tsconfig.build.json` without emitting or `composite`, for tests.                                                                                                                                                                                                           |
+| `swcrc.jsonc`           | TypeScript and TSX to `esnext` ESM (`nodenext` modules), with source maps, import attributes kept, React's automatic runtime and helpers inlined, so `@swc/helpers` is never a dependency.                                                                                  |
+| `c8rc.json`             | 100% thresholds on every metric; HTML, lcov and summary reports; tests, configs and declarations excluded.                                                                                                                                                                  |
+| `biome.base.json`       | Formatting only: 4 spaces, single quotes, width 100 for JavaScript and TypeScript; 2 spaces for JSON; Markdown and YAML. Linting off. Follows `.gitignore`. Changelogs are left alone. Not named `biome.json`, which Biome would take as the config of the folder it is in. |
+| `vitest.config.js`      | Runs compiled tests from `dist-test/unit` in worker threads (so c8 sees their coverage), with hooks in registration order and native `import` instead of Vite's module runner.                                                                                              |
+
+## Versioning
+
+Before 1.0, a release that can make passing code fail (a stricter compiler option, a higher threshold, a formatting change) is a minor, and other changes are patches.

package/biome.base.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "assist": {
+    "enabled": false
+  },
+  "vcs": {
+    "clientKind": "git",
+    "enabled": true,
+    "useIgnoreFile": true
+  },
+  "formatter": {
+    "enabled": true,
+    "formatWithErrors": true,
+    "indentStyle": "space",
+    "lineEnding": "lf",
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+      "arrowParentheses": "asNeeded",
+      "bracketSameLine": false,
+      "bracketSpacing": true,
+      "indentWidth": 4,
+      "jsxQuoteStyle": "double",
+      "quoteProperties": "asNeeded",
+      "quoteStyle": "single",
+      "semicolons": "always",
+      "trailingCommas": "es5"
+    },
+    "linter": {
+      "enabled": false
+    },
+    "parser": {
+      "unsafeParameterDecoratorsEnabled": false
+    }
+  },
+  "json": {
+    "formatter": {
+      "indentWidth": 2,
+      "lineWidth": 1
+    },
+    "linter": {
+      "enabled": false
+    }
+  },
+  "linter": {
+    "enabled": false
+  },
+  "markdown": {
+    "formatter": {
+      "enabled": true,
+      "formatEmbeds": false
+    },
+    "linter": {
+      "enabled": false
+    },
+    "parser": {
+      "frontmatter": true
+    }
+  },
+  "yaml": {
+    "formatter": {
+      "enabled": true,
+      "quoteStyle": "single"
+    },
+    "linter": {
+      "enabled": false
+    }
+  },
+  "overrides": [
+    {
+      "includes": [
+        "**/CHANGELOG.md"
+      ],
+      "markdown": {
+        "formatter": {
+          "enabled": false
+        }
+      }
+    }
+  ]
+}

package/c8rc.json

@@ -0,0 +1,50 @@
+{
+  "reporter": [
+    "html",
+    "lcovonly",
+    "text-summary"
+  ],
+  "exclude": [
+    "coverage/**",
+    "*.config.{,c,m}js",
+    "test/**",
+    "dist-test/**",
+    "**/*.d.{,c,m}ts",
+    "**/*.d.*.{,c,m}ts"
+  ],
+  "exclude-after-remap": true,
+  "extension": [
+    ".js",
+    ".cjs",
+    ".mjs",
+    ".ts",
+    ".cts",
+    ".mts",
+    ".tsx",
+    ".jsx"
+  ],
+
+  "lines": 100,
+  "statements": 100,
+  "functions": 100,
+  "branches": 100,
+
+  "watermarks": {
+    "lines": [
+      100,
+      95
+    ],
+    "functions": [
+      100,
+      95
+    ],
+    "branches": [
+      100,
+      95
+    ],
+    "statements": [
+      100,
+      95
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@leyman/configs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Strict shared configs for TypeScript ESM packages: tsconfig bases per Node.js support floor, SWC, c8 at 100% coverage, Biome and Vitest, each consumed by extending or pointing at the installed file.",
+  "type": "module",
+  "author": "JacobLey",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JacobLey/leyman.git",
+    "directory": "leyman/configs"
+  },
+  "homepage": "https://github.com/JacobLey/leyman/tree/main/leyman/configs#readme",
+  "bugs": {
+    "url": "https://github.com/JacobLey/leyman/issues"
+  },
+  "keywords": [
+    "tsconfig",
+    "typescript",
+    "swc",
+    "swcrc",
+    "c8",
+    "coverage",
+    "biome",
+    "vitest",
+    "config",
+    "strict",
+    "esm"
+  ],
+  "files": [
+    "biome.base.json",
+    "c8rc.json",
+    "swcrc.jsonc",
+    "tsconfig.build.json",
+    "tsconfig.node-22.json",
+    "tsconfig.node-24.json",
+    "tsconfig.test.json",
+    "vitest.config.js"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.4"
+  }
 }

package/swcrc.jsonc

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://swc.rs/schema.json",
+  "isModule": true,
+  "sourceMaps": true,
+  "inlineSourcesContent": false,
+  "jsc": {
+    "target": "esnext",
+    "externalHelpers": false,
+    "parser": {
+      "syntax": "typescript",
+      "decorators": false,
+      "dynamicImport": true,
+      "tsx": true
+    },
+    "transform": {
+      "react": {
+        // Use `__jsx` instead of `React`
+        "runtime": "automatic"
+      }
+    },
+    "experimental": {
+      "keepImportAttributes": true
+    },
+    // Removes comments
+    "minify": {
+      "compress": false,
+      "mangle": false
+    }
+  },
+  "module": {
+    "type": "nodenext",
+    "strict": true,
+    "strictMode": true,
+    // Prevents path rewrites from cjs -> cjs
+    "resolveFully": false,
+    "ignoreDynamic": true
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,52 @@
+{
+  "compilerOptions": {
+    "allowJs": false,
+    "allowSyntheticDefaultImports": true,
+    "allowUnreachableCode": false,
+    "allowUnusedLabels": false,
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "incremental": true,
+    "isolatedDeclarations": false,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "lib": [
+      "DOM",
+      "ESNext"
+    ],
+    "module": "NodeNext",
+    "moduleResolution": "nodenext",
+    "newLine": "lf",
+    "noImplicitReturns": true,
+    "noImplicitOverride": true,
+    "noEmitOnError": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": false,
+    "noUncheckedIndexedAccess": true,
+    "noUncheckedSideEffectImports": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": false,
+    "pretty": true,
+    "preserveConstEnums": true,
+    "removeComments": false,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "ESNext",
+    "types": [
+      "node"
+    ],
+    "useDefineForClassFields": true,
+    "useUnknownInCatchVariables": true
+  },
+  "exclude": [
+    "${configDir}/**/coverage/**/*.d.*ts",
+    "${configDir}/**/dist/**/*.d.*ts",
+    "${configDir}/**/nyc/**/*.d.*ts"
+  ]
+}

package/tsconfig.node-22.json

@@ -0,0 +1,15 @@
+{
+  "extends": "./tsconfig.build.json",
+  "compilerOptions": {
+    // Node.js 22 has ES2024, plus Set methods, iterator helpers and `Array.fromAsync` from later years, but not
+    // `Promise.try`, `RegExp.escape`, `Error.isError` or `Float16Array`
+    "lib": [
+      "DOM",
+      "ES2024",
+      "ES2025.Collection",
+      "ES2025.Iterator",
+      "ESNext.Array"
+    ],
+    "target": "ES2024"
+  }
+}

package/tsconfig.node-24.json

@@ -0,0 +1,15 @@
+{
+  "extends": "./tsconfig.build.json",
+  "compilerOptions": {
+    // Node.js 24 has ES2025, plus `Array.fromAsync`, `using` with `DisposableStack`, and `Error.isError`, but not
+    // `Uint8Array.fromBase64` or `Iterator.concat`
+    "lib": [
+      "DOM",
+      "ES2025",
+      "ESNext.Array",
+      "ESNext.Disposable",
+      "ESNext.Error"
+    ],
+    "target": "ES2025"
+  }
+}

package/tsconfig.test.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.build.json",
+  "compilerOptions": {
+    "composite": false,
+    "declaration": false,
+    "declarationMap": false,
+    "emitDeclarationOnly": false,
+    "incremental": false,
+    "noEmit": true
+  }
+}

package/vitest.config.js

@@ -0,0 +1,23 @@
+/**
+ * Vitest config for tests compiled to `dist-test/unit` before they run.
+ *
+ * Plain object (rather than `defineConfig`) so it can be loaded without resolving `vitest` from this directory.
+ */
+export default {
+    test: {
+        include: ['dist-test/unit/**/*.spec.js'],
+        // Forked workers are killed before V8 can flush coverage, so c8 would see nothing.
+        // Worker threads write their coverage on exit.
+        pool: 'threads',
+        sequence: {
+            // vitest-chain passes context forward through hooks, so hooks must run in registration order.
+            // The default (`stack`) runs afterEach/afterAll in reverse.
+            hooks: 'list',
+        },
+        experimental: {
+            // Tests are pre-compiled, so load them with native `import`.
+            // Keeps V8 coverage attributed to the real files on disk, for c8 to collect.
+            viteModuleRunner: false,
+        },
+    },
+};