@critiq/rules 0.2.0 → 0.4.0

package/rules/typescript/ts.correctness.unsafe-negation-in-relational.rule.yaml

@@ -0,0 +1,38 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.correctness.unsafe-negation-in-relational
+  title: Negated left operand in relational expression
+  summary: A relational or membership test applies unary `!` to the left operand instead of negating the whole comparison.
+  rationale: Expressions like `!key in object` parse as `(!key) in object`, which is usually not what authors intend.
+  aliases:
+    - JS-0019
+  tags:
+    - correctness
+    - language
+    - rules-catalog
+    - crq-cor-042
+    - public-directory-parity
+  stability: stable
+  appliesTo: file
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: language.unsafe-negation-in-relational
+    bind: issue
+emit:
+  finding:
+    category: correctness.language
+    severity: medium
+    confidence: 0.9
+    tags:
+      - correctness
+      - language
+  message:
+    title: Parenthesize negated relational comparisons
+    summary: "`${captures.issue.text}` negates only the left operand of a relational or membership operator."
+  remediation:
+    summary: Wrap the full comparison in parentheses, for example `!(left in right)` or `!(left instanceof Type)`.

package/rules/typescript/ts.correctness.unused-expression.rule.yaml

@@ -0,0 +1,37 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.correctness.unused-expression
+  title: Unused expressions found
+  summary: Expression statement has no side effects and its result is discarded.
+  rationale: Expressions without side effects whose results are discarded indicate dead code or a programming mistake (e.g., `a && b` instead of `if (a) b()`).
+  aliases:
+    - JS-B003
+  tags:
+    - correctness
+    - language
+    - rules-catalog
+    - public-directory-parity
+  stability: experimental
+  appliesTo: block
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: language.unused-expression
+    bind: issue
+emit:
+  finding:
+    category: correctness.language
+    severity: medium
+    confidence: 0.70
+    tags:
+      - correctness
+      - language
+  message:
+    title: Remove or use the result of this expression
+    summary: "`${captures.issue.text}` has no side effects and its result is discarded."
+  remediation:
+    summary: Either assign the expression result to a variable, use it in a condition, or remove the dead code entirely.

package/rules/typescript/ts.correctness.unused-variable.rule.yaml

@@ -0,0 +1,37 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.correctness.unused-variable
+  title: Unused variable
+  summary: Detects unused variable issues in JavaScript and TypeScript source.
+  rationale: Unused variables represent dead code and cleanup opportunities; they rarely indicate correctness bugs.
+  aliases:
+    - JS-0128
+  tags:
+    - correctness
+    - language
+    - rules-catalog
+    - public-directory-parity
+  stability: stable
+  appliesTo: file
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: language.unused-variable
+    bind: issue
+emit:
+  finding:
+    category: correctness.language
+    severity: low
+    confidence: 0.55
+    tags:
+      - correctness
+      - language
+  message:
+    title: Fix unused variable
+    summary: "`${captures.issue.text}` matches ts.correctness.unused-variable."
+  remediation:
+    summary: Refactor the code to remove the unused variable pattern.

package/rules/typescript/ts.correctness.use-number-is-nan.rule.yaml

@@ -5,6 +5,8 @@ metadata:
   title: Use Number.isNaN for NaN checks
   summary: Do not compare values to NaN with `===` or `==`.
   rationale: NaN is not equal to itself; identity comparisons are always false.
+  aliases:
+    - JS-0027
   tags:
     - correctness
     - language

package/rules/typescript/ts.correctness.used-before-definition.rule.yaml

