@regardio/dev 0.9.0

package/src/bin/lint-biome.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * lint-biome: Run Biome (formatter/linter) against the codebase.
+ * Usage: lint-biome [biome args...]
+ */
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const bin = require.resolve('@biomejs/biome/bin/biome');
+const args = process.argv.slice(2);
+const child = spawn(process.execPath, [bin, ...args], { stdio: 'inherit' });
+child.on('exit', (code) => process.exit(code ?? 0));

package/src/bin/lint-commit.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * lint-commit: Run commitlint against commit messages.
+ * Usage: lint-commit [commitlint args...]
+ */
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const bin = require.resolve('@commitlint/cli/cli.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/src/bin/lint-md.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * lint-md: Run markdownlint-cli2 to lint and fix Markdown files.
+ * Usage: lint-md [markdownlint-cli2 args...]
+ */
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+// Resolve to any exported file to find the package directory
+const packageDir = dirname(require.resolve('markdownlint-cli2'));
+const bin = join(packageDir, 'markdownlint-cli2-bin.mjs');
+const args = process.argv.slice(2);
+const child = spawn(process.execPath, [bin, ...args], { stdio: 'inherit' });
+child.on('exit', (code) => process.exit(code ?? 0));

package/src/biome/preset.json

@@ -0,0 +1,297 @@
+{
+  "$schema": "https://biomejs.dev/schemas/latest/schema.json",
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on",
+        "useSortedAttributes": "on",
+        "useSortedKeys": "on",
+        "useSortedProperties": "on"
+      }
+    }
+  },
+  "css": {
+    "assist": {
+      "enabled": true
+    },
+    "formatter": {
+      "enabled": true,
+      "indentStyle": "space",
+      "indentWidth": 2,
+      "lineEnding": "lf",
+      "lineWidth": 100,
+      "quoteStyle": "double"
+    },
+    "linter": {
+      "enabled": true
+    },
+    "parser": {
+      "cssModules": true,
+      "tailwindDirectives": true
+    }
+  },
+  "files": {
+    "ignoreUnknown": false,
+    "maxSize": 1048576
+  },
+  "formatter": {
+    "attributePosition": "multiline",
+    "bracketSpacing": true,
+    "enabled": true,
+    "expand": "auto",
+    "formatWithErrors": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineEnding": "lf",
+    "lineWidth": 100,
+    "useEditorconfig": true
+  },
+  "graphql": {
+    "assist": {
+      "enabled": true
+    },
+    "formatter": {
+      "enabled": false,
+      "indentStyle": "space",
+      "indentWidth": 2,
+      "lineEnding": "lf",
+      "lineWidth": 100,
+      "quoteStyle": "double"
+    },
+    "linter": {
+      "enabled": true
+    }
+  },
+  "html": {
+    "assist": {
+      "enabled": true
+    },
+    "experimentalFullSupportEnabled": true,
+    "formatter": {
+      "attributePosition": "multiline",
+      "bracketSameLine": false,
+      "enabled": true,
+      "indentScriptAndStyle": true,
+      "indentStyle": "space",
+      "indentWidth": 2,
+      "lineEnding": "lf",
+      "lineWidth": 100
+    },
+    "linter": {
+      "enabled": true
+    }
+  },
+  "javascript": {
+    "assist": {
+      "enabled": true
+    },
+    "formatter": {
+      "arrowParentheses": "always",
+      "attributePosition": "multiline",
+      "bracketSameLine": false,
+      "bracketSpacing": true,
+      "enabled": true,
+      "expand": "auto",
+      "indentStyle": "space",
+      "indentWidth": 2,
+      "jsxQuoteStyle": "double",
+      "lineEnding": "lf",
+      "lineWidth": 100,
+      "quoteProperties": "asNeeded",
+      "quoteStyle": "single",
+      "semicolons": "always",
+      "trailingCommas": "all"
+    },
+    "globals": [],
+    "jsxRuntime": "transparent",
+    "linter": {
+      "enabled": true
+    },
+    "parser": {
+      "jsxEverywhere": true,
+      "unsafeParameterDecoratorsEnabled": false
+    }
+  },
+  "json": {
+    "assist": {
+      "enabled": true
+    },
+    "formatter": {
+      "bracketSpacing": true,
+      "enabled": true,
+      "expand": "auto",
+      "indentStyle": "space",
+      "indentWidth": 2,
+      "lineEnding": "lf",
+      "lineWidth": 100,
+      "trailingCommas": "none"
+    },
+    "linter": {
+      "enabled": true
+    },
+    "parser": {
+      "allowComments": true,
+      "allowTrailingCommas": true
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "a11y": {
+        "noSvgWithoutTitle": "off",
+        "recommended": true,
+        "useGenericFontNames": "error"
+      },
+      "complexity": {
+        "noArguments": "error",
+        "noCommaOperator": "error",
+        "recommended": true,
+        "useNumericLiterals": "error"
+      },
+      "correctness": {
+        "noInvalidPositionAtImportRule": "off",
+        "noUnknownFunction": "off",
+        "noUnknownTypeSelector": "off",
+        "recommended": true,
+        "useUniqueElementIds": {
+          "level": "error",
+          "options": {
+            "excludedComponents": [
+              "circle",
+              "clipPath",
+              "defs",
+              "ellipse",
+              "filter",
+              "g",
+              "input",
+              "line",
+              "linearGradient",
+              "mask",
+              "path",
+              "pattern",
+              "polygon",
+              "polyline",
+              "radialGradient",
+              "rect",
+              "stop",
+              "svg",
+              "symbol",
+              "Trans"
+            ]
+          }
+        },
+        "useValidTypeof": "error"
+      },
+      "nursery": {
+        "recommended": true
+      },
+      "performance": {
+        "noBarrelFile": "error",
+        "recommended": true
+      },
+      "recommended": true,
+      "security": {
+        "noDangerouslySetInnerHtml": "off",
+        "recommended": true
+      },
+      "style": {
+        "noInferrableTypes": "error",
+        "noNonNullAssertion": "error",
+        "noParameterAssign": "error",
+        "noUnusedTemplateLiteral": "error",
+        "noUselessElse": "error",
+        "recommended": true,
+        "useAsConstAssertion": "error",
+        "useConst": "error",
+        "useDefaultParameterLast": "error",
+        "useEnumInitializers": "error",
+        "useExponentiationOperator": "error",
+        "useExportType": "error",
+        "useImportType": "error",
+        "useLiteralEnumMembers": "error",
+        "useNodejsImportProtocol": "error",
+        "useNumberNamespace": "error",
+        "useSelfClosingElements": "error",
+        "useShorthandFunctionType": "error",
+        "useSingleVarDeclarator": "error",
+        "useTemplate": "error"
+      },
+      "suspicious": {
+        "noApproximativeNumericConstant": "error",
+        "noArrayIndexKey": "error",
+        "noAssignInExpressions": "error",
+        "noAsyncPromiseExecutor": "error",
+        "noCatchAssign": "error",
+        "noClassAssign": "error",
+        "noCommentText": "error",
+        "noCompareNegZero": "error",
+        "noConfusingLabels": "error",
+        "noConfusingVoidType": "error",
+        "noConsole": "off",
+        "noConstEnum": "error",
+        "noControlCharactersInRegex": "error",
+        "noDebugger": "error",
+        "noDoubleEquals": "error",
+        "noDuplicateAtImportRules": "error",
+        "noDuplicateCase": "error",
+        "noDuplicateClassMembers": "error",
+        "noDuplicateFontNames": "error",
+        "noDuplicateJsxProps": "error",
+        "noDuplicateObjectKeys": "error",
+        "noDuplicateParameters": "error",
+        "noDuplicateSelectorsKeyframeBlock": "error",
+        "noDuplicateTestHooks": "error",
+        "noEmptyBlock": "error",
+        "noEmptyBlockStatements": "off",
+        "noEmptyInterface": "error",
+        "noEvolvingTypes": "error",
+        "noExplicitAny": "error",
+        "noExportsInTest": "error",
+        "noExtraNonNullAssertion": "error",
+        "noFallthroughSwitchClause": "error",
+        "noFocusedTests": "error",
+        "noFunctionAssign": "error",
+        "noGlobalAssign": "error",
+        "noGlobalIsFinite": "error",
+        "noGlobalIsNan": "error",
+        "noImplicitAnyLet": "error",
+        "noImportAssign": "error",
+        "noImportantInKeyframe": "error",
+        "noLabelVar": "error",
+        "noMisleadingCharacterClass": "error",
+        "noMisleadingInstantiator": "error",
+        "noMisplacedAssertion": "error",
+        "noMisrefactoredShorthandAssign": "error",
+        "noPrototypeBuiltins": "error",
+        "noReactSpecificProps": "off",
+        "noRedeclare": "error",
+        "noRedundantUseStrict": "error",
+        "noSelfCompare": "error",
+        "noShadowRestrictedNames": "error",
+        "noShorthandPropertyOverrides": "error",
+        "noSkippedTests": "error",
+        "noSparseArray": "error",
+        "noSuspiciousSemicolonInJsx": "error",
+        "noThenProperty": "error",
+        "noUnknownAtRules": "off",
+        "noUnsafeDeclarationMerging": "error",
+        "noUnsafeNegation": "error",
+        "recommended": true,
+        "useAwait": "error",
+        "useDefaultSwitchClauseLast": "error",
+        "useErrorMessage": "error",
+        "useGetterReturn": "error",
+        "useIsArray": "error",
+        "useNamespaceKeyword": "error",
+        "useNumberToFixedDigitsArgument": "error"
+      }
+    }
+  },
+  "root": true,
+  "vcs": {
+    "clientKind": "git",
+    "defaultBranch": "main",
+    "enabled": true,
+    "useIgnoreFile": true
+  }
+}

