soft-archmap 0.1.0__tar.gz

soft_archmap-0.1.0/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 Excited Nuclei Tech Labs
+All rights reserved.
+
+No part of this software may be reproduced, distributed, or transmitted in any form
+or by any means, including photocopying, recording, or other electronic or mechanical
+methods, without the prior written permission of Excited Nuclei Tech Labs.
+
+For permission requests, contact: excitednuclei.techlabs@gmail.com

soft_archmap-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: soft-archmap
+Version: 0.1.0
+Summary: Python tool to analyze architecture and dependencies in Python projects.
+Author-email: Excited Nuclei Tech Labs <excitednuclei.techlabs@gmail.com>
+Project-URL: Homepage, https://github.com/EN-Tech-Labs/ArchMap
+Project-URL: Repository, https://github.com/EN-Tech-Labs/ArchMap
+Project-URL: Documentation, https://github.com/EN-Tech-Labs/ArchMap
+Keywords: architecture,dependency,python,analysis
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Operating System :: OS Independent
+Classifier: License :: Other/Proprietary License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: graphviz>=0.21
+Requires-Dist: networkx>=3.6.1
+Requires-Dist: pyvis>=0.3.2
+Requires-Dist: rich>=15.0.0
+Requires-Dist: requests>=2.33.1
+Provides-Extra: dev
+Requires-Dist: asttokens==3.0.1; extra == "dev"
+Requires-Dist: build==1.5.0; extra == "dev"
+Requires-Dist: certifi==2026.4.22; extra == "dev"
+Requires-Dist: charset-normalizer==3.4.7; extra == "dev"
+Requires-Dist: colorama==0.4.6; extra == "dev"
+Requires-Dist: comm==0.2.3; extra == "dev"
+Requires-Dist: debugpy==1.8.20; extra == "dev"
+Requires-Dist: decorator==5.2.1; extra == "dev"
+Requires-Dist: docutils==0.22.4; extra == "dev"
+Requires-Dist: executing==2.2.1; extra == "dev"
+Requires-Dist: id==1.6.1; extra == "dev"
+Requires-Dist: idna==3.13; extra == "dev"
+Requires-Dist: ipykernel==7.2.0; extra == "dev"
+Requires-Dist: ipython==9.13.0; extra == "dev"
+Requires-Dist: ipython_pygments_lexers==1.1.1; extra == "dev"
+Requires-Dist: jaraco.classes==3.4.0; extra == "dev"
+Requires-Dist: jaraco.context==6.1.2; extra == "dev"
+Requires-Dist: jaraco.functools==4.4.0; extra == "dev"
+Requires-Dist: jedi==0.19.2; extra == "dev"
+Requires-Dist: Jinja2==3.1.6; extra == "dev"
+Requires-Dist: jsonpickle==4.1.1; extra == "dev"
+Requires-Dist: jupyter_client==8.8.0; extra == "dev"
+Requires-Dist: jupyter_core==5.9.1; extra == "dev"
+Requires-Dist: keyring==25.7.0; extra == "dev"
+Requires-Dist: markdown-it-py==4.0.0; extra == "dev"
+Requires-Dist: MarkupSafe==3.0.3; extra == "dev"
+Requires-Dist: matplotlib-inline==0.2.1; extra == "dev"
+Requires-Dist: mdurl==0.1.2; extra == "dev"
+Requires-Dist: more-itertools==11.0.2; extra == "dev"
+Requires-Dist: nest-asyncio==1.6.0; extra == "dev"
+Requires-Dist: nh3==0.3.5; extra == "dev"
+Requires-Dist: packaging==26.1; extra == "dev"
+Requires-Dist: parso==0.8.6; extra == "dev"
+Requires-Dist: platformdirs==4.9.6; extra == "dev"
+Requires-Dist: prompt_toolkit==3.0.52; extra == "dev"
+Requires-Dist: psutil==7.2.2; extra == "dev"
+Requires-Dist: pure_eval==0.2.3; extra == "dev"
+Requires-Dist: Pygments==2.20.0; extra == "dev"
+Requires-Dist: pyproject_hooks==1.2.0; extra == "dev"
+Requires-Dist: python-dateutil==2.9.0.post0; extra == "dev"
+Requires-Dist: pywin32-ctypes==0.2.3; extra == "dev"
+Requires-Dist: pyzmq==27.1.0; extra == "dev"
+Requires-Dist: readme_renderer==44.0; extra == "dev"
+Requires-Dist: requests-toolbelt==1.0.0; extra == "dev"
+Requires-Dist: rfc3986==2.0.0; extra == "dev"
+Requires-Dist: six==1.17.0; extra == "dev"
+Requires-Dist: stack-data==0.6.3; extra == "dev"
+Requires-Dist: tornado==6.5.5; extra == "dev"
+Requires-Dist: traitlets==5.14.3; extra == "dev"
+Requires-Dist: twine==6.2.0; extra == "dev"
+Requires-Dist: urllib3==2.6.3; extra == "dev"
+Requires-Dist: wcwidth==0.6.0; extra == "dev"
+Dynamic: license-file
+
+# ArchMap-Python
+
+ArchMap-Python is a CLI tool by **Excited Nuclei Tech Labs** for analyzing Python software architecture. It helps developers understand dependencies, detect cycles, measure module health, compute risk, and visualize the architecture.
+
+## Features
+
+- Dependency graph generation
+- Cycle detection
+- Health metrics
+- Risk scoring of modules/functions
+- Impact analysis
+- Graphviz visualization and JSON export
+
+## Installation
+

