github-license-scanner 0.1.0__py3-none-any.whl

gls/deploy_advisor.py

@@ -0,0 +1,286 @@
+"""
+Deploy platform recommender.
+
+Inspects repository language, dependency names, and Dockerfile presence
+to suggest where the application is easiest to host (Vercel, Railway, etc.).
+
+This is heuristic guidance for developers — not a production capacity plan.
+"""
+
+from __future__ import annotations
+
+from .models import Dependency, DeployAdvice
+
+# ---------------------------------------------------------------------------
+# Platform catalog
+# ---------------------------------------------------------------------------
+
+PLATFORMS: dict[str, dict[str, str]] = {
+    "Vercel": {
+        "docs_url": "https://vercel.com/docs",
+        "blurb": "Frontend and serverless-first hosting",
+    },
+    "Cloudflare Pages": {
+        "docs_url": "https://developers.cloudflare.com/pages/",
+        "blurb": "Static sites and Pages Functions at the edge",
+    },
+    "Netlify": {
+        "docs_url": "https://docs.netlify.com/",
+        "blurb": "JAMstack and static site hosting",
+    },
+    "Railway": {
+        "docs_url": "https://docs.railway.app/",
+        "blurb": "Simple full-stack deploys from Git",
+    },
+    "Render": {
+        "docs_url": "https://render.com/docs",
+        "blurb": "Web services, workers, and static sites",
+    },
+    "Fly.io": {
+        "docs_url": "https://fly.io/docs/",
+        "blurb": "Global app VMs close to users",
+    },
+    "Google Cloud Run": {
+        "docs_url": "https://cloud.google.com/run/docs",
+        "blurb": "Containerized services that scale to zero",
+    },
+    "GitHub Pages": {
+        "docs_url": "https://docs.github.com/pages",
+        "blurb": "Free static hosting from the repo",
+    },
+    "Hugging Face / RunPod / GPU VPS": {
+        "docs_url": "https://huggingface.co/docs/hub/spaces-sdks-docker",
+        "blurb": "GPU-oriented hosts for ML workloads",
+    },
+    "Any VPS (Docker)": {
+        "docs_url": "https://docs.docker.com/get-started/",
+        "blurb": "Full control with Docker on a VPS",
+    },
+}
+
+# Frontend framework package names (lowercase)
+FRONTEND_FRAMEWORKS = {
+    "next": "Next.js",
+    "nuxt": "Nuxt",
+    "vite": "Vite",
+    "react": "React",
+    "react-dom": "React",
+    "vue": "Vue",
+    "@angular/core": "Angular",
+    "svelte": "Svelte",
+    "astro": "Astro",
+    "gatsby": "Gatsby",
+    "@remix-run/react": "Remix",
+}
+
+# Backend / full-stack Python & similar
+BACKEND_PYTHON = {
+    "fastapi",
+    "flask",
+    "django",
+    "nicegui",
+    "starlette",
+    "uvicorn",
+    "gunicorn",
+    "streamlit",
+    "gradio",
+    "dash",
+    "tornado",
+    "sanic",
+    "aiohttp",
+}
+
+BACKEND_NODE = {
+    "express",
+    "fastify",
+    "koa",
+    "nestjs",
+    "@nestjs/core",
+    "hono",
+    "hapi",
+}
+
+ML_HEAVY = {
+    "torch",
+    "pytorch",
+    "tensorflow",
+    "keras",
+    "transformers",
+    "diffusers",
+    "langchain",
+    "scikit-learn",
+    "sklearn",
+    "xgboost",
+    "opencv-python",
+    "opencv-python-headless",
+}
+
+
+def recommend_deploy(
+    *,
+    primary_language: str | None,
+    topics: list[str] | None,
+    dependencies: list[Dependency],
+    dependency_files: list[str] | None = None,
+    has_dockerfile: bool = False,
+    description: str | None = None,
+) -> list[DeployAdvice]:
+    """
+    Score deploy platforms and return them sorted by score (descending).
+
+    Only platforms with score > 0 are returned (plus a sensible default if none).
+    """
+    scores: dict[str, int] = {name: 0 for name in PLATFORMS}
+    reasons: dict[str, list[str]] = {name: [] for name in PLATFORMS}
+
+    dep_names = {d.name.lower() for d in dependencies}
+    ecosystems = {d.ecosystem for d in dependencies}
+    files = [f.replace("\\", "/").lower() for f in (dependency_files or [])]
+    lang = (primary_language or "").lower()
+    topic_set = {t.lower() for t in (topics or [])}
+    desc = (description or "").lower()
+
+    def bump(platform: str, points: int, reason: str) -> None:
+        scores[platform] += points
+        if reason not in reasons[platform]:
+            reasons[platform].append(reason)
+
+    # --- Dockerfile signal ---
+    if has_dockerfile:
+        bump("Fly.io", 25, "Dockerfile detected — container-friendly hosts fit well")
+        bump("Railway", 22, "Dockerfile detected — Railway deploys containers easily")
+        bump("Render", 20, "Dockerfile detected — Render supports Docker web services")
+        bump("Google Cloud Run", 22, "Dockerfile detected — Cloud Run is container-native")
+        bump("Any VPS (Docker)", 18, "Dockerfile present — any Docker host works")
+
+    # --- Frontend frameworks ---
+    found_fe: list[str] = []
+    for pkg, label in FRONTEND_FRAMEWORKS.items():
+        if pkg in dep_names:
+            found_fe.append(label)
+    if found_fe:
+        labels = ", ".join(sorted(set(found_fe)))
+        bump("Vercel", 35, f"Frontend stack detected ({labels})")
+        bump("Netlify", 28, f"Frontend stack detected ({labels})")
+        bump("Cloudflare Pages", 26, f"Frontend stack detected ({labels})")
+        if "next" in dep_names or "Next.js" in found_fe:
+            bump("Vercel", 15, "Next.js is first-class on Vercel")
+        if "nuxt" in dep_names:
+            bump("Vercel", 10, "Nuxt deploys cleanly on Vercel / Node hosts")
+            bump("Railway", 8, "Nuxt can run as a Node service on Railway")
+
+    # --- Backend Python ---
+    py_hits = sorted(BACKEND_PYTHON & dep_names)
+    if py_hits:
+        bump("Railway", 32, f"Python backend packages: {', '.join(py_hits)}")
+        bump("Render", 30, f"Python backend packages: {', '.join(py_hits)}")
+        bump("Fly.io", 24, f"Python backend packages: {', '.join(py_hits)}")
+        if "nicegui" in dep_names:
+            bump("Railway", 8, "NiceGUI needs a long-running Python process (not pure static hosts)")
+            bump("Render", 8, "NiceGUI needs a long-running Python process")
+        if "streamlit" in dep_names or "gradio" in dep_names:
+            bump("Railway", 6, "Streamlit/Gradio apps need a process host")
+            bump("Hugging Face / RunPod / GPU VPS", 10, "ML demo UIs often ship on HF Spaces")
+
+    # --- Backend Node ---
+    node_hits = sorted(BACKEND_NODE & dep_names)
+    if node_hits:
+        bump("Railway", 28, f"Node backend packages: {', '.join(node_hits)}")
+        bump("Render", 26, f"Node backend packages: {', '.join(node_hits)}")
+        bump("Fly.io", 22, f"Node backend packages: {', '.join(node_hits)}")
+        bump("Vercel", 12, "API routes / serverless Node can run on Vercel")
+
+    # --- ML heavy ---
+    ml_hits = sorted(ML_HEAVY & dep_names)
+    if ml_hits:
+        bump(
+            "Hugging Face / RunPod / GPU VPS",
+            40,
+            f"Heavy ML libraries detected: {', '.join(ml_hits)}",
+        )
+        bump("Any VPS (Docker)", 15, "ML stacks often need custom GPU/CPU sizing")
+        bump("Google Cloud Run", 8, "Possible if containerized and within memory limits")
+
+    # --- Ecosystem files ---
+    if any(f.endswith("go.mod") for f in files) or "go" in ecosystems:
+        bump("Fly.io", 30, "Go module project — Fly.io is excellent for Go binaries")
+        bump("Google Cloud Run", 26, "Go services containerize well for Cloud Run")
+        bump("Railway", 18, "Go apps deploy on Railway")
+
+    if any(f.endswith("cargo.toml") for f in files) or "cargo" in ecosystems:
+        bump("Fly.io", 28, "Rust (Cargo) project — compile to a binary on Fly.io")
+        bump("Railway", 20, "Rust projects can build on Railway")
+        bump("Any VPS (Docker)", 16, "Rust binaries run well on a VPS")
+
+    if any("composer.json" in f for f in files) or "composer" in ecosystems:
+        bump("Railway", 20, "PHP (Composer) project")
+        bump("Render", 18, "PHP (Composer) project")
+        bump("Any VPS (Docker)", 15, "Classic PHP stack on VPS")
+
+    if any(f.endswith("gemfile") for f in files) or "rubygems" in ecosystems:
+        bump("Railway", 22, "Ruby (Bundler) project")
+        bump("Render", 22, "Ruby (Bundler) project")
+        bump("Fly.io", 16, "Ruby app on Fly.io")
+
+    if any(f.endswith("pom.xml") or "build.gradle" in f for f in files):
+        bump("Google Cloud Run", 22, "JVM project — containerize and run on Cloud Run")
+        bump("Railway", 18, "JVM project")
+        bump("Render", 18, "JVM project")
+        bump("Any VPS (Docker)", 16, "JVM services commonly run via Docker on a VPS")
+
+    # --- Language fallback signals ---
+    if lang in {"javascript", "typescript"}:
+        bump("Vercel", 12, f"Primary language is {primary_language}")
+        bump("Cloudflare Pages", 10, f"Primary language is {primary_language}")
+        bump("Netlify", 10, f"Primary language is {primary_language}")
+    elif lang == "python":
+        bump("Railway", 14, "Primary language is Python")
+        bump("Render", 12, "Primary language is Python")
+    elif lang == "go":
+        bump("Fly.io", 14, "Primary language is Go")
+        bump("Google Cloud Run", 12, "Primary language is Go")
+    elif lang in {"html", "css"}:
+        bump("GitHub Pages", 25, "Looks like a static site (HTML)")
+        bump("Cloudflare Pages", 22, "Looks like a static site (HTML)")
+        bump("Netlify", 20, "Looks like a static site (HTML)")
+    elif lang == "rust":
+        bump("Fly.io", 14, "Primary language is Rust")
+
+    # Topics / description hints
+    if topic_set & {"static-site", "documentation", "docs", "github-pages"}:
+        bump("GitHub Pages", 20, "Topics suggest a documentation / static site")
+        bump("Cloudflare Pages", 15, "Topics suggest a static site")
+    if "docker" in topic_set or "docker" in desc:
+        bump("Fly.io", 8, "Docker mentioned in topics/description")
+        bump("Google Cloud Run", 8, "Docker mentioned in topics/description")
+
+    # Pure static: only package.json missing backend, or no deps at all
+    has_backend = bool(py_hits or node_hits or ml_hits)
+    has_frontend = bool(found_fe)
+    if has_frontend and not has_backend and not has_dockerfile:
+        bump("Cloudflare Pages", 10, "Frontend-heavy with no clear backend process")
+        bump("Netlify", 8, "Frontend-heavy with no clear backend process")
+
+    # Default polyglot fallback so we always return something useful
+    if max(scores.values(), default=0) == 0:
+        bump("Railway", 10, "General-purpose Git deploy (no strong stack signals)")
+        bump("Render", 9, "General-purpose Git deploy (no strong stack signals)")
+        bump("Fly.io", 8, "General-purpose container/VM host")
+
+    # Build sorted advice list
+    advice: list[DeployAdvice] = []
+    for platform, score in sorted(scores.items(), key=lambda x: (-x[1], x[0])):
+        if score <= 0:
+            continue
+        meta = PLATFORMS[platform]
+        advice.append(
+            DeployAdvice(
+                platform=platform,
+                score=score,
+                reasons=reasons[platform] or [meta["blurb"]],
+                docs_url=meta["docs_url"],
+            )
+        )
+
+    # Cap to top 5 recommendations for UI clarity
+    return advice[:5]