package/src/commitlint/commitlint.cjs

@@ -0,0 +1,26 @@
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'body-leading-blank': [1, 'always'],
+    'footer-leading-blank': [1, 'always'],
+    'header-max-length': [2, 'always', 100],
+    'type-enum': [
+      2,
+      'always',
+      [
+        'BREAKING CHANGE',
+        'build',
+        'chore',
+        'ci',
+        'docs',
+        'feat',
+        'fix',
+        'perf',
+        'refactor',
+        'revert',
+        'style',
+        'test',
+      ],
+    ],
+  },
+};

package/src/config.test.ts

@@ -0,0 +1,129 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const srcDir = path.dirname(fileURLToPath(import.meta.url));
+
+function readJson(filePath: string) {
+  // biome-ignore lint/suspicious/noExplicitAny: Test file needs flexible typing for nested config access
+  return JSON.parse(fs.readFileSync(filePath, 'utf8')) as any;
+}
+
+describe('Config Structure Validation', () => {
+  describe('biome/preset.json', () => {
+    const configPath = path.join(srcDir, 'biome/preset.json');
+    const config = readJson(configPath);
+
+    it('has $schema defined', () => {
+      expect(config.$schema).toContain('biomejs.dev');
+    });
+
+    it('has linter enabled', () => {
+      expect(config.linter?.enabled).toBe(true);
+    });
+
+    it('has formatter enabled', () => {
+      expect(config.formatter?.enabled).toBe(true);
+    });
+
+    it('has recommended rules enabled', () => {
+      expect(config.linter?.rules?.recommended).toBe(true);
+    });
+
+    it('disallows explicit any', () => {
+      expect(config.linter?.rules?.suspicious?.noExplicitAny).toBe('error');
+    });
+  });
+
+  describe('typescript/base.json', () => {
+    const configPath = path.join(srcDir, 'typescript/base.json');
+    const config = readJson(configPath);
+
+    it('has $schema defined', () => {
+      expect(config.$schema).toContain('schemastore.org');
+    });
+
+    it('has strict mode enabled', () => {
+      expect(config.compilerOptions?.strict).toBe(true);
+    });
+
+    it('has noUncheckedIndexedAccess enabled', () => {
+      expect(config.compilerOptions?.noUncheckedIndexedAccess).toBe(true);
+    });
+
+    it('has strictNullChecks enabled', () => {
+      expect(config.compilerOptions?.strictNullChecks).toBe(true);
+    });
+
+    it('has noImplicitAny enabled', () => {
+      expect(config.compilerOptions?.noImplicitAny).toBe(true);
+    });
+
+    it('targets ES2022', () => {
+      expect(config.compilerOptions?.target).toBe('ES2022');
+    });
+
+    it('uses ESNext module', () => {
+      expect(config.compilerOptions?.module).toBe('ESNext');
+    });
+  });
+
+  describe('typescript/react.json', () => {
+    const configPath = path.join(srcDir, 'typescript/react.json');
+    const config = readJson(configPath);
+
+    it('extends base.json', () => {
+      expect(config.extends).toContain('./base.json');
+    });
+
+    it('has jsx set to react-jsx', () => {
+      expect(config.compilerOptions?.jsx).toBe('react-jsx');
+    });
+  });
+
+  describe('markdownlint/markdownlint.json', () => {
+    const configPath = path.join(srcDir, 'markdownlint/markdownlint.json');
+    const config = readJson(configPath);
+
+    it('is a valid JSON object', () => {
+      expect(typeof config).toBe('object');
+      expect(config).not.toBeNull();
+    });
+
+    it('has MD013 (line-length) rule configured', () => {
+      expect(config.MD013).toBeDefined();
+    });
+  });
+
+  describe('commitlint/commitlint.cjs', () => {
+    const configPath = path.join(srcDir, 'commitlint/commitlint.cjs');
+
+    it('file exists', () => {
+      expect(fs.existsSync(configPath)).toBe(true);
+    });
+
+    it('exports extends with conventional config', () => {
+      const content = fs.readFileSync(configPath, 'utf8');
+      expect(content).toContain('@commitlint/config-conventional');
+    });
+  });
+});
+
+describe('Vitest Configs', () => {
+  describe('vitest/node', () => {
+    it('exports vitestNodeConfig', async () => {
+      const { vitestNodeConfig } = await import('./vitest/node.js');
+      expect(vitestNodeConfig).toBeDefined();
+      expect(vitestNodeConfig.environment).toBe('node');
+    });
+  });
+
+  describe('vitest/react', () => {
+    it('exports vitestReactConfig', async () => {
+      const { vitestReactConfig } = await import('./vitest/react.js');
+      expect(vitestReactConfig).toBeDefined();
+      expect(vitestReactConfig.environment).toBe('jsdom');
+    });
+  });
+});

