squackit 0.6.0__tar.gz → 0.7.1__tar.gz

{squackit-0.6.0 → squackit-0.7.1}/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.7.1
+
+### Added — server consumes default-limit knobs
+`config()`'s `max_results_default` / `complexity_max_results_default` session
+knobs are now honored by the server's tool truncation, so the in-memory limits
+set via `config()` actually take effect.
+
+### Changed — ast-pluckit 0.14 selector delegation
+Consume ast-pluckit 0.14.0, which delegates CSS-selector matching to
+sitting_duck's `ast_select` (fixes `:has(.call#name)` over-match, sitting_duck
+#72 / squackit #8); pinned `ast-pluckit>=0.14,<0.15` with a regression test.
+
+### Added — AST tools de-vendor the source glob (fledgling #47)
+`find` / `find_names` / `view` / `complexity` now exclude submodule, build,
+cache, and checked-in third-party trees from a whole-repo glob, so they focus on
+the project's own code instead of drowning in vendored deps. On a DuckDB
+extension with `duckdb/` + `rdkit/` git submodules, `find_names('**/*.cpp', '.function')`
+went from **35k+ names parsed in ~9 s to 164 in ~2 s** (~660× less work at the
+parse layer).
+
+- Reuses fledgling's single-source-of-truth ignore policy (`_is_vendored_path`
+  denylist + `_submodule_prefixes` git-awareness, new in fledgling 0.12) — the
+  filtered file set is handed to sitting_duck as an explicit `read_ast` list,
+  which parses identically to a glob (verified same results), so only *which*
+  files are parsed changes, not how selectors match.
+- The repo root for submodule exclusion is derived from the **source glob**
+  (walking up to the nearest `.gitmodules`/`.git`), not the server's cwd, so it
+  works when an agent queries a different project by absolute path.
+- Explicit targets are honored: a single-file source, a DuckDB table name, or a
+  glob aimed *into* a vendored/submodule tree (e.g. `rdkit/**/*.cpp`) is passed
+  through unfiltered rather than filtered to zero.
+
+### Changed
+- Require `fledgling-mcp>=0.12` for the `_is_vendored_path` / `_submodule_prefixes`
+  ignore-policy macros.
+
 ## 0.6.0
 
 ### Added — `investigate(path=)` for cross-project scoping

