Code Quality and Standards

Purpose and Scope

This page documents the code quality standards, naming conventions, formatting rules, and linting configuration used in the simap-mcp project. It specifies the tools, configurations, and practices that ensure consistency and maintainability across the codebase. As of v1.3.0, the project requires Node.js >=22 for development and execution CONTRIBUTING.md31

For information about the development workflow and pull request process, see 9.1 How to Contribute For testing strategies and test execution, see 6.4 Testing

---

Quality Toolchain Overview

The project uses four primary quality tools, each configured and invoked through npm scripts defined in package.json.

Title: Quality Toolchain and Data Flow

Sources: CONTRIBUTING.md48-60 tsconfig.json1-17 eslint.config.js1-21

Tool Responsibilities

Tool	Purpose	Configuration	npm Script
Prettier	Enforces consistent code formatting (spacing, quotes, semicolons)	.prettierrc1-7	npm run format
ESLint	Detects code quality issues, unused variables, type violations	eslint.config.js1-21	npm run lint
TypeScript	Validates type safety, compiles to JavaScript	tsconfig.json1-17	npm run typecheck
Vitest	Executes unit tests, validates behavior	CONTRIBUTING.md58-59	npm test

Sources: CONTRIBUTING.md48-60 tsconfig.json1-17 eslint.config.js1-21 .prettierrc1-7

---

TypeScript Standards

The project enforces strict TypeScript standards to maximize type safety and prevent runtime errors.

Compiler Configuration

Key TypeScript compiler options from tsconfig.json:

Option	Value	Purpose
strict	true	Enables all strict type-checking options tsconfig.json8
target	"ES2023"	Compiles to modern JavaScript tsconfig.json3
module	"NodeNext"	Modern module resolution for Node.js tsconfig.json4-5
forceConsistentCasingInFileNames	true	Prevents case-sensitivity issues tsconfig.json11

Type Safety Rules

Title: Natural Language Requirements to TypeScript Entities

Sources: tsconfig.json8 CONTRIBUTING.md131-150 CONTRIBUTING.md190-195

Public API Guidelines

The project uses strict mode to ensure robustness. The use of any is discouraged in favor of more specific types or unknown.

• Strict mode: Always enabled tsconfig.json8
• No any: Triggers a warning via ESLint eslint.config.js14 Use unknown if necessary CONTRIBUTING.md193
• Explicit types: Required for public function parameters CONTRIBUTING.md194
• Zod Validation: Used for all tool inputs to ensure runtime safety via *InputSchema CONTRIBUTING.md148-150

Sources: tsconfig.json8 eslint.config.js14 CONTRIBUTING.md131-150 CONTRIBUTING.md190-195

---

Naming Conventions

The project follows strict naming conventions to maintain consistency across files, functions, classes, and MCP tools.

Convention Summary

Element	Convention	Examples
Files	kebab-case	search-cpv.ts
Functions	camelCase	registerSearchCpv
Classes	PascalCase	SimapClient
Constants	UPPER_SNAKE	SIMAP_API_BASE
MCP Tools	snake_case	search_cpv_codes
Types/Interfaces	PascalCase	SearchXxxInput

Sources: CONTRIBUTING.md150 CONTRIBUTING.md196-205

Naming Patterns in Code

Title: System Names to Code Identifiers

Sources: CONTRIBUTING.md123-129 CONTRIBUTING.md196-205

---

Code Formatting

Prettier enforces consistent code formatting automatically as defined in .prettierrc.

Formatting Rules

Rule	Value	Configuration Key
Indentation	2 spaces	"tabWidth": 2
Semicolons	Required	"semi": true
Quotes	Double quotes	"singleQuote": false
Trailing Commas	ES5	"trailingComma": "es5"
Line Width	90 characters	"printWidth": 90

Sources: CONTRIBUTING.md207-212 .prettierrc1-7

---

Linting Configuration

ESLint analyzes code for quality issues, enforcing TypeScript best practices. Configuration is defined in eslint.config.js using the modern flat config format.

ESLint Rule Set

The project uses typescript-eslint with several specific overrides:

• Unused Variables: Errors on unused variables unless prefixed with an underscore (_) eslint.config.js9-12
• Explicit Returns: Explicit function return types are not strictly required (off) to allow for inference where appropriate eslint.config.js13
• No Explicit Any: Usage of any triggers a warning to encourage safer types eslint.config.js14

Sources: eslint.config.js1-21

---

Quality Gates

Before code is considered production-ready, it must pass several checks as defined in the development workflow. Note that Node.js 22+ is required for these gates CONTRIBUTING.md31

1. Compilation: npm run build must succeed CONTRIBUTING.md50 CONTRIBUTING.md107
2. Type Checking: npm run typecheck (tsc --noEmit) must pass CONTRIBUTING.md57 CONTRIBUTING.md106
3. Testing: npm test must pass all vitest suites CONTRIBUTING.md58 CONTRIBUTING.md108
4. Linting: npm run lint must pass without errors CONTRIBUTING.md53 CONTRIBUTING.md105
5. Formatting: Code must be checked via npm run format:check CONTRIBUTING.md56

Sources: CONTRIBUTING.md46-60 CONTRIBUTING.md102-110 eslint.config.js1-21