@critiq/rules 0.0.2 → 0.2.0

package/rules/typescript/ts.react.no-children-prop.rule.yaml

@@ -0,0 +1,34 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-children-prop
+  title: Prefer nested JSX children over the children prop
+  summary: Passing `children` as a named prop is harder to read than composing elements between opening and closing tags.
+  rationale: Nested children match React composition idioms and keep component APIs consistent across the tree.
+  tags:
+    - react
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.children-prop
+    bind: issue
+emit:
+  finding:
+    category: maintainability.ui
+    severity: low
+    confidence: 0.8
+    tags:
+      - react
+      - ui
+  message:
+    title: Nest JSX children instead of using the children prop
+    summary: "`${captures.issue.text}` passes children through a prop attribute."
+  remediation:
+    summary: Place child elements between the component tags or accept `children` through normal function parameters without a JSX prop.

package/rules/typescript/ts.react.no-click-without-keyboard-handler.rule.yaml

@@ -0,0 +1,36 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-click-without-keyboard-handler
+  title: Support keyboard interaction for click handlers
+  summary: "Non-interactive JSX elements that respond to clicks also need an equivalent keyboard path."
+  rationale: Mouse-only interaction blocks keyboard users and creates inaccessible custom controls that do not behave like native UI elements.
+  tags:
+    - react
+    - accessibility
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.click-without-keyboard-handler
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: high
+    confidence: 0.84
+    tags:
+      - react
+      - accessibility
+      - ui
+  message:
+    title: Add keyboard support to click-driven UI
+    summary: "`${captures.issue.text}` handles clicks without an equivalent keyboard event."
+  remediation:
+    summary: Prefer native buttons or links, or add the necessary role, focus behavior, and keyboard handlers for the same action.

package/rules/typescript/ts.react.no-deprecated-create-factory.rule.yaml

@@ -0,0 +1,34 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-deprecated-create-factory
+  title: Avoid React.createFactory
+  summary: "`createFactory` is a legacy helper for pre-JSX code and is removed from modern React typings and guidance."
+  rationale: Function components and JSX provide clearer element construction without the indirection and weaker typing of factory helpers.
+  tags:
+    - react
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.deprecated-create-factory
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: low
+    confidence: 0.86
+    tags:
+      - react
+      - ui
+  message:
+    title: Replace createFactory with JSX or createElement
+    summary: "`${captures.issue.text}` relies on the deprecated `createFactory` helper."
+  remediation:
+    summary: Inline JSX, call `React.createElement` with explicit props, or convert the call site to a small function component.

package/rules/typescript/ts.react.no-deprecated-react-dom-root-api.rule.yaml

@@ -0,0 +1,34 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-deprecated-react-dom-root-api
+  title: Migrate off legacy ReactDOM render entrypoints
+  summary: "`render`, `hydrate`, and `unmountComponentAtNode` from `react-dom` are legacy APIs replaced by the `createRoot` and `hydrateRoot` clients."
+  rationale: The concurrent renderer expects roots created through the client API; legacy entrypoints block adoption of React 18 streaming and suspense features.
+  tags:
+    - react
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.deprecated-react-dom-root-api
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: medium
+    confidence: 0.88
+    tags:
+      - react
+      - ui
+  message:
+    title: Switch to createRoot or hydrateRoot
+    summary: "`${captures.issue.text}` calls a deprecated ReactDOM mounting API."
+  remediation:
+    summary: Import `createRoot` or `hydrateRoot` from `react-dom/client`, create a root once, and use `root.render` for updates instead of legacy `ReactDOM.render`.

package/rules/typescript/ts.react.no-derived-state-from-props.rule.yaml

@@ -0,0 +1,34 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-derived-state-from-props
+  title: Avoid initializing state directly from props
+  summary: Duplicating props into useState without an explicit sync strategy hides updates and confuses controlled versus uncontrolled boundaries.
+  rationale: Props-driven initial state goes stale when props change unless you synchronize intentionally or lift state up.
+  tags:
+    - react
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.derived-state-from-props
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: medium
+    confidence: 0.72
+    tags:
+      - react
+      - ui
+  message:
+    title: Derive values from props without fragile state copies
+    summary: "`${captures.issue.text}` initializes state from incoming props."
+  remediation:
+    summary: Prefer controlled props, derive with useMemo, or synchronize with useEffect when props legitimately own the value.

