Contributing to express-swagger-auto

Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to the express-swagger-auto project.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the maintainers.

Getting Started
Development Workflow
Commit Guidelines
Testing
Documentation
Submitting Changes
Code Style
Release Process

Getting Started

Prerequisites

Node.js 16+ (tested with 16, 18, 20, 22)
pnpm 8+ (monorepo package manager)
Git 2.x+
TypeScript knowledge (project is TypeScript-first)

Setup Development Environment

Fork the repository

# Visit https://github.com/iAn-P1nt0/express-swagger-auto/fork

Clone your fork

git clone https://github.com/YOUR_USERNAME/express-swagger-auto.git
cd express-swagger-auto

Add upstream remote

git remote add upstream https://github.com/iAn-P1nt0/express-swagger-auto.git

Install dependencies
```
pnpm install
```
Verify setup
```
pnpm build
pnpm test
pnpm lint
```
All commands should complete without errors.

Development Workflow

Creating a Feature Branch

Use conventional branch naming:

# Features
git checkout -b feature/security-detector-enhancements

# Bug fixes
git checkout -b fix/route-discovery-cycle-detection

# Documentation
git checkout -b docs/add-migration-guide

# Performance improvements
git checkout -b perf/lazy-schema-loading

# Refactoring
git checkout -b refactor/validator-registry

Local Development

Start development mode (watches TypeScript changes)
```
pnpm dev
```
Run tests in watch mode
```
pnpm test:watch
```
Generate coverage report
```
pnpm test:coverage
```
Type check only (without building)
```
pnpm typecheck
```

Lint code

pnpm lint
pnpm lint:fix  # Auto-fix issues

Testing Requirements

All contributions must include tests. Here's what's expected:

Unit Tests

Test individual functions and classes
Place in same directory as source: src/module/Feature.test.ts
Use Vitest (already configured)
Aim for >85% coverage for new code

Integration Tests

Test how modules work together
Verify real-world scenarios
Add to src/integration.test.ts
Test with actual Express apps when applicable

Example Tests

Test example apps work end-to-end
Run: cd examples/decorator-example && pnpm test

Example Test Structure

import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { Feature } from './Feature';

describe('Feature', () => {
  let instance: Feature;

  beforeEach(() => {
    instance = new Feature();
  });

  afterEach(() => {
    // Cleanup
  });

  it('should do something', () => {
    const result = instance.someMethod();
    expect(result).toBe(expectedValue);
  });

  it('should handle errors', () => {
    expect(() => instance.invalidMethod()).toThrow();
  });
});

Commit Guidelines

We follow Conventional Commits for clear commit history.

Format

<type>(<scope>): <subject>

<body>

<footer>

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (not affecting logic)
refactor: Code refactoring
perf: Performance improvements
test: Adding or updating tests
chore: Build process, dependencies
ci: CI/CD configuration changes

Scope

Scopes help categorize changes:

cli: CLI interface changes
core: Core engine (RouteDiscovery, SpecGenerator)
security: Security detection module
watch: File watching module
validators: Validator adapters
parsers: JSDoc and decorator parsers
middleware: Express middleware
docs: Documentation files
ci: GitHub workflows
build: Build configuration

Examples

git commit -m "feat(cli): add watch mode for development"
git commit -m "fix(security): improve JWT detection regex"
git commit -m "docs(cli): update command examples"
git commit -m "test(validators): add edge case tests for Yup adapter"
git commit -m "perf(core): implement schema caching"

Commit Message Best Practices

Use imperative mood: "add feature" not "added feature"
Be specific: "fix route discovery for nested routers" not "fix bug"
Reference issues: Include Fixes #123 in body
Keep subject under 50 characters
Explain why, not what: The code shows what, commit shows why

Testing

Running Tests

# Run all tests once
pnpm test

# Watch mode (re-runs on changes)
pnpm test:watch

# Generate coverage report
pnpm test:coverage

# Run specific test file
pnpm test src/security/SecurityDetector.test.ts

Coverage Requirements