@@ -0,0 +1,38 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.correctness.used-before-definition
+  title: Variable used before definition
+  summary: Detects variable used before definition issues in JavaScript and TypeScript source.
+  rationale: Variable used-before-definition patterns are mostly hoisting and TDZ analysis artifacts; they rarely indicate real bugs.
+  aliases:
+    - JS-0129
+    - JS-0357
+  tags:
+    - correctness
+    - language
+    - rules-catalog
+    - public-directory-parity
+  stability: stable
+  appliesTo: file
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: language.used-before-definition
+    bind: issue
+emit:
+  finding:
+    category: correctness.language
+    severity: low
+    confidence: 0.50
+    tags:
+      - correctness
+      - language
+  message:
+    title: Fix variable used before definition
+    summary: "`${captures.issue.text}` matches ts.correctness.used-before-definition."
+  remediation:
+    summary: Refactor the code to remove the variable used before definition pattern.

package/rules/typescript/ts.correctness.var-declaration.rule.yaml

@@ -0,0 +1,38 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.correctness.var-declaration
+  title: var declaration instead of let or const
+  summary: Consider using `let` or `const` instead of `var`.
+  rationale: var declarations are function-scoped and can cause subtle hoisting bugs; let and const provide block scoping and clearer intent.
+  aliases:
+    - JS-0239
+  tags:
+    - correctness
+    - language
+    - rules-catalog
+    - crq-cor-047
+    - public-directory-parity
+  stability: stable
+  appliesTo: file
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: language.var-declaration
+    bind: issue
+emit:
+  finding:
+    category: correctness.language
+    severity: low
+    confidence: 1.0
+    tags:
+      - correctness
+      - language
+  message:
+    title: Prefer let or const over var
+    summary: "`${captures.issue.text}` declares with `var` instead of `let` or `const`."
+  remediation:
+    summary: Replace `var` with `let` for reassignable bindings or `const` for constant bindings.

package/rules/typescript/ts.next.no-document-import-outside-custom-document.rule.yaml

@@ -0,0 +1,39 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.next.no-document-import-outside-custom-document
+  title: Avoid importing next/document outside the custom document file
+  summary: next/document should only be imported in pages/_document.(ts|tsx) or src/pages/_document.(ts|tsx).
+  rationale: The next/document module is designed exclusively for customizing the HTML document shell in Next.js Pages Router. Importing it in other files indicates a misunderstanding of Next.js rendering architecture and may cause runtime errors or confusing component boundaries.
+  aliases:
+    - JS-E1002
+  tags:
+    - next
+    - react
+    - correctness
+    - rules-catalog
+    - public-directory-parity
+  stability: experimental
+  appliesTo: file
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: framework.next.document-import-outside-custom-document
+    bind: issue
+emit:
+  finding:
+    category: correctness.framework
+    severity: high
+    confidence: 0.95
+    tags:
+      - next
+      - react
+      - correctness
+  message:
+    title: Move next/document import to _document file
+    summary: "next/document is imported outside of _document.tsx — this module only works in the custom document file."
+  remediation:
+    summary: Remove the next/document import or move it to pages/_document.(ts|tsx).

package/rules/typescript/ts.next.no-head-import-in-custom-document.rule.yaml

@@ -0,0 +1,39 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.next.no-head-import-in-custom-document
+  title: Avoid importing next/head in the custom document file
+  summary: pages/_document should use next/document's Head component, not next/head.
+  rationale: In Next.js, the custom document (pages/_document) should use the Head export from next/document, not next/head. Using next/head inside _document causes incorrect head element management and breaks the expected component hierarchy.
+  aliases:
+    - JS-E1003
+  tags:
+    - next
+    - react
+    - correctness
+    - rules-catalog
+    - public-directory-parity
+  stability: experimental
+  appliesTo: file
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: framework.next.head-import-in-custom-document
+    bind: issue
+emit:
+  finding:
+    category: correctness.framework
+    severity: high
+    confidence: 0.95
+    tags:
+      - next
+      - react
+      - correctness
+  message:
+    title: Use next/document's Head instead of next/head in _document
+    summary: "next/head is imported in _document.tsx — use Head from next/document instead."
+  remediation:
+    summary: Replace `import Head from 'next/head'` with `import { Head } from 'next/document'`.

package/rules/typescript/ts.performance.no-await-in-loop.rule.yaml

