@gotgenes/pi-permission-system 18.1.1 → 18.2.0

package/test/helpers/external-directory-fixtures.ts

@@ -1,269 +0,0 @@
-/**
- * Shared fixtures for the external-directory handler-pipeline tests.
- *
- * Targets the collapsed external-directory gate (Phase 6 Step 5, #477).
- * Consumed by external-directory-integration.test.ts and
- * external-directory-session-dedup.test.ts.
- */
-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 { SkillInputGatePipeline } from "#src/handlers/gates/skill-input-gate-pipeline";
-import { ToolCallGatePipeline } from "#src/handlers/gates/tool-call-gate-pipeline";
-import { PermissionGateHandler } from "#src/handlers/permission-gate-handler";
-import type { ScopedPermissionManager } from "#src/permission-manager";
-import type { SessionLogger } from "#src/session-logger";
-import type { PermissionCheckResult, PermissionState } from "#src/types";
-import { wildcardMatch } from "#src/wildcard-matcher";
-
-import {
-  getDecisionEvents,
-  makeEvents,
-  makeSurfaceCheck,
-  makeToolRegistry,
-} from "#test/helpers/handler-fixtures";
-import {
-  makeRealResolver,
-  makeRealSession,
-} from "#test/helpers/session-fixtures";
-
-// ── Shared constants ───────────────────────────────────────────────────────
-
-/** Working-directory used by the external-directory handler-pipeline tests. */
-export const EXT_DIR_CWD = "/test/project";
-
-/** An external path (outside {@link EXT_DIR_CWD}) used across the test suite. */
-export const EXTERNAL_PATH = "/outside/project/file.ts";
-
-/** All path-bearing tools subject to the external-directory gate. */
-export const ALL_PATH_BEARING_TOOLS = [
-  "read",
-  "write",
-  "edit",
-  "find",
-  "grep",
-  "ls",
-];
-
-/** Path-bearing tools where the path is optional (no input → gate is skipped). */
-export const OPTIONAL_PATH_TOOLS = ["find", "grep", "ls"];
-
-/** Full tool set used as the default registry in external-directory tests. */
-export const ALL_TOOLS = [...ALL_PATH_BEARING_TOOLS, "bash"];
-
-// ── Setup builders ─────────────────────────────────────────────────────────
-
-/**
- * Builds a `checkPermission` mock for external-directory tests.
- *
- * Routes `external_directory` to `externalDirectoryState`, `path` to allow
- * with `source: "special"` (so the cross-cutting path gate is transparent),
- * and every other surface to `toolState` (default: allow).
- */
-export function makeExtDirCheck(
-  externalDirectoryState: PermissionState,
-  toolState: PermissionState = "allow",
-) {
-  return makeSurfaceCheck(
-    {
-      external_directory: { state: externalDirectoryState },
-      path: { state: "allow", source: "special" },
-    },
-    { state: toolState },
-  );
-}
-
-/** GatePrompter stub that approves with `state: "approved"`. */
-export function makeApprovingPrompter(): GatePrompter {
-  return {
-    canConfirm: vi.fn().mockReturnValue(true),
-    prompt: vi
-      .fn<GatePrompter["prompt"]>()
-      .mockResolvedValue({ approved: true, state: "approved" }),
-  };
-}
-
-/**
- * GatePrompter stub that denies.
- *
- * Pass `denialReason` to simulate a user who explains the refusal.
- */
-export function makeDenyingPrompter(denialReason?: string): GatePrompter {
-  return {
-    canConfirm: vi.fn().mockReturnValue(true),
-    prompt: vi
-      .fn<GatePrompter["prompt"]>()
-      .mockResolvedValue(
-        denialReason !== undefined
-          ? { approved: false, state: "denied", denialReason }
-          : { approved: false, state: "denied" },
-      ),
-  };
-}
-
-/** GatePrompter stub that reports no UI is available (`canConfirm: false`). */
-export function makeUnavailablePrompter(): GatePrompter {
-  return {
-    canConfirm: vi.fn().mockReturnValue(false),
-    prompt: vi.fn<GatePrompter["prompt"]>(),
-  };
-}
-
-// ── Query helpers ──────────────────────────────────────────────────────────
-
-/** Find the `external_directory` decision event from the events mock. */
-export function findExtDirDecision(events: ReturnType<typeof makeEvents>) {
-  return getDecisionEvents(events).find(
-    (d) => d.surface === "external_directory",
-  );
-}
-
-/** Return the `permission_request.blocked` review-log entries from the logger mock. */
-export function blockReviewEntries(logger: SessionLogger) {
-  return (logger.review as ReturnType<typeof vi.fn>).mock.calls.filter(
-    ([eventName]: string[]) => eventName === "permission_request.blocked",
-  );
-}
-
-// ── Session-dedup wiring ──────────────────────────────────────────────────
-
-/**
- * Installs the session-aware `check(intent)` mock on the permission manager.
- *
- * Returns `ask` for `external_directory` on first access; re-checks recorded
- * session rules on subsequent calls and returns `allow` (source: "session")
- * when a `wildcardMatch` covers the path.
- */
-export function makeExtDirDedupCheck(
-  permissionManager: ScopedPermissionManager,
-): void {
-  vi.mocked(permissionManager.check).mockImplementation(
-    (intent, rules): PermissionCheckResult => {
-      const { surface } = intent;
-      const pathValue =
-        intent.kind === "path-values" ? (intent.values[0] ?? null) : null;
-
-      if (surface === "external_directory") {
-        if (pathValue && rules && rules.length > 0) {
-          const match = rules.findLast(
-            (r) =>
-              r.surface === "external_directory" &&
-              wildcardMatch(r.pattern, pathValue),
-          );
-          if (match) {
-            return {
-              state: "allow",
-              toolName: surface,
-              source: "session",
-              origin: "session",
-              matchedPattern: match.pattern,
-            };
-          }
-        }
-        return {
-          state: "ask",
-          toolName: surface,
-          source: "special",
-          origin: "global",
-        };
-      }
-
-      return {
-        state: "allow",
-        toolName: surface,
-        source: "tool",
-        origin: "builtin",
-      };
-    },
-  );
-}
-
-/** GatePrompter stub that approves for the session (`state: "approved_for_session"`). */
-function makeSessionApprovingPrompter(): GatePrompter {
-  return {
-    canConfirm: vi.fn().mockReturnValue(true),
-    prompt: vi
-      .fn<GatePrompter["prompt"]>()
-      .mockResolvedValue({ approved: true, state: "approved_for_session" }),
-  };
-}
-
-/**
- * Builds the fully-wired session-dedup handler with real collaborators.
- *
- * Unlike `makeHandler`, this wires `makeRealSession` + `makeRealResolver`
- * manually so the caller can access the raw `session` for shutdown tests.
- *
- * Returns `{ handler, prompter, session }`.
- */
-export function makeDedupWiring(prompter?: GatePrompter) {
-  const { session, permissionManager, sessionRules, logger } =
-    makeRealSession();
-  const { resolver } = makeRealResolver(permissionManager, sessionRules);
-  makeExtDirDedupCheck(permissionManager);
-  const events = makeEvents();
-  const reporter = new GateDecisionReporter(logger, events);
-  const resolvedPrompter: GatePrompter =
-    prompter ?? makeSessionApprovingPrompter();
-  const runner = new GateRunner(
-    resolver,
-    sessionRules,
-    resolvedPrompter,
-    reporter,
-  );
-  const handler = new PermissionGateHandler(
-    session,
-    makeToolRegistry({
-      getAll: vi
-        .fn()
-        .mockReturnValue([
-          { name: "read" },
-          { name: "write" },
-          { name: "edit" },
-          { name: "bash" },
-        ]),
-    }),
-    new ToolCallGatePipeline(resolver, session),
-    new SkillInputGatePipeline(resolver),
-    runner,
-  );
-  return { handler, prompter: resolvedPrompter, session };
-}
-
-/**
- * Builds the session-dedup handler without exposing the raw session.
- *
- * Wraps `makeDedupWiring`; returns `{ handler, prompter }`.
- * Use `makeDedupWiring` when the test also needs `session.shutdown()`.
- */
-export function makeDeduplicatingHandler(prompter?: GatePrompter) {
-  const { handler, prompter: resolvedPrompter } = makeDedupWiring(prompter);
-  return { handler, prompter: resolvedPrompter };
-}
-
-// ── Event builders ─────────────────────────────────────────────────────────
-
-/**
- * Builds a tool-call event in the shape that external-directory-session-dedup
- * tests use — `toolName` field (not `name`); both are accepted by
- * `getToolNameFromValue`.
- */
-export function makeExtDirToolEvent(
-  toolName: string,
-  path: string,
-  toolCallId = "tc-1",
-) {
-  return { type: "tool_call" as const, toolCallId, toolName, input: { path } };
-}
-
-/** Builds a bash tool-call event for external-directory session-dedup tests. */
-export function makeExtDirBashEvent(command: string, toolCallId = "tc-1") {
-  return {
-    type: "tool_call" as const,
-    toolCallId,
-    toolName: "bash",
-    input: { command },
-  };
-}

