frappe-builder 1.1.0-dev.8

package/extensions/frappe-tools.ts

@@ -0,0 +1,278 @@
+import { Type } from "@sinclair/typebox";
+import { startFeature, completeComponent } from "../tools/feature-tools.js";
+import { setActiveProject, getProjectStatus } from "../tools/project-tools.js";
+import { getAuditLog } from "../state/journal.js";
+import { invokeDebugger, endDebug } from "../tools/debug-tools.js";
+import { spawnAgent } from "../tools/agent-tools.js";
+import { scaffoldDoctype, benchExecute, runTests } from "../tools/bench-tools.js";
+import { frappeQuery } from "../tools/frappe-query-tools.js";
+import { getFrappeDocs } from "../tools/frappe-context7.js";
+
+// pi.registerTool's execute callback is untyped (pi is `any`); params are
+// enforced at runtime via TypeBox schemas. One explicit-any alias avoids
+// noImplicitAny errors across all callbacks without per-line suppressions.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ToolParams = any;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default function (pi: any) {
+  pi.registerTool({
+    name: "start_feature",
+    label: "Start Feature",
+    description:
+      "Creates and names a new feature within the active project, initialising its state in state.db. Valid only in the 'idle' phase.",
+    parameters: Type.Object({
+      name: Type.String({ description: "Feature name (e.g. 'PO Approval')" }),
+      mode: Type.Union([Type.Literal("full"), Type.Literal("quick")], {
+        description: "Workflow mode: 'full' for all phases, 'quick' for rapid delivery",
+      }),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = startFeature(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "complete_component",
+    label: "Complete Component",
+    description:
+      "Marks a feature component as complete in state.db and creates an automatic git checkpoint commit. Valid only in the 'implementation' phase.",
+    parameters: Type.Object({
+      featureId: Type.String({ description: "Feature ID (kebab-case slug, e.g. 'po-approval')" }),
+      componentId: Type.String({ description: "Component ID (e.g. 'auth-module')" }),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = await completeComponent(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "set_active_project",
+    label: "Set Active Project",
+    description:
+      "Switches the active Frappe project and site. Flushes current session state, creates a new session for the target project (restoring prior phase if known), and reloads the system prompt context. Available in any phase.",
+    parameters: Type.Object({
+      projectId: Type.String({ description: "Project identifier (e.g. 'my-frappe-site')" }),
+      sitePath: Type.String({ description: "Absolute path to the Frappe bench site (e.g. '/home/user/frappe-bench/sites/site1.local')" }),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = await setActiveProject(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "invoke_debugger",
+    label: "Invoke Debugger",
+    description:
+      "Loads the frappe-debugger specialist without triggering a phase transition. Valid in any phase (FR34).",
+    parameters: Type.Object({}),
+    execute: async (_toolCallId: string, _params: ToolParams) => {
+      const result = invokeDebugger();
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "end_debug",
+    label: "End Debug",
+    description:
+      "Exits the debugger session and restores the specialist for the preserved phase. Valid in any phase.",
+    parameters: Type.Object({}),
+    execute: async (_toolCallId: string, _params: ToolParams) => {
+      const result = endDebug();
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "spawn_agent",
+    label: "Spawn Agent",
+    description:
+      "Spawns a sub-agent for parallel work. Requires explicit user approval when requirePermission is true in config. Valid in any phase.",
+    parameters: Type.Object({
+      skill: Type.String({ description: "Sub-agent skill name (e.g. 'dev-agent')" }),
+      trigger: Type.String({ description: "Trigger reason (e.g. 'scaffold')" }),
+      reason: Type.String({ description: "Human-readable reason for spawning" }),
+      approved: Type.Optional(Type.Boolean({ description: "User approval decision (set after permission prompt)" })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = await spawnAgent(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "scaffold_doctype",
+    label: "Scaffold DocType",
+    description:
+      "Creates a new Frappe DocType via bench. Valid only in the 'implementation' phase. (Story 4.2 deferred)",
+    parameters: Type.Object({
+      name: Type.String({ description: "DocType name in PascalCase (e.g. 'Purchase Order')" }),
+      module: Type.String({ description: "Frappe module name (e.g. 'Buying')" }),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = scaffoldDoctype(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "run_tests",
+    label: "Run Tests",
+    description:
+      "Runs the Frappe test suite for the active feature via bench. Valid only in the 'testing' phase. (Epic 6)",
+    parameters: Type.Object({
+      featureId: Type.Optional(Type.String({ description: "Feature ID to scope tests (optional)" })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = runTests(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "get_project_status",
+    label: "Get Project Status",
+    description:
+      "Returns a dashboard summary of the active project: features, components, phase, and progress. Available in any phase. (Story 5.2)",
+    parameters: Type.Object({}),
+    execute: async (_toolCallId: string, _params: ToolParams) => {
+      const result = getProjectStatus();
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "frappe_query",
+    label: "Frappe Query",
+    description:
+      "Queries Frappe data via mcp2cli subprocess. Output is routed through the context-mode sandbox — raw payloads never enter the LLM context. Available in any phase.",
+    parameters: Type.Object({
+      doctype: Type.String({ description: "Frappe DocType to query (e.g. 'Sales Order')" }),
+      filters: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
+        description: "Filter key-value pairs (e.g. { status: 'Draft' })",
+      })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = await frappeQuery(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  // 9th tool — outside the 8 core Frappe-semantic tools; bypasses phase guard via ALWAYS_ALLOWED_TOOLS
+  pi.registerTool({
+    name: "get_frappe_docs",
+    label: "Get Frappe Docs",
+    description:
+      "Retrieves compressed Frappe/ERPNext documentation via context7 MCP. Raw web content never enters the LLM context (~90% token reduction). Valid in any phase. (Story 4.4)",
+    parameters: Type.Object({
+      topic: Type.String({ description: "Documentation topic (e.g. 'DocType', 'hooks', 'frappe.db')" }),
+      version: Type.Optional(Type.String({ description: "Frappe version to scope docs (e.g. 'v15')" })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = await getFrappeDocs(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "get_audit_log",
+    label: "Get Audit Log",
+    description:
+      "Queries JSONL audit log entries from session files. Supports filtering by sessionId, featureId, and limit. Available in any phase. (Story 5.3)",
+    parameters: Type.Object({
+      sessionId: Type.Optional(Type.String({ description: "Session ID to query (omit for all sessions)" })),
+      featureId: Type.Optional(Type.String({ description: "Feature ID to filter entries by payload.feature" })),
+      limit: Type.Optional(Type.Number({ description: "Maximum number of entries to return (default: all)" })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = getAuditLog(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  // /status slash command — displays project dashboard (FR21, Story 5.2)
+  // Defensive: pi.registerCommand may not be available in all pi-mono versions
+  if (typeof pi.registerCommand === "function") {
+    pi.registerCommand("status", {
+      description: "Show project dashboard: features, components, phase, and progress",
+      handler: async (_args: string, ctx: Record<string, unknown>) => {
+        const status = getProjectStatus();
+        const lines: string[] = [];
+        if (status.message) {
+          lines.push(status.message);
+        } else {
+          for (const f of status.features) {
+            lines.push(`[${f.phase}] ${f.name} (${f.componentsDone}/${f.componentsTotal} done)`);
+            for (const c of f.components) {
+              const mark = c.status === "complete" ? "✓" : "·";
+              lines.push(`  ${mark} ${c.componentId}`);
+            }
+          }
+        }
+        const output = lines.join("\n") || "No project data";
+        if (ctx.hasUI && ctx.ui && typeof (ctx.ui as Record<string, unknown>).notify === "function") {
+          (ctx.ui as { notify: (msg: string, sev: string) => void }).notify(output, "info");
+        }
+        return output;
+      },
+    });
+  }
+
+  pi.registerTool({
+    name: "bench_execute",
+    label: "Bench Execute",
+    description:
+      "Runs a whitelisted bench command via subprocess. Output sandboxed through context-mode. Valid only in the 'implementation' phase. (Story 4.3)",
+    parameters: Type.Object({
+      command: Type.String({ description: "Bench command (e.g. 'migrate')" }),
+      args: Type.Optional(Type.Array(Type.String(), { description: "Additional arguments" })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = benchExecute(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+}

package/extensions/frappe-ui.ts

@@ -0,0 +1,119 @@
+import type { AfterToolCallContext, AfterToolCallResult } from "@mariozechner/pi-agent-core";
+import { db, getCurrentPhase } from "../state/db.js";
+
+interface FooterState {
+  projectId: string | null;
+  featureName: string | null;
+  phase: string;
+  tokenCount: number;
+}
+
+function readFooterState(): FooterState {
+  try {
+    const session = db
+      .prepare(
+        `SELECT s.project_id, f.name AS feature_name, s.current_phase
+         FROM sessions s
+         LEFT JOIN features f ON f.feature_id = s.feature_id
+         WHERE s.is_active = 1 LIMIT 1`
+      )
+      .get() as
+      | { project_id: string | null; feature_name: string | null; current_phase: string }
+      | undefined;
+
+    // Token count: count journal_entries for active session; table may not exist yet
+    let tokenCount = 0;
+    try {
+      const tokenRow = db
+        .prepare(
+          `SELECT COUNT(*) as count FROM journal_entries
+           WHERE session_id = (SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1)`
+        )
+        .get() as { count: number } | undefined;
+      tokenCount = tokenRow?.count ?? 0;
+    } catch {
+      // journal_entries table not yet created — default to 0
+    }
+
+    return {
+      projectId: session?.project_id ?? null,
+      featureName: session?.feature_name ?? null,
+      phase: session?.current_phase ?? "idle",
+      tokenCount,
+    };
+  } catch {
+    return { projectId: null, featureName: null, phase: "idle", tokenCount: 0 };
+  }
+}
+
+/**
+ * Pure formatting function — no I/O, no side effects.
+ * Exported for unit testing.
+ */
+export function formatFooter(state: FooterState): string {
+  if (!state.projectId) {
+    return `No active project | Phase: ${state.phase}`;
+  }
+  if (!state.featureName) {
+    return `Project: ${state.projectId} | No active feature | Phase: ${state.phase}`;
+  }
+  return `Project: ${state.projectId} | Feature: ${state.featureName} | Phase: ${state.phase} | Tokens: ${state.tokenCount}`;
+}
+
+function renderFooter(): void {
+  try {
+    const state = readFooterState();
+    const line = formatFooter(state);
+    process.stderr.write(`\r\x1b[2K[frappe-builder] ${line}\n`);
+  } catch {
+    // Silently swallow all rendering errors — footer is non-critical
+  }
+}
+
+/**
+ * beforeToolCall announcement hook — writes "→ Calling {tool} [{phase}]" to stderr.
+ * Always returns undefined — this hook only announces, never blocks.
+ * Wrap in try/catch so announcement failure never crashes the session.
+ *
+ * Load order note: frappe-ui must load before frappe-workflow so this fires
+ * before the FSM guard. Load order is controlled by the pi extension list;
+ * package.json "pi" field is currently empty so order is determined by the
+ * pi CLI -e flags at startup.
+ */
+export function handleBeforeToolCall(toolName: string): undefined {
+  try {
+    const phase = getCurrentPhase();
+    process.stderr.write(`→ Calling ${toolName} [${phase}]\n`);
+  } catch {
+    // Swallow — announcement is non-critical, must never block or crash
+  }
+  return undefined;
+}
+
+/**
+ * afterToolCall hook — renders the footer and returns undefined so the
+ * original tool result passes through unmodified.
+ */
+export async function handleAfterToolCall(
+  _context: AfterToolCallContext,
+  _signal?: AbortSignal
+): Promise<AfterToolCallResult | undefined> {
+  renderFooter();
+  return undefined;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default function (pi: any) {
+  pi.on("session_start", () => {
+    renderFooter();
+  });
+
+  // Announcement hook — fires before FSM guard in frappe-workflow.ts (FR25)
+  pi.on("tool_call", (event: { toolName?: string }) => {
+    return handleBeforeToolCall(event.toolName ?? "");
+  });
+
+  pi.on("after_tool_call", async (context: AfterToolCallContext) => {
+    return await handleAfterToolCall(context);
+  });
+}

package/extensions/frappe-workflow.ts

@@ -0,0 +1,85 @@
+import { getCurrentPhase, db } from "../state/db.js";
+import { isToolAllowedInPhase, getValidPhase, type Phase } from "../state/fsm.js";
+import { appendEntry } from "../state/journal.js";
+
+interface BlockedResponse {
+  blocked: true;
+  tool: string;
+  current_phase: Phase;
+  valid_phase: Phase | "any";
+  message: string;
+}
+
+function buildBlockedResponse(
+  tool: string,
+  currentPhase: Phase,
+  validPhase: Phase | "any"
+): BlockedResponse {
+  return {
+    blocked: true,
+    tool,
+    current_phase: currentPhase,
+    valid_phase: validPhase,
+    message: `${tool} is not available in ${currentPhase} phase. Available in: ${validPhase}`,
+  };
+}
+
+/**
+ * Phase guard logic for beforeToolCall. Returns a blocked response if the tool
+ * is not valid in the current phase, undefined to allow.
+ *
+ * Override: if args.override === true, writes a JSONL entry and allows the tool
+ * regardless of phase. Does NOT disable quality gates (frappe-gates.ts).
+ *
+ * Never throws — always returns a value or undefined.
+ */
+// Tools valid in all phases — never blocked by the phase guard (FR34)
+const ALWAYS_ALLOWED_TOOLS = ["invoke_debugger", "end_debug", "spawn_agent", "get_frappe_docs", "get_audit_log"];
+
+export function beforeToolCall(
+  toolName: string,
+  args: Record<string, unknown>
+): BlockedResponse | undefined {
+  // Always-allowed bypass — checked before everything else
+  if (ALWAYS_ALLOWED_TOOLS.includes(toolName)) return undefined;
+
+  const currentPhase = getCurrentPhase() as Phase;
+
+  // Override bypass — checked BEFORE phase guard (FR10 escape hatch)
+  if (args.override === true) {
+    const session = db
+      .prepare("SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1")
+      .get() as { session_id: string } | undefined;
+
+    appendEntry({
+      ts: new Date().toISOString(),
+      sessionId: session?.session_id ?? "unknown",
+      type: "tool_call",
+      payload: {
+        override: true,
+        reason: (args.reason as string) ?? "unspecified",
+        tool: toolName,
+        phase: currentPhase,
+      },
+    });
+    return undefined; // allow
+  }
+
+  // Phase guard
+  if (!isToolAllowedInPhase(toolName, currentPhase)) {
+    return buildBlockedResponse(toolName, currentPhase, getValidPhase(toolName));
+  }
+
+  return undefined; // allow
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default function (pi: any) {
+  pi.on("tool_call", (event: { toolName?: string; input?: Record<string, unknown> }) => {
+    const result = beforeToolCall(event.toolName ?? "", event.input ?? {});
+    if (result) {
+      return { block: true, reason: result.message };
+    }
+    return undefined;
+  });
+}

package/gates/coverage-check.ts

@@ -0,0 +1,37 @@
+/**
+ * gates/coverage-check.ts — Async coverage gate (NOT a pure function).
+ * Runs `bench run-tests --coverage` via execa and parses the result.
+ *
+ * NOT wired via frappe-gates.ts — integrated directly in completeComponent().
+ * Triggers when the final component is completed in `testing` phase. (FR29)
+ */
+import { execa } from "execa";
+import type { GateContext } from "./types.js";
+
+export type CoverageResult =
+  | { passed: true; coverage: number }
+  | { passed: false; coverage: number; required: string; error?: string };
+
+function parseCoverage(stdout: string): number {
+  const match = stdout.match(/^TOTAL\s+\d+\s+\d+\s+(\d+)%/m);
+  return match ? parseInt(match[1], 10) : 0;
+}
+
+export async function coverageCheck(_context: GateContext): Promise<CoverageResult> {
+  try {
+    const { stdout } = await execa("bench", ["run-tests", "--coverage"], {
+      cwd: process.env.FRAPPE_BENCH_PATH ?? process.cwd(),
+      reject: false,      // don't throw on non-zero exit — coverage data may still be in stdout
+      timeout: 120_000,   // 2 minute timeout
+    });
+
+    const coverage = parseCoverage(stdout ?? "");
+
+    if (coverage < 70) {
+      return { passed: false, coverage, required: "70%" };
+    }
+    return { passed: true, coverage };
+  } catch (err) {
+    return { passed: false, coverage: 0, required: "70%", error: (err as Error).message };
+  }
+}

package/gates/frappe-native-check.ts

@@ -0,0 +1,65 @@
+/**
+ * gates/frappe-native-check.ts — pure gate function, no side effects.
+ * No imports from state/, extensions/, or config/.
+ * No async, no db, no I/O. Same input always produces same output.
+ */
+
+export type NativeCheckResult =
+  | { passed: true }
+  | { passed: true; result: "override"; justification: string; detectedPatterns: string[] }
+  | { passed: false; requiresJustification: true; message: string; detectedPatterns: string[] };
+
+export const NON_NATIVE_PATTERNS: { pattern: RegExp; label: string }[] = [
+  // HTTP clients — use frappe.call() or frappe.db instead
+  { pattern: /import\s+axios/, label: "axios (use frappe.call)" },
+  { pattern: /require\(['"]axios['"]\)/, label: "axios (use frappe.call)" },
+  { pattern: /import\s+requests/, label: "requests (use frappe.call)" },
+  { pattern: /from\s+requests\s+import/, label: "requests (use frappe.call)" },
+
+  // Raw database access — use Frappe ORM
+  { pattern: /cursor\.execute\s*\(/, label: "raw SQL cursor (use frappe.db.sql or ORM)" },
+  { pattern: /pymysql|psycopg2|sqlite3\.connect/, label: "direct DB driver (use Frappe ORM)" },
+  { pattern: /mongoose|sequelize|typeorm/i, label: "external ORM (use Frappe DocType)" },
+
+  // Custom auth — use frappe.whitelist()
+  { pattern: /jwt\.sign|jsonwebtoken/, label: "JWT auth (use frappe.whitelist + session)" },
+  { pattern: /passport\.authenticate/, label: "passport auth (use Frappe auth)" },
+
+  // External data processing — use Frappe reports/scripts
+  { pattern: /import\s+pandas/, label: "pandas (use Frappe Script Report)" },
+  { pattern: /import\s+numpy/, label: "numpy (use Frappe computation)" },
+
+  // File system — use Frappe file manager
+  { pattern: /fs\.writeFileSync|fs\.readFileSync/, label: "raw fs (use frappe.get_file_url or File DocType)" },
+
+  // HTTP server — use Frappe whitelisted methods
+  { pattern: /express\(\)|fastapi|flask\.Flask/, label: "external web framework (use Frappe whitelist)" },
+];
+
+/**
+ * Scans `content` for non-Frappe-native patterns.
+ *
+ * - No detected patterns → { passed: true }
+ * - Detected + no justification → { passed: false, requiresJustification: true, ... }
+ * - Detected + justification provided → { passed: true, result: "override", ... }
+ */
+export function checkFrappeNative(content: string, justification?: string): NativeCheckResult {
+  const detectedPatterns = NON_NATIVE_PATTERNS
+    .filter(({ pattern }) => pattern.test(content))
+    .map(({ label }) => label);
+
+  if (detectedPatterns.length === 0) {
+    return { passed: true };
+  }
+
+  if (justification) {
+    return { passed: true, result: "override", justification, detectedPatterns };
+  }
+
+  return {
+    passed: false,
+    requiresJustification: true,
+    message: "This uses a non-Frappe-native approach. Justification required to proceed.",
+    detectedPatterns,
+  };
+}

package/gates/permission-check.ts

@@ -0,0 +1,65 @@
+/**
+ * gates/permission-check.ts — Pure gate function, no side effects.
+ * No imports from state/, extensions/, or config/.
+ * No async, no db, no I/O. Same input always produces same output.
+ *
+ * Scans Python code for @frappe.whitelist() decorated methods that lack
+ * a permission check inside their function body. (FR26)
+ */
+import type { GateContext, GateResult } from "./types.js";
+
+const PERMISSION_PATTERNS = [
+  /frappe\.has_permission\s*\(/,
+  /frappe\.only_for\s*\(/,
+  /frappe\.check_permission\s*\(/,
+  /frappe\.has_role\s*\(/,
+  /frappe\.session\.user/,
+];
+
+function getLineNumber(code: string, offset: number): number {
+  return code.slice(0, offset).split("\n").length;
+}
+
+function extractFunctionBody(code: string, defStart: number): string {
+  const bodyStart = code.indexOf("\n", defStart) + 1;
+  // Find next top-level def/class/decorator (at column 0)
+  const nextTopLevel = /\n(?=def |class |@)/g;
+  nextTopLevel.lastIndex = bodyStart;
+  const match = nextTopLevel.exec(code);
+  return match ? code.slice(bodyStart, match.index) : code.slice(bodyStart);
+}
+
+function hasPermissionCheck(body: string): boolean {
+  return PERMISSION_PATTERNS.some((p) => p.test(body));
+}
+
+export function permissionCheck(code: string, context: GateContext): GateResult {
+  // Only scan Python files
+  if (!context.file.endsWith(".py")) return { passed: true };
+
+  // Find all @frappe.whitelist(...) followed by a def
+  const WHITELIST_DECORATOR = /@frappe\.whitelist\([^)]*\)\s*\ndef\s+(\w+)/g;
+
+  const violations: Array<{ method: string; line: number; reason: string }> = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = WHITELIST_DECORATOR.exec(code)) !== null) {
+    const decoratorOffset = match.index;
+    const methodName = match[1];
+    const line = getLineNumber(code, decoratorOffset);
+
+    // defStart: position of "def " within the full match
+    const defStart = code.indexOf("\ndef ", decoratorOffset) + 1;
+    const body = extractFunctionBody(code, defStart);
+
+    if (!hasPermissionCheck(body)) {
+      violations.push({ method: methodName, line, reason: "missing permission check" });
+    }
+  }
+
+  if (violations.length > 0) {
+    return { passed: false, violations };
+  }
+
+  return { passed: true };
+}