package/src/markdownlint/markdownlint.json

@@ -0,0 +1,9 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD024": {
+    "siblings_only": false
+  },
+  "MD026": false,
+  "MD060": false
+}

package/src/playwright/index.test.ts

@@ -0,0 +1,73 @@
+import { devices } from '@playwright/test';
+import { describe, expect, it } from 'vitest';
+import type { BuildPlaywrightBaseConfigParams } from './index.js';
+import { buildPlaywrightBaseConfig } from './index.js';
+
+describe('buildPlaywrightBaseConfig', () => {
+  const validParams: BuildPlaywrightBaseConfigParams = {
+    appPort: 3000,
+    appUrl: 'http://localhost:3000',
+    devices,
+    webServerCommand: 'pnpm dev',
+  };
+
+  describe('validation', () => {
+    it('throws if appUrl is missing', () => {
+      expect(() => buildPlaywrightBaseConfig({ ...validParams, appUrl: '' })).toThrow(
+        '[playwright] appUrl must be a non-empty string',
+      );
+    });
+
+    it('throws if appPort is not a number', () => {
+      expect(() =>
+        buildPlaywrightBaseConfig({ ...validParams, appPort: '3000' as unknown as number }),
+      ).toThrow('[playwright] appPort must be a number');
+    });
+
+    it('throws if devices is missing', () => {
+      expect(() =>
+        buildPlaywrightBaseConfig({
+          ...validParams,
+          devices: undefined as unknown as typeof devices,
+        }),
+      ).toThrow('[playwright] devices must be provided');
+    });
+  });
+
+  describe('config output', () => {
+    it('returns valid Playwright config structure', () => {
+      const config = buildPlaywrightBaseConfig(validParams);
+
+      expect(config).toHaveProperty('projects');
+      expect(config).toHaveProperty('testDir', './tests');
+      expect(config).toHaveProperty('testMatch', '**/*.e2e.ts');
+      expect(config).toHaveProperty('webServer');
+      expect(config).toHaveProperty('use.baseURL', 'http://localhost:3000');
+    });
+
+    it('configures 6 browser projects', () => {
+      const config = buildPlaywrightBaseConfig(validParams);
+      expect(config.projects).toHaveLength(6);
+    });
+
+    it('sets retries to 0 when not in CI', () => {
+      const config = buildPlaywrightBaseConfig({ ...validParams, ci: false });
+      expect(config.retries).toBe(0);
+    });
+
+    it('sets retries to 2 in CI', () => {
+      const config = buildPlaywrightBaseConfig({ ...validParams, ci: true });
+      expect(config.retries).toBe(2);
+    });
+
+    it('sets workers to 1 in CI', () => {
+      const config = buildPlaywrightBaseConfig({ ...validParams, ci: true });
+      expect(config.workers).toBe(1);
+    });
+
+    it('sets forbidOnly to true in CI', () => {
+      const config = buildPlaywrightBaseConfig({ ...validParams, ci: true });
+      expect(config.forbidOnly).toBe(true);
+    });
+  });
+});

