projectreadmegen 1.0.0__tar.gz

projectreadmegen-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zenith Open Source Projects
+
+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.

projectreadmegen-1.0.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: projectreadmegen
+Version: 1.0.0
+Summary: Auto-generate README files from folder structure
+License: MIT License
+        
+        Copyright (c) 2026 Zenith Open Source Projects
+        
+        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.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer[all]>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: jinja2>=3.1
+Requires-Dist: flask>=3.0
+Dynamic: license-file

projectreadmegen-1.0.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires      = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name            = "projectreadmegen"
+version         = "1.0.0"
+description     = "Auto-generate README files from folder structure"
+readme          = "README.md"
+requires-python = ">=3.10"
+license         = { file = "LICENSE" }
+
+dependencies = [
+    "typer[all]>=0.12",
+    "rich>=13",
+    "jinja2>=3.1",
+    "flask>=3.0",
+]
+
+[project.scripts]
+readmegen = "cli:app"

projectreadmegen-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

projectreadmegen-1.0.0/src/badges.py

@@ -0,0 +1,72 @@
+# src/badges.py
+
+
+def lang_badge(language: str) -> str:
+    """Return a language badge."""
+    colors = {
+        "Python":     "3776AB",
+        "JavaScript": "F7DF1E",
+        "TypeScript": "3178C6",
+        "C++":        "00599C",
+        "C":          "A8B9CC",
+        "Rust":       "000000",
+        "Go":         "00ADD8",
+        "Java":       "007396",
+        "HTML/CSS":   "E34F26",
+        "Shell":      "4EAA25",
+        "PowerShell": "5391FE",
+    }
+    color = colors.get(language, "555555")
+    label = language.replace("+", "%2B").replace("/", "%2F").replace(" ", "%20")
+    return f"![Language](https://img.shields.io/badge/Language-{label}-{color})"
+
+
+def license_badge(license_id: str) -> str:
+    """Return a license badge."""
+    if license_id in ["None", "Unknown", ""]:
+        return ""
+    label = license_id.replace("-", "--").replace(" ", "%20")
+    return f"![License](https://img.shields.io/badge/License-{label}-blue)"
+
+
+def platform_badge(platform: str) -> str:
+    """Return a platform badge (Linux, Windows, Cross-Platform)."""
+    colors = {
+        "Linux":         "FCC624",
+        "Windows":       "0078D6",
+        "Cross-Platform":"brightgreen",
+    }
+    color = colors.get(platform, "lightgrey")
+    return f"![Platform](https://img.shields.io/badge/Platform-{platform}-{color})"
+
+
+def build_badge_line(detection: dict) -> str:
+    """
+    Build the full badge line for a README from detection results.
+
+    Parameters:
+        detection (dict): Output from detector.detect_stack().
+
+    Returns:
+        str: One line of Markdown with all relevant badges space-separated.
+    """
+    badges = []
+    
+    lang = detection.get("primary_lang", "")
+    if lang and lang != "Unknown":
+        badges.append(lang_badge(lang))
+    
+    lic = detection.get("license", "None")
+    if lic and lic != "None":
+        b = license_badge(lic)
+        if b:
+            badges.append(b)
+    
+    return "  ".join(badges)
+
+
+if __name__ == "__main__":
+    print(lang_badge("Python"))
+    print(lang_badge("C++"))
+    print(license_badge("MIT"))
+    print(build_badge_line({"primary_lang": "TypeScript", "license": "MIT"}))

projectreadmegen-1.0.0/src/config.py

