@critiq/rules 0.0.1

package/rules/typescript/ts.correctness.optional-value-without-fallback.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.correctness.optional-value-without-fallback
+  title: Optional value used without fallback
+  summary: Optional values should be normalized before arithmetic, concatenation, or other direct use.
+  rationale: Using maybe-undefined values in ordinary expressions bakes uncertainty into the result and can fail or stringify unexpectedly at runtime.
+  tags:
+    - correctness
+    - "null"
+    - rules-catalog
+    - crq-cor-004
+  stability: stable
+  appliesTo: block
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: data-flow.optional-value-without-fallback
+    bind: issue
+emit:
+  finding:
+    category: correctness.null
+    severity: medium
+    confidence: 0.8
+    tags:
+      - correctness
+      - "null"
+  message:
+    title: Normalize optional values before using them
+    summary: "`${captures.issue.text}` uses a maybe-missing value without a fallback."
+  remediation:
+    summary: Add `??`, `||`, or an explicit guard so the expression always receives a defined value.

package/rules/typescript/ts.correctness.possible-null-dereference.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.correctness.possible-null-dereference
+  title: Possible null or undefined dereference
+  summary: Nullable values should be guarded before property access or invocation.
+  rationale: Dereferencing a value that can still be null or undefined causes avoidable runtime failures on common unhappy paths.
+  tags:
+    - correctness
+    - "null"
+    - rules-catalog
+    - crq-cor-001
+  stability: stable
+  appliesTo: block
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: data-flow.possible-null-dereference
+    bind: issue
+emit:
+  finding:
+    category: correctness.null
+    severity: high
+    confidence: 0.85
+    tags:
+      - correctness
+      - "null"
+  message:
+    title: Guard nullable values before dereferencing
+    summary: "`${captures.issue.text}` dereferences a value that may still be null or undefined."
+  remediation:
+    summary: Add an explicit guard, use optional chaining deliberately, or provide a fallback before dereferencing the value.

package/rules/typescript/ts.correctness.shared-state-race.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.correctness.shared-state-race
+  title: Race condition on shared state
+  summary: Async functions that mutate shared state after an await boundary should be reviewed for races.
+  rationale: Mutating outer-scope or instance state after suspension can interleave with concurrent callers and corrupt shared state.
+  tags:
+    - correctness
+    - concurrency
+    - rules-catalog
+    - crq-cor-015
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: concurrency.shared-state-race
+    bind: issue
+emit:
+  finding:
+    category: correctness.concurrency
+    severity: high
+    confidence: 0.65
+    tags:
+      - correctness
+      - concurrency
+  message:
+    title: Review shared-state mutation across await boundaries
+    summary: "`${captures.issue.text}` mutates shared state after async suspension."
+  remediation:
+    summary: Isolate the state per request, serialize access, or move the mutation before the await boundary.

package/rules/typescript/ts.correctness.unchecked-map-key-access.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.correctness.unchecked-map-key-access
+  title: Unchecked map or dictionary key access
+  summary: Lookups should verify key presence before reading from maps or keyed objects.
+  rationale: Missing-key reads often flow undefined deeper into the function and fail far away from the original lookup.
+  tags:
+    - correctness
+    - data-access
+    - rules-catalog
+    - crq-cor-003
+  stability: stable
+  appliesTo: block
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: data-flow.unchecked-map-key-access
+    bind: issue
+emit:
+  finding:
+    category: correctness.data-access
+    severity: medium
+    confidence: 0.8
+    tags:
+      - correctness
+      - data-access
+  message:
+    title: Guard keyed lookups before reading values
+    summary: "`${captures.issue.text}` reads from a keyed collection without checking whether the key is present."
+  remediation:
+    summary: Check `has`, `in`, or `Object.hasOwn` before reading, or provide a safe default when the key is missing.

package/rules/typescript/ts.correctness.unhandled-async-error.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.correctness.unhandled-async-error
+  title: Unhandled promise rejection or async error
+  summary: Promise chains started in a function should terminate with explicit rejection handling.
+  rationale: Floating `.then(...)` chains without a terminal catch can reject outside the intended error-handling path and make failures hard to trace.
+  tags:
+    - correctness
+    - async
+    - rules-catalog
+    - crq-cor-012
+  stability: stable
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: async.unhandled-async-error
+    bind: issue
+emit:
+  finding:
+    category: correctness.async
+    severity: high
+    confidence: 0.85
+    tags:
+      - correctness
+      - async
+  message:
+    title: Handle async rejections explicitly
+    summary: Review `${captures.issue.text}` and terminate the promise chain with rejection handling.
+  remediation:
+    summary: Await the operation in a try/catch block or attach a terminal `.catch(...)` handler to the promise chain.

