/**
 * pi-ast-guard 配置文件（.pi/ast-guard.yml 或 ~/.pi/agent/ast-guard.yml）的
 * JSON Schema 类型源。
 *
 * 由 ts-json-schema-generator 生成 config/ast-guard.schema.json：
 *   bun run schema
 *
 * 注意：本文件为纯类型声明（d.ts），仅用于 schema 生成，不参与运行时。
 * 约束与解析器 src/policy/parse.ts 保持一致（互斥/必填由解析器校验，schema 尽力表达）。
 */

/** 动作：放行 / 询问 / 拦截。 */
export type PolicyAction = "allow" | "ask" | "block";

/** UI 语言设置：auto 跟随系统。 */
export type LanguageSetting = "auto" | "zh" | "en";

/** DNA 模式（Do Not Ask）下的自动回答动作（ask 无意义，仅 allow/block）。 */
export type DnaAction = "allow" | "block";

/** DNA 模式（Do Not Ask）配置。 */
export interface DnaSettings {
  /** 工具白名单（非空时启用白名单模式，仅允许名单中的工具）。 */
  allowTools?: string[];
  /** 工具黑名单（白名单为空时启用黑名单模式，禁止名单中的工具）。 */
  blockTools?: string[];
  /** 交互被拦截时追加给 AI 的结果说明（不配置时使用内置默认提示）。 */
  cancelledNote?: string;
  /** 附加提示词：DNA 模式下附加给 AI 的提示，让 AI 自动选择方案（如 select/confirm 交互）。不配置时使用内置默认提示。 */
  extraPrompt?: string;
  /** 格式报告 nudge 重试预算（任务结束后未按 REPORT: SUCCESS|FAILURE 收尾时提醒次数，缺省 2，达到后放弃）。 */
  maxNudges?: number;
  /** 本次 DNA 模式下累计自动拒绝的总上限（所有规则含工具黑白名单，缺省 3，达到后强制中断会话并清零计数）。 */
  maxViolations?: number;
  /** Bash/PowerShell 解析失败时 DNA 模式的默认动作（缺省 block）。 */
  parseFailure?: PolicyAction;
  /** 工作区内读的默认动作（缺省 allow）。 */
  readInside?: DnaAction;
  /** 工作区外读的默认动作（缺省 allow）。 */
  readOutside?: DnaAction;
  /** 工作区内写/删/移动的默认动作（缺省 allow）。 */
  writeInside?: DnaAction;
  /** 工作区外写/删/移动的默认动作（缺省 block）。 */
  writeOutside?: DnaAction;
}

/** 策略设置。 */
export interface PolicySettings {
  /** DNA 模式配置。 */
  dna?: DnaSettings;
  /** 额外工作区目录列表；与 cwd 共同构成「完整的工作区」，outsideWorkdir: true 的语义变为「在工作区目录列表之外」。 */
  extraDirs?: string[];
  /** UI 提示语言（zh/en/auto），默认 auto 跟随系统。 */
  language?: LanguageSetting;
  /** Bash 解析失败时的动作。 */
  parseFailure?: PolicyAction;
  /** 是否在状态栏显示 🛡/⚠️ 图标。 */
  showStatus?: boolean;
}

/** 语义化标志匹配（any/all/none 至少一个）。 */
export interface FlagMatcher {
  all?: string[];
  any?: string[];
  none?: string[];
}

/** 子命令检测前的全局选项（如 git -C repo ...，boolean/value 至少一个）。 */
export interface OptionsBeforeSubcommand {
  boolean?: string[];
  value?: string[];
}

/** 操作数数量范围（min/max 至少一个）。 */
export interface OperandCount {
  max?: number;
  min?: number;
}

/** 命令匹配条件：command 与 commandAny 二选一必填；subcommand 与 subcommandAny 互斥。 */
export interface CommandMatch {
  argsAll?: string[];
  argsAny?: string[];
  argsContainAll?: string[];
  argsContainAny?: string[];
  argsNone?: string[];
  command?: string;
  commandAny?: string[];
  dynamic?: boolean;
  flags?: FlagMatcher;
  operandCount?: OperandCount;
  optionsBeforeSubcommand?: OptionsBeforeSubcommand;
  subcommand?: string;
  subcommandAny?: string[];
  visibleTextAll?: string[];
  visibleTextAny?: string[];
  visibleTextNone?: string[];
}

/** 路径模式对象：any 与 outsideWorkdir 二选一。 */
export interface PathPatternObject {
  any?: string | string[];
  except?: string[];
  /** true 时匹配工作区目录列表之外的所有路径（工作区 = cwd + extraDirs）。 */
  outsideWorkdir?: boolean;
}

/** 路径模式：字符串/字符串数组（简写）或对象。 */
export type PathPattern = string | string[] | PathPatternObject;

/** 路径规则 match（仅 path 字段）。 */
export interface PathMatch {
  path: PathPattern;
}

/** 命令规则。 */
export interface CommandRule {
  action?: PolicyAction;
  id: string;
  label?: string;
  match: CommandMatch;
  /** 优先级：值越大越优先（缺省 0）。项目规则 0 / home -0.3 / 默认 -0.6。 */
  priority?: number;
  reason: string;
  type: "command";
}

/** 路径规则类型。 */
export type PathRuleType =
  | "path:zeroAccess"
  | "path:readOnly"
  | "path:noDelete";

/** 路径规则。 */
export interface PathRule {
  action?: PolicyAction;
  id: string;
  label?: string;
  match: PathMatch;
  /** 优先级：值越大越优先（缺省 0）。项目规则 0 / home -0.3 / 默认 -0.6。 */
  priority?: number;
  reason: string;
  type: PathRuleType;
}

/** 规则：命令规则或路径规则。 */
export type Rule = CommandRule | PathRule;

/** 配置文件顶层结构。 */
export interface DamageControlPolicyConfig {
  rules: Rule[];
  settings: PolicySettings;
  /** 历史版本字段，已不区分、可省略。 */
  version?: number;
}