@@ -0,0 +1,49 @@
+# src/config.py
+
+LANG_PATTERNS = {
+    "Python":     ["requirements.txt", "setup.py", "pyproject.toml", "*.py", "Pipfile"],
+    "JavaScript": ["package.json", "*.js", ".eslintrc", ".babelrc"],
+    "TypeScript": ["tsconfig.json", "*.ts", "*.tsx"],
+    "C++":        ["CMakeLists.txt", "*.cpp", "*.hpp", "Makefile"],
+    "C":          ["*.c", "*.h", "Makefile"],
+    "Rust":       ["Cargo.toml", "*.rs"],
+    "Go":         ["go.mod", "*.go"],
+    "Java":       ["pom.xml", "build.gradle", "*.java"],
+    "HTML/CSS":   ["*.html", "*.css"],
+    "Shell":      ["*.sh", "*.bash"],
+    "PowerShell": ["*.ps1"],
+}
+
+LICENSE_NAMES = {
+    "LICENSE":        "Unknown",
+    "LICENSE.md":     "Unknown",
+    "LICENSE.txt":    "Unknown",
+    "LICENSE-MIT":    "MIT",
+    "LICENSE-APACHE": "Apache-2.0",
+}
+
+SKIP_DIRS = {
+    ".git", ".svn", "__pycache__", "node_modules",
+    ".venv", "venv", "env", ".env",
+    "dist", "build", ".next", ".nuxt",
+    "target", "bin", "obj",
+    ".idea", ".vscode",
+}
+
+SKIP_FILES = {
+    ".DS_Store", "Thumbs.db", "desktop.ini",
+    "*.pyc", "*.pyo", "*.class", "*.o",
+}
+
+DEFAULT_CONFIG = {
+    "template":          "standard",
+    "output_file":       "README.md",
+    "include_tree":      True,
+    "max_tree_depth":    3,
+    "include_badges":    True,
+    "gemini_enabled":    False,
+    "author":            "",
+    "github_username":   "",
+}
+
+TEMPLATES_DIR = "templates"

projectreadmegen-1.0.0/src/detector.py

