@heildamm/cli 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+MIT License
+
+Copyright (c) 2026 Heildamm
+
+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...
+
+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.
+EOF

package/README.md

@@ -0,0 +1,155 @@
+
+<div align="center">
+<pre style="color: #8e61c6; background: transparent; border: none; font-weight: bold; line-height: 1.2;">
+                                         ░▒▓▓▒░                                                    
+                                        ░▒▓▓▓▓░    ▒▓▓▓▒                                           
+                                        ░▒▓▓▓▓░    ▒▓▓▓▓░                                          
+                                        ░▒▓▓▓▓▓▒░  ▒▓▓▓▓░                                          
+                                        ░▒▓▓▓▓▓▓▓▓▒▒▓▓▓▓░                                          
+                                        ░▒▓▓▓▓▒▓▓▓▓▓▓▓▓▓░                                          
+                                        ░▒▓▓▓▓  ░▓▓▓▓▓▓▓░                                          
+                                        ░▒▓▓▓▓    ░▒▓▓▓▓░                                          
+                                        ░▒▓▓▓▓░    ▒▓▓▓▓░                                          
+                                        ░▒▓▓▓▓     ▒▓▓▓▓░                                          
+                                         ░▓▓▓▓░    ▒▓▓▓▓░                                          
+                                             ░░     ▒▓▒▒░                                          
+</pre>
+</div>
+
+# Heildamm
+
+> **A local-first Git analysis engine.** Extract structural, temporal, and ownership insights from any repository without relying on external services or compromising data security.
+
+Heildamm operates exclusively within the local `.git` directory. By applying deterministic algorithms, it reconstructs the evolutionary timeline of a codebase, transforming historical Git data into actionable engineering metrics.
+
+---
+
+## Table of Contents
+1. [Executive Overview](#executive-overview)
+2. [Core Principles](#core-principles)
+3. [Conceptual Model](#conceptual-model)
+4. [Architecture](#architecture)
+5. [Roadmap & Capabilities](#roadmap--capabilities)
+6. [Getting Started (Planned)](#getting-started-planned)
+7. [License](#license)
+
+---
+
+## Executive Overview
+
+Modern codebases accumulate structural complexity through continuous modification, but the contextual reasoning behind these changes is frequently lost. Traditional version control interfaces provide fragmented visibility:
+
+* **`git log`:** Outputs chronological sequences devoid of systemic context.
+* **`git blame`:** Attributes line-level authorship without accounting for temporal relevance.
+* **Code Review Platforms:** Isolate analysis to immediate, pending changes.
+
+**Heildamm** bridges this visibility gap. It treats the repository's history as a comprehensive dataset, allowing engineering leadership and maintainers to model, analyze, and interpret the lifecycle of the codebase holistically.
+
+---
+
+## Core Principles
+
+* **Local-First & Secure:** All analytical processing is executed locally. Zero network requests, no external APIs, and no source code exfiltration, ensuring strict compliance with internal security policies.
+* **Deterministic Execution:** System outputs are exclusively derived from reproducible algorithms applied to raw Git data. The architecture deliberately avoids non-deterministic probabilistic models or opaque machine learning layers.
+* **Structural History:** The commit timeline is parsed not as a flat log, but as a structured sequence of architectural transformations that can be queried and grouped.
+* **Knowledge over Authorship:** Code ownership is dynamically calculated based on active contribution and recency, discarding the static and often outdated metric of original authorship.
+
+---
+
+## Conceptual Model
+
+### 1. Authorship and Knowledge Distribution
+Heildamm calculates a **"living ownership"** matrix utilizing:
+* Granular line-level attribution.
+* Temporal decay algorithms (weighting recent modifications more heavily).
+* Aggregate contribution metrics per file and subsystem.
+
+**Business Value:** Identifies active knowledge domain experts, highlights stale code maintained by inactive personnel, and quantifies knowledge silos.
+
+### 2. Temporal Clustering (Evolution Arcs)
+Individual commits are mathematically grouped into **"arcs"** based on:
+* Chronological proximity.
+* File intersection and cross-dependency across commits.
+
+**Business Value:** Reconstructs the narrative of the project—such as the phased rollout of a feature, the execution of technical debt reduction, or major architectural pivots—abstracting the noise of atomic commits.
+
+### 3. Hotspot Detection
+Systemic risk areas are flagged by evaluating:
+* Modification frequency (commit velocity per file).
+* Unique contributor volume.
+* Codebase expansion rates over defined intervals.
+
+**Business Value:** Statistically isolates files with a high probability of latent defects, pinpointing optimal candidates for targeted refactoring to prevent regressions.
+
+### 4. Bus Factor Estimation
+For any given module or specific file, Heildamm computes:
+* The raw count of engineers possessing critical operational knowledge.
+* The mathematical dependency on specific individual contributors.
+
+**Business Value:** Provides objective metrics on structural maintenance risks and aids in capacity planning and team onboarding strategies.
+
+---
+
+## Architecture
+
+Heildamm is built on a highly modular, decoupled architecture, enabling robust performance and future extensibility:
+
+```text
+Engine Core
+ ├── Git Parser           # Extracts and normalizes raw .git object data
+ ├── Data Model           # Constructs the in-memory representation of repository state
+ ├── Analyzer             # Applies deterministic rulesets and clustering algorithms
+ └── Metrics Engine       # Aggregates scores (hotspots, bus factor, ownership)
+```
+
+**Planned Interface Layers:**
+* **CLI Engine:** Built for continuous integration (CI/CD) pipelines and terminal usage.
+* **Local Visualization Server:** Generates interactive, browser-based telemetry dashboards.
+* **Narrative Generator:** Compiles automated, human-readable executive summaries of codebase health.
+
+---
+
+## Roadmap & Capabilities
+
+The following features dictate the current development roadmap, all guaranteed to run in offline, air-gapped environments:
+
+* **Deep Git Object Parsing:** Complete historical traversal without overhead.
+* **Blame-Based Authorship Matrix:** High-fidelity contributor tracking.
+* **Recency-Weighted Scoring System:** Intelligent degradation of historical authorship.
+* **Commit Arc Clustering:** Feature-level timeline reconstruction.
+* **Volatility Hotspot Scoring:** Predictive risk assessment based on churn.
+* **Bus Factor Analytics:** Automated team dependency reporting.
+
+---
+
+## Getting Started (Planned)
+
+### Installation
+*(Pending release - placeholder for binary/package manager instructions)*
+```bash
+# Example: curl -sSL [https://heildamm.dev/install.sh](https://heildamm.dev/install.sh) | bash
+```
+
+### Usage Examples
+Execute Heildamm at the root of your Git repository:
+
+```bash
+# Initialize a full repository analysis
+heildamm analyze .
+
+# Output a targeted report of the top 10 most volatile files
+heildamm report --type hotspots --limit 10
+
+# Calculate the bus factor for a specific architectural boundary
+heildamm bus-factor ./src/core/networking
+
+# Generate a machine-readable JSON output for CI pipeline ingestion
+heildamm analyze . --format json > report.json
+```
+
+---
+
+## License
+
+Copyright © 2026. All rights reserved. 
+*(Update this section with your specific open-source or proprietary license).*

package/bin/run.js

@@ -0,0 +1,2 @@
+"use strict";
+console.log("Hello from heildamm CLI!");

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@heildamm/cli",
+  "version": "0.1.0",
+  "description": "A local-first Git analysis engine to extract structural, temporal, and ownership insights.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "heildamm": "./bin/run.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:clean": "rm -rf dist && tsc",
+    "dev": "tsc --watch",
+    "start": "node ./bin/run.js",
+    "lint": "eslint 'src/**/*.{js,ts}' --quiet --fix",
+    "test": "jest --passWithNoTests",
+    "test:coverage": "jest --coverage",
+    "prepare": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/glatztp/heildamm"
+  },
+  "keywords": [
+    "git",
+    "analysis",
+    "telemetry",
+    "engineering-metrics",
+    "cli",
+    "local-first"
+  ],
+  "author": "Gabriel Glatz ",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=9.0.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "dependencies": {
+    "next": "16.1.6",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "server-only": "^0.0.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "babel-plugin-react-compiler": "1.0.0",
+    "eslint": "^9",
+    "eslint-config-next": "16.1.6",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}