boost-skill-cli 1.0.154__tar.gz → 1.0.155__tar.gz

{boost_skill_cli-1.0.154 → boost_skill_cli-1.0.155}/Makefile

@@ -43,6 +43,7 @@ lint:
 	@command -v actionlint >/dev/null 2>&1 && actionlint || echo "actionlint not on PATH — skipping (CI enforces it)"
 	$(PY) scripts/build_registries.py --check
 	$(PY) scripts/build_roadmap.py --check
+	$(PY) scripts/import_budget.py
 
 # Supply-chain CVE gate: fail on a known OSV/PyPI advisory in the project's
 # dependency closure. Mirrors the pip-audit CI workflow; run before releasing.

{boost_skill_cli-1.0.154 → boost_skill_cli-1.0.155}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.154
+Version: 1.0.155
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.154 → boost_skill_cli-1.0.155}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.154'
-__version_tuple__ = version_tuple = (1, 0, 154)
+__version__ = version = '1.0.155'
+__version_tuple__ = version_tuple = (1, 0, 155)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.154 → boost_skill_cli-1.0.155}/boost_cli/commands/discovery.py

@@ -17,7 +17,7 @@ import urllib.parse
 from pathlib import Path
 
 from .. import cliparse, spin
-from ..core import (agents, ai, catalog, config, dense, embed, gitutil,
+from ..core import (agents, ai, catalog, config, gitutil,
                     journal, lockfile, paths, rag, registry, store, util)
 from ..core import output as out
 from ..core.stackprobe import detect_stack  # re-exported: shared with Quality
@@ -165,6 +165,11 @@ def cmd_reindex(argv):
         stats = rag.build(force=args.force)
     dense_stats = None
     if args.dense:
+        # Imported lazily (only on `--dense`) so the optional dense/embedding
+        # stack never loads for the common offline commands this module also
+        # holds — count, stats, trending, plain search. See the import-budget
+        # gate (scripts/import_budget.py).
+        from ..core import embed
         with spin.Spinner("embedding chunks into the dense store"):
             dense_stats = _reindex_dense(args.force)
     if args.as_json:
@@ -192,6 +197,9 @@ def cmd_reindex(argv):
 
 def _reindex_dense(force):
     """Build the dense vector store; returns stats or None when unavailable."""
+    # Local import: the dense/embedding engines are opt-in (`search --dense`),
+    # so they stay out of startup for every other command in this module.
+    from ..core import dense, embed
     if not dense.have_backend() or not embed.available():
         return None
     return dense.build(force=force)

{boost_skill_cli-1.0.154 → boost_skill_cli-1.0.155}/boost_skill_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.154
+Version: 1.0.155
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.154 → boost_skill_cli-1.0.155}/boost_skill_cli.egg-info/SOURCES.txt

@@ -224,6 +224,7 @@ scripts/ensure_eval_corpus.sh
 scripts/eval_explain.py
 scripts/eval_recommend.py
 scripts/eval_retrieval.py
+scripts/import_budget.py
 scripts/mutation_gate.py
 style/README.md
 style/boost.css
@@ -282,6 +283,7 @@ tests/unit/test_errors_and_cli_table.py
 tests/unit/test_frontmatter.py
 tests/unit/test_gitutil.py
 tests/unit/test_imperative.py
+tests/unit/test_import_budget.py
 tests/unit/test_injectscan.py
 tests/unit/test_journal.py
 tests/unit/test_lockfile.py

{boost_skill_cli-1.0.154 → boost_skill_cli-1.0.155}/docs/roadmap/items/startup-and-import-time-budget-x-importtime.md

@@ -2,15 +2,15 @@
 id: startup-and-import-time-budget-x-importtime
 board: code
 section: compat
-status: planned
+status: shipped
 category: Perf · Startup
 complexity: M
 impact: High
 wow: 4
 note: lazy-import guard
 order: 5
-owner:
-pr:
+owner: loop/import-budget
+pr: 179
 title: Startup &amp; import-time budget — <code>-X importtime</code>
 ---
 For a CLI, cold-start latency <em>is</em> the UX — every command pays it.

