@oletizi/shakespeare

AI-driven content review and improvement system with configurable content collection support.

Features

• AI-Powered Analysis: Uses real AI (via Goose CLI) to analyze and score content quality
• Content Collections: Built-in support for Astro, Next.js, Gatsby, and custom configurations
• Multiple Quality Dimensions: Analyzes readability, SEO, technical accuracy, engagement, and content depth
• Automated Improvement: AI-generated content improvements with tracking
• Flexible Configuration: Supports MDX, Markdown, and custom file patterns

Quick Start

For Astro Projects (Default)

import { ShakespeareFactory } from '@oletizi/shakespeare';

// Uses Astro's src/content directory by default
const shakespeare = ShakespeareFactory.forAstro();

// Analyze all content
await shakespeare.updateContentIndex();

// Find lowest quality content
const worstContent = await shakespeare.getWorstScoringContent();
console.log('Needs improvement:', worstContent);

// Improve content with AI
await shakespeare.improveContent(worstContent);

For Other Frameworks

// Next.js projects
const shakespeare = ShakespeareFactory.forNextJS();

// Gatsby projects  
const shakespeare = ShakespeareFactory.forGatsby();

// Custom configuration
const shakespeare = ShakespeareFactory.forCustom({
  baseDir: 'docs',
  include: ['**/*.mdx', '**/*.md'],
  exclude: ['**/README.md']
});

Manual Configuration

import { Shakespeare, CONTENT_COLLECTIONS } from '@oletizi/shakespeare';

const shakespeare = new Shakespeare(process.cwd(), undefined, {
  contentCollection: 'astro' // or 'nextjs', 'gatsby'
});

// Or with custom config
const shakespeare = new Shakespeare(process.cwd(), undefined, {
  contentCollection: {
    baseDir: 'src/content',
    include: ['**/*.mdx', '**/*.md'],
    exclude: ['**/index.md', '**/README.md'],
    framework: 'custom'
  }
});

Content Collection Configurations

Built-in Configurations

| Framework | Base Directory | Includes | Excludes | |-----------|---------------|----------|----------| | Astro | src/content | **/*.mdx, **/*.md | **/index.md, **/README.md | | Next.js | content | **/*.mdx, **/*.md | **/README.md | | Gatsby | content | **/*.mdx, **/*.md | **/README.md |

Custom Configuration

import { ContentCollectionConfig, CONTENT_COLLECTIONS } from '@oletizi/shakespeare';

// Create custom configuration
const customConfig: ContentCollectionConfig = {
  baseDir: 'my-docs',
  include: ['**/*.mdx'],
  exclude: ['**/draft-*.mdx'],
  framework: 'custom'
};

// Or use the helper function
const config = CONTENT_COLLECTIONS.custom(
  'my-docs',           // baseDir
  ['**/*.mdx'],        // include patterns
  ['**/draft-*.mdx']   // exclude patterns
);

Quality Dimensions

Shakespeare analyzes content across five dimensions:

• Readability (1-10): How easy the content is to read and understand
• SEO Score (1-10): Search engine optimization potential
• Technical Accuracy (1-10): Correctness and completeness of technical content
• Engagement (1-10): How engaging and interactive the content is
• Content Depth (1-10): Comprehensiveness and depth of coverage

Content Status

Based on average scores, content receives one of three statuses:

• meets_targets: Average score ≥ 8.5 - High quality content
• needs_improvement: Average score ≥ 7.0 - Good content with room for improvement
• needs_review: Average score < 7.0 - Requires significant attention

API Reference

Core Classes

Shakespeare

Main class for content analysis and improvement.

constructor(
  rootDir?: string,              // Project root directory
  dbPath?: string,               // Database file path
  options?: ShakespeareOptions   // Configuration options
)

ShakespeareFactory

Convenience factory for framework-specific configurations.

ShakespeareFactory.forAstro(rootDir?, dbPath?, options?)
ShakespeareFactory.forNextJS(rootDir?, dbPath?, options?)
ShakespeareFactory.forGatsby(rootDir?, dbPath?, options?)
ShakespeareFactory.forCustom(config, rootDir?, dbPath?, options?)

Content Discovery Workflow

Shakespeare provides two approaches to content management:

1. Lightweight Discovery (Recommended for large projects)

# Quick discovery - indexes files without AI scoring
npm run discover-content

# Review individual files as needed
npm run review-content src/content/article.md

# Find worst reviewed content for improvement
npm run improve-content