@@ -0,0 +1,212 @@
+# src/detector.py
+
+import sys
+from pathlib import Path
+
+if __name__ != "__main__":
+    from src.config import LANG_PATTERNS, LICENSE_NAMES
+else:
+    sys.path.insert(0, str(Path(__file__).parent.parent))
+    from src.config import LANG_PATTERNS, LICENSE_NAMES
+
+
+def detect_stack(scan_result: dict) -> dict:
+    """
+    Analyze scan result and detect languages, license, and project type.
+
+    Parameters:
+        scan_result (dict): Output from scanner.scan_directory().
+
+    Returns:
+        dict: {
+            "languages":     list[str] — detected languages in priority order,
+            "primary_lang":  str — most likely main language,
+            "license":       str — license identifier or "None",
+            "project_type":  str — one of: "library", "cli-tool", "web-app",
+                                   "telegram-bot", "game", "script", "unknown",
+            "description_hint": str — one sentence hint for README description,
+            "has_tests":     bool,
+            "has_docs":      bool,
+            "install_cmd":   str — likely install command,
+            "run_cmd":       str — likely run command,
+        }
+    """
+    files = scan_result["files"]
+    dirs  = scan_result["dirs"]
+    exts  = scan_result["file_extensions"]
+    name  = scan_result["name"]
+    
+    languages   = _detect_languages(files, exts)
+    primary     = languages[0] if languages else "Unknown"
+    license_id  = _detect_license(files, scan_result["root"])
+    proj_type   = _detect_project_type(files, dirs, languages, name)
+    desc_hint   = _build_description_hint(name, primary, proj_type)
+    install_cmd = _detect_install_command(files, primary)
+    run_cmd     = _detect_run_command(files, dirs, primary, proj_type)
+    
+    return {
+        "languages":        languages,
+        "primary_lang":     primary,
+        "license":          license_id,
+        "project_type":     proj_type,
+        "description_hint": desc_hint,
+        "has_tests":        any(d in dirs for d in ["tests", "test", "__tests__", "spec"]),
+        "has_docs":         any(d in dirs for d in ["docs", "doc", "documentation"]),
+        "install_cmd":      install_cmd,
+        "run_cmd":          run_cmd,
+    }
+
+
+def _detect_languages(files: list, extensions: list) -> list:
+    """
+    Detect languages from files and extensions, returns sorted by confidence.
+    """
+    scores = {}
+    
+    for lang, patterns in LANG_PATTERNS.items():
+        score = 0
+        for pattern in patterns:
+            if pattern.startswith("*."):
+                ext = pattern[1:]
+                if ext in extensions:
+                    score += 2
+            else:
+                if pattern in files:
+                    score += 5
+        
+        if score > 0:
+            scores[lang] = score
+    
+    return sorted(scores.keys(), key=lambda l: scores[l], reverse=True)
+
+
+def _detect_license(files: list, root: str) -> str:
+    """
+    Detect license type from license files.
+    """
+    for fname in files:
+        if fname.upper() in [f.upper() for f in LICENSE_NAMES.keys()]:
+            try:
+                license_path = Path(root) / fname
+                with open(license_path, "r", encoding="utf-8") as f:
+                    first_line = f.readline().upper()
+                
+                if "MIT" in first_line:
+                    return "MIT"
+                elif "APACHE" in first_line:
+                    return "Apache-2.0"
+                elif "GNU GENERAL PUBLIC" in first_line:
+                    return "GPL-3.0"
+                elif "BSD" in first_line:
+                    return "BSD-3-Clause"
+                else:
+                    return "See LICENSE"
+            except (IOError, UnicodeDecodeError):
+                return "See LICENSE"
+    
+    return "None"
+
+
+def _detect_project_type(files: list, dirs: list, languages: list, name: str) -> str:
+    """
+    Classify project type based on files, dirs, and detected languages.
+    """
+    name_lower = name.lower()
+    
+    if any(f in files for f in ["bot.py", "main.py"]) and "Python" in languages:
+        if any(kw in name_lower for kw in ["bot", "telegram", "monolith"]):
+            return "telegram-bot"
+    
+    if any(f in files for f in ["package.json", "index.html", "tsconfig.json"]):
+        if any(d in dirs for d in ["src", "public", "pages", "components"]):
+            return "web-app"
+    
+    if any(f in files for f in ["cli.py", "main.py", "setup.py", "pyproject.toml"]):
+        if "Python" in languages:
+            return "cli-tool"
+    
+    if "CMakeLists.txt" in files or "Makefile" in files:
+        if "C++" in languages:
+            return "cli-tool"
+    
+    if any(f.endswith(".sh") or f.endswith(".ps1") for f in files):
+        return "script"
+    
+    if any(kw in name_lower for kw in ["game", "numsuko", "logic"]):
+        return "game"
+    
+    return "unknown"
+
+
+def _build_description_hint(name: str, lang: str, proj_type: str) -> str:
+    """
+    Build a one-sentence description template based on detected metadata.
+    """
+    type_phrases = {
+        "telegram-bot": f"A Telegram bot built with {lang}",
+        "web-app":      f"A web application built with {lang}",
+        "cli-tool":     f"A command-line tool written in {lang}",
+        "game":         f"An interactive game written in {lang}",
+        "script":       f"A collection of automation scripts",
+        "library":      f"A {lang} library",
+        "unknown":      f"A {lang} project",
+    }
+    
+    phrase = type_phrases.get(proj_type, f"A {lang} project")
+    return f"{phrase} — {name.replace('-', ' ').replace('_', ' ').title()}."
+
+
+def _detect_install_command(files: list, primary_lang: str) -> str:
+    """
+    Return the most likely install command based on detected stack.
+    """
+    if "requirements.txt" in files:
+        return "pip install -r requirements.txt"
+    elif "pyproject.toml" in files:
+        return "pip install ."
+    elif "package.json" in files:
+        return "npm install"
+    elif "Cargo.toml" in files:
+        return "cargo build"
+    elif "CMakeLists.txt" in files:
+        return "cmake -B build && cmake --build build"
+    elif "Makefile" in files:
+        return "make"
+    else:
+        return "# See setup instructions below"
+
+
+def _detect_run_command(files: list, dirs: list, primary_lang: str, proj_type: str) -> str:
+    """
+    Return the most likely run command.
+    """
+    if proj_type == "cli-tool" and "cli.py" in files:
+        return "python cli.py"
+    elif proj_type == "cli-tool" and "main.py" in files:
+        return "python main.py"
+    elif proj_type == "telegram-bot":
+        return "python bot.py"
+    elif proj_type == "web-app" and "package.json" in files:
+        return "npm run dev"
+    elif "CMakeLists.txt" in files:
+        return "./build/projectname"
+    elif "Makefile" in files:
+        return "make run"
+    else:
+        return "# See usage section below"
+
+
+if __name__ == "__main__":
+    import sys
+    from src.scanner import scan_directory
+    
+    path = sys.argv[1] if len(sys.argv) > 1 else "."
+    scan  = scan_directory(path, max_depth=3)
+    detec = detect_stack(scan)
+    
+    print(f"Languages : {detec['languages']}")
+    print(f"Primary   : {detec['primary_lang']}")
+    print(f"Type      : {detec['project_type']}")
+    print(f"License   : {detec['license']}")
+    print(f"Install   : {detec['install_cmd']}")
+    print(f"Run       : {detec['run_cmd']}")

projectreadmegen-1.0.0/src/generator.py

