reposhowcase 0.1.0__tar.gz

reposhowcase-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RepoShowcase Team
+
+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.

reposhowcase-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: reposhowcase
+Version: 0.1.0
+Summary: Evidence-based showcases for multi-language software repositories.
+Author: RepoShowcase contributors
+License: MIT
+Project-URL: Homepage, https://github.com/OttoHui/reposhowcase
+Project-URL: Repository, https://github.com/OttoHui/reposhowcase
+Project-URL: Issues, https://github.com/OttoHui/reposhowcase/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2; python_version < "3.11"
+Provides-Extra: pptx
+Requires-Dist: python-pptx>=0.6.23; extra == "pptx"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# RepoShowcase
+
+RepoShowcase analyzes an existing multi-language software repository and turns
+verified repository facts into an evidence-based project showcase. The same
+storyboard can be exported as an interactive HTML presentation, an editable
+PowerPoint file, or an MP4 video.
+
+## Motivation
+
+Explaining an unfamiliar software project usually requires manually collecting
+facts from its README, source tree, dependency files, tests, and Git history.
+That process is slow and can lead to claims that are difficult to verify.
+RepoShowcase automates the evidence-gathering stage while keeping each claim
+linked to the repository-relative path that supports it.
+
+## What makes it different
+
+- **Evidence before presentation:** generated claims come from files and Git
+  data found in the repository rather than invented project descriptions.
+- **One model, three outputs:** HTML, PPTX, and MP4 are generated from the same
+  storyboard, so the formats remain consistent.
+- **Multi-language fallback:** common languages receive file-level detection,
+  while unfamiliar file types still contribute generic repository evidence.
+- **Useful for existing projects:** the target repository does not need to
+  follow a special framework or add RepoShowcase-specific annotations.
+
+## Example use cases
+
+- Give a one-minute overview of a team software project.
+- Create a review presentation for an unfamiliar open-source repository.
+- Produce an evidence-backed project summary for a class demonstration.
+- Generate a machine-readable JSON report for later analysis or tooling.
+
+## Quick start
+
+```bash
+pip install -e ".[dev]"
+reposhowcase build ./my-project --outputs html,pptx,mp4 --output showcase/
+```
+
+HTML is dependency-free. PPTX requires the `pptx` extra, and MP4 requires an
+`ffmpeg` executable on `PATH`.
+
+After the first PyPI release, the installation command will become:
+
+```bash
+pip install reposhowcase
+```
+
+For development with optional exporters and test tools:
+
+```bash
+pip install -e ".[dev,pptx]"
+```
+
+## Analysis pipeline
+
+```text
+scan repository
+    -> detect languages and project files
+    -> extract README, dependency, test, symbol, and Git evidence
+    -> build a four-slide storyboard
+    -> export HTML, PPTX, MP4, or JSON
+```
+
+The default storyboard contains:
+
+1. **Project idea** — README-based project description
+2. **How it works** — languages, source files, and dependencies
+3. **Evidence** — tests, public Python symbols, and contributors
+4. **Demo** — commands found in the README and next steps
+
+## Python API
+
+```python
+from reposhowcase import analyze_repository, build_storyboard
+from reposhowcase.exporters import export_html
+
+report = analyze_repository("./my-project")
+storyboard = build_storyboard(report, duration=60)
+export_html(storyboard, "showcase.html")
+```
+
+The analyzer deliberately reports unknown languages and generic file evidence
+instead of guessing unsupported details. The CLI also supports `json`, which
+writes the analyzed report as machine-readable data.
+
+## Team
+
+RepoShowcase is developed by a six-member student project team for the
+CS1302A Agentic Coding project. Team member names will be added before the
+public project release.
+
+## Development
+
+The package uses a `src/` layout. Run the focused checks from the repository
+root:
+
+```bash
+python -m pytest
+python -m ruff check src tests
+```
+
+The public repository will contain the project history, documentation,
+automated checks, and release information. Personal contact details and
+student IDs should not be included in the package.

reposhowcase-0.1.0/README.md

