@aion0/forge 0.5.48 → 0.5.49

package/lib/help-docs/14-migration.md

@@ -1,154 +0,0 @@
-# API Migration Cockpit
-
-Parity-test API endpoints between a legacy module and a new module during a large migration. Designed for projects where the same paths must be served identically by two different processes (e.g. legacy on `:8080`, new web-server on `:9090`).
-
-## When to use
-
-- You're moving REST endpoints from one Spring/Java module to another and the new module **must keep the exact same paths** (no rewrites allowed in the legacy code).
-- You have lots of endpoints (hundreds) and need batch testing + AI-assisted fix.
-- You already track migration status in markdown — Forge reads your docs instead of re-scanning the source.
-
-## Quick start
-
-1. Open the project, click the **🚚 Migration** tab.
-2. Click **Config** and set:
-   - `Legacy base URL` (e.g. `http://localhost:8080`)
-   - `New base URL` (e.g. `http://localhost:9090`)
-   - `Per-controller docs dir` (default `docs/migration`)
-   - `History fallback` (default `docs/lead/migration-history.md`)
-3. Click **Discover from docs** — Forge parses your existing migration docs.
-4. Click **Run all** to fire each endpoint at both base URLs in parallel and compare JSON.
-5. Failures show up in the right sidebar, clustered by error type.
-6. Select rows or a cluster → **AI fix → task** (background) or **AI fix → inject** (paste prompt into a tmux session).
-
-## Discovery
-
-Two strategies, controlled by `endpointSource.openApiSpec` in config:
-
-### Strategy A — OpenAPI as primary source (recommended)
-
-When `openApiSpec` points at an OpenAPI 3 JSON (e.g. `docs/fnac-rest-schema-7.6.json`), Forge:
-
-1. Loads every operation in the spec — this is the full surface, including endpoints not yet covered by your migration docs.
-2. Annotates each endpoint with status (`migrated` / `stubbed` / `pending`) by cross-referencing your `docs/migration/<X>.java.md` per-controller files (matched by exact `METHOD path`) and `docs/lead/migration-history.md` (matched by controller/tag name).
-3. Resolves `$ref` chains so each operation has an inline response schema you can validate against.
-
-Endpoints not covered by any doc are flagged `pending` so you can see what's not yet planned.
-
-### Strategy B — Doc-only discovery (fallback)
-
-If no `openApiSpec` is configured, Forge falls back to parsing `docs/migration/*.md` tables (Migrated / Stubbed sections) plus `migration-history.md` inline `METHOD /path` mentions.
-
-### Primary parser — `docs/migration/<File>.java.md`
-
-Looks for sections marked **Migrated** / **Stubbed** / **URL Parity Only** with markdown tables containing `` `METHOD` `path` `` cells:
-
-```
-### ✅ Migrated (11 endpoints — DB-backed)
-
-| HTTP path | Method | Service method | Notes |
-|---|---|---|---|
-| `GET /control/{id}` | `getById` | `getById(id)` | Single task by PK |
-
-### 🚫 Stubbed (12 endpoints — return 501 Not Implemented)
-
-| HTTP path | Method | Runtime dependency |
-|---|---|---|
-| `POST /control/macaddress` | `controlByMacForm` | … |
-```
-
-Stubbed endpoints get `expectedHttpStatus: 501` so they pass when the new side correctly returns 501.
-
-### Fallback parser — `docs/lead/migration-history.md`
-
-For controllers without a per-file doc, Forge scans entries shaped like:
-
-```
-- [x] `MFAController.java` — **migrated 2026-04-23** (… `GET /mfa/foo` …)
-- [x] `Foo.java` — **skip 2026-04-23**: out of scope
-```
-
-`skip` and `defer` entries are excluded. Inline `` `METHOD /path` `` mentions in the description become endpoints; otherwise a placeholder row is added with a note.
-
-## Running
-
-| Action | Behavior |
-|---|---|
-| **Run** (per row) | Fires both sides once, expands diff inline |
-| **Run selected** | Batch-run checked rows (SSE progress) |
-| **Run all** | Batch-run every endpoint |
-
-The runner fires `legacy` and `new` in parallel for each endpoint, with concurrency=4 across endpoints. Path placeholders like `{id}` are filled from `pathSubstitutions` in config.
-
-### Diff modes (`config.diffMode`)
-
-| Mode | Hits legacy? | Comparison |
-|---|---|---|
-| `shape` (default) | no | Validates new response against the OpenAPI schema (subset semantics — extra fields OK, missing required fail, wrong types fail, enum violations fail). Use this when legacy is unreachable. |
-| `exact` | yes | Original behavior — fires both sides in parallel, deep-equal JSON comparison with array sort + ignore-paths. |
-| `both` | yes | Both deep-equal AND schema validation. |
-
-### Match outcomes
-
-| Match | Meaning |
-|---|---|
-| `pass` | Comparison succeeded for the configured mode |
-| `stub-ok` | Endpoint marked stubbed; new side returned 501 as expected |
-| `fail` | Schema violation, status mismatch, or JSON diff |
-| `error` | Unreachable or timed out |
-
-Top-level arrays are sorted before exact comparison so order alone won't fail. Schema mode samples the first 10 array items to keep reports tractable.
-
-## Config (`<project>/.forge/migration/config.yaml`)
-
-```yaml
-legacy:
-  baseUrl: http://localhost:8080
-next:
-  baseUrl: http://localhost:9090
-auth:
-  mode: skip            # skip / bearer / basic
-  tokenEnv: FORTINAC_TOKEN
-diffMode: shape         # shape / exact / both
-ignorePaths:            # JSONPath patterns to skip during diff/validation
-  - $.timestamp
-  - $.requestId
-healthCheck:
-  legacyTimeout: 2000
-  newTimeout: 2000
-  skipUnhealthy: true
-clusterMode: simple     # simple / ai
-endpointSource:
-  type: mixed
-  openApiSpec: docs/fnac-rest-schema-7.6.json   # primary source when set
-  primary: docs/migration                        # used to annotate status
-  fallback: docs/lead/migration-history.md       # used to annotate status
-pathSubstitutions:
-  id: "1"
-  ip: "127.0.0.1"
-  mac: "00:00:00:00:00:00"
-```
-
-## Storage
-
-```
-<project>/.forge/migration/
-├── config.yaml
-├── endpoints.json            # discovered endpoints
-├── runs/<timestamp>.json     # one file per batch run
-└── failures/current.json     # latest failures (used by clustering)
-```
-
-## AI fix
-
-After a batch run, failure clusters appear in the sidebar grouped by error type (`http-status-mismatch`, `json-diff`, `legacy-unreachable`, …) with sub-counts per controller.
-
-- **AI fix → task** spawns a Forge background task in the project; the task receives a structured prompt naming the failing endpoints + diffs and is told *not* to modify legacy code.
-- **AI fix → inject** prompts for a tmux session name and pastes the prompt + Enter into a running Claude Code session. Use this when you have a Claude terminal already open and want it to take over the fix.
-
-## Tips
-
-- The cockpit assumes both base URLs are reachable and serve identical paths. If the new module isn't running yet, every row will show `error` — that's expected.
-- Stubbed endpoints intentionally return 501; they're still listed so you can audit URL parity.
-- The diff output truncates each side to 4 KB and shows up to 50 jsonpath diffs per endpoint. Run output JSON files contain the full payload.
-- Use the **Search** box to scope to one controller, then **Select all visible** + **Run selected** to focus on a single migration unit.

