@fitzzero/quickdraw-core 3.8.0 → 3.9.0

package/README.md

@@ -352,18 +352,52 @@ import {
 import { createMockSocket, createTestWrapper } from "@fitzzero/quickdraw-core/client/testing";
 ```
 
+## Linting
+
+The package ships a shared oxlint base config, `oxlint.base.jsonc` — the
+framework's lint best practices (strict type-safety, complexity budgets, and
+the `quickdraw` plugin rules pre-wired for `services/**` and client code).
+Extend it from your root `.oxlintrc.json` so best practices update with the
+package:
+
+```jsonc
+{
+  "extends": ["./node_modules/@fitzzero/quickdraw-core/oxlint.base.jsonc"],
+  // plugins are NOT purely inherited: omitting this array unions oxlint's
+  // default plugin set into the merge — mirror the base's list.
+  "plugins": ["typescript", "import", "react", "nextjs", "jsx_a11y"],
+  // ignorePatterns, env, globals, and settings are not inherited — declare here.
+  "ignorePatterns": ["**/dist/**", "**/node_modules/**"],
+  "overrides": [
+    // Project-specific relaxations win over the base (overrides concatenate,
+    // consumer last), e.g. allow specific cross-service mutations:
+    {
+      "files": ["**/services/**/*.ts"],
+      "rules": {
+        "quickdraw/no-cross-service-mutations": [
+          "error",
+          { "allowedModels": { "chat": ["chatMember"] } },
+        ],
+      },
+    },
+  ],
+}
+```
+
+The base config also loads `./eslint-plugin` (the `quickdraw` rules) via
+`jsPlugins` — no separate wiring needed. The `./eslint-config` export (ESLint
+flat config) is legacy; prefer the oxlint base.
+
 ## Local Development
 
 This package is developed alongside [quickdraw-chat](https://github.com/fitzzero/quickdraw-chat), a reference implementation.
 
-### Using pnpm link
+quickdraw-chat consumes the published npm package. For local iteration
+against a checkout, use `bun link` (or point lint `extends` at the sibling
+path), and always re-verify against a published version before releasing:
 
 ```bash