@@ -0,0 +1,106 @@
+# RepoShowcase
+
+RepoShowcase analyzes an existing multi-language software repository and turns
+verified repository facts into an evidence-based project showcase. The same
+storyboard can be exported as an interactive HTML presentation, an editable
+PowerPoint file, or an MP4 video.
+
+## Motivation
+
+Explaining an unfamiliar software project usually requires manually collecting
+facts from its README, source tree, dependency files, tests, and Git history.
+That process is slow and can lead to claims that are difficult to verify.
+RepoShowcase automates the evidence-gathering stage while keeping each claim
+linked to the repository-relative path that supports it.
+
+## What makes it different
+
+- **Evidence before presentation:** generated claims come from files and Git
+  data found in the repository rather than invented project descriptions.
+- **One model, three outputs:** HTML, PPTX, and MP4 are generated from the same
+  storyboard, so the formats remain consistent.
+- **Multi-language fallback:** common languages receive file-level detection,
+  while unfamiliar file types still contribute generic repository evidence.
+- **Useful for existing projects:** the target repository does not need to
+  follow a special framework or add RepoShowcase-specific annotations.
+
+## Example use cases
+
+- Give a one-minute overview of a team software project.
+- Create a review presentation for an unfamiliar open-source repository.
+- Produce an evidence-backed project summary for a class demonstration.
+- Generate a machine-readable JSON report for later analysis or tooling.
+
+## Quick start
+
+```bash
+pip install -e ".[dev]"
+reposhowcase build ./my-project --outputs html,pptx,mp4 --output showcase/
+```
+
+HTML is dependency-free. PPTX requires the `pptx` extra, and MP4 requires an
+`ffmpeg` executable on `PATH`.
+
+After the first PyPI release, the installation command will become:
+
+```bash
+pip install reposhowcase
+```
+
+For development with optional exporters and test tools:
+
+```bash
+pip install -e ".[dev,pptx]"
+```
+
+## Analysis pipeline
+
+```text
+scan repository
+    -> detect languages and project files
+    -> extract README, dependency, test, symbol, and Git evidence
+    -> build a four-slide storyboard
+    -> export HTML, PPTX, MP4, or JSON
+```
+
+The default storyboard contains:
+
+1. **Project idea** — README-based project description
+2. **How it works** — languages, source files, and dependencies
+3. **Evidence** — tests, public Python symbols, and contributors
+4. **Demo** — commands found in the README and next steps
+
+## Python API
+
+```python
+from reposhowcase import analyze_repository, build_storyboard
+from reposhowcase.exporters import export_html
+
+report = analyze_repository("./my-project")
+storyboard = build_storyboard(report, duration=60)
+export_html(storyboard, "showcase.html")
+```
+
+The analyzer deliberately reports unknown languages and generic file evidence
+instead of guessing unsupported details. The CLI also supports `json`, which
+writes the analyzed report as machine-readable data.
+
+## Team
+
+RepoShowcase is developed by a six-member student project team for the
+CS1302A Agentic Coding project. Team member names will be added before the
+public project release.
+
+## Development
+
+The package uses a `src/` layout. Run the focused checks from the repository
+root:
+
+```bash
+python -m pytest
+python -m ruff check src tests
+```
+
+The public repository will contain the project history, documentation,
+automated checks, and release information. Personal contact details and
+student IDs should not be included in the package.

reposhowcase-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "reposhowcase"
+version = "0.1.0"
+description = "Evidence-based showcases for multi-language software repositories."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "RepoShowcase contributors"}]
+dependencies = ["tomli>=2; python_version < '3.11'"]
+
+[project.urls]
+Homepage = "https://github.com/OttoHui/reposhowcase"
+Repository = "https://github.com/OttoHui/reposhowcase"
+Issues = "https://github.com/OttoHui/reposhowcase/issues"
+
+[project.optional-dependencies]
+pptx = ["python-pptx>=0.6.23"]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+reposhowcase = "reposhowcase.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

reposhowcase-0.1.0/setup.cfg

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

reposhowcase-0.1.0/src/reposhowcase/__init__.py

