gnost 0.1.0__tar.gz

gnost-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mohd Zain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gnost-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: gnost
+Version: 0.1.0
+Summary: GNOST — Codebase Knowledge
+Author-email: Mohd Zain <zainmohd1998@gmail.com>
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich
+Requires-Dist: tqdm
+Dynamic: license-file
+
+# GNOST — Codebase Knowledge
+![Status](https://img.shields.io/badge/status-v0.1.0--pre--release-yellow)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+
+
+GNOST helps developers understand unfamiliar codebases by automatically identifying **entry points**, **execution flow**, and **core logic**.
+
+It is designed for **first-day onboarding**, not just code statistics.
+
+---
+
+## What GNOST Does
+
+- Detects **where execution starts**
+- Infers **high-level execution flow**
+- Identifies **hotspot files** (most important code)
+- Generates **onboarding documentation**
+- Produces **Mermaid flow diagrams**
+- Works across multiple languages
+
+Supported languages:
+- Python
+- JavaScript
+- TypeScript
+- Java
+
+---
+
+## Installation
+
+```bash
+pip install gnost
+```
+
+## Quick Start
+```bash
+gnost onboard .
+```
+This will:
+- Print a human-readable onboarding summary
+- Generate ONBOARD.md
+- Generate an execution flow diagram
+
+## Usage
+```bash
+gnost summary [path]
+gnost stats [path]
+gnost folders [path]
+gnost files [path] --top 10
+gnost onboard [path]
+```
+
+## Key Commands
+- `summary` Show a high-level project summary
+- `stats` Show detailed language statistics
+- `folders` Show LOC grouped by folder
+- `files` Show largest files by LOC
+- `onboard` Generate onboarding summary and flow diagrams
+- `version` Display GNOST version
+
+## Onboarding & Flow Analysis
+- Generate onboarding documentation:
+  ```bash
+  gnost onboard .
+  ```
+- Generate only a Mermaid flow diagram:
+  ```bash
+  gnost onboard . --mermaid
+  ```
+  This produces:
+  - ONBOARD.md — onboarding guide
+  - FLOW.mmd — pure Mermaid flow diagram
+
+### Options
+- `--include` Comma-separated folders to include
+- `--exclude` Comma-separated folders to exclude
+- `--top` Number of files to show with files
+- `--version` Show version and exit
+- `--help` Show help
+
+## examples
+```bash
+gnost summary .
+gnost stats .
+gnost onboard .
+gnost onboard . --mermaid
+gnost files src --top 20
+```
+
+## Philosophy
+GNOST is not a **static analyzer or linter**.
+
+It focuses on:
+- Mental model generation
+- Execution understanding
+- Developer onboarding
+
+It uses **heuristic-based static analysis** to stay fast, simple, and language-agnostic.
+
+## Roadmap
+
+### v0.2.0 (Planned)
+
+- Hotspot visualization in Mermaid diagrams
+- Standalone `gnost hotspots` command
+- Improved JavaScript / TypeScript import resolution
+- Better framework awareness (Express, Spring MVC)
+- Optional Tree-sitter based parsing for deeper analysis
+- GitHub Action enhancements (PR comments, annotations)
+
+## License
+MIT License

gnost-0.1.0/README.md

@@ -0,0 +1,113 @@
+# GNOST — Codebase Knowledge
+![Status](https://img.shields.io/badge/status-v0.1.0--pre--release-yellow)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+
+
+GNOST helps developers understand unfamiliar codebases by automatically identifying **entry points**, **execution flow**, and **core logic**.
+
+It is designed for **first-day onboarding**, not just code statistics.
+
+---
+
+## What GNOST Does
+
+- Detects **where execution starts**
+- Infers **high-level execution flow**
+- Identifies **hotspot files** (most important code)
+- Generates **onboarding documentation**
+- Produces **Mermaid flow diagrams**
+- Works across multiple languages
+
+Supported languages:
+- Python
+- JavaScript
+- TypeScript
+- Java
+
+---
+
+## Installation
+
+```bash
+pip install gnost
+```
+
+## Quick Start
+```bash
+gnost onboard .
+```
+This will:
+- Print a human-readable onboarding summary
+- Generate ONBOARD.md
+- Generate an execution flow diagram
+
+## Usage
+```bash
+gnost summary [path]
+gnost stats [path]
+gnost folders [path]
+gnost files [path] --top 10
+gnost onboard [path]
+```
+
+## Key Commands
+- `summary` Show a high-level project summary
+- `stats` Show detailed language statistics
+- `folders` Show LOC grouped by folder
+- `files` Show largest files by LOC
+- `onboard` Generate onboarding summary and flow diagrams
+- `version` Display GNOST version
+
+## Onboarding & Flow Analysis
+- Generate onboarding documentation:
+  ```bash
+  gnost onboard .
+  ```
+- Generate only a Mermaid flow diagram:
+  ```bash
+  gnost onboard . --mermaid
+  ```
+  This produces:
+  - ONBOARD.md — onboarding guide
+  - FLOW.mmd — pure Mermaid flow diagram
+
+### Options
+- `--include` Comma-separated folders to include
+- `--exclude` Comma-separated folders to exclude
+- `--top` Number of files to show with files
+- `--version` Show version and exit
+- `--help` Show help
+
+## examples
+```bash
+gnost summary .
+gnost stats .
+gnost onboard .
+gnost onboard . --mermaid
+gnost files src --top 20
+```
+
+## Philosophy
+GNOST is not a **static analyzer or linter**.
+
+It focuses on:
+- Mental model generation
+- Execution understanding
+- Developer onboarding
+
+It uses **heuristic-based static analysis** to stay fast, simple, and language-agnostic.
+
+## Roadmap
+
+### v0.2.0 (Planned)
+
+- Hotspot visualization in Mermaid diagrams
+- Standalone `gnost hotspots` command
+- Improved JavaScript / TypeScript import resolution
+- Better framework awareness (Express, Spring MVC)
+- Optional Tree-sitter based parsing for deeper analysis
+- GitHub Action enhancements (PR comments, annotations)
+
+## License
+MIT License

gnost-0.1.0/gnost/__init__.py

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

gnost-0.1.0/gnost/cli/__init__.py

@@ -0,0 +1,3 @@
+from gnost.cli.app import main
+
+__all__ = ["main"]

gnost-0.1.0/gnost/cli/app.py

@@ -0,0 +1,111 @@
+import argparse
+from gnost import __version__
+from gnost.scanner.engine import scan
+from gnost.reporters import stats, folders, files, loc_summary
+from gnost.cli.commands.onboard import run as onboard_run
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="gnost",
+        usage="gnost [command]",
+        description="GNOST — Code Knowledge Scanner",
+        formatter_class=argparse.RawTextHelpFormatter,
+        epilog=(
+            "Command Options:\n"
+            "  summary|stats|folders|files:\n"
+            "    --include  Comma-separated folder names to include\n"
+            "    --exclude  Comma-separated folder names to exclude\n"
+            "    --progress Show a progress bar while scanning\n"
+            "  onboard:\n"
+            "    --progress Show a progress bar while onboarding\n"
+            "    --mermaid  Generate only Mermaid flow diagram\n"
+            "  files:\n"
+            "    --top      Number of files to show (default: 5)\n"
+            "Use `gnost <command> --help` for full command options."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"gnost {__version__}")
+
+    sub = parser.add_subparsers(
+        dest="cmd",
+        required=True,
+        title="Available Commands",
+        metavar="command",
+    )
+
+    base = argparse.ArgumentParser(add_help=False)
+    base.add_argument("path", nargs="?", default=".", help="Directory to scan")
+    base.add_argument(
+        "--exclude",
+        help="Comma-separated folder names to exclude (e.g. node_modules,dist)",
+    )
+    base.add_argument(
+        "--include",
+        help="Comma-separated folder names to include (only these are scanned)",
+    )
+    base.add_argument(
+        "--progress",
+        action="store_true",
+        help="Show a progress bar while scanning",
+    )
+
+    sub.add_parser("summary", parents=[base], help="Show a summary table")
+    sub.add_parser("stats", parents=[base], help="Show detailed stats per language")
+    sub.add_parser("folders", parents=[base], help="Show LOC grouped by folder")
+
+    files_parser = sub.add_parser(
+        "files", parents=[base], help="Show the largest files by LOC"
+    )
+    files_parser.add_argument(
+        "--top",
+        type=int,
+        default=5,
+        help="Number of files to show (default: 5)",
+    )
+
+    sub.add_parser("version", help="Display gnost version")
+    onboard = sub.add_parser("onboard", help="Onboard a new codebase")
+    onboard.add_argument("path", nargs="?", default=".")
+    onboard.add_argument(
+        "--mermaid",
+        action="store_true",
+        help="Generate only Mermaid flow diagram (FLOW.mmd)",
+    )
+    onboard.add_argument(
+        "--progress",
+        action="store_true",
+        help="Show a progress bar while onboarding",
+    )
+
+    args = parser.parse_args()
+
+    if args.cmd == "version":
+        print(f"gnost {__version__}")
+        return
+
+    if args.cmd == "onboard":
+        onboard_run(
+            args.path,
+            diagram_only=getattr(args, "mermaid", False),
+            progress=getattr(args, "progress", False),
+        )
+        return
+
+    include = args.include.split(",") if args.include else []
+    exclude = args.exclude.split(",") if args.exclude else []
+
+    data = scan(args.path, include, exclude, progress=args.progress)
+
+    if args.cmd == "stats":
+        stats.render(data)
+    elif args.cmd == "folders":
+        folders.render(data)
+    elif args.cmd == "files":
+        files.render(data, args.top)
+    else:
+        loc_summary.render(data)
+
+
+if __name__ == "__main__":
+    main()

gnost-0.1.0/gnost/cli/commands/__init__.py

@@ -0,0 +1,3 @@
+from gnost.cli.commands.onboard import run as onboard
+
+__all__ = ["onboard"]

gnost-0.1.0/gnost/cli/commands/onboard.py

@@ -0,0 +1,94 @@
+# gnost/cli/commands/onboard.py
+
+import os
+
+from gnost.languages.python import PythonAdapter
+from gnost.languages.javascript import JavaScriptAdapter
+from gnost.languages.typescript import TypeScriptAdapter
+from gnost.languages.java import JavaAdapter
+from gnost.scanner.engine import ScannerEngine
+from gnost.core.graph import DependencyGraph
+from gnost.core.flow import FlowBuilder
+from gnost.reporters.summary import SummaryReporter
+from gnost.reporters.markdown import MarkdownReporter
+from gnost.reporters.mermaid import MermaidFlowReporter
+from gnost.utils.progress import progress_bar
+
+
+def run(path: str | None = None, diagram_only: bool = False, progress: bool = False):
+    """
+    gnost onboard [path] [--mermaid]
+    Generates a high-level onboarding summary for a codebase.
+    """
+    root = os.path.abspath(path or ".")
+
+    with progress_bar(enabled=progress, total=4, desc="Onboarding") as bar:
+        # -------------------------
+        # 1. Language adapters
+        # -------------------------
+        adapters = [
+            PythonAdapter(),
+            JavaScriptAdapter(),
+            TypeScriptAdapter(),
+            JavaAdapter(),
+        ]
+
+        # -------------------------
+        # 2. Scan repository
+        # -------------------------
+        scanner = ScannerEngine(adapters=adapters)
+        scan_result = scanner.scan(root)
+        if bar is not None:
+            bar.update(1)
+
+        # -------------------------
+        # 3. Build dependency graph
+        # -------------------------
+        graph = DependencyGraph.from_scan(scan_result)
+        if bar is not None:
+            bar.update(1)
+
+        # -------------------------
+        # 4. Build execution flow
+        # -------------------------
+        flow_builder = FlowBuilder(graph=graph, scan=scan_result)
+        flow_result = flow_builder.build()
+        if bar is not None:
+            bar.update(1)
+
+        # -------------------------
+        # 5. Diagram-only mode
+        # -------------------------
+        if diagram_only:
+            diagram = MermaidFlowReporter(
+                flow=flow_result,
+                root=scan_result.root,
+            ).render(markdown=False)
+
+            output_path = os.path.join(root, "FLOW.mmd")
+            with open(output_path, "w", encoding="utf-8") as f:
+                f.write(diagram + "\n")
+
+            if bar is not None:
+                bar.update(1)
+
+            print(f"Mermaid flow diagram written to {output_path}")
+            return
+
+        # -------------------------
+        # 6. Normal onboarding
+        # -------------------------
+        SummaryReporter(
+            scan=scan_result,
+            flow=flow_result,
+            graph=graph,
+        ).render()
+
+        MarkdownReporter(
+            scan=scan_result,
+            flow=flow_result,
+            output_file="ONBOARD.md",
+        ).write()
+
+        if bar is not None:
+            bar.update(1)

gnost-0.1.0/gnost/config/languages.py

@@ -0,0 +1,23 @@
+LANG_EXTENSIONS = {
+    "py": "Python",
+    "js": "JavaScript",
+    "ts": "TypeScript",
+    "java": "Java",
+    "go": "Go",
+    "cpp": "C++",
+    "c": "C",
+    "cs": "C#",
+    "rs": "Rust",
+    "php": "PHP",
+    "html": "HTML",
+    "css": "CSS",
+}
+
+LANGUAGES = {
+    "py": {"name": "Python", "comment": "#"},
+    "js": {"name": "JavaScript", "comment": "//"},
+    "ts": {"name": "TypeScript", "comment": "//"},
+    "java": {"name": "Java", "comment": "//"},
+    "c": {"name": "C", "comment": "//"},
+    "cpp": {"name": "C++", "comment": "//"},
+}

gnost-0.1.0/gnost/core/counter.py

@@ -0,0 +1,23 @@
+import os
+from gnost.config.languages import LANG_EXTENSIONS
+
+
+def count_loc(path: str = "."):
+    results = {}
+    file_count = {}
+
+    for root, _, files in os.walk(path):
+        for f in files:
+            ext = f.split(".")[-1].lower()
+            if ext in LANG_EXTENSIONS:
+                file_count.setdefault(ext, 0)
+                results.setdefault(ext, 0)
+                file_count[ext] += 1
+
+                try:
+                    with open(os.path.join(root, f), "r", errors="ignore") as fh:
+                        results[ext] += sum(1 for _ in fh)
+                except:
+                    pass
+
+    return results, file_count

gnost-0.1.0/gnost/core/flow.py

@@ -0,0 +1,130 @@
+# gnost/core/flow.py
+
+from typing import List, Dict, Set
+from dataclasses import dataclass
+
+from gnost.scanner.models import ScanResult
+from gnost.languages.base import EntryPoint
+from gnost.core.graph import DependencyGraph
+
+
+@dataclass
+class FlowPath:
+    """
+    Represents one execution path.
+    """
+
+    start: str
+    path: List[str]
+
+
+@dataclass
+class FlowResult:
+    """
+    Complete flow analysis result.
+    """
+
+    entry_points: List[EntryPoint]
+    paths: List[FlowPath]
+    layers: Dict[str, Set[str]]  # entry, core, leaf
+
+
+class FlowBuilder:
+    """
+    Builds execution flow using:
+    - Entry points
+    - Dependency graph
+    """
+
+    def __init__(self, graph: DependencyGraph, scan: ScanResult):
+        self.graph = graph
+        self.scan = scan
+
+    # -------------------------
+    # Public API
+    # -------------------------
+
+    def build(self) -> FlowResult:
+        entry_files = self._resolve_entry_files()
+        paths: List[FlowPath] = []
+
+        for entry in entry_files:
+            self._walk(
+                start=entry,
+                current=entry,
+                visited=set(),
+                path=[],
+                paths=paths,
+            )
+
+        layers = self._classify_layers(paths)
+
+        return FlowResult(
+            entry_points=self.scan.entry_points,
+            paths=paths,
+            layers=layers,
+        )
+
+    def _walk(
+        self,
+        start: str,
+        current: str,
+        visited: Set[str],
+        path: List[str],
+        paths: List[FlowPath],
+    ):
+        if current in visited:
+            return
+
+        visited.add(current)
+        path.append(current)
+
+        dependencies = self.graph.dependencies_of(current)
+
+        if not dependencies:
+            paths.append(FlowPath(start=start, path=list(path)))
+        else:
+            for dep in dependencies:
+                self._walk(
+                    start=start,
+                    current=dep,
+                    visited=set(visited),
+                    path=list(path),
+                    paths=paths,
+                )
+
+    def _resolve_entry_files(self) -> List[str]:
+        """
+        Convert EntryPoint objects into concrete files.
+        """
+        resolved = []
+
+        for ep in self.scan.entry_points:
+            resolved.append(ep.file)
+
+        # Fallback: graph roots if no explicit entry point
+        if not resolved:
+            resolved.extend(self.graph.roots())
+
+        return list(set(resolved))
+
+    def _classify_layers(self, paths: List[FlowPath]) -> Dict[str, Set[str]]:
+        entry = set()
+        core = set()
+        leaf = set()
+
+        for flow in paths:
+            if not flow.path:
+                continue
+
+            entry.add(flow.path[0])
+            leaf.add(flow.path[-1])
+
+            for mid in flow.path[1:-1]:
+                core.add(mid)
+
+        return {
+            "entry": entry,
+            "core": core,
+            "leaf": leaf,
+        }