@arch-atlas/core

AST scanner and architecture graph engine for Arch Atlas.

Version: 0.1.8

Most users should install the CLI:

npm install -D arch-atlas
npx arch-atlas

Use this package directly when you want to embed scanning in a custom tool, script, or CI helper without the web UI.

Install

npm install @arch-atlas/core

Requires Node.js >= 18.

Quick start

import { scanProject, getImpactTree, analyzePackageBoundaries } from '@arch-atlas/core';

const graph = await scanProject(
  { root: '/path/to/project' },
  (progress) => console.log(progress.message),
);

console.log(graph.stats);
console.log(graph.deadCode[0]?.explanation); // why unused
console.log(graph.packageBoundaries.deepImports);

const impact = getImpactTree(graph, graph.files[0].id, 3);

Main exports

| API | Purpose | |-----|---------| | scanProject(options, onProgress?) | Full scan → ArchitectureGraph | | discoverProject(root) | Project type, entries, aliases, workspaces | | detectDeadCode(files, entries, type?) | Unused files with explanation.checks | | getDependencyTree(graph, fileId, depth?) | Forward import tree | | getImpactTree(graph, fileId, depth?) | Reverse dependents (“what breaks?”) | | analyzePackageBoundaries(files) | Cross-package / deep-import report | | detectCircularDependencies(files, edges) | Cycle list | | loadIgnoreMatcher(root) | Defaults + .arch-atlasignore |

The graph includes nodes, edges, files, deadCode, circularDependencies, packageBoundaries, packages, routes, folders, searchIndex, and config.

Dead-code explanations

Each DeadCodeItem includes:

explanation: {
  summary: string;
  importerPaths: string[];
  checks: Array<{
    id: 'entry' | 'framework-route' | 'reachable' | 'importers' | 'platform-sibling';
    label: string;
    ok: boolean;
    detail?: string;
  }>;
}

Runtime reachability ignores import type / export type. Platform siblings (.ios, .android, …) stay live when the base module is reachable.

Accuracy notes (v0.1.8)

• Entries from package.json main / react-native / module, Expo entryPoint, app.config.*, Next middleware
• React.lazy(() => import('…')) and require.context('…') when the argument is a string literal
• Barrel re-exports (export … from) count toward reachability
• Type-only imports do not create runtime graph edges

Fixtures & tests

npm run test -w @arch-atlas/core

Fixtures live under packages/core/fixtures/ (Expo Router, Next.js, RN CLI, monorepo).

Related packages

• arch-atlas — CLI
• @arch-atlas/server — local API + UI host

License

MIT