iterate-plugin 3.14.0 → 3.16.0

package/src/client/run-compare.ts

@@ -0,0 +1,213 @@
+/**
+ * src/client/run-compare.ts — cross-session run comparison (the observatory F2 tab).
+ *
+ * The F2 convergence tab compares ROUNDS *within* one session, but comparing
+ * two ITERATIONS of the same project (before / after a refactor) used to be a
+ * manual chore: export JSON for each run, open both files, line up the columns.
+ * This module turns that into a first-class interaction. The current run is
+ * reduced to a compact, serializable summary and saved to localStorage as the
+ * comparison baseline; any later run can then be compared against it side by
+ * side, with a per-metric delta and a directional "better / worse" tint.
+ *
+ * Design constraints (mirrors `i18n.ts` / `session-cache.ts`):
+ *   - **Pure / dependency-free**: no React, no DOM, no Chinese literals (the
+ *     bilingual labels live next to `t()` in index.ts, which is the layer the
+ *     i18n dictionary-contract test scans). The summary builder and the
+ *     compare reducer are unit-testable on their own.
+ *   - **Versioned**: the stored payload carries a `version` so a future schema
+ *     change can migrate or reject stale baselines instead of mis-reading them.
+ *   - **Never fabricated**: every field is derived from real manifest fields
+ *     with defensive optional chaining; a run with no findings simply reads 0.
+ */
+
+/** Current schema version of the persisted baseline. */
+export const RUN_BASELINE_VERSION = 1
+
+/** localStorage key holding the single comparison baseline (per browser). */
+export const RUN_BASELINE_STORAGE_KEY = 'iterate.run-baseline'
+
+/**
+ * A compact, serializable summary of one run — everything the side-by-side
+ * comparison needs, and nothing the client cannot already see in the manifest.
+ */
+export interface RunBaseline {
+  version: 1
+  /** ISO timestamp of when this baseline was saved (NOT the run end time). */
+  savedAt: string
+  /** Project root the run was anchored to (informational). */
+  project?: string
+  /** 'normal' | 'dry-run' — the mode that produced the run. */
+  mode?: string
+  /** Number of review rounds captured. */
+  rounds: number
+  /** Total findings raised across the run. */
+  findings: number
+  /** critical + high findings (the "must fix" surface). */
+  criticalHigh: number
+  /** Fixes that succeeded. */
+  fixed: number
+  /** Fixes that failed (rolled back / validation-rejected). */
+  failedFixes: number
+  /** Fraction of validation command runs that passed, 0-100, or null if none ran. */
+  validationPassRate: number | null
+  /** Number of validation command runs. */
+  validationTotal: number
+  /** 'pass' | 'fail' | null — the quality gate verdict, when it was computed. */
+  qualityGateStatus: string | null
+  /** Quality gate overall score (0-100) when computed. */
+  qualityGateScore: number | null
+  /** Why the run ended: converged / max_rounds_reached / aborted_by_validation. */
+  stoppedReason: string | null
+  /** Findings per round (the convergence series), for a side-by-side trend. */
+  convergence: number[]
+}
+
+/** The manifest-shaped inputs the summary builder reads (defensively). */
+export interface RunBaselineInput {
+  project?: string
+  mode?: string
+  convergence?: number[]
+  findings?: Array<{ severity?: string }>
+  fixes?: Array<{ success?: boolean }>
+  validations?: Array<{ allowed?: boolean }>
+  qualityGateStatus?: string | null
+  qualityGateScore?: number | null
+  stoppedReason?: string | null
+}
+
+/**
+ * Reduce a run manifest (plus the session-scanned quality gate) to a compact,
+ * comparison-ready summary. Pure: `savedAt` is injected by the caller so this
+ * stays deterministic and testable.
+ */
+export function buildRunBaseline(input: RunBaselineInput, savedAt: string): RunBaseline {
+  const convergence = Array.isArray(input.convergence) ? input.convergence : []
+  // Only object entries count — a null / primitive in a malformed manifest
+  // must never be read as a finding / fix / validation (and skew the rate).
+  const findings = (Array.isArray(input.findings) ? input.findings : []).filter(
+    (f): f is { severity?: string } => typeof f === 'object' && f !== null,
+  )
+  const fixes = (Array.isArray(input.fixes) ? input.fixes : []).filter(
+    (f): f is { success?: boolean } => typeof f === 'object' && f !== null,
+  )
+  const validations = (Array.isArray(input.validations) ? input.validations : []).filter(
+    (v): v is { allowed?: boolean } => typeof v === 'object' && v !== null,
+  )
+
+  let criticalHigh = 0
+  for (const f of findings) {
+    const sev = String((f && f.severity) || '').toLowerCase()
+    if (sev === 'critical' || sev === 'high') criticalHigh += 1
+  }
+
+  let fixed = 0
+  let failedFixes = 0
+  for (const x of fixes) {
+    if (x && x.success === true) fixed += 1
+    else if (x && x.success === false) failedFixes += 1
+  }
+
+  let passed = 0
+  for (const v of validations) {
+    if (v && v.allowed === true) passed += 1
+  }
+  const validationTotal = validations.length
+  const validationPassRate = validationTotal > 0 ? Math.round((passed / validationTotal) * 100) : null
+
+  return {
+    version: RUN_BASELINE_VERSION,
+    savedAt,
+    ...(input.project ? { project: input.project } : {}),
+    ...(input.mode ? { mode: input.mode } : {}),
+    rounds: convergence.length,
+    findings: findings.length,
+    criticalHigh,
+    fixed,
+    failedFixes,
+    validationPassRate,
+    validationTotal,
+    qualityGateStatus: input.qualityGateStatus || null,
+    qualityGateScore: typeof input.qualityGateScore === 'number' ? input.qualityGateScore : null,
+    stoppedReason: input.stoppedReason || null,
+    convergence,
+  }
+}
+
+/**
+ * Parse a persisted baseline JSON string. Returns `null` for anything that is
+ * not a well-formed, version-matched baseline — a stale/corrupt payload must
+ * never be mis-read as a real run, and never throws.
+ */
+export function parseRunBaseline(raw: string | null): RunBaseline | null {
+  if (!raw) return null
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return null
+  }
+  if (typeof parsed !== 'object' || parsed === null) return null
+  const b = parsed as Record<string, unknown>
+  if (b.version !== RUN_BASELINE_VERSION) return null
+  if (typeof b.savedAt !== 'string' || b.savedAt.length === 0) return null
+  if (typeof b.findings !== 'number' || !Number.isFinite(b.findings)) return null
+  // convergence must be a number array (defensive; a non-array becomes []).
+  const convergence = Array.isArray(b.convergence)
+    ? b.convergence.filter((n): n is number => typeof n === 'number' && Number.isFinite(n))
+    : []
+  return {
+    version: RUN_BASELINE_VERSION,
+    savedAt: b.savedAt,
+    ...(typeof b.project === 'string' && b.project ? { project: b.project } : {}),
+    ...(typeof b.mode === 'string' && b.mode ? { mode: b.mode } : {}),
+    rounds: typeof b.rounds === 'number' && Number.isFinite(b.rounds) ? b.rounds : convergence.length,
+    findings: b.findings,
+    criticalHigh: typeof b.criticalHigh === 'number' && Number.isFinite(b.criticalHigh) ? b.criticalHigh : 0,
+    fixed: typeof b.fixed === 'number' && Number.isFinite(b.fixed) ? b.fixed : 0,
+    failedFixes: typeof b.failedFixes === 'number' && Number.isFinite(b.failedFixes) ? b.failedFixes : 0,
+    validationPassRate:
+      typeof b.validationPassRate === 'number' && Number.isFinite(b.validationPassRate) ? b.validationPassRate : null,
+    validationTotal:
+      typeof b.validationTotal === 'number' && Number.isFinite(b.validationTotal) ? b.validationTotal : 0,
+    qualityGateStatus: typeof b.qualityGateStatus === 'string' && b.qualityGateStatus ? b.qualityGateStatus : null,
+    qualityGateScore:
+      typeof b.qualityGateScore === 'number' && Number.isFinite(b.qualityGateScore) ? b.qualityGateScore : null,
+    stoppedReason: typeof b.stoppedReason === 'string' && b.stoppedReason ? b.stoppedReason : null,
+    convergence,
+  }
+}
+
+/**
+ * One row of the side-by-side comparison.
+ *
+ * `higherIsBetter` tells the renderer how to tint the delta:
+ *   - `true`  → a larger current value is an improvement (fixed, pass rate, score)
+ *   - `false` → a smaller current value is an improvement (findings, failed fixes)
+ *   - `null`  → neutral (rounds — fewer is usually faster but not always better)
+ */
+export interface RunCompareMetric {
+  key: 'rounds' | 'findings' | 'criticalHigh' | 'fixed' | 'failedFixes' | 'validationPassRate' | 'qualityGateScore'
+  baseline: number | null
+  current: number | null
+  higherIsBetter: boolean | null
+}
+
+/**
+ * Compare a saved baseline against the current run. Both sides come from
+ * `buildRunBaseline`, so `null` means "that side had no such measurement"
+ * (e.g. a dry-run has no fixes; a run that never validated has no pass rate).
+ */
+export function compareRuns(baseline: RunBaseline, current: RunBaseline): RunCompareMetric[] {
+  const num = (v: number | null | undefined): number | null =>
+    typeof v === 'number' && Number.isFinite(v) ? v : null
+  const rows: RunCompareMetric[] = [
+    { key: 'rounds', baseline: num(baseline.rounds), current: num(current.rounds), higherIsBetter: null },
+    { key: 'findings', baseline: num(baseline.findings), current: num(current.findings), higherIsBetter: false },
+    { key: 'criticalHigh', baseline: num(baseline.criticalHigh), current: num(current.criticalHigh), higherIsBetter: false },
+    { key: 'fixed', baseline: num(baseline.fixed), current: num(current.fixed), higherIsBetter: true },
+    { key: 'failedFixes', baseline: num(baseline.failedFixes), current: num(current.failedFixes), higherIsBetter: false },
+    { key: 'validationPassRate', baseline: num(baseline.validationPassRate), current: num(current.validationPassRate), higherIsBetter: true },
+    { key: 'qualityGateScore', baseline: num(baseline.qualityGateScore), current: num(current.qualityGateScore), higherIsBetter: true },
+  ]
+  return rows
+}