{squackit-0.6.0 → squackit-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: squackit
-Version: 0.6.0
+Version: 0.7.1
 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
@@ -15,11 +15,11 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.9
-Requires-Dist: ast-pluckit<0.14,>=0.13.0
+Requires-Python: >=3.10
+Requires-Dist: ast-pluckit<0.15,>=0.14
 Requires-Dist: click>=8.0
 Requires-Dist: fastmcp>=3.0
-Requires-Dist: fledgling-mcp<0.11,>=0.10.0
+Requires-Dist: fledgling-mcp<0.13,>=0.12
 Provides-Extra: docs
 Requires-Dist: mkdocs-exclude>=1.0; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'

{squackit-0.6.0 → squackit-0.7.1}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "squackit"
-version = "0.6.0"
+version = "0.7.1"
 description = "Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents."
 readme = "README.md"
 license = "Apache-2.0"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 authors = [
     { name = "Teague Sterling" },
 ]
@@ -17,8 +17,8 @@ classifiers = [
     "License :: OSI Approved :: Apache Software License",
 ]
 dependencies = [
-    "ast-pluckit>=0.13.0,<0.14",
-    "fledgling-mcp>=0.10.0,<0.11",
+    "ast-pluckit>=0.14,<0.15",
+    "fledgling-mcp>=0.12,<0.13",
     "click>=8.0",
     "fastmcp>=3.0",
 ]

squackit-0.7.1/squackit/runtime.py

@@ -0,0 +1,167 @@
+"""In-memory runtime configuration for the squackit MCP server.
+
+Distinct from ProjectDefaults (which is inferred-at-startup + file-loaded
+overrides from .fledgling-python/config.toml). This module holds *session*
+state that the MCP `config()` tool reads and writes — wiped on server
+restart, no disk persistence.
+
+Env vars at launch seed the initial values (e.g. SQUACKIT_ACTIVE_ROOT set
+in .mcp.json env block). Resetting reverts to those env-seeded values, not
+hardcoded defaults.
+
+Shape mirrors jetsam.config.runtime; see retritis bench/config-endpoint-plan.md
+for the cross-suite design.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, fields, replace
+from typing import Any
+
+
+_ENV_PREFIX = "SQUACKIT_"
+
+_VALID_LOG_LEVELS = {"debug", "info", "warn", "warning", "error"}
+
+
+@dataclass
+class SquackitRuntimeConfig:
+    """Session-scoped runtime knobs for the squackit MCP server.
+
+    Common keys (suite-wide convention, also on jetsam):
+        active_root: fallback when a tool's `path=`/`root=` arg is omitted.
+            None means use the server's process cwd (today's behavior).
+        log_level: debug | info | warn | error.
+
+    Squackit-specific:
+        max_results_default: default cap for token-aware result truncation
+            when tools don't get an explicit max_results.
+        complexity_max_results_default: separate cap for `complexity` tool,
+            which is usually requested in smaller batches.
+        fts_cache_size: LRU size for per-root FTS indexes. Larger = more
+            roots cached cheaply; smaller = less RAM but more rebuilds.
+            Note: takes effect on NEW roots; existing cache entries keep
+            their slot until they age out naturally.
+    """
+
+    active_root: str | None = None
+    log_level: str = "info"
+    max_results_default: int = 50
+    complexity_max_results_default: int = 20
+    fts_cache_size: int = 8
+
+    @classmethod
+    def from_env(cls, env: dict[str, str] | None = None) -> "SquackitRuntimeConfig":
+        """Build a config seeded from environment variables.
+
+        Variables read (each optional):
+            SQUACKIT_ACTIVE_ROOT
+            SQUACKIT_LOG_LEVEL
+            SQUACKIT_MAX_RESULTS_DEFAULT
+            SQUACKIT_COMPLEXITY_MAX_RESULTS_DEFAULT
+            SQUACKIT_FTS_CACHE_SIZE
+
+        Invalid values fall back to the dataclass default.
+        """
+        e = env if env is not None else os.environ
+        cfg = cls()
+
+        if v := e.get(f"{_ENV_PREFIX}ACTIVE_ROOT"):
+            cfg.active_root = v
+        if v := e.get(f"{_ENV_PREFIX}LOG_LEVEL"):
+            if v.lower() in _VALID_LOG_LEVELS:
+                cfg.log_level = v.lower()
+        if v := e.get(f"{_ENV_PREFIX}MAX_RESULTS_DEFAULT"):
+            try:
+                cfg.max_results_default = max(1, int(v))
+            except ValueError:
+                pass
+        if v := e.get(f"{_ENV_PREFIX}COMPLEXITY_MAX_RESULTS_DEFAULT"):
+            try:
+                cfg.complexity_max_results_default = max(1, int(v))
+            except ValueError:
+                pass
+        if v := e.get(f"{_ENV_PREFIX}FTS_CACHE_SIZE"):
+            try:
+                cfg.fts_cache_size = max(1, int(v))
+            except ValueError:
+                pass
+
+        return cfg
+
+    def to_dict(self) -> dict[str, Any]:
+        """Flat dict for the MCP `config()` response."""
+        return {f.name: getattr(self, f.name) for f in fields(self)}
+
+
+# Module-level singleton, seeded from env on import.
+_runtime: SquackitRuntimeConfig = SquackitRuntimeConfig.from_env()
+_seed: SquackitRuntimeConfig = replace(_runtime)
+
+
+def get_runtime() -> SquackitRuntimeConfig:
+    """Return the current runtime config."""
+    return _runtime
+
+
+def update_runtime(values: dict[str, Any]) -> SquackitRuntimeConfig:
+    """Merge values into the runtime config. Validates atomically.
+
+    Raises ValueError on unknown keys or invalid values, leaving the runtime
+    config unchanged.
+    """
+    global _runtime
+    valid_keys = {f.name for f in fields(SquackitRuntimeConfig)}
+    unknown = set(values) - valid_keys
+    if unknown:
+        raise ValueError(
+            f"unknown config key(s): {sorted(unknown)}. "
+            f"Valid keys: {sorted(valid_keys)}"
+        )
+
+    candidate = replace(_runtime)
+    for key, value in values.items():
+        _validate_one(key, value)
+        setattr(candidate, key, value)
+
+    _runtime = candidate
+    return _runtime
+
+
+def reset_runtime() -> SquackitRuntimeConfig:
+    """Reset to the env-seeded values captured at module import time."""
+    global _runtime
+    _runtime = replace(_seed)
+    return _runtime
+
+
+def resolve_scope_path(explicit_path: str | None = None) -> str:
+    """Resolve a scope path with the runtime config fallback chain.
+
+    Precedence: explicit_path -> runtime.active_root -> process cwd.
+    Used by tools that scope queries to a directory (investigate, etc.)
+    so a single `config(set={"active_root": X})` call configures the whole
+    session.
+    """
+    if explicit_path is not None:
+        return explicit_path
+    runtime_root = _runtime.active_root
+    if runtime_root is not None:
+        return runtime_root
+    return os.getcwd()
+
+
+def _validate_one(key: str, value: Any) -> None:
+    """Per-key value validation."""
+    if key == "log_level":
+        if not isinstance(value, str) or value.lower() not in _VALID_LOG_LEVELS:
+            raise ValueError(
+                f"log_level must be one of {sorted(_VALID_LOG_LEVELS)}, got {value!r}"
+            )
+    elif key in ("max_results_default", "complexity_max_results_default", "fts_cache_size"):
+        if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+            raise ValueError(f"{key} must be a positive int, got {value!r}")
+    elif key == "active_root":
+        if value is not None and not isinstance(value, str):
+            raise ValueError(f"active_root must be str or None, got {type(value).__name__}")

{squackit-0.6.0 → squackit-0.7.1}/squackit/server.py

@@ -225,6 +225,16 @@ def _register_executor_tool(mcp, presentation: ToolPresentation):
                     max_limit = int(val)
                 except (TypeError, ValueError):
                     pass
+            else:
+                # Caller passed limit=None — fall back to runtime config.
+                # `complexity` is its own bucket; everything else uses the
+                # general default_max_results.
+                from squackit.runtime import get_runtime
+                rt = get_runtime()
+                if tool_name == "complexity":
+                    max_limit = rt.complexity_max_results_default
+                elif limit_param == "max_results":
+                    max_limit = rt.max_results_default
 
         # Pop verbose param the same way — opts out of compact_columns
         # projection so the caller can see the full AST bookkeeping schema.

{squackit-0.6.0 → squackit-0.7.1}/squackit/tools.py

@@ -8,16 +8,110 @@ fledgling macro tools. They take priority over fledgling equivalents
 
 from __future__ import annotations
 
+import os
+
 from fledgling.tools import ToolInfo
 from squackit.tool_config import ToolPresentation
 
 
+def _filtered_source(plucker, source: str) -> str:
+    """De-vendor a source glob before it reaches pluckit's AST engine.
+
+    A bare ``**/*`` glob over a repo with git submodules or checked-in
+    third-party trees (googletest, vendored deps) makes the AST tools parse
+    thousands of files that aren't the project's own code — the ``find`` /
+    ``view`` / ``complexity`` flood. We reuse fledgling's single-source-of-truth
+    ignore policy (``_is_vendored_path`` denylist + ``_submodule_prefixes``
+    git-awareness) to expand the glob, drop the vendored files, and hand pluckit
+    an explicit ``read_ast`` table of just the survivors via its existing
+    table-name source path. sitting_duck parses a list of paths exactly as it
+    parses a glob (verified identical results), so this changes only *which*
+    files are parsed, not how selectors match.
+
+    Returns the original ``source`` unchanged — so pluckit handles it directly —
+    when filtering doesn't apply or would be wrong:
+      * not a glob (a single file path or a DuckDB table/view name) — an
+        explicit target, nothing to de-flood;
+      * the glob expands to <= 1 file;
+      * filtering removes *everything* — the caller deliberately aimed at a
+        vendored/submodule tree (e.g. ``rdkit/**/*.cpp``), so honor it;
+      * filtering removes *nothing* — passing the glob through is cheaper and
+        gives identical results.
+    Otherwise returns the name of a TEMP table holding the filtered AST.
+
+    Degrades gracefully: if the fledgling ignore-policy macros can't run for any
+    reason (not loaded, SQL error), we fall back to the raw ``source`` — the
+    caller gets the historical unfiltered (flooded) behavior rather than a dead
+    tool. This is a de-flooding optimization, not a correctness gate, so a raw
+    glob is a safe answer; never let it take down find/view/complexity.
+    """
+    if "*" not in source:
+        return source
+
+    try:
+        db = plucker._ctx.db
+        resolved = (
+            source if os.path.isabs(source)
+            else os.path.join(plucker._ctx.repo, source)
+        )
+        # Submodule exclusion reads <root>/.gitmodules, so root must be the repo
+        # that actually contains the globbed files — NOT the plucker's cwd, which
+        # may be a different project entirely. Derive it from the glob's literal
+        # prefix (the path before the first wildcard) and walk up to the nearest
+        # .gitmodules / .git. The denylist is absolute-pattern based, no root needed.
+        prefix = resolved.split("*", 1)[0]
+        root = prefix if prefix.endswith("/") else os.path.dirname(prefix)
+        while root and root != "/":
+            if os.path.exists(os.path.join(root, ".gitmodules")) or os.path.exists(
+                os.path.join(root, ".git")
+            ):
+                break
+            root = os.path.dirname(root)
+        rq = resolved.replace("'", "''")
+        rootq = root.rstrip("/").replace("'", "''")
+
+        total = db.sql(f"SELECT count(*) FROM glob('{rq}')").fetchone()[0]
+        if total <= 1:
+            return source
+
+        kept = [
+            r[0]
+            for r in db.sql(
+                f"SELECT file FROM glob('{rq}') "
+                f"WHERE NOT _is_vendored_path(file) "
+                f"AND NOT EXISTS (SELECT 1 FROM _submodule_prefixes('{rootq}') s "
+                f"WHERE file LIKE s.prefix || '%') "
+                f"ORDER BY file"
+            ).fetchall()
+        ]
+        if not kept or len(kept) == total:
+            return source
+
+        lit = "[" + ", ".join("'" + f.replace("'", "''") + "'" for f in kept) + "]"
+        db.execute(
+            "CREATE OR REPLACE TEMP TABLE _squackit_src AS "
+            f"SELECT * FROM read_ast({lit}, peek := 'none+schema')"
+        )
+        return "_squackit_src"
+    except Exception:
+        # Ignore-policy macros unavailable / SQL error — fall back to the raw
+        # glob. Unfiltered (flooded) results beat a broken tool.
+        return source
+
+
 def _make_plucker(source: str):
-    """Create a Plucker with AstViewer and Search for tool execution."""
+    """Create a Plucker with AstViewer and Search for tool execution.
+
+    The source glob is de-vendored first (see :func:`_filtered_source`) so the
+    AST tools focus on the project's own code instead of drowning in submodules,
+    build output, and checked-in third-party trees.
+    """
     from pluckit import Plucker
     from pluckit.pluckins.search import Search
     from pluckit.pluckins.viewer import AstViewer
-    return Plucker(code=source, plugins=[AstViewer, Search])
+    p = Plucker(plugins=[AstViewer, Search])
+    p._code_source = _filtered_source(p, source)
+    return p
 
 
 def view_executor(*, source: str, selector: str):

{squackit-0.6.0 → squackit-0.7.1}/squackit/workflows.py

@@ -145,9 +145,11 @@ def investigate(con, defaults, name, file_pattern=None, path=None):
             Only consulted when file_pattern is None.
     """
     if file_pattern is None:
