@regardio/dev 1.24.0 → 2.0.2

package/docs/en/tools/typescript.md

@@ -0,0 +1,89 @@
+---
+
+title: TypeScript Configuration
+type: guide
+status: published
+summary: TypeScript setup and configuration for Regardio projects
+related: [biome, vitest]
+locale: en-US
+---
+
+# TypeScript Configuration
+
+Strict shared TypeScript presets for Regardio projects. Extend from `@regardio/dev` instead of rebuilding config from scratch. Keep strict settings enabled.
+
+## Presets
+
+| Preset | Use Case |
+|--------|----------|
+| `@regardio/dev/typescript/base` | Node.js packages, libraries |
+| `@regardio/dev/typescript/react` | React applications and components |
+| `@regardio/dev/typescript/build` | Build-specific settings (extends base) |
+
+## Configuration
+
+### tsconfig.json
+
+```json
+{
+  "extends": "@regardio/dev/typescript/base",
+  "include": ["src/**/*.ts"]
+}
+```
+
+For React projects:
+
+```json
+{
+  "extends": "@regardio/dev/typescript/react",
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}
+```
+
+### tsconfig.build.json
+
+Separate build config for production output:
+
+```json
+{
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "extends": ["./tsconfig.json", "@regardio/dev/typescript/build"],
+  "include": ["src/**/*.ts"]
+}
+```
+
+## Strict Settings
+
+The base config enables strict TypeScript checking:
+
+- `strict: true` - All strict type-checking options
+- `noUncheckedIndexedAccess: true` - Adds `undefined` to index signatures
+- `exactOptionalPropertyTypes: true` - Distinguishes between `undefined` and missing
+- `noImplicitReturns: true` - All code paths must return a value
+- `noFallthroughCasesInSwitch: true` - Prevents switch fallthrough bugs
+
+## Scripts
+
+```json
+{
+  "scripts": {
+    "build": "exec-tsc --project tsconfig.build.json",
+    "typecheck": "exec-tsc --noEmit"
+  }
+}
+```
+
+Run `typecheck` regularly during development to catch type errors early.
+
+Related documents:
+
+- [Biome](./biome.md) — Linting and formatting
+- [Vitest](./vitest.md) — Unit and integration testing for TypeScript projects
+
+### Resources
+
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/)
+- [tsconfig Reference](https://www.typescriptlang.org/tsconfig)

package/docs/en/tools/vitest.md

@@ -0,0 +1,146 @@
+---
+
+title: Vitest
+type: guide
+status: published
+summary: Unit and integration testing for TypeScript projects
+related: [typescript, playwright]
+locale: en-US
+---
+
+# Vitest
+
+Unit and integration testing for TypeScript projects. Vite-native, TypeScript-first. Configuration centralized in `@regardio/dev`.
+
+## Coverage Thresholds
+
+Library packages must meet minimum coverage thresholds before publishing:
+
+| Metric | Minimum |
+|--------|---------|
+| **Statements** | 80% |
+| **Branches** | 80% |
+| **Functions** | 80% |
+| **Lines** | 80% |
+
+These thresholds are enforced by:
+
+1. **`pnpm report`** - Fails if coverage is below thresholds
+2. **`ship-staging`** - Runs coverage check before deploying to staging
+3. **GitHub Actions** - Runs coverage check before publishing to npm
+
+To check coverage locally:
+
+```bash
+pnpm report
+```
+
+## Configuration
+
+### Node.js Packages
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import { vitestNodeConfig } from '@regardio/dev/vitest/node';
+
+export default defineConfig({ test: vitestNodeConfig });
+```
+
+### React Packages
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import { vitestReactConfig } from '@regardio/dev/vitest/react';
+
+export default defineConfig({ test: vitestReactConfig });
+```
+
+## Scripts
+
+```json
+{
+  "scripts": {
+    "test": "exec-s test:*",
+    "test:unit": "vitest run",
+    "report": "vitest run --coverage"
+  }
+}
+```
+
+Required devDependencies:
+
+```json
+{
+  "devDependencies": {
+    "@regardio/dev": "^1.11.0",
+    "@vitest/coverage-v8": "^4.0.0",
+    "vitest": "^4.0.0"
+  }
+}
+```
+
+## Running Tests
+
+```bash
+pnpm test:unit          # Run all tests once
+pnpm vitest             # Watch mode
+pnpm vitest --ui        # Visual UI
+pnpm vitest --coverage  # With coverage report
+```
+
+## Test File Naming
+
+- Unit tests: `*.test.ts` or `*.test.tsx`
+- Place tests next to source files or in `__tests__` directories
+
+## Writing Tests
+
+Follow the Arrange-Act-Assert pattern:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+
+describe('calculateTotal', () => {
+  it('should apply discount correctly', () => {
+    // Arrange
+    const items = [{ price: 100 }, { price: 50 }];
+    const discount = 0.1;
+
+    // Act
+    const total = calculateTotal(items, discount);
+
+    // Assert
+    expect(total).toBe(135);
+  });
+});
+```
+
+## React Component Testing
+
+```typescript
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Button } from './Button';
+
+it('calls onClick when clicked', async () => {
+  const handleClick = vi.fn();
+  render(<Button onClick={handleClick}>Click me</Button>);
+
+  await userEvent.click(screen.getByRole('button'));
+
+  expect(handleClick).toHaveBeenCalledOnce();
+});
+```
+
+Related documents:
+
+- [Testing Approach](../standards/testing.md) — Testing philosophy and patterns for Regardio projects
+- [Playwright](./playwright.md) — End-to-end testing for web applications
+- [TypeScript Configuration](./typescript.md) — TypeScript setup and configuration for Regardio projects
+
+### Resources
+
+- [Vitest Documentation](https://vitest.dev/)
+- [Testing Library](https://testing-library.com/)

package/package.json

@@ -1,31 +1,34 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@regardio/dev",
-  "version": "1.24.0",
+  "version": "2.0.2",
   "private": false,
-  "description": "Regardio developer tooling for testing, linting, and build workflows",
+  "description": "Regardio development presets: biome, typescript, commitlint, markdownlint, vitest, playwright, sqlfluff, husky, and GitLab-flow ship tooling",
   "keywords": [
     "biome",
     "commitlint",
     "dev",
     "documentation",
+    "gitlab-flow",
     "husky",
     "linting",
     "markdownlint",
     "playwright",
+    "release",
     "sqlfluff",
     "testing",
     "tooling",
     "typescript",
     "vitest"
   ],
-  "homepage": "https://github.com/regardio/dev/blob/main/README.md",
+  "homepage": "https://codeberg.org/regardio/commons/src/branch/main/packages/dev",
   "bugs": {
-    "url": "https://github.com/regardio/dev/issues"
+    "url": "https://codeberg.org/regardio/commons/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/regardio/dev.git"
+    "url": "git+https://codeberg.org/regardio/commons.git",
+    "directory": "packages/dev"
   },
   "license": "MIT",
   "author": "Bernd Matzner <bernd.matzner@regard.io>",
@@ -35,92 +38,76 @@
     "./biome": "./src/biome/preset.json",
     "./commitlint": "./src/commitlint/commitlint.cjs",
     "./markdownlint": "./src/markdownlint/markdownlint.json",
-    "./markdownlint-cli2": "./src/markdownlint/markdownlint-cli2.jsonc",
     "./playwright": {
-      "types": "./dist/playwright/index.d.ts",
-      "default": "./dist/playwright/index.js"
+      "import": "./dist/playwright/index.mjs",
+      "types": "./dist/playwright/index.d.mts"
     },
-    "./testing/setup-react": {
-      "types": "./dist/testing/setup-react.d.ts",
-      "default": "./dist/testing/setup-react.js"
-    },
-    "./typescript/base.json": "./src/typescript/base.json",
-    "./typescript/build.json": "./src/typescript/build.json",
-    "./typescript/react.json": "./src/typescript/react.json",
+    "./typescript/base": "./src/typescript/base.json",
+    "./typescript/build": "./src/typescript/build.json",
+    "./typescript/react": "./src/typescript/react.json",
     "./vitest/node": {
-      "types": "./dist/vitest/node.d.ts",
-      "default": "./dist/vitest/node.js"
+      "import": "./dist/vitest/node.mjs",
+      "types": "./dist/vitest/node.d.mts"
     },
     "./vitest/react": {
-      "types": "./dist/vitest/react.d.ts",
-      "default": "./dist/vitest/react.js"
+      "import": "./dist/vitest/react.mjs",
+      "types": "./dist/vitest/react.d.mts"
     }
   },
   "bin": {
-    "exec-clean": "dist/bin/exec/clean.js",
-    "exec-husky": "dist/bin/exec/husky.js",
-    "exec-p": "dist/bin/exec/p.js",
-    "exec-s": "dist/bin/exec/s.js",
-    "exec-tsc": "dist/bin/exec/tsc.js",
-    "lint-biome": "dist/bin/lint/biome.js",
-    "lint-commit": "dist/bin/lint/commit.js",
-    "lint-md": "dist/bin/lint/md.js",
-    "lint-package": "dist/bin/lint/package.js",
-    "ship-hotfix": "dist/bin/ship/hotfix.js",
-    "ship-production": "dist/bin/ship/production.js",
-    "ship-staging": "dist/bin/ship/staging.js"
+    "ship-hotfix": "dist/bin/ship/hotfix.bin.mjs",
+    "ship-production": "dist/bin/ship/production.bin.mjs",
+    "ship-staging": "dist/bin/ship/staging.bin.mjs"
   },
   "files": [
     "dist",
-    "src"
+    "src/biome",
+    "src/commitlint",
+    "src/markdownlint",
+    "src/typescript",
+    "docs",
+    "templates"
   ],
+  "devDependencies": {
+    "@total-typescript/ts-reset": "0.6.1",
+    "@types/node": "25.6.0",
+    "@vitest/coverage-v8": "4.1.5",
+    "tsdown": "0.21.9",
+    "vitest": "4.1.5"
+  },
+  "peerDependencies": {
+    "@biomejs/biome": ">=2",
+    "@changesets/changelog-git": ">=0.2",
+    "@changesets/cli": ">=2",
+    "@commitlint/cli": ">=20",
+    "@commitlint/config-conventional": ">=20",
+    "@playwright/test": ">=1",
+    "@testing-library/jest-dom": ">=6",
+    "@testing-library/react": ">=16",
+    "husky": ">=9",
+    "jsdom": ">=29",
+    "markdownlint-cli2": ">=0.22",
+    "typescript": ">=6",
+    "vitest": ">=4"
+  },
+  "engines": {
+    "node": ">=24"
+  },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "clean": "tsx src/bin/exec/clean.ts .turbo dist",
+    "build": "tsdown",
+    "clean": "rimraf .turbo dist",
+    "dev": "tsdown --watch",
     "fix": "run-s fix:pkg fix:md fix:biome",
     "fix:biome": "biome check --write --unsafe .",
     "fix:md": "markdownlint-cli2 --fix",
-    "fix:pkg": "tsx src/bin/lint/package.ts --fix",
+    "fix:pkg": "sort-package-json",
     "lint": "run-s lint:md lint:biome",
     "lint:biome": "biome check .",
     "lint:md": "markdownlint-cli2",
-    "lint:pkg": "tsx src/bin/lint/package.ts",
-    "prepare": "husky",
-    "report": "vitest run --coverage",
-    "ship:hotfix": "tsx src/bin/ship/hotfix.ts",
-    "ship:production": "tsx src/bin/ship/production.ts",
-    "ship:staging": "tsx src/bin/ship/staging.ts",
+    "lint:pkg": "sort-package-json --check",
     "test": "run-p test:*",
+    "test:e2e": "echo 'no e2e tests'",
     "test:unit": "vitest run",
     "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@biomejs/biome": "2.4.12",
-    "@commitlint/cli": "20.5.0",
-    "@commitlint/config-conventional": "20.5.0",
-    "@playwright/test": "1.59.1",
-    "@testing-library/jest-dom": "6.9.1",
-    "@testing-library/react": "16.3.2",
-    "@total-typescript/ts-reset": "0.6.1",
-    "@types/node": "25.6.0",
-    "@vitest/coverage-v8": "4.1.4",
-    "@vitest/ui": "4.1.4",
-    "husky": "9.1.7",
-    "jsdom": "29.0.2",
-    "markdownlint-cli2": "0.22.0",
-    "npm-run-all": "4.1.5",
-    "postcss": "8.5.10",
-    "rimraf": "6.1.3",
-    "rollup": "4.60.1",
-    "sort-package-json": "3.6.1",
-    "typescript": "6.0.2",
-    "vite": "8.0.8",
-    "vitest": "4.1.4"
-  },
-  "devDependencies": {
-    "tsx": "4.21.0"
-  },
-  "engines": {
-    "node": ">=24"
   }
 }

package/src/biome/preset.json

@@ -336,6 +336,9 @@
           }
         }
       },
+      "formatter": {
+        "enabled": false
+      },
       "includes": ["**/package.json"]
     }
   ],

package/templates/changeset/README.md

@@ -0,0 +1,14 @@
+# Changesets
+
+Pending version bumps live here as small Markdown files. Add one with `pnpm changeset` whenever you make a version-worthy change.
+
+## How it fits the GitLab flow
+
+- On `main`, authors run `pnpm changeset` alongside their change to describe the bump.
+- `ship-staging` deploys to staging without touching versions.
+- `ship-production` runs quality checks, consumes pending changesets (bumping versions and updating each package's `CHANGELOG.md`), commits the bumps on `main`, and merges to `production`.
+- CI on `production` runs `changeset publish` to push the new versions to npm.
+
+## Skipping a release
+
+If a commit is tooling-only and should not trigger a release, don't add a changeset.

package/templates/changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
+  "access": "public",
+  "baseBranch": "main",
+  "changelog": "@changesets/changelog-git",
+  "commit": false,
+  "fixed": [],
+  "ignore": [],
+  "linked": [],
+  "updateInternalDependencies": "patch"
+}

package/templates/github/release.yml

@@ -0,0 +1,77 @@
+# Regardio Release Workflow (GitHub Actions)
+# Copy this file to .github/workflows/release.yml
+#
+# Required setup:
+# 1. Initialize Changesets in your repo:
+#      cp -r node_modules/@regardio/dev/templates/changeset .changeset
+# 2. Add these scripts to package.json:
+#      "changeset": "changeset",
+#      "changeset:publish": "changeset publish",
+#      "ship:staging": "ship-staging",
+#      "ship:production": "ship-production",
+#      "ship:hotfix": "ship-hotfix"
+# 3. Create the branches:
+#      git checkout -b staging && git push -u origin staging
+#      git checkout -b production && git push -u origin production
+# 4. Add `NPM_TOKEN` to repo secrets. First npm publish of any new package
+#    must be done locally (`npm publish --access public`).
+#
+# Usage:
+# - Author adds a changeset on main: `pnpm changeset`
+# - `pnpm ship:staging` deploys to staging for validation
+# - `pnpm ship:production` consumes changesets locally, bumps versions, merges
+#   to production. This workflow then publishes to npm.
+
+name: Release
+
+on:
+  push:
+    branches:
+      - production
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v5
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm -r build
+
+      - name: Publish changed public packages
+        # `changeset publish`:
+        #   - walks the workspace topologically
+        #   - replaces `workspace:*` with real versions
+        #   - skips packages where the current version already exists on npm
+        #   - skips packages marked `"private": true`
+        #   - creates git tags like `@scope/pkg@1.2.3` for each published package
+        run: pnpm changeset publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_CONFIG_PROVENANCE: "true"
+
+      - name: Push tags
+        run: git push --tags

package/dist/bin/exec/clean.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export declare function resolveRimrafBin(require: NodeRequire): string | null;
-//# sourceMappingURL=clean.d.ts.map

package/dist/bin/exec/clean.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"clean.d.ts","sourceRoot":"","sources":["../../../src/bin/exec/clean.ts"],"names":[],"mappings":";AAcA,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAQpE"}

package/dist/bin/exec/clean.js

@@ -1,25 +0,0 @@
-#!/usr/bin/env node
-import { spawn } from 'node:child_process';
-import { createRequire } from 'node:module';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-export function resolveRimrafBin(require) {
-    const pkgPath = require.resolve('rimraf/package.json');
-    const pkg = require(pkgPath);
-    const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.rimraf;
-    if (!binRel)
-        return null;
-    const normalized = binRel.startsWith('./') ? binRel.slice(2) : binRel;
-    return path.join(path.dirname(pkgPath), normalized);
-}
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    const require = createRequire(import.meta.url);
-    const bin = resolveRimrafBin(require);
-    if (!bin) {
-        console.error('Unable to locate rimraf binary from package.json bin field');
-        process.exit(1);
-    }
-    const args = process.argv.slice(2);
-    const child = spawn(process.execPath, [bin, ...args], { stdio: 'inherit' });
-    child.on('exit', (code) => process.exit(code ?? 0));
-}

package/dist/bin/exec/clean.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=clean.test.d.ts.map

package/dist/bin/exec/clean.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"clean.test.d.ts","sourceRoot":"","sources":["../../../src/bin/exec/clean.test.ts"],"names":[],"mappings":""}

package/dist/bin/exec/clean.test.js

@@ -1,45 +0,0 @@
-import { createRequire } from 'node:module';
-import path from 'node:path';
-import { describe, expect, it } from 'vitest';
-import { resolveRimrafBin } from './clean.js';
-function makeRequire(pkgPath, pkg) {
-    const req = (id) => (id === pkgPath ? pkg : undefined);
-    req.resolve = (_id) => pkgPath;
-    return req;
-}
-describe('resolveRimrafBin', () => {
-    it('resolves when bin is a plain string', () => {
-        const pkgPath = '/node_modules/rimraf/package.json';
-        const req = makeRequire(pkgPath, { bin: './dist/esm/bin.js' });
-        const result = resolveRimrafBin(req);
-        expect(result).toBe(path.join('/node_modules/rimraf', 'dist/esm/bin.js'));
-    });
-    it('strips leading ./ from the bin path', () => {
-        const pkgPath = '/node_modules/rimraf/package.json';
-        const req = makeRequire(pkgPath, { bin: './bin/rimraf' });
-        const result = resolveRimrafBin(req);
-        expect(result).toBe(path.join('/node_modules/rimraf', 'bin/rimraf'));
-    });
-    it('resolves when bin is an object with a rimraf key', () => {
-        const pkgPath = '/node_modules/rimraf/package.json';
-        const req = makeRequire(pkgPath, { bin: { rimraf: './dist/esm/bin.js' } });
-        const result = resolveRimrafBin(req);
-        expect(result).toBe(path.join('/node_modules/rimraf', 'dist/esm/bin.js'));
-    });
-    it('returns null when bin field is missing', () => {
-        const pkgPath = '/node_modules/rimraf/package.json';
-        const req = makeRequire(pkgPath, {});
-        expect(resolveRimrafBin(req)).toBeNull();
-    });
-    it('returns null when bin object has no rimraf key', () => {
-        const pkgPath = '/node_modules/rimraf/package.json';
-        const req = makeRequire(pkgPath, { bin: { other: './dist/other.js' } });
-        expect(resolveRimrafBin(req)).toBeNull();
-    });
-    it('resolves against the real rimraf package', () => {
-        const req = createRequire(import.meta.url);
-        const result = resolveRimrafBin(req);
-        expect(result).not.toBeNull();
-        expect(path.isAbsolute(result ?? '')).toBe(true);
-    });
-});

package/dist/bin/exec/husky.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=husky.d.ts.map

package/dist/bin/exec/husky.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"husky.d.ts","sourceRoot":"","sources":["../../../src/bin/exec/husky.ts"],"names":[],"mappings":""}

package/dist/bin/exec/husky.js

@@ -1,9 +0,0 @@
-#!/usr/bin/env node
-import { spawn } from 'node:child_process';
-import { createRequire } from 'node:module';
-import { dirname, resolve } from 'node:path';
-const require = createRequire(import.meta.url);
-const bin = resolve(dirname(require.resolve('husky')), 'bin.js');
-const args = process.argv.slice(2);
-const child = spawn(process.execPath, [bin, ...args], { stdio: 'inherit' });
-child.on('exit', (code) => process.exit(code ?? 0));

package/dist/bin/exec/p.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=p.d.ts.map

package/dist/bin/exec/p.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"p.d.ts","sourceRoot":"","sources":["../../../src/bin/exec/p.ts"],"names":[],"mappings":""}

package/dist/bin/exec/p.js

@@ -1,8 +0,0 @@
-#!/usr/bin/env node
-import { spawn } from 'node:child_process';
-import { createRequire } from 'node:module';
-const require = createRequire(import.meta.url);
-const bin = require.resolve('npm-run-all/bin/run-p/index.js');
-const args = process.argv.slice(2);
-const child = spawn(process.execPath, [bin, ...args], { stdio: 'inherit' });
-child.on('exit', (code) => process.exit(code ?? 0));

package/dist/bin/exec/s.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=s.d.ts.map

package/dist/bin/exec/s.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"s.d.ts","sourceRoot":"","sources":["../../../src/bin/exec/s.ts"],"names":[],"mappings":""}