@cursor/july 0.1.55 → 0.1.61

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

@@ -0,0 +1,589 @@
+// Vendored from the Agentic Owners policy core; see README.md in this
+// directory for the deliberate divergences. Validation semantics for the
+// committed policy files this template reads must stay identical to the
+// source's. Bare team slugs stay bare (no hardcoded-org prefix) — the agent
+// resolves them against the watched repository's owner at actuation.
+
+import yaml from "yaml";
+import {
+  AGENTIC_OWNERS_CONFIG_VERSION,
+  AGENTIC_OWNERS_DIR,
+  AGENTIC_OWNERS_GENERATED_DIR,
+  AGENTIC_OWNERS_POLICY_FILE,
+  ROOT_POLICY_SOURCE_PATH,
+} from "./constants.js";
+import {
+  parseAgenticOwnersPolicyMode,
+  resolvePolicyModeFromFields,
+} from "./policyMode.js";
+import type { AgenticOwnersPathRule } from "./types.js";
+
+/**
+ * True when `filepath` lives under the generated policy directory
+ * (`.agentic-owners/generated/`). These files are produced at review time
+ * (e.g. the CI runner's CODEOWNERS codemod) and must be excluded from the
+ * agent's changed-file set even if they somehow appear in the diff.
+ */
+export function isGeneratedAgenticOwnersPath(filepath: string): boolean {
+  const normalized = filepath.replace(/^\/+/, "");
+  return (
+    normalized === AGENTIC_OWNERS_GENERATED_DIR ||
+    normalized.startsWith(`${AGENTIC_OWNERS_GENERATED_DIR}/`)
+  );
+}
+
+/**
+ * Every `.agentic-owners/policy.yml` path that could govern the changed
+ * files: the root policy plus one candidate per ancestor directory.
+ */
+export function listAgenticOwnersConfigPathsForChangedFiles(
+  changedFiles: readonly string[]
+): string[] {
+  const paths = new Set<string>([
+    `${AGENTIC_OWNERS_DIR}/${AGENTIC_OWNERS_POLICY_FILE}`,
+  ]);
+
+  for (const filepath of changedFiles) {
+    const normalized = filepath.replace(/^\/+/, "");
+    const segments = normalized.split("/");
+    for (let index = 0; index < segments.length; index += 1) {
+      const prefix = segments.slice(0, index).join("/");
+      const base =
+        prefix === "" ? AGENTIC_OWNERS_DIR : `${prefix}/${AGENTIC_OWNERS_DIR}`;
+      paths.add(`${base}/${AGENTIC_OWNERS_POLICY_FILE}`);
+    }
+  }
+
+  return [...paths].sort();
+}
+
+export class AgenticOwnersConfigValidationError extends Error {
+  readonly issues: readonly string[];
+
+  constructor(issues: readonly string[]) {
+    const message =
+      issues.length === 1
+        ? issues[0]!
+        : `Agentic Owners config validation failed:\n- ${issues.join("\n- ")}`;
+    super(message);
+    this.name = "AgenticOwnersConfigValidationError";
+    this.issues = issues;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseVersion(
+  value: unknown,
+  label: string,
+  issues: string[]
+): number | undefined {
+  if (value === undefined) {
+    issues.push(`${label}: missing version`);
+    return undefined;
+  }
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    issues.push(`${label}: version must be an integer`);
+    return undefined;
+  }
+  if (value !== AGENTIC_OWNERS_CONFIG_VERSION) {
+    issues.push(
+      `${label}: unsupported version ${value} (expected ${AGENTIC_OWNERS_CONFIG_VERSION})`
+    );
+    return undefined;
+  }
+  return value;
+}
+
+function parsePaths(
+  value: unknown,
+  label: string,
+  issues: string[]
+): string[] | undefined {
+  if (value === undefined) {
+    issues.push(`${label}: missing paths`);
+    return undefined;
+  }
+  if (
+    !Array.isArray(value) ||
+    value.some((entry) => typeof entry !== "string")
+  ) {
+    issues.push(`${label}: paths must be a list of strings`);
+    return undefined;
+  }
+  const paths = value
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== "");
+  if (paths.length === 0) {
+    issues.push(`${label}: paths must not be empty`);
+    return undefined;
+  }
+  return paths;
+}
+
+function parseGlobalExclusions({
+  value,
+  sourcePath,
+  issues,
+}: {
+  value: unknown;
+  sourcePath: string;
+  issues: string[];
+}): string[] {
+  if (value === undefined) {
+    return [];
+  }
+  if (sourcePath !== ROOT_POLICY_SOURCE_PATH) {
+    issues.push(
+      `${sourcePath}: global_exclusions is only allowed in ${ROOT_POLICY_SOURCE_PATH}`
+    );
+    return [];
+  }
+  return parsePaths(value, `${sourcePath}: global_exclusions`, issues) ?? [];
+}
+
+function parsePromptPath(
+  value: unknown,
+  label: string,
+  issues: string[]
+): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "string") {
+    issues.push(`${label}: prompt must be a string filename`);
+    return undefined;
+  }
+  const prompt = value.trim();
+  if (prompt === "") {
+    issues.push(`${label}: prompt must not be empty`);
+    return undefined;
+  }
+  if (
+    prompt.startsWith("/") ||
+    prompt.includes("/") ||
+    prompt.includes("\\") ||
+    prompt.includes("..")
+  ) {
+    issues.push(
+      `${label}: prompt must be a filename in the same directory as policy.yml (no paths)`
+    );
+    return undefined;
+  }
+  return prompt;
+}
+
+function parseTeamSlug(
+  value: unknown,
+  label: string,
+  issues: string[]
+): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    issues.push(`${label}: team must be a non-empty team slug`);
+    return undefined;
+  }
+  const team = value.trim().replace(/^@/, "");
+  if (team.includes("/")) {
+    // GitHub team handle form (`org/team`) — names a GitHub team directly.
+    if (!/^[^/\s]+\/[^/\s]+$/.test(team)) {
+      issues.push(
+        `${label}: team must be a team slug or a "org/team" GitHub handle`
+      );
+      return undefined;
+    }
+    return team;
+  }
+  return team;
+}
+
+function parseUserHandle(
+  value: unknown,
+  label: string,
+  issues: string[]
+): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    issues.push(`${label}: user must be a non-empty GitHub handle`);
+    return undefined;
+  }
+  const user = value.trim();
+  if (user.includes("/") || user.startsWith("@")) {
+    issues.push(
+      `${label}: user must be a GitHub handle without org prefix or @`
+    );
+    return undefined;
+  }
+  return user;
+}
+
+/** Dedupe while preserving first-seen order. */
+function dedupe(values: readonly string[]): string[] {
+  return [...new Set(values)];
+}
+
+/**
+ * Resolve the owners for one policy record from the singular (`team`/`user`)
+ * and plural (`teams`/`users`) forms. Both may be present; entries are merged
+ * (singular first) and deduped. Each entry is validated with the same rules as
+ * the singular form.
+ */
+function parseOwnerList({
+  singular,
+  plural,
+  label,
+  field,
+  issues,
+  parseEntry,
+}: {
+  singular: unknown;
+  plural: unknown;
+  label: string;
+  field: "teams" | "users";
+  issues: string[];
+  parseEntry: (
+    value: unknown,
+    label: string,
+    issues: string[]
+  ) => string | undefined;
+}): string[] {
+  const owners: string[] = [];
+  const singularField = field === "teams" ? "team" : "user";
+  const parsedSingular = parseEntry(
+    singular,
+    `${label}.${singularField}`,
+    issues
+  );
+  if (parsedSingular !== undefined) {
+    owners.push(parsedSingular);
+  }
+  if (plural !== undefined) {
+    if (
+      !Array.isArray(plural) ||
+      plural.some((entry) => typeof entry !== "string")
+    ) {
+      issues.push(`${label}.${field}: ${field} must be a list of strings`);
+    } else {
+      for (const [index, entry] of plural.entries()) {
+        const parsed = parseEntry(entry, `${label}.${field}[${index}]`, issues);
+        if (parsed !== undefined) {
+          owners.push(parsed);
+        }
+      }
+    }
+  }
+  return dedupe(owners);
+}
+
+function parseBooleanField(
+  value: unknown,
+  label: string,
+  field: string,
+  issues: string[]
+): boolean | undefined {
+  if (value === undefined) {
+    return false;
+  }
+  if (typeof value !== "boolean") {
+    issues.push(`${label}: ${field} must be a boolean`);
+    return undefined;
+  }
+  return value;
+}
+
+function rejectLegacyPolicyFields(
+  record: Record<string, unknown>,
+  label: string,
+  issues: string[]
+): void {
+  if (record.rules !== undefined) {
+    issues.push(`${label}: use top-level policies instead of rules`);
+  }
+  if (record.required_approvers !== undefined) {
+    issues.push(
+      `${label}: required_approvers is no longer supported; set team and human_review_required`
+    );
+  }
+  if (record.review_required !== undefined) {
+    issues.push(
+      `${label}: review_required is no longer supported; use human_review_required`
+    );
+  }
+  if (record.prompt_file !== undefined) {
+    issues.push(
+      `${label}: prompt_file is no longer supported; use prompt: <filename>`
+    );
+  }
+}
+
+function scopeDepthForConfigPath(configPath: string): number {
+  const marker = `/${AGENTIC_OWNERS_DIR}/`;
+  const index = configPath.lastIndexOf(marker);
+  if (index <= 0) {
+    return 0;
+  }
+  const prefix = configPath.slice(0, index);
+  if (prefix === "") {
+    return 0;
+  }
+  return prefix.split("/").filter((segment) => segment !== "").length;
+}
+
+function parsePolicyRecord({
+  record,
+  sourcePath,
+  label,
+  issues,
+}: {
+  record: Record<string, unknown>;
+  sourcePath: string;
+  label: string;
+  issues: string[];
+}): AgenticOwnersPathRule | undefined {
+  rejectLegacyPolicyFields(record, label, issues);
+
+  const paths = parsePaths(record.paths, `${label}.paths`, issues);
+  const alwaysApprove = parseBooleanField(
+    record.always_approve,
+    `${label}.always_approve`,
+    "always_approve",
+    issues
+  );
+  const humanReviewRequired = parseBooleanField(
+    record.human_review_required,
+    `${label}.human_review_required`,
+    "human_review_required",
+    issues
+  );
+  const parsedMode = parseAgenticOwnersPolicyMode(
+    record.mode,
+    `${label}.mode`,
+    issues
+  );
+  const selfReview = parseBooleanField(
+    record.self_review,
+    `${label}.self_review`,
+    "self_review",
+    issues
+  );
+  const prompt = parsePromptPath(record.prompt, `${label}.prompt`, issues);
+  const teams = parseOwnerList({
+    singular: record.team,
+    plural: record.teams,
+    label,
+    field: "teams",
+    issues,
+    parseEntry: parseTeamSlug,
+  });
+  const users = parseOwnerList({
+    singular: record.user,
+    plural: record.users,
+    label,
+    field: "users",
+    issues,
+    parseEntry: parseUserHandle,
+  });
+  if (record.delegated_automations !== undefined) {
+    // Fail loudly rather than validate-and-ignore: nothing in this template
+    // consumes automation-delegated approvals.
+    issues.push(
+      `${label}: delegated_automations is not supported by this template`
+    );
+  }
+
+  if (
+    paths === undefined ||
+    alwaysApprove === undefined ||
+    humanReviewRequired === undefined ||
+    selfReview === undefined
+  ) {
+    return undefined;
+  }
+
+  const mode = resolvePolicyModeFromFields({
+    mode: parsedMode,
+    humanReviewRequired,
+    label,
+    issues,
+  });
+  if (mode === undefined) {
+    return undefined;
+  }
+
+  const scopeDepth = scopeDepthForConfigPath(sourcePath);
+
+  if (
+    alwaysApprove &&
+    (teams.length > 0 ||
+      users.length > 0 ||
+      prompt !== undefined ||
+      humanReviewRequired ||
+      selfReview ||
+      parsedMode !== undefined)
+  ) {
+    issues.push(
+      `${label}: always_approve cannot be combined with owners, prompt, human_review_required, self_review, or mode`
+    );
+  }
+
+  if (
+    !alwaysApprove &&
+    !humanReviewRequired &&
+    teams.length === 0 &&
+    users.length === 0
+  ) {
+    issues.push(
+      scopeDepth === 0
+        ? `${label}: ownerless root policies must use global_exclusions or set always_approve: true`
+        : `${label}: ownerless nested policies must set always_approve: true`
+    );
+  }
+
+  if (humanReviewRequired && teams.length === 0 && users.length === 0) {
+    issues.push(
+      `${label}: team(s) or user(s) is required when human_review_required is true`
+    );
+  }
+
+  if (
+    mode === "notify" &&
+    !alwaysApprove &&
+    teams.length === 0 &&
+    users.length === 0
+  ) {
+    issues.push(`${label}: team(s) or user(s) is required when mode is notify`);
+  }
+
+  return {
+    sourcePath,
+    scopeDepth,
+    paths,
+    teams,
+    users,
+    team: teams[0],
+    user: users[0],
+    prompt,
+    alwaysApprove,
+    mode,
+    humanReviewRequired: mode === "hard",
+    selfReview,
+  };
+}
+
+function globalExclusionsRule({
+  sourcePath,
+  paths,
+}: {
+  sourcePath: string;
+  paths: readonly string[];
+}): AgenticOwnersPathRule {
+  return {
+    sourcePath,
+    scopeDepth: 0,
+    globalExclusion: true,
+    paths,
+    teams: [],
+    users: [],
+    prompt: undefined,
+    alwaysApprove: true,
+    mode: "advisory",
+    humanReviewRequired: false,
+    selfReview: false,
+  };
+}
+
+export function parseAgenticOwnersPolicyYaml({
+  sourcePath,
+  contents,
+}: {
+  sourcePath: string;
+  contents: string;
+}): AgenticOwnersPathRule[] {
+  const issues: string[] = [];
+  let parsed: unknown;
+  try {
+    parsed = yaml.parse(contents);
+  } catch (error) {
+    throw new AgenticOwnersConfigValidationError([
+      `${sourcePath}: invalid YAML (${error instanceof Error ? error.message : String(error)})`,
+    ]);
+  }
+
+  if (!isRecord(parsed)) {
+    throw new AgenticOwnersConfigValidationError([
+      `${sourcePath}: root must be a mapping`,
+    ]);
+  }
+
+  parseVersion(parsed.version, sourcePath, issues);
+  const globalExclusions = parseGlobalExclusions({
+    value: parsed.global_exclusions,
+    sourcePath,
+    issues,
+  });
+
+  if (parsed.rules !== undefined) {
+    issues.push(`${sourcePath}: use policies instead of rules`);
+  }
+  if (parsed.required_approvers !== undefined) {
+    issues.push(
+      `${sourcePath}: required_approvers is no longer supported; use policies with team and human_review_required`
+    );
+  }
+  if (parsed.review_required !== undefined) {
+    issues.push(
+      `${sourcePath}: review_required is no longer supported; use human_review_required`
+    );
+  }
+
+  const policiesValue = parsed.policies;
+  if (policiesValue === undefined) {
+    issues.push(`${sourcePath}: missing policies`);
+  } else if (!Array.isArray(policiesValue)) {
+    issues.push(`${sourcePath}: policies must be a list`);
+  } else {
+    const rules: AgenticOwnersPathRule[] = [];
+    for (const [index, entry] of policiesValue.entries()) {
+      if (!isRecord(entry)) {
+        issues.push(`${sourcePath}: policies[${index}] must be a mapping`);
+        continue;
+      }
+      const rule = parsePolicyRecord({
+        record: entry,
+        sourcePath,
+        label: `${sourcePath}: policies[${index}]`,
+        issues,
+      });
+      if (rule !== undefined) {
+        rules.push(rule);
+      }
+    }
+    if (issues.length > 0) {
+      throw new AgenticOwnersConfigValidationError(issues);
+    }
+    if (rules.length === 0) {
+      throw new AgenticOwnersConfigValidationError([
+        `${sourcePath}: policies must not be empty`,
+      ]);
+    }
+    if (globalExclusions.length > 0) {
+      rules.push(
+        globalExclusionsRule({
+          sourcePath,
+          paths: globalExclusions,
+        })
+      );
+    }
+    return rules;
+  }
+
+  throw new AgenticOwnersConfigValidationError(
+    issues.length > 0 ? issues : [`${sourcePath}: missing policies`]
+  );
+}

