code-finder 0.1.0__py3-none-any.whl

claude_context/skills/api_surface.py

@@ -0,0 +1,219 @@
+"""
+API Surface Extraction skill.
+
+Extracts the public API surface from source code files or directories
+using AST parsing. Deterministic — no LLM, no indexing, no embeddings.
+
+Usage:
+    python -m claude_context.skills.api_surface --target src/auth/
+    python -m claude_context.skills.api_surface --target src/auth/handler.py --include-private
+"""
+
+import argparse
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..enhanced_ast_chunker import EnhancedASTChunker, EnhancedCodeChunk
+
+logger = logging.getLogger(__name__)
+
+# Types that represent API surface entities
+API_ENTITY_TYPES = {"function", "class", "method", "interface", "type"}
+
+
+def extract_api_surface(
+    target_path: str,
+    languages: Optional[List[str]] = None,
+    include_private: bool = False,
+    include_docstrings: bool = True,
+    max_chunk_size: int = 1500,
+) -> Dict[str, Any]:
+    """Extract the public API surface from source files.
+
+    Args:
+        target_path: Path to a file or directory
+        languages: Filter by language (e.g., ["python", "typescript"])
+        include_private: Include _prefixed names
+        include_docstrings: Include docstrings in output
+        max_chunk_size: Max chunk size for AST chunker
+
+    Returns:
+        Dict with structured API surface grouped by file
+    """
+    target = Path(target_path).resolve()
+    if not target.exists():
+        raise FileNotFoundError(f"Target path does not exist: {target}")
+
+    chunker = EnhancedASTChunker(max_chunk_size=max_chunk_size, context_mode="full")
+
+    # Collect files to process
+    if target.is_file():
+        files = [target]
+    else:
+        files = sorted(_discover_source_files(target))
+
+    api_surface: Dict[str, Any] = {}
+    total_entities = 0
+
+    for file_path in files:
+        chunks = chunker.chunk_file(file_path)
+        if not chunks:
+            continue
+
+        # Filter to API entities
+        entities = [c for c in chunks if c.chunk_type in API_ENTITY_TYPES]
+
+        # Filter by language
+        if languages:
+            entities = [e for e in entities if e.language.lower() in [l.lower() for l in languages]]
+
+        # Filter private
+        if not include_private:
+            entities = [e for e in entities if not (e.name and e.name.startswith("_"))]
+
+        if not entities:
+            continue
+
+        file_key = str(file_path)
+        file_language = entities[0].language if entities else ""
+        structured = _structure_entities(entities, include_docstrings)
+
+        api_surface[file_key] = {
+            "language": file_language,
+            "entities": structured,
+        }
+        total_entities += len(entities)
+
+    return {
+        "target_path": str(target),
+        "files_processed": len(files),
+        "files_with_api": len(api_surface),
+        "total_entities": total_entities,
+        "api_surface": api_surface,
+    }
+
+
+def _discover_source_files(directory: Path) -> List[Path]:
+    """Discover source files in a directory, skipping common non-source dirs."""
+    skip_dirs = {".git", "__pycache__", "node_modules", ".venv", "venv", ".vibe2doc"}
+    extensions = {
+        ".py", ".js", ".ts", ".tsx", ".jsx", ".go", ".rs",
+        ".java", ".kt", ".cpp", ".c", ".h", ".hpp",
+    }
+    files = []
+    for path in directory.rglob("*"):
+        if any(part in skip_dirs for part in path.parts):
+            continue
+        if path.is_file() and path.suffix in extensions:
+            files.append(path)
+    return files
+
+
+def _structure_entities(
+    entities: List[EnhancedCodeChunk],
+    include_docstrings: bool,
+) -> List[Dict[str, Any]]:
+    """Structure entities, nesting methods under their parent classes."""
+    # Separate classes and top-level items
+    classes: Dict[str, Dict[str, Any]] = {}
+    top_level: List[Dict[str, Any]] = []
+
+    for entity in entities:
+        entry = _entity_to_dict(entity, include_docstrings)
+
+        if entity.chunk_type == "class":
+            entry["methods"] = []
+            classes[entity.name] = entry
+        elif entity.scope:
+            # Has a parent scope — nest under parent class if we have it.
+            # The chunker may report chunk_type="function" for methods,
+            # so we use scope presence as the signal, not chunk_type.
+            parent_name = entity.scope[0]
+            if parent_name in classes:
+                classes[parent_name]["methods"].append(entry)
+            else:
+                top_level.append(entry)
+        else:
+            top_level.append(entry)
+
+    # Classes first, then top-level functions
+    result = list(classes.values()) + top_level
+    return result
+
+
+def _entity_to_dict(entity: EnhancedCodeChunk, include_docstrings: bool) -> Dict[str, Any]:
+    """Convert a single entity to output dict."""
+    d: Dict[str, Any] = {
+        "type": entity.chunk_type,
+        "name": entity.name,
+        "signature": entity.signature,
+        "line_range": list(entity.line_range),
+    }
+
+    if entity.parameters:
+        d["parameters"] = [
+            {
+                "name": p.name,
+                "type": p.type_annotation,
+                "default": p.default_value,
+            }
+            for p in entity.parameters
+            if p.name != "self"
+        ]
+
+    if entity.return_type:
+        d["return_type"] = entity.return_type
+
+    if include_docstrings and entity.docstring:
+        d["docstring"] = entity.docstring
+
+    if entity.scope:
+        d["scope"] = entity.scope
+
+    return d
+
+
+def main():
+    """CLI entry point."""
+    from . _cli_common import setup_logging, add_common_args, output_result, error_result
+    setup_logging()
+
+    parser = argparse.ArgumentParser(
+        description="Extract API surface from source code using AST parsing"
+    )
+    parser.add_argument(
+        "--target", required=True,
+        help="File or directory to analyze"
+    )
+    parser.add_argument(
+        "--languages", type=str, default=None,
+        help="Comma-separated language filter (e.g., python,typescript)"
+    )
+    parser.add_argument(
+        "--include-private", action="store_true",
+        help="Include _prefixed private names"
+    )
+    parser.add_argument(
+        "--no-docstrings", action="store_true",
+        help="Exclude docstrings from output"
+    )
+    add_common_args(parser)
+
+    args = parser.parse_args()
+
+    try:
+        langs = args.languages.split(",") if args.languages else None
+        result = extract_api_surface(
+            target_path=args.target,
+            languages=langs,
+            include_private=args.include_private,
+            include_docstrings=not args.no_docstrings,
+        )
+        output_result(result, args, filename="api_surface.json")
+    except Exception as e:
+        error_result(str(e))
+
+
+if __name__ == "__main__":
+    main()

