archidoc-types 0.3.1

# archidoc

[![CI](https://github.com/archidoc/archidoc/actions/workflows/ci.yml/badge.svg)](https://github.com/archidoc/archidoc/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/archidoc-cli.svg)](https://crates.io/crates/archidoc-cli)
[![npm](https://img.shields.io/npm/v/archidoc-ts.svg)](https://www.npmjs.com/package/archidoc-ts)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

archidoc pulls your architecture — module boundaries, dependency edges, and GoF pattern contracts — straight from comments in your code, turns them into docs and LLM context, and fails your CI build if they fall out of sync.

## What It Does

Archidoc gives AI and humans high-level intent, mid-level structure, and links to details all in one enforcible file.
Archidoc pulls your architecture — module boundaries, dependency edges, and GoF pattern contracts — straight from comments in your code, turns them into docs and LLM context, and fails your CI build if they fall out of sync.

Developers annotate module entry files (`mod.rs`, `index.ts`, `__init__.py`) with structured comments containing C4 markers, GoF pattern labels, and file-level responsibility tables. archidoc compiles these annotations into a single **ARCHITECTURE.md** containing:

- **Inline Mermaid C4 diagrams** (container and component levels)
- **Component index table** (linking directly to source files)
- **Relationship map** (dependency arrows with labels and protocols)
- **AI context file** (`ARCHITECTURE.ai.md`) — token-optimized tree format for LLM consumption (~75% fewer tokens)
- **JSON IR** (portable intermediate representation for cross-language pipelines)

Optional sidecar outputs: **PlantUML** (`--plantuml`) and **draw.io CSV** (`--drawio`). The AI context file is generated by default (suppress with `--no-ai`).

It also detects **architecture drift** (docs out of sync with code), validates **file tables** (ghost/orphan detection), and reports **architecture health** (pattern confidence, file maturity).

## Install

```bash
# From crates.io
cargo install archidoc-cli

# Or from source
cargo install --path core/archidoc-cli

# Or build locally
cargo build --release
# Binary at target/release/archidoc
```

```bash
# TypeScript adapter (npm)
npm install archidoc-ts
```

## Usage

```bash
# Generate ARCHITECTURE.md + ARCHITECTURE.ai.md from source annotations
archidoc .

# Custom output path
archidoc . -o docs/ARCHITECTURE.md

# Skip AI context generation
archidoc . --no-ai

# Also generate PlantUML and/or draw.io sidecar files
archidoc . --plantuml --drawio

# Scaffold root-level lib.rs template for a new project
archidoc init

# Scaffold with explicit language (if auto-detection fails)
archidoc init --lang rust
archidoc init --lang ts

# Generate annotation template for a module directory
archidoc suggest src/api/

# Write the template directly into a module entry file
archidoc suggest src/api/ >> src/api/mod.rs

# Check for documentation drift (CI gate — exits non-zero on drift)
archidoc --check .

# Print architecture health report
archidoc --health .

# Validate file tables (ghost/orphan detection)
archidoc --validate .

# Export JSON IR for cross-language pipelines
archidoc --emit-ir .

# Generate ARCHITECTURE.md from JSON IR (any language adapter)
archidoc --from-json-file ir.json .

# Merge IR from multiple adapters (polyglot projects)
archidoc --merge-ir --from-json-file rust.json --from-json-file ts.json .
```

## Annotation Convention

Container-level (`mod.rs`):

```rust
//! @c4 container
//!
//! # Bus Module
//!
//! Central messaging and caching backbone.
//!
//! @c4 uses agents_internal "Processed market data" "crossbeam channel"
//!
//! | File | Pattern | Purpose | Health |
//! |------|---------|---------|--------|
//! | `lanes.rs` | Observer | Event routing channels | active |
//! | `store.rs` | Repository | Lock-free cache | stable |
```

TypeScript (`index.ts`):

```typescript
/**
 * @c4 container
 *
 * Central messaging and caching backbone.
 *
 * @c4 uses agents_internal "Processed market data" "WebSocket"
 *
 * | File | Pattern | Purpose | Health |
 * |------|---------|---------|--------|
 * | `core.ts` | Facade | Entry point | stable |
 */
```

### C4 Markers

- `@c4 container` — marks a C4 container
- `@c4 component` — marks a C4 component
- `@c4 uses target "label" "protocol"` — declares a dependency

### File Table

Each row declares a file in the module with its GoF pattern, purpose, and health status:

| Column | Values |
|--------|--------|
| **Pattern** | Any GoF pattern name, or `--` for none |
| **Health** | `planned` (not yet implemented), `active` (in progress), `stable` (complete) |

### Pattern Confidence

Pattern labels have two tiers:

- **planned** — developer's stated intent
- **verified** — structurally confirmed by heuristic analysis (Observer, Strategy, Facade)

## Getting Started

### Greenfield (new project)

1. **Scaffold the root template** — generates a `lib.rs` / `index.ts` doc comment with TODO sections for purpose, C4 context, data flow, concurrency patterns, deployment, and external dependencies:

   ```bash
   archidoc init                   # auto-detects Rust/TS from Cargo.toml or package.json
   archidoc init --lang rust       # explicit
   ```

   Paste the output into your root entry file (`lib.rs` or `index.ts`) and fill in the TODOs.

2. **Add module annotations** — as you create modules, scaffold their annotations:

   ```bash
   archidoc suggest src/api/       # generates a @c4 container/component template
   archidoc suggest src/api/ >> src/api/mod.rs
   ```

3. **Generate docs**:

   ```bash
   archidoc .
   ```

   This produces `ARCHITECTURE.md` (human-readable) and `ARCHITECTURE.ai.md` (token-optimized for LLMs).

### Brownfield (existing project)

1. **Pick your top-level modules** — identify the 3-5 directories that represent your system's major containers (e.g. `api/`, `core/`, `database/`)

2. **Scaffold annotations** for each module:

   ```bash
   archidoc suggest src/api/       # prints a ready-to-paste annotation block
   ```

3. **Add a C4 marker** to each module's entry file (`mod.rs`, `index.ts`, or `__init__.py`):

   ```rust
   //! @c4 container
   //!
   //! # Api
   //!
   //! REST API gateway — handles authentication and request routing.
   ```

4. **Run archidoc** to generate your first diagrams:

   ```bash
   archidoc .
   ```

5. **Optionally scaffold the root** — if you want data flow, concurrency, and deployment sections in your docs:

   ```bash
   archidoc init >> src/lib.rs     # append the template, then fill in the TODOs
   ```

6. **Add relationships** between containers:

   ```rust
   //! @c4 uses database "Persists user data" "sqlx"
   ```

7. **Gate your CI** to prevent architecture drift:

   ```bash
   archidoc --check .
   ```

Start with containers only. Add components, file tables, and relationships as the architecture stabilizes. See [Annotating Your Project](docs/annotating-your-project.md) for the full step-by-step guide.

## Project Structure

```
Cargo.toml              Workspace root
core/
  archidoc-types/       Shared types (ModuleDoc, C4Level, FileEntry, Relationship, etc.)
  archidoc-engine/      Language-agnostic generator (ARCHITECTURE.md, ai context, mermaid, plantuml, draw.io, IR, drift, health)
  archidoc-cli/         CLI binary: archidoc
  spec/                 JSON IR schema
  tests/                BDD test infrastructure (DSL, protocol drivers, fakes)
adapters/
  archidoc-rust/        Rust adapter (//! doc comments -> ModuleDoc)
  archidoc-ts/          TypeScript adapter (@c4 JSDoc -> JSON IR)
docs/                   Guides (annotation spec, getting started, LLM context)
examples/               Example annotated projects
```

## Architecture

archidoc follows a three-layer architecture:

1. **Types** (`archidoc-types`) — shared domain model: `ModuleDoc`, `C4Level`, `FileEntry`, `Relationship`, `PatternStatus`, `HealthStatus`
2. **Adapters** (`archidoc-rust`, `archidoc-ts`) — language-specific parsers that extract annotations and emit `ModuleDoc` arrays
3. **Engine** (`archidoc-engine`) — language-agnostic generators that consume `ModuleDoc` and produce ARCHITECTURE.md, diagrams, IR, drift reports, and health summaries

The CLI orchestrates: adapter parses source -> engine generates ARCHITECTURE.md.

### JSON IR

The intermediate representation (`ModuleDoc[]` as JSON) is the contract between adapters and the engine. Any language adapter that emits conforming JSON can use the full engine pipeline. See `core/spec/archidoc-ir-schema.json` for the schema.

## Writing a Language Adapter

To add support for a new language:

1. Scaffold with `archidoc init-adapter --lang python`
2. Implement a parser that extracts annotations from your language's comment format
3. Implement a walker that traverses source directories and collects `ModuleDoc` entries
4. Emit `ModuleDoc[]` JSON to stdout — the engine handles the rest

See the `archidoc-rust` and `archidoc-ts` adapters for reference implementations.

## Tests

```bash
# Run all Rust tests
cargo test

# Run TypeScript adapter tests
cd adapters/archidoc-ts && npm test
```

The test suite uses Dave Farley-style BDD: declarative test cases specify WHAT (behavior), protocol drivers translate to HOW (implementation). When the implementation changes, update drivers — not tests.

## License

MIT