gitgalaxy 0.1.0__tar.gz

gitgalaxy-0.1.0/LICENSE

@@ -0,0 +1,73 @@
+PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Joe Esquibel (https://github.com/squid-protocol/gitgalaxy)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

gitgalaxy-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: gitgalaxy
+Version: 0.1.0
+Summary: Visualizes codebase complexity as explorable 3D galaxies.
+Author: Joseph Michael Esquibel
+License: PolyForm Noncommercial License 1.0.0
+Project-URL: Homepage, https://gitgalaxy.io
+Project-URL: Source, https://github.com/squid-protocol/gitgalaxy
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# GitGalaxy
+
+Code is art. Logic is art. Systems engineering is art.
+
+GitGalaxy reveals the complexity of codebases as explorable 3D galaxies by using source code as a seed for procedural generative art. It acts as a Rosetta Stone for code complexity, allowing you to visually compare the scale and risk exposure of different projects—from Apollo 11 to the Linux Kernel—under the same set of rules.
+
+> **Note:** This is a condensed version of the full documentation. For the 200-page Architectural Master Blueprint, please visit: [https://github.com/squid-protocol/gitgalaxy](https://github.com/squid-protocol/gitgalaxy)
+
+---
+
+## Quickstart
+
+### 1. Install
+
+```bash
+pip install gitgalaxy
+```
+
+### 2. Scan a Repository
+
+Point the GalaxyScope at any local repository or ZIP archive. The engine runs entirely on your local machine—zero data is transmitted.
+
+```bash
+gitgalaxy /path/to/your/repo
+```
+
+### 3. View the Galaxy
+
+GitGalaxy offers two ways to visualize your 3D architecture, both built on a strict Zero-Trust Privacy Model where your code never leaves your machine.
+
+**Option A: The Web Viewer (Frictionless)**
+Simply drag and drop your generated "your_repo_galaxy.json" file (or a .zip of your raw repository) directly into GitGalaxy.io. All rendering and scanning happens entirely in your browser's local memory.
+
+**Option B: The Local Server (Enterprise & Offline)**
+For teams working behind strict corporate firewalls, you can host the 3D viewer locally. Clone the repository and spin up the included Flask server:
+
+```bash
+git clone https://github.com/squid-protocol/gitgalaxy.git
+cd gitgalaxy
+python app.py
+```
+
+Then open http://localhost:5000 in your browser and drop your JSON file in securely.
+
+## What Does it Measure?
+
+Traditional code analysis tools act like strict linguists. GitGalaxy functions as a sensor grid. We do not assess "Bad Code"; we measure Risk Exposure. By analyzing 9 independent metrics, we procedurally generate a 3D universe where:
+
+* **Stars (Files):** Mass indicates Lines of Code (LOC).
+* **Bioluminescence (Pulse):** Indicates inbound references and popularity.
+* **Satellites (Functions):** Moons orbit their parent stars; orbital reach dictates function length.
+* **Color Overlays:** Instantly highlight Cognitive Load (Purple), Tech Debt (Red), Churn (Orange), and API Exposure (Electric Rose).
+
+## Zero-Trust Architecture
+
+Your code never leaves your machine. GitGalaxy performs 100% of its scanning and vectorization locally.
+
+* **No Data Transmission:** Source code is never transmitted to any API, cloud database, or third-party service.
+* **Ephemeral Memory Processing:** Repositories are unpacked into a volatile memory buffer (RAM) and are automatically purged when the browser tab is closed.
+* **Privacy-by-Design:** Even when using the web-based viewer, the data remains behind the user's firewall at all times.
+
+## License & Copyright
+
+Copyright (c) 2026 Joseph Michael Esquibel
+
+GitGalaxy is released under the PolyForm Noncommercial License 1.0.0. It is completely free for personal use, research, experiment, testing, and hobby projects. Use by educational or charitable organizations is also permitted.
+
+Any commercial use or integration into commercial SaaS products or corporate CI/CD pipelines requires a separate commercial license. Please reach out via gitgalaxy.io to discuss commercial integration.

gitgalaxy-0.1.0/README.md

@@ -0,0 +1,68 @@
+# GitGalaxy
+
+Code is art. Logic is art. Systems engineering is art.
+
+GitGalaxy reveals the complexity of codebases as explorable 3D galaxies by using source code as a seed for procedural generative art. It acts as a Rosetta Stone for code complexity, allowing you to visually compare the scale and risk exposure of different projects—from Apollo 11 to the Linux Kernel—under the same set of rules.
+
+> **Note:** This is a condensed version of the full documentation. For the 200-page Architectural Master Blueprint, please visit: [https://github.com/squid-protocol/gitgalaxy](https://github.com/squid-protocol/gitgalaxy)
+
+---
+
+## Quickstart
+
+### 1. Install
+
+```bash
+pip install gitgalaxy
+```
+
+### 2. Scan a Repository
+
+Point the GalaxyScope at any local repository or ZIP archive. The engine runs entirely on your local machine—zero data is transmitted.
+
+```bash
+gitgalaxy /path/to/your/repo
+```
+
+### 3. View the Galaxy
+
+GitGalaxy offers two ways to visualize your 3D architecture, both built on a strict Zero-Trust Privacy Model where your code never leaves your machine.
+
+**Option A: The Web Viewer (Frictionless)**
+Simply drag and drop your generated "your_repo_galaxy.json" file (or a .zip of your raw repository) directly into GitGalaxy.io. All rendering and scanning happens entirely in your browser's local memory.
+
+**Option B: The Local Server (Enterprise & Offline)**
+For teams working behind strict corporate firewalls, you can host the 3D viewer locally. Clone the repository and spin up the included Flask server:
+
+```bash
+git clone https://github.com/squid-protocol/gitgalaxy.git
+cd gitgalaxy
+python app.py
+```
+
+Then open http://localhost:5000 in your browser and drop your JSON file in securely.
+
+## What Does it Measure?
+
+Traditional code analysis tools act like strict linguists. GitGalaxy functions as a sensor grid. We do not assess "Bad Code"; we measure Risk Exposure. By analyzing 9 independent metrics, we procedurally generate a 3D universe where:
+
+* **Stars (Files):** Mass indicates Lines of Code (LOC).
+* **Bioluminescence (Pulse):** Indicates inbound references and popularity.
+* **Satellites (Functions):** Moons orbit their parent stars; orbital reach dictates function length.
+* **Color Overlays:** Instantly highlight Cognitive Load (Purple), Tech Debt (Red), Churn (Orange), and API Exposure (Electric Rose).
+
+## Zero-Trust Architecture
+
+Your code never leaves your machine. GitGalaxy performs 100% of its scanning and vectorization locally.
+
+* **No Data Transmission:** Source code is never transmitted to any API, cloud database, or third-party service.
+* **Ephemeral Memory Processing:** Repositories are unpacked into a volatile memory buffer (RAM) and are automatically purged when the browser tab is closed.
+* **Privacy-by-Design:** Even when using the web-based viewer, the data remains behind the user's firewall at all times.
+
+## License & Copyright
+
+Copyright (c) 2026 Joseph Michael Esquibel
+
+GitGalaxy is released under the PolyForm Noncommercial License 1.0.0. It is completely free for personal use, research, experiment, testing, and hobby projects. Use by educational or charitable organizations is also permitted.
+
+Any commercial use or integration into commercial SaaS products or corporate CI/CD pipelines requires a separate commercial license. Please reach out via gitgalaxy.io to discuss commercial integration.

gitgalaxy-0.1.0/gitgalaxy/aperture.py

@@ -0,0 +1,315 @@
+import os
+import logging
+import fnmatch
+from pathlib import Path
+from typing import Dict, Any, Set, Optional, TypedDict, Union, List, Tuple
+
+# ==============================================================================
+# GitGalaxy Phase 0.1: Ingestion & Filtering (The Solar Shield)
+# Strategy: v6.2.0 (Bayesian Optics, Intent Overrides & Stateful Caching)
+# Architecture: Lead Shield -> Path Gate -> Intent Gate -> Content Gate
+# ==============================================================================
+
+# --- CUSTOM EXCEPTION HIERARCHY (The Lead Shield) ---
+
+class ApertureError(Exception):
+    """Base class for all errors generated by the Solar Shield filtering process."""
+    pass
+
+class InaccessibleArtifactError(ApertureError):
+    """Raised when an artifact cannot be accessed due to OS permissions or path corruption."""
+    pass
+
+class SaturationError(ApertureError):
+    """Raised when a signal is too dense or minified to be safely refracted by the detector."""
+    pass
+
+class FilterResult(TypedDict):
+    """Structured telemetry returned by the Solar Shield for the Pipeline Orchestrator."""
+    is_in_scope: bool
+    band: str
+    reason: Optional[str]
+    path: str
+    size_bytes: int
+    total_loc: int
+
+
+class ApertureFilter:
+    """
+    Primary solar shield for the telescope. Performs perimeter gating to ensure 
+    only maintainable source code matter reaches the detector. Integrates with 
+    GuideStar's Bayesian 'Intent Locks' to dynamically adjust suppression 
+    thresholds for known, high-priority artifacts.
+    """
+
+    def __init__(
+        self, 
+        root_dir: Union[str, Path], 
+        language_definitions: Dict[str, Any], 
+        aperture_config: Dict[str, Any],
+        parent_logger: Optional[logging.Logger] = None
+    ):
+        # --- TELEMETRY SYNC ---
+        if parent_logger:
+            self.logger = parent_logger.getChild("filter")
+            self.logger.setLevel(parent_logger.level)
+        else:
+            self.logger = logging.getLogger("filter")
+            self.logger.setLevel(logging.INFO)
+        self.root = Path(root_dir).resolve()
+        self.registry = language_definitions
+        
+        # 1. Safely bind the config passed down from the Orchestrator
+        self.config = aperture_config or {}
+        
+        # 2. Extract specific variables from the config payload
+        self.bands = self.config.get("BANDS", {
+            "RADIO": "radio_noise", "MICROWAVE": "binary_debris", 
+            "DARK_MATTER": "unknown_ext", "INFRARED": "saturated", 
+            "VISIBLE": "source_code"
+        })
+        self.black_holes = set(self.config.get("EXCLUDED_DIRECTORIES", set()))
+        self.black_hole_exts = set(self.config.get("BLACKLISTED_EXTENSIONS", set())) 
+        
+        # --- STATE CACHE --- 
+        self._intent_cache: Set[str] = set()
+        
+        self.logger.debug(f"Initializing Solar Shield for sector: '{self.root.name}'...")
+
+        # Optimized lookup sets from Language Definitions
+        self.whitelisted_extensions: Set[str] = set()
+        self.ecosystem_anchors: Set[str] = set()
+        
+        for lang_id, data in self.registry.items():
+            self.whitelisted_extensions.update(data.get('extensions', []))
+            self.ecosystem_anchors.update(data.get('exact_matches', []))
+
+        self.ignore_patterns = self._load_gitignore_patterns()
+        
+        self.logger.info(
+            f"Dispatching Survey Probe to Sector '{self.root.name}' | "
+            f"Tracking {len(self.whitelisted_extensions)} spectral bands."
+        )
+
+    def evaluate_path_integrity(self, file_path: Union[str, Path], has_intent: bool = False) -> Tuple[bool, int, str]:
+        """
+        [PHASE 0 ENTRY POINT]
+        Fast path-only check to build the CensusArray (Radar Walk).
+        Now safely fetches file size to prevent the 0-Byte Dark Matter telemetry bug.
+        
+        Args:
+            file_path: The artifact's path.
+            has_intent: True if the GuideStar mapped this file in a manifest or priority list.
+            
+        Returns:
+            Tuple: (is_valid: bool, size_bytes: int, reason: str)
+        """
+        path_obj = Path(file_path)
+        normalized_path = path_obj.as_posix()
+        _, ext = os.path.splitext(path_obj.name)
+        
+        try:
+            relative_path = path_obj.relative_to(self.root).as_posix()
+        except ValueError:
+            relative_path = normalized_path
+
+        # Safely fetch size before making drop decisions to ensure accurate Dark Matter telemetry
+        try:
+            size_bytes = path_obj.stat().st_size if path_obj.exists() else 0
+        except OSError:
+            size_bytes = 0
+
+        # 0. TIER 0.5: THE ABSOLUTE EXTENSION SHIELD (Impervious to Intent)
+        # Drops SVGs, 3D Models, PDFs, and PGP keys before disk I/O ever happens.
+        if ext.lower() in self.black_hole_exts:
+            reason = f"Blocked (Explicitly Blacklisted Media/Binary Extension: '{ext}')"
+            self.logger.debug(f"{reason}: {relative_path}")
+            return False, size_bytes, reason
+
+        # Resolve intent status against cache
+        active_intent = has_intent or (normalized_path in self._intent_cache)
+        if active_intent:
+            self._intent_cache.add(normalized_path)
+
+        # 1. TIER 1: THE SOLAR SHIELD (Radio Noise)
+        if not self._check_solar_shield(relative_path, has_intent=active_intent):
+            reason = "Blocked (Path Excluded by System Rules, Hidden Directory, or .gitignore)"
+            self.logger.debug(f"{reason}: {relative_path}")
+            return False, size_bytes, reason
+
+        # --- INTENT BYPASS ---
+        # If the file has a GuideStar lock, it bypasses linguistic whitelisting entirely.
+        if active_intent:
+            reason = "Passed (GuideStar Intent Lock Bypassed Tier 2)"
+            self.logger.debug(f"{reason}: {relative_path}")
+            return True, size_bytes, reason
+
+        # 2. TIER 2: THE VISIBLE SPECTRUM (Linguistic Whitelisting)
+        # Rule 2.1: Deep Space Remnants (Spec 2.3.3.B)
+        # We allow extensionless files through without intent to be evaluated by the Shebang Scanner
+        if not ext:
+            reason = "Passed (Extensionless -> Shebang scan required)"
+            self.logger.debug(f"{reason}: {relative_path}")
+            return True, size_bytes, reason
+            
+        # Rule 2.2: Known Ecosystem Anchor or Whitelisted Extension
+        if path_obj.name in self.ecosystem_anchors or ext.lower() in self.whitelisted_extensions:
+            reason = "Passed (Ecosystem Anchor or Whitelisted Ext)"
+            return True, size_bytes, reason
+
+        reason = f"Blocked (Unsupported or Unrecognized Extension: '{ext}')"
+        self.logger.debug(f"{reason}: {relative_path}")
+        return False, size_bytes, reason
+
+    def is_in_scope(self, file_path: Union[str, Path], content: Optional[str] = None, has_intent: bool = False) -> FilterResult:
+        """Runs the 5-tier perimeter gate to validate maintainable code matter."""
+        path_obj = Path(file_path)
+        normalized_path = path_obj.as_posix() 
+        
+        try:
+            relative_path = path_obj.relative_to(self.root).as_posix()
+        except ValueError:
+            relative_path = normalized_path
+
+        # Pull from state to guarantee consistency between Phase 0 and Phase 1 calls
+        active_intent = has_intent or (normalized_path in self._intent_cache)
+
+        result: FilterResult = {
+            "is_in_scope": False,
+            "band": self.bands.get("VISIBLE", "source_code"),
+            "reason": None,
+            "path": normalized_path,
+            "size_bytes": 0,
+            "total_loc": 0
+        }
+
+        try:
+            # --- TIER 0: THE LEAD SHIELD (Resource Guarding) ---
+            # NOTE: Intent cannot override file size or existence checks. Physics are absolute.
+            if not path_obj.exists():
+                raise InaccessibleArtifactError("Artifact missing or path invalid")
+            
+            stats = path_obj.stat()
+            result["size_bytes"] = stats.st_size
+            
+            max_mb = self.config.get("MAX_FILE_SIZE_MB", 10)
+            if stats.st_size > (max_mb * 1024 * 1024):
+                self.logger.warning(f"Resource Guard: Rejected massive file '{relative_path}' ({stats.st_size / (1024 * 1024):.1f} MB)")
+                result["band"] = self.bands.get("INFRARED", "saturated")
+                result["reason"] = f"Blocked (File Size Exceeds Configured Limit: > {max_mb}MB)"
+                return result
+
+            # --- TIER 1 & 2: PATH VALIDATION ---
+            is_valid, size_bytes, reason = self.evaluate_path_integrity(path_obj, has_intent=active_intent)
+            if not is_valid:
+                result["band"] = self.bands.get("RADIO", "radio_noise")
+                result["reason"] = reason
+                result["size_bytes"] = size_bytes
+                return result
+
+            # --- TIER 3 & 4: ARTIFACT INTEGRITY (Content Gate) ---
+            if content is None:
+                self.logger.warning(f"Protocol Violation: Missing content buffer for '{relative_path}'")
+                result["reason"] = "Protocol Violation: Missing content buffer"
+                return result
+
+            integrity = self._check_artifact_integrity(content, relative_path)
+            result["total_loc"] = integrity["loc"]
+            
+            if not integrity["valid"]:
+                result["band"] = integrity["band"]
+                result["reason"] = integrity["reason"]
+                return result
+
+            # --- SUCCESS ---
+            result["is_in_scope"] = True
+            self.logger.debug(f"Aperture Lock: '{relative_path}' safely in scope (LOC: {result['total_loc']}).")
+            return result
+
+        except (InaccessibleArtifactError, PermissionError) as e:
+            self.logger.warning(f"Inaccessible Artifact: '{relative_path}' | {str(e)}")
+            result["band"] = self.bands.get("RADIO", "radio_noise")
+            result["reason"] = f"I/O Exception: {str(e)}"
+            return result
+        except Exception as e:
+            self.logger.error(f"Critical Solar Shield Failure on '{relative_path}': {str(e)}", exc_info=True)
+            result["reason"] = f"Internal Exception: {str(e)}"
+            return result
+
+    def _check_artifact_integrity(self, content: str, rel_path: str) -> Dict[str, Any]:
+        """Inspects the Photon Buffer for corruption or saturation."""
+        report = {"valid": True, "band": self.bands.get("VISIBLE", "source_code"), "reason": None, "loc": 0}
+        
+        # --- TIER 3: THE LEAD SHIELD (Binary Detection) ---
+        # FIX: Removed the [:1024] slice. We must check the entire buffer 
+        # so binary files don't sneak into Visible Stars.
+        if '\x00' in content:
+            self.logger.debug(f"Integrity check failed (Opaque Binary / Null Bytes): {rel_path}")
+            report.update({
+                "valid": False,
+                "band": self.bands.get("MICROWAVE", "binary_debris"),
+                "reason": "Blocked (Binary Format: Null bytes detected during read)"
+            })
+            return report
+
+        # --- TIER 4: INFRARED GATE (Minification & Saturation) ---
+        max_line = self.config.get("MAX_LINE_LENGTH", 500)
+        scan_limit = self.config.get("MINIFICATION_SCAN_LIMIT", 50)
+        
+        lines = content.splitlines()
+        report["loc"] = len(lines)
+
+        for i, line in enumerate(lines):
+            if i < scan_limit:
+                if len(line) > max_line:
+                    self.logger.debug(f"Integrity check failed: '{rel_path}' saturated > {max_line} chars on line {i+1}")
+                    report.update({
+                        "valid": False,
+                        "band": self.bands.get("INFRARED", "saturated"),
+                        "reason": f"Blocked (Minified or Dense Data: Line {i+1} exceeds {max_line} characters)"
+                    })
+                    return report
+            else:
+                break
+        
+        return report
+
+    def _load_gitignore_patterns(self) -> List[str]:
+        """Reads local .gitignore files to identify Radio Noise."""
+        patterns = []
+        ignore_file = self.root / ".gitignore"
+        if ignore_file.exists():
+            try:
+                with ignore_file.open('r', encoding='utf-8') as f:
+                    for line in f:
+                        line = line.strip()
+                        if line and not line.startswith('#'):
+                            patterns.append(line)
+            except (IOError, OSError) as e:
+                self.logger.warning(f"Failed to load .gitignore rules: {e}")
+        return patterns
+
+    def _check_solar_shield(self, rel_path: str, has_intent: bool = False) -> bool:
+        """Determines if the path sits in a blocked or ignored sector."""
+        parts = rel_path.split('/')
+        
+        for part in parts:
+            if part in self.black_holes:
+                return False
+            
+            # Hidden Path Suppression (e.g., .github/, .vscode/)
+            if part.startswith('.') and part not in self.ecosystem_anchors:
+                # If GuideStar explicitly mapped a dotfile (e.g., .hooks/pre-commit), lift the blockade.
+                if has_intent:
+                    self.logger.debug(f"Solar Shield VIP Pass: Bypassing hidden-path block for intent-locked artifact '{part}'")
+                    continue
+                self.logger.debug(f"Blocked by Hidden Path Component '{part}': {rel_path}")
+                return False
+        
+        for pattern in self.ignore_patterns:
+            if pattern.endswith('/') and any(fnmatch.fnmatch(p + '/', pattern) for p in parts):
+                return False
+            if fnmatch.fnmatch(rel_path, pattern) or fnmatch.fnmatch(parts[-1], pattern):
+                return False
+        
+        return True