fossilize-cli

Generate documentation from actual code execution evidence — test-driven docs that never lie.

The Problem

Documentation is usually broken in one of three ways:

1. Manual and stale — engineers ship code faster than they update docs
2. Auto-generated but shallow — signatures and comments, not real behavior
3. AI-generated but ungrounded — sounds polished, fabricates examples

The Solution

Fossilize generates docs from evidence:

• Test descriptions become behavior documentation
• Export signatures become API references
• Route handlers become API docs (with real status codes from tests)
• Import graphs become architecture docs
• Git history becomes changelogs

Every example is REAL — from test execution, code signatures, or git history. Never fabricated.

Installation

npm install -g fossilize-cli

Usage

# Generate all docs for current project
fossilize .

# Output to specific directory
fossilize . --output docs/

# Only generate README
fossilize . --readme-only

# Output doc structure as JSON
fossilize . --format json

# Show what would be generated (no files written)
fossilize . --dry-run

# Skip test execution
fossilize . --skip-tests

# Skip git analysis
fossilize . --skip-git

What Gets Generated

| Document | Source | |----------|--------| | README.md | package.json + exports + test summary | | docs/api.md | Route handlers + test-verified status codes | | docs/architecture.md | Import graph + directory structure | | docs/changelog.md | Git history with conventional commit grouping |

Supported Stacks

• Languages: TypeScript, JavaScript (Python/Rust/Go detection planned)
• Frameworks: Next.js (App Router), Express, Fastify, Hono
• Test Runners: Vitest, Jest, Mocha (pytest/cargo test detection planned)

Key Principle

If no test exists for a function, Fossilize documents the signature but notes "no test coverage." It will never fabricate examples. Trust comes from proof.

License

MIT