@stigmer/react 3.1.2 → 3.1.4

package/src/workspace/__tests__/a11y/harness.tsx

@@ -0,0 +1,140 @@
+// Shared harness for the browser-mode accessibility audits (DD-22).
+//
+// Renders an audited component inside the `.stgm` scope against the SDK's
+// SHIPPED stylesheet (the prebuilt `dist/styles.css`, not a test-time
+// recompile), then runs axe-core with the SAME policy as the e2e page audit
+// (`test/e2e/tests/functional/accessibility.spec.ts`): WCAG 2.0 A/AA tags,
+// fail on critical/serious, log moderate/minor.
+//
+// Why this file exists and how it stays honest:
+// - Contrast/target-size are the point, so it runs in a real browser via
+//   `vitest.a11y.config.ts` (happy-dom can't evaluate either).
+// - axe is scoped to the rendered container and restricted to WCAG tags, so
+//   page-level rules (`region`, `landmark-one-main`, `html-has-lang`, …) don't
+//   false-positive on a component rendered in isolation.
+// - The wrapper carries the themed background so `color-contrast` is measured
+//   against the real surface color in BOTH color modes, not the browser default.
+
+import "../../../../dist/styles.css";
+
+import { render, cleanup } from "@testing-library/react";
+import type { ReactElement } from "react";
+import axe from "axe-core";
+import { expect } from "vitest";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../../context.js";
+import { __clearWorkspaceListingCache } from "../../workspaceListingCache.js";
+
+/** The color modes every state is audited under. */
+export const COLOR_MODES = ["light", "dark"] as const;
+export type ColorMode = (typeof COLOR_MODES)[number];
+
+/**
+ * Rules that are audited but reported as advisory (logged, non-blocking) rather
+ * than failing the suite — mirroring the e2e audit's graduated rollout, which
+ * ships fixing only some severities first.
+ *
+ * `color-contrast`: the workspace panel's deliberately-dense small muted text
+ * (tree labels, section headers, `text-[0.65rem]` path subtitles/previews,
+ * count badges, the empty-state placeholder) falls below WCAG AA 4.5:1 in both
+ * modes. This is a PRE-EXISTING, app-wide design-token/density concern (the
+ * `--stgm-muted-foreground` token at small sizes), not a Session 18 regression,
+ * and its fix needs a deliberate design pass across presets (tracked in DD-22's
+ * Follow-ups). Kept advisory here so this audit can land and guard the
+ * STRUCTURAL hardening (roles, names, relationships, nesting) immediately.
+ * Promote back to blocking once the contrast pass ships.
+ */
+const ADVISORY_RULE_IDS = new Set<string>(["color-contrast"]);
+
+// The audited surfaces reach the SDK client only through the diff path's
+// artifact hooks, which skip all fetches for inline file changes (the only kind
+// the fixtures build). No client method is ever invoked, so an empty stub is
+// sufficient — and required, since `useStigmer` throws outside a provider.
+const stubClient = {} as unknown as Stigmer;
+
+/**
+ * Render `ui` inside a themed `.stgm` container for the given color mode.
+ * Returns the container so callers can await the settled DOM before auditing.
+ */
+export function renderAudited(ui: ReactElement, mode: ColorMode): HTMLElement {
+  const container = document.createElement("div");
+  container.className = "stgm";
+  container.setAttribute("data-stgm-color-mode", mode);
+  // The panel always sits on a themed surface; matching it here means
+  // color-contrast is computed against the real background, not body white.
+  container.style.background = "var(--stgm-background)";
+  container.style.color = "var(--stgm-foreground)";
+  // A fixed height gives the flex/scroll surfaces (ResizableSplit, editor pane)
+  // a real box to lay out in — observer-driven measurement that is a no-op in
+  // happy-dom but correct in Chromium.
+  container.style.height = "720px";
+  container.style.width = "1024px";
+  // RTL does NOT attach a caller-provided container to the document, so attach
+  // it ourselves — both `screen` queries and axe need it in the live DOM.
+  document.body.appendChild(container);
+
+  render(<StigmerContext.Provider value={stubClient}>{ui}</StigmerContext.Provider>, {
+    container,
+  });
+  return container;
+}
+
+function summarize(violations: axe.Result[]): string {
+  return violations
+    .map((v) => {
+      const nodes = v.nodes
+        .slice(0, 5)
+        .map((n) => `    · ${n.target.join(" ")}\n      ${n.html.slice(0, 160)}`)
+        .join("\n");
+      return `  [${v.impact}] ${v.id}: ${v.help} (${v.nodes.length} node(s))\n${nodes}`;
+    })
+    .join("\n");
+}
+
+/**
+ * Run the WCAG 2.0 A/AA audit over `container`. Fails the test on any
+ * critical/serious violation (mirroring the e2e gate); logs moderate/minor.
+ */
+export async function auditA11y(container: HTMLElement, label: string): Promise<void> {
+  const results = await axe.run(container, {
+    runOnly: { type: "tag", values: ["wcag2a", "wcag2aa"] },
+  });
+
+  // Blocking: critical/serious violations that are NOT on the advisory list.
+  const serious = results.violations.filter(
+    (v) =>
+      (v.impact === "critical" || v.impact === "serious") &&
+      !ADVISORY_RULE_IDS.has(v.id),
+  );
+  // Advisory: everything else worth logging — the deferred rules plus any
+  // moderate/minor findings.
+  const advisory = results.violations.filter(
+    (v) =>
+      ADVISORY_RULE_IDS.has(v.id) ||
+      v.impact === "moderate" ||
+      v.impact === "minor",
+  );
+
+  if (advisory.length > 0) {
+    // Non-blocking a11y signal (mirrors the e2e audit's moderate/minor logging).
+    console.warn(`[a11y: ${label}] non-blocking violations:\n${summarize(advisory)}`);
+  }
+
+  expect(
+    serious,
+    `[a11y: ${label}] critical/serious axe violations:\n${summarize(serious)}`,
+  ).toHaveLength(0);
+}
+
+/**
+ * Reset cross-test state. The listing cache is module-level (keyed by entry id),
+ * so without this a scenario could take a prior scenario's cached listing —
+ * masking the truncation banner or leaking a stale tree. Call in `afterEach`.
+ */
+export function resetWorkspaceAudit(): void {
+  cleanup();
+  // cleanup() unmounts React trees but does not remove caller-provided
+  // containers; drop any leftover `.stgm` wrappers so scenarios never bleed.
+  document.querySelectorAll(".stgm").forEach((node) => node.remove());
+  __clearWorkspaceListingCache();
+}

