gitgalaxy 2.0.5__tar.gz → 2.0.8__tar.gz

gitgalaxy-2.0.8/.github/ISSUE_TEMPLATE/parsing_discrepancy.yml

@@ -0,0 +1,50 @@
+name: 🐛 Report a Parsing/blAST Discrepancy
+description: Report an issue where the blAST engine misidentified or failed to parse a repository structure.
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a discrepancy! Please provide the context we need to reproduce the issue.
+  - type: input
+    id: repo_link
+    attributes:
+      label: Repository Link
+      description: Provide a link to the public repository you were scanning (e.g., GitHub, GitLab URL).
+      placeholder: https://github.com/torvalds/linux
+    validations:
+      required: true
+  - type: dropdown
+    id: viewer_used
+    attributes:
+      label: Which Observatory viewer were you using?
+      description: Help us identify if this is a backend parsing issue or a frontend visual constraint.
+      options:
+        - GitGalaxy.io (Web Viewer)
+        - Airgap Observatory (Local Server)
+        - CLI Only (Did not use a visualizer)
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Description of the Discrepancy
+      description: What did GitGalaxy report, and what should it have been? (e.g., "Flagged X files as Python, but they are actually Cython.")
+    validations:
+      required: true
+  - type: textarea
+    id: custom_standards
+    attributes:
+      label: Custom standards.py (If Applicable)
+      description: If you are using a custom `standards.py`, please paste its contents here, or drag and drop the file into this box.
+      render: python
+    validations:
+      required: false
+  - type: input
+    id: contact
+    attributes:
+      label: Contact Info
+      description: An email or Discord handle where we can reach you if we have questions about this specific codebase.
+    validations:
+      required: false

gitgalaxy-2.0.8/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  # 1. Keep GitHub Actions up to date
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "security"
+      - "github-actions"
+
+  # 2. Keep Python dependencies up to date
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "security"
+      - "python"

gitgalaxy-2.0.8/.github/pull_request_template.md

@@ -0,0 +1,9 @@
+### Description of Structural Changes
+### Visual Observatory Testing
+- [ ] I tested the output JSON on **GitGalaxy.io** OR the **Airgap Observatory**.
+- [ ] Flexbox constraints, HUD elements, and 3D rendering remain intact.
+
+### The Differential Scan Acknowledgement
+- [ ] I understand that my PR will be subjected to a Full Differential Scan.
+- [ ] I have provided the link to the specific repository this PR addresses so it can be tested alongside the 80-repo calibrated baseline.
+- [ ] I believe these changes will measurably improve the engine's Accuracy, Speed, Utility, or Ethos without causing regressions.

gitgalaxy-2.0.8/.github/workflows/codeql.yml

@@ -0,0 +1,40 @@
+name: "CodeQL Security Scan"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '0 12 * * 1' # Runs every Monday at 12:00 UTC
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+        # If you have specific queries you want to run, you can specify them here.
+        # "security-extended" adds deeper vulnerability hunting.
+        queries: security-extended,security-and-quality
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"

gitgalaxy-2.0.8/.github/workflows/deploy-docs.yml

@@ -0,0 +1,37 @@
+name: Deploy Museum of Code Docs
+
+on:
+  push:
+    branches:
+      - main # Triggers the action when you push to the main branch
+  workflow_dispatch: # Allows you to manually trigger the build from the GitHub UI
+
+# Grants the action permission to push the built site to the gh-pages branch
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required for git info/history (like last updated timestamps)
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install Dependencies
+        # Installs Material theme and the PyMdown extensions required by your mkdocs.yml
+        run: pip install mkdocs-material pymdown-extensions
+
+      - name: Build and Deploy Docs
+        run: mkdocs gh-deploy --force

