@ivannikov-pro/ai-context-surgeon 1.0.0

package/strategy/jsdoc-guide.md

@@ -0,0 +1,596 @@
+<!-- FNH: Strategy — JSDoc standard for AI agents | SECTIONS: Density, Identifiers, Filtering, Barrel Files | DEPS: none -->
+
+# 📝 JSDoc for AI Agents — Not for Humans, but for Machines
+
+> Guide: how to comment code so that the AI spends minimum tokens on understanding | SECTIONS: Density Rules, First Line Rule, Context Tags, Deprecation | DEPS: none
+
+> [!IMPORTANT]
+> **AI AGENT FIRST Manifesto**: We do not optimize for human readability. Humans ideally will never look at this code. YOU (the AI Agent) write the code, and YOU read the code. The codebase is formatted exclusively to improve **your** "life". JSDoc exists to make parsing and reasoning easy for a machine interpreter, not to generate pretty HTML documentation for humans.
+
+---
+
+## How an Agent Reads a File
+
+```
+Step 1: list_dir("src/services/")
+  → Sees 15 file names
+  → Chooses a candidate by name
+
+Step 2: view_file("user.service.ts", lines=1-5)       ← EVERYTHING IS DECIDED HERE
+  → Reads FIRST LINES
+  → Decides: "is this the right file?" in 10-20 tokens
+  → If yes — reads further
+  → If no — moves to the next file
+
+Step 3: view_file("user.service.ts")
+  → Reads the entire file
+  → Looks for a specific function/class
+  → Each JSDoc block = context tokens
+```
+
+**Conclusion**: The first line of the file is the most valuable real estate in the repo.
+Every JSDoc block inside the file is a tradeoff between usefulness and cost.
+
+---
+
+## File Header: One Line, Maximum Meaning
+
+### Format
+
+```typescript
+/** <Category>: <Name> — <Purpose> | EXPORTS: <... > | ROUTES: <...> | DEPS: <...> | <Gotchas> */
+```
+
+### Anatomy (5 Mandatory Layers)
+
+As defined in `strategy/file-navigation-header.md`, a complete FNH uses 5 layers:
+
+```
+/** Service: UserService — CRUD + auth | EXPORTS: create, getById | DEPS: prisma, bcrypt | @throws Conflict */
+     ↑         ↑              ↑                   ↑                     ↑                      ↑
+   Category   Name         Purpose              Exports               Dependencies         Gotchas (Layer 5)
+```
+
+**Cost**: ~15–25 tokens. The agent immediately knows: type, purpose, dependencies.
+
+### Categories (Standardized)
+
+Use a **fixed vocabulary** of categories. The agent learns the pattern and predicts the content:
+
+| Category | Purpose | Example   |
+| --- | --- | --- | --- |
+| `Service` | Business logic | `/** Service: OrderService — create, validate, fulfill orders */` |
+| `Route` | HTTP endpoint | `/** Route: POST /api/v1/users — user registration + validation */` |
+| `Middleware` | Request pipeline | `/** Middleware: AuthGuard — JWT verify, sets req.user, 401 on fail */` |
+| `Controller` | Request handler | `/** Controller: PaymentController — Stripe webhook + checkout flow */` |
+| `Repository` | Data access | `/** Repository: UserRepo — Prisma CRUD for users table */` |
+| `Entity` | Domain model | `/\*\* Entity: Order — id, items[], status, total | immutable after PAID \*/` |
+| `Types` | Type definitions | `/** Types: User DTOs — CreateUserInput, UpdateUserInput, UserResponse */` |
+| `Utility` | Helper functions | `/** Utility: date — formatISO, parseRelative, diffDays */` |
+| `Config` | Configuration | `/** Config: database — Prisma client init, connection pool settings */` |
+| `Schema` | Validation | `/** Schema: user.validation — Zod schemas for user input endpoints */` |
+| `Hook` | React hook | `/** Hook: useAuth — login/logout/refresh, returns { user, isLoading } */` |
+| `Component` | React component | `/** Component: UserCard — displays user avatar + name + role badge */` |
+| `Test` | Test suite | `/** Test: UserService — unit tests for CRUD + edge cases */` |
+| `Migration` | DB migration | `/** Migration: 003 — add phone column to users, backfill from profiles */` |
+| `Script` | CLI/build script | `/** Script: seed — populates dev DB with 100 users + 500 orders */` |
+| `Constants` | Enums/constants | `/** Constants: http-status — SUCCESS, CREATED, BAD_REQUEST, ... */` |
+| `Factory` | Object creation | `/** Factory: createTestUser — generates User with random valid data */` |
+| `Adapter` | External integration | `/** Adapter: StripeClient — wraps Stripe SDK, handles retry + logging */` |
+| `Event` | Event definitions | `/** Event: OrderEvents — CREATED, PAID, SHIPPED, DELIVERED, CANCELLED */` |
+| `Guard` | Access control | `/** Guard: RoleGuard — checks req.user.role against allowed roles */` |
+
+### Examples — Good vs Bad
+
+```typescript
+// ✅ PERFECT: 1 line, everything is clear
+/** Service: UserService — CRUD + password hashing + email uniqueness check | deps: prisma, bcrypt */
+
+// ✅ GOOD: 1 line, sufficient
+/** Route: GET/POST /api/v1/orders — list orders (paginated) + create order */
+
+// 🟡 ACCEPTABLE: if 1 line cannot contain critical info
+/** Middleware: RateLimiter — sliding window, 100req/min per IP | MUTATES: req.rateLimit */
+
+// ❌ BAD: multiline JSDoc for the file — wasteful
+/**
+ * @fileoverview This module provides the UserService class which handles
+ * all user-related business logic including creation, updating, deletion,
+ * and authentication of user entities in the system.
+ *
+ * @module services/user
+ * @requires prisma
+ * @requires bcrypt
+ * @author John Doe
+ * @since 2024-01-15
+ * @version 2.3.1
+ */
+
+// ❌ TERRIBLE: empty/meaningless comment
+/** User service */
+/** This file contains the user service */
+/** @module user */
+```
+
+---
+
+## Functions and Methods: Only What TypeScript Doesn't Say
+
+### Golden Rule
+
+> **If the TypeScript signature fully describes the behavior — JSDoc is not needed.**
+> JSDoc is only needed for what is **not visible from types**: side effects, throws, mutations, non-obvious logic.
+
+### What TypeScript ALREADY Says (JSDoc = Noise)
+
+```typescript
+// ❌ JSDoc duplicates types — pure noise, +20 tokens for zero information
+/**
+ * Creates a new user
+ * @param {string} name - The user's name
+ * @param {string} email - The user's email
+ * @returns {Promise<User>} The created user
+ */
+async function createUser(name: string, email: string): Promise<User>;
+
+// ✅ Types speak for themselves — JSDoc is not needed
+async function createUser(name: string, email: string): Promise<User>;
+```
+
+### What TypeScript DOES NOT Say (JSDoc = Value)
+
+```typescript
+// ✅ THROWS — return type does not show errors
+/** @throws {ConflictError} if email already exists */
+async function createUser(input: CreateUserInput): Promise<User>;
+
+// ✅ SIDE EFFECTS — invisible in signature
+/** Sends welcome email after creation. Logs to audit trail. */
+async function createUser(input: CreateUserInput): Promise<User>;
+
+// ✅ MUTATES — argument mutation is not visible from types
+/** @mutates req.user — sets authenticated user from JWT payload */
+function authMiddleware(req: Request, res: Response, next: NextFunction): void;
+
+// ✅ NON-OBVIOUS LOGIC — algorithm is not obvious from name
+/** Uses bcrypt with 12 rounds. Compares timing-safe. */
+async function verifyPassword(plain: string, hash: string): Promise<boolean>;
+
+// ✅ CONSTRAINTS — business rules invisible from types
+/** Max 100 items per order. Throws if total > $10,000 without manager approval. */
+async function createOrder(items: OrderItem[]): Promise<Order>;
+
+// ✅ PERFORMANCE — critical information
+/** O(n²) — avoid for arrays > 1000 items. Use batchProcess() instead. */
+function processItems(items: Item[]): Result[];
+
+// ✅ DEPRECATION + MIGRATION PATH
+/** @deprecated Use UserServiceV2.create() — this ignores email verification */
+async function createUser(name: string, email: string): Promise<User>;
+```
+
+---
+
+## Priority JSDoc Tag Map
+
+### 🔴 Tier 1 — Critical (Agent MUST see)
+
+These tags communicate what **cannot be inferred from the code**:
+
+| Tag | Purpose | Tokens | Example |
+| --- | --- | --- | --- |
+| `@throws` | Which errors it throws | ~8–15 | `@throws {NotFoundError} if user doesn't exist` |
+| `@mutates` | What it mutates (non-standard but valuable) | ~5–10 | `@mutates req.user` |
+| `@sideeffect` | Side effects | ~8–15 | `Sends email. Writes audit log.` |
+| `@deprecated` | Do not use + alternative | ~10–15 | `@deprecated Use v2/createUser instead` |
+| `@important` / inline `⚠️` | Critical gotcha | ~10–20 | `⚠️ NOT idempotent — calling twice creates duplicate` |
+
+### 🟡 Tier 2 — Useful (Situational)
+
+| Tag | When needed | Tokens | Example |
+| --- | --- | --- | --- |
+| `@returns` | If return is non-obvious from type | ~5–10 | `@returns null if not found (not undefined)` |
+| `@example` | If API is counterintuitive | ~15–40 | Compact example |
+| `@see` | If there is a related function | ~5 | `@see UserService.update` |
+| `@default` | If default is not visible | ~3 | `@default 30` |
+| `@async` | (TS doesn't need it, JS without types does) | ~2 | — |
+
+### 🟢 Tier 3 — Noise (Do not write)
+
+| Tag | Why it's noise | Tokens Wasted |
+| --- | --- | --- |
+| `@param {type}` | TypeScript already knows types | ~10–30 per param |
+| `@returns {type}` | TypeScript already knows return type | ~5–10 |
+| `@type` | That is TypeScript's job | ~5 |
+| `@typedef` | Use `type`/`interface` | ~15–30 |
+| `@callback` | Use `type` | ~15–30 |
+| `@template` | Use generics | ~5–10 |
+| `@readonly` | Use `readonly` modifier | ~3 |
+| `@abstract` | Use `abstract` keyword | ~3 |
+| `@override` | Use `override` keyword | ~3 |
+| `@implements` | Obvious from class declaration | ~5 |
+
+### ⚫ Tier 4 — Harmful (Remove)
+
+| Tag | Why harmful | Tokens Wasted |
+| --- | --- | --- |
+| `@author` | Agent doesn't care who wrote it | ~5–10 |
+| `@since` | Agent doesn't care when added | ~5 |
+| `@version` | git blame is better | ~3 |
+| `@copyright` | Legally meaningless in code | ~10–20 |
+| `@license` | Already in LICENSE file | ~3–5 |
+| `@date` | git log is better | ~5 |
+| `@todo` | Use issues/tasks | ~5–15 |
+| `@hack` / `@fixme` | Use issues | ~5–15 |
+| `@fileoverview` | Replaced by 1-line `/**` header | ~30–80 |
+| `@module` | Obvious from filename | ~5 |
+| `@namespace` | Obvious from structure | ~5 |
+| `@memberof` | Obvious from class structure | ~5 |
+| `@classdesc` | Obvious from class name | ~10–20 |
+| `@constructs` | Obvious from `constructor` | ~5 |
+| `@fires` / `@emits` | Better inline `// emits: 'order.created'` | ~10 |
+| `@listens` | Better inline | ~10 |
+| `@augments` / `@extends` | Obvious from `extends` keyword | ~5 |
+
+---
+
+## One-Line Annotation Format
+
+For maximum density — use **inline format**, not block:
+
+```typescript
+// ✅ Inline — 1 line, ~15 tokens
+/** @throws {ConflictError} email exists | @mutates db.users */
+async function createUser(input: CreateUserInput): Promise<User> {
+
+// ❌ Block — 5 lines, ~40 tokens (same data, 3x more expensive)
+/**
+ * Creates a new user in the database.
+ * @throws {ConflictError} Thrown when email already exists
+ * @mutates db.users - Inserts a new row into the users table
+ */
+async function createUser(input: CreateUserInput): Promise<User> {
+```
+
+### Compact Method Annotations
+
+```typescript
+class UserService {
+  /** @throws NotFound */
+  async getById(id: string): Promise<User> { ... }
+
+  /** @throws Conflict(email) | sends welcome email */
+  async create(input: CreateUserInput): Promise<User> { ... }
+
+  /** @throws NotFound | partial update, merges with existing */
+  async update(id: string, patch: Partial<User>): Promise<User> { ... }
+
+  /** @throws NotFound | soft delete (sets deletedAt) */
+  async delete(id: string): Promise<void> { ... }
+
+  /** bcrypt 12 rounds | timing-safe compare */
+  async verifyPassword(plain: string, hashed: string): Promise<boolean> { ... }
+}
+```
+
+**5 methods, 5 JSDoc lines, ~60 tokens.** The agent knows all the gotchas.
+
+---
+
+## Scenarios: When to Write What
+
+### Scenario 1: Simple CRUD Function
+
+```typescript
+// Type tells everything. No JSDoc needed.
+async function getUsers(filter: UserFilter): Promise<User[]> {
+```
+
+### Scenario 2: Function with Hidden Behavior
+
+```typescript
+/** @throws NotFound | returns cached for 60s, invalidates on update */
+async function getUserById(id: string): Promise<User> {
+```
+
+### Scenario 3: Middleware with Mutation
+
+```typescript
+/** @mutates req.user, req.permissions | 401 if no token, 403 if insufficient role */
+function authorize(...roles: Role[]): Middleware {
+```
+
+### Scenario 4: Complex Function with Business Rules
+
+```typescript
+/** Max 50 items | free shipping > $100 | @throws OutOfStock, InvalidCoupon | sends confirmation email */
+async function checkout(cart: Cart, coupon?: string): Promise<Order> {
+```
+
+### Scenario 5: Utility without Surprises
+
+```typescript
+// Name and types tell everything. Zero JSDoc.
+function formatCurrency(amount: number, currency: Currency): string {
+```
+
+### Scenario 6: Re-export / Barrel File
+
+```typescript
+/** Barrel: public API for @project/core — entities, services, types */
+export { User, Order } from "./entities";
+export { UserService, OrderService } from "./services";
+export type { CreateUserInput, OrderDTO } from "./types";
+```
+
+### Scenario 7: Global Dependency Version Pegging
+
+AI Agents know global packages up to their training cutoff date. If an API has changed, the agent will hallucinate. Keep global dependencies annotated with versions (either in FNH `DEPS` or directly on the import).
+
+```typescript
+// ✅ Annotate directly on the import
+import { useState } from 'react'; // React 18
+import { ReentrancyGuard } from '@openzeppelin/contracts/security/ReentrancyGuard.sol'; // OpenZeppelin ^5.6.0
+
+// ✅ Or annotate in the FNH header
+/** Component: UserCard — renders profile | DEPS: react 18, framer-motion 11 */
+```
+
+---
+
+## JS (Without TypeScript) — Different Rules
+
+Without types, JSDoc takes on more work. But **it remains compact**:
+
+```javascript
+/** @param {string} id @returns {Promise<User|null>} @throws {DatabaseError} */
+async function getUserById(id) { ... }
+
+/** @param {{name: string, email: string}} input @returns {Promise<User>} @throws {ConflictError} email exists */
+async function createUser(input) { ... }
+```
+
+Rule: **In JS files, @param and @returns are needed** (they substitute types).
+But write them **on a single line**, not in a multi-line block.
+
+---
+
+## Quantitative Analysis
+
+### Typical File: 200 Lines of Code
+
+| JSDoc Style | JSDoc Lines | Tokens | Useful Information |
+| --- | --- | --- | --- |
+| ⚫ Enterprise Style (full) | 80 | ~400 | ~60 tokens really useful |
+| 🟡 Moderate | 25 | ~120 | ~80 tokens really useful |
+| ✅ **AI-Optimized** | 8 | ~50 | ~45 tokens really useful |
+| ❌ No documentation | 0 | 0 | Agent wastes ~200 tokens guessing |
+
+**AI-optimized style**: 8x fewer lines, 8x cheaper, same (or greater) usefulness.
+
+### JSDoc Utility Formula
+
+```
+Utility = (information_invisible_from_types) / (JSDoc_tokens)
+
+Enterprise: 60 / 400 = 0.15   ← 85% noise
+Moderate:   80 / 120 = 0.67   ← 33% noise
+AI-optim:   45 / 50  = 0.90   ← 10% noise  ← IDEAL
+```
+
+---
+
+## Checklist: Bring JSDoc to AI Optimum
+
+### File Level
+
+- [ ] Every file starts with a one-line `/** Category: Name — what it does */`
+- [ ] Category from standard vocabulary (Service, Route, Middleware, ...)
+- [ ] Contains key deps if non-obvious
+
+### Functions/Methods
+
+- [ ] No `@param {type}` in TypeScript files (types visible from signature)
+- [ ] No `@returns {type}` in TypeScript files
+- [ ] Has `@throws` for every thrown error
+- [ ] Has annotation for side effects (email, logging, cache)
+- [ ] Has annotation for mutations (req.user, state changes)
+- [ ] Everything on a single line where possible
+
+### Remove
+
+- [ ] No `@author`, `@since`, `@version`, `@copyright`, `@license`
+- [ ] No `@fileoverview` (replaced by 1-line header)
+- [ ] No `@module` (visible from filename)
+- [ ] No `@todo`, `@hack`, `@fixme` (move to issues)
+- [ ] No type duplication in JSDoc
+
+---
+
+## Full Example: File Before and After
+
+### ❌ BEFORE (Enterprise JSDoc) — 55 JSDoc Lines, ~280 tokens
+
+```typescript
+/**
+ * @fileoverview User Service Module
+ *
+ * This module provides the UserService class which handles all user-related
+ * business logic including creation, retrieval, updating, and deletion of
+ * user entities. It also manages password hashing and email verification.
+ *
+ * @module services/user
+ * @requires @prisma/client
+ * @requires bcrypt
+ * @author John Doe <john@example.com>
+ * @since 2024-01-15
+ * @version 2.3.1
+ * @copyright 2024 Acme Corp
+ * @license MIT
+ */
+
+import { PrismaClient } from '@prisma/client';
+import bcrypt from 'bcrypt';
+
+/**
+ * Service class for managing user entities.
+ * Provides CRUD operations and authentication helpers.
+ *
+ * @class UserService
+ * @classdesc Handles user business logic
+ */
+export class UserService {
+  /**
+   * Creates a new user in the database.
+   *
+   * @async
+   * @method create
+   * @memberof UserService
+   * @param {Object} input - The user creation input
+   * @param {string} input.name - The user's display name
+   * @param {string} input.email - The user's email address
+   * @param {string} input.password - The user's plain text password
+   * @returns {Promise<User>} The newly created user object
+   * @throws {ConflictError} When a user with the same email already exists
+   * @fires user.created
+   * @example
+   * const user = await userService.create({
+   *   name: 'John',
+   *   email: 'john@example.com',
+   *   password: 'secure123'
+   * });
+   */
+  async create(input: CreateUserInput): Promise<User> {
+```
+
+### ✅ AFTER (AI-Optimized) — 4 JSDoc Lines, ~40 tokens
+
+```typescript
+/** Service: UserService — CRUD + auth for users | deps: prisma, bcrypt */
+import { PrismaClient } from '@prisma/client';
+import bcrypt from 'bcrypt';
+
+export class UserService {
+  /** @throws Conflict(email) | hashes password (bcrypt 12) | sends welcome email */
+  async create(input: CreateUserInput): Promise<User> {
+```
+
+**Result: 7x fewer tokens, all critical information preserved.**
+Lost: author, date, copyright, example, parameter types — nothing the agent needs.
+
+---
+
+## Headers for Non-Code Files (MD, YAML, JSON, etc.)
+
+JSDoc syntax (`/** */`) only works in JS/TS. But the **concept** of one-line context is needed EVERYWHERE. Here is the format for each file type:
+
+### Markdown (.md)
+
+Use an HTML comment on line 1 (The First Line Rule), AND a `>` blockquote right after H1. They work in tandem:
+
+```markdown
+<!-- FNH: Package — domain entities | EXPORTS: User, Order | DEPS: @project/shared -->
+
+# @project/core
+
+> Package: Domain entities, services, and repositories | DEPS: @project/shared | ENTRY: src/index.ts
+```
+
+The agent reads the first line for rapid parsing, and the blockquote for deeper context.
+
+**Categories for Markdown files:**
+
+| Format | Purpose | Example     |
+| --- | --- | --- |
+| `> Package: ...` | Package README | `> Package: REST API — Express + Zod + Prisma middleware` |
+| `> Guide: ...` | Documentation/guide | `> Guide: API conventions — request/response format, error codes, pagination` |
+| `> Role: ...` | Role prompt | `> Role: Scout — read-only analysis, Gemini Flash, produces scout-report.md` |
+| `> Checklist: ...` | Checklist | `> Checklist: Phase 3 — restructuring steps with build checkpoints` |
+| `> Knowledge: ...` | Knowledge Item | `> Knowledge: Auth flow — JWT lifecycle, bcrypt rounds, role hierarchy` |
+| `> Skill: ...` | Skill desc (frontmatter) | `> Skill: annotate-jsdoc — AI-optimized JSDoc headers for source files` |
+| `> Architecture: ...` | Architectural doc | `> Architecture: migration plan — 12 steps, leaves-first, build checkpoints` |
+| `> Report: ...` | Report | `> Report: scout analysis — 47 files, 3 god-files, no AGENTS.md` |
+
+**Examples:**
+
+```markdown
+# API Conventions
+
+> Knowledge: API response format, error codes, and pagination patterns for all endpoints
+
+---
+
+# Phase 3: Restructuring
+
+> Checklist: 15 migration steps with build checkpoints | Role: Surgeon | Model: Gemini 3.1 Pro
+
+---
+
+# Scout Report: MyProject
+
+> Report: 847 files, 12 packages, 5 god-files, 0 READMEs, no AGENTS.md | estimated 25K tokens waste
+```
+
+### YAML (.yml, .yaml)
+
+Use a `#` comment on the first line:
+
+```yaml
+# Config: GitHub Actions CI — build + test + lint on push/PR | Node 18+
+name: CI
+on: [push, pull_request]
+```
+
+```yaml
+# Config: Turbo pipeline — build depends on ^build, test depends on build
+{ "$schema": "https://turbo.build/schema.json", "pipeline": { ... } }
+```
+
+### JSON (no comments — use name + description)
+
+JSON doesn't support comments. Therefore `name` + `description` in package.json **is** the header:
+
+```json
+{
+  "name": "@project/core",
+  "description": "Domain entities + business logic | deps: prisma, shared"
+}
+```
+
+For JSON configs without `description` (tsconfig, etc.) — the agent relies on the file name. That is fine.
+
+### Shell scripts (.sh)
+
+```bash
+#!/bin/bash
+# Tool: analyze-structure — count files, detect god-files, measure depth | POSIX, read-only
+```
+
+### Dockerfiles
+
+```dockerfile
+# Config: production Node.js image — multi-stage, node:18-alpine, distroless final
+FROM node:18-alpine AS builder
+```
+
+### Format Summary Table
+
+| File Type | Header Syntax | Example |
+| --- | --- | --- |
+| `.ts` / `.js` | `/** Category: Name — desc */` | `/** Service: UserService — CRUD + auth */` |
+| `.md` | `> Category: desc` (after H1) | `> Package: REST API — Express + Zod` |
+| `.yml` / `.yaml` | `# Category: desc` | `# Config: CI pipeline — build + test` |
+| `.json` | `"description": "..."` | `"description": "Domain logic"` |
+| `.sh` | `# Category: desc` | `# Tool: analyze — count files` |
+| `Dockerfile` | `# Category: desc` | `# Config: production image` |
+| `.env` | `# Category: desc` | `# Config: local env — API keys, DB URL` |
+| `.sql` | `-- Category: desc` | `-- Migration: add phone to users` |
+| `.py` | `"""Category: desc"""` | `"""Script: seed — 100 users"""` |
+
+### Rule: Every File in the Repo MUST Have a Context Header
+
+Regardless of format. If the agent opens a file and cannot understand WHAT it is from the first 2 lines — the file is not optimized.
+
+---
+
+_ai-context-surgeon / strategy | 2026-04-04_