@cascivo/eslint-config 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) cascivo contributors
+
+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,29 @@
+<!-- generated by scripts/readme/generate.ts — edit readme.body.md, not this file -->
+
+<div align="center">
+  <a href="https://cascivo.com"><img src="https://cascivo.com/favicon.svg" width="72" height="72" alt="cascivo logo"></a>
+  <h1>@cascivo/eslint-config</h1>
+  <p><strong>Flat ESLint config for apps using cascivo — reconciles the signal-based reactivity contract with eslint-plugin-react-hooks 7</strong></p>
+
+[![npm](https://img.shields.io/npm/v/%40cascivo%2Feslint-config?style=flat-square&color=0079bf)](https://www.npmjs.com/package/@cascivo/eslint-config)
+[![downloads](https://img.shields.io/npm/dm/%40cascivo%2Feslint-config?style=flat-square&color=0079bf)](https://www.npmjs.com/package/@cascivo/eslint-config)
+[![license](https://img.shields.io/npm/l/%40cascivo%2Feslint-config?style=flat-square&color=0079bf)](https://github.com/cascivo/cascivo/blob/main/LICENSE)
+![types](https://img.shields.io/badge/types-included-0079bf?style=flat-square&logo=typescript&logoColor=white)
+
+[npm](https://www.npmjs.com/package/@cascivo/eslint-config) · [cascivo.com](https://cascivo.com) · [Docs](https://cascivo.com/docs) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/cascivo/cascivo)
+
+</div>
+
+---
+
+## Install
+
+```sh
+pnpm add @cascivo/eslint-config
+```
+
+---
+
+[cascivo.com](https://cascivo.com) · [Docs](https://cascivo.com/docs) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/cascivo/cascivo) · AI agents: read [`llms.txt`](https://cascivo.com/llms.txt) (install steps + component index, plain text) or use [`@cascivo/mcp`](https://github.com/cascivo/cascivo/tree/main/packages/mcp) and [`registry.json`](https://github.com/cascivo/cascivo/blob/main/registry.json) · MIT
+
+<div align="center"><a href="https://cascivo.com"><img src="https://cascivo.com/favicon.svg" width="28" height="28" alt="cascivo"></a></div>

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@cascivo/eslint-config",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Flat ESLint config for apps using cascivo — reconciles the signal-based reactivity contract with eslint-plugin-react-hooks 7",
+  "keywords": [
+    "cascivo",
+    "design-system",
+    "eslint",
+    "eslint-config",
+    "react",
+    "react-hooks",
+    "signals"
+  ],
+  "homepage": "https://github.com/cascivo/cascivo/tree/main/packages/eslint-config#readme",
+  "bugs": "https://github.com/cascivo/cascivo/issues",
+  "license": "MIT",
+  "author": "urbanisierung",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cascivo/cascivo.git",
+    "directory": "packages/eslint-config"
+  },
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "!src/**/*.test.js"
+  ],
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "echo 'eslint-config: plain ESM, no build'",
+    "test": "node --test src/index.test.js"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Flat-config fragments for apps using cascivo.
+ *
+ * Typed loosely on purpose: ESLint's flat-config object type lives in `eslint`, which this
+ * package deliberately does not depend on — it ships plain data, so it stays installable
+ * next to any ESLint 9+ without a version handshake.
+ */
+
+/** A single ESLint flat-config object. */
+export interface CascadeFlatConfig {
+  name?: string
+  files?: string[]
+  rules?: Record<string, unknown>
+  linterOptions?: Record<string, unknown>
+}
+
+/**
+ * Turns off `react-hooks/immutability`, which reports cascivo's mandatory signal-write
+ * idiom (`signal.value = next`) as an error under `eslint-plugin-react-hooks@7`'s
+ * `recommended-latest`. Applies to all files — signal writes live in your own page code,
+ * not only in vendored source.
+ */
+export declare const cascivoSignals: CascadeFlatConfig
+
+/**
+ * Scopes host stylistic rules off source vendored by `cascivo add`. Copy-paste path only.
+ *
+ * @param glob Your `outputDir` from `cascivo.config.ts`. Defaults to `src/components/ui/**`.
+ */
+export declare function cascivoVendoredSource(glob?: string): CascadeFlatConfig
+
+/** Both fragments. Spread last in your flat config — last-wins. */
+declare const cascivo: CascadeFlatConfig[]
+export default cascivo

package/src/index.js

@@ -0,0 +1,108 @@
+/**
+ * `@cascivo/eslint-config` — flat-config fragments for apps that use cascivo.
+ *
+ * ## Why this package exists
+ *
+ * `eslint-plugin-react-hooks@7` ships `react-hooks/immutability`, enabled by default in
+ * `recommended-latest`. It reports any write to a value returned from a hook — which is
+ * exactly cascivo's mandatory state idiom:
+ *
+ * ```
+ * error  Error: This value cannot be modified
+ * Modifying a value returned from a hook is not allowed.
+ *   onValueChange={(v) => (env.value = v)}
+ *                          ^^^ `env` cannot be modified
+ * ```
+ *
+ * `docs/AI-RULES.md` says "Local state -> `useSignal(initial)` … Never `useState`", and
+ * `docs/HEADLESS.md`'s canonical example is `onClick={() => (open.value = !open.value)}`.
+ * So a stock 2026 React app lints the documented idiom as an error on every piece of state
+ * the adopter wrote. One reported build hit this 8 times across 3 files — every lint error
+ * in the app, and nothing else.
+ *
+ * ## Why the rule is turned off rather than narrowed
+ *
+ * A signal write through `.value` is a deliberate mutation of a live reactive cell; that is
+ * the whole point of the primitive. The rule cannot distinguish it from an accidental
+ * mutation of `useState` output, and it has no allowlist option for hook names. There is no
+ * narrower mechanism, so the honest thing is to turn it off and say what that costs:
+ * **you lose the rule's protection against genuinely mutating React state elsewhere in the
+ * file.** If that matters more to you than ergonomics, drop `cascivoSignals` and write
+ * `signal.value = x` behind a `// eslint-disable-next-line` at each site instead.
+ *
+ * ## Usage
+ *
+ * ```js
+ * // eslint.config.js
+ * import cascivo from '@cascivo/eslint-config'
+ *
+ * export default [
+ *   // …your existing config…
+ *   ...cascivo,
+ * ]
+ * ```
+ *
+ * Spread it AFTER the configs it adjusts — flat config is last-wins.
+ *
+ * Prefer the pieces individually when you only vendor source, or only use the package:
+ *
+ * ```js
+ * import { cascivoSignals, cascivoVendoredSource } from '@cascivo/eslint-config'
+ * export default [...yourConfig, cascivoSignals, cascivoVendoredSource()]
+ * ```
+ */
+
+/**
+ * Reconciles `eslint-plugin-react-hooks@7` with cascivo's signal-based reactivity.
+ *
+ * Applies everywhere by default — signal writes live in *your* page and component code,
+ * not just in vendored files, so a directory-scoped override cannot cover them. That is
+ * precisely why the pre-existing `src/components/ui/**` recipe did not help prebuilt-path
+ * (Path B) adopters, who have no such directory at all.
+ */
+export const cascivoSignals = {
+  name: 'cascivo/signals',
+  rules: {
+    // See the module header for the full rationale and what turning this off costs.
+    'react-hooks/immutability': 'off',
+  },
+}
+
+/**
+ * Host stylistic rules scoped off source you vendored with `cascivo add`.
+ *
+ * Only relevant on the copy-paste path (Path A). `cascivo update` re-copies these files, so
+ * any in-place style fixes are undone on the next update — scoping the rules off is the
+ * durable move. Correctness rules stay on.
+ *
+ * @param {string} [glob] Your `outputDir` from `cascivo.config.ts`, as a glob.
+ */
+export function cascivoVendoredSource(glob = 'src/components/ui/**') {
+  return {
+    name: 'cascivo/vendored-source',
+    files: [glob],
+    rules: {
+      // Style: `T[]` vs `Array<T>`, import ordering, generic-param naming (`Row` vs
+      // `TRow`), method-signature style — cascivo does not adopt these.
+      '@typescript-eslint/array-type': 'off',
+      '@typescript-eslint/naming-convention': 'off',
+      '@typescript-eslint/method-signature-style': 'off',
+      'sort-imports': 'off',
+      'import/order': 'off',
+      // Opinionated / misfires on legitimate cascivo patterns:
+      'react/no-array-index-key': 'off', // stable-content lists key by index intentionally
+      'no-shadow': 'off', // false-positives on TS declaration merging (compound components)
+      'no-control-regex': 'off', // e.g. the log viewer strips ANSI escapes (\x1b) on purpose
+    },
+    linterOptions: {
+      // cascivo's rule-scoped `eslint-disable` directives may target rule ids your config
+      // doesn't define — don't report them as "unused".
+      reportUnusedDisableDirectives: 'off',
+    },
+  }
+}
+
+/** Both fragments, in the order flat config wants them. Spread last. */
+const cascivo = [cascivoSignals, cascivoVendoredSource()]
+
+export default cascivo