@@ -0,0 +1,15 @@
+"""Public API for evidence-based repository showcases."""
+
+from .analyzer import analyze_repository
+from .models import Evidence, RepositoryReport, Slide, Storyboard
+from .storyboard import build_storyboard
+
+__all__ = [
+    "Evidence",
+    "RepositoryReport",
+    "Slide",
+    "Storyboard",
+    "analyze_repository",
+    "build_storyboard",
+]
+

reposhowcase-0.1.0/src/reposhowcase/analyzer.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import ast
+import json
+import re
+import subprocess
+from collections import Counter
+from pathlib import Path
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # Python 3.10 compatibility
+    import tomli as tomllib
+
+from .models import Evidence, RepositoryReport
+
+LANGUAGES = {
+    ".py": "Python", ".js": "JavaScript", ".jsx": "JavaScript",
+    ".ts": "TypeScript", ".tsx": "TypeScript", ".go": "Go",
+    ".rs": "Rust", ".java": "Java", ".kt": "Kotlin", ".rb": "Ruby",
+    ".php": "PHP", ".cs": "C#", ".cpp": "C++", ".c": "C",
+    ".swift": "Swift", ".vue": "Vue", ".html": "HTML", ".css": "CSS",
+}
+IGNORED = {".git", ".venv", "venv", "node_modules", "__pycache__", "dist", "build"}
+MANIFESTS = {
+    "pyproject.toml", "requirements.txt", "package.json", "go.mod",
+    "Cargo.toml", "pom.xml", "Gemfile", "composer.json",
+}
+
+
+def _files(root: Path) -> list[Path]:
+    return [
+        path for path in root.rglob("*")
+        if path.is_file() and not any(part in IGNORED for part in path.parts)
+    ]
+
+
+def _python_symbols(path: Path) -> int:
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8", errors="ignore"))
+    except (OSError, SyntaxError):
+        return 0
+    return sum(
+        isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef))
+        and not node.name.startswith("_")
+        for node in ast.walk(tree)
+    )
+
+
+def _git_contributors(root: Path) -> int:
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(root), "shortlog", "-sne", "HEAD"],
+            check=False, capture_output=True, text=True, timeout=5,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return 0
+    return len([line for line in result.stdout.splitlines() if line.strip()])
+
+
+def _dependencies(path: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    if path.name == "package.json":
+        try:
+            package = json.loads(text)
+        except json.JSONDecodeError:
+            return []
+        if not isinstance(package, dict):
+            return []
+        sections = ("dependencies", "devDependencies", "peerDependencies", "optionalDependencies")
+        return sorted({
+            name for section in sections
+            for name in package.get(section, {})
+            if isinstance(name, str)
+        })
+    if path.name in {"requirements.txt", "Gemfile"}:
+        names = set()
+        for line in text.splitlines():
+            line = line.strip()
+            if not line or line.startswith(("#", "-", "git+", "http")):
+                continue
+            names.add(re.split(r"[<>=!~;\[\s]", line, maxsplit=1)[0])
+        return sorted(names)
+    if path.name == "pyproject.toml":
+        try:
+            project = tomllib.loads(text).get("project", {})
+        except tomllib.TOMLDecodeError:
+            return []
+        return sorted({
+            re.split(r"[<>=!~;\[\s]", requirement, maxsplit=1)[0]
+            for requirement in project.get("dependencies", [])
+            if isinstance(requirement, str)
+        })
+    return sorted(set(re.findall(r'(?m)^\s*([A-Za-z][A-Za-z0-9_.-]+)\s*=', text)))[:30]
+
+
+def analyze_repository(repository: str | Path) -> RepositoryReport:
+    """Scan *repository* and return facts with paths that support them."""
+    root = Path(repository).expanduser().resolve()
+    if not root.is_dir():
+        raise NotADirectoryError(f"Repository directory does not exist: {root}")
+    paths = _files(root)
+    counts = Counter(LANGUAGES[path.suffix.lower()] for path in paths if path.suffix.lower() in LANGUAGES)
+    languages = [name for name, _ in counts.most_common()]
+    source_paths = [path for path in paths if path.suffix.lower() in LANGUAGES]
+    test_paths = [path for path in paths if "test" in path.name.lower() or "tests" in path.parts]
+    evidence: list[Evidence] = []
+
+    readme = next((p for p in paths if p.name.lower() in {"readme.md", "readme.rst", "readme.txt"}), None)
+    excerpt = ""
+    if readme:
+        readme_text = readme.read_text(encoding="utf-8", errors="ignore").strip()
+        excerpt = readme_text[:500]
+        evidence.append(Evidence(str(readme.relative_to(root)), "documentation", "Project README"))
+    for path in paths:
+        if path.name in MANIFESTS:
+            deps = _dependencies(path)
+            evidence.append(Evidence(str(path.relative_to(root)), "manifest", f"{len(deps)} declared dependencies"))
+    for path in test_paths[:10]:
+        evidence.append(Evidence(str(path.relative_to(root)), "tests", "Test source"))
+    for path in source_paths[:10]:
+        evidence.append(Evidence(str(path.relative_to(root)), "source", f"{LANGUAGES[path.suffix.lower()]} source"))
+
+    commands = re.findall(r"(?m)^\s*(?:\$|>)\s*(.+)$", readme_text) if readme else []
+    return RepositoryReport(
+        root=root, name=root.name, languages=languages,
+        source_files=len(source_paths), test_files=len(test_paths),
+        public_symbols=sum(_python_symbols(p) for p in source_paths if p.suffix == ".py"),
+        dependencies=sorted({dep for path in paths if path.name in MANIFESTS for dep in _dependencies(path)}),
+        contributors=_git_contributors(root), evidence=evidence,
+        commands=commands[:8], readme_excerpt=excerpt,
+    )

reposhowcase-0.1.0/src/reposhowcase/cli.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .analyzer import analyze_repository
+from .exporters.html import export_html
+from .exporters.mp4 import export_mp4
+from .exporters.pptx import export_pptx
+from .storyboard import build_storyboard
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="reposhowcase")
+    sub = parser.add_subparsers(dest="command", required=True)
+    build = sub.add_parser("build", help="Analyze a repository and export a showcase")
+    build.add_argument("repository", type=Path)
+    build.add_argument("--outputs", default="html", help="Comma-separated: html,pptx,mp4,json")
+    build.add_argument("--duration", type=float, default=60)
+    build.add_argument("--output", type=Path, default=Path("showcase"))
+    args = parser.parse_args(argv)
+    report = analyze_repository(args.repository)
+    storyboard = build_storyboard(report, args.duration)
+    args.output.mkdir(parents=True, exist_ok=True)
+    outputs = {item.strip().lower() for item in args.outputs.split(",")}
+    if "html" in outputs:
+        export_html(storyboard, args.output / "showcase.html")
+    if "pptx" in outputs:
+        export_pptx(storyboard, args.output / "showcase.pptx")
+    if "mp4" in outputs:
+        export_mp4(storyboard, args.output / "showcase.mp4")
+    if "json" in outputs:
+        (args.output / "report.json").write_text(json.dumps(report.to_dict(), indent=2), encoding="utf-8")
+    print(f"Analyzed {report.name}: {len(storyboard.slides)} slides written to {args.output}")
+    return 0