package/test/helpers/gate-fixtures.ts

@@ -1,316 +0,0 @@
-/**
- * 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 { PathNormalizer } from "#src/path-normalizer";
-import type { ScopedPermissionResolver } from "#src/permission-resolver";
-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 { PathRuleTokenMatcher, 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"]>();
-  if (defaultCheck) {
-    resolve.mockReturnValue(defaultCheck);
-  }
-  return { resolve };
-}
-
-/**
- * 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"];
-    recordSessionApproval?: SessionApprovalRecorder["recordSessionApproval"];
-    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 recordSessionApproval =
-    overrides.recordSessionApproval ??
-    (vi.fn() as SessionApprovalRecorder["recordSessionApproval"]);
-  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 },
-    { recordSessionApproval },
-    { canConfirm, prompt },
-    reporter,
-  );
-  return {
-    runner,
-    deps: {
-      resolve,
-      recordSessionApproval,
-      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((intent) => {
-    if (intent.kind === "tool") {
-      const path = (intent.input as Record<string, unknown>).path;
-      if (typeof path === "string" && path in byPath) {
-        return byPath[path];
-      }
-      return defaultResult;
-    }
-    const values = intent.path.matchValues();
-    for (const value of values) {
-      if (value in byPath) return byPath[value];
-    }
-    return defaultResult;
-  });
-  return { resolve };
-}
-
-/**
- * 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;
-    getPathNormalizer?: () => PathNormalizer;
-    getPromotablePathTokenMatcher?: (
-      agentName?: string,
-    ) => PathRuleTokenMatcher;
-  } = {},
-): 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,
-      })),
-    getPathNormalizer:
-      overrides.getPathNormalizer ??
-      vi.fn<() => PathNormalizer>(
-        () => new PathNormalizer(process.platform, "/test/cwd"),
-      ),
-    getPromotablePathTokenMatcher:
-      overrides.getPromotablePathTokenMatcher ??
-      vi.fn<(agentName?: string) => PathRuleTokenMatcher>(() => () => false),
-  };
-}
-
-/**
- * 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>(),
-  };
-}