@@ -2,9 +2,9 @@ apiVersion: critiq.dev/v1alpha1
 kind: Rule
 metadata:
   id: ts.performance.no-await-in-loop
-  title: No Await In Loop
-  summary: Avoid await inside loops
-  rationale: Avoid await inside loops:sequential awaits in loops multiply latency; batch work or use Promise.all when safe.
+  title: Sequential await in loop -- consider Promise.all() to parallelize
+  summary: Using await inside a loop serializes async operations, multiplying total latency.
+  rationale: Each await inside a loop pauses until the promise resolves before starting the next iteration. Collect promises into an array and await Promise.all instead.
   tags:
     - performance
     - rules-catalog
@@ -26,7 +26,7 @@ emit:
     tags:
       - performance
   message:
-    title: No Await In Loop
-    summary: "`${captures.issue.text}` matches ts.performance.no-await-in-loop."
+    title: Sequential await in loop
+    summary: "${captures.issue.text} uses await inside a loop -- this serializes async operations. If the operations are independent, collect promises and use Promise.all()."
   remediation:
-    summary: Avoid await inside loops:sequential awaits in loops multiply latency; batch work or use Promise.all when safe.
+    summary: Use Promise.all to run independent async operations concurrently, e.g. await Promise.all(items.map(item => process(item))).

package/rules/typescript/ts.performance.no-json-parse-stringify-clone.rule.yaml

@@ -14,6 +14,14 @@ scope:
   languages:
     - typescript
     - javascript
+  paths:
+    exclude:
+      - "**/test/**"
+      - "**/tests/**"
+      - "**/__tests__/**"
+      - "**/*.test.*"
+      - "**/*.spec.*"
+      - "**/examples/**"
 match:
   fact:
     kind: performance.no-json-parse-stringify-clone

package/rules/typescript/ts.performance.sequential-async-calls.rule.yaml

@@ -2,9 +2,9 @@ apiVersion: critiq.dev/v1alpha1
 kind: Rule
 metadata:
   id: ts.performance.sequential-async-calls
-  title: Sequential async calls that could run in parallel
-  summary: Independent awaited calls in the same block should not serialize unnecessarily.
-  rationale: Awaiting unrelated async operations one by one increases end-to-end latency without adding correctness.
+  title: Parallelize independent async calls with Promise.all
+  summary: Independent awaited calls in the same block should run concurrently. Skips test files, build scripts, and data-dependent chains.
+  rationale: Awaiting unrelated async operations one by one stalls the event loop and adds unnecessary wall-clock time without improving correctness or error isolation.
   tags:
     - performance
     - async
@@ -16,6 +16,15 @@ scope:
   languages:
     - typescript
     - javascript
+  paths:
+    exclude:
+      - "**/*.test.*"
+      - "**/*.spec.*"
+      - "**/__tests__/**"
+      - "**/tests/**"
+      - "**/test/**"
+      - "**/docs/**"
+      - "**/scripts/**"
 match:
   fact:
     kind: performance.sequential-async-calls
@@ -23,13 +32,13 @@ match:
 emit:
   finding:
     category: performance.async
-    severity: medium
+    severity: low
     confidence: 0.8
     tags:
       - performance
       - async
   message:
-    title: Parallelize independent async calls
-    summary: "`${captures.issue.text}` is awaited after an independent async call and may serialize work unnecessarily."
+    title: Parallelize independent async calls with `Promise.all`
+    summary: "`${captures.issue.text}` has no data dependency on the previous awaited call and could run concurrently."
   remediation:
-    summary: Start both operations first and await them together, for example with `Promise.all(...)`.
+    summary: Start all independent operations first, then await them together with `Promise.all(...)`. Do not apply when the second call depends on the first call's result, inside error-handling chains, or in build/test scripts where sequential ordering or state isolation is intentional.

package/rules/typescript/ts.quality.no-banned-type.rule.yaml

