gh-issue-lens 0.1.0__tar.gz

gh_issue_lens-0.1.0/LICENSE

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

gh_issue_lens-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include src *.py

gh_issue_lens-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: gh-issue-lens
+Version: 0.1.0
+Summary: Find beginner-friendly GitHub issues and export them as JSONL for LLM analysis.
+Author-email: Mohammad El-Shennawy <mohamedwork216@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Mohammad El-Shennawy
+        
+        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.
+Project-URL: Homepage, https://github.com/MohamedM216/gh-issue-lens
+Project-URL: Repository, https://github.com/MohamedM216/gh-issue-lens
+Project-URL: Issues, https://github.com/MohamedM216/gh-issue-lens/issues
+Keywords: github,open-source,issues,llm,cli,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Dynamic: license-file
+
+# Easier open source contribution process for newcomers
+
+Stop digging through stale GitHub issues. **gh-issue-lens** finds unassigned, beginner-friendly open source issues in any repository and prepares them for LLM analysis in seconds. It bypasses API rate limits by grabbing issues, linked Pull Requests, assignees, and non-bot comments in a single network pass.
+
+# How to use it?
+
+## Option 1: Install from PyPI
+
+```bash
+pip install gh-issue-lens
+```
+**Export your GitHub Personal Access Token:**
+
+First of all, create your personal github token from your github account then use it.
+
+```bash
+export GITHUB_TOKEN="your_personal_access_token"
+```
+
+**Fetch issues:**
+
+```bash
+gh-issue-lens kubernetes kubernetes -d 200
+```
+
+**Filter by labels:**
+
+```bash
+gh-issue-lens kubernetes kubernetes -l "good first issue" "help wanted" -d 50
+```
+
+And for more commands, you can see the sections below. The guidelines are the same. The only difference is to use `gh-issue-lens` directly instead of `python3 cli.py`.
+
+## Option 2: Build it manually
+
+**Clone the repo:**
+
+```bash
+git clone https://github.com/MohamedM216/gh-issue-lens.git
+```
+
+**Install requirements:**
+
+```bash
+pip3 install requests
+```
+
+**Export your GitHub Personal Access Token:**
+
+First of all, create your personal github token from your github account then use it.
+
+```bash
+export GITHUB_TOKEN="your_personal_access_token"
+```
+
+**Verify it works:**
+
+```bash
+cd src/gh_issue_lens/
+python3 cli.py --help
+```
+
+**Fetch 100 issues from a repository:**
+
+100 issues is the default depth you can change it using the -d option.
+
+```bash
+python3 cli.py kubernetes kubernetes
+```
+
+### Filter by up to 5 labels (ORed) and set a depth limit:
+
+This fetches a maximum of 50 issues that have EITHER the "good first issue", "help wanted", or "bug" label.
+
+```bash
+python3 cli.py kubernetes kubernetes -l "good first issue" "help wanted" "bug" -d 50
+```
+
+### Save to a custom JSON file:
+
+If you want to use a custom name for the output file, you can run:
+
+```bash
+python3 cli.py kubernetes kubernetes -l "feature" -d 10 -o custom_dataset.json
+```
+
+### Incremental Saving & Resumability (Checkpointing):
+
+When scraping massive repositories (like Kubernetes), hitting GitHub's API rate limits or network timeouts is common. You no longer have to worry about losing your progress!
+* **JSONL Format:** Issues are now saved line-by-line instantly as they are fetched, ensuring zero data loss.
+* **Auto-Resume:** The tool creates a hidden `.checkpoint` file tracking your progress. If the script crashes or you stop it, simply run the **exact same command** again. It will automatically resume from the exact page it left off, saving your API budget and time.
+
+### Exclude issues with open PRs:
+
+```bash
+python3 cli.py kubernetes kubernetes --exclude-open-prs
+```
+
+### SQLite caching:
+
+`gh-issue-lens` can cache already-exported issues in a local SQLite database. This prevents duplicate issues from being written again when you run the same export multiple times.
+
+Enable caching:
+
+```bash
+python3 cli.py kubernetes kubernetes -d 200 --cache
+```
+
+By default, the cache is stored in `.gh_issue_lens_cache.db`. Use a custom cache database:
+
+```bash
+python3 cli.py kubernetes kubernetes -d 200 --cache --cache-db my_cache.db
+```
+
+Run again with caching enabled. Issues that were already exported in previous runs will be skipped. You can also enable early stopping when the tool keeps finding only cached issues:
+
+```bash
+python3 cli.py kubernetes kubernetes -d 200 --cache --cache-stop
+```
+
+This is useful when re-running the tool against the same repository and you only want newly discovered issues. To reset the cache, delete the cache file:
+
+```bash
+rm .gh_issue_lens_cache.db
+```
+
+Caching is different from checkpointing: checkpointing helps resume a crashed or interrupted run, while caching helps avoid exporting the same issues again across separate runs.
+
+## What's next?
+
+The generated JSON file is suitable to be used as context for Large Language Models (like Gemini, Claude, or ChatGPT). You can upload the output file to an LLM and use targeted prompts to find the perfect issue to work on.
+
+**Example Prompts to try:**
+
+> "I am a newcomer to this repository. Based on the attached JSON, find an issue that is easy to implement, has no active PRs, and doesn't have a long, debated comment history."
+
+> "Filter these issues and list only the ones related to [backend / frontend / database / specific component]."
+
+> "Read the comments on these issues. Which maintainers seem the most responsive and welcoming to beginners? Point me to issues authored or reviewed by them."
+
+> "Summarize the technical requirements for issue #123 based on its description and comment thread. What files should I look at first?"
+
+*Don't forget to STAR the repository :)*
+
+*Happy hacking!*

