ai-contextor

v0.5.4

Published

6 months ago

Check documentation freshness for AI assistant projects. Keep your AI docs in sync with code changes.

ai-contextor

Keep your AI documentation fresh and in sync with code changes.

📦 npm package: ai-contextor
⭐ Star us on GitHub: driule/ai-contextor
💝 Support this project: GitHub Sponsors

Check documentation freshness for AI assistant projects. Automatically detects when documentation needs updates after code changes. Non-intrusive, git-aware, and highly configurable.

🚀 Quick Start

Step 1: Installation

Install as a development dependency:

npm install --save-dev ai-contextor

Or use it directly with npx (no installation needed):

npx ai-contextor

Step 2: Initialize Documentation

Generate initial documentation structure for your project:

npx contextor init

This command will:

🔍 Analyze your project structure
📊 Detect project type (frontend, backend, fullstack, library, etc.)
🛠️ Identify frameworks and technologies
📄 Create .ai/INIT.md with project context for AI assistants

Example output:

🔍 Analyzing project structure...

✅ Documentation initialized!

📄 Created: .ai/INIT.md

📊 Project Type: frontend
🛠️  Frameworks: React, Next.js
💻 Languages: TypeScript, JavaScript, CSS

💡 Review and customize .ai/INIT.md as needed.

Step 3: Configure (Optional)

Create .contextor.config.js in your project root to customize behavior:

module.exports = {
  // Documentation directory
  docsDir: ".ai",
  
  // Source directories to monitor
  sourceDirs: ["src"],
  
  // Mapping: source files → documentation files
  mappings: {
    "src/app.ts": [".ai/architecture/system-overview.md"],
    "src/services/**/*.ts": [".ai/architecture/components.md"],
  },
  
  // Cache file location (default: .ai/docs-check-cache.json)
  cacheFile: ".ai/docs-check-cache.json",
  
  // Check settings
  check: {
    lastUpdated: true,  // Check "Last Updated" dates
    version: true,       // Check version numbers
    links: true,         // Check broken links
    structure: true,     // Check required sections
  },
};

Step 4: Check Documentation

Run the checker to verify documentation freshness:

# Basic check
npx contextor

# Force check (ignore cache)
npx contextor --force

# Quiet mode (minimal output)
npx contextor --quiet

Step 5: Development Task Workflow (Optional)

Use the task system for managing development documentation:

# 1. Create a new task
npx contextor task:new "Add user authentication"

# 2. Develop and document in .ai/dev/task-0/ folder
#    - Edit requirements.md
#    - Add notes to notes.md
#    - Document implementation in implementation.md

# 3. Generate documentation drafts
npx contextor 0

# 4. AI assistant reviews and improves drafts
#    - Review .ai/dev/task-0/doc-integration-*.md files
#    - Follow instructions in DOC-INTEGRATION.md

# 5. Integrate improved documentation
npx contextor 0 --integrate

# 6. Commit documentation updates
git add .ai/
git commit -m "Update documentation for user authentication"

📖 Features

✅ Smart Project Analysis - Automatically detects project type and tech stack
✅ Documentation Initialization - Generates .ai/INIT.md with project context
✅ Development Task System - Manage temporary task documentation with integration workflow
✅ Freshness Checking - Detects outdated documentation
✅ Git Integration - Only checks when code changes
✅ Link Validation - Checks for broken internal links
✅ Structure Validation - Ensures required sections exist
✅ Smart Caching - Avoids redundant checks
✅ Safe Defaults - Won't overwrite existing documentation unless forced
✅ Configurable - Works with any project structure

📝 Usage Guide

Initializing Documentation

The init command analyzes your project and creates a comprehensive INIT.md file:

npx contextor init

What it does:

Scans project structure (directories, files, dependencies)
Detects project type (frontend/backend/fullstack/library/monorepo)
Identifies frameworks (React, Vue, Express, NestJS, etc.)
Detects build tools (Webpack, Vite, etc.)
Identifies test frameworks (Jest, Vitest, Cypress, etc.)
Generates .ai/INIT.md with:
- Project overview and type
- Technology stack
- Project structure explanation
- Development workflow
- Documentation guidelines
- AI assistant instructions

Checking Documentation Freshness

Run the checker to ensure documentation stays up-to-date:

# Standard check
npx contextor

# Force check (bypass cache)
npx contextor --force
npx contextor -f

# Quiet mode
npx contextor --quiet
npx contextor -q

What it checks:

Whether source files were modified after documentation
Missing "Last Updated" dates
Broken internal links
Required documentation sections
Documentation structure compliance

Development Task Management

Manage temporary development documentation with the task system:

1. Create a new task:

npx contextor task:new "Add user authentication"

This creates .ai/dev/task-0/ with:

README.md - Task overview and status
requirements.md - Detailed requirements template
notes.md - Development notes template
implementation.md - Implementation details template

2. Generate documentation drafts:

# After committing code changes
npx contextor 0

This generates:

doc-integration-*.md - Draft documentation files
DOC-INTEGRATION.md - Instructions for AI assistant

3. Integrate improved drafts:

# After AI assistant improves drafts
npx contextor 0 --integrate

This integrates the improved drafts into main documentation (.ai/ directory).

Task workflow:

Create task → Develop → Document in task folder
Commit code → Generate drafts
AI assistant improves drafts
Integrate → Commit documentation

Configuration

Copy .contextor.config.js.example to .contextor.config.js and customize:

cp .contextor.config.js.example .contextor.config.js

Key configuration options:

