GraFOSa Vision — Long-Term Direction

GraFOSa Vision — Long-Term Direction

Date: 2026-02-27
Status: Aspirational — not scheduled for near-term implementation
Prerequisite: Complete Phases 0-3 from docs/ROADMAP.md first

This document captures features that would make GraFOSa a full platform engineering
tool. Each section is a standalone product-level capability. They are recorded here
for direction-setting, not as commitments.

Why This Is Separate from the Roadmap

The roadmap (Phases 0-4) focuses on making GraFOSa accurate and portable — fixing
data quality, eliminating hardcoding, adding CALLS edges, and integrating into developer
workflow. That work is concrete, scoped, and deliverable.

The items below are different in kind. They are:

• Multi-week to multi-month efforts
• Each could be a standalone product
• Some require external dependencies (tree-sitter, LLM APIs, CI infrastructure)
• Some overlap with mature existing tools (SonarQube, CodeClimate, Snyk)

The risk of mixing them with tactical fixes is scope creep and loss of focus.

V1: Full TypeScript AST Scanner

What: Replace the 90-line regex TS scanner with a proper AST parser.

Options (in order of recommendation):
1. tree-sitter (via tree-sitter-typescript) — fast, battle-tested, Python bindings exist
2. SWC (via swc-python) — very fast, full AST
3. TypeScript compiler via subprocess — accurate but slower

What it enables:

• CALLS edges for TypeScript (function→function call graph)
• Express/Next.js route detection from AST (not regex)
• Path alias resolution (@/ → src/, ~/ → src/)
• Re-export resolution (export { foo } from './bar')
• Dynamic import detection (import('./module'))

Impact: maestro_api's 10,500 symbols go from 100% N/A to fully analyzable.

Honest estimate: 2-3 weeks for production quality. tree-sitter Python bindings are
finicky, JSX/TSX handling has edge cases, and TS module resolution
(paths, baseUrl, compilerOptions) is complex.

Prerequisite: Phase 0.1 (scanner tests) — need a baseline before replacing the scanner.

V2: Anti-Pattern Detection Library

What: Detect known architectural patterns and anti-patterns from graph structure.

Overlap warning: SonarQube, CodeClimate, and Semgrep already detect many of these
at the file/function level. GraFOSa's unique angle is cross-service pattern detection
(e.g., god service, circular service deps, fan-out). Focus there to differentiate.

Honest estimate: 1-2 weeks for the cross-service patterns. File-level patterns
are better left to existing lint tools.

V3: API Coverage Gap Analysis

What: Compare declared endpoints against tests, clients, and documentation.

• Which endpoints have no test cases?
• Which endpoints are never called by any other service?
• Which endpoints are missing from OpenAPI specs?

Output: "47 endpoints have no tests, 12 are never called by any client,
8 are undocumented."

Challenge: Matching test file content to endpoint paths requires heuristics.
A test file named test_chat.py doesn't necessarily test /v1/chat. Pattern matching
will have false positives/negatives.

Honest estimate: 1-2 weeks for a useful-but-imperfect version.

V4: Performance Topology Analysis

What: Infer performance characteristics from graph structure.

• Critical path length: longest chain from frontend to external API
• Parallelization opportunities: independent deps from same service
• Caching candidates: endpoints called by multiple services, read-only semantics
• Bottleneck services: high in-degree + high complexity

Limitation: This is structural inference, not runtime measurement. It can identify
potential bottlenecks but cannot confirm them without profiling data. Be clear about
this in the output — "potential bottleneck based on graph topology" not "bottleneck."

Honest estimate: 1-2 weeks.

V5: Enhanced Deduplication

What: Go beyond name-based collision detection.

• Signature similarity: Functions with different names but same parameter types
• Copy-paste detection: Files with >80% similar symbol structure across services
• Shared type extraction: Types like ValidationResult (22 copies) → recommend

shared package with migration steps

Limitation: Semantic similarity without CALLS edges or type information is noisy.
This becomes much more valuable after Phase 3 (CALLS edges) is complete.

Honest estimate: 1-2 weeks.

V6: Pluggable Scanner Registry

What: Make the scanner architecture extensible for new languages.

class ScannerRegistry:
    _scanners: dict[str, Scanner] = {}

    def register(self, language: str, scanner: Scanner): ...
    def scan_file(self, path: str) -> ScanResult:
        lang = detect_language(path)
        return self._scanners[lang].scan(path)

Each scanner produces the same primitives: File, Symbol, Endpoint, DEFINES, IMPORTS,
CALLS, HANDLES. Language detection by file extension + shebang.

Languages to support over time: Go, Java, Rust, Ruby, PHP, C#.

Honest estimate: 1-2 days for the registry itself. 2-4 weeks per new language
scanner (tree-sitter-based).

V7: Migration Planner

What: Given two graph snapshots (before/after), generate migration guidance.

• Breaking change detection: removed/renamed endpoints, changed signatures
• Migration steps: "Service X depends on removed endpoint Y — update to use Z"
• Dependency compatibility: which service versions work together
• Deploy ordering: blue-green rollout plan for zero downtime
• Risk verdict: safe / caution / dangerous

The scheduler layer (GraphSched) already has plan_change(), simulate(), and
what_if() — this builds on those primitives.

Honest estimate: 1-2 months for a production-quality migration planner. Breaking
change detection alone is a research problem (especially for dynamically-typed languages).

V8: Cross-Repository Analysis

What: Scan multiple repositories and link them via shared packages.

• Shared NPM/PyPI packages create cross-repo DEPENDS_ON edges
• API contract matching (OpenAPI spec → consumer code)
• Event contract matching (NATS/Kafka schemas → publisher/subscriber)
• Multi-repo graph with REPO label nodes containing services

Honest estimate: 1-2 months. Package resolution (npm/pip), version compatibility
checking, and API contract inference are each significant problems.

V9: Infrastructure-as-Code Integration

What: Extend the graph to include infrastructure topology.

• Docker Compose → container→service edges
• Terraform → resource→service edges
• K8s manifests → pod→service→ingress topology
• Helm charts → deployment dependency chains
• New node labels: Container, Resource, Pod, Ingress, Volume

Honest estimate: 1-2 months. Each IaC format is its own parser. Kubernetes alone
has 50+ resource types.

V10: Time-Series Health Tracking

What: Store graph snapshots and health reports over time.

• Track score trends per section ("Architecture improved 72→92 over 30 days")
• Detect regressions ("Circular deps increased 5→8 this week")
• Alert on threshold crossings ("Code quality below 50")
• SQLite-backed for lightweight persistence

Honest estimate: 1-2 weeks.

V11: LLM-Powered Recommendations

What: Use the MCP server (44 tools) as an interface for AI-driven analysis.

• "Explain why service X has high coupling and suggest refactoring"
• "Generate a migration plan for extracting auth into a microservice"
• "What's the safest way to deprecate endpoint /v1/users?"
• "Which services break if we remove Redis?"

Current state: Already partially possible via MCP tools. The gap is generating
structured, natural-language recommendations from graph patterns — essentially
prompt engineering + output formatting.

Honest estimate: 1-2 weeks for structured prompt templates + output formatting.

Prioritization (If We Had Unlimited Time)

Recommendation: After completing the roadmap (Phases 0-4), tackle V1 (TS AST) and
V2 (anti-patterns) first — they have the highest impact-to-effort ratio and build
directly on the foundation the roadmap establishes.