gh_issue_lens-0.1.0/README.md

@@ -0,0 +1,145 @@
+# Easier open source contribution process for newcomers
+
+Stop digging through stale GitHub issues. **gh-issue-lens** finds unassigned, beginner-friendly open source issues in any repository and prepares them for LLM analysis in seconds. It bypasses API rate limits by grabbing issues, linked Pull Requests, assignees, and non-bot comments in a single network pass.
+
+# How to use it?
+
+## Option 1: Install from PyPI
+
+```bash
+pip install gh-issue-lens
+```
+**Export your GitHub Personal Access Token:**
+
+First of all, create your personal github token from your github account then use it.
+
+```bash
+export GITHUB_TOKEN="your_personal_access_token"
+```
+
+**Fetch issues:**
+
+```bash
+gh-issue-lens kubernetes kubernetes -d 200
+```
+
+**Filter by labels:**
+
+```bash
+gh-issue-lens kubernetes kubernetes -l "good first issue" "help wanted" -d 50
+```
+
+And for more commands, you can see the sections below. The guidelines are the same. The only difference is to use `gh-issue-lens` directly instead of `python3 cli.py`.
+
+## Option 2: Build it manually
+
+**Clone the repo:**
+
+```bash
+git clone https://github.com/MohamedM216/gh-issue-lens.git
+```
+
+**Install requirements:**
+
+```bash
+pip3 install requests
+```
+
+**Export your GitHub Personal Access Token:**
+
+First of all, create your personal github token from your github account then use it.
+
+```bash
+export GITHUB_TOKEN="your_personal_access_token"
+```
+
+**Verify it works:**
+
+```bash
+cd src/gh_issue_lens/
+python3 cli.py --help
+```
+
+**Fetch 100 issues from a repository:**
+
+100 issues is the default depth you can change it using the -d option.
+
+```bash
+python3 cli.py kubernetes kubernetes
+```
+
+### Filter by up to 5 labels (ORed) and set a depth limit:
+
+This fetches a maximum of 50 issues that have EITHER the "good first issue", "help wanted", or "bug" label.
+
+```bash
+python3 cli.py kubernetes kubernetes -l "good first issue" "help wanted" "bug" -d 50
+```
+
+### Save to a custom JSON file:
+
+If you want to use a custom name for the output file, you can run:
+
+```bash
+python3 cli.py kubernetes kubernetes -l "feature" -d 10 -o custom_dataset.json
+```
+
+### Incremental Saving & Resumability (Checkpointing):
+
+When scraping massive repositories (like Kubernetes), hitting GitHub's API rate limits or network timeouts is common. You no longer have to worry about losing your progress!
+* **JSONL Format:** Issues are now saved line-by-line instantly as they are fetched, ensuring zero data loss.
+* **Auto-Resume:** The tool creates a hidden `.checkpoint` file tracking your progress. If the script crashes or you stop it, simply run the **exact same command** again. It will automatically resume from the exact page it left off, saving your API budget and time.
+
+### Exclude issues with open PRs:
+
+```bash
+python3 cli.py kubernetes kubernetes --exclude-open-prs
+```
+
+### SQLite caching:
+
+`gh-issue-lens` can cache already-exported issues in a local SQLite database. This prevents duplicate issues from being written again when you run the same export multiple times.
+
+Enable caching:
+
+```bash
+python3 cli.py kubernetes kubernetes -d 200 --cache
+```
+
+By default, the cache is stored in `.gh_issue_lens_cache.db`. Use a custom cache database:
+
+```bash
+python3 cli.py kubernetes kubernetes -d 200 --cache --cache-db my_cache.db
+```
+
+Run again with caching enabled. Issues that were already exported in previous runs will be skipped. You can also enable early stopping when the tool keeps finding only cached issues:
+
+```bash
+python3 cli.py kubernetes kubernetes -d 200 --cache --cache-stop
+```
+
+This is useful when re-running the tool against the same repository and you only want newly discovered issues. To reset the cache, delete the cache file:
+
+```bash
+rm .gh_issue_lens_cache.db
+```
+
+Caching is different from checkpointing: checkpointing helps resume a crashed or interrupted run, while caching helps avoid exporting the same issues again across separate runs.
+
+## What's next?
+
+The generated JSON file is suitable to be used as context for Large Language Models (like Gemini, Claude, or ChatGPT). You can upload the output file to an LLM and use targeted prompts to find the perfect issue to work on.
+
+**Example Prompts to try:**
+
+> "I am a newcomer to this repository. Based on the attached JSON, find an issue that is easy to implement, has no active PRs, and doesn't have a long, debated comment history."
+
+> "Filter these issues and list only the ones related to [backend / frontend / database / specific component]."
+
+> "Read the comments on these issues. Which maintainers seem the most responsive and welcoming to beginners? Point me to issues authored or reviewed by them."
+
+> "Summarize the technical requirements for issue #123 based on its description and comment thread. What files should I look at first?"
+
+*Don't forget to STAR the repository :)*
+
+*Happy hacking!*