gitgalaxy-2.0.8/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Build and Publish to PyPI
+    runs-on: ubuntu-latest
+    
+    # This matches the environment name you set in PyPI
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gitgalaxy
+
+    # This specific permission is REQUIRED for Trusted Publishing
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # <--- ADD THIS so it downloads your Git tags!
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Install build tools
+      run: python -m pip install --upgrade pip build
+
+    - name: Build the wheel and source distribution
+      run: python -m build
+
+    - name: Publish package to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

gitgalaxy-2.0.8/.github/workflows/smoke-test.yml

@@ -0,0 +1,66 @@
+name: GitGalaxy Smoke Tests
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  smoke-test:
+    runs-on: ${{ matrix.os }}
+    env:
+      PYTHONUTF8: "1" # <--- FIX 1: Forces Windows to render emojis without crashing
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        
+    steps:
+    - name: Check out repository code
+      uses: actions/checkout@v6
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install macOS dependencies (OpenMP for XGBoost)
+      if: runner.os == 'macOS'
+      run: brew install libomp
+
+    - name: Install dependencies
+      shell: bash
+      run: |
+        python -m pip install --upgrade pip setuptools wheel
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+        pip install PyYAML networkx tiktoken pandas xgboost pytest flake8
+        pip install --no-build-isolation -e . # <--- FIX 2: Bypasses the pip build bubble
+        
+    - name: Global Syntax Sweep (Flake8)
+      run: |
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+
+    - name: Smoke Test - Core Engine
+      # Using the -m flag is the safest way to run modules inside a package
+      run: python -m gitgalaxy.galaxyscope --help
+
+    - name: Smoke Test - Legacy Refractor Controller
+      run: python -m gitgalaxy.cobol_refractor_controller --help
+
+    - name: Smoke Test - Java Spring Forge Controller
+      run: python -m gitgalaxy.cobol_to_java_controller --help
+
+    - name: Smoke Test - SBOM Generator
+      run: python -m gitgalaxy.tools.compliance.sbom_generator --help
+
+    - name: Smoke Test - Supply Chain Firewall
+      run: python -m gitgalaxy.tools.supply_chain_security.supply_chain_firewall --help
+
+    - name: Smoke Test - API Network Map
+      run: python -m gitgalaxy.tools.network_auditing.full_api_network_map --help
+
+    - name: Golden Record Integration Test (Pytest)
+      run: |
+        pytest tests/ -v

gitgalaxy-2.0.8/.gitignore

@@ -0,0 +1,73 @@
+# ==========================================
+# SECURITY / SECRETS (CRITICAL)
+.env
+.env.*
+*.pem
+*.key
+
+# PYTHON, FLASK & VIRTUAL ENVIRONMENTS
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+venv/
+env/
+.venv/
+flask_session/
+
+# PYPI PACKAGING & BUILD ARTIFACTS
+build/
+dist/
+*.egg-info/
+
+# TESTING & LINTING (NEW)
+.coverage
+htmlcov/
+.mypy_cache/
+
+# LOGS & DATABASES
+*.log
+gitgalaxy_dropped_orders.log
+*.sqlite3
+*.sqlite3-journal
+
+# FRONTEND & NODE
+node_modules/
+tailwindcss
+
+# OS & EDITOR FILES
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+*.swp
+*~
+*.bak
+.~lock.*
+
+# PROJECT-SPECIFIC SCRIPTS & DRAFTS
+get_ids.py
+get_shop.py
+histogram_matcher.py
+archive/
+*.odt
+
+# GITGALAXY HEAVY DATA
+data/
+museum/
+museum_2/
+*.json
+*_llm.md
+venvs/
+
+# Local data mounts
+data/
+museum/
+docs_build/
+updated_results/
+utilities/
+# Ignore local data symlinks
+site/museum/
+museum/
+updated_results_expanded_story/
+updated_results_2/

