@matthewbub/toolshed 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Bub
+
+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

@@ -0,0 +1,4 @@
+# toolshed
+
+> [!NOTE]
+> This repository is published for reference and reuse. I am not accepting pull requests or feature requests at this time.

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@matthewbub/toolshed",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "a digital toolshed — shared ESLint presets and Prettier config",
+  "keywords": [
+    "eslint",
+    "eslint-config",
+    "flat-config",
+    "prettier",
+    "prettier-config",
+    "config"
+  ],
+  "homepage": "https://github.com/matthewbub/toolshed#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/matthewbub/toolshed.git"
+  },
+  "author": "matthewbub",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    "./eslint-config": "./packages/eslint-config/index.mjs",
+    "./eslint-config/base": "./packages/eslint-config/base.mjs",
+    "./eslint-config/react": "./packages/eslint-config/react.mjs",
+    "./eslint-config/vite": "./packages/eslint-config/vite.mjs",
+    "./eslint-config/next": "./packages/eslint-config/next.mjs",
+    "./eslint-config/hono": "./packages/eslint-config/hono.mjs",
+    "./eslint-config/storybook": "./packages/eslint-config/storybook.mjs",
+    "./eslint-config/package-json": "./packages/eslint-config/package-json.mjs",
+    "./eslint-config/plugin": "./packages/eslint-config/plugin/index.mjs",
+    "./prettier-config": "./packages/prettier-config/index.mjs"
+  },
+  "files": [
+    "packages/eslint-config/*.mjs",
+    "packages/eslint-config/plugin/**/*.mjs",
+    "packages/eslint-config/README.md",
+    "packages/prettier-config/index.mjs",
+    "packages/prettier-config/README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "prettier": "@matthewbub/toolshed/prettier-config",
+  "dependencies": {
+    "@eslint/js": "9.39.4",
+    "@eslint/json": "2.0.0",
+    "eslint-config-next": "16.2.7",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-react-hooks": "7.1.1",
+    "eslint-plugin-react-refresh": "0.5.2",
+    "eslint-plugin-storybook": "10.4.4",
+    "globals": "17.6.0",
+    "typescript-eslint": "8.62.0",
+    "yaml-eslint-parser": "2.0.0"
+  },
+  "peerDependencies": {
+    "eslint": "9.39.4",
+    "prettier": "3.8.3"
+  },
+  "peerDependenciesMeta": {
+    "eslint": {
+      "optional": true
+    },
+    "prettier": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/cli": "2.31.0",
+    "eslint": "9.39.4",
+    "prettier": "3.8.3",
+    "turbo": "2.9.18"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "turbo run prettier",
+    "format:check": "prettier --check . --ignore-path .prettierignore",
+    "check": "turbo run lint && pnpm format:check",
+    "release": "pnpm publish --access public --no-git-checks"
+  }
+}

package/packages/eslint-config/README.md