package/src/workspace/__tests__/a11y/mock-capabilities.ts

@@ -0,0 +1,138 @@
+// In-memory workspace capabilities for the browser-mode accessibility audit
+// (DD-22). These mirror the shapes a real host injects (DD-004) — a GitHub
+// lister/reader on web, a Tauri walker on desktop — but serve a tiny fixed
+// tree so the Session 18 hardened surfaces render deterministically, with no
+// network, backend, or token. Fixtures render REAL component output only; they
+// introduce no Tailwind utility classes of their own, so the prebuilt
+// `dist/styles.css` (generated by `@source` scanning over SDK source) covers
+// every class in the audited DOM.
+
+import { create } from "@bufbuild/protobuf";
+import {
+  FileChangeSchema,
+  FileContentSchema,
+  type FileChange,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  FileChangeCaptureLevel,
+  FileChangeType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { WorkspaceEntry } from "../../useWorkspaceEntries.js";
+import type {
+  WorkspaceFileEntry,
+  WorkspaceFileLister,
+} from "../../WorkspaceFileLister.js";
+import type {
+  WorkspaceFileContent,
+  WorkspaceFileReader,
+} from "../../WorkspaceFileReader.js";
+import type { WorkspaceContentSearcher } from "../../WorkspaceContentSearcher.js";
+
+/** A git entry whose listing is a normal (non-truncated) multi-level tree. */
+export const EXPLORER_ENTRY: WorkspaceEntry = {
+  id: "a11y-explorer",
+  name: "acme/app",
+  type: "git",
+  gitUrl: "https://github.com/acme/app.git",
+  gitBranch: "main",
+};
+
+/** A git entry whose listing is capped, exercising the truncation banner. */
+export const TRUNCATED_ENTRY: WorkspaceEntry = {
+  id: "a11y-truncated",
+  name: "acme/monorepo",
+  type: "git",
+  gitUrl: "https://github.com/acme/monorepo.git",
+  gitBranch: "main",
+};
+
+/** The file opened by the viewer audits (present in {@link EXPLORER_ENTRY}). */
+export const OPEN_FILE_PATH = "src/index.ts";
+
+const OPEN_FILE_TEXT = [
+  "export interface Greeting {",
+  "  readonly message: string;",
+  "}",
+  "",
+  "export function greet(name: string): Greeting {",
+  "  return { message: `Hello, ${name}!` };",
+  "}",
+  "",
+].join("\n");
+
+const EXPLORER_LISTING: readonly WorkspaceFileEntry[] = [
+  { path: "src", isDirectory: true },
+  { path: "src/index.ts", isDirectory: false },
+  { path: "src/lib", isDirectory: true },
+  { path: "src/lib/format.ts", isDirectory: false },
+  { path: "src/lib/logo.png", isDirectory: false },
+  { path: "README.md", isDirectory: false },
+  { path: "package.json", isDirectory: false },
+];
+
+const TRUNCATED_LISTING: readonly WorkspaceFileEntry[] = [
+  { path: "src", isDirectory: true },
+  { path: "src/a.ts", isDirectory: false },
+  { path: "src/b.ts", isDirectory: false },
+  // The lister's advisory notice — the cache collapses this into the single
+  // `truncated` banner the audit asserts is accessible (DD-11).
+  { path: "Listing truncated — repository too large.", isDirectory: false, notice: true },
+];
+
+/** Lister serving the fixed tree, keyed by entry id. */
+export const mockLister: WorkspaceFileLister = async (entry) => {
+  if (entry.id === TRUNCATED_ENTRY.id) return [...TRUNCATED_LISTING];
+  if (entry.id === EXPLORER_ENTRY.id) return [...EXPLORER_LISTING];
+  return [];
+};
+
+const TEXT_CONTENT: WorkspaceFileContent = {
+  text: OPEN_FILE_TEXT,
+  isBinary: false,
+  size: OPEN_FILE_TEXT.length,
+  encoding: "utf-8",
+};
+
+const BINARY_CONTENT: WorkspaceFileContent = {
+  text: null,
+  isBinary: true,
+  size: 2048,
+  encoding: "base64",
+};
+
+/** Reader returning text for source files and a binary sentinel for the png. */
+export const mockReader: WorkspaceFileReader = async (_entry, path) => {
+  if (path.endsWith(".png")) return BINARY_CONTENT;
+  return TEXT_CONTENT;
+};
+
+/** Content searcher returning a couple of deterministic line hits. */
+export const mockSearcher: WorkspaceContentSearcher = async (entry, query) => {
+  if (entry.id !== EXPLORER_ENTRY.id) return null;
+  return {
+    matches: [
+      { path: "src/index.ts", line: 5, preview: `export function ${query}(name: string): Greeting {` },
+      { path: "src/lib/format.ts", line: 2, preview: `  // ${query} helper` },
+    ],
+    truncated: false,
+  };
+};
+
+/**
+ * An inline (non-offloaded) MODIFY change for the open file, so the diff pane
+ * resolves its before/after text synchronously — `useFileChangeContent` issues
+ * no artifact fetch for inline sides, so the audit needs no live backend.
+ */
+export function fileChangeForOpenFile(): FileChange {
+  return create(FileChangeSchema, {
+    path: OPEN_FILE_PATH,
+    changeType: FileChangeType.MODIFY,
+    captureLevel: FileChangeCaptureLevel.WHOLE_FILE,
+    before: create(FileContentSchema, {
+      body: { case: "inline", value: "export function greet(name: string) {\n  return name;\n}\n" },
+    }),
+    after: create(FileContentSchema, {
+      body: { case: "inline", value: OPEN_FILE_TEXT },
+    }),
+  });
+}

package/src/workspace/__tests__/a11y/workspace-editor.a11y.test.tsx

@@ -0,0 +1,65 @@
+// Accessibility audit (DD-22) — WorkspaceEditor (the Config-facet workspace
+// entry manager).
+//
+// Covers the Session 18 hardening here: aria-labeled git inputs and focus rings
+// on the editor's buttons. Audits two states — the default action list and the
+// manual "add git repository" form — in light + dark against the shipped CSS.
+
+import { describe, it, afterEach } from "vitest";
+import { screen } from "@testing-library/react";
+import { WorkspaceEditor } from "../../WorkspaceEditor.js";
+import type { UseWorkspaceEntriesReturn } from "../../useWorkspaceEntries.js";
+import {
+  COLOR_MODES,
+  auditA11y,
+  renderAudited,
+  resetWorkspaceAudit,
+} from "./harness.js";
+
+/** A minimal workspace hook return — rendering only reads `entries`. */
+function mockWorkspace(
+  entries: UseWorkspaceEntriesReturn["entries"] = [],
+): UseWorkspaceEntriesReturn {
+  return {
+    entries,
+    addGitRepo: () => {},
+    addLocalPath: () => {},
+    remove: () => {},
+    clear: () => {},
+    clearLocal: () => {},
+    toInput: () => [],
+    hasEntries: entries.length > 0,
+  };
+}
+
+const GIT_ENTRY = {
+  id: "editor-entry",
+  name: "acme/app",
+  type: "git" as const,
+  gitUrl: "https://github.com/acme/app.git",
+  gitBranch: "main",
+};
+
+afterEach(resetWorkspaceAudit);
+
+describe("WorkspaceEditor a11y", () => {
+  it.each(COLOR_MODES)("default action list with an entry (%s)", async (mode) => {
+    const container = renderAudited(
+      <WorkspaceEditor workspace={mockWorkspace([GIT_ENTRY])} enableLocal />,
+      mode,
+    );
+    await screen.findByText("Connect GitHub");
+    await auditA11y(container, `editor list · ${mode}`);
+  });
+
+  it.each(COLOR_MODES)("manual add-git form with labeled inputs (%s)", async (mode) => {
+    const container = renderAudited(
+      // Empty entries + initialPanel="github" with no connection opens the
+      // manual URL/branch form (the labeled git inputs Session 18 hardened).
+      <WorkspaceEditor workspace={mockWorkspace()} initialPanel="github" />,
+      mode,
+    );
+    await screen.findByLabelText("Git repository URL");
+    await auditA11y(container, `editor git form · ${mode}`);
+  });
+});

package/src/workspace/__tests__/a11y/workspace-explorer-search.a11y.test.tsx

@@ -0,0 +1,112 @@
+// Accessibility audit (DD-22) — the explorer tree and both search surfaces.
+//
+// Covers the Session 18 hardening for these surfaces: file-tree `role="tree"` +
+// `aria-level` + `aria-hidden` glyphs, the neutral truncation banner + Retry
+// focus ring, the search `role="status"` live region, the combobox/listbox
+// results, and the `Name | Text` search-mode radiogroup — each in light + dark
+// against the shipped stylesheet.
+
+import { describe, it, afterEach } from "vitest";
+import { screen, fireEvent } from "@testing-library/react";
+import { WorkspaceSurface } from "../../WorkspaceSurface.js";
+import {
+  EXPLORER_ENTRY,
+  TRUNCATED_ENTRY,
+  mockLister,
+  mockReader,
+  mockSearcher,
+} from "./mock-capabilities.js";
+import {
+  COLOR_MODES,
+  auditA11y,
+  renderAudited,
+  resetWorkspaceAudit,
+} from "./harness.js";
+
+const noop = () => {};
+
+/** The controlled props every WorkspaceSurface render needs, minus the ones a
+ *  given scenario varies (entries/lister/searcher/view). */
+const baseProps = {
+  reader: mockReader,
+  editors: [],
+  selectedFile: null,
+  onOpenFile: noop,
+  onActivateEditor: noop,
+  onPinEditor: noop,
+  onCloseEditor: noop,
+  onCollapse: noop,
+};
+
+afterEach(resetWorkspaceAudit);
+
+describe("WorkspaceSurface a11y — explorer + search", () => {
+  it.each(COLOR_MODES)("explorer tree, populated listing (%s)", async (mode) => {
+    const container = renderAudited(
+      <WorkspaceSurface
+        entries={[EXPLORER_ENTRY]}
+        lister={mockLister}
+        view="files"
+        {...baseProps}
+      />,
+      mode,
+    );
+    // The first root auto-expands; wait for a top-level file before auditing so
+    // axe sees the loaded tree, not the loading state.
+    await screen.findByText("README.md");
+    await auditA11y(container, `explorer tree · ${mode}`);
+  });
+
+  it.each(COLOR_MODES)("explorer truncation banner (%s)", async (mode) => {
+    const container = renderAudited(
+      <WorkspaceSurface
+        entries={[TRUNCATED_ENTRY]}
+        lister={mockLister}
+        view="files"
+        {...baseProps}
+      />,
+      mode,
+    );
+    await screen.findByText(/Showing a partial listing/i);
+    await auditA11y(container, `explorer truncation · ${mode}`);
+  });
+
+  it.each(COLOR_MODES)("filename search with results (%s)", async (mode) => {
+    const container = renderAudited(
+      <WorkspaceSurface
+        entries={[EXPLORER_ENTRY]}
+        lister={mockLister}
+        searcher={mockSearcher}
+        view="search"
+        {...baseProps}
+      />,
+      mode,
+    );
+    const input = await screen.findByRole("combobox", {
+      name: "Search workspace files by name",
+    });
+    fireEvent.change(input, { target: { value: "index" } });
+    await screen.findByRole("listbox", { name: "Search results" });
+    await auditA11y(container, `filename search · ${mode}`);
+  });
+
+  it.each(COLOR_MODES)("content (text) search with results (%s)", async (mode) => {
+    const container = renderAudited(
+      <WorkspaceSurface
+        entries={[EXPLORER_ENTRY]}
+        lister={mockLister}
+        searcher={mockSearcher}
+        view="search"
+        {...baseProps}
+      />,
+      mode,
+    );
+    fireEvent.click(await screen.findByRole("radio", { name: "Text" }));
+    const input = await screen.findByRole("combobox", {
+      name: "Search text in workspace files",
+    });
+    fireEvent.change(input, { target: { value: "greet" } });
+    await screen.findByRole("listbox", { name: "Search results" });
+    await auditA11y(container, `content search · ${mode}`);
+  });
+});

package/src/workspace/__tests__/a11y/workspace-viewer-tabs.a11y.test.tsx

@@ -0,0 +1,69 @@
+// Accessibility audit (DD-22) — the editor area: open tabs, the file viewer in
+// both File and Diff modes, and the mode toggle.
+//
+// Covers the Session 18 hardening here: `EditorTabs` `role="tablist"`/`tab` with
+// `aria-controls`, the single `role="tabpanel"` body, the `FileViewer`
+// `role="region"` (Escape-focusable) and its `Diff | File` `ViewerModeToggle`
+// radiogroup — each in light + dark against the shipped stylesheet.
+
+import { describe, it, afterEach, expect } from "vitest";
+import { screen, waitFor } from "@testing-library/react";
+import { WorkspaceSurface } from "../../WorkspaceSurface.js";
+import {
+  EXPLORER_ENTRY,
+  OPEN_FILE_PATH,
+  fileChangeForOpenFile,
+  mockLister,
+  mockReader,
+} from "./mock-capabilities.js";
+import {
+  COLOR_MODES,
+  auditA11y,
+  renderAudited,
+  resetWorkspaceAudit,
+} from "./harness.js";
+
+const noop = () => {};
+
+const openEditorProps = {
+  entries: [EXPLORER_ENTRY],
+  lister: mockLister,
+  reader: mockReader,
+  editors: [{ entryId: EXPLORER_ENTRY.id, path: OPEN_FILE_PATH, preview: false }],
+  selectedFile: { entryId: EXPLORER_ENTRY.id, path: OPEN_FILE_PATH },
+  view: "files",
+  onOpenFile: noop,
+  onActivateEditor: noop,
+  onPinEditor: noop,
+  onCloseEditor: noop,
+  onCollapse: noop,
+};
+
+afterEach(resetWorkspaceAudit);
+
+describe("WorkspaceSurface a11y — editor tabs + viewer", () => {
+  it.each(COLOR_MODES)("open file, File view (%s)", async (mode) => {
+    const container = renderAudited(<WorkspaceSurface {...openEditorProps} />, mode);
+    await screen.findByRole("region", { name: "File viewer" });
+    // Audit the settled surface: the explorer tree loaded AND the file content
+    // rendered (not the skeletons) — both sidebar and editor stable.
+    await screen.findByText("README.md");
+    await waitFor(() =>
+      expect(screen.queryByLabelText("Loading file")).toBeNull(),
+    );
+    await auditA11y(container, `file view · ${mode}`);
+  });
+
+  it.each(COLOR_MODES)("open file, Diff view (%s)", async (mode) => {
+    const container = renderAudited(
+      <WorkspaceSurface {...openEditorProps} change={fileChangeForOpenFile()} />,
+      mode,
+    );
+    // A change makes the viewer diff-default and exposes the Diff|File toggle;
+    // inline diff content resolves synchronously (no artifact fetch).
+    await screen.findByRole("radio", { name: "Diff" });
+    // Also wait for the explorer tree to settle so we audit the stable surface.
+    await screen.findByText("README.md");
+    await auditA11y(container, `diff view · ${mode}`);
+  });
+});