package/rules/typescript/ts.correctness.unreachable-statement.rule.yaml

@@ -0,0 +1,40 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.correctness.unreachable-statement
+  title: Unreachable code after return or throw
+  summary: Statements after terminal exits should be removed or moved before the exit.
+  rationale: Dead statements obscure intent and often indicate a refactor that left stale logic behind.
+  tags:
+    - correctness
+    - control-flow
+    - rules-catalog
+    - crq-cor-010
+  stability: stable
+  appliesTo: block
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: control-flow.unreachable-statement
+    bind: issue
+    where:
+      - path: reason
+        in:
+          - after-return
+          - after-throw
+emit:
+  finding:
+    category: correctness.control-flow
+    severity: low
+    confidence: 0.95
+    tags:
+      - correctness
+      - control-flow
+  message:
+    title: Remove unreachable statement
+    summary: "`${captures.issue.text}` cannot execute because control flow already terminated."
+  remediation:
+    summary: Delete the dead statement or move it before the return or throw.

package/rules/typescript/ts.logging.no-console-error.rule.yaml

@@ -0,0 +1,34 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.logging.no-console-error
+  title: Avoid console.error
+  summary: Route error logs through the project logger.
+  rationale: Console error calls bypass the shared logging pipeline.
+  tags:
+    - logging
+    - rules-catalog
+scope:
+  languages:
+    - typescript
+match:
+  node:
+    kind: CallExpression
+    bind: call
+    where:
+      - path: callee.object.text
+        equals: console
+      - path: callee.property.text
+        equals: error
+emit:
+  finding:
+    category: maintainability
+    severity: medium
+    confidence: high
+    tags:
+      - logging
+  message:
+    title: Avoid `${captures.call.text}`
+    summary: Route `${captures.call.text}` through the project logger.
+  remediation:
+    summary: Replace `${captures.call.text}` with the logger.

package/rules/typescript/ts.logging.no-console-log.rule.yaml

@@ -0,0 +1,34 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.logging.no-console-log
+  title: Avoid console.log
+  summary: Use the project logger instead of console.log.
+  rationale: Console logging bypasses the shared logger pipeline.
+  tags:
+    - logging
+    - rules-catalog
+scope:
+  languages:
+    - typescript
+match:
+  node:
+    kind: CallExpression
+    bind: call
+    where:
+      - path: callee.object.text
+        equals: console
+      - path: callee.property.text
+        equals: log
+emit:
+  finding:
+    category: maintainability
+    severity: low
+    confidence: high
+    tags:
+      - logging
+  message:
+    title: Avoid `${captures.call.text}`
+    summary: Use the project logger instead of `${captures.call.text}`.
+  remediation:
+    summary: Replace `${captures.call.text}` with the logger.

package/rules/typescript/ts.next.no-server-client-boundary-leaks.rule.yaml

@@ -0,0 +1,36 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.next.no-server-client-boundary-leaks
+  title: Avoid server/client boundary leaks in Next.js
+  summary: Server components should not use browser-only APIs or client-only hooks without an explicit client boundary.
+  rationale: Browser globals and client-only hooks break server rendering boundaries and make component intent unclear.
+  tags:
+    - next
+    - react
+    - rules-catalog
+  stability: experimental
+  appliesTo: file
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: framework.next-server-client-boundary-leak
+    bind: issue
+emit:
+  finding:
+    category: correctness.framework
+    severity: high
+    confidence: 0.8
+    tags:
+      - next
+      - react
+      - correctness
+  message:
+    title: Add a client boundary before using browser-only APIs
+    summary: "`${captures.issue.text}` uses a browser-only API or client-only hook in a server file."
+  remediation:
+    summary: Add `'use client'` or move the code into a client component or hook.
+

