Eve library

Yaa Code Quality Analysis

Guide

Revision 1

On this page

Analysis Date: January 2026 Scope: Complete Yaa codebase quality assessment Methodology: Static analysis, pattern detection, code review


Table of Contents#

  1. Executive Summary
  2. Statistics Overview
  3. TypeScript Quality
  4. Code Duplication
  5. Error Handling Issues
  6. Large Files Analysis
  7. Test Quality Issues
  8. Best Practices Violations
  9. Technical Debt Backlog
  10. Recommendations

Executive Summary#

The Yaa codebase demonstrates good overall architecture with 95 packages organized by domain. However, several code quality issues require attention:

Key Findings:

  • 86 instances of duplicated sleep() function across packages
  • 2,875-line file (v1.ts) containing all API routes
  • 40+ instances of as any casts in test files
  • 10+ instances of swallowed errors with // ignore comments
  • ESLint configured with any type as warning instead of error

Positive Aspects:

  • Consistent package structure
  • Good separation of concerns in most areas
  • Comprehensive type definitions in models package
  • Well-organized configuration management

Statistics Overview#

Metric Value Assessment
Total TypeScript Source Files 1,142 Large codebase
Total Packages 95 Good modularity
Files Over 1000 Lines 14+ Needs refactoring
Duplicated Helper Functions 107+ High duplication
as any Casts in Tests 40+ Reduces test value
Swallowed Errors 10+ Risk of silent failures
.map()/.filter()/.reduce() Usage 152 Normal for FP style

TypeScript Quality#

Type Annotation Issues#

Loose Type Annotations#

Location: packages/ai/agents/agents/devops/analytics.ts:135

typescript
// Problem: Uses 'any' type for critical fields
Array<{
  service?: string;
  env: any; // Should be specific environment type
  signals: Array<{
    kind: string;
    metric?: any; // Should be number | string | boolean
    // ...
  }>;
}>;

Impact: Loses type safety for DevOps metrics data.

Recommendation: Define proper interfaces:

typescript
interface DevOpsSignal {
  kind: 'cpu' | 'memory' | 'latency' | 'error_rate';
  metric?: number | string | boolean;
  // ... other typed fields
}

interface DevOpsAnalytics {
  service?: string;
  env: 'development' | 'staging' | 'production';
  signals: DevOpsSignal[];
}

Missing Type Annotations (as unknown Casts)#

Multiple instances of double-casting as workarounds:

File Line Pattern
market-summary-generator/src/forex.ts 60 (await res.json()) as unknown
weather-report-generator/src/gmet.ts 22, 73 as unknown as GmetForecast
fuel-price-update-generator/src/worker.ts 31 XLSX sheet to unknown[][]

Root Cause: Missing TypeScript interfaces for external API responses.

Recommendation: Create response types:

typescript
// packages/models/src/external-api-responses.ts
interface ForexApiResponse {
  time_last_update_utc: string;
  rates: Record<string, number>;
}

interface GmetForecast {
  location: string;
  temperature: number;
  // ... other fields
}

ESLint Configuration#

Location: eslint.config.js

Current Configuration:

javascript
'@typescript-eslint/no-explicit-any': 'warn'

Issue: Allows any types to pass builds without blocking.

Recommended Fix:

javascript
'@typescript-eslint/no-explicit-any': 'error'

Code Duplication#

Critical: Sleep Function (86 Instances)#

The same sleep() function is defined in 86 different files:

typescript
function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

Affected Files (Sample):

  • packages/ai/market-summary-generator/src/cli.ts:70-71
  • packages/ai/weather-report-generator/src/cli.ts:82-83
  • packages/ai/event-calendar-updater/src/cli.ts:87-88
  • packages/ai/story-clustering-worker/src/cli.ts:82-83
  • packages/social/tiktok-business-setup/src/tiktok.ts
  • packages/social/instagram-scheduler/src/client.ts
  • Plus 80+ more instances in test files and workers

Estimated Lines Duplicated: 172+ (2 lines x 86 instances)

Recommendation: Create shared utility package:

typescript
// packages/shared-utils/src/timing.ts
export function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

export function timeout<T>(promise: Promise<T>, ms: number): Promise<T> {
  return Promise.race([
    promise,
    sleep(ms).then(() => {
      throw new Error(`Operation timed out after ${ms}ms`);
    }),
  ]);
}

High: Print Help Functions (60+ Instances)#

Every CLI module has its own printHelp() function:

typescript
function printHelp(): void {
  console.log(`
Usage: pnpm run cli [command]

Commands:
  run     Run the generator
  help    Show this message
  `);
}