gls/docs/LEGAL_DISCLAIMER.md

@@ -0,0 +1,57 @@
+# Legal disclaimer — GitHub License Scanner
+
+**Effective date:** 2026-07-24
+
+## Not legal advice
+
+GitHub License Scanner (“the Tool”) provides **automated heuristics** about open-source licenses detected in public (or token-accessible) GitHub repositories and package registries.
+
+The Tool:
+
+- is **not** a law firm, attorney, or licensed legal service;
+- does **not** create an attorney–client relationship;
+- does **not** issue formal license-compatibility opinions;
+- does **not** warrant non-infringement, fitness for purpose, or merchantability;
+- may produce **false positives and false negatives**.
+
+**You must consult a qualified attorney** before commercial closed-source distribution, M&A diligence, or any high-stakes compliance decision.
+
+## What the Tool does not fully model
+
+Among other things, results may be incomplete or wrong regarding:
+
+| Topic | Why it matters |
+|-------|----------------|
+| Static vs dynamic linking | GPL obligations often depend on how code is combined |
+| SaaS / network use | AGPL and SSPL may impose duties without traditional “distribution” |
+| Dual licensing / additional permissions | “MIT OR GPL” choice and exceptions change outcomes |
+| Private patches & internal forks | History and LICENSE files may not reflect reality |
+| System libraries & OS exceptions | Some jurisdictions/license texts have special rules |
+| Patent, trademark, export, privacy law | Outside license text classification |
+| Contracts / CLAs / ToS | Can override or add to open-source license terms |
+| Transitive / lockfile-only deps | Not fully resolved from lockfiles in all ecosystems |
+| Maven/Gradle/Go registry licenses | Often unresolved (unknown) |
+
+## “Can sell closed” / “Forces open source”
+
+These UI labels are **risk signals**, not legal conclusions. A green or “OK” result still requires:
+
+1. Attribution and notice preservation (MIT, BSD, Apache-2.0, etc.).
+2. Compliance with Apache-2.0 patent and NOTICE rules where applicable.
+3. Review of each dependency’s full license text and any third-party notices.
+4. Confirmation that build pipelines do not ship “dev-only” copyleft code.
+
+## Copyright notice templates
+
+Generated notices are **templates only**. The GitHub **owner or organization name is not proof of copyright ownership** (forks, employers, multi-author projects, work-for-hire). Always verify LICENSE, NOTICE, and authorship before use.
+
+## No warranty / limitation of liability
+
+THE TOOL IS PROVIDED “AS IS” AND “AS AVAILABLE”, WITHOUT WARRANTY OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE AUTHORS AND COPYRIGHT HOLDERS SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM USE OF THE TOOL OR RELIANCE ON ITS OUTPUT.
+
+See also the project [MIT License](../LICENSE).
+
+## Related documents
+
+- [Privacy](PRIVACY.md)
+- [Terms of use](TERMS.md)

