@ttsc/lint 0.14.0-dev.20260529.2 → 0.14.1

package/src/structures/{ITtscLintFormat.ts → format/ITtscLintFormat.ts}

@@ -1,10 +1,12 @@
-import type { TtscLintSeverity } from "./TtscLintSeverity";
+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
+ * `@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.
@@ -14,42 +16,6 @@ import type { TtscLintSeverity } from "./TtscLintSeverity";
  * `ttsc check` does not report format findings unless `severity` is set to a
  * non-off value. Individual rules can be overridden or disabled through the
  * `rules` map (the `rules` entry wins on conflict).
- *
- * @example
- *   import type { ITtscLintConfig } from "@ttsc/lint";
- *
- *   export default {
- *   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.
- *
- *   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 findings produced from this block are off by default. Set `severity`
- *   only when a project intentionally wants check-time format diagnostics.
  */
 export interface ITtscLintFormat {
   /**
@@ -80,6 +46,40 @@ export interface ITtscLintFormat {
    */
   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, and type literals; block,
+   * class, interface, and enum braces are unaffected.
+   *
+   * @default true
+   */
+  bracketSpacing?: boolean;
+
+  /**
+   * Quoting policy for object-literal property keys. 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"` keeps
+   * every key quoted when any one of them requires quotes. `"preserve"` never
+   * changes quoting.
+   *
+   * @default "as-needed"
+   */
+  quoteProps?: "as-needed" | "consistent" | "preserve";
+
   /**
    * Trailing-comma policy. Mirrors Prettier's `trailingComma`. The `"none"`
    * mode disables the rule's edits.
@@ -120,49 +120,22 @@ export interface ITtscLintFormat {
   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.
+   * Import sorting & merging. Off unless present; `true` enables it with
+   * defaults, an object customizes.
    *
    * @default false
    */
-  importOrderCaseInsensitive?: boolean;
+  sortImports?: boolean | ITtscLintFormatSortImports;
 
   /**
-   * Enable `format/jsdoc`. Pass `true` to turn it on with built-in defaults, or
-   * an object to customize:
+   * JSDoc tag normalization. On by default like the rest of the format set;
+   * pass `false` to disable, 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).
+   * Today it only rewrites tag synonyms (`@return` → `@returns`, `@arg` →
+   * `@param`, ...); tag sorting, `@param` column alignment, and description
+   * wrapping are on the roadmap.
    *
-   * @default false (off)
+   * @default true
    */
-  jsdoc?:
-    | boolean
-    | {
-        tagSynonyms?: Record<string, string>;
-        sortTags?: boolean;
-      };
+  jsDoc?: boolean | ITtscLintFormatJsDoc;
 }

package/src/structures/format/ITtscLintFormatJsDoc.ts

@@ -0,0 +1,16 @@
+/** Object form of {@link ITtscLintFormat.jsDoc}. */
+export interface ITtscLintFormatJsDoc {
+  /**
+   * Extra `from → to` tag rewrites layered on the built-in synonym table
+   * (`@return` → `@returns`, `@arg` → `@param`, ...).
+   */
+  tagSynonyms?: Record<string, string>;
+
+  /**
+   * Sort JSDoc tags into canonical order. Reserved; the current MVP only
+   * rewrites tag names.
+   *
+   * @default false
+   */
+  sortTags?: boolean;
+}

package/src/structures/format/ITtscLintFormatSortImports.ts

