readmenator 1.0.0__py3-none-any.whl

readmenator/__init__.py

@@ -0,0 +1,20 @@
+"""Public API for the readmenator knowledge graph generator.
+
+Export the core types and application class used by external consumers:
+  - Config: immutable settings dataclass
+  - Symbol, Node, Edge: data model for codebase entities and relations
+  - readmenatorApplication: high-level orchestrator for scanning, querying,
+    and generating the KNOWLEDGE_BASE.md artifact
+"""
+
+from readmenator._app import readmenatorApplication
+from readmenator._config import Config
+from readmenator._models import Edge, Node, Symbol
+
+__all__ = [
+    "Config",
+    "Symbol",
+    "Node",
+    "Edge",
+    "readmenatorApplication",
+]

readmenator/__main__.py

@@ -0,0 +1,125 @@
+"""CLI entry point for readmenator.
+
+Parses command-line arguments, dispatches to the appropriate subcommand
+(query, explain, path, summary, --rebuild, --test), and manages the
+target directory analysis lifecycle.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import unittest
+from pathlib import Path
+
+from readmenator._app import readmenatorApplication
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the argument parser with subcommand help and examples."""
+    parser = argparse.ArgumentParser(
+        description="ReadMenator: Zero-token polyglot codebase knowledge graph generator.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Subcommands:\n"
+            "  query \"<question>\"   Answer a question using the knowledge base\n"
+            "  explain \"<symbol>\"   Explain a symbol with relationships\n"
+            "  path \"<A>\" \"<B>\"     Trace dependency chain between two symbols\n"
+            "\n"
+            "Examples:\n"
+            "  python -m readmenator /path/to/project\n"
+            "  python -m readmenator /path/to/project explain ClassName\n"
+            "  python -m readmenator . query \"What classes handle HTTP?\"\n"
+        ),
+    )
+    parser.add_argument(
+        "target",
+        nargs="?",
+        default=".",
+        help="Target directory to analyze (default: current directory)",
+    )
+    parser.add_argument(
+        "--rebuild",
+        action="store_true",
+        help="Force regeneration of KNOWLEDGE_BASE.md",
+    )
+    parser.add_argument(
+        "--test",
+        action="store_true",
+        help="Run the built-in test suite",
+    )
+    return parser
+
+
+def _run_tests() -> None:
+    """Discover and run the full test suite from the tests/ directory."""
+    package_dir = Path(__file__).resolve().parent.parent
+    tests_dir = package_dir / "tests"
+    if tests_dir.is_dir():
+        sys.path.insert(0, str(package_dir))
+        loader = unittest.TestLoader()
+        suite = loader.discover(str(tests_dir), pattern="test_*.py")
+        runner = unittest.TextTestRunner(verbosity=2)
+        result = runner.run(suite)
+        sys.exit(0 if result.wasSuccessful() else 1)
+    else:
+        print("No tests directory found.", file=sys.stderr)
+        sys.exit(1)
+
+
+def main() -> None:
+    """Primary CLI entry point invoked by ``python -m readmenator``.
+
+    Supports direct subcommand dispatch (query, explain, path, summary,
+    --rebuild, update) or falls back to the argument parser for the
+    default workflow: generate or summarise KNOWLEDGE_BASE.md.
+    """
+    if "--test" in sys.argv:
+        _run_tests()
+        return
+
+    if len(sys.argv) > 2 and sys.argv[1] != "--rebuild" and not sys.argv[1].startswith("-"):
+        target = sys.argv[1]
+        command = sys.argv[2]
+        app = readmenatorApplication()
+
+        if command == "query" and len(sys.argv) >= 4:
+            result = app.query(target, sys.argv[3])
+            print(result)
+        elif command == "explain" and len(sys.argv) >= 4:
+            result = app.explain(target, sys.argv[3])
+            print(result)
+        elif command == "path" and len(sys.argv) >= 5:
+            result = app.find_path(target, sys.argv[3], sys.argv[4])
+            print(result)
+        elif command in ("summary", "sum", "info"):
+            result = app.summary(target)
+            print(result)
+        elif command == "--rebuild":
+            app.rebuild(target)
+        elif command == "update":
+            app.rebuild(target)
+        else:
+            print(f"Unknown command: {command}", file=sys.stderr)
+            sys.exit(1)
+        return
+
+    parser = build_parser()
+    args = parser.parse_args()
+    target = args.target
+
+    app = readmenatorApplication()
+    output_path = Path(target) / "KNOWLEDGE_BASE.md"
+
+    if args.rebuild or not output_path.exists():
+        app.run(target)
+    else:
+        result = app.summary(target)
+        print(result)
+
+    print("\nRun with --rebuild to regenerate or use query/explain/path subcommands.")
+
+
+if __name__ == "__main__":
+    main()

