@ngxtm/devkit 3.4.0 → 3.5.0

package/rules/typescript/best-practices/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: TypeScript Best Practices
+description: Idiomatic TypeScript patterns for clean, maintainable code.
+metadata:
+  labels: [typescript, best-practices, idioms, conventions]
+  triggers:
+    files: ['**/*.ts', '**/*.tsx']
+    keywords: [class, function, module, import, export, async, promise]
+---
+
+# TypeScript Best Practices
+
+## **Priority: P1 (OPERATIONAL)**
+
+Idiomatic patterns for writing clean, maintainable TypeScript code.
+
+## Implementation Guidelines
+
+- **Naming Conventions**:
+  - PascalCase for classes, interfaces, types, enums
+  - camelCase for variables, functions, methods, parameters
+  - UPPER_SNAKE_CASE for constants
+  - Prefix interfaces with `I` only when necessary for disambiguation
+- **Functions**:
+  - Prefer arrow functions for callbacks and short functions
+  - Use regular functions for methods and exported functions
+  - Always specify return types for public APIs
+- **Modules**:
+  - One export per file for major components/classes
+  - Use named exports over default exports for better refactoring
+  - Organize imports: external -> internal -> relative
+- **Async/Await**:
+  - Prefer `async/await` over raw Promises
+  - Always handle errors with try/catch in async functions
+  - Use `Promise.all()` for parallel operations
+- **Classes**:
+  - Use `private`/`protected`/`public` modifiers explicitly
+  - Prefer composition over inheritance
+  - Use `readonly` for properties that don't change after construction
+- **Exhaustiveness Checking**: Use `never` type in `switch` cases.
+- **Assertion Functions**: Use `asserts` for runtime type validation.
+- **Optional Properties**: Use `?:`, not `| undefined`.
+- **Type Imports**: Use `import type` for tree-shaking.
+
+## Anti-Patterns
+
+- **No Default Exports**: Use named exports.
+- **No Implicit Returns**: Specify return types.
+- **No Unused Variables**: Enable `noUnusedLocals`.
+- **No `require`**: Use ES6 `import`.
+- **No Empty Interfaces**: Use `type` or non-empty interface.
+
+## Code
+
+````typescript
+// Named Export + Immutable Interface
+export interface User {
+  readonly id: string;
+  name: string;
+}
+
+// Exhaustive Check
+function getStatus(s: 'ok' | 'fail') {
+  switch (s) {
+    case 'ok': return 'OK';
+    case 'fail': return 'Fail';
+    default: const _chk: never = s; return _chk;
+  }
+}
+
+// Assertion
+function assertDefined<T>(val: T): asserts val is NonNullable<T> {
+  if (val == null) throw new Error("Defined expected");
+}
+```  private readonly repository: UserRepository;
+
+  constructor(repository: UserRepository) {
+    this.repository = repository;
+  }
+
+  async getUser(id: string): Promise<UserProfile> {
+    try {
+      return await this.repository.findById(id);
+    } catch (error) {
+      throw new Error(`Failed to get user: ${error.message}`);
+    }
+  }
+}
+
+// Organize imports
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+
+import { UserRepository } from '@/repositories/user.repository';
+import { Logger } from '@/utils/logger';
+
+// Type-only imports
+import type { Request, Response } from 'express';
+````
+
+## Reference & Examples
+
+For project structure and module organization:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+language | tooling | security

package/rules/typescript/best-practices/references/REFERENCE.md

@@ -0,0 +1,68 @@
+# TypeScript Best Practices Reference
+
+Project structure and advanced patterns.
+
+## References
+
+- [**Project Structure**](project-structure.md) - Scalable directory organization.
+- [**Configuration**](configuration.md) - TSConfig best practices.
+
+## Project Structure
+
+```
+src/
+├── domain/           # Business logic (entities, value objects)
+│   ├── user/
+│   │   ├── user.entity.ts
+│   │   └── user.repository.interface.ts
+├── application/      # Use cases
+│   └── user/
+│       └── create-user.usecase.ts
+├── infrastructure/   # External concerns
+│   ├── database/
+│   └── http/
+├── presentation/     # Controllers, DTOs
+│   └── user/
+│       ├── user.controller.ts
+│       └── user.dto.ts
+└── shared/          # Shared utilities
+    ├── types/
+    └── utils/
+```
+
+## TSConfig Best Practices
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "moduleResolution": "node",
+    "baseUrl": "./",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  }
+}
+```
+
+## Barrel Exports (Use Sparingly)
+
+```typescript
+// index.ts - Barrel file
+export * from './user.service';
+export * from './user.repository';
+export type { UserDTO } from './user.dto';
+```
+
+Note: Avoid deep barrel exports as they can impact build performance.