soft_archmap-0.1.0/README.md

@@ -0,0 +1,15 @@
+# ArchMap-Python
+
+ArchMap-Python is a CLI tool by **Excited Nuclei Tech Labs** for analyzing Python software architecture. It helps developers understand dependencies, detect cycles, measure module health, compute risk, and visualize the architecture.
+
+## Features
+
+- Dependency graph generation
+- Cycle detection
+- Health metrics
+- Risk scoring of modules/functions
+- Impact analysis
+- Graphviz visualization and JSON export
+
+## Installation
+

soft_archmap-0.1.0/pyproject.toml

@@ -0,0 +1,92 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "soft-archmap"          # must be lowercase, use '-' not '_'
+version = "0.1.0"
+description = "Python tool to analyze architecture and dependencies in Python projects."
+readme = "README.md"             # include README on PyPI
+requires-python = ">=3.10"
+authors = [
+    { name = "Excited Nuclei Tech Labs", email = "excitednuclei.techlabs@gmail.com" }
+]
+license = { file = "LICENSE.txt" }   # or use SPDX identifier if open source, e.g., "MIT"
+keywords = ["architecture", "dependency", "python", "analysis"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Operating System :: OS Independent",
+    "License :: Other/Proprietary License"
+]
+dependencies = [
+    "graphviz>=0.21",
+    "networkx>=3.6.1",
+    "pyvis>=0.3.2",
+    "rich>=15.0.0",
+    "requests>=2.33.1"
+]
+
+[project.optional-dependencies]
+dev = [
+    "asttokens==3.0.1",
+    "build==1.5.0",
+    "certifi==2026.4.22",
+    "charset-normalizer==3.4.7",
+    "colorama==0.4.6",
+    "comm==0.2.3",
+    "debugpy==1.8.20",
+    "decorator==5.2.1",
+    "docutils==0.22.4",
+    "executing==2.2.1",
+    "id==1.6.1",
+    "idna==3.13",
+    "ipykernel==7.2.0",
+    "ipython==9.13.0",
+    "ipython_pygments_lexers==1.1.1",
+    "jaraco.classes==3.4.0",
+    "jaraco.context==6.1.2",
+    "jaraco.functools==4.4.0",
+    "jedi==0.19.2",
+    "Jinja2==3.1.6",
+    "jsonpickle==4.1.1",
+    "jupyter_client==8.8.0",
+    "jupyter_core==5.9.1",
+    "keyring==25.7.0",
+    "markdown-it-py==4.0.0",
+    "MarkupSafe==3.0.3",
+    "matplotlib-inline==0.2.1",
+    "mdurl==0.1.2",
+    "more-itertools==11.0.2",
+    "nest-asyncio==1.6.0",
+    "nh3==0.3.5",
+    "packaging==26.1",
+    "parso==0.8.6",
+    "platformdirs==4.9.6",
+    "prompt_toolkit==3.0.52",
+    "psutil==7.2.2",
+    "pure_eval==0.2.3",
+    "Pygments==2.20.0",
+    "pyproject_hooks==1.2.0",
+    "python-dateutil==2.9.0.post0",
+    "pywin32-ctypes==0.2.3",
+    "pyzmq==27.1.0",
+    "readme_renderer==44.0",
+    "requests-toolbelt==1.0.0",
+    "rfc3986==2.0.0",
+    "six==1.17.0",
+    "stack-data==0.6.3",
+    "tornado==6.5.5",
+    "traitlets==5.14.3",
+    "twine==6.2.0",
+    "urllib3==2.6.3",
+    "wcwidth==0.6.0"
+]
+
+[project.scripts]
+soft-archmap = "soft_archmap.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/EN-Tech-Labs/ArchMap"
+Repository = "https://github.com/EN-Tech-Labs/ArchMap"
+Documentation = "https://github.com/EN-Tech-Labs/ArchMap"