@@ -0,0 +1,36 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.quality.no-banned-type
+  title: Avoid `any` type
+  summary: Using the `any` type defeats TypeScript's type safety guarantees.
+  rationale: The `any` type disables all type checking for the affected expression, hiding potential type errors.
+  aliases:
+    - JS-0296
+  tags:
+    - quality
+    - typescript
+    - rules-catalog
+    - public-directory-parity
+  stability: experimental
+  appliesTo: block
+scope:
+  languages:
+    - typescript
+match:
+  fact:
+    kind: quality.banned-type
+    bind: issue
+emit:
+  finding:
+    category: quality.type-safety
+    severity: medium
+    confidence: 0.7
+    tags:
+      - quality
+      - typescript
+  message:
+    title: Replace `any` type
+    summary: "`${captures.issue.text}` uses the `any` type. Use a specific type or `unknown` instead."
+  remediation:
+    summary: Replace `any` with a more specific type, or use `unknown` with proper type narrowing. Consider enabling `strict` mode in tsconfig.

package/rules/typescript/ts.quality.no-empty-function.rule.yaml

@@ -22,7 +22,7 @@ emit:
   finding:
     category: quality
     severity: low
-    confidence: 0.85
+    confidence: 0.45
     tags:
       - quality
   message:

package/rules/typescript/ts.quality.no-side-effect-in-pure-callback.rule.yaml

@@ -0,0 +1,36 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.quality.no-side-effect-in-pure-callback
+  title: Avoid side effects in getters and pure callbacks
+  summary: Getters and transformation callbacks (map/filter/reduce) should not produce side effects such as assignments or mutations.
+  rationale: Side effects in getters violate the principle of least surprise and can cause hard-to-debug reactivity issues. Getters are expected to be idempotent and side-effect-free.
+  aliases:
+    - JS-0804
+  tags:
+    - quality
+    - maintainability
+    - rules-catalog
+  stability: experimental
+  appliesTo: block
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: quality.side-effect-in-getter
+    bind: issue
+emit:
+  finding:
+    category: quality.maintainability
+    severity: high
+    confidence: 0.78
+    tags:
+      - quality
+      - maintainability
+  message:
+    title: Side effect detected in getter
+    summary: "${captures.issue.text} performs a side effect inside a getter. Getters should only compute and return derived values."
+  remediation:
+    summary: Move the side effect into a method or setter. The getter should remain pure and only return a computed value.

package/rules/typescript/ts.quality.swallowed-error.rule.yaml

@@ -4,7 +4,10 @@ metadata:
   id: ts.quality.swallowed-error
   title: Errors swallowed silently
   summary: Catch blocks must log, reject, or rethrow failures instead of dropping them silently.
-  rationale: Silent catch blocks hide failures and make production diagnosis unnecessarily difficult.
+  rationale: >-
+    Silent catch blocks hide failures and make production diagnosis difficult.
+    Context-dependent callback propagation through error sinks is valid handling
+    and this rule may flag legitimate patterns.
   tags:
     - quality
     - error-handling
@@ -23,8 +26,8 @@ match:
 emit:
   finding:
     category: quality.error-handling
-    severity: medium
-    confidence: 0.95
+    severity: low
+    confidence: 0.55
     tags:
       - quality
       - error-handling

package/rules/typescript/ts.react.no-deprecated-is-mounted.rule.yaml

@@ -0,0 +1,36 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-deprecated-is-mounted
+  title: Avoid deprecated isMounted method
+  summary: isMounted is a legacy anti-pattern that leads to stale references and masks async lifecycle bugs.
+  rationale: The isMounted pattern is removed in newer React versions and indicates a design where asynchronous work outlives the component. Use cancellation tokens or AbortController instead.
+  aliases:
+    - JS-0446
+  tags:
+    - react
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.deprecated-is-mounted
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: high
+    confidence: 0.9
+    tags:
+      - react
+      - ui
+  message:
+    title: Replace isMounted with cancelable async patterns
+    summary: "${captures.issue.text} uses the deprecated isMounted pattern."
+  remediation:
+    summary: Track the mounted state with a useRef flag or cancel subscriptions with AbortController and useEffect cleanup.

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