package/rules/typescript/language/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: TypeScript Language Patterns
+description: Modern TypeScript standards for type safety, performance, and maintainability.
+metadata:
+  labels: [typescript, language, types, generics]
+  triggers:
+    files: ['**/*.ts', '**/*.tsx', 'tsconfig.json']
+    keywords:
+      [
+        type,
+        interface,
+        generic,
+        enum,
+        union,
+        intersection,
+        readonly,
+        const,
+        namespace,
+      ]
+---
+
+# TypeScript Language Patterns
+
+## **Priority: P0 (CRITICAL)**
+
+Modern TypeScript standards for type-safe, maintainable code.
+
+## Implementation Guidelines
+
+- **Type Annotations**: Explicit params/returns. Infer locals.
+- **Interfaces vs Types**: `interface` for APIs. `type` for unions.
+- **Strict Mode**: `strict: true`.
+- **Null Safety**: `?.` and `??`.
+- **Enums**: Literal unions or `as const`.
+- **Generics**: Reusable, type-safe code.
+- **Type Guards**: `typeof`, `instanceof`, predicates.
+- **Utility Types**: `Partial`, `Pick`, `Omit`, `Record`.
+- **Immutability**: `readonly` arrays/objects.
+- **Const Assertions**: `as const` and `satisfies`.
+- **Template Literals**: `on${Capitalize<string>}`.
+- **Discriminated Unions**: Literal `kind` property.
+- **Advanced**: Mapped, Conditional, Indexed types.
+- **Branded Types**: `string & { __brand: 'Id' }`.
+
+## Anti-Patterns
+
+- **No `any`**: Use `unknown`.
+- **No `Function`**: Use signature `() => void`.
+- **No `enum`**: Runtime cost.
+- **No `!`**: Use narrowing.
+
+## Code
+
+```typescript
+// Branded Type
+type UserId = string & { __brand: 'Id' };
+
+// Satisfies (Validate + Infer)
+const cfg = { port: 3000 } satisfies Record<string, number>;
+
+// Discriminated Union
+type Result<T> = { kind: 'ok'; data: T } | { kind: 'err'; error: Error };
+```
+
+## Reference & Examples
+
+For advanced type patterns and utility types:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+best-practices | security | tooling

package/rules/typescript/language/references/REFERENCE.md

@@ -0,0 +1,67 @@
+# TypeScript Language Patterns Reference
+
+Advanced type patterns and utility implementations.
+
+## References
+
+- [**Advanced Types**](advanced-types.md) - Conditional types, mapped types, and template literals.
+- [**Type Guards**](type-guards.md) - Custom type guard patterns.
+- [**Utility Types**](utility-types.md) - Custom utility type implementations.
+
+## Advanced Generic Patterns
+
+```typescript
+// Conditional types
+type NonNullable<T> = T extends null | undefined ? never : T;
+
+// Mapped types
+type Readonly<T> = {
+  readonly [P in keyof T]: T[P];
+};
+
+// Template literal types
+type EventName<T extends string> = `on${Capitalize<T>}`;
+
+// Recursive types
+type DeepReadonly<T> = {
+  readonly [P in keyof T]: T[P] extends object
+    ? DeepReadonly<T[P]>
+    : T[P];
+};
+```
+
+## Branded Types for Type Safety
+
+```typescript
+type UserId = string & { readonly __brand: 'UserId' };
+type OrderId = string & { readonly __brand: 'OrderId' };
+
+function createUserId(id: string): UserId {
+  return id as UserId;
+}
+
+// Prevents mixing IDs at compile time
+function getUser(id: UserId) { /* ... */ }
+getUser(createUserId('123')); // OK
+// getUser('123'); // Error: Type 'string' is not assignable to type 'UserId'
+```
+
+## Discriminated Unions
+
+```typescript
+type Shape =
+  | { kind: 'circle'; radius: number }
+  | { kind: 'rectangle'; width: number; height: number }
+  | { kind: 'square'; size: number };
+
+function area(shape: Shape): number {
+  switch (shape.kind) {
+    case 'circle':
+      return Math.PI * shape.radius ** 2;
+    case 'rectangle':
+      return shape.width * shape.height;
+    case 'square':
+      return shape.size ** 2;
+  }
+}
+```