reposhowcase-0.1.0/src/reposhowcase/exporters/__init__.py

@@ -0,0 +1,9 @@
+"""Storyboard exporters."""
+
+"""Output adapters for the shared RepoShowcase storyboard."""
+
+from .html import export_html
+from .mp4 import export_mp4
+from .pptx import export_pptx
+
+__all__ = ["export_html", "export_mp4", "export_pptx"]

reposhowcase-0.1.0/src/reposhowcase/exporters/html.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import html
+from pathlib import Path
+
+from ..models import Storyboard
+
+
+def export_html(storyboard: Storyboard, output: str | Path) -> Path:
+    """Write a self-contained, keyboard-navigable HTML presentation."""
+    slides = []
+    for slide in storyboard.slides:
+        bullets = "".join(f"<li>{html.escape(item)}</li>" for item in slide.bullets)
+        sources = "".join(
+            f'<small class="source">{html.escape(item.path)} — {html.escape(item.detail)}</small>'
+            for item in slide.evidence
+        )
+        slides.append(
+            f'<article class="slide"><small>{slide.number:02d} / {len(storyboard.slides):02d}</small>'
+            f"<h2>{html.escape(slide.title)}</h2><p>{html.escape(slide.body)}</p>"
+            f"<ul>{bullets}</ul><div>{sources}</div></article>"
+        )
+    content = f"""<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width">
+<title>{html.escape(storyboard.title)}</title>
+<style>
+body{{margin:0;background:#f7f9fc;color:#162033;font:16px/1.5 system-ui,-apple-system,sans-serif}}
+header{{padding:42px 24px;color:white;background:linear-gradient(120deg,#173b8f,#2864e8 55%,#7654d6)}}
+header h1{{max-width:900px;margin:0 auto;font-size:clamp(2rem,5vw,4rem)}} main{{max-width:900px;margin:auto;padding:32px 24px}}
+.slide{{display:none;background:white;border:1px solid #dbe2ef;border-radius:16px;padding:32px;min-height:360px;box-shadow:0 5px 18px #243d7110}}
+.slide.active{{display:block}} h2{{font-size:2.5rem;color:#2864e8}} li{{margin:14px 0}} .source{{display:block;color:#63708a;margin-top:8px}}
+button{{padding:10px 16px;border:0;border-radius:8px;background:#2864e8;color:white;cursor:pointer;margin-right:8px}}
+button:focus-visible{{outline:3px solid #7654d6;outline-offset:2px}}
+@media (prefers-reduced-motion: reduce){{*{{scroll-behavior:auto!important}}}}
+</style><header><h1>{html.escape(storyboard.title)}</h1></header><main><section id="slides" aria-live="polite">{"".join(slides)}</section>
+<p><button id="prev">Previous</button><button id="next">Next</button><span id="count"></span></p>
+<script>let i=0,s=[...document.querySelectorAll('.slide')],count=document.querySelector('#count');function show(){{s.forEach((x,n)=>x.classList.toggle('active',n===i));count.textContent=` ${{i+1}} / ${{s.length}}`;}}document.querySelector('#next').onclick=()=>{{i=(i+1)%s.length;show()}};document.querySelector('#prev').onclick=()=>{{i=(i+s.length-1)%s.length;show()}};onkeydown=e=>{{if(e.key==='ArrowRight')document.querySelector('#next').click();if(e.key==='ArrowLeft')document.querySelector('#prev').click()}};show();</script></main>"""
+    destination = Path(output)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(content, encoding="utf-8")
+    return destination