soft_archmap-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

soft_archmap-0.1.0/soft_archmap/adapters/python_adapter.py

@@ -0,0 +1,198 @@
+import ast
+import os
+from soft_archmap.core.model import Entity, Relation
+
+class PythonParser:
+    def __init__(self, repo_path: str, model):
+        self.repo_path = repo_path
+        self.model = model
+
+        self.current_module = None
+        self.current_class = None
+        self.current_function = None
+
+        # NEW: track import aliases
+        self.import_aliases = {}
+
+    # ----------------------------
+    # PUBLIC
+    # ----------------------------
+    def parse_file(self, file_path: str):
+        if any(part in {"venv", ".venv", "env", ".env"} for part in file_path.split(os.sep)):
+            return
+
+        with open(file_path, "r", encoding="utf-8") as f:
+            print(f"Parsing {file_path}...")
+            source = f.read()
+
+        try:
+            tree = ast.parse(source, filename=file_path)
+        except SyntaxError as e:
+            print(f"Skipping {file_path} due to syntax error: {e}")
+            return
+
+        module_name = os.path.relpath(file_path, self.repo_path) \
+            .replace(os.sep, ".") \
+            .replace(".py", "")
+
+        self.current_module = module_name
+        module_id = f"module:{module_name}"
+
+        # Ensure module entity exists
+        self._ensure_entity(module_id, "module", module_name, file_path)
+
+        for node in tree.body:
+
+            # -------- Imports --------
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    real_name = alias.name
+                    alias_name = alias.asname or alias.name
+
+                    self.import_aliases[alias_name] = real_name
+                    self._add_import(module_id, real_name)
+
+            elif isinstance(node, ast.ImportFrom):
+                if node.module:
+                    for alias in node.names:
+                        alias_name = alias.asname or alias.name
+                        full_name = f"{node.module}.{alias.name}"
+                        self.import_aliases[alias_name] = full_name
+
+                    self._add_import(module_id, node.module)
+
+            # -------- Classes --------
+            elif isinstance(node, ast.ClassDef):
+                self._handle_class(node, module_id, module_name, file_path)
+
+            # -------- Top-level Functions --------
+            elif isinstance(node, ast.FunctionDef):
+                self._handle_function(
+                    node, module_id, module_name, file_path, parent_class=None
+                )
+
+    # ----------------------------
+    # ENTITY HELPERS
+    # ----------------------------
+    def _ensure_entity(self, entity_id, entity_type, name, file):
+        if entity_id not in self.model.entities:
+            self.model.add_entity(Entity(
+                id=entity_id,
+                type=entity_type,
+                name=name,
+                file=file
+            ))
+
+    def _ensure_external_entity(self, entity_id):
+        if entity_id not in self.model.entities:
+            self.model.add_entity(Entity(
+                id=entity_id,
+                type="external",
+                name=entity_id.split(":", 1)[-1],
+                file="external"
+            ))
+
+    def _add_relation(self, src, dst, rel_type):
+        self._ensure_external_entity(dst)
+
+        self.model.add_relation(Relation(
+            src=src,
+            dst=dst,
+            type=rel_type
+        ))
+
+    # ----------------------------
+    # IMPORTS
+    # ----------------------------
+    def _add_import(self, module_id: str, imported_module: str):
+        target_id = f"module:{imported_module}"
+        self._add_relation(module_id, target_id, "imports")
+
+    # ----------------------------
+    # CLASS HANDLER
+    # ----------------------------
+    def _handle_class(self, node, module_id, module_name, file_path):
+        class_name = node.name
+        qualname = f"{module_name}.{class_name}"
+        class_id = f"class:{qualname}"
+
+        self._ensure_entity(class_id, "class", qualname, file_path)
+
+        self._add_relation(module_id, class_id, "contains")
+
+        # -------- Inheritance --------
+        for base in node.bases:
+            if isinstance(base, ast.Name):
+                base_id = f"class:{base.id}"
+                self._add_relation(class_id, base_id, "inherits")
+
+        prev_class = self.current_class
+        self.current_class = class_name
+
+        for item in node.body:
+            if isinstance(item, ast.FunctionDef):
+                self._handle_function(
+                    item, module_id, module_name, file_path, parent_class=class_name
+                )
+
+        self.current_class = prev_class
+
+    # ----------------------------
+    # FUNCTION / METHOD HANDLER
+    # ----------------------------
+    def _handle_function(self, node, module_id, module_name, file_path, parent_class):
+        func_name = node.name
+
+        if parent_class:
+            qualname = f"{module_name}.{parent_class}.{func_name}"
+            func_id = f"function:{qualname}"
+            parent_id = f"class:{module_name}.{parent_class}"
+            entity_type = "method"
+        else:
+            qualname = f"{module_name}.{func_name}"
+            func_id = f"function:{qualname}"
+            parent_id = module_id
+            entity_type = "function"
+
+        self._ensure_entity(func_id, entity_type, qualname, file_path)
+
+        self._add_relation(parent_id, func_id, "contains")
+
+        # -------- Calls --------
+        prev_function = self.current_function
+        self.current_function = func_id
+
+        for child in ast.walk(node):
+            if isinstance(child, ast.Call):
+                called_name = self._resolve_call(child.func)
+                if called_name:
+                    target_id = f"function:{called_name}"
+                    self._add_relation(func_id, target_id, "calls")
+
+        self.current_function = prev_function
+
+    # ----------------------------
+    # CALL RESOLUTION (IMPROVED)
+    # ----------------------------
+    def _resolve_call(self, node):
+        # foo()
+        if isinstance(node, ast.Name):
+            return self._resolve_alias(node.id)
+
+        # obj.method()
+        elif isinstance(node, ast.Attribute):
+            parts = []
+            while isinstance(node, ast.Attribute):
+                parts.append(node.attr)
+                node = node.value
+
+            if isinstance(node, ast.Name):
+                base = self._resolve_alias(node.id)
+                parts.append(base)
+
+            return ".".join(reversed(parts))
+
+        return None
+
+    def _resolve_alias(self, name):
+        return self.import_aliases.get(name, name)

