@ttsc/lint 0.12.3 → 0.13.0

package/src/structures/ITtscLintFormatConfig.ts

@@ -4,10 +4,10 @@ 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.
+ * `@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.
@@ -19,37 +19,37 @@ import type { TtscLintSeverity } from "./TtscLintSeverity";
  *   import type { ITtscLintConfig } from "@ttsc/lint";
  *
  *   export default {
- *     rules: { "no-var": "error" },
- *     format: {
- *       severity: "warning",
- *       printWidth: 100,
- *       singleQuote: true,
- *       importOrder: ["<THIRD_PARTY_MODULES>", "^[./]"],
- *     },
+ *   rules: { "no-var": "error" },
+ *   format: {
+ *   severity: "warning",
+ *   printWidth: 100,
+ *   singleQuote: true,
+ *   importOrder: ["<THIRD_PARTY_MODULES>", "^[./]"],
+ *   },
  *   } satisfies ITtscLintConfig;
  *
- * 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.
+ *   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.
  *
- * Rule enablement matrix (when the `format` block is present):
+ *   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.
+ *   - `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.
  *
- * Format findings produced from this block are off by default. Set `severity`
- * only when a project intentionally wants check-time format diagnostics.
+ *   Format findings produced from this block are off by default. Set `severity`
+ *   only when a project intentionally wants check-time format diagnostics.
  */
 export interface ITtscLintFormatConfig {
   /**
@@ -64,33 +64,33 @@ export interface ITtscLintFormatConfig {
   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`).
+   * 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).
+   * 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.
+   * 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`.
+   * Maximum column width before broken-form layout is chosen. Mirrors
+   * Prettier's `printWidth`.
    *
    * @default 80
    */
@@ -111,20 +111,19 @@ export interface ITtscLintFormatConfig {
   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.
+   * 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.
+   * 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 & {}))[];
 
