# ArcSight [![npm downloads](https://img.shields.io/npm/dm/arcsight.svg)](https://www.npmjs.com/package/arcsight) Deterministic architectural analysis for codebases. **Free:** Architecture monitoring for every developer — `arc scan`, `arc analyze`, `arc watch`, hotspots, and issue explanations. **Pro:** Cursor-ready architectural fixes and advanced workflows — `[c]` / `arc finish --copy` handoff, deep impact, and team workflows. ArcSight analyzes your codebase and shows architecture health, risky modules, what to fix first, and how to refactor safely. --- ## Quick Start Run instantly: ```bash npx arcsight analyze ``` Or install globally: ```bash npm install -g arcsight arc analyze ``` Example commands: ```bash arc scan arc analyze arc hotspots arc explain arc impact arc doctor ``` Example output: ``` Architecture Score: 84/100 (B) Issues detected: 2 dependency cycles, 3 high fan-in modules, 1 duplicate source of truth Suggested next steps: arc hotspots · arc impact src/cli.ts ``` Then try `arc hotspots` and `arc impact src/cli.ts`. Optional: `arc graph` (Enterprise) for visualization. **Modules** are usually source files in your repo (e.g. `src/api.ts`, `src/commands/registry.ts`). Examples: ```bash arc impact src/cli.ts arc impact src/commands/registry.ts ``` Requires Node.js 18+. No configuration required. See [Getting Started](docs/GETTING-STARTED.md) for the full workflow. **Coverage:** See [Known Capabilities & Limits](docs/KNOWN-CAPABILITIES-AND-LIMITS.md) for supported stacks, unsupported languages, and trust guarantees. For reporting misses on supported code, see [Known limitations](docs/KNOWN-LIMITATIONS.md). --- ## Telemetry ArcSight collects **anonymous usage metrics** to help improve the tool. **What we collect:** command usage, CLI version, operating system, repository size bucket (e.g. tiny / small / medium / large). No exact file counts. **What we do NOT collect:** source code, file paths, repository contents, personal data. Telemetry is **anonymous**, **optional**, and **automatically disabled in CI**. Disable anytime: ```bash arc telemetry disable ``` Full details: [docs/TELEMETRY.md](docs/TELEMETRY.md). --- ## Run in your repository ```bash cd my-project arc scan arc analyze ``` --- ## Example output After `arc analyze`, you'll see a health report like: ``` Architecture Score: 84/100 (B) Issues detected: • 2 dependency cycles • 3 high fan-in modules • 1 duplicate source of truth Suggested next steps: • arc hotspots • arc impact src/cli.ts ``` --- ## Example analysis Example: analyzing **stripe-node**: - **Files analyzed:** 420 - **Modules discovered:** 420 - **Architecture Score:** 87/100 **Top hotspots:** `requestHandler`, `stripeClient`, `retryManager` Run `arc scan` then `arc analyze` in any repository to get a similar report. --- ## Command reference | Command | Description | Tier | |---------|-------------|------| | `arc scan` | Discover repository architecture and run invariants | Free | | `arc analyze` | Architecture health and issue detection | Free | | `arc hotspots` | High fan-in modules (architectural hotspots) | Free | | `arc impact ` | Blast radius for a module (e.g. `arc impact src/cli.ts`) | Free | | `arc why ` | Understand why dependencies exist and trace dependency paths | Free | | `arc share` | Generate a shareable architecture summary for Slack, PRs, or issues | Free | | `arc prioritize` | Rank issues by impact; what to fix first | Pro | | `arc graph` | Visualize dependency graph | Enterprise | | `arc guard` | CI architecture guard (invariants) | Team | **arc share** — Generate a concise, shareable architecture summary from existing analysis (no re-run). Use in Slack, pull requests, or GitHub issues. Examples: ```bash arc share arc share --summary arc share --copy ``` **arc why** — Understand why dependencies exist in your architecture and trace the paths that create them. Three modes: `arc why `, `arc why `, or `arc why `. Examples: ```bash arc why payments arc why src/payments/service.ts arc why auth payments ``` Example output (dependency paths): ``` Why does the architecture depend on "payments"? Direct dependents: billing checkout notifications Dependency paths: auth → billing → payments orders → checkout → payments notifications → payments Total dependency paths: 6 Showing shortest 3 paths. ``` Run `arc --help` for the full list and tier groupings. --- ## Typical Workflow ```bash arc scan arc analyze arc explain src/cli.ts arc why payments arc why src/payments/service.ts arc why auth payments arc impact src/cli.ts arc prioritize arc guard ``` 1. **scan** — Discover repository architecture and run invariant checks 2. **analyze** — Run architecture analysis and issue detection 3. **explain** — Understand why a module is architecturally risky 4. **why** — Understand why dependencies exist and trace the paths that create them 5. **impact** — Simulate change blast radius 6. **prioritize** — Find the most impactful improvements (Pro) 7. **guard** — Protect architecture in CI (Team) --- ## Feature Tiers Tiers are defined in `src/config/tiers.ts`. Run `arc --help` to see commands grouped by tier. | Tier | Price | Commands (examples) | |------|-------|----------------------| | **Free** | $0 / month | scan, analyze, explain, impact, hotspots, map, investigate | | **Pro** | $49 / developer / month | prioritize, suggest, plan, simulate, fix, blast, risk, refactor | | **Team** | $79 / developer / month | guard, drift, report, score, pr-risk | | **Enterprise** | Custom | verify, audit, ownership, graph | See [docs/tiers.md](docs/tiers.md) and [docs/pricing.md](docs/pricing.md) for the full pricing model. --- ## Upgrade Pro, Team, and Enterprise commands show an upgrade prompt when used without a valid license. **https://convergence.dev/pricing** --- ## Demo From a clone of this repository: ```bash git clone https://github.com/arcsight-ai/arcsight.git cd arcsight bash demo/run-demo.sh ``` Output goes to `demo/output/`; summary in [demo/DEMO.md](demo/DEMO.md). --- ## Links [npm](https://www.npmjs.com/package/arcsight) · [License](LICENSE) · [Feedback](https://github.com/arcsight-ai/arcsight/issues) --- ## Maintainer Release ```bash npm login npm publish --access public ``` ## Legacy Package Deprecation (Do Not Unpublish) ```bash npm deprecate @arcsight-ai/convergence "ArcSight has moved. Install using: npm install -g arcsight" npm deprecate @arcsight-ai/cli "Deprecated. Install ArcSight CLI using: npm install -g arcsight" npm deprecate @arcsight-ai/wedge "Deprecated. Install ArcSight CLI using: npm install -g arcsight" npm deprecate @arcsight-ai/anchr "Deprecated. Install ArcSight CLI using: npm install -g arcsight" ```