package/rules/typescript/ts.react.no-direct-state-mutation.rule.yaml

@@ -0,0 +1,34 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-direct-state-mutation
+  title: Do not mutate React state directly
+  summary: Assigning to `this.state` bypasses React change detection and produces stale UI.
+  rationale: State updates must flow through setState or hooks so React can schedule renders and enforce immutability guarantees.
+  tags:
+    - react
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.direct-state-mutation
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: high
+    confidence: 0.88
+    tags:
+      - react
+      - ui
+  message:
+    title: Update React state with setState
+    summary: "`${captures.issue.text}` mutates state directly."
+  remediation:
+    summary: Call setState with the next value or replace the state object immutably instead of assigning into this.state.

package/rules/typescript/ts.react.no-duplicate-jsx-attributes.rule.yaml

@@ -0,0 +1,34 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-duplicate-jsx-attributes
+  title: Remove duplicate JSX attributes
+  summary: Repeating the same prop on a JSX element makes the last value win silently and hides author intent.
+  rationale: Duplicate attributes are usually copy-paste mistakes that change runtime behavior without type errors.
+  tags:
+    - react
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.duplicate-jsx-attribute
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: medium
+    confidence: 0.9
+    tags:
+      - react
+      - ui
+  message:
+    title: Keep only one JSX attribute with the same name
+    summary: "`${captures.issue.text}` appears more than once on the same JSX element."
+  remediation:
+    summary: Remove the duplicate attribute or merge the values into a single prop expression.

package/rules/typescript/ts.react.no-effect-fetch-without-cancellation.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-effect-fetch-without-cancellation
+  title: Cancel inflight fetches inside React effects
+  summary: React effects that fetch remote data should attach AbortSignal wiring so stale responses cannot commit after dependencies change.
+  rationale: Race conditions from abandoned requests produce inconsistent UI state and duplicated side effects when identifiers or routes change quickly.
+  tags:
+    - performance
+    - react
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: performance.react-effect-fetch-without-cancellation
+    bind: issue
+emit:
+  finding:
+    category: performance.ui
+    severity: medium
+    confidence: 0.74
+    tags:
+      - performance
+      - react
+  message:
+    title: Abort stale fetch responses inside effects
+    summary: "`${captures.issue.text}` loads remote data without an AbortSignal or comparable cancellation guard."
+  remediation:
+    summary: >-
+      Thread AbortController.signal through fetch or axios calls and abort inside the effect cleanup, or migrate to a data library that manages cancellation.

package/rules/typescript/ts.react.no-find-dom-node.rule.yaml

@@ -0,0 +1,34 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-find-dom-node
+  title: Avoid ReactDOM.findDOMNode
+  summary: "`findDOMNode` reaches through component boundaries with a deprecated escape hatch that breaks strict mode migrations."
+  rationale: Direct DOM lookups make React trees harder to refactor and fail to model multi-node or fragment-based rendering safely.
+  tags:
+    - react
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.find-dom-node
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: medium
+    confidence: 0.8
+    tags:
+      - react
+      - ui
+  message:
+    title: "Replace `findDOMNode` with direct refs"
+    summary: "`${captures.issue.text}` uses the deprecated `findDOMNode` API."
+  remediation:
+    summary: Attach a ref directly to the rendered element, or forward refs through component boundaries instead of reading DOM nodes imperatively.

package/rules/typescript/ts.react.no-img-missing-alt-text.rule.yaml

@@ -0,0 +1,36 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-img-missing-alt-text
+  title: Add alt text to meaningful images
+  summary: "JSX images need a meaningful `alt` value, or an explicit empty string when the image is decorative."
+  rationale: Missing alternative text hides visual meaning from screen reader users and creates avoidable accessibility regressions.
+  tags:
+    - react
+    - accessibility
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.missing-alt-text
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: high
+    confidence: 0.87
+    tags:
+      - react
+      - accessibility
+      - ui
+  message:
+    title: Add alternative text to images
+    summary: "`${captures.issue.text}` renders without alternative text."
+  remediation:
+    summary: "Add a meaningful `alt` string, or set `alt=\"\"` only when the image is purely decorative and redundant."

