squackit 0.8.3__tar.gz → 0.9.0__tar.gz

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

@@ -1,5 +1,79 @@
 # Changelog
 
+## 0.9.0
+
+### Added — structured output for programmatic callers (#18)
+
+Every tool accepts `as_json=true` and returns one envelope:
+
+    {"rows": [...], "columns": [...], "omitted": <int>}
+
+squackit renders for a human reader — markdown tables and newline-joined text.
+That is right for an agent reading a briefing and close to useless to a program
+composing calls. Measured by a session driving four local models through
+lackpy: **0/24 correct while 17/24 called the correct tool**. `len()` on
+`find_names`' newline-joined string gives 67 (characters) where the answer is
+8; on `find`'s table it gives 2239.
+
+The structure was never lost, only discarded at the last step: the executors
+already return DuckDB relations and View objects, and the CLI already had
+`--json`. This exposes that over MCP, on both the macro and pluckit wrappers.
+
+Deliberate choices:
+
+- **One envelope for every tool**, so a caller learns the shape once.
+- **`omitted` rather than a bare array.** A truncated array is
+  indistinguishable from a complete one, and shipping silent truncation on the
+  programmatic path would reproduce the defect this mode exists to fix.
+- **The shape is stated in every tool's description.** The cost of the
+  envelope is that `len()` of it is 3, not the row count — the same misread
+  that produced the 0/24 — so it is named beside the signature rather than left
+  to be inferred.
+- **An empty result is `[]`**, not the prose `(no results)`.
+- **The default is unchanged.** Existing callers see exactly what they saw
+  before; `as_json` is opt-in, so this is additive rather than a migration.
+
+The `compact_columns` projection and `verbose` still apply, so a JSON caller
+sees the same columns a markdown caller would unless it asks for more.
+
+
+## 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.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: squackit
-Version: 0.8.3
+Version: 0.9.0
 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.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "squackit"
-version = "0.8.3"
+version = "0.9.0"
 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.9.0}/squackit/server.py

@@ -21,6 +21,7 @@ Usage::
 from __future__ import annotations
 
 import inspect
+import json as _json
 import threading
 from collections import OrderedDict
 from pathlib import Path
@@ -246,6 +247,8 @@ def _register_executor_tool(mcp, presentation: ToolPresentation):
             elif v is not None:
                 verbose = bool(v)
 
+        as_json = _as_json_requested(kwargs)
+
         filtered = {k: v for k, v in kwargs.items() if v is not None}
 
         try:
@@ -259,6 +262,16 @@ def _register_executor_tool(mcp, presentation: ToolPresentation):
         # View -> markdown (truncate by blocks if too many)
         if hasattr(result, 'markdown') and hasattr(result, 'blocks'):
             blocks = result.blocks
+            if as_json:
+                tabular = getattr(result, "tabular", None)
+                if tabular is not None:
+                    vcols, vrows = tabular
+                    kept, omitted = _limit_rows(list(vrows), max_limit)
+                    return _json_envelope(
+                        [dict(zip(vcols, r)) for r in kept], vcols, omitted)
+                kept, omitted = _limit_rows(list(blocks), max_limit)
+                return _json_envelope(
+                    [b.markdown for b in kept if b.markdown], (), omitted)
             if max_limit > 0 and len(blocks) > max_limit:
                 kept = blocks[:max_limit]
                 omitted = len(blocks) - max_limit
@@ -269,6 +282,13 @@ def _register_executor_tool(mcp, presentation: ToolPresentation):
         if hasattr(result, 'columns') and hasattr(result, 'fetchall'):
             cols = result.columns
             rows = result.fetchall()
+            if as_json:
+                # Projection still applies, so a JSON caller gets the same
+                # columns a markdown caller would unless it asks for verbose.
+                jcols, jrows = _project(cols, rows, presentation, verbose)
+                kept, omitted = _limit_rows(jrows, max_limit)
+                return _json_envelope(
+                    [dict(zip(jcols, r)) for r in kept], jcols, omitted)
             if not rows:
                 return "(no results)"
             omission = None
@@ -312,6 +332,9 @@ def _register_executor_tool(mcp, presentation: ToolPresentation):
             return text
         # list -> joined (truncate)
         if isinstance(result, list):
+            if as_json:
+                kept, omitted = _limit_rows(list(result), max_limit)
+                return _json_envelope(kept, (), omitted)
             if not result:
                 return "(no results)"
             if max_limit > 0 and len(result) > max_limit:
@@ -324,7 +347,7 @@ def _register_executor_tool(mcp, presentation: ToolPresentation):
 
     tool_fn.__name__ = tool_name
     tool_fn.__qualname__ = tool_name
-    tool_fn.__doc__ = description
+    tool_fn.__doc__ = description + _AS_JSON_NOTE
 
     required_set = set(presentation.required)
     annotations = {}
@@ -354,6 +377,13 @@ def _register_executor_tool(mcp, presentation: ToolPresentation):
             "verbose", inspect.Parameter.KEYWORD_ONLY,
             default=None, annotation=Optional[bool],
         ))
