squackit 0.8.3__tar.gz → 0.8.4__tar.gz

{squackit-0.8.3 → squackit-0.8.4}/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.8.4
+
+A review of 0.8.1–0.8.3 found both fixes had reached the macro-tool layer and
+stopped there. The compound tools have their own parameters and never pass
+through `apply_defaults`, so each gap was reachable through a different door.
+
+### Fixed — the compound tools did not anchor explicit patterns
+
+0.8.1 anchored caller-supplied relative patterns, but only in the macro-tool
+wrapper. `investigate`, `review` and `search` take `file_pattern` themselves and
+handed it to the macro unchanged, so a relative glob still resolved against the
+process working directory. On a server whose cwd is not the corpus — the exact
+deployment 0.8.1 was written for — this reproduced the original failure:
+
+    investigate(name="parse_config", file_pattern="src/**/*.py")
+    -> IOException: Failed to initialize file processing ... Permission
+
+Verified against the published 0.8.3 before fixing. The 0.8.1 note that
+"caller-supplied relative patterns are anchored too" was true of the macro path
+only; it is now true of both. Absolute patterns are still passed through
+untouched, and an explicit pattern still works without a defaults object.
+
+### Fixed — briefing sections named no cause
+
+`_section` wraps every part of `explore`, `review` and `search`, and
+`investigate`'s Source/Called-by/Calls. It caught everything, logged at DEBUG —
+invisible at normal levels — and rendered a bare `(could not load)`. A
+permission error, a missing git revision and an unloaded macro were
+indistinguishable from each other and from a section that legitimately had
+nothing.
+
+That is the same defect 0.8.3 fixed in `investigate`'s primary lookup and did
+not carry to the siblings. Sections now report the exception type and message,
+capped at 200 characters with the truncation marked, and log at WARNING. One
+failing section still cannot take down a briefing.
+
+
 ## 0.8.3
 
 Three fixes with one theme: a failure must not be representable as an ordinary