readmenator/_app.py

@@ -0,0 +1,108 @@
+"""Application orchestrator for the readmenator pipeline.
+
+Wires together scanner, documentation generator, and query engine
+into a single facade consumed by the CLI entry point (__main__) and
+the public API (__init__).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from readmenator._config import Config
+from readmenator._documentation import DocumentationGenerator
+from readmenator._models import Edge, Node
+from readmenator._query import QueryEngine
+from readmenator._scanner import PolyglotScanner
+
+
+class readmenatorApplication:
+    """High-level facade for readmenator operations.
+
+    Provides convenience methods for the full pipeline:
+      - ``run`` / ``rebuild``: scan + generate KNOWLEDGE_BASE.md
+      - ``query``, ``explain``, ``find_path``, ``summary``:
+        scan + query in a single call.
+    """
+
+    def __init__(self, config: Optional[Config] = None) -> None:
+        """Initialise the application with an optional custom config.
+
+        Args:
+            config: Application settings; defaults to Config() if omitted.
+        """
+        self._config = config or Config()
+        self._scanner = PolyglotScanner(self._config)
+        self._generator = DocumentationGenerator(self._config)
+        self._last_nodes: List[Node] = []
+        self._last_edges: List[Edge] = []
+
+    def _scan(self, target_dir: str) -> Tuple[List[Node], List[Edge]]:
+        """Resolve *target_dir* and run the scanner, caching results."""
+        root = Path(target_dir).resolve()
+        nodes, edges = self._scanner.scan(root)
+        self._last_nodes = nodes
+        self._last_edges = edges
+        return nodes, edges
+
+    def run(self, target_dir: str) -> None:
+        """Scan *target_dir* and write KNOWLEDGE_BASE.md to disk.
+
+        Prints a summary of files, symbols, and imports on completion.
+        """
+        root = Path(target_dir).resolve()
+        nodes, edges = self._scanner.scan(root)
+        content = self._generator.generate(nodes, edges)
+        output_path = root / self._config.OUTPUT_FILENAME
+        output_path.write_text(content, encoding="utf-8")
+        total_symbols = sum(len(n.symbols) for n in nodes)
+        print(f"[+] Knowledge base generated: {output_path}")
+        print(
+            f"[+] Files: {len(nodes)} | "
+            f"Symbols: {total_symbols} | "
+            f"Imports: {len(edges)}"
+        )
+
+    def query(self, target_dir: str, question: str) -> str:
+        """Scan *target_dir* and answer *question* using the query engine."""
+        nodes, edges = self._scan(target_dir)
+        engine = QueryEngine(nodes, edges)
+        return engine.query(question)
+
+    def explain(self, target_dir: str, symbol_name: str) -> str:
+        """Scan *target_dir* and return a detailed explanation of *symbol_name*."""
+        nodes, edges = self._scan(target_dir)
+        engine = QueryEngine(nodes, edges)
+        result = engine.explain(symbol_name)
+        if result is None:
+            return (
+                f"Symbol '{symbol_name}' not found in the knowledge base. "
+                f"Scanned {len(nodes)} files with "
+                f"{sum(len(n.symbols) for n in nodes)} total symbols."
+            )
+        return result
+
+    def find_path(self, target_dir: str, symbol_a: str, symbol_b: str) -> str:
+        """Scan *target_dir* and find the shortest import path between two symbols."""
+        nodes, edges = self._scan(target_dir)
+        engine = QueryEngine(nodes, edges)
+        result = engine.find_path(symbol_a, symbol_b)
+        if result is None:
+            return (
+                f"Could not find a dependency path between '{symbol_a}' "
+                f"and '{symbol_b}'. They may be in disconnected components "
+                f"or one of the symbols does not exist."
+            )
+        path_str = " --imports--> ".join(result)
+        return f"Dependency path: {path_str}"
+
+    def summary(self, target_dir: str) -> str:
+        """Scan *target_dir* and return a concise knowledge base overview."""
+        nodes, edges = self._scan(target_dir)
+        engine = QueryEngine(nodes, edges)
+        return engine.summary()
+
+    def rebuild(self, target_dir: str) -> None:
+        """Alias for ``run`` -- forces regeneration of KNOWLEDGE_BASE.md."""
+        self.run(target_dir)

readmenator/_config.py

@@ -0,0 +1,78 @@
+"""Immutable configuration dataclass for readmenator.
+
+All tuneable parameters live here as frozen dataclass fields. No magic
+numbers or hardcoded paths exist elsewhere in the codebase. Derived
+consumers import Config and read values from an instance.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Tuple
+
+
+@dataclass(frozen=True)
+class Config:
+    """Single source of truth for all readmenator settings.
+
+    Every tuneable constant -- file-size limits, directory depth,
+    supported extensions, symbol pluralisation map, and Mermaid style
+    tokens -- is defined here and consumed by reference elsewhere.
+    """
+    IGNORE_DIRS: Tuple[str, ...] = (
+        ".git", "__pycache__", "venv", ".venv", "env", ".env", "node_modules",
+        ".tox", ".eggs", ".pytest_cache", "build", "dist", ".idea", ".vscode",
+        "target", "bin", "obj", "out", "vendor", "third_party", "deps",
+        "third-party", "thirdparty", ".m2", ".gradle", ".nuget", "packages",
+        "Pods", ".dart_tool", ".pub-cache", "bower_components", ".yarn",
+        "Carthage", "node_packages", ".meteor", ".gitlab", ".github",
+        "htmlcov", ".coverage", "__pycache__",
+    )
+
+    OUTPUT_FILENAME: str = "KNOWLEDGE_BASE.md"
+
+    MAX_FILE_SIZE_MB: float = 10.0
+
+    MAX_DIRECTORY_DEPTH: int = 20
+
+    DOCSTRING_LOOKBACK_LINES: int = 15
+
+    DOCSTRING_MAX_LENGTH: int = 150
+
+    MERMAID_MAX_NODES: int = 300
+
+    MERMAID_MODULE_STYLE: str = "fill:#1e1e1e,stroke:#ff6666,stroke-width:2px,color:#fff"
+
+    MERMAID_CLASS_STYLE: str = "fill:#2d2d2d,stroke:#4ec9b0,stroke-width:2px,color:#fff"
+
+    MERMAID_FUNCTION_STYLE: str = "fill:#333,stroke:#dcdcaa,stroke-width:1px,color:#dcdcaa"
+
+    MERMAID_EXTERNAL_STYLE: str = "fill:#111,stroke:#666,stroke-dasharray:5 5,color:#aaa"
+
+    SUPPORTED_EXTENSIONS: Tuple[str, ...] = (
+        ".c", ".cpp", ".cc", ".cxx", ".h", ".hpp", ".hxx",
+        ".py", ".go", ".rs",
+        ".js", ".ts", ".jsx", ".tsx",
+        ".java", ".cs",
+        ".sh", ".bash", ".zsh",
+        ".php", ".dart", ".gd", ".nim",
+        ".asm", ".s", ".S",
+    )
+
+    SYMBOL_TYPE_PLURALS: Tuple[Tuple[str, str], ...] = (
+        ("class", "classes"),
+        ("struct", "structs"),
+        ("function", "functions"),
+        ("method", "methods"),
+        ("macro", "macros"),
+        ("trait", "traits"),
+        ("enum", "enums"),
+        ("interface", "interfaces"),
+        ("record", "records"),
+        ("variable", "variables"),
+        ("constant", "constants"),
+        ("type_alias", "type_aliases"),
+        ("module", "modules"),
+        ("protocol", "protocols"),
+        ("extension", "extensions"),
+    )

