faultlines 0.1.0__py3-none-any.whl

faultline/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

faultline/analyzer/ast_extractor.py

@@ -0,0 +1,354 @@
+"""
+Regex-based signature extractor for TypeScript and JavaScript files.
+
+Extracts exports, route definitions, and imports from each file
+without any external AST dependencies. This "skeleton" is then
+fed to an LLM to identify user-facing flows within each feature.
+
+Supported patterns:
+  - Named exports:     export function Foo / export const Foo / export class Foo
+  - Default exports:   export default function Foo / export default class Foo
+  - Re-exports:        export { Foo, Bar }
+  - Next.js routes:    export async function GET/POST/PUT/DELETE/PATCH (App Router)
+  - Next.js pages:     getServerSideProps, getStaticProps (Pages Router)
+  - Express routes:    router.get('/path', ...) / app.post('/path', ...)
+  - ES imports:        import X from 'Y'
+"""
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from faultline.models.types import SymbolRange
+
+
+_TS_JS_EXTENSIONS = {".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"}
+_PYTHON_EXTENSIONS = {".py"}
+
+# Named function/class/const exports
+_RE_NAMED_EXPORT = re.compile(
+    r"export\s+(?:async\s+)?(?:function\s*\*?\s*|class\s+|const\s+|let\s+|var\s+)(\w+)"
+)
+# Default function/class exports with a name
+_RE_DEFAULT_EXPORT = re.compile(
+    r"export\s+default\s+(?:async\s+)?(?:function|class)\s+(\w+)"
+)
+# Re-export block: export { Foo, Bar as Baz }
+_RE_REEXPORT = re.compile(r"export\s*\{([^}]+)\}")
+
+# Next.js App Router HTTP method handlers
+_RE_NEXTJS_ROUTE = re.compile(
+    r"export\s+(?:async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\b"
+)
+# Next.js Pages Router data fetchers
+_RE_NEXTJS_PAGE = re.compile(
+    r"export\s+(?:async\s+)?function\s+(getServerSideProps|getStaticProps|getStaticPaths)\b"
+)
+# Express/Fastify route definitions: router.get('/path', ...) or app.post('/path')
+_RE_EXPRESS_ROUTE = re.compile(
+    r"\b(?:router|app|server)\s*\.\s*(get|post|put|delete|patch|head)\s*\(\s*['\"]([^'\"]+)['\"]"
+)
+# ES6 import paths
+_RE_IMPORT = re.compile(r"import\s+.*?from\s+['\"]([^'\"]+)['\"]")
+
+# Python patterns
+_RE_PYTHON_CLASS = re.compile(r"^class\s+(\w+)", re.MULTILINE)
+_RE_PYTHON_FUNC = re.compile(r"^(?:async\s+)?def\s+([a-zA-Z]\w*)", re.MULTILINE)
+_RE_PYTHON_ROUTE = re.compile(
+    r"@\w*(?:router|app|blueprint|bp|api)\s*\.\s*(get|post|put|delete|patch)\s*\(\s*['\"]([^'\"]+)['\"]",
+    re.IGNORECASE,
+)
+
+
+# Named import destructuring: import { FOO, BAR as Baz } from './path'
+_RE_NAMED_IMPORT = re.compile(
+    r"import\s*\{([^}]+)\}\s*from\s*['\"]([^'\"]+)['\"]"
+)
+# Namespace import: import * as X from './path'
+_RE_NAMESPACE_IMPORT = re.compile(
+    r"import\s*\*\s*as\s+\w+\s+from\s*['\"]([^'\"]+)['\"]"
+)
+
+# TS type/interface/enum exports
+_RE_TYPE_EXPORT = re.compile(
+    r"export\s+(?:declare\s+)?(?:type|interface|enum)\s+(\w+)"
+)
+
+
+@dataclass
+class FileSignature:
+    path: str
+    exports: list[str] = field(default_factory=list)
+    routes: list[str] = field(default_factory=list)
+    imports: list[str] = field(default_factory=list)
+    symbol_ranges: list[SymbolRange] = field(default_factory=list)
+    source: str = field(default="", repr=False)
+
+    def is_empty(self) -> bool:
+        return not self.exports and not self.routes and not self.imports
+
+    def to_prompt_line(self) -> str:
+        """Formats the signature as a single line for LLM prompts."""
+        parts = []
+        if self.exports:
+            parts.append(f"exports: {', '.join(self.exports[:8])}")
+        if self.routes:
+            parts.append(f"routes: {', '.join(self.routes[:5])}")
+        if not parts:
+            return ""
+        return f"  {self.path} → {' | '.join(parts)}"
+
+
+def extract_signatures(
+    files: list[str],
+    repo_path: str,
+) -> dict[str, FileSignature]:
+    """
+    Extracts function/route/import signatures from TypeScript and JavaScript files.
+
+    Args:
+        files: List of relative file paths (relative to repo_path).
+        repo_path: Absolute path to the repository root.
+
+    Returns:
+        Dict mapping relative file path → FileSignature.
+        Non-TS/JS files are skipped and not included in the result.
+    """
+    result: dict[str, FileSignature] = {}
+    root = Path(repo_path)
+
+    for rel_path in files:
+        suffix = Path(rel_path).suffix.lower()
+        if suffix not in _TS_JS_EXTENSIONS and suffix not in _PYTHON_EXTENSIONS:
+            continue
+        abs_path = root / rel_path
+        try:
+            source = abs_path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+
+        if suffix in _PYTHON_EXTENSIONS:
+            sig = _parse_python_file(rel_path, source)
+        else:
+            sig = _parse_file(rel_path, source)
+            sig.symbol_ranges = extract_symbol_ranges(source)
+            sig.source = source
+
+        if not sig.is_empty():
+            result[rel_path] = sig
+
+    return result
+
+
+def _parse_file(rel_path: str, source: str) -> FileSignature:
+    sig = FileSignature(path=rel_path)
+
+    # Collect named exports
+    seen_exports: set[str] = set()
+
+    for match in _RE_NAMED_EXPORT.finditer(source):
+        name = match.group(1)
+        if name not in seen_exports:
+            seen_exports.add(name)
+            sig.exports.append(name)
+
+    for match in _RE_DEFAULT_EXPORT.finditer(source):
+        name = match.group(1)
+        if name not in seen_exports:
+            seen_exports.add(name)
+            sig.exports.append(name)
+
+    for match in _RE_REEXPORT.finditer(source):
+        for token in match.group(1).split(","):
+            # Handle "Foo as Bar" → take the exported name "Bar"
+            parts = token.strip().split(" as ")
+            name = parts[-1].strip()
+            if name and name not in seen_exports:
+                seen_exports.add(name)
+                sig.exports.append(name)
+
+    # Collect route definitions
+    for match in _RE_NEXTJS_ROUTE.finditer(source):
+        method = match.group(1)
+        # Infer path from the file path for App Router (files live at the route path)
+        route_path = _infer_nextjs_route_path(rel_path)
+        sig.routes.append(f"{method} {route_path}")
+
+    for match in _RE_NEXTJS_PAGE.finditer(source):
+        sig.routes.append(match.group(1))
+
+    for match in _RE_EXPRESS_ROUTE.finditer(source):
+        method = match.group(1).upper()
+        path = match.group(2)
+        sig.routes.append(f"{method} {path}")
+
+    # Collect imports (only internal/relative, skip node_modules)
+    for match in _RE_IMPORT.finditer(source):
+        src = match.group(1)
+        if src.startswith(".") or src.startswith("@/") or src.startswith("~/"):
+            sig.imports.append(src)
+
+    return sig
+
+
+def _parse_python_file(rel_path: str, source: str) -> FileSignature:
+    sig = FileSignature(path=rel_path)
+    seen: set[str] = set()
+
+    for match in _RE_PYTHON_CLASS.finditer(source):
+        name = match.group(1)
+        if name not in seen:
+            seen.add(name)
+            sig.exports.append(name)
+
+    for match in _RE_PYTHON_FUNC.finditer(source):
+        name = match.group(1)
+        if name not in seen:
+            seen.add(name)
+            sig.exports.append(name)
+
+    for match in _RE_PYTHON_ROUTE.finditer(source):
+        method = match.group(1).upper()
+        path = match.group(2)
+        sig.routes.append(f"{method} {path}")
+
+    return sig
+
+
+def _infer_nextjs_route_path(rel_path: str) -> str:
+    """
+    Infers the Next.js API route path from the file's relative path.
+
+    Examples:
+        app/api/auth/login/route.ts → /api/auth/login
+        pages/api/auth.ts           → /api/auth
+        src/app/api/users/route.ts  → /api/users
+    """
+    p = Path(rel_path)
+    parts = p.parts
+
+    # Drop leading src/, app/ wrappers
+    skip = {"src", "app"}
+    start = 0
+    for i, part in enumerate(parts):
+        if part not in skip:
+            start = i
+            break
+
+    trimmed = parts[start:]
+
+    # Drop trailing "route.ts" filename
+    if trimmed and Path(trimmed[-1]).stem == "route":
+        trimmed = trimmed[:-1]
+    else:
+        # Drop the filename extension for pages/api style
+        trimmed = trimmed[:-1] + (Path(trimmed[-1]).stem,) if trimmed else trimmed
+
+    return "/" + "/".join(trimmed) if trimmed else "/"
+
+
+def extract_symbol_ranges(source: str) -> list[SymbolRange]:
+    """Extracts line ranges for each exported symbol in TS/JS source.
+
+    MVP heuristic: each export's end_line = next export's start_line - 1,
+    or EOF for the last export. This avoids complex brace-balancing but
+    gives reasonable line attribution for most files.
+    """
+    total_lines = source.count("\n") + 1
+    # Collect all export positions with their symbol names and kinds
+    exports: list[tuple[int, str, str]] = []  # (start_line, name, kind)
+
+    for match in _RE_NAMED_EXPORT.finditer(source):
+        line = source[:match.start()].count("\n") + 1
+        name = match.group(1)
+        # Determine kind from the keyword before the name
+        text = source[match.start():match.end()]
+        if "function" in text:
+            kind = "function"
+        elif "class" in text:
+            kind = "class"
+        else:
+            kind = "const"
+        exports.append((line, name, kind))
+
+    for match in _RE_DEFAULT_EXPORT.finditer(source):
+        line = source[:match.start()].count("\n") + 1
+        name = match.group(1)
+        text = source[match.start():match.end()]
+        kind = "class" if "class" in text else "function"
+        exports.append((line, name, kind))
+
+    for match in _RE_TYPE_EXPORT.finditer(source):
+        line = source[:match.start()].count("\n") + 1
+        name = match.group(1)
+        text = source[match.start():match.end()]
+        if "enum" in text:
+            kind = "enum"
+        elif "interface" in text:
+            kind = "type"
+        else:
+            kind = "type"
+        exports.append((line, name, kind))
+
+    for match in _RE_REEXPORT.finditer(source):
+        line = source[:match.start()].count("\n") + 1
+        for token in match.group(1).split(","):
+            parts = token.strip().split(" as ")
+            name = parts[-1].strip()
+            if name:
+                exports.append((line, name, "reexport"))
+
+    if not exports:
+        return []
+
+    # Sort by start_line, deduplicate by name (keep first occurrence)
+    exports.sort(key=lambda x: x[0])
+    seen: set[str] = set()
+    unique: list[tuple[int, str, str]] = []
+    for start, name, kind in exports:
+        if name not in seen:
+            seen.add(name)
+            unique.append((start, name, kind))
+
+    # Assign end_line: next export's start_line - 1, or EOF for last
+    ranges = []
+    for i, (start, name, kind) in enumerate(unique):
+        if i + 1 < len(unique):
+            end = unique[i + 1][0] - 1
+        else:
+            end = total_lines
+        ranges.append(SymbolRange(
+            name=name, start_line=start, end_line=max(start, end), kind=kind,
+        ))
+
+    return ranges
+
+
+def extract_named_imports(source: str) -> dict[str, set[str]]:
+    """Extracts named imports from TS/JS source.
+
+    Returns:
+        Dict mapping module path → set of imported symbol names.
+        For namespace imports (import * as X), returns {"*"} as the symbol set.
+    """
+    result: dict[str, set[str]] = {}
+
+    for match in _RE_NAMED_IMPORT.finditer(source):
+        names_str = match.group(1)
+        module = match.group(2)
+        if not (module.startswith(".") or module.startswith("@/") or module.startswith("~/")):
+            continue
+        names = set()
+        for token in names_str.split(","):
+            parts = token.strip().split(" as ")
+            original = parts[0].strip()
+            if original:
+                names.add(original)
+        if names:
+            result.setdefault(module, set()).update(names)
+
+    for match in _RE_NAMESPACE_IMPORT.finditer(source):
+        module = match.group(1)
+        if module.startswith(".") or module.startswith("@/") or module.startswith("~/"):
+            result.setdefault(module, set()).add("*")
+
+    return result

