codebase-brief 0.1.2__tar.gz → 0.1.4__tar.gz

{codebase_brief-0.1.2 → codebase_brief-0.1.4}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.4
+
+- Refresh the package listing with the current first-run instructions, product fit, limitations, and importer-aware `--base` behavior.
+- Link package metadata to the project site and keep source-code and issue links explicit.
+
+## 0.1.3
+
+- Find task-matching snippets deeper inside selected source files and show their line ranges instead of always starting at the file's beginning.
+- Keep excerpt reads bounded and apply the existing secret redaction before including source snippets.
+
 ## 0.1.2
 
 - Add `brief --demo`, which generates a real example brief from temporary sample files without reading or modifying the user's project.

{codebase_brief-0.1.2 → codebase_brief-0.1.4}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: codebase-brief
-Version: 0.1.2
+Version: 0.1.4
 Summary: Local-first CLI that builds task-focused context briefs from code repositories
 Author: Mohamed Maggy
 License-Expression: MIT
-Project-URL: Homepage, https://github.com/mohamed1111111m/codebase-brief
+Project-URL: Homepage, https://mohamed1111111m.github.io/codebase-brief/
 Project-URL: Repository, https://github.com/mohamed1111111m/codebase-brief
 Project-URL: Issues, https://github.com/mohamed1111111m/codebase-brief/issues
 Keywords: developer-tools,codebase,context,cli
