@cascivo/eslint-config 0.2.4 → 0.4.0

package/README.md

@@ -1,7 +1,7 @@
 <!-- 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>
+  <a href="https://cascivo.com"><img src="https://cascivo.com/logo-mark-img-accent.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>
 
@@ -26,4 +26,4 @@ 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>
+<div align="center"><a href="https://cascivo.com"><img src="https://cascivo.com/logo-mark-img.svg" width="28" height="28" alt="cascivo"></a></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cascivo/eslint-config",
-  "version": "0.2.4",
+  "version": "0.4.0",
   "private": false,
   "description": "Flat ESLint config for apps using cascivo — reconciles the signal-based reactivity contract with eslint-plugin-react-hooks 7",
   "keywords": [
@@ -24,6 +24,7 @@
   "files": [
     "src/**/*.js",
     "src/**/*.d.ts",
+    "src/**/*.json",
     "!src/**/*.test.js"
   ],
   "type": "module",
@@ -32,12 +33,16 @@
     ".": {
       "types": "./src/index.d.ts",
       "default": "./src/index.js"
-    }
+    },
+    "./oxlintrc.json": "./src/oxlintrc.json"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
+  "dependencies": {
+    "@cascivo/eslint-plugin": "0.2.0"
+  },
   "scripts": {
     "build": "echo 'eslint-config: plain ESM, no build'",
     "test": "node --test src/index.test.js"

package/src/index.d.ts

@@ -22,6 +22,22 @@ export interface CascadeFlatConfig {
  */
 export declare const cascivoSignals: CascadeFlatConfig
 
+/**
+ * Enables `cascivo/prop-vocabulary` at **warn** — the rule that answers a wrong prop guess
+ * with the prop that exists (`<Text tone=…>` → `muted`, `gap="4"` → `gap={4}`,
+ * `const { theme } = useTheme()` → the tuple). Kept at `warn` deliberately: an error over a
+ * naming opinion gets this whole config deleted.
+ */
+export declare const cascivoPropVocabulary: CascadeFlatConfig
+
+/**
+ * Enables `cascivo/token-values` at **warn** — the rule that reports a `--cascivo-*` custom
+ * property that does not exist. CSS drops an unknown custom property silently, so a
+ * misspelled token is not an error anywhere: it simply has no effect. Kept at `warn` for the
+ * same reason as `cascivoPropVocabulary`.
+ */
+export declare const cascivoTokenValues: CascadeFlatConfig
+
 /**
  * Scopes host stylistic rules off source vendored by `cascivo add`. Copy-paste path only.
  *
@@ -29,6 +45,6 @@ export declare const cascivoSignals: CascadeFlatConfig
  */
 export declare function cascivoVendoredSource(glob?: string): CascadeFlatConfig
 
-/** Both fragments. Spread last in your flat config — last-wins. */
+/** Every fragment. Spread last in your flat config — last-wins. */
 declare const cascivo: CascadeFlatConfig[]
 export default cascivo

package/src/index.js

@@ -47,10 +47,11 @@
  * 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()]
+ * import { cascivoSignals, cascivoPropVocabulary, cascivoTokenValues, cascivoVendoredSource } from '@cascivo/eslint-config'
+ * export default [...yourConfig, cascivoSignals, cascivoPropVocabulary, cascivoTokenValues, cascivoVendoredSource()]
  * ```
  */
+import cascivoPlugin from '@cascivo/eslint-plugin'
 
 /**
  * Reconciles `eslint-plugin-react-hooks@7` with cascivo's signal-based reactivity.
@@ -147,7 +148,49 @@ export function cascivoVendoredSource(glob = 'src/components/ui/**') {
   }
 }
 
-/** Both fragments, in the order flat config wants them. Spread last. */
-const cascivo = [cascivoSignals, cascivoVendoredSource()]
+/**
+ * The near-miss prop messages, at `warn`.
+ *
+ * `<Text tone="subtle">` is a correct TypeScript error whose text — "Property 'tone' does not
+ * exist on type 'TextProps'" — names the mistake and teaches nothing, so the adopter goes
+ * looking for the docs. That is the dependency the 2026-08-21 report named: "the docs are
+ * doing work the API should eventually do itself." Most of that work moved into the types;
+ * this rule carries the part TypeScript structurally cannot say. See
+ * `@cascivo/eslint-plugin`'s `prop-vocabulary.js` for the full rationale.
+ *
+ * **`warn`, never `error`.** A lint rule that fails somebody's build over a naming opinion
+ * gets the whole config deleted — and that takes `react-hooks/immutability` with it, which is
+ * the thing this package exists for. Raise it yourself if you want it enforced.
+ */
+export const cascivoPropVocabulary = {
+  name: 'cascivo/prop-vocabulary',
+  plugins: { cascivo: cascivoPlugin },
+  rules: { 'cascivo/prop-vocabulary': 'warn' },
+}
+
+/**
+ * The unknown-token messages, at `warn`.
+ *
+ * `--cascivo-color-acent` is not a type error, not a build error, and not a runtime error:
+ * CSS drops an unknown custom property silently, so a misspelled token simply has no effect
+ * and the search for the cause starts in the component. React's `CSSProperties` has no index
+ * signature for `--*` keys either, so every custom property in a `style` prop reaches the DOM
+ * through a cast the adopter wrote — and a cast launders a typo by definition.
+ *
+ * This rule is the editor-time half of that gap; `CascivoTokenStyle` + `satisfies` (from
+ * `@cascivo/tokens/style-contract`) is the compile-time half, and `cascivo audit --ai` is the
+ * gate. See `@cascivo/eslint-plugin`'s `token-values.js` for the full rationale.
+ *
+ * **`warn`, never `error`**, for the same reason as `prop-vocabulary`: a rule that fails a
+ * build gets this config deleted, and that takes `react-hooks/immutability` with it.
+ */
+export const cascivoTokenValues = {
+  name: 'cascivo/token-values',
+  plugins: { cascivo: cascivoPlugin },
+  rules: { 'cascivo/token-values': 'warn' },
+}
+
+/** Every fragment, in the order flat config wants them. Spread last. */
+const cascivo = [cascivoSignals, cascivoPropVocabulary, cascivoTokenValues, cascivoVendoredSource()]
 
 export default cascivo

package/src/oxlintrc.json

@@ -0,0 +1,30 @@
+{
+  // oxlint fragment for apps that use cascivo — the oxlint half of this package.
+  //
+  // `pnpm create vite --template react-ts` scaffolds oxlint with a `.oxlintrc.json`, not
+  // ESLint, so the documented remedy for the signals idiom ("add @cascivo/eslint-config and
+  // spread it into eslint.config.js") did not apply to the most common way to start a
+  // project in 2026 — the adopter had no eslint.config.js to spread into and worked the rule
+  // id out themselves (2026-08-31 report §13).
+  //
+  // Extend it from your own config:
+  //
+  //   {
+  //     "extends": ["./node_modules/@cascivo/eslint-config/src/oxlintrc.json"],
+  //     "categories": { "correctness": "error" }
+  //   }
+  //
+  // Or copy the one rule below — that is all this file is.
+  //
+  // ⚠ oxlint REJECTS a config that names a rule its build does not implement
+  // ("Rule 'immutability' not found in plugin 'react'"), so this fragment needs an oxlint
+  // recent enough to ship `react/immutability`. On an older oxlint the rule does not fire in
+  // the first place, so you need neither the fragment nor the rule.
+  "rules": {
+    // oxlint's port of `react-hooks/immutability`. It reports every `signal.value = next` —
+    // cascivo's mandatory state idiom — as "This value cannot be modified". See
+    // docs/USING-WITH-STRICT-ESLINT.md §1 for what turning it off costs; the reasoning is
+    // identical to the ESLint half of this package.
+    "react/immutability": "off"
+  }
+}