faultline/analyzer/cochange_detector.py

@@ -0,0 +1,198 @@
+"""Deterministic feature detection via co-change community detection.
+
+Files that frequently change together in git history are grouped into the same
+feature using Union-Find. This is the primary detection algorithm.
+
+Same git history → same groups every time (100% deterministic).
+
+When --llm is enabled, the LLM *names* the groups (but does not determine them).
+Results are cached, so repeated runs return identical names.
+"""
+
+from collections import defaultdict
+from itertools import combinations
+from pathlib import Path
+
+from faultline.models.types import Commit
+
+# Minimum commits in history to trust co-change signal.
+# Below this threshold the caller falls back to directory heuristics.
+_MIN_COMMITS_FOR_COCHANGE = 50
+
+# Jaccard coupling threshold for merging two files into the same feature.
+# Jaccard = commits_touching_both / commits_touching_either.
+# 0.20 means "these files change together in ≥20% of commits that touch either one".
+_COCHANGE_THRESHOLD = 0.20
+
+# Commits that touch more files than this are excluded (bulk ops / large refactors).
+_MAX_FILES_PER_COMMIT = 30
+
+# A file must appear in at least this many commits to participate in coupling.
+# Files edited only once produce noisy pairs.
+_MIN_FILE_COMMITS = 2
+
+# Directory names that are generic structural wrappers, not business feature names.
+_SKIP_DIRS = {
+    "src", "app", "lib", "pkg", "internal", "core",
+    "views", "pages", "screens", "routes", "containers",
+    "components", "layouts", "features",
+}
+
+
+class _UnionFind:
+    """Path-compressed, union-by-rank disjoint set data structure."""
+
+    def __init__(self, nodes: list[str]) -> None:
+        self._parent: dict[str, str] = {n: n for n in nodes}
+        self._rank: dict[str, int] = defaultdict(int)
+
+    def find(self, x: str) -> str:
+        if self._parent[x] != x:
+            self._parent[x] = self.find(self._parent[x])  # path compression
+        return self._parent[x]
+
+    def union(self, x: str, y: str) -> None:
+        rx, ry = self.find(x), self.find(y)
+        if rx == ry:
+            return
+        if self._rank[rx] < self._rank[ry]:
+            rx, ry = ry, rx
+        self._parent[ry] = rx
+        if self._rank[rx] == self._rank[ry]:
+            self._rank[rx] += 1
+
+    def groups(self) -> dict[str, list[str]]:
+        clusters: dict[str, list[str]] = defaultdict(list)
+        for node in self._parent:
+            clusters[self.find(node)].append(node)
+        return dict(clusters)
+
+
+def detect_features_from_cochange(
+    files: list[str],
+    commits: list[Commit],
+) -> dict[str, list[str]] | None:
+    """Groups files into features based on co-change patterns.
+
+    Returns None when there are fewer than _MIN_COMMITS_FOR_COCHANGE commits —
+    the caller should fall back to directory-based heuristics in that case.
+    Also returns None if the resulting mapping is empty (no co-change signal).
+
+    The returned dict maps feature_name → list of file paths.
+    Names are directory-derived; pass the result to name_clusters_llm() or
+    name_clusters_ollama() to replace them with semantic business domain names.
+
+    Args:
+        files: Tracked file paths (relative, with path prefix already stripped).
+        commits: Commit history for the analysis window.
+    """
+    if len(commits) < _MIN_COMMITS_FOR_COCHANGE:
+        return None
+
+    file_set = set(files)
+
+    # Index: file → set of commit SHAs (non-bulk commits only)
+    file_commits: dict[str, set[str]] = defaultdict(set)
+    for commit in commits:
+        if len(commit.files_changed) > _MAX_FILES_PER_COMMIT:
+            continue
+        for f in commit.files_changed:
+            if f in file_set:
+                file_commits[f].add(commit.sha)
+
+    # Inverted index: commit SHA → files (for efficient O(k²) pair counting)
+    commit_to_files: dict[str, list[str]] = defaultdict(list)
+    for f, shas in file_commits.items():
+        if len(shas) < _MIN_FILE_COMMITS:
+            continue  # too few appearances — unreliable signal
+        for sha in shas:
+            commit_to_files[sha].append(f)
+
+    # Count co-occurrences for each file pair
+    pair_both: dict[tuple[str, str], int] = defaultdict(int)
+    for touched in commit_to_files.values():
+        if len(touched) < 2:
+            continue
+        for f1, f2 in combinations(sorted(touched), 2):
+            pair_both[(f1, f2)] += 1
+
+    # Union-Find: merge files whose Jaccard score meets the threshold
+    uf = _UnionFind(files)
+    for (f1, f2), both in pair_both.items():
+        a = len(file_commits.get(f1, set()))
+        b = len(file_commits.get(f2, set()))
+        denom = a + b - both
+        if denom > 0 and both / denom >= _COCHANGE_THRESHOLD:
+            uf.union(f1, f2)
+
+    result = _finalize_clusters(uf.groups())
+    return result if result else None
+
+
+def _finalize_clusters(
+    raw_groups: dict[str, list[str]],
+) -> dict[str, list[str]]:
+    """Converts raw Union-Find groups to named feature clusters.
+
+    Multi-file clusters receive a directory-derived name.
+    Singleton clusters are merged into a same-directory cluster if one exists,
+    or grouped together under a shared directory name.
+    """
+    multi: dict[str, list[str]] = {}
+    singletons: list[str] = []
+
+    for members in raw_groups.values():
+        members_sorted = sorted(members)
+        if len(members_sorted) >= 2:
+            name = _cluster_name(members_sorted)
+            name = _unique_name(name, multi)
+            multi[name] = members_sorted
+        else:
+            singletons.extend(members_sorted)
+
+    # Build dir → cluster index so singletons can be absorbed
+    dir_to_cluster: dict[str, str] = {}
+    for cluster_name, members in multi.items():
+        for f in members:
+            dir_to_cluster[str(Path(f).parent)] = cluster_name
+
+    # Assign singletons: merge into same-dir cluster or bucket by dir name
+    dir_orphans: dict[str, list[str]] = defaultdict(list)
+    for f in singletons:
+        d = str(Path(f).parent)
+        if d in dir_to_cluster:
+            multi[dir_to_cluster[d]].append(f)
+        else:
+            dir_orphans[_feature_name_from_path(f)].append(f)
+
+    for name, fs in dir_orphans.items():
+        name = _unique_name(name, multi)
+        multi[name] = sorted(fs)
+
+    return multi
+
+
+def _cluster_name(files: list[str]) -> str:
+    """Derives a cluster name from the most common meaningful directory component."""
+    counts: dict[str, int] = defaultdict(int)
+    for f in files:
+        counts[_feature_name_from_path(f)] += 1
+    return max(counts, key=lambda k: counts[k])
+
+
+def _feature_name_from_path(path: str) -> str:
+    """Extracts the first non-generic directory component as a feature name."""
+    for part in Path(path).parts[:-1]:
+        if part.lower() not in _SKIP_DIRS:
+            return part.lower()
+    return "root"
+
+
+def _unique_name(name: str, existing: dict) -> str:
+    """Returns a unique name by appending a numeric suffix if needed."""
+    if name not in existing:
+        return name
+    suffix = 2
+    while f"{name}-{suffix}" in existing:
+        suffix += 1
+    return f"{name}-{suffix}"