@@ -0,0 +1,90 @@
+# src/generator.py
+
+import sys
+from pathlib import Path
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+if __name__ != "__main__":
+    from src.badges import build_badge_line
+else:
+    sys.path.insert(0, str(Path(__file__).parent.parent))
+    from src.badges import build_badge_line
+
+
+def generate_readme(scan_result: dict, detection: dict, config: dict) -> str:
+    """
+    Generate a complete README.md string from scan + detection data.
+
+    Parameters:
+        scan_result (dict): Output from scanner.scan_directory().
+        detection   (dict): Output from detector.detect_stack().
+        config      (dict): Merged config from scanner.load_config().
+
+    Returns:
+        str: Full README.md content as a string.
+    """
+    template_name   = config.get("template", "standard")
+    template_file   = f"{template_name}.md.j2"
+    templates_dir   = Path(__file__).parent / "templates"
+    
+    if not (templates_dir / template_file).exists():
+        raise FileNotFoundError(
+            f"Template '{template_file}' not found in {templates_dir}. "
+            f"Available: minimal, standard, full, academic"
+        )
+    
+    env = Environment(
+        loader=FileSystemLoader(str(templates_dir)),
+        autoescape=select_autoescape([]),
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+    
+    template = env.get_template(template_file)
+    
+    context = {
+        "project_name":    _format_title(scan_result["name"]),
+        "project_raw_name": scan_result["name"],
+        "description":     detection["description_hint"],
+        "author":          config.get("author", ""),
+        "github_username": config.get("github_username", ""),
+        
+        "badge_line":      build_badge_line(detection) if config.get("include_badges") else "",
+        
+        "primary_lang":    detection["primary_lang"],
+        "all_languages":   detection["languages"],
+        "project_type":    detection["project_type"],
+        
+        "install_cmd":     detection["install_cmd"],
+        "run_cmd":         detection["run_cmd"],
+        
+        "folder_tree":     scan_result["tree"] if config.get("include_tree") else "",
+        
+        "has_license":      scan_result["has_license"],
+        "has_contributing": scan_result["has_contributing"],
+        "has_tests":        detection["has_tests"],
+        "has_docs":         detection["has_docs"],
+        "license_id":       detection["license"],
+    }
+    
+    return template.render(**context)
+
+
+def save_readme(content: str, output_path: str) -> None:
+    """
+    Write the generated README content to a file.
+
+    Parameters:
+        content (str): The full README Markdown string.
+        output_path (str): Full path where README.md should be written.
+    """
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+
+def _format_title(raw_name: str) -> str:
+    """
+    Convert a folder name like 'projectreadmegen' or 'my-project'
+    into a display title like 'Projectreadmegen' or 'My Project'.
+    """
+    return raw_name.replace("-", " ").replace("_", " ").title()

projectreadmegen-1.0.0/src/projectreadmegen.egg-info/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: projectreadmegen
+Version: 1.0.0
+Summary: Auto-generate README files from folder structure
+License: MIT License
+        
+        Copyright (c) 2026 Zenith Open Source Projects
+        
+        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.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer[all]>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: jinja2>=3.1
+Requires-Dist: flask>=3.0
+Dynamic: license-file

projectreadmegen-1.0.0/src/projectreadmegen.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+pyproject.toml
+src/__init__.py
+src/badges.py
+src/config.py
+src/detector.py
+src/generator.py
+src/scanner.py
+src/projectreadmegen.egg-info/PKG-INFO
+src/projectreadmegen.egg-info/SOURCES.txt
+src/projectreadmegen.egg-info/dependency_links.txt
+src/projectreadmegen.egg-info/entry_points.txt
+src/projectreadmegen.egg-info/requires.txt
+src/projectreadmegen.egg-info/top_level.txt
+src/web/app.py
+tests/test_detector.py
+tests/test_generator.py
+tests/test_scanner.py

projectreadmegen-1.0.0/src/projectreadmegen.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

projectreadmegen-1.0.0/src/projectreadmegen.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+readmegen = cli:app

projectreadmegen-1.0.0/src/projectreadmegen.egg-info/requires.txt

@@ -0,0 +1,4 @@
+typer[all]>=0.12
+rich>=13
+jinja2>=3.1
+flask>=3.0

projectreadmegen-1.0.0/src/projectreadmegen.egg-info/top_level.txt

@@ -0,0 +1,8 @@
+__init__
+badges
+config
+detector
+generator
+scanner
+templates
+web

projectreadmegen-1.0.0/src/scanner.py

@@ -0,0 +1,150 @@
+# src/scanner.py
+
+import os
+import sys
+import json
+from pathlib import Path
+
+if __name__ != "__main__":
+    from src.config import SKIP_DIRS, SKIP_FILES, DEFAULT_CONFIG
+else:
+    sys.path.insert(0, str(Path(__file__).parent.parent))
+    from src.config import SKIP_DIRS, SKIP_FILES, DEFAULT_CONFIG
+
+
+def scan_directory(root_path: str, max_depth: int | None = None) -> dict:
+    """
+    Walk a directory and collect metadata about its structure.
+
+    Parameters:
+        root_path (str): Absolute or relative path to the project root.
+        max_depth (int): Maximum depth to traverse. None = unlimited.
+
+    Returns:
+        dict: {
+            "root": str — absolute path,
+            "name": str — folder name (used as project title),
+            "files": list[str] — all file names found (not paths),
+            "dirs":  list[str] — all directory names found,
+            "tree":  str — ASCII tree representation,
+            "has_license": bool,
+            "has_contributing": bool,
+            "has_gitignore": bool,
+            "has_existing_readme": bool,
+            "file_extensions": list[str] — unique extensions found,
+        }
+    """
+    root = Path(root_path).resolve()
+    
+    all_files = []
+    all_dirs  = []
+    extensions = set()
+    
+    for dirpath, dirnames, filenames in os.walk(root):
+        current_depth = len(Path(dirpath).relative_to(root).parts)
+        
+        if max_depth is not None and current_depth >= max_depth:
+            dirnames.clear()
+            continue
+        
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith('.')]
+        
+        for filename in filenames:
+            if filename.startswith('.') and filename not in ['.gitignore', '.env.example']:
+                continue
+            
+            all_files.append(filename)
+            ext = Path(filename).suffix.lower()
+            if ext:
+                extensions.add(ext)
+        
+        for dirname in dirnames:
+            all_dirs.append(dirname)
+    
+    tree_str = _build_tree(root, max_depth)
+    
+    return {
+        "root":               str(root),
+        "name":               root.name,
+        "files":              all_files,
+        "dirs":               all_dirs,
+        "tree":               tree_str,
+        "has_license":        any(f in all_files for f in ["LICENSE", "LICENSE.md", "LICENSE.txt", "license"]),
+        "has_contributing":   any(f.upper() in ["CONTRIBUTING.MD", "CONTRIBUTING.TXT"] for f in all_files),
+        "has_gitignore":      ".gitignore" in all_files,
+        "has_existing_readme": any(f.lower() == "readme.md" for f in all_files),
+        "file_extensions":    sorted(list(extensions)),
+    }
+
+
+def _build_tree(root: Path, max_depth: int | None = None, prefix: str = "", current_depth: int = 0) -> str:
+    """
+    Recursively build an ASCII directory tree string.
+
+    Parameters:
+        root (Path): Current directory path.
+        max_depth (int): Maximum recursion depth.
+        prefix (str): Indentation prefix for the current level.
+        current_depth (int): Tracks current recursion depth.
+
+    Returns:
+        str: Multi-line ASCII tree string.
+    """
+    if max_depth is not None and current_depth > max_depth:
+        return ""
+    
+    lines = []
+    
+    try:
+        entries = sorted(root.iterdir(), key=lambda e: (e.is_file(), e.name.lower()))
+    except PermissionError:
+        return ""
+    
+    entries = [e for e in entries 
+               if not e.name.startswith('.') 
+               and e.name not in SKIP_DIRS]
+    
+    for i, entry in enumerate(entries):
+        is_last = (i == len(entries) - 1)
+        connector = "└── " if is_last else "├── "
+        lines.append(f"{prefix}{connector}{entry.name}")
+        
+        if entry.is_dir():
+            extension = "    " if is_last else "│   "
+            subtree = _build_tree(entry, max_depth, prefix + extension, current_depth + 1)
+            if subtree:
+                lines.append(subtree)
+    
+    return "\n".join(lines)
+
+
+def load_config(root_path: str) -> dict:
+    """
+    Load readmegen.config.json from the project root if it exists,
+    otherwise return DEFAULT_CONFIG.
+
+    Parameters:
+        root_path (str): Path to the project root.
+
+    Returns:
+        dict: Merged configuration (user config overrides defaults).
+    """
+    config_path = Path(root_path) / "readmegen.config.json"
+    config = DEFAULT_CONFIG.copy()
+    
+    if config_path.exists():
+        with open(config_path, "r", encoding="utf-8") as f:
+            user_config = json.load(f)
+        config.update(user_config)
+    
+    return config
+
+
+if __name__ == "__main__":
+    import sys
+    path = sys.argv[1] if len(sys.argv) > 1 else "."
+    result = scan_directory(path, max_depth=3)
+    print(f"Project: {result['name']}")
+    print(f"Files found: {len(result['files'])}")
+    print(f"Extensions: {result['file_extensions']}")
+    print(f"\nTree:\n{result['tree']}")

