Tauta

Tauta is a local-first dependency analysis CLI for JavaScript and TypeScript projects. It scans a project on your machine, builds an internal dependency graph, and opens an interactive explorer that helps developers decide what to review, refactor, test, or clean up next.

This package is designed as a decision-support tool, not as a raw metric board. The intended user questions are:

• What is happening in this file or module?
• Why should I care?
• If I change it, what should I review or test next?

Package

npm package: @ramaaudra/tauta
CLI binary : tauta

Use tauta for npm package usage. The current npm package binary map does not install a code-mapper command.

Quick Start

Run Tauta without installing it globally:

pnpm dlx @ramaaudra/tauta@latest analyze . --open

Equivalent npm commands:

npx @ramaaudra/tauta@latest analyze . --open
npm exec --package=@ramaaudra/tauta@latest -- tauta analyze . --open

Or install the CLI globally:

npm install -g @ramaaudra/tauta
tauta analyze . --open

Run the command from the project, package, app, frontend, or backend directory you want to analyze. Do not run it from a detected workspace monorepo root; Tauta blocks common workspace-root setups and asks you to choose a concrete workspace instead.

The analyze command starts a local web explorer. If you do not pass --open, copy the printed http://localhost:<port> URL into your browser.

Requirements

• Node.js 20 or newer is recommended.
• The target project should contain JavaScript or TypeScript source files.
• tsconfig.json, tsconfig.app.json, or jsconfig.json is recommended when the project uses path aliases.
• Git history is optional, but required for churn and hotspot signals.

Commands

Analyze A Project

tauta analyze <directory>

Examples:

tauta analyze . --open
tauta analyze . --no-confirm
tauta analyze . --port 2633
tauta analyze . --include "src/**/*.ts,src/**/*.tsx"
tauta analyze . --exclude "**/*.test.ts,**/generated/**"
tauta analyze . --verbose

Useful options:

| Option | Purpose | | ---------------------- | ------------------------------------------------------------------------------- | | --open | Open the browser automatically after analysis starts. | | --no-confirm | Skip the interactive project summary confirmation. | | -p, --port <port> | Preferred local server port. Tauta scans for the next available port if needed. | | --include <patterns> | Comma-separated glob patterns for files to include. | | --exclude <patterns> | Comma-separated glob patterns for files to exclude. | | --verbose | Print additional technical diagnostics. | | --build-path <path> | Use a custom frontend build directory when running from a source checkout. |

The CLI help currently exposes --tsconfig <path>, but analysis still relies on automatic config discovery. Prefer placing the relevant TypeScript or JavaScript config in the target project root.

Generate A Standalone HTML Report

tauta generate-report <directory> --output ./tauta-report.html

Examples:

tauta generate-report . --output ./tauta-report.html
tauta generate-report . --include "src/**/*.ts,src/**/*.tsx" --exclude "**/*.test.ts"

The report is a single HTML file that can be shared without running the local server. It preserves substantial interactive exploration behavior, but some live-only capabilities are reduced because the report has no backend process behind it.

Recommended Workflow

1. Run tauta analyze . --open from the specific project or package directory.
2. Start from the recommended review queue or actionable insight area.
3. Open the file, module, cycle, or architecture view that explains the signal.
4. Check the "why it matters" evidence before changing code.
5. Use the suggested review or testing scope when touching risky files.
6. Export a report when the findings need to be shared or archived.

The intended outcome is a decision, not just a number. A good Tauta session should help answer questions like:

• Which file should I review first?
• Which module is structurally sensitive?
• Which cycle blocks a broader refactor?
• Which cleanup candidate needs manual validation?
• Which changed area deserves wider tests?

What Tauta Analyzes

Tauta currently supports:

• .js, .jsx, .ts, and .tsx source files;
• static import and export relationships between internal project files;
• path resolution through common TypeScript and JavaScript config behavior;
• file-level and module-level dependency graphs;
• circular dependency detection;
• orphan candidate detection through reachability from detected entry points;
• structural metrics such as afferent coupling, efferent coupling, instability, and propagation risk;
• Git-based churn and hotspot signals when Git history is available;
• conservative connascence-style coordination signals for selected typed contracts and positional call patterns;
• dependency path tracing;
• live file removal impact exploration;
• unresolved import and unsupported file warnings;
• standalone interactive HTML report export.

External packages are not modeled as first-class graph nodes. Tauta focuses on the internal dependency structure of the selected project directory.

How To Read Key Signals