readmenator/_documentation.py

@@ -0,0 +1,124 @@
+"""KNOWLEDGE_BASE.md generator for the readmenator project.
+
+Produces the human-readable Markdown artifact that contains the
+structural knowledge map (Mermaid graph), architecture reference
+grouped by language, and per-file symbol listings with docstrings
+and signatures.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+from readmenator._config import Config
+from readmenator._mermaid import MermaidRenderer
+from readmenator._models import Edge, Node, Symbol, pluralize_symbol_kind
+
+
+class DocumentationGenerator:
+    """Builds the KNOWLEDGE_BASE.md document from scanned nodes and edges.
+
+    Delegates graph rendering to MermaidRenderer and handles the
+    Markdown layout: header metadata, Mermaid block, and per-language
+    architecture sections with pluralised symbol kind headings.
+    """
+
+    def __init__(self, config: Config) -> None:
+        """Initialise with config and pre-compute the plural map.
+
+        Args:
+            config: Application settings including SYMBOL_TYPE_PLURALS.
+        """
+        self._config = config
+        self._mermaid = MermaidRenderer(config)
+        self._plural_map: Dict[str, str] = dict(config.SYMBOL_TYPE_PLURALS)
+
+    def generate(self, nodes: List[Node], edges: List[Edge]) -> str:
+        """Assemble the full KNOWLEDGE_BASE.md Markdown document.
+
+        Groups files by language, lists symbols per file under
+        pluralised kind headings (e.g. "Classes", "Functions"),
+        and includes a note when the Mermaid graph was pruned.
+
+        Returns:
+            Complete Markdown string ready to write to disk.
+        """
+        total_symbols = sum(len(n.symbols) for n in nodes)
+        graph_output, is_truncated = self._mermaid.render(nodes, edges)
+
+        sections: List[str] = [
+            "# Polyglot Codebase Knowledge Graph",
+            "",
+            "> Generated offline by **readmenator**. "
+            "Supports C, C++, Python, Go, Rust, JS/TS, Java, C#, Shell, PHP, "
+            "Dart, GDScript, Nim, ASM.",
+            "> No LLMs. No tokens. Pure static analysis. "
+            "See more [here](https://github.com/grisuno/ReadMenator)",
+            "",
+            f"**Total Files Parsed:** {len(nodes)} | "
+            f"**Total Symbols Extracted:** {total_symbols} | "
+            f"**Total Imports:** {len(edges)}",
+            "",
+            "## Structural Knowledge Map",
+        ]
+
+        if is_truncated:
+            sections.append(
+                "> **Note:** The visual graph below has been intelligently pruned "
+                f"to the top {self._config.MERMAID_MAX_NODES} most relevant nodes "
+                "to prevent rendering crashes. Full details of all "
+                f"{len(nodes)} files are documented below."
+            )
+            sections.append("")
+
+        sections.extend(
+            [
+                "```mermaid",
+                graph_output,
+                "```",
+                "",
+                "---",
+                "",
+                "## Architecture Reference",
+                "",
+            ]
+        )
+
+        files_by_lang: Dict[str, List[Node]] = {}
+        for node in nodes:
+            lang = node.language.upper() if node.language else "UNKNOWN"
+            if lang not in files_by_lang:
+                files_by_lang[lang] = []
+            files_by_lang[lang].append(node)
+
+        for lang, lang_nodes in sorted(files_by_lang.items()):
+            sections.append(f"### {lang} ({len(lang_nodes)} files)")
+            sections.append("")
+
+            for node in lang_nodes:
+                sections.append(f"#### `{node.label}`")
+                sections.append(f"**Path:** `{node.node_id}`")
+                sections.append("")
+
+                if node.symbols:
+                    symbols_by_type: Dict[str, List[Symbol]] = {}
+                    for symbol in node.symbols:
+                        if symbol.kind not in symbols_by_type:
+                            symbols_by_type[symbol.kind] = []
+                        symbols_by_type[symbol.kind].append(symbol)
+
+                    for sym_kind, symbols in sorted(symbols_by_type.items()):
+                        plural = pluralize_symbol_kind(sym_kind, self._plural_map)
+                        sections.append(f"**{plural.title()}:**")
+                        for symbol in symbols:
+                            doc_str = f" - *{symbol.doc}*" if symbol.doc else ""
+                            sig_str = f" `{symbol.signature}`" if symbol.signature else ""
+                            sections.append(
+                                f"- `{symbol.name}` (line {symbol.line}){sig_str}{doc_str}"
+                            )
+                        sections.append("")
+                else:
+                    sections.append("*No symbols extracted*")
+                    sections.append("")
+
+        return "\n".join(sections)

readmenator/_mermaid.py

@@ -0,0 +1,124 @@
+"""Mermaid graph renderer with intelligent pruning.
+
+Converts the internal Node/Edge graph into a Mermaid flowchart
+(string) suitable for embedding in Markdown. Handles node limits,
+deduplication, and CSS-like class styling.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Set, Tuple
+
+from readmenator._config import Config
+from readmenator._models import Edge, Node
+
+
+class MermaidRenderer:
+    """Renders a knowledge graph to Mermaid JS flowchart syntax.
+
+    Nodes are ordered by import count and symbol richness; the top
+    ``MERMAID_MAX_NODES`` entries are included. External dependencies
+    (import targets not matching any scanned file) appear as dashed
+    boxes.
+    """
+
+    def __init__(self, config: Config) -> None:
+        """Initialise with configuration for style tokens and node limits.
+
+        Args:
+            config: Provides MERMAID_* style strings and MERMAID_MAX_NODES.
+        """
+        self._config = config
+
+    def _sanitize_id(self, node_id: str) -> str:
+        """Convert *node_id* to a Mermaid-safe identifier.
+
+        Replaces non-alphanumeric characters with underscores and
+        prepends ``n_`` if the result starts with a digit.
+        """
+        sanitized = re.sub(r"[^a-zA-Z0-9]", "_", node_id)
+        if sanitized and sanitized[0].isdigit():
+            sanitized = "n_" + sanitized
+        return sanitized
+
+    def render(self, nodes: List[Node], edges: List[Edge]) -> Tuple[str, bool]:
+        """Produce a Mermaid flowchart string and a truncation flag.
+
+        Nodes are sorted by import popularity, then by symbol count.
+        At most ``MERMAID_MAX_NODES`` items (files + child symbols +
+        external deps) are emitted. External imports use dashed edges.
+
+        Returns:
+            Tuple of (Mermaid source string, is_truncated bool).
+        """
+        lines: List[str] = ["graph TD"]
+        lines.append(f"    classDef mod {self._config.MERMAID_MODULE_STYLE};")
+        lines.append(f"    classDef cls {self._config.MERMAID_CLASS_STYLE};")
+        lines.append(f"    classDef fn {self._config.MERMAID_FUNCTION_STYLE};")
+        lines.append(f"    classDef ext {self._config.MERMAID_EXTERNAL_STYLE};")
+
+        seen_ids: Set[str] = set()
+        node_count = 0
+        is_truncated = False
+        max_nodes = self._config.MERMAID_MAX_NODES
+
+        import_counts: Dict[str, int] = {node.node_id: 0 for node in nodes}
+        for edge in edges:
+            if edge.source in import_counts:
+                import_counts[edge.source] += 1
+
+        sorted_nodes = sorted(
+            nodes,
+            key=lambda n: (import_counts.get(n.node_id, 0), len(n.symbols)),
+            reverse=True,
+        )
+
+        for node in sorted_nodes:
+            safe_id = self._sanitize_id(node.node_id)
+            if safe_id in seen_ids:
+                continue
+            label = node.label.replace('"', '\\"')
+            lines.append(f'    {safe_id}["{label} ({node.language})"]')
+            lines.append(f"    class {safe_id} mod;")
+            seen_ids.add(safe_id)
+            node_count += 1
+
+            for symbol in node.symbols[:5]:
+                if node_count >= max_nodes:
+                    is_truncated = True
+                    break
+                symbol_id = f"{safe_id}_{self._sanitize_id(symbol.name)}"
+                symbol_label = symbol.name.replace('"', '\\"')
+                lines.append(f'    {symbol_id}["{symbol_label}"]')
+                cls_types = {"class", "struct", "interface", "trait", "enum", "record"}
+                if symbol.kind in cls_types:
+                    lines.append(f"    class {symbol_id} cls;")
+                else:
+                    lines.append(f"    class {symbol_id} fn;")
+                lines.append(f"    {safe_id} --> {symbol_id}")
+                node_count += 1
+
+            if node_count >= max_nodes:
+                is_truncated = True
+                break
+
+        for edge in edges:
+            if is_truncated:
+                break
+            src = self._sanitize_id(edge.source)
+            if src not in seen_ids:
+                continue
+            target_id = self._sanitize_id(f"ext_{edge.target}")
+            target_label = edge.target.split("/")[-1].replace('"', '\\"')
+            if target_id not in seen_ids:
+                if node_count >= max_nodes:
+                    is_truncated = True
+                    break
+                lines.append(f'    {target_id}["{target_label}"]')
+                lines.append(f"    class {target_id} ext;")
+                seen_ids.add(target_id)
+                node_count += 1
+            lines.append(f"    {src} -.->|imports| {target_id}")
+
+        return "\n".join(lines), is_truncated