projectreadmegen-1.0.0/src/web/app.py

@@ -0,0 +1,100 @@
+# src/web/app.py
+
+import sys
+import os
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from flask import Flask, render_template, request, jsonify
+from src.scanner import scan_directory, load_config
+from src.detector import detect_stack
+from src.generator import generate_readme
+
+app = Flask(__name__, template_folder="templates", static_folder="static")
+
+
+@app.route("/")
+def index():
+    """Render the main input page."""
+    return render_template("index.html")
+
+
+@app.route("/generate", methods=["POST"])
+def generate():
+    """
+    Accept a folder tree string (textarea input),
+    run the generator, return rendered README as JSON.
+    """
+    data = request.get_json()
+    tree_txt = data.get("tree", "").strip()
+    template = data.get("template", "standard")
+    author = data.get("author", "")
+    username = data.get("github_username", "")
+    
+    if not tree_txt:
+        return jsonify({"error": "No folder tree provided."}), 400
+    
+    scan_result = _parse_tree_to_scan(tree_txt)
+    
+    config = {
+        "template": template,
+        "include_badges": True,
+        "include_tree": True,
+        "max_tree_depth": 3,
+        "output_file": "README.md",
+        "author": author,
+        "github_username": username,
+    }
+    
+    detection = detect_stack(scan_result)
+    readme = generate_readme(scan_result, detection, config)
+    
+    return jsonify({
+        "readme": readme,
+        "language": detection["primary_lang"],
+        "type": detection["project_type"],
+        "license": detection["license"],
+    })
+
+
+def _parse_tree_to_scan(tree_text: str) -> dict:
+    """
+    Parse a pasted ASCII folder tree into a minimal scan_result dict.
+    """
+    lines = tree_text.strip().splitlines()
+    files = []
+    dirs = []
+    extensions = set()
+    
+    project_name = lines[0].strip().rstrip("/") if lines else "my-project"
+    
+    for line in lines[1:]:
+        name = line.replace("├──", "").replace("└──", "").replace("│", "").replace(" ", "").strip()
+        
+        if not name:
+            continue
+        
+        if "." in name:
+            files.append(name)
+            ext = "." + name.split(".")[-1].lower()
+            extensions.add(ext)
+        else:
+            dirs.append(name)
+    
+    return {
+        "root": "",
+        "name": project_name,
+        "files": files,
+        "dirs": dirs,
+        "tree": "\n".join(lines[1:]),
+        "has_license": any(f in files for f in ["LICENSE", "LICENSE.md", "license"]),
+        "has_contributing": any("contributing" in f.lower() for f in files),
+        "has_gitignore": ".gitignore" in files,
+        "has_existing_readme": any(f.lower() == "readme.md" for f in files),
+        "file_extensions": sorted(list(extensions)),
+    }
+
+
+if __name__ == "__main__":
+    app.run(debug=True, port=5000)

