Tauta

Tauta is a local-first dependency analysis tool for JavaScript and TypeScript codebases. It combines a CLI, a backend analysis engine, a local web explorer, and a standalone HTML report so developers can understand dependency structure without sending code to a remote service.

The product goal is decision support, not raw metric display. A useful Tauta session should help answer three practical questions:

• 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 command: tauta
• Package source: code-mapper-backend/
• npm-facing README: code-mapper-backend/README.md

The current npm package installs the tauta binary. Use tauta for package usage.

Run the published package without installing it globally:

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

Or using npx:

npx @ramaaudra/tauta@latest analyze . --open

Or install the CLI globally:

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

Use this from a specific project, package, app, frontend, or backend directory. Do not run Tauta from a detected workspace monorepo root; the CLI blocks common workspace-root setups and asks you to analyze a concrete workspace instead.

Why This Exists

Dependency graphs and architecture metrics can be correct but still hard to act on. Tauta is built around review and refactoring decisions such as:

• Which area should I review first?
• Is this file safe to refactor?
• Will this change spread into shared code?
• Does this area need broader testing?
• Which circular dependency should I break first?
• Which cleanup candidate needs manual validation?

Metric labels, risk bands, and hotspot rankings are review heuristics. They are useful triage signals, not universal scientific defect predictions.

What Tauta Does

Current capabilities include:

• static dependency analysis for internal .ts, .tsx, .js, and .jsx files;
• import resolution with common TypeScript and JavaScript config behavior, including path aliases;
• file-level and module-level dependency graph exploration;
• circular dependency detection and a dedicated cycle triage workspace;
• orphan candidate detection based on reachability from detected entry points;
• file-level and folder-level architecture metrics;
• Git-based churn analysis and hotspot ranking when local Git history is available;
• conservative connascence-style coordination signals for selected typed contracts and positional APIs;
• dependency path tracing;
• live file removal impact exploration;
• setup guidance for unresolved imports and analysis-quality warnings;
• an in-app metrics guide that explains interpretation and caveats;
• standalone interactive HTML report export.

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

Product Surfaces

Overview

The overview is the main decision surface. It starts with a prioritized review queue, then shows supporting context such as shared spread risk, recent change pressure, cleanup candidates, and coupling distribution.

Graph

The graph supports both file view and module view. It helps users move from repository-level structure into a concrete file or module that needs review.

Architecture

The architecture view summarizes folder and file metrics such as coupling, instability, propagation risk, and shared impact so users can identify foundational or risky areas.

Cycle Triage

The cycle triage workspace compares circular dependencies and helps decide which loop to inspect or break first.

Metrics Guide

The metrics guide explains what each metric means, what it does not mean, and how to use it for practical review or refactoring decisions.

Analysis Setup

The setup guide helps diagnose unresolved imports, alias configuration issues, unsupported files, and other analysis-quality problems instead of silently accepting incomplete data.

Static Report

Tauta can generate a standalone HTML report that preserves substantial interactive exploration behavior. Some live-only features are reduced in report mode because there is no backend process behind the exported file.

Repository Layout

.
├── code-mapper-backend/   # npm package, CLI, analyzer, HTTP API, report generation
├── code-mapper-frontend/  # React/Vite explorer and report UI
├── sample-project/        # intentionally problematic demo project
├── docs/                  # product and engineering notes
└── docs-skripsi/          # thesis context and academic support material

Local Development

Prerequisites

• Node.js 20 or newer is recommended.
• pnpm is used for this repository.

This repository is not configured as one root pnpm workspace. Install dependencies inside each project directory.

Install Dependencies

pnpm --dir code-mapper-backend install
pnpm --dir code-mapper-frontend install
pnpm --dir sample-project install

Build From Source

The backend build script builds the frontend app, builds the report bundle, compiles the backend, and syncs frontend assets into code-mapper-backend/dist.

pnpm --dir code-mapper-backend build

For frontend-only iteration, build the explorer or report bundle directly:

pnpm --dir code-mapper-frontend build
pnpm --dir code-mapper-frontend build:report

Run The Live Explorer From Source

pnpm --dir code-mapper-backend cli:dev analyze ../sample-project --no-confirm --open

By default, Tauta starts a local explorer on port 2633 and moves to the next available port if needed.

When using pnpm --dir code-mapper-backend cli:dev, paths are resolved from code-mapper-backend/. Use ../sample-project, ../code-mapper-frontend, or . for the backend package itself. Do not point the CLI at this repository root.

Generate A Standalone Report From Source

pnpm --dir code-mapper-frontend build:report
pnpm --dir code-mapper-backend cli:dev generate-report ../sample-project --output ./tauta-report.html

If the report UI source changes, rebuild the report bundle before exporting again. The backend report generator checks bundle freshness and fails when the report bundle is stale.

Common Commands

Backend

pnpm --dir code-mapper-backend dev
pnpm --dir code-mapper-backend build
pnpm --dir code-mapper-backend test
pnpm --dir code-mapper-backend lint
pnpm --dir code-mapper-backend format
pnpm --dir code-mapper-backend cli:dev analyze ../sample-project --no-confirm

Frontend

pnpm --dir code-mapper-frontend dev
pnpm --dir code-mapper-frontend build
pnpm --dir code-mapper-frontend build:report
pnpm --dir code-mapper-frontend verify
pnpm --dir code-mapper-frontend format

Analysis Scope And Limitations

• Analyze a concrete project directory, not a detected workspace monorepo root.
• Best results require accurate tsconfig.json, tsconfig.app.json, or jsconfig.json configuration when the target project uses path aliases.
• The current analyzer focuses on internal JS/TS dependencies, not full multi-language analysis.
• External packages are not represented as first-class graph nodes.
• Git-based churn and hotspot signals require local Git history.
• Orphan status means "not reachable from detected entry points" and should be validated before deleting files.
• Live mode and static report mode are close, but not identical. Report mode reduces features that depend on a live backend.
• Metric bands are product heuristics for review prioritization, not universal scientific thresholds.

Sample Project

The sample-project/ directory is an intentionally problematic codebase for demos and regression checks. It contains dependency cycles, heavy coupling, bottlenecks, orphan candidates, and other risky structures.

Use it for local demos, UI validation, report export checks, thesis screenshots, and predictable analysis output.

Useful References

• code-mapper-backend/README.md for npm package usage and CLI reference.
• docs-skripsi/CONTEXT_MY_PROJECT_CODEMAPPER.md for current thesis context.
• docs-skripsi/metrics-diagnosis-guide.md for metric formulas, thresholds, and diagnosis mapping.
• docs/parity-verification-flow.md for live/report verification flow.
• code-mapper-backend/src/cli/create-program.ts for current CLI behavior.
• code-mapper-backend/src/services/report-generator.ts for report export requirements.

License

MIT