Skip to content

Latest commit

 

History

History
79 lines (65 loc) · 4.91 KB

code-quality.md

File metadata and controls

79 lines (65 loc) · 4.91 KB

Code quality limits

These are this project's review and CI policies, not universal definitions of good code. They apply to maintained TypeScript and JavaScript: application and parser code, build/release scripts, mutation/cache gates, fuzz generators, benchmarks, and configuration modules. eslint.config.mjs defines the exact scopes and limits. Shell, Python, Terraform, and JavaScript embedded in workflow YAML are outside this ESLint gate. Generated output and dependencies are also excluded; maintained JavaScript/TypeScript tooling is included.

Check Production limit Enforcement
Cyclomatic complexity 10 per function ESLint error
File size 300 code lines ESLint error; blank/comment-only lines excluded
Function size 60 code lines ESLint error; blank/comment-only lines excluded; IIFEs included
Maximum line width 120 characters ESLint error with narrow exceptions below
Formatting width 100 characters Existing Prettier configuration, unchanged

Prettier's preferred wrapping width is not a hard maximum. The separate ESLint width gate rejects lines above 120 even when Prettier cannot wrap them.

Width exceptions are limited to a standalone, single-line quoted/template literal, or a comment containing only an HTTP(S) URL. They preserve exact binary protocol strings, generated-source fixtures and useful links. A line merely containing a string or URL is not exempt: surrounding code still has to fit. There are currently no local width, production complexity, or production size suppressions. Strings containing suppression directives in scanner test fixtures are rejection controls, not active lint exemptions.

Test policy

Test files (*.test.ts, *.test.js, *.test.mjs, *.test.cjs) retain complete declarative scenario tables and suite callbacks. They do not inherit the production file/function line caps: splitting a table or nested describe only to reduce its measured length makes the tests harder to review. Width checks still apply. Test helpers outside test files retain the production size caps.

TypeScript under tests/ and JavaScript test files receive a complexity warning above 16. Helpers retain the production file/function size caps. This advisory threshold is deliberately separate from the production error at 10; it is not permission to hide production logic in test files. Test behavior, assertions and coverage/mutation thresholds must not be weakened to satisfy a metric.

Refactoring and exceptions

Prefer cohesive responsibilities with explicit inputs and outputs. Do not split arbitrary predicates, rename production files as tests, compress statements onto one line, change the complexity variant, or add blanket parser/tooling exemptions to silence a limit. Preserve validation order, typed failures, returned values, iterator/resource lifecycles, cache trust boundaries and artifact contents.

Before a behavior-preserving refactor, establish characterization cases on the original implementation; compare the candidate's results and failures where practical. Keep every existing assertion. Coverage, differential tests and mutation checks provide bounded evidence, not proof that no possible behavior has changed. Any source-bound mutation equivalence needs independent context and location review, even if only helper placement changes.

An exceptional production suppression must be local, state the invariant or unavoidable external contract, explain why an ordinary decomposition is worse, and include focused tests plus reviewer approval. Exceptions should be rare; none are needed by this refactor.

scripts/complexity-policy.test.mjs checks effective file scopes, error severity, 10/11 complexity, 300/301 file lines, 60/61 function lines, IIFEs, comment/blank handling, 120/121 width, and the limited test/literal exceptions. npm run check includes those tests through test:tooling; npm run lint fails on every production limit because the rules are errors, not warnings.

The pinned ESLint 10 release still provides the core max-len rule. It is deprecated upstream, so an ESLint major-version upgrade must migrate that rule to its maintained replacement and rerun the policy boundary tests. This change does not add an otherwise unnecessary plugin dependency to the current lockfile.

References: complexity, max-lines, max-lines-per-function, max-len, Prettier print width.