package/rules/typescript/ts.performance.inefficient-data-structure-usage.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.performance.inefficient-data-structure-usage
+  title: Inefficient data structure usage
+  summary: Linear membership checks or key projections should be reviewed for more suitable lookup structures.
+  rationale: Repeated array scans or `Object.keys(...).includes(...)` patterns are often avoidable with `Set`, `Map`, or direct key checks.
+  tags:
+    - performance
+    - algorithmic
+    - rules-catalog
+    - crq-per-034
+  stability: stable
+  appliesTo: block
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: performance.inefficient-data-structure-usage
+    bind: issue
+emit:
+  finding:
+    category: performance.algorithmic
+    severity: medium
+    confidence: 0.8
+    tags:
+      - performance
+      - algorithmic
+  message:
+    title: Prefer a more efficient lookup structure
+    summary: "`${captures.issue.text}` uses a linear lookup where a dedicated structure would be cheaper."
+  remediation:
+    summary: Replace repeated array scans with `Set` or `Map`, or use direct key existence checks instead of projecting keys first.

package/rules/typescript/ts.performance.large-payload-without-streaming.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.performance.large-payload-without-streaming
+  title: Large payload processing without streaming
+  summary: Whole-payload reads of likely large content should be reviewed for streaming alternatives.
+  rationale: Pulling large payloads into memory increases latency and memory pressure compared with streaming or chunked processing.
+  tags:
+    - performance
+    - memory-io
+    - rules-catalog
+    - crq-per-037
+  stability: stable
+  appliesTo: block
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: performance.large-payload-without-streaming
+    bind: issue
+emit:
+  finding:
+    category: performance.memory-io
+    severity: medium
+    confidence: 0.8
+    tags:
+      - performance
+      - memory-io
+  message:
+    title: Stream large payloads when practical
+    summary: "`${captures.issue.text}` reads likely large payload data into memory at once."
+  remediation:
+    summary: Prefer `createReadStream`, iterator-based parsing, or chunked processing for large files and binary payloads.

package/rules/typescript/ts.performance.missing-batch-operations.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.performance.missing-batch-operations
+  title: Missing batching of operations
+  summary: Repeated one-by-one operations inside loops should prefer available batch-style helpers.
+  rationale: Batch APIs usually reduce round trips, contention, and request overhead compared with item-at-a-time loops.
+  tags:
+    - performance
+    - io
+    - rules-catalog
+    - crq-per-036
+  stability: stable
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: performance.missing-batch-operations
+    bind: issue
+emit:
+  finding:
+    category: performance.io
+    severity: medium
+    confidence: 0.75
+    tags:
+      - performance
+      - io
+  message:
+    title: Prefer batch helpers over one-by-one loops
+    summary: "`${captures.issue.text}` runs one item at a time even though a batch-style helper appears available."
+  remediation:
+    summary: Replace the per-item loop with the available batch or bulk helper, or add one if the dependency already supports it.

package/rules/typescript/ts.performance.nested-loops-hot-path.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.performance.nested-loops-hot-path
+  title: Nested loops in hot path (O(n²) risk)
+  summary: Nested loops in the same function should be reviewed for quadratic work on larger inputs.
+  rationale: Nested iteration often becomes the dominant cost on hot paths and usually benefits from indexing or precomputation.
+  tags:
+    - performance
+    - algorithmic
+    - rules-catalog
+    - crq-per-031
+  stability: stable
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: performance.nested-loops-hot-path
+    bind: issue
+emit:
+  finding:
+    category: performance.algorithmic
+    severity: medium
+    confidence: 0.75
+    tags:
+      - performance
+      - algorithmic
+  message:
+    title: Review nested loops on hot paths
+    summary: "`${captures.issue.text}` nests loops and may introduce quadratic work."
+  remediation:
+    summary: Precompute lookups, index one side with a set or map, or otherwise flatten the repeated scan.

package/rules/typescript/ts.performance.repeated-expensive-computation.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.performance.repeated-expensive-computation
+  title: Repeated expensive computation
+  summary: Repeating the same expensive computation in one block should usually be cached.
+  rationale: Recomputing the same serialization, key projection, or formatter construction wastes CPU and obscures intent.
+  tags:
+    - performance
+    - compute
+    - rules-catalog
+    - crq-per-032
+  stability: stable
+  appliesTo: block
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: performance.repeated-expensive-computation
+    bind: issue
+emit:
+  finding:
+    category: performance.compute
+    severity: medium
+    confidence: 0.8
+    tags:
+      - performance
+      - compute
+  message:
+    title: Cache repeated expensive work
+    summary: "`${captures.issue.text}` repeats expensive computation in the same block."
+  remediation:
+    summary: Compute the value once, store it in a local binding, and reuse the cached result.