@@ -0,0 +1,52 @@
+# @matthewbub/toolshed/eslint-config
+
+Shared [flat-config](https://eslint.org/docs/latest/use/configure/configuration-files) ESLint presets, plus exact-version governance for `package.json` and the pnpm `catalog:`. Shipped as part of [`@matthewbub/toolshed`](../../README.md).
+
+## Install
+
+```sh
+npm install --save-dev @matthewbub/toolshed eslint
+```
+
+## Presets
+
+Each preset is a factory you spread into your flat config. Pass `tsconfigRootDir: import.meta.dirname` when you want type-aware parsing rooted at the config file.
+
+| Export                                                       | Use for                                                            |
+| ------------------------------------------------------------ | ------------------------------------------------------------------ |
+| `base` (`/eslint-config/base`)                               | Any TS project — JS + typescript-eslint recommended + house style. |
+| `react` (`/eslint-config/react`)                             | React libraries — `base` + react-hooks.                            |
+| `vite` (`/eslint-config/vite`)                               | Vite + React apps — `react` + react-refresh (Fast Refresh).        |
+| `next` (`/eslint-config/next`)                               | Next.js apps — core-web-vitals + typescript, Prettier-deferred.    |
+| `hono` (`/eslint-config/hono`)                               | Hono / Cloudflare Worker source — `base` + worker globals.         |
+| `storybook` (`/eslint-config/storybook`)                     | `vite` + eslint-plugin-storybook.                                  |
+| `packageJson`, `pnpmCatalog` (`/eslint-config/package-json`) | Exact-version governance (see below).                              |
+
+The presets are also re-exported as named members of `@matthewbub/toolshed/eslint-config` (except `next`, which loads the `next` package eagerly — import it from `@matthewbub/toolshed/eslint-config/next`).
+
+### Example: a Vite app
+
+```js
+// eslint.config.mjs
+import {vite} from "@matthewbub/toolshed/eslint-config/vite";
+
+export default vite({tsconfigRootDir: import.meta.dirname});
+```
+
+### Example: repo-root version governance
+
+Enforces exact versions (no `^`/`~`/ranges) across every `package.json` and the `pnpm-workspace.yaml` catalog(s):
+
+```js
+// eslint.config.mjs
+import {packageJson, pnpmCatalog} from "@matthewbub/toolshed/eslint-config/package-json";
+
+export default [...packageJson(), ...pnpmCatalog()];
+```
+
+## Custom rules
+
+The bundled `local/` plugin (also exported as `localPlugin`) ships two rules, both wired up by the governance presets above:
+
+- `local/exact-dependency-versions` — every specifier in `package.json` dependency blocks must be an exact pin (or a `workspace:`/`catalog:`/`link:`/`file:` protocol).
+- `local/exact-catalog-versions` — every entry under the pnpm `catalog:` / `catalogs:` maps must be an exact version.

package/packages/eslint-config/base.mjs

@@ -0,0 +1,45 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+import {defineConfig, globalIgnores} from "eslint/config";
+
+const DEFAULT_IGNORES = ["dist/**", "out/**", "node_modules/**", "storybook-static/**"];
+
+export const globalRules = {
+  "curly": ["error", "all"],
+  "no-trailing-spaces": "error",
+  "object-curly-newline": [
+    "error",
+    {
+      ObjectExpression: {
+        multiline: true,
+        minProperties: 1,
+      },
+    },
+  ],
+  "object-property-newline": [
+    "error",
+    {
+      allowAllPropertiesOnSameLine: false,
+    },
+  ],
+};
+
+export function base({ignores = [], files = ["**/*.{ts,tsx}"], tsconfigRootDir} = {}) {
+  return defineConfig([
+    globalIgnores([...DEFAULT_IGNORES, ...ignores]),
+    {
+      files,
+      extends: [js.configs.recommended, tseslint.configs.recommended],
+      languageOptions: tsconfigRootDir
+        ? {
+            parserOptions: {
+              tsconfigRootDir,
+            },
+          }
+        : {},
+      rules: globalRules,
+    },
+  ]);
+}
+
+export default base;

package/packages/eslint-config/hono.mjs

@@ -0,0 +1,24 @@
+import globals from "globals";
+import {defineConfig} from "eslint/config";
+import {base} from "./base.mjs";
+
+export function hono({ignores, files = ["**/*.ts"], tsconfigRootDir} = {}) {
+  return defineConfig([
+    ...base({
+      ignores,
+      files,
+      tsconfigRootDir,
+    }),
+    {
+      files,
+      languageOptions: {
+        globals: {
+          ...globals.serviceworker,
+          ...globals.node,
+        },
+      },
+    },
+  ]);
+}
+
+export default hono;

package/packages/eslint-config/index.mjs

@@ -0,0 +1,10 @@
+export {base, globalRules} from "./base.mjs";
+export {react} from "./react.mjs";
+export {vite} from "./vite.mjs";
+export {storybook} from "./storybook.mjs";
+export {hono} from "./hono.mjs";
+export {packageJson, pnpmCatalog} from "./package-json.mjs";
+export {default as localPlugin} from "./plugin/index.mjs";
+
+// `next` is not re-exported: eslint-config-next loads the `next` package eagerly,
+// which breaks non-Next consumers. Import from "@matthewbub/toolshed/eslint-config/next".

package/packages/eslint-config/next.mjs

@@ -0,0 +1,50 @@
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+import prettier from "eslint-config-prettier/flat";
+import storybookPlugin from "eslint-plugin-storybook";
+import {defineConfig, globalIgnores} from "eslint/config";
+import {globalRules} from "./base.mjs";
+
+// Default ignores for a Next.js app (mirrors eslint-config-next's own defaults,
+// which `globalIgnores` here re-asserts so they survive our extra entries).
+const NEXT_IGNORES = [".next/**", "out/**", "build/**", "next-env.d.ts", "external/**"];
+
+/**
+ * Next.js preset: core-web-vitals + typescript configs, with eslint-config-prettier
+ * to defer formatting to Prettier. `globalRules` is re-asserted AFTER prettier,
+ * since eslint-config-prettier disables those rules and they are global — enforced
+ * here as everywhere else.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.storybook] append eslint-plugin-storybook flat/recommended
+ * @param {string[]} [options.ignores] extra ignore globs
+ * @param {string} [options.tsconfigRootDir] usually `import.meta.dirname`
+ */
+export function next({storybook = false, ignores = [], tsconfigRootDir} = {}) {
+  return defineConfig([
+    ...nextVitals,
+    ...nextTs,
+    {
+      ...(tsconfigRootDir
+        ? {
+            languageOptions: {
+              parserOptions: {
+                tsconfigRootDir,
+              },
+            },
+          }
+        : {}),
+      rules: {
+        "react/no-unescaped-entities": "off",
+      },
+    },
+    prettier,
+    {
+      rules: globalRules,
+    },
+    globalIgnores([...NEXT_IGNORES, ...(storybook ? ["storybook-static/**"] : []), ...ignores]),
+    ...(storybook ? storybookPlugin.configs["flat/recommended"] : []),
+  ]);
+}
+
+export default next;

package/packages/eslint-config/package-json.mjs

@@ -0,0 +1,40 @@
+import json from "@eslint/json";
+import * as yamlParser from "yaml-eslint-parser";
+import {defineConfig} from "eslint/config";
+import localPlugin from "./plugin/index.mjs";
+
+export function packageJson({files = ["**/package.json"], ignores = []} = {}) {
+  return defineConfig([
+    {
+      files,
+      ignores: ["**/node_modules/**", ...ignores],
+      language: "json/json",
+      plugins: {
+        json,
+        local: localPlugin,
+      },
+      rules: {
+        "local/exact-dependency-versions": "error",
+      },
+    },
+  ]);
+}
+
+export function pnpmCatalog({files = ["pnpm-workspace.yaml"]} = {}) {
+  return defineConfig([
+    {
+      files,
+      languageOptions: {
+        parser: yamlParser,
+      },
+      plugins: {
+        local: localPlugin,
+      },
+      rules: {
+        "local/exact-catalog-versions": "error",
+      },
+    },
+  ]);
+}
+
+export default packageJson;

package/packages/eslint-config/plugin/exact-version.mjs

@@ -0,0 +1,15 @@
+export const ALLOWED_PROTOCOLS = ["workspace:", "catalog:", "link:", "file:"];
+
+// Exact semver: 1.2.3, optionally with -prerelease and/or +build metadata.
+export const EXACT_SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
+
+export function isExact(spec) {
+  if (typeof spec !== "string") {
+    return false;
+  }
+  const trimmed = spec.trim();
+  if (ALLOWED_PROTOCOLS.some((protocol) => trimmed.startsWith(protocol))) {
+    return true;
+  }
+  return EXACT_SEMVER.test(trimmed);
+}

package/packages/eslint-config/plugin/index.mjs

@@ -0,0 +1,12 @@
+import exactDependencyVersions from "./rules/exact-dependency-versions.mjs";
+import exactCatalogVersions from "./rules/exact-catalog-versions.mjs";
+
+export default {
+  meta: {
+    name: "@matthewbub/eslint-config/plugin",
+  },
+  rules: {
+    "exact-dependency-versions": exactDependencyVersions,
+    "exact-catalog-versions": exactCatalogVersions,
+  },
+};

package/packages/eslint-config/plugin/rules/exact-catalog-versions.mjs

@@ -0,0 +1,66 @@
+import {isExact} from "../exact-version.mjs";
+
+function keyName(pair) {
+  return pair.key && "value" in pair.key ? String(pair.key.value) : "";
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require exact versions in the pnpm-workspace catalog(s) (no ^, ~, ranges).",
+    },
+    messages: {
+      notExact:
+        '"{{name}}": "{{spec}}" in {{catalog}} must be an exact version (e.g. 1.2.3) — ' +
+        "no ranges (^, ~, >=, *, ||).",
+    },
+    schema: [],
+  },
+  create(context) {
+    function checkCatalogMapping(mapping, catalogLabel) {
+      if (!mapping || mapping.type !== "YAMLMapping") {
+        return;
+      }
+      for (const pair of mapping.pairs) {
+        const value = pair.value;
+        if (!value || value.type !== "YAMLScalar") {
+          continue;
+        }
+        const spec = String(value.value);
+        if (isExact(spec)) {
+          continue;
+        }
+        context.report({
+          loc: value.loc,
+          messageId: "notExact",
+          data: {
+            name: keyName(pair),
+            spec,
+            catalog: catalogLabel,
+          },
+        });
+      }
+    }
+
+    return {
+      YAMLDocument(node) {
+        const root = node.content;
+        if (!root || root.type !== "YAMLMapping") {
+          return;
+        }
+        for (const pair of root.pairs) {
+          const key = keyName(pair);
+          // Only `catalog`/`catalogs`; `overrides:` keys are range selectors, not pins.
+          if (key === "catalog") {
+            checkCatalogMapping(pair.value, "catalog");
+          } else if (key === "catalogs" && pair.value?.type === "YAMLMapping") {
+            for (const named of pair.value.pairs) {
+              checkCatalogMapping(named.value, `catalogs.${keyName(named)}`);
+            }
+          }
+        }
+      },
+    };
+  },
+};