reposhowcase-0.1.0/src/reposhowcase/exporters/mp4.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from ..models import Storyboard
+
+
+def export_mp4(storyboard: Storyboard, output: str | Path) -> Path:
+    """Render a storyboard to a simple, portable H.264 slide video."""
+    ffmpeg = shutil.which("ffmpeg")
+    if not ffmpeg:
+        raise RuntimeError("MP4 export requires ffmpeg installed and available on PATH.")
+    destination = Path(output)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="reposhowcase-") as temp:
+        temp_path = Path(temp)
+        clips: list[Path] = []
+        for index, slide in enumerate(storyboard.slides):
+            text_file = temp_path / f"{index}.txt"
+            text_file.write_text(
+                f"{slide.title}\n\n{slide.body}\n\n"
+                + "\n".join(f"- {bullet}" for bullet in slide.bullets),
+                encoding="utf-8",
+            )
+            clip = temp_path / f"{index}.mp4"
+            _run_ffmpeg(
+                ffmpeg,
+                "-y", "-loglevel", "error",
+                "-f", "lavfi", "-i", "color=c=173b8f:s=1280x720:r=30",
+                "-t", str(slide.seconds), "-vf",
+                f"drawtext=textfile={text_file}:fontcolor=white:fontsize=40:"
+                "line_spacing=14:x=70:y=150",
+                "-c:v", "libx264", "-pix_fmt", "yuv420p", str(clip),
+            )
+            clips.append(clip)
+        concat = temp_path / "concat.txt"
+        concat.write_text(
+            "".join(f"file '{clip.as_posix()}'\n" for clip in clips),
+            encoding="utf-8",
+        )
+        _run_ffmpeg(
+            ffmpeg, "-y", "-loglevel", "error", "-f", "concat", "-safe", "0",
+            "-i", str(concat), "-c", "copy", str(destination),
+        )
+    return destination
+
+
+def _run_ffmpeg(ffmpeg: str, *arguments: str) -> None:
+    try:
+        subprocess.run([ffmpeg, *arguments], check=True, capture_output=True, text=True)
+    except subprocess.CalledProcessError as exc:
+        detail = (exc.stderr or "ffmpeg failed").strip()
+        raise RuntimeError(f"MP4 export failed: {detail}") from exc