package/rules/typescript/ts.react.no-index-as-key-in-dynamic-list.rule.yaml

@@ -0,0 +1,34 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-index-as-key-in-dynamic-list
+  title: Avoid array index keys in dynamic lists
+  summary: Using the map index as a React key breaks reconciliation when lists reorder, filter, or insert items.
+  rationale: Stable keys help React preserve component state and reduce subtle UI bugs when list membership changes.
+  tags:
+    - react
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.index-key-in-list
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: medium
+    confidence: 0.78
+    tags:
+      - react
+      - ui
+  message:
+    title: Replace index keys with stable identifiers
+    summary: "`${captures.issue.text}` uses a list index as a React key."
+  remediation:
+    summary: Use a stable business identifier from each item, or derive a stable key when the dataset truly never mutates order.

package/rules/typescript/ts.react.no-interactive-role-on-static-semantics.rule.yaml

@@ -0,0 +1,36 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-interactive-role-on-static-semantics
+  title: Keep interactive roles off static semantics
+  summary: "Headings, captions, and phrasing content should not pretend to be buttons or tabs without restructuring the markup."
+  rationale: Mixing document roles with widget roles confuses assistive technologies and usually signals a heading or label that should stay static while a real control sits nearby.
+  tags:
+    - react
+    - accessibility
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.semantic-static-with-interactive-role
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: medium
+    confidence: 0.78
+    tags:
+      - react
+      - accessibility
+      - ui
+  message:
+    title: Avoid widget roles on semantic text elements
+    summary: "`${captures.issue.text}` assigns an interactive ARIA role to a semantic text element."
+  remediation:
+    summary: Move the interaction to a sibling `button` or link, keep the heading for structure only, and wire behaviour with IDs or aria-controls instead of overloading roles.

package/rules/typescript/ts.react.no-invalid-anchor-href.rule.yaml

@@ -0,0 +1,36 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-invalid-anchor-href
+  title: Use real destinations for anchor elements
+  summary: "Links need a concrete `href` so navigation, keyboard activation, and assistive technologies behave predictably."
+  rationale: Placeholder anchors and `javascript:` URLs break expectations for links, harm accessibility, and often hide ad-hoc click handlers that should be buttons instead.
+  tags:
+    - react
+    - accessibility
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.anchor-with-invalid-href
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: medium
+    confidence: 0.82
+    tags:
+      - react
+      - accessibility
+      - ui
+  message:
+    title: Give anchors a valid href
+    summary: "`${captures.issue.text}` is an anchor without a usable navigation target."
+  remediation:
+    summary: Point `href` at a real URL or in-page fragment, use a native button for actions, or add an explicit widget role with keyboard support when mimicking controls.

package/rules/typescript/ts.react.no-jsx-props-spread.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-jsx-props-spread
+  title: Avoid spreading props onto JSX elements
+  summary: Unfiltered prop spreads hide which attributes reach the DOM and defeat static analysis of event handlers and accessibility props.
+  rationale: Explicit prop forwarding documents the component contract and avoids accidentally passing invalid or sensitive attributes downstream.
+  tags:
+    - react
+    - performance
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.jsx-props-spread
+    bind: issue
+emit:
+  finding:
+    category: maintainability.ui
+    severity: low
+    confidence: 0.75
+    tags:
+      - react
+      - ui
+  message:
+    title: Forward JSX props explicitly
+    summary: "`${captures.issue.text}` spreads props onto a JSX element."
+  remediation:
+    summary: Destructure the props you intend to pass, whitelist safe attributes, or use a typed wrapper component.

package/rules/typescript/ts.react.no-keyboard-interaction-without-widget-role.rule.yaml