projectreadmegen-1.0.0/tests/test_detector.py

@@ -0,0 +1,130 @@
+# tests/test_detector.py
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import pytest
+from src.detector import detect_stack
+
+
+class TestDetector:
+    def test_detect_python_project(self):
+        """Test detection of Python project."""
+        scan_result = {
+            "files": ["main.py", "requirements.txt", "setup.py"],
+            "dirs": ["tests", "src"],
+            "file_extensions": [".py", ".txt"],
+            "name": "my-python-bot",
+            "root": "/path/to/project"
+        }
+        
+        result = detect_stack(scan_result)
+        
+        assert "Python" in result["languages"]
+        assert result["primary_lang"] == "Python"
+    
+    def test_detect_cpp_project(self):
+        """Test detection of C++ project."""
+        scan_result = {
+            "files": ["main.cpp", "CMakeLists.txt", "Makefile"],
+            "dirs": ["src", "include"],
+            "file_extensions": [".cpp", ".txt"],
+            "name": "cpp-app",
+            "root": "/path/to/project"
+        }
+        
+        result = detect_stack(scan_result)
+        
+        assert "C++" in result["languages"]
+        assert result["primary_lang"] == "C++"
+    
+    def test_detect_typescript_project(self):
+        """Test detection of TypeScript project."""
+        scan_result = {
+            "files": ["index.ts", "tsconfig.json", "package.json"],
+            "dirs": ["src", "components"],
+            "file_extensions": [".ts", ".json"],
+            "name": "web-app",
+            "root": "/path/to/project"
+        }
+        
+        result = detect_stack(scan_result)
+        
+        assert "TypeScript" in result["languages"]
+        assert result["primary_lang"] == "TypeScript"
+    
+    def test_detect_telegram_bot(self):
+        """Test detection of telegram bot project."""
+        scan_result = {
+            "files": ["bot.py", "requirements.txt"],
+            "dirs": ["tests"],
+            "file_extensions": [".py", ".txt"],
+            "name": "telegram-bot",
+            "root": "/path/to/project"
+        }
+        
+        result = detect_stack(scan_result)
+        
+        assert result["project_type"] == "telegram-bot"
+    
+    def test_detect_web_app(self):
+        """Test detection of web application."""
+        scan_result = {
+            "files": ["package.json", "index.html", "tsconfig.json"],
+            "dirs": ["src", "public", "components"],
+            "file_extensions": [".json", ".html", ".ts"],
+            "name": "my-web-app",
+            "root": "/path/to/project"
+        }
+        
+        result = detect_stack(scan_result)
+        
+        assert result["project_type"] == "web-app"
+    
+    def test_detect_cli_tool(self):
+        """Test detection of CLI tool."""
+        scan_result = {
+            "files": ["cli.py", "setup.py", "requirements.txt"],
+            "dirs": ["tests"],
+            "file_extensions": [".py", ".txt"],
+            "name": "my-cli-tool",
+            "root": "/path/to/project"
+        }
+        
+        result = detect_stack(scan_result)
+        
+        assert result["project_type"] == "cli-tool"
+    
+    def test_detect_has_tests(self):
+        """Test that has_tests is detected correctly."""
+        scan_result = {
+            "files": ["main.py"],
+            "dirs": ["tests", "src"],
+            "file_extensions": [".py"],
+            "name": "test-project",
+            "root": "/path/to/project"
+        }
+        
+        result = detect_stack(scan_result)
+        
+        assert result["has_tests"] is True
+    
+    def test_detect_has_docs(self):
+        """Test that has_docs is detected correctly."""
+        scan_result = {
+            "files": ["main.py"],
+            "dirs": ["docs", "src"],
+            "file_extensions": [".py"],
+            "name": "doc-project",
+            "root": "/path/to/project"
+        }
+        
+        result = detect_stack(scan_result)
+        
+        assert result["has_docs"] is True
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