gls/docs/PRIVACY.md

@@ -0,0 +1,69 @@
+# Privacy policy — GitHub License Scanner
+
+**Effective date:** 2026-07-24  
+**Data controller (self-hosted):** the operator who runs this instance.
+
+This Tool is primarily designed for **local / self-hosted** use. If you deploy it as a multi-user service, **you** become responsible for providing a complete privacy notice to your users under applicable law (e.g. GDPR, CCPA/CPRA, UK GDPR).
+
+## Data we process
+
+| Data | Purpose | Storage | Retention |
+|------|---------|---------|-----------|
+| GitHub repo URLs you submit | Run license analysis | In memory during scan; may be written to local history | See history settings |
+| Scan results (owner/repo, license ids, risk flags, short verdict text) | History UI / CLI | `history.json` in the user data directory on the host | Max entries + optional max age (default 90 days) |
+| UI preferences (language, theme) | UX | Browser cookie / NiceGUI user storage (signed) | Browser session / cookie lifetime |
+| Rate-limit counters | Abuse prevention | In-process memory | Rolling window (default 1 hour) |
+| Optional `GITHUB_TOKEN` | Higher GitHub API limits / private repos | Environment of the host process only | Until you remove it |
+
+The Tool **does not intentionally collect** names, emails, payment data, or government IDs.
+
+## Third-party processing
+
+When you run a scan, the host machine sends requests to:
+
+- **api.github.com** — repository metadata and file contents  
+- Package registries as needed (e.g. **registry.npmjs.org**, **pypi.org**, **crates.io**, **rubygems.org**, **repo.packagist.org**)
+
+Those services process the request under **their** privacy policies and terms. Do not submit private repository URLs unless you are authorized and understand that API tokens and network logs may retain metadata.
+
+## History isolation
+
+| Mode | Path | Visibility |
+|------|------|------------|
+| Auth **disabled** (default) | `history.json` in the user data directory | Shared by everyone on the instance |
+| Auth **enabled** (`GLS_AUTH_ENABLED=1`) | `history/<username>.json` in the user data directory | Isolated per logged-in user |
+
+On a multi-user deployment **without** authentication, any user of that instance can see others’ recent scans. Enable auth (create users with `gls user-add …`) for per-user isolation.
+
+## Your rights (GDPR / CCPA-style)
+
+If EU/UK GDPR or similar laws apply to **your** deployment:
+
+| Right | How to exercise on this Tool |
+|-------|------------------------------|
+| Access | Read `history.json` in the user data directory / History tab |
+| Erasure | Use **Clear history** in the UI, or delete `history.json` in the user data directory |
+| Restriction / objection | Stop using the service; operator may disable history |
+| Portability | Export Markdown report from a scan result |
+
+Cookie/local storage for language and theme is used for **strictly necessary / preference** purposes on this self-hosted UI.
+
+## Security measures (baseline)
+
+- Default bind address `127.0.0.1` (local only)  
+- Configurable session signing secret (`GLS_STORAGE_SECRET`)  
+- Scan rate limiting  
+- Batch size caps  
+- History retention limits  
+- No hardcoded production secrets (see `.env.example`)
+
+Operators should still place TLS, access control, and log hygiene in front of any public deployment.
+
+## Children
+
+The Tool is not directed at children under 16 (or the age required in your jurisdiction).
+
+## Contact
+
+For the public open-source project, open an issue on the GitHub repository.  
+For a **self-hosted** instance, contact the organization that runs the server.

