From 54d1b0441239ea03dc6871074f4bb62b51f56799 Mon Sep 17 00:00:00 2001 From: Shannon Lockett Date: Thu, 14 May 2026 13:42:36 +0800 Subject: [PATCH] docs(build): define canonical build contract across scripts and CI --- .github/workflows/ci.yml | 37 ++++++++++++++++--------------------- AGENTS.md | 4 ++-- README.md | 12 +++++++++++- docs/DEVELOPMENT.md | 27 ++++++++++++++++++++++----- docs/README.md | 4 ++++ package.json | 6 ++++-- 6 files changed, 59 insertions(+), 31 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b94286a8..09ed3b81 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,9 +1,4 @@ name: CI -permissions: - contents: read - -permissions: - contents: read on: push: @@ -11,6 +6,9 @@ on: pull_request: branches: [main] +permissions: + contents: read + jobs: lint: name: Lint @@ -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 diff --git a/AGENTS.md b/AGENTS.md index 94ba4b82..5c1b0ec4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 @@ -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 `` 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) diff --git a/README.md b/README.md index 9c3f0c4c..742879e0 100644 --- a/README.md +++ b/README.md @@ -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`). ### Preview Production Build diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index d1e83ae9..a6231239 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -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) @@ -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** @@ -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 diff --git a/docs/README.md b/docs/README.md index c050f60e..96e5a2b0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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). diff --git a/package.json b/package.json index 05de492e..9e5d8e58 100644 --- a/package.json +++ b/package.json @@ -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", @@ -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",