f (feature.metadata?.requiredFields) { const required = feature.metadata.requiredFields as string[]; return required.every(field => data && typeof data === 'object' && field in data); } return true; } }

#### 3. The Analysis Runner

The runner orchestrates probes and computes the matrix.

```typescript
// engine/analysis-runner.ts

import { CompetitiveMatrix, FeatureDefinition, CompetitorProfile, ProbeResult } from '../models/competitive-model';
import { Probe } from '../probes/probe.interface';

export class AnalysisRunner {
  private probes: Map<string, Probe> = new Map();

  registerProbe(probe: Probe) {
    this.probes.set(probe.type, probe);
  }

  async runAnalysis(
    competitors: CompetitorProfile[],
    features: FeatureDefinition[]
  ): Promise<CompetitiveMatrix> {
    const results: ProbeResult[] = [];

    // Execute probes in parallel per competitor to optimize latency
    const executionPromises = competitors.map(async (competitor) => {
      const featurePromises = features.map(async (feature) => {
        const probe = this.probes.get(feature.detectionStrategy);
        if (!probe) {
          throw new Error(`No probe registered for strategy: ${feature.detectionStrategy}`);
        }
        return probe.execute(competitor, feature);
      });

      return Promise.all(featurePromises);
    });

    const competitorResults = await Promise.all(executionPromises);
    results.push(...competitorResults.flat());

    return this.computeMatrix(features, competitors, results);
  }

  private computeMatrix(
    features: FeatureDefinition[],
    competitors: CompetitorProfile[],
    results: ProbeResult[]
  ): CompetitiveMatrix {
    // Calculate weighted parity score
    // Example: Score is sum of (present * weight) / sum of (all weights)
    const totalWeight = features.reduce((acc, f) => acc + f.weight, 0);
    
    // Assuming the first competitor is the baseline or internal product
    const baselineId = competitors[0].id;
    const baselineResults = results.filter(r => r.competitorId === baselineId);
    const baselineScore = baselineResults
      .filter(r => r.present)
      .reduce((acc, r) => {
        const feature = features.find(f => f.id === r.featureId);
        return acc + (feature?.weight || 0);
      }, 0);

    const parityScore = baselineScore / totalWeight;

    return {
      features,
      competitors,
      results,
      parityScore: Math.round(parityScore * 100) / 100
    };
  }
}

4. Configuration and Execution

Wire up the engine with configuration.

// main.ts

import { AnalysisRunner } from './engine/analysis-runner';
import { ApiCheckProbe } from './probes/api-check.probe';
import { FeatureDefinition, CompetitorProfile } from './models/competitive-model';

const features: FeatureDefinition[] = [
  {
    id: 'feat-auth-oauth2',
    name: 'OAuth 2.0 Support',
    category: 'API',
    weight: 0.8,
    detectionStrategy: 'API_CHECK',
    metadata: { endpoint: '/.well-known/openid-configuration', requiredFields: ['authorization_endpoint'] }
  },
  {
    id: 'feat-rate-limit',
    name: 'Rate Limiting Headers',
    category: 'API',
    weight: 0.5,
    detectionStrategy: 'API_CHECK',
    metadata: { endpoint: '/api/v1/status', requiredFields: [] } // Check headers in validateResponse
  }
];

const competitors: CompetitorProfile[] = [
  { id: 'internal', name: 'Our Product', baseUrl: 'https://api.ourproduct.io' },
  { id: 'comp-a', name: 'Competitor A', baseUrl: 'https://api.competitor-a.io' },
  { id: 'comp-b', name: 'Competitor B', baseUrl: 'https://api.competitor-b.io' }
];

async function bootstrap() {
  const runner = new AnalysisRunner();
  runner.registerProbe(new ApiCheckProbe());

  console.log('Starting competitive analysis...');
  const matrix = await runner.runAnalysis(competitors, features);

  console.log(`Parity Score: ${(matrix.parityScore * 100).toFixed(1)}%`);
  
  // Output delta analysis
  const deltas = matrix.results.filter(r => {
    if (r.competitorId === 'internal') return false;
    const internal = matrix.results.find(i => i.featureId === r.featureId && i.competitorId === 'internal');
    return internal && internal.present !== r.present;
  });

  console.log('Critical Deltas Detected:', deltas.length);
  deltas.forEach(d => {
    console.log(`- ${d.featureId} on ${d.competitorId}: ${d.present ? 'Present' : 'Missing'}`);
  });
}

bootstrap().catch(console.error);

Pitfall Guide

Implementing automated competitive analysis introduces technical risks. The following pitfalls are derived from production experience with large-scale monitoring systems.

1. Violating Terms of Service: Automated probes can trigger legal or blocking mechanisms.

   • Best Practice: Always respect robots.txt, implement rate limiting in probes, and use public APIs where available. Avoid scraping login-gated content unless explicitly permitted. Add User-Agent headers identifying your bot.

2. False Positives from Dynamic Content: Competitors may use A/B testing, geo-blocking, or bot detection.

   • Best Practice: Run probes from multiple regions. Implement retry logic with jitter. Use statistical aggregation over time rather than single-point snapshots. Validate responses against multiple signals.

3. Brittle Selectors and Endpoints: UI scrapers break frequently when DOM structures change.

   • Best Practice: Prioritize API-level probes over DOM scraping. If DOM analysis is required, use semantic selectors and implement a "probe health" monitor that alerts when success rates drop, indicating a structural change.

4. Analysis Paralysis: Collecting excessive data without actionable outputs.

   • Best Practice: Define strict thresholds for alerts. Only notify on high-weight feature changes or significant performance deltas. Integrate results directly into the product backlog via API webhooks to Slack/Jira.

5. Ignoring "Time-to-Value" Metrics: Focusing solely on feature presence without measuring usability or performance.

   • Best Practice: Include performance probes (Lighthouse, TTFB, API latency) and integration complexity scores in the matrix. A feature is less valuable if it is significantly slower or harder to implement than the internal equivalent.

6. Data Normalization Errors: Comparing features with different scopes or capabilities.

   • Best Practice: Use a normalized taxonomy. Map competitor features to internal capabilities explicitly. Avoid 1:1 mapping if capabilities differ; use a scoring rubric within the feature definition to handle nuance.

7. Resource Exhaustion: Running too many probes concurrently can exhaust internal resources or get IP blocks.

   • Best Practice: Implement a job queue with concurrency controls. Use exponential backoff for retries. Monitor probe execution costs and optimize by scheduling non-critical probes during off-peak hours.

Production Bundle

Action Checklist

• Define Feature Taxonomy: Create a weighted list of features and metrics aligned with product strategy.
• Implement Probe Adapters: Build probes for API checks, performance metrics, and critical UI flows.
• Configure Competitor Profiles: Set up base URLs, headers, and authentication for each competitor.
• Set Alert Thresholds: Define delta conditions that trigger notifications (e.g., weight > 0.7, parity drop > 5%).
• Integrate with CI/CD: Schedule analysis jobs to run nightly or on deployment triggers.
• Review Legal Compliance: Audit probes against competitor Terms of Service and data privacy regulations.
• Build Dashboard: Create a visualization for the Competitive Matrix to track trends over time.
• Automate Backlog Updates: Configure webhooks to create tickets for critical parity gaps.

Decision Matrix

Configuration Template

Use this TypeScript configuration structure to initialize the engine.

// config/analysis.config.ts

import { AnalysisConfig } from './models/config-model';

export const config: AnalysisConfig = {
  execution: {
    concurrency: 5,
    timeoutMs: 10000,
    retryAttempts: 2,
    schedule: '0 2 * * *' // Daily at 2 AM UTC
  },
  competitors: [
    {
      id: 'comp-alpha',
      name: 'Alpha Corp',
      baseUrl: 'https://api.alpha.io',
      region: 'us-east-1',
      headers: { 'Accept': 'application/json' }
    }
  ],
  features: [
    {
      id: 'webhooks-v2',
      name: 'Webhooks v2 Support',
      category: 'API',
      weight: 0.9,
      detectionStrategy: 'API_CHECK',
      metadata: {
        endpoint: '/api/v2/webhooks',
        requiredFields: ['secret_rotation', 'retry_policy']
      }
    }
  ],
  alerts: {
    webhookUrl: process.env.SLACK_WEBHOOK_URL,
    thresholds: {
      parityDrop: 0.05,
      criticalFeatureMissing: true,
      perfRegressionMs: 200
    }
  }
};

Quick Start Guide

1. Initialize Project:

   mkdir competitive-engine && cd competitive-engine
   npm init -y
   npm install typescript axios puppeteer lighthouse
   npx tsc --init
   

2. Create Configuration: Copy the analysis.config.ts template and populate with your first competitor and three critical features.

3. Run First Analysis: Execute the runner script. Verify output in the console.

   npx ts-node main.ts
   

4. Schedule Execution: Add a cron job or GitHub Action to run the analysis daily.

   # .github/workflows/competitive-analysis.yml
   name: Competitive Analysis
   on:
     schedule:
       - cron: '0 2 * * *'
   jobs:
     analyze:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - run: npm ci
         - run: npx ts-node main.ts
           env:
             SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
   

5. Monitor Deltas: Check Slack or your dashboard for alerts. Review high-weight deltas in the weekly product sync to prioritize roadmap adjustments.