Metadata-Version: 2.4
Name: topological-visibility
Version: 1.2.0
Summary: Deterministic architectural auditing for large codebases. Discover and validate your system's structure.
Author-email: Matrix CR Studio <sales@matrixcr.ai>
License: ALL RIGHTS RESERVED
Project-URL: Homepage, https://matrixcr.ai
Project-URL: Documentation, https://github.com/matrixcr/topological-visibility
Project-URL: Repository, https://github.com/matrixcr/topological-visibility
Project-URL: Issues, https://github.com/matrixcr/topological-visibility/issues
Keywords: architecture,auditing,code-analysis,governance,refactoring,microservices,technical-debt
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Version Control
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Provides-Extra: serve
Requires-Dist: fastapi>=0.110; extra == "serve"
Requires-Dist: uvicorn[standard]>=0.29; extra == "serve"
Requires-Dist: pydantic>=2.0; extra == "serve"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# Topological Visibility System

**4D Architecture Discovery & Audit Tool**

Discover and audit the hidden structure of your codebase across 5 registers: Code, Governance, Data, Knowledge, and Deployment.

## What It Does

The Topological Visibility System automatically maps your architecture across:

1. **Code Register** — All Python source files, imports, exports, dependencies
2. **Governance Register** — Project structure, shops/teams, manifests, policies
3. **Data Register** — Databases, schemas, cardinality, storage footprint
4. **Knowledge Register** — Documentation, structure, cross-references
5. **Deployment Register** — Services, artifacts, deployment status

Then it audits for:
- **Orphans** — Code without governance, data without owners
- **Dependencies** — Import cycles, gravity wells, critical paths
- **Coherence** — Cross-register alignment, consistency
- **Decay** — Trends, drift, breach forecasting
- **Impact** — Blast radius analysis for changes

## Quick Start

### 1. Initialize Your Project

```bash
python -m src.product.cli init --name "MyProject"
```

This creates `topological.yaml` with sensible defaults.

### 2. Run a Full Report

```bash
python -m src.product.cli report --config topological.yaml
```

This produces:
- `data/MyProject_register.json` — Full unified register
- `data/audit_report.json` — Comprehensive audit findings

### 3. Check Health

```bash
python -m src.product.cli health --config topological.yaml
```

Quick status: `HEALTHY` or list of issues.

## Commands

### `topological init`

Create a default `topological.yaml` configuration.

```bash
python -m src.product.cli init --name "MyProject" --output topological.yaml
```

### `topological scan`

Run all discoverers (extract metadata from 5 registers).

```bash
python -m src.product.cli scan --config topological.yaml --output data/register.json
```

Outputs: JSON with all souls, shops, databases, documents, artifacts.

### `topological audit`

Run all auditors (analyze the register).

```bash
python -m src.product.cli audit --config topological.yaml --register data/register.json
```

Outputs: JSON with all audit findings (errors, warnings, info).

### `topological health`

Quick health check (scan + audit, brief output).

```bash
python -m src.product.cli health --config topological.yaml
```

Returns exit code 0 (healthy) or 1 (issues found).

### `topological report`

Full scan + audit + report.

```bash
python -m src.product.cli report --config topological.yaml --output-dir data/
```

Outputs both register and audit report.

## Configuration

Edit `topological.yaml` to customize:

```yaml
project_name: MyProject
root_path: .
description: Topology configuration for MyProject

code_register:
  enabled: true
  root_path: src
  include_patterns:
    - "*.py"
  exclude_patterns:
    - "__pycache__/*"
    - "*.pyc"

governance_register:
  enabled: true
  root_path: shops
  include_patterns:
    - "*.yaml"
    - "*.yml"

data_register:
  enabled: true
  root_path: data
  include_patterns:
    - "*.db"
    - "*.sqlite3"

knowledge_register:
  enabled: true
  root_path: docs
  include_patterns:
    - "*.md"

deployment_register:
  enabled: true
  root_path: ""

auditors:
  enabled: true
  strict_mode: false
  phi_floor: 0.618
  checks:
    unmapped_souls: true
    cycles: true
    orphans: true
    coherence: true
    manifest: true
    decay: true
    impact: true

output_dir: data
output_format: json
verbose: false
```

## Output Formats

### Register (JSON)