2. Full Indexing (All-in-one approach)

# Comprehensive scan with immediate AI analysis
npm run update-content-index

# Improve worst content
npm run improve-content

Content States

• needs_review - Discovered but not yet analyzed by AI (zero scores)
• needs_improvement - Reviewed with scores < 8.5 average
• meets_targets - High quality content (≥ 8.5 average)
• in_progress - Currently being improved

Key Methods

// Lightweight content discovery (fast, no AI scoring)
const newFiles = await shakespeare.discoverContent();

// Get unreviewed content
const needsReview = shakespeare.getContentNeedingReview();

// Review specific content with AI
await shakespeare.reviewContent(filePath);

// Scan and analyze all content (slower, includes AI scoring)
await shakespeare.updateContentIndex();

// Get content that needs the most improvement (excludes unreviewed)
const worstContent = await shakespeare.getWorstScoringContent();

// Improve content with AI
await shakespeare.improveContent(filePath);

Requirements

• Node.js 18+
• Goose CLI installed and configured with API credentials
• TypeScript project with ES modules

Installing Goose CLI

# Install goose (see https://github.com/block-open-source/goose for details)
pip install goose-ai

# Configure with your AI provider
goose configure

Configuration Files

Shakespeare creates a .shakespeare/ directory in your project with:

• content-db.json: Content analysis database with scores and history
• Improved content files with .improved.md extension

Database Portability

The content database stores file paths as relative paths from the database directory, making it portable across different systems and project locations. This means you can:

• Move your project to different directories
• Share the database across team members
• Deploy to different environments
• Archive and restore project state

Example database structure:

{
  "lastUpdated": "2025-08-26T06:15:31.708Z",
  "entries": {
    "../src/content/blog/post1.md": {
      "path": "../src/content/blog/post1.md",
      "currentScores": { ... },
      "status": "needs_review"
    }
  }
}

Add to .gitignore:

.shakespeare/
*.improved.md
*.improved.mdx

Testing

# Run all tests (unit + integration, excludes smoke tests)
npm test

# Run tests with coverage report
npm run test:coverage

# Run integration tests only (uses mocks)
npm run test:integration  

# Run smoke tests manually (requires real AI configuration & expensive API calls)
npm run test:smoke

Test Coverage

The project maintains comprehensive test coverage with automatic threshold enforcement:

• Coverage Badge: Automatically updated via GitHub Actions and Codecov
• Coverage Reports: Generated in coverage/ directory
• HTML Report: View detailed coverage at coverage/index.html
• Thresholds: Configured per-file minimums to maintain code quality
• CI Integration: Coverage uploaded to Codecov on every push/PR

# View coverage summary in terminal
npm run test:coverage

# Open detailed HTML coverage report
open coverage/index.html  # macOS
start coverage/index.html # Windows

Note: Smoke tests are excluded from the default test suite (npm test) because they make real AI API calls which can be expensive. Run them manually only when needed for end-to-end verification.

Publishing

This package is configured for publishing to npm with industry-standard best practices.

For Package Maintainers

Initial Setup

1. Authenticate with npm:

   npm login

2. Verify package configuration:

   npm run prepublishOnly  # Runs tests and build

Publishing Process

Patch Release (bug fixes):

npm run publish:patch  # 1.0.0 → 1.0.1 + publish
# Or manually: npm version patch && npm publish --otp=<code>

Minor Release (new features):

npm run publish:minor  # 1.0.0 → 1.1.0 + publish
# Or manually: npm version minor && npm publish --otp=<code>

Major Release (breaking changes):

npm run publish:major  # 1.0.0 → 2.0.0 + publish
# Or manually: npm version major && npm publish --otp=<code>

Note: If you have 2FA enabled, you'll be prompted for your OTP code during the publish step.

Automated Publishing Workflow

The package includes automated scripts that:

• npm version: Builds the package and stages dist files
• npm publish: Runs full test suite and build before publishing
• Post-publish: Creates git tags and pushes to repository

Manual Verification

Before publishing, verify:

# Check what files will be published
npm pack --dry-run

# Verify package contents
tar -tvf *.tgz

# Test local installation
npm install -g ./shakespeare-1.0.0.tgz

Package Configuration

• Registry: https://registry.npmjs.org/ (public)
• Access: Public package under @oletizi scope
• Files: Only dist/, README.md, and CHANGELOG.md are published
• Exports: Proper ES module support with TypeScript declarations
• License: ISC

License

ISC