Skip to content

docs(build): define canonical build contract across scripts and CI #222

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shazzar00ni wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(build): define canonical build contract across scripts and CI #222

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 16 additions & 21 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,14 @@
name: CI
permissions:
contents: read

permissions:
contents: read

on:
push:
branches: [main]
pull_request:
branches: [main]

permissions:
contents: read

jobs:
lint:
name: Lint
Expand All @@ -20,46 +18,43 @@ jobs:
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
cache: npm
- run: npm ci
- run: npm run lint

- name: Super-Linter
- uses: super-linter/super-linter@v8.6.0

typecheck:
name: TypeScript Check

test:
name: Tests
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
cache: npm
- run: npm ci
- run: npx tsc --noEmit
- run: npm run test:run

test:
name: Tests
typecheck:
name: TypeScript Check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
cache: npm
- run: npm ci
- run: npm run test:run
- run: npm run typecheck

build:
name: Build
name: Build Contract
runs-on: ubuntu-latest
needs: [lint, typecheck, test]
needs: [lint, test, typecheck]
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
cache: npm
- run: npm ci
- run: npm run build
4 changes: 2 additions & 2 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This document provides guidelines for AI agents working in the DocuGen codebase.

```bash
npm run dev # Start development server on port 3000
npm run build # TypeScript check + Vite build (run before committing)
npm run build # Canonical build contract: typecheck + Vite production bundle
npm run preview # Preview production build locally
npm run lint # Run ESLint with strict rules (fails on warnings)
npm run test # Run Vitest in watch mode
Expand Down Expand Up @@ -190,4 +190,4 @@ Comprehensive documentation is available in the `docs/` directory:
- Default font: Inter (sans-serif), JetBrains Mono for code
- Dark mode default: `class="dark"` on `<html>` element
- Animations: Subtle and professional, no bouncing or spring effects
- Commit hook: `npm run lint` and `npm run build` run pre-commit
- Canonical verification command: `npm run ci:verify` (lint + tests + build contract)
12 changes: 11 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,17 @@ Open [http://localhost:3000](http://localhost:3000) in your browser.
npm run build
```

The built files will be in the `dist/` directory.
`npm run build` is the canonical build contract: it first runs TypeScript type-checking and then emits the Vite production bundle in `dist/`.

### Verification Contract

Run this before every commit and in CI:

```bash
npm run ci:verify
```

This command enforces the project contract in order: lint (`npm run lint`), unit tests (`npm run test:run`), and canonical build (`npm run build`).
Comment on lines +56 to +62

@greptile-apps greptile-apps Bot May 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 ci:verify is not what actually runs in the CI pipeline

The README says to use npm run ci:verify "in CI", but the CI workflow (ci.yml) runs each stage as a separate parallel job — lint, test, typecheck, and build — not through ci:verify. A contributor reading this could reasonably believe the GitHub Actions workflow uses ci:verify as its entry point, when it does not. Consider rephrasing to "run locally before pushing" or "to replicate the CI checks locally" to avoid the ambiguity.


### Preview Production Build

Expand Down
27 changes: 22 additions & 5 deletions docs/DEVELOPMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ Complete guide for setting up the DocuGen development environment, understanding
- [Development Workflow](#development-workflow)
- [Project Structure](#project-structure)
- [Available Scripts](#available-scripts)
- [Build Contract](#build-contract)
- [Code Style & Standards](#code-style--standards)
- [Git Workflow](#git-workflow)
- [Troubleshooting](#troubleshooting)
Expand Down Expand Up @@ -144,9 +145,7 @@ All tests should pass.
3. **Verify Changes**

```bash
npm run lint
npm run test:run
npm run build
npm run ci:verify
```

4. **Commit Changes**
Expand Down Expand Up @@ -287,14 +286,32 @@ Utility functions and hooks:
Before committing, always run:

```bash
npm run lint && npm run test:run && npm run build
npm run ci:verify
```

This ensures:

1. No linting errors
2. All tests pass
3. Production build succeeds
3. TypeScript type-checking passes
4. Production bundle succeeds

## Build Contract

DocuGen has one canonical build policy:

- `npm run build` must always perform **TypeScript type-checking first**, then run the **Vite production build**.
- `npm run ci:verify` is the canonical pre-commit and CI verification command.

Contract commands:

```bash
npm run typecheck # TypeScript only (no emitted files)
npm run build # Canonical build contract (typecheck + bundle)
npm run ci:verify # lint + tests + canonical build
```

Use `npm run build:bundle` only when you intentionally need to bypass type-checking for local diagnostics. Never use it in CI.

## Code Style & Standards

Expand Down
4 changes: 4 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,3 +97,7 @@ _Status: ✅ Complete | 🚧 In Progress | ⏳ Planned_
**Note**: DocuGen is currently in active development. See the [roadmap](../.planning/ROADMAP.md) for feature availability and upcoming phases.

For the high-level project overview, see the [root README](../README.md).

## Build Contract

Use `npm run ci:verify` as the single verification command. It runs `npm run lint`, `npm run test:run`, and `npm run build` (which itself runs typecheck + Vite build).
6 changes: 4 additions & 2 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"type": "module",
"scripts": {
"dev": "vite",
"build": "vite build",
"build": "npm run typecheck && vite build",
"preview": "vite preview",
"lint": "eslint . --max-warnings 0",
"lint:fix": "eslint . --max-warnings 0 --fix",
Expand All @@ -15,7 +15,9 @@
"test": "vitest",
"test:run": "vitest run",
"prepare": "husky",
"e2e": "playwright test"
"e2e": "playwright test",
"build:bundle": "vite build",
"ci:verify": "npm run lint && npm run test:run && npm run build"
},
"dependencies": {
"framer-motion": "^12.38.0",
Expand Down
Loading