@codyswann/lisa 1.56.1 → 1.56.2

package/plugins/lisa-rails/skills/jsdoc-best-practices/SKILL.md

@@ -1,432 +0,0 @@
----
-name: jsdoc-best-practices
-description: Enforces JSDoc documentation standards for this TypeScript project. This skill should be used when writing or reviewing TypeScript code to ensure proper documentation with file preambles, function docs, interface docs, and the critical distinction between documenting "what" vs "why". Use this skill to understand the project's JSDoc ESLint rules and established patterns.
----
-
-# JSDoc Best Practices
-
-## Overview
-
-This skill defines the JSDoc documentation standards for this project. The core principle is that **documentation should explain "why", not just "what"**. Code already shows what it does—good documentation explains the reasoning, context, and non-obvious details that help developers understand and maintain the code.
-
-## Core Philosophy: Why Over What
-
-### The Problem with "What" Documentation
-
-```typescript
-// Bad: Just restates the code
-/**
- * Gets the user by ID
- * @param id - The ID
- * @returns The user
- */
-function getUserById(id: string): User { ... }
-```
-
-This documentation adds no value—the function name already tells us it gets a user by ID.
-
-### The Solution: Document "Why"
-
-```typescript
-// Good: Explains context, constraints, and non-obvious behavior
-/**
- * Retrieves a user by their unique identifier
- * @param id - The user's UUID (not the legacy numeric ID)
- * @returns The user if found, null if not found or soft-deleted
- * @remarks Used by DataLoader for batching - maintains input order
- */
-function getUserById(id: string): User | null { ... }
-```
-
-This documentation adds value by explaining:
-- What kind of ID (UUID vs legacy)
-- What happens when not found
-- Why this specific implementation exists (DataLoader batching)
-
-## ESLint Enforcement
-
-The project enforces JSDoc through `eslint-plugin-jsdoc` with these rules:
-
-### Required Documentation
-
-| Rule | Setting | What It Enforces |
-|------|---------|------------------|
-| `jsdoc/require-jsdoc` | error | JSDoc on function declarations, interfaces, type aliases, and PascalCase arrow functions |
-| `jsdoc/require-param-description` | error | All `@param` tags must have descriptions |
-| `jsdoc/require-returns-description` | error | All `@returns` tags must have descriptions |
-| `jsdoc/require-property-description` | error | All `@property` tags must have descriptions |
-
-### Allowed Tags
-
-| Rule | Setting | Effect |
-|------|---------|--------|
-| `jsdoc/check-tag-names` | `definedTags: ["remarks"]` | Allows `@remarks` for "why" documentation |
-| `jsdoc/no-types` | off | TypeScript types in JSDoc are optional |
-| `jsdoc/require-param-type` | off | Types come from TypeScript, not JSDoc |
-| `jsdoc/require-returns-type` | off | Types come from TypeScript, not JSDoc |
-
-### What Requires Documentation
-
-Per `jsdoc/require-jsdoc` configuration:
-
-```javascript
-{
-  require: {
-    FunctionDeclaration: true,      // function foo() {}
-    MethodDefinition: false,        // class methods (optional)
-    ClassDeclaration: false,        // classes (optional but recommended)
-    ArrowFunctionExpression: false, // const foo = () => {} (optional)
-    FunctionExpression: false,      // const foo = function() {} (optional)
-  },
-  contexts: [
-    "TSInterfaceDeclaration",       // interface Foo {}
-    "TSTypeAliasDeclaration",       // type Foo = ...
-    // PascalCase arrow functions (React components, factories):
-    "VariableDeclaration[declarations.0.init.type='ArrowFunctionExpression']:has([id.name=/^[A-Z]/])"
-  ]
-}
-```
-
-## Documentation Patterns
-
-### File Preambles
-
-Every file should have a preamble comment at the top:
-
-```typescript
-/**
- * @file complexity.plugin.ts
- * @description Apollo Server plugin for query complexity analysis and limiting
- * @module graphql
- */
-```
-
-| Tag | Purpose |
-|-----|---------|
-| `@file` | The filename (for navigation and search) |
-| `@description` | What this file provides |
-| `@module` | The feature module this belongs to |
-
-### Service Documentation
-
-```typescript
-/**
- * Service for managing user accounts
- * @description Provides CRUD operations for user entities
- * @remarks
- * - All methods are idempotent
- * - Throws NotFoundException for missing resources
- * - Uses DataLoader batching for bulk operations
- */
-@Injectable()
-export class UserService { ... }
-```
-
-### Method Documentation
-
-```typescript
-/**
- * Batch loads entities by IDs (for DataLoader)
- * @param ids - Array of entity IDs to load
- * @returns Promise resolving to array of entities in same order as input
- * @remarks Used by DataLoader for batching - maintains input order
- */
-async findByIds(ids: readonly string[]): Promise<Entity[]> { ... }
-```
-
-### Interface Documentation
-
-```typescript
-/**
- * Interface for authentication services
- * @description Defines the contract for both Cognito and Local auth implementations.
- * This interface ensures both AuthService (production) and LocalAuthService
- * (local development) provide the same public API for authentication operations.
- */
-export interface IAuthService {
-  /**
-   * Initiates the sign-in flow by sending an OTP to the user
-   * @param input - The sign-in input containing the user identifier (phone/email)
-   * @returns A promise resolving to the sign-in result with session and challenge info
-   */
-  signIn(input: SignInInput): Promise<SignInResult>;
-}
-```
-
-### Type/Constant Documentation
-
-```typescript
-/**
- * Default complexity configuration
- * @description Tune these values based on your server capacity
- */
-const COMPLEXITY_CONFIG = {
-  /** Maximum allowed query complexity */
-  maxComplexity: 100,
-  /** Default complexity for fields without explicit complexity */
-  defaultComplexity: 1,
-} as const;
-```
-
-## The @remarks Tag
-
-Use `@remarks` to document the "why" and important context:
-
-### When to Use @remarks
-
-| Use Case | Example |
-|----------|---------|
-| Design decisions | `@remarks Uses closure pattern to cache between Lambda invocations` |
-| Usage constraints | `@remarks Call getLoaders() once per GraphQL request in context factory` |
-| Non-obvious behavior | `@remarks Maintains input order for DataLoader compatibility` |
-| Important caveats | `@remarks All methods are idempotent - safe to retry` |
-| Integration details | `@remarks Connects on module initialization, disconnects on destruction` |
-
-### @remarks Format
-
-Use bullet points for multiple remarks:
-
-```typescript
-/**
- * Apollo Server plugin that calculates and limits query complexity
- * @description Prevents expensive queries from overwhelming the server
- * @remarks
- * - Uses field extensions estimator for custom complexity values
- * - Falls back to simple estimator with default complexity of 1
- * - Rejects queries that exceed the configured maximum complexity
- */
-```
-
-Use inline for single remarks:
-
-```typescript
-/**
- * Creates all DataLoader instances for a single request
- * @returns Object containing all typed DataLoaders
- * @remarks Called in GraphQL context factory - creates fresh instances per request
- */
-```
-
-## Parameter Descriptions
-
-### Bad: Restating the Name
-
-```typescript
-/**
- * @param id - The id
- * @param name - The name
- * @param options - The options
- */
-```
-
-### Good: Adding Value
-
-```typescript
-/**
- * @param id - The user's UUID (not the legacy numeric ID from v1 API)
- * @param name - Display name, max 50 characters, sanitized for XSS
- * @param options - Configuration for the query, see QueryOptions type
- */
-```
-
-### Parameter Description Guidelines
-
-| Include | Avoid |
-|---------|-------|
-| Valid value ranges | Restating the parameter name |
-| Format requirements | Restating the type |
-| Default behavior | Obvious information |
-| Edge cases | Implementation details |
-| Units (ms, bytes, etc.) | Internal variable names |
-
-## Return Value Descriptions
-
-### Bad: Restating the Type
-
-```typescript
-/**
- * @returns The user
- * @returns A promise
- * @returns The result
- */
-```
-
-### Good: Explaining Behavior
-
-```typescript
-/**
- * @returns The user if found, null if not found or soft-deleted
- * @returns Promise resolving to array of entities in same order as input
- * @returns Authentication tokens on success, error message on failure
- */
-```
-
-## Anti-Patterns to Avoid
-
-### Don't Document the Obvious
-
-```typescript
-// Wrong: Adds no value
-/**
- * Constructor
- */
-constructor() {}
-
-/**
- * Gets the name
- * @returns The name
- */
-getName(): string { return this.name; }
-```
-
-### Don't Duplicate TypeScript Types
-
-```typescript
-// Wrong: Type is already in signature
-/**
- * @param id - {string} The user ID
- * @returns {Promise<User>} The user
- */
-async getUser(id: string): Promise<User> { ... }
-
-// Correct: Description only, type from TypeScript
-/**
- * @param id - The user's UUID identifier
- * @returns The user entity with populated relations
- */
-async getUser(id: string): Promise<User> { ... }
-```
-
-### Don't Write Implementation Comments
-
-```typescript
-// Wrong: Documents how, not why
-/**
- * Loops through users and filters by active status
- */
-const activeUsers = users.filter(u => u.active);
-
-// Correct: Self-documenting code needs no comment
-// If explanation is needed, explain WHY:
-// Active users are filtered first to avoid unnecessary permission checks
-const activeUsers = users.filter(u => u.active);
-```
-
-## Escaping @ Symbols in JSDoc
-
-When documenting code that contains TypeScript/NestJS decorators (like `@Injectable()`, `@Processor('queue-name')`), JSDoc will interpret the `@` as a tag marker. This causes lint errors because JSDoc sees `@Processor('qpr-v2')` as a single unknown tag name (including the parentheses and arguments).
-
-**The problem:** Adding decorator names to `definedTags` doesn't help because JSDoc parses the entire string `@Processor('qpr-v2')` as the tag name, not just `@Processor`.
-
-### Solution 1: Backticks in Prose
-
-When mentioning decorators in description text, wrap them in backticks:
-
-```typescript
-/**
- * Queue processor for QPR calculations
- * @description Handles jobs from the `@Processor('qpr-v2')` queue
- * @remarks Uses `@Injectable()` scope for request isolation
- */
-```
-
-### Solution 2: Escape in @example Blocks
-
-In `@example` blocks, use fenced code blocks and escape `@` as `\@`:
-
-```typescript
-/**
- * Creates a queue processor
- * @example
- * ```typescript
- * \@Processor('my-queue')
- * export class MyProcessor {
- *   \@Process()
- *   async handle(job: Job) { ... }
- * }
- * ```
- */
-```
-
-### Quick Reference for Escaping
-
-| Context | Approach | Example |
-|---------|----------|---------|
-| Prose/description | Wrap in backticks | `` `@Injectable()` `` |
-| @example block | Escape with backslash | `\@Processor('name')` |
-| Code comments | No escaping needed | `// Uses @Injectable` |
-
-## Quick Reference
-
-### Required Structure for Services
-
-```typescript
-/**
- * @file feature.service.ts
- * @description Service providing feature functionality
- * @module feature
- */
-
-/**
- * Service for feature operations
- * @description Brief description of what this service handles
- * @remarks
- * - Important architectural decisions
- * - Usage patterns or constraints
- */
-@Injectable()
-export class FeatureService {
-  /**
-   * Brief description of what this method does
-   * @param paramName - What this parameter represents and any constraints
-   * @returns What is returned and under what conditions
-   * @remarks Any non-obvious behavior or usage notes
-   */
-  methodName(paramName: Type): ReturnType { ... }
-}
-```
-
-### Required Structure for Interfaces
-
-```typescript
-/**
- * Interface for feature operations
- * @description Explains the contract this interface defines
- */
-export interface IFeature {
-  /**
-   * Method description
-   * @param param - Parameter description with constraints
-   * @returns Return description with conditions
-   */
-  method(param: Type): ReturnType;
-}
-```
-
-### Required Structure for Types
-
-```typescript
-/**
- * Represents a feature configuration
- * @description Used to configure feature behavior at initialization
- */
-export type FeatureConfig = {
-  /** Maximum retry attempts before failing */
-  maxRetries: number;
-  /** Timeout in milliseconds */
-  timeoutMs: number;
-};
-```
-
-## Verification Checklist
-
-Before committing code, verify:
-
-1. **File preamble exists**: `@file`, `@description`, `@module`
-2. **Function declarations have JSDoc**: Required by ESLint
-3. **Interfaces have JSDoc**: Required by ESLint
-4. **Type aliases have JSDoc**: Required by ESLint
-5. **Parameters have meaningful descriptions**: Not just restating the name
-6. **Returns have meaningful descriptions**: Explain conditions and edge cases
-7. **@remarks used for "why"**: Design decisions, constraints, non-obvious behavior
-8. **No TypeScript types in JSDoc**: Types come from the signature

