flowindex 0.1.0__py3-none-any.whl

flowindex/__init__.py

@@ -0,0 +1,3 @@
+"""FlowIndex — behavior-first repository indexing for AI coding agents."""
+
+__version__ = "0.1.0"

flowindex/cli.py

@@ -0,0 +1,198 @@
+"""FlowIndex CLI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from flowindex.config import find_project_root, load_config, write_default_config
+from flowindex.db.migrations import migrate
+from flowindex.db.session import get_session, init_db
+from flowindex.indexer.context_pack import make_context_pack
+from flowindex.indexer.explain import explain_target
+from flowindex.indexer.impact import analyze_impact, suggest_tests
+from flowindex.indexer.overview import build_overview
+from flowindex.indexer.pipeline import run_scan
+from flowindex.render.markdown import render_context_pack, render_explain
+from flowindex.render.tables import print_impact, print_overview, print_scan_summary
+
+app = typer.Typer(
+    name="flowindex",
+    help="Behavior-first repository indexing for AI coding agents.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command()
+def init(
+    path: Path | None = typer.Argument(None, help="Repository root (default: git root or cwd)"),
+    here: bool = typer.Option(False, "--here", help="Use current directory as repo root"),
+) -> None:
+    """Initialize FlowIndex in a repository."""
+    root = find_project_root(path, here=here)
+    config_path = write_default_config(root)
+    db_path = root / ".flowindex" / "flowindex.db"
+    init_db(db_path)
+    migrate(db_path)
+    console.print(f"[green]FlowIndex initialized[/green] at {root / '.flowindex'}")
+    console.print(f"  Config: {config_path}")
+    console.print(f"  Database: {db_path}")
+    console.print("\nNext: [bold]flowindex scan[/bold]")
+
+
+@app.command()
+def scan(
+    path: Path | None = typer.Argument(None, help="Repository root"),
+    here: bool = typer.Option(False, "--here", help="Use nearest .flowindex from cwd"),
+) -> None:
+    """Scan repository and build behavior index."""
+    try:
+        config = load_config(path)
+    except FileNotFoundError:
+        root = find_project_root(path, here=here)
+        console.print("[yellow]FlowIndex not initialized. Running init...[/yellow]")
+        write_default_config(root)
+        init_db(root / ".flowindex" / "flowindex.db")
+        config = load_config(root)
+
+    summary = run_scan(config)
+    print_scan_summary(summary.model_dump())
+
+
+@app.command()
+def overview(
+    path: Path | None = typer.Argument(None, help="Repository root"),
+) -> None:
+    """Show high-level repository map."""
+    config = load_config(path)
+    with get_session(config.db_path) as session:
+        from sqlmodel import select
+
+        from flowindex.db.models import Repository
+
+        repo = session.exec(
+            select(Repository).where(Repository.root_path == str(config.root_path.resolve()))
+        ).first()
+        if not repo or not repo.id:
+            console.print("[red]No indexed repository found. Run `flowindex scan`.[/red]")
+            raise typer.Exit(1)
+        data = build_overview(session, repo.id)
+    print_overview(data)
+
+
+@app.command()
+def explain(
+    target: str = typer.Argument(..., help="Entrypoint, symbol, or file path"),
+    path: Path | None = typer.Option(None, "--path", help="Repository root"),
+) -> None:
+    """Explain an entrypoint, symbol, or file flow."""
+    config = load_config(path)
+    with get_session(config.db_path) as session:
+        from sqlmodel import select
+
+        from flowindex.db.models import Repository
+
+        repo = session.exec(
+            select(Repository).where(Repository.root_path == str(config.root_path.resolve()))
+        ).first()
+        if not repo or not repo.id:
+            console.print("[red]No indexed repository. Run `flowindex scan`.[/red]")
+            raise typer.Exit(1)
+        result = explain_target(session, repo.id, target)
+    console.print(render_explain(result))
+
+
+@app.command()
+def impact(
+    target: str = typer.Argument(..., help="File path or symbol name"),
+    path: Path | None = typer.Option(None, "--path", help="Repository root"),
+) -> None:
+    """Show change impact and risk for a file or symbol."""
+    config = load_config(path)
+    with get_session(config.db_path) as session:
+        from sqlmodel import select
+
+        from flowindex.db.models import Repository
+
+        repo = session.exec(
+            select(Repository).where(Repository.root_path == str(config.root_path.resolve()))
+        ).first()
+        if not repo or not repo.id:
+            console.print("[red]No indexed repository. Run `flowindex scan`.[/red]")
+            raise typer.Exit(1)
+        result = analyze_impact(session, repo.id, target)
+    print_impact(result)
+
+
+@app.command("tests-for")
+def tests_for(
+    target: str = typer.Argument(..., help="File path or symbol name"),
+    path: Path | None = typer.Option(None, "--path", help="Repository root"),
+) -> None:
+    """Suggest tests to run for a change."""
+    config = load_config(path)
+    with get_session(config.db_path) as session:
+        from sqlmodel import select
+
+        from flowindex.db.models import Repository
+
+        repo = session.exec(
+            select(Repository).where(Repository.root_path == str(config.root_path.resolve()))
+        ).first()
+        if not repo or not repo.id:
+            console.print("[red]No indexed repository. Run `flowindex scan`.[/red]")
+            raise typer.Exit(1)
+        tests = suggest_tests(session, repo.id, target)
+    console.print(f"\n[bold]Suggested tests for:[/bold] {target}\n")
+    for t in tests or ["(none found)"]:
+        console.print(f"  - {t}")
+    console.print()
+
+
+@app.command()
+def context(
+    task: str = typer.Argument(..., help="Natural language task description"),
+    path: Path | None = typer.Option(None, "--path", help="Repository root"),
+) -> None:
+    """Generate an AI-agent-ready context pack."""
+    config = load_config(path)
+    with get_session(config.db_path) as session:
+        from sqlmodel import select
+
+        from flowindex.db.models import Repository
+
+        repo = session.exec(
+            select(Repository).where(Repository.root_path == str(config.root_path.resolve()))
+        ).first()
+        if not repo or not repo.id:
+            console.print("[red]No indexed repository. Run `flowindex scan`.[/red]")
+            raise typer.Exit(1)
+        pack = make_context_pack(session, repo.id, task)
+    console.print(render_context_pack(pack))
+
+
+@app.command()
+def mcp(
+    path: Path | None = typer.Option(None, "--path", help="Repository root"),
+) -> None:
+    """Start the FlowIndex MCP server for AI coding agents."""
+    try:
+        from flowindex.mcp.server import run_server
+    except ImportError:
+        console.print(
+            "[red]MCP dependencies not installed.[/red] Run: pip install -e '.[mcp]'"
+        )
+        raise typer.Exit(1) from None
+    config = load_config(path)
+    run_server(config)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

flowindex/config.py

@@ -0,0 +1,181 @@
+"""FlowIndex configuration and repository root detection."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import tomli_w
+
+FLOWINDEX_DIR = ".flowindex"
+CONFIG_FILE = "config.toml"
+DB_FILE = "flowindex.db"
+
+DEFAULT_EXCLUDES = [
+    ".git",
+    "node_modules",
+    ".venv",
+    "venv",
+    "dist",
+    "build",
+    ".next",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".flowindex",
+]
+
+DEFAULT_INCLUDES = ["**/*"]
+
+DEFAULT_LANGUAGES = ["python", "typescript", "javascript"]
+
+DEFAULT_TEST_DIRS = ["tests", "test", "__tests__", "spec"]
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "included_paths": DEFAULT_INCLUDES,
+    "excluded_paths": DEFAULT_EXCLUDES,
+    "supported_languages": DEFAULT_LANGUAGES,
+    "test_directories": DEFAULT_TEST_DIRS,
+    "framework_detection": {
+        "fastapi": True,
+        "flask": True,
+        "django": True,
+        "express": True,
+        "nextjs": True,
+    },
+    "git": {
+        "max_commits": 500,
+        "changed_with_min_count": 2,
+    },
+}
+
+
+@dataclass
+class FlowIndexConfig:
+    """Runtime configuration loaded from `.flowindex/config.toml`."""
+
+    root_path: Path
+    included_paths: list[str] = field(default_factory=lambda: list(DEFAULT_INCLUDES))
+    excluded_paths: list[str] = field(default_factory=lambda: list(DEFAULT_EXCLUDES))
+    supported_languages: list[str] = field(default_factory=lambda: list(DEFAULT_LANGUAGES))
+    test_directories: list[str] = field(default_factory=lambda: list(DEFAULT_TEST_DIRS))
+    framework_detection: dict[str, bool] = field(
+        default_factory=lambda: dict(DEFAULT_CONFIG["framework_detection"])
+    )
+    git_max_commits: int = 500
+    git_changed_with_min_count: int = 2
+
+    @property
+    def flowindex_dir(self) -> Path:
+        return self.root_path / FLOWINDEX_DIR
+
+    @property
+    def db_path(self) -> Path:
+        return self.flowindex_dir / DB_FILE
+
+    @property
+    def config_path(self) -> Path:
+        return self.flowindex_dir / CONFIG_FILE
+
+    @classmethod
+    def from_dict(cls, root_path: Path, data: dict[str, Any]) -> FlowIndexConfig:
+        git = data.get("git", {})
+        return cls(
+            root_path=root_path.resolve(),
+            included_paths=list(data.get("included_paths", DEFAULT_INCLUDES)),
+            excluded_paths=list(data.get("excluded_paths", DEFAULT_EXCLUDES)),
+            supported_languages=list(data.get("supported_languages", DEFAULT_LANGUAGES)),
+            test_directories=list(data.get("test_directories", DEFAULT_TEST_DIRS)),
+            framework_detection=dict(
+                data.get("framework_detection", DEFAULT_CONFIG["framework_detection"])
+            ),
+            git_max_commits=int(git.get("max_commits", 500)),
+            git_changed_with_min_count=int(git.get("changed_with_min_count", 2)),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "included_paths": self.included_paths,
+            "excluded_paths": self.excluded_paths,
+            "supported_languages": self.supported_languages,
+            "test_directories": self.test_directories,
+            "framework_detection": self.framework_detection,
+            "git": {
+                "max_commits": self.git_max_commits,
+                "changed_with_min_count": self.git_changed_with_min_count,
+            },
+        }
+
+
+def find_repo_root(start: Path | None = None) -> Path:
+    """Walk up from start (or cwd) to find the nearest `.flowindex` directory."""
+    current = (start or Path.cwd()).resolve()
+    for path in [current, *current.parents]:
+        if (path / FLOWINDEX_DIR).is_dir():
+            return path
+    raise FileNotFoundError(
+        "FlowIndex is not initialized. Run `flowindex init` in your repository root."
+    )
+
+
+def find_project_root(start: Path | None = None, *, here: bool = False) -> Path:
+    """Find git root or cwd for init/scan before `.flowindex` exists."""
+    current = (start or Path.cwd()).resolve()
+    if here:
+        return current
+    for path in [current, *current.parents]:
+        if (path / ".git").exists():
+            return path
+    return current
+
+
+def load_config(root: Path | None = None) -> FlowIndexConfig:
+    root_path = find_repo_root(root)
+    config_path = root_path / FLOWINDEX_DIR / CONFIG_FILE
+    if not config_path.exists():
+        raise FileNotFoundError(f"Missing config at {config_path}. Run `flowindex init`.")
+    with config_path.open("rb") as f:
+        data = tomllib.load(f)
+    return FlowIndexConfig.from_dict(root_path, data)
+
+
+def write_default_config(root_path: Path) -> Path:
+    """Create `.flowindex/config.toml` with defaults."""
+    flowindex_dir = root_path / FLOWINDEX_DIR
+    flowindex_dir.mkdir(parents=True, exist_ok=True)
+    config_path = flowindex_dir / CONFIG_FILE
+    with config_path.open("wb") as f:
+        tomli_w.dump(DEFAULT_CONFIG, f)
+    return config_path
+
+
+def should_exclude(path: Path, root: Path, config: FlowIndexConfig) -> bool:
+    rel = path.relative_to(root).as_posix()
+    parts = rel.split("/")
+    for excluded in config.excluded_paths:
+        if excluded in parts or rel.startswith(excluded.rstrip("/")):
+            return True
+        if rel == excluded or rel.startswith(f"{excluded}/"):
+            return True
+    return False
+
+
+def detect_language(path: Path) -> str | None:
+    ext = path.suffix.lower()
+    mapping = {
+        ".py": "python",
+        ".pyi": "python",
+        ".ts": "typescript",
+        ".tsx": "typescript",
+        ".js": "javascript",
+        ".jsx": "javascript",
+        ".mjs": "javascript",
+        ".cjs": "javascript",
+    }
+    lang = mapping.get(ext)
+    if lang == "typescript" and "javascript" in os.environ.get("FLOWINDEX_FORCE_JS", ""):
+        return "javascript"
+    return lang