soft_archmap-0.1.0/soft_archmap/analysis/cycles.py

@@ -0,0 +1,13 @@
+# analysis/cycles.py
+from soft_archmap.core.graph import DependencyGraph
+
+def detect_cycles(model):
+    """
+    Detect cycles in architecture.
+    Returns a list of cycles (list of entity IDs).
+    """
+    graph = DependencyGraph()
+    for r in model.relations:
+        graph.add_edge(r.src, r.dst)
+
+    return graph.find_cycles()

soft_archmap-0.1.0/soft_archmap/analysis/health.py

@@ -0,0 +1,15 @@
+# analysis/health.py
+from soft_archmap.core.graph import DependencyGraph
+
+def compute_health(model):
+    """
+    Simple health metric: ratio of used entities to total entities.
+    """
+    graph = DependencyGraph()
+    for r in model.relations:
+        graph.add_edge(r.src, r.dst)
+
+    total = len(model.entities)
+    unused = len([e for e in model.entities.values() if not graph.dependents(e.id)])
+    score = (total - unused) / total if total else 1.0
+    return round(score, 2)

soft_archmap-0.1.0/soft_archmap/analysis/impact.py

@@ -0,0 +1,22 @@
+from collections import defaultdict, deque
+from soft_archmap.core.graph import DependencyGraph
+
+class ImpactAnalyzer:
+    def __init__(self, model):
+        # Build a dependency graph from the model
+        self.graph = DependencyGraph()
+        self.graph.build_from_model(model)
+
+    def analyze(self, target):
+        visited = set()
+        result = []
+
+        def dfs(node):
+            for dep in self.graph.dependents(node):
+                if dep not in visited:
+                    visited.add(dep)
+                    result.append(dep)
+                    dfs(dep)
+
+        dfs(target)
+        return result

