npm - @webpieces/dev-config - Versions diffs - 0.2.32 → 0.2.34 - Mend

@webpieces/dev-config 0.2.32 → 0.2.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/eslint-plugin/rules/no-unmanaged-exceptions.js +18 -467
package/eslint-plugin/rules/no-unmanaged-exceptions.js.map +1 -1
package/eslint-plugin/rules/no-unmanaged-exceptions.ts +21 -468
package/executors/validate-versions/executor.d.ts +16 -0
package/executors/validate-versions/executor.js +210 -0
package/executors/validate-versions/executor.js.map +1 -0
package/executors/validate-versions/executor.ts +255 -0
package/executors/validate-versions/schema.json +8 -0
package/executors.json +5 -0
package/package.json +1 -1
package/templates/webpieces.exceptions.md +677 -0

package/eslint-plugin/rules/no-unmanaged-exceptions.js CHANGED Viewed

@@ -91,483 +91,34 @@ function ensureDocFile(docPath, content) {
 /**
  * Ensures the exception documentation markdown file exists
  * Only creates file once per lint run using module-level flag
+ *
+ * Reads from the template file packaged with @webpieces/dev-config
+ * and copies it to tmp/webpieces/ for AI agents to read.
  */
 function ensureExceptionDoc(context) {
     if (exceptionDocCreated)
         return;
     const workspaceRoot = getWorkspaceRoot(context);
     const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.exceptions.md');
-    if (ensureDocFile(docPath, EXCEPTION_DOC_CONTENT)) {
-        exceptionDocCreated = true;
-    }
-}
-// Module-level flag to prevent redundant markdown file creation
-let exceptionDocCreated = false;
-// Comprehensive markdown documentation content
-const EXCEPTION_DOC_CONTENT = `# AI Agent Instructions: Try-Catch Blocks Detected
-**READ THIS FILE to understand why try-catch blocks are restricted and how to fix violations**
-## Core Principle
-**EXCEPTIONS MUST BUBBLE TO GLOBAL HANDLER WITH TRACEID FOR DEBUGGABILITY.**
-The webpieces framework uses a global error handling architecture where:
-- Every request gets a unique traceId stored in RequestContext
-- All errors bubble to the global handler (WebpiecesMiddleware.globalErrorHandler)
-- Error IDs enable lookup via \`/debugLocal/{id}\` and \`/debugCloud/{id}\` endpoints
-- Local try-catch blocks break this pattern by losing error IDs and context
-This is not a performance concern - it's an architecture decision for distributed tracing and debugging in production.
-## Why This Rule Exists
-### Problem 1: AI Over-Adds Try-Catch (Especially Frontend)
-AI agents tend to add defensive try-catch blocks everywhere, which:
-- Swallows errors and loses traceId
-- Shows custom error messages without debugging context
-- Makes production issues impossible to trace
-- Creates "blind spots" where errors disappear
-### Problem 2: Lost TraceId = Lost Debugging Capability
-Without traceId in errors:
-- \`/debugLocal/{id}\` endpoint cannot retrieve error details
-- \`/debugCloud/{id}\` endpoint cannot correlate logs
-- DevOps cannot trace request flow through distributed systems
-- Users report "an error occurred" with no way to investigate
-### Problem 3: Try-Catch-Rethrow Is Code Smell
-\`\`\`typescript
-// BAD: Why catch if you're just rethrowing?
-try {
-  await operation();
-} catch (err: any) {
-  const error = toError(err);
-  console.error('Failed:', error);
-  throw error;  // Why catch at all???
-}
-\`\`\`
-99% of the time, there's a better pattern (logging filter, global handler, etc.).
-### Problem 4: Swallowing Exceptions = Lazy Programming
-\`\`\`typescript
-// BAD: "I don't want to deal with this error"
-try {
-  await riskyOperation();
-} catch (err: any) {
-  // Silence...
-}
-\`\`\`
-This is the #1 shortcut developers take that creates production nightmares.
-## Industry Best Practices (2025)
-### Distributed Tracing: The Three Pillars
-Modern observability requires correlation across:
-1. **Traces** - Request flow through services
-2. **Logs** - Contextual debugging information
-3. **Metrics** - Aggregated system health
-TraceId (also called correlation ID, request ID) ties these together.
-### Research Findings
-- **Performance**: Try-catch is an expensive operation in V8 engine (source: Node.js performance docs)
-- **Error Handling**: Global handlers at highest level reduce blind spots by 40% (source: Google SRE practices)
-- **Middleware Pattern**: Express/Koa middleware with async error boundaries is industry standard (source: Express.js error handling docs)
-- **Only Catch What You Can Handle**: If you can't recover, let it bubble (source: "Effective Error Handling" - JavaScript design patterns)
-### 2025 Trends
-- Correlation IDs are standard in microservices (OpenTelemetry, Datadog, New Relic)
-- Structured logging with context (Winston, Pino)
-- Middleware-based error boundaries reduce boilerplate
-- Frontend: React Error Boundaries, not scattered try-catch
-## Command: Remove Try-Catch and Use Global Handler
-## AI Agent Action Steps
-1. **IDENTIFY** the try-catch block flagged in the error message
-2. **ANALYZE** the purpose:
-   - Is it catching errors just to log them? → Remove (use LogApiFilter)
-   - Is it catching to show custom message? → Remove (use global handler)
-   - Is it catching to retry? → Requires approval (see Acceptable Patterns)
-   - Is it catching in a batch loop? → Requires approval (see Acceptable Patterns)
-   - Is it catching for cleanup? → Usually wrong pattern
-3. **REMOVE** the try-catch block:
-   - Delete the \`try {\` and \`} catch (err: any) { ... }\` wrapper
-   - Let the code execute normally
-   - Errors will bubble to global handler automatically
-4. **VERIFY** global handler exists:
-   - Check that WebpiecesMiddleware.globalErrorHandler is registered
-   - Check that ContextFilter is setting up RequestContext
-   - Check that traceId is being added to RequestContext
-5. **ADD** traceId to RequestContext (if not already present):
-   - In ContextFilter or similar high-priority filter
-   - Use \`RequestContext.put('TRACE_ID', generateTraceId())\`
-6. **TEST** error flow:
-   - Trigger an error in the code
-   - Verify error is logged with traceId
-   - Verify \`/debugLocal/{traceId}\` endpoint works
-## Pattern 1: Global Error Handler (GOOD)
-### Server-Side: WebpiecesMiddleware
-\`\`\`typescript
-// packages/http/http-server/src/WebpiecesMiddleware.ts
-@provideSingleton()
-@injectable()
-export class WebpiecesMiddleware {
-  async globalErrorHandler(
-    req: Request,
-    res: Response,
-    next: NextFunction
-  ): Promise<void> {
-    console.log('[GlobalErrorHandler] Request START:', req.method, req.path);
+    // Read from the template file packaged with the npm module
+    // Path: from eslint-plugin/rules/ -> ../../templates/
+    const templatePath = path.join(__dirname, '..', '..', 'templates', 'webpieces.exceptions.md');
+    let content;
     try {
-      // Await catches BOTH sync throws AND rejected promises
-      await next();
-      console.log('[GlobalErrorHandler] Request END (success)');
-    } catch (err: any) {
-      const error = toError(err);
-      const traceId = RequestContext.get<string>('TRACE_ID');
-      // Log with traceId for /debugLocal lookup
-      console.error('[GlobalErrorHandler] ERROR:', {
-        traceId,
-        message: error.message,
-        stack: error.stack,
-        path: req.path,
-        method: req.method,
-      });
-      // Store error for /debugLocal/{id} endpoint
-      ErrorStore.save(traceId, error);
-      if (!res.headersSent) {
-        res.status(500).send(\`
-          <!DOCTYPE html>
-          <html>
-          <head><title>Server Error</title></head>
-          <body>
-            <h1>Server Error</h1>
-            <p>An error occurred. Reference ID: \${traceId}</p>
-            <p>Contact support with this ID to investigate.</p>
-          </body>
-          </html>
-        \`);
-      }
-    }
-  }
-}
-\`\`\`
-### Adding TraceId: ContextFilter
-\`\`\`typescript
-// packages/http/http-server/src/filters/ContextFilter.ts
-import { v4 as uuidv4 } from 'uuid';
-@provideSingleton()
-@injectable()
-export class ContextFilter extends Filter<MethodMeta, WpResponse<unknown>> {
-  async filter(
-    meta: MethodMeta,
-    nextFilter: Service<MethodMeta, WpResponse<unknown>>
-  ): Promise<WpResponse<unknown>> {
-    return RequestContext.run(async () => {
-      // Generate unique traceId for this request
-      const traceId = uuidv4();
-      RequestContext.put('TRACE_ID', traceId);
-      RequestContext.put('METHOD_META', meta);
-      RequestContext.put('REQUEST_PATH', meta.path);
-      return await nextFilter.invoke(meta);
-      // RequestContext auto-cleared when done
-    });
-  }
-}
-\`\`\`
-## Pattern 2: Debug Endpoints (GOOD)
-\`\`\`typescript
-// Example debug endpoint for local development
-@provideSingleton()
-@Controller()
-export class DebugController implements DebugApi {
-  @Get()
-  @Path('/debugLocal/:id')
-  async getErrorById(@PathParam('id') id: string): Promise<DebugErrorResponse> {
-    const error = ErrorStore.get(id);
-    if (!error) {
-      throw new HttpNotFoundError(\`Error \${id} not found\`);
+        content = fs.readFileSync(templatePath, 'utf-8');
     }
-    return {
-      traceId: id,
-      message: error.message,
-      stack: error.stack,
-      timestamp: error.timestamp,
-      requestPath: error.requestPath,
-      requestMethod: error.requestMethod,
-    };
-  }
-}
-// ErrorStore singleton (in-memory for local, Redis for production)
-class ErrorStoreImpl {
-  private errors = new Map<string, ErrorRecord>();
-  save(traceId: string, error: Error): void {
-    this.errors.set(traceId, {
-      traceId,
-      message: error.message,
-      stack: error.stack,
-      timestamp: new Date(),
-      requestPath: RequestContext.get('REQUEST_PATH'),
-      requestMethod: RequestContext.get('HTTP_METHOD'),
-    });
-  }
-  get(traceId: string): ErrorRecord | undefined {
-    return this.errors.get(traceId);
-  }
-}
-export const ErrorStore = new ErrorStoreImpl();
-\`\`\`
-## Examples
-### BAD Example 1: Local Try-Catch That Swallows Error
-\`\`\`typescript
-// BAD: Error is swallowed, no traceId in logs
-async function processOrder(order: Order): Promise<void> {
-  try {
-    await validateOrder(order);
-    await saveToDatabase(order);
-  } catch (err: any) {
-    // Error disappears into void - debugging nightmare!
-    console.log('Order processing failed');
-  }
-}
-\`\`\`
-**Problem**: When this fails in production, you have:
-- No traceId to look up the error
-- No stack trace
-- No request context
-- No way to investigate
-### BAD Example 2: Try-Catch With Custom Error (No TraceId)
-\`\`\`typescript
-// BAD: Shows custom message but loses traceId
-async function fetchUserData(userId: string): Promise<User> {
-  try {
-    const response = await fetch(\`/api/users/\${userId}\`);
-    return await response.json();
-  } catch (err: any) {
-    const error = toError(err);
-    // Custom message without traceId
-    throw new Error(\`Failed to fetch user \${userId}: \${error.message}\`);
-  }
-}
-\`\`\`
-**Problem**:
-- Original error context is lost
-- No traceId attached to new error
-- Global handler receives generic error, can't trace root cause
-### GOOD Example 1: Let Error Bubble
-\`\`\`typescript
-// GOOD: Error bubbles to global handler with traceId
-async function processOrder(order: Order): Promise<void> {
-  // No try-catch needed!
-  await validateOrder(order);
-  await saveToDatabase(order);
-  // If error occurs, it bubbles with traceId intact
-}
-\`\`\`
-**Why GOOD**:
-- Global handler catches error
-- TraceId from RequestContext is preserved
-- Full stack trace available
-- \`/debugLocal/{traceId}\` endpoint works
-### GOOD Example 2: Global Handler Logs With TraceId
-\`\`\`typescript
-// GOOD: Global handler has full context
-// In WebpiecesMiddleware.globalErrorHandler (see Pattern 1 above)
-catch (err: any) {
-  const error = toError(err);
-  const traceId = RequestContext.get<string>('TRACE_ID');
-  console.error('[GlobalErrorHandler] ERROR:', {
-    traceId,          // Unique ID for this request
-    message: error.message,
-    stack: error.stack,
-    path: req.path,   // Request context preserved
-  });
-}
-\`\`\`
-**Why GOOD**:
-- TraceId logged with every error
-- Full request context available
-- Error stored for \`/debugLocal/{id}\` lookup
-- DevOps can trace distributed requests
-### ACCEPTABLE Example 1: Retry Loop (With eslint-disable)
-\`\`\`typescript
-// ACCEPTABLE: Retry pattern requires try-catch
-// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Retry loop with exponential backoff
-async function callVendorApiWithRetry(request: VendorRequest): Promise<VendorResponse> {
-  const maxRetries = 3;
-  let lastError: Error | undefined;
-  for (let i = 0; i < maxRetries; i++) {
-    try {
-      return await vendorApi.call(request);
-    } catch (err: any) {
-      const error = toError(err);
-      lastError = error;
-      console.warn(\`Retry \${i + 1}/\${maxRetries} failed:\`, error.message);
-      await sleep(1000 * Math.pow(2, i)); // Exponential backoff
+    catch {
+        // Fallback message if template not found (shouldn't happen in published package)
+        content = `# Exception Documentation Not Found\n\nTemplate file not found at: ${templatePath}\n\nPlease ensure @webpieces/dev-config is properly installed.`;
     }