@@ -0,0 +1,36 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-keyboard-interaction-without-widget-role
+  title: Declare a widget role when mixing click and key handlers
+  summary: "Elements that handle both clicks and key events behave like custom controls and should advertise an appropriate ARIA role."
+  rationale: Assistive technologies cannot infer widget behaviour from events alone; an explicit role pairs keyboard support with the correct accessibility tree semantics.
+  tags:
+    - react
+    - accessibility
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.keyboard-interaction-without-widget-role
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: medium
+    confidence: 0.8
+    tags:
+      - react
+      - accessibility
+      - ui
+  message:
+    title: Add a widget role for custom controls
+    summary: "`${captures.issue.text}` combines click and keyboard handlers without a widget role."
+  remediation:
+    summary: Set `role="button"` or another fitting widget role, ensure focusability, and mirror native control keyboard patterns.

package/rules/typescript/ts.react.no-legacy-lifecycle.rule.yaml

@@ -0,0 +1,34 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-legacy-lifecycle
+  title: Avoid legacy React lifecycle methods
+  summary: Legacy class lifecycle hooks are brittle in strict mode and block migration toward modern React patterns.
+  rationale: Deprecated lifecycle methods are easy to misuse during async rendering and create noisy upgrade work across older React codebases.
+  tags:
+    - react
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.legacy-lifecycle
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: medium
+    confidence: 0.76
+    tags:
+      - react
+      - ui
+  message:
+    title: Replace legacy React lifecycle methods
+    summary: "`${captures.issue.text}` is a legacy React lifecycle method."
+  remediation:
+    summary: "Prefer modern lifecycle alternatives, hooks, or an explicit `UNSAFE_` migration name only as a short-lived bridge."

package/rules/typescript/ts.react.no-missing-error-boundary.rule.yaml

@@ -0,0 +1,36 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-missing-error-boundary
+  title: Add a route-level error boundary for Next.js App Router segments
+  summary: Next.js route segments should declare an error.tsx handler so async and client failures surface safely.
+  rationale: Without a segment error boundary, failures in pages or layouts can crash the entire subtree without recovery UI.
+  tags:
+    - react
+    - next
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: project
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.missing-error-boundary
+    bind: issue
+emit:
+  finding:
+    category: correctness.framework
+    severity: medium
+    confidence: 0.75
+    tags:
+      - react
+      - next
+      - ui
+  message:
+    title: Provide error.tsx for App Router segments
+    summary: "`${captures.issue.text}` is missing a sibling error boundary file for its route segment."
+  remediation:
+    summary: Add error.tsx next to the segment’s page or layout, or hoist shared handling to a parent segment.

package/rules/typescript/ts.react.no-positive-tabindex.rule.yaml

@@ -0,0 +1,36 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-positive-tabindex
+  title: Avoid positive tabIndex values
+  summary: "Positive `tabIndex` values create a custom keyboard order that is fragile and usually less accessible than DOM order."
+  rationale: Manual focus sequencing is easy to break as layouts evolve and makes keyboard navigation less predictable for assistive-technology users.
+  tags:
+    - react
+    - accessibility
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.positive-tabindex
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: medium
+    confidence: 0.85
+    tags:
+      - react
+      - accessibility
+      - ui
+  message:
+    title: Keep keyboard focus order natural
+    summary: "`${captures.issue.text}` uses a positive `tabIndex` value."
+  remediation:
+    summary: "Prefer source-order focus flow, use `tabIndex={0}` only when needed, and reserve negative values for programmatic focus targets."

package/rules/typescript/ts.react.no-set-state-in-component-did-mount.rule.yaml

@@ -0,0 +1,34 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-set-state-in-component-did-mount
+  title: Avoid setState in componentDidMount
+  summary: Synchronous state updates during mount trigger an extra render before the browser paints the initial tree.
+  rationale: Initial state belongs in the constructor or class field initializers so the first render already reflects the mounted view.
+  tags:
+    - react
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.set-state-in-component-did-mount
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: medium
+    confidence: 0.82
+    tags:
+      - react
+      - ui
+  message:
+    title: Initialize state before mount completes
+    summary: "`${captures.issue.text}` calls setState inside componentDidMount."
+  remediation:
+    summary: Move the initial value into state initialization or derive it from props with a guarded update strategy.