package/rules/typescript/patterns.rule.md

@@ -0,0 +1,85 @@
+---
+id: typescript-patterns
+version: 1.0.0
+triggers: [typescript, types, patterns]
+---
+
+# TypeScript Patterns
+
+Type-safe patterns for robust code.
+
+## Discriminated Unions
+
+```typescript
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+function handle(result: Result<User>) {
+  if (result.ok) {
+    console.log(result.value.name);
+  } else {
+    console.error(result.error.message);
+  }
+}
+```
+
+## Branded Types
+
+```typescript
+type UserId = string & { readonly __brand: 'UserId' };
+
+function createUserId(id: string): UserId {
+  return id as UserId;
+}
+
+function getUser(id: UserId) { /* ... */ }
+
+// Prevents accidental mixing
+const userId = createUserId('123');
+const orderId = '456';
+
+getUser(userId);  // OK
+getUser(orderId); // Type error
+```
+
+## Exhaustive Checks
+
+```typescript
+type Status = 'pending' | 'active' | 'closed';
+
+function assertNever(x: never): never {
+  throw new Error(`Unexpected: ${x}`);
+}
+
+function getLabel(status: Status): string {
+  switch (status) {
+    case 'pending': return 'Pending';
+    case 'active': return 'Active';
+    case 'closed': return 'Closed';
+    default: return assertNever(status);
+  }
+}
+```
+
+## Builder Pattern
+
+```typescript
+class QueryBuilder {
+  private filters: string[] = [];
+
+  where(field: string, value: unknown): this {
+    this.filters.push(`${field} = ${value}`);
+    return this;
+  }
+
+  build(): string {
+    return this.filters.join(' AND ');
+  }
+}
+
+new QueryBuilder()
+  .where('status', 'active')
+  .where('age', 18)
+  .build();
+```

package/rules/typescript/security/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: TypeScript Security
+description: Secure coding practices for building safe TypeScript applications.
+metadata:
+  labels: [security, typescript, validation, sanitization]
+  triggers:
+    files: ['**/*.ts', '**/*.tsx']
+    keywords:
+      [validate, sanitize, xss, injection, auth, password, secret, token]
+---
+
+# TypeScript Security
+
+## **Priority: P0 (CRITICAL)**
+
+Security standards for TypeScript applications based on OWASP guidelines.
+
+## Implementation Guidelines
+
+- **Validation**: Validate all inputs with `zod`/`joi`/`class-validator`.
+- **Sanitization**: Use `DOMPurify` for HTML. Prevent XSS.
+- **Secrets**: Use env vars. Never hardcode.
+- **SQL Injection**: Use parameterized queries or ORMs (Prisma/TypeORM).
+- **Auth**: Use `bcrypt` for hashing. Implement strict RBAC.
+- **HTTPS**: Enforce HTTPS. Set `secure`, `httpOnly`, `sameSite` cookies.
+- **Rate Limit**: Prevent brute-force/DDoS.
+- **Deps**: Audit with `npm audit`.
+
+## Anti-Patterns
+
+- **No `eval()`**: Avoid dynamic execution.
+- **No Plaintext**: Never commit secrets.
+- **No Trust**: Validate everything server-side.
+
+## Code
+
+```typescript
+// Validation (Zod)
+const UserSchema = z.object({
+  email: z.string().email(),
+  pass: z.string().min(8),
+});
+
+// Secure Cookie
+const cookieOpts = {
+  httpOnly: true,
+  secure: process.env.NODE_ENV === 'prod',
+  sameSite: 'strict' as const,
+};
+```
+
+## Reference & Examples
+
+For authentication patterns and security headers:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+best-practices | language

package/rules/typescript/security/references/REFERENCE.md