package/src/client/shortcuts.ts

@@ -0,0 +1,152 @@
+/**
+ * src/client/shortcuts.ts — iterate-plugin keyboard-command contributions.
+ *
+ * dsh 0.2.2-rc.1 added the *unified keyboard-command* capability
+ * (`@deepseek-ai/dsh-client-shortcuts`): any client plugin may register a
+ * command with a default key binding and a target resolver, and dsh's own
+ * keyboard adapter dispatches the gesture to it. The same capability also lets
+ * a context-menu action carry a `commandId` so the menu shows the live
+ * keycap next to the action (selection still invokes the action's `run`).
+ *
+ * This module turns that new upstream capability into a *user-perceivable*
+ * iterate surface: instead of hunting for the docked observatory (or
+ * right-clicking a session), the user can now press **Cmd/Ctrl+Shift+O** to
+ * open the iterate quality command center from anywhere in the session. The
+ * matching context-menu action carries the same `commandId`, so the shortcut
+ * is discoverable in the right-click menu ("open command center" shows the
+ * keycap), and dsh's own shortcut settings page lists it as an editable
+ * binding.
+ *
+ * Design (mirrors `context-menu.ts` and the rest of the client half):
+ *   - **Defensive**: the `shortcuts` service is optional and probed at
+ *     apply-time (see `readShortcuts` in `index.ts`); a host that predates
+ *     0.2.2-rc.1 simply has no keyboard command (the docked panel stays the
+ *     entry point). Nothing throws.
+ *   - **Pure builder**: `buildObservatoryShortcutCommand` returns the command
+ *     shape with no `ctx`/DOM side effects, so it is unit-testable on its own
+ *     (label resolution, binding defaults, resolve→run). The imperative
+ *     wiring (`openObservatory` / `lang`) is injected by
+ *     `registerIterateShortcuts`.
+ *   - **Bilingual**: the label resolves against the language passed in at
+ *     registration (a language switch is picked up by dsh's own command
+ *     catalog on the next render).
+ *   - **No external import**: like the rest of the client half, the dsh
+ *     `@deepseek-ai/dsh-client-shortcuts` types are NOT imported (no
+ *     compile-time coupling to a package a pre-0.2.2-rc.1 host may not have);
+ *     the surface below is the structural subset this plugin consumes.
+ */
+
+import type { Lang } from './i18n.ts'
+
+// ─── Structural service types (defensive; mirrors ContextMenusService) ───────
+
+/** Stable command identity owned by this plugin (a branded string upstream). */
+export const OBSERVATORY_SHORTCUT_ID = 'iterate.open-observatory'
+
+/** One physical key + modifiers; `primary` expands to Meta on macOS. */
+export interface ShortcutBinding {
+  code: string
+  secondCode?: string
+  modifiers: readonly string[]
+}
+
+/** The dsh command catalog shape this plugin registers. */
+export interface ShortcutCommand {
+  id: string
+  label: () => string
+  aliases: readonly string[]
+  defaults: Readonly<Record<string, ShortcutBinding>>
+  regions: readonly string[]
+  modals: readonly string[]
+  resolve(context: { region?: string; modal?: string | null; target?: Element | null }): ShortcutResolution
+}
+
+/** A resolved command either runs, is blocked with a reason, or passes. */
+export type ShortcutResolution =
+  | { status: 'handled'; run: () => void }
+  | { status: 'blocked'; reason: string }
+  | { status: 'pass' }
+
+/** Structural view of the dsh `shortcuts` service this plugin consumes. */
+export interface ShortcutsService {
+  register(command: ShortcutCommand): () => void
+}
+
+/** Injection points the shortcut wiring needs (kept dependency-light for tests). */
+export interface ShortcutDeps {
+  /** Open the observatory panel (optionally for a session, on a tab). */
+  openObservatory: (detail?: { sessionId?: string; tab?: string }) => void
+  /** Resolve the current UI language at label-build time. */
+  lang: () => Lang
+}
+
+/**
+ * Default key binding for the observatory command: Cmd/Ctrl+Shift+O
+ * ("O" = Open), applied uniformly across every runtime/platform profile so the
+ * feature is on by default on desktop and web. If an existing dsh command
+ * already owns this combination, `register` throws and the plugin degrades
+ * gracefully (no keyboard command; the observatory stays mouse-reachable).
+ */
+const DEFAULT_BINDING: ShortcutBinding = { code: 'KeyO', modifiers: ['primary', 'shift'] }
+
+const DEFAULT_PROFILES = [
+  'desktop:macos',
+  'desktop:windows',
+  'desktop:linux',
+  'web:macos',
+  'web:windows',
+  'web:linux',
+] as const
+
+/** Every runtime/platform profile maps to the same default binding. */
+export const OBSERVATORY_DEFAULT_BINDINGS: Readonly<Record<string, ShortcutBinding>> = Object.fromEntries(
+  DEFAULT_PROFILES.map((profile) => [profile, DEFAULT_BINDING]),
+) as Readonly<Record<string, ShortcutBinding>>
+
+/**
+ * Build the pure command descriptor for "open iterate observatory". The
+ * resolver always handles the gesture and runs the injected opener; it never
+ * blocks (opening the observatory is safe from any region and no modal).
+ */
+export function buildObservatoryShortcutCommand(deps: ShortcutDeps): ShortcutCommand {
+  const label = (): string =>
+    deps.lang() === 'zh' ? '打开 iterate 观测台' : 'Open iterate observatory'
+  return {
+    id: OBSERVATORY_SHORTCUT_ID,
+    label,
+    aliases: [],
+    defaults: OBSERVATORY_DEFAULT_BINDINGS,
+    regions: ['page', 'editable', 'terminal'],
+    modals: [],
+    resolve: () => ({ status: 'handled', run: () => deps.openObservatory({}) }),
+  }
+}
+
+/**
+ * Register the observatory keyboard command on the (already-validated)
+ * `shortcuts` service. Returns an unregister function; a host without the
+ * service is a no-op that returns `() => {}` (callers guard).
+ */
+export function registerIterateShortcuts(service: ShortcutsService, deps: ShortcutDeps): () => void {
+  try {
+    const dispose = service.register(buildObservatoryShortcutCommand(deps))
+    let done = false
+    return () => {
+      if (done) return
+      done = true
+      try {
+        dispose()
+      } catch {
+        /* noop */
+      }
+    }
+  } catch (err) {
+    // A duplicate id or an overlapping default binding must not take the
+    // plugin down — log and continue with no keyboard command (the docked
+    // panel and the context-menu "open" action remain the entry points).
+    if (typeof console !== 'undefined' && typeof console.error === 'function') {
+      console.error('[iterate-ui] keyboard-command registration failed; continuing without it.', err)
+    }
+    return () => {}
+  }
+}