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
2. Core Principles
3. Conceptual Model
4. Architecture
5. Roadmap & Capabilities
6. Getting Started (Planned)
7. 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:

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)

# 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:

# 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).