@qontinui/shared-types 0.2.1 → 0.2.3

package/src/tauri-events/_api.ts

@@ -0,0 +1,76 @@
+/**
+ * Tauri Event Payload Types
+ *
+ * Wire-format types for payloads emitted on Tauri event channels by the
+ * runner. Use these to type the generic parameter of `listen<T>(...)` so
+ * future Rust serde renames (e.g. snake_case → camelCase) and shape
+ * changes break the TypeScript build instead of silently dropping events
+ * at the listener guard.
+ *
+ * ## Adjacently-tagged envelope (`AppEvent`)
+ *
+ * Most runner events are variants of the `AppEvent` enum, which is
+ * serialized via `#[serde(tag = "event_type", content = "data")]`. The
+ * wire payload is therefore `{ event_type: "<VariantName>", data: { ... } }`
+ * and consumers MUST read `event.payload.data.<field>` (NOT
+ * `event.payload.<field>`). The `AppEvent` discriminated union below
+ * encodes that envelope; reaching `data.<field>` after narrowing by
+ * `event_type` is type-safe.
+ *
+ * ## Direct-payload events
+ *
+ * A handful of events bypass `AppEvent` and emit a payload struct
+ * directly:
+ *  - `terminal-output` → `TerminalOutputEvent`
+ *  - `terminal-exit` → `TerminalExitEvent`
+ *  - `terminal-created` → `TerminalInfo`
+ *  - `finding_detected` / `finding_resolved` → wrap a `RunnerFinding`
+ *    inside the `AppEvent` envelope's `data.finding` field as untyped
+ *    JSON; consumers should cast `data.finding as RunnerFinding`.
+ *
+ * Source of truth:
+ *  - `AppEvent`: `qontinui-runner/src-tauri/src/event_system/types.rs`
+ *  - Terminal events: `qontinui-schemas/rust/src/terminal.rs`
+ *  - `RunnerFinding`: `qontinui-runner/src-tauri/src/tauri_event_payloads.rs`
+ *
+ * Regenerate via `cd qontinui-runner && npm run gen-events`.
+ */
+
+export type { AppEvent } from "../generated/AppEvent";
+
+// ── Terminal events (direct payloads, not wrapped in AppEvent) ──
+export type { TerminalInfo } from "../generated/TerminalInfo";
+export type { TerminalOutputEvent } from "../generated/TerminalOutputEvent";
+export type { TerminalExitEvent } from "../generated/TerminalExitEvent";
+
+// ── Runner-local finding payload (carried inside AppEvent::FindingDetected /
+//    AppEvent::FindingResolved as `data.finding`). Distinct from
+//    `qontinui_types::verification::Finding`. ──
+export type { RunnerFinding } from "../generated/RunnerFinding";
+export type { RunnerFindingCodeContext } from "../generated/RunnerFindingCodeContext";
+export type { RunnerFindingUserInput } from "../generated/RunnerFindingUserInput";
+
+// ── WS relay envelopes (runner→backend) and backend→client status events.
+//    Discriminated unions tagged on `type`. Source of truth lives in
+//    `qontinui-runner/src-tauri/src/relay_envelopes.rs`; backend-originated
+//    events mirror `qontinui-web/backend/app/services/runner/event_publisher.py`. ──
+export type { RunnerRelayMessage } from "../generated/RunnerRelayMessage";
+export type { RunnerStatusEvent } from "../generated/RunnerStatusEvent";
+export type { RunnerConnectedConnection } from "../generated/RunnerConnectedConnection";
+
+// ── Dev-only seed-finding payload (`dev:seed-finding` Tauri event from
+//    `commands/dev_findings.rs`). Sibling to the camelCase RunnerFinding
+//    fields so the TS listener can spread them straight into a Finding. ──
+export type { DevSeedFindingPayload } from "../generated/DevSeedFindingPayload";
+
+// ── Recommendation review decision payloads (`review-approved` /
+//    `review-rejected` from `commands/productivity.rs`). One struct
+//    covers both channels — only `userDecision` differs. ──
+export type { RecommendationReviewDecisionPayload } from "../generated/RecommendationReviewDecisionPayload";
+
+// ── Canvas panel payload carried inside AppEvent::CanvasUpdate's
+//    `data.panel` field. Wire-format mirror of the runner's `StoredPanel`
+//    (`mcp/canvas.rs`). The hand-written `CanvasPanel` in `../canvas/index.ts`
+//    pre-dates this generated re-export; both shapes are intentionally
+//    identical. New consumers should prefer this generated import. ──
+export type { CanvasPanel as CanvasUpdatePanel } from "../generated/CanvasPanel";