package/src/playwright/index.ts

@@ -0,0 +1,63 @@
+import type { PlaywrightTestConfig } from '@playwright/test';
+
+export interface BuildPlaywrightBaseConfigParams {
+  appUrl: string;
+  appPort: number;
+  devices: typeof import('@playwright/test').devices;
+  ci?: boolean;
+  webServerCommand: string;
+}
+
+/**
+ * Build a base Playwright config object with Regardio defaults.
+ * Consumers should wrap with defineConfig() in their local playwright.config.ts
+ */
+export function buildPlaywrightBaseConfig({
+  appUrl,
+  appPort,
+  devices,
+  ci = !!process.env.CI,
+  webServerCommand,
+}: BuildPlaywrightBaseConfigParams): PlaywrightTestConfig {
+  if (!appUrl || typeof appUrl !== 'string') {
+    throw new Error('[playwright] appUrl must be a non-empty string');
+  }
+  if (!appPort || typeof appPort !== 'number') {
+    throw new Error('[playwright] appPort must be a number');
+  }
+  if (!devices) {
+    throw new Error('[playwright] devices must be provided from "@playwright/test"');
+  }
+
+  return {
+    forbidOnly: ci,
+    fullyParallel: true,
+    outputDir: './tests/test-results',
+    projects: [
+      { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+      { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+      { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+      {
+        name: 'iPad Pro 11 landscape',
+        use: { ...devices['iPad Pro 11 landscape'] },
+      },
+      { name: 'iPhone 14 portrait', use: { ...devices['iPhone 14'] } },
+      { name: 'Pixel 7 portrait', use: { ...devices['Pixel 7'] } },
+    ],
+    reporter: [['html', { open: 'never', outputFolder: './tests/playwright-report' }]],
+    retries: ci ? 2 : 0,
+    testDir: './tests',
+    testMatch: '**/*.e2e.ts',
+    use: {
+      baseURL: appUrl,
+      trace: 'on-first-retry',
+    },
+    webServer: {
+      command: webServerCommand,
+      ignoreHTTPSErrors: true,
+      reuseExistingServer: !ci,
+      url: appUrl,
+    },
+    ...(ci ? { workers: 1 } : {}),
+  };
+}

package/src/testing/setup-react.ts

@@ -0,0 +1,8 @@
+/**
+ * Test setup file for React packages using Vitest and Testing Library.
+ * Import this in your vitest.config.ts setupFiles array.
+ *
+ * Usage in vitest.config.ts:
+ *   setupFiles: ['@regardio/dev/testing/setup-react']
+ */
+import '@testing-library/jest-dom/vitest';