Contributing to Unreach

Thank you for your interest in contributing to Unreach! This document provides guidelines and instructions for contributing to the project.

Code of Conduct

This project adheres to a code of conduct that all contributors are expected to follow. Please be respectful, inclusive, and constructive in all interactions.

Getting Started

Prerequisites

Node.js: Version 18.0.0 or higher
npm: Package manager
Git: Version control

Fork and Clone

Fork the repository on GitHub

Clone your fork:

bash

git clone https://github.com/kiron0/unreach.git
cd unreach

Add the upstream repository:

bash

git remote add upstream https://github.com/kiron0/unreach.git

Development Setup

1. Install Dependencies

bash

npm install

2. Build the Project

bash

npm run build

This compiles TypeScript to JavaScript in the dist/ directory.

3. Run in Development Mode

bash

# Build and watch for changes
npm run build:watch

# In another terminal, run the CLI
node dist/index.js scan

4. Link for Local Testing

bash

# Build first
npm run build

# Link globally (allows using 'unreach' command)
npm link

Now you can use unreach command from anywhere to test your changes.

Project Structure

package/
├── src/
│   ├── cli/              # CLI interface (args, handler, ui, interactive)
│   ├── core/             # Core error handling
│   ├── lib/              # Core library code
│   │   ├── analyzer/     # Analysis logic (finders, reachability)
│   │   ├── cache.ts      # Caching system
│   │   ├── config.ts     # Configuration loading
│   │   ├── graph.ts      # Dependency graph builder
│   │   ├── parser.ts     # AST parser
│   │   └── ...
│   ├── types/            # TypeScript type definitions
│   └── utils/            # Utility functions
├── dist/                 # Compiled output (generated)
├── reports/              # Documentation and analysis reports
├── tests/                # Test files (co-located with source)
└── package.json

Key Components

Parser (src/lib/parser.ts): Parses TypeScript/JavaScript files into AST
Graph Builder (src/lib/graph.ts): Builds dependency graph from parsed files
Analyzer (src/lib/analyzer/): Performs reachability analysis and finds unused code
CLI (src/cli/): Command-line interface and user interaction

Code Style Guidelines

TypeScript

Strict Mode: The project uses strict TypeScript settings
Type Safety: Avoid any types. Use proper types or unknown with type guards
Naming Conventions:
- Classes: PascalCase (e.g., DependencyGraph)
- Functions/Variables: camelCase (e.g., parseFile)
- Constants: UPPER_SNAKE_CASE (e.g., MAX_FILE_SIZE)
- Files: kebab-case.ts (e.g., config-loader.ts)

Formatting

The project uses Prettier for code formatting:

bash

# Format all files
npm run format

# Or format specific files
npx prettier --write "src/**/*.ts"

Code Organization

Single Responsibility: Each file/class should have one clear purpose
Modular Design: Keep functions small and focused
Error Handling: Use the UnreachError class for consistent error handling
Comments: Add JSDoc comments for public APIs

Example Code Style

typescript

/**
 * Parses a TypeScript file and extracts dependency information.
 * @param filePath - Path to the file to parse
 * @param useCache - Whether to use cached AST if available
 * @returns Dependency node or null if parsing fails
 */
export function parseFile(
  filePath: string,
  useCache: boolean = true,
): DependencyNode | null {
  // Implementation
}

Import Organization

External dependencies (npm packages)
Internal modules (from src/)
Type imports (use import type when possible)

typescript

import chalk from "chalk";
import * as fs from "fs";
import * as path from "path";

import type { DependencyNode } from "../types/index.js";
import { ASTParser } from "./parser.js";

Testing

Running Tests

bash

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

# Run tests with coverage
npm run test:coverage

Test Structure

Tests are co-located with source files:

Source: src/lib/config.ts
Test: src/lib/config.test.ts

Writing Tests

Use Vitest as the testing framework
Follow the describe → it structure
Use descriptive test names
Test both happy paths and edge cases

Example Test:

typescript

import { describe, expect, it } from "vitest";
import { ConfigLoader } from "./config.js";

describe("ConfigLoader", () => {
  it("should load configuration file", () => {
    // Arrange
    const loader = new ConfigLoader("./test-fixtures");

    // Act
    const config = loader.load();

    // Assert
    expect(config).not.toBeNull();
    expect(config?.ignore?.files).toContain("**/*.test.ts");
  });
});

Test Coverage

Aim for high test coverage, especially for core functionality
Test edge cases and error conditions
Use beforeEach and afterEach for test setup/cleanup
Mock external dependencies when appropriate

Test Requirements

✅ All tests must pass before submitting a PR
✅ New features should include tests
✅ Bug fixes should include regression tests
✅ Tests should be fast and isolated

Making Changes

1. Create a Branch

bash

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

2. Make Your Changes

Write clean, well-documented code
Follow the code style guidelines
Add tests for new functionality
Update documentation if needed

3. Commit Your Changes

Use clear, descriptive commit messages:

bash