package/rules/typescript/ts.performance.repeated-io-in-loop.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.performance.repeated-io-in-loop
+  title: Repeated IO call inside loop
+  summary: Database or network calls inside loops can multiply latency and load.
+  rationale: Per-item IO in loops often turns one operation into N round trips and is a common performance bottleneck.
+  tags:
+    - performance
+    - io
+    - rules-catalog
+    - crq-per-033
+  stability: stable
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: performance.repeated-io-in-loop
+    bind: issue
+emit:
+  finding:
+    category: performance.io
+    severity: high
+    confidence: 0.9
+    tags:
+      - performance
+      - io
+  message:
+    title: Avoid repeated IO calls inside loops
+    summary: "`${captures.issue.text}` performs IO inside a loop and can multiply latency."
+  remediation:
+    summary: Move the IO outside the loop, batch the work, or fetch the required data in one call before iterating.

package/rules/typescript/ts.performance.retained-large-object.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.performance.retained-large-object
+  title: Unnecessarily retained large object
+  summary: Large payloads assigned into shared state should be reviewed for shorter lifetimes.
+  rationale: Retaining large buffers or payload objects longer than needed increases memory pressure and GC churn.
+  tags:
+    - performance
+    - memory
+    - rules-catalog
+    - crq-per-039
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: performance.retained-large-object
+    bind: issue
+emit:
+  finding:
+    category: performance.memory
+    severity: medium
+    confidence: 0.65
+    tags:
+      - performance
+      - memory
+  message:
+    title: Avoid retaining large payloads in shared state
+    summary: Review `${captures.issue.text}` and release large payload objects as soon as possible.
+  remediation:
+    summary: Keep the payload local, persist only the fields you need, or clear the shared reference after use.

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

@@ -0,0 +1,35 @@
+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.
+  tags:
+    - performance
+    - async
+    - rules-catalog
+    - crq-per-035
+  stability: stable
+  appliesTo: block
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: performance.sequential-async-calls
+    bind: issue
+emit:
+  finding:
+    category: performance.async
+    severity: medium
+    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."
+  remediation:
+    summary: Start both operations first and await them together, for example with `Promise.all(...)`.

package/rules/typescript/ts.performance.unbounded-growth-memory-leak.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.performance.unbounded-growth-memory-leak
+  title: Potential memory leak from unbounded growth
+  summary: Shared collections that only grow should be reviewed for eviction or lifecycle boundaries.
+  rationale: Appending to long-lived state without a cap can leak memory across requests or over process lifetime.
+  tags:
+    - performance
+    - memory
+    - rules-catalog
+    - crq-per-038
+  stability: stable
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: performance.unbounded-growth-memory-leak
+    bind: issue
+emit:
+  finding:
+    category: performance.memory
+    severity: high
+    confidence: 0.75
+    tags:
+      - performance
+      - memory
+  message:
+    title: Bound long-lived collection growth
+    summary: Review `${captures.issue.text}` for unbounded growth of shared state.
+  remediation:
+    summary: Add eviction, scoping, or cleanup so the collection cannot grow forever across calls.

package/rules/typescript/ts.performance.unnecessary-rerenders-from-state-misuse.rule.yaml

@@ -0,0 +1,35 @@
+apiVersion: critiq.dev/v1alpha1
+kind: Rule
+metadata:
+  id: ts.performance.unnecessary-rerenders-from-state-misuse
+  title: Unnecessary re-renders from state misuse
+  summary: React state setters invoked directly during render should be reviewed for rerender loops.
+  rationale: Calling a state setter during render can trigger avoidable rerenders and unstable component behavior.
+  tags:
+    - performance
+    - ui
+    - rules-catalog
+    - crq-per-040
+  stability: experimental
+  appliesTo: function
+scope:
+  languages:
+    - typescript
+    - javascript
+match:
+  fact:
+    kind: performance.unnecessary-rerenders-from-state-misuse
+    bind: issue
+emit:
+  finding:
+    category: performance.ui
+    severity: medium
+    confidence: 0.7
+    tags:
+      - performance
+      - ui
+  message:
+    title: Avoid render-path state updates
+    summary: Review `${captures.issue.text}` and move state updates out of the render path.
+  remediation:
+    summary: Trigger the state update from an event, effect, or transition instead of directly during render.