Skip to content

contributing.md

Latest commit

 

History

History
298 lines (210 loc) · 8.21 KB

contributing.md

File metadata and controls

298 lines (210 loc) · 8.21 KB
Raw

Contributing Guide

This guide covers the development workflow, conventions, and tooling for contributing to Renderify.

Prerequisites

  • Node.js >= 22.0.0
  • pnpm >= 10.29.3

The preinstall script enforces pnpm usage. Running npm install or yarn install will error.

Setup

git clone https://github.com/unadlib/renderify.git
cd renderify
pnpm install

Monorepo Structure

renderify/
├── packages/
│   ├── ir/           # @renderify/ir — Intermediate representation
│   ├── runtime/      # @renderify/runtime — Execution engine
│   ├── security/     # @renderify/security — Security policies
│   ├── mcp-app/      # @renderify/mcp-app — Offline MCP Apps adapter
│   ├── core/         # @renderify/core — Orchestration facade
│   ├── llm/          # @renderify/llm — LLM providers
│   ├── renderify/    # renderify — Official SDK facade
│   └── cli/          # @renderify/cli — CLI and playground
├── tests/            # Unit, integration, e2e, and benchmark tests
├── examples/         # Browser and runtime examples
├── scripts/          # Build and CI helper scripts
└── docs/             # Documentation

Development Commands

# Install dependencies
pnpm install

# Start development mode (tsup watch)
pnpm dev

# Start the playground
pnpm playground

# Type checking
pnpm typecheck

# Linting (biome)
pnpm lint

# Auto-format
pnpm format

# Unit tests
pnpm unit

# Compatibility tests (JSPM module resolution)
pnpm compat

# End-to-end tests (Playwright-based)
pnpm e2e

# Benchmarks
pnpm bench

# All quality gates (typecheck + unit)
pnpm test

# Full test suite (typecheck + unit + e2e)
pnpm test:all

# Build all packages
pnpm build

# Validate package metadata
pnpm validate

# Clean build artifacts
pnpm clean

Package Dependencies

The dependency graph must be respected when making changes:

ir (no internal deps)
  ↑
security (depends on ir)
  ↑
runtime (depends on ir, security)
  ↑
core (depends on ir, security, runtime)
  ↑
llm (depends on core, ir)
  ↑
renderify (depends on core, ir, llm, runtime, security)

mcp-app (depends on ir, security, runtime, official MCP Apps SDK)

cli (depends on core, ir, llm, security, runtime)

Changes to @renderify/ir may affect all packages. Changes to renderify and @renderify/cli typically affect nothing downstream.

Changes to the MCP App plan surface, CSP, bridge lifecycle, or tool allowlist must update the feature spec and threat model and pass the official-bridge Chromium test without skipped cases.

Build System

Turbo

The monorepo uses Turborepo for task orchestration with caching. Task dependencies are defined in turbo.json:

  • build depends on all packages being valid
  • unit depends on typecheck
  • e2e depends on build (no caching)
  • bench depends on typecheck (no caching)

Tsup

tsup manages package builds:

  • Generates CommonJS and ESM outputs for each package entrypoint
  • Emits TypeScript declaration files alongside build outputs
  • Supports package-local watch mode used by pnpm dev
pnpm dev       # Run tsup watch across all packages
pnpm build     # Production build for all packages
pnpm validate  # Check package metadata conventions

TypeScript

TypeScript project references are used for incremental compilation:

  • tsconfig.base.json — shared compiler options
  • tsconfig.build.json — references all package tsconfigs
  • tsconfig.tests.json — test-specific configuration
  • Each package has its own tsconfig.json

Code Quality

Biome

Biome handles both linting and formatting:

pnpm lint          # Check for lint issues
pnpm format        # Auto-format all files
pnpm format:check  # Check formatting without writing

Configuration is in biome.jsonc.

Pre-commit Hooks

Husky runs lint-staged on pre-commit:

# Automatically runs on commit:
biome check --write --files-ignore-unknown=true --no-errors-on-unmatched

Conventional Commits

The project uses Conventional Commits via Commitizen:

pnpm commit  # Interactive commit message builder

Commit types: feat, fix, docs, chore, test, refactor, perf, ci, build, style.

Testing

Unit Tests

Tests use Node.js built-in test runner with tsx:

pnpm unit

Test files are in tests/*.test.ts. Key test areas:

File Coverage
core.test.ts RenderifyApp orchestration, streaming, abort
ir.test.ts Node types, validation, path utilities, hashing
runtime.test.ts Execution, modules, sandboxing, preflight
security.test.ts Policy profiles, tag blocking, source analysis
codegen.test.ts Plan generation, TSX extraction, streaming
config.test.ts Environment variables, defaults
llm.test.ts OpenAI, OpenAI Codex, Anthropic, Google, local providers
ui.test.ts HTML rendering, XSS protection
runtime-utils.test.ts Budget enforcement, template interpolation
runtime-jspm.test.ts Module resolution, compatibility

E2E Tests

End-to-end tests use Playwright for browser testing:

pnpm e2e

E2E tests cover:

  • CLI commands (render-plan, probe-plan, plan)
  • Playground API endpoints
  • LLM provider integration (with fake servers)
  • Hash deep-link loading in the browser

Benchmarks

pnpm bench

Benchmarks use tinybench and measure:

  • Code generation throughput
  • Plan execution performance
  • Compilation speed

Results are output as Markdown tables. In CI, JSON artifacts are uploaded for tracking.

Release Process

Renderify uses Changesets for versioning and publishing.

Adding a Changeset

When your PR changes package behavior or API:

pnpm changeset

This creates a markdown file in .changeset/ describing the change and affected packages. CI enforces that package changes include a changeset entry.

Version and Publish

# Apply version bumps and update changelogs
pnpm version-packages

# Publish to npm
pnpm release

Release automation publishes only from a valid SemVer tag such as v0.8.0. The tag version must match packages/renderify/package.json. The release workflow validates both values, runs formatting, lint, type, unit and compatibility checks, then validates package metadata and built entry points before publishing to npm with provenance.

CI Pipeline

The CI workflow (.github/workflows/ci.yml) runs on every push and PR:

  1. Lint — code quality checks
  2. Typecheck — TypeScript validation (Node 22 + 24 matrix)
  3. Unit tests — all test suites (Node 22 + 24 matrix)
  4. Compatibility tests — JSPM module resolution
  5. Build — package validation and build
  6. E2E tests — full integration tests
  7. Benchmarks — performance measurement with artifact upload

Concurrency is controlled per-branch to cancel in-progress runs on new pushes.

Adding a New Package

  1. Create the package directory in packages/
  2. Add package.json with proper entry points and dependencies
  3. Add tsconfig.json referencing tsconfig.base.json
  4. Add the reference to tsconfig.build.json
  5. Run pnpm dev to link the package
  6. Add tests in tests/

Guidelines

  • Keep packages focused — each package has a single responsibility
  • Test thoroughly — aim for comprehensive coverage of happy paths and edge cases
  • Validate security — any code that handles untrusted input must go through security checks
  • Use TypeScript strictly — enable strict mode, use explicit types for public APIs
  • Follow existing patterns — look at existing packages for conventions
  • Document public APIs — exported types and functions should be self-documenting
  • Avoid breaking changes — use changesets to communicate API changes