reposhowcase-0.1.0/src/reposhowcase/exporters/pptx.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..models import Storyboard
+
+
+def export_pptx(storyboard: Storyboard, output: str | Path) -> Path:
+    try:
+        from pptx import Presentation
+    except ImportError as exc:
+        raise RuntimeError("PPTX export requires `pip install reposhowcase[pptx]`.") from exc
+    destination = Path(output)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    presentation = Presentation()
+    for slide_data in storyboard.slides:
+        slide = presentation.slides.add_slide(presentation.slide_layouts[1])
+        slide.shapes.title.text = slide_data.title
+        frame = slide.placeholders[1].text_frame
+        frame.text = slide_data.body
+        for bullet in slide_data.bullets:
+            paragraph = frame.add_paragraph()
+            paragraph.text = bullet
+            paragraph.level = 0
+        notes = slide.notes_slide.notes_text_frame
+        notes.text = "Evidence: " + ", ".join(item.path for item in slide_data.evidence)
+    presentation.save(destination)
+    return destination

reposhowcase-0.1.0/src/reposhowcase/models.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Evidence:
+    """A claim-supporting repository location and a short extracted detail."""
+
+    path: str
+    kind: str
+    detail: str
+
+
+@dataclass
+class RepositoryReport:
+    root: Path
+    name: str
+    languages: list[str]
+    source_files: int
+    test_files: int
+    public_symbols: int
+    dependencies: list[str]
+    contributors: int
+    evidence: list[Evidence] = field(default_factory=list)
+    commands: list[str] = field(default_factory=list)
+    readme_excerpt: str = ""
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "name": self.name,
+            "languages": self.languages,
+            "source_files": self.source_files,
+            "test_files": self.test_files,
+            "public_symbols": self.public_symbols,
+            "dependencies": self.dependencies,
+            "contributors": self.contributors,
+            "evidence": [e.__dict__ for e in self.evidence],
+            "commands": self.commands,
+        }
+
+
+@dataclass(frozen=True)
+class Slide:
+    number: int
+    title: str
+    body: str
+    bullets: tuple[str, ...] = ()
+    evidence: tuple[Evidence, ...] = ()
+    seconds: float = 0
+
+
+@dataclass(frozen=True)
+class Storyboard:
+    title: str
+    slides: tuple[Slide, ...]
+    duration: float
+

reposhowcase-0.1.0/src/reposhowcase/storyboard.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from .models import RepositoryReport, Slide, Storyboard
+
+
+def build_storyboard(report: RepositoryReport, duration: float = 60) -> Storyboard:
+    if duration <= 0:
+        raise ValueError("duration must be greater than zero")
+    durations = [duration * ratio for ratio in (0.2, 0.3, 0.3, 0.2)]
+    evidence = tuple(report.evidence)
+    return Storyboard(
+        title=f"{report.name}: repository showcase",
+        duration=duration,
+        slides=(
+            Slide(1, "Project idea", "What the repository is built to do.",
+                  (report.readme_excerpt or "No README evidence found.",), evidence[:2], durations[0]),
+            Slide(2, "How it works", "Languages, source files, and dependencies.",
+                  (f"Languages: {', '.join(report.languages) or 'Unknown'}",
+                   f"{report.source_files} source files and {len(report.dependencies)} dependencies"),
+                  tuple(e for e in evidence if e.kind in {"source", "manifest"}), durations[1]),
+            Slide(3, "Evidence", "Quality signals found in the repository.",
+                  (f"{report.test_files} test files", f"{report.public_symbols} public Python symbols",
+                   f"{report.contributors or 'No'} Git contributors detected"),
+                  tuple(e for e in evidence if e.kind in {"tests", "documentation"}), durations[2]),
+            Slide(4, "Demo", "Commands and next steps.",
+                  tuple(report.commands or ("Inspect the generated evidence report.",)),
+                  evidence[-3:], durations[3]),
+        ),
+    )
+