claude_context/skills/evidence_retrieval.py

@@ -0,0 +1,151 @@
+"""
+Code Evidence Retrieval skill.
+
+Given a natural language query and a repo path, returns ranked code
+snippets with file paths, signatures, and context scores.
+
+Usage:
+    python -m claude_context.skills.evidence_retrieval \
+        --repo /path/to/repo --query "how does auth work?" --limit 10
+"""
+
+import argparse
+import logging
+from typing import Any, Dict, List, Optional
+
+from ._index_manager import ensure_index
+
+logger = logging.getLogger(__name__)
+
+
+def retrieve_evidence(
+    repo_path: str,
+    query: str,
+    limit: int = 10,
+    filter_types: Optional[List[str]] = None,
+    filter_languages: Optional[List[str]] = None,
+    filter_paths: Optional[List[str]] = None,
+    db_path: Optional[str] = None,
+    reindex: bool = False,
+) -> Dict[str, Any]:
+    """Search a codebase for evidence matching a natural language query.
+
+    Args:
+        repo_path: Path to the repository
+        query: Natural language search query
+        limit: Maximum number of results
+        filter_types: Filter by chunk type (function, class, method, etc.)
+        filter_languages: Filter by language (python, typescript, etc.)
+        filter_paths: Filter results to files under these directory prefixes
+        db_path: Override Milvus DB path
+        reindex: Force re-indexing
+
+    Returns:
+        Dict with ranked search results and metadata
+    """
+    searcher, index_info = ensure_index(repo_path, db_path=db_path, reindex=reindex)
+
+    # Resolve filter paths relative to repo_path (not cwd) so they match
+    # the absolute file_path values stored in the index
+    resolved_paths = None
+    if filter_paths:
+        from pathlib import Path
+        repo_root = Path(repo_path).resolve()
+        resolved_paths = [str((repo_root / p).resolve()) for p in filter_paths]
+
+    results = searcher.search(
+        query=query,
+        limit=limit,
+        filter_chunk_types=filter_types,
+        filter_languages=filter_languages,
+        filter_paths=resolved_paths,
+    )
+
+    return {
+        "query": query,
+        "repo_path": repo_path,
+        "result_count": len(results),
+        "index_info": index_info,
+        "results": [
+            {
+                "rank": i + 1,
+                "file_path": r.file_path,
+                "file_name": r.file_name,
+                "start_line": r.start_line,
+                "end_line": r.end_line,
+                "language": r.language,
+                "chunk_type": r.chunk_type,
+                "chunk_name": r.chunk_name,
+                "parent_context": r.parent_context,
+                "signature": r.signature,
+                "docstring": r.docstring,
+                "return_type": r.return_type,
+                "content": r.content,
+                "scores": {
+                    "vector": round(r.vector_score, 4),
+                    "bm25": round(r.bm25_score, 4),
+                    "combined": round(r.combined_score, 4),
+                },
+            }
+            for i, r in enumerate(results)
+        ],
+    }
+
+
+def main():
+    """CLI entry point."""
+    from ._cli_common import setup_logging, add_common_args, output_result, error_result
+    setup_logging()
+
+    parser = argparse.ArgumentParser(
+        description="Search codebase for code evidence matching a query"
+    )
+    parser.add_argument(
+        "--repo", required=True,
+        help="Path to the repository to search"
+    )
+    parser.add_argument(
+        "--query", required=True,
+        help="Natural language search query"
+    )
+    parser.add_argument(
+        "--limit", type=int, default=10,
+        help="Maximum number of results (default: 10)"
+    )
+    parser.add_argument(
+        "--filter-types", type=str, default=None,
+        help="Comma-separated chunk type filter (e.g., function,method)"
+    )
+    parser.add_argument(
+        "--filter-languages", type=str, default=None,
+        help="Comma-separated language filter (e.g., python,typescript)"
+    )
+    parser.add_argument(
+        "--filter-paths", type=str, default=None,
+        help="Comma-separated directory prefixes to scope results (e.g., src/auth,src/config)"
+    )
+    add_common_args(parser)
+
+    args = parser.parse_args()
+
+    try:
+        types = args.filter_types.split(",") if args.filter_types else None
+        langs = args.filter_languages.split(",") if args.filter_languages else None
+        paths = args.filter_paths.split(",") if args.filter_paths else None
+        result = retrieve_evidence(
+            repo_path=args.repo,
+            query=args.query,
+            limit=args.limit,
+            filter_types=types,
+            filter_languages=langs,
+            filter_paths=paths,
+            db_path=args.db_path,
+            reindex=args.reindex,
+        )
+        output_result(result, args, filename="evidence.json")
+    except Exception as e:
+        error_result(str(e))
+
+
+if __name__ == "__main__":
+    main()

