flash-context 0.2.0__tar.gz → 0.3.0__tar.gz

flash_context-0.3.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+User-visible changes and migration instructions for each release.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-11-01
+
+### Fixed
+
+- Resolve bare file-path queries locally with bounded previews and find unique
+  Python definitions even when many references precede them.
+- Keep literal and scoped searches from scanning unrelated directory trees while
+  preserving safety checks and existing resource limits.
+- Surface scan failures from the initial file sample and CLI result warnings.
+- Describe the MCP exploration tool during discovery and use tool-specific
+  trajectory counters instead of misleading empty read-content counts.
+
+### Migration
+
+- Citation objects no longer include the unused `reason` field. Consumers should
+  read `path`, `start_line`, and `end_line` without expecting `reason: null`.
+- The CLI now exits 6 for empty results after scan-budget exhaustion or a tool
+  processing timeout, retaining text/JSON on stdout and warnings on stderr.
+  Partial cited results and complete empty searches still exit 0.
+- Trajectory tool entries now include only their relevant counter:
+  `content_length` (read), `hit_count` (grep), or `match_count` (glob).
+
+### Changed
+
+- Prompt the explorer to prefer implementation source for coding questions and
+  the smallest supporting citation ranges. Validation checks safe line coverage;
+  precision and relevance remain model-dependent.
+- Publish GitHub releases automatically after PyPI installation verification,
+  using this changelog and the same distribution artifacts uploaded to PyPI.
+- Refresh package-index metadata during release installation retries.
+
+## [0.2.0] - 2026-11-01
+
+### Changed
+
+- Enforce deny/ignore rules on requested and resolved paths, including environment
+  files, private-key names, and runtime histories. Prune denied directories.
+- Bound scan bytes, directory entries, processing time, regex execution, tool
+  batches, and model observations; report incomplete coverage explicitly.
+- Improve exact-lookup routing, read ranges, truncation metadata, and structured
+  endpoint/filesystem failures across CLI and MCP.
+- Keep optional trajectory logs metadata-only and outside the inspected root.
+
+### Migration
+
+- Move any trajectory directory inside the inspected repository outside it, or
+  disable logging with `FLASH_CONTEXT_TRAJ_DIR=`. Empty/null settings disable
+  inherited logging. Existing logs remain untouched.
+
+## [0.1.0] - 2026-11-01
+
+### Added
+
+- Initial Python CLI and optional MCP adapter sharing a read-only explorer core.
+- OpenAI-compatible tool-call loop with bounded Read/Glob/Grep repository tools,
+  root-scoped path validation, validated citations, and raw source snippets.
+- Exact path/symbol lookup shortcuts, concurrent local tools, and configurable
+  endpoint settings and limits.
+- Wheel/source packaging and tag-driven TestPyPI/PyPI publication and smoke checks.