flowindex/db/__init__.py

@@ -0,0 +1,12 @@
+"""Simple schema migrations for FlowIndex SQLite database."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from flowindex.db.session import init_db
+
+
+def migrate(db_path: Path) -> None:
+    """Create or upgrade schema. MVP uses create_all."""
+    init_db(db_path)

flowindex/db/migrations.py

@@ -0,0 +1,12 @@
+"""Simple schema migrations for FlowIndex SQLite database."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from flowindex.db.session import init_db
+
+
+def migrate(db_path: Path) -> None:
+    """Create or upgrade schema. MVP uses create_all."""
+    init_db(db_path)

flowindex/db/models.py

@@ -0,0 +1,127 @@
+"""SQLModel database models for FlowIndex."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from sqlmodel import Field, SQLModel
+
+
+def utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class Repository(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    root_path: str
+    name: str
+    created_at: datetime = Field(default_factory=utcnow)
+    updated_at: datetime = Field(default_factory=utcnow)
+
+
+class FileNode(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    repo_id: int = Field(foreign_key="repository.id", index=True)
+    path: str = Field(index=True)
+    language: str
+    size_bytes: int
+    content_hash: str
+    last_indexed_at: datetime = Field(default_factory=utcnow)
+
+
+class SymbolNode(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    repo_id: int = Field(foreign_key="repository.id", index=True)
+    file_id: int = Field(foreign_key="filenode.id", index=True)
+    name: str = Field(index=True)
+    qualified_name: str = Field(index=True)
+    symbol_type: str = Field(index=True)
+    start_line: int
+    end_line: int
+    signature: str = ""
+    docstring: str = ""
+    visibility: str = "public"
+
+
+class EntrypointNode(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    repo_id: int = Field(foreign_key="repository.id", index=True)
+    file_id: int = Field(foreign_key="filenode.id", index=True)
+    symbol_id: int | None = Field(default=None, foreign_key="symbolnode.id")
+    entrypoint_type: str = Field(index=True)
+    method: str | None = None
+    path: str | None = Field(default=None, index=True)
+    name: str
+    framework: str
+    start_line: int
+    end_line: int
+
+
+class TestNode(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    repo_id: int = Field(foreign_key="repository.id", index=True)
+    file_id: int = Field(foreign_key="filenode.id", index=True)
+    symbol_id: int | None = Field(default=None, foreign_key="symbolnode.id")
+    test_name: str = Field(index=True)
+    framework: str
+    target_hint: str | None = None
+    start_line: int
+    end_line: int
+
+
+class CommitNode(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    repo_id: int = Field(foreign_key="repository.id", index=True)
+    commit_hash: str = Field(index=True)
+    author: str
+    date: datetime
+    message: str
+
+
+class GraphEdge(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    repo_id: int = Field(foreign_key="repository.id", index=True)
+    source_type: str
+    source_id: int
+    target_type: str
+    target_id: int
+    edge_type: str = Field(index=True)
+    weight: float = 1.0
+    evidence: str = ""
+    created_at: datetime = Field(default_factory=utcnow)
+
+
+EDGE_TYPES = frozenset(
+    {
+        "defines",
+        "imports",
+        "calls",
+        "exposes",
+        "handled_by",
+        "tests",
+        "covers",
+        "changed_with",
+        "depends_on",
+        "reads",
+        "writes",
+        "mentions",
+    }
+)
+
+RISK_KEYWORDS = frozenset(
+    {
+        "fix",
+        "bug",
+        "regression",
+        "revert",
+        "failing",
+        "broken",
+        "incident",
+        "hotfix",
+        "flaky",
+    }
+)
+
+CRITICAL_PATH_KEYWORDS = frozenset(
+    {"auth", "payment", "billing", "db", "database", "security", "migration"}
+)

flowindex/db/session.py

@@ -0,0 +1,45 @@
+"""Database session management."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from sqlalchemy.engine import Engine
+from sqlmodel import Session, SQLModel, create_engine, select
+
+from flowindex.db.models import (
+    CommitNode,
+    EntrypointNode,
+    FileNode,
+    GraphEdge,
+    SymbolNode,
+    TestNode,
+)
+
+
+def get_engine(db_path: Path) -> Engine:
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    return create_engine(f"sqlite:///{db_path}", echo=False)
+
+
+def init_db(db_path: Path) -> None:
+    engine = get_engine(db_path)
+    SQLModel.metadata.create_all(engine)
+
+
+@contextmanager
+def get_session(db_path: Path) -> Iterator[Session]:
+    engine = get_engine(db_path)
+    with Session(engine) as session:
+        yield session
+
+
+def clear_repo_data(session: Session, repo_id: int) -> None:
+    """Remove all indexed data for a repository before re-scan."""
+    for model in (GraphEdge, CommitNode, TestNode, EntrypointNode, SymbolNode, FileNode):
+        rows = session.exec(select(model).where(model.repo_id == repo_id)).all()
+        for row in rows:
+            session.delete(row)
+    session.commit()

