@f-o-t/content-analysis 1.0.0

package/README.md

@@ -0,0 +1,371 @@
+# @f-o-t/content-analysis
+
+A comprehensive content analysis library for SEO optimization, readability scoring, structure validation, and problematic pattern detection.
+
+## Installation
+
+```bash
+# npm
+npm install @f-o-t/content-analysis
+
+# pnpm
+pnpm add @f-o-t/content-analysis
+
+# bun
+bun add @f-o-t/content-analysis
+```
+
+## Features
+
+- **SEO Analysis** - Title, meta description, headings, keywords, content length, links, images
+- **Readability Scoring** - Flesch-Kincaid Reading Ease and Grade Level with audience targeting
+- **Structure Validation** - Heading hierarchy, paragraph lengths, table of contents, conclusions
+- **Bad Pattern Detection** - Clickbait, filler phrases, keyword stuffing, engagement begging
+- **Keyword Analysis** - Density, placement, and optimization recommendations
+- **Zero dependencies** - Lightweight and fast
+- **Full TypeScript support** - All types exported
+
+## Quick Start
+
+### Combined Analysis
+
+Run all analyzers at once with `analyzeContent()`:
+
+```typescript
+import { analyzeContent } from "@f-o-t/content-analysis";
+
+const result = analyzeContent({
+  content: "## Introduction\n\nThis is my blog post about TypeScript...",
+  title: "Complete Guide to TypeScript in 2024",
+  description: "Learn TypeScript from scratch with practical examples",
+  targetKeywords: ["typescript", "tutorial"],
+});
+
+console.log(result.seo.score);           // 85
+console.log(result.readability.fleschKincaidReadingEase); // 65.2
+console.log(result.structure.structure.hasQuickAnswer);   // false
+console.log(result.badPatterns.hasIssues);               // true
+console.log(result.keywords?.overallScore);              // 90
+```
+
+### Individual Analyzers
+
+Use specific analyzers when you only need certain metrics:
+
+```typescript
+import {
+  analyzeSeo,
+  analyzeReadability,
+  analyzeStructure,
+  analyzeBadPatterns,
+  analyzeKeywords,
+} from "@f-o-t/content-analysis";
+
+// SEO analysis
+const seo = analyzeSeo({
+  content: "## Getting Started\n\nLearn how to...",
+  title: "TypeScript Tutorial",
+  metaDescription: "A comprehensive guide to TypeScript",
+  targetKeywords: ["typescript", "tutorial"],
+});
+
+// Readability analysis
+const readability = analyzeReadability(content, "general");
+
+// Structure analysis
+const structure = analyzeStructure(content, "how-to");
+
+// Bad pattern detection
+const badPatterns = analyzeBadPatterns(content, title);
+
+// Keyword analysis
+const keywords = analyzeKeywords({
+  content,
+  title,
+  targetKeywords: ["typescript", "tutorial"],
+});
+```
+
+## API Reference
+
+### `analyzeContent(input)`
+
+Performs comprehensive content analysis using all available analyzers.
+
+```typescript
+type AnalysisInput = {
+  content: string;           // Markdown content to analyze
+  title?: string;            // Page title
+  description?: string;      // Meta description
+  targetKeywords?: string[]; // Keywords to track
+};
+
+type ContentAnalysisResult = {
+  seo: SeoResult;
+  readability: ReadabilityResult;
+  structure: StructureResult;
+  badPatterns: BadPatternResult;
+  keywords: KeywordAnalysisResult | null;
+  analyzedAt: string;        // ISO timestamp
+};
+```
+
+---
+
+### `analyzeSeo(input)`
+
+Analyzes content for search engine optimization factors.
+
+**Checks performed:**
+- Title length (optimal: 50-60 characters)
+- Title contains target keyword
+- Meta description length (optimal: 150-160 characters)
+- Heading structure (H1 should not be in content)
+- H2 heading frequency (1 per 200-300 words)
+- Keywords in H2 headings
+- Content length (minimum: 600-1000 words)
+- Internal/external links
+- Images with alt text
+- Quick answer in first 100 words
+- Keyword in first paragraph
+- Keyword density (optimal: 1-2%)
+- Conclusion section
+
+```typescript
+type SeoInput = {
+  content: string;
+  title?: string;
+  metaDescription?: string;
+  targetKeywords?: string[];
+};
+
+type SeoResult = {
+  score: number;              // 0-100
+  issues: SeoIssue[];         // Problems found
+  recommendations: string[];  // Action items
+  metrics: SeoMetrics;        // Counts and flags
+};
+```
+
+---
+
+### `analyzeReadability(content, targetAudience)`
+
+Analyzes content readability using Flesch-Kincaid algorithms.
+
+**Target audiences:**
+| Audience | Reading Ease Range | Description |
+|----------|-------------------|-------------|
+| `general` | 60-70 | Easy to read for general audience |
+| `technical` | 40-60 | Technical but accessible |
+| `academic` | 30-50 | Academic/professional level |
+| `casual` | 70-80 | Very easy, conversational |
+
+```typescript
+type ReadabilityResult = {
+  fleschKincaidReadingEase: number;  // 0-100 (higher = easier)
+  fleschKincaidGradeLevel: number;   // US grade level
+  readabilityLevel: string;          // Human-readable description
+  targetScore: TargetScore;          // Target range for audience
+  isOnTarget: boolean;               // Within target range
+  suggestions: string[];             // Improvement suggestions
+  metrics: ReadabilityMetrics;       // Detailed metrics
+};
+```
+
+**Reading Ease Scale:**
+| Score | Level |
+|-------|-------|
+| 90-100 | Very Easy (5th grade) |
+| 80-89 | Easy (6th grade) |
+| 70-79 | Fairly Easy (7th grade) |
+| 60-69 | Standard (8th-9th grade) |
+| 50-59 | Fairly Difficult (10th-12th grade) |
+| 30-49 | Difficult (College) |
+| 0-29 | Very Difficult (College Graduate) |
+
+---
+
+### `analyzeStructure(content, contentType?)`
+
+Analyzes content structure for SEO and readability best practices.
+
+**Content types:**
+- `how-to` - Expects numbered steps
+- `comparison` - Expects comparison tables
+- `listicle` - Expects multiple list items
+- `explainer` - General explanatory content
+- `general` - Default
+
+**Checks performed:**
+- H1 heading not in content body
+- Heading hierarchy (no skipped levels)
+- Quick answer in first 100 words
+- Paragraph lengths (max 4 sentences recommended)
+- H2 frequency (1 per 250 words)
+- Table of contents for long content (1500+ words)
+- Conclusion section
+
+```typescript
+type StructureResult = {
+  score: number;                   // 0-100
+  issues: StructureIssue[];        // Problems found
+  structure: ContentStructure;     // Structure metrics
+};
+
+type ContentStructure = {
+  hasQuickAnswer: boolean;
+  headingHierarchyValid: boolean;
+  avgParagraphLength: number;
+  hasTableOfContents: boolean;
+  hasTables: boolean;
+  hasConclusion: boolean;
+  headingCount: number;
+  wordCount: number;
+};
+```
+
+---
+
+### `analyzeBadPatterns(content, title?)`
+
+Detects problematic content patterns that hurt quality and SEO.
+
+**Patterns detected:**
+
+| Pattern | Description |
+|---------|-------------|
+| `word_count_mention` | References to word count in content |
+| `word_count_in_title` | Word count claims in title |
+| `meta_commentary` | "In this article...", "As mentioned above..." |
+| `engagement_begging` | "Don't forget to like and subscribe" |
+| `endless_introduction` | Introduction over 150 words |
+| `vague_instructions` | "Configure appropriately", "Set up as needed" |
+| `clickbait_markers` | "You won't believe...", excessive punctuation |
+| `filler_phrases` | "Without further ado", "At the end of the day" |
+| `over_formatting` | Excessive consecutive bold/italic |
+| `wall_of_text` | Paragraphs over 100 words |
+| `keyword_stuffing` | Phrase density over 3% |
+
+```typescript
+type BadPatternResult = {
+  hasIssues: boolean;
+  issueCount: number;
+  patterns: BadPattern[];
+};
+
+type BadPattern = {
+  pattern: string;           // Pattern type identifier
+  severity: "error" | "warning";
+  locations: string[];       // Context snippets
+  suggestion: string;        // How to fix
+};
+```
+
+---
+
+### `analyzeKeywords(input)`
+
+Analyzes keyword usage, density, and placement.
+
+**Checks performed:**
+- Keyword count and density (optimal: 0.5-3%)
+- Keyword locations (title, headings, first/last 100 words)
+- Missing keywords
+- Overused keywords
+- Top 10 most frequent words in content
+
+```typescript
+type KeywordInput = {
+  content: string;
+  title?: string;
+  targetKeywords: string[];
+};
+
+type KeywordAnalysisResult = {
+  analysis: KeywordAnalysisItem[];   // Per-keyword analysis
+  overallScore: number;              // 0-100
+  topKeywords: TopKeyword[];         // Most frequent words
+  recommendations: string[];         // Action items
+  metrics: KeywordMetrics;           // Word counts
+};
+
+type KeywordAnalysisItem = {
+  keyword: string;
+  count: number;
+  density: number;                   // Percentage
+  locations: KeywordLocation[];      // Where found
+  status: "optimal" | "low" | "high" | "missing";
+  suggestion?: string;
+};
+```
+
+---
+
+### Utility Functions
+
+Low-level utilities exported for advanced usage:
+
+```typescript
+import {
+  calculateFleschKincaid,  // Get reading ease and grade level
+  countSyllables,          // Count syllables in a word
+  getReadabilityLevel,     // Convert score to description
+  extractWords,            // Split content into words
+  extractParagraphs,       // Split content into paragraphs
+  extractHeadings,         // Extract headings with levels
+  findOccurrences,         // Find regex matches with context
+  hasQuickAnswerPattern,   // Check for quick answer patterns
+  hasConclusionSection,    // Check for conclusion heading
+  clampScore,              // Clamp value to 0-100
+} from "@f-o-t/content-analysis";
+
+// Examples
+const { readingEase, gradeLevel } = calculateFleschKincaid(text);
+const syllables = countSyllables("comprehensive"); // 4
+const level = getReadabilityLevel(65); // "Standard (8th-9th grade)"
+const headings = extractHeadings(content);
+// [{ level: 2, text: "Introduction", index: 0 }, ...]
+```
+
+## Types
+
+All types are exported from the main package and from `@f-o-t/content-analysis/types`:
+
+```typescript
+import type {
+  // Input types
+  AnalysisInput,
+  SeoInput,
+  KeywordInput,
+
+  // Result types
+  ContentAnalysisResult,
+  SeoResult,
+  ReadabilityResult,
+  StructureResult,
+  BadPatternResult,
+  KeywordAnalysisResult,
+
+  // Detail types
+  SeoIssue,
+  SeoMetrics,
+  ReadabilityMetrics,
+  StructureIssue,
+  ContentStructure,
+  BadPattern,
+  KeywordAnalysisItem,
+  TopKeyword,
+
+  // Enums/unions
+  Severity,
+  TargetAudience,
+  ContentType,
+  BadPatternType,
+  KeywordStatus,
+} from "@f-o-t/content-analysis";
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+/**
+* Content Analysis Types
+* All type definitions for SEO, readability, structure, and pattern analysis
+*/
+type SeoIssueType = "title" | "meta_description" | "headings" | "keyword_density" | "content_length" | "readability" | "links" | "images" | "quick_answer" | "first_paragraph" | "heading_keywords" | "structure";
+type Severity = "error" | "warning" | "info";
+type SeoIssue = {
+	type: SeoIssueType;
+	severity: Severity;
+	message: string;
+	suggestion: string;
+};
+type SeoMetrics = {
+	wordCount: number;
+	headingCount: number;
+	paragraphCount: number;
+	linkCount: number;
+	imageCount: number;
+	hasQuickAnswer: boolean;
+	keywordInFirstParagraph: boolean;
+	keywordDensity?: Record<string, number>;
+};
+type SeoResult = {
+	score: number;
+	issues: SeoIssue[];
+	recommendations: string[];
+	metrics: SeoMetrics;
+};
+type SeoInput = {
+	content: string;
+	title?: string;
+	metaDescription?: string;
+	targetKeywords?: string[];
+};
+type TargetAudience = "general" | "technical" | "academic" | "casual";
+type ReadabilityMetrics = {
+	sentenceCount: number;
+	wordCount: number;
+	avgWordsPerSentence: number;
+	avgSyllablesPerWord: number;
+	complexWordCount: number;
+	complexWordPercentage: number;
+};
+type TargetScore = {
+	min: number;
+	max: number;
+	description: string;
+};
+type ReadabilityResult = {
+	fleschKincaidReadingEase: number;
+	fleschKincaidGradeLevel: number;
+	readabilityLevel: string;
+	targetScore: TargetScore;
+	isOnTarget: boolean;
+	suggestions: string[];
+	metrics: ReadabilityMetrics;
+};
+type ContentType = "how-to" | "comparison" | "explainer" | "listicle" | "general";
+type StructureIssue = {
+	type: string;
+	severity: Severity;
+	message: string;
+	suggestion: string;
+};
+type ContentStructure = {
+	hasQuickAnswer: boolean;
+	headingHierarchyValid: boolean;
+	avgParagraphLength: number;
+	hasTableOfContents: boolean;
+	hasTables: boolean;
+	hasConclusion: boolean;
+	headingCount: number;
+	wordCount: number;
+};
+type StructureResult = {
+	score: number;
+	issues: StructureIssue[];
+	structure: ContentStructure;
+};
+type BadPatternType = "word_count_mention" | "word_count_in_title" | "meta_commentary" | "engagement_begging" | "endless_introduction" | "vague_instructions" | "clickbait_markers" | "filler_phrases" | "over_formatting" | "wall_of_text" | "keyword_stuffing";
+type BadPattern = {
+	pattern: string;
+	severity: "error" | "warning";
+	locations: string[];
+	suggestion: string;
+};
+type BadPatternResult = {
+	hasIssues: boolean;
+	issueCount: number;
+	patterns: BadPattern[];
+};
+type KeywordLocationType = "title" | "heading" | "paragraph" | "first100words" | "last100words";
+type KeywordStatus = "optimal" | "low" | "high" | "missing";
+type KeywordLocation = {
+	type: KeywordLocationType;
+	index?: number;
+};
+type KeywordAnalysisItem = {
+	keyword: string;
+	count: number;
+	density: number;
+	locations: KeywordLocation[];
+	status: KeywordStatus;
+	suggestion?: string;
+};
+type TopKeyword = {
+	keyword: string;
+	count: number;
+	density: number;
+};
+type KeywordMetrics = {
+	totalWordCount: number;
+	uniqueWordCount: number;
+	avgKeywordDensity: number;
+};
+type KeywordAnalysisResult = {
+	analysis: KeywordAnalysisItem[];
+	overallScore: number;
+	topKeywords: TopKeyword[];
+	recommendations: string[];
+	metrics: KeywordMetrics;
+};
+type KeywordInput = {
+	content: string;
+	title?: string;
+	targetKeywords: string[];
+};
+type ContentAnalysisResult = {
+	seo: SeoResult;
+	readability: ReadabilityResult;
+	structure: StructureResult;
+	badPatterns: BadPatternResult;
+	keywords: KeywordAnalysisResult | null;
+	analyzedAt: string;
+};
+type AnalysisInput = {
+	content: string;
+	title?: string;
+	description?: string;
+	targetKeywords?: string[];
+};
+/**
+* Analyze content for bad patterns
+*/
+declare function analyzeBadPatterns(content: string, title?: string): BadPatternResult;
+/**
+* Analyze keyword usage in content
+*/
+declare function analyzeKeywords(input: KeywordInput): KeywordAnalysisResult;
+/**
+* Analyze content readability
+*/
+declare function analyzeReadability(content: string, targetAudience?: TargetAudience): ReadabilityResult;
+/**
+* Analyze content for SEO optimization
+*/
+declare function analyzeSeo(input: SeoInput): SeoResult;
+/**
+* Analyze content structure
+*/
+declare function analyzeStructure(content: string, contentType?: ContentType): StructureResult;
+/**
+* Shared utility functions for content analysis
+*/
+/**
+* Count syllables in a word using a simplified vowel group algorithm
+*/
+declare function countSyllables(word: string): number;
+/**
+* Calculate Flesch-Kincaid readability metrics
+*/
+declare function calculateFleschKincaid(text: string): {
+	readingEase: number;
+	gradeLevel: number;
+};
+/**
+* Convert reading ease score to human-readable level
+*/
+declare function getReadabilityLevel(score: number): string;
+/**
+* Find all occurrences of a regex pattern with surrounding context
+*/
+declare function findOccurrences(regex: RegExp, text: string): string[];
+/**
+* Extract words from content
+*/
+declare function extractWords(content: string): string[];
+/**
+* Extract paragraphs from content
+*/
+declare function extractParagraphs(content: string): string[];
+/**
+* Extract headings from markdown content
+*/
+declare function extractHeadings(content: string): Array<{
+	level: number;
+	text: string;
+	index: number;
+}>;
+/**
+* Clamp score between 0 and 100
+*/
+declare function clampScore(score: number): number;
+/**
+* Check if content has a quick answer pattern in the first portion
+*/
+declare function hasQuickAnswerPattern(text: string): boolean;
+/**
+* Check if content has a conclusion section
+*/
+declare function hasConclusionSection(content: string): boolean;
+/**
+* Perform a comprehensive content analysis
+*
+* This function runs all available analyzers and returns a combined result:
+* - SEO analysis (title, meta, keywords, structure)
+* - Readability analysis (Flesch-Kincaid scores)
+* - Structure analysis (headings, paragraphs, quick answers)
+* - Bad pattern detection (filler phrases, clickbait, etc.)
+* - Keyword analysis (density, placement, recommendations)
+*
+* @param input - The content and metadata to analyze
+* @returns Combined analysis results from all analyzers
+*
+* @example
+* ```typescript
+* import { analyzeContent } from '@f-o-t/content-analysis';
+*
+* const result = analyzeContent({
+*   content: '## Introduction\n\nThis is my blog post...',
+*   title: 'My Blog Post Title',
+*   description: 'A short description for SEO',
+*   targetKeywords: ['blog', 'tutorial'],
+* });
+*
+* console.log(result.seo.score); // 85
+* console.log(result.readability.fleschKincaidReadingEase); // 65.2
+* ```
+*/
+declare function analyzeContent(input: AnalysisInput): ContentAnalysisResult;
+export { hasQuickAnswerPattern, hasConclusionSection, getReadabilityLevel, findOccurrences, extractWords, extractParagraphs, extractHeadings, countSyllables, clampScore, calculateFleschKincaid, analyzeStructure, analyzeSeo, analyzeReadability, analyzeKeywords, analyzeContent, analyzeBadPatterns, TopKeyword, TargetScore, TargetAudience, StructureResult, StructureIssue, Severity, SeoResult, SeoMetrics, SeoIssueType, SeoIssue, SeoInput, ReadabilityResult, ReadabilityMetrics, KeywordStatus, KeywordMetrics, KeywordLocationType, KeywordLocation, KeywordInput, KeywordAnalysisResult, KeywordAnalysisItem, ContentType, ContentStructure, ContentAnalysisResult, BadPatternType, BadPatternResult, BadPattern, AnalysisInput };