@@ -33,11 +33,13 @@ Dynamic: license-file
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
 [![MIT License](https://img.shields.io/badge/license-MIT-8A63D2.svg)](LICENSE)
 
-**Browser-based coding chats cannot see your local repo.** Codebase Brief turns one coding task into a short, reviewable file shortlist—with excerpts, reasons, and source paths—so you can give ChatGPT, Claude, or another chat the project context it cannot inspect itself.
+**Need a reviewed, task-specific handoff for a coding chat?** Codebase Brief turns one coding task into a short file shortlist—with excerpts, reasons, and source paths—when your assistant cannot access the project directly or you want to choose exactly what context to share.
 
-It works locally, without an AI service or account. Review the brief, save it, or paste it into ChatGPT, Claude, or another assistant that cannot inspect your local working tree.
+It works locally, without an AI service or account. Review the brief, save it, or paste it into the assistant you want to use.
 
-**Best fit:** a browser chat that cannot inspect your local files, or a task where you want to choose exactly what context to share. If your coding agent already reads and indexes the working tree, its built-in repo tools may be enough.
+## When Codebase Brief fits
+
+It is most useful when your chat cannot access the current local project, or when you want a small, reviewable handoff instead of giving an assistant broad repo access. Some tools now offer local-folder or GitHub-repository access—for example, [ChatGPT Work and Codex](https://help.openai.com/en/articles/20001275), [Claude's local and GitHub connections](https://support.anthropic.com/en/articles/11725091-when-to-use-desktop-and-web-connectors), and [Gemini's GitHub import](https://support.google.com/gemini/answer/16176929). Availability depends on the tool, plan, and setup. If your assistant can already read the current working tree and do the task safely, its built-in repo access may be simpler; you may not need Codebase Brief.
 
 ## See it in action
 
@@ -53,7 +55,7 @@ The first image is a terminal-style rendering of the app's actual numbered menu.
 
 You need Python 3.10 or newer. Git is optional, but required for recent-history and base-diff details.
 
-The current PyPI release is `0.1.2` and includes the review-feedback summary, importer-aware `--base` selection, and a sample demo. Install it with `pipx`:
+The current PyPI package includes the review-feedback summary, importer-aware `--base` selection, and a sample demo. Install it with `pipx`:
 
 ```powershell
 pipx install codebase-brief
@@ -90,6 +92,8 @@ When the menu opens, it uses the folder you launched it from as the starting pro
 
 In plain terms, Codebase Brief makes a small guide to a project so an AI coding assistant can get oriented before helping with a task. It does not write or fix code. It reads project information locally and prepares a guide for you to review and share.
 
+For selected source files, it looks for code near words in your task and labels each excerpt with its source line range. This is a bounded, best-effort search: if it finds no clear match, it falls back to a general excerpt. Check the cited lines in your editor before relying on them.
+
 Before generating the brief, the tool shows suggested files and why they were selected. Press Enter to keep the checked files, type file numbers to toggle selections, or use `add path/to/file.py` to include another safe text file from the repository. Type `none` for an overview without source excerpts. After the brief is shown, saved, or copied, Codebase Brief prints a copyable summary of files kept, removed, added from suggestions, and manually added. To help improve file selection, paste that summary into the [tester feedback form](https://github.com/mohamed1111111m/codebase-brief/issues/new?template=tester-feedback.yml) along with your task and whether the brief helped. Do not include private source code or secrets. The menu's save-here choice writes `context.md` in the folder where you launched the menu; if that is the target repository, the file will be created there. Choose the show or copy option to avoid writing a file into that folder.
 
 For your first try, choose a project you know and a task you understand. Check whether the suggested files are the ones you would have shown a coding assistant yourself.

{codebase_brief-0.1.2 → codebase_brief-0.1.4}/README.md

@@ -8,11 +8,13 @@
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
 [![MIT License](https://img.shields.io/badge/license-MIT-8A63D2.svg)](LICENSE)
 
-**Browser-based coding chats cannot see your local repo.** Codebase Brief turns one coding task into a short, reviewable file shortlist—with excerpts, reasons, and source paths—so you can give ChatGPT, Claude, or another chat the project context it cannot inspect itself.
+**Need a reviewed, task-specific handoff for a coding chat?** Codebase Brief turns one coding task into a short file shortlist—with excerpts, reasons, and source paths—when your assistant cannot access the project directly or you want to choose exactly what context to share.
 
-It works locally, without an AI service or account. Review the brief, save it, or paste it into ChatGPT, Claude, or another assistant that cannot inspect your local working tree.
+It works locally, without an AI service or account. Review the brief, save it, or paste it into the assistant you want to use.
 
-**Best fit:** a browser chat that cannot inspect your local files, or a task where you want to choose exactly what context to share. If your coding agent already reads and indexes the working tree, its built-in repo tools may be enough.
+## When Codebase Brief fits
+
+It is most useful when your chat cannot access the current local project, or when you want a small, reviewable handoff instead of giving an assistant broad repo access. Some tools now offer local-folder or GitHub-repository access—for example, [ChatGPT Work and Codex](https://help.openai.com/en/articles/20001275), [Claude's local and GitHub connections](https://support.anthropic.com/en/articles/11725091-when-to-use-desktop-and-web-connectors), and [Gemini's GitHub import](https://support.google.com/gemini/answer/16176929). Availability depends on the tool, plan, and setup. If your assistant can already read the current working tree and do the task safely, its built-in repo access may be simpler; you may not need Codebase Brief.
 
 ## See it in action
 
@@ -28,7 +30,7 @@ The first image is a terminal-style rendering of the app's actual numbered menu.
 
 You need Python 3.10 or newer. Git is optional, but required for recent-history and base-diff details.
 
-The current PyPI release is `0.1.2` and includes the review-feedback summary, importer-aware `--base` selection, and a sample demo. Install it with `pipx`:
+The current PyPI package includes the review-feedback summary, importer-aware `--base` selection, and a sample demo. Install it with `pipx`:
 
 ```powershell
 pipx install codebase-brief
@@ -65,6 +67,8 @@ When the menu opens, it uses the folder you launched it from as the starting pro
 
 In plain terms, Codebase Brief makes a small guide to a project so an AI coding assistant can get oriented before helping with a task. It does not write or fix code. It reads project information locally and prepares a guide for you to review and share.
 
+For selected source files, it looks for code near words in your task and labels each excerpt with its source line range. This is a bounded, best-effort search: if it finds no clear match, it falls back to a general excerpt. Check the cited lines in your editor before relying on them.
+
 Before generating the brief, the tool shows suggested files and why they were selected. Press Enter to keep the checked files, type file numbers to toggle selections, or use `add path/to/file.py` to include another safe text file from the repository. Type `none` for an overview without source excerpts. After the brief is shown, saved, or copied, Codebase Brief prints a copyable summary of files kept, removed, added from suggestions, and manually added. To help improve file selection, paste that summary into the [tester feedback form](https://github.com/mohamed1111111m/codebase-brief/issues/new?template=tester-feedback.yml) along with your task and whether the brief helped. Do not include private source code or secrets. The menu's save-here choice writes `context.md` in the folder where you launched the menu; if that is the target repository, the file will be created there. Choose the show or copy option to avoid writing a file into that folder.
 
 For your first try, choose a project you know and a task you understand. Check whether the suggested files are the ones you would have shown a coding assistant yourself.

{codebase_brief-0.1.2 → codebase_brief-0.1.4}/codebase_brief.egg-info/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: codebase-brief
-Version: 0.1.2
+Version: 0.1.4
 Summary: Local-first CLI that builds task-focused context briefs from code repositories
 Author: Mohamed Maggy
 License-Expression: MIT
-Project-URL: Homepage, https://github.com/mohamed1111111m/codebase-brief
+Project-URL: Homepage, https://mohamed1111111m.github.io/codebase-brief/
 Project-URL: Repository, https://github.com/mohamed1111111m/codebase-brief
 Project-URL: Issues, https://github.com/mohamed1111111m/codebase-brief/issues
 Keywords: developer-tools,codebase,context,cli
@@ -33,11 +33,13 @@ Dynamic: license-file
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
 [![MIT License](https://img.shields.io/badge/license-MIT-8A63D2.svg)](LICENSE)
 
-**Browser-based coding chats cannot see your local repo.** Codebase Brief turns one coding task into a short, reviewable file shortlist—with excerpts, reasons, and source paths—so you can give ChatGPT, Claude, or another chat the project context it cannot inspect itself.
+**Need a reviewed, task-specific handoff for a coding chat?** Codebase Brief turns one coding task into a short file shortlist—with excerpts, reasons, and source paths—when your assistant cannot access the project directly or you want to choose exactly what context to share.
 
-It works locally, without an AI service or account. Review the brief, save it, or paste it into ChatGPT, Claude, or another assistant that cannot inspect your local working tree.
+It works locally, without an AI service or account. Review the brief, save it, or paste it into the assistant you want to use.
 
-**Best fit:** a browser chat that cannot inspect your local files, or a task where you want to choose exactly what context to share. If your coding agent already reads and indexes the working tree, its built-in repo tools may be enough.
+## When Codebase Brief fits
+
+It is most useful when your chat cannot access the current local project, or when you want a small, reviewable handoff instead of giving an assistant broad repo access. Some tools now offer local-folder or GitHub-repository access—for example, [ChatGPT Work and Codex](https://help.openai.com/en/articles/20001275), [Claude's local and GitHub connections](https://support.anthropic.com/en/articles/11725091-when-to-use-desktop-and-web-connectors), and [Gemini's GitHub import](https://support.google.com/gemini/answer/16176929). Availability depends on the tool, plan, and setup. If your assistant can already read the current working tree and do the task safely, its built-in repo access may be simpler; you may not need Codebase Brief.
 
 ## See it in action
 
@@ -53,7 +55,7 @@ The first image is a terminal-style rendering of the app's actual numbered menu.
 
 You need Python 3.10 or newer. Git is optional, but required for recent-history and base-diff details.
 
-The current PyPI release is `0.1.2` and includes the review-feedback summary, importer-aware `--base` selection, and a sample demo. Install it with `pipx`:
+The current PyPI package includes the review-feedback summary, importer-aware `--base` selection, and a sample demo. Install it with `pipx`:
 
 ```powershell
 pipx install codebase-brief
@@ -90,6 +92,8 @@ When the menu opens, it uses the folder you launched it from as the starting pro
 
 In plain terms, Codebase Brief makes a small guide to a project so an AI coding assistant can get oriented before helping with a task. It does not write or fix code. It reads project information locally and prepares a guide for you to review and share.
 
+For selected source files, it looks for code near words in your task and labels each excerpt with its source line range. This is a bounded, best-effort search: if it finds no clear match, it falls back to a general excerpt. Check the cited lines in your editor before relying on them.
+
 Before generating the brief, the tool shows suggested files and why they were selected. Press Enter to keep the checked files, type file numbers to toggle selections, or use `add path/to/file.py` to include another safe text file from the repository. Type `none` for an overview without source excerpts. After the brief is shown, saved, or copied, Codebase Brief prints a copyable summary of files kept, removed, added from suggestions, and manually added. To help improve file selection, paste that summary into the [tester feedback form](https://github.com/mohamed1111111m/codebase-brief/issues/new?template=tester-feedback.yml) along with your task and whether the brief helped. Do not include private source code or secrets. The menu's save-here choice writes `context.md` in the folder where you launched the menu; if that is the target repository, the file will be created there. Choose the show or copy option to avoid writing a file into that folder.
 
 For your first try, choose a project you know and a task you understand. Check whether the suggested files are the ones you would have shown a coding assistant yourself.

{codebase_brief-0.1.2 → codebase_brief-0.1.4}/context_inject/cli.py

@@ -24,7 +24,7 @@ MAX_KEY_FILES = 12
 MAX_SELECTION_CHOICES = 30
 MAX_DISCOVERED_FILES = 20_000
 IMPORT_SUFFIXES = {".py", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".mts", ".cts"}
-VERSION = "0.1.2"
+VERSION = "0.1.4"
 MANIFESTS = (
     "package.json", "pyproject.toml", "requirements.txt", "Cargo.toml",
     "go.mod", "Gemfile", "composer.json", "pom.xml",
@@ -203,6 +203,103 @@ def task_words(task: str) -> set[str]:
     return {word.lower() for word in re.findall(r"[A-Za-z][A-Za-z0-9_-]{2,}", task)}
 
 
+_TASK_STOP_WORDS = {
+    "about", "after", "also", "and", "are", "does", "from", "give", "help",
+    "how", "into", "its", "make", "show", "that", "the", "this", "what", "with",
+}
+
+
+def read_task_excerpt(
+    root: Path, relative: str, task: str, limit: int = 1050,
+    max_bytes: int = 96_000,
+) -> str | None:
+    """Find compact, task-related source windows, including later definitions.
+
+    File ranking alone is not enough: returning only the first lines of a large
+    file can omit the function that made it relevant. Reads remain bounded and
+    pass through the same path and secret safeguards as ordinary excerpts.
+    """
+    path = safe_path(root, relative)
+    if path is None:
+        return None
+    try:
+        with path.open("rb") as source:
+            raw = source.read(max_bytes + 1)
+    except OSError:
+        return None
+    if b"\0" in raw[:4096]:
+        return None
+
+    truncated = len(raw) > max_bytes
+    text = raw[:max_bytes].decode("utf-8", errors="replace")
+    all_lines = text.splitlines()
+    if not all_lines:
+        return None
+    lines = [line[:500] for line in all_lines[:1500]]
+    truncated = truncated or len(all_lines) > len(lines) or any(len(line) > 500 for line in all_lines[:1500])
+    terms = {term for term in task_words(task) if term not in _TASK_STOP_WORDS}
+    # Split snake_case and hyphenated identifiers so "demo" can match
+    # generate_demo_brief without requiring an exact function-name query.
+    tokenized_lines = [
+        {part.lower() for part in re.findall(r"[A-Za-z][A-Za-z0-9]*", line)}
+        for line in lines
+    ]
+    frequencies = {
+        term: sum(term in line_terms for line_terms in tokenized_lines)
+        for term in terms
+    }
+    scores: list[float] = []
+    for line_terms in tokenized_lines:
+        scores.append(sum(
+            1 + math.log((len(lines) + 1) / (frequencies[term] + 1))
+            for term in terms if term in line_terms
+        ))
+    for index, line in enumerate(lines):
+        if scores[index] and re.match(r"\s*(?:async\s+)?(?:def|class)\s+", line):
+            # In source files, a matching function/class declaration is a
+            # stronger anchor than a help string that merely mentions the task.
+            scores[index] += 8
+
+    if not any(scores):
+        return compact(redact("\n".join(lines)), limit)
+
+    # Make short windows around the strongest matching lines. Merge overlaps,
+    # then take the best windows until the excerpt budget is used.
+    candidates = sorted(range(len(lines)), key=lambda index: (-scores[index], index))
+    windows: list[tuple[int, int]] = []
+    for index in candidates:
+        if scores[index] == 0:
+            break
+        start, end = max(0, index - 4), min(len(lines), index + 11)
+        if any(start <= old_end and end >= old_start for old_start, old_end in windows):
+            continue
+        windows.append((start, end))
+    selected: list[tuple[int, int, str]] = []
+    used = 0
+    for start, end in windows:
+        body = "\n".join(lines[start:end]).strip()
+        snippet = f"Lines {start + 1}–{end}:\n{body}"
+        if not body:
+            continue
+        remaining = limit - used
+        if remaining <= 0:
+            break
+        if len(snippet) > remaining:
+            break
+        selected.append((start, end, snippet))
+        used += len(snippet) + 2
+    if not selected:
+        return compact("\n".join(lines), limit)
+
+    selected.sort(key=lambda item: item[0])
+    result = "\n…\n".join(snippet for _start, _end, snippet in selected)
+    if truncated:
+        result += "\nMore of this file was left out to keep the brief short."
+    elif len(selected) < len(windows):
+        result += "\nOther matching sections were left out to keep the brief short."
+    return redact(result)
+
+
 def discover_files(root: Path) -> list[str]:
     found: list[str] = []
     visited_dirs = 0
@@ -816,12 +913,14 @@ def gather(
             if label and label != "additional project file":
                 key.append(f"{relative} is already included above; it was also {label}.")
             continue
-        excerpt = read_excerpt(root, relative)
+        excerpt = read_task_excerpt(root, relative, task)
+        if excerpt is None:
+            fallback = read_excerpt(root, relative)
+            excerpt = fallback[0] if fallback else None
         if excerpt:
-            content, truncated = excerpt
-            content = compact(content, 1050)
+            content = compact(excerpt, 1050)
             label = reasons.get(relative, "selected by project signals")
-            shortened_note = "" if "Some lines were left out" in content else ("\nMore of this file was left out to keep the brief short." if truncated else "")
+            shortened_note = "" if "Some lines were left out" in content or "More of this file was left out" in content else ""
             key.append(f"{relative} — {label}\n{excerpt_for_brief(relative, content)}" + shortened_note)
     if not key:
         if selected_files is not None and not key_files:

{codebase_brief-0.1.2 → codebase_brief-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codebase-brief"
-version = "0.1.2"
+version = "0.1.4"
 description = "Local-first CLI that builds task-focused context briefs from code repositories"
 readme = "README.md"
 license = "MIT"
@@ -27,7 +27,7 @@ classifiers = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/mohamed1111111m/codebase-brief"
+Homepage = "https://mohamed1111111m.github.io/codebase-brief/"
 Repository = "https://github.com/mohamed1111111m/codebase-brief"
 Issues = "https://github.com/mohamed1111111m/codebase-brief/issues"
 

{codebase_brief-0.1.2 → codebase_brief-0.1.4}/tests/test_cli.py

@@ -6,7 +6,7 @@ import unittest
 from pathlib import Path
 from unittest.mock import patch
 
-from context_inject.cli import DEFAULT_BUDGET_TOKENS, MAX_CHARS, MAX_FILE_BYTES, MAX_KEY_FILES, choose_files, compact, copy_to_clipboard, gather, interactive, local_imports, main, read_excerpt, redact, review_feedback, safe_path, suggest_file_details, suggest_files
+from context_inject.cli import DEFAULT_BUDGET_TOKENS, MAX_CHARS, MAX_FILE_BYTES, MAX_KEY_FILES, VERSION, choose_files, compact, copy_to_clipboard, gather, interactive, local_imports, main, read_excerpt, read_task_excerpt, redact, review_feedback, safe_path, suggest_file_details, suggest_files
 
 
 class ContextInjectTests(unittest.TestCase):
@@ -75,6 +75,21 @@ class ContextInjectTests(unittest.TestCase):
         self.assertLess(output.index("Files that may help"), output.index("Technology and commands"))
         self.assertLessEqual(len(output), 1000 * 4)
 
+    def test_task_excerpt_finds_relevant_function_beyond_file_prefix(self):
+        filler = "\n".join(f"def unrelated_{index}(): return {index}" for index in range(180))
+        source = filler + "\n\ndef build_demo_brief():\n    return gather(sample_files, task)\n"
+        self.put("src/app.py", source)
+
+        excerpt = read_task_excerpt(
+            self.root, "src/app.py",
+            "Explain how the built-in demo creates a sample context brief",
+        )
+
+        self.assertIsNotNone(excerpt)
+        self.assertIn("def build_demo_brief", excerpt)
+        self.assertIn("return gather(sample_files, task)", excerpt)
+        self.assertNotIn("def unrelated_0", excerpt)
+
     def test_excerpt_shortening_stops_on_a_word_boundary(self):
         excerpt = compact("This is a long sentence that should end on a complete word. " * 3, 90)
         self.assertTrue(excerpt.startswith("This is a long sentence that should\nSome lines were left out"))
@@ -486,7 +501,7 @@ class ContextInjectTests(unittest.TestCase):
         plain = __import__("re").sub(r"\x1b\[[0-9;]*m", "", output.getvalue())
         self.assertIn("CODEBASE", plain)
         self.assertIn("BRIEF", plain)
-        self.assertIn("v0.1.2", plain)
+        self.assertIn(f"v{VERSION}", plain)
         self.assertIn("Meet Briefy - your repo guide", plain)
         self.assertIn("WHAT THIS DOES", plain)
         self.assertIn("Makes a short guide to your project for an AI coding assistant", plain)