{squackit-0.8.3 → squackit-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: squackit
-Version: 0.8.3
+Version: 0.8.4
 Summary: Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents.
 Project-URL: Homepage, https://github.com/teaguesterling/squackit
 Project-URL: Documentation, https://squackit.readthedocs.io

{squackit-0.8.3 → squackit-0.8.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "squackit"
-version = "0.8.3"
+version = "0.8.4"
 description = "Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents."
 readme = "README.md"
 license = "Apache-2.0"

{squackit-0.8.3 → squackit-0.8.4}/squackit/workflows.py

@@ -32,20 +32,41 @@ def _format_briefing(title: str, sections: list[tuple[str, str]]) -> str:
     return "\n".join(parts)
 
 
+#: How much of a failing section's error text reaches the briefing. DuckDB
+#: errors run to hundreds of characters and a briefing is prose, but a cause
+#: the reader cannot see is the thing this whole clause exists to avoid.
+_SECTION_ERROR_CHARS = 200
+
+
 def _section(heading: str, fn):
     """Run fn() with error handling, return (heading, content) tuple.
 
-    Returns "(no data)" for empty/None results,
-    "(could not load)" on exceptions.
+    Returns "(no data)" for empty/None results, and "(could not load — <type>:
+    <message>)" on exceptions.
+
+    THE CAUSE IS IN THE TEXT ON PURPOSE. This wrapper covers every section of
+    explore/review/search and investigate's Source/Called-by/Calls. It used to
+    return a bare "(could not load)" and log at DEBUG, which is invisible at
+    normal levels — so a permission error, a missing git revision and a macro
+    that simply is not loaded all rendered identically, and none of them said
+    why. That is the same "a failure must not be representable as an ordinary
+    result" defect fixed in investigate's primary lookup in 0.8.3; it was not
+    extended to the sibling sections until 0.8.4.
+
+    Still non-fatal: one broken section must not take down the briefing, which
+    is why the guard stays.
     """
     try:
         content = fn()
         if not content:
             return (heading, "(no data)")
         return (heading, content)
-    except Exception:
-        log.debug("section %s failed", heading, exc_info=True)
-        return (heading, "(could not load)")
+    except Exception as exc:
+        log.warning("section %r failed: %s", heading, exc, exc_info=True)
+        detail = str(exc).strip().replace("\n", " ")
+        if len(detail) > _SECTION_ERROR_CHARS:
+            detail = detail[:_SECTION_ERROR_CHARS] + "…"
+        return (heading, f"(could not load — {type(exc).__name__}: {detail})")
 
 
 def _has_module(con, module_name: str) -> bool:
@@ -92,6 +113,31 @@ def _sorted_table(con, macro_name, kwargs, sort_col, max_rows, descending=True):
 # ── Compound tools ─────────────────────────────────────────────────
 
 
+def _anchored(defaults, file_pattern):
+    """Root a caller-supplied file pattern, the way apply_defaults does.
+
+    The compound tools take `file_pattern` as their own parameter and never
+    pass through `apply_defaults`, so 0.8.1's anchoring of explicit relative
+    patterns reached the macro tools only. A relative glob handed to
+    `investigate`/`review`/`search` still resolved against the process cwd and,
+    under fledgling's sandbox, failed outright — the same deployment shape
+    0.8.1 was written for, reached through a different door.
+
+    `anchor()` passes absolute patterns through untouched, so a caller who
+    named a path in full still gets it.
+
+    Tolerates ``defaults=None``. An explicit ``file_pattern`` previously needed
+    no defaults object at all — the caller had already said where to look — and
+    callers rely on that: several tests drive ``investigate`` with a fake
+    connection and no defaults to isolate the name-matching logic. There is
+    also nothing to anchor *against* without a root, which is the same reason
+    ``anchor()`` itself passes patterns through when ``root`` is None.
+    """
+    if file_pattern is None or defaults is None:
+        return file_pattern
+    return defaults.anchor(file_pattern)
+
+
 def explore(con, defaults, path=None):
     """First-contact codebase briefing."""
     # Scope patterns to path if provided
@@ -144,6 +190,7 @@ def investigate(con, defaults, name, file_pattern=None, path=None):
         path: Project root to scope the search to. Defaults to process cwd.
             Only consulted when file_pattern is None.
     """
+    file_pattern = _anchored(defaults, file_pattern)
     if file_pattern is None:
         from squackit.runtime import resolve_scope_path
         # Precedence: explicit path -> runtime.active_root -> process cwd.
@@ -288,7 +335,7 @@ def review(con, defaults, from_rev=None, to_rev=None, file_pattern=None):
     """Code review prep for a revision range."""
     from_rev = from_rev or defaults.from_rev
     to_rev = to_rev or defaults.to_rev
-    file_pattern = file_pattern or defaults.code_glob
+    file_pattern = _anchored(defaults, file_pattern) or defaults.code_glob
 
     sections = []
 
@@ -368,7 +415,7 @@ def review(con, defaults, from_rev=None, to_rev=None, file_pattern=None):
 
 def search(con, defaults, query, file_pattern=None):
     """Multi-source search across code, docs, and git."""
-    file_pattern = file_pattern or defaults.code_glob
+    file_pattern = _anchored(defaults, file_pattern) or defaults.code_glob
 
     sections = []
 

{squackit-0.8.3 → squackit-0.8.4}/tests/test_error_visibility.py

@@ -196,3 +196,58 @@ class TestMutationNamedMacrosSayTheyDoNotMutate:
         d = ToolPresentation(info=_Info("ast_replace", ["source"]),
                              description_override="Overridden.")
         assert d.description == "Overridden."
+
+
+# ── Briefing sections name their failure (#2 from the 0.8.3 review) ──
+
+
+class TestSectionFailuresAreNamed:
+    """`_section` wraps every part of explore/review/search/investigate.
+
+    It caught everything, logged at DEBUG (invisible at normal levels) and
+    rendered "(could not load)" — a string that cannot be told apart from a
+    section that legitimately has nothing, and which names no cause. 0.8.3
+    fixed exactly this shape in investigate's primary lookup but never reached
+    the sibling sections, so the same permission error that motivated 0.8.1
+    still arrived as undifferentiated text in three of the four compound tools.
+    """
+
+    def test_a_failing_section_still_reports_could_not_load(self):
+        """Keep the recognisable phrase — callers and tests match on it."""
+        from squackit.workflows import _section
+
+        heading, content = _section("Diffs", lambda: (_ for _ in ()).throw(
+            RuntimeError("boom")))
+        assert heading == "Diffs"
+        assert "could not load" in content.lower()
+
+    def test_a_failing_section_names_the_error(self):
+        from squackit.workflows import _section
+
+        _heading, content = _section("Diffs", lambda: (_ for _ in ()).throw(
+            RuntimeError("permission denied on **/*.py")))
+        assert "RuntimeError" in content, content
+        assert "permission denied" in content, content
+
+    def test_an_empty_section_is_distinguishable_from_a_failed_one(self):
+        from squackit.workflows import _section
+
+        _h, empty = _section("Docs", lambda: "")
+        _h2, failed = _section("Docs", lambda: (_ for _ in ()).throw(
+            RuntimeError("boom")))
+        assert empty != failed
+        assert "no data" in empty.lower()
+
+    def test_a_very_long_error_is_capped_visibly(self):
+        """DuckDB errors run to hundreds of characters; a briefing is prose."""
+        from squackit.workflows import _section
+
+        _h, content = _section("Diffs", lambda: (_ for _ in ()).throw(
+            RuntimeError("x" * 4000)))
+        assert len(content) < 400, len(content)
+        assert "…" in content or "..." in content, content
+
+    def test_a_working_section_is_untouched(self):
+        from squackit.workflows import _section
+
+        assert _section("Docs", lambda: "| a | b |") == ("Docs", "| a | b |")

{squackit-0.8.3 → squackit-0.8.4}/tests/test_sandbox_anchoring.py

@@ -156,6 +156,19 @@ def repo(tmp_path_factory):
     subprocess.run(["git", "add", "-A"], cwd=root, check=True)
     subprocess.run(["git", "-c", "user.email=t@e", "-c", "user.name=t",
                     "commit", "-qm", "initial"], cwd=root, check=True)
+    # A SECOND commit, so HEAD~1 resolves. `review` defaults to HEAD~1..HEAD,
+    # and on a one-commit repo its git sections fail for that reason alone —
+    # which renders as "(could not load)", exactly like the sandbox failure
+    # this file is about. Without this the review test passes or fails for the
+    # wrong reason.
+    (root / "src" / "mod.py").write_text(
+        "def parse_widget_config(path):\n"
+        "    '''Load the widget config.'''\n"
+        "    return {'version': 1}\n"
+    )
+    subprocess.run(["git", "add", "-A"], cwd=root, check=True)
+    subprocess.run(["git", "-c", "user.email=t@e", "-c", "user.name=t",
+                    "commit", "-qm", "second"], cwd=root, check=True)
     return root
 
 
@@ -221,3 +234,85 @@ class TestServedFromForeignCwd:
         mcp = create_server(root=str(repo), init=False)
         result = _run_async(mcp.call_tool("doc_outline", {}))
         assert "Widget Guide" in result.content[0].text or "guide.md" in result.content[0].text
+
+
+# ── Workflow tools anchor explicit patterns too (0.8.4) ─────────────
+
+
+@requires_fastmcp
+class TestWorkflowToolsAnchorExplicitPatterns:
+    """The compound tools never passed through `apply_defaults`.
+
+    0.8.1 anchored caller-supplied relative patterns — but only on the macro
+    tool wrapper in server.py. `investigate`, `review` and `search` take
+    `file_pattern` as their own parameter and handed it to the macro unchanged,
+    so an explicit relative glob still resolved against the process cwd and,
+    under fledgling's sandbox, failed outright:
+
+        investigate(name="parse_config", file_pattern="src/**/*.py")
+        -> IOException: Failed to initialize file processing ... Permission
+
+    Same deployment shape 0.8.1 was written for, reached through a different
+    door. The CHANGELOG claim "caller-supplied relative patterns are anchored
+    too" was true of the macro path only.
+    """
+
+    def _server(self, repo):
+        from squackit.server import create_server
+        return create_server(root=str(repo), init=False)
+
+    def test_investigate_with_an_explicit_relative_pattern(self, repo, outside_cwd):
+        mcp = self._server(repo)
+        text = _run_async(mcp.call_tool(
+            "investigate", {"name": "parse_widget_config",
+                            "file_pattern": "src/**/*.py"})).content[0].text
+        assert "Could not look up" not in text, (
+            f"explicit relative pattern was not anchored:\n{text[:300]}")
+        assert "parse_widget_config" in text
+
+    def test_search_with_an_explicit_relative_pattern(self, repo, outside_cwd):
+        mcp = self._server(repo)
+        text = _run_async(mcp.call_tool(
+            "search", {"query": "parse", "file_pattern": "src/**/*.py"})).content[0].text
+        assert "could not load" not in text.lower(), (
+            f"search section failed with an explicit relative pattern:\n{text[:400]}")
+
+    def test_review_with_an_explicit_relative_pattern(self, repo, outside_cwd):
+        mcp = self._server(repo)
+        text = _run_async(mcp.call_tool(
+            "review", {"file_pattern": "src/**/*.py"})).content[0].text
+        assert "could not load" not in text.lower(), (
+            f"review section failed with an explicit relative pattern:\n{text[:400]}")
+
+    def test_an_explicit_absolute_pattern_is_still_honoured(self, repo, outside_cwd):
+        """Anchoring must not re-root a path the caller gave in full."""
+        mcp = self._server(repo)
+        text = _run_async(mcp.call_tool(
+            "investigate", {"name": "parse_widget_config",
+                            "file_pattern": f"{repo}/src/**/*.py"})).content[0].text
+        assert "parse_widget_config" in text
+
+
+class TestAnchoringToleratesMissingDefaults:
+    """An explicit pattern needs no defaults object.
+
+    Regression: the 0.8.4 anchoring helper dereferenced `defaults` whenever a
+    pattern was supplied, which broke callers that pass `defaults=None` to
+    drive a workflow against a fake connection. The old code never touched
+    defaults on that path — the caller had already said where to look.
+    """
+
+    def test_explicit_pattern_survives_a_none_defaults(self):
+        from squackit.workflows import _anchored
+
+        assert _anchored(None, "src/**/*.py") == "src/**/*.py"
+
+    def test_none_pattern_with_none_defaults(self):
+        from squackit.workflows import _anchored
+
+        assert _anchored(None, None) is None
+
+    def test_a_rootless_defaults_leaves_the_pattern_alone(self):
+        from squackit.workflows import _anchored
+
+        assert _anchored(ProjectDefaults(), "src/**/*.py") == "src/**/*.py"