faultline/analyzer/coverage.py

@@ -0,0 +1,66 @@
+"""Reads test coverage data from standard coverage file formats."""
+
+import json
+from pathlib import Path
+
+
+def read_coverage(repo_path: str, coverage_path: str | None = None) -> dict[str, float]:
+    """
+    Returns file_path → line coverage % (0–100).
+
+    If coverage_path is provided, reads that file directly (lcov or jest format).
+    Otherwise tries coverage/coverage-summary.json (Jest/NYC) then coverage/lcov.info.
+    Returns empty dict if no coverage data found.
+    """
+    if coverage_path:
+        p = Path(coverage_path)
+        if not p.exists():
+            return {}
+        if p.name.endswith(".json"):
+            return _read_jest(p)
+        return _read_lcov(p)
+
+    root = Path(repo_path)
+    # Auto-detect: check common locations
+    candidates = [
+        root / "coverage" / "coverage-summary.json",
+        root / "coverage" / "lcov.info",
+        root / "lcov.info",
+        root / "coverage.lcov",
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            if candidate.name.endswith(".json"):
+                return _read_jest(candidate)
+            return _read_lcov(candidate)
+    return {}
+
+
+def _read_jest(path: Path) -> dict[str, float]:
+    data = json.loads(path.read_text())
+    result: dict[str, float] = {}
+    for file_path, stats in data.items():
+        if file_path == "total":
+            continue
+        pct = (stats.get("lines") or {}).get("pct")
+        if pct is not None:
+            result[str(file_path)] = float(pct)
+    return result
+
+
+def _read_lcov(path: Path) -> dict[str, float]:
+    result: dict[str, float] = {}
+    current: str | None = None
+    lf = lh = 0
+    for line in path.read_text().splitlines():
+        if line.startswith("SF:"):
+            current = line[3:]
+            lf = lh = 0
+        elif line.startswith("LF:"):
+            lf = int(line[3:])
+        elif line.startswith("LH:"):
+            lh = int(line[3:])
+        elif line == "end_of_record" and current:
+            result[current] = round(lh / lf * 100, 1) if lf > 0 else 0.0
+            current = None
+    return result