@ttsc/lint 0.10.2 → 0.11.0-dev.20260518

package/src/structures/ITtscLintPlugin.ts

@@ -0,0 +1,56 @@
+import type { ITtscLintPluginMeta } from "./ITtscLintPluginMeta";
+
+/**
+ * Plugin descriptor exported by a `@ttsc/lint` contributor package.
+ *
+ * The shape intentionally mirrors ESLint's flat-config plugin object so a
+ * contributor can read like an ESLint plugin at a glance:
+ *
+ * ```ts
+ * // ttsc-lint-plugin-demo/src/index.ts
+ * import type { ITtscLintPlugin } from "@ttsc/lint";
+ * import path from "node:path";
+ *
+ * const plugin: ITtscLintPlugin = {
+ *   meta: {
+ *     name: "ttsc-lint-plugin-demo",
+ *     version: "0.1.0",
+ *     namespace: "demo",
+ *   },
+ *   rules: ["no-todo-comment"],
+ *   source: path.resolve(__dirname, "..", "rules"),
+ * };
+ *
+ * export default plugin;
+ * ```
+ *
+ * The only field with runtime semantics is `source`: it points at the
+ * contributor's Go source directory. `@ttsc/lint`'s factory passes that path to
+ * ttsc's plugin builder, which links the contributor into the host binary at
+ * build time. `meta.namespace` and `rules` are advisory (used for type
+ * inference and diagnostic messages); the authoritative rule registration
+ * happens in the Go `init()` of the contributor module.
+ */
+export interface ITtscLintPlugin {
+  /**
+   * Plugin metadata. Optional, but `meta.namespace` is the conventional source
+   * for the rule-name prefix; when absent, the tsconfig `plugins` map key fills
+   * that role.
+   */
+  meta?: ITtscLintPluginMeta;
+
+  /**
+   * Rule names exported by the Go side, used for TypeScript autocomplete in
+   * user configs. Purely advisory — the Go `init()` is the registration
+   * authority. Missing entries will not be flagged at runtime.
+   */
+  rules?: readonly string[];
+
+  /**
+   * Absolute path to the contributor's Go source directory.
+   *
+   * Resolve with `path.resolve(__dirname, ...)` so the path stays valid
+   * regardless of where the consumer's `node_modules` lives.
+   */
+  source: string;
+}

package/src/structures/ITtscLintPluginConfig.ts