docsDir - Documentation directory (default: .ai)
sourceDirs - Directories to monitor for changes
mappings - Map source files to documentation files
cacheFile - Cache file location
check.* - Enable/disable specific checks

🎯 Common Workflows

New Project Setup

# 1. Install
npm install --save-dev ai-contextor

# 2. Initialize documentation
npx contextor init

# 3. Review and customize .ai/INIT.md

# 4. Add to package.json scripts
# "scripts": {
#   "docs:check": "contextor"
# }

# 5. Run checks
npm run docs:check

Existing Project

# 1. Initialize documentation
npx contextor init

# 2. Configure mappings in .contextor.config.js
# 3. Create documentation files in .ai/ directory
# 4. Run checks regularly
npx contextor

CI/CD Integration

Add to your CI pipeline:

# GitHub Actions example
- name: Check documentation freshness
  run: npx contextor

📁 Project Structure

After initialization, your project will have:

your-project/
├── .ai/
│   ├── INIT.md                      # Generated project context
│   ├── README.md                    # Documentation framework overview
│   ├── architecture/                # Architecture documentation
│   ├── api/                         # API documentation
│   ├── examples/                    # Usage examples
│   ├── dev/                         # Development tasks (gitignored)
│   │   ├── README.md                # Task system documentation
│   │   └── task-N/                  # Individual task directories
│   └── docs-check-cache.json        # Cache file (gitignored)
├── .contextor.config.js             # Configuration (optional)
└── ...

Note: The .ai/dev/ directory is gitignored and contains temporary task documentation.

🔧 CLI Commands

Core Commands

| Command | Description | |---------|-------------| | npx contextor | Check documentation freshness (default) | | npx contextor init | Initialize documentation structure | | npx contextor init --force | Initialize and overwrite existing INIT.md | | npx contextor task:new "description" | Create a new development task directory | | npx contextor <task-list> | Generate documentation drafts for tasks | | npx contextor <task-list> --integrate | Integrate improved drafts into main docs | | npx contextor --help | Show help message | | npx contextor --version | Show version number |

Options

| Option | Description | |--------|-------------| | --force, -f | Force mode (overwrite INIT.md or ignore cache) | | --quiet, -q | Quiet mode (minimal output) |

Examples

# Initialize documentation
npx contextor init

# Initialize and overwrite existing INIT.md
npx contextor init --force

# Create a new task
npx contextor task:new "Add user authentication"

# Generate drafts for task-0
npx contextor 0
# or
npx contextor task-0

# Generate drafts for multiple tasks
npx contextor 0,1,2
# or
npx contextor task-0,task-1,task-2

# Integrate improved drafts
npx contextor 0 --integrate

# Check documentation freshness
npx contextor

# Force check (ignore cache)
npx contextor --force

# Quiet mode
npx contextor --quiet

📚 Documentation Structure

Documentation files in .ai/ directory should follow this structure:

# Document Title

**Last Updated**: YYYY-MM-DD
**Version**: 1.0.0

## Overview
Brief description...

## Details
Main content...

## 🔗 Related Documentation
- [Link to related doc](./other-doc.md)

🤝 Contributing

Contributions welcome! Please read our Contributing Guidelines first.

Ways to contribute:

🐛 Report bugs
💡 Suggest new features
📝 Improve documentation
🔧 Submit pull requests
⭐ Star the repository

💝 Support & Sponsorship

This project is open source and free to use. If you find it helpful, please consider:

⭐ Starring the repository on GitHub
🐛 Reporting bugs and issues
💬 Sharing with your team and community
💝 Sponsoring the project to support continued development

GitHub Sponsors

Support this project through GitHub Sponsors. Your sponsorship helps:

🚀 Maintain and improve the project
🐛 Fix bugs faster
✨ Add new features
📚 Create better documentation

Sponsorship Tiers:

🤖 Assistant ($5/month) - Thank you! Your name in README supporters list
🚀 Navigator ($15/month) - Priority support + your name in README
⚡ Architect ($50/month) - All above + feature requests priority
🌟 Context Master ($200/month) - All above + custom features consultation

Note: GitHub Sponsors is free - GitHub doesn't take any fees for personal accounts!

Other Ways to Support

💼 Hire me for consulting or custom development
📧 Contact: GitHub Profile

📄 License

MIT © Andrius

📦 Version

Current version: 0.5.4

Status: 🚧 Beta - Ready for use, but still in active development

What's New in v0.5.0

✨ Safe init behavior - INIT.md is now skipped if exists (prevents overwriting custom docs)
✨ --force flag - Allows overwriting INIT.md when needed
🔧 Refactored generator - Improved code maintainability and extensibility
📚 Task system - Complete development task workflow with draft generation and integration

Roadmap

[ ] Unit tests and test coverage
[ ] CI/CD pipeline
[ ] TypeScript definitions
[ ] More project type templates
[ ] Enhanced error messages

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ai-contextor

🚀 Quick Start

Step 1: Installation

Step 2: Initialize Documentation

Step 3: Configure (Optional)

Step 4: Check Documentation

Step 5: Development Task Workflow (Optional)

📖 Features

📝 Usage Guide

Initializing Documentation

Checking Documentation Freshness

Development Task Management

Configuration

🎯 Common Workflows

New Project Setup

Existing Project

CI/CD Integration

📁 Project Structure

🔧 CLI Commands

Core Commands

Options

Examples

📚 Documentation Structure

🤝 Contributing

💝 Support & Sponsorship

GitHub Sponsors

Other Ways to Support

📄 License

📦 Version

What's New in v0.5.0

Roadmap