package/src/tauri-events/index.ts

@@ -0,0 +1 @@
+export * from "./_api";

package/src/ui-bridge-ir/document.ts

@@ -16,6 +16,61 @@ import type { IRTransition } from "./transition";
  */
 export type IRVersion = "1.0";
 
+/**
+ * Axes that the spec <-> IR pairing gate compares. A document's
+ * `pairingPolicy.acceptDrift.axes` lists which of these are
+ * intentionally allowed to diverge between the legacy spec and the
+ * IR's forward projection.
+ */
+export type IRPairingAxis = "groupCount" | "groupIds" | "assertionCount";
+
+/**
+ * Per-document opt-out for specific spec<->IR pairing axes.
+ *
+ * The canonical use case is a hand-authored IR that uses a different
+ * grouping convention than the legacy spec. Without an explicit policy
+ * the pairing gate flags it as a mismatch on every PR, which trains
+ * reviewers to ignore the gate. The policy makes the divergence
+ * explicit and audit-friendly:
+ *
+ *   - `axes`     — which fingerprint comparisons to skip
+ *   - `reason`   — human-readable justification (required, surfaced in
+ *                  `check-spec-pairing` summary output)
+ *   - `since`    — ISO date (YYYY-MM-DD) the exemption was added
+ *   - `expiresAt` — optional ISO date (YYYY-MM-DD) after which the
+ *                   exemption stops applying. Forces periodic
+ *                   re-justification: the pairing gate downgrades
+ *                   expired exemptions back to ordinary mismatches.
+ *
+ * Mismatches NOT covered by the listed `axes` still fail the gate as
+ * usual — you can accept drift on `groupCount` while still requiring
+ * the assertion total to match.
+ */
+export interface IRAcceptDriftPolicy {
+  /** Fingerprint axes whose mismatches are tolerated. */
+  axes: IRPairingAxis[];
+  /** Human-readable justification for the exemption. */
+  reason: string;
+  /** ISO date (YYYY-MM-DD) the exemption was added. */
+  since: string;
+  /**
+   * Optional ISO date (YYYY-MM-DD) after which the exemption stops
+   * applying. The pairing gate then surfaces the document as an
+   * ordinary mismatch.
+   */
+  expiresAt?: string;
+}
+
+/**
+ * Per-document pairing policy block. Currently only carries
+ * `acceptDrift`; future policies (e.g. assertion-shape exemptions)
+ * can extend this without breaking the IR schema.
+ */
+export interface IRPairingPolicy {
+  /** Opt-out from specific spec<->IR pairing mismatch axes. */
+  acceptDrift?: IRAcceptDriftPolicy;
+}
+
 /**
  * Top-level IR document.
  */
