17 added, 16 removed. Audit A to A.
---
name: arclux
description: Use ARCLUX's CLI to understand codebase structure, check impact before editing, and catch structural issues (circular dependencies, dead code, ambiguous symbols) before shipping changes in this repository.
---
# ARCLUX
- This repository ships its own codebase intelligence CLI (`arclux`). Use it instead of guessing about dependency structure, blast radius, or code health from reading files alone.
+ This repository ships its own codebase intelligence CLI (arclux). Use it instead of guessing about dependency structure, blast radius, or code health from reading files alone.
## When to use which command
- **Before editing a file** -- check what depends on it, so you know the blast radius before you touch it:
+ Before editing a file -- check what depends on it, so you know the blast radius before you touch it:
```bash
npx tsx apps/cli/index.ts impact <path/to/file>
```
- **After editing files** -- check for new structural issues introduced by the change:
+ After editing files -- check for new structural issues introduced by the change:
```bash
npx tsx apps/cli/index.ts diagnose [path]
```
- Reports circular dependencies, dead code, and ambiguous symbol resolution, each with impact context (how many files are affected) and a fix suggestion. Defaults to the current directory if `path` is omitted.
+ Reports circular dependencies, dead code, and ambiguous symbol resolution, each with impact context (how many files are affected) and a fix suggestion. Defaults to the current directory if path is omitted.
- **Before opening a PR or finishing a task** -- run the full detector suite for a single PASS/FAIL verdict:
+ Before opening a PR or finishing a task -- run the full detector suite for a single PASS/FAIL verdict:
```bash
npx tsx apps/cli/index.ts verify [path]
```
- **Applying a change programmatically** (not manual file edits) -- go through the Change Pipeline instead of writing the file directly, so writes are transactional and recoverable on crash:
+ Applying a change programmatically (not manual file edits) -- go through the Change Pipeline instead of writing the file directly, so writes are transactional and recoverable on crash:
```bash
- npx tsx apps/cli/index.ts work <file> <newContentFile>
+ npx tsx apps/cli/commands/work.ts <file> <newContentFile>
```
- **Understanding a file or module before working on it:**
+ Understanding a file or module before working on it:
```bash
npx tsx apps/cli/index.ts graph [path] # dependency graph, prints or saves JSON
npx tsx apps/cli/index.ts language <file> # exports/imports/calls for a single file
npx tsx apps/cli/index.ts analyze [path] # full parse + index + graph build
```
- **Comparing two states** (e.g. before/after a refactor, or two git refs):
+ Comparing two states (e.g. before/after a refactor, or two git refs):
```bash
- npx tsx apps/cli/index.ts diff <ref1> <ref2>
+ npx tsx apps/cli/index.ts diff <refA> <refB> [repoPath]
```
- ## Environment gotchas (see progres/gotchas.md for the full list)
+ ## Environment gotchas (see progres/gotchas.md and progres/bugs.md for the full list)
- - Running on Termux (Android) arm64: `apps/web` uses Webpack, not Turbopack -- don't add `--turbo` to dev scripts.
- - Large repos (1000+ files) may need `NODE_OPTIONS="--max-old-space-size=4096"` for `diagnose` and similar commands.
- - Python parsing depends on `tree-sitter-wasms`; do not reintroduce `require.resolve()` for locating the `.wasm` file inside `packages/parser/python/parsePython.ts` -- this has regressed multiple times (see `progres/bugs.md`, entries tagged "Python WASM path").
+ - Running on Termux (Android) arm64: apps/web uses Webpack, not Turbopack -- don't add --turbo to dev scripts.
+ - diagnose previously crashed with heap-out-of-memory on large repos (~1000 modules); root cause was fixed in packages/diagnostics/ErrorContext.ts (getImpactCount() replaced retaining full impact trees for every finding). Should no longer need NODE_OPTIONS=--max-old-space-size for typical repos -- if it still OOMs, that's a regression worth reporting, not an expected workaround.
+ - Python parsing depends on tree-sitter-wasms; do NOT reintroduce require.resolve() for locating the .wasm file inside packages/parser/python/parsePython.ts -- this has regressed 3 times already (progres/bugs.md, most recently 2026-08-15). Always walk up from process.cwd() instead.
## Don't
- - Don't hand-edit `progres/PROGRES-*.md` files -- use `scripts/log-progress.sh` (see `TOOLING.md`).
- - Don't add a new top-level intelligence/search/RAG capability inside `packages/engine`, `packages/graph`, or `packages/detectors` -- see `ARCHITECTURE_MAP.md`'s "Where intelligence layers go" section. New capabilities in that direction belong in a new top-level package consuming ARCLUX's stable outputs, not woven into core.
+ - Don't hand-edit progres/PROGRES-*.md files -- use scripts/log-progress.sh (see TOOLING.md).
+ - Don't add a new top-level intelligence/search/RAG capability inside packages/engine, packages/graph, or packages/detectors -- see ARCHITECTURE_MAP.md's "Where intelligence layers go" section. New capabilities in that direction belong in a new top-level package consuming ARCLUX's stable outputs, not woven into core.
+ - Don't assume ARCLUX.main and main are the same branch -- they have diverged before. Always git pull origin ARCLUX.main.