flowindex/frameworks/django.py

@@ -0,0 +1,43 @@
+"""Django view detection (heuristic)."""
+
+from __future__ import annotations
+
+import re
+
+from flowindex.schemas import RouteInfo, SymbolInfo
+
+PATH_DECORATOR = re.compile(r"@(?:path|re_path)\(\s*['\"]([^'\"]+)['\"]")
+
+
+def detect_django_views(source: str, symbols: list[SymbolInfo]) -> list[RouteInfo]:
+    lines = source.splitlines()
+    routes: list[RouteInfo] = []
+    symbol_by_line = {s.start_line: s for s in symbols}
+
+    for i, line in enumerate(lines, 1):
+        m = PATH_DECORATOR.search(line)
+        if not m:
+            continue
+        handler = _next_function_name(lines, i, symbol_by_line)
+        routes.append(
+            RouteInfo(
+                method="GET",
+                path=m.group(1),
+                handler_name=handler,
+                framework="django",
+                start_line=i,
+                end_line=i,
+            )
+        )
+    return routes
+
+
+def _next_function_name(lines: list[str], decor_line: int, symbols: dict[int, SymbolInfo]) -> str:
+    for j in range(decor_line, min(decor_line + 5, len(lines))):
+        sym = symbols.get(j + 1)
+        if sym:
+            return sym.name
+        stripped = lines[j].strip()
+        if stripped.startswith("def "):
+            return stripped.split("(")[0].replace("def ", "").strip()
+    return "view"