@@ -136,8 +135,7 @@ export interface ITtscLintFormatConfig {
   importOrderSeparation?: boolean;
 
   /**
-   * Sort named import specifiers alphabetically within each
-   * declaration.
+   * Sort named import specifiers alphabetically within each declaration.
    *
    * @default true
    */
@@ -151,13 +149,13 @@ export interface ITtscLintFormatConfig {
   importOrderCaseInsensitive?: boolean;
 
   /**
-   * Enable `format/jsdoc`. Pass `true` to turn it on with built-in
-   * defaults, or an object to customize:
+   * 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).
+   * - `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)
    */

package/src/structures/ITtscLintPluginConfig.ts

@@ -1,6 +1,3 @@
-import type { ITtscLintFormatConfig } from "./ITtscLintFormatConfig";
-import type { TtscLintRuleMap } from "./TtscLintRuleMap";
-
 /** `compilerOptions.plugins[]` entry shape consumed by `@ttsc/lint`. */
 export interface ITtscLintPluginConfig {
   /** Set to `false` to keep the entry while disabling this plugin. */
@@ -10,94 +7,24 @@ export interface ITtscLintPluginConfig {
   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.
+   * Path to the lint config file, overriding auto-discovery.
    *
-   * 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.
+   * Relative paths are resolved from the tsconfig directory; absolute paths are
+   * used as-is. Accepts the usual `lint.config.*` / `ttsc-lint.config.*`
+   * extensions (`.ts`, `.cts`, `.mts`, `.js`, `.cjs`, `.mjs`, `.json`).
    *
-   * ```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 ITtscLintFormatConfig} for the full surface.
+   * When omitted, `@ttsc/lint` discovers a `lint.config.*` /
+   * `ttsc-lint.config.*` file by walking upward from the tsconfig directory.
    *
    * ```jsonc
    * {
    *   "transform": "@ttsc/lint",
-   *   "format": { "printWidth": 100, "singleQuote": true }
+   *   "configFile": "./lint.config.ts"
    * }
    * ```
    *
-   * 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.
+   * Every rule, format, and plugin setting lives in the config file — the
+   * tsconfig plugin entry carries nothing but this pointer.
    */
-  format?: ITtscLintFormatConfig;
-
-  /**
-   * Inline rule map or path to a standalone lint config file.
-   *
-   * @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 full config object
-   *   would silently let unsupported nested shapes pass type-checking and fail
-   *   at runtime.
-   */
-  config?: string | TtscLintRuleMap;
-
-  /** Extra plugin-owned fields are passed through unchanged. */
-  [key: string]: unknown;
+  configFile?: string;
 }

package/src/structures/ITtscLintPluginMeta.ts

@@ -1,4 +1,12 @@
-/** Plugin-level metadata shared with the diagnostic surface. */
+/**
+ * Plugin-level metadata exposed on `ITtscLintPlugin.meta`.
+ *
+ * All fields are optional. When `namespace` is absent, `@ttsc/lint` falls back
+ * to the key used in the tsconfig `plugins` map (or `lint.config.*` `plugins`
+ * object) as the rule-name prefix. `name` and `version` are purely
+ * informational — they appear in diagnostic messages and are not validated at
+ * build time.
+ */
 export interface ITtscLintPluginMeta {
   /** Plugin package name as published on npm. */
   name?: string;

package/src/structures/TtscLintRule.ts

@@ -1,9 +1,18 @@
 /**
- * Lint rule names understood by the `@ttsc/lint` native sidecar.
+ * Union of every built-in lint rule name understood by the `@ttsc/lint` native
+ * sidecar.
  *
  * These names intentionally mirror familiar ESLint / TypeScript-ESLint rule
  * names so a `compilerOptions.plugins[]` entry can configure native linting
  * without introducing a separate lint config file.
+ *
+ * The `format/*` members at the bottom of the union are applied by `ttsc
+ * format`; their severity also controls whether `ttsc check` surfaces
+ * unformatted code as a diagnostic.
+ *
+ * This type is used as the key constraint in `TtscLintRuleMap` for rules that
+ * carry no per-rule options. Rules with typed option objects are additionally
+ * listed in `ITtscLintRuleOptionsMap`.
  */
 export type TtscLintRule =
   | "adjacent-overload-signatures"

package/src/structures/TtscLintRuleMap.ts

@@ -11,8 +11,8 @@ import type { TtscLintSeverity } from "./TtscLintSeverity";
  *   `[severity, options]`, with the options type picked per rule key.
  * - Every other built-in rule accepts `severity` or `[severity]`.
  * - Namespaced contributor plugin rules accept `severity`, `[severity]`, or
- *   `[severity, unknownOptions]` because the host type surface no longer
- *   knows contributor rule schemas.
+ *   `[severity, unknownOptions]` because the host type surface no longer knows
+ *   contributor rule schemas.
  *
  * Splitting the two halves (instead of folding them into one mapped type with a
  * conditional value) keeps TypeScript's contextual typing intact inside the
@@ -38,19 +38,18 @@ import type { TtscLintSeverity } from "./TtscLintSeverity";
  * splits each negative case into its own const to keep every branch
  * load-bearing.
  */
-export type TtscLintRuleMap =
-  {
-    [K in keyof ITtscLintRuleOptionsMap]?:
-      | TtscLintSeverity
-      | readonly [TtscLintSeverity]
-      | readonly [TtscLintSeverity, ITtscLintRuleOptionsMap[K]];
-  } & {
-    [K in Exclude<TtscLintRule, keyof ITtscLintRuleOptionsMap>]?:
-      | TtscLintSeverity
-      | readonly [TtscLintSeverity];
-  } & {
-    [K in `${string}/${string}`]?:
-      | TtscLintSeverity
-      | readonly [TtscLintSeverity]
-      | readonly [TtscLintSeverity, unknown];
-  };
+export type TtscLintRuleMap = {
+  [K in keyof ITtscLintRuleOptionsMap]?:
+    | TtscLintSeverity
+    | readonly [TtscLintSeverity]
+    | readonly [TtscLintSeverity, ITtscLintRuleOptionsMap[K]];
+} & {
+  [K in Exclude<TtscLintRule, keyof ITtscLintRuleOptionsMap>]?:
+    | TtscLintSeverity
+    | readonly [TtscLintSeverity];
+} & {
+  [K in `${string}/${string}`]?:
+    | TtscLintSeverity
+    | readonly [TtscLintSeverity]
+    | readonly [TtscLintSeverity, unknown];
+};

package/src/structures/TtscLintRuleOptions.ts

@@ -99,6 +99,21 @@ export interface ITtscLintPrintWidthRuleOptions {
    * @default "lf"
    */
   endOfLine?: "lf" | "crlf";
+
+  /**
+   * Trailing-comma policy the reflow honors when it breaks a list across
+   * lines. Mirrors prettier's `trailingComma` and must match the
+   * `format/trailing-comma` rule's `mode`; otherwise the two rules
+   * disagree on every cascade pass and oscillate against each other.
+   *
+   * When a `format` block is configured, `format.trailingComma` is mirrored
+   * into this option automatically. Set it directly only when overriding
+   * the print-width rule via a `rules` tuple — see the conflict-resolution
+   * notes in the README.
+   *
+   * @default "all"
+   */
+  trailingComma?: "all" | "es5" | "none";
 }
 
 /** `format/jsdoc` rule options. */