@@ -0,0 +1,62 @@
+/**
+ * Object form of {@link ITtscLintFormat.sortImports}.
+ *
+ * The declarative {@link order} array expresses group order, blank-line
+ * separation, and special groups all by position. Multiple imports of the same
+ * module are always merged into one declaration; merging a value import with a
+ * type-only import additionally requires {@link combineTypeAndValue}.
+ */
+export interface ITtscLintFormatSortImports {
+  /**
+   * Group order. Each entry is a regular expression matched against a
+   * declaration's module specifier, or one of these placeholders:
+   *
+   * - `<BUILTIN_MODULES>` — Node built-in modules (`fs`, `node:path`, ...).
+   * - `<THIRD_PARTY_MODULES>` — catch-all for specifiers that match no other
+   *   group. Injected implicitly at the front when omitted.
+   * - `<TYPES>` — `import type` declarations. Combine with a regex to scope it,
+   *   e.g. `<TYPES>^[.]` groups type-only relative imports.
+   * - `""` (empty string) — emit one blank line at this position. An array with
+   *   no `""` entry produces no blank lines between groups.
+   *
+   * Named specifiers inside each declaration are always sorted. Omit for the
+   * default grouping. Example:
+   *
+   * ```ts
+   * order: [
+   *   "<BUILTIN_MODULES>",
+   *   "",
+   *   "<THIRD_PARTY_MODULES>",
+   *   "",
+   *   "<TYPES>^[.]",
+   *   "^[.]",
+   * ];
+   * ```
+   */
+  order?: readonly (
+    | "<BUILTIN_MODULES>"
+    | "<THIRD_PARTY_MODULES>"
+    | "<TYPES>"
+    | ""
+    | (string & {})
+  )[];
+
+  /**
+   * Case-sensitive comparison. `false` (the default) sorts case-insensitively,
+   * so `React` and `react` order together; `true` uses raw ASCII order
+   * (uppercase before lowercase).
+   *
+   * @default false
+   */
+  caseSensitive?: boolean;
+
+  /**
+   * Merge a value import and a type-only import of the same module into one
+   * declaration with inline `type` specifiers: `import { foo } from "m"` plus
+   * `import type { Bar } from "m"` collapse to `import { foo, type Bar } from
+   * "m"`.
+   *
+   * @default false
+   */
+  combineTypeAndValue?: boolean;
+}

package/src/structures/format/index.ts

@@ -0,0 +1,3 @@
+export * from "./ITtscLintFormat";
+export * from "./ITtscLintFormatJsDoc";
+export * from "./ITtscLintFormatSortImports";

package/src/structures/index.ts

@@ -1,5 +1,5 @@
 export * from "./ITtscLintConfig";
-export * from "./ITtscLintFormat";
+export * from "./format";
 export * from "./ITtscLintPlugin";
 export * from "./ITtscLintPluginConfig";
 export * from "./ITtscLintPluginMeta";

package/src/structures/rules/ITtscLintBoundariesRuleOptions.ts

@@ -1,11 +1,10 @@
 /**
  * Options shapes for every rule in {@link ITtscLintBoundariesRules}.
  *
- * The `boundaries/*` family classifies each source file as belonging to a
- * named *element* (a layer, feature, or app within the project). Every
- * rule below shares the same element-declaration block, so the helper
- * interfaces in this file describe that block first and then layer the
- * per-rule options on top.
+ * The `boundaries/*` family classifies each source file as belonging to a named
+ * _element_ (a layer, feature, or app within the project). Every rule below
+ * shares the same element-declaration block, so the helper interfaces in this
+ * file describe that block first and then layer the per-rule options on top.
  *
  * @reference https://github.com/javierbrea/eslint-plugin-boundaries
  */
