Wythe

Why (?) → Therefore (∴) — Generalizable 3-tier architecture verifier, cross-boundary lineage solver, interactive 3D WebGL latticework visualizer, and fail-closed CI gate built around three masonry wythe invariants:

1. Database holds truth — Relational schemas (PostgreSQL, MySQL, SQLite via SQLAlchemy 2.0 + Alembic, Prisma, Drizzle ORM, Django ORM, Rust sqlx/Diesel/SeaORM, or raw SQL DDL/sqlc + optional read-only catalog probes) own domain policy, thresholds, temporal validity, and write-lane guards, while Redis keyspaces and worker queues are modeled explicitly as ephemeral stores/lanes rather than durable shadow truth.
2. Backend manipulates truth — Services, background workers, solvers, and routers (Python/FastAPI, TypeScript/Node/Express/Hono/Fastify/NestJS/Next.js/SvelteKit, Python/Django/DRF/Ninja, Go net/http/chi/gin/echo, Rust axum/actix-web/rocket/Tauri) execute mechanisms over database rows behind explicit transactional service/SQL doors without embedding shadow policy literals or host-clock drift.
3. Frontend displays truth — UI surfaces (Next.js, React/Vite/TanStack Router/Remix, Vue 3/Nuxt, Svelte 5/SvelteKit, Rust WASM Leptos/Dioxus/Yew + Tauri invoke()) bind to typed contracts, centralized clock utilities, and WCAG-accessible markup without inventing client-side policy maps or unbacked HTTP/IPC calls.

Wythe supports 19 stack profiles via --profile auto (1 production-dogfooded Tier-1 profile + 17 experimental profiles + 1 planned slot), pairs Python's native ast with an optional Tree-sitter CST grammar engine (wythe[treesitter] for TypeScript/TSX, JavaScript, Rust, and Go), traces background worker & scheduled beat queues (Celery / Beat, BullMQ, Asynq), enforces WCAG accessibility semantics (DISP-005), renders both Simple Solids and 120 fps Breathing Atomic Wythe Polyhedra (with adaptive System | Dark | Light polarity and custom user palettes), and self-dogfoods its own 3-tier codebase (wythe gate --strict wythe passes with zero blocking and zero warning findings).

Instant Usage (uvx / uv)

Run Wythe directly from PyPI (wythe) without polluting project dependencies (add [treesitter] to enable prebuilt Tree-sitter CST wheels for TS/TSX, JS, Rust, and Go):

# Instant CLI gate & lineage scan directly from PyPI
uvx "wythe[treesitter]" scan /path/to/repo
uvx "wythe[treesitter]" diff /path/to/repo --base origin/main
uvx "wythe[treesitter]" gate --strict /path/to/repo

# Launch single-port API + interactive 3D WebGL UI on http://127.0.0.1:8780 (no Node.js runtime needed)
uvx "wythe[treesitter]" serve /path/to/repo

# Or install persistently as an isolated CLI tool
uv tool install "wythe[treesitter]"
wythe serve .

GitHub Actions Integration

Pin an explicit release tag (do not track unpinned branches if you want zero-surprise builds):

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- uses: Euda1mon1a/wythe@v0.1.3
  with:
    mode: diff
    base-ref: origin/main
    sarif-file: wythe.sarif.json

Persisted Rule Catalog (atlas_rule_policies)

Rule severity, enablement, gate-blocking behavior, and effective-date windows live in database truth (atlas_rule_policies) and round-trip cleanly to Git via .wythe/governance.json:

How a frontend call with no matching route is classified. A call served by the frontend's own Next.js route.ts / pages/api handler is not a backend call and is not reported. A path built at runtime that could match real routes is DISP-006. On the typescript-nextjs and typescript-react display adapters, Wythe follows imports per exported symbol from entry pages/layouts/roots (honoring tsconfig path aliases, barrels, re-exports, and dynamic imports); a call in a symbol nothing reaches is DISP-007. Everything else is DISP-004, and its detail names the page/entry trail that reaches it. When the analysis cannot tell, it treats the call as reachable, so a real defect is never demoted to a warning by a parsing gap. Other display profiles keep DISP-004 for every unmatched call.

Separate databases and migration DDL. SQLAlchemy models on a second declarative base (their own metadata, often another database or schema) are not checked for drift against the primary schema and are listed in the scan notes. Alembic upgrade() DDL is read from literals, module-level constants (including f-strings), and helper functions it calls, in down_revision order, so a table a later revision drops is no longer counted as created.