package/lib/migration/differ.ts

@@ -1,193 +0,0 @@
-// Strict JSON deep-equal with a JSONPath-style ignore list.
-// Supported ignore syntax: $.field, $.nested.field, $.array[*].field
-
-import type { DiffEntry } from './types';
-
-function compileIgnore(patterns: string[]): RegExp[] {
-  return patterns.map(p => {
-    const body = p.startsWith('$') ? p.slice(1) : p;
-    const escaped = body
-      .replace(/\./g, '\\.')
-      .replace(/\[\*\]/g, '\\[\\d+\\]')
-      .replace(/\[(\d+)\]/g, '\\[$1\\]');
-    return new RegExp(`^${escaped}$`);
-  });
-}
-
-function isIgnored(path: string, compiled: RegExp[]): boolean {
-  return compiled.some(re => re.test(path));
-}
-
-function normalizeArray(arr: any[]): any[] {
-  // Sort by stable-stringify so order doesn't matter for top-level array results.
-  return [...arr].sort((a, b) => stableStringify(a).localeCompare(stableStringify(b)));
-}
-
-function stableStringify(v: any): string {
-  if (v === null || typeof v !== 'object') return JSON.stringify(v);
-  if (Array.isArray(v)) return '[' + v.map(stableStringify).join(',') + ']';
-  const keys = Object.keys(v).sort();
-  return '{' + keys.map(k => JSON.stringify(k) + ':' + stableStringify(v[k])).join(',') + '}';
-}
-
-export function diff(legacy: any, next: any, ignorePaths: string[] = [], opts: { sortArrays?: boolean } = {}): DiffEntry[] {
-  const compiled = compileIgnore(ignorePaths);
-  const out: DiffEntry[] = [];
-  walk(legacy, next, '$', compiled, out, !!opts.sortArrays);
-  return out;
-}
-
-function walk(a: any, b: any, path: string, compiled: RegExp[], out: DiffEntry[], sortArrays: boolean) {
-  if (isIgnored(path, compiled)) return;
-
-  const ta = a === null ? 'null' : Array.isArray(a) ? 'array' : typeof a;
-  const tb = b === null ? 'null' : Array.isArray(b) ? 'array' : typeof b;
-
-  if (ta !== tb) {
-    out.push({ jsonPath: path, legacy: a, next: b, reason: 'type-mismatch' });
-    return;
-  }
-
-  if (ta === 'array') {
-    let aa = a, bb = b;
-    if (sortArrays) { aa = normalizeArray(a); bb = normalizeArray(b); }
-    const len = Math.max(aa.length, bb.length);
-    for (let i = 0; i < len; i++) {
-      const cp = `${path}[${i}]`;
-      if (i >= aa.length) out.push({ jsonPath: cp, legacy: undefined, next: bb[i], reason: 'missing-in-legacy' });
-      else if (i >= bb.length) out.push({ jsonPath: cp, legacy: aa[i], next: undefined, reason: 'missing-in-next' });
-      else walk(aa[i], bb[i], cp, compiled, out, sortArrays);
-    }
-    return;
-  }
-
-  if (ta === 'object') {
-    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
-    for (const k of keys) {
-      const cp = `${path}.${k}`;
-      if (!(k in a)) out.push({ jsonPath: cp, legacy: undefined, next: b[k], reason: 'missing-in-legacy' });
-      else if (!(k in b)) out.push({ jsonPath: cp, legacy: a[k], next: undefined, reason: 'missing-in-next' });
-      else walk(a[k], b[k], cp, compiled, out, sortArrays);
-    }
-    return;
-  }
-
-  if (a !== b) out.push({ jsonPath: path, legacy: a, next: b, reason: 'value' });
-}
-
-// ── OpenAPI schema validator (subset shape mode) ─────────
-// Validates `value` against an inlined OpenAPI 3 schema.
-// Subset semantics: extra fields in `value` are OK; missing required fields fail.
-
-export interface SchemaViolation {
-  jsonPath: string;
-  expected: string;
-  actual: string;
-  reason: 'missing-required' | 'type-mismatch' | 'enum-mismatch' | 'unresolved';
-  detail?: any;
-}
-
-export function validateAgainstSchema(value: any, schema: any, path = '$', out: SchemaViolation[] = [], ignore?: RegExp[]): SchemaViolation[] {
-  if (!schema || typeof schema !== 'object') return out;
-  if (schema.__cycle || schema.__unresolved) return out;
-  if (ignore && ignore.some(re => re.test(path))) return out;
-
-  // oneOf / anyOf — pass if any branch validates with no violations.
-  if (Array.isArray(schema.oneOf) || Array.isArray(schema.anyOf)) {
-    const branches = schema.oneOf || schema.anyOf;
-    let bestErrors: SchemaViolation[] | null = null;
-    for (const branch of branches) {
-      const errs: SchemaViolation[] = [];
-      validateAgainstSchema(value, branch, path, errs, ignore);
-      if (errs.length === 0) return out;
-      if (!bestErrors || errs.length < bestErrors.length) bestErrors = errs;
-    }
-    if (bestErrors) out.push(...bestErrors);
-    return out;
-  }
-  if (Array.isArray(schema.allOf)) {
-    for (const branch of schema.allOf) validateAgainstSchema(value, branch, path, out, ignore);
-    return out;
-  }
-
-  const t = schema.type;
-  const actualType = jsType(value);
-
-  // Nullable check
-  if (value === null) {
-    if (schema.nullable === true) return out;
-    if (Array.isArray(t) && t.includes('null')) return out;
-    if (t === 'null') return out;
-    out.push({ jsonPath: path, expected: String(t || 'non-null'), actual: 'null', reason: 'type-mismatch' });
-    return out;
-  }
-
-  if (t === 'object' || (t === undefined && schema.properties)) {
-    if (actualType !== 'object') {
-      out.push({ jsonPath: path, expected: 'object', actual: actualType, reason: 'type-mismatch' });
-      return out;
-    }
-    const required: string[] = schema.required || [];
-    for (const r of required) {
-      if (!(r in value)) {
-        out.push({ jsonPath: `${path}.${r}`, expected: 'required', actual: 'missing', reason: 'missing-required' });
-      }
-    }
-    const props = schema.properties || {};
-    for (const [k, sub] of Object.entries(props)) {
-      if (k in value) validateAgainstSchema(value[k], sub, `${path}.${k}`, out, ignore);
-    }
-    return out;
-  }
-
-  if (t === 'array') {
-    if (actualType !== 'array') {
-      out.push({ jsonPath: path, expected: 'array', actual: actualType, reason: 'type-mismatch' });
-      return out;
-    }
-    const item = schema.items;
-    if (item && value.length > 0) {
-      // Validate first 10 items only — keeps reports tractable for large arrays.
-      const sample = value.slice(0, 10);
-      for (let i = 0; i < sample.length; i++) {
-        validateAgainstSchema(sample[i], item, `${path}[${i}]`, out, ignore);
-      }
-    }
-    return out;
-  }
-
-  if (t === 'integer' || t === 'number') {
-    if (actualType !== 'number') {
-      out.push({ jsonPath: path, expected: String(t), actual: actualType, reason: 'type-mismatch' });
-    }
-    return out;
-  }
-
-  if (t === 'string') {
-    if (actualType !== 'string') {
-      out.push({ jsonPath: path, expected: 'string', actual: actualType, reason: 'type-mismatch' });
-      return out;
-    }
-    if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
-      out.push({ jsonPath: path, expected: `enum ${JSON.stringify(schema.enum)}`, actual: JSON.stringify(value), reason: 'enum-mismatch' });
-    }
-    return out;
-  }
-
-  if (t === 'boolean') {
-    if (actualType !== 'boolean') {
-      out.push({ jsonPath: path, expected: 'boolean', actual: actualType, reason: 'type-mismatch' });
-    }
-    return out;
-  }
-
-  // No type constraint → pass.
-  return out;
-}
-
-function jsType(v: any): string {
-  if (v === null) return 'null';
-  if (Array.isArray(v)) return 'array';
-  return typeof v;
-}
-