@komarspn/pi-permission-system 16.0.2

package/test/helpers/gate-fixtures.ts

@@ -0,0 +1,323 @@
+/**
+ * Shared gate-level test fixtures for gate descriptor and runner tests.
+ */
+import { vi } from "vitest";
+import type { DecisionReporter } from "#src/decision-reporter";
+import type { DenialContext } from "#src/denial-messages";
+import type { GatePrompter } from "#src/gate-prompter";
+import type { GateDescriptor } from "#src/handlers/gates/descriptor";
+import { GateRunner } from "#src/handlers/gates/runner";
+import type { SkillInputGateInputs } from "#src/handlers/gates/skill-input-gate-pipeline";
+import type { ToolCallGateInputs } from "#src/handlers/gates/tool-call-gate-pipeline";
+import type { ToolCallContext } from "#src/handlers/gates/types";
+import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import type { PersistentApprovalRecorder } from "#src/persistent-approval-recorder";
+import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
+import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
+import type { ToolPreviewFormatterOptions } from "#src/tool-preview-formatter";
+import type { PermissionCheckResult } from "#src/types";
+
+import { makeCheckResult } from "#test/helpers/handler-fixtures";
+
+/**
+ * Permission resolver mock with an optional default check result.
+ *
+ * Returns a plain object whose `resolve` is a `vi.fn` so callers retain full
+ * mock access (`mockReturnValue`, `mockImplementation`, `mock.calls`).
+ */
+export function makeResolver(defaultCheck?: PermissionCheckResult) {
+  const resolve = vi.fn<ScopedPermissionResolver["resolve"]>();
+  const resolvePathPolicy =
+    vi.fn<ScopedPermissionResolver["resolvePathPolicy"]>();
+  if (defaultCheck) {
+    resolve.mockReturnValue(defaultCheck);
+    resolvePathPolicy.mockReturnValue(defaultCheck);
+  }
+  return { resolve, resolvePathPolicy };
+}
+
+/**
+ * Gate descriptor factory with runner-test defaults.
+ *
+ * Uses deny as the default `denialContext` check result so tests that
+ * verify block paths don't need to override the surface check.
+ */
+export function makeDescriptor(
+  overrides: Partial<GateDescriptor> = {},
+): GateDescriptor {
+  return {
+    surface: "read",
+    input: {},
+    denialContext: {
+      kind: "tool",
+      check: makeCheckResult({ state: "deny", matchedPattern: "*" }),
+    },
+    promptDetails: {
+      source: "tool_call",
+      agentName: null,
+      message: "Allow tool 'read'?",
+      toolCallId: "tc-1",
+      toolName: "read",
+    },
+    logContext: {
+      source: "tool_call",
+      toolCallId: "tc-1",
+      toolName: "read",
+    },
+    decision: {
+      surface: "read",
+      value: "read",
+    },
+    ...overrides,
+  };
+}
+
+/**
+ * Reporter mock with independently inspectable vi.fn() stubs.
+ */
+export function makeReporter(
+  overrides: Partial<DecisionReporter> = {},
+): DecisionReporter {
+  return {
+    writeReviewLog: vi.fn(),
+    emitDecision: vi.fn(),
+    ...overrides,
+  };
+}
+
+/**
+ * Gate runner factory for `GateRunner` unit tests.
+ *
+ * Builds one `GateRunner` from four role mocks and returns `{ runner, deps }`
+ * so tests can both invoke `runner.run(...)` and assert on the individual
+ * mock call records (`deps.reporter.*`, `deps.resolve`, etc.).
+ */
+export function makeGateRunner(
+  overrides: {
+    resolveResult?: PermissionCheckResult;
+    resolve?: ScopedPermissionResolver["resolve"];
+    resolvePathPolicy?: ScopedPermissionResolver["resolvePathPolicy"];
+    recordSessionApproval?: SessionApprovalRecorder["recordSessionApproval"];
+    recordPersistentApproval?: PersistentApprovalRecorder["recordApproval"];
+    canConfirm?: GatePrompter["canConfirm"];
+    prompt?: GatePrompter["prompt"];
+    reporter?: Partial<DecisionReporter>;
+  } = {},
+) {
+  const reporter = makeReporter(overrides.reporter);
+  const resolve =
+    overrides.resolve ??
+    vi
+      .fn<ScopedPermissionResolver["resolve"]>()
+      .mockReturnValue(
+        overrides.resolveResult ?? makeCheckResult({ matchedPattern: "*" }),
+      );
+  const resolvePathPolicy =
+    overrides.resolvePathPolicy ??
+    vi
+      .fn<ScopedPermissionResolver["resolvePathPolicy"]>()
+      .mockReturnValue(
+        overrides.resolveResult ?? makeCheckResult({ matchedPattern: "*" }),
+      );
+  const recordSessionApproval =
+    overrides.recordSessionApproval ??
+    (vi.fn() as SessionApprovalRecorder["recordSessionApproval"]);
+  const recordPersistentApproval =
+    overrides.recordPersistentApproval ??
+    (vi.fn() as PersistentApprovalRecorder["recordApproval"]);
+  const canConfirm =
+    overrides.canConfirm ??
+    (vi.fn().mockReturnValue(true) as GatePrompter["canConfirm"]);
+  const prompt =
+    overrides.prompt ??
+    vi
+      .fn<GatePrompter["prompt"]>()
+      .mockResolvedValue({ approved: true, state: "approved" });
+  const runner = new GateRunner(
+    { resolve, resolvePathPolicy },
+    { recordSessionApproval },
+    { canConfirm, prompt },
+    reporter,
+    { recordApproval: recordPersistentApproval } as PersistentApprovalRecorder,
+  );
+  return {
+    runner,
+    deps: {
+      resolve,
+      resolvePathPolicy,
+      recordSessionApproval,
+      recordPersistentApproval,
+      canConfirm,
+      prompt,
+      reporter,
+    },
+  };
+}
+
+/**
+ * Gate descriptor variant with write-surface defaults and a caller-supplied
+ * denialContext.
+ *
+ * Use instead of `makeDescriptor` when the test exercises denial-message
+ * formatting — the write surface and its matching promptDetails/logContext
+ * keep the message helpers' field access consistent.
+ */
+export function makeDenialDescriptor(
+  denialContext: DenialContext,
+  overrides: Partial<GateDescriptor> = {},
+): GateDescriptor {
+  return {
+    surface: "write",
+    input: {},
+    denialContext,
+    promptDetails: {
+      source: "tool_call",
+      agentName: null,
+      message: "Allow tool 'write'?",
+      toolCallId: "tc-1",
+      toolName: "write",
+    },
+    logContext: {
+      source: "tool_call",
+      toolCallId: "tc-1",
+      toolName: "write",
+    },
+    decision: {
+      surface: "write",
+      value: "write",
+    },
+    ...overrides,
+  };
+}
+
+/**
+ * Tool-call context factory with bash defaults.
+ *
+ * path.test.ts uses different defaults (toolName "read", path input) and
+ * keeps a local wrapper; bash-path.test.ts uses this factory directly.
+ */
+export function makeTcc(
+  overrides: Partial<ToolCallContext> = {},
+): ToolCallContext {
+  return {
+    toolName: "bash",
+    agentName: null,
+    input: { command: "cat .env" },
+    toolCallId: "tc-1",
+    cwd: "/test/project",
+    ...overrides,
+  };
+}
+
+/**
+ * Resolver whose `resolve` dispatches on `input.path`, falling back to a
+ * default result for any path not in the map.
+ *
+ * Use when a test needs different results for different path tokens without
+ * writing a full `mockImplementation` block.
+ *
+ * Return type is intentionally unannotated so callers retain full `vi.fn()`
+ * mock access (`mock.calls`, `toHaveBeenCalledWith`, etc.).
+ */
+export function makePathDispatchResolver(
+  byPath: Record<string, PermissionCheckResult>,
+  defaultResult: PermissionCheckResult,
+) {
+  const resolve = vi.fn<ScopedPermissionResolver["resolve"]>();
+  resolve.mockImplementation((_surface, input) => {
+    const path = (input as Record<string, unknown>).path;
+    if (typeof path === "string" && path in byPath) {
+      return byPath[path];
+    }
+    return defaultResult;
+  });
+  const resolvePathPolicy =
+    vi.fn<ScopedPermissionResolver["resolvePathPolicy"]>();
+  resolvePathPolicy.mockImplementation((values) => {
+    for (const value of values) {
+      if (value in byPath) return byPath[value];
+    }
+    return defaultResult;
+  });
+  return { resolve, resolvePathPolicy };
+}
+
+/**
+ * Path-surface check result factory.
+ *
+ * Shared between bash-path.test.ts and path.test.ts; both use
+ * toolName "path", source "special", origin "global" as defaults.
+ */
+export function makeGateCheckResult(
+  overrides: Partial<PermissionCheckResult> = {},
+): PermissionCheckResult {
+  return {
+    toolName: "path",
+    state: "allow",
+    source: "special",
+    origin: "global",
+    ...overrides,
+  };
+}
+
+/**
+ * Mock of `ToolCallGateInputs` for `ToolCallGatePipeline` unit tests.
+ *
+ * Each method is a `vi.fn()` stub so callers retain full mock access
+ * (`mock.calls`, `mockReturnValue`, etc.) on the returned object.
+ * Pass `overrides` to replace individual stubs without rebuilding the whole
+ * mock from scratch.
+ */
+export function makeGateInputs(
+  overrides: {
+    getActiveSkillEntries?: () => SkillPromptEntry[];
+    getInfrastructureReadDirs?: () => string[];
+    getToolPreviewLimits?: () => ToolPreviewFormatterOptions;
+  } = {},
+): ToolCallGateInputs {
+  return {
+    getActiveSkillEntries:
+      overrides.getActiveSkillEntries ??
+      vi.fn<() => SkillPromptEntry[]>(() => []),
+    getInfrastructureReadDirs:
+      overrides.getInfrastructureReadDirs ?? vi.fn<() => string[]>(() => []),
+    getToolPreviewLimits:
+      overrides.getToolPreviewLimits ??
+      vi.fn<() => ToolPreviewFormatterOptions>(() => ({
+        toolInputPreviewMaxLength: 500,
+        toolTextSummaryMaxLength: 100,
+        toolInputLogPreviewMaxLength: 200,
+      })),
+  };
+}
+
+/**
+ * Mock of `SkillInputGateInputs` for `SkillInputGatePipeline` unit tests.
+ *
+ * Returns a plain object with a `checkPermission` `vi.fn()` stub so callers
+ * retain full mock access (`mockReturnValue`, `mock.calls`, etc.).
+ */
+export function makeSkillInputInputs(
+  overrides: { checkPermission?: SkillInputGateInputs["checkPermission"] } = {},
+): SkillInputGateInputs {
+  return {
+    checkPermission:
+      overrides.checkPermission ??
+      vi
+        .fn<SkillInputGateInputs["checkPermission"]>()
+        .mockReturnValue(makeCheckResult()),
+  };
+}
+
+/**
+ * Mock `GateNotifier` for `SkillInputGatePipeline` unit tests.
+ *
+ * Return type is intentionally unannotated so callers retain full `vi.fn()`
+ * mock access (`mock.calls`, `toHaveBeenCalledWith`, etc.) — annotating with
+ * `GateNotifier` would erase `Mock<...>` methods from the inferred type.
+ */
+export function makeNotifier() {
+  return {
+    warn: vi.fn<(message: string) => void>(),
+  };
+}