{flash_context-0.2.0 → flash_context-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flash-context
-Version: 0.2.0
+Version: 0.3.0
 Summary: Read-only context exploration and retrieval for AI agents, starting with codebases and repositories.
 Project-URL: Repository, https://github.com/zyf0717/flash-context
 Project-URL: Issues, https://github.com/zyf0717/flash-context/issues
@@ -39,10 +39,14 @@ Codebases and repositories are the current focus; the same tools explore
 documentation, configuration, and other local text files. CLI and MCP share one
 exploration core with read-only tools, path safety, and resource limits.
 Scans and regex execution are bounded; partial results report truncation.
+Citation validation checks safe paths and existing line coverage, not semantic
+relevance or minimal ranges. Citation precision depends on the explorer model.
 Optional metadata-only trajectory logs must stay outside the inspected repository.
 
 Inspired by [FastContext](https://arxiv.org/abs/2606.14066), a now-withdrawn paper
-on delegating repository exploration to a dedicated model.
+on separating repository exploration from task solving, using specialized models
+to return focused file-line evidence while reducing the coding agent's context
+and token overhead.
 
 ## Quickstart
 
@@ -73,6 +77,14 @@ lookups can resolve locally without an endpoint. See the
 [CLI contract](specs/001-flash-context-explorer/contracts/cli.md) for options,
 output schemas, and exit codes.
 
+For example, `--query 'httpx/_client.py'` returns a bounded file preview, while
+`--query 'BaseTransport'` returns its definition if unique within a complete
+Python source/stub scan. Local successes report `turns_used: 0` in JSON.
+
+Warnings go to stderr in both output formats. An empty result after scan-budget
+exhaustion exits **6** while preserving stdout; a complete empty search exits
+**0**. For large repositories, see [scan-budget tuning](docs/configuration.md#large-repositories).
+
 ## MCP
 
 ```bash
@@ -87,6 +99,7 @@ See [MCP integration](docs/mcp.md) for editor configuration and source launches.
 - [Configuration](docs/configuration.md): endpoint settings, precedence, and limits.
 - [Architecture and scope](docs/architecture.md): design, status, specs, and references.
 - [Contributing](CONTRIBUTING.md): development setup, tests, and pull requests.
+- [Changelog](CHANGELOG.md): release history and migration instructions.
 - [Releasing](docs/releasing.md): package checks and tag-driven TestPyPI/PyPI publishing.
 
 ## License

{flash_context-0.2.0 → flash_context-0.3.0}/README.md

@@ -16,10 +16,14 @@ Codebases and repositories are the current focus; the same tools explore
 documentation, configuration, and other local text files. CLI and MCP share one
 exploration core with read-only tools, path safety, and resource limits.
 Scans and regex execution are bounded; partial results report truncation.
+Citation validation checks safe paths and existing line coverage, not semantic
+relevance or minimal ranges. Citation precision depends on the explorer model.
 Optional metadata-only trajectory logs must stay outside the inspected repository.
 
 Inspired by [FastContext](https://arxiv.org/abs/2606.14066), a now-withdrawn paper
-on delegating repository exploration to a dedicated model.
+on separating repository exploration from task solving, using specialized models
+to return focused file-line evidence while reducing the coding agent's context
+and token overhead.
 
 ## Quickstart
 
@@ -50,6 +54,14 @@ lookups can resolve locally without an endpoint. See the
 [CLI contract](specs/001-flash-context-explorer/contracts/cli.md) for options,
 output schemas, and exit codes.
 
+For example, `--query 'httpx/_client.py'` returns a bounded file preview, while
+`--query 'BaseTransport'` returns its definition if unique within a complete
+Python source/stub scan. Local successes report `turns_used: 0` in JSON.
+
+Warnings go to stderr in both output formats. An empty result after scan-budget
+exhaustion exits **6** while preserving stdout; a complete empty search exits
+**0**. For large repositories, see [scan-budget tuning](docs/configuration.md#large-repositories).
+
 ## MCP
 
 ```bash
@@ -64,6 +76,7 @@ See [MCP integration](docs/mcp.md) for editor configuration and source launches.
 - [Configuration](docs/configuration.md): endpoint settings, precedence, and limits.
 - [Architecture and scope](docs/architecture.md): design, status, specs, and references.
 - [Contributing](CONTRIBUTING.md): development setup, tests, and pull requests.
+- [Changelog](CHANGELOG.md): release history and migration instructions.
 - [Releasing](docs/releasing.md): package checks and tag-driven TestPyPI/PyPI publishing.
 
 ## License

{flash_context-0.2.0 → flash_context-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flash-context"
-version = "0.2.0"
+version = "0.3.0"
 description = "Read-only context exploration and retrieval for AI agents, starting with codebases and repositories."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -52,6 +52,7 @@ include = [
   "/src/flash_context",
   "/pyproject.toml",
   "/README.md",
+  "/CHANGELOG.md",
   "/LICENSE",
   "/config.yaml.example",
   "/.env.example",
@@ -74,5 +75,5 @@ select = ["E", "F", "I", "UP", "B", "SIM"]
 [tool.mypy]
 python_version = "3.13"
 strict = true
-files = ["src/flash_context", "tests/unit", "tests/contract"]
+files = ["src/flash_context", "tests/unit", "tests/contract", "scripts"]
 exclude = ["tests/fixtures"]

{flash_context-0.2.0 → flash_context-0.3.0}/src/flash_context/agent.py

@@ -99,8 +99,9 @@ def explore(
     )
     messages = _initial_messages(request, file_sample, settings)
     tools = tool_schemas()
-    truncated = False
-    warnings: list[str] = []
+    # A capped file sample is expected; actual scan failures must reach callers.
+    warnings = list(file_sample.warnings)
+    truncated = bool(warnings)
     last_content = ""
     evidence = EvidenceState()
 
@@ -436,6 +437,7 @@ def _finalize_result(
             truncated
             or any(x.truncated for x in raw_locations)
             or "citation verification limit reached" in warnings
+            or "read scan budget exhausted" in warnings
         ),
         warnings=warnings,
     )
@@ -448,33 +450,30 @@ def _citation_text(citations: list[Citation]) -> str:
 
 
 def _merge_adjacent_citations(citations: list[Citation]) -> list[Citation]:
-    grouped: dict[str, list[tuple[int, Citation]]] = {}
+    grouped: dict[str, list[Citation]] = {}
     path_order: list[str] = []
     non_mergeable: list[Citation] = []
-    for index, citation in enumerate(citations):
+    for citation in citations:
         if citation.start_line is None or citation.end_line is None:
             non_mergeable.append(citation)
             continue
         if citation.path not in grouped:
             grouped[citation.path] = []
             path_order.append(citation.path)
-        grouped[citation.path].append((index, citation))
+        grouped[citation.path].append(citation)
 
     merged: list[Citation] = []
     for path in path_order:
         ranges = sorted(
             grouped[path],
             key=lambda item: (
-                item[1].start_line or 0,
-                item[1].end_line or 0,
+                item.start_line or 0,
+                item.end_line or 0,
             ),
         )
         current_start: int | None = None
         current_end: int | None = None
-        current_reason: str | None = None
-        current_reason_index: int | None = None
-
-        for index, citation in ranges:
+        for citation in ranges:
             start = citation.start_line
             end = citation.end_line
             if start is None or end is None:
@@ -482,27 +481,18 @@ def _merge_adjacent_citations(citations: list[Citation]) -> list[Citation]:
             if current_start is None or current_end is None:
                 current_start = start
                 current_end = end
-                current_reason = citation.reason
-                current_reason_index = index if citation.reason else None
                 continue
 
             if start <= current_end + 1:
                 current_end = max(current_end, end)
-                if citation.reason and (
-                    current_reason_index is None or index < current_reason_index
-                ):
-                    current_reason = citation.reason
-                    current_reason_index = index
                 continue
 
-            merged.append(Citation(path, current_start, current_end, current_reason))
+            merged.append(Citation(path, current_start, current_end))
             current_start = start
             current_end = end
-            current_reason = citation.reason
-            current_reason_index = index if citation.reason else None
 
         if current_start is not None and current_end is not None:
-            merged.append(Citation(path, current_start, current_end, current_reason))
+            merged.append(Citation(path, current_start, current_end))
 
     merged.extend(non_mergeable)
     return merged
@@ -562,6 +552,33 @@ def _try_exact_fast_path(
     repo_root: Path,
     settings: Settings,
 ) -> ExploreResult | None:
+    bare_path = request.query.strip()
+    if len(bare_path) >= 2 and bare_path[0] in "`'\"" and bare_path[-1] == bare_path[0]:
+        bare_path = bare_path[1:-1]
+    if re.fullmatch(r"(?:[A-Za-z0-9_.-]+/)*[A-Za-z0-9_.-]+", bare_path):
+        try:
+            observation = read_file(
+                repo_root=repo_root,
+                path=bare_path,
+                end_line=settings.max_read_lines,
+                max_bytes=settings.max_read_bytes,
+                preview=True,
+                ignore=settings.ignore,
+                limits=settings.limits,
+            )
+        except ExplorerError:
+            pass  # Missing, empty, or unsafe paths retain normal model routing.
+        else:
+            return _finalize_result(
+                request=request,
+                repo_root=repo_root,
+                settings=settings,
+                answer="",
+                citations=_citations_from_reads([observation]),
+                turns_used=0,
+                truncated=observation.truncated,
+                warnings=list(observation.warnings),
+            )
     if not _is_exact_lookup(request.query):
         return None
     evidence = EvidenceState()
@@ -748,7 +765,6 @@ def _exact_matches_in_file(
         grep_result,
         target=target,
         allow_assignment=allow_assignment,
-        definitions_only=False,
     )
     return citations if 0 < len(citations) <= MAX_FINAL_CITATIONS else []
 
@@ -759,32 +775,28 @@ def _unique_definition_citation(
     settings: Settings,
     symbol: str,
 ) -> Citation | None:
-    grep_result = _grep_exact_target(
+    definition_pattern = rf"^\s*(?:async\s+def|def|class)\s+{re.escape(symbol)}\b"
+    grep_result = repo_grep(
         repo_root=repo_root,
-        settings=settings,
-        target=symbol,
+        pattern=definition_pattern,
         glob="**/*.py",
+        max_results=2,
+        ignore=settings.ignore,
+        limits=settings.limits,
     )
-    pyi_result = _grep_exact_target(
+    pyi_result = repo_grep(
         repo_root=repo_root,
-        settings=settings,
-        target=symbol,
+        pattern=definition_pattern,
         glob="**/*.pyi",
+        max_results=2,
+        ignore=settings.ignore,
+        limits=settings.limits,
     )
-    citations = _citations_for_target_hits(
-        grep_result,
-        target=symbol,
-        allow_assignment=False,
-        definitions_only=True,
-    )
-    citations.extend(
-        _citations_for_target_hits(
-            pyi_result,
-            target=symbol,
-            allow_assignment=False,
-            definitions_only=True,
-        )
-    )
+    citations = [
+        Citation(hit.path, hit.line, hit.line)
+        for result in (grep_result, pyi_result)
+        for hit in result.hits
+    ]
     if grep_result.truncated or pyi_result.truncated or len(citations) > 1:
         return None
     return citations[0] if len(citations) == 1 else None
@@ -812,7 +824,6 @@ def _citations_for_target_hits(
     *,
     target: str,
     allow_assignment: bool,
-    definitions_only: bool,
 ) -> list[Citation]:
     citations: list[Citation] = []
     for hit in observation.hits:
@@ -820,7 +831,6 @@ def _citations_for_target_hits(
             hit.text,
             target=target,
             allow_assignment=allow_assignment,
-            definitions_only=definitions_only,
         ):
             citations.append(Citation(hit.path, hit.line, hit.line))
     return citations
@@ -831,14 +841,11 @@ def _line_matches_target(
     *,
     target: str,
     allow_assignment: bool,
-    definitions_only: bool,
 ) -> bool:
     escaped = re.escape(target)
     definition_pattern = rf"^\s*(?:async\s+def|def|class)\s+{escaped}\b"
     if re.search(definition_pattern, line):
         return True
-    if definitions_only:
-        return False
     if allow_assignment and re.search(rf"^\s*{escaped}\s*(?::|=)", line):
         return True
     return bool(re.search(rf"\b{escaped}\b", line))
@@ -862,6 +869,7 @@ def _validated_citations_from_content(
         repo_root=repo_root,
         settings=settings,
         evidence=evidence,
+        warnings=warnings,
     )
     if not validated:
         _append_warning_once(warnings, "invalid citation rejected")
@@ -874,6 +882,7 @@ def _validate_citations(
     repo_root: Path,
     settings: Settings,
     evidence: EvidenceState,
+    warnings: list[str],
 ) -> list[Citation]:
     validated: list[Citation] = []
     for citation in citations[:16]:
@@ -888,6 +897,7 @@ def _validate_citations(
             repo_root=repo_root,
             settings=settings,
             evidence=evidence,
+            warnings=warnings,
         )
         if verified is not None:
             validated.append(verified)
@@ -909,7 +919,6 @@ def _normalize_citation(citation: Citation) -> Citation | None:
         path=citation.path,
         start_line=citation.start_line,
         end_line=citation.end_line,
-        reason=citation.reason,
     )
 
 
@@ -961,6 +970,7 @@ def _verify_citation_by_read(
     repo_root: Path,
     settings: Settings,
     evidence: EvidenceState,
+    warnings: list[str],
 ) -> Citation | None:
     if citation.start_line is None or citation.end_line is None:
         return None
@@ -974,13 +984,16 @@ def _verify_citation_by_read(
             ignore=settings.ignore,
             limits=settings.limits,
         )
-    except ExplorerError:
+    except ExplorerError as exc:
+        if exc.code == "TOOL_LIMIT_EXCEEDED":
+            _append_warning_once(warnings, "read scan budget exhausted")
         return None
+    for warning in observation.warnings:
+        _append_warning_once(warnings, warning)
     verified = Citation(
         path=observation.path or citation.path,
         start_line=citation.start_line,
         end_line=citation.end_line,
-        reason=citation.reason,
     )
     if verified.path != citation.path:
         return None
@@ -1232,6 +1245,11 @@ def _initial_messages(
                 "tool calls in the same turn. "
                 "For exact symbol, function, or class names, use repo_grep "
                 "before reading broad file ranges. "
+                "For implementation questions, prefer implementation source over "
+                "documentation or Markdown; use documentation when requested or "
+                "needed to support the answer. Cite the smallest line ranges "
+                "that support the answer, rather than whole files or classes "
+                "when a smaller function or region suffices. "
                 f"Use read_file line ranges of at most {settings.max_read_lines} "
                 "lines unless no narrower range is known. "
                 f"{output_contract}"
@@ -1464,7 +1482,11 @@ def _execute_tool_call(
                 limits=settings.limits,
             )
     except ExplorerError as exc:
-        return ToolObservation.from_error(exc, tool_call_id=tool_call.id)
+        observation = ToolObservation.from_error(exc, tool_call_id=tool_call.id)
+        if exc.code == "TOOL_LIMIT_EXCEEDED":
+            observation.truncated = True
+            observation.warnings.append("read scan budget exhausted")
+        return observation
     raise AssertionError(f"unhandled tool: {tool_call.name}")
 
 

{flash_context-0.2.0 → flash_context-0.3.0}/src/flash_context/cli.py

@@ -11,6 +11,15 @@ from flash_context.config import SettingsOverrides, load_settings
 from flash_context.mcp_server import run_mcp
 from flash_context.types import ExploreRequest, ExplorerError
 
+_SCAN_LIMIT_WARNINGS = frozenset(
+    {
+        "glob scan budget exhausted",
+        "grep scan budget exhausted",
+        "read scan budget exhausted",
+        "grep match timed out",
+    }
+)
+
 
 def main(argv: Sequence[str] | None = None) -> int:
     parser = _build_parser()
@@ -60,6 +69,12 @@ def _run_explore(args: argparse.Namespace) -> int:
         print(json.dumps(result.to_dict(), indent=2, sort_keys=True))
     else:
         print(format_text_result(result, citation=args.citation))
+    for warning in result.warnings:
+        print(f"WARNING: {warning}", file=sys.stderr)
+    if result.truncated and not result.warnings:
+        print("WARNING: Result truncated", file=sys.stderr)
+    if not result.citations and _SCAN_LIMIT_WARNINGS.intersection(result.warnings):
+        return 6
     return 0
 
 

{flash_context-0.2.0 → flash_context-0.3.0}/src/flash_context/logging.py

@@ -50,16 +50,19 @@ class TrajectoryRecorder:
         self, turn: int, tool_name: str, observation: ToolObservation
     ) -> None:
         if self._traj_dir is not None:
-            self._turns.append(
-                {
-                    "turn": turn,
-                    "tool": tool_name,
-                    "ok": observation.ok,
-                    "truncated": observation.truncated,
-                    "hit_count": len(observation.hits),
-                    "content_length": len(observation.content or ""),
-                }
-            )
+            metadata: dict[str, object] = {
+                "turn": turn,
+                "tool": tool_name,
+                "ok": observation.ok,
+                "truncated": observation.truncated,
+            }
+            if tool_name == "read_file":
+                metadata["content_length"] = len(observation.content or "")
+            elif tool_name == "repo_grep":
+                metadata["hit_count"] = len(observation.hits)
+            elif tool_name == "repo_glob":
+                metadata["match_count"] = len(observation.matches)
+            self._turns.append(metadata)
 
     def finish(
         self, *, result: ExploreResult | None = None, error: ExplorerError | None = None

{flash_context-0.2.0 → flash_context-0.3.0}/src/flash_context/mcp_server.py

@@ -60,6 +60,13 @@ def create_server() -> Any:
         max_turns: int | None = None,
         citation: bool | None = None,
     ) -> dict[str, object]:
+        """Find code or local text relevant to a focused repository question.
+
+        Explore read-only when implementation locations or supporting evidence
+        are unknown. Return validated file-line citations and bounded source
+        snippets, with warnings for incomplete exploration. repo_root defaults
+        to the server's working directory.
+        """
         return explore_repository_handler(
             query=query,
             repo_root=repo_root,

{flash_context-0.2.0 → flash_context-0.3.0}/src/flash_context/tools/safety.py

@@ -173,7 +173,31 @@ class PathSafety:
             except OSError:
                 budget.warnings.append("search skipped an unreadable directory")
 
-        yield from walk(self.repo_root)
+        directory = self.repo_root
+        parts = Path(pattern).parts
+        try:
+            for index, part in enumerate(parts):
+                if any(char in part for char in "*?["):
+                    break
+                candidate = directory / part
+                budget.consume(entries=1)
+                self.ensure_allowed(candidate)
+                if index == len(parts) - 1:
+                    if candidate.exists() and not candidate.is_dir():
+                        yield self.resolve_existing_file(candidate)
+                    return
+                # Match the walker's policy: never traverse directory symlinks.
+                if candidate.is_symlink() or not candidate.is_dir():
+                    return
+                directory = candidate
+            yield from walk(directory)
+        except ExplorerError as exc:
+            if exc.code == "TOOL_LIMIT_EXCEEDED":
+                raise
+            if exc.code not in {"PATH_DENIED", "PATH_OUTSIDE_ROOT"}:
+                budget.warnings.append("search skipped an unreadable entry")
+        except OSError:
+            budget.warnings.append("search skipped an unreadable directory")
 
 
 def _matches_patterns(rel_path: str, patterns: tuple[str, ...]) -> bool:

{flash_context-0.2.0 → flash_context-0.3.0}/src/flash_context/types.py

@@ -49,14 +49,12 @@ class Citation:
     path: str
     start_line: int | None = None
     end_line: int | None = None
-    reason: str | None = None
 
     def to_dict(self) -> dict[str, object]:
         return {
             "path": self.path,
             "start_line": self.start_line,
             "end_line": self.end_line,
-            "reason": self.reason,
         }
 
     def label(self) -> str: