@cursor/bdk 0.2.24 → 0.2.25

package/templates/agentic-owners/bot/lib/owners/match.ts

@@ -3,6 +3,7 @@
 
 import { posix } from "node:path";
 import { AGENTIC_OWNERS_DIR } from "./constants.js";
+import { blocksGlobalOverride, mergeGlobalOverride } from "./globalOverride.js";
 import { patternMatchesFile, patternSpecificity } from "./matching.js";
 import type {
   AgenticOwnersMatchedConfig,
@@ -16,6 +17,11 @@ type PathScopedRule = {
   readonly paths: readonly string[];
   /** Root-only repository-wide exemption, produced from `global_exclusions`. */
   readonly globalExclusion?: boolean;
+  /**
+   * Root `global_overrides` entry. Applied after precedence, not as a
+   * candidate for it.
+   */
+  readonly globalOverride?: boolean;
 };
 
 /**
@@ -116,23 +122,84 @@ function compareRulePrecedence(
   return left.sourcePath.localeCompare(right.sourcePath);
 }
 
-function pickWinningRuleForFile<T extends PathScopedRule>({
-  filepath,
-  rules,
-}: {
-  filepath: string;
-  rules: readonly T[];
-}): T | undefined {
-  let winner: T | undefined;
-  for (const rule of rules) {
+function selectRuleForFile(
+  filepath: string,
+  rules: readonly AgenticOwnersPathRule[],
+): {
+  readonly winner: { readonly rule: AgenticOwnersPathRule; readonly order: number } | undefined;
+  readonly overrides: readonly { readonly rule: AgenticOwnersPathRule; readonly order: number }[];
+} {
+  let winner: { readonly rule: AgenticOwnersPathRule; readonly order: number } | undefined;
+  const overrides: { readonly rule: AgenticOwnersPathRule; readonly order: number }[] = [];
+  for (const [order, rule] of rules.entries()) {
     if (!ruleMatchesFile({ rule, filepath })) {
       continue;
     }
-    if (winner === undefined || compareRulePrecedence(rule, winner, filepath) > 0) {
-      winner = rule;
+    if (rule.globalOverride === true) {
+      overrides.push({ rule, order });
+      continue;
+    }
+    if (winner === undefined || compareRulePrecedence(rule, winner.rule, filepath) > 0) {
+      winner = { rule, order };
     }
   }
-  return winner;
+  return { winner, overrides };
+}
+
+function teamsSkippedByOverride(
+  winner: AgenticOwnersPathRule,
+  override: AgenticOwnersPathRule,
+): boolean {
+  const skipped = override.skipTeams;
+  if (skipped === undefined || skipped.length === 0) {
+    return false;
+  }
+  const names = new Set(skipped.map((team) => team.trim().toLowerCase()));
+  return winner.teams.some((team) => names.has(team.trim().toLowerCase()));
+}
+
+function overrideAppliesToFile(
+  override: AgenticOwnersPathRule,
+  winner: AgenticOwnersPathRule,
+  filepath: string,
+): boolean {
+  if (teamsSkippedByOverride(winner, override)) {
+    return false;
+  }
+  const skipPaths = override.skipPaths;
+  if (skipPaths === undefined || skipPaths.length === 0) {
+    return true;
+  }
+  return !ruleMatchesFile({ rule: { ...override, paths: skipPaths }, filepath });
+}
+
+function effectiveRuleSelector(
+  rules: readonly AgenticOwnersPathRule[],
+): (filepath: string) => AgenticOwnersPathRule | undefined {
+  const cache = new Map<string, AgenticOwnersPathRule>();
+  return (filepath) => {
+    const { winner, overrides } = selectRuleForFile(filepath, rules);
+    if (winner === undefined || blocksGlobalOverride(winner.rule)) {
+      return winner?.rule;
+    }
+    const applicable = overrides.filter((entry) =>
+      overrideAppliesToFile(entry.rule, winner.rule, filepath),
+    );
+    if (applicable.length === 0) {
+      return winner.rule;
+    }
+    const key = `${winner.order}:${applicable.map((entry) => entry.order).join(",")}`;
+    const cached = cache.get(key);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const effective = mergeGlobalOverride(
+      winner.rule,
+      applicable.map((entry) => entry.rule),
+    );
+    cache.set(key, effective);
+    return effective;
+  };
 }
 
 export function matchRepoConfigForChangedFiles({
@@ -147,8 +214,9 @@ export function matchRepoConfigForChangedFiles({
   // file path would silently drop one (e.g. a hard-gate rule lost behind an
   // advisory rule from the same policy).
   const winners = new Set<AgenticOwnersPathRule>();
+  const ruleForFile = effectiveRuleSelector(config.rules);
   for (const filepath of changedFiles) {
-    const winner = pickWinningRuleForFile({ filepath, rules: config.rules });
+    const winner = ruleForFile(filepath);
     if (winner !== undefined) {
       winners.add(winner);
     }
@@ -175,9 +243,8 @@ export function changedFilesWithoutWinningRule({
   changedFiles: readonly string[];
   rules: readonly AgenticOwnersPathRule[];
 }): string[] {
-  return changedFiles.filter(
-    (filepath) => pickWinningRuleForFile({ filepath, rules }) === undefined,
-  );
+  const ruleForFile = effectiveRuleSelector(rules);
+  return changedFiles.filter((filepath) => ruleForFile(filepath) === undefined);
 }
 
 /**
@@ -198,9 +265,8 @@ export function everyChangedFileGloballyExcluded({
   if (changedFiles.length === 0) {
     return false;
   }
-  return changedFiles.every(
-    (filepath) => pickWinningRuleForFile({ filepath, rules })?.globalExclusion === true,
-  );
+  const ruleForFile = effectiveRuleSelector(rules);
+  return changedFiles.every((filepath) => ruleForFile(filepath)?.globalExclusion === true);
 }
 
 function hasOwners(rule: AgenticOwnersPathRule): boolean {

package/templates/agentic-owners/bot/lib/owners/parse.ts

@@ -143,6 +143,131 @@ function parseGlobalExclusions({
   return paths;
 }
 
+const GLOBAL_OVERRIDE_KEYS = [
+  "paths",
+  "team",
+  "teams",
+  "user",
+  "users",
+  "self_review",
+  "skip_teams",
+  "skip_paths",
+] as const;
+
+function parseGlobalOverrides({
+  value,
+  sourcePath,
+  issues,
+}: {
+  value: unknown;
+  sourcePath: string;
+  issues: string[];
+}): AgenticOwnersPathRule[] {
+  if (value === undefined) {
+    return [];
+  }
+  if (sourcePath !== ROOT_POLICY_SOURCE_PATH) {
+    issues.push(`${sourcePath}: global_overrides is only allowed in ${ROOT_POLICY_SOURCE_PATH}`);
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    issues.push(`${sourcePath}: global_overrides must be a list`);
+    return [];
+  }
+  const rules: AgenticOwnersPathRule[] = [];
+  for (const [index, entry] of value.entries()) {
+    const label = `${sourcePath}: global_overrides[${index}]`;
+    if (!isRecord(entry)) {
+      issues.push(`${label} must be a mapping`);
+      continue;
+    }
+    const unknownKeys = Object.keys(entry).filter(
+      (key) => !(GLOBAL_OVERRIDE_KEYS as readonly string[]).includes(key),
+    );
+    if (unknownKeys.length > 0) {
+      issues.push(
+        `${label}: unknown key(s) ${unknownKeys.join(", ")} (allowed: ${GLOBAL_OVERRIDE_KEYS.join(", ")})`,
+      );
+    }
+    const paths = parsePaths(entry.paths, `${label}.paths`, issues);
+    const selfReview = parseBooleanField(
+      entry.self_review,
+      `${label}.self_review`,
+      "self_review",
+      issues,
+    );
+    const teams = parseOwnerList({
+      singular: entry.team,
+      plural: entry.teams,
+      label,
+      field: "teams",
+      issues,
+      parseEntry: parseTeamSlug,
+    });
+    const users = parseOwnerList({
+      singular: entry.user,
+      plural: entry.users,
+      label,
+      field: "users",
+      issues,
+      parseEntry: parseUserHandle,
+    });
+    const skipTeams = parseOwnerList({
+      singular: undefined,
+      plural: entry.skip_teams,
+      label,
+      field: "skip_teams",
+      issues,
+      parseEntry: parseTeamSlug,
+    });
+    const skipPaths =
+      entry.skip_paths === undefined
+        ? []
+        : parsePaths(entry.skip_paths, `${label}.skip_paths`, issues);
+    if (paths === undefined || selfReview === undefined || skipPaths === undefined) {
+      continue;
+    }
+    validatePathsStayWithinRepository({
+      paths,
+      sourcePath,
+      label: `${label}.paths`,
+      issues,
+    });
+    validatePathsStayWithinRepository({
+      paths: skipPaths,
+      sourcePath,
+      label: `${label}.skip_paths`,
+      issues,
+    });
+    if (teams.length === 0 && users.length === 0) {
+      issues.push(`${label}: team or user is required`);
+    }
+    if (!selfReview) {
+      issues.push(
+        `${label}: self_review: true is required (an override only lets its owners clear matching files by self-review)`,
+      );
+    }
+    rules.push({
+      sourcePath,
+      scopeDepth: 0,
+      globalOverride: true,
+      paths,
+      teams,
+      users,
+      team: teams[0],
+      user: users[0],
+      prompt: undefined,
+      alwaysApprove: false,
+      mode: "advisory",
+      humanReviewRequired: false,
+      selfReview,
+      ...(skipTeams.length > 0 ? { skipTeams } : {}),
+      ...(skipPaths.length > 0 ? { skipPaths } : {}),
+    });
+  }
+  return rules;
+}
+
 function parsePromptPath(value: unknown, label: string, issues: string[]): string | undefined {
   if (value === undefined) {
     return undefined;
@@ -228,12 +353,12 @@ function parseOwnerList({
   singular: unknown;
   plural: unknown;
   label: string;
-  field: "teams" | "users";
+  field: "teams" | "users" | "skip_teams";
   issues: string[];
   parseEntry: (value: unknown, label: string, issues: string[]) => string | undefined;
 }): string[] {
   const owners: string[] = [];
-  const singularField = field === "teams" ? "team" : "user";
+  const singularField = field === "users" ? "user" : "team";
   const parsedSingular = parseEntry(singular, `${label}.${singularField}`, issues);
   if (parsedSingular !== undefined) {
     owners.push(parsedSingular);
@@ -507,6 +632,11 @@ export function parseAgenticOwnersPolicyYaml({
     sourcePath,
     issues,
   });
+  const globalOverrides = parseGlobalOverrides({
+    value: parsed.global_overrides,
+    sourcePath,
+    issues,
+  });
 
   if (parsed.rules !== undefined) {
     issues.push(`${sourcePath}: use policies instead of rules`);
@@ -548,6 +678,7 @@ export function parseAgenticOwnersPolicyYaml({
     if (rules.length === 0) {
       throw new AgenticOwnersConfigValidationError([`${sourcePath}: policies must not be empty`]);
     }
+    rules.push(...globalOverrides);
     if (globalExclusions.length > 0) {
       rules.push(
         globalExclusionsRule({

package/templates/agentic-owners/bot/lib/owners/types.ts

@@ -12,12 +12,27 @@ export type AgenticOwnersPathRule = {
    * no owners, so they never enroll a review.
    */
   readonly globalExclusion?: boolean;
+  /**
+   * True for a root `global_overrides` entry. These rules are not precedence
+   * candidates. After a file's winning rule is chosen, a matching override
+   * adds its owners to an advisory winner, or becomes the owner when no
+   * committed rule owns the file. `self_review` on the override applies to
+   * the override's owners either way, and does not extend to the existing
+   * winner's owners. Exclusions, always-approve, hard, and notify winners
+   * stay unchanged, as do winners owned by a `skip_teams` team and paths
+   * listed in `skip_paths`.
+   */
+  readonly globalOverride?: boolean;
   /**
    * Glob patterns relative to the directory containing `.agentic-owners`.
    * Root-policy paths are relative to the repository root.
    * Leading `../` segments may address sibling trees but cannot leave the repo.
    */
   readonly paths: readonly string[];
+  /** Teams whose winning rule a `global_overrides` entry must not change. */
+  readonly skipTeams?: readonly string[];
+  /** Paths a `global_overrides` entry must not change. */
+  readonly skipPaths?: readonly string[];
   /**
    * Team slugs (or `org/team` handles) that own these paths. A policy may
    * list more than one. `team` is the first entry, kept for convenience.
@@ -39,6 +54,14 @@ export type AgenticOwnersPathRule = {
   readonly mode: AgenticOwnersPolicyMode;
   readonly humanReviewRequired: boolean;
   readonly selfReview: boolean;
+  /**
+   * Owners who may use {@link selfReview}. Absent means every owner on the
+   * rule. A merged override lists the winner's owners when that rule sets
+   * `self_review`, and the override's owners when the override sets it.
+   */
+  readonly selfReviewTeams?: readonly string[];
+  /** User owners who may use {@link selfReview}. See {@link selfReviewTeams}. */
+  readonly selfReviewUsers?: readonly string[];
 };
 
 export type AgenticOwnersRepoConfig = {