soft_archmap-0.1.0/soft_archmap/analysis/metrics.py

@@ -0,0 +1,24 @@
+# analysis/metrics.py
+from soft_archmap.core.graph import DependencyGraph
+
+def compute_metrics(model):
+    """
+    Compute simple architecture metrics.
+    """
+    graph = DependencyGraph()
+    for r in model.relations:
+        graph.add_edge(r.src, r.dst)
+
+    num_modules = sum(1 for e in model.entities.values() if e.type == "module")
+    num_classes = sum(1 for e in model.entities.values() if e.type == "class")
+    num_functions = sum(1 for e in model.entities.values() if e.type == "function")
+    num_relations = len(model.relations)
+    num_cycles = len(graph.find_cycles())
+
+    return {
+        "modules": num_modules,
+        "classes": num_classes,
+        "functions": num_functions,
+        "relations": num_relations,
+        "cycles": num_cycles
+    }

soft_archmap-0.1.0/soft_archmap/analysis/risk.py

@@ -0,0 +1,33 @@
+class RiskEngine:
+    def __init__(self, graph):
+        self.graph = graph
+
+    # -------------------------
+    # CORE RISK SCORE
+    # -------------------------
+    def compute_risk(self, node_id):
+        direct = len(self.graph.dependents(node_id))
+
+        # indirect risk (2-hop approximation)
+        indirect = 0
+        for child in self.graph.dependents(node_id):
+            indirect += len(self.graph.dependents(child))
+
+        # cycle penalty
+        cycles = self._in_cycle(node_id)
+        cycle_penalty = 2 if cycles else 0
+
+        risk_score = (
+            direct * 0.6 +
+            indirect * 0.2 +
+            cycle_penalty * 0.2
+        )
+
+        return round(risk_score, 3)
+
+    # -------------------------
+    # CHECK IF NODE IN CYCLE
+    # -------------------------
+    def _in_cycle(self, node_id):
+        cycles = self.graph.find_cycles()
+        return any(node_id in cycle for cycle in cycles)

soft_archmap-0.1.0/soft_archmap/analysis/top_risk.py

@@ -0,0 +1,45 @@
+from soft_archmap.analysis.risk import RiskEngine
+
+
+# class TopRiskAnalyzer:
+#     def __init__(self, graph):
+#         self.graph = graph
+#         self.risk_engine = RiskEngine(graph)
+
+#     def get_top_risk_modules(self, top_k=10):
+#         scores = []
+
+#         for node in self.graph.nodes():
+#             score = self.risk_engine.compute_risk(node)
+#             scores.append((node, score))
+
+#         # sort by risk descending
+#         scores.sort(key=lambda x: x[1], reverse=True)
+
+#         return {
+#             "top_risk": scores[:top_k]
+#         }
+
+class TopRiskAnalyzer:
+    def __init__(self, model):
+        self.model = model
+        self.graph = model.graph
+        self.engine = RiskEngine(self.graph)
+
+    def get_top_risk_modules(self):
+        results = []
+
+        for node_id, entity in self.model.entities.items():
+
+            # 🚫 SKIP EXTERNAL CODE HERE
+            if entity.type == "external":
+                continue
+
+            score = self.engine.compute_risk(node_id)
+            results.append((node_id, score))
+
+        results.sort(key=lambda x: x[1], reverse=True)
+
+        return {
+            "top_risk": results[:10]
+        }

soft_archmap-0.1.0/soft_archmap/analysis/visualize.py

@@ -0,0 +1,23 @@
+# analysis/visualize.py
+import os
+import subprocess
+import shutil
+
+def visualize_architecture(dot_file, output_file="architecture.png"):
+    """
+    Generate PNG from Graphviz DOT file.
+    Requires 'dot' (Graphviz) installed.
+    """
+    # png_path = os.path.join(output_dir, "architecture.png")
+    if not shutil.which("dot"):
+        print("Graphviz 'dot' not found. Install Graphviz to generate visualization.")
+        return
+
+    try:
+        subprocess.run(
+            ["dot", "-Tpng", dot_file, "-o", output_file],
+            check=True
+        )
+        print(f"✅ Architecture visualization saved to {output_file}")
+    except subprocess.CalledProcessError as e:
+        print(f"Error generating visualization: {e}")