reposhowcase-0.1.0/src/reposhowcase.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: reposhowcase
+Version: 0.1.0
+Summary: Evidence-based showcases for multi-language software repositories.
+Author: RepoShowcase contributors
+License: MIT
+Project-URL: Homepage, https://github.com/OttoHui/reposhowcase
+Project-URL: Repository, https://github.com/OttoHui/reposhowcase
+Project-URL: Issues, https://github.com/OttoHui/reposhowcase/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2; python_version < "3.11"
+Provides-Extra: pptx
+Requires-Dist: python-pptx>=0.6.23; extra == "pptx"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# RepoShowcase
+
+RepoShowcase analyzes an existing multi-language software repository and turns
+verified repository facts into an evidence-based project showcase. The same
+storyboard can be exported as an interactive HTML presentation, an editable
+PowerPoint file, or an MP4 video.
+
+## Motivation
+
+Explaining an unfamiliar software project usually requires manually collecting
+facts from its README, source tree, dependency files, tests, and Git history.
+That process is slow and can lead to claims that are difficult to verify.
+RepoShowcase automates the evidence-gathering stage while keeping each claim
+linked to the repository-relative path that supports it.
+
+## What makes it different
+
+- **Evidence before presentation:** generated claims come from files and Git
+  data found in the repository rather than invented project descriptions.
+- **One model, three outputs:** HTML, PPTX, and MP4 are generated from the same
+  storyboard, so the formats remain consistent.
+- **Multi-language fallback:** common languages receive file-level detection,
+  while unfamiliar file types still contribute generic repository evidence.
+- **Useful for existing projects:** the target repository does not need to
+  follow a special framework or add RepoShowcase-specific annotations.
+
+## Example use cases
+
+- Give a one-minute overview of a team software project.
+- Create a review presentation for an unfamiliar open-source repository.
+- Produce an evidence-backed project summary for a class demonstration.
+- Generate a machine-readable JSON report for later analysis or tooling.
+
+## Quick start
+
+```bash
+pip install -e ".[dev]"
+reposhowcase build ./my-project --outputs html,pptx,mp4 --output showcase/
+```
+
+HTML is dependency-free. PPTX requires the `pptx` extra, and MP4 requires an
+`ffmpeg` executable on `PATH`.
+
+After the first PyPI release, the installation command will become:
+
+```bash
+pip install reposhowcase
+```
+
+For development with optional exporters and test tools:
+
+```bash
+pip install -e ".[dev,pptx]"
+```
+
+## Analysis pipeline
+
+```text
+scan repository
+    -> detect languages and project files
+    -> extract README, dependency, test, symbol, and Git evidence
+    -> build a four-slide storyboard
+    -> export HTML, PPTX, MP4, or JSON
+```
+
+The default storyboard contains:
+
+1. **Project idea** — README-based project description
+2. **How it works** — languages, source files, and dependencies
+3. **Evidence** — tests, public Python symbols, and contributors
+4. **Demo** — commands found in the README and next steps
+
+## Python API
+
+```python
+from reposhowcase import analyze_repository, build_storyboard
+from reposhowcase.exporters import export_html
+
+report = analyze_repository("./my-project")
+storyboard = build_storyboard(report, duration=60)
+export_html(storyboard, "showcase.html")
+```
+
+The analyzer deliberately reports unknown languages and generic file evidence
+instead of guessing unsupported details. The CLI also supports `json`, which
+writes the analyzed report as machine-readable data.
+
+## Team
+
+RepoShowcase is developed by a six-member student project team for the
+CS1302A Agentic Coding project. Team member names will be added before the
+public project release.
+
+## Development
+
+The package uses a `src/` layout. Run the focused checks from the repository
+root:
+
+```bash
+python -m pytest
+python -m ruff check src tests
+```
+
+The public repository will contain the project history, documentation,
+automated checks, and release information. Personal contact details and
+student IDs should not be included in the package.

