Immutable. This exact content is served forever at /api/v1/blob/62ec6b584efa7f20.
--- 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. ## When to use which command 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: ```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. 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: ```bash npx tsx apps/cli/commands/work.ts <file> <newContentFile> ``` 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): ```bash npx tsx apps/cli/index.ts diff <refA> <refB> [repoPath] ``` ## 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. - 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 assume ARCLUX.main and main are the same branch -- they have diverged before. Always git pull origin ARCLUX.main.