@brainwav/diagram 1.0.7 → 1.1.0

package/README.md

@@ -1,400 +1,186 @@
-# diagram-cli
+# archscope
 
-Generate codebase architecture diagrams from source files. No AI required.
+Architecture evidence for humans and AI coding agents.
 
 ## Table of Contents
 
-- [Upgrade notice](#upgrade-notice)
-- [Plain-language summary](#plain-language-summary)
-- [Install](#install)
-- [Quick start](#quick-start)
-- [First-run checklist](#first-run-checklist)
-- [Commands](#commands)
-- [Diagram types](#diagram-types)
-- [AI-focused diagram outputs](#ai-focused-diagram-outputs)
-- [Output formats](#output-formats)
-- [Video and animation prerequisites](#video-and-animation-prerequisites)
-- [Architecture Testing](#architecture-testing)
-- [Documentation](#documentation)
+- [Overview](#overview)
+- [Quick Start](#quick-start)
+- [Architecture Evidence Pack](#architecture-evidence-pack)
+- [Human Workflows](#human-workflows)
+- [AI Agent Workflows](#ai-agent-workflows)
+- [Machine Output Contracts](#machine-output-contracts)
+- [Migration State](#migration-state)
+- [Documentation Index](#documentation-index)
 - [Development](#development)
-- [License](#license)
+- [Distribution](#distribution)
 
-## Upgrade notice
+## Overview
 
-⚠️ `@brainwav/diagram@1.0.0` had a packaging regression and failed at runtime with
-`Cannot find module './utils/commands'`. Please use
-`@brainwav/diagram@1.0.1` or later.
+`archscope` is the canonical CLI identity for the `@brainwav/diagram` package.
+The compatibility command `diagram` remains available during the migration
+window for existing scripts.
 
-## Plain-language summary
+Before you review a PR, run Archscope. Before an AI agent edits a repo, give it
+Archscope evidence.
 
-This tool reads code and draws a map.
-You point it at a repo.
-It scans files.
-It finds links.
-It prints a clear graph.
-You can save that graph.
-You can save PNG or SVG files.
-You can make short video clips.
-You can test code layer rules.
-You can run it on your laptop.
-You can run it in CI.
-The goal is simple: keep the code map clear and keep rule drift low.
+The CLI scans your repository and produces architecture evidence:
 
-## Install
+- A default evidence pack (`scan`) for first-run review and agent handoff
+- PR architecture impact reports (`workflow pr`)
+- AI-context artifacts (`context`)
+- Architecture policy validation (`validate`)
+- Mermaid diagrams (`generate`, `generate-all`), including schema-backed ERD output
 
-```bash
-# Clone and link locally
-git clone https://github.com/jscraik/diagram-cli.git
-cd diagram-cli
-npm install
-npm link
-```
+Default resolution precedence for scan parameters is explicit:
 
-## Quick start
+1. CLI flags
+2. `.diagramrc`
+3. command built-ins
 
-```bash
-# Analyze repository structure
-diagram analyze .
+This applies to `patterns`, `exclude`, `maxFiles`, and `theme` where relevant.
 
-# Generate architecture diagram (default type)
-diagram generate .
-
-# Generate all diagram types into ./diagrams
-diagram all .
-```
-
-## First-run checklist
-
-Use a small test repo first.
-Run from the repo root.
-Start with `diagram analyze .`.
-Read the file and link count.
-Next, run `diagram generate .`.
-Save one file with `--output`.
-Pick `.mmd` for text output.
-Pick `.svg` for image output.
-Use `diagram all .` for all views.
-Use `--max-files` if runs are slow.
-Keep path globs short and clear.
-Skip build and vendored dirs.
-Try `diagram test --init` for rules.
-Then run `diagram test` to check rules.
-Use `--dry-run` when match sets look odd.
-Use `--verbose` if you need more detail.
-Run `npm test` to check local health.
-Run `npm run test:deep` for deep checks.
-
-## Commands
-
-### `diagram analyze [path]`
-
-Analyze file structure and dependencies without rendering a diagram.
+## Quick Start
 
 ```bash
-diagram analyze ./my-project
-diagram analyze . --json
-diagram analyze . --patterns "**/*.py,**/*.go"
-diagram analyze . --max-files 200
-```
-
-Options:
-
-- `-p, --patterns <list>` file patterns (default: `**/*.ts,**/*.tsx,**/*.js,**/*.jsx,**/*.py,**/*.go,**/*.rs`)
-- `-e, --exclude <list>` exclude patterns
-- `-m, --max-files <n>` max files to analyze (default: `100`)
-- `-j, --json` JSON output
-
-### `diagram generate [path]`
-
-Generate one Mermaid diagram and print a preview URL.
-
-```bash
-diagram generate .
-diagram generate . --type sequence
-diagram generate . --focus src/api
-diagram generate . --theme dark
-diagram generate . --output diagram.mmd
-diagram generate . --output diagram.svg
-diagram generate . --open
-```
-
-Options:
-
-- `-t, --type <type>` `architecture|sequence|dependency|class|flow|database|user|events|auth|security` (default: `architecture`)
-- `-f, --focus <module>` focus on one module or directory
-- `-o, --output <file>` write `.mmd`, `.svg`, or `.png`
-- `-m, --max-files <n>` max files to analyze
-- `--theme <theme>` `default|dark|forest|neutral`
-- `--open` open generated preview URL
-
-### `diagram all [path]`
-
-Generate all diagram types in one run.
-
-```bash
-diagram all .
-diagram all . --output-dir ./docs/diagrams
+git clone https://github.com/jscraik/diagram-cli.git
+cd diagram-cli
+npm install
+npm link
 ```
 
-Options:
+After `npm link`, use `archscope ...` for new workflows. Without `npm link`, run
+commands with `node src/diagram.js ...`.
 
-- `-o, --output-dir <dir>` output directory (default: `./diagrams`)
+## Architecture Evidence Pack
 
-### `diagram manifest [path]`
+The default evidence pack gives humans a short architecture brief and gives AI
+coding agents a manifest-first context path.
 
-Summarize the generated `.diagram/manifest.json` artifact.
+Use this path for new repositories:
 
 ```bash
-diagram manifest .
-diagram manifest . --manifest-dir .diagram --output .diagram/manifest-summary.json
-diagram manifest . --manifest-dir .diagram --require-types architecture,security --fail-on-placeholder
+archscope init .
+archscope doctor .
+archscope scan .
 ```
 
-Options:
-
-- `-d, --manifest-dir <dir>` directory containing `manifest.json` (default: `.diagram`)
-- `-o, --output <file>` write summary JSON to file
-- `--require-types <list>` require specific diagram types, comma-separated
-- `--fail-on-placeholder` fail if any diagram entry is a placeholder
+What this gives you:
 
-### `diagram video [path]`
+- `.architecture.yml` starter rules
+- `.diagramrc` defaults
+- CI step sample at `.diagram/ci/github-actions-step.yml`
+- toolchain diagnostics before CI rollout
+- `.diagram/manifest.json` as the stable artifact index
+- `.diagram/brief.md` as the human architecture brief
+- `.diagram/report.html` as the human architecture report
+- `.diagram/agent-context.json` as the canonical agent handoff
+- `.diagram/architecture.mmd` as the first architecture diagram
 
-Generate an animated video (`.mp4`, `.webm`, `.mov`) from a Mermaid diagram.
+For PR review evidence, add git refs:
 
 ```bash
-diagram video .
-diagram video . --type dependency --output architecture.mp4
-diagram video . --duration 8 --fps 60 --width 1920 --height 1080
+archscope scan . --base origin/main --head HEAD
 ```
 
-Options:
-
-- `-t, --type <type>` `architecture|sequence|dependency|class|flow|database|user|events|auth|security` (default: `architecture`)
-- `-o, --output <file>` output file (default: `diagram.mp4`)
-- `-d, --duration <sec>` video duration in seconds (default: `5`)
-- `-f, --fps <n>` frames per second (default: `30`)
-- `--width <n>` output width in pixels (default: `1280`)
-- `--height <n>` output height in pixels (default: `720`)
-- `--theme <theme>` `default|dark|forest|neutral` (default: `dark`)
-- `-m, --max-files <n>` max files to analyze (default: `100`)
+That keeps the same evidence pack and adds `.diagram/pr-impact/pr-impact.json`
+when refs resolve. `.diagram/report.html` is written by default and becomes the
+primary human artifact when report generation succeeds.
 
-### `diagram animate [path]`
-
-Generate an animated SVG with CSS animations.
+## Human Workflows
 
 ```bash
-diagram animate .
-diagram animate . --type sequence --output sequence-animated.svg
-diagram animate . --theme forest
-```
-
-Options:
-
-- `-t, --type <type>` `architecture|sequence|dependency|class|flow|database|user|events|auth|security` (default: `architecture`)
-- `-o, --output <file>` output file (default: `diagram-animated.svg`)
-- `--theme <theme>` `default|dark|forest|neutral` (default: `dark`)
-- `-m, --max-files <n>` max files to analyze (default: `100`)
-
-## Diagram types
-
-| Type | Description | Best for |
-| --- | --- | --- |
-| `architecture` | Component hierarchy by directory | Overall structure |
-| `sequence` | Service or module interactions | API and flow analysis |
-| `dependency` | Internal and external imports | Dependency review |
-| `class` | Class-oriented relationships | OOP-heavy codebases |
-| `flow` | Process/data flow | Control-flow mapping |
-| `database` | Database operations and condition paths | Conditional persistence flows |
-| `user` | User-facing entrypoints and handlers | Interaction flow mapping |
-| `events` | Event streams and async channels | Event-driven architecture |
-| `auth` | Authentication and authorization checks | Credential/identity flow |
-| `security` | Security boundaries and trust paths | Threat/risk analysis |
-
-## AI-focused diagram outputs
-
-For agent workflows, the Mermaid output is especially useful because it is
-compact, textual, and structured. Feeding `.mmd` into an AI at startup lets it
-understand architecture faster than reading all source files.
-
-The generated types cover these high-value areas for automated reasoning:
-
-- **Database Operations** — conditional record paths (for example "record exists?"
-  / "not found" branches), storage and mutation decisions.
-- **User Actions and Interactions** — user entrypoints and downstream handler
-  chains.
-- **Events and Channels** — internal publishers, workers, listeners, and trigger
-  paths.
-- **Authentication Flows** — step-by-step identity and credential checks.
-- **Security and Data Flows** — trust boundaries, sensitive components, and
-  integrations to support security review and compliance context.
-
-When reviewing PRs, run:
-
-```bash
-diagram all . --output-dir .diagram
-```
-
-so `.diagram/` includes the new AI-oriented variants beside the classic ones.
-
-The command also writes `.diagram/manifest.json` summarizing what diagrams were
-produced and whether any outputs are placeholder/no-data (helpful for CI and
-agent bootstrap checks).
-
-## Output formats
+# Analyze repository structure
+archscope analyze .
 
-- Terminal Mermaid output
-- `.mmd` Mermaid source files
-- `.svg`/`.png` rendered images (requires Mermaid CLI)
-- `.mp4`/`.webm`/`.mov` video export (requires Playwright + ffmpeg)
-- Animated `.svg` export (requires Playwright)
-- `.diagram/manifest.json` machine-readable artifact index
+# Generate the default evidence pack
+archscope scan .
 
-Install Mermaid CLI for image export:
+# Generate one diagram and open preview
+archscope generate . --type architecture --open
 
-```bash
-npm install -g @mermaid-js/mermaid-cli
-```
+# Analyze only changed files in your branch
+archscope changed . --base origin/main --head HEAD
 
-## Video and animation prerequisites
-
-Install Playwright browser dependencies:
-
-```bash
-npm install
-npx playwright install chromium
-```
+# Explain a local dependency neighborhood
+archscope explain auth-service .
 
-Install ffmpeg for `diagram video`:
+# PR risk/blast-radius report
+archscope workflow pr . --base origin/main --head HEAD --risk-threshold medium --fail-on-risk
 
-```bash
-brew install ffmpeg
+# PR evidence pack for reviewers and agents
+archscope scan . --base origin/main --head HEAD
 ```
 
-Quick verification:
+Optional advanced media output remains available after the evidence path is
+working:
 
 ```bash
-diagram video . --duration 2 --output smoke-test.mp4
-diagram animate . --output smoke-test-animated.svg
+archscope generate-video .
+archscope generate-animated .
 ```
 
-## Architecture Testing
-
-Validate codebase architecture against declarative YAML rules
-to prevent architectural drift.
-
-### Architecture test quick start
+## AI Agent Workflows
 
 ```bash
-# Generate starter configuration
-diagram test --init
-
-# Run validation
-diagram test
-
-# Preview file matching without validating
-diagram test --dry-run
-
-# CI-friendly output
-diagram test --format junit --output test-results.xml
-```
-
-### Configuration (`.architecture.yml`)
+# Stable machine outputs
+archscope scan . --format json --deterministic
+archscope scan . --base origin/main --head HEAD --format json --deterministic
+archscope generate . --type architecture --format json --deterministic
+archscope workflow pr . --base origin/main --head HEAD --format json --deterministic
 
-```yaml
-version: "1.0"
-
-rules:
-  - name: "Domain isolation"
-    description: "Domain logic should not depend on UI"
-    layer: "src/domain"
-    must_not_import_from: ["src/ui", "src/components"]
-
-  - name: "API contract"
-    description: "API routes only use domain and shared"
-    layer: "src/api"
-    may_import_from: ["src/domain", "src/shared", "src/types"]
-    must_not_import_from: ["src/ui"]
-
-  - name: "Test independence"
-    description: "Tests should not import other tests"
-    layer: "**/*.test.ts"
-    must_not_import_from: ["**/*.test.ts", "**/*.spec.ts"]
+# Canonical agent read order
+cat .diagram/manifest.json
+cat .diagram/brief.md
+cat .diagram/agent-context.json
 ```
 
-### Rule types
+Agents should read `.diagram/manifest.json` first, then consume only artifacts
+whose manifest status is `written`. The standalone `context` command remains
+available for refreshing the older `.diagram/context` pack when existing
+automation depends on it.
 
-| Constraint | Description |
-| --- | --- |
-| `must_not_import_from` | Forbidden import patterns |
-| `may_import_from` | Whitelist of allowed imports |
-| `must_import_from` | Required import patterns |
+## Machine Output Contracts
 
-### Command options
+- Use `--format json` for machine output.
+- `--json` is a compatibility alias and is normalized to `--format json`.
+- Covered command outputs use the canonical machine envelope with `schemaVersion`,
+  `command`, `status`, `meta`, `data`, `errors`, and optional `agentSummary`.
+- Use `--deterministic` for stable ordering/timestamps in machine payloads.
+- JSON-capable command coverage is tracked in
+  `.diagram/contracts/machine-command-coverage.json`.
+- `scan --format json` nests the evidence manifest under `data.evidencePack`
+  and includes `data.pr` when PR refs are supplied.
+- PR impact JSON nests its analytical payload under `data.prImpact` and includes
+  `agentSummary` with:
+  - `changedComponents`
+  - `riskReasons`
+  - `suggestedReviewerChecks`
 
-```bash
-diagram test [path] [options]
-
-Options:
-  -c, --config <file>    Config file (default: ".architecture.yml")
-  -f, --format <format>  Output: console, json, junit
-  -o, --output <file>    Write output to file
-  --dry-run              Preview file matching
-  --verbose              Show detailed output
-  --init                 Generate starter config
-  --force                Overwrite existing config when used with --init
-```
+## Migration State
 
-### Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| 0 | All rules passed |
-| 1 | One or more rules failed |
-| 2 | Configuration error |
-
-### CI Integration
-
-```yaml
-# .github/workflows/architecture.yml
-name: Architecture
-on: [push, pull_request]
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-      - run: npm ci
-      - run: npm test
-      - run: npm run test:deep
-      - run: npm run ci:artifacts
-      - uses: actions/upload-artifact@v4
-        with:
-          name: diagram-ci-artifacts
-          path: .diagram
-      - uses: dorny/test-reporter@v1
-        if: success() || failure()
-        with:
-          name: Architecture Tests
-          path: .diagram/architecture-results.xml
-          reporter: java-junit
-```
+Current migration state: `compatibility`.
 
-## Documentation
+- Canonical command: `archscope`
+- Compatibility command: `diagram`
+- Package name: `@brainwav/diagram`
+- Finalization policy: `.diagram/migration/finalization-policy.json`
+- Release readiness evidence: `.diagram/migration/releases/<releaseId>/migration-readiness.json`
+- Latest readiness pointer: `.diagram/migration/migration-readiness.json`
+- Append-only readiness ledger: `.diagram/migration/releases/ledger.json`
 
-- Getting started: [docs/getting-started.md](docs/getting-started.md)
-- Architecture testing guide: [docs/architecture-testing.md](docs/architecture-testing.md)
-- Migration guide: [docs/migration-from-dependency-cruiser.md](docs/migration-from-dependency-cruiser.md)
-- Contributor guide: [CONTRIBUTING.md](CONTRIBUTING.md)
-- Security policy: [SECURITY.md](SECURITY.md)
-- Support policy: [SUPPORT.md](SUPPORT.md)
-- Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
-- Maintainer docs index: [docs/README.md](docs/README.md)
-- Release history: [CHANGELOG.md](CHANGELOG.md)
+Do not treat the package as renamed or the compatibility command as removable
+until the finalization policy and release evidence prove the required migration
+window. See [Archscope compatibility migration](docs/migration/archscope-compatibility.md).
 
-## Documentation signature
+## Documentation Index
 
-brAInwav - from demo to duty
+- [CLI reference](docs/cli-reference.md)
+- [Getting started](docs/getting-started.md)
+- [Architecture testing](docs/architecture-testing.md)
+- [Archscope compatibility migration](docs/migration/archscope-compatibility.md)
+- [Migration from dependency-cruiser](docs/migration-from-dependency-cruiser.md)
+- [Maintainer docs index](docs/README.md)
 
 ## Development
 
@@ -402,9 +188,16 @@ brAInwav - from demo to duty
 npm install
 npm test
 npm run test:deep
+npm run migration:readiness
 node src/diagram.js --help
 ```
 
 ## License
 
-MIT - see [LICENSE](LICENSE).
+Apache 2.0 - see [LICENSE](LICENSE).
+
+## Distribution
+
+Official installation instructions are maintained in this repository only.
+
+Third-party indexes or mirrors may list this project, but they are not affiliated with, endorsed by, or maintained by this project unless explicitly stated here.

package/package.json

@@ -1,20 +1,37 @@
 {
   "name": "@brainwav/diagram",
-  "version": "1.0.7",
-  "description": "Generate architecture diagrams from codebases",
+  "version": "1.1.0",
+  "packageManager": "npm@10.9.2",
+  "description": "Generate architecture evidence for humans and AI agents",
   "main": "src/diagram.js",
   "bin": {
+    "archscope": "src/diagram.js",
     "diagram": "src/diagram.js"
   },
   "scripts": {
-    "test": "node src/diagram.js analyze .",
+    "test": "mocha",
+    "test:watch": "mocha --watch",
     "test:deep": "node scripts/deep-regression.js",
-    "ci:artifacts": "mkdir -p .diagram && node src/diagram.js all . --output-dir .diagram && node src/diagram.js test . --format junit --output .diagram/architecture-results.xml",
+    "migration:readiness": "node scripts/validate-archscope-readiness.js",
+    "ci:artifacts": "node scripts/assert-ci-artifacts.js",
     "prepublishOnly": "npm test",
     "release:prepare": "bash scripts/release-npm.sh",
     "release:prepare:initial": "bash scripts/release-npm.sh --initial",
     "release:publish": "bash scripts/release-npm.sh --publish",
-    "release:publish:initial": "bash scripts/release-npm.sh --publish --initial"
+    "release:publish:initial": "bash scripts/release-npm.sh --publish --initial",
+    "harness": "echo 'Harness command is disabled in this repo. Run: npm run harness:check' >&2 && exit 1",
+    "harness:pr-gates": "bash scripts/harness-pr-gates.sh",
+    "prepare": "simple-git-hooks",
+    "harness:check": "bash scripts/harness-check.sh",
+    "lint": "echo 'No linter configured (plain JS project)' && exit 0",
+    "typecheck": "echo 'No TypeScript configured (plain JS project)' && exit 0",
+    "audit": "npm audit --audit-level=high",
+    "check": "npm test",
+    "secrets:staged": "bash scripts/check-staged-secrets.sh",
+    "docs:lint": "echo 'No docs linter configured (plain JS project)' && exit 0",
+    "docs:style:changed": "bash scripts/check-doc-style.sh",
+    "test:related": "bash scripts/check-related-tests.sh",
+    "semgrep:changed": "bash scripts/check-semgrep-changed.sh"
   },
   "keywords": [
     "diagrams",
@@ -24,15 +41,14 @@
     "cli"
   ],
   "author": "",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "dependencies": {
     "chalk": "^4.1.2",
-    "cli-table3": "^0.6.5",
-    "commander": "^12.0.0",
+    "commander": "^14.0.3",
     "glob": "^10.0.0",
     "picomatch": "^4.0.3",
-    "yaml": "^2.8.2",
-    "zod": "^4.3.6"
+    "yaml": "^2.8.4",
+    "zod": "^4.4.3"
   },
   "repository": {
     "type": "git",
@@ -47,14 +63,31 @@
     "registry": "https://registry.npmjs.org/"
   },
   "files": [
-    "src/diagram.js",
-    "src/video.js",
-    "src/utils/commands.js",
+    ".diagram/contracts/**/*.json",
+    ".diagram/migration/finalization-policy.json",
+    ".diagram/migration/migration-readiness.json",
+    ".diagram/migration/releases/**/*.json",
+    "src/**/*.js",
     "README.md",
     "scripts/refresh-diagram-context.sh",
     "LICENSE"
   ],
   "engines": {
     "node": ">=18"
+  },
+  "devDependencies": {
+    "chai": "^4.5.0",
+    "mocha": "^11.3.0",
+    "simple-git-hooks": "^2.13.1"
+  },
+  "overrides": {
+    "chai": "^4.5.0",
+    "serialize-javascript": "^7.0.0",
+    "diff": "^8.0.3"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "make hooks-pre-commit",
+    "commit-msg": "node scripts/validate-commit-msg.js $1",
+    "pre-push": "make hooks-pre-push"
   }
 }