@@ -1,4 +1,5 @@
-import type { TtscLintConfig } from "./TtscLintConfig";
+import type { TtscLintFormatConfig } from "./TtscLintFormatConfig";
+import type { TtscLintRuleMap } from "./TtscLintRuleMap";
 
 /** `compilerOptions.plugins[]` entry shape consumed by `@ttsc/lint`. */
 export interface ITtscLintPluginConfig {
@@ -8,14 +9,94 @@ export interface ITtscLintPluginConfig {
   /** Plugin module specifier. */
   transform?: string;
 
+  /**
+   * Inline rule severity map applied to the project.
+   *
+   * Mirrors the `rules` field of an ESLint flat-config entry. When set, the
+   * sidecar uses this map directly and does NOT consult any `lint.config.*`
+   * file (use `extends` for that). Combine with `plugins` to register
+   * contributor rule namespaces in the same entry.
+   *
+   * ```jsonc
+   * {
+   *   "transform": "@ttsc/lint",
+   *   "rules": { "no-var": "error", "prefer-const": "warning" }
+   * }
+   * ```
+   */
+  rules?: TtscLintRuleMap;
+
+  /**
+   * Path to a standalone lint config file whose rules should be applied to this
+   * project. Relative paths are resolved from the tsconfig directory. Accepts
+   * the usual `lint.config.*` / `ttsc-lint.config.*` / `eslint.config.*`
+   * extensions.
+   *
+   * Mirrors the `extends` field of an ESLint flat-config entry — "inherit this
+   * file's configuration".
+   *
+   * ```jsonc
+   * {
+   *   "transform": "@ttsc/lint",
+   *   "extends": "./lint.config.ts"
+   * }
+   * ```
+   *
+   * `rules` and `extends` are mutually exclusive on a single plugin entry; the
+   * sidecar surfaces a loud error when both are set.
+   */
+  extends?: string;
+
+  /**
+   * Contributor lint plugins to compile into the `@ttsc/lint` binary.
+   *
+   * Each entry maps a namespace (rule-name prefix) to an npm specifier or
+   * relative path. The factory resolves the package, reads its exported
+   * `ITtscLintPlugin` descriptor, and forwards the Go source directory to
+   * ttsc's plugin builder via the `contributors` field.
+   *
+   * ```jsonc
+   * {
+   *   "transform": "@ttsc/lint",
+   *   "plugins": { "demo": "ttsc-lint-plugin-demo" },
+   *   "rules": { "demo/no-todo-comment": "error" }
+   * }
+   * ```
+   */
+  plugins?: Record<string, string>;
+
+  /**
+   * Prettier-style flat configuration for the `format/*` rules. Sibling of
+   * `rules`. See {@link TtscLintFormatConfig} for the full surface.
+   *
+   * ```jsonc
+   * {
+   *   "transform": "@ttsc/lint",
+   *   "format": { "printWidth": 100, "singleQuote": true }
+   * }
+   * ```
+   *
+   * Combines with `rules` (per-rule overrides win on collision). Cannot be
+   * combined with `extends` on the same plugin entry — put format options
+   * inside the extends-target lint.config.ts instead.
+   */
+  format?: TtscLintFormatConfig;
+
   /**
    * Inline rule map or path to a standalone lint config file.
    *
-   * Inline maps are passed to the native sidecar through `--plugins-json`.
-   * String values are resolved by the sidecar from the owning tsconfig
-   * directory and may point at JSON, JavaScript, or TypeScript config files.
+   * @deprecated Use `rules` for inline severity maps or `extends` for a config
+   *   file path. The sidecar maps a legacy `config` entry onto the appropriate
+   *   new field and emits a one-time stderr deprecation notice. Removed in a
+   *   future minor.
+   *
+   *   The legacy shape is intentionally narrower than `rules`/`extends`: a string
+   *   (file path) or a flat rule-name → severity map. The Go-side parser only
+   *   accepts those two shapes; widening the TS type to the new
+   *   `TtscLintConfig` union would silently let `config: [{ rules: {...} }]`
+   *   pass type-checking and fail at runtime.
    */
-  config?: string | TtscLintConfig;
+  config?: string | TtscLintRuleMap;
 
   /** Extra plugin-owned fields are passed through unchanged. */
   [key: string]: unknown;

package/src/structures/ITtscLintPluginMeta.ts

@@ -0,0 +1,14 @@
+/** Plugin-level metadata shared with the diagnostic surface. */
+export interface ITtscLintPluginMeta {
+  /** Plugin package name as published on npm. */
+  name?: string;
+
+  /** Plugin package version. */
+  version?: string;
+
+  /**
+   * Rule namespace prefix (e.g. "import" → "import/no-cycle"). When omitted,
+   * `@ttsc/lint` uses the key from the tsconfig `plugins` map.
+   */
+  namespace?: string;
+}

package/src/structures/PluginRuleNames.ts

@@ -0,0 +1,19 @@
+import type { TtscLintPlugins } from "./TtscLintPlugins";
+
+/**
+ * Builds the union of `${namespace}/${rule}` strings from a plugins map.
+ *
+ * Each plugin's `rules` tuple is read literally: an `as const` tuple
+ * (`["no-cycle", "order"] as const`) provides exact autocomplete, while a plain
+ * `string[]` collapses to `${namespace}/${string}` and disables rule-level typo
+ * detection for that namespace.
+ */
+export type PluginRuleNames<P extends TtscLintPlugins> = {
+  [Ns in keyof P]: P[Ns] extends { rules?: infer R }
+    ? R extends readonly (infer N)[]
+      ? N extends string
+        ? `${Ns & string}/${N}`
+        : never
+      : never
+    : never;
+}[keyof P];

package/src/structures/TtscLintConfig.ts

@@ -1,12 +1,31 @@
-import type { TtscLintRule } from "./TtscLintRule";
-import type { TtscLintSeverity } from "./TtscLintSeverity";
+import type { TtscLintConfigEntry } from "./TtscLintConfigEntry";
+import type { TtscLintPlugins } from "./TtscLintPlugins";
+import type { TtscLintRuleMap } from "./TtscLintRuleMap";
 
 /**
- * Inline rule map accepted by the `@ttsc/lint` tsconfig plugin entry.
+ * Top-level config accepted by `@ttsc/lint`.
  *
- * Each property key is a native lint rule name. Omitted rules are disabled,
- * while present rules enable or disable that rule for the current project.
+ * Three accepted forms, listed in expected order of preference:
+ *
+ * 1. **Flat-config array** — mirrors ESLint flat config exactly. Each entry can
+ *    scope by `files` / `ignores`, declare a `plugins` map of contributors,
+ *    configure `rules`, and configure formatting through the Prettier-style
+ *    {@link TtscLintFormatConfig | `format`} block. Multiple entries layer in
+ *    order.
+ * 2. **Single config object** — same shape as one flat-config entry. Useful when
+ *    the project has no per-file scoping. Pass `format: { … }` here for the
+ *    smallest "describe my style" config.
+ * 3. **Rules-only map** — historical shape kept for backward compat with
+ *    single-file projects. `{"no-var":"error"}` is interpreted as `[{rules:
+ *    {"no-var":"error"}}]`. The shorthand intentionally has no slot for the
+ *    `format` block — use form (1) or (2) to enable formatting.
+ *
+ * The generic parameter `P` lets `defineConfig` capture the literal plugin
+ * object types declared in `plugins`. When non-empty, rule-name keys
+ * autocomplete as `BuiltInRule | "<ns>/<rule>"` where the namespace-rule
+ * combinations come from each plugin's `rules` tuple.
  */
-export type TtscLintConfig = {
-  [P in TtscLintRule]?: TtscLintSeverity;
-};
+export type TtscLintConfig<P extends TtscLintPlugins = Record<string, never>> =
+  | TtscLintRuleMap<P>
+  | TtscLintConfigEntry<P>
+  | readonly TtscLintConfigEntry<P>[];

package/src/structures/TtscLintConfigEntry.ts

@@ -0,0 +1,50 @@
+import type { TtscLintFormatConfig } from "./TtscLintFormatConfig";
+import type { TtscLintPlugins } from "./TtscLintPlugins";
+import type { TtscLintRuleMap } from "./TtscLintRuleMap";
+
+/**
+ * One flat-config entry. ESLint-style `files` / `ignores` glob scoping, a
+ * `plugins` namespace map of contributor plugin objects, an `extends` list of
+ * child entries to fold in first, and a severity-keyed `rules` map applied
+ * after the extends chain.
+ *
+ * Prettier-style formatting opts in through a sibling `format` block — see
+ * `TtscLintFormatConfig`. The block can scope per-entry (e.g. wider
+ * `printWidth` for `legacy/**`) just like `rules` does.
+ */
+export interface TtscLintConfigEntry<
+  P extends TtscLintPlugins = Record<string, never>,
+> {
+  /** Globs that select the files this entry applies to. */
+  files?: string | readonly string[];
+
+  /** Globs that exclude files this entry would otherwise match. */
+  ignores?: string | readonly string[];
+
+  /**
+   * Nested entries (or arrays of entries) folded in before this entry's own
+   * rules apply. Mirrors ESLint flat config's `extends`: each child's rules
+   * layer first, with `this.rules` taking precedence on key collisions.
+   */
+  extends?:
+    | TtscLintConfigEntry<P>
+    | readonly TtscLintConfigEntry<P>[]
+    | readonly (TtscLintConfigEntry<P> | readonly TtscLintConfigEntry<P>[])[];
+
+  /**
+   * Contributor plugin objects keyed by namespace. Each value is the default
+   * export of a `@ttsc/lint` contributor package (an `ITtscLintPlugin`).
+   */
+  plugins?: P;
+
+  /** Rule-name → severity map. Supports severity tuples with options. */
+  rules?: TtscLintRuleMap<P>;
+
+  /**
+   * Prettier-style flat configuration for the `format/*` rules. Presence
+   * (even an empty `format: {}`) enables format-class rules at Prettier
+   * defaults; absence keeps them all off. Per-rule overrides go through
+   * the `rules` map — the `rules` entry wins on conflict.
+   */
+  format?: TtscLintFormatConfig;
+}

package/src/structures/TtscLintFormatConfig.ts

@@ -0,0 +1,169 @@
+import type { TtscLintSeverity } from "./TtscLintSeverity";
+
+/**
+ * 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 enables a curated set of format rules at
+ * Prettier-aligned defaults. Individual rules can be overridden or
+ * disabled through the `rules` map (the `rules` entry wins on conflict).
+ *
+ * @example
+ *   import type { TtscLintConfig } from "@ttsc/lint";
+ *
+ *   export default {
+ *     rules: { "no-var": "error" },
+ *     format: {
+ *       printWidth: 100,
+ *       singleQuote: true,
+ *       importOrder: ["<THIRD_PARTY_MODULES>", "^[./]"],
+ *     },
+ *   } satisfies TtscLintConfig;
+ *
+ * Deviations from Prettier:
+ *  - `endOfLine` is restricted to `"lf"` and `"crlf"`. Prettier's
+ *    `"cr"` and `"auto"` modes are intentionally unsupported — the
+ *    printer does not auto-detect terminators.
+ *  - Many Prettier knobs (`bracketSpacing`, `arrowParens`,
+ *    `quoteProps`, JSX-specific switches) are not yet implemented.
+ *    See `docs/14-prettier-migration.md` for the full gap list.
+ *
+ * Rule enablement matrix (when the `format` block is present):
+ *
+ *  - `format/semi` — always on. `semi: false` flips it to `prefer:
+ *    "never"`.
+ *  - `format/quotes` — always on. `singleQuote: true` flips to
+ *    `prefer: "single"`.
+ *  - `format/trailing-comma` — always on. `trailingComma: "none"`
+ *    disables the rule's edits without removing the surface.
+ *  - `format/print-width` — always on, driven by `printWidth`,
+ *    `tabWidth`, `useTabs`, `endOfLine`.
+ *  - `format/sort-imports` — opt-in. Setting `importOrder` enables it.
+ *  - `format/jsdoc` — opt-in. Setting `jsdoc` enables it.
+ *
+ * For per-rule severity overrides, drop a `rules` entry alongside:
+ *
+ *   format: { semi: true, severity: "warning" },
+ *   rules: { "format/semi": "error" },
+ */
+export interface TtscLintFormatConfig {
+  /**
+   * Severity for every format diagnostic emitted by `ttsc check`. The
+   * same vocabulary as the `rules` map (`"off" | "warn" | "warning" |
+   * "error"` plus numeric 0/1/2). `"off"` disables both the diagnostic
+   * and the `ttsc format` / `ttsc fix` rewrite for every format rule.
+   *
+   * @default "warning"
+   */
+  severity?: TtscLintSeverity;
+
+  /**
+   * Insert trailing semicolons on ASI-terminated statements. 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;
+
+  /**
+   * Trailing-comma policy. Mirrors Prettier's `trailingComma`. The
+   * `"none"` mode disables the rule's edits.
+   *
+   * @default "all"
+   */
+  trailingComma?: "all" | "es5" | "none";
+
+  /**
+   * Maximum column width before broken-form layout is chosen.
+   * Mirrors Prettier's `printWidth`.
+   *
+   * @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";
+
+  /**
+   * Group order for `format/sort-imports`. Setting this enables the
+   * rule; mirrors `@trivago/prettier-plugin-sort-imports`'
+   * `importOrder`. The `<THIRD_PARTY_MODULES>` literal is the
+   * catch-all placeholder for specifiers that match no other group.
+   */
+  importOrder?: readonly ("<THIRD_PARTY_MODULES>" | (string & {}))[];
+
+  /**
+   * Insert blank line between sort-imports groups.
+   *
+   * @default true
+   */
+  importOrderSeparation?: boolean;
+
+  /**
+   * Sort named import specifiers alphabetically within each
+   * declaration.
+   *
+   * @default true
+   */
+  importOrderSortSpecifiers?: boolean;
+
+  /**
+   * Case-insensitive comparison for sort-imports.
+   *
+   * @default false
+   */
+  importOrderCaseInsensitive?: boolean;
+
+  /**
+   * Enable `format/jsdoc`. Pass `true` to turn it on with built-in
+   * defaults, or an object to customize:
+   *
+   *   - `tagSynonyms` — extra `from → to` rewrites layered on the
+   *     built-in synonym table.
+   *   - `sortTags` — sort JSDoc tags into canonical order (reserved;
+   *     today's MVP only rewrites tag names).
+   *
+   * @default false (off)
+   */
+  jsdoc?:
+    | boolean
+    | {
+        tagSynonyms?: Record<string, string>;
+        sortTags?: boolean;
+      };
+}

package/src/structures/TtscLintPlugins.ts

@@ -0,0 +1,10 @@
+import type { ITtscLintPlugin } from "./ITtscLintPlugin";
+
+/**
+ * Map of contributor plugins, keyed by their namespace prefix.
+ *
+ * The key (e.g. `"import"`) is what `@ttsc/lint`'s rule-name union joins with
+ * each plugin's exported `rules` tuple (`"no-cycle"`) to produce the namespaced
+ * rule names a user writes in `rules` (`"import/no-cycle"`).
+ */
+export type TtscLintPlugins = Record<string, ITtscLintPlugin>;

package/src/structures/TtscLintRule.ts

@@ -8,12 +8,14 @@
 export type TtscLintRule =
   | "adjacent-overload-signatures"
   | "array-type"
+  | "await-thenable"
   | "ban-ts-comment"
   | "ban-tslint-comment"
   | "consistent-indexed-object-style"
   | "consistent-type-assertions"
   | "consistent-type-definitions"
   | "consistent-type-imports"
+  | "default-param-last"
   | "dot-notation"
   | "eqeqeq"
   | "for-direction"
@@ -56,6 +58,7 @@ export type TtscLintRule =
   | "no-extra-non-null-assertion"
   | "no-fallthrough"
   | "no-func-assign"
+  | "no-import-type-side-effects"
   | "no-inferrable-types"
   | "no-inner-declarations"
   | "no-irregular-whitespace"
@@ -66,6 +69,7 @@ export type TtscLintRule =
   | "no-loss-of-precision"
   | "no-misleading-character-class"
   | "no-misused-new"
+  | "no-mixed-enums"
   | "no-multi-assign"
   | "no-multi-str"
   | "no-namespace"
@@ -113,6 +117,7 @@ export type TtscLintRule =
   | "no-useless-computed-key"
   | "no-useless-concat"
   | "no-useless-constructor"
+  | "no-useless-escape"
   | "no-useless-rename"
   | "no-var"
   | "no-with"
@@ -135,4 +140,12 @@ export type TtscLintRule =
   | "use-isnan"
   | "valid-typeof"
   | "vars-on-top"
-  | "yoda";
+  | "yoda"
+  // Format rules — applied by `ttsc format`. Severity also controls
+  // whether `ttsc check` surfaces unformatted code as a diagnostic.
+  | "format/semi"
+  | "format/quotes"
+  | "format/trailing-comma"
+  | "format/sort-imports"
+  | "format/jsdoc"
+  | "format/print-width";

package/src/structures/TtscLintRuleEntry.ts

@@ -0,0 +1,28 @@
+import type { TtscLintRuleOptionsMap } from "./TtscLintRuleOptions";
+import type { TtscLintSeverity } from "./TtscLintSeverity";
+
+/**
+ * One rule's configuration entry.
+ *
+ * Accepts either a bare severity literal or a `[severity, options]` tuple. The
+ * options slot's type is _picked per rule name_ via `TtscLintRuleOptionsMap` —
+ * so a user writing
+ *
+ *     "format/sort-imports": ["error", { importOrder: [...] }]
+ *
+ * Inside `TtscLintRuleMap` gets exact autocomplete and typo detection on the
+ * options object. The rule name is the object key; the `[severity, options]`
+ * tuple is the value.
+ *
+ * Rules that do not appear in `TtscLintRuleOptionsMap` accept only the severity
+ * literal (or the bare `[severity]` tuple): the conditional arm collapses to
+ * `never`, removing the options-tuple branch from the union for those rules.
+ * This keeps `no-var` and friends from silently accepting unrecognized option
+ * blobs.
+ */
+export type TtscLintRuleEntry<R extends string = string> =
+  | TtscLintSeverity
+  | readonly [TtscLintSeverity]
+  | (R extends keyof TtscLintRuleOptionsMap
+      ? readonly [TtscLintSeverity, TtscLintRuleOptionsMap[R]]
+      : never);

package/src/structures/TtscLintRuleMap.ts

@@ -0,0 +1,52 @@
+import type { PluginRuleNames } from "./PluginRuleNames";
+import type { TtscLintPlugins } from "./TtscLintPlugins";
+import type { TtscLintRule } from "./TtscLintRule";
+import type { TtscLintRuleOptionsMap } from "./TtscLintRuleOptions";
+import type { TtscLintSeverity } from "./TtscLintSeverity";
+
+/**
+ * Rule-name → severity or severity-tuple map.
+ *
+ * Built from two independent mapped types intersected together:
+ *
+ * - Rules listed in `TtscLintRuleOptionsMap` accept `severity`, `[severity]`, or
+ *   `[severity, options]`, with the options type picked per rule key.
+ * - Every other built-in rule plus any contributor plugin rule accepts `severity`
+ *   or `[severity]`.
+ *
+ * Splitting the two halves (instead of folding them into one mapped type with a
+ * conditional value) keeps TypeScript's contextual typing intact inside the
+ * options object literal: typing
+ *
+ * ```ts
+ * rules: {
+ *   "format/sort-imports": ["warning", { importOrder: [...] }],
+ *   "no-var":              "error",
+ * }
+ * ```
+ *
+ * Yields exact autocomplete on `importOrder`, `importOrderSeparation`, etc.,
+ * while `no-var` rejects any tuple beyond a bare severity.
+ *
+ * The `(string & {})` widener is intentionally absent: typos in rule names
+ * produce a `TS2353` excess-property error when the literal is checked in
+ * isolation (e.g. one negative-case-per-const). When the literal also carries
+ * other shape-incompatible entries — e.g. `prefre` typo on `format/quotes` next
+ * to the rule-name typo — TS sometimes elides the rule-name error after
+ * reporting the option-key error first. The test at
+ * `tests/test-lint/.../test_lib_index_d_ts_rule_options_autocomplete_per_rule.ts`
+ * splits each negative case into its own const to keep every branch
+ * load-bearing.
+ */
+export type TtscLintRuleMap<P extends TtscLintPlugins = Record<string, never>> =
+  {
+    [K in keyof TtscLintRuleOptionsMap]?:
+      | TtscLintSeverity
+      | readonly [TtscLintSeverity]
+      | readonly [TtscLintSeverity, TtscLintRuleOptionsMap[K]];
+  } & {
+    [K in Exclude<
+      TtscLintRule | PluginRuleNames<P>,
+      keyof TtscLintRuleOptionsMap
+    >]?: TtscLintSeverity | readonly [TtscLintSeverity];
+  };