gh_issue_lens-0.1.0/pyproject.toml

@@ -0,0 +1,100 @@
+[build-system]
+requires = [
+    "setuptools>=68",
+    "wheel",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gh-issue-lens"
+description = "Find beginner-friendly GitHub issues and export them as JSONL for LLM analysis."
+dynamic = [
+    "version",
+    "readme",
+]
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Mohammad El-Shennawy", email = "mohamedwork216@gmail.com" },
+]
+keywords = [
+    "github",
+    "open-source",
+    "issues",
+    "llm",
+    "cli",
+    "developer-tools",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "requests>=2.31.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2.0",
+    "twine>=5.0.0",
+    "pytest>=8.0.0",
+    "ruff>=0.5.0",
+]
+
+[project.scripts]
+gh-issue-lens = "gh_issue_lens.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/MohamedM216/gh-issue-lens"
+Repository = "https://github.com/MohamedM216/gh-issue-lens"
+Issues = "https://github.com/MohamedM216/gh-issue-lens/issues"
+
+[tool.setuptools.dynamic]
+version = { attr = "gh_issue_lens.__version__" }
+readme = { file = "README.md", content-type = "text/markdown" }
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = [
+    "src",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+exclude = [
+    ".git",
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".mypy_cache",
+    ".ruff_cache",
+    "node_modules",
+    "dist",
+    "build",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+]
+fixable = ["ALL"]
+
+[tool.ruff.format]
+indent-style = "space"
+quote-style = "double"

gh_issue_lens-0.1.0/setup.cfg

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

gh_issue_lens-0.1.0/src/gh_issue_lens/__init__.py

@@ -0,0 +1,3 @@
+"""gh-issue-lens package."""
+
+__version__ = "0.1.0"

gh_issue_lens-0.1.0/src/gh_issue_lens/cli.py

@@ -0,0 +1,136 @@
+"""Command line interface for gh-issue-lens."""
+
+import argparse
+import os
+import sys
+
+from . import __version__
+from .core import DEFAULT_CACHE_DB, fetch_issues
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="gh-issue-lens",
+        description=(
+            "Easier open source contribution process for newcomers. "
+            "Fetch open issues from a GitHub repository and export them "
+            "as JSONL for LLM analysis."
+        ),
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    parser.add_argument(
+        "owner",
+        help="GitHub repository owner (e.g., 'kubernetes')",
+    )
+
+    parser.add_argument(
+        "repo",
+        help="GitHub repository name (e.g., 'kubernetes')",
+    )
+
+    parser.add_argument(
+        "-l",
+        "--labels",
+        nargs="+",
+        help=(
+            "Filter by up to 5 labels. Labels are ORed "
+            "(e.g., -l 'good first issue' 'help wanted')"
+        ),
+        default=[],
+    )
+
+    parser.add_argument(
+        "-d",
+        "--depth",
+        type=int,
+        help="Maximum number of issues to fetch (default: 100)",
+        default=100,
+    )
+
+    parser.add_argument(
+        "-o",
+        "--output",
+        help="Output JSONL filename",
+        default=None,
+    )
+
+    parser.add_argument(
+        "--exclude-open-prs",
+        action="store_true",
+        help="Skip issues that already have an open pull request against them.",
+    )
+
+    parser.add_argument(
+        "--cache",
+        action="store_true",
+        help="Enable SQLite caching to avoid exporting issues seen in previous runs.",
+    )
+
+    parser.add_argument(
+        "--cache-db",
+        default=DEFAULT_CACHE_DB,
+        help=f"Path to SQLite cache file. Default: {DEFAULT_CACHE_DB}",
+    )
+
+    parser.add_argument(
+        "--cache-stop",
+        action="store_true",
+        help=(
+            "Stop early when multiple consecutive pages contain "
+            "only cached eligible issues."
+        ),
+    )
+
+    args = parser.parse_args()
+
+    if len(args.labels) > 5:
+        print("Error: You can specify a maximum of 5 labels.")
+        sys.exit(1)
+
+    token = os.getenv("GITHUB_TOKEN")
+
+    if not token:
+        print("Error: GITHUB_TOKEN environment variable not set.")
+        print("Please run: export GITHUB_TOKEN='your_personal_access_token'")
+        sys.exit(1)
+
+    output_filename = args.output if args.output else f"{args.repo}_issues.jsonl"
+    checkpoint_file = f".checkpoint_{args.owner}_{args.repo}.json"
+
+    # If cache is disabled and there is no checkpoint, start with a fresh output file.
+    # If cache is enabled, keep the old output file and append only new issues.
+    if not os.path.exists(checkpoint_file) and not args.cache:
+        open(output_filename, "w", encoding="utf-8").close()
+
+    try:
+        total_fetched = fetch_issues(
+            owner=args.owner,
+            repo=args.repo,
+            labels=args.labels,
+            depth=args.depth,
+            token=token,
+            output_filename=output_filename,
+            exclude_open_prs=args.exclude_open_prs,
+            use_cache=args.cache,
+            cache_db=args.cache_db,
+            cache_stop=args.cache_stop,
+        )
+
+        print(f"\nDone! Scraped {total_fetched} issues in this run.")
+        print(f"Data saved to {output_filename} (JSONL format)")
+
+    except KeyboardInterrupt:
+        print("\nProcess interrupted by user.")
+        print("Progress has been saved to the checkpoint file.")
+        print("Run the same command again to resume.")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

gh_issue_lens-0.1.0/src/gh_issue_lens/core.py

@@ -0,0 +1,390 @@
+"""Core logic for gh-issue-lens."""
+
+import json
+import os
+import sqlite3
+import sys
+from datetime import datetime, timezone
+
+import requests
+
+DEFAULT_CACHE_DB = ".gh_issue_lens_cache.db"
+
+
+def get_graphql_query():
+    """
+    GraphQL query used to fetch open issues.
+
+    The page size is intentionally small to reduce the chance of timeouts
+    and GitHub 502 responses on very large repositories.
+    """
+    return """
+query($owner: String!, $repo: String!, $cursor: String) {
+  repository(owner: $owner, name: $repo) {
+    issues(
+      first: 20,
+      after: $cursor,
+      states: OPEN,
+      orderBy: {
+        field: CREATED_AT,
+        direction: DESC
+      }
+    ) {
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      nodes {
+        number
+        title
+        url
+        createdAt
+        body
+        labels(first: 10) {
+          nodes {
+            name
+          }
+        }
+        assignees(first: 10) {
+          nodes {
+            login
+          }
+        }
+        comments(first: 20) {
+          nodes {
+            author {
+              login
+              __typename
+            }
+            body
+          }
+        }
+        timelineItems(itemTypes: [CROSS_REFERENCED_EVENT], first: 10) {
+          nodes {
+            ... on CrossReferencedEvent {
+              source {
+                ... on PullRequest {
+                  state
+                  number
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+"""
+
+
+def init_cache(cache_db):
+    """Create or open the SQLite cache."""
+    conn = sqlite3.connect(cache_db)
+
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS cached_issues (
+            repo TEXT NOT NULL,
+            issue_number INTEGER NOT NULL,
+            url TEXT,
+            cached_at TEXT NOT NULL,
+            PRIMARY KEY (repo, issue_number)
+        )
+        """
+    )
+
+    conn.commit()
+    return conn
+
+
+def is_issue_cached(conn, repo_full_name, issue_number):
+    """Return True if this issue number is already cached."""
+    cur = conn.execute(
+        """
+        SELECT 1
+        FROM cached_issues
+        WHERE repo = ? AND issue_number = ?
+        LIMIT 1
+        """,
+        (repo_full_name.lower(), issue_number),
+    )
+
+    return cur.fetchone() is not None
+
+
+def cache_issues(conn, repo_full_name, issues):
+    """Insert newly exported issues into the cache."""
+    if not issues:
+        return
+
+    now = datetime.now(timezone.utc).isoformat()
+
+    rows = [
+        (
+            repo_full_name.lower(),
+            issue["number"],
+            issue.get("url"),
+            now,
+        )
+        for issue in issues
+    ]
+
+    conn.executemany(
+        """
+        INSERT OR IGNORE INTO cached_issues (
+            repo,
+            issue_number,
+            url,
+            cached_at
+        )
+        VALUES (?, ?, ?, ?)
+        """,
+        rows,
+    )
+
+    conn.commit()
+
+
+def fetch_issues(
+    owner,
+    repo,
+    labels,
+    depth,
+    token,
+    output_filename,
+    exclude_open_prs=False,
+    use_cache=False,
+    cache_db=DEFAULT_CACHE_DB,
+    cache_stop=False,
+):
+    """
+    Fetch issues from GitHub and append them to a JSONL file.
+
+    Returns the number of newly exported issues in this run.
+    """
+    url = "https://api.github.com/graphql"
+
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "User-Agent": "gh-issue-lens",
+    }
+
+    query = get_graphql_query()
+
+    has_labels = bool(labels and len(labels) > 0)
+    target_labels_lower = [label.lower() for label in labels] if has_labels else []
+
+    has_next_page = True
+    cursor = None
+    page_num = 1
+    extracted_count = 0
+
+    checkpoint_file = f".checkpoint_{owner}_{repo}.json"
+
+    conn = init_cache(cache_db) if use_cache else None
+    repo_key = f"{owner}/{repo}".lower()
+
+    cached_skipped = 0
+    no_new_pages = 0
+
+    if os.path.exists(checkpoint_file):
+        try:
+            with open(checkpoint_file, "r", encoding="utf-8") as f:
+                cp_data = json.load(f)
+
+            cursor = cp_data.get("cursor")
+            page_num = cp_data.get("page_num", 1)
+            extracted_count = cp_data.get("extracted_count", 0)
+
+            print(
+                f"Resuming from checkpoint. Starting at page {page_num}, "
+                f"{extracted_count} issues already fetched."
+            )
+        except Exception as e:
+            print(f"Warning: Could not read checkpoint file: {e}")
+
+    label_text = f" (Filtering by ANY of: {', '.join(labels)})" if has_labels else ""
+
+    print(f"Starting extraction for {owner}/{repo}{label_text}...")
+    print(f"Target depth: {depth} matches.")
+
+    try:
+        while has_next_page and extracted_count < depth:
+            variables = {
+                "owner": owner,
+                "repo": repo,
+                "cursor": cursor,
+            }
+
+            print(f" -> Scanning page {page_num} (Fetching up to 20 open issues from GitHub)...")
+
+            try:
+                response = requests.post(
+                    url,
+                    json={
+                        "query": query,
+                        "variables": variables,
+                    },
+                    headers=headers,
+                    timeout=60,
+                )
+            except requests.exceptions.RequestException as exc:
+                print(f"Network error: {exc}")
+                print("Progress saved to checkpoint. Run the command again to resume.")
+                sys.exit(1)
+
+            if response.status_code != 200:
+                print(f"Error {response.status_code}: {response.text}")
+                print("Progress saved to checkpoint. Run the command again to resume.")
+                sys.exit(1)
+
+            try:
+                data = response.json()
+            except ValueError as exc:
+                print(f"Could not parse GitHub response: {exc}")
+                print("Progress saved to checkpoint. Run the command again to resume.")
+                sys.exit(1)
+
+            if "errors" in data:
+                print(f"GraphQL Error: {data['errors'][0]['message']}")
+                print("Progress saved to checkpoint. Run the command again to resume.")
+                sys.exit(1)
+
+            repository = data.get("data", {}).get("repository")
+
+            if not repository:
+                print(f"Repository {owner}/{repo} not found.")
+                sys.exit(1)
+
+            issues_data = repository.get("issues", {})
+            nodes = issues_data.get("nodes", [])
+
+            page_issues = []
+            eligible_before_cache = 0
+
+            for issue in nodes:
+                if not issue:
+                    continue
+
+                issue_labels = [
+                    label_node["name"].lower()
+                    for label_node in issue.get("labels", {}).get("nodes", [])
+                    if label_node
+                ]
+
+                if has_labels:
+                    if not any(label in issue_labels for label in target_labels_lower):
+                        continue
+
+                assignees = [
+                    assignee["login"]
+                    for assignee in issue.get("assignees", {}).get("nodes", [])
+                    if assignee
+                ]
+
+                comments = []
+
+                for comment in issue.get("comments", {}).get("nodes", []):
+                    if not comment:
+                        continue
+
+                    author = comment.get("author")
+
+                    if author and author.get("__typename") != "Bot":
+                        comments.append(
+                            {
+                                "author": author.get("login"),
+                                "body": comment.get("body"),
+                            }
+                        )
+
+                has_open_pr = False
+
+                for event in issue.get("timelineItems", {}).get("nodes", []):
+                    if not event:
+                        continue
+
+                    source = event.get("source")
+
+                    if source and source.get("state") == "OPEN":
+                        has_open_pr = True
+                        break
+
+                if exclude_open_prs and has_open_pr:
+                    continue
+
+                eligible_before_cache += 1
+
+                if conn is not None and is_issue_cached(conn, repo_key, issue.get("number")):
+                    cached_skipped += 1
+                    continue
+
+                page_issues.append(
+                    {
+                        "number": issue.get("number"),
+                        "title": issue.get("title"),
+                        "url": issue.get("url"),
+                        "created_at": issue.get("createdAt"),
+                        "is_assigned": len(assignees) > 0,
+                        "assigned_to": assignees,
+                        "has_open_pr_against_it": has_open_pr,
+                        "labels": issue_labels,
+                        "body": issue.get("body"),
+                        "comments": comments,
+                    }
+                )
+
+                if extracted_count + len(page_issues) >= depth:
+                    break
+
+            with open(output_filename, "a", encoding="utf-8") as f:
+                for item in page_issues:
+                    f.write(json.dumps(item) + "\n")
+
+            if conn is not None and page_issues:
+                cache_issues(conn, repo_key, page_issues)
+
+            extracted_count += len(page_issues)
+
+            page_info = issues_data.get("pageInfo", {})
+            has_next_page = page_info.get("hasNextPage", False)
+            cursor = page_info.get("endCursor")
+            page_num += 1
+
+            cache_should_stop = False
+
+            if conn is not None and cache_stop:
+                if eligible_before_cache > 0 and len(page_issues) == 0:
+                    no_new_pages += 1
+
+                    if no_new_pages >= 3:
+                        cache_should_stop = True
+                else:
+                    no_new_pages = 0
+
+            if has_next_page and extracted_count < depth and not cache_should_stop:
+                with open(checkpoint_file, "w", encoding="utf-8") as f:
+                    json.dump(
+                        {
+                            "cursor": cursor,
+                            "page_num": page_num,
+                            "extracted_count": extracted_count,
+                        },
+                        f,
+                    )
+            else:
+                if os.path.exists(checkpoint_file):
+                    os.remove(checkpoint_file)
+
+            if cache_should_stop:
+                print("Stopping early: 3 consecutive pages contained only cached eligible issues.")
+                break
+
+        if use_cache:
+            print(f"Cached issues skipped: {cached_skipped}")
+
+        return extracted_count
+    finally:
+        if conn is not None:
+            conn.close()

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

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: gh-issue-lens
+Version: 0.1.0
+Summary: Find beginner-friendly GitHub issues and export them as JSONL for LLM analysis.
+Author-email: Mohammad El-Shennawy <mohamedwork216@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Mohammad El-Shennawy
+        
+        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.
+Project-URL: Homepage, https://github.com/MohamedM216/gh-issue-lens
+Project-URL: Repository, https://github.com/MohamedM216/gh-issue-lens
+Project-URL: Issues, https://github.com/MohamedM216/gh-issue-lens/issues
+Keywords: github,open-source,issues,llm,cli,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Dynamic: license-file
+
+# Easier open source contribution process for newcomers
+
+Stop digging through stale GitHub issues. **gh-issue-lens** finds unassigned, beginner-friendly open source issues in any repository and prepares them for LLM analysis in seconds. It bypasses API rate limits by grabbing issues, linked Pull Requests, assignees, and non-bot comments in a single network pass.
+
+# How to use it?
+
+## Option 1: Install from PyPI
+
+```bash
+pip install gh-issue-lens
+```
+**Export your GitHub Personal Access Token:**
+
+First of all, create your personal github token from your github account then use it.
+
+```bash
+export GITHUB_TOKEN="your_personal_access_token"
+```
+
+**Fetch issues:**
+
+```bash
+gh-issue-lens kubernetes kubernetes -d 200
+```
+
+**Filter by labels:**
+
+```bash
+gh-issue-lens kubernetes kubernetes -l "good first issue" "help wanted" -d 50
+```
+
+And for more commands, you can see the sections below. The guidelines are the same. The only difference is to use `gh-issue-lens` directly instead of `python3 cli.py`.
+
+## Option 2: Build it manually
+
+**Clone the repo:**
+
+```bash
+git clone https://github.com/MohamedM216/gh-issue-lens.git
+```
+
+**Install requirements:**
+
+```bash
+pip3 install requests
+```
+
+**Export your GitHub Personal Access Token:**
+
+First of all, create your personal github token from your github account then use it.
+
+```bash
+export GITHUB_TOKEN="your_personal_access_token"
+```
+
+**Verify it works:**
+
+```bash
+cd src/gh_issue_lens/
+python3 cli.py --help
+```
+
+**Fetch 100 issues from a repository:**
+
+100 issues is the default depth you can change it using the -d option.
+
+```bash
+python3 cli.py kubernetes kubernetes
+```
+
+### Filter by up to 5 labels (ORed) and set a depth limit:
+
+This fetches a maximum of 50 issues that have EITHER the "good first issue", "help wanted", or "bug" label.
+
+```bash
+python3 cli.py kubernetes kubernetes -l "good first issue" "help wanted" "bug" -d 50
+```
+
+### Save to a custom JSON file:
+
+If you want to use a custom name for the output file, you can run:
+
+```bash
+python3 cli.py kubernetes kubernetes -l "feature" -d 10 -o custom_dataset.json
+```
+
+### Incremental Saving & Resumability (Checkpointing):
+
+When scraping massive repositories (like Kubernetes), hitting GitHub's API rate limits or network timeouts is common. You no longer have to worry about losing your progress!
+* **JSONL Format:** Issues are now saved line-by-line instantly as they are fetched, ensuring zero data loss.
+* **Auto-Resume:** The tool creates a hidden `.checkpoint` file tracking your progress. If the script crashes or you stop it, simply run the **exact same command** again. It will automatically resume from the exact page it left off, saving your API budget and time.
+
+### Exclude issues with open PRs:
+
+```bash
+python3 cli.py kubernetes kubernetes --exclude-open-prs
+```
+
+### SQLite caching:
+
+`gh-issue-lens` can cache already-exported issues in a local SQLite database. This prevents duplicate issues from being written again when you run the same export multiple times.
+
+Enable caching:
+
+```bash
+python3 cli.py kubernetes kubernetes -d 200 --cache
+```
+
+By default, the cache is stored in `.gh_issue_lens_cache.db`. Use a custom cache database:
+
+```bash
+python3 cli.py kubernetes kubernetes -d 200 --cache --cache-db my_cache.db
+```
+
+Run again with caching enabled. Issues that were already exported in previous runs will be skipped. You can also enable early stopping when the tool keeps finding only cached issues:
+
+```bash
+python3 cli.py kubernetes kubernetes -d 200 --cache --cache-stop
+```
+
+This is useful when re-running the tool against the same repository and you only want newly discovered issues. To reset the cache, delete the cache file:
+
+```bash
+rm .gh_issue_lens_cache.db
+```
+
+Caching is different from checkpointing: checkpointing helps resume a crashed or interrupted run, while caching helps avoid exporting the same issues again across separate runs.
+
+## What's next?
+
+The generated JSON file is suitable to be used as context for Large Language Models (like Gemini, Claude, or ChatGPT). You can upload the output file to an LLM and use targeted prompts to find the perfect issue to work on.
+
+**Example Prompts to try:**
+
+> "I am a newcomer to this repository. Based on the attached JSON, find an issue that is easy to implement, has no active PRs, and doesn't have a long, debated comment history."
+
+> "Filter these issues and list only the ones related to [backend / frontend / database / specific component]."
+
+> "Read the comments on these issues. Which maintainers seem the most responsive and welcoming to beginners? Point me to issues authored or reviewed by them."
+
+> "Summarize the technical requirements for issue #123 based on its description and comment thread. What files should I look at first?"
+
+*Don't forget to STAR the repository :)*
+
+*Happy hacking!*

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

@@ -0,0 +1,14 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/gh_issue_lens/__init__.py
+src/gh_issue_lens/cli.py
+src/gh_issue_lens/core.py
+src/gh_issue_lens.egg-info/PKG-INFO
+src/gh_issue_lens.egg-info/SOURCES.txt
+src/gh_issue_lens.egg-info/dependency_links.txt
+src/gh_issue_lens.egg-info/entry_points.txt
+src/gh_issue_lens.egg-info/requires.txt
+src/gh_issue_lens.egg-info/top_level.txt
+tests/test_smoke.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+[console_scripts]
+gh-issue-lens = gh_issue_lens.cli:main

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

@@ -0,0 +1,7 @@
+requests>=2.31.0
+
+[dev]
+build>=1.2.0
+twine>=5.0.0
+pytest>=8.0.0
+ruff>=0.5.0

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

@@ -0,0 +1 @@
+gh_issue_lens

gh_issue_lens-0.1.0/tests/test_smoke.py

@@ -0,0 +1,17 @@
+from gh_issue_lens import __version__
+from gh_issue_lens.core import get_graphql_query
+
+
+def test_version_exists():
+    assert __version__
+    assert isinstance(__version__, str)
+
+
+def test_graphql_query_contains_expected_fields():
+    query = get_graphql_query()
+
+    assert "repository" in query
+    assert "issues" in query
+    assert "pageInfo" in query
+    assert "hasNextPage" in query
+    assert "endCursor" in query