@ttsc/lint 0.12.3 → 0.12.4

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/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];
+};