gitgalaxy-2.0.8/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing to GitGalaxy
+
+First off, thank you for considering contributing to GitGalaxy! The blAST engine is essentially a tunable scientific instrument, and calibrating it across the vast ecosystem of open-source software requires a community effort.
+
+Whether you are reporting a taxonomic discrepancy, refining the parsing engine, or expanding the documentation, your input helps map the structural DNA of software more accurately.
+
+## 🧬 The blAST Philosophy
+
+Before diving in, please remember that GitGalaxy treats code as a living organism. The blAST engine evaluates structural logic and behavioral genetic markers, not just rigid syntax. 
+
+Sometimes, what appears to be a traditional parsing error might actually be blAST intentionally flagging a structural anomaly or a dense risk exposure. Please keep this in mind when reporting issues or proposing changes to the sequencing algorithms.
+
+---
+
+## 🔬 The Differential Scan (How We Review Pull Requests)
+
+We do not merge structural backend changes based solely on subjective code review. GitGalaxy operates at hyper-scale, and every change to the parsing logic has cascading effects.
+
+When you submit a Pull Request that alters the blAST engine, your candidate changes will be subjected to a **Full Differential Scan**. 
+
+* **The Control + Variable Test:** We run your branch against our calibrated baseline of ~80 massive open-source repositories, **plus** the specific repository your PR is designed to address.
+* **Before and After:** We perform a strict comparison of the engine's output before and after your rule update across this entire dataset (80 + 1). This ensures your addition resolves the target discrepancy without degrading the established baseline.
+* **The Metrics:** The output is assessed strictly on four vectors: **Accuracy, Speed, Utility, and Ethos.**
+* Only changes that are mathematically and practically *measurably better* across the broader ecosystem will be incorporated.
+
+---
+
+## 🛠️ Submitting Pull Requests
+
+To ensure your contribution integrates smoothly into the blAST ecosystem:
+
+1. **Fork and Branch:** Create a feature branch from `main` (`git checkout -b feature/your-feature-name`).
+2. **Maintain the Contract:** Ensure that any backend changes to the CLI do not break the universal JSON contract expected by the frontend Observatory. 
+3. **Test Visually:** Run your newly generated `_galaxy.json` through either **[GitGalaxy.io](https://gitgalaxy.io)** or your local **Airgap Observatory** to verify that visual rendering and flexbox constraints remain intact. Whichever is more convenient for you is fine.
+4. **Document:** If you are adding new language phenotypes or altering the parsing logic, please update the Taxonomical Equivalence Map in the wiki.
+5. **Submit:** Open a PR with a clear title. Explain the *why* behind your structural changes, not just the *what*. Be sure to include the link to the target repository so we can include it in the Differential Scan.
+
+---
+
+## 🐛 Reporting Discrepancies
+
+If the galaxyscope misidentifies a repository's structure or fails to parse a specific file phenotype, please use our **[Parsing Discrepancy Form](https://github.com/squid-protocol/gitgalaxy/issues/new/choose)**. 
+
+To help us reproduce the issue with quantitative precision, you will be asked to provide:
+* A direct link to the public repository being scanned.
+* The Observatory viewer you were using (GitGalaxy.io or Airgap Observatory).
+* A clear description of the expected vs. actual output.
+* The contents of your custom `standards.py` file (if applicable).
+* Contact information for follow-up questions.
+
+---
+
+## 🛡️ Security Vulnerabilities
+
+If you discover a vulnerability within GitGalaxy itself (e.g., a way to bypass the local sandbox or an issue in the Airgap Observatory), **do not open a public issue.** Please reach out directly via the contact portal at [GitGalaxy.io](https://gitgalaxy.io) so the vulnerability can be patched securely before public disclosure.
+
+---
+
+## 📜 Licensing Reminder
+
+GitGalaxy is released under the **PolyForm Noncommercial License 1.0.0**. By contributing to this repository, you agree that your contributions will be licensed under these same terms. 
+
+*Note: This tool is free for research, education, testing, and hobby projects. Any commercial use or integration into commercial SaaS products or corporate CI/CD pipelines requires a separate commercial license.*

{gitgalaxy-2.0.5/gitgalaxy.egg-info → gitgalaxy-2.0.8}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: gitgalaxy
-Version: 2.0.5
-Summary: An AST-free, zero-trust static analysis engine for mapping architectural risk, securing CI/CD pipelines, and modernizing legacy monoliths.
+Version: 2.0.8
+Summary: An AST-free, LLM-free zero-trust static analysis engine for mapping architectural risk, securing CI/CD pipelines, and modernizing legacy monoliths.
 Author: Joe Esquibel
 Project-URL: Homepage, https://gitgalaxy.io
 Project-URL: Documentation, https://squid-protocol.github.io/gitgalaxy/
@@ -108,6 +108,33 @@ Point the GalaxyScope at any local repository or ZIP archive. The engine runs en
 galaxyscope /path/to/your/local/repo
 ```
 
+### 3. GitHub Actions CI/CD Integration
+
+GitGalaxy can be integrated directly into your GitHub Actions pipeline for automated DevSecOps auditing, Zero-Trust SBOM generation, or Pre-Commit firewalls. 
+
+Create a file in your repository at `.github/workflows/gitgalaxy-scan.yml`:
+
+```yaml
+name: GitGalaxy Security Audit
+
+on:
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  gitgalaxy-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Run GitGalaxy Supply Chain Firewall
+        uses: squid-protocol/gitgalaxy@main
+        with:
+          tool: 'supply-chain-firewall' # Options: galaxyscope, zero-trust-sbom, pii-leak-hunter, etc.
+          target: '.'
+```
+
 ---
 
 ### [GitGalaxy Core Analysis Engine](docs/wiki/01-project-overview.md)

{gitgalaxy-2.0.5 → gitgalaxy-2.0.8}/README.md

@@ -85,6 +85,33 @@ Point the GalaxyScope at any local repository or ZIP archive. The engine runs en
 galaxyscope /path/to/your/local/repo
 ```
 
+### 3. GitHub Actions CI/CD Integration
+
+GitGalaxy can be integrated directly into your GitHub Actions pipeline for automated DevSecOps auditing, Zero-Trust SBOM generation, or Pre-Commit firewalls. 
+
+Create a file in your repository at `.github/workflows/gitgalaxy-scan.yml`:
+
+```yaml
+name: GitGalaxy Security Audit
+
+on:
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  gitgalaxy-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Run GitGalaxy Supply Chain Firewall
+        uses: squid-protocol/gitgalaxy@main
+        with:
+          tool: 'supply-chain-firewall' # Options: galaxyscope, zero-trust-sbom, pii-leak-hunter, etc.
+          target: '.'
+```
+
 ---
 
 ### [GitGalaxy Core Analysis Engine](docs/wiki/01-project-overview.md)

gitgalaxy-2.0.8/action.yml

@@ -0,0 +1,61 @@
+name: 'GitGalaxy Scanner'
+description: 'High-velocity, AST-free DevSecOps scanner for zero-trust CI/CD, SBOMs, secret detection, and supply chain security.'
+branding:
+  icon: 'shield'
+  color: 'purple'
+
+inputs:
+  tool:
+    description: >
+      The GitGalaxy command to execute. 
+      Options: galaxyscope, blast, vault-sentinel, supply-chain-firewall, xray-inspector, zero-trust-sbom, pii-leak-hunter, terabyte-log-scanner, api-network-map.
+    required: true
+    default: 'galaxyscope'
+  target:
+    description: 'The directory or file path to scan.'
+    required: true
+    default: '.'
+  args:
+    description: 'Any additional CLI arguments to pass to the tool (e.g., --output json, --paranoid).'
+    required: false
+    default: ''
+  version:
+    description: 'The version of GitGalaxy to install from PyPI. Defaults to latest.'
+    required: false
+    default: 'latest'
+  full_precision:
+    description: 'Opt-in to install heavy physics engines (networkx, tiktoken, xgboost) for Blast Radius and ML Threat Inference.'
+    required: false
+    default: 'false'
+
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+
+    - name: Install GitGalaxy
+      shell: bash
+      run: |
+        if [ "${{ inputs.version }}" = "latest" ]; then
+          echo "Installing latest GitGalaxy from PyPI..."
+          pip install gitgalaxy
+        else
+          echo "Installing GitGalaxy version ${{ inputs.version }}..."
+          pip install gitgalaxy==${{ inputs.version }}
+        fi
+        
+        if [ "${{ inputs.full_precision }}" = "true" ]; then
+          echo "Unlocking Full Precision Mode..."
+          pip install networkx tiktoken xgboost pandas numpy
+        else
+          echo "Running in ultra-fast Zero-Dependency Mode."
+        fi
+
+    - name: Execute GitGalaxy Tool
+      shell: bash
+      run: |
+        echo "Running: ${{ inputs.tool }} ${{ inputs.target }} ${{ inputs.args }}"
+        ${{ inputs.tool }} ${{ inputs.target }} ${{ inputs.args }}

gitgalaxy-2.0.8/gitgalaxy/README.md

@@ -0,0 +1,72 @@
+# GitGalaxy: The Core Engine & GalaxyScope Orchestrator
+
+[![Architecture](https://img.shields.io/badge/Architecture-blAST_Engine-00BFFF.svg)](#)
+[![Velocity](https://img.shields.io/badge/Velocity-40k%2B_LOC%2Fsec-00C957.svg)](#)
+[![CLI](https://img.shields.io/badge/Interface-GalaxyScope_CLI-8A2BE2.svg)](#)
+
+Welcome to the internal source code for the **GitGalaxy Core Engine**. 
+
+This directory contains the central orchestrator—**GalaxyScope**—alongside the core physics, optical routing, and mathematical heuristics that power the entire system. If you are a developer looking to contribute, understand the pipeline, or run the primary CLI, here is your architectural map.
+
+### 🗺️ The Developer Map (How the Pipeline Flows)
+
+When you trigger the `galaxyscope` command, the data flows through these five physical directories:
+
+* **`/core/` (The Frontline):** The optical routing layer. Contains the [Aperture Filter](https://squid-protocol.github.io/gitgalaxy/02-03-aperture-filter/) and [The Prism](https://squid-protocol.github.io/gitgalaxy/02-07-the-prism/), which break down source code into structural signals, separating executable logic from ghost mass (comments) and inert binaries.
+* **`/physics/` (The Math):** The heuristics engine. Contains the [Signal Processor](https://squid-protocol.github.io/gitgalaxy/02-09-signal-processing/) and [Neural Auditor](https://squid-protocol.github.io/gitgalaxy/02-19-neural-auditor/), which apply GitGalaxy mathematics to score O(N) complexity, topological blast radius, and state flux without using ASTs.
+* **`/recorders/` (The Exporters):** The translation layer. Converts the internal state maps into highly relational [SQLite Databases](https://squid-protocol.github.io/gitgalaxy/02-21-record-keeper/), AI-agent JSON tickets, and the final 3D WebGPU payload.
+* **`/security/` (The Sentinel):** The zero-trust validation layer. Contains the [Security Lens](https://squid-protocol.github.io/gitgalaxy/02-06-security-lens/) responsible for intercepting embedded malware, hardcoded secrets, and logic bombs on the fly.
+* **`/tools/` (The Spokes):** The enterprise automation layer. Contains specialized controllers for CI/CD pipelines—like the [Supply Chain Firewall](https://squid-protocol.github.io/gitgalaxy/04-03-supply-chain-firewall/) and [PII Leak Hunter](https://squid-protocol.github.io/gitgalaxy/04-06-pii-leak-hunter/)—that consume the core engine's telemetry.
+
+---
+
+### ⚡ Performance Showcase: NVDA (NonVisual Desktop Access)
+
+To demonstrate the GalaxyScope orchestrator's capability on complex, cross-language system architecture, we unleashed it on **NVDA**, the open-source Windows screen reader. 
+
+Because NVDA relies heavily on bridging Python application logic with low-level C++ system hooks, it requires advanced polyglot dependency mapping. The blAST engine successfully parsed the mixed-language architecture, analyzing **236,754 lines of code** in just **5.59 seconds** (a velocity of 42,357 LOC/sec). 
+
+Crucially, during the import resolution phase, the Air-Gapped Dependency Radar successfully intercepted a structural naming collision (`fstream` vs `sstream`), proving the real-time typosquatting defenses are fully operational without relying on cloud APIs.
+
+> **Note on False Positives:** Because `fstream` and `sstream` are both standard C++ libraries, this specific flag is a false positive. To prevent the engine from halting on trusted internal libraries, contributors can whitelist them by adding them to the global `approved_imports.json` registry (see [GitGalaxy Config](https://squid-protocol.github.io/gitgalaxy/06-01-gitgalaxy-config/)).
+
+![NVDA Processing Demo](../../docs/wiki/assets/nvda_processing.gif)
+
+```text
+[INFO] PASS_1.5: Running Air-Gapped Typosquatting & Dependency Confusion Radar...
+[CRITICAL] 🚨 TYPOSQUATTING DETECTED: 'fstream' in nvdaHelper/vbufBase/storage.cpp closely matches anchor 'sstream'!
+[WARNING] Intercepted 1 typosquatting attempts via repository baseline analysis.
+...
+[INFO] --- MISSION_SUCCESS: 849 files mapped in 5.59s ---
+[INFO] --- ENGINE_TELEMETRY: Processed 236,754 lines of code at 42,357 LOC/s ---
+```
+
+---
+
+### 🛠️ Local Development & GalaxyScope Execution
+
+If you are modifying the internal physics or optical routing, it is highly recommended to install the package in editable mode so your CLI commands instantly reflect your local code changes.
+
+From the **root directory** of the repository, run:
+```bash
+pip install -e .
+```
+
+Once installed, you can trigger the main orchestrator globally from your terminal. This command runs the full [Data Pipeline](https://squid-protocol.github.io/gitgalaxy/02-01-pipeline-overview/) and outputs the final artifact.
+```bash
+galaxyscope /path/to/test/repo --debug
+```
+
+Before submitting a Pull Request, ensure your changes do not skew the core baseline risk equations by running the test suite:
+```bash
+python3 -m unittest discover tests/
+```
+
+---
+### 🌌 Deep Dive into the Pipeline Architecture
+To fully understand how GalaxyScope processes data, maps files, and applies risk exposures, explore the official documentation:
+
+* 📖 **[GalaxyScope CLI Reference](https://squid-protocol.github.io/gitgalaxy/01-02-galaxyscope-cli-reference/)** (Flags, outputs, and behaviors)
+* 📖 **[The Data Pipeline Overview](https://squid-protocol.github.io/gitgalaxy/02-01-pipeline-overview/)** (Step-by-step breakdown of the runtime)
+* 📖 **[Risk Exposures & Methodology](https://squid-protocol.github.io/gitgalaxy/08-01-methodology/)** (The math behind the heuristics)
+* 🪐 **[Return to the Main GitGalaxy Hub](https://github.com/squid-protocol/gitgalaxy)**

gitgalaxy-2.0.8/gitgalaxy/core/README.md

@@ -0,0 +1,44 @@
+# GitGalaxy: Core Lexical Parsing & Topology Engine
+
+[![Core](https://img.shields.io/badge/Core-Lexical_Parsing-00BFFF.svg)](#)
+[![Velocity](https://img.shields.io/badge/Velocity-Zero_AST_Overhead-00C957.svg)](#)
+[![Architecture](https://img.shields.io/badge/Architecture-Structural_Extraction-8A2BE2.svg)](#)
+
+This directory contains the primary ingestion, lexical tokenization, and topological mapping layers for the **blAST Engine**.
+
+These files form the core ingestion pipeline. They are responsible for reading raw source code from disk, filtering out irrelevant noise (like massive minified files or `.git` directories), slicing the code into measurable architectural components, and wiring the mathematical network graph.
+
+> **⚠️ Configuration Warning:** Do not modify these core files to tune the engine's behavior. Almost all variables, thresholds, language regexes, and mathematical tuning parameters have been abstracted to the **[Standards Registry](../standards/README.md)**. If you need to tweak risk curves or add a language, do it there.
+
+### 🗺️ The Architecture
+
+Each file in this core represents a discrete phase in the GitGalaxy ingestion pipeline. Read the official documentation links for deep dives into the underlying mathematics.
+
+* **`aperture.py` (The Boundary Filter):** The primary perimeter gate. It enforces Zero-Trust ingestion rules, blocking steganography, minified blobs, and infrastructure directories before they consume system memory.
+  * 📖 **[Read the Aperture Filter Specs](https://squid-protocol.github.io/gitgalaxy/02-03-aperture-filter/)**
+
+* **`guidestar_lens.py` (The Metadata Resolver):** The contextual intelligence module. It parses standard project manifests (`package.json`, `Cargo.toml`), resolves explicit linguistic overrides via `.gitattributes`, and hunts for evasion tactics (like force-includes) hidden in `.gitignore`.
+  * 📖 **[Read the GuideStar Protocol Specs](https://squid-protocol.github.io/gitgalaxy/02-04-guidestar-protocol/)**
+
+* **`prism.py` (The Lexical Tokenizer):** The structural separator. It surgically separates human intent (documentation/comments) from structural execution logic across multiple syntax families, all while safely preserving complex string literals.
+  * 📖 **[Read the Prism Optics Specs](https://squid-protocol.github.io/gitgalaxy/02-07-the-prism/)**
+
+* **`detector.py` (The Function Slicer & Spatial Engine):** The architectural extractor. It splices files into discrete functions, calculates Big-O algorithmic nesting depth, tracks recursive functions, and assigns exact 3D coordinates using deterministic fractal distribution algorithms.
+  * 📖 **[Read the Detector Mechanics](https://squid-protocol.github.io/gitgalaxy/02-08-the-detector/)**
+
+* **`network_risk_sensor.py` (The Topology Mapper):** The mathematical routing layer. It wires the ingested files into a directed graph, executing PageRank mathematics to determine absolute Blast Radius, betweenness centrality, and ecosystem roles (Producer vs. Consumer).
+  * 📖 **[Read the Network Risk Sensor Specs](https://squid-protocol.github.io/gitgalaxy/02-16-network-risk-sensor/)**
+
+* **`state_rehydrator.py` (The Cache Manager):** The incremental differential scanner. It extracts the previous temporal state from the SQLite database and rehydrates it directly into RAM, enabling ultra-fast differential delta scanning for CI/CD pipelines.
+  * 📖 **[Read the State Rehydrator Specs](https://squid-protocol.github.io/gitgalaxy/02-22-state-rehydrator/)**
+
+<br><br>
+
+---
+
+### 🌌 Powered by the blAST Engine
+
+This documentation is part of the [GitGalaxy Ecosystem](https://github.com/squid-protocol/gitgalaxy), an AST-free, LLM-free heuristic knowledge graph engine.
+
+* 🪐 **[Explore the GitHub Repository](https://github.com/squid-protocol/gitgalaxy)** for code, tools, and updates.
+* 🔭 **[Visualize your own repository at GitGalaxy.io](https://gitgalaxy.io/)** using our interactive 3D WebGPU dashboard.