From 99e781cd1048808fa94d17d13ee73044ba2472e6 Mon Sep 17 00:00:00 2001 From: Ignaciobrenas Date: Sat, 14 Nov 2026 23:08:29 +0100 Subject: [PATCH] feat(design): add DESIGN.md, agent design/QA skills, and staging PR workflow (#6) --- .claude/skills/commitflow-canvas-dag/SKILL.md | 19 ++++++ .../skills/commitflow-issue-workflow/SKILL.md | 27 ++++++++ .claude/skills/commitflow-qa-testing/SKILL.md | 20 ++++++ .claude/skills/commitflow-ui-design/SKILL.md | 19 ++++++ .github/workflows/ci.yml | 4 +- .github/workflows/staging-pr-check.yml | 23 +++++++ DESIGN.md | 61 +++++++++++++++++++ scripts/bootstrap-issues.sh | 29 +++++++++ 8 files changed, 200 insertions(+), 2 deletions(-) create mode 100644 .claude/skills/commitflow-canvas-dag/SKILL.md create mode 100644 .claude/skills/commitflow-issue-workflow/SKILL.md create mode 100644 .claude/skills/commitflow-qa-testing/SKILL.md create mode 100644 .claude/skills/commitflow-ui-design/SKILL.md create mode 100644 .github/workflows/staging-pr-check.yml create mode 100644 DESIGN.md create mode 100644 scripts/bootstrap-issues.sh diff --git a/.claude/skills/commitflow-canvas-dag/SKILL.md b/.claude/skills/commitflow-canvas-dag/SKILL.md new file mode 100644 index 0000000..4aedc4b --- /dev/null +++ b/.claude/skills/commitflow-canvas-dag/SKILL.md @@ -0,0 +1,19 @@ +--- +name: commitflow-canvas-dag +description: Guía técnica para diseñar y optimizar el motor topológico del DAG, renderizado de splines Bézier, virtual scrolling (< 150 nodos DOM), minimapa de ramas, drag-and-drop y Web Workers / OffscreenCanvas en CommitFlow. +--- + +# CommitFlow DAG & Virtual Scroll Skill + +Cuando trabajes en `src/graph/graphLayout.ts`, `src/graph/dagWorkerClient.ts` o el renderizado del grafo en `src/webview/main.ts`: +1. **Presupuesto de DOM y Rendimiento:** + - El scroll virtual (`updateVirtualWindow`) DEBE mantener `< 150` filas DOM montadas en el viewport en todo momento, reciclando elementos del pool cuando sea posible incluso con `100,000+` commits. + - Usa cálculos incrementales con `requestAnimationFrame` y evita reflows síncronos (`offsetHeight`/`getBoundingClientRect`) dentro de bucles por fila. +2. **Motor Topológico y Offload (`GraphLayout` & `DagWorkerEngine`):** + - Mantén el cálculo puro en funciones deterministas sin dependencias de `vscode` para poder ejecutarlas tanto en Node.js como dentro de un Web Worker. + - Al usar `OffscreenCanvas` (para el minimapa o carriles), provee siempre fallback limpio para entornos sin `OffscreenCanvas`. + - Soporta hashes SHA-1 (40 chars) y SHA-256 (64 chars), así como merges múltiples (octopus) y commits raíz huérfanos. +3. **Interactividad & A11y:** + - Todo nodo SVG/Canvas decorativo debe llevar `aria-hidden="true"`. + - Cada fila de commit debe mantener su `role="row"`, `aria-label` descriptivo con ramas/tags/padres y sincronización exacta con la navegación por teclado (`ArrowUp`, `ArrowDown`, `PageUp`, `PageDown`, `Home`, `End`). + - Las operaciones Drag-and-Drop sobre ramas/commits (reset, checkout, cherry-pick, rebase) DEBEN pedir confirmación explícita en modal seguro antes de mutar Git. diff --git a/.claude/skills/commitflow-issue-workflow/SKILL.md b/.claude/skills/commitflow-issue-workflow/SKILL.md new file mode 100644 index 0000000..11d31f0 --- /dev/null +++ b/.claude/skills/commitflow-issue-workflow/SKILL.md @@ -0,0 +1,27 @@ +--- +name: commitflow-issue-workflow +description: Flujo de trabajo GitFlow estricto de CommitFlow: main <- staging <- ramas por issue (feat|fix|design|test|perf/-), enlace con gh issue develop, Conventional Commits y PRs hacia staging. +--- + +# CommitFlow Issue & Branch Workflow Skill + +Sigue siempre este ciclo de vida GitFlow adaptado al repositorio `Ignaciobrenas/CommitFlow`: +1. **Jerarquía de Ramas:** + - `main`: Producción estable y releases del Marketplace. Solo recibe PRs desde `staging` (o `hotfix/*`). + - `staging`: Rama de integración continua. **Todas** las ramas de trabajo nacen de `staging` y regresan mediante PR hacia `staging`. + - Nomenclatura de ramas (compatible con `IssueBranchLinker`): + - `feat/-` (nuevas funcionalidades) + - `fix/-` (corrección de bugs) + - `design/-` (UI/UX, `DESIGN.md`, `SKILL.md`, accesibilidad) + - `test/-` (suites de tests, fuzzing, E2E, CI) + - `perf/-` (rendimiento, Web Workers, `OffscreenCanvas`, watcher) +2. **Crear rama enlazada al Issue:** + ```bash + git checkout staging && git pull origin staging + gh issue develop --base staging --name /- --checkout + ``` +3. **Commits Convencionales:** + - Usa `type(scope): description (#ID)`, por ejemplo: `feat(engine): add binary packfile reader in GitFsReader (#10)`. +4. **Pull Request hacia `staging`:** + - Incluye siempre `Refs #` en el cuerpo del PR hacia `staging` (y `Closes #` en el PR de release `staging` -> `main` para cierre automático). + - Antes de abrir o mergear el PR, ejecuta `npm run compile`, `npm test` y `npm run build`. diff --git a/.claude/skills/commitflow-qa-testing/SKILL.md b/.claude/skills/commitflow-qa-testing/SKILL.md new file mode 100644 index 0000000..6a2a48c --- /dev/null +++ b/.claude/skills/commitflow-qa-testing/SKILL.md @@ -0,0 +1,20 @@ +--- +name: commitflow-qa-testing +description: Guía de la pirámide completa de QA para CommitFlow: tests unitarios, property-based fuzzing, pruebas E2E del servidor MCP (stdio + HTTP/SSE), auditoría responsiva y WCAG 2.1 AA en Chromium headless, benchmarks de 50k commits y smoke tests E2E de extensión VS Code. +--- + +# CommitFlow QA & Testing Pyramid Skill + +Antes de dar por finalizada cualquier feature, bugfix o refactorización, valida las capas aplicables de la pirámide de calidad: +1. **Typecheck y Compilación (`npm run compile` & `npm run build`):** + - Cero errores de TypeScript estricto y bundle limpio en `dist/`. +2. **Tests Unitarios y de Integración (`npm test` -> `test/runTests.ts`):** + - Cubre lógica pura (`GraphLayout`, `GitFsReader`, `GitParser`, `SshConfigParser`, `IssueBranchLinker`, `ConventionalCommitsBuilder`, `IpcSchemaValidator`, `AdaptiveDebouncer`). +3. **Property-Based Fuzzing (`test/fuzzTests.ts`):** + - Ejecuta 1,000+ iteraciones deterministas inyectando `packed-refs` corruptos, reflogs truncados, buffers binarios aleatorios, alias SSH circulares, rutas Unicode y grafos complejos sin lanzar excepciones no controladas. +4. **E2E del Servidor MCP (`test/mcpE2eTests.ts`):** + - Prueba real contra repositorio temporal en disco: `stdio` (`dist/mcp.js`) y `CommitFlowHttpServer` (`/health`, `/sse`, `/mcp`), JSON-RPC 2.0 `initialize`, todas las tools y resources, scoping de repo, rechazo 401/403, rate-limiting 429 y log de auditoría. +5. **Webview Multi-Viewport, Temas y WCAG 2.1 AA (`scripts/verify-responsive.js`):** + - Verifica en Chromium/Edge headless los 4 breakpoints (`240px` Nano, `360px` Sidebar, `520px` Compact, `1100px` Wide Split) y temas (`dark`, `light`, `high-contrast`, `high-contrast-light`) con `0` overflows, `0` colisiones y `0` violaciones A11y. +6. **Benchmarks y Empaquetado (`scripts/benchmark-50k.js` & `npx vsce package`):** + - Verifica layout de 50,000 commits dentro del presupuesto de latencia/memoria y que el `.vsix` se empaquete sin errores. diff --git a/.claude/skills/commitflow-ui-design/SKILL.md b/.claude/skills/commitflow-ui-design/SKILL.md new file mode 100644 index 0000000..d10fa9c --- /dev/null +++ b/.claude/skills/commitflow-ui-design/SKILL.md @@ -0,0 +1,19 @@ +--- +name: commitflow-ui-design +description: Diseña e implementa interfaces Webview para CommitFlow siguiendo DESIGN.md, variables CSS de VS Code, Codicons, accesibilidad WCAG 2.1 AA y los 4 breakpoints responsivos multi-dock. Úsala al crear o modificar componentes UI, drawers, modales o temas. +--- + +# CommitFlow UI & Webview Design Skill + +Antes de escribir código UI en `src/graph/graphWebviewProvider.ts`, `src/webview/main.ts`, `src/webview/primitives.ts` o `src/webview/style.css`: +1. Lee `DESIGN.md` en la raíz del proyecto. +2. Verifica que **NO** se importe ni se referencie `@vscode/webview-ui-toolkit` (deprecado en enero de 2025). Utiliza tokens `--vscode-*` y los primitivos nativos en `src/webview/primitives.ts` (`CfButton`, `CfBadge`, `CfDrawer`, `CfTabs`, `CfToast`, `CfSkeleton`, `clampPopoverToViewport`). +3. **Checklist obligatorio por componente:** + - [ ] Funciona en temas VS Code: Dark+, Light+, High Contrast Dark (`.vscode-high-contrast`) y High Contrast Light (`.vscode-high-contrast-light`). + - [ ] Verificado en los 4 viewports multi-dock: Nano (`240px`), Sidebar Compact (`360px`), Compact (`520px`), Wide Split (`1100px`) y Bottom Panel (`1000x250px`). + - [ ] Usa `tabular-nums` (`font-variant-numeric: tabular-nums`) para hashes SHA, timestamps y contadores `+N/-N`. + - [ ] Incluye roles ARIA semánticos (`treegrid`, `row`, `gridcell` en el grafo; `role="dialog"` y `trapModalFocus` en modales) y foco visible (`outline: 1px solid var(--vscode-focusBorder)`). + - [ ] Cero `innerHTML` con datos de commits/issues/usuarios sin escapar (`escapeHtml`); CSP estricto con `nonce`. + - [ ] Popovers/drawers usan `clampPopoverToViewport` y se cierran al hacer clic fuera o pulsar `Escape`. + - [ ] Mensajes de estado vacío claros con CTA accionable y `CfSkeleton` loaders no bloqueantes. + - [ ] Respeta `@media (prefers-reduced-motion: reduce)`. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d3eb164..005a543 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,9 +2,9 @@ name: CI & Quality Gate on: push: - branches: [ main ] + branches: [ main, staging ] pull_request: - branches: [ main ] + branches: [ main, staging ] jobs: build-and-test: diff --git a/.github/workflows/staging-pr-check.yml b/.github/workflows/staging-pr-check.yml new file mode 100644 index 0000000..af69174 --- /dev/null +++ b/.github/workflows/staging-pr-check.yml @@ -0,0 +1,23 @@ +name: Staging PR & Issue Link Gate + +on: + pull_request: + branches: [ staging, main ] + +jobs: + verify-issue-link: + name: Verify Issue Reference in PR + runs-on: ubuntu-latest + steps: + - name: Check PR references an Issue + uses: actions/github-script@v7 + with: + script: | + const pr = context.payload.pull_request; + const text = `${pr.title}\n${pr.body || ''}`; + const hasIssueRef = /#\d+/.test(text); + if (!hasIssueRef) { + core.setFailed('El PR debe referenciar al menos un Issue (ej: "Refs #6" o "Closes #6").'); + } else { + core.info(`PR #${pr.number} references issue(s) cleanly.`); + } diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000..9aa1359 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,61 @@ +# CommitFlow Design System (DESIGN.md) + +## 1. Visual Theme & Atmosphere +- **Philosophy:** **"Precision Developer Telemetry"**. High information density without visual noise; native VS Code integration that respects 100% of the user's active IDE theme (Light, Dark, High Contrast Dark, High Contrast Light) while delivering vivid semantic identity across the commit DAG via curated chromatic lane palettes. +- **Surface Hierarchy:** Strictly layered via native VS Code tokens with sensible fallbacks: + - Primary Canvas / Editor Surface: `var(--vscode-editor-background)` (`--bg-primary`) + - Secondary Chrome / Sidebar / Header: `var(--vscode-sideBar-background)` (`--bg-secondary`) + - Elevated / Tabs / Popovers / Modals: `var(--vscode-editorGroupHeader-tabsBackground)` / `var(--vscode-panel-background)` (`--bg-tertiary`) + - Interactive States: `var(--vscode-list-hoverBackground)` (`--bg-hover`), `var(--vscode-list-activeSelectionBackground)` (`--bg-active`) + - Borders & Focus: `var(--vscode-widget-border)` / `var(--vscode-panel-border)` (`--border-subtle`), `var(--vscode-focusBorder)` (`--focus-ring`) + +## 2. Color Palette & Tokens +- **Base IDE Integration:** + - Foreground: `var(--vscode-editor-foreground)` / `var(--vscode-foreground)` + - Secondary Muted Text: `var(--vscode-descriptionForeground)` + - Focus Ring: `var(--vscode-focusBorder)` (must always remain visible on keyboard focus) + - High Contrast Borders: `var(--vscode-contrastBorder)`, `var(--vscode-contrastActiveBorder)` +- **Semantic Status Tokens:** + - `Success / Bisect Good / Valid Sig / Ready PR`: `#10b981` (`--accent-emerald` in Dark) / `#1a7f37` (Light) + - `Danger / Bisect Bad / Conflict / Drop`: `#ef4444` / `#f43f5e` (`--accent-rose` in Dark) / `#cf222e` (Light) + - `Warning / Untrusted / Dirty / Pending`: `#f59e0b` (`--accent-amber` in Dark) / `#9a6700` (Light) + - `Probe / Active Bisect / Primary Accent`: `#38bdf8` / `#06b6d4` (`--accent-cyan` in Dark) / `#0969da` (Light) + - `MCP / AI Studio / Rebase Accent`: `#8b5cf6` (`--accent-violet` in Dark) / `#8250df` (Light) +- **DAG Chromatic Lane Palettes (`GraphLayout.THEME_LANE_COLORS`):** + - Supported presets: `auto`, `dark`, `light`, `cyberpunk`, `dracula`, `github`, `neon-pink`, `neon-green`, `neon-blue`. + - Adjacent lanes must maintain clear perceptual color separation. In High Contrast themes (`vscode-high-contrast`, `vscode-high-contrast-light`), borders and focus outlines override subtle alpha fills. + +## 3. Typography & Rhythm +- **UI Font:** `var(--vscode-font-family)` with adaptive sizing (`--font-size-base: 12px`, `--font-size-sm: 11px`, `--font-size-xs: 10px`). +- **Monospace Telemetry Font:** `var(--vscode-editor-font-family)` with mandatory `font-variant-numeric: tabular-nums` (`class="tabular-nums"`) for: + - Commit SHAs (`shortHash`, full 40/64-char SHA) + - Diff line deltas (`+N / -M`) + - Relative/absolute timestamps, branch pill counters, and stat bar counters + - File paths and bisect step estimators +- **Spacing & Radii:** `--radius-xs: 4px`, `--radius-sm: 6px`, `--radius-md: 8px`, `--radius-lg: 10px`, `--radius-xl: 12px`, `--radius-full: 9999px`. +- **Density Tiers (`commitflow.graph.density`):** `compact` (`22px` row height), `comfortable` (`26px`), `spacious` (`32px`). + +## 4. Adaptive Multi-Dock Breakpoints +CommitFlow operates seamlessly across left/right Activity Bar sidebars, bottom terminal panel, and full Editor panels using container-aware layout classes: +- **Nano (`<= 260px` / `.layout-nano`):** + - Navigation tabs collapse to icon-only buttons with native `title` + `aria-label` tooltips. + - Secondary metadata (author email, timestamps, extra stats dividers) are hidden cleanly. + - Minimum touch/click target size `28x28px`. +- **Sidebar Compact (`261px - 440px` / `.layout-sidebar-compact`):** + - Single-column stacked layout for DAG rows and cards. + - Inspector drawer renders as a full-width overlay drawer clamped cleanly inside the viewport. +- **Compact (`441px - 600px` / `.layout-width-compact`):** + - Compact branch pills, abbreviated badges, wrapped flex toolbars with zero horizontal overflow. +- **Wide / Bottom Panel (`> 600px`):** + - Dual-pane split view (DAG + Minimap on the left, Commit/PR Inspector Drawer on the right) or horizontal bottom-dock layout (`>= 540px` width and `<= 380px` height -> `.auto-detected-bottom` / `.layout-height-short`). + +## 5. Component Rules (Zero Deprecated Toolkits) +1. **ZERO `@vscode/webview-ui-toolkit`:** Officially deprecated and archived in January 2025. Never import or depend on it. +2. **Native UI Primitives (`src/webview/primitives.ts`):** All new UI elements use CommitFlow's lightweight zero-dependency primitives (`CfButton`, `CfBadge`, `CfDrawer`, `CfTabs`, `CfToast`, `CfSkeleton`) built exclusively with `--vscode-*` CSS variables and `@vscode/codicons`. +3. **Icons:** Use `@vscode/codicons` (``) or accessible inline SVGs marked with `aria-hidden="true"`. +4. **Viewport Clamping & Popover Dismissal:** All popovers, tooltips, context menus, and drawers must clamp against viewport edges (`clampPopoverToViewport`) and dismiss on outside click or `Escape`. +5. **Motion & Reduced Motion:** Use `--ease-spring` / `--duration-fast` for crisp transitions, and strictly disable animations, spinners, and pulse keyframes inside `@media (prefers-reduced-motion: reduce)`. +6. **Security & CSP:** Enforce `default-src 'none'` with cryptographic `nonce` per load; never inject untrusted user or commit strings via raw `innerHTML` without HTML escaping. +7. **Accessibility (WCAG 2.1 AA):** + - Graph container uses `role="treegrid"` with `role="row"` and `role="gridcell"`, descriptive `aria-label` per commit, and roving `tabindex` (`ArrowUp`, `ArrowDown`, `PageUp`, `PageDown`, `Home`, `End`). + - All modals trap `Tab`/`Shift+Tab` focus (`trapModalFocus`) and restore focus on close. diff --git a/scripts/bootstrap-issues.sh b/scripts/bootstrap-issues.sh new file mode 100644 index 0000000..db868c1 --- /dev/null +++ b/scripts/bootstrap-issues.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +set -euo pipefail + +# 1. Asegurar main actualizada y crear staging (si no existe) +git checkout main +git pull origin main +if ! git show-ref --verify --quiet refs/heads/staging; then + git checkout -b staging + git push -u origin staging +else + git checkout staging + git pull origin staging +fi + +# 2. Crear etiquetas organizadas en el repositorio +gh label create "epic:design" --color "ec4899" --description "Design system, SKILLS, UI/UX y responsive" --force +gh label create "epic:engine" --color "0284c7" --description "GitFsReader offline, performance y DAG" --force +gh label create "epic:features" --color "10b981" --description "Funcionalidades Git, Providers y Conflict Studio" --force +gh label create "epic:security" --color "ef4444" --description "Seguridad MCP, CSP y validacion IPC" --force +gh label create "epic:testing" --color "8b5cf6" --description "Playwright, Fuzzing, A11y, MCP E2E y CI" --force + +create_issue() { + local title="$1" + local label="$2" + local body="$3" + gh issue create --title "$title" --label "$label" --body "$body" +} + +echo "Usa create_issue \"\" \"\" \"\" para crear nuevos issues enlazables a staging."