New code: ≥85% coverage required
Core modules (src/core/*): ≥85% coverage
Overall: Track and aim for 85%+
Run pnpm test:coverage to check

Mutation Testing

Mutation testing helps validate the quality of tests by checking if they can detect small code changes:

# Run mutation testing (time-intensive)
pnpm test:mutation

# Run on core modules only (faster)
pnpm test:mutation:core

# Generate mutation report summary
pnpm mutation-report

Target mutation scores:

Core modules: ≥85%
Parsers/Validators: ≥80%
CLI: ≥75%

See docs/MUTATION_TESTING.md for detailed guidance.

Example App Testing

# Test decorator example
cd examples/decorator-example
pnpm install
pnpm build
pnpm test

# Test jsdoc example
cd examples/jsdoc-example
pnpm install
pnpm test

# Test runtime example
cd examples/runtime-example
pnpm install
node index.js  # Should start server

Documentation

Where Documentation Lives

User Docs: docs/ folder
- docs/CLI.md - Command reference
- docs/SECURITY.md - Security guide
- docs/PERFORMANCE.md - Performance tuning
- docs/API.md - API reference (if adding public APIs)
Code Comments: Use JSDoc for public APIs
Examples: examples/ folder with working apps
Release Notes: CHANGELOG.md

Documentation Standards

Public APIs must have JSDoc

/**
 * Discovers routes in an Express application
 * @param app Express Application or Router
 * @returns Array of discovered routes
 */
public discover(app: ExpressApp): RouteMetadata[] {
  // ...
}

Update docs when changing behavior
- If CLI flags change, update docs/CLI.md
- If API changes, update docs/API.md
- If security scheme detection changes, update docs/SECURITY.md
Add examples for complex features
- Include code snippets in documentation
- Preferably link to working example apps

Submitting Changes

Before Creating a PR

Sync with upstream

git fetch upstream
git rebase upstream/main

Build and test

pnpm install
pnpm build
pnpm test
pnpm lint:fix

Check for conflicts
```
git status  # Should be clean
```

Creating a Pull Request

Push your branch
```
git push origin feature/your-feature
```
Create PR on GitHub
- Use the PR template (auto-provided)
- Link related issues: "Fixes #123"
- Describe what and why
- List testing steps

PR Title Format

feat(scope): brief description
fix(scope): brief description
docs(scope): brief description

PR Checklist

Before submitting, ensure:

Review Process

Automated Checks
- CI/CD workflows must pass
- Coverage must not decrease significantly
- All tests must pass
Code Review
- At least one maintainer review required
- Feedback will be provided on design/implementation
- Discussion on tradeoffs is encouraged
Changes Requested
- Address feedback in follow-up commits
- Push to same branch (PR auto-updates)
- Re-request review when ready

Code Style

TypeScript/JavaScript Standards

Formatter: Prettier (configured in package.json)
Linter: ESLint with TypeScript support
Auto-fix: Run pnpm lint:fix to fix style issues

Conventions

// ✅ Use const, not let or var
const discovery = new RouteDiscovery();

// ✅ Explicit type annotations for public APIs
public generate(routes: RouteMetadata[]): OpenAPISpec {

// ✅ Use interfaces for public types
export interface OpenAPIInfo {
  title: string;
  version: string;
}

// ✅ Prefer early returns
if (!routes) return [];
if (routes.length === 0) return [];

// ✅ Use meaningful variable names
const routeMetadata = discovery.discover(app);

// ❌ Avoid single-letter variables (except loop counters)
const x = 5; // Bad
const routeCount = 5; // Good

// ✅ Use async/await, not .then()
const spec = await generator.generate(routes);

// ✅ Group related functionality together
describe('RouteDiscovery', () => {
  describe('initialization', () => { ... });
  describe('discovery', () => { ... });
});

File Organization

src/
├── core/                    # Core engine
│   ├── RouteDiscovery.ts
│   ├── SpecGenerator.ts
│   └── *.test.ts
├── security/                # Security module
│   ├── SecurityDetector.ts
│   ├── SecurityDetector.test.ts
│   └── index.ts
├── watch/                   # File watching
├── validators/              # Validator adapters
├── parsers/                 # JSDoc/Decorator parsers
├── middleware/              # Express middleware
├── decorators/              # Decorator system
├── types.ts                 # Shared types
├── index.ts                 # Public exports
└── cli.ts                   # CLI entry point

Release Process

Version Numbering

We follow Semantic Versioning:

MAJOR (1.0.0): Breaking changes
MINOR (0.1.0): New features (backward compatible)
PATCH (0.0.1): Bug fixes

Release Checklist

Update Version
```
npm version minor  # or patch/major
```
Update CHANGELOG.md
- Document all changes since last release
- Group by: Added, Changed, Fixed, Removed, Security
- Link to PRs where applicable

Run Full Test Suite

pnpm clean
pnpm install
pnpm build
pnpm test

Create GitHub Tag
```
git tag v0.2.0
git push origin v0.2.0
```
Publish to npm
```
npm publish
```
Create GitHub Release
- Use automated GitHub Releases feature
- Copy CHANGELOG excerpt to release notes

Common Questions

How long does review take?

Usually 1-3 days for maintainer review. Critical fixes may be faster.

Can I work on multiple features?

Prefer one feature/fix per branch and PR. Easier to review and revert if needed.

How do I report a bug?

File an issue with:

Detailed description
Steps to reproduce
Expected vs actual behavior
Environment (Node version, Express version, OS)

How do I suggest a feature?

Open an issue with:

Use case and motivation
Proposed API (if applicable)
Any implementation ideas

What if my PR is stale?

Maintainer will reach out after 2 weeks
You can update branch: git rebase upstream/main
Re-request review when ready

Resources

Project Goals: See ROADMAP.md
Architecture: See CLAUDE.md (internal guardrails)
Setup Guide: See README.md
API Reference: See docs/API.md
Security Guide: See docs/SECURITY.md

Questions?

Documentation: Check docs/ folder
Issues: Browse GitHub Issues
Discussions: Use GitHub Discussions

Thank you for contributing! Your efforts help make express-swagger-auto better for everyone. 🎉

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History