+    # Every one of these tools returns data, so the structured mode is offered
+    # unconditionally rather than per-tool.
+    annotations["as_json"] = Optional[bool]
+    sig_params.append(inspect.Parameter(
+        "as_json", inspect.Parameter.KEYWORD_ONLY,
+        default=None, annotation=Optional[bool],
+    ))
     tool_fn.__annotations__ = {**annotations, "return": str}
     tool_fn.__signature__ = inspect.Signature(
         sig_params, return_annotation=str,
@@ -448,6 +478,76 @@ def _fts_con_for_root(mcp, root: str):
         return con
 
 
+#: Appended to every tool's description. A caller that has to GUESS the return
+#: shape guesses wrong: measured at 0/24 correct while calling the right tool
+#: 17/24 times, because `len()` on a rendered table counts characters. Naming
+#: the shape beside the signature is the cheapest fix for that, and it is the
+#: reason the envelope is a stable object rather than a bare array.
+_AS_JSON_NOTE = (
+    "\n\nPass as_json=true for structured output: "
+    '{"rows": [...], "columns": [...], "omitted": <int>}. '
+    "`omitted` is how many rows the limit dropped — it is 0 when the result is "
+    "complete, so a truncated result can never be mistaken for a whole one."
+)
+
+
+def _limit_rows(rows, max_limit):
+    """Apply the presentation limit, returning (kept, omitted_count)."""
+    if max_limit and max_limit > 0 and len(rows) > max_limit:
+        return rows[:max_limit], len(rows) - max_limit
+    return rows, 0
+
+
+def _project(cols, rows, presentation, verbose):
+    """Apply the compact_columns projection, if the tool declares one.
+
+    Shared so JSON and markdown callers see the same columns; a caller opts
+    out of both with verbose=True.
+    """
+    if not presentation.compact_columns or verbose:
+        return list(cols), list(rows)
+    keep_idx = [i for i, name in enumerate(cols)
+                if name in presentation.compact_columns]
+    order = {name: pos for pos, name in enumerate(presentation.compact_columns)}
+    keep_idx.sort(key=lambda i: order.get(cols[i], len(order)))
+    if not keep_idx:
+        return list(cols), list(rows)
+    return ([cols[i] for i in keep_idx],
+            [tuple(row[i] for i in keep_idx) for row in rows])
+
+
+def _json_envelope(rows, columns=(), omitted: int = 0) -> str:
+    """The one shape every tool returns under `as_json=True`.
+
+        {"rows": [...], "columns": [...], "omitted": <int>}
+
+    One envelope for every tool, so a caller learns the shape once instead of
+    per tool. `omitted` exists so truncation stays REPRESENTABLE: a bare array
+    that had been cut is indistinguishable from a complete one, and shipping
+    silent truncation on the programmatic path would reproduce the exact defect
+    this output mode was added to fix.
+
+    The trade is that `len()` of the envelope is 3, not the row count — which
+    is the misread that motivated this ("0/24 correct while 17/24 called the
+    right tool"). That is why the shape is stated in the tool description
+    rather than left to be guessed.
+    """
+    return _json.dumps(
+        {"rows": list(rows), "columns": list(columns), "omitted": int(omitted)},
+        indent=2, default=str,
+    )
+
+
+def _as_json_requested(kwargs) -> bool:
+    """Pop `as_json`, accepting the string forms MCP clients send."""
+    if "as_json" not in kwargs:
+        return False
+    v = kwargs.pop("as_json")
+    if isinstance(v, str):
+        return v.lower() in ("true", "1", "yes")
+    return bool(v) if v is not None else False
+
+
 def _register_tool(
     mcp,  # FastMCP type annotation removed to avoid import at module level
     con,
@@ -510,6 +610,10 @@ def _register_tool(
             max_rows = 0
 
         # Remove None values; coerce known numeric params to int.
+        # Pop before building macro args: `as_json` is a presentation choice,
+        # not a macro parameter, and passing it through raises a binder error.
+        as_json = _as_json_requested(kwargs)
+
         # Only numeric_params are coerced — blanket isdigit() would
         # break git SHAs like "1234567".
         filtered = {}
@@ -587,10 +691,18 @@ def _register_tool(
             elapsed = (_time.time() - t0) * 1000
             access_log.record(tool_name, cache_args, 0,
                               cached=False, elapsed_ms=elapsed)
-            return _empty_msg()
+            # A program needs an empty list it can iterate, not a sentence.
+            return _json_envelope([], cols, 0) if as_json else _empty_msg()
 
         total_rows = len(rows)
 
+        if as_json:
+            # Structured callers get every row the limit allows plus an
+            # explicit count of what was dropped — never a quietly short list.
+            kept, omitted = _limit_rows(list(rows), max_rows if limit_param else 0)
+            return _json_envelope([dict(zip(cols, r)) for r in kept],
+                                  cols, omitted)
+
         # Apply truncation
         omission = None
         if limit_param and max_rows > 0:
@@ -669,7 +781,7 @@ def _register_tool(
             "DIFFERENT repository, pass `root=<repository directory>` (an absolute path) — the "
             "repo is indexed on first use and cached."
         )
-    tool_fn.__doc__ = description
+    tool_fn.__doc__ = description + _AS_JSON_NOTE
 
     # Build parameter annotations for FastMCP schema generation.
     # All params get default=None so FastMCP validation passes even when
@@ -697,6 +809,13 @@ def _register_tool(
             "root", inspect.Parameter.KEYWORD_ONLY, default=None,
             annotation=Optional[str],
         ))
+    # Every one of these tools returns data, so the structured mode is offered
+    # unconditionally rather than per-tool.
+    annotations["as_json"] = Optional[bool]
+    sig_params.append(inspect.Parameter(
+        "as_json", inspect.Parameter.KEYWORD_ONLY,
+        default=None, annotation=Optional[bool],
+    ))
     tool_fn.__annotations__ = {**annotations, "return": str}
 
     tool_fn.__signature__ = inspect.Signature(

{squackit-0.8.3 → squackit-0.9.0}/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.9.0}/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.9.0}/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"