Code Quality Gates
Relevant source files
The following files were used as context for generating this wiki page:
Code Quality Gates are a mandatory set of 17 automated checks enforced to maintain project stability, code readability, and architectural integrity. These gates serve as a centralized bus for pre-commit, pre-push, and CI pipelines, ensuring that every contribution adheres to strict technical "redlines" before being merged or deployed.
The system utilizes a "ratchet" mechanism stored in .gates/*.json files. This mechanism defines current baselines for style and quality metrics, allowing these metrics to improve (decrease) over time while strictly prohibiting any regressions (increases) without explicit justification and an --update command.
Sources: scripts/gates/run.ts:1-12, scripts/AGENTS.md:15-18
Core Architecture and Execution
The gate system is centralized in a single runner script that executes various check modules. It enforces a "fail-fast" policy where the first failing check stops the execution and provides a reproduction command for the developer.
The diagram shows the flow of gate execution from selection through the execution bus to final result.
Sources: scripts/gates/run.ts:63-80, scripts/gates/run.ts:108-137
Execution Commands
Developers interact with the gate system via the following commands:
node scripts/gates/run.ts: Runs all 17 gates.node scripts/gates/run.ts <lane>: Runs a specific group (e.g.,code,doc,guard,notes).node scripts/gates/run.ts --list: Lists all available gates and their descriptions.node scripts/gates/run.ts --dry-run: Displays the commands that would be executed without running them.
Sources: scripts/AGENTS.md:8-13, scripts/gates/run.ts:18-25
Tiered Rules and Limits
The project categorizes files into "Tiers" to apply different quality thresholds. These rules are governed by scripts/gates/rules.ts, which serves as the single source of truth for all thresholds.
| Threshold Category | Backend Limit | Frontend Limit | Description |
|---|---|---|---|
| File Lines | 300 lines | 500 lines | Maximum physical lines per file. |
| Directory Density | 5 files | 5 files | Maximum controlled files per directory. |
| Function Length | 80 lines | 80 lines | Maximum lines for a single function. |
| Line Length | 120 chars | 120 chars | Maximum horizontal characters per line. |
Sources: scripts/gates/rules.ts:25-34, scripts/gates/run.ts:40-48
Path Classification
Tiers are assigned based on the file path to determine which limits apply or if a file is exempt.
- Frontend: Paths starting with
dashboard/. - Exempt: External assets, third-party code (e.g.,
dashboard/vendor/), documentation (docs/), and metadata (.gates/). - Backend: Default for all other files in
src/,bin/, andscripts/.
Sources: scripts/gates/rules.ts:39-50, scripts/gates/rules.ts:66-70
Specialized Validation Gates
Syntax and Contract Safety
Before performing complex analysis, the system ensures code is syntactically valid and complies with upstream contracts.
- Syntax Gate: Uses
tsc --noCheckfor TypeScript files to ensure they can be parsed. This prevents a "false green" in type-checking ratchets caused by parser early exits. - Upstream Contract Gate: Verifies that all mandatory upstream endpoints and header names used in the code are registered in the centralized truth file
src/upstream/upstream-contract.ts. It prohibits raw string literals for headers to ensure consistency.
Sources: scripts/gates/checks/code/syntax.ts:15-20, scripts/check-upstream-contract.ts:9-19
Text and Style Standards
The project enforces strict linguistic rules to ensure grep-ability and readability.
- ASCII Punctuation: Prohibits full-width (CJK) punctuation in comments and documentation to ensure searchability.
- Emoji/Emoticon Ban: Prohibits emojis, dingbats, and text-based emoticons (e.g., "233", "(笑)") in source code and documentation.
- Markdown Restriction: Prohibits Markdown syntax within source code comments (e.g., backticks, bolding, headers) as they are not rendered in IDEs and cause visual noise.
Sources: scripts/gates/checks/style/style.ts:9-30, scripts/gates/checks/style/style.ts:54-65
Documentation Alignment
The check-docs.ts gate ensures that the documentation truthfully represents the implementation.
The documentation gate validates endpoints, file paths, and index links.
Sources: scripts/gates/checks/doc/check-docs.ts:4-15
Internationalization (i18n) Redlines
The check-i18n.ts script enforces three primary rules for the dashboard:
- No Hardcoded CJK: TypeScript files in
dashboard/must not contain hardcoded Chinese/Japanese/Korean characters; they must use thet('key')function. - Key Alignment: All language dictionaries must contain exactly the same keys as the base locale.
- No Duplicate Keys: Dictionary files are scanned for duplicate key definitions to prevent silent data overwrites.
Sources: scripts/check-i18n.ts:8-16, scripts/check-i18n.ts:108-115
Ratchet and Baseline Management
The system uses .gates/*.json files to track the "strictness" of certain rules.
- Detection: The check script counts violations (e.g., 50 full-width commas in
file.ts). - Comparison: The script compares this count against the baseline in
.gates/style-baseline.json. - Enforcement: If the count increases, the gate fails. If the count decreases, the gate passes but warns the developer to update the baseline.
- Updating: Running the gate with
--updateacknowledges the current state as the new, stricter baseline.
Sources: scripts/AGENTS.md:19-24, scripts/gates/checks/style/style.ts:133-145
Summary
Code Quality Gates act as an automated guardian for the freebuff-proxy project. By enforcing hard limits on file size and function length, prohibiting hardcoded CJK strings in the UI, and ensuring documentation stays in sync with code routes, the system prevents technical debt from accumulating. The use of the "ratchet" mechanism ensures that while the project can have legacy style issues, the quality can only improve over time.