projectreadmegen-1.0.0/tests/test_generator.py

@@ -0,0 +1,165 @@
+# tests/test_generator.py
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import pytest
+from src.generator import generate_readme
+
+
+class TestGenerator:
+    def test_generate_minimal_template(self):
+        """Test that minimal template produces non-empty output."""
+        scan_result = {
+            "name": "test-project",
+            "tree": "├── src/\n│   └── main.py",
+            "has_license": False,
+            "has_contributing": False,
+        }
+        
+        detection = {
+            "primary_lang": "Python",
+            "languages": ["Python"],
+            "project_type": "cli-tool",
+            "description_hint": "A Python project — Test Project.",
+            "install_cmd": "pip install -r requirements.txt",
+            "run_cmd": "python main.py",
+            "has_tests": False,
+            "has_docs": False,
+            "license": "None",
+        }
+        
+        config = {
+            "template": "minimal",
+            "include_badges": False,
+            "include_tree": True,
+            "max_tree_depth": 3,
+            "author": "Test Author",
+            "github_username": "testuser",
+        }
+        
+        result = generate_readme(scan_result, detection, config)
+        
+        assert isinstance(result, str)
+        assert len(result) > 0
+        assert "Test Project" in result
+    
+    def test_generate_standard_template(self):
+        """Test that standard template produces output."""
+        scan_result = {
+            "name": "my-cli-tool",
+            "tree": "├── main.py",
+            "has_license": True,
+            "has_contributing": False,
+        }
+        
+        detection = {
+            "primary_lang": "Python",
+            "languages": ["Python"],
+            "project_type": "cli-tool",
+            "description_hint": "A CLI tool written in Python.",
+            "install_cmd": "pip install .",
+            "run_cmd": "python cli.py",
+            "has_tests": True,
+            "has_docs": False,
+            "license": "MIT",
+        }
+        
+        config = {
+            "template": "standard",
+            "include_badges": True,
+            "include_tree": True,
+            "max_tree_depth": 2,
+            "author": "",
+            "github_username": "developer",
+        }
+        
+        result = generate_readme(scan_result, detection, config)
+        
+        assert isinstance(result, str)
+        assert len(result) > 0
+    
+    def test_generate_full_template(self):
+        """Test that full template produces output."""
+        scan_result = {
+            "name": "web-app",
+            "tree": "src/\n  index.ts",
+            "has_license": True,
+            "has_contributing": True,
+        }
+        
+        detection = {
+            "primary_lang": "TypeScript",
+            "languages": ["TypeScript", "JavaScript"],
+            "project_type": "web-app",
+            "description_hint": "A web application built with TypeScript.",
+            "install_cmd": "npm install",
+            "run_cmd": "npm run dev",
+            "has_tests": True,
+            "has_docs": True,
+            "license": "Apache-2.0",
+        }
+        
+        config = {
+            "template": "full",
+            "include_badges": True,
+            "include_tree": True,
+            "max_tree_depth": 3,
+            "author": "Dev",
+            "github_username": "devuser",
+        }
+        
+        result = generate_readme(scan_result, detection, config)
+        
+        assert isinstance(result, str)
+        assert len(result) > 0
+    
+    def test_generate_academic_template(self):
+        """Test that academic template produces output."""
+        scan_result = {
+            "name": "academic-project",
+            "tree": "main.py",
+            "has_license": False,
+            "has_contributing": False,
+        }
+        
+        detection = {
+            "primary_lang": "Python",
+            "languages": ["Python"],
+            "project_type": "unknown",
+            "description_hint": "A Python project.",
+            "install_cmd": "pip install -r requirements.txt",
+            "run_cmd": "python main.py",
+            "has_tests": False,
+            "has_docs": False,
+            "license": "None",
+        }
+        
+        config = {
+            "template": "academic",
+            "include_badges": False,
+            "include_tree": True,
+            "max_tree_depth": 2,
+            "author": "Student",
+            "github_username": "student",
+        }
+        
+        result = generate_readme(scan_result, detection, config)
+        
+        assert isinstance(result, str)
+        assert len(result) > 0
+    
+    def test_generate_invalid_template_raises(self):
+        """Test that invalid template raises error."""
+        scan_result = {"name": "test", "tree": "", "has_license": False, "has_contributing": False}
+        detection = {"primary_lang": "Python", "languages": ["Python"], "project_type": "unknown", "description_hint": "A Python project.", "install_cmd": "", "run_cmd": "", "has_tests": False, "has_docs": False, "license": "None"}
+        config = {"template": "nonexistent", "include_badges": False, "include_tree": False, "max_tree_depth": 3, "author": "", "github_username": ""}
+        
+        with pytest.raises(FileNotFoundError):
+            generate_readme(scan_result, detection, config)
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

