// ── Document definitions ──────────────────────────────────────────────

/** Canonical document names managed by docgraph */
export const DOC_NAMES = [
  "README.md",
  "AGENTS.md",
  "docs/SPEC.md",
  "docs/ARCHITECTURE.md",
  "docs/API.md",
  "docs/DESIGN.md",
  "docs/ROADMAP.md",
  "docs/BACKLOG.md",
] as const;

export type DocName = (typeof DOC_NAMES)[number];

/** Metadata block present at the top of every managed document */
export interface DocMetadata {
  purpose: string;
  audience: "Human" | "AI" | "Both";
  sourceOfTruth: string;
  lastUpdated: string;
  dependsOn: string[];
  referencedBy: string[];
}

/** Parsed document with its metadata and body */
export interface DocEntry {
  path: DocName;
  metadata: DocMetadata;
  body: string;
}

// ── Ticket definitions ─────────────────────────────────────────────────

export type TicketStatus = "backlog" | "ready" | "in-progress" | "review" | "done" | "blocked";

export type TicketPriority = "P0" | "P1" | "P2" | "P3";

export interface Ticket {
  id: string;
  title: string;
  status: TicketStatus;
  priority: TicketPriority;
  estimate?: string;
  dependencies: string[];
  context: string;
  /** Original context/requirements are preserved when the ticket is updated. */
  acceptanceCriteria: ChecklistItem[];
  definitionOfDone: ChecklistItem[];
  /** Dated, append-only completion notes added when a ticket is marked done. */
  implementationNotes: string[];
  relatedDocs: string[];
  relatedFiles: string[];
  createdAt: string;
  updatedAt: string;
}

/**
 * A single checklist entry under `## Acceptance Criteria` or `## Definition of
 * Done`. The checkbox state and any verification comment are preserved across
 * parse/serialize round-trips so an implemented ticket is never clobbered back
 * to `- [ ]` and comments never end up stranded on their own line.
 */
export interface ChecklistItem {
  /** Criterion text, without the checkbox marker or verification comment. */
  text: string;
  /** True when the box is marked checked (`[x]`). */
  checked: boolean;
  /**
   * Optional inline HTML comment (e.g. `VERIFIED: ...` or
   * `HUMAN VERIFICATION REQUIRED: ...`), rendered inline after the text so it
   * survives any re-serialization.
   */
  comment: string;
}

// ── Persisted state (stored in tool-result details) ───────────────────

export interface DocgraphState {
  /** Which documents currently exist in the repo */
  initialized: boolean;
  /** Version of the docgraph schema for migrations */
  schemaVersion: number;
}

export interface DocgraphToolDetails {
  action: string;
  state: DocgraphState;
  error?: string;
}

// ── Tool parameter types ──────────────────────────────────────────────

export interface InitParams {
  /** Whether to create scaffolding even on an existing project */
  force?: boolean;
  /** Optional project name override */
  projectName?: string;
}

export interface ReadDocParams {
  path: string;
}

export interface SyncDocParams {
  path: string;
  /** If true, only validate, don't write changes */
  dryRun?: boolean;
}

export interface UpdateDocParams {
  path: string;
  field:
    | "purpose"
    | "audience"
    | "dependsOn"
    | "referencedBy"
    | "body";
  value: string;
}

export interface CreateTicketParams {
  title: string;
  priority: TicketPriority;
  estimate?: string;
  dependencies?: string[];
  context?: string;
  acceptanceCriteria?: string[];
  /** Additional Definition of Done items. The mandatory TDD checklist is always included by default. */
  definitionOfDone?: string[];
  relatedDocs?: string[];
  relatedFiles?: string[];
}

export interface UpdateTicketParams {
  id: string;
  status?: TicketStatus;
  priority?: TicketPriority;
  title?: string;
  context?: string;
  /** Concise note appended to the Implementation Notes section (preserves existing context). */
  implementationNote?: string;
}

export interface ListTicketsParams {
  status?: TicketStatus;
}