@@ -33,6 +88,13 @@ export interface IRDocument {
   /** Where this document came from. */
   provenance?: IRProvenance;
 
+  /**
+   * Per-document policy block — opt-out from specific spec<->IR
+   * pairing mismatches. Used by hand-authored IRs that intentionally
+   * diverge from the legacy spec shape.
+   */
+  pairingPolicy?: IRPairingPolicy;
+
   /** State declarations within this document. */
   states: IRState[];
   /** Transition declarations within this document. */

package/src/ui-bridge-ir/ir.schema.json

@@ -15,6 +15,7 @@
     "description": { "type": "string" },
     "metadata": { "$ref": "#/$defs/IRMetadata" },
     "provenance": { "$ref": "#/$defs/IRProvenance" },
+    "pairingPolicy": { "$ref": "#/$defs/IRPairingPolicy" },
     "initialState": { "type": "string" },
     "states": {
       "type": "array",
@@ -26,6 +27,30 @@
     }
   },
   "$defs": {
+    "IRPairingPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "acceptDrift": {
+          "type": "object",
+          "required": ["axes", "reason", "since"],
+          "additionalProperties": false,
+          "properties": {
+            "axes": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": ["groupCount", "groupIds", "assertionCount"]
+              },
+              "minItems": 1
+            },
+            "reason": { "type": "string", "minLength": 1 },
+            "since": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
+            "expiresAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }
+          }
+        }
+      }
+    },
     "IRElementCriteria": {
       "type": "object",
       "additionalProperties": false,

package/src/ui-bridge-ir/__tests__/legacy-roster.test.ts

@@ -1,182 +0,0 @@
-/**
- * Legacy spec roster test (Phase A2 fixture gate).
- *
- * Walks the entire `qontinui_parent` monorepo, collects every shipping
- * `*.spec.uibridge.json`, and round-trips each through:
- *
- *     legacy --projectLegacyToIR-->  IR  --projectIRToBundledPage-->  legacy'
- *
- * For each fixture we assert (semantically — not byte-strict):
- *   - same number of groups
- *   - same group ids in input order
- *   - same total assertion count across all groups
- *
- * This is coarse but effective: it catches any data loss in the inverse
- * projection without forcing the inverse to preserve hand-edited assertion
- * ids / severity / category / etc. (which the forward direction regenerates
- * from defaults). Phase A4 will tighten the contract for hand-authored
- * fields.
- *
- * The walker fails fast if it finds < 100 fixtures (canary against a
- * misconfigured directory walk) — current expected count is 121 (96 runner +
- * 19 web + 5 mobile + 2 supervisor) as of 2026-04. The number is allowed to
- * grow; the lower bound just guards against accidentally testing nothing.
- */
-
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import path from "node:path";
-
-import { describe, expect, it } from "vitest";
-
-import {
-  projectIRToBundledPage,
-  projectLegacyToIR,
-  type LegacySpec,
-} from "../projection";
-
-// ---------------------------------------------------------------------------
-// Discovery
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve the monorepo root from the test file's location. The test file
- * lives at `qontinui-schemas/ts/src/ui-bridge-ir/__tests__/`, so five
- * `..` segments take us to `qontinui_parent/`.
- *
- * Use `process.cwd()` as a fallback only when the test runs from outside the
- * usual layout (e.g. CI checkout with renamed parent) — vitest sets cwd to
- * the package root by default.
- */
-const MONOREPO_ROOT = path.resolve(
-  __dirname,
-  "..",
-  "..",
-  "..",
-  "..",
-  "..",
-);
-
-// Directories to skip. Note: do NOT include "build" — Next.js apps have route
-// folders named `build/` (e.g., qontinui-web/frontend/src/app/(app)/build/)
-// that legitimately contain spec fixtures.
-const SKIP_DIRS = new Set([
-  "node_modules",
-  "target",
-  "target-agent",
-  "dist",
-  ".git",
-  ".next",
-  ".venv",
-  "__pycache__",
-  "out",
-]);
-
-/**
- * Recursively walk `root`, collecting every `*.spec.uibridge.json` file.
- * Skips the directory names in `SKIP_DIRS`. Synchronous; the fixture set is
- * small (low hundreds) so we don't bother with worker threads.
- */
-function collectSpecs(root: string): string[] {
-  const out: string[] = [];
-  const stack: string[] = [root];
-  while (stack.length > 0) {
-    const current = stack.pop()!;
-    let entries: import("node:fs").Dirent[];
-    try {
-      entries = readdirSync(current, { withFileTypes: true });
-    } catch {
-      // Permission errors / vanished dirs — skip silently.
-      continue;
-    }
-    for (const entry of entries) {
-      if (SKIP_DIRS.has(entry.name)) continue;
-      const full = path.join(current, entry.name);
-      if (entry.isDirectory()) {
-        stack.push(full);
-      } else if (entry.isFile() && entry.name.endsWith(".spec.uibridge.json")) {
-        out.push(full);
-      } else if (entry.isSymbolicLink()) {
-        // Resolve symlinks defensively — some plugin checkouts use them.
-        try {
-          const stat = statSync(full);
-          if (stat.isDirectory()) {
-            stack.push(full);
-          } else if (stat.isFile() && entry.name.endsWith(".spec.uibridge.json")) {
-            out.push(full);
-          }
-        } catch {
-          // ignore
-        }
-      }
-    }
-  }
-  // Sort for deterministic test ordering.
-  out.sort();
-  return out;
-}
-
-const SPECS = collectSpecs(MONOREPO_ROOT);
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe("legacy spec roster — discovery sanity", () => {
-  it("finds at least 100 *.spec.uibridge.json files in the monorepo", () => {
-    expect(SPECS.length).toBeGreaterThanOrEqual(100);
-  });
-
-  it("does not include node_modules / dist / target paths", () => {
-    for (const f of SPECS) {
-      expect(f).not.toMatch(/[\\/](?:node_modules|dist|target|\.git)[\\/]/);
-    }
-  });
-});
-
-describe("legacy spec roster — round-trip via IR", () => {
-  // Use it.each so every fixture gets its own test name and failures pinpoint
-  // the exact file. Pre-load each fixture as a tuple for the iterator.
-  const cases: ReadonlyArray<readonly [string, string]> = SPECS.map((p) => [
-    path.relative(MONOREPO_ROOT, p),
-    p,
-  ] as const);
-
-  it.each(cases)("%s round-trips through IR without data loss", (_relpath, full) => {
-    let raw = readFileSync(full, "utf-8");
-    // Strip UTF-8 BOM if present — at least one shipping spec
-    // (settings-security.spec.uibridge.json) was saved with a BOM.
-    if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
-    const legacy = JSON.parse(raw) as LegacySpec;
-
-    const ir = projectLegacyToIR(legacy);
-    const projected = projectIRToBundledPage(ir);
-
-    // 1. Same number of groups.
-    expect(projected.groups.length).toBe(legacy.groups.length);
-
-    // 2. Same group ids in input order.
-    expect(projected.groups.map((g) => g.id)).toEqual(legacy.groups.map((g) => g.id));
-
-    // 3. Same total assertion count across all groups (coarse data-loss check).
-    const projectedAssertionCount = projected.groups.reduce(
-      (sum, g) => sum + g.assertions.length,
-      0,
-    );
-    const legacyAssertionCount = legacy.groups.reduce(
-      (sum, g) => sum + (Array.isArray(g.assertions) ? g.assertions.length : 0),
-      0,
-    );
-    // The forward projection emits a placeholder assertion for any state with
-    // zero requiredElements. Real legacy fixtures never have zero-assertion
-    // groups, but be defensive: allow projected >= legacy when legacy had
-    // groups with zero assertions.
-    const legacyHasEmptyGroup = legacy.groups.some(
-      (g) => !Array.isArray(g.assertions) || g.assertions.length === 0,
-    );
-    if (legacyHasEmptyGroup) {
-      expect(projectedAssertionCount).toBeGreaterThanOrEqual(legacyAssertionCount);
-    } else {
-      expect(projectedAssertionCount).toBe(legacyAssertionCount);
-    }
-  });
-});