@webpieces/code-rules 0.0.1 → 0.2.113

package/src/validate-no-inline-types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Validate No Inline Types Executor
+ *
+ * Validates that inline type literals AND tuple types are not used in type positions.
+ * Prefer named types/interfaces/classes for clarity and reusability.
+ *
+ * ============================================================================
+ * VIOLATIONS (BAD) - These patterns are flagged:
+ * ============================================================================
+ *
+ * 1. INLINE TYPE LITERALS { }
+ *    -------------------------
+ *    - Inline parameter type:     function foo(arg: { x: number }) { }
+ *    - Inline return type:        function foo(): { x: number } { }
+ *    - Inline variable type:      const config: { timeout: number } = { timeout: 5 };
+ *    - Inline property type:      class C { data: { id: number }; }
+ *    - Inline in union:           type T = { x: number } | null;
+ *    - Inline in intersection:    type T = { x: number } & { y: number };
+ *    - Inline in generic:         Promise<{ data: string }>
+ *    - Inline in array:           function foo(): { id: string }[] { }
+ *    - Nested inline in alias:    type T = { data: { nested: number } };  // inner { } flagged
+ *    - Inline in tuple:           type T = [{ x: number }, string];
+ *
+ * 2. TUPLE TYPES [ ]
+ *    ----------------
+ *    - Tuple return type:         function foo(): [Items[], number] { }
+ *    - Tuple parameter type:      function foo(arg: [string, number]) { }
+ *    - Tuple variable type:       const result: [Data[], number] = getData();
+ *    - Tuple in generic:          Promise<[Items[], number]>
+ *    - Tuple in union:            type T = [A, B] | null;
+ *    - Nested tuple:              type T = { data: [A, B] };
+ *
+ * ============================================================================
+ * ALLOWED (GOOD) - These patterns pass validation:
+ * ============================================================================
+ *
+ * 1. TYPE ALIAS DEFINITIONS (direct body only)
+ *    -----------------------------------------
+ *    - Type alias with literal:   type MyConfig = { timeout: number };
+ *    - Type alias with tuple:     type MyResult = [Items[], number];
+ *    - Interface definition:      interface MyData { id: number }
+ *    - Class definition:          class UserData { id: number; name: string; }
+ *
+ * 2. USING NAMED TYPES
+ *    ------------------
+ *    - Named param type:          function foo(arg: MyConfig) { }
+ *    - Named return type:         function foo(): MyConfig { }
+ *    - Named with null:           function foo(): MyConfig | null { }
+ *    - Named with undefined:      function foo(): MyConfig | undefined { }
+ *    - Union of named types:      type Either = TypeA | TypeB;
+ *    - Named in generic:          Promise<MyResult>
+ *    - Named tuple alias:         function foo(): MyTupleResult { }
+ *
+ * 3. PRIMITIVES AND BUILT-INS
+ *    -------------------------
+ *    - Primitive types:           function foo(): string { }
+ *    - Primitive arrays:          function foo(): string[] { }
+ *    - Built-in generics:         function foo(): Promise<string> { }
+ *    - Void return:               function foo(): void { }
+ *
+ * ============================================================================
+ * MODES
+ * ============================================================================
+ * - OFF:                      Skip validation entirely
+ * - NEW_METHODS:              Only validate in new methods (detected via git diff)
+ * - NEW_AND_MODIFIED_METHODS: Validate in new methods + methods with changes
+ * - MODIFIED_FILES:           Validate all violations in modified files
+ *
+ * ============================================================================
+ * ESCAPE HATCH
+ * ============================================================================
+ * Add comment above the violation:
+ *   // webpieces-disable no-inline-types -- [your justification]
+ *   function foo(arg: { x: number }) { }
+ *
+ * Use sparingly! Common valid reasons:
+ * - Prisma payload types that require inline generics
+ * - Third-party library APIs that expect inline types
+ * - Legacy code being incrementally migrated
+ */
+export type NoInlineTypesMode = 'OFF' | 'NEW_METHODS' | 'NEW_AND_MODIFIED_METHODS' | 'MODIFIED_FILES';
+export interface ValidateNoInlineTypesOptions {
+    mode?: NoInlineTypesMode;
+    disableAllowed?: boolean;
+    ignoreModifiedUntilEpoch?: number;
+}
+export interface ExecutorResult {
+    success: boolean;
+}
+export default function runValidator(options: ValidateNoInlineTypesOptions, workspaceRoot: string): Promise<ExecutorResult>;