create-hq 5.0.0

package/template/workers/content-shared/lib/scorer.ts

@@ -0,0 +1,140 @@
+/**
+ * Scoring utilities for content analysis workers
+ */
+
+import type { ScoreCategory, Finding, AnalysisResult } from './types.js';
+
+/**
+ * Calculate weighted overall score from categories
+ */
+export function calculateOverallScore(categories: ScoreCategory[]): number {
+  const totalWeight = categories.reduce((sum, cat) => sum + cat.weight, 0);
+  if (totalWeight === 0) return 0;
+
+  const weightedSum = categories.reduce((sum, cat) => {
+    const normalizedScore = (cat.score / cat.maxScore) * 100;
+    return sum + (normalizedScore * cat.weight);
+  }, 0);
+
+  return Math.round(weightedSum / totalWeight);
+}
+
+/**
+ * Create a score category
+ */
+export function createCategory(
+  name: string,
+  score: number,
+  maxScore: number,
+  weight: number,
+  details?: string
+): ScoreCategory {
+  return {
+    name,
+    score: Math.max(0, Math.min(score, maxScore)),
+    maxScore,
+    weight,
+    details
+  };
+}
+
+/**
+ * Calculate category score from findings
+ */
+export function scoreFromFindings(
+  findings: Finding[],
+  categoryName: string,
+  maxScore: number
+): number {
+  const categoryFindings = findings.filter(f => f.category === categoryName);
+
+  let deductions = 0;
+  for (const finding of categoryFindings) {
+    switch (finding.severity) {
+      case 'critical':
+        deductions += 25;
+        break;
+      case 'warning':
+        deductions += 10;
+        break;
+      case 'info':
+        deductions += 2;
+        break;
+      case 'pass':
+        // No deduction
+        break;
+    }
+  }
+
+  return Math.max(0, maxScore - deductions);
+}
+
+/**
+ * Get score grade from percentage
+ */
+export function getGrade(score: number): string {
+  if (score >= 90) return 'A';
+  if (score >= 80) return 'B';
+  if (score >= 70) return 'C';
+  if (score >= 60) return 'D';
+  return 'F';
+}
+
+/**
+ * Get score label from percentage
+ */
+export function getScoreLabel(score: number): string {
+  if (score >= 90) return 'Excellent';
+  if (score >= 80) return 'Good';
+  if (score >= 70) return 'Acceptable';
+  if (score >= 60) return 'Needs Improvement';
+  return 'Critical Issues';
+}
+
+/**
+ * Count findings by severity
+ */
+export function countBySeverity(findings: Finding[]): Record<Finding['severity'], number> {
+  return {
+    critical: findings.filter(f => f.severity === 'critical').length,
+    warning: findings.filter(f => f.severity === 'warning').length,
+    info: findings.filter(f => f.severity === 'info').length,
+    pass: findings.filter(f => f.severity === 'pass').length
+  };
+}
+
+/**
+ * Sort findings by severity (critical first)
+ */
+export function sortBySeverity(findings: Finding[]): Finding[] {
+  const severityOrder: Record<Finding['severity'], number> = {
+    critical: 0,
+    warning: 1,
+    info: 2,
+    pass: 3
+  };
+
+  return [...findings].sort((a, b) =>
+    severityOrder[a.severity] - severityOrder[b.severity]
+  );
+}
+
+/**
+ * Calculate percentage match
+ */
+export function calculateMatchPercentage(
+  matches: number,
+  total: number
+): number {
+  if (total === 0) return 100;
+  return Math.round((matches / total) * 100);
+}
+
+/**
+ * Normalize score to 0-100 range
+ */
+export function normalizeScore(score: number, min: number, max: number): number {
+  if (max === min) return 100;
+  const normalized = ((score - min) / (max - min)) * 100;
+  return Math.round(Math.max(0, Math.min(100, normalized)));
+}

package/template/workers/content-shared/lib/types.ts