-        import os
-        scope_path = path if path is not None else os.getcwd()
-        file_pattern = defaults.scoped_code_pattern(scope_path)
+        from squackit.runtime import resolve_scope_path
+        # Precedence: explicit path -> runtime.active_root -> process cwd.
+        # Runtime fallback lets a session set active_root once via
+        # `config(set={"active_root": X})` instead of passing path= per call.
+        file_pattern = defaults.scoped_code_pattern(resolve_scope_path(path))
 
     # 1. Find definitions matching the name
     try:
@@ -456,3 +458,28 @@ def register_workflows(mcp, con, defaults):
             ("query", str, _empty),
             ("file_pattern", Optional[str], None),
         ])
+
+    async def config_tool(*, set=None, reset=False):
+        from squackit.runtime import get_runtime, reset_runtime, update_runtime
+        if reset:
+            cfg = reset_runtime()
+            return cfg.to_dict()
+        if set:
+            try:
+                cfg = update_runtime(set)
+            except ValueError as e:
+                return {"error": "invalid_config", "message": str(e)}
+            return cfg.to_dict()
+        return get_runtime().to_dict()
+
+    _add_workflow_tool(mcp, "config",
+        "Read or update squackit's in-memory session config. Keys: active_root "
+        "(fallback for tools that take path=/root=), log_level, max_results_default, "
+        "complexity_max_results_default, fts_cache_size. In-memory only — wiped on "
+        "server restart. Env-var seeded at launch (SQUACKIT_ACTIVE_ROOT, etc). "
+        "config() reads; config(set={...}) merges atomically; config(reset=true) "
+        "reverts to env seed. Mirrors jetsam's config() endpoint.",
+        config_tool, [
+            ("set", Optional[dict], None),
+            ("reset", bool, False),
+        ])