reposhowcase-0.1.0/src/reposhowcase.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+src/reposhowcase/__init__.py
+src/reposhowcase/analyzer.py
+src/reposhowcase/cli.py
+src/reposhowcase/models.py
+src/reposhowcase/storyboard.py
+src/reposhowcase.egg-info/PKG-INFO
+src/reposhowcase.egg-info/SOURCES.txt
+src/reposhowcase.egg-info/dependency_links.txt
+src/reposhowcase.egg-info/entry_points.txt
+src/reposhowcase.egg-info/requires.txt
+src/reposhowcase.egg-info/top_level.txt
+src/reposhowcase/exporters/__init__.py
+src/reposhowcase/exporters/html.py
+src/reposhowcase/exporters/mp4.py
+src/reposhowcase/exporters/pptx.py
+tests/test_reposhowcase.py

reposhowcase-0.1.0/src/reposhowcase.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

reposhowcase-0.1.0/src/reposhowcase.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+reposhowcase = reposhowcase.cli:main

reposhowcase-0.1.0/src/reposhowcase.egg-info/requires.txt

@@ -0,0 +1,10 @@
+
+[:python_version < "3.11"]
+tomli>=2
+
+[dev]
+pytest>=8
+ruff>=0.6
+
+[pptx]
+python-pptx>=0.6.23

reposhowcase-0.1.0/src/reposhowcase.egg-info/top_level.txt

@@ -0,0 +1 @@
+reposhowcase

reposhowcase-0.1.0/tests/test_reposhowcase.py

@@ -0,0 +1,47 @@
+from pathlib import Path
+
+from reposhowcase import analyze_repository, build_storyboard
+from reposhowcase.exporters.html import export_html
+
+
+def test_analyze_and_export(tmp_path: Path) -> None:
+    (tmp_path / "README.md").write_text("# Demo\nRun it with `$ demo run`.\n")
+    (tmp_path / "main.py").write_text("def public_api():\n    return 1\n")
+    (tmp_path / "tests").mkdir()
+    (tmp_path / "tests" / "test_main.py").write_text("def test_it(): pass\n")
+
+    report = analyze_repository(tmp_path)
+    assert report.languages == ["Python"]
+    assert report.source_files == 2
+    assert report.test_files == 1
+    assert report.public_symbols == 2
+    storyboard = build_storyboard(report)
+    destination = export_html(storyboard, tmp_path / "showcase.html")
+    assert destination.read_text().count("class=\"slide\"") == 4
+
+
+def test_manifest_dependencies_and_readme_commands(tmp_path: Path) -> None:
+    (tmp_path / "README.md").write_text("# Demo\n$ python -m demo\n")
+    (tmp_path / "pyproject.toml").write_text(
+        "[project]\n"
+        'dependencies = ["requests>=2", "rich"]\n'
+    )
+    (tmp_path / "package.json").write_text(
+        '{"dependencies": {"react": "^1"}, "scripts": {"build": "x"}}\n'
+    )
+
+    report = analyze_repository(tmp_path)
+
+    assert report.dependencies == ["react", "requests", "rich"]
+    assert report.commands == ["python -m demo"]
+
+
+def test_invalid_repository_is_rejected(tmp_path: Path) -> None:
+    missing = tmp_path / "missing"
+
+    try:
+        analyze_repository(missing)
+    except NotADirectoryError as exc:
+        assert str(missing) in str(exc)
+    else:
+        raise AssertionError("analyze_repository should reject a missing directory")