package/templates/agentic-owners/agent/lib/owners/policyMode.ts

@@ -0,0 +1,65 @@
+/** Explicit review enforcement on a `.agentic-owners` policy rule. */
+export type AgenticOwnersPolicyMode = "hard" | "advisory" | "notify";
+
+const POLICY_MODES: readonly AgenticOwnersPolicyMode[] = [
+  "hard",
+  "advisory",
+  "notify",
+];
+
+export function parseAgenticOwnersPolicyMode(
+  value: unknown,
+  label: string,
+  issues: string[]
+): AgenticOwnersPolicyMode | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "string") {
+    issues.push(`${label}: mode must be hard, advisory, or notify`);
+    return undefined;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!POLICY_MODES.includes(normalized as AgenticOwnersPolicyMode)) {
+    issues.push(`${label}: mode must be hard, advisory, or notify`);
+    return undefined;
+  }
+  return normalized as AgenticOwnersPolicyMode;
+}
+
+export function resolvePolicyModeFromFields(args: {
+  mode: AgenticOwnersPolicyMode | undefined;
+  humanReviewRequired: boolean;
+  label: string;
+  issues: string[];
+}): AgenticOwnersPolicyMode | undefined {
+  const { mode, humanReviewRequired, label, issues } = args;
+  if (mode === undefined) {
+    return humanReviewRequired ? "hard" : "advisory";
+  }
+  if (humanReviewRequired && mode !== "hard") {
+    issues.push(
+      `${label}: human_review_required: true requires mode: hard (or omit mode)`
+    );
+  }
+  return mode;
+}
+
+export function ruleIsHardGate(rule: {
+  readonly mode?: AgenticOwnersPolicyMode;
+  readonly humanReviewRequired: boolean;
+}): boolean {
+  if (rule.mode === "notify") {
+    return false;
+  }
+  if (rule.mode === "hard") {
+    return true;
+  }
+  return rule.humanReviewRequired;
+}
+
+export function ruleIsNotifyOnly(rule: {
+  readonly mode?: AgenticOwnersPolicyMode;
+}): boolean {
+  return rule.mode === "notify";
+}