gls/docs/TERMS.md

@@ -0,0 +1,52 @@
+# Terms of use — GitHub License Scanner
+
+**Effective date:** 2026-07-24
+
+By using this software (web UI or CLI), you agree to these terms. If you do not agree, do not use the Tool.
+
+## License of the Tool itself
+
+The source code of GitHub License Scanner is released under the **MIT License** (see `LICENSE` in the repository root). That license governs the Tool’s code, **not** the licenses of repositories or packages you scan.
+
+## Acceptable use
+
+You agree to:
+
+1. Only scan repositories and private resources you are **authorized** to access.  
+2. Comply with the [GitHub Terms of Service](https://docs.github.com/site-policy/github-terms/github-terms-of-service) and API rate limits.  
+3. Not use the Tool to overwhelm third-party APIs, bypass access controls, or harass others.  
+4. Not present Tool output as formal legal advice to third parties without independent legal review.  
+5. Not remove or obscure the Tool’s disclaimers when redistributing reports.
+
+## No professional services
+
+Output is **informational only**. You remain solely responsible for license compliance, intellectual property clearance, and commercial decisions.
+
+## Accounts and tokens
+
+If you supply a `GITHUB_TOKEN` (or similar), you are responsible for:
+
+- keeping it secret;
+- using least-privilege scopes;
+- rotating it if leaked;
+- ensuring your use of private repository data is lawful and authorized.
+
+## Availability
+
+The Tool is provided without uptime guarantees. APIs (GitHub, npm, PyPI, etc.) may fail, throttle, or change without notice.
+
+## Indemnity (where enforceable)
+
+To the extent permitted by law, you agree to indemnify and hold harmless the authors and contributors from claims arising from your misuse of the Tool or reliance on its output in commercial or legal contexts.
+
+## Limitation of liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE AUTHORS AND COPYRIGHT HOLDERS SHALL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS OR DATA, ARISING FROM USE OF THE TOOL.
+
+## Changes
+
+Self-hosted operators may present additional terms. Upstream project terms may be updated in this repository; continued use of a newer version constitutes acceptance of updated docs shipped with that version.
+
+## Governing note
+
+These terms are a practical baseline for an open-source developer tool. They are not a substitute for counsel-drafted SaaS terms if you offer the Tool as a commercial multi-tenant service.