package/plugins/lisa-rails/skills/lisa-review-implementation/SKILL.md

@@ -1,209 +0,0 @@
----
-name: lisa-review-implementation
-description: This skill should be used when comparing a project's Lisa-managed files against Lisa's source templates to identify drift. It reads the project manifest, locates source templates, generates diffs for drifted files, and offers to upstream improvements back to Lisa.
----
-
-# Lisa Implementation Review
-
-This skill compares the current project's Lisa-managed files against Lisa's source templates to identify drift and offer to upstream improvements back to Lisa.
-
-## Prerequisites
-
-This skill requires access to the Lisa installation directory. Either:
-1. Start Claude Code with `--add-dir ~/lisa` (or your Lisa path)
-2. Pass the Lisa directory as an argument: `/lisa-review-implementation ~/lisa`
-
-## Instructions
-
-### Step 1: Locate Lisa Directory
-
-First, determine the Lisa installation directory:
-
-1. If an argument was provided, use that path
-2. Otherwise, check if any `--add-dir` paths contain a `src/core/lisa.ts` file (Lisa's signature file)
-3. Common locations to check: `~/lisa`, `~/workspace/lisa`, `../lisa`
-
-If Lisa directory cannot be found, inform the user:
-```
-Unable to locate Lisa installation directory.
-
-Please either:
-1. Start Claude Code with: claude --add-dir /path/to/lisa
-2. Run this command with the path: /lisa-review-implementation /path/to/lisa
-```
-
-### Step 2: Read the Manifest
-
-Read the project's `.lisa-manifest` file to get the list of managed files.
-
-Parse each line to extract:
-- `strategy`: The copy strategy used (copy-overwrite, copy-contents, merge, create-only)
-- `relativePath`: The file path relative to project root
-
-Skip:
-- Lines starting with `#` (comments)
-- Empty lines
-- Files with `create-only` strategy (these are meant to be customized)
-- Files with `merge` strategy (these are intentionally combined)
-
-### Step 3: Find Source Templates
-
-For each managed file, locate its source in Lisa by checking these directories in order:
-1. `npm-package/copy-overwrite/` and `npm-package/copy-contents/`
-2. `cdk/copy-overwrite/` and `cdk/copy-contents/`
-3. `nestjs/copy-overwrite/` and `nestjs/copy-contents/`
-4. `expo/copy-overwrite/` and `expo/copy-contents/`
-5. `typescript/copy-overwrite/` and `typescript/copy-contents/`
-6. `all/copy-overwrite/` and `all/copy-contents/`
-
-The FIRST match wins (most specific type takes precedence).
-
-Detect which project types apply by checking the project for:
-- `npm-package`: package.json without `"private": true` AND has `main`, `bin`, `exports`, or `files`
-- `cdk`: presence of `cdk.json` or `aws-cdk` in dependencies
-- `nestjs`: presence of `nest-cli.json` or `@nestjs` in dependencies
-- `expo`: presence of `app.json`, `eas.json`, or `expo` in dependencies
-- `typescript`: presence of `tsconfig.json` or `typescript` in dependencies
-
-Only check type directories that match the project.
-
-### Step 4: Compare Files
-
-For each file, compare the project version against the Lisa source:
-
-1. Read both files
-2. If identical, mark as "in sync"
-3. If different, generate a diff summary
-
-Use the Bash tool with `diff` to generate readable diffs:
-```bash
-diff -u "/path/to/lisa/source" "/path/to/project/file" || true
-```
-
-### Step 5: Generate Report
-
-Create a markdown report with these sections:
-
-```markdown
-# Lisa Implementation Review
-
-**Project:** [project name from package.json]
-**Lisa Source:** [lisa directory path]
-**Generated:** [current date/time]
-
-## Summary
-
-- **Total managed files:** X
-- **In sync:** X
-- **Drifted:** X
-- **Source not found:** X
-
-## Drifted Files
-
-### [relative/path/to/file]
-
-**Source:** [lisa-type]/copy-overwrite/[path]
-**Strategy:** copy-overwrite
-
-<details>
-<summary>View diff</summary>
-
-```diff
-[diff output]
-```
-
-</details>
-
-**Recommendation:** [Brief analysis of whether this change should be upstreamed]
-
----
-
-[Repeat for each drifted file]
-
-## Files Not Found in Lisa
-
-These files are in the manifest but their source templates couldn't be located:
-
-- [list of files]
-
-## In Sync Files
-
-<details>
-<summary>X files are in sync with Lisa</summary>
-
-- [list of files]
-
-</details>
-```
-
-### Step 6: Offer to Upstream Changes
-
-After presenting the report, ask the user which drifted files they want to copy back to Lisa.
-
-For each file the user wants to upstream:
-
-1. Confirm the target path in Lisa (e.g., `typescript/copy-overwrite/.github/workflows/ci.yml`)
-2. Use the Write tool to copy the project's version to Lisa
-3. Report success
-
-Example prompt:
-```
-I found X files that have drifted from Lisa's templates.
-
-Which files would you like to copy back to Lisa?
-1. .github/workflows/ci.yml - [brief description of changes]
-2. .claude/settings.json - [brief description of changes]
-3. All of the above
-4. None - just show me the report
-
-Select an option (or list specific numbers):
-```
-
-### Important Notes
-
-- **Never auto-upstream without confirmation** - always ask the user first
-- **Preserve the most specific type directory** - if a file exists in both `typescript/` and `all/`, upstream to where it currently exists
-- **Handle binary files gracefully** - skip comparison for non-text files
-- **Respect .gitignore patterns** - some generated files shouldn't be compared
-- For `copy-contents` files like `.gitignore`, the comparison is trickier since the project may have additional lines - highlight only if Lisa's required lines are missing
-
-## Example Usage
-
-```
-User: /lisa-review-implementation
-
-Claude: I'll review your project's Lisa-managed files against the Lisa source templates.
-
-[Locates Lisa directory]
-[Reads manifest]
-[Compares files]
-[Generates report]
-
-# Lisa Implementation Review
-
-**Project:** my-awesome-app
-**Lisa Source:** /Users/dev/lisa
-**Generated:** 2026-01-18 10:30:00
-
-## Summary
-
-- **Total managed files:** 45
-- **In sync:** 42
-- **Drifted:** 3
-- **Source not found:** 0
-
-## Drifted Files
-
-### .github/workflows/ci.yml
-
-**Source:** typescript/copy-overwrite/.github/workflows/ci.yml
-**Strategy:** copy-overwrite
-
-[diff details]
-
-**Recommendation:** This adds a new caching step that improves CI performance. Good candidate for upstreaming.
-
----
-
-I found 3 files that have drifted. Would you like to upstream any of these changes back to Lisa?
-```