devLap

ARCLUX 🦖 —a codebase intelligence tools

typescript dev.to

Documentation

OPEN SOURCE
official documentation
content, searchable and organized

Install (from source)

Installation via npm is deprecated. Use one of the recommended methods below.

Not yet published to npm. Clone and build locally:

git clone https://github.com/GSF-001/ARCLUX.git
cd ARCLUX
pnpm install
Enter fullscreen mode Exit fullscreen mode

Web dashboard: 

cd apps/web
pnpm run dev
Enter fullscreen mode Exit fullscreen mode

If you've ever stared at a 15,000-file monorepo wondering "what actually breaks if I touch this file," you know the feeling: you either click through imports by hand, or you trust a tool that's quietly guessing.

ARCLUX is my answer to that — a dependency graph, impact analysis, and security analysis tool, CLI + web dashboard, built on one non-negotiable rule: every fact it reports has to trace back to real parsed code. An import statement. An export declaration. A resolved path. Not a probability. Not an embedding similarity score. A fact.

Why deterministic, on purpose

There's a wave of AI-powered "codebase intelligence" tools right now — semantic search, RAG over your repo, agents that summarize what a function does. Those are legitimate, useful tools solving a real problem.

ARCLUX solves a different one: can a machine tell you, with zero ambiguity, exactly how your code is structurally connected — and where it's structurally risky? No LLM in the loop, no "probably." Just parse → index → graph → impact → detect, every step traceable and reproducible.

repository -> parser -> graph -> detectors -> engine -> report
                          |
                          -> rules (framework conventions)
                          -> impact (consumer/dependent tracing)
                          -> security-analysis (secrets, unsafe patterns, attack surface)
Enter fullscreen mode Exit fullscreen mode

How it actually traces impact


This is the core of "what breaks if I touch this file." No heuristics, no scoring — just a breadth-first walk over the real dependency graph, starting from whoever directly imports the module and expanding outward until every transitive consumer is accounted for.

export function traceConsumers(repository: Repository, moduleId: string): ConsumerTraceResult {
  const startModule = repository.getModule(moduleId);
  if (!startModule) {
    return { direct: [], transitive: [], notFound: true };
  }

  const direct = [...startModule.importedBy];
  const visited = new Set<string>([moduleId]);
  const transitive: string[] = [];
  const queue = [...direct];

  while (queue.length > 0) {
    const current = queue.shift()!;
    if (visited.has(current)) continue;
    visited.add(current);
    transitive.push(current);

    const module = repository.getModule(current);
    if (!module) continue;

    for (const consumer of module.importedBy) {
      if (!visited.has(consumer)) queue.push(consumer);
    }
  }

  return { direct, transitive, notFound: false };
}
Enter fullscreen mode Exit fullscreen mode

direct is everyone who imports the file right now. transitive is everyone downstream of those, walked out through the whole graph. Nothing here is inferred — every name in that result list is a file that will genuinely need attention if you change the module.

New: security analysis, built on the same graph

The newest layer walks the same dependency graph to answer a different question: not "what breaks," but "what's exposed." It runs entirely against code you already have on disk — no LLM, no network calls, same deterministic philosophy as the rest of ARCLUX.

Running it against ARCLUX's own codebase surfaced real findings on the first try:

$arclux security .

Security summary: 46 findings (0 critical, 34 high, 5 medium, 7 low)
Attack surface: 392 entry point(s), 749 reachable / 10 unreachable modules
  [high] shell-exec — packages/runtime/ProcessManager.ts:58 — Shell command execution
  [high] dangerously-set-innerhtml — ...tsx — React dangerouslySetInnerHTML (XSS sink)
  [medium] weak-crypto-md5 — ... — MD5 usage (weak hash)
  [low] unpinned-dependency — manifest — Runtime dependency "..." is not pinned to an exact version
Enter fullscreen mode Exit fullscreen mode

What makes this different from a plain grep for eval( or exec( is the attack surface map underneath it: ARCLUX does a BFS from every real entry point (convention-detected routes, structurally-orphaned modules with no importers, explicit config) along the actual import graph, so every finding comes with a real answer to "is this code even reachable from the outside, and via what path" — not just "this pattern exists somewhere in the repo."

export function mapAttackSurface(repository: Repository, graph: DependencyGraph): AttackSurfaceMap {
  const entryPoints = [...conventionEntries, ...structuralEntries, ...explicitEntries];
  const { reachable, distance, parent } = bfs(adjacency, entryPoints, maxDepth);
  // every module in the repo gets tagged: reachable or not, and if so, how far and via which path
}
Enter fullscreen mode Exit fullscreen mode

A bug class most tools miss

One of ARCLUX's structural detectors looks for ambiguous symbol resolution — the same exported name defined in more than one place in your repo. It sounds like a minor annoyance until you realize what it actually causes: any tool (including AI coding assistants) that resolves "give me the definition of X" has to pick one, silently, with no principled criterion. Pick wrong, and you get confidently incorrect answers.

The detector's severity model reflects that directly: a collision is flagged high only when a real source definition has a shadow sitting in a test, example, fixture, mock, or script folder — because that's exactly the shape of bug where tooling picks the wrong file confidently. Two definitions both legitimately in source paths get medium. Everything else is low.

What it actually does today

  • Dependency graph — imports, exports, folders, built from static analysis, not guesses
  • Impact analysis — "what's affected if I change file X," traced through the real graph, not a heuristic
  • Security analysis — secret exposure, unsafe patterns, weak crypto, trust-boundary violations, and attack-surface mapping, all against code you already have locally
  • 18+ structural detectors — circular dependencies, dead code, unused exports, duplicate modules, orphan files, ambiguous symbol resolution, and more
  • TypeScript, JavaScript, and Python parsing today, with Go, Rust, Java, C#, C++, PHP, and Ruby parsers in progress
  • CLI + web dashboard + daemon — a background watcher that re-analyzes on file change and streams results over SSE, so an editor extension can stay live-updated

Open source, actively worked on, honestly alpha

ARCLUX is Apache 2.0, and it's genuinely still alpha — expect stubs, expect rough edges, expect things marked "not yet built" in the project's own progress notes rather than silently pretended to work.

If deterministic, verifiable codebase analysis is a problem space you care about, I'd love more eyes on it — issues, PRs, or just poking around and telling me what's missing.

🔗 github.com/GSF-001/ARCLUX

Source: dev.to

arrow_back Back to Tutorials