{boost_skill_cli-1.0.154 → boost_skill_cli-1.0.155}/docs/roadmap.html

@@ -1787,7 +1787,7 @@ and the work stays visible.</p>
       </article>
 
       <article class="cap rcard">
-        <div class="head"><span class="pill planned">Planned</span><span class="cat">Perf · Startup</span></div>
+        <div class="head"><span class="pill shipped">Shipped</span><span class="cat">Perf · Startup</span></div>
         <h3>Startup &amp; import-time budget — <code>-X importtime</code></h3>
         <p>For a CLI, cold-start latency <em>is</em> the UX — every command pays it.
            A gate on <code>python -X importtime boost</code> catches the accidental

boost_skill_cli-1.0.155/scripts/import_budget.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""Startup import-time budget — the lazy-import guard.
+
+For a CLI, cold-start latency *is* the UX: every command pays it before it does
+anything. This gate runs ``python -X importtime`` for a set of common, fully
+offline commands and asserts that a denylist of heavy or optional-only modules
+never gets imported at startup.
+
+The classic regression it catches is the accidental *top-level* import of an
+optional dependency — the ``[rag]`` stack (``sqlite_vec``), an embedding/AI SDK,
+or a scientific-python tree — that a hot path only ever needs lazily. boost is
+architected so those load inside the one function that needs them (e.g.
+``search --dense``); this gate keeps it that way.
+
+Deliberately name-based, not timing-based: a denylisted module is either
+imported or it isn't, identically on a fast laptop and a slow, differently
+CPU-throttled CI runner across every Python version — so the gate is
+deterministic and never flakes. A coarse module-count ceiling is reported as an
+advisory only (stdlib import graphs differ across Python versions), never a hard
+failure.
+
+Usage:
+    python scripts/import_budget.py           # exit 1 if anything leaked
+    python scripts/import_budget.py --list     # also print each command's count
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Dict, List, Set
+
+ROOT = Path(__file__).resolve().parent.parent
+
+# Common commands that must stay lean. All are fully offline and touch the core
+# dispatch + store/catalog paths, so a leak anywhere in that surface is caught.
+COMMANDS: List[List[str]] = [["--help"], ["--version"], ["list"], ["count"]]
+
+# Modules that must NEVER load for the commands above. Heavy C extensions,
+# scientific-python, and the embedding/AI SDKs — plus boost's own optional-only
+# engines, which stay lazy behind `search --dense`. A leak means a hot path grew
+# a top-level import of an optional dependency.
+DENYLIST: Set[str] = {
+    # the [rag] extra's native dependency
+    "sqlite_vec",
+    # scientific-python / vector libs an embedding backend might drag in
+    "numpy", "scipy", "pandas", "torch", "transformers",
+    "sentence_transformers", "faiss",
+    # embedding / LLM provider SDKs (boost talks to them over stdlib urllib,
+    # so none of these should ever import at startup)
+    "openai", "voyageai", "anthropic", "cohere",
+    "langchain", "langchain_core", "langchain_community",
+    "ragas", "ranx",
+    # boost's own optional-only engines
+    "boost_cli.core.dense", "boost_cli.core.embed",
+}
+
+# Advisory ceiling on total modules imported by a single command — reported, not
+# enforced (import graphs legitimately differ across Python versions/platforms).
+SOFT_MODULE_CEILING = 260
+
+
+def parse_modules(importtime_stderr: str) -> Set[str]:
+    """Module names from ``python -X importtime`` stderr.
+
+    Each line is ``import time: <self> | <cumulative> | <indent><module>``; the
+    module name is the third ``|``-delimited field with its nesting indent
+    stripped. The header line (``self [us] | cumulative | imported package``)
+    has no numeric first field and is skipped.
+    """
+    modules: Set[str] = set()
+    for line in importtime_stderr.splitlines():
+        if "import time:" not in line:
+            continue
+        _, _, rest = line.partition("import time:")
+        parts = rest.split("|")
+        if len(parts) != 3:
+            continue
+        if not parts[0].strip().isdigit():   # the header row
+            continue
+        name = parts[2].strip()
+        if name:
+            modules.add(name)
+    return modules
+
+
+def imported_modules(command: List[str]) -> Set[str]:
+    """The set of modules imported when running ``boost <command>``.
+
+    Runs in a subprocess with a throwaway ``$HOME`` so a real ``~/.boost`` can
+    never influence which modules load (or leave state behind), and with
+    ``PYTHONPATH`` pointed at the repo so no editable install is required.
+    """
+    env = dict(os.environ)
+    with tempfile.TemporaryDirectory(prefix="boost-import-budget-") as home:
+        env["HOME"] = home
+        env["PYTHONPATH"] = str(ROOT)
+        env["BOOST_NO_AI"] = "1"
+        env.pop("BOOST_HOME", None)
+        proc = subprocess.run(
+            [sys.executable, "-X", "importtime", "-c",
+             "from boost_cli.cli import main; main(%r)" % (command,)],
+            cwd=str(ROOT), env=env, capture_output=True, text=True,
+        )
+    return parse_modules(proc.stderr)
+
+
+def leaks_for(modules: Set[str]) -> List[str]:
+    """Sorted denylisted modules present in ``modules`` (empty = clean)."""
+    return sorted(DENYLIST & modules)
+
+
+def check() -> Dict[str, dict]:
+    """Run every command; return ``{label: {"leaks": [...], "count": int}}``."""
+    report: Dict[str, dict] = {}
+    for command in COMMANDS:
+        mods = imported_modules(command)
+        report["boost " + " ".join(command)] = {
+            "leaks": leaks_for(mods),
+            "count": len(mods),
+        }
+    return report
+
+
+def main(argv: List[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    show_counts = "--list" in argv
+    report = check()
+
+    failed = False
+    for label, data in report.items():
+        if data["leaks"]:
+            failed = True
+            print("import-budget: FAIL %s imported %s"
+                  % (label, ", ".join(data["leaks"])))
+        if show_counts:
+            print("  %-16s %d modules" % (label, data["count"]))
+        if data["count"] > SOFT_MODULE_CEILING:
+            print("import-budget: note — %s imported %d modules (advisory "
+                  "ceiling %d); check for a new heavy dependency"
+                  % (label, data["count"], SOFT_MODULE_CEILING))
+
+    if failed:
+        print("\nimport-budget: heavy/optional modules must stay lazy — move "
+              "the import inside the function that needs it (see "
+              "scripts/import_budget.py DENYLIST).")
+        return 1
+    print("import-budget: OK — no heavy/optional module imported by %d common "
+          "commands" % len(COMMANDS))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

boost_skill_cli-1.0.155/tests/unit/test_import_budget.py

@@ -0,0 +1,135 @@
+"""Unit tests: scripts/import_budget.py — the startup lazy-import guard.
+
+The pure parsing/denylist logic is tested directly; a single integration test
+runs the real gate over the live interpreter so a genuine leak (a heavy module
+newly imported at startup) fails here too, not just in CI.
+"""
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+_SCRIPT = Path(__file__).resolve().parents[2] / "scripts" / "import_budget.py"
+
+
+def _load():
+    spec = importlib.util.spec_from_file_location("import_budget", _SCRIPT)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+pytestmark = pytest.mark.skipif(
+    not _SCRIPT.exists(), reason="repo-root scripts/ not reachable (e.g. mutation sandbox)")
+
+
+# A realistic slice of `python -X importtime` stderr (the real header + rows).
+_SAMPLE = """\
+import time: self [us] | cumulative | imported package
+import time:       120 |        120 |   _io
+import time:       200 |        900 |   urllib.request
+import time:        90 |         90 |     http.client
+import time:       300 |       1200 | boost_cli.cli
+import time:       150 |        150 |   sqlite_vec
+"""
+
+
+class TestParseModules:
+    def test_extracts_names_and_skips_header(self):
+        mod = _load()
+        names = mod.parse_modules(_SAMPLE)
+        assert "urllib.request" in names
+        assert "boost_cli.cli" in names
+        assert "sqlite_vec" in names
+        # the header row ("self [us] | cumulative | imported package") is not a
+        # module and must not be captured
+        assert "imported package" not in names
+        assert "cumulative" not in names
+
+    def test_strips_nesting_indent(self):
+        mod = _load()
+        # deeply nested rows keep only the dotted module name, no leading spaces
+        names = mod.parse_modules("import time:  90 |  90 |       a.b.c\n")
+        assert names == {"a.b.c"}
+
+    def test_ignores_non_importtime_lines(self):
+        mod = _load()
+        noise = "some other stderr line\nWARNING: whatever\n"
+        assert mod.parse_modules(noise) == set()
+
+    def test_ignores_malformed_rows(self):
+        mod = _load()
+        # a row missing the third field yields nothing rather than a bad name
+        assert mod.parse_modules("import time:   10 |   10\n") == set()
+
+
+class TestLeaksFor:
+    def test_flags_denylisted_modules_only(self):
+        mod = _load()
+        present = {"json", "os", "sqlite_vec", "boost_cli.core.dense", "urllib.request"}
+        assert mod.leaks_for(present) == ["boost_cli.core.dense", "sqlite_vec"]
+
+    def test_clean_set_has_no_leaks(self):
+        mod = _load()
+        assert mod.leaks_for({"json", "os", "boost_cli.cli", "urllib.request"}) == []
+
+    def test_result_is_sorted(self):
+        mod = _load()
+        present = {"ranx", "anticipation", "numpy", "torch"}
+        assert mod.leaks_for(present) == sorted(mod.DENYLIST & present)
+
+
+class TestMain:
+    def test_returns_1_and_reports_on_leak(self, monkeypatch, capsys):
+        mod = _load()
+        monkeypatch.setattr(mod, "check", lambda: {
+            "boost count": {"leaks": ["sqlite_vec"], "count": 210},
+        })
+        rc = mod.main([])
+        out = capsys.readouterr().out
+        assert rc == 1
+        assert "FAIL" in out and "sqlite_vec" in out and "boost count" in out
+
+    def test_returns_0_when_clean(self, monkeypatch, capsys):
+        mod = _load()
+        monkeypatch.setattr(mod, "check", lambda: {
+            "boost --help": {"leaks": [], "count": 177},
+        })
+        rc = mod.main([])
+        assert rc == 0
+        assert "OK" in capsys.readouterr().out
+
+    def test_list_flag_prints_counts(self, monkeypatch, capsys):
+        mod = _load()
+        monkeypatch.setattr(mod, "check", lambda: {
+            "boost list": {"leaks": [], "count": 201},
+        })
+        mod.main(["--list"])
+        assert "201 modules" in capsys.readouterr().out
+
+    def test_soft_ceiling_is_advisory_not_fatal(self, monkeypatch, capsys):
+        mod = _load()
+        over = mod.SOFT_MODULE_CEILING + 50
+        monkeypatch.setattr(mod, "check", lambda: {
+            "boost --help": {"leaks": [], "count": over},
+        })
+        rc = mod.main([])
+        # a high module count is a note, not a failure (import graphs differ
+        # across Python versions/platforms)
+        assert rc == 0
+        assert "advisory ceiling" in capsys.readouterr().out
+
+
+class TestIntegration:
+    def test_live_startup_has_no_heavy_imports(self):
+        """The real gate over this interpreter must be clean — a genuine
+        regression (a heavy module imported at startup) fails the suite here."""
+        mod = _load()
+        report = mod.check()
+        offenders = {label: data["leaks"]
+                     for label, data in report.items() if data["leaks"]}
+        assert not offenders, (
+            "heavy/optional modules leaked into startup: %s — keep the import "
+            "lazy (see scripts/import_budget.py)" % offenders)