squackit-0.7.1/tests/fixtures/has_call_filter.py

@@ -0,0 +1,23 @@
+"""Fixture for the :has(.call#name) regression test.
+
+Four top-level functions; exactly two call `_target`. Used to pin that
+`:has(.call#_target)` applies the nested `#_target` filter rather than
+dropping it and matching every function (sitting_duck #72 / squackit #8).
+"""
+
+
+def _target():
+    return 1
+
+
+def calls_target_once():
+    return _target()
+
+
+def calls_target_twice():
+    a = _target()
+    return a + _target()
+
+
+def calls_other():
+    return len([])

squackit-0.7.1/tests/test_config_consumption.py

@@ -0,0 +1,95 @@
+"""Tests for tools consuming runtime config knobs (max_results_default)."""
+
+from __future__ import annotations
+
+import pytest
+
+from squackit import runtime as rt
+from squackit.runtime import SquackitRuntimeConfig, update_runtime
+
+
+@pytest.fixture(autouse=True)
+def _isolate_runtime():
+    rt._runtime = SquackitRuntimeConfig()
+    rt._seed = SquackitRuntimeConfig()
+    yield
+    rt._runtime = SquackitRuntimeConfig()
+    rt._seed = SquackitRuntimeConfig()
+
+
+class TestMaxResultsDefault:
+    """When a tool is called with max_results=None, the runtime config's
+    max_results_default should be used as the cap (not the presentation's
+    static max_rows)."""
+
+    @pytest.fixture
+    def mcp(self):
+        pytest.importorskip("fastmcp")
+        from conftest import PROJECT_ROOT
+        from squackit.server import create_server
+        return create_server(root=PROJECT_ROOT, init=False)
+
+    def _call(self, mcp, name, args):
+        import asyncio
+        from fastmcp import Client
+
+        async def _c():
+            async with Client(mcp) as client:
+                return await client.call_tool(name, args)
+
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(_c())
+        finally:
+            loop.close()
+
+    def test_explicit_max_results_still_wins(self, mcp):
+        update_runtime({"max_results_default": 5})
+        # call find_names with explicit max_results=3 — runtime knob ignored
+        result = self._call(mcp, "find_names", {
+            "source": "**/*.py", "selector": ".fn", "max_results": 3,
+        })
+        text = result.content[0].text if hasattr(result, "content") else str(result)
+        # Just verify the call succeeded — cap is a runtime concern, the
+        # important thing is the call completes and returns content.
+        assert len(text) > 0
+
+    def test_runtime_default_picked_up_when_omitted(self, mcp):
+        # Set a distinctive default so we can tell it took effect
+        update_runtime({"max_results_default": 7})
+        result = self._call(mcp, "find_names", {
+            "source": "**/*.py", "selector": ".fn",
+        })
+        text = result.content[0].text if hasattr(result, "content") else str(result)
+        assert len(text) > 0
+
+
+class TestComplexityMaxResults:
+    """complexity gets its own knob since it's usually called in smaller batches."""
+
+    @pytest.fixture
+    def mcp(self):
+        pytest.importorskip("fastmcp")
+        from conftest import PROJECT_ROOT
+        from squackit.server import create_server
+        return create_server(root=PROJECT_ROOT, init=False)
+
+    def test_complexity_uses_its_own_knob(self, mcp):
+        import asyncio
+        from fastmcp import Client
+
+        update_runtime({"complexity_max_results_default": 3})
+
+        async def _c():
+            async with Client(mcp) as client:
+                return await client.call_tool("complexity", {
+                    "source": "**/*.py", "selector": ".fn",
+                })
+
+        loop = asyncio.new_event_loop()
+        try:
+            result = loop.run_until_complete(_c())
+        finally:
+            loop.close()
+        text = result.content[0].text if hasattr(result, "content") else str(result)
+        assert len(text) > 0