@@ -16,31 +15,28 @@ export interface ITtscLintBoundariesElement {
   type: string;
 
   /**
-   * Glob-like source path pattern. Relative patterns are matched against
-   * any project-path suffix, so `src/app/**` works in temporary and
-   * monorepo roots alike.
+   * Glob-like source path pattern. Relative patterns are matched against any
+   * project-path suffix, so `src/app/**` works in temporary and monorepo roots
+   * alike.
    */
   pattern: string;
 
   /**
-   * File(s) inside the element that may be imported from outside that
-   * element. Used by `boundaries/entry-point`.
+   * File(s) inside the element that may be imported from outside that element.
+   * Used by `boundaries/entry-point`.
    */
   entry?: string | readonly string[];
 
   /**
-   * File(s) inside the element that may only be imported by the same
-   * element. Used by `boundaries/no-private`.
+   * File(s) inside the element that may only be imported by the same element.
+   * Used by `boundaries/no-private`.
    */
   private?: string | readonly string[];
 }
 
 /** Dependency policy used by `boundaries/element-types`. */
 export interface ITtscLintBoundariesElementTypesRule {
-  /**
-   * Source element type(s) the policy applies to. Omit to match all
-   * sources.
-   */
+  /** Source element type(s) the policy applies to. Omit to match all sources. */
   from?: string | readonly string[];
 
   /** Target element type(s) allowed from the matching source. */
@@ -58,15 +54,12 @@ export interface ITtscLintBoundariesElementTypesRule {
  * `boundaries/*` rule.
  */
 export interface ITtscLintBoundariesElementsOptions {
-  /**
-   * Source path elements used to classify importers and imported files.
-   */
+  /** Source path elements used to classify importers and imported files. */
   elements?: readonly ITtscLintBoundariesElement[];
 }
 
 /** `boundaries/element-types` rule options. */
-export interface ITtscLintBoundariesElementTypesRuleOptions
-  extends ITtscLintBoundariesElementsOptions {
+export interface ITtscLintBoundariesElementTypesRuleOptions extends ITtscLintBoundariesElementsOptions {
   /**
    * Fallback policy when no rule matches.
    *
@@ -80,10 +73,7 @@ export interface ITtscLintBoundariesElementTypesRuleOptions
 
 /** `boundaries/external` rule options. */
 export interface ITtscLintBoundariesExternalRuleOptions {
-  /**
-   * External package/specifier patterns that are allowed. Empty means
-   * all.
-   */
+  /** External package/specifier patterns that are allowed. Empty means all. */
   allow?: string | readonly string[];
 
   /** External package/specifier patterns that are rejected. */
@@ -109,13 +99,12 @@ export type ITtscLintBoundariesNoUnknownRuleOptions =
  * `boundaries/dependencies` rule options.
  *
  * The upstream unified rule subsumes `element-types`, `entry-point`,
- * `external`, `no-private`, and `no-unknown` behind a single
- * direction-aware policy block. The v1 native port registers the rule
- * name and decodes this config shape but does not yet emit diagnostics
- * (`v1 stub; full validation deferred` — see `rules_boundaries.go`).
+ * `external`, `no-private`, and `no-unknown` behind a single direction-aware
+ * policy block. The v1 native port registers the rule name and decodes this
+ * config shape but does not yet emit diagnostics (`v1 stub; full validation
+ * deferred` — see `rules_boundaries.go`).
  */
-export interface ITtscLintBoundariesDependenciesRuleOptions
-  extends ITtscLintBoundariesElementsOptions {
+export interface ITtscLintBoundariesDependenciesRuleOptions extends ITtscLintBoundariesElementsOptions {
   /**
    * Fallback policy when no rule matches.
    *

package/src/structures/rules/ITtscLintBoundariesRules.ts

@@ -1,3 +1,7 @@
+import type {
+  TtscLintRuleOptionsSetting,
+  TtscLintRuleSetting,
+} from "../TtscLintRuleSetting";
 import type {
   ITtscLintBoundariesDependenciesRuleOptions,
   ITtscLintBoundariesElementTypesRuleOptions,
@@ -6,29 +10,25 @@ import type {
   ITtscLintBoundariesNoPrivateRuleOptions,
   ITtscLintBoundariesNoUnknownRuleOptions,
 } from "./ITtscLintBoundariesRuleOptions";
-import type {
-  TtscLintRuleOptionsSetting,
-  TtscLintRuleSetting,
-} from "../TtscLintRuleSetting";
 
 /**
- * Architecture-boundary rules that enforce import direction and
- * module visibility between configured source-path *elements*
- * (layers, features, apps in a monorepo).
+ * Architecture-boundary rules that enforce import direction and module
+ * visibility between configured source-path _elements_ (layers, features, apps
+ * in a monorepo).
  *
- * Every rule operates on the *resolved source file* of an import —
- * relative imports are followed to the real `.ts`/`.tsx`/`.d.ts`
- * file before classification.
+ * Every rule operates on the _resolved source file_ of an import — relative
+ * imports are followed to the real `.ts`/`.tsx`/`.d.ts` file before
+ * classification.
  *
  * @reference https://github.com/javierbrea/eslint-plugin-boundaries
  */
 export interface ITtscLintBoundariesRules {
   /**
-   * Enforce allowed dependency directions between configured
-   * source-path element types.
+   * Enforce allowed dependency directions between configured source-path
+   * element types.
    *
-   * Each `element` entry declares a name, a matching glob, and the
-   * other element types it is allowed to import.
+   * Each `element` entry declares a name, a matching glob, and the other
+   * element types it is allowed to import.
    *
    * Imports that fall outside the allow-list are reported.
    *
@@ -37,39 +37,37 @@ export interface ITtscLintBoundariesRules {
   "boundaries/element-types"?: TtscLintRuleOptionsSetting<ITtscLintBoundariesElementTypesRuleOptions>;
 
   /**
-   * Require imports that cross element boundaries to target the
-   * importee element's configured public entry files (typically
-   * `index.ts`), so the public surface of each element is explicit.
+   * Require imports that cross element boundaries to target the importee
+   * element's configured public entry files (typically `index.ts`), so the
+   * public surface of each element is explicit.
    *
    * @reference https://github.com/javierbrea/eslint-plugin-boundaries/blob/master/docs/rules/entry-point.md
    */
   "boundaries/entry-point"?: TtscLintRuleOptionsSetting<ITtscLintBoundariesEntryPointRuleOptions>;
 
   /**
-   * Restrict external package imports by package or specifier
-   * pattern.
+   * Restrict external package imports by package or specifier pattern.
    *
-   * Useful for forbidding direct imports of an underlying library
-   * when a project-local facade exists.
+   * Useful for forbidding direct imports of an underlying library when a
+   * project-local facade exists.
    *
    * @reference https://github.com/javierbrea/eslint-plugin-boundaries/blob/master/docs/rules/external.md
    */
   "boundaries/external"?: TtscLintRuleOptionsSetting<ITtscLintBoundariesExternalRuleOptions>;
 
   /**
-   * Reject imports of files declared *private* by a parent element
-   * from outside that element.
+   * Reject imports of files declared _private_ by a parent element from outside
+   * that element.
    *
-   * Combines with `element-types` to keep implementation details
-   * hidden.
+   * Combines with `element-types` to keep implementation details hidden.
    *
    * @reference https://github.com/javierbrea/eslint-plugin-boundaries/blob/master/docs/rules/no-private.md
    */
   "boundaries/no-private"?: TtscLintRuleOptionsSetting<ITtscLintBoundariesNoPrivateRuleOptions>;
 
   /**
-   * Reject relative imports whose resolved source file falls under
-   * no configured element.
+   * Reject relative imports whose resolved source file falls under no
+   * configured element.
    *
    * Catches stray files that escape the project's boundary map.
    *
@@ -78,16 +76,14 @@ export interface ITtscLintBoundariesRules {
   "boundaries/no-unknown"?: TtscLintRuleOptionsSetting<ITtscLintBoundariesNoUnknownRuleOptions>;
 
   /**
-   * Unified dependency-direction rule from upstream
-   * `eslint-plugin-boundaries`, intended to replace
-   * `element-types` / `entry-point` / `external` / `no-private` /
-   * `no-unknown` with a single policy block.
+   * Unified dependency-direction rule from upstream `eslint-plugin-boundaries`,
+   * intended to replace `element-types` / `entry-point` / `external` /
+   * `no-private` / `no-unknown` with a single policy block.
    *
-   * The native port registers the rule name and accepts the same
-   * `elements` + `rules` config shape as `element-types`, but does not
-   * emit diagnostics yet (v1 stub; full direction validation
-   * deferred). Configure it today to claim the upstream rule id; the
-   * legacy split rules continue to enforce policy.
+   * The native port registers the rule name and accepts the same `elements` +
+   * `rules` config shape as `element-types`, but does not emit diagnostics yet
+   * (v1 stub; full direction validation deferred). Configure it today to claim
+   * the upstream rule id; the legacy split rules continue to enforce policy.
    *
    * @reference https://github.com/javierbrea/eslint-plugin-boundaries/blob/master/docs/rules/dependencies.md
    */

package/src/structures/rules/ITtscLintContributorRules.ts

@@ -1,15 +1,14 @@
-import type { TtscLintSeverity } from "../TtscLintSeverity";
 import type { TtscLintRuleSetting } from "../TtscLintRuleSetting";
+import type { TtscLintSeverity } from "../TtscLintSeverity";
 
 /**
  * Catch-all index signature for contributor plugin rules.
  *
- * Plugin authors expose rules under their own namespace prefix
- * (`demo/no-demo`, `myplugin/foo-bar`). The signature here
- * accepts any `"<namespace>/<rule>"` key with either the bare
- * severity form, the severity tuple, or the
- * severity-plus-options tuple. Plugins ship their own typings to
- * tighten the options shape per rule.
+ * Plugin authors expose rules under their own namespace prefix (`demo/no-demo`,
+ * `myplugin/foo-bar`). The signature here accepts any `"<namespace>/<rule>"`
+ * key with either the bare severity form, the severity tuple, or the
+ * severity-plus-options tuple. Plugins ship their own typings to tighten the
+ * options shape per rule.
  *
  * @reference https://ttsc.dev/lint/development/rules
  */