git commit -m "feat: add file size limit configuration"
git commit -m "fix: resolve config validation error"
git commit -m "test: add tests for watch mode rate limiting"

Commit Message Format:

feat: - New feature
fix: - Bug fix
test: - Adding or updating tests
docs: - Documentation changes
refactor: - Code refactoring
perf: - Performance improvements
chore: - Maintenance tasks

4. Keep Your Branch Updated

bash

# Fetch latest changes
git fetch upstream

# Rebase your branch on main
git rebase upstream/main

Pull Request Process

Before Submitting

✅ All tests pass: Run npm test
✅ Code is formatted: Run npm run format
✅ Build succeeds: Run npm run build
✅ No linter errors: Check for TypeScript errors
✅ Documentation updated: Update relevant docs if needed

Creating a Pull Request

Push your branch:

bash

git push origin feature/your-feature-name

Create PR on GitHub:
- Go to the repository on GitHub
- Click "New Pull Request"
- Select your branch
- Fill out the PR template

PR Description Template

markdown

## Description

Brief description of changes

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing

- [ ] Tests added/updated
- [ ] All tests pass
- [ ] Manual testing completed

## Checklist

- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings generated

PR Review Process

Automated Checks: CI will run tests and checks
Code Review: Maintainers will review your code
Feedback: Address any requested changes
Approval: Once approved, your PR will be merged

After PR is Merged

Your branch can be deleted
Update your local main branch: git pull upstream main

Reporting Issues

Before Reporting

Check if the issue already exists
Try to reproduce the issue
Check the documentation

Issue Template

When creating an issue, include:

Description: Clear description of the issue
Steps to Reproduce: How to reproduce the issue
Expected Behavior: What should happen
Actual Behavior: What actually happens
Environment: Node.js version, OS, etc.
Screenshots/Logs: If applicable

Bug Reports

markdown

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:

1. Run 'unreach scan ...'
2. See error

**Expected behavior**
What you expected to happen.

**Environment:**

- Node.js version: [e.g., 18.0.0]
- OS: [e.g., macOS 14.0]
- Unreach version: [e.g., 0.1.0]

**Additional context**
Any other relevant information.

Development Tips

Debugging

Use --debug flag for detailed error information
Use --verbose flag for detailed processing logs
Use Node.js debugger: node --inspect dist/index.js scan

Common Tasks

Adding a new finder (e.g., unused interfaces):

Create src/lib/analyzer/finders/interface-finder.ts
Implement the finder logic
Export from src/lib/analyzer/finders/index.ts
Add to src/lib/analyzer/index.ts
Add tests

Adding a new CLI option:

Add option to src/cli/args.ts
Add to ScanOptions in src/types/index.ts
Implement logic in src/cli/handler.ts
Update help text in src/cli/ui.ts
Add tests

Adding configuration option:

Add to UnreachConfig in src/lib/config.ts
Add validation in validateConfig()
Add default in mergeWithDefaults()
Update documentation
Add tests

Getting Help

Documentation: Check reports/ directory for detailed docs
Issues: Search existing issues on GitHub
Discussions: Use GitHub Discussions for questions

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to Unreach! 🎉

Contributing to Unreach ​

Code of Conduct ​

Getting Started ​

Prerequisites ​

Fork and Clone ​

Development Setup ​

1. Install Dependencies ​

2. Build the Project ​

3. Run in Development Mode ​

4. Link for Local Testing ​

Project Structure ​

Key Components ​

Code Style Guidelines ​

TypeScript ​

Formatting ​

Code Organization ​

Example Code Style ​

Import Organization ​

Testing ​

Running Tests ​

Test Structure ​

Writing Tests ​

Test Coverage ​

Test Requirements ​

Making Changes ​

1. Create a Branch ​

2. Make Your Changes ​

3. Commit Your Changes ​

4. Keep Your Branch Updated ​

Pull Request Process ​

Before Submitting ​

Creating a Pull Request ​

PR Description Template ​

PR Review Process ​

After PR is Merged ​

Reporting Issues ​

Before Reporting ​

Issue Template ​

Bug Reports ​

Development Tips ​

Debugging ​

Common Tasks ​

Getting Help ​

License ​

Contributing to Unreach

Code of Conduct

Getting Started

Prerequisites

Fork and Clone

Development Setup

1. Install Dependencies

2. Build the Project

3. Run in Development Mode

4. Link for Local Testing

Project Structure

Key Components

Code Style Guidelines

TypeScript

Formatting

Code Organization

Example Code Style

Import Organization

Testing

Running Tests

Test Structure

Writing Tests

Test Coverage

Test Requirements

Making Changes

1. Create a Branch

2. Make Your Changes

3. Commit Your Changes

4. Keep Your Branch Updated

Pull Request Process

Before Submitting

Creating a Pull Request

PR Description Template

PR Review Process

After PR is Merged

Reporting Issues

Before Reporting

Issue Template

Bug Reports

Development Tips

Debugging

Common Tasks

Getting Help

License