Afferent Coupling, Or Ca

Ca means "how many internal files depend on this file." A high value usually means the file is shared. Changing it may require broader review because more files can be affected.

Efferent Coupling, Or Ce

Ce means "how many internal files this file depends on." A high value can mean the file coordinates many dependencies or sits near an integration point.

Instability

Instability is calculated as:

I = Ce / (Ca + Ce)

In Tauta, this describes structural position. It should not be read as a defect score by itself.

Propagation Risk

Propagation Risk is a derived review heuristic based on:

Propagation Risk = Ca * Instability

Cycle members are elevated because changes in a cycle can feed back through the same dependency chain. Treat the band as review guidance, not as proof that the file is broken.

Hotspots

Hotspot signals combine recent Git churn with structural risk. A hotspot means "this area changed recently and is structurally sensitive." It is useful for review prioritization, but it is not a direct bug predictor.

Circular Dependencies

Circular dependencies are detected from the internal dependency graph. They are important because a change can loop back through the same dependency chain, making refactors harder to reason about.

Orphan Candidates

Orphan detection uses reachability from detected entry points. Treat an orphan as a cleanup candidate that needs validation, not as guaranteed dead code.

Connascence Signals

Connascence signals highlight coordination risk, such as fragile positional APIs or shared typed contracts. They are additive review guidance, not a global quality score.

Analysis Scope And Limitations

• Analyze a specific project directory, package, app, frontend, or backend.
• Do not point Tauta at a detected workspace monorepo root. The CLI blocks common workspace-root setups and asks you to choose a specific package instead.
• Keep path aliases in tsconfig.json, tsconfig.app.json, or jsconfig.json accurate for better import resolution.
• Config discovery is automatic in the current analysis pipeline. Prefer placing the relevant TypeScript or JavaScript config in the project root.
• Unsupported files are skipped and reported in warnings.
• Dynamic runtime behavior, framework-specific route loading, reflection, and non-JS/TS assets are outside the current dependency graph scope.
• External packages are not represented as first-class graph nodes.
• Git-based churn and hotspot data require local Git history.
• Live mode and report mode are close, but not identical. Source viewing and backend-dependent interactions are reduced or unavailable in the static report.
• Metric bands are product heuristics for review prioritization. They are not universal scientific thresholds.

Troubleshooting

Unresolved Imports

If Tauta reports unresolved imports:

• check path aliases in tsconfig.json, tsconfig.app.json, or jsconfig.json;
• make sure the command is run from the actual project directory;
• narrow or correct custom --include and --exclude patterns;
• open the Setup Guide in the UI for project-specific guidance.

Monorepo Root Blocked

Tauta intentionally blocks automatic analysis from detected workspace monorepo roots. Move into the specific package or app first:

cd apps/web
pnpm dlx @ramaaudra/tauta@latest analyze . --open

Port Already In Use

Choose another preferred port:

tauta analyze . --port 2640

If that port is also busy, Tauta will try the next available port within its scan range.

Unsupported Files Were Skipped

The analyzer currently supports JavaScript and TypeScript source files. If warnings mention unsupported extensions, narrow the include pattern:

tauta analyze . --include "src/**/*.js,src/**/*.jsx,src/**/*.ts,src/**/*.tsx"

Hotspot Data Looks Empty

Hotspot data depends on local Git history. If the target directory has no Git history, or the relevant files have no recent changes in the analyzed windows, hotspot signals may stay low or empty.

Local Development UI Bundle Missing

When running from a source checkout, the backend needs a built frontend UI. Build from the repository root:

pnpm --dir code-mapper-frontend build
pnpm --dir code-mapper-backend build

You can also point the server to a custom UI build:

tauta analyze . --build-path /absolute/path/to/frontend/dist

Local Development

From the repository root:

pnpm --dir code-mapper-backend install
pnpm --dir code-mapper-frontend install
pnpm --dir code-mapper-backend build
pnpm --dir code-mapper-backend test
pnpm --dir code-mapper-backend format

Useful backend scripts:

| Script | Purpose | | -------------- | ----------------------------------------------------------------------------------- | | pnpm dev | Run the backend server with hot reload. | | pnpm cli:dev | Run the TypeScript CLI entrypoint directly. | | pnpm build | Build frontend assets, report assets, backend TypeScript, and bundled public files. | | pnpm test | Run backend Node test files. | | pnpm lint | Run oxlint. | | pnpm format | Run formatter and lint auto-fixes. |

License

MIT