@@ -0,0 +1,227 @@
+/**
+ * Shared types for content analysis workers
+ */
+
+// Page content structure from JSON extraction
+export interface PageContent {
+  url: string;
+  title: string;
+  meta: PageMeta;
+  sections: ContentSection[];
+  ctas: CTA[];
+  images: ImageAsset[];
+  extractedAt: string;
+}
+
+export interface PageMeta {
+  description?: string;
+  keywords?: string[];
+  ogTitle?: string;
+  ogDescription?: string;
+  ogImage?: string;
+}
+
+export interface ContentSection {
+  id: string;
+  type: 'hero' | 'features' | 'testimonials' | 'pricing' | 'cta' | 'content' | 'footer' | 'header' | 'other';
+  heading?: string;
+  subheading?: string;
+  paragraphs: string[];
+  bulletPoints?: string[];
+}
+
+export interface CTA {
+  text: string;
+  href?: string;
+  type: 'primary' | 'secondary' | 'link';
+  location: string; // section id or description
+}
+
+export interface ImageAsset {
+  src: string;
+  alt?: string;
+  context: string; // surrounding text or section
+}
+
+// Analysis result types
+export interface AnalysisResult {
+  workerId: string;
+  pageUrl: string;
+  analyzedAt: string;
+  overallScore: number;
+  categories: ScoreCategory[];
+  findings: Finding[];
+  recommendations: Recommendation[];
+}
+
+export interface ScoreCategory {
+  name: string;
+  score: number;
+  maxScore: number;
+  weight: number;
+  details?: string;
+}
+
+export interface Finding {
+  severity: 'critical' | 'warning' | 'info' | 'pass';
+  category: string;
+  message: string;
+  location?: string;
+  evidence?: string;
+}
+
+export interface Recommendation {
+  priority: 'high' | 'medium' | 'low';
+  category: string;
+  current: string;
+  suggested: string;
+  rationale: string;
+}
+
+// Worker configuration
+export interface WorkerConfig {
+  id: string;
+  name: string;
+  type: 'ContentWorker';
+  version: string;
+  knowledgePaths: string[];
+  outputDestination: string;
+}
+
+// Report metadata
+export interface ReportMeta {
+  generatedAt: string;
+  workerId: string;
+  pageAnalyzed: string;
+  version: string;
+}
+
+// ============================================
+// Analysis Input Types (US-006)
+// ============================================
+
+/**
+ * Structured input for analysis modules
+ */
+export interface AnalysisInput {
+  pageSlug: string;
+  title: string;
+  headings: string[];
+  paragraphs: string[];
+  ctas: { text: string; link: string }[];
+  stats: { value: string; label: string }[];
+  claims: string[];
+  sections: SectionAnalysis[];
+}
+
+export interface SectionAnalysis {
+  id: string;
+  type: ContentSection['type'];
+  heading: string;
+  content: string[];
+  wordCount: number;
+}
+
+// ============================================
+// Brand Analysis Types (US-007)
+// ============================================
+
+export interface BrandGuidelines {
+  voiceAttributes: string[];
+  toneDescriptors: string[];
+  approvedTerms: string[];
+  avoidTerms: string[];
+  messagingPillars: string[];
+}
+
+export interface BrandAnalysis {
+  overallScore: number;
+  toneScore: number;
+  messagingScore: number;
+  clarityScore: number;
+  findings: Finding[];
+  recommendations: Recommendation[];
+}
+
+// ============================================
+// Conversion Analysis Types (US-008)
+// ============================================
+
+export interface ConversionAnalysis {
+  overallScore: number;
+  ctaScore: number;
+  valuePropScore: number;
+  urgencyScore: number;
+  socialProofScore: number;
+  findings: Finding[];
+  recommendations: Recommendation[];
+}
+
+// ============================================
+// Accuracy Analysis Types (US-009)
+// ============================================
+
+export interface ProductData {
+  productName: string;
+  features: string[];
+  stats: Record<string, string>;
+  certifications: string[];
+  integrations: string[];
+  lastUpdated: string;
+}
+
+export interface AccuracyAnalysis {
+  overallScore: number;
+  claimsVerified: number;
+  claimsUnverified: number;
+  statsFound: number;
+  statsOutdated: number;
+  findings: Finding[];
+  recommendations: Recommendation[];
+}
+
+// ============================================
+// Compliance Analysis Types (US-010)
+// ============================================
+
+export interface RegulatedTerm {
+  term: string;
+  location: string;
+  requiresProof: boolean;
+  hasProof: boolean;
+  disclaimer?: string;
+  risk: 'high' | 'medium' | 'low';
+}
+
+export interface ComplianceAnalysis {
+  overallScore: number;
+  regulatedTermsFound: RegulatedTerm[];
+  missingDisclaimers: string[];
+  unsubstantiatedClaims: string[];
+  findings: Finding[];
+  recommendations: Recommendation[];
+}
+
+// ============================================
+// Full Analysis Types
+// ============================================
+
+export interface AnalysisConfig {
+  brandGuidelines?: BrandGuidelines;
+  productData?: ProductData;
+  enableBrand?: boolean;
+  enableConversion?: boolean;
+  enableAccuracy?: boolean;
+  enableCompliance?: boolean;
+}
+
+export interface FullAnalysis {
+  page: string;
+  timestamp: string;
+  brand?: BrandAnalysis;
+  conversion?: ConversionAnalysis;
+  accuracy?: AccuracyAnalysis;
+  compliance?: ComplianceAnalysis;
+  overallHealth: number;
+  topPriorities: Recommendation[];
+}