import type { TtscLintSeverity } from "../TtscLintSeverity";
import type { ITtscLintFormatJsDoc } from "./ITtscLintFormatJsDoc";
import type { ITtscLintFormatSortImports } from "./ITtscLintFormatSortImports";

/**
 * Prettier-style flat configuration for the format rules.
 *
 * The `format` block is the recommended way to enable formatting in
 * `@ttsc/lint`. Each key mirrors a Prettier option of the same name, users
 * coming from a `.prettierrc` can copy their config almost verbatim. The block
 * is opt-in by presence: a `lint.config.ts` with no `format` field keeps every
 * format rule off, exactly as before.
 *
 * Once present, the block configures a curated set of format rules at
 * Prettier-aligned defaults. `ttsc format` uses these rules to rewrite source.
 * `ttsc check` does not report format findings unless `severity` is set to a
 * non-off value. Formatter options belong exclusively to this block; `format/*`
 * entries in the `rules` map are ignored.
 *
 * @evidence contracts/common.md#principled-implementation Optional formatter fields encode presence-based activation and constrained public values; nested import and JSDoc settings preserve their distinct semantics.
 * @evidence contracts/common.md#clear-and-simple-design A flat record handles ordinary options and delegates the two structured options to dedicated types.
 * @evidence contracts/common.md#prohibited-implementation-shortcuts Defaults and customizations use this documented format block rather than hidden fixture-dependent formatting paths or rules-map overrides.
 * @evidence contracts/common.md#meaningful-documentation Native prose explains opt-in activation, check severity, the exclusive format configuration surface and member defaults; separated paragraphs and members follow documentation guidance.
 */
export interface ITtscLintFormat {
  /**
   * Check-time severity for format findings generated from this block.
   *
   * The default is `"off"` so formatting policy does not affect compilation
   * unless the project opts into that behavior. `ttsc format` can still use the
   * rest of this block to rewrite files.
   *
   * @default "off"
   */
  severity?: TtscLintSeverity;

  /**
   * Insert trailing semicolons on ASI-terminated statements, and on the
   * interface, type-literal, and class members that carry no body. Mirrors
   * Prettier's `semi`. `false` flips the rule to require _no_ trailing
   * semicolon (rare; matches prettier's `semi: false`).
   *
   * @default true
   */
  semi?: boolean;

  /**
   * Prefer single-quoted strings. Mirrors Prettier's `singleQuote`. `false`
   * means double quotes (Prettier's default).
   *
   * @default false
   */
  singleQuote?: boolean;

  /**
   * Parenthesize a single arrow-function parameter. Mirrors Prettier's
   * `arrowParens`. `"always"` (the default) keeps `(x) => x`; `"avoid"` strips
   * the parentheses of a single bare-identifier parameter, giving `x => x`. A
   * typed, destructured, rest, optional, defaulted, or multi-parameter list
   * keeps its parentheses in both modes.
   *
   * @default "always"
   */
  arrowParens?: "always" | "avoid";

  /**
   * Pad the inside of single-line braces with one space. Mirrors Prettier's
   * `bracketSpacing`. `true` (the default) gives `{ x: 1 }`, `import { foo }`;
   * `false` gives `{x: 1}`, `import {foo}`. Applies to object literals, object
   * destructuring patterns, named imports/exports, type literals, mapped types,
   * and import attributes; block, class, interface, and enum braces are
   * unaffected. Empty single-line braces remain `{}` in either mode.
   *
   * @default true
   */
  bracketSpacing?: boolean;

  /**
   * Quoting policy for object-literal keys plus class-method and type-member
   * names. Mirrors Prettier's `quoteProps`. `"as-needed"` (the default) removes
   * quotes from a key that is a valid identifier (`{ "foo": 1 }` becomes `{
   * foo: 1 }`), keeping them on non-identifier or numeric keys (`"bar-baz"`,
   * `"123"`). `"consistent"` quotes every object-literal identifier key when a
   * sibling requires quotes. `"preserve"` never changes quoting. Non-ASCII and
   * escaped keys retain their quoted spelling under the conservative identifier
   * policy; `"__proto__"` follows the same quoting policy as other ASCII
   * names.
   *
   * @default "as-needed"
   */
  quoteProps?: "as-needed" | "consistent" | "preserve";

  /**
   * Trailing-comma policy. Mirrors Prettier's `trailingComma`. `"none"` removes
   * an existing governed trailing comma, `"es5"` keeps it on ES5-level lists,
   * and `"all"` also keeps it on calls and parameter lists.
   *
   * @default "all"
   */
  trailingComma?: "all" | "es5" | "none";

  /**
   * Preferred column budget for supported broken-form layouts. Mirrors
   * Prettier's `printWidth`; it is not a hard bound on every emitted line.
   *
   * @default 80
   */
  printWidth?: number;

  /**
   * Indentation increment in columns. Mirrors Prettier's `tabWidth`.
   *
   * @default 2
   */
  tabWidth?: number;

  /**
   * Emit indentation as tab characters. Mirrors Prettier's `useTabs`.
   *
   * @default false
   */
  useTabs?: boolean;

  /**
   * Line terminator the printer emits on reflow. `@ttsc/lint` supports `"lf"`
   * and `"crlf"`. Prettier's `"cr"` and `"auto"` are intentionally unsupported
   * because the printer does not auto-detect line endings.
   *
   * @default "lf"
   */
  endOfLine?: "lf" | "crlf";

  /**
   * Import formatting. Off unless present; `true` sorts named specifiers and
   * erased type-only imports with defaults, and an object customizes behavior.
   * Runtime declaration reordering requires an explicit unsafe opt-in.
   *
   * @default false
   */
  sortImports?: boolean | ITtscLintFormatSortImports;

  /**
   * JSDoc tag normalization. On by default like the rest of the format set;
   * pass `false` to disable, or an object to customize.
   *
   * Today it only rewrites tag synonyms (`@return` → `@returns`, `@arg` →
   * `@param`, ...); tag sorting, `@param` column alignment, and description
   * wrapping are on the roadmap.
   *
   * @default true
   */
  jsDoc?: boolean | ITtscLintFormatJsDoc;
}