-  }
-  // After retries exhausted, throw with traceId
-  const traceId = RequestContext.get<string>('TRACE_ID');
-  throw new HttpVendorError(
-    \`Vendor API failed after \${maxRetries} retries. TraceId: \${traceId}\`,
-    lastError
-  );
-}
-\`\`\`
-**Why ACCEPTABLE**:
-- Legitimate use case: retry logic
-- Final error still includes traceId
-- Error still bubbles to global handler
-- Requires senior developer approval (enforced by PR review)
-### ACCEPTABLE Example 2: Batching Pattern (With eslint-disable)
-\`\`\`typescript
-// ACCEPTABLE: Batching requires try-catch to continue processing
-// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Batch processing continues on individual failures
-async function processBatch(items: Item[]): Promise<BatchResult> {
-  const results: ItemResult[] = [];
-  const errors: ItemError[] = [];
-  const traceId = RequestContext.get<string>('TRACE_ID');
-  for (const item of items) {
-    try {
-      const result = await processItem(item);
-      results.push(result);
-    } catch (err: any) {
-      const error = toError(err);
-      // Log individual error with traceId
-      console.error(\`[Batch] Item \${item.id} failed (traceId: \${traceId}):\`, error);
-      errors.push({ itemId: item.id, error: error.message, traceId });
+    if (ensureDocFile(docPath, content)) {
+        exceptionDocCreated = true;
     }
-  }
-  // Return both successes and failures
-  return {
-    traceId,
-    successCount: results.length,
-    failureCount: errors.length,
-    results,
-    errors,
-  };
 }
-\`\`\`
-**Why ACCEPTABLE**:
-- Legitimate use case: partial failure handling
-- Each error logged with traceId
-- Batch traceId included in response
-- Requires senior developer approval (enforced by PR review)
-### UNACCEPTABLE Example: Try-Catch-Rethrow
-\`\`\`typescript
-// UNACCEPTABLE: Pointless try-catch that just rethrows
-async function saveUser(user: User): Promise<void> {
-  try {
-    await database.save(user);
-  } catch (err: any) {
-    const error = toError(err);
-    console.error('Save failed:', error);
-    throw error;  // Why catch at all???
-  }
-}
-\`\`\`
-**Why UNACCEPTABLE**:
-- Adds no value - logging should be in LogApiFilter
-- Global handler already logs errors
-- Just adds noise and confusion
-- Remove the try-catch entirely!
-## When eslint-disable IS Acceptable
-You may use \`// eslint-disable-next-line @webpieces/no-unmanaged-exceptions\` ONLY for:
-1. **Retry loops** with exponential backoff (vendor API calls)
-2. **Batching patterns** where partial failure is expected
-3. **Resource cleanup** with explicit approval
-All three require:
-- Senior developer approval in PR review
-- Comment explaining WHY try-catch is needed
-- TraceId must still be logged/included in final error
-## How to Request Approval
-If you believe you have a legitimate use case for try-catch:
-1. **Add a comment** explaining why it's needed:
-   \`\`\`typescript
-   // JUSTIFICATION: Vendor API requires retry loop with exponential backoff
-   // to handle rate limiting. Final error includes traceId for debugging.
-   // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
-   \`\`\`
-2. **Ensure traceId is preserved** in final error or logged
-3. **Request PR review** from senior developer
-4. **Be prepared to justify** - 99% of try-catch can be removed
-## Summary
-**The webpieces philosophy**: Errors should bubble to the global handler where they are logged with traceId and stored for debugging. Local try-catch blocks break this architecture and create blind spots in production.
-**Key takeaways**:
-- Global error handler with traceId = debuggable production issues
-- Local try-catch = lost context and debugging nightmares
-- 99% of try-catch blocks can be removed safely
-- Only use try-catch for: retries, batching (with approval)
-- TraceId enables \`/debugLocal/{id}\` and \`/debugCloud/{id}\` endpoints
-**Remember**: If you can't handle the error meaningfully, don't catch it. Let it bubble to the global handler where it will be logged with full context and traceId.
-`;
+// Module-level flag to prevent redundant markdown file creation
+let exceptionDocCreated = false;
+// NOTE: Documentation content moved to templates/webpieces.exceptions.md
+// The ensureExceptionDoc function reads from that file at runtime.
 const rule = {
     meta: {
         type: 'problem',
@@ -598,7 +149,7 @@ const rule = {
                 // Has catch block outside test file - report violation
                 ensureExceptionDoc(context);
                 context.report({
-                    node,
+                    node: node,
                     messageId: 'noUnmanagedExceptions',
                 });
             },

package/eslint-plugin/rules/no-unmanaged-exceptions.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"no-unmanaged-exceptions.js","sourceRoot":"","sources":["../../../../../../packages/tooling/dev-config/eslint-plugin/rules/no-unmanaged-exceptions.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;AAGH,+CAAyB;AACzB,mDAA6B;AAE7B;;;GAGG;AACH,SAAS,UAAU,CAAC,QAAgB;IAChC,MAAM,cAAc,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IAE9C,wBAAwB;IACxB,IAAI,cAAc,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,cAAc,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7E,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,yCAAyC;IACzC,IAAI,cAAc,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QACrF,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,OAAyB;IAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAC3D,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEjC,yBAAyB;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QAC/C,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC;gBACD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;gBAC1D,sCAAsC;gBACtC,IAAI,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;oBAChD,OAAO,GAAG,CAAC;gBACf,CAAC;YACL,CAAC;YAAC,MAAM,CAAC;gBACL,+BAA+B;YACnC,CAAC;QACL,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,SAAS,KAAK,GAAG;YAAE,MAAM,CAAC,0BAA0B;QACxD,GAAG,GAAG,SAAS,CAAC;IACpB,CAAC;IAED,qCAAqC;IACrC,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa,CAAC,OAAe,EAAE,OAAe;IACnD,IAAI,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,CAAC;QAED,+CAA+C;QAC/C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC7E,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAChD,CAAC;QAED,OAAO,IAAI,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,6DAA6D;QAC7D,OAAO,KAAK,CAAC;IACjB,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,SAAS,kBAAkB,CAAC,OAAyB;IACjD,IAAI,mBAAmB;QAAE,OAAO;IAEhC,MAAM,aAAa,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK,EAAE,WAAW,EAAE,yBAAyB,CAAC,CAAC;IAExF,IAAI,aAAa,CAAC,OAAO,EAAE,qBAAqB,CAAC,EAAE,CAAC;QAChD,mBAAmB,GAAG,IAAI,CAAC;IAC/B,CAAC;AACL,CAAC;AAED,gEAAgE;AAChE,IAAI,mBAAmB,GAAG,KAAK,CAAC;AAEhC,+CAA+C;AAC/C,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+c7B,CAAC;AAEF,MAAM,IAAI,GAAoB;IAC1B,IAAI,EAAE;QACF,IAAI,EAAE,SAAS;QACf,IAAI,EAAE;YACF,WAAW,EAAE,4EAA4E;YACzF,QAAQ,EAAE,gBAAgB;YAC1B,WAAW,EAAE,IAAI;YACjB,GAAG,EAAE,8FAA8F;SACtG;QACD,QAAQ,EAAE;YACN,qBAAqB,EACjB,oMAAoM;SAC3M;QACD,OAAO,EAAE,SAAS;QAClB,MAAM,EAAE,EAAE;KACb;IAED,MAAM,CAAC,OAAyB;QAC5B,OAAO;YACH,YAAY,CAAC,IAAS;gBAClB,qEAAqE;gBACrE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;oBAChB,OAAO;gBACX,CAAC;gBAED,2BAA2B;gBAC3B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;gBAC3D,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACvB,OAAO;gBACX,CAAC;gBAED,uDAAuD;gBACvD,kBAAkB,CAAC,OAAO,CAAC,CAAC;gBAC5B,OAAO,CAAC,MAAM,CAAC;oBACX,IAAI;oBACJ,SAAS,EAAE,uBAAuB;iBACrC,CAAC,CAAC;YACP,CAAC;SACJ,CAAC;IACN,CAAC;CACJ,CAAC;AAEF,iBAAS,IAAI,CAAC","sourcesContent":["/*\n ESLint rule to discourage try-catch blocks outside test files\n \n Works alongside catch-error-pattern rule:\n * - catch-error-pattern: Enforces HOW to handle exceptions (with toError())\n * - no-unmanaged-exceptions: Enforces WHERE try-catch is allowed (tests only by default)\n \n Philosophy: Exceptions should bubble to global error handlers where they are logged\n * with traceId and stored for debugging via /debugLocal and /debugCloud endpoints.\n * Local try-catch blocks break this architecture and create blind spots in production.\n \n Auto-allowed in:\n * - Test files (.test.ts, .spec.ts, __tests__/)\n \n Requires eslint-disable comment in:\n * - Retry loops with exponential backoff\n * - Batch processing where partial failure is expected\n * - Resource cleanup (with approval)\n /\n\nimport type { Rule } from 'eslint';\nimport as fs from 'fs';\nimport * as path from 'path';\n\n/*\n Determines if a file is a test file based on naming conventions\n * Test files are auto-allowed to use try-catch blocks\n /\nfunction isTestFile(filename: string): boolean {\n const normalizedPath = filename.toLowerCase();\n\n // Check file extensions\n if (normalizedPath.endsWith('.test.ts') \|\| normalizedPath.endsWith('.spec.ts')) {\n return true;\n }\n\n // Check directory names (cross-platform)\n if (normalizedPath.includes('/__tests__/') \|\| normalizedPath.includes('\\\\__tests__\\\\')) {\n return true;\n }\n\n return false;\n}\n\n/\n Finds the workspace root by walking up the directory tree\n * Looks for package.json with workspaces or name === 'webpieces-ts'\n /\nfunction getWorkspaceRoot(context: Rule.RuleContext): string {\n const filename = context.filename \|\| context.getFilename();\n let dir = path.dirname(filename);\n\n // Walk up directory tree\n for (let i = 0; i < 10; i++) {\n const pkgPath = path.join(dir, 'package.json');\n if (fs.existsSync(pkgPath)) {\n try {\n const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));\n // Check if this is the root workspace\n if (pkg.workspaces \|\| pkg.name === 'webpieces-ts') {\n return dir;\n }\n } catch {\n // Invalid JSON, keep searching\n }\n }\n\n const parentDir = path.dirname(dir);\n if (parentDir === dir) break; // Reached filesystem root\n dir = parentDir;\n }\n\n // Fallback: return current directory\n return process.cwd();\n}\n\n/\n Ensures a documentation file exists at the given path\n * Creates parent directories if needed\n /\nfunction ensureDocFile(docPath: string, content: string): boolean {\n try {\n const dir = path.dirname(docPath);\n if (!fs.existsSync(dir)) {\n fs.mkdirSync(dir, { recursive: true });\n }\n\n // Only write if file doesn't exist or is empty\n if (!fs.existsSync(docPath) \|\| fs.readFileSync(docPath, 'utf-8').trim() === '') {\n fs.writeFileSync(docPath, content, 'utf-8');\n }\n\n return true;\n } catch (error) {\n // Silently fail - don't break linting if file creation fails\n return false;\n }\n}\n\n/\n Ensures the exception documentation markdown file exists\n * Only creates file once per lint run using module-level flag\n /\nfunction ensureExceptionDoc(context: Rule.RuleContext): void {\n if (exceptionDocCreated) return;\n\n const workspaceRoot = getWorkspaceRoot(context);\n const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.exceptions.md');\n\n if (ensureDocFile(docPath, EXCEPTION_DOC_CONTENT)) {\n exceptionDocCreated = true;\n }\n}\n\n// Module-level flag to prevent redundant markdown file creation\nlet exceptionDocCreated = false;\n\n// Comprehensive markdown documentation content\nconst EXCEPTION_DOC_CONTENT = `# AI Agent Instructions: Try-Catch Blocks Detected\n\nREAD THIS FILE to understand why try-catch blocks are restricted and how to fix violations\n\n## Core Principle\n\nEXCEPTIONS MUST BUBBLE TO GLOBAL HANDLER WITH TRACEID FOR DEBUGGABILITY.\n\nThe webpieces framework uses a global error handling architecture where:\n- Every request gets a unique traceId stored in RequestContext\n- All errors bubble to the global handler (WebpiecesMiddleware.globalErrorHandler)\n- Error IDs enable lookup via \\`/debugLocal/{id}\\` and \\`/debugCloud/{id}\\` endpoints\n- Local try-catch blocks break this pattern by losing error IDs and context\n\nThis is not a performance concern - it's an architecture decision for distributed tracing and debugging in production.\n\n## Why This Rule Exists\n\n### Problem 1: AI Over-Adds Try-Catch (Especially Frontend)\nAI agents tend to add defensive try-catch blocks everywhere, which:\n- Swallows errors and loses traceId\n- Shows custom error messages without debugging context\n- Makes production issues impossible to trace\n- Creates \"blind spots\" where errors disappear\n\n### Problem 2: Lost TraceId = Lost Debugging Capability\nWithout traceId in errors:\n- \\`/debugLocal/{id}\\` endpoint cannot retrieve error details\n- \\`/debugCloud/{id}\\` endpoint cannot correlate logs\n- DevOps cannot trace request flow through distributed systems\n- Users report \"an error occurred\" with no way to investigate\n\n### Problem 3: Try-Catch-Rethrow Is Code Smell\n\\`\\`\\`typescript\n// BAD: Why catch if you're just rethrowing?\ntry {\n await operation();\n} catch (err: any) {\n const error = toError(err);\n console.error('Failed:', error);\n throw error; // Why catch at all???\n}\n\\`\\`\\`\n99% of the time, there's a better pattern (logging filter, global handler, etc.).\n\n### Problem 4: Swallowing Exceptions = Lazy Programming\n\\`\\`\\`typescript\n// BAD: \"I don't want to deal with this error\"\ntry {\n await riskyOperation();\n} catch (err: any) {\n // Silence...\n}\n\\`\\`\\`\nThis is the #1 shortcut developers take that creates production nightmares.\n\n## Industry Best Practices (2025)\n\n### Distributed Tracing: The Three Pillars\nModern observability requires correlation across:\n1. Traces* - Request flow through services\n2. Logs - Contextual debugging information\n3. Metrics - Aggregated system health\n\nTraceId (also called correlation ID, request ID) ties these together.\n\n### Research Findings\n- Performance: Try-catch is an expensive operation in V8 engine (source: Node.js performance docs)\n- Error Handling: Global handlers at highest level reduce blind spots by 40% (source: Google SRE practices)\n- Middleware Pattern: Express/Koa middleware with async error boundaries is industry standard (source: Express.js error handling docs)\n- Only Catch What You Can Handle: If you can't recover, let it bubble (source: \"Effective Error Handling\" - JavaScript design patterns)\n\n### 2025 Trends\n- Correlation IDs are standard in microservices (OpenTelemetry, Datadog, New Relic)\n- Structured logging with context (Winston, Pino)\n- Middleware-based error boundaries reduce boilerplate\n- Frontend: React Error Boundaries, not scattered try-catch\n\n## Command: Remove Try-Catch and Use Global Handler\n\n## AI Agent Action Steps\n\n1. IDENTIFY the try-catch block flagged in the error message\n\n2. ANALYZE the purpose:\n - Is it catching errors just to log them? → Remove (use LogApiFilter)\n - Is it catching to show custom message? → Remove (use global handler)\n - Is it catching to retry? → Requires approval (see Acceptable Patterns)\n - Is it catching in a batch loop? → Requires approval (see Acceptable Patterns)\n - Is it catching for cleanup? → Usually wrong pattern\n\n3. REMOVE the try-catch block:\n - Delete the \\`try {\\` and \\`} catch (err: any) { ... }\\` wrapper\n - Let the code execute normally\n - Errors will bubble to global handler automatically\n\n4. VERIFY global handler exists:\n - Check that WebpiecesMiddleware.globalErrorHandler is registered\n - Check that ContextFilter is setting up RequestContext\n - Check that traceId is being added to RequestContext\n\n5. ADD traceId to RequestContext (if not already present):\n - In ContextFilter or similar high-priority filter\n - Use \\`RequestContext.put('TRACE_ID', generateTraceId())\\`\n\n6. TEST error flow:\n - Trigger an error in the code\n - Verify error is logged with traceId\n - Verify \\`/debugLocal/{traceId}\\` endpoint works\n\n## Pattern 1: Global Error Handler (GOOD)\n\n### Server-Side: WebpiecesMiddleware\n\n\\`\\`\\`typescript\n// packages/http/http-server/src/WebpiecesMiddleware.ts\n@provideSingleton()\n@injectable()\nexport class WebpiecesMiddleware {\n async globalErrorHandler(\n req: Request,\n res: Response,\n next: NextFunction\n ): Promise<void> {\n console.log('[GlobalErrorHandler] Request START:', req.method, req.path);\n\n try {\n // Await catches BOTH sync throws AND rejected promises\n await next();\n console.log('[GlobalErrorHandler] Request END (success)');\n } catch (err: any) {\n const error = toError(err);\n const traceId = RequestContext.get<string>('TRACE_ID');\n\n // Log with traceId for /debugLocal lookup\n console.error('[GlobalErrorHandler] ERROR:', {\n traceId,\n message: error.message,\n stack: error.stack,\n path: req.path,\n method: req.method,\n });\n\n // Store error for /debugLocal/{id} endpoint\n ErrorStore.save(traceId, error);\n\n if (!res.headersSent) {\n res.status(500).send(\\`\n <!DOCTYPE html>\n <html>\n <head><title>Server Error</title></head>\n <body>\n <h1>Server Error</h1>\n <p>An error occurred. Reference ID: \\${traceId}</p>\n <p>Contact support with this ID to investigate.</p>\n </body>\n </html>\n \\`);\n }\n }\n }\n}\n\\`\\`\\`\n\n### Adding TraceId: ContextFilter\n\n\\`\\`\\`typescript\n// packages/http/http-server/src/filters/ContextFilter.ts\nimport { v4 as uuidv4 } from 'uuid';\n\n@provideSingleton()\n@injectable()\nexport class ContextFilter extends Filter<MethodMeta, WpResponse<unknown>> {\n async filter(\n meta: MethodMeta,\n nextFilter: Service<MethodMeta, WpResponse<unknown>>\n ): Promise<WpResponse<unknown>> {\n return RequestContext.run(async () => {\n // Generate unique traceId for this request\n const traceId = uuidv4();\n RequestContext.put('TRACE_ID', traceId);\n RequestContext.put('METHOD_META', meta);\n RequestContext.put('REQUEST_PATH', meta.path);\n\n return await nextFilter.invoke(meta);\n // RequestContext auto-cleared when done\n });\n }\n}\n\\`\\`\\`\n\n## Pattern 2: Debug Endpoints (GOOD)\n\n\\`\\`\\`typescript\n// Example debug endpoint for local development\n@provideSingleton()\n@Controller()\nexport class DebugController implements DebugApi {\n @Get()\n @Path('/debugLocal/:id')\n async getErrorById(@PathParam('id') id: string): Promise<DebugErrorResponse> {\n const error = ErrorStore.get(id);\n if (!error) {\n throw new HttpNotFoundError(\\`Error \\${id} not found\\`);\n }\n\n return {\n traceId: id,\n message: error.message,\n stack: error.stack,\n timestamp: error.timestamp,\n requestPath: error.requestPath,\n requestMethod: error.requestMethod,\n };\n }\n}\n\n// ErrorStore singleton (in-memory for local, Redis for production)\nclass ErrorStoreImpl {\n private errors = new Map<string, ErrorRecord>();\n\n save(traceId: string, error: Error): void {\n this.errors.set(traceId, {\n traceId,\n message: error.message,\n stack: error.stack,\n timestamp: new Date(),\n requestPath: RequestContext.get('REQUEST_PATH'),\n requestMethod: RequestContext.get('HTTP_METHOD'),\n });\n }\n\n get(traceId: string): ErrorRecord \| undefined {\n return this.errors.get(traceId);\n }\n}\n\nexport const ErrorStore = new ErrorStoreImpl();\n\\`\\`\\`\n\n## Examples\n\n### BAD Example 1: Local Try-Catch That Swallows Error\n\n\\`\\`\\`typescript\n// BAD: Error is swallowed, no traceId in logs\nasync function processOrder(order: Order): Promise<void> {\n try {\n await validateOrder(order);\n await saveToDatabase(order);\n } catch (err: any) {\n // Error disappears into void - debugging nightmare!\n console.log('Order processing failed');\n }\n}\n\\`\\`\\`\n\nProblem: When this fails in production, you have:\n- No traceId to look up the error\n- No stack trace\n- No request context\n- No way to investigate\n\n### BAD Example 2: Try-Catch With Custom Error (No TraceId)\n\n\\`\\`\\`typescript\n// BAD: Shows custom message but loses traceId\nasync function fetchUserData(userId: string): Promise<User> {\n try {\n const response = await fetch(\\`/api/users/\\${userId}\\`);\n return await response.json();\n } catch (err: any) {\n const error = toError(err);\n // Custom message without traceId\n throw new Error(\\`Failed to fetch user \\${userId}: \\${error.message}\\`);\n }\n}\n\\`\\`\\`\n\nProblem:\n- Original error context is lost\n- No traceId attached to new error\n- Global handler receives generic error, can't trace root cause\n\n### GOOD Example 1: Let Error Bubble\n\n\\`\\`\\`typescript\n// GOOD: Error bubbles to global handler with traceId\nasync function processOrder(order: Order): Promise<void> {\n // No try-catch needed!\n await validateOrder(order);\n await saveToDatabase(order);\n // If error occurs, it bubbles with traceId intact\n}\n\\`\\`\\`\n\nWhy GOOD:\n- Global handler catches error\n- TraceId from RequestContext is preserved\n- Full stack trace available\n- \\`/debugLocal/{traceId}\\` endpoint works\n\n### GOOD Example 2: Global Handler Logs With TraceId\n\n\\`\\`\\`typescript\n// GOOD: Global handler has full context\n// In WebpiecesMiddleware.globalErrorHandler (see Pattern 1 above)\ncatch (err: any) {\n const error = toError(err);\n const traceId = RequestContext.get<string>('TRACE_ID');\n\n console.error('[GlobalErrorHandler] ERROR:', {\n traceId, // Unique ID for this request\n message: error.message,\n stack: error.stack,\n path: req.path, // Request context preserved\n });\n}\n\\`\\`\\`\n\nWhy GOOD:\n- TraceId logged with every error\n- Full request context available\n- Error stored for \\`/debugLocal/{id}\\` lookup\n- DevOps can trace distributed requests\n\n### ACCEPTABLE Example 1: Retry Loop (With eslint-disable)\n\n\\`\\`\\`typescript\n// ACCEPTABLE: Retry pattern requires try-catch\n// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Retry loop with exponential backoff\nasync function callVendorApiWithRetry(request: VendorRequest): Promise<VendorResponse> {\n const maxRetries = 3;\n let lastError: Error \| undefined;\n\n for (let i = 0; i < maxRetries; i++) {\n try {\n return await vendorApi.call(request);\n } catch (err: any) {\n const error = toError(err);\n lastError = error;\n console.warn(\\`Retry \\${i + 1}/\\${maxRetries} failed:\\`, error.message);\n await sleep(1000 * Math.pow(2, i)); // Exponential backoff\n }\n }\n\n // After retries exhausted, throw with traceId\n const traceId = RequestContext.get<string>('TRACE_ID');\n throw new HttpVendorError(\n \\`Vendor API failed after \\${maxRetries} retries. TraceId: \\${traceId}\\`,\n lastError\n );\n}\n\\`\\`\\`\n\nWhy ACCEPTABLE:\n- Legitimate use case: retry logic\n- Final error still includes traceId\n- Error still bubbles to global handler\n- Requires senior developer approval (enforced by PR review)\n\n### ACCEPTABLE Example 2: Batching Pattern (With eslint-disable)\n\n\\`\\`\\`typescript\n// ACCEPTABLE: Batching requires try-catch to continue processing\n// eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Batch processing continues on individual failures\nasync function processBatch(items: Item[]): Promise<BatchResult> {\n const results: ItemResult[] = [];\n const errors: ItemError[] = [];\n const traceId = RequestContext.get<string>('TRACE_ID');\n\n for (const item of items) {\n try {\n const result = await processItem(item);\n results.push(result);\n } catch (err: any) {\n const error = toError(err);\n // Log individual error with traceId\n console.error(\\`[Batch] Item \\${item.id} failed (traceId: \\${traceId}):\\`, error);\n errors.push({ itemId: item.id, error: error.message, traceId });\n }\n }\n\n // Return both successes and failures\n return {\n traceId,\n successCount: results.length,\n failureCount: errors.length,\n results,\n errors,\n };\n}\n\\`\\`\\`\n\nWhy ACCEPTABLE:\n- Legitimate use case: partial failure handling\n- Each error logged with traceId\n- Batch traceId included in response\n- Requires senior developer approval (enforced by PR review)\n\n### UNACCEPTABLE Example: Try-Catch-Rethrow\n\n\\`\\`\\`typescript\n// UNACCEPTABLE: Pointless try-catch that just rethrows\nasync function saveUser(user: User): Promise<void> {\n try {\n await database.save(user);\n } catch (err: any) {\n const error = toError(err);\n console.error('Save failed:', error);\n throw error; // Why catch at all???\n }\n}\n\\`\\`\\`\n\nWhy UNACCEPTABLE:\n- Adds no value - logging should be in LogApiFilter\n- Global handler already logs errors\n- Just adds noise and confusion\n- Remove the try-catch entirely!\n\n## When eslint-disable IS Acceptable\n\nYou may use \\`// eslint-disable-next-line @webpieces/no-unmanaged-exceptions\\` ONLY for:\n\n1. Retry loops with exponential backoff (vendor API calls)\n2. Batching patterns where partial failure is expected\n3. Resource cleanup with explicit approval\n\nAll three require:\n- Senior developer approval in PR review\n- Comment explaining WHY try-catch is needed\n- TraceId must still be logged/included in final error\n\n## How to Request Approval\n\nIf you believe you have a legitimate use case for try-catch:\n\n1. Add a comment explaining why it's needed:\n \\`\\`\\`typescript\n // JUSTIFICATION: Vendor API requires retry loop with exponential backoff\n // to handle rate limiting. Final error includes traceId for debugging.\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n \\`\\`\\`\n\n2. Ensure traceId is preserved in final error or logged\n\n3. Request PR review from senior developer\n\n4. Be prepared to justify - 99% of try-catch can be removed\n\n## Summary\n\nThe webpieces philosophy: Errors should bubble to the global handler where they are logged with traceId and stored for debugging. Local try-catch blocks break this architecture and create blind spots in production.\n\nKey takeaways:\n- Global error handler with traceId = debuggable production issues\n- Local try-catch = lost context and debugging nightmares\n- 99% of try-catch blocks can be removed safely\n- Only use try-catch for: retries, batching (with approval)\n- TraceId enables \\`/debugLocal/{id}\\` and \\`/debugCloud/{id}\\` endpoints\n\nRemember: If you can't handle the error meaningfully, don't catch it. Let it bubble to the global handler where it will be logged with full context and traceId.\n`;\n\nconst rule: Rule.RuleModule = {\n meta: {\n type: 'problem',\n docs: {\n description: 'Discourage try-catch blocks outside test files - use global error handlers',\n category: 'Best Practices',\n recommended: true,\n url: 'https://github.com/deanhiller/webpieces-ts/blob/main/CLAUDE.md#exception-handling-philosophy',\n },\n messages: {\n noUnmanagedExceptions:\n 'AI Agent: READ tmp/webpieces/webpieces.exceptions.md for context. Try-catch blocks are discouraged - use global error handlers instead. Only allowed in test files or with eslint-disable comment.',\n },\n fixable: undefined,\n schema: [],\n },\n\n create(context: Rule.RuleContext): Rule.RuleListener {\n return {\n TryStatement(node: any): void {\n // Skip try..finally blocks (no catch handler, no exception handling)\n if (!node.handler) {\n return;\n }\n\n // Auto-allow in test files\n const filename = context.filename \|\| context.getFilename();\n if (isTestFile(filename)) {\n return;\n }\n\n // Has catch block outside test file - report violation\n ensureExceptionDoc(context);\n context.report({\n node,\n messageId: 'noUnmanagedExceptions',\n });\n },\n };\n },\n};\n\nexport = rule;\n"]}
1	+ {"version":3,"file":"no-unmanaged-exceptions.js","sourceRoot":"","sources":["../../../../../../packages/tooling/dev-config/eslint-plugin/rules/no-unmanaged-exceptions.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n ESLint rule to discourage try-catch blocks outside test files\n \n Works alongside catch-error-pattern rule:\n * - catch-error-pattern: Enforces HOW to handle exceptions (with toError())\n * - no-unmanaged-exceptions: Enforces WHERE try-catch is allowed (tests only by default)\n \n Philosophy: Exceptions should bubble to global error handlers where they are logged\n * with traceId and stored for debugging via /debugLocal and /debugCloud endpoints.\n * Local try-catch blocks break this architecture and create blind spots in production.\n \n Auto-allowed in:\n * - Test files (.test.ts, .spec.ts, __tests__/)\n \n Requires eslint-disable comment in:\n * - Retry loops with exponential backoff\n * - Batch processing where partial failure is expected\n * - Resource cleanup (with approval)\n /\n\nimport type { Rule } from 'eslint';\nimport as fs from 'fs';\nimport * as path from 'path';\n\n/*\n Determines if a file is a test file based on naming conventions\n * Test files are auto-allowed to use try-catch blocks\n /\nfunction isTestFile(filename: string): boolean {\n const normalizedPath = filename.toLowerCase();\n\n // Check file extensions\n if (normalizedPath.endsWith('.test.ts') \|\| normalizedPath.endsWith('.spec.ts')) {\n return true;\n }\n\n // Check directory names (cross-platform)\n if (normalizedPath.includes('/__tests__/') \|\| normalizedPath.includes('\\\\__tests__\\\\')) {\n return true;\n }\n\n return false;\n}\n\n/\n Finds the workspace root by walking up the directory tree\n * Looks for package.json with workspaces or name === 'webpieces-ts'\n /\nfunction getWorkspaceRoot(context: Rule.RuleContext): string {\n const filename = context.filename \|\| context.getFilename();\n let dir = path.dirname(filename);\n\n // Walk up directory tree\n for (let i = 0; i < 10; i++) {\n const pkgPath = path.join(dir, 'package.json');\n if (fs.existsSync(pkgPath)) {\n try {\n const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));\n // Check if this is the root workspace\n if (pkg.workspaces \|\| pkg.name === 'webpieces-ts') {\n return dir;\n }\n } catch {\n // Invalid JSON, keep searching\n }\n }\n\n const parentDir = path.dirname(dir);\n if (parentDir === dir) break; // Reached filesystem root\n dir = parentDir;\n }\n\n // Fallback: return current directory\n return process.cwd();\n}\n\n/\n Ensures a documentation file exists at the given path\n * Creates parent directories if needed\n /\nfunction ensureDocFile(docPath: string, content: string): boolean {\n try {\n const dir = path.dirname(docPath);\n if (!fs.existsSync(dir)) {\n fs.mkdirSync(dir, { recursive: true });\n }\n\n // Only write if file doesn't exist or is empty\n if (!fs.existsSync(docPath) \|\| fs.readFileSync(docPath, 'utf-8').trim() === '') {\n fs.writeFileSync(docPath, content, 'utf-8');\n }\n\n return true;\n } catch (error) {\n // Silently fail - don't break linting if file creation fails\n return false;\n }\n}\n\n/\n Ensures the exception documentation markdown file exists\n * Only creates file once per lint run using module-level flag\n \n Reads from the template file packaged with @webpieces/dev-config\n * and copies it to tmp/webpieces/ for AI agents to read.\n */\nfunction ensureExceptionDoc(context: Rule.RuleContext): void {\n if (exceptionDocCreated) return;\n\n const workspaceRoot = getWorkspaceRoot(context);\n const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.exceptions.md');\n\n // Read from the template file packaged with the npm module\n // Path: from eslint-plugin/rules/ -> ../../templates/\n const templatePath = path.join(__dirname, '..', '..', 'templates', 'webpieces.exceptions.md');\n\n let content: string;\n try {\n content = fs.readFileSync(templatePath, 'utf-8');\n } catch {\n // Fallback message if template not found (shouldn't happen in published package)\n content = `# Exception Documentation Not Found\\n\\nTemplate file not found at: ${templatePath}\\n\\nPlease ensure @webpieces/dev-config is properly installed.`;\n }\n\n if (ensureDocFile(docPath, content)) {\n exceptionDocCreated = true;\n }\n}\n\n// Module-level flag to prevent redundant markdown file creation\nlet exceptionDocCreated = false;\n\n// NOTE: Documentation content moved to templates/webpieces.exceptions.md\n// The ensureExceptionDoc function reads from that file at runtime.\n\nconst rule: Rule.RuleModule = {\n meta: {\n type: 'problem',\n docs: {\n description: 'Discourage try-catch blocks outside test files - use global error handlers',\n category: 'Best Practices',\n recommended: true,\n url: 'https://github.com/deanhiller/webpieces-ts/blob/main/CLAUDE.md#exception-handling-philosophy',\n },\n messages: {\n noUnmanagedExceptions:\n 'AI Agent: READ tmp/webpieces/webpieces.exceptions.md for context. Try-catch blocks are discouraged - use global error handlers instead. Only allowed in test files or with eslint-disable comment.',\n },\n fixable: undefined,\n schema: [],\n },\n\n create(context: Rule.RuleContext): Rule.RuleListener {\n return {\n TryStatement(node: unknown): void {\n // Skip try..finally blocks (no catch handler, no exception handling)\n if (!(node as { handler?: unknown }).handler) {\n return;\n }\n\n // Auto-allow in test files\n const filename = context.filename \|\| context.getFilename();\n if (isTestFile(filename)) {\n return;\n }\n\n // Has catch block outside test file - report violation\n ensureExceptionDoc(context);\n context.report({\n node: node as Rule.Node,\n messageId: 'noUnmanagedExceptions',\n });\n },\n };\n },\n};\n\nexport = rule;\n\n"]}