codedna-analyzer 1.4.0__tar.gz

codedna_analyzer-1.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shenald-dev
+
+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.

codedna_analyzer-1.4.0/PKG-INFO

@@ -0,0 +1,425 @@
+Metadata-Version: 2.4
+Name: codedna-analyzer
+Version: 1.4.0
+Summary: 🧬 A genetic analyzer for software — reverse-engineer any codebase into a DNA profile.
+Author-email: Shenal Diluksha <shenald@users.noreply.github.com>
+Maintainer-email: shenald-dev <shenald@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/shenald-dev/codedna
+Project-URL: Documentation, https://github.com/shenald-dev/codedna#readme
+Project-URL: Repository, https://github.com/shenald-dev/codedna
+Project-URL: Issues, https://github.com/shenald-dev/codedna/issues
+Project-URL: Changelog, https://github.com/shenald-dev/codedna/blob/main/CHANGELOG.md
+Keywords: code-analysis,architecture,dependency-graph,software-intelligence,dna,cli
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: GitPython>=3.1.0
+Requires-Dist: networkx>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-subtests; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Provides-Extra: ai
+Requires-Dist: openai>=1.0.0; extra == "ai"
+Dynamic: license-file
+
+<div align="center">
+  <img src="assets/logo.png" alt="CodeDNA Logo" width="250" />
+  
+  <br/>
+
+  <h1>🧬 CodeDNA</h1>
+  <p><b>Software Intelligence System — A Genetic Analyzer for Code</b></p>
+  <i>Reverse-engineer any codebase into a DNA profile. Track genetic drift across releases, enforce architectural quality gates in CI/CD, and visualize system evolution.</i>
+
+  <br/>
+
+  [![PyPI version](https://img.shields.io/pypi/v/codedna-analyzer.svg)](https://pypi.org/project/codedna-analyzer/)
+  [![CI](https://github.com/shenald-dev/codedna/actions/workflows/ci.yml/badge.svg)](https://github.com/shenald-dev/codedna/actions)
+  [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://python.org)
+  [![Version](https://img.shields.io/badge/Release-v1.4.0-cyan.svg)](https://github.com/shenald-dev/codedna/releases)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+</div>
+
+---
+
+## 📑 Table of Contents
+- [✨ What is CodeDNA?](#-what-is-codedna)
+- [🚀 Flagship Capabilities](#-flagship-capabilities)
+  - [1. ⚙️ Declarative Configuration (`codedna.toml`)](#1-️-declarative-configuration-codednatoml)
+  - [2. 🛡️ Architectural Drift Regression Gating (`gate`)](#2-️-architectural-drift-regression-gating-gate)
+  - [3. 🧬 Genetic Drift & Architecture Diff Engine (`diff`)](#3--genetic-drift--architecture-diff-engine-diff)
+  - [4. 🛡️ CI/CD Quality Gatekeeper & SARIF / PR Markdown (`check`)](#4-️-cicd-quality-gatekeeper--sarif--pr-markdown-check)
+  - [5. 🔒 Enterprise Security & Shannon Entropy Scanner](#5--enterprise-security--shannon-entropy-scanner)
+  - [6. 🎯 Interactive Executive Radar & HTML Dashboard](#6--interactive-executive-radar--html-dashboard)
+  - [7. 🔌 Model Context Protocol Gateway (`mcp`)](#7--model-context-protocol-gateway-mcp)
+  - [8. ⚙️ Cyclomatic & Cognitive Complexity Engine (`complexity`)](#8-️-cyclomatic--cognitive-complexity-engine-complexity)
+  - [9. 🔒 Executive Compliance Audit (`audit`)](#9--executive-compliance-audit-audit)
+  - [10. 📦 Software Bill of Materials Engine (`sbom`)](#10--software-bill-of-materials-engine-sbom)
+  - [11. 🔧 Intelligent Auto-Remediation Engine (`fix` / `remediate`)](#11--intelligent-auto-remediation-engine-fix--remediate)
+- [🏗️ Analysis Pipeline](#️-analysis-pipeline)
+- [🛠️ Quick Start Guide](#️-quick-start-guide)
+- [💻 Comprehensive Usage](#-comprehensive-usage)
+  - [Project Scaffolding (`init`)](#project-scaffolding-init)
+  - [Analyze a Codebase](#analyze-a-codebase)
+  - [Compare Codebases / Branches (`diff`)](#compare-codebases--branches-diff)
+  - [Gating Architectural Drift in CI (`gate`)](#gating-architectural-drift-in-ci-gate)
+  - [Enforce Quality Gates in CI (`check`)](#enforce-quality-gates-in-ci-check)
+  - [GitHub Actions Integration Examples](#github-actions-integration-examples)
+- [🧬 Example Output](#-example-output)
+- [🤝 Contributing](#-contributing)
+
+---
+
+## ✨ What is CodeDNA?
+
+**CodeDNA** reverse-engineers any codebase and generates a comprehensive "DNA profile". It acts as an automated software architect, traversing tens of thousands of lines of code to distill exactly what a system does, how it is structured, where technical debt hides, and how it is mutating over time.
+
+| Dimension | What It Reveals |
+| :--- | :--- |
+| 🏗️ **Architecture Pattern** | Monolith, MVC, Layered, Microservices, Plugin, Event-Driven |
+| 📊 **Language Distribution** | Files, lines, and percentage share per language (50+ languages supported) |
+| 🔗 **Dependency Graph** | Module topology, coupling density, circular dependency cycle detection |
+| 🐛 **Code Smells & Hygiene** | God classes, runaway file length, bloated functions, Spaghetti Hub coupling |
+| 🔒 **Security Posture** | Hardcoded secrets, AI API keys (OpenAI, Anthropic, HF), command & SQL injection |
+| 👥 **Developer Genome** | Active contributors, bus factor risk, primary architects, collaboration |
+| 📈 **Evolution Timeline** | Commit growth velocity, churn hotspots, architecture shifts |
+| 🧬 **Genetic Drift** | Similarity scoring and mutation delta between branches, commits, or forks |
+
+---
+
+## 🚀 Flagship Capabilities
+
+### 1. ⚙️ Declarative Configuration (`codedna.toml`)
+Configure CodeDNA directly within your repository using `codedna.toml` or `pyproject.toml [tool.codedna]`:
+- **Path Exclusion Globs:** Cleanly ignore test suites, build outputs, and minified bundles across all analyzers.
+- **Secret Whitelisting:** Suppress false positives for intentional test fixtures or mock keys.
+- **Custom Smell Thresholds:** Tailor file length, function lines, and method count thresholds to your project's standards.
+- **Gate Policies:** Specify default CI quality constraints without repeating CLI flags.
+
+```toml
+# codedna.toml
+ignore_paths = ["tests/*", "docs/*", "build/*"]
+whitelisted_secrets = ["PUBLIC_KEY", "MOCK_TOKEN"]
+
+[gate]
+min_health = "Fair"
+max_critical_smells = 0
+fail_on_secrets = true
+fail_on_circular = false
+max_drift = 20.0
+
+[smells]
+max_file_lines = 650
+max_function_lines = 120
+god_class_methods = 20
+```
+
+### 2. 🛡️ Architectural Drift Regression Gating (`gate`)
+Block pull requests that introduce architectural regressions or degrade code quality:
+- **Baseline vs. Target:** Compare incoming PR branches against `origin/main` or pre-computed baseline JSON profiles.
+- **Zero-Regression Policies:** Fails immediately if codebase health degrades (e.g., Healthy ➔ Critical), circular dependencies are introduced, or genetic drift exceeds allowable tolerance.
+- **Exit Codes:** Exits with `0` on clean gates, `1` on regression breach.
+
+```bash
+# Evaluate drift between main branch and current working tree
+codedna gate origin/main .
+
+# Evaluate drift between two DNA profiles with custom similarity requirements
+codedna gate baseline_profile.json pr_profile.json --min-similarity 85.0
+```
+
+### 3. 🧬 Genetic Drift & Architecture Diff Engine (`diff`)
+Compare two repositories, branches, or pre-generated DNA profiles to measure **architectural drift** and **genetic similarity** (0.0% to 100.0%):
+- **Similarity Scoring:** Multi-vector composite evaluation across language distributions, structural size, architectural patterns, dependency graph density, and health ratings.
+- **Structural Deltas:** Track added/removed modules, file volume shifts, and language composition changes.
+- **Coupling & Cycle Shifts:** Instant alerts if circular dependencies were introduced or resolved.
+- **Inline Gating:** Pass `--fail-on-drift` to turn `diff` into a regression gatekeeper.
+
+```bash
+# Compare two local repositories
+codedna diff ./repo-main ./repo-refactor
+
+# Compare two saved DNA profile snapshots with inline drift gating
+codedna diff reports/profile_v1.json reports/profile_v2.json --fail-on-drift
+```
+
+### 4. 🛡️ CI/CD Quality Gatekeeper & SARIF / PR Markdown (`check`)
+Enforce architectural rules and security standards directly in your build and PR validation pipelines:
+- **Policy Gates:** Reject PRs that breach health ratings, introduce hardcoded secrets, or exceed smell thresholds.
+- **Native SARIF v2.1.0:** Generates OASIS SARIF output for GitHub Code Scanning tab annotations.
+- **PR Review Markdown:** Generates formatted markdown tables (`--format markdown`) ready to post as PR review comments.
+
+```bash
+# Validate local repo in CI
+codedna check .
+
+# Generate Markdown table for GitHub Actions PR comment
+codedna check . --format markdown --output pr-comment.md
+
+# Export SARIF for GitHub Code Scanning
+codedna check . --format sarif --output codedna-results.sarif
+```
+
+### 5. 🔒 Enterprise Security & Shannon Entropy Scanner
+Built-in zero-dependency scanning for high-risk vulnerabilities, high-entropy secrets, and cloud credentials:
+- **Shannon Entropy Secret Hunter:** Computes mathematical information density ($H(S) = -\sum p(c) \log_2 p(c)$) to surface unformatted API keys, hex secrets, and base64 private tokens without relying on brittle prefix guessing.
+- **AI & Cloud API Tokens:** Detects exposed keys for OpenAI (`sk-...`), Anthropic (`sk-ant-...`), Google Gemini (`AIzaSy...`), Cohere, Mistral, Perplexity, DeepSeek, Groq, Hugging Face (`hf_...`), Pinecone (`pcsk_...`), AWS, GitHub, Stripe, and Slack.
+- **Database Connection URIs:** Flags embedded passwords in database strings (`postgres://`, `mysql://`, `mongodb://`, `redis://`).
+- **Insecure Deserialization & Injection:** Catches dangerous `pickle.loads()`, `yaml.unsafe_load()`, `subprocess.*(shell=True)`, and SQL f-strings.
+
+### 6. 🎯 Interactive Executive Radar & HTML Dashboard
+The generated HTML dashboard includes:
+- **Pure SVG Radar Chart:** Five-dimensional assessment (Health & Hygiene, Security Posture, Modularity & Coupling, Architecture Cohesion, Team Resilience) rendered with zero external CDN dependencies.
+- **Interactive Risk Filter:** Client-side instant filtering across code smells, god classes, and security warnings.
+- **Print / PDF Ready:** Fully styled `@media print` support for executive architecture reviews.
+
+### 7. 🔌 Model Context Protocol Gateway (`mcp`)
+Expose CodeDNA as an official **MCP (2024-11-05 Specification)** JSON-RPC 2.0 server over stdio for AI coding assistants:
+- Seamlessly integrates with **Claude Desktop**, **Cursor**, **Windsurf**, and **Antigravity**.
+- Provides 7 standard tools: `codedna_analyze`, `codedna_inspect_architecture`, `codedna_security_audit`, `codedna_complexity_metrics`, `codedna_dependency_graph`, `codedna_quality_gate`, and `codedna_drift_diff`.
+
+```json
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "codedna": {
+      "command": "codedna",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### 8. ⚙️ Cyclomatic & Cognitive Complexity Engine (`complexity`)
+Comprehensive function-level structural analysis using Python AST and universal token streaming:
+- **McCabe Cyclomatic Complexity ($CC$):** Exact decision point counting (`if`, `while`, `for`, `except`, `assert`, boolean chains, comprehensions).
+- **Cognitive Complexity:** Standard Sonarsource nesting-penalized evaluation.
+- **Maintainability Index ($MI$):** Standard SEI maintainability scoring on a 0–100 scale with letter grade rankings (A through F).
+
+### 9. 🛡️ Executive Compliance Audit (`audit`)
+Fast, terminal-native security and architectural compliance audit with colorized Rich tables and strict exit codes (`0` for pass, `1` for policy breach).
+
+### 10. 📦 Software Bill of Materials Engine (`sbom`)
+Generate industry-standard, audit-ready SBOM manifests conforming to federal and enterprise compliance mandates:
+- **CycloneDX (v1.5 JSON):** Complete component graphs, Package URLs (`purl`), and dependency relationships.
+- **SPDX (v2.3 JSON):** Open source package catalogs, licensing assertions, and document hashes.
+- **Multi-Ecosystem Discovery:** Parses Python (`pyproject.toml`, `requirements.txt`), Node.js (`package.json`, `package-lock.json`), Rust (`Cargo.toml`, `Cargo.lock`), and Go (`go.mod`).
+```bash
+# Generate CycloneDX SBOM
+codedna sbom . --format cyclonedx --output sbom-cyclonedx.json
+
+# Generate SPDX SBOM
+codedna sbom . --format spdx --output sbom-spdx.json
+```
+
+### 11. 🔧 Intelligent Auto-Remediation Engine (`fix` / `remediate`)
+Close the loop from diagnostic detection to resolution with deterministic code patches:
+- **Bare Exceptions:** Safely transforms broad `except:` to typed `except Exception:` handlers.
+- **Secret Extraction:** Refactors hardcoded API keys and tokens into `os.getenv(...)` variables.
+- **Wildcard Resolution:** Pins open-ended `package.json` `"*"` wildcards to safe semantic ranges (`^1.0.0`).
+- **Unified Diffs & Dry-Runs:** Preview patches before application or export unified patch files.
+```bash
+# Preview auto-remediation plan
+codedna remediate . --dry-run
+
+# Automatically patch safe findings on disk
+codedna fix .
+```
+
+---
+
+## 🏗️ Analysis Pipeline
+
+CodeDNA executes a modular 10-stage analysis pipeline:
+
+```mermaid
+graph TD
+    A[Repository / Git Input] --> B[Repo Cloner / Path Resolver]
+    B --> C[Language Detector]
+    C --> D[Structure Analyzer]
+    D --> E[Dependency Mapper & Mermaid Graph]
+    E --> F[Architecture Pattern Detector]
+    F --> G[Code Smell & Hygiene Detector]
+    G --> H[Security & Secret Scanner]
+    H --> I[Developer & Bus Factor Analyzer]
+    I --> J[Evolution & Git Churn Engine]
+    J --> K[DNA Profile Synthesis]
+    K --> L[Terminal Visualizer]
+    K --> M[HTML Executive Dashboard]
+    K --> N[CI Gatekeeper & SARIF]
+    K --> O[Genetic Diff Engine]
+```
+
+---
+
+## 🛠️ Quick Start Guide
+
+### Installation
+```bash
+pip install codedna-analyzer
+```
+
+Or install via `pipx` or `uv`:
+```bash
+pipx install codedna-analyzer
+# or
+uv tool install codedna-analyzer
+```
+
+Verify installation:
+```bash
+codedna --version
+# codedna, version 1.4.0
+```
+
+---
+
+## 💻 Comprehensive Usage
+
+### Project Scaffolding (`init`)
+Scaffold a starter configuration file in your project:
+```bash
+codedna init .
+```
+
+### Analyze a Codebase
+```bash
+# Analyze a public GitHub repository
+codedna analyze https://github.com/user/project
+
+# Analyze local directory and save all reports (HTML, JSON, Markdown)
+codedna analyze . --output reports/
+
+# Headless mode for automated environments
+codedna analyze . --no-visualize --output reports/ --format json
+```
+
+### Compare Codebases / Branches (`diff`)
+```bash
+# Terminal comparison
+codedna diff ./release-1.0 ./release-2.0
+
+# Generate Markdown diff report
+codedna diff ./branch-a ./branch-b --format markdown --output diff-report.md
+```
+
+### Gating Architectural Drift in CI (`gate`)
+```bash
+# Block PR if architecture degrades compared to baseline
+codedna gate baseline_dna.json current_dna.json
+
+# Fail if similarity drops below 90% or circular dependencies are added
+codedna gate ./main-repo ./pr-repo --min-similarity 90.0
+```
+
+### Enforce Quality Gates in CI (`check`)
+```bash
+# Standard CI check
+codedna check .
+
+# Fail on circular dependencies or critical smells
+codedna check . --fail-on-circular --max-critical-smells 0
+```
+
+### GitHub Actions Integration Examples
+
+#### 1. GitHub Code Scanning (SARIF)
+```yaml
+name: Architecture & Security Gate
+on: [pull_request]
+
+jobs:
+  codedna-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 100
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install CodeDNA
+        run: pip install codedna
+
+      - name: Run CodeDNA Gatekeeper & SARIF Export
+        run: codedna check . --format sarif --output codedna.sarif
+
+      - name: Upload SARIF to GitHub Code Scanning
+        if: always()
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: codedna.sarif
+```
+
+#### 2. Automated PR Review Comment
+```yaml
+      - name: Generate PR Quality Table
+        run: codedna check . --format markdown --output pr-summary.md
+
+      - name: Comment PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const body = fs.readFileSync('pr-summary.md', 'utf8');
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: body
+            });
+```
+
+---
+
+## 🧬 Example Output
+
+### Genetic Drift & Mutation Diff
+```
+┌─────────────────────────── 🧬 Architecture Diff ────────────────────────────┐
+│                                                                             │
+│  🧬 CodeDNA Genetic Drift & Mutation Diff                                   │
+│  Baseline (A): ./v1.1.0                                                     │
+│  Target   (B): ./v1.2.0                                                     │
+│                                                                             │
+│  Genetic Similarity: 96.5% ███████████████████░                             │
+│  Mutation Verdict:   Quality & Hygiene Improvement                          │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                      📊 Architectural & Structural Drift                      
+┌──────────────────┬──────────────┬──────────────┬────────────────────────────┐
+│ Dimension        │ Baseline (A) │ Target (B)   │ Drift / Delta              │
+├──────────────────┼──────────────┼──────────────┼────────────────────────────┤
+│ Architecture     │ Monolith     │ Monolith     │ Unchanged                  │
+│ Health Score     │ Fair         │ Healthy      │ Improved (crit: 0, warn: 0)│
+│ Files Count      │ -            │ -            │ +6 files                   │
+│ Circular Deps    │ None ✅      │ None ✅      │ Clean                      │
+│ Bus Factor       │ -            │ -            │ +1                         │
+└──────────────────┴──────────────┴──────────────┴────────────────────────────┘
+```
+
+---
+
+## 🤝 Contributing
+- 🐛 **Bug reports & ideas:** Open an issue on GitHub.
+- 🚀 **Feature additions:** PRs welcome! Ensure all tests pass with `pytest` and code matches `ruff check`.
+
+---
+> *Software has DNA too. Decode it with CodeDNA.*