@@ -0,0 +1,113 @@
+# TypeScript Security Reference
+
+Authentication, authorization, and security patterns.
+
+## References
+
+- [**Authentication**](authentication.md) - JWT and session management.
+- [**Security Headers**](security-headers.md) - HTTP security headers configuration.
+
+## JWT Authentication Pattern
+
+```typescript
+import jwt from 'jsonwebtoken';
+
+interface JWTPayload {
+  userId: string;
+  role: string;
+}
+
+export class AuthService {
+  private readonly secret: string;
+  
+  constructor() {
+    this.secret = process.env.JWT_SECRET!;
+    if (!this.secret) {
+      throw new Error('JWT_SECRET environment variable is required');
+    }
+  }
+
+  generateToken(payload: JWTPayload): string {
+    return jwt.sign(payload, this.secret, {
+      expiresIn: '1h',
+      issuer: 'your-app',
+      audience: 'your-api',
+    });
+  }
+
+  verifyToken(token: string): JWTPayload {
+    try {
+      return jwt.verify(token, this.secret) as JWTPayload;
+    } catch (error) {
+      throw new Error('Invalid token');
+    }
+  }
+}
+```
+
+## Security Headers (Express)
+
+```typescript
+import helmet from 'helmet';
+import express from 'express';
+
+const app = express();
+
+// Security headers
+app.use(helmet({
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      scriptSrc: ["'self'"],
+      styleSrc: ["'self'", "'unsafe-inline'"],
+      imgSrc: ["'self'", 'data:', 'https:'],
+    },
+  },
+  hsts: {
+    maxAge: 31536000,
+    includeSubDomains: true,
+    preload: true,
+  },
+}));
+
+// CORS configuration
+app.use(cors({
+  origin: process.env.ALLOWED_ORIGINS?.split(',') || [],
+  credentials: true,
+}));
+```
+
+## Role-Based Access Control
+
+```typescript
+enum Role {
+  ADMIN = 'admin',
+  USER = 'user',
+  GUEST = 'guest',
+}
+
+type Permission = 'read' | 'write' | 'delete';
+
+const rolePermissions: Record<Role, Permission[]> = {
+  [Role.ADMIN]: ['read', 'write', 'delete'],
+  [Role.USER]: ['read', 'write'],
+  [Role.GUEST]: ['read'],
+};
+
+function hasPermission(role: Role, permission: Permission): boolean {
+  return rolePermissions[role].includes(permission);
+}
+
+// Middleware
+function requirePermission(permission: Permission) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const user = req.user; // Assume user is set by auth middleware
+    
+    if (!user || !hasPermission(user.role, permission)) {
+      return res.status(403).json({ error: 'Forbidden' });
+    }
+    
+    next();
+  };
+}
+```

package/rules/typescript/tooling/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: TypeScript Tooling
+description: Development tools, linting, and build configuration for TypeScript projects.
+metadata:
+  labels: [tooling, typescript, eslint, prettier, testing]
+  triggers:
+    files: ['tsconfig.json', '.eslintrc.*', 'jest.config.*', 'package.json']
+    keywords: [eslint, prettier, jest, vitest, build, compile, lint]
+---
+
+# TypeScript Tooling
+
+## **Priority: P1 (OPERATIONAL)**
+
+Essential tooling for TypeScript development and maintenance.
+
+## Implementation Guidelines
+
+- **Compiler**: `tsc` for CI. `ts-node`/`esbuild` for dev.
+- **Lint**: ESLint + `@typescript-eslint`. Strict type checking.
+- **Format**: Prettier (on save + commit).
+- **Test**: Jest/Vitest > 80% coverage.
+- **Build**: `tsup` (libs), Vite/Webpack (apps).
+- **Check**: `tsc --noEmit` in CI.
+
+## Anti-Patterns
+
+- **No Disable**: Avoid `// eslint-disable`.
+- **No Skip**: Avoid `skipLibCheck: true` if possible.
+- **No Ignore**: Use `@ts-expect-error` > `@ts-ignore`.
+
+## Configuration
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitReturns": true,
+    "noUnusedLocals": true
+  }
+}
+```
+
+## Reference & Examples
+
+For testing configuration and CI/CD setup:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+best-practices | language