Reachability and removal decisions. With the Tree-sitter extra, a lazy import such as import('./widgets').then(m => m.Chart) reaches the selected export while retaining barrel dependencies and import-time initializers. Unknown export selectors conservatively retain all exports; runtime-selected module paths are explicitly unresolved. Scan notes record these distinctions, and additional import dependencies appear as declared edges in the existing blast-radius graph. DISP-007 keeps inactive broken calls visible. A small blast radius or a missing caller is evidence for review, not proof that deletion is safe: check external entry points, registration side effects and the relevant build/tests before removing code or reconnecting its useful behavior. Without a usable CST, import execution stays conservative.

Python services and operational declarations (experimental). The python-services profile maps Python imports, literal importlib targets and package initializers outside an app/ layout, shell script references, launchd commands, and JSON command fields under config/ or configs/. It also recognizes literal deployment constructors whose first fields are repo_path and live_path, including source-to-installed-path renames. These are declared edges, not proof of admission, installation or execution. Module summaries distinguish source references, deployment-only references, and no discovered references; none certifies safe deletion. Missing deployment source files and invalid launchd commands are review warnings. Coverage notes name exclusions, parse failures and unresolved dynamic imports. This profile does not analyze UI/custom HTTP routes, evaluate job eligibility, execute installers, or query running services. Use wythe scan /path/to/services --profile python-services and inspect the coverage notes before interpreting a passing gate.

Deletion and rename diffs. wythe diff resolves the requested base to an exact commit and scans its committed files in a temporary directory, without checking out or executing target code. It traverses the base and current graphs separately, retaining removed nodes, their old callers and import-time dependencies. Renames include both paths. New violation counts still use current-side changed lines. PASS means the diff gate found no blocking findings on those lines; it does not certify safe deletion. Invalid bases exit with code 2. If the base cannot be reconstructed (including unresolved symlinks or submodules), JSON and SARIF explicitly report incomplete evidence and the CLI exits 2.

CLI Commands

# Scan any supported full-stack repository (--profile auto)
wythe scan /path/to/repo --json report.json --sarif report.sarif.json

# Optional metadata-only live DB & Redis keyspace probes (zero row or value reads;
# PostgreSQL table names come from pg_catalog, so a least-privilege role still sees every table)
wythe scan /path/to/repo \
  --dsn "postgresql://readonly@127.0.0.1:5432/appdb" \
  --redis-dsn "redis://127.0.0.1:6379/0"

# Opt-in: confirm unbacked calls against a RUNNING backend (one unauthenticated GET each,
# never a write; loopback/private hosts only unless --probe-allow-remote).
# 404 confirms a missing path; 401/403/422 means the route exists and the finding moves to DISP-006.
wythe scan /path/to/repo --probe-url http://127.0.0.1:8000

# PR diff gate & directional 3-tier blast-radius slice
wythe diff /path/to/repo --base origin/main --sarif diff.sarif.json

# Git-portable governance bundle (.wythe/governance.json) for CI runners
wythe export-config /path/to/repo
wythe gate --sync-config /path/to/repo

# Single-port API + 3D WebGL UI (auto-registers target directory on startup)
wythe serve /path/to/repo --host 127.0.0.1 --port 8780

First-Class LLM & Human ↔ Vision/MCP Bridge (On-Device AI, Streamable HTTP MCP, OpenAPI & WebMCP)

Full JSON scans on large repositories span megabytes; Wythe exposes five zero-copy-paste Human ↔ LLM surfaces spanning bare-minimum on-device models through remote Tailnet agents:

1. Zero-Setup On-Device AI (Ask AI [A] / ⌘J, /api/v1/ask) — Zero-cloud, zero-API-key cascade with real-time Three.js camera-frustum & screen-color telemetry, 1024px WebP vision frames, and rolling multi-turn sessions across:
   • Apple Intelligence (apple): macOS 26+/27 native FoundationModels helper (arm64-apple-macos26.0, serialized with modelmanagerd backoff).
   • Chrome Built-In (chrome): Client-side browser LanguageModel (Gemini Nano via Prompt API, including 1-click download and multimodal WebGL <canvas> vision when enabled).
   • Local OpenAI /v1 (local): Auto-probes browser-host & server loopback /v1/models & /v1/chat/completions (:8080/:8084/:8083 MLX, :11434 Ollama, :1234 LM Studio) without triggering weight reloads.
