Add Semgrep/GritQL lint rules for JS/TS complexity and documentation contracts

[leynos]

Problem

Biome can enforce some of our desired JS/TS maintainability constraints, but not
all of them.

Pure Biome can enforce:

• Functions no longer than 70 lines via complexity.noExcessiveLinesPerFunction.
• Functions with no more than 4 parameters via complexity.useMaxParams.

Biome cannot currently enforce these requirements exactly:

• C90/McCabe cyclomatic complexity no greater than 8.
• General function nesting depth no greater than 3.
• Public JS/TS functions must have JSDoc covering usage, parameters, return
  value, and errors.
• Private JS/TS functions must have one-line JSDoc.
• JS/TS modules/files must have module-level JSDoc, preferably @file.

Biome has noExcessiveCognitiveComplexity, but cognitive complexity is not the
same metric as C90/McCabe cyclomatic complexity. Biome also has
useSingleJsDocAsterisk, but that only normalizes existing JSDoc formatting and
does not require documentation to exist or validate required tags/sections.

Proposed Work

Add either GritQL or Semgrep rules to enforce the remaining contracts:

1. Report JS/TS functions whose McCabe/cyclomatic complexity exceeds 8.
2. Report JS/TS functions whose statement/block nesting depth exceeds 3.
3. Report exported/public functions without complete JSDoc covering:
   • usage
   • parameters
   • return value, where applicable
   • thrown/rejected errors, where applicable
4. Report private/internal functions without a concise one-line JSDoc summary.
5. Report JS/TS files without module-level JSDoc.

Biome Configuration To Enable Alongside This

