basalt-ui 1.28.0 → 1.29.1

package/configs/oxlint-plugin.js

@@ -80,16 +80,38 @@ import { fileURLToPath } from 'node:url'
 
 // ── Shared helpers ──────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Guard kinds and plugin rules RETIRED — kept recognized by `KNOWN_RULE_IDS` (below) and the
+ * guard's own `PLUGIN_RULE_IDS` copy so an existing `theme-allow <id>` reads as a dead waiver via
+ * `check-theme --audit-allows`, never as a typo.
+ *
+ * - `unframed-chart` (regex: a `<ChartLegend items={[...]}>` array literal) →
+ *   `basalt/chart-legend-literal`, which also catches the `.map()`-over-a-non-series form the
+ *   regex never could reach.
+ * - `duplicate-notifications-mount` — its only case, `<BasaltNotifications />` mounted beside
+ *   `<BasaltOverlays notifications>`, is unreachable now that `BasaltNotifications` no longer
+ *   exists as a standalone export; the rule had nothing left to fire on.
+ * - `query-dual-import` — its whole premise (a raw `@tanstack/react-query` import beside
+ *   `basalt-ui/query`) is unreachable now that C1 (1.29.0) dropped the `./query` subpath: a
+ *   consumer MUST import `@tanstack/react-query` directly, so the rule warned on every such
+ *   import instead of the drift it was written to catch.
+ */
+export const RETIRED_RULE_IDS = new Set([
+  'unframed-chart',
+  'duplicate-notifications-mount',
+  'query-dual-import',
+])
+
 /**
  * Rule ids a `theme-allow` may name — this plugin's own rules plus `src/guard`'s kinds. Duplicated
  * by hand for the same reason `majorOf` is: this file loads standalone out of a consumer's
  * node_modules and must not import from the package.
  *
  * Exported, and `oxlint-plugin.test.ts` asserts it is EXACTLY the plugin's own rule ids plus
- * `GUARD_RULES`'s keys. Forgetting an entry here is not a cosmetic omission — an id this set does
- * not know is treated as a typo, so the annotation naming it waives nothing (see
- * {@link parseThemeAllow}); before the fail-closed change it was worse still, silently widening to
- * a blanket waiver.
+ * `GUARD_RULES`'s keys plus `RETIRED_RULE_IDS`. Forgetting an entry here is not a cosmetic
+ * omission — an id this set does not know is treated as a typo, so the annotation naming it waives
+ * nothing (see {@link parseThemeAllow}); before the fail-closed change it was worse still, silently
+ * widening to a blanket waiver.
  */
 export const KNOWN_RULE_IDS = new Set([
   // this plugin
@@ -111,7 +133,6 @@ export const KNOWN_RULE_IDS = new Set([
   'search-literal-link',
   'use-search-from-literal',
   'provider-above-router',
-  'duplicate-notifications-mount',
   'query-dual-import',
   'query-fn-unwrap',
   'deprecated-export',
@@ -121,6 +142,7 @@ export const KNOWN_RULE_IDS = new Set([
   'visx-boundary',
   'visx-tooltip',
   'token-layer-boundary',
+  'no-import-meta-env',
   // These three honour `basalt-agent-allow`, never `theme-allow` — but they are real ids, so an
   // annotation naming one must parse as a (useless) scoped annotation rather than as prose.
   'agent-resume-guard',
@@ -142,7 +164,6 @@ export const KNOWN_RULE_IDS = new Set([
   'inline-display',
   'raw-visx-axis',
   'raw-motion-value',
-  'unframed-chart',
   'chart-missing-aria-label',
   'raw-form-control',
   'sub-16-input-font',
@@ -154,6 +175,9 @@ export const KNOWN_RULE_IDS = new Set([
   'hidden-inline-style',
   'in-body-page-title',
   'raw-selection-control',
+  // Retired guard kinds — no longer in GUARD_RULES, but a `theme-allow` naming one must still
+  // parse as a real (dead) waiver rather than an unknown-id typo. See RETIRED_RULE_IDS above.
+  ...RETIRED_RULE_IDS,
 ])
 
 const ALLOW_RULE_TOKEN = /^(?:basalt\/)?([a-z][a-z0-9-]*)(?=$|[\s,:—–])/
@@ -3338,202 +3362,15 @@ const providerAboveRouter = {
   },
 }
 
-// ── Rule 26 — duplicate-notifications-mount ─────────────────────────────────────────────────────
-
-const DUPLICATE_NOTIFICATIONS_MOUNT_MESSAGE =
-  '<BasaltNotifications /> mounted alongside <BasaltOverlays notifications> — the two double-mount ' +
-  "Mantine's <Notifications>, so a single notify() renders twice. BasaltOverlays already composes " +
-  'the notifications layer; drop the standalone mount, or pass `notifications={false}` to ' +
-  'BasaltOverlays if the standalone one is the mount you want. ' +
-  '(basalt/duplicate-notifications-mount)'
-
-/**
- * The ancestor chain from `node` up to its `Program`, OUTERMOST first — captured during the visit,
- * because `node.parent` is only walkable then, and compared at `Program:exit`. Unlike
- * {@link ancestorTagBindings} it keeps the NODES, which is what makes a nearest-common-ancestor
- * question answerable at all.
- */
-function ancestorChain(node) {
-  const chain = []
-  let current = node
-  for (let depth = 0; current !== null && current !== undefined; depth++) {
-    if (depth > ANCESTRY_MAX_DEPTH) break
-    chain.push(current)
-    if (current.type === 'Program') break
-    current = current.parent
-  }
-  return chain.toReversed()
-}
-
-/**
- * True when two nodes sit in DIFFERENT branches of ONE conditional — `a ? <X/> : <Y/>`, or the two
- * operands of one `&&`/`||`. Exactly one of the pair ever renders, so a double-mount rule firing on
- * them would be reporting a mount that cannot happen.
- *
- * Deliberately the NEAREST common ancestor only, and deliberately expression-level: two separate
- * `cond && <X/>` expressions under one parent are NOT exclusive (both conditions can hold), and an
- * `if`/`return` split across statements is a control-flow question this does not pretend to answer.
- * The runtime guard in `src/commands/overlays-mount.tsx` is the lane that counts real mounts.
- */
-function mutuallyExclusive(chainA, chainB) {
-  let i = 0
-  while (i < chainA.length && i < chainB.length && chainA[i] === chainB[i]) i++
-  const ancestor = chainA[i - 1]
-  const branchA = chainA[i]
-  const branchB = chainB[i]
-  if (ancestor === undefined || branchA === undefined || branchB === undefined) return false
-  const [first, second] =
-    ancestor.type === 'ConditionalExpression'
-      ? [ancestor.consequent, ancestor.alternate]
-      : ancestor.type === 'LogicalExpression'
-        ? [ancestor.left, ancestor.right]
-        : [undefined, undefined]
-  if (first === undefined || second === undefined) return false
-  return (branchA === first && branchB === second) || (branchA === second && branchB === first)
-}
-
-/**
- * `<BasaltOverlays notifications>` and `<BasaltNotifications />` in ONE file — F5, the second
- * `basalt-mantine.md` law with no guard, and the static half of a warning that already exists at
- * runtime (`src/commands/overlays-mount.tsx` warns in dev when both mount).
- *
- * A pair split across the two branches of one conditional is EXEMPT: `a ? <BasaltNotifications/> :
- * <BasaltOverlays/>` is a file with two mounts written and one mount rendered, and reporting it
- * taught a consumer to reach for a waiver over code that was already right.
- *
- * `notifications` DEFAULTS to true on `BasaltOverlays`, so the absence of the attribute counts as
- * enabled and only an explicit `notifications={false}` clears it — the same polarity the component
- * itself reads. Both tags are provenance-gated through {@link collectBasaltImportMap}.
- *
- * Same-FILE only, and deliberately so: the runtime warning is the lane that sees a cross-file
- * double mount, because it counts real mounts rather than JSX. This is the cheap half that catches
- * it before the app runs, which is the whole reason a static twin is worth having.
- */
-// Ships: warn (grace → 1.30.0)
-const duplicateNotificationsMount = {
-  meta: {
-    type: 'suggestion',
-    docs: {
-      description: 'Warn when BasaltOverlays and a standalone BasaltNotifications both mount.',
-    },
-    schema: [],
-  },
-  create(context) {
-    if (isTestFile(context)) return {}
-    const ownTree = isBasaltOwnSource(getFilename(context))
-    const basalt = new Map()
-    const mounts = []
-
-    return {
-      ImportDeclaration(node) {
-        collectBasaltImportMap(node, basalt, ownTree)
-      },
-      JSXOpeningElement(node) {
-        const root = jsxRootName(node.name)
-        if (root === undefined || !basalt.has(root)) return
-        // `notifications` DEFAULTS to true, so only an explicit `={false}` clears the layer.
-        const disabled = (node.attributes ?? []).some(
-          (attr) =>
-            attr.type === 'JSXAttribute' &&
-            attr.name?.name === 'notifications' &&
-            unwrapExpressionContainer(attr.value)?.value === false,
-        )
-        mounts.push({ node, root, disabled, chain: ancestorChain(node) })
-      },
-      'Program:exit'() {
-        const overlays = mounts.filter(
-          ({ root, disabled }) => basalt.get(root) === 'BasaltOverlays' && !disabled,
-        )
-        if (overlays.length === 0) return
-        for (const { node, root, chain } of mounts) {
-          if (basalt.get(root) !== 'BasaltNotifications') continue
-          // Every enabled overlays mount on the other branch of one conditional → nothing to report.
-          if (overlays.every((overlay) => mutuallyExclusive(overlay.chain, chain))) continue
-          if (hasThemeAllow(context, node, 'duplicate-notifications-mount')) continue
-          context.report({ node, message: DUPLICATE_NOTIFICATIONS_MOUNT_MESSAGE })
-        }
-      },
-    }
-  },
-}
-
-// ── Rule 27 — query-dual-import ─────────────────────────────────────────────────────────────────
-
-/** `@tanstack/react-query` and its subpaths — never `@tanstack/react-query-devtools`. */
-const TANSTACK_QUERY_SOURCE = /^@tanstack\/react-query(?:\/|$)/
+// Rule 27 — query-dual-import — RETIRED. 1.29.0 dropped every raw TanStack re-export from
+// `basalt-ui/query` (the subpath itself is gone), so "dual-importing `@tanstack/react-query`
+// beside `basalt-ui/query`" is no longer a thing a consumer can even do — a consumer MUST import
+// `@tanstack/react-query` directly now, and this rule warned on every such import (90+ false
+// positives on argo alone). See `RETIRED_RULE_IDS` below.
 
-/** The `basalt-ui/query` subpath, exactly — the seam the hooks are supposed to arrive through. */
+/** The `basalt-ui/query` subpath, exactly — kept for `query-fn-unwrap`'s own gate below. */
 const BASALT_QUERY_SOURCE = 'basalt-ui/query'
 
-/** The root barrel — where `QueryState` and the dashboard composites live. */
-const BASALT_ROOT_SOURCE = 'basalt-ui'
-
-const QUERY_DUAL_IMPORT_MESSAGE =
-  'Dual query import — this file imports from @tanstack/react-query AND from basalt-ui/query. ' +
-  'Take the hooks, the client factory and `unwrap` from basalt-ui/query only: two entry points to ' +
-  'one library is how a second QueryClient, a second devtools bundle and a duplicated ' +
-  '`toErrorMessage` reach an app (agent/rules/basalt-batteries.md). ' +
-  '(basalt/query-dual-import)'
-
-const QUERY_ROOT_IMPORT_MESSAGE =
-  'Raw @tanstack/react-query import in a basalt file — the hooks come through basalt-ui/query, ' +
-  'which re-exports them beside `createBasaltQueryClient`, `unwrap`, `toErrorMessage` and the lazy ' +
-  'devtools (agent/rules/basalt-batteries.md). Import from basalt-ui/query instead. ' +
-  '(basalt/query-dual-import)'
-
-/**
- * The `basalt-batteries.md` law "import query hooks from `basalt-ui/query`, never dual-import
- * `@tanstack/react-query`" — F5, and one of the two `./query` surfaces that shipped advisory.
- *
- * TWO forms, one id, because they are one law read at two strengths. The DUAL form (both
- * specifiers present) is the law verbatim. The softer form — a raw `@tanstack/react-query` import
- * in a file that also imports the basalt root barrel — is a heuristic: it says "this file is
- * already a basalt file, so the query seam is right there", and it is the form that actually
- * catches the drift, since a file that has never heard of `basalt-ui/query` cannot dual-import.
- * The softer form is why the whole rule lands at `warn` rather than `error`.
- *
- * Gated on the LITERAL specifier, never on `ownTree` relative resolution: basalt's own
- * `src/query/**` and `src/dashboard/query-state.tsx` import `@tanstack/react-query` because they
- * ARE the seam, and they reach their siblings relatively. A file that writes `basalt-ui/query` is
- * by definition a consumer of the published surface.
- */
-// Ships: warn (grace → 1.30.0)
-const queryDualImport = {
-  meta: {
-    type: 'suggestion',
-    docs: { description: 'Warn on a raw @tanstack/react-query import beside a basalt import.' },
-    schema: [],
-  },
-  create(context) {
-    if (isTestFile(context)) return {}
-    const raw = []
-    let basaltQuery = false
-    let basaltRoot = false
-
-    return {
-      ImportDeclaration(node) {
-        const source = node.source?.value
-        if (typeof source !== 'string') return
-        if (source === BASALT_QUERY_SOURCE) basaltQuery = true
-        else if (source === BASALT_ROOT_SOURCE) basaltRoot = true
-        // `import type { UseQueryResult } from '@tanstack/react-query'` is erased at compile time
-        // — there is no runtime import to route through the seam, and typing against the library's
-        // own result type is exactly what `QueryStateLike` documents as legitimate. Same skip
-        // `agent-no-raw-usechat` and `ai-sdk-major` take.
-        else if (TANSTACK_QUERY_SOURCE.test(source) && node.importKind !== 'type') raw.push(node)
-      },
-      'Program:exit'() {
-        if (!basaltQuery && !basaltRoot) return
-        const message = basaltQuery ? QUERY_DUAL_IMPORT_MESSAGE : QUERY_ROOT_IMPORT_MESSAGE
-        for (const node of raw) {
-          if (hasThemeAllow(context, node, 'query-dual-import')) continue
-          context.report({ node, message })
-        }
-      },
-    }
-  },
-}
-
 // ── Rule 28 — query-fn-unwrap ───────────────────────────────────────────────────────────────────
 
 const QUERY_FN_UNWRAP_MESSAGE =
@@ -3643,36 +3480,8 @@ const queryFnUnwrap = {
  * @type {readonly DeprecatedExport[]}
  */
 export const DEPRECATED_EXPORTS = [
-  {
-    subpath: 'basalt-ui/forms',
-    name: 'field',
-    replacement: 'inputProps',
-    removeIn: '1.29.0',
-    // Not a drop-in: `inputProps` no longer returns `key`, so a rename alone would silently drop
-    // the reconciler key. The nudge stays; the rewrite is `basalt/forms-field-key`'s job.
-    fix: false,
-  },
-  {
-    subpath: 'basalt-ui',
-    name: 'BasaltProvider',
-    prop: 'sseUrl',
-    replacement: 'connectivity={{ sseUrl }}',
-    removeIn: '1.29.0',
-  },
-  {
-    subpath: 'basalt-ui',
-    name: 'BasaltProvider',
-    prop: 'healthUrl',
-    replacement: 'connectivity={{ healthUrl }}',
-    removeIn: '1.29.0',
-  },
-  {
-    subpath: 'basalt-ui',
-    name: 'BasaltProvider',
-    prop: 'healthIntervalMs',
-    replacement: 'connectivity={{ healthIntervalMs }}',
-    removeIn: '1.29.0',
-  },
+  // Empty since 1.29.0: every 1.28.x deprecation was removed on schedule. The next
+  // deprecation adds a row here in the same commit as its @deprecated JSDoc and MIGRATING entry.
 ]
 
 function deprecatedExportMessage(row) {
@@ -3914,6 +3723,51 @@ const formsFieldKey = {
   },
 }
 
+// ── Rule 31 — no-import-meta-env ────────────────────────────────────────────────────────────────
+
+const NO_IMPORT_META_ENV_MESSAGE =
+  'import.meta.env is banned in shipped basalt-ui source — this package is consumed both as a ' +
+  'Vite-bundled dep AND resolved directly by a consumer whose own bundler may define no ' +
+  'import.meta.env at all (basaltViteConfig defines process.env.NODE_ENV precisely so basalt ' +
+  'code never needs it). Use process.env.NODE_ENV instead. (basalt/no-import-meta-env)'
+
+/**
+ * `import.meta.env` — a MemberExpression whose object is the `import.meta` MetaProperty and whose
+ * property is `env`. Repo-local only: a CONSUMER's own app code legitimately uses
+ * `import.meta.env.VITE_*` for its own config, so this must never reach the shipped preset — only
+ * `/.oxlintrc.json` wires it, scoped to `packages/basalt-ui/src/**` the same way the Mantine-free
+ * boundaries above are scoped, rather than through path logic in the rule itself (unlike
+ * `token-layer-boundary`, which every package resolves the plugin from and so has to self-scope).
+ */
+// Ships: repo-local only
+const noImportMetaEnv = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow import.meta.env — basalt-ui source must use process.env.NODE_ENV.',
+    },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+
+    return {
+      MemberExpression(node) {
+        const object = node.object
+        if (
+          object?.type !== 'MetaProperty' ||
+          object.meta?.name !== 'import' ||
+          object.property?.name !== 'meta'
+        )
+          return
+        if (node.computed || node.property?.name !== 'env') return
+        if (hasThemeAllow(context, node, 'no-import-meta-env')) return
+        context.report({ node, message: NO_IMPORT_META_ENV_MESSAGE })
+      },
+    }
+  },
+}
+
 // ── Grace ledger ────────────────────────────────────────────────────────────────────────────────
 
 /**
@@ -3990,29 +3844,6 @@ export const PLUGIN_RULE_GRACE = {
       'image-gen and the playground is measured — every one of them mounts a router, so the ' +
       'false-positive question has a real sample.',
   },
-  'duplicate-notifications-mount': {
-    since: '1.28.0',
-    promote: '1.30.0',
-    why:
-      'F5 — the static half of a double-mount the runtime already warns about in dev ' +
-      '(`src/commands/overlays-mount.tsx`). Same-file only, so like its sibling it guards a ' +
-      'fraction of the law and cannot claim `error`. It also reads a prop DEFAULT (`notifications` ' +
-      'is true when unwritten), which is the kind of polarity a consumer disagrees with exactly ' +
-      'once before it is worth knowing about — a minor at `warn` is how that disagreement arrives ' +
-      'as feedback rather than as a broken build.',
-  },
-  'query-dual-import': {
-    since: '1.28.0',
-    promote: '1.30.0',
-    why:
-      'F5 — the basalt-batteries.md law with no guard. TWO forms under one id: the dual import ' +
-      '(both `@tanstack/react-query` and `basalt-ui/query` in one file) is the law verbatim, and ' +
-      'the softer form — a raw `@tanstack/react-query` import in a file that also imports the ' +
-      'basalt root barrel — is the heuristic that actually catches the drift, since a file that ' +
-      'never names `basalt-ui/query` cannot dual-import. The soft form is what holds the whole ' +
-      'rule at `warn`: "this file is already a basalt file" is a claim about intent. 1.30.0 is ' +
-      'when the consumer count is measured and the soft form is either kept or split off.',
-  },
   'forms-field-key': {
     since: '1.28.0',
     promote: '1.30.0',
@@ -4097,8 +3928,6 @@ export default {
     'search-literal-link': searchLiteralLink,
     'use-search-from-literal': useSearchFromLiteral,
     'provider-above-router': providerAboveRouter,
-    'duplicate-notifications-mount': duplicateNotificationsMount,
-    'query-dual-import': queryDualImport,
     'query-fn-unwrap': queryFnUnwrap,
     'deprecated-export': deprecatedExport,
     'forms-field-key': formsFieldKey,
@@ -4108,5 +3937,6 @@ export default {
     'agent-resume-guard': agentResumeGuard,
     'agent-no-raw-usechat': agentNoRawUseChat,
     'ai-sdk-major': aiSdkMajor,
+    'no-import-meta-env': noImportMetaEnv,
   },
 }