Structure:
```json
{
  "metadata": {
    "project_name": "MyProject",
    "root_path": "/path/to/project",
    "scan_timestamp": "2026-05-27T14:02:00",
    "schema_version": "1.0"
  },
  "code_register": {
    "souls": {
      "soul_name": {
        "path": "src/soul_name.py",
        "imports": ["dependency1", "dependency2"],
        "exports": ["function1", "class1"],
        "has_pulse": true,
        "commit_frequency": 0.5,
        "last_update_days_ago": 5
      }
    }
  },
  "governance_register": {
    "shops": {
      "shop_name": {
        "path": "shops/shop_name",
        "souls": ["soul1", "soul2"],
        "phi_score": 0.9,
        "semantic_drift": 0.1
      }
    }
  },
  "data_register": {
    "databases": {
      "data/db.db": {
        "tables": [
          {
            "name": "users",
            "columns": ["id", "name"],
            "row_count": 1000
          }
        ],
        "size_mb": 5.2
      }
    }
  },
  "knowledge_register": {
    "documents": {
      "docs/README.md": {
        "size_bytes": 2500,
        "headings": ["Installation", "Usage"],
        "cross_references": ["src/soul.py", "docs/guide.md"]
      }
    }
  },
  "deployment_register": {
    "artifacts": {
      "service1": {
        "path": "worker/service1",
        "artifact_type": "worker"
      }
    }
  }
}
```

### Audit Report (JSON)

Structure:
```json
{
  "timestamp": "2026-05-27T14:02:00",
  "total_audits": 7,
  "total_findings": 12,
  "errors": 0,
  "warnings": 12,
  "info": 5,
  "is_healthy": true,
  "health_status": "HEALTHY",
  "audit_reports": [
    {
      "name": "Soul Registry (#1)",
      "errors": 0,
      "warnings": 1,
      "info": 0,
      "errors_detail": [],
      "warnings_detail": [
        {
          "code": "SOULS_UNMAPPED",
          "message": "177 souls exist in code but not listed in any SHOP.yaml",
          "affected_items": ["soul1", "soul2"],
          "metadata": {"count": 177}
        }
      ]
    }
  ]
}
```

## Auditors (7 Critical Audits)

### #1: Soul Registry

Creates canonical index of all code-level entities (souls).

**Detects:**
- Unmapped souls (code without governance)
- Missing souls (referenced but don't exist)

### #2: Dependency Auditor

Builds import graph and analyzes dependencies.

**Detects:**
- Cycles (broken architecture)
- Gravity wells (critical dependencies, SPOFs)
- Isolated souls

### #3: Orphan Auditor

Checks for misalignment between code and data.

**Detects:**
- Orphaned data/ directories (no corresponding soul)
- Stateless souls (no corresponding data)

### #4: Coherence Auditor

Cross-register validation.

**Detects:**
- Souls not in governance
- Souls with no data directories
- Shops referencing missing souls
- Docs with broken references

### #5: Manifest Validator

Validates governance manifests (SHOP.yaml, LEDGER.md, STATE.md).

**Detects:**
- Invalid phi scores
- Invalid semantic drift
- Empty LEDGERs

### #6: Decay Forecaster

Analyzes φ-score trends and predicts breach dates.

**Detects:**
- Phi breaches (< 0.618 floor)
- Declining phi scores
- High semantic drift

### #7: Impact Analyzer

Analyzes blast radius for code/governance changes.

**Detects:**
- Critical souls (3+ dependents)
- Large shops (10+ souls)
- Infrastructure change risks

## Use Cases

**1. Architecture Visibility**
```bash
topological report --config topological.yaml
```
Understand your full architecture: what modules exist, who imports what, what data they own.

**2. Governance Auditing**
```bash
topological health --config topological.yaml
```
Quick health check: are all code modules listed in governance? Are LEDGERs current?

**3. Impact Analysis (before refactoring)**
```bash
topological audit --config topological.yaml
# Check "Impact Analyzer" section for blast radius
```
Know which souls are critical before changing them.

**4. Decay Forecasting**
```bash
topological audit --config topological.yaml
# Check "Decay Forecaster" section for breach dates
```
When will your governance φ-scores breach the floor? Plan maintenance.

**5. Orphan Cleanup**
```bash
topological audit --config topological.yaml
# Check "Orphan Auditor" for stale data dirs
```
Which data directories have no corresponding code?

## Example Projects

See `examples/` for configs for:
- Python packages
- Monorepos
- Django projects
- Flask services
- Custom architectures

## Installation

```bash
# As part of matrix-cr-studio
cd matrix-cr-studio
python -m src.product.cli --help

# Or standalone (future)
pip install topological
topological --help
```

## Output

Results are JSON (ready for downstream tools, dashboards, APIs):
- `*_register.json` — Unified architecture model
- `audit_report.json` — Audit findings and metrics

## Philosophy

**Determinism over guessing.** The tool doesn't use ML classifiers or heuristics. It scans actual code, actual configuration, actual databases. Findings are facts, not probabilistic.

**Geometry over sequential.** Instead of reading files line-by-line, you get a unified 5D model (code × governance × data × knowledge × deployment). See the shape of your system.

**Actionable over alarming.** Findings are specific (affected items listed) and auditable (metadata included). No generic warnings.

---

**Built by Matrix CR Studio**  
4D Architecture for High-Stakes Claims
