Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
136 lines (99 loc) · 4.48 KB

CONTRIBUTING.md

File metadata and controls

136 lines (99 loc) · 4.48 KB
Raw

Contributing to aspens

Prerequisites

Setup

# 1. Fork the repo on GitHub, then:
git clone https://github.com/<your-username>/aspens.git
cd aspens
npm install

# 2. Verify it works
node bin/cli.js --help
npm test

No build step. The CLI runs directly from source (ES modules).

Testing Your Changes Locally

Run the test suite

npm test                          # Run all tests
npx vitest run tests/scanner.test.js  # Run a single test file
npx vitest --watch                # Watch mode during development

Test against a real repo

The best way to verify your changes is to run aspens against an actual codebase.

Option 1: npm link (recommended)

Link your local aspens globally so you can use it like the published package:

# In the aspens directory:
npm link

# Now test from any repo:
cd /path/to/some-project
aspens scan .
aspens doc init --dry-run .

When you're done, unlink:

npm unlink -g aspens

Option 2: Run directly

node /path/to/aspens/bin/cli.js scan /path/to/some-project

Option 3: Use --dry-run

Most write commands support --dry-run to preview output without touching files:

node bin/cli.js doc init --dry-run /path/to/some-project
node bin/cli.js doc sync --dry-run /path/to/some-project

Code Review with CodeRabbit

We use CodeRabbit for automated code review on every PR. Here's what to expect:

  • Automatic review — CodeRabbit reviews your PR when you open it and on each push. No action needed from you.
  • Summary comment — It posts a walkthrough summarizing your changes, sequence diagrams, and a file-by-file breakdown.
  • Inline suggestions — It may leave inline comments with improvement suggestions. You can reply to these directly.
  • Chat commands — You can interact with CodeRabbit in PR comments:
    • @coderabbitai resolve — Mark a suggestion as resolved
    • @coderabbitai summary — Regenerate the summary
    • @coderabbitai review — Request a re-review after changes

Don't worry about "passing" CodeRabbit — the review profile is set to chill. It's there to catch things, not block you. A maintainer will do the final review.

Submitting a Pull Request

  1. Fork the repo and create a branch (git checkout -b my-change)
  2. Make your changes
  3. Run the tests (npm test)
  4. Test against at least one real repo (see above)
  5. Open a PR with a clear description of what changed and why

What makes a good PR

  • Small and focused — one feature or fix per PR
  • Tests included — add or update tests in tests/ for any logic changes
  • Tested against a real repo — mention which repo you tested with in the PR description

Project Structure

bin/cli.js              # Entry point — Commander setup, welcome screen
src/
  commands/
    scan.js             # Tech stack detection output
    doc-init.js         # Skill generation pipeline (3 modes)
    doc-sync.js         # Diff-based skill updates + git hook
    add.js              # Add individual components
    customize.js        # Inject project context into agents
  lib/
    scanner.js          # Deterministic repo scanner (no LLM)
    graph-builder.js    # Import graph construction
    context-builder.js  # Assembles repo context for prompts
    runner.js           # Claude CLI wrapper, stream parsing
    skill-writer.js     # Writes skill files to disk
  prompts/              # Markdown prompt templates
    partials/           # Shared format specs
  templates/            # Bundled components (agents, hooks, commands)
tests/                  # Vitest test files

Code Style

  • ES modules — import/export, no require()
  • Path handling — path.resolve() for absolute, path.relative() for display
  • UI — @clack/prompts for interactive prompts, picocolors for color
  • Error handling — throw descriptive errors with remediation hints, process.exit(1) on unrecoverable failures
  • File reads — try/catch returning null on failure, never throw on missing files

Where to Start

Look for issues labeled good first issue — these are scoped, well-described tasks ideal for first-time contributors.

If you have an idea but aren't sure where to start, open an issue first to discuss it.