{
  "linter": {
    "rules": {
      "complexity": {
        "noExcessiveLinesPerFunction": {
          "level": "error",
          "options": {
            "maxLines": 70,
            "skipBlankLines": false,
            "skipIifes": false
          }
        },
        "useMaxParams": {
          "level": "error",
          "options": {
            "max": 4
          }
        }
      }
    }
  }

Mapping:

• Function length <= 70: complexity.noExcessiveLinesPerFunction.
• Parameters <= 4: complexity.useMaxParams.
• McCabe/C90 complexity <= 8: not exactly supported. Biome supports cognitive complexity via noExcessiveCognitiveComplexity, but that is not McCabe/cyclomatic complexity.
• Nesting depth <= 3: not supported as a general function nesting rule. Biome only has targeted nesting rules such as nested test suites, nested promises, nested ternaries, etc.
• Required public/private/module JSDoc: not supported by pure Biome. useSingleJsDocAsterisk only formats existing JSDoc blocks.

Additionally, enable cognitive complexity as an additional readability guard, but
do not treat it as satisfying the McCabe/C90 requirement:

{
  "complexity": {
    "noExcessiveCognitiveComplexity": {
      "level": "error",
      "options": {
        "maxAllowedComplexity": 8
      }
    }
  }

Acceptance Criteria

• CI fails when a JS/TS function exceeds 70 lines.
• CI fails when a JS/TS function has more than 4 parameters.
• CI fails when a JS/TS function has McCabe/cyclomatic complexity greater than 8.
• CI fails when a JS/TS function nests deeper than 3 levels.
• CI fails when public functions lack complete JSDoc.
• CI fails when private functions lack one-line JSDoc.
• CI fails when JS/TS files lack module-level JSDoc.
• Rules are documented in the developers’ guide with examples and suppression
  guidance.

Sources

• Biome JavaScript rules list: https://biomejs.dev/linter/javascript/rules/
• Function line rule: https://biomejs.dev/linter/rules/no-excessive-lines-per-function/
• Max params rule: https://biomejs.dev/linter/rules/use-max-params/
• Cognitive complexity rule: https://biomejs.dev/linter/rules/no-excessive-cognitive-complexity/
• JSDoc formatting rule: https://biomejs.dev/linter/rules/use-single-js-doc-asterisk/
• Biome GritQL reference: https://biomejs.dev/reference/gritql/
• Semgrep rule syntax: https://semgrep.dev/docs/writing-rules/rule-syntax

[leynos]

@CodeRabbit plan

[coderabbitai]

⚠️ Possible Duplicate Issue(s)

• Add Semgrep/GritQL lint rules for JS/TS complexity and documentation contracts simulacat-core#11

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Enable three Biome rules (noExcessiveLinesPerFunction, useMaxParams, noExcessiveCognitiveComplexity) via biome.jsonc configuration for constraints Biome supports natively
• Implement two custom Bun scripts using the TypeScript compiler API: one for McCabe complexity and nesting depth (check-function-complexity.ts), one for JSDoc validation (check-jsdoc.ts)
• Wire both scripts into the semantic:lint pipeline via package.json so CI fails on violations
• Document all rules in the developers' guide with examples and suppression guidance, following the established formatting conventions

Design Choices

Design Choice 1: GritQL/Semgrep vs Custom Bun Scripts for complexity and JSDoc rules

Options Considered:

1. Extend GritQL rules to pattern-match function declarations and JSDoc comments
2. Write Semgrep rules using metavariable-analysis or pattern-where-python for complexity
3. Create custom Bun scripts using the TypeScript compiler API (matching existing check-classlist-length.ts pattern)

Chosen Option: 3

Rationale: Custom Bun scripts. The TypeScript compiler API already powers four existing lint scripts, provides full AST access including comments, and enables stateful traversal needed for complexity/nesting counters. GritQL and Semgrep lack the required capabilities.

Design Choice 2: "Complete JSDoc" definition for public functions

Options Considered:

1. Require @param for every parameter, @returns for non-void functions, @throws for any function containing a throw statement
2. Require description text plus @param/@returns only; treat @throws as optional advisory
3. Require all four tags unconditionally, even when not applicable

Chosen Option: 1

Rationale: Require @param per parameter, @returns for non-void return types, and @throws when a throw statement is present. This balances completeness with practicality and can be statically verified via AST inspection.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Enable Biome Complexity Rules

Configure Biome's built-in complexity rules to enforce function length, parameter count, and cognitive complexity thresholds.

Add Biome complexity rules to configuration

Add three rules to the linter.rules.complexity section of biome.jsonc to enforce function-level maintainability constraints.

• Add noExcessiveLinesPerFunction with maxLines: 70, skipBlankLines: false, skipIifes: false
• Add useMaxParams with max: 4
• Add noExcessiveCognitiveComplexity with maxAllowedComplexity: 8
• Ensure all three rules are set to "error" level

🤖 Prompt for AI agents

Enable three Biome built-in complexity rules by editing `biome.jsonc`, adding
entries to the `linter.rules.complexity` section.

- Add `noExcessiveLinesPerFunction` set to `"error"` with options `maxLines:
70`, `skipBlankLines: false`, `skipIifes: false`
- Add `useMaxParams` set to `"error"` with option `max: 4`
- Add `noExcessiveCognitiveComplexity` set to `"error"` with option
`maxAllowedComplexity: 8`
- All three rules must be set to `"error"` level

Phase 2: Implement McCabe Complexity and Nesting Depth Checker

Create a custom Bun script that traverses function bodies to compute McCabe cyclomatic complexity and maximum nesting depth, failing CI when thresholds are exceeded.

Task 1: Add complexity thresholds to configuration

Extend tools/semantic-lint.config.json with thresholds for the new complexity checker.

• Add functionComplexity section with maxCyclomaticComplexity: 8 and maxNestingDepth: 3
• Follow the existing naming conventions (camelCase keys, numeric values)

Task 2: Create the function complexity checker script

Create scripts/check-function-complexity.ts following the established lint script pattern.

• Add module-level @file JSDoc explaining the script's purpose
• Use Bun.Glob to discover src/**/*.{ts,tsx} files
• Parse each file with ts.createSourceFile using ScriptTarget.Latest and ScriptKind.TSX
• Implement a recursive visitor that identifies function declarations, function expressions, arrow functions, and method declarations
• For each function, compute McCabe complexity by counting: if, for, while, do, case, catch, &&, ||, ??, and conditional expressions (?:)
• Track nesting depth by incrementing on entering block-scoped constructs (if/else, for, while, do, switch, try/catch/finally, arrow/function bodies) and decrementing on exit
• Record violations with file path, line, column, function name, metric name, and actual value
• Output violations to stderr in file:line:col message format
• Return exit code 1 if any violations exist, 0 otherwise
• Guard execution with if (import.meta.main) for testability

Task 3: Wire complexity checker into the lint pipeline

Integrate the new script into the build system and CI pipeline.

• Add lint:complexity script to package.json invoking bun run scripts/check-function-complexity.ts
• Insert bun run lint:complexity into the semantic:lint script chain (after lint:hardcoded-strings, before uvx semgrep)

🤖 Prompt for AI agents

Implement the McCabe cyclomatic complexity and nesting depth checker, then wire
it into the lint pipeline.

**Step 1 — Update `tools/semantic-lint.config.json`:**
- Add a `functionComplexity` section with `maxCyclomaticComplexity: 8` and
`maxNestingDepth: 3`
- Use camelCase keys and numeric values, matching existing conventions

**Step 2 — Create `scripts/check-function-complexity.ts`:**
- Open with a module-level `@file` JSDoc comment explaining the script's purpose
- Use `Bun.Glob` to discover all `src/**/*.{ts,tsx}` files
- Parse each file with `ts.createSourceFile` using `ScriptTarget.Latest` and
`ScriptKind.TSX`
- Implement a recursive visitor identifying function declarations, function
expressions, arrow functions, and method declarations
- For each function, compute McCabe complexity by counting occurrences of: `if`,
`for`, `while`, `do`, `case`, `catch`, `&&`, `||`, `??`, and conditional
expressions (`?:`)
- Track nesting depth by incrementing when entering block-scoped constructs
(`if`/`else`, `for`, `while`, `do`, `switch`, `try`/`catch`/`finally`,
arrow/function bodies) and decrementing on exit
- Record violations including file path, line, column, function name, metric
name, and actual value
- Output all violations to stderr in `file:line:col message` format
- Return exit code 1 if any violations exist, 0 otherwise
- Guard execution with `if (import.meta.main)` for testability

**Step 3 — Update `package.json`:**
- Add a `lint:complexity` script that invokes `bun run
scripts/check-function-complexity.ts`
- Insert `bun run lint:complexity` into the `semantic:lint` script chain after
`lint:hardcoded-strings` and before `uvx semgrep`

Phase 3: Implement JSDoc Validation Checker

Create a custom Bun script that validates JSDoc presence and completeness for exported functions, private functions, and module files.

Task 1: Add JSDoc validation configuration

Extend tools/semantic-lint.config.json with settings for JSDoc validation.

• Add jsdoc section with requireFileDoc: true, requirePublicDoc: true, requirePrivateDoc: true
• Include publicRequiredTags array: ["param", "returns", "throws"] (applied contextually)
• Include privateMinLength: 1 to enforce at least one line of description

Task 2: Create the JSDoc validation script

Create scripts/check-jsdoc.ts following the established lint script pattern.

• Add module-level @file JSDoc explaining the script's purpose
• Use Bun.Glob to discover src/**/*.{ts,tsx} files
• Parse each file with ts.createSourceFile
• Check the first comment in each file for @file tag; report missing module-level JSDoc
• Identify exported functions (those with export modifier or exported via export { name })
• For each exported function, retrieve the leading JSDoc comment using ts.getJSDocCommentsAndTags
• Validate exported functions have: description text, @param for each parameter, @returns if return type is not void/undefined/never, @throws if function body contains a throw statement
• Identify private functions (non-exported function declarations, arrow functions assigned to const)
• Validate private functions have at least one line of JSDoc description
• Output violations to stderr in file:line:col message format
• Return exit code 1 if any violations exist, 0 otherwise
• Guard execution with if (import.meta.main)

Task 3: Wire JSDoc checker into the lint pipeline

Integrate the new script into the build system and CI pipeline.

• Add lint:jsdoc script to package.json invoking bun run scripts/check-jsdoc.ts
• Insert bun run lint:jsdoc into the semantic:lint script chain (after lint:complexity, before uvx semgrep)

🤖 Prompt for AI agents

Implement the JSDoc validation checker, then wire it into the lint pipeline.

**Step 1 — Update `tools/semantic-lint.config.json`:**
- Add a `jsdoc` section with `requireFileDoc: true`, `requirePublicDoc: true`,
`requirePrivateDoc: true`
- Include a `publicRequiredTags` array: `["param", "returns", "throws"]`
(applied contextually)
- Include `privateMinLength: 1` to enforce at least one line of description

**Step 2 — Create `scripts/check-jsdoc.ts`:**
- Open with a module-level `@file` JSDoc comment explaining the script's purpose
- Use `Bun.Glob` to discover all `src/**/*.{ts,tsx}` files
- Parse each file with `ts.createSourceFile`
- Check the first comment in each file for a `@file` tag; report any file
missing module-level JSDoc
- Identify exported functions — those with an `export` modifier or exported via
`export { name }`
- For each exported function, retrieve the leading JSDoc comment using
`ts.getJSDocCommentsAndTags`
- Validate exported functions have: description text, `@param` for each
parameter, `@returns` if the return type is not void/undefined/never, and
`@throws` if the function body contains a `throw` statement
- Identify private functions (non-exported function declarations, arrow
functions assigned to `const`)
- Validate private functions have at least one line of JSDoc description
- Output all violations to stderr in `file:line:col message` format
- Return exit code 1 if any violations exist, 0 otherwise
- Guard execution with `if (import.meta.main)`

**Step 3 — Update `package.json`:**
- Add a `lint:jsdoc` script that invokes `bun run scripts/check-jsdoc.ts`
- Insert `bun run lint:jsdoc` into the `semantic:lint` script chain after
`lint:complexity` and before `uvx semgrep`

Phase 4: Document Rules in Developers' Guide

Update the developers' guide with comprehensive documentation of all new lint rules, including examples of violations, compliant code, and suppression guidance.

Task 1: Expand the semantic lint pipeline documentation

Extend the "What bun semantic does" section in docs/developers-guide.md to cover the new rules.

• Add numbered entry for Function complexity check describing McCabe complexity (≤8) and nesting depth (≤3) enforcement
• Add numbered entry for JSDoc validation describing module-level, public, and private documentation requirements
• Update the existing Biome CI entry to mention the three new complexity rules (function length, parameter count, cognitive complexity)

Task 2: Add dedicated lint rules reference section

Create a new ### Lint rules reference section in docs/developers-guide.md with detailed rule documentation.

• Document each rule with: rule name, threshold/requirement, rationale
• For each rule, provide a fenced TypeScript code block showing a violating example (marked // ✗) and a compliant example (marked // ✓)
• Include suppression guidance showing how to disable each rule type:
  • Biome rules: // biome-ignore lint/complexity/ruleName: justification
  • Custom scripts: Document any inline disable comment pattern (e.g., // lint-disable complexity if implemented) or note that whole-file exclusion via glob patterns in config is the mechanism
• Document the @file JSDoc requirement with example module header
• Document public function JSDoc requirements with example showing @param, @returns, @throws
• Document private function JSDoc requirement with example showing minimal one-line description

🤖 Prompt for AI agents

Update `docs/developers-guide.md` to document all new lint rules introduced in
this ticket.

**Step 1 — Expand the "What `bun semantic` does" section:**
- Add a numbered entry for **Function complexity check** describing McCabe
complexity (≤8) and nesting depth (≤3) enforcement
- Add a numbered entry for **JSDoc validation** describing module-level, public,
and private documentation requirements
- Update the existing Biome CI entry to mention the three new complexity rules:
function length, parameter count, and cognitive complexity

**Step 2 — Add a `### Lint rules reference` section:**
- Document each rule with its name, threshold/requirement, and rationale
- For each rule, provide a fenced TypeScript code block with a **violating**
example (marked `// ✗`) and a **compliant** example (marked `// ✓`)
- Include suppression guidance for:
  - Biome rules: `// biome-ignore lint/complexity/ruleName: justification`
- Custom scripts: inline disable comment pattern (e.g., `// lint-disable
complexity`) or note that whole-file exclusion via glob patterns in config is
the mechanism
- Document the `@file` JSDoc requirement with an example module header
- Document public function JSDoc requirements with an example showing `@param`,
`@returns`, and `@throws`
- Document the private function JSDoc requirement with an example showing a
minimal one-line description

Research

The project uses a three-layer linting stack: Biome (with 44 GritQL plugins), Semgrep (regex/AST rules in tools/semgrep-semantic.yml), and custom Bun scripts (scripts/*.ts) driven by tools/semantic-lint.config.json. All linting is orchestrated via bun semantic which chains biome ci, custom scripts, Semgrep, and Stylelint. Custom scripts use the TypeScript compiler API (ts.createSourceFile + ts.forEachChild) for AST traversal and follow a consistent pattern: import.meta.main guard, main() returning exit code 0/1, and error output in file:line:col message format.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Enable three Biome built-in complexity rules by editing `biome.jsonc`, adding
entries to the `linter.rules.complexity` section.

- Add `noExcessiveLinesPerFunction` set to `"error"` with options `maxLines:
70`, `skipBlankLines: false`, `skipIifes: false`
- Add `useMaxParams` set to `"error"` with option `max: 4`
- Add `noExcessiveCognitiveComplexity` set to `"error"` with option
`maxAllowedComplexity: 8`
- All three rules must be set to `"error"` level
===============================================================================

Task: 2

Implement the McCabe cyclomatic complexity and nesting depth checker, then wire
it into the lint pipeline.

**Step 1 — Update `tools/semantic-lint.config.json`:**
- Add a `functionComplexity` section with `maxCyclomaticComplexity: 8` and
`maxNestingDepth: 3`
- Use camelCase keys and numeric values, matching existing conventions

**Step 2 — Create `scripts/check-function-complexity.ts`:**
- Open with a module-level `@file` JSDoc comment explaining the script's purpose
- Use `Bun.Glob` to discover all `src/**/*.{ts,tsx}` files
- Parse each file with `ts.createSourceFile` using `ScriptTarget.Latest` and
`ScriptKind.TSX`
- Implement a recursive visitor identifying function declarations, function
expressions, arrow functions, and method declarations
- For each function, compute McCabe complexity by counting occurrences of: `if`,
`for`, `while`, `do`, `case`, `catch`, `&&`, `||`, `??`, and conditional
expressions (`?:`)
- Track nesting depth by incrementing when entering block-scoped constructs
(`if`/`else`, `for`, `while`, `do`, `switch`, `try`/`catch`/`finally`,
arrow/function bodies) and decrementing on exit
- Record violations including file path, line, column, function name, metric
name, and actual value
- Output all violations to stderr in `file:line:col message` format
- Return exit code 1 if any violations exist, 0 otherwise
- Guard execution with `if (import.meta.main)` for testability

**Step 3 — Update `package.json`:**
- Add a `lint:complexity` script that invokes `bun run
scripts/check-function-complexity.ts`
- Insert `bun run lint:complexity` into the `semantic:lint` script chain after
`lint:hardcoded-strings` and before `uvx semgrep`
===============================================================================

Task: 3

Implement the JSDoc validation checker, then wire it into the lint pipeline.

**Step 1 — Update `tools/semantic-lint.config.json`:**
- Add a `jsdoc` section with `requireFileDoc: true`, `requirePublicDoc: true`,
`requirePrivateDoc: true`
- Include a `publicRequiredTags` array: `["param", "returns", "throws"]`
(applied contextually)
- Include `privateMinLength: 1` to enforce at least one line of description

**Step 2 — Create `scripts/check-jsdoc.ts`:**
- Open with a module-level `@file` JSDoc comment explaining the script's purpose
- Use `Bun.Glob` to discover all `src/**/*.{ts,tsx}` files
- Parse each file with `ts.createSourceFile`
- Check the first comment in each file for a `@file` tag; report any file
missing module-level JSDoc
- Identify exported functions — those with an `export` modifier or exported via
`export { name }`
- For each exported function, retrieve the leading JSDoc comment using
`ts.getJSDocCommentsAndTags`
- Validate exported functions have: description text, `@param` for each
parameter, `@returns` if the return type is not void/undefined/never, and
`@throws` if the function body contains a `throw` statement
- Identify private functions (non-exported function declarations, arrow
functions assigned to `const`)
- Validate private functions have at least one line of JSDoc description
- Output all violations to stderr in `file:line:col message` format
- Return exit code 1 if any violations exist, 0 otherwise
- Guard execution with `if (import.meta.main)`

**Step 3 — Update `package.json`:**
- Add a `lint:jsdoc` script that invokes `bun run scripts/check-jsdoc.ts`
- Insert `bun run lint:jsdoc` into the `semantic:lint` script chain after
`lint:complexity` and before `uvx semgrep`
===============================================================================

Task: 4

Update `docs/developers-guide.md` to document all new lint rules introduced in
this ticket.

**Step 1 — Expand the "What `bun semantic` does" section:**
- Add a numbered entry for **Function complexity check** describing McCabe
complexity (≤8) and nesting depth (≤3) enforcement
- Add a numbered entry for **JSDoc validation** describing module-level, public,
and private documentation requirements
- Update the existing Biome CI entry to mention the three new complexity rules:
function length, parameter count, and cognitive complexity

**Step 2 — Add a `### Lint rules reference` section:**
- Document each rule with its name, threshold/requirement, and rationale
- For each rule, provide a fenced TypeScript code block with a **violating**
example (marked `// ✗`) and a **compliant** example (marked `// ✓`)
- Include suppression guidance for:
  - Biome rules: `// biome-ignore lint/complexity/ruleName: justification`
- Custom scripts: inline disable comment pattern (e.g., `// lint-disable
complexity`) or note that whole-file exclusion via glob patterns in config is
the mechanism
- Document the `@file` JSDoc requirement with an example module header
- Document public function JSDoc requirements with an example showing `@param`,
`@returns`, and `@throws`
- Document the private function JSDoc requirement with an example showing a
minimal one-line description

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!