package/test/helpers/handler-fixtures.ts

@@ -0,0 +1,335 @@
+/**
+ * Shared handler-level test fixtures for PermissionGateHandler tests.
+ *
+ * `makeHandler` builds a real PermissionSession + PermissionResolver and wires
+ * them into the handler and pipelines exactly as `index.ts` does.
+ * Call-site overrides for permission results flow through
+ * `permissionManager.checkPermission`; session state overrides are applied
+ * via vi.spyOn on the real session instance.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { vi } from "vitest";
+
+import { GateDecisionReporter } from "#src/decision-reporter";
+import type { GatePrompter } from "#src/gate-prompter";
+import { GateRunner } from "#src/handlers/gates/runner";
+import {
+  type SkillInputGateInputs,
+  SkillInputGatePipeline,
+} from "#src/handlers/gates/skill-input-gate-pipeline";
+import {
+  type ToolCallGateInputs,
+  ToolCallGatePipeline,
+} from "#src/handlers/gates/tool-call-gate-pipeline";
+import { PermissionGateHandler } from "#src/handlers/permission-gate-handler";
+import type { PermissionDecisionEvent } from "#src/permission-events";
+import { PERMISSIONS_DECISION_CHANNEL } from "#src/permission-events";
+import type { Rule } from "#src/rule";
+import { SessionRules } from "#src/session-rules";
+import type { ToolRegistry } from "#src/tool-registry";
+import type { PermissionCheckResult, PermissionState } from "#src/types";
+import {
+  makeRealResolver,
+  makeRealSession,
+} from "#test/helpers/session-fixtures";
+
+// ── MockGateHandlerSession ────────────────────────────────────────────────
+
+/**
+ * Mock type for gate-pipeline inputs (ToolCallGateInputs + SkillInputGateInputs).
+ *
+ * Used by `makeSurfaceCheck`, `makeBashCommandCheck`, and the `session`
+ * override bag in `makeHandler`.  The `GateHandlerSession` role (activate +
+ * resolveAgentName) is now satisfied by the real `PermissionSession`; this
+ * type covers only the pipeline input surface.
+ *
+ * The 4-arg `checkPermission` is a superset of `SkillInputGateInputs` —
+ * it routes through `permissionManager.checkPermission` in production.
+ */
+export type MockGateHandlerSession = ToolCallGateInputs &
+  SkillInputGateInputs & {
+    /** 4-arg form so surface-check mocks can receive optional rules. */
+    checkPermission(
+      surface: string,
+      input: unknown,
+      agentName?: string,
+      rules?: Rule[],
+    ): PermissionCheckResult;
+  };
+
+// ── Small utility factories ───────────────────────────────────────────────
+
+export function makeEvents() {
+  return {
+    emit: vi.fn(),
+    on: vi.fn().mockReturnValue(() => undefined),
+  };
+}
+
+export function makeCtx(
+  overrides: Partial<ExtensionContext> = {},
+): ExtensionContext {
+  return {
+    cwd: "/test/project",
+    hasUI: true,
+    ui: {
+      setStatus: vi.fn(),
+      notify: vi.fn(),
+      select: vi.fn(),
+      input: vi.fn(),
+    },
+    sessionManager: {
+      getEntries: vi.fn().mockReturnValue([]),
+      getSessionDir: vi.fn().mockReturnValue("/sessions/test"),
+      addEntry: vi.fn(),
+    },
+    ...overrides,
+  } as unknown as ExtensionContext;
+}
+
+export function makeToolCallEvent(
+  toolName: string,
+  extraFields: Record<string, unknown> = {},
+) {
+  return {
+    type: "tool_call",
+    toolCallId: "tc-1",
+    name: toolName,
+    input: {},
+    ...extraFields,
+  };
+}
+
+/**
+ * Neutral-default check-result builder.
+ *
+ * Pass exactly the fields the original fixture hard-coded so divergent
+ * defaults across test files are preserved at their call sites.
+ */
+export function makeCheckResult(
+  overrides: Partial<PermissionCheckResult> = {},
+): PermissionCheckResult {
+  return {
+    state: "allow",
+    toolName: "read",
+    source: "tool",
+    origin: "builtin",
+    ...overrides,
+  };
+}
+
+export function makeToolRegistry(
+  overrides: Partial<ToolRegistry> = {},
+): ToolRegistry {
+  return {
+    getAll: vi.fn().mockReturnValue([{ name: "read" }, { name: "bash" }]),
+    getActive: vi.fn().mockReturnValue(["read", "bash"]),
+    setActive: vi.fn(),
+    ...overrides,
+  };
+}
+
+// ── Surface-check factories ────────────────────────────────────────────────
+
+/**
+ * Surface-dispatching `checkPermission` mock.
+ *
+ * Returns the matching per-surface result or `defaultResult`.
+ * Pass the returned function as `session.checkPermission` in a `makeHandler`
+ * override bag — it is applied to `permissionManager.checkPermission`.
+ *
+ * Return type is intentionally unannotated so callers retain full `vi.fn()`
+ * mock access (`mock.calls`, `toHaveBeenCalledWith`, etc.).
+ */
+export function makeSurfaceCheck(
+  bySurface: Record<
+    string,
+    Partial<PermissionCheckResult> & { state: PermissionState }
+  >,
+  defaultResult: Partial<PermissionCheckResult> & { state: PermissionState } = {
+    state: "allow",
+  },
+) {
+  return vi
+    .fn<MockGateHandlerSession["checkPermission"]>()
+    .mockImplementation((surface): PermissionCheckResult => {
+      const base = bySurface[surface] ?? defaultResult;
+      return {
+        toolName: surface,
+        source: "tool",
+        origin: "builtin",
+        ...base,
+      };
+    });
+}
+
+/**
+ * Bash-surface `checkPermission` mock that dispatches on a command regex.
+ *
+ * Pass the returned function as `session.checkPermission` in a `makeHandler`
+ * override bag — it is applied to `permissionManager.checkPermission`.
+ *
+ * Return type is intentionally unannotated so callers retain full `vi.fn()`
+ * mock access.
+ */
+export function makeBashCommandCheck(opts: {
+  deny: RegExp;
+  denyMatched: string;
+  allowMatched?: string;
+}) {
+  return vi
+    .fn<MockGateHandlerSession["checkPermission"]>()
+    .mockImplementation((surface, input): PermissionCheckResult => {
+      if (surface === "bash") {
+        const command = (input as { command?: string }).command ?? "";
+        return opts.deny.test(command)
+          ? makeCheckResult({
+              state: "deny",
+              source: "bash",
+              command,
+              matchedPattern: opts.denyMatched,
+            })
+          : makeCheckResult({
+              state: "allow",
+              source: "bash",
+              command,
+              matchedPattern: opts.allowMatched,
+            });
+      }
+      return makeCheckResult({ state: "allow" });
+    });
+}
+
+// ── makeHandler ────────────────────────────────────────────────────────────
+
+/**
+ * Constructs a PermissionGateHandler wired with real collaborators.
+ *
+ * The `session` override bag maps to the real collaborators:
+ * - `checkPermission` → applied to `permissionManager.checkPermission`
+ * - `getActiveSkillEntries`, `getInfrastructureReadDirs`, `getToolPreviewLimits`
+ *   → applied as vi.spyOn overrides on the real session
+ * - `resolveAgentName` → applied as a vi.spyOn override on the real session
+ *
+ * Returns `{ handler, events, session, toolRegistry, prompter, recorder,
+ * permissionManager, forwarding }` so each test file can destructure only
+ * what it needs.
+ * `session.activate` is not a mock — use `forwarding.start` to assert it
+ * was called.
+ */
+export function makeHandler(overrides?: {
+  session?: Partial<MockGateHandlerSession> & {
+    resolveAgentName?: (
+      ctx: ExtensionContext,
+      systemPrompt?: string,
+    ) => string | null;
+  };
+  /** Override the GatePrompter passed to GateRunner. Defaults to an allow-all stub. */
+  prompter?: GatePrompter;
+  toolRegistry?: Partial<ToolRegistry>;
+  /** Sugar: builds the `getAll` mock from a list of tool names. */
+  tools?: string[];
+}) {
+  const { session, permissionManager, sessionRules, forwarding, logger } =
+    makeRealSession();
+  const { resolver } = makeRealResolver(permissionManager, sessionRules);
+
+  // Apply session override bag to the real collaborators.
+  const so = overrides?.session;
+  const surfaceCheck = so?.checkPermission;
+  if (surfaceCheck) {
+    vi.mocked(permissionManager.checkPermission).mockImplementation(
+      surfaceCheck,
+    );
+    // The bash path and external-directory gates resolve through
+    // checkPathPolicy; route it through the same surface dispatcher (threading
+    // the real surface) so `path` / `external_directory` overrides apply to
+    // bash tokens and tool paths alike (#418).
+    vi.mocked(permissionManager.checkPathPolicy).mockImplementation(
+      (values, agentName, sessionRules, surface = "path") =>
+        surfaceCheck(
+          surface,
+          { path: values[0] ?? "*" },
+          agentName,
+          sessionRules,
+        ),
+    );
+  }
+  if (so?.getActiveSkillEntries) {
+    vi.spyOn(session, "getActiveSkillEntries").mockImplementation(
+      so.getActiveSkillEntries,
+    );
+  }
+  if (so?.getInfrastructureReadDirs) {
+    vi.spyOn(session, "getInfrastructureReadDirs").mockImplementation(
+      so.getInfrastructureReadDirs,
+    );
+  }
+  if (so?.getToolPreviewLimits) {
+    vi.spyOn(session, "getToolPreviewLimits").mockImplementation(
+      so.getToolPreviewLimits,
+    );
+  }
+  if (so?.resolveAgentName) {
+    vi.spyOn(session, "resolveAgentName").mockImplementation(
+      so.resolveAgentName,
+    );
+  }
+
+  const events = makeEvents();
+  const toolRegistry =
+    overrides?.tools !== undefined
+      ? makeToolRegistry({
+          getAll: vi
+            .fn()
+            .mockReturnValue(overrides.tools.map((name) => ({ name }))),
+        })
+      : makeToolRegistry(overrides?.toolRegistry);
+
+  const recorder = new SessionRules();
+  const pipeline = new ToolCallGatePipeline(resolver, session);
+  const skillInputPipeline = new SkillInputGatePipeline(resolver);
+  const reporter = new GateDecisionReporter(logger, events);
+  const prompter: GatePrompter = overrides?.prompter ?? {
+    canConfirm: vi.fn().mockReturnValue(true),
+    prompt: vi
+      .fn<GatePrompter["prompt"]>()
+      .mockResolvedValue({ approved: true, state: "approved" }),
+  };
+  const runner = new GateRunner(
+    resolver,
+    recorder,
+    prompter,
+    reporter,
+    { recordApproval: vi.fn() } as never,
+  );
+  const handler = new PermissionGateHandler(
+    session,
+    toolRegistry,
+    pipeline,
+    skillInputPipeline,
+    runner,
+  );
+  return {
+    handler,
+    events,
+    session,
+    logger,
+    toolRegistry,
+    prompter,
+    recorder,
+    permissionManager,
+    forwarding,
+  };
+}
+
+// ── Decision-event helper ─────────────────────────────────────────────────
+
+/** Extract all permissions:decision payloads from the events.emit mock. */
+export function getDecisionEvents(
+  events: ReturnType<typeof makeEvents>,
+): PermissionDecisionEvent[] {
+  return events.emit.mock.calls
+    .filter(([channel]) => channel === PERMISSIONS_DECISION_CHANNEL)
+    .map(([, payload]) => payload as PermissionDecisionEvent);
+}