Skip to content
Sarj Code Standards

Rules

456 rules

Rule Category Introduced
Py async-cleanup-registered-synchronously Do not register a proven async cleanup function with ExitStack.callback. correctness
Py async-executor-shutdown Run waiting executor shutdown outside the async event-loop thread. correctness
Py async-mock-call-without-await-assertion Pair positive AsyncMock call assertions with evidence that the mock was awaited. testing
Py async-subprocess-cancellation-cleanup Settle locally owned asyncio subprocesses when their caller is cancelled. correctness
Py cancel-owned-task-without-join Join a cancelled locally owned task before releasing its lifecycle. correctness
cloudbuild-contract Cloud Build dependencies and execution fields must have valid, safe semantics. correctness
combine-alter-table Combine compatible adjacent ALTER TABLE actions. maintainability
commented-out-config unexplained disabled config blocks or adjacent alternatives maintainability
Py complex-postgres-query-requires-architecture-review Complex executable PostgreSQL query shapes require architecture review. architecture
IaC conditional-resource-presence Prefer stable Terraform resource presence or an explicit review justification. maintainability
config-comment-wall four or more nearby configuration comments mostly repeat their entries maintainability
declarative-deployment-boundary recognized control-plane commands bypass Terraform resource ownership architecture
declared-column-bounds Encode explicitly declared numeric and interval ranges in SQL CHECK constraints. correctness
Py defect-xfail-requires-explicit-strict A deterministic known-defect `xfail` must set literal `strict=True` so XPASS fails the suite. testing
Py delete-route-returns-no-content FastAPI DELETE routes declare status code 204 No Content. correctness
TS directive-disable-enable-pair Require an `eslint-enable` directive for every block `eslint-disable` or `oxlint-disable` directive. maintainability
TS directive-no-aggregating-enable Disallow one `eslint-enable` or `oxlint-enable` directive closing several disable directives. maintainability
TS directive-no-duplicate-disable Disallow `eslint-disable` and `oxlint-disable` directives for rules that are already disabled there. maintainability
TS directive-no-restricted-disable Disallow `eslint-disable` and `oxlint-disable` directives that turn off a restricted rule or every rule. maintainability
TS directive-no-unused-enable Disallow `eslint-enable` and `oxlint-enable` directives for rules that are not disabled. maintainability
TS directive-no-use Disallow directive comments, `eslint-*` or `oxlint-*`, except the allowed kinds. maintainability
TS directive-require-description Require a `--` description on every directive comment, `eslint-*` or `oxlint-*`. maintainability
Py docstring-args-restate-signature Remove a wholly redundant Google-style Args section when every entry only repeats the function signature. maintainability
Py docstring-returns-restate-signature Google-style Returns and Yields documentation must add facts beyond the corresponding annotated result type. maintainability
Py duplicate-adjacent-exception-handler Adjacent exception handlers repeat the same executable translation. maintainability
Py duplicate-closed-pure-helper Closed private helpers repeat one proven native regex/string transformation. maintainability
Py duplicate-pytest-fixture-params Review repeated immutable values in a pytest fixture parameter list. testing
TS duplicate-test-body Disallow substantial sibling tests with the same body shape; express their differing inputs as a parameterized case table. testing
TS enforce-file-structure Require imports before body statements and require `use server` to be the first statement. correctness
enforce-timestamptz TIMESTAMP without TIME ZONE — use TIMESTAMPTZ. correctness
ephemeral-execution-artifact ephemeral execution brief, audit report, or change diary maintainability
exact-config-comment-restatement YAML or TOML comment exactly repeats the adjacent scalar assignment maintainability
excess-migration-index-requires-justification Limit explicit indexes to three per table and eight per authored migration. performance
TS excessive-commentary Flag long standalone implementation commentary that should be expressed by code. maintainability
Py excessive-commentary Delete comment paragraphs that exactly repeat the following ordered action names. maintainability
existing-table-check-or-foreign-key-requires-not-valid CHECK and foreign-key constraints added to existing PostgreSQL tables should defer validation. performance
IaC expression-complexity Limit Terraform statement and variable-validation expression complexity. maintainability
Py failed-probe-zero-threshold Do not let a failed subprocess count probe meet its threshold through a zero fallback. correctness
Py fakes-in-shared-location Review named top-level test doubles for shared-support ownership unless they are intentionally scenario-local. testing
Py fastapi-class-router-contract FastAPI HTTP routes use injected `*Router.build()` owners and explicit named object response models. architecture
Py fastapi-explicit-openapi-contract Visible FastAPI operations pin locally reviewable metadata and avoid statically provable OpenAPI gaps. correctness
Py fastapi-route-declares-security Declare each FastAPI route access decision, including inherited router dependencies. security
hidden-markdown-heading HTML comment hides a Markdown heading maintainability
TS iac-source-coupled-test Disallow raw IaC source text as a test oracle; inspect a rendered plan, provider state, or runtime behavior. testing
Py iac-source-coupled-test Test uses raw Terraform/HCL text as an infrastructure-behavior oracle. testing
iac-source-coupled-test shell test asserts on raw IaC source text testing
idempotent-ddl DDL omits a supported IF [NOT] EXISTS guard. correctness
index-concurrently CREATE INDEX without CONCURRENTLY — locks the table against writes. performance
insert-requires-replay-policy Every INSERT must declare replay-safe upsert behavior or explicitly document intentional insert-only semantics. correctness
TS interface-contract-members-private Require methods outside an implemented interface contract to use ECMAScript private names. architecture
invalid-concurrent-ddl Keep concurrent PostgreSQL DDL in supported execution contexts. correctness
invalid-postgres-ddl Use supported PostgreSQL index and constraint definitions. correctness
Py invalid-pydantic-field-default Require literal Pydantic model-field defaults to satisfy their resolved contract. correctness
large-shell-program shell program contains at least 200 substantive lines architecture
migration-timeout-requires-justification Require an explicit operational reason for migration timeout settings. maintainability
mixed-migration-phases Review existing-table migrations that combine backfill, enforcement, and contract phases. architecture
Py mock-without-spec Unrestricted mock permits attributes outside the collaborator contract. testing
TS named-child-schema-type Reference a named Zod record child's complete schema type instead of repeating its explicit annotation. maintainability
Py named-record-at-boundaries Public Python API returns an unnamed fixed-shape record. architecture
Py nan-hidden-by-builtin-min Validate floating candidates before a built-in min/max can hide a NaN. correctness
Py negative-only-http-status-assertion HTTP test assertion only excludes a server error instead of identifying the intended response. testing
new-table-inline-constraints Declare new-table constraints inside CREATE TABLE. maintainability
Py no-analytical-aggregation-in-postgres-store Keep DISTINCT, GROUP BY, and SQL aggregates in analytical databases. architecture
no-analytical-queries-in-transactional-db Keep DISTINCT, GROUP BY, and aggregate queries in analytical databases. architecture
Py no-any-mapping-types String-keyed mapping types must not erase their values with `Any`. correctness
no-application-schema-check Review JSON shape validation duplicated in database CHECK constraints. architecture
Py no-async-client-in-constructor Inject an HTTPX AsyncClient instead of constructing one in __init__. architecture
Py no-async-function-cache Standard library cache decorates a coroutine function and retains single-use coroutine objects. correctness
TS no-bare-return-from-test-catch Disallow a bare return from a test catch block when it skips a later assertion. testing
Py no-bare-test-phase-comments Test files must not use bare phase comments such as Arrange, Act, Assert, Given, When, or Then. testing
Py no-before-validator-input-mutation Preserve raw inputs in Pydantic before validators. correctness
TS no-bespoke-api-case-conversion Review direct snake_case/camelCase mirror mappings on explicitly API-typed adapter values. architecture
Py no-blanket-suppression Use named, line-local suppressions instead of blanket, file or range disables. correctness
TS no-blocked-input-paste Allow clipboard input when a text control has no replacement paste handling. correctness
IaC no-boolean-enable-variable Require a retirement date and removal plan, or a permanent rationale, for Boolean inputs. maintainability
TS no-boolean-selector-parameter Prefer intention-revealing operations over a boolean parameter selecting between actions. maintainability
Py no-broad-keyword-capture Prefer precise keyword interfaces over missing, Any- or object-valued captures. maintainability
TS no-broad-return-type Report explicit broad return annotations that erase a known return value. maintainability
TS no-client-side-data-fetching Disallow direct data fetching inside `useEffect` or `useLayoutEffect`. performance
IaC no-comment-cruft Commented-out HCL declarations or decorative divider comments must be removed; retain comments that explain constraints or rationale. maintainability
TS no-comment-cruft Flag commented-out code, section-banner comments, and leading file-header comment preambles. maintainability
Py no-comment-cruft Commented-out code, mechanical narration, decorative banner, or untracked work marker. maintainability
TS no-conditional-empty-object-spread Build conditional properties explicitly instead of spreading an empty-object branch. style
Py no-conflicting-pydantic-alias-validation Pydantic alias configuration must retain a validation path. correctness
Py no-conftest-test-module-import Do not import individual test modules from conftest.py. testing
TS no-contradictory-overload-return Preserve the input/result relationship promised by literal overloads. correctness
Py no-contradictory-type-guard Primitive type guards must agree with the builtin predicate they return. correctness
TS no-contradictory-type-predicate Keep explicit type predicates consistent with their primitive, array or record membership check. correctness
Py no-copied-inherited-docstring An override repeats the documentation of the single local base method it actually overrides. maintainability
TS no-cors-wildcard-with-credentials Review wildcard CORS origins combined with an explicit credentials opt-in. correctness
Py no-cors-wildcard-with-credentials Credentialed CORS must not allow a wildcard origin. security
Py no-create-verb-in-post-path POST routes name their collection instead of ending in a create, add or new segment. architecture
TS no-credential-in-browser-storage Do not write credential-named values to browser storage or script-readable cookies. security
Py no-custom-control-flow-exception Return coded typed outcomes for expected domain failures instead of exception-only contracts. architecture
TS no-dangerously-allow-svg Require an explicit hardening policy for Next Image SVG delivery security
no-database-functions Ban stored SQL functions and procedures in migrations. architecture
Py no-database-programmability Keep stored SQL functions and triggers out of embedded SQL. architecture
no-database-triggers Keep behavioral logic in application code, not database triggers. architecture
IaC no-dead-environment-input Find undeclared tfvars assignments and potentially redundant scalar values across discovered Terraform environments. maintainability
TS no-declaration-comment-wall Flag an enum body or class body whose member comments mostly re-spell the members' own names. maintainability
Py no-defaulted-environment-setting A settings field that names the deployment environment must not declare a default. correctness
Py no-delete-statement Avoid `del` statements; prefer constructing an immutable replacement value. maintainability
TS no-detached-global-fetch Keep the ambient global fetch receiver-safe when storing or explicitly rebinding it. correctness
Py no-discarded-tagged-outcome Handle a returned tagged outcome instead of discarding it. correctness
TS no-discarded-validation-result Consume Zod validation outcomes and transformed outputs instead of discarding them. correctness
Py no-discarded-validation-result Consume a value-producing validator's result instead of relying on its exceptions. correctness
Py no-docstring-type-restatement A docstring type label repeats an annotation from the fully typed signature. maintainability
Py no-dual-shape-model-field-reader Normalize a known model instead of reading its fields through a model-or-dict accessor. maintainability
Py no-dunder-all modules should not define or mutate `__all__` maintainability
IaC no-duplicate-deployment-literal Share repeated cloud deployment values through variables, locals or resource references. maintainability
Py no-duplicate-dunder-all-entry static module `__all__` declarations should list each exported name once correctness
Py no-duplicate-field-validator-body Pydantic field validators in one model repeat the same body. maintainability
no-duplicate-index Report duplicate and conservatively covered indexes that remain active in one authored migration. performance
TS no-duplicate-lifecycle-refresh-listeners Do not register one Next.js route-refresh callback for both focus and visibilitychange. performance
TS no-duplicate-test-case Report repeated literal rows in framework each tables and Vitest for tables. testing
Py no-dynamic-builtins Use explicit typed state instead of dynamic Python builtin access. maintainability
TS no-dynamic-sql Disallow runtime values and fragments interpolated into SQL passed to statement-execution methods. security
TS no-enum Disallow TypeScript `enum`; use string-literal unions or `as const` objects instead. maintainability
IaC no-environment-conditional Warn when Terraform chooses behavior from deployment-identity comparisons; prefer explicit typed capabilities or values. architecture
Py no-exception-text-in-500-detail HTTP 500 exception details must not carry exception text or tracebacks. security
TS no-exception-text-in-5xx-response Keep caught exception messages and stacks out of returned 5xx JSON responses and Server Action results. security
TS no-excess-jsx-props Report statically known fields spread outside a resolved component props contract. maintainability
TS no-excessive-cognitive-complexity Report an error for function bodies with cognitive complexity above 20. maintainability
Py no-excessive-cognitive-complexity Error on cognitive complexity above 20; scores up to 20 pass. maintainability
TS no-explicit-type-predicate Use compiler-checked narrowing instead of handwritten type predicates. maintainability
Py no-fastapi-on-event Deprecated FastAPI or Starlette on_event lifecycle registration. correctness
TS no-fat-try-blocks Review try blocks exceeding the configured count of syntactically selected operations. correctness
Py no-file-level-escape-hatch-suppression File-level Ruff suppression disables an escape-hatch rule across the entire file. maintainability
TS no-first-party-module-mock Prefer injected collaborators over mocking maintained first-party modules in tests. testing
Py no-first-party-private-import A first-party consumer imports a private name or private module across its package boundary. architecture
Py no-fixed-sleep-before-assert Do not sleep for a fixed interval and then assert in a test. testing
Py no-fixed-sleep-in-loop Do not sleep for a fixed literal interval inside a production loop. testing
Py no-folded-bad-request-not-found Do not handle HTTP 400 and 404 statuses in one branch. correctness
TS no-frontend-comments Express frontend behavior through code instead of prose comments. maintainability
Py no-frozen-after-validator-field-write Do not assign declared fields in after-validators on frozen Pydantic models. correctness
TS no-generic-json-parser Parse known JSON fields with an object schema instead of an open JSON or record parser. correctness
Py no-generic-json-parser Parse consumed JSON fields with a bespoke declarative model instead of an open JSON parser. correctness
TS no-generic-single-export-module Disallow generic module stems when one runtime export already names the responsibility. maintainability
Py no-generic-single-export-module A generic module name should not conceal a single-definition responsibility. architecture
TS no-growing-array-spread-in-loop Review repeated prefix copies of a growing fresh local array inside a loop. performance
TS no-hand-rolled-sleep Disallow uncancellable promisified timers and timeout arms. correctness
TS no-hand-rolled-spinner Disallow intrinsic elements styled as Tailwind border-ring spinners outside the design-system implementation. maintainability
IaC no-hardcoded-deployment-location Pass cloud deployment regions, zones and locations through explicit configuration inputs. architecture
Py no-hasattr Do not probe attributes with the builtin hasattr. maintainability
Py no-hidden-constructor-fallback Constructor option silently falls back to application settings when omitted. architecture
Py no-impossible-pydantic-field-bounds Pydantic field bounds must admit at least one value. correctness
TS no-impossible-zod-literal-bounds Disallow same-chain literal Zod bounds whose accepted set is mathematically empty. correctness
TS no-in-operator-on-built-in-collections Do not use the `in` operator to test entries in built-in Map and Set collections. correctness
Py no-injected-module-loader Avoid a generic module-loader parameter used only to import one fixed module. architecture
Py no-input-model-mutation Return replacement values instead of mutating caller-owned Pydantic models. correctness
TS no-insecure-random-id Disallow using `Math.random()` to generate identifiers, tokens, or secrets; use `crypto.randomUUID()` or `crypto.getRandomValues(...)` instead. security
Py no-interpreter-source-arguments Keep interpreter programs in linted files or modules, outside process argv and literal Python stdin. architecture
Py no-invalid-argument-name-suppression External parameter spelling must use framework aliases instead of disabling snake_case naming. maintainability
Py no-invalid-pydantic-bypass Do not create a provably invalid model through Pydantic validation bypass APIs. correctness
Py no-invalid-pydantic-validator-return A terminal field validator must not return a literal contradicting its stored field type. correctness
TS no-invalid-typed-mutation Keep native object mutation APIs from writing incompatible values into declared property types. correctness
TS no-invalid-web-resource-hints Keep native resource hints consistent with browser loading and preload request modes. performance
TS no-invalid-zod-custom-parse Do not parse an incompatible primitive literal through an unvalidated Zod custom schema. correctness
TS no-json-stringify-error Avoid generic JSON serialization that can omit native Error details. correctness
TS no-json-stringify-object-equality Do not use JSON serialization as structural object equality. correctness
TS no-known-value-widening Preserve a known value's contract instead of widening a local binding to unknown, object, or an unknown-valued dictionary. maintainability
TS no-log-only-catch Disallow `catch` clauses that only log (or silently do nothing) and then swallow the error; rethrow or handle it instead. correctness
TS no-logical-or-fallback Use nullish defaults or explicit falsy-value checks instead of logical OR fallbacks. correctness
Py no-loguru-exc-info Loguru exc_info=True adds a field rather than retaining the exception traceback. correctness
Py no-loguru-printf-format Use brace formatting for positional values passed to Loguru. correctness
TS no-long-comment Flag unusually large unstructured JSDoc blocks in implementation code. maintainability
no-long-migration-narration Long migration comments narrate implementation instead of recording durable constraints. maintainability
Py no-magic-arithmetic Name nontrivial numeric factors and operational limits. maintainability
IaC no-managed-service-account-key Disallow Terraform-managed Google service-account keys. security
TS no-message-origin-string-matching Compare incoming browser message origins against exact trusted origins. security
no-migration-comment-cruft Commented-out SQL, decorative banners, and untracked debt markers must be removed. maintainability
no-migration-comments Encode migration invariants in SQL instead of explanatory comments. maintainability
Py no-mocked-pydantic-value-object Build real Pydantic models when test doubles supply model field data. testing
IaC no-mocked-terraform-test-oracle Warn when a Terraform assertion directly reasserts the same literal injected by a module override. testing
TS no-mutating-container-transform Return array replacements without mutating borrowed array inputs. correctness
Py no-mutating-container-transform Return container replacements without mutating borrowed builtin inputs. correctness
TS no-mutating-input-with-result Return replacement object values instead of writing input fields in result-returning functions. correctness
Py no-mutating-input-with-result Separate input attribute mutation from functions that return a result. correctness
TS no-negative-only-http-status-assertion Assert the intended HTTP status instead of only excluding a server error. testing
IaC no-nested-conditional Prefer a named value or explicit input over chained Terraform conditional selections. maintainability
Py no-nested-pydantic-field-validator Outer-model Pydantic field validator is owned by a nested helper class. correctness
no-noop-migration-down A migration down section must perform a rollback instead of silently doing nothing. correctness
no-null-comparison Use explicit NULL predicates instead of ordinary NULL comparisons. correctness
Py no-nullable-dependency-fallback Require concrete function dependencies instead of resolving a None default inside the function. architecture
TS no-numeric-search-param-coercion Parse numeric URL search parameters with a schema instead of parseInt or Number. correctness
TS no-offset-pagination Prefer keyset pagination for embedded SQL queries using OFFSET. performance
Py no-offset-pagination Potentially unbounded `OFFSET` pagination in store SQL. performance
no-offset-pagination Dynamic OFFSET pagination in query SQL should use a stable cursor. performance
TS no-oxlint-directive Write every suppression directive with the `eslint-*` spelling. maintainability
Py no-partial-type-is TypeIs must not reject a value belonging to its declared target type. correctness
TS no-partial-type-predicate Do not give a partial primitive filter an explicit type predicate that excludes valid values in the false branch. correctness
TS no-password-get-form Keep named password controls out of native GET form submissions. security
no-pg-enum CREATE TYPE ... AS ENUM — use TEXT with an application enum instead. maintainability
IaC no-plaintext-secret-env A secret-named container environment variable should come from a secret reference, not a plain value. security
Py no-positional-psycopg-row-escape A positional Psycopg record must not escape its function unchanged. correctness
Py no-positional-tuple-record Fixed tuple return records should use named fields instead of positional slots. maintainability
TS no-positional-tuple-return Disallow returning a multi-field tuple from a named function; return a named object so call sites cannot mismatch slots. maintainability
TS no-production-browser-source-maps Next.js production browser source maps expose application source security
IaC no-project-basic-privilege Disallow proven project IAM Owner and Editor grants. security
IaC no-project-secret-access-for-service-account Grant service accounts Secret Manager access per secret, not on the project. security
Py no-provably-dead-mock-configuration Remove mock behavior configuration proven unable to affect a test. testing
Py no-psycopg-execution-in-loop Use bounded bulk queries instead of executing Psycopg operations inside item loops. performance
Py no-psycopg-execution-outside-injected-owner Psycopg execution occurs outside a constructor-injected persistence owner. architecture
Py no-random-uuid-in-sql Embedded SQL generates a random UUIDv4 instead of a time-ordered UUIDv7. performance
Py no-raw-connection-in-tests Do not execute raw SQL or acquire raw database connections in tests. testing
TS no-raw-env Disallow direct `process.env` and `import.meta.env` reads outside validated boundaries. correctness
TS no-raw-fetch-outside-clients Disallow calling the global `fetch` outside the client layer; route outbound HTTP through a client module that owns retry, timeout and status handling. architecture
Py no-raw-source-text-test-oracle Test uses raw text from a source-like project path as its oracle. testing
TS no-readonly-prop-state Review props copied into state without a usable updater. correctness
Py no-recording-store Use the PostgreSQL store in tests instead of a recording-only store implementation. testing
TS no-reduce-accumulator-copy Review copies of the accumulated collection inside a built-in reduce callback. performance
Py no-redundant-attribute-unpacking Use an aggregate's named attributes instead of repeating their names in tuple aliases. maintainability
TS no-redundant-consumer-union Keep the covering object contract in a private scalar consumer union. maintainability
TS no-redundant-local-alias Pass the original local into an object field instead of creating a single-use rename. maintainability
Py no-redundant-local-alias Remove a local alias used only for its matching keyword argument. maintainability
Py no-redundant-module-alias-exports Do not manufacture public APIs from private names or replace the current module. maintainability
TS no-redundant-optional-array-default Remove `.optional()` immediately inside a Zod array default. maintainability
Py no-redundant-sql-alias Remove SQL aliases that repeat the original relation or column name. maintainability
IaC no-redundant-variable-validation Flag Terraform variable validations already guaranteed by the declared type or nullability. maintainability
TS no-repeated-string-literal Disallow a long structured string literal repeated across functions; the copies drift when one is edited. Extract a module-level constant. maintainability
Py no-repeated-structured-string-literal Exact SQL or route literals repeated across callable scopes should share one named binding. maintainability
Py no-repeated-test-body Substantial sibling pytest tests repeat the same structural body. testing
Py no-repeated-unseeded-stdlib-random-in-test A collected test may repeatedly sample an unseeded standard-library PRNG. testing
Py no-restated-closed-domain-description Do not restate a string Literal or local string Enum domain in its Pydantic description. maintainability
IaC no-restated-comment Flag a short comment attached to an HCL declaration when it only repeats that declaration's kind, label, or attribute name. maintainability
TS no-restated-comment Flag short standalone comments that repeat the adjacent statement's identifiers. maintainability
Py no-restated-comment Short standalone comment lexically restates the immediately following simple action. maintainability
TS no-restated-jsdoc Flag JSDoc prose that appears to repeat declaration names without adding behavioral information. maintainability
TS no-restricted-library-load Apply configured library restrictions to literal runtime loads and CommonJS resolution references. architecture
TS no-return-disposed-resource Do not return a resource whose using declaration disposes it before the caller receives it. correctness
TS no-router-refresh-polling Do not poll by calling a Next.js router's refresh method from a timer. performance
TS no-runtime-typeof Prefer Zod boundary schemas or discriminated unions over runtime typeof checks. maintainability
TS no-secret-in-log Disallow passing a secret-named value or a raw request/response blob to a logging call; both leak to log sinks. Redact or omit. security
Py no-secret-in-log A direct credential-like reference is passed to a recognized logging call. security
TS no-select-star Prefer explicit column projections over SELECT * in embedded SQL. correctness
Py no-select-star SQL SELECT projections should list explicit result columns instead of wildcards. maintainability
TS no-sentinel-return-on-catch Disallow swallowing a caught error by returning an empty sentinel unless the error is handled or the sentinel is part of the function contract. correctness
TS no-server-env-in-client-component server-only environment settings imported or re-exported by a client module correctness
TS no-server-file-uploads Keep native File handling outside explicit server boundaries. architecture
Py no-service-behavior-in-settings Settings and configuration types should not orchestrate injected collaborators. architecture
Py no-shallow-container-type-guard Do not claim typed container contents from a container-only type guard. correctness
Py no-shallow-record-type-guard Do not promise a local record's contract from a container-only check. correctness
Py no-shared-mutable-default Do not share mutable function defaults through aliases or read-only annotations. correctness
TS no-silent-promise-catch Disallow `.catch()` and second-argument `.then()` handlers that silently swallow a rejection; log, rethrow, or handle the error. correctness
Py no-slash-collection-root-under-prefix A collection-root route under a literal router prefix uses an empty path instead of a slash. correctness
TS no-sleep-in-test-body Avoid fixed timed sleeps directly in test bodies; synchronize on observable behavior or use controlled timers. testing
Py no-statically-truthy-assertion An assertion condition is statically truthy, including deferred expressions and test-local scalar setup. testing
TS no-storage-in-stateless-modules Disallow SQL or key/value access inside configured stateless modules; derive state from a system of record instead. architecture
TS no-string-concat-in-loop Prefer collecting string fragments over repeatedly accumulating a growing string inside a loop. performance
Py no-string-concat-in-loop Avoid repeatedly growing a proven string accumulator across a loop backedge. performance
Py no-swallowed-asyncio-cancellation Preserve cancellation when an async operation is cancelled. correctness
Py no-sys-path-mutation Do not mutate the interpreter import search path. correctness
TS no-tautological-expect Disallow supported assertions fixed by literal setup or immutable self identity. testing
IaC no-terraform-comments Express Terraform intent through names and descriptions, with optional concise module summaries. style
IaC no-terraform-data-condition Disallow lifecycle conditions attached to terraform_data guard resources. maintainability
IaC no-terraform-guard-blocks Ban Terraform validation, precondition, postcondition, and check blocks. maintainability
TS no-test-comments Express test behavior through names, fixtures and assertions instead of prose comments. testing
Py no-test-comments Express test behavior in names and assertions instead of ordinary comments. testing
Py no-test-method-grafting Avoid assigning replacement implementations directly onto resolved methods in tests. testing
Py no-trailing-numeric-unit-assignment-comment A trailing comment redundantly labels a numeric assignment with its value and unit. maintainability
TS no-trailing-value-narration Flag a trailing comment that repeats the line's numeric value only to name its unit. maintainability
TS no-type-member-comment-wall Flag an object type whose member comments mostly re-spell the members' own names and types. maintainability
TS no-typed-doc-sections Reject typed-signature repetition while preserving behavior that types cannot express. maintainability
TS no-union-in-comment Flag a comment that lists a `string` field's allowed values instead of the type listing them. maintainability
Py no-unique-violation-message-match Do not make unique-violation control flow depend on rendered exception text. correctness
Py no-unknown-pydantic-validator-field Pydantic field decorators must target declared fields. correctness
TS no-unlocalized-jsx-attributes Require translation for literal user-visible JSX attributes in opted-in localized interfaces. correctness
TS no-unlocalized-jsx-text Require translation for literal JSX text in opted-in localized interfaces. correctness
TS no-unlocalized-toast Require translation for literal toast messages in opted-in localized interfaces. correctness
Py no-unnecessary-docstring No docstring consumer detected — delete it; make author-controlled names, types, and structure explain the code. maintainability
TS no-unnecessary-use-client Flag `'use client'` files with no hooks or event handlers — they could be RSC. performance
no-unsafe-command-argument-interpolation raw Claude command argument interpolated into an executable shell or query fence security
TS no-unsafe-mock-casting Disallow casting to mock types like `jest.Mock` or `vi.Mock`. Use `vi.mocked()` or `jest.mocked()` instead. testing
TS no-unsafe-test-double-cast Disallow mock-backed test doubles that bypass collaborator contracts through double assertions. testing
Py no-unused-copy-result Use the replacement returned by a resolved copy API. correctness
Py no-unused-underscored-keyword-parameter Remove unused underscore-prefixed keyword-only parameters instead of hiding them from lint. maintainability
Py no-unused-value-marker Do not use standalone assignments to `_` to discard values. maintainability
TS no-vague-suppression-description Require suppression descriptions to name the concrete mismatch or invariant instead of a generic non-reason. maintainability
Py no-vague-suppression-description Suppressions need a concrete description of the exception. maintainability
Py no-whole-request-response-payload-in-log Whole request or response payloads passed to logging calls require review. security
no-wildcard-secret-read-permission Claude settings grant wildcard access to secret values security
Py no-work-verb-get-route GET routes must not end in a work verb such as run, send, trigger or retry. security
TS no-zod-native-enum Disallow `z.nativeEnum()` (and `z.enum()` over a TypeScript enum); use `z.enum(["a", "b"])` with a string-literal union instead. maintainability
TS no-zod-parse-typed-object Reuse known object contracts instead of parsing them again with Zod. architecture
Py numeric-literal-separators Group long decimal numeric literals with thousands separators. maintainability
Py opaque-parametrize-case-needs-id Opaque static pytest parameter cases lack table-local semantic IDs. testing
Py over-mocked-test Tests should not use more than five independently rooted test doubles or collaborator substitutions. testing
Py prefer-application-model-joins Compose distinct model records in application code instead of a cross-model SQL join. architecture
Py prefer-autospec-for-callable-mock Prefer autospec for specced function mocks called with explicit keywords. testing
TS prefer-await-in-async-return Prefer explicit `await` for proven Promise `.then` calls; the default scope checks direct async returns. maintainability
Py prefer-bulk-upsert Use declared compatible bulk APIs for repeated singleton reads and writes. performance
Py prefer-class-row Avoid fetching a Psycopg dictionary row only to construct the same model manually. maintainability
TS prefer-coded-error-result Return a stable error code and typed context instead of only a rendered failure message. correctness
Py prefer-collection-comprehension Single-purpose fresh collection builder loop — prefer a direct comprehension. style
TS prefer-configured-cloud-scope Prefer validated deployment configuration for account scope in outgoing cloud management requests. correctness
Py prefer-configured-cloud-scope Read Cloudflare account targets from validated deployment configuration. architecture
TS prefer-constant-time-secret-compare Prefer a supported constant-time comparison primitive for secret-like values. security
Py prefer-constant-time-secret-compare Externally supplied authenticators are compared with timing-sensitive equality. security
prefer-constrained-status Review CHECK-constrained boolean states for a single status column. maintainability
Py prefer-coordinated-state-owner Review dictionaries with repeated same-key writes and removals for one typed owner. architecture
Py prefer-declarative-batch-validation Validate a homogeneous Pydantic batch with a declared collection contract. maintainability
TS prefer-dependency-interface Annotate retained collaborators with their existing interface when the consumer uses only that contract. architecture
Py prefer-direct-import-module Prefer static imports for eager module loads with a literal module name. style
Py prefer-discriminated-model-union Give data unions explicit Literal discriminators and express tag-dependent payloads as variants. architecture
TS prefer-discriminated-union Preserve producer-proven tag/payload and Boolean state relationships in return types. correctness
TS prefer-ecmascript-private-members Prefer ECMAScript `#private` class members over TypeScript-only `private` members. maintainability
Py prefer-explicit-class-contract Declare a contract for a stateful behavior class. architecture
Py prefer-fstring-over-concat Prefer f-strings for short human-readable interpolation when they make the result clearer. style
Py prefer-grouped-settings Group settings fields that share a Python namespace prefix into a nested settings object. architecture
TS prefer-immutable-module-constant Require module-level constant collections to expose readonly state. correctness
Py prefer-immutable-module-constant Module collection constants should use native immutable containers or declare their bindings as Final. maintainability
Py prefer-injected-dependency-over-monkeypatch Prefer explicit test dependencies; justify scoped attribute patches at the boundary. testing
Py prefer-injected-service Inject a service instead of constructing it from dependencies already available to the consumer. architecture
TS prefer-input-group-search Require search icons and shared Input controls in the same visual wrapper to use InputGroup. style
prefer-jsonb JSON column type or table-DDL cast — use JSONB. performance
Py prefer-library-fake Prefer a maintained fake, emulator, recorder, or test service for substantial third-party protocols. testing
TS prefer-logical-tailwind-utilities Prefer logical Tailwind utilities in explicitly opted-in bidirectional interfaces. correctness
Py prefer-match-assert-never Typed enum dispatch must not silently ignore unhandled members. correctness
Py prefer-match-exception-dispatch Prefer guarded match/case for refined exception type dispatch. maintainability
Py prefer-match-type-dispatch Prefer `match` for structural runtime type dispatch. maintainability
Py prefer-match-value-dispatch Prefer match/case for repeated dispatch on one value with a fallback. maintainability
TS prefer-millisecond-control-duration-schema Require application-owned Zod control-duration fields to use millisecond granularity. correctness
TS prefer-minimal-parameter-contract Prefer the proven read-only subset for a private consumer parameter. architecture
TS prefer-module-level-constant Hoist literal-only constant collections and regexes out of function bodies to module scope so they are allocated once. performance
Py prefer-module-level-constant Hoist repeatedly read static values when a module constant preserves behavior. performance
TS prefer-module-level-refined-schema Declare closed Zod scalar, format, and wrapper schemas at module scope. performance
TS prefer-module-level-schema Declare a Zod schema at module scope when it closes over nothing in the enclosing function performance
Py prefer-monkeypatch-for-process-state-in-test Test mutates process-wide state without a restoring test scope. testing
Py prefer-monotonic-for-elapsed-time Use a monotonic clock for a local wall-clock value used only to measure elapsed time. correctness
TS prefer-multi-value-zod-literal Use the Zod 4 multi-value literal API instead of a union of literal schemas. maintainability
TS prefer-named-callback-domain Name literal-union domains used by callbacks in exported contracts. maintainability
TS prefer-named-complex-return-type Prefer a named contract for structurally complex function return types. maintainability
TS prefer-native-fetch-in-server-actions Server action modules should call native fetch instead of importing ky. correctness
TS prefer-native-random-uuid Prefer `globalThis.crypto.randomUUID()` over resolved zero-argument UUID v4 bindings from the `uuid` package. maintainability
Py prefer-native-string-check Avoid unconstrained adapters for string assertions or already encoded JSON mappings. maintainability
TS prefer-node-crypto-hash Prefer the modern one-shot node:crypto hash API when streaming state is unnecessary. performance
TS prefer-node-fs-promises Prefer promise-based Node.js filesystem APIs over synchronous calls in production modules. performance
TS prefer-nominal-id-types Distinguish identifier roles sharing primitive types at callable boundaries. correctness
Py prefer-nominal-id-types Python boundaries should distinguish swappable identifier roles with nominal types. correctness
Py prefer-nominal-mapping-keys Declare record shapes or nominal keys at primitive-keyed mapping boundaries. architecture
TS prefer-non-nullable-collection Suggest reviewing nullish arrays that use local empty-array defaults or a shared null-or-empty guard. maintainability
Py prefer-non-nullable-collection Avoid nullable list parameters that are immediately collapsed to an empty list. maintainability
TS prefer-nullish-filter-predicate Prefer an explicit nullish predicate when `filter(Boolean)` removes only nullish values but does not narrow the result type. correctness
Py prefer-optional-composite Review related optional fields as one optional composite value. maintainability
Py prefer-or-pattern Merge adjacent `case` arms with identical bodies into one or-pattern. maintainability
Py prefer-outcome-variants Express nullable success and error state as tagged outcome variants. architecture
Py prefer-precise-object-contract Use a precise type for declared application contracts instead of object. maintainability
Py prefer-psycopg-executemany Use Psycopg executemany for a serial loop of invariant parameterized writes without row results. performance
Py prefer-pydantic-json-value Recursive JSON value alias duplicates `pydantic.JsonValue`. correctness
Py prefer-pydantic-model-assertion Compare a Pydantic model or an explicit field projection instead of consecutive property assertions. testing
Py prefer-pytest-dependency-fixtures Reuse supplied pytest fixtures and pass test collaborators through fixture dependencies. testing
Py prefer-pytest-fixture-contract Expose existing abstract contracts from pytest fixtures and injected parameters. testing
Py prefer-pytest-fixture-injection Request shared database-pool setup through a pytest fixture. testing
Py prefer-regex-fullmatch An anchored regex validation predicate does not require a full-string match. correctness
Py prefer-required-constructor-parameters Prefer required constructor parameters so callers choose dependencies and configuration explicitly. architecture
Py prefer-runtime-validation Prefer runtime validation to TypeGuard assertions. maintainability
TS prefer-schema-for-api-payload Require Zod (or similar) schema validation on `response.json()` / `JSON.parse()` results before property access. correctness
Py prefer-self-documenting-constant Encode a constant's units or HTTP status meaning in its name, type, or value. maintainability
Py prefer-self-type-annotation Prefer `Self` for self-returning methods and alternate constructors. maintainability
TS prefer-semantic-colors Enforce semantic color tokens over raw Tailwind palette classes, arbitrary color values, and inline color literals. style
TS prefer-server-actions Prefer Next.js Server Actions over same-origin API mutations. architecture
TS prefer-server-data-preparation Prepare data-only input collections before an interactive client view when possible. architecture
Py prefer-set-isdisjoint Prefer `set.isdisjoint` when a built-in set intersection is used only as a boolean predicate. style
TS prefer-shadcn-primitives Require visible raw JSX controls to use the corresponding shared shadcn primitive. style
TS prefer-shared-zod-enum Give repeated literal Zod enum domains one reusable module-level schema. maintainability
Py prefer-single-psycopg-cursor Review repeated Psycopg cursor creation within one function. maintainability
Py prefer-str-enum Prefer `StrEnum` for application-owned string domains with explicit closed-set evidence. maintainability
Py prefer-struct-over-namedtuple Prefer typed declarations for static application-owned `collections.namedtuple` records. maintainability
TS prefer-switch-for-repeated-equality Prefer switch over long if/else-if chains that compare one value for strict equality. maintainability
TS prefer-test-fixture-reuse Reuse a requested test fixture instead of constructing another instance of its class. testing
prefer-text-over-varchar VARCHAR(n) — use TEXT (+ CHECK length if needed). maintainability
Py prefer-typed-cli Declare CLI arguments with typed Typer commands. maintainability
Py prefer-typed-mapping-get Read named fields from typed records instead of schema-free mappings. maintainability
TS prefer-typed-reflection Prefer typed access when Reflect.get or Reflect.apply discards a known contract. maintainability
Py prefer-typed-settings-field Declare numeric model domains and use typed choices for token-valued defaults. maintainability
prefer-uuidv7-default `gen_random_uuid()` emits a random UUIDv4 — use `uuidv7()` so keys are time-ordered. performance
Py prefer-validated-uuid-comparison Validate UUID identifiers at input boundaries before comparing them. architecture
Py prefer-walrus-awaited-none-guard Bind a compact awaited lookup in its immediately following terminal None guard. style
Py prefer-walrus-comprehension-filter The same call runs in a comprehension filter and its result. performance
Py prefer-walrus-regex-match A proven regex Match-or-None result is assigned only for the following condition. style
Py prefer-walrus-stream-loop Collapse a compact producer assignment and immediate sentinel break into a named-expression loop. style
TS prefer-whole-object-assertion Collapse consecutive assertions on one object into a whole-object assertion so related mismatches are reported together. testing
TS prefer-zod-enum-validator Express closed string validators with a reusable Zod enum schema. maintainability
TS prefer-zod-infer Derive a type from its Zod schema with `z.infer` instead of hand-writing a twin declaration beside it. correctness
TS prefer-zod-parse-output-type Consider deriving validated return contracts from the Zod schema when the schema owns the contract. correctness
TS production-derived-test-cases Keep an independent membership oracle when production collections supply test cases. testing
Py production-derived-test-cases Warn when pytest membership-contract cases are derived only from the first-party production collection. testing
Py pytest-fixture-returns-bare-tuple Pytest fixture exposes a fixed positional record as an unnamed tuple. testing
Py pytest-fixture-returns-closed-resource Yield a managed fixture resource until its requesting test finishes. testing
Py redundant-class-docstring Undecorated base-free class docstring only repeats the class name. maintainability
Py redundant-docstring Function or plain-method docstring only repeats its declaration. maintainability
Py redundant-module-docstring Delete top-of-file module docstrings without a detected runtime or documentation consumer. maintainability
Py redundant-test-constructor-forwarder A private test helper mirrors a resolved value-record constructor without adding a contract. testing
Py repeated-kwarg-heavy-call-in-test Tests repeat at least seven explicit keyword names across calls to the same callee. testing
TS repeated-static-call-cases Review three or more consecutive static-input call assertions as potential named cases. testing
Py repeated-static-call-cases Three same-shape literal call assertions may be independent parameter cases. testing
Py repeated-test-composition Sibling tests repeat service collaborator wiring or managed ASGI HTTP clients. testing
Py repeated-unimplemented-test-contract Share repeated typed fail-fast abstract operations between test fakes. testing
Py replay-contract-insert-requires-duplicate-policy A literal INSERT in a replay-named store callable must declare duplicate behavior. correctness
TS require-assert-never Require a never witness in empty switch defaults so discriminated unions remain exhaustive at compile time. correctness
TS require-button-accessible-name Require an accessible name on statically unnamed native or configured JSX buttons. correctness
TS require-camelcase-properties Require unquoted lower snake_case TypeScript properties and dot access to use camelCase. style
Py require-constrained-api-integer Declare numeric bounds for scalar integer FastAPI request parameters. correctness
TS require-constrained-schema-integer Declare integer and lower-bound validation for numeric limit and version schema fields. correctness
IaC require-deletion-protection Require a curated stateful Terraform resource to declare a proven provider-native deletion guard or literal lifecycle destroy guard. correctness
Py require-exp-on-jwt-decode PyJWT decode calls require the exp claim. security
TS require-explicit-contract-implementation Require nominal inheritance when an injected abstract class is rejected by an instanceof guard. architecture
Py require-explicit-contract-implementation Require owned substitutes to inherit an injected nominal abstract contract. architecture
Py require-explicit-psycopg-transaction Make Psycopg locking reads and related writes explicitly transactional. correctness
TS require-explicit-service-contract Require explicit contracts for classes that invoke retained collaborators. architecture
Py require-explicit-service-contract Require an explicit contract for services that invoke collaborators or perform HTTP operations. architecture
TS require-fetch-timeout Require an explicit abort signal on locally analyzable global fetch calls. correctness
require-fk-index Cascading or set-value FOREIGN KEY action lacks a child-table index. performance
TS require-ime-safe-enter-handler Preserve IME composition before Enter submits or blurs a native text control. correctness
Py require-injectable-retry-sleep Pass an injectable sleep to a tenacity retry policy that waits between attempts. testing
TS require-interface-for-exported-class Require exported concrete classes with public behavior to declare a contract. architecture
TS require-jwt-lifetime Require an expiration claim or a maximum token age when returning a verified JWT. security
Py require-keyword-only-swap-prone-params Risky-name positional parameters sharing a primitive annotation may be confused. correctness
Py require-nodecode-for-splitting-settings-field Warn when an unconditional raw-string splitter lacks a pydantic-settings decoding policy. correctness
TS require-pascal-case-zod-schema-name Require confirmed module-level Zod schema contracts to use PascalCase with a `Schema` suffix. style
TS require-port-for-service Advise when an exported service with injected collaborators has public methods not covered by its declared ports. architecture
Py require-port-for-service Consider a consumer-owned port when visible service structure suggests a substitution boundary. architecture
Py require-precise-factory-signature Keep fixed keyword factory calls behind a precise callable signature. architecture
IaC require-prevent-destroy-on-irreplaceable Require a curated durable-data container to declare a literal provider-side deletion guard or Terraform lifecycle destroy guard. correctness
Py require-public-dependency-contract Reuse an existing substitutable contract instead of its concrete implementation annotation. architecture
Py require-pydantic-for-external-json Proven external JSON record fields are consumed before runtime schema validation. correctness
Py require-pydantic-for-mapping-shape Declare opaque mapping field shapes in Pydantic instead of probing them by hand. maintainability
Py require-pydantic-for-structured-payload Structured nested FastAPI payloads must be parsed into a named Pydantic model before field access. correctness
Py require-pydantic-ordinal-lower-bound A Pydantic ordinal field maps its first position to N but accepts smaller integers. correctness
TS require-sql-access-class Keep SQL reads and writes inside a class that receives its database dependency. architecture
TS require-static-next-matcher Require Next.js middleware and proxy matcher configuration to contain only build-time literals. correctness
TS require-svg-accessible-name Require a name or explicit decorative semantics on inline SVG elements. correctness
TS require-use-form-default-values Require explicit form-level initialization or a field default for directly bound Controller fields. correctness
TS require-use-server-in-actions-file route action module missing the use server directive correctness
TS require-zod-form-validation Require Zod validation (`Schema.parse(...)` / `Schema.safeParse(...)`) when reading values out of a `FormData` object. security
Py restated-test-docstring Collected test docstring only repeats names and visible code. testing
Py service-singleton-delegates-to-bulk Service singleton CRUD operations must delegate to a bulk primitive. architecture
Py shared-mutable-pydantic-factory Pydantic default factories should not return a captured mutable singleton. correctness
slack-event-text-in-mrkdwn Keep proven event-controlled text out of Slack markup controls. security
TS sole-export-matches-filename Make a module filename reflect its sole named public runtime export. maintainability
TS source-coupled-test Disallow raw repository source text as a test oracle; parse or execute the artifact instead. testing
TS stepdown Place a private helper below its sole direct same-scope caller. maintainability
Py stepdown A private helper used by one caller should be defined below that caller. maintainability
Py store-field-update-reuses-upsert A plain field UPDATE duplicates fields already writable through the store's upsert command. maintainability
Py store-get-delegates-to-bulk-read A store singleton operation should reuse its equivalent bulk implementation. maintainability
Py store-insert-requires-explicit-conflict-policy Declare SQL conflict behavior for store INSERT statements, including fixture writes. correctness
TS store-insert-requires-on-conflict Review conflict handling for embedded inserts in replay-named callables. correctness
Py store-mutation-command-fanout Review per-field store mutations beside an existing model write command. architecture
Py subprocess-kill-without-reap Reap a locally owned subprocess after killing it on timeout. correctness
TS test-loops-over-literal-cases Disallow assertions over an inline literal case loop in a test; parameterization reports and names every case independently. testing
TS test-phase-label-comment Tests must not use bare Arrange, Act, Assert, Given, When, or Then phase comments. testing
Py test-without-explicit-oracle A collected test has no visible assertion or exception oracle. testing
Py timestamp-order-requires-tiebreaker Bounded store SQL whose final result-order key looks like a `*_at` timestamp should include a deterministic secondary key. correctness
Py typed-error-reasons Review joined exception strings for fixed reason identities versus dynamic context. architecture
Py unused-test-factory-option A private test factory exposes an invariant literal or unexercised local callable option. testing
workflow-embedded-program DevOps execution block embeds program logic architecture