package/templates/agentic-owners/agent/lib/owners/prompt.ts

@@ -0,0 +1,66 @@
+// Vendored from the Agentic Owners policy core; see README.md in this
+// directory.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { AGENTIC_OWNERS_MAX_COMPOSED_PROMPT_CHARS } from "./constants.js";
+import { AgenticOwnersConfigValidationError } from "./parse.js";
+import type { AgenticOwnersPathRule } from "./types.js";
+
+/** Cap the embedded diff so a huge PR cannot blow the model context budget. */
+export const DEFAULT_MAX_DIFF_CHARS = 200_000;
+
+/**
+ * Base review prompt that EVERY review starts with, shipped as an in-tree
+ * asset so it deploys with the agent. Edit it to tune the risk rubric.
+ */
+export const BASE_REVIEW_PROMPT_PATH: string = join(
+  import.meta.dirname,
+  "prompts",
+  "base-review.md"
+);
+
+export function readBaseReviewPrompt(): string {
+  return readFileSync(BASE_REVIEW_PROMPT_PATH, "utf8").trim();
+}
+
+/**
+ * Compose the review prompt: the always-applied base prompt as the starting
+ * block, followed by any matched per-rule prompts in order.
+ *
+ * The base prompt is always included (even when `rulePrompts` is empty) and is
+ * counted toward {@link AGENTIC_OWNERS_MAX_COMPOSED_PROMPT_CHARS}.
+ */
+export function composeReviewPrompt(args: {
+  basePrompt: string;
+  rulePrompts: readonly string[];
+}): string {
+  const parts = [args.basePrompt, ...args.rulePrompts].filter(
+    (part) => part !== ""
+  );
+  const composed = parts.join("\n\n");
+  if (composed.length > AGENTIC_OWNERS_MAX_COMPOSED_PROMPT_CHARS) {
+    throw new AgenticOwnersConfigValidationError([
+      `composed prompt (base + matched rules) is ${composed.length} characters, exceeding the limit of ${AGENTIC_OWNERS_MAX_COMPOSED_PROMPT_CHARS}`,
+    ]);
+  }
+  return composed;
+}
+
+export function describeRuleForContext(rule: AgenticOwnersPathRule): string {
+  const parts: string[] = [`paths=[${rule.paths.join(", ")}]`];
+  if (rule.teams.length > 0) {
+    parts.push(`teams=[${rule.teams.join(", ")}]`);
+  }
+  if (rule.users.length > 0) {
+    parts.push(`users=[${rule.users.join(", ")}]`);
+  }
+  if (rule.alwaysApprove) {
+    parts.push("always_approve");
+  }
+  parts.push(`mode=${rule.mode}`);
+  if (rule.selfReview) {
+    parts.push("self_review");
+  }
+  return `${rule.sourcePath} (${parts.join(", ")})`;
+}