-# In quickdraw-chat, the package is linked:
-"@fitzzero/quickdraw-core": "link:../../../quickdraw"
-
-# Changes to quickdraw-core are instantly available after rebuild
-pnpm build  # or pnpm dev for watch mode
+bun run build  # or bun run dev for watch mode
 ```
 
 ## Type Definitions

package/oxlint.base.jsonc

@@ -0,0 +1,123 @@
+// Shared oxlint base config for quickdraw apps.
+//
+// Consume from a project by extending it in your root .oxlintrc.json:
+//
+//   {
+//     "extends": ["./node_modules/@fitzzero/quickdraw-core/oxlint.base.jsonc"],
+//     ...project-specific config
+//   }
+//
+// oxlint merge semantics (v1.x): `rules` and `categories` merge per-key with
+// the extending config winning; `overrides` concatenate (base first, so a
+// consumer override on the same glob wins); `jsPlugins` concatenate.
+// NOT inherited — declare these in the consumer config:
+//   - `ignorePatterns`, `env`, `globals`, `settings`
+//   - `plugins`: if the consumer omits its `plugins` array, oxlint unions the
+//     DEFAULT plugin set into the merge — mirror the list below to avoid
+//     surprise diagnostics from plugins you didn't opt into.
+{
+  "plugins": ["typescript", "import", "react", "nextjs", "jsx_a11y"],
+  "categories": {
+    "correctness": "deny",
+    "suspicious": "deny",
+    "pedantic": "deny",
+  },
+  // The quickdraw framework rules, shipped alongside this file.
+  // The relative specifier resolves against this file's location, i.e. inside
+  // the installed package — consumers don't need their own jsPlugins entry.
+  "jsPlugins": [
+    {
+      "name": "quickdraw",
+      "specifier": "./eslint-plugin-quickdraw/index.mjs",
+    },
+  ],
+  "rules": {
+    "react/rules-of-hooks": "error",
+    "no-console": "error",
+    "no-var": "error",
+    "typescript/no-explicit-any": "error",
+    "typescript/no-non-null-assertion": "error",
+    "typescript/no-import-type-side-effects": "error",
+
+    "typescript/no-unsafe-assignment": "error",
+    "typescript/no-unsafe-call": "error",
+    "typescript/no-unsafe-member-access": "error",
+    "typescript/no-unsafe-return": "error",
+    "typescript/no-unsafe-argument": "error",
+    "typescript/restrict-template-expressions": "off",
+    "typescript/no-redundant-type-constituents": "off",
+
+    "require-await": "error",
+    "no-inline-comments": "error",
+    "no-unmodified-loop-condition": "error",
+    "no-promise-executor-return": "error",
+    "eqeqeq": "error",
+    "import/max-dependencies": ["error", { "max": 10 }],
+
+    // Complexity budgets: keep units small enough to reason about (and small
+    // enough for focused AI edits).
+    "complexity": ["error", { "max": 15 }],
+    "max-depth": ["error", { "max": 4 }],
+    "max-lines": ["error", { "max": 500, "skipBlankLines": true, "skipComments": true }],
+    "max-lines-per-function": [
+      "error",
+      { "max": 80, "skipBlankLines": true, "skipComments": true },
+    ],
+  },
+  "overrides": [
+    // Service layer: enforce the quickdraw service contract.
+    // `no-cross-service-mutations` ships with an EMPTY allowlist (strictest).
+    // Projects relax it with their own services override, e.g.:
+    //   { "files": ["**/services/**/*.ts"], "rules": { "quickdraw/no-cross-service-mutations": ["error", { "allowedModels": { "chat": ["chatMember"] } }] } }
+    {
+      "files": ["**/services/**/*.ts"],
+      "rules": {
+        "quickdraw/no-raw-service-room-string": "error",
+        "quickdraw/no-cross-service-mutations": "error",
+        "quickdraw/require-zod-schema": "error",
+        "quickdraw/no-service-method-record": "error",
+        "quickdraw/no-unsafe-payload-cast": "error",
+      },
+    },
+    // Client/React code: relax server-oriented strictness, enforce the
+    // typed-socket and design-system rules instead.
+    {
+      "files": ["apps/web/**", "**/*.tsx"],
+      "rules": {
+        "typescript/explicit-function-return-type": "off",
+        "jsx_a11y/no-autofocus": "off",
+        "react/react-in-jsx-scope": "off",
+        "import/no-unassigned-import": "off",
+        "import/max-dependencies": "off",
+        "max-lines-per-function": "off",
+        "max-lines": "off",
+        "no-warning-comments": "off",
+        "quickdraw/no-raw-tooltip-strings": "error",
+        "quickdraw/no-raw-typography-strings": "error",
+        "quickdraw/no-raw-button-strings": "error",
+        "quickdraw/no-raw-socket-on": "error",
+        "quickdraw/no-raw-socket-emit": "error",
+      },
+    },
+    // Shared/db packages: public surface — explicit types required.
+    {
+      "files": ["packages/shared/**", "packages/db/**"],
+      "rules": {
+        "typescript/explicit-function-return-type": "error",
+        "typescript/explicit-module-boundary-types": "error",
+        "no-console": "error",
+      },
+    },
+    // Tests: size and style budgets don't apply.
+    {
+      "files": ["**/__tests__/**", "**/*.test.ts", "**/*.test.tsx"],
+      "rules": {
+        "max-lines-per-function": "off",
+        "max-lines": "off",
+        "no-inline-comments": "off",
+        "require-await": "off",
+        "import/max-dependencies": "off",
+      },
+    },
+  ],
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitzzero/quickdraw-core",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "Fast fullstack patterns for real-time applications with Socket.io and TanStack Query",
   "keywords": [
     "fullstack",
@@ -15,7 +15,8 @@
   "files": [
     "dist",
     "eslint-plugin-quickdraw",
-    "eslint-config"
+    "eslint-config",
+    "oxlint.base.jsonc"
   ],
   "type": "module",
   "main": "./dist/shared/index.js",