readmenator/_models.py

@@ -0,0 +1,75 @@
+"""Data model types for the readmenator knowledge graph.
+
+Defines the three core entity types -- Symbol, Node, Edge -- plus a
+utility function for pluralising symbol kind labels. Every parser,
+scanner, renderer, and query engine depends on these definitions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+
+@dataclass
+class Symbol:
+    """A single code symbol extracted from a source file.
+
+    Attributes:
+        name: Identifier of the symbol (class name, function name, etc.).
+        kind: Semantic type (class, function, struct, enum, ...).
+        line: One-based line number where the symbol is defined.
+        doc: Optional docstring or comment extracted from the source.
+        signature: Optional method or function signature snippet.
+    """
+
+    name: str
+    kind: str
+    line: int
+    doc: str = ""
+    signature: str = ""
+
+
+@dataclass
+class Node:
+    """A file node in the knowledge graph, containing its symbols.
+
+    Attributes:
+        node_id: Relative path of the file used as a unique identifier.
+        label: Base file name for display purposes.
+        kind: Type of node (typically "module").
+        language: Programming language derived from the file extension.
+        doc: Optional file-level documentation string.
+        symbols: List of Symbol instances defined in this file.
+    """
+
+    node_id: str
+    label: str
+    kind: str
+    language: str
+    doc: str = ""
+    symbols: List[Symbol] = field(default_factory=list)
+
+
+@dataclass
+class Edge:
+    """A directed relationship between two nodes in the knowledge graph.
+
+    Attributes:
+        source: Node ID of the source (dependent) file.
+        target: Node ID of the target (dependency) file or module.
+        relation: Semantic relation label (e.g. "imports").
+    """
+
+    source: str
+    target: str
+    relation: str
+
+
+def pluralize_symbol_kind(kind: str, plural_map: Dict[str, str]) -> str:
+    """Return the plural form of *kind* according to *plural_map*.
+
+    Falls back to appending ``"s"`` when the kind is not found.
+    This prevents obvious misspellings like ``"Classs"``.
+    """
+    return plural_map.get(kind, kind + "s")