flowindex/frameworks/express.py

@@ -0,0 +1,44 @@
+"""Express route detection."""
+
+from __future__ import annotations
+
+import re
+
+from flowindex.schemas import RouteInfo, SymbolInfo
+
+EXPRESS_ROUTE = re.compile(
+    r"(?:app|router)\.(get|post|put|patch|delete|options|head)\(\s*['\"]([^'\"]+)['\"]",
+    re.IGNORECASE,
+)
+
+
+def detect_express_routes(source: str, symbols: list[SymbolInfo]) -> list[RouteInfo]:
+    routes: list[RouteInfo] = []
+    for m in EXPRESS_ROUTE.finditer(source):
+        start = source[: m.start()].count("\n") + 1
+        handler = _handler_near(source, m.end())
+        routes.append(
+            RouteInfo(
+                method=m.group(1).upper(),
+                path=m.group(2),
+                handler_name=handler,
+                framework="express",
+                start_line=start,
+                end_line=start,
+            )
+        )
+    return routes
+
+
+def _handler_near(source: str, pos: int) -> str:
+    chunk = source[pos : pos + 200]
+    fn = re.search(r"(?:async\s+)?function\s+(\w+)", chunk)
+    if fn:
+        return fn.group(1)
+    arrow = re.search(r"(?:const|let)\s+(\w+)\s*=", chunk)
+    if arrow:
+        return arrow.group(1)
+    sym = re.search(r",\s*(\w+)\s*\)", chunk)
+    if sym:
+        return sym.group(1)
+    return "handler"