@dependency-maritime/cli 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 g1ddy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# Dependency Maritime ⚓️
+
+![License](https://img.shields.io/badge/license-MIT-blue)
+![React](https://img.shields.io/badge/react-19.2.3-blue)
+![Vite](https://img.shields.io/badge/vite-7.3.1-purple)
+![TypeScript](https://img.shields.io/badge/typescript-5.9.3-blue)
+![Status](https://img.shields.io/badge/status-Phase%201%20Complete-green)
+
+**Chart, navigate, and refactor your application's architecture.**
+
+Dependency Maritime is an interactive visualization tool for [dependency-cruiser](https://github.com/sverweij/dependency-cruiser). It transforms complex dependency graphs into navigable, interactive maps, helping you enforce boundaries, identify tangles, and plan refactoring efforts.
+
+## 📸 Visuals
+
+### Interactive Dashboard
+Visualize your project's structure with an interactive graph. Zoom, pan, and filter to understand relationships.
+![Dashboard View](docs/images/screenshot-dashboard.png)
+
+### Node Inspector
+Select any file to view detailed metrics, including incoming and outgoing dependencies.
+![Node Inspector](docs/images/screenshot-inspector.png)
+
+### Bring Your Own Data
+Easily upload your own `dependency-cruiser` JSON output to visualize your codebase.
+![Upload Data](docs/images/screenshot-upload.png)
+
+## ✨ Features
+
+*   **Interactive Visualization:** Zoom, pan, and drag nodes to explore your architecture.
+*   **Deep Inspection:** Click any node to see its full path, metrics, and direct neighbors.
+*   **Dependency Filtering:** Toggle between "Product" and "Test" code (planned) or specific folders.
+*   **Isolate Modules:** Focus on specific sub-graphs to declutter the view.
+*   **Metrics (Phase 2):** Analyze instability, centrality, and **Cyclomatic Complexity & Lines of Code (LOC)**.
+*   **Compound Health Score:** Automatically assesses node health (Healthy, Warning, Unhealthy) based on a compound formula combining LOC, Complexity, Fan-Out, and Instability.
+*   **100% Client-Side:** Your code structure is analyzed locally; no data leaves your machine.
+
+## 🛠 Installation
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/your-username/dependency-maritime.git
+    cd dependency-maritime
+    ```
+
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    ```
+
+3.  **Start the development server:**
+    ```bash
+    npm run dev
+    ```
+
+## 🚀 Usage
+
+### 1. Generating a Dependency Graph
+To visualize your own project, you need to generate a JSON report using `dependency-cruiser`.
+
+Run the following command in the root of the project you want to analyze:
+
+```bash
+npx dependency-cruiser src \
+  --include-only "^src" \
+  --output-type json \
+  > dependency-graph.json
+```
+
+*Adjust the `src` and `--include-only` patterns to match your project structure.*
+
+#### Integrating Complexity Metrics (Optional)
+To view Cyclomatic Complexity and LOC in the Node Inspector, generate a metrics file using the provided script (if available in your project) or construct a JSON map matching the schema:
+
+```json
+{
+  "src/App.tsx": { "complexity": 5, "loc": 120 },
+  "src/utils.ts": { "complexity": 2, "loc": 45 }
+}
+```
+
+The built-in **Project Graph** loads the validated `.maritime/dependency-graph.json` and `.maritime/complexity-metrics.json` artifacts generated by the repository workflow. Uploaded graphs may optionally include a metrics map using this same schema.
+
+#### Compound Score & Health Status
+The application calculates a **Compound Complexity Score** for each node to determine its health status:
+
+**Formula:**
+`Score = (LOC / 10) + (Complexity * 2) + (FanOut * 2) + (Instability * 20)`
+
+**Health Thresholds:**
+*   🟢 **Healthy:** Score < 20
+*   🟡 **Warning:** Score between 20 and 50
+*   🔴 **Unhealthy:** Score > 50
+
+Nodes will visually reflect their status with colored borders and backgrounds.
+
+### 2. Loading Data
+1.  Open **Dependency Maritime** in your browser (default: `http://localhost:5173`).
+2.  Click the **Upload** icon (cloud/arrow) in the header.
+3.  Drag and drop your `dependency-graph.json` file or click to select it.
+4.  The graph will automatically render your data.
+
+## 🏗 Architecture & Phases
+
+The project is being built in 4 phases:
+1.  **Phase 1: The "Chartroom" (MVP)** - Core visualization (Complete).
+2.  **Phase 2: The "Inspector"** - Metrics and health heatmaps (In Progress).
+3.  **Phase 3: The "Simulator"** - Refactoring playground.
+4.  **Phase 4: The "Cohesion" Assistant** - AI-assisted suggestions.
+
+For more details, check out the documentation:
+*   [Architecture](./docs/ARCHITECTURE.md)
+*   [CLI and Artifact Contract](./docs/CLI.md)
+*   [Roadmap](./docs/ROADMAP.md)
+*   [Development Guide](./docs/DEVELOPMENT.md)
+*   [Design Decisions](./docs/DESIGN_DECISIONS.md)
+
+## 🤝 Contributing
+
+This project uses **npm** for package management. Please ensure you lock files are updated accordingly.
+
+1.  Fork the repo.
+2.  Create a feature branch.
+3.  Commit your changes.
+4.  Push to the branch.
+5.  Create a Pull Request.
+
+## 📝 License
+
+Distributed under the MIT License.

package/dist/cli/cli/analyze/adapters.d.ts

@@ -0,0 +1,32 @@
+import { type DependencyCruiserModule, type EslintResult } from './models';
+export interface ResolvedDepcruiseConfig {
+    config: Record<string, unknown>;
+    configPath: string | null;
+    source: 'explicit' | 'discovered' | 'fallback';
+}
+export declare function getPortableFallbackConfig(cwd?: string): {
+    options: Record<string, unknown>;
+};
+export declare function resolveDepcruiseConfig(configPath?: string, cwd?: string): Promise<ResolvedDepcruiseConfig>;
+export interface GenerateDependencyGraphOptions {
+    sourceRoots: string[];
+    configPath?: string;
+    cwd?: string;
+}
+export interface GenerateDependencyGraphResult {
+    cruiseResult: unknown;
+    modules: DependencyCruiserModule[];
+    configSource: 'explicit' | 'discovered' | 'fallback';
+}
+export declare function generateDependencyGraph(options: GenerateDependencyGraphOptions): Promise<GenerateDependencyGraphResult>;
+export declare function readDependencyGraph(graphPath: string, cwd?: string): Promise<DependencyCruiserModule[]>;
+export declare function runEslintComplexityScan(sourcePath: string | string[], sourceFiles?: string[], cwd?: string): Promise<EslintResult[]>;
+export declare function countLinesOfCode(sourceFiles: string[], cwd?: string): Promise<Record<string, number>>;
+export declare function getToolVersion(): string;
+export declare function writeOutputFiles(metricsPath: string, metricsData: unknown, reportPath: string, reportData: string, cwd?: string): Promise<void>;
+export declare function writeOutputFiles(metricsPath: string, metricsData: unknown, reportPath: string, reportData: string, options?: {
+    manifestPath?: string;
+    manifestData?: unknown;
+    cwd?: string;
+}): Promise<void>;
+export declare function writeOutputFiles(metricsPath: string, metricsData: unknown, reportPath: string, reportData: string, manifestPath?: string, manifestData?: unknown, cwd?: string): Promise<void>;

package/dist/cli/cli/analyze/calculate-metrics.d.ts

@@ -0,0 +1,6 @@
+import type { FileMetric, AnalysisThresholds, AnalysisResult, DependencyCruiserModule, EslintFileComplexity } from './models';
+export declare function isSupportedTypeScriptFile(filepath: string): boolean;
+export declare function calculateInstability(fanIn: number, fanOut: number): number;
+export declare function calculateScore(loc: number, complexity: number, fanOut: number, instability: number): number;
+export declare function calculateHealthScore(files: FileMetric[], thresholds: AnalysisThresholds): number;
+export declare function calculateMetrics(modules: DependencyCruiserModule[], locMap: Record<string, number>, complexityMap: Record<string, EslintFileComplexity | number>, thresholds: AnalysisThresholds, sourcePrefix?: string | string[]): AnalysisResult;

package/dist/cli/cli/analyze/environment.d.ts

@@ -0,0 +1,10 @@
+export declare function validateNodeVersion(nodeVersionStr?: string): void;
+export declare function detectEslintConfig(cwd?: string): {
+    mode: string;
+    isLegacy: boolean;
+    hasFlatConfig: boolean;
+    legacyFile?: string;
+};
+export declare function validateEslintEnvironment(cwd?: string, nodeVersionStr?: string): {
+    mode: string;
+};

package/dist/cli/cli/analyze/models.d.ts

@@ -0,0 +1,47 @@
+export interface FileMetric {
+    file: string;
+    loc: number;
+    complexity: number;
+    fanIn: number;
+    fanOut: number;
+    instability: number;
+    score: number;
+    scanned: boolean;
+}
+export interface AnalysisThresholds {
+    loc: number;
+    complexity: number;
+    fanOut: number;
+    instabilityMin?: number;
+    instabilityMax?: number;
+}
+export interface AnalysisResult {
+    files: FileMetric[];
+    healthScore: number;
+    topByScore: FileMetric[];
+    topByComplexity: FileMetric[];
+    skippedCount: number;
+    unmeasuredFiles: string[];
+}
+export interface EslintMessage {
+    ruleId: string;
+    message: string;
+    fatal?: boolean;
+}
+export interface EslintResult {
+    filePath: string;
+    messages: EslintMessage[];
+    ignored?: boolean;
+}
+export interface EslintFileComplexity {
+    complexity: number;
+    scanned: boolean;
+}
+export interface DependencyCruiserModule {
+    source: string;
+    dependencies: unknown[];
+    dependents: unknown[];
+}
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}

package/dist/cli/cli/analyze/parse-eslint.d.ts

@@ -0,0 +1,2 @@
+import type { EslintResult, EslintFileComplexity } from './models';
+export declare function parseEslintComplexityReport(eslintResults: EslintResult[], cwd: string): Record<string, EslintFileComplexity>;

package/dist/cli/cli/analyze/render-markdown-report.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisResult, AnalysisThresholds } from './models';
+export declare function renderMarkdownReport(result: AnalysisResult, thresholds: AnalysisThresholds, date?: Date): string;

package/dist/cli/cli/commands/analyze.d.ts

@@ -0,0 +1 @@
+export declare function runAnalyzeCommand(args: string[]): Promise<number>;

package/dist/cli/cli/commands/validate.d.ts

@@ -0,0 +1 @@
+export declare function runValidateCommand(args: string[]): Promise<number>;

package/dist/cli/cli/index.d.ts

@@ -0,0 +1,25 @@
+import { runAnalyzeCommand } from './commands/analyze';
+import { runValidateCommand } from './commands/validate';
+import { validateArtifacts } from './validate/validate';
+export { runAnalyzeCommand, runValidateCommand, validateArtifacts };
+export * from '../schema/manifest';
+export { readDependencyGraph, resolveDepcruiseConfig, generateDependencyGraph, runEslintComplexityScan, countLinesOfCode, writeOutputFiles } from './analyze/adapters';
+export { calculateMetrics, isSupportedTypeScriptFile, calculateInstability, calculateScore, calculateHealthScore } from './analyze/calculate-metrics';
+export { parseEslintComplexityReport } from './analyze/parse-eslint';
+export { renderMarkdownReport } from './analyze/render-markdown-report';
+export { validateEslintEnvironment, validateNodeVersion, detectEslintConfig } from './analyze/environment';
+export * from './analyze/models';
+export declare function analyzeProject(options: {
+    graph?: string;
+    metrics?: string;
+    report?: string;
+    output?: string;
+    depcruiseConfig?: string;
+    source?: string | string[];
+    cwd?: string;
+    failOnUnmeasured?: boolean;
+}): Promise<number>;
+export declare function validateProject(options?: {
+    artifactDir?: string;
+    cwd?: string;
+}): Promise<number>;

package/dist/cli/cli/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/cli/validate/validate.d.ts

@@ -0,0 +1,10 @@
+import { type ArtifactManifest } from '../../schema/manifest';
+export interface ValidateArtifactsOptions {
+    artifactDir?: string;
+    cwd?: string;
+}
+export interface ValidateArtifactsResult {
+    manifest: ArtifactManifest;
+    artifactDir: string;
+}
+export declare function validateArtifacts(options?: ValidateArtifactsOptions): Promise<ValidateArtifactsResult>;

package/dist/cli/index.d.ts

@@ -0,0 +1,25 @@
+import { runAnalyzeCommand } from './commands/analyze';
+import { runValidateCommand } from './commands/validate';
+import { validateArtifacts } from './validate/validate';
+export { runAnalyzeCommand, runValidateCommand, validateArtifacts };
+export * from '../schema/manifest';
+export { readDependencyGraph, resolveDepcruiseConfig, generateDependencyGraph, runEslintComplexityScan, countLinesOfCode, writeOutputFiles } from './analyze/adapters';
+export { calculateMetrics, isSupportedTypeScriptFile, calculateInstability, calculateScore, calculateHealthScore } from './analyze/calculate-metrics';
+export { parseEslintComplexityReport } from './analyze/parse-eslint';
+export { renderMarkdownReport } from './analyze/render-markdown-report';
+export { validateEslintEnvironment, validateNodeVersion, detectEslintConfig } from './analyze/environment';
+export * from './analyze/models';
+export declare function analyzeProject(options: {
+    graph?: string;
+    metrics?: string;
+    report?: string;
+    output?: string;
+    depcruiseConfig?: string;
+    source?: string | string[];
+    cwd?: string;
+    failOnUnmeasured?: boolean;
+}): Promise<number>;
+export declare function validateProject(options?: {
+    artifactDir?: string;
+    cwd?: string;
+}): Promise<number>;