package/packages/eslint-config/plugin/rules/exact-dependency-versions.mjs

@@ -0,0 +1,53 @@
+import {isExact} from "../exact-version.mjs";
+
+const DEP_SECTIONS = new Set(["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]);
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require exact dependency versions in package.json (no ^, ~, >=, *, or other ranges).",
+    },
+    messages: {
+      notExact:
+        '"{{name}}": "{{spec}}" in {{section}} must be an exact version (e.g. 1.2.3) — ' +
+        "no ranges (^, ~, >=, *, ||). Pin the version, or use workspace:/catalog: for internal refs.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      Document(node) {
+        const root = node.body;
+        if (!root || root.type !== "Object") {
+          return;
+        }
+        for (const section of root.members) {
+          if (!DEP_SECTIONS.has(section.name?.value)) {
+            continue;
+          }
+          if (section.value?.type !== "Object") {
+            continue;
+          }
+          for (const dependency of section.value.members) {
+            if (dependency.value?.type !== "String") {
+              continue;
+            }
+            if (isExact(dependency.value.value)) {
+              continue;
+            }
+            context.report({
+              loc: dependency.value.loc,
+              messageId: "notExact",
+              data: {
+                name: dependency.name?.value ?? "",
+                spec: dependency.value.value,
+                section: section.name.value,
+              },
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/packages/eslint-config/react.mjs

@@ -0,0 +1,23 @@
+import globals from "globals";
+import reactHooks from "eslint-plugin-react-hooks";
+import {defineConfig} from "eslint/config";
+import {base} from "./base.mjs";
+
+export function react({ignores, files = ["**/*.{ts,tsx}"], tsconfigRootDir} = {}) {
+  return defineConfig([
+    ...base({
+      ignores,
+      files,
+      tsconfigRootDir,
+    }),
+    {
+      files,
+      extends: [reactHooks.configs.flat["recommended-latest"]],
+      languageOptions: {
+        globals: globals.browser,
+      },
+    },
+  ]);
+}
+
+export default react;

package/packages/eslint-config/storybook.mjs

@@ -0,0 +1,9 @@
+import storybookPlugin from "eslint-plugin-storybook";
+import {defineConfig} from "eslint/config";
+import {vite} from "./vite.mjs";
+
+export function storybook(options = {}) {
+  return defineConfig([...vite(options), ...storybookPlugin.configs["flat/recommended"]]);
+}
+
+export default storybook;

package/packages/eslint-config/vite.mjs

@@ -0,0 +1,22 @@
+import reactRefresh from "eslint-plugin-react-refresh";
+import {defineConfig} from "eslint/config";
+import {react} from "./react.mjs";
+
+export function vite({ignores, files = ["**/*.{ts,tsx}"], tsconfigRootDir} = {}) {
+  return defineConfig([
+    ...react({
+      ignores,
+      files,
+      tsconfigRootDir,
+    }),
+    {
+      files,
+      extends: [reactRefresh.configs.vite],
+      rules: {
+        "react-refresh/only-export-components": "warn",
+      },
+    },
+  ]);
+}
+
+export default vite;

package/packages/prettier-config/README.md

@@ -0,0 +1,40 @@
+# @matthewbub/toolshed/prettier-config
+
+Shared [Prettier](https://prettier.io) configuration. Shipped as part of [`@matthewbub/toolshed`](../../README.md).
+
+## Install
+
+```sh
+npm install --save-dev @matthewbub/toolshed prettier
+```
+
+## Usage
+
+Reference it from the `prettier` field of your `package.json`:
+
+```json
+{
+  "prettier": "@matthewbub/toolshed/prettier-config"
+}
+```
+
+To extend it, create a `prettier.config.mjs` instead:
+
+```js
+import base from "@matthewbub/toolshed/prettier-config";
+
+/** @type {import("prettier").Config} */
+export default {
+  ...base,
+  // your overrides
+};
+```
+
+## What it sets
+
+| Option           | Value          |
+| ---------------- | -------------- |
+| `quoteProps`     | `"consistent"` |
+| `bracketSpacing` | `false`        |
+| `objectWrap`     | `"preserve"`   |
+| `printWidth`     | `120`          |

package/packages/prettier-config/index.mjs

@@ -0,0 +1,14 @@
+/**
+ * Shared Prettier configuration for the toolshed monorepo.
+ *
+ * Single source of truth — every consumer references this via the `prettier`
+ * field in its package.json. To change formatting repo-wide, edit it here.
+ *
+ * @type {import("prettier").Config}
+ */
+export default {
+  quoteProps: "consistent",
+  bracketSpacing: false,
+  objectWrap: "preserve",
+  printWidth: 120,
+};