claude_context/skills/grounded_review.py

@@ -0,0 +1,212 @@
+"""
+Code-Grounded Review skill.
+
+Given a draft document and a repo path, extracts factual claims from
+the document and verifies each against the source code using hybrid
+search. Returns per-claim verdicts with supporting evidence.
+
+Usage:
+    python -m claude_context.skills.grounded_review \
+        --repo /path/to/repo --draft docs/getting-started.md
+"""
+
+import argparse
+import logging
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from ..search import SearchResult
+from ._index_manager import ensure_index
+
+logger = logging.getLogger(__name__)
+
+
+def grounded_review(
+    repo_path: str,
+    draft_path: str,
+    max_evidence_per_claim: int = 5,
+    db_path: Optional[str] = None,
+    reindex: bool = False,
+) -> Dict[str, Any]:
+    """Review a draft document by checking claims against source code.
+
+    Args:
+        repo_path: Path to the repository
+        draft_path: Path to the markdown draft document
+        max_evidence_per_claim: Max evidence snippets per claim
+        db_path: Override Milvus DB path
+        reindex: Force re-indexing
+
+    Returns:
+        Dict with per-claim verdicts and evidence
+    """
+    draft = Path(draft_path)
+    if not draft.exists():
+        raise FileNotFoundError(f"Draft not found: {draft_path}")
+
+    draft_text = draft.read_text(encoding="utf-8", errors="ignore")
+    claims = _extract_claims(draft_text)
+
+    if not claims:
+        return {
+            "draft_path": str(draft_path),
+            "repo_path": repo_path,
+            "total_claims": 0,
+            "summary": {"supported": 0, "partially_supported": 0, "unsupported": 0, "no_evidence_found": 0},
+            "claims": [],
+        }
+
+    searcher, index_info = ensure_index(repo_path, db_path=db_path, reindex=reindex)
+
+    claim_results = []
+    summary = {"supported": 0, "partially_supported": 0, "unsupported": 0, "no_evidence_found": 0}
+
+    for i, claim_text in enumerate(claims):
+        results = searcher.search(query=claim_text, limit=max_evidence_per_claim)
+        verdict, confidence = _judge_claim(claim_text, results)
+        summary[verdict] += 1
+
+        claim_results.append({
+            "claim_id": i + 1,
+            "text": claim_text,
+            "verdict": verdict,
+            "confidence": round(confidence, 4),
+            "evidence": [
+                {
+                    "file_path": r.file_path,
+                    "start_line": r.start_line,
+                    "end_line": r.end_line,
+                    "chunk_type": r.chunk_type,
+                    "chunk_name": r.chunk_name,
+                    "signature": r.signature,
+                    "relevance_score": round(r.combined_score, 4),
+                    "content_snippet": r.content[:300],
+                }
+                for r in results[:3]  # Top 3 evidence per claim
+            ],
+        })
+
+    return {
+        "draft_path": str(draft_path),
+        "repo_path": repo_path,
+        "total_claims": len(claims),
+        "summary": summary,
+        "claims": claim_results,
+        "index_info": index_info,
+    }
+
+
+def _extract_claims(draft_text: str) -> List[str]:
+    """Extract verifiable factual claims from a markdown draft.
+
+    Looks for sentences that reference code identifiers: backtick-quoted
+    names, file paths, function-like names (snake_case, camelCase), or
+    import statements.
+    """
+    # Remove code blocks (they're examples, not claims)
+    text = re.sub(r"```[\s\S]*?```", "", draft_text)
+
+    # Remove headings
+    text = re.sub(r"^#+\s+.*$", "", text, flags=re.MULTILINE)
+
+    # Split into sentences
+    sentences = re.split(r"(?<=[.!?])\s+", text)
+
+    claims = []
+    # Patterns that indicate a factual claim about code
+    code_patterns = [
+        r"`[^`]+`",                      # backtick-quoted identifiers
+        r"\b\w+\.\w+\b",                 # dotted names (module.func)
+        r"\b[a-z]+_[a-z_]+\b",           # snake_case identifiers
+        r"\b[a-z]+[A-Z][a-zA-Z]+\b",     # camelCase identifiers
+        r"[/\\]\w+\.\w+",                # file paths
+        r"\bimport\b",                    # import references
+        r"\bclass\b",                     # class references
+        r"\bfunction\b|\bmethod\b|\bdef\b",  # function references
+    ]
+    combined_pattern = "|".join(code_patterns)
+
+    for sentence in sentences:
+        sentence = sentence.strip()
+        if len(sentence) < 20:
+            continue
+        if re.search(combined_pattern, sentence):
+            # Clean up whitespace
+            claim = " ".join(sentence.split())
+            if len(claim) <= 500:  # Skip overly long passages
+                claims.append(claim)
+
+    return claims
+
+
+def _judge_claim(claim: str, evidence: List[SearchResult]) -> Tuple[str, float]:
+    """Produce a verdict for a claim based on search evidence.
+
+    Uses score thresholds and keyword overlap. Deterministic — no LLM.
+    Phase 2 can add LLM-based judgment using the evidence as context.
+    """
+    if not evidence:
+        return "no_evidence_found", 0.0
+
+    top_score = evidence[0].combined_score
+
+    # Calculate keyword overlap between claim and top evidence
+    claim_tokens = set(re.findall(r"\b\w+\b", claim.lower()))
+    evidence_tokens = set(re.findall(r"\b\w+\b", evidence[0].content.lower()))
+    if claim_tokens:
+        overlap = len(claim_tokens & evidence_tokens) / len(claim_tokens)
+    else:
+        overlap = 0.0
+
+    if top_score < 0.3 and overlap < 0.2:
+        return "no_evidence_found", top_score
+
+    if top_score > 0.7 and overlap > 0.4:
+        return "supported", top_score
+
+    if top_score > 0.5 or overlap > 0.3:
+        return "partially_supported", top_score
+
+    return "unsupported", top_score
+
+
+def main():
+    """CLI entry point."""
+    from ._cli_common import setup_logging, add_common_args, output_result, error_result
+    setup_logging()
+
+    parser = argparse.ArgumentParser(
+        description="Review a draft document by checking claims against source code"
+    )
+    parser.add_argument(
+        "--repo", required=True,
+        help="Path to the repository"
+    )
+    parser.add_argument(
+        "--draft", required=True,
+        help="Path to the markdown draft document"
+    )
+    parser.add_argument(
+        "--max-evidence", type=int, default=5,
+        help="Max evidence snippets per claim (default: 5)"
+    )
+    add_common_args(parser)
+
+    args = parser.parse_args()
+
+    try:
+        result = grounded_review(
+            repo_path=args.repo,
+            draft_path=args.draft,
+            max_evidence_per_claim=args.max_evidence,
+            db_path=args.db_path,
+            reindex=args.reindex,
+        )
+        output_result(result, args, filename="review.json")
+    except Exception as e:
+        error_result(str(e))
+
+
+if __name__ == "__main__":
+    main()

claude_context/synthesis/__init__.py

@@ -0,0 +1,8 @@
+from .llm_synthesizer import LLMSynthesizer
+
+__all__ = [
+    "LLMSynthesizer",
+]
+
+
+