2. Streamable HTTP MCP (POST /api/v1/mcp & GET /api/v1/mcp) + Stdio MCP (wythe mcp) — Connect local or remote Tailnet coding agents (http://<host>:8780/api/v1/mcp) with zero local install.
3. OpenAPI 3.1 (/openapi.json) + Remote CLI (wythe focus --remote <url>) — Universal HTTP tool/Actions compatibility plus cross-host CLI X-Ray inspection.
4. In-Tab WebMCP (navigator.modelContext & window.wythe) — Exposes whatIsThis(), getLineageCone(query), selectNode(nodeId), and ask(question) directly to browser agents and extensions.
5. Token-Budgeted llms.txt & Lineage Cone Slicer — Deterministic ~2,000-token repo maps and ~300-token 3-tier cones.

# 1. Token-budgeted llms.txt pointer map (~2,000 tokens regardless of repo size)
wythe llms /path/to/repo --max-tokens 2200 --out llms-wythe.txt

# 2. Surgical ~300-token 3-tier Lineage Cone around any table, file, route, or queue
wythe context /path/to/repo audit_exports
wythe context /path/to/repo /api/v1/scans --json

# 3. Zero-copy-paste Human <-> LLM Bridge (local state or remote private/Tailnet server)
wythe focus
wythe focus --remote http://100.64.0.10:8780

# 4. Zero-dependency read-only stdio MCP server (or connect directly to http://127.0.0.1:8780/api/v1/mcp)
wythe mcp

MCP client configuration (Stdio or Streamable HTTP — exposes wythe_what_is_this, wythe_list_targets, wythe_overview, wythe_lineage_cone, wythe_blast_radius, wythe_findings):

{
  "mcpServers": {
    "wythe-http": {
      "url": "http://127.0.0.1:8780/api/v1/mcp"
    },
    "wythe-stdio": {
      "command": "uvx",
      "args": ["wythe[treesitter]", "mcp"]
    }
  }
}

Adapter Maturity Matrix

Only the dogfooded Python/SQLAlchemy/Next.js trio is classified Implemented; secondary polyglot adapters are classified Experimental (atlas_stack_profiles.implementation_status = 'experimental'):

Empirical Corpus Benchmarks (Dogfood + Wild Open-Source Repos)

Every stack family has been scanned against synthetic test fixtures and multi-thousand-line real-world repositories (wythe[treesitter]):

FAQ & Known Limitations

1. Which stacks are production-ready vs. experimental? fastapi-sqlalchemy-nextjs (PostgreSQL/SQLite + SQLAlchemy 2.0/Alembic + Python/FastAPI + Next.js/TypeScript) is Tier-1 dogfooded (implemented). All 17 other enabled stack profiles are experimental. On experimental profiles, start with wythe scan, wythe llms, wythe context, or wythe diff --base origin/main (or capture a .wythe/governance.json ratchet ceiling) rather than turning on wythe gate --strict blind.

2. What happens if my app uses GraphQL, gRPC / Connect-RPC, tRPC, or Next.js Server Actions instead of HTTP REST? Wythe's cross-tier linker currently matches HTTP REST paths (RouteDescriptor ↔ FrontendHttpCall) plus Tauri #[tauri::command] ↔ invoke(). On GraphQL (lldap), Connect-RPC/gRPC (memos), tRPC, or React Server Actions ("use server"), Wythe still extracts intra-tier DB tables, backend call graphs, and frontend component graphs, but cross-tier HTTP E2E chains will read 0 and rules like TRUTH-001, MANIP-003, or DISP-004 may fire until ratcheted or disabled in .wythe/governance.json.

3. Why ship a static analyzer, SARIF CI gate, 120 fps 3D WebGL UI, and local AI/MCP bridges in one wheel? So uvx "wythe[treesitter]" serve /path/to/repo works in one command on any machine with zero Node.js toolchain, zero cloud API keys, and zero split-version drift between the CLI gate, MCP server, and visual X-Ray UI. Core wythe stays lightweight; prebuilt Tree-sitter C grammars are isolated in the optional [treesitter] extra.

4. Is Wythe actively maintained, or can I request features / SLAs? No. Wythe is shared openly as a free community give-back from internal R&D, provided strictly "AS IS" under MIT with zero commitment to maintain, patch, review PRs, triage issues, or preserve backward compatibility. Pin exact versions in CI and fork freely.

Architecture & Ecosystem Docs

• docs/architecture/ecosystem-and-positioning.md — Ecosystem comparison (tach, import-linter, dependency-cruiser, sqllineage, OpenLineage, CodeCharta, Semgrep) and pairing tach + Wythe in CI.
• docs/architecture/multi-language-extensibility.md — Language-neutral intermediate contract, adapter maturity matrix, wild OSS corpus benchmarks, and non-REST boundaries.

Local Development

make types      # Export OpenAPI 3.1 -> generate TypeScript schema types -> run tsc --noEmit
make build-ui   # Build static Next.js export into backend/app/ui_dist
make lint       # Run ruff check
make test       # Run serial pytest suite
make gate       # Run strict self-dogfood 3-tier + WCAG gate
make package    # Build standalone wheel & sdist containing bundled 3D WebGL UI

License & Disclaimer

MIT — see LICENSE. Provided strictly "AS IS", without warranty of any kind and with no promise of ongoing maintenance or support.