Affected Packages:

  • Every packages/ai/*/src/cli.ts
  • Every packages/social/*/src/cli.ts
  • Every packages/ingestion/*/src/cli.ts

Recommendation: Create CLI utility:

typescript
// packages/shared-utils/src/cli.ts
interface CliConfig {
  name: string;
  commands: Record<string, { description: string; run: () => Promise<void> }>;
}

export function createCli(config: CliConfig) {
  return {
    printHelp: () => {
      /* ... */
    },
    run: async (args: string[]) => {
      /* ... */
    },
  };
}

Medium: Pool Factory Functions#

Identical makePool() implementations in test files:

Locations:

  • packages/api/test/searchIndexer.test.ts:8
  • packages/web/src/lib/server/articleAiDecision.test.ts:7
typescript
function makePool(): Pool {
  return new Pool({
    connectionString: process.env.DATABASE_URL,
  });
}

Recommendation: Create test utilities package:

typescript
// packages/test-utils/src/database.ts
export function createTestPool(): Pool {
  return new Pool({
    connectionString: process.env.DATABASE_URL,
    application_name: 'yaa-test',
    max: 5,
  });
}

Error Handling Issues#

Swallowed Errors#

Multiple instances of empty or comment-only catch blocks:

File Line Pattern
market-summary-generator/src/db.ts 20 catch { // ignore }
weather-report-generator/src/db.ts 20 catch { // ignore }
event-calendar-updater/src/db.ts 17 catch { // ignore }
api/src/search-indexer.ts 46-52 Multiple empty catches

Example (Current):

typescript
try {
  await pool.end();
} catch {
  // ignore
}

Impact:

  • Silent failures in production
  • Difficult debugging
  • No metrics/alerts on errors

Recommended Fix:

typescript
try {
  await pool.end();
} catch (error) {
  logger.warn('Failed to close pool connection', {
    error: error instanceof Error ? error.message : String(error),
    pool: pool.options?.application_name,
  });
}

Error Type Safety in Tests#

40+ instances of unsafe type casting in tests:

typescript
// Current (unsafe)
expect((created?.data as any).ok).toBe(true);
const data = result.data as any;

// Better (type-safe)
interface TaskResult {
  ok: boolean;
  data?: unknown;
}
const result = created?.data as TaskResult;
expect(result.ok).toBe(true);

Affected Test Files:

  • packages/ai/agents/test/managing-editor-deadlines.test.ts:131
  • packages/ai/agents/test/fact-checker-agent.test.ts:133
  • packages/ai/agents/test/managing-editor-qc-pipeline.test.ts:38
  • packages/ai/agents/test/qa-agent.test.ts:120
  • Plus 36+ more instances

Large Files Analysis#

Files Exceeding 1000 Lines#

File Lines Primary Issue
api/src/interfaces/http/routes/v1.ts 2,875 Monolithic route file
ingestion/source-discovery/src/wire-service-automation.ts 1,520 Complex automation
ai/blindspot-detection/src/notifications.ts 1,504 Many notification types
ai/agents/agents/journalist/journalist-agent.ts 1,497 Complex agent logic
ai/agents/orchestration/orchestrator.ts 1,426 Orchestration complexity
nlp/ghana-nlp/src/hybrid-tts.ts 1,187 TTS provider logic
nlp/ghana-nlp/src/types.ts 1,069 Many type definitions

Critical: API Routes File (v1.ts)#

File: packages/api/src/interfaces/http/routes/v1.ts Lines: 2,875 Exports: 284 items

Current Structure:

typescript
// All routes in one file:
export const v1Routes = {
  // Article routes (lines 1-500)
  getArticle: async (req, res) => {
    /* ... */
  },
  listArticles: async (req, res) => {
    /* ... */
  },
  searchArticles: async (req, res) => {
    /* ... */
  },

  // Story routes (lines 501-900)
  getStory: async (req, res) => {
    /* ... */
  },
  // ...

  // Claim routes (lines 901-1200)
  // ...

  // Plus 200+ more handlers
};

Issues:

  1. Single file too large to navigate
  2. Mixed concerns (articles, stories, claims, users, etc.)
  3. Difficult to test individual routes
  4. No clear domain boundaries

Recommended Refactoring:

text
packages/api/src/interfaces/http/routes/
├── index.ts              # Combines all route modules
├── articles/
│   ├── index.ts          # Article route handlers
│   ├── validators.ts     # Article validation schemas
│   └── types.ts          # Article route types
├── stories/
│   ├── index.ts
│   └── ...
├── claims/
│   ├── index.ts
│   └── ...
└── ...

Test Quality Issues#

Type Safety#

Tests using as any lose the benefit of TypeScript:

typescript
// packages/ai/agents/test/managing-editor-qc-pipeline.test.ts:38
const storyId = (task.input.content as any)?.storyId;

// packages/ai/agents/test/qa-agent.test.ts:120
const planData = planRes.data as any;

Impact:

  • Tests may pass but miss actual type errors
  • False confidence in type coverage
  • Harder to maintain as types evolve

Missing Test Types#

Create proper test utility types:

typescript
// packages/test-utils/src/types.ts
export interface MockTaskResult<T> {
  ok: boolean;
  data?: T;
  error?: Error;
}

export interface MockAgentResponse<T> {
  status: 'success' | 'failure';
  result: T;
  duration: number;
}

Best Practices Violations#

Console.log in Production Code#

Location: packages/api/src/search-indexer.ts:34

typescript
console.log('[search-indexer] Starting...');

Recommendation: Use structured logging:

typescript
import { logger } from '@yaa/logger';

logger.info('Search indexer starting', {
  component: 'search-indexer',
  timestamp: new Date().toISOString(),
});

Hardcoded Values#

SQL Dates:

typescript
// packages/ingestion/social-x/src/db.ts:43
'1970-01-01'::timestamptz

// packages/ingestion/rss-collector/src/db.ts:50
'1970-01-01'::timestamptz

Recommendation:

typescript
// packages/shared-utils/src/constants.ts
export const UNIX_EPOCH_SQL = "'1970-01-01'::timestamptz";
export const UNIX_EPOCH_DATE = new Date(0);

Inefficient Array Checks#

Current:

typescript
if (filters.subjectTypes && filters.subjectTypes.length > 0)

Better:

typescript
if (filters.subjectTypes?.length)

Technical Debt Backlog#

Priority 1: High Impact#

ID Issue Effort Impact
TD-001 Create @yaa/shared-utils package 1 week Reduces 107+ duplications
TD-002 Split v1.ts into domain modules 2 weeks Improves maintainability
TD-003 Set ESLint no-explicit-any to error 2 hours Prevents future issues
TD-004 Add error logging to catch blocks 1 week Improves observability

Priority 2: Medium Impact#

ID Issue Effort Impact
TD-005 Create test utility package 3 days Improves test quality
TD-006 Add TypeScript interfaces for APIs 1 week Type safety
TD-007 Split large agent files 1 week Maintainability
TD-008 Add structured logging 3 days Observability

Priority 3: Low Impact#

ID Issue Effort Impact
TD-009 Replace hardcoded SQL dates 1 hour Code clarity
TD-010 Optimize array checks 2 hours Minor performance
TD-011 Add JSDoc to public APIs 1 week Documentation

Recommendations#

Immediate Actions (This Sprint)#

  1. Create shared utilities package

    bash
    pnpm nx generate @nrwl/node:library shared-utils --directory=packages
    
    • Move sleep(), printHelp(), makePool() functions
    • Update all imports across packages
  2. Update ESLint configuration

    javascript
    // eslint.config.js
    '@typescript-eslint/no-explicit-any': 'error',
    '@typescript-eslint/no-unused-vars': 'error',
    'no-console': ['error', { allow: ['warn', 'error'] }],
    
  3. Add error handling to catch blocks

    • Search for catch { and catch ( followed by empty or comment-only blocks
    • Add minimum logging to each

Short-term Actions (This Month)#

  1. Refactor v1.ts route file

    • Create domain-specific route modules
    • Extract validators and types
    • Add unit tests per module
  2. Create test utilities

    • Type-safe mock factories
    • Database test helpers
    • Agent test utilities
  3. Add TypeScript interfaces for external APIs

    • Forex API responses
    • Weather API responses
    • Social media API responses

Long-term Actions (This Quarter)#

  1. Implement structured logging

    • Create @yaa/logger package
    • Replace all console.log/error
    • Add log correlation IDs
  2. Reduce file sizes

    • Target: No file over 500 lines
    • Extract helper functions
    • Split complex logic
  3. Improve type coverage

    • Target: 100% explicit types
    • No any or unknown without justification
    • Add TypeScript strict mode

Appendix: Code Quality Metrics#

Files by Size#

text
> 2000 lines:  1 file   (v1.ts)
> 1500 lines:  3 files
> 1000 lines:  14 files
> 500 lines:   42 files
< 500 lines:   1,082 files

Duplication Hotspots#

text
sleep():           86 instances
printHelp():       60+ instances
makePool():        10+ instances
Provider helpers:  20+ instances

Type Safety Score#

text
Explicit any:      Configured as warning (should be error)
Test as any:       40+ instances
Unknown casts:     15+ instances
Proper types:      ~95% of codebase

Analysis Date: January 2026

Part of the Veritas domain integration documentation