projectreadmegen-1.0.0/tests/test_scanner.py

@@ -0,0 +1,58 @@
+# tests/test_scanner.py
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import pytest
+from src.scanner import scan_directory, load_config
+
+
+class TestScanner:
+    def test_scan_directory_returns_dict(self):
+        """Test that scan_directory returns a dictionary with expected keys."""
+        result = scan_directory("examples/sample-cpp-project", max_depth=2)
+        
+        assert isinstance(result, dict)
+        assert "root" in result
+        assert "name" in result
+        assert "files" in result
+        assert "dirs" in result
+        assert "tree" in result
+        assert "file_extensions" in result
+    
+    def test_scan_cpp_project_detects_extensions(self):
+        """Test that scanner detects .cpp extensions."""
+        result = scan_directory("examples/sample-cpp-project", max_depth=2)
+        
+        assert ".cpp" in result["file_extensions"]
+    
+    def test_scan_python_bot_detects_py(self):
+        """Test that scanner detects Python files."""
+        result = scan_directory("examples/sample-python-bot", max_depth=2)
+        
+        assert ".py" in result["file_extensions"]
+        assert "requirements.txt" in result["files"]
+    
+    def test_scan_web_project_detects_json(self):
+        """Test that scanner detects web project files."""
+        result = scan_directory("examples/sample-web-project", max_depth=2)
+        
+        assert ".json" in result["file_extensions"]
+    
+    def test_load_config_returns_dict(self):
+        """Test that load_config returns a dictionary."""
+        config = load_config("examples/sample-cpp-project")
+        
+        assert isinstance(config, dict)
+        assert "template" in config
+    
+    def test_scan_nonexistent_path_raises(self):
+        """Test that scanning a nonexistent path raises an error."""
+        with pytest.raises(Exception):
+            scan_directory("nonexistent/path/12345")
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])