@@ -15,6 +15,11 @@ scope:
   languages:
     - typescript
     - javascript
+  paths:
+    exclude:
+      - "**/types/react-dom/v15/**"
+      - "**/types/react-dom/v16/**"
+      - "**/embed-*/**"
 match:
   fact:
     kind: ui.react.deprecated-react-dom-root-api
@@ -29,6 +34,23 @@ emit:
       - ui
   message:
     title: Switch to createRoot or hydrateRoot
-    summary: "`${captures.issue.text}` calls a deprecated ReactDOM mounting API."
+    summary: "${captures.issue.text} calls a deprecated ReactDOM mounting API. In React 18+, use `createRoot` or `hydrateRoot` instead. Note that embed SDKs and packages targeting React 16/17 may intentionally use `ReactDOM.render` for cross-version compatibility."
   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`.
+    summary: |-
+      Import `createRoot` or `hydrateRoot` from `react-dom/client`, create a root once, and use `root.render` for updates instead of legacy `ReactDOM.render`.
+
+      If this is an embed SDK or widget package that must support React 16/17 users, `ReactDOM.render` is intentionally used for cross-version compatibility. In that case, add a `// critiq-ignore` comment to suppress this finding.
+
+      ### React 18+ migration
+
+      ```typescript
+      import { createRoot } from 'react-dom/client';
+
+      const root = createRoot(document.getElementById('root')!);
+      root.render(<App />);
+      ```
+
+      ### References
+
+      - React 18 migration guide: https://react.dev/blog/2022/03/08/react-18-upgrade-guide
+      - CWE-477: Use of Obsolete Functions

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

@@ -5,6 +5,8 @@ metadata:
   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.
+  aliases:
+    - JS-0444
   tags:
     - react
     - ui

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

@@ -5,6 +5,8 @@ metadata:
   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.
+  aliases:
+    - JS-0419
   tags:
     - react
     - ui

package/rules/typescript/ts.react.no-hooks-rule-violation.rule.yaml

@@ -0,0 +1,38 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-hooks-rule-violation
+  title: Avoid React hook violations
+  summary: React hooks must only be called at the top level of React function components or custom hooks, not inside conditions, loops, or regular functions.
+  rationale: React relies on call order to preserve hook state between renders. Conditional or looped hooks break this contract and cause subtle bugs like stale state, missing effects, or crashes.
+  aliases:
+    - JS-0820
+  tags:
+    - react
+    - hooks
+    - correctness
+    - rules-catalog
+  stability: experimental
+  appliesTo: block
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: framework.react.hooks-rule-violation
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: high
+    confidence: 0.80
+    tags:
+      - react
+      - hooks
+      - correctness
+  message:
+    title: Fix React hook violation
+    summary: "${captures.issue.text} calls a React hook in an invalid position. Hooks must only be called at the top level of a component or custom hook."
+  remediation:
+    summary: Move the hook call to the top level of the component or custom hook. Do not call hooks inside conditions, loops, or non-component functions.

package/rules/typescript/ts.react.no-invalid-markup-characters.rule.yaml

@@ -0,0 +1,36 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.react.no-invalid-markup-characters
+  title: Invalid characters in JSX markup
+  summary: Control characters and zero-width Unicode codepoints in JSX text content can cause rendering anomalies and accessibility issues.
+  rationale: Non-printable characters in rendered text are invisible to users but may break layout, screen readers, or text-processing pipelines.
+  aliases:
+    - JS-0454
+  tags:
+    - react
+    - ui
+    - rules-catalog
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: ui.react.invalid-markup-characters
+    bind: issue
+emit:
+  finding:
+    category: correctness.ui
+    severity: medium
+    confidence: 0.85
+    tags:
+      - react
+      - ui
+  message:
+    title: Remove invalid characters from JSX text
+    summary: JSX text content contains invisible control or zero-width characters.
+  remediation:
+    summary: Strip or replace non-printable and zero-width characters from JSX text content.