boost-skill-cli 1.0.394__tar.gz → 1.0.396__tar.gz

{boost_skill_cli-1.0.394 → boost_skill_cli-1.0.396}/.lighthouserc.json

@@ -1,7 +1,7 @@
 {
   "ci": {
     "collect": {
-      "startServerCommand": "python3 -m http.server 8099 --bind 127.0.0.1",
+      "startServerCommand": "python3 scripts/serve_docs.py --port 8099 --bind 127.0.0.1",
       "startServerReadyPattern": "Serving HTTP",
       "url": [
         "http://127.0.0.1:8099/docs/index.html",

{boost_skill_cli-1.0.394 → boost_skill_cli-1.0.396}/PKG-INFO

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

{boost_skill_cli-1.0.394 → boost_skill_cli-1.0.396}/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.394'
-__version_tuple__ = version_tuple = (1, 0, 394)
+__version__ = version = '1.0.396'
+__version_tuple__ = version_tuple = (1, 0, 396)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.394 → boost_skill_cli-1.0.396}/boost_skill_cli.egg-info/PKG-INFO

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

{boost_skill_cli-1.0.394 → boost_skill_cli-1.0.396}/boost_skill_cli.egg-info/SOURCES.txt

@@ -253,6 +253,7 @@ docs/roadmap/items/langchain-langgraph-langsmith-integration.md
 docs/roadmap/items/layering-guard-import-linter.md
 docs/roadmap/items/license-compliance-scanning.md
 docs/roadmap/items/lighthouse-ci-on-the-pages-site.md
+docs/roadmap/items/lighthouse-scored-a-page-nobody-is-served.md
 docs/roadmap/items/lint-tap-misscopes-rule-workflow-entries.md
 docs/roadmap/items/list-rules-and-workflows.md
 docs/roadmap/items/localize-the-stored-bm25-snippet.md
@@ -428,6 +429,7 @@ scripts/post_deploy_smoke.py
 scripts/publish_eval_json.py
 scripts/release_guard.py
 scripts/release_preflight.py
+scripts/serve_docs.py
 style/README.md
 style/boost.css
 style/boost.js
@@ -597,6 +599,7 @@ tests/unit/test_scopes.py
 tests/unit/test_secretscan.py
 tests/unit/test_selfupdate.py
 tests/unit/test_serve.py
+tests/unit/test_serve_docs.py
 tests/unit/test_spin.py
 tests/unit/test_stackprobe.py
 tests/unit/test_staleness.py

boost_skill_cli-1.0.396/docs/roadmap/items/lighthouse-scored-a-page-nobody-is-served.md

@@ -0,0 +1,64 @@
+---
+id: lighthouse-scored-a-page-nobody-is-served
+board: code
+section: docsite
+status: shipped
+category: Docs · Performance
+complexity: S
+impact: High
+wow: 5
+note: the page was never the slow part — the harness sent 3.27x the bytes Pages sends
+order: 97
+owner: fix/lighthouse-serves-uncompressed
+pr: 455
+title: The performance gate was measuring a page nobody is served
+---
+<b>The board's Lighthouse score was decided by a missing HTTP header.</b> The gate serves the docs
+with <code>python3 -m http.server</code>, which has never sent <code>Content-Encoding</code>. GitHub
+Pages answers <code>content-encoding: gzip</code> for the same URL &mdash; checked against the live
+site. So every performance number this project has ever recorded for
+<code>roadmap.html</code> was measured on a document <b>3.27&times;</b> larger than the one a visitor
+receives.
+
+<b>The failing run says so itself.</b> In its own artifact,
+<code>uses-text-compression</code> scores <b>0</b> with an estimated saving of 404&nbsp;KiB, and
+<code>transferSize</code> 567,874 sits against <code>resourceSize</code> 567,685 &mdash; the bytes on
+the wire are the bytes on disk. Lighthouse throttles to <b>1,474.56&nbsp;kbps</b>, where 566&nbsp;KB
+is <b>3.08&nbsp;s</b> of download; the observed FCP was <b>3.63&nbsp;s</b>. There is nothing left
+over to explain.
+
+<b>And the score decomposes exactly.</b> FCP&nbsp;3,638&nbsp;ms scores 0.31 (&times;10) &middot;
+SI&nbsp;3,638&nbsp;ms 0.86 (&times;10) &middot; LCP&nbsp;3,858&nbsp;ms 0.53 (&times;25) &middot;
+TBT&nbsp;100&nbsp;ms 0.98 (&times;30) &middot; CLS&nbsp;0 1.00 (&times;25), which totals
+<b>79.35 &rarr; 0.79</b>, the reported figure to the digit. The entire 21-point deficit is FCP and
+LCP. Both are transfer-bound. Neither is about the page.
+
+<b>This is why two rounds of optimisation moved nothing.</b>
+[[roadmap-perf-budget-has-no-local-guard]] records collapsing card bodies into
+<code>&lt;details&gt;</code>, which cut laid-out body text 33% and moved the score by <b>0.00</b>,
+and trimming 3,066 characters of prose, which also moved it by <b>0.00</b>. Both changed
+<i>layout</i> work while the score was being decided by <i>transfer</i>. <code>content-visibility:
+auto</code> bought 0.01 &mdash; about all that was on the table, because TBT already scored 0.98.
+The conclusions drawn from those experiments were sound about what they measured and wrong about
+what they implied: the floor was lowered 0.85&nbsp;&rarr;&nbsp;0.80 and the raise back was declared
+"gated on making the page genuinely faster", when the page was never the slow part.
+
+<b>It also names the cheap local proxy that card called not obvious.</b> It is markup bytes &mdash;
+the dimension <code>scripts/page_budget.py</code> already measures, shipped by the same PR that
+declared the budget non-predictive. Compression is a near-constant factor here (roadmap.html 3.27&times;,
+index.html 3.38&times;, boost.css 2.99&times;), so bytes on disk track bytes on the wire, and bytes on
+the wire are what FCP is spending.
+
+<b>What shipped.</b> <code>scripts/serve_docs.py</code> &mdash; a stdlib static server that
+compresses exactly what Pages compresses (text, JS, JSON, XML, SVG; never images or fonts) and only
+when the client asks, so the raw path stays reachable. On the audited page that is
+<b>597,782&nbsp;&rarr;&nbsp;184,126&nbsp;B</b>, or <b>3.24&nbsp;s&nbsp;&rarr;&nbsp;1.00&nbsp;s</b> of
+download on Lighthouse's link. Nothing else about the harness changed &mdash; not even HTTP/1.1
+keep-alive, which was left off on purpose so the score move has one cause and not two.
+
+<b>What it deliberately is not.</b> A way to make the number look better. It is the opposite: the
+number now describes bytes someone is actually sent, so a floor raised against it means something.
+Twenty-two unit tests pin the behaviour, including that HEAD and GET agree on
+<code>Content-Length</code>, that an image is left alone, and that the rc's
+<code>startServerReadyPattern</code> still matches the banner &mdash; a drift there does not fail the
+job, it hangs it until timeout.

{boost_skill_cli-1.0.394 → boost_skill_cli-1.0.396}/docs/roadmap.html

@@ -125,7 +125,7 @@
       <div class="stat"><b>16</b><span>Shipped</span></div>
       <div class="stat"><b>1</b><span>Next up</span></div>
       <div class="stat"><b>7</b><span>Planned</span></div>
-      <div class="stat"><b>209</b><span>Loop finds</span></div>
+      <div class="stat"><b>210</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -7152,6 +7152,67 @@ value is that its code runs.</p>
           <span class="m">the eval.html genre, pointed at the LangChain stack — and it can only document what has shipped</span>
         </div>
       </article>
+
+      <article class="cap rcard" id="lighthouse-scored-a-page-nobody-is-served">
+        <div class="head"><span class="pill shipped">Shipped</span><span class="cat">Docs · Performance</span></div>
+        <h3>The performance gate was measuring a page nobody is served</h3>
+        <details class="cardbody"><summary>Write-up</summary>
+        <p><b>The board's Lighthouse score was decided by a missing HTTP header.</b> The gate serves the docs
+with <code>python3 -m http.server</code>, which has never sent <code>Content-Encoding</code>. GitHub
+Pages answers <code>content-encoding: gzip</code> for the same URL &mdash; checked against the live
+site. So every performance number this project has ever recorded for
+<code>roadmap.html</code> was measured on a document <b>3.27&times;</b> larger than the one a visitor
+receives.
+
+<b>The failing run says so itself.</b> In its own artifact,
+<code>uses-text-compression</code> scores <b>0</b> with an estimated saving of 404&nbsp;KiB, and
+<code>transferSize</code> 567,874 sits against <code>resourceSize</code> 567,685 &mdash; the bytes on
+the wire are the bytes on disk. Lighthouse throttles to <b>1,474.56&nbsp;kbps</b>, where 566&nbsp;KB
+is <b>3.08&nbsp;s</b> of download; the observed FCP was <b>3.63&nbsp;s</b>. There is nothing left
+over to explain.
+
+<b>And the score decomposes exactly.</b> FCP&nbsp;3,638&nbsp;ms scores 0.31 (&times;10) &middot;
+SI&nbsp;3,638&nbsp;ms 0.86 (&times;10) &middot; LCP&nbsp;3,858&nbsp;ms 0.53 (&times;25) &middot;
+TBT&nbsp;100&nbsp;ms 0.98 (&times;30) &middot; CLS&nbsp;0 1.00 (&times;25), which totals
+<b>79.35 &rarr; 0.79</b>, the reported figure to the digit. The entire 21-point deficit is FCP and
+LCP. Both are transfer-bound. Neither is about the page.
+
+<b>This is why two rounds of optimisation moved nothing.</b>
+[[roadmap-perf-budget-has-no-local-guard]] records collapsing card bodies into
+<code>&lt;details&gt;</code>, which cut laid-out body text 33% and moved the score by <b>0.00</b>,
+and trimming 3,066 characters of prose, which also moved it by <b>0.00</b>. Both changed
+<i>layout</i> work while the score was being decided by <i>transfer</i>. <code>content-visibility:
+auto</code> bought 0.01 &mdash; about all that was on the table, because TBT already scored 0.98.
+The conclusions drawn from those experiments were sound about what they measured and wrong about
+what they implied: the floor was lowered 0.85&nbsp;&rarr;&nbsp;0.80 and the raise back was declared
+"gated on making the page genuinely faster", when the page was never the slow part.
+
+<b>It also names the cheap local proxy that card called not obvious.</b> It is markup bytes &mdash;
+the dimension <code>scripts/page_budget.py</code> already measures, shipped by the same PR that
+declared the budget non-predictive. Compression is a near-constant factor here (roadmap.html 3.27&times;,
+index.html 3.38&times;, boost.css 2.99&times;), so bytes on disk track bytes on the wire, and bytes on
+the wire are what FCP is spending.
+
+<b>What shipped.</b> <code>scripts/serve_docs.py</code> &mdash; a stdlib static server that
+compresses exactly what Pages compresses (text, JS, JSON, XML, SVG; never images or fonts) and only
+when the client asks, so the raw path stays reachable. On the audited page that is
+<b>597,782&nbsp;&rarr;&nbsp;184,126&nbsp;B</b>, or <b>3.24&nbsp;s&nbsp;&rarr;&nbsp;1.00&nbsp;s</b> of
+download on Lighthouse's link. Nothing else about the harness changed &mdash; not even HTTP/1.1
+keep-alive, which was left off on purpose so the score move has one cause and not two.
+
+<b>What it deliberately is not.</b> A way to make the number look better. It is the opposite: the
+number now describes bytes someone is actually sent, so a floor raised against it means something.
+Twenty-two unit tests pin the behaviour, including that HEAD and GET agree on
+<code>Content-Length</code>, that an image is left alone, and that the rc's
+<code>startServerReadyPattern</code> still matches the banner &mdash; a drift there does not fail the
+job, it hangs it until timeout.</p></details>
+        <div class="meta">
+          <span class="m">Complexity <b>S</b></span>
+          <span class="m hi">Impact <b>High</b></span>
+          <span class="m">Wow <b class="wow">★★★★★</b></span>
+          <span class="m">the page was never the slow part — the harness sent 3.27x the bytes Pages sends</span>
+        </div>
+      </article>
       <!-- /ROADMAP:cards -->
 
     </div>

{boost_skill_cli-1.0.394 → boost_skill_cli-1.0.396}/scripts/page_budget.py

@@ -35,6 +35,15 @@ fire on the next shipped card and be raised reflexively, which is worse than no
 check: it teaches people that the number is noise. These are set to catch a step
 change — roughly a doubling — not ordinary growth.
 
+TWO NUMBERS GATE, NOT ONE. `test_the_board_still_has_headroom_to_grow` fails the
+board at 80% of its ceiling, so the number that actually stops a build is
+`elements * 0.8`, not `elements`. Choosing the ceiling without that factor is
+how the first pair of numbers here missed its own stated intent: 10,000 was set
+against a measured 7,484, which reads as 1.34x but gated at 8,000 — 516 elements
+of usable room, about ten cards, for a budget whose docstring said it bounded a
+doubling. It was reached in a day. Pick the ceiling so that FOUR FIFTHS of it is
+the step change worth waking up for.
+
 Run:  python3 scripts/page_budget.py [-v]
 """
 from __future__ import annotations
@@ -64,11 +73,18 @@ class Budget(NamedTuple):
 
 
 #: Per-page ceilings; ``*`` is the default for any page without its own row.
-#: Measured 2026-08-02 (bytes / elements / depth):
-#:   roadmap.html 525,472 / 7,484 / 10   ·   commands.html 86,026 / 1,512 /  8
-#:   index.html    58,352 /   488 / 12   ·   mcp-hub.html  51,162 /   607 / 10
-#:   design-roadmap 45,931 /  727 / 10   ·   eval.html     36,320 /   528 / 10
-#:   carousel.html 27,829 /   328 / 14   ·   adapters.html 23,559 /   306 / 11
+#: Measured 2026-08-03 (bytes / elements / depth):
+#:   roadmap.html 565,883 / 7,951 / 10   ·   commands.html 86,070 / 1,512 /  8
+#:   index.html    63,239 /   488 / 12   ·   mcp-hub.html  51,163 /   607 / 10
+#:   design-roadmap 48,187 /  746 / 10   ·   eval.html     36,321 /   528 / 10
+#:   carousel.html 27,830 /   328 / 14   ·   adapters.html 23,560 /   306 / 11
+#:   demo.html     21,348 /   119 /  9   ·   chat.html     11,681 /   126 / 10
+#:
+#: The board moved 7,484 -> 7,951 elements in the 24 hours after these ceilings
+#: shipped, which is the growth rate they were written to tolerate rather than a
+#: step change — and it was enough to reach the 8,000 gate. Regenerate this block
+#: with `python3 scripts/page_budget.py -v` when you raise a ceiling; a stale
+#: measurement is what makes the next raise a guess.
 #:
 #: Depth is uniform and tight on purpose. Every page here nests 8-14 deep and
 #: none has any reason to go deeper, so unlike bytes and elements it is not a
@@ -76,9 +92,11 @@ class Budget(NamedTuple):
 #: and the roadmap board is no more nested than the smallest page on the site.
 BUDGETS: Dict[str, Budget] = {
     "roadmap.html": Budget(
-        kbytes=720, elements=10_000, depth=20,
+        kbytes=1_200, elements=16_000, depth=20,
         why="the code board — already 5x Lighthouse's DOM-size failure "
-            "threshold, so this bounds a step change, not ordinary growth"),
+            "threshold, so this bounds a step change, not ordinary growth; "
+            "raised deliberately 2026-08-03 from 720/10,000, which gated at "
+            "8,000 and was reached by ordinary card growth in a day"),
     "commands.html": Budget(
         kbytes=180, elements=3_000, depth=20,
         why="generated from COMMANDS, so it grows a block per new command"),

boost_skill_cli-1.0.396/scripts/serve_docs.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Serve the repo over HTTP the way GitHub Pages serves it: compressed.
+
+WHY THIS EXISTS. The `lighthouse` job scored `docs/roadmap.html` at 0.79 against
+a 0.80 floor — three runs, 0.79 every time, so not the sampling luck that the
+floor was lowered to 0.80 to escape. Pulled from that job's own artifact, the
+score decomposes exactly:
+
+    FCP  3,638 ms  score 0.31  x10       SI  3,638 ms  score 0.86  x10
+    LCP  3,858 ms  score 0.53  x25      TBT    100 ms  score 0.98  x30
+    CLS      0     score 1.00  x25   ->  3.1 + 8.6 + 13.25 + 29.4 + 25 = 79.35
+
+The whole 21-point deficit is FCP and LCP. Both are transfer-bound, and the same
+report says why: `uses-text-compression` scores **0**, with `transferSize`
+567,874 against `resourceSize` 567,685 — the document arrives uncompressed,
+because `python3 -m http.server` has never sent `Content-Encoding`. Lighthouse
+throttles to 1,474.56 kbps, so 567,685 bytes is 3.08 s of download for the HTML
+alone, which is the 3.6 s FCP with nothing left to explain.
+
+GitHub Pages, meanwhile, answers `content-encoding: gzip` for that exact URL —
+checked against the live site, not assumed. Lighthouse estimates gzip takes the
+document to 173,407 B and the stylesheet to 9,831 B, saving 404 KiB and 1,950 ms.
+
+So the job was scoring a page 3.3x larger than the one any visitor receives, and
+every conclusion drawn from it inherited that. Two rounds of work had already
+gone into "making the page faster" — collapsing card bodies into `<details>`
+(0.00) and trimming 3,066 characters of prose (0.00) — and neither could have
+moved the number, because both changed *layout* work while the score was being
+decided by *transfer* bytes. `content-visibility: auto` bought 0.01, which is
+about all that was available: TBT already scores 0.98.
+
+WHAT THIS IS NOT. It is not a way to make the number look better. It is the
+opposite — it makes the number mean something, by measuring the bytes that are
+actually sent. If the page is genuinely slow once compressed, this reports that,
+and the floor should be raised until it hurts.
+
+WHAT IT COMPRESSES. The types Pages compresses: text/*, JavaScript, JSON, XML
+and SVG. Never images or fonts, which are already compressed and would only cost
+CPU. And only when the client asks — a client that sends no `Accept-Encoding`
+gets the raw bytes, which is what makes the uncompressed path still reachable.
+
+Run:  python3 scripts/serve_docs.py [--port 8099] [--bind 127.0.0.1]
+"""
+from __future__ import annotations
+
+import argparse
+import gzip
+import io
+import os
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from typing import Optional
+
+#: Compressed by GitHub Pages, and worth compressing: markup, styles, scripts
+#: and data. `image/svg+xml` is in because SVG is text; every other image type
+#: and every font is deliberately out — already-compressed bytes only get bigger.
+COMPRESSIBLE = (
+    "text/",
+    "application/javascript",
+    "application/json",
+    "application/xml",
+    "application/xhtml+xml",
+    "image/svg+xml",
+)
+
+#: gzip's default. Level 9 costs measurably more CPU for ~1% fewer bytes, and a
+#: harness that is slower than the thing it measures gets switched off.
+LEVEL = 6
+
+#: `.lighthouserc.json` waits for this substring before it starts collecting.
+#: `test_serve_docs.py` pins the two together, because the failure mode when
+#: they drift is a job that hangs until it times out rather than one that says
+#: what went wrong.
+READY = "Serving HTTP"
+
+
+def compressible(ctype: Optional[str]) -> bool:
+    """True if `ctype` is a type Pages would compress."""
+    if not ctype:
+        return False
+    return ctype.split(";")[0].strip().startswith(COMPRESSIBLE)
+
+
+class GzipHandler(SimpleHTTPRequestHandler):
+    """`SimpleHTTPRequestHandler`, plus the `Content-Encoding` Pages sends.
+
+    `protocol_version` is left at the base class's HTTP/1.0 on purpose. Raising
+    it to 1.1 would enable keep-alive and cut handshakes, which moves the same
+    metrics compression moves — and then the score change this PR reports would
+    have two causes and no way to separate them. One variable at a time.
+    """
+
+    def send_head(self):  # type: ignore[override]
+        """Return the body to send, gzipped when the client asked and it helps.
+
+        Overriding `send_head` rather than `do_GET` keeps HEAD honest: the base
+        class calls this for both verbs, so a HEAD reports the same
+        `Content-Length` a GET would actually deliver.
+        """
+        path = self.translate_path(self.path)
+        if os.path.isdir(path):
+            return super().send_head()          # directory index: not worth it
+        accepted = self.headers.get("Accept-Encoding", "")
+        ctype = self.guess_type(path)
+        if "gzip" not in accepted or not compressible(ctype):
+            return super().send_head()
+        try:
+            with open(path, "rb") as fh:
+                raw = fh.read()
+            mtime = os.stat(path).st_mtime
+        except OSError:
+            return super().send_head()          # 404/403 wording stays the base
+        # mtime=0: the gzip header otherwise carries a timestamp, which would
+        # make two runs of the same file differ byte for byte and turn any
+        # future "did the payload change?" check into noise.
+        body = gzip.compress(raw, LEVEL, mtime=0)
+        self.send_response(200)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Encoding", "gzip")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Last-Modified", self.date_time_string(mtime))
+        self.end_headers()
+        return io.BytesIO(body)
+
+    def log_message(self, fmt, *args):
+        """Quiet. Three Lighthouse runs over two pages is a lot of 200 lines."""
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="serve_docs.py", description=__doc__)
+    ap.add_argument("--port", type=int, default=8099)
+    ap.add_argument("--bind", default="127.0.0.1")
+    ap.add_argument("--directory", default=os.getcwd())
+    args = ap.parse_args(argv)
+
+    os.chdir(args.directory)
+    httpd = ThreadingHTTPServer((args.bind, args.port), GzipHandler)
+    print("%s on %s port %d (gzip)" % (READY, args.bind, args.port), flush=True)
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        httpd.server_close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{boost_skill_cli-1.0.394 → boost_skill_cli-1.0.396}/setup.cfg

@@ -14,6 +14,7 @@ also_copy =
 	CODE_OF_CONDUCT.md
 	evals/
 	Makefile
+	.lighthouserc.json
 
 [egg_info]
 tag_build = 

{boost_skill_cli-1.0.394 → boost_skill_cli-1.0.396}/tests/unit/test_page_budget.py

@@ -149,3 +149,23 @@ class TestTheShippedPages:
         assert elements < ceiling * 0.8, (
             "roadmap.html is at %d of %d elements — raise the ceiling in "
             "BUDGETS deliberately" % (elements, ceiling))
+
+    @pytest.mark.skipif(not (_ROOT / "docs" / "roadmap.html").exists(),
+                        reason="board absent")
+    def test_the_board_has_byte_headroom_too(self):
+        """Bytes had the ceiling but not the warning — the same hole, one over.
+
+        The element ceiling gets an early warning at 80% so the raise is a
+        decision; `kbytes` had none, so it would have gone from green straight
+        to a red required job with no step in between. When this was written the
+        board sat at 565,883 B — 78.6% of the then-720 kB ceiling, 10,117 B
+        short of it, which is two to six more cards at the 1.8-5.5 kB the four
+        then queued each added.
+        """
+        m = _load()
+        nbytes, _e, _d = m.measure(
+            (_ROOT / "docs" / "roadmap.html").read_text(encoding="utf-8"))
+        ceiling = m.BUDGETS["roadmap.html"].kbytes * 1000
+        assert nbytes < ceiling * 0.8, (
+            "roadmap.html is at %d kB of %d kB — raise the ceiling in BUDGETS "
+            "deliberately" % (nbytes // 1000, ceiling // 1000))

boost_skill_cli-1.0.396/tests/unit/test_serve_docs.py

@@ -0,0 +1,197 @@
+"""Unit tests: scripts/serve_docs.py — serving docs the way Pages serves them.
+
+WHY THIS FILE EXISTS. The `lighthouse` job scored `roadmap.html` 0.79 three
+times against a 0.80 floor while `uses-text-compression` scored 0 and
+`transferSize` equalled `resourceSize` — the harness served the document
+uncompressed, which GitHub Pages does not. These tests pin the properties that
+makes true: compressible types are compressed, already-compressed types are left
+alone, a client that does not ask still gets raw bytes, and the headers describe
+the bytes actually sent.
+
+NO SOCKET IS BOUND. The handler is driven over an in-memory pair of buffers
+instead of a listening port. That is not only for the sandboxes that refuse to
+bind one — a test that needs a free port is a test that fails on a busy machine
+for reasons having nothing to do with the code under test.
+"""
+from __future__ import annotations
+
+import gzip
+import importlib.util
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+_ROOT = Path(__file__).resolve().parents[2]
+_SCRIPT = _ROOT / "scripts" / "serve_docs.py"
+
+pytestmark = pytest.mark.skipif(
+    not _SCRIPT.exists(), reason="repo-root script not reachable")
+
+
+def _load():
+    spec = importlib.util.spec_from_file_location("serve_docs", _SCRIPT)
+    assert spec and spec.loader
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+class _Wire(io.BytesIO):
+    """A write buffer the handler is allowed to `close()` without losing it."""
+
+    def close(self):
+        # Not discarding the bytes is the whole point: the handler closes its
+        # `wfile` in `finish()`, and a real BytesIO would drop the response.
+        pass
+
+
+class _Socket:
+    """Just enough socket for `BaseHTTPRequestHandler.setup()`."""
+
+    def __init__(self, request: bytes):
+        self._in = io.BytesIO(request)
+        self.out = _Wire()
+
+    def makefile(self, mode="r", *args, **kwargs):
+        return self.out if "w" in mode else self._in
+
+    def close(self):
+        pass
+
+    # `BaseHTTPRequestHandler.finish()` may flush and shut the connection down.
+    def shutdown(self, how):
+        pass
+
+    def sendall(self, data):
+        self.out.write(data)
+
+
+def _request(mod, target, accept_encoding=None, method="GET"):
+    """Run one request through `GzipHandler`; return `(headers, body)`."""
+    lines = ["%s %s HTTP/1.0" % (method, target), "Host: 127.0.0.1"]
+    if accept_encoding:
+        lines.append("Accept-Encoding: %s" % accept_encoding)
+    raw = ("\r\n".join(lines) + "\r\n\r\n").encode()
+    sock = _Socket(raw)
+    mod.GzipHandler(sock, ("127.0.0.1", 41234), None)
+    head, _sep, body = sock.out.getvalue().partition(b"\r\n\r\n")
+    headers = {}
+    for line in head.decode("latin-1").split("\r\n")[1:]:
+        if ":" in line:
+            k, _c, v = line.partition(":")
+            headers[k.strip().lower()] = v.strip()
+    return headers, body
+
+
+@pytest.fixture
+def site(tmp_path, monkeypatch):
+    """A tiny two-file site as the process CWD, plus the loaded module."""
+    (tmp_path / "page.html").write_text("<p>%s</p>" % ("hello " * 400),
+                                        encoding="utf-8")
+    # A PNG header followed by noise: already-compressed bytes, so gzipping it
+    # would spend CPU to make it bigger.
+    (tmp_path / "pic.png").write_bytes(
+        b"\x89PNG\r\n\x1a\n" + bytes(range(256)) * 8)
+    monkeypatch.chdir(tmp_path)
+    return _load(), tmp_path
+
+
+class TestWhatGetsCompressed:
+    def test_markup_is_gzipped_and_round_trips(self, site):
+        mod, root = site
+        headers, body = _request(mod, "/page.html", "gzip")
+        assert headers["content-encoding"] == "gzip"
+        assert gzip.decompress(body) == (root / "page.html").read_bytes()
+
+    def test_the_length_header_describes_the_bytes_sent(self, site):
+        # A Content-Length taken from the uncompressed file is how a client
+        # ends up waiting for bytes that already arrived.
+        mod, _root = site
+        headers, body = _request(mod, "/page.html", "gzip")
+        assert int(headers["content-length"]) == len(body)
+
+    def test_compression_actually_shrinks_the_document(self, site):
+        mod, _root = site
+        _h, gz = _request(mod, "/page.html", "gzip")
+        _h2, raw = _request(mod, "/page.html")
+        assert len(gz) < len(raw) / 4, (
+            "the point of this harness is the size difference: %d vs %d"
+            % (len(gz), len(raw)))
+
+    def test_an_image_is_not_compressed(self, site):
+        # Already-compressed bytes: gzip costs CPU and adds bytes, and Pages
+        # does not do it either.
+        mod, _root = site
+        headers, _body = _request(mod, "/pic.png", "gzip")
+        assert "content-encoding" not in headers
+
+    def test_a_client_that_does_not_ask_gets_raw_bytes(self, site):
+        # The uncompressed path has to stay reachable — it is what `curl` with
+        # no header gets, and what any tool measuring raw weight expects.
+        mod, _root = site
+        headers, body = _request(mod, "/page.html")
+        assert "content-encoding" not in headers
+        assert body.startswith(b"<p>hello")
+
+    def test_a_head_reports_the_compressed_length(self, site):
+        # HEAD and GET must agree, or a client sizes the response wrong. This
+        # is why the override is on `send_head` and not on `do_GET`.
+        mod, _root = site
+        get_h, get_body = _request(mod, "/page.html", "gzip")
+        head_h, head_body = _request(mod, "/page.html", "gzip", method="HEAD")
+        assert head_body == b""
+        assert head_h["content-length"] == get_h["content-length"]
+        assert int(head_h["content-length"]) == len(get_body)
+
+    def test_a_missing_file_is_still_a_404(self, site):
+        mod, _root = site
+        sock = _Socket(b"GET /nope.html HTTP/1.0\r\nAccept-Encoding: gzip\r\n\r\n")
+        mod.GzipHandler(sock, ("127.0.0.1", 41234), None)
+        assert b"404" in sock.out.getvalue().split(b"\r\n")[0]
+
+
+class TestTheTypeTable:
+    @pytest.mark.parametrize("ctype", [
+        "text/html", "text/html; charset=utf-8", "text/css",
+        "application/javascript", "application/json", "image/svg+xml",
+    ])
+    def test_text_shaped_types_compress(self, ctype):
+        assert _load().compressible(ctype)
+
+    @pytest.mark.parametrize("ctype", [
+        "image/png", "image/webp", "font/woff2", "application/zip", "", None,
+    ])
+    def test_binary_types_do_not(self, ctype):
+        assert not _load().compressible(ctype)
+
+
+class TestTheHarnessAgrees:
+    def test_the_ready_line_matches_what_lighthouse_waits_for(self):
+        """A drift here hangs the job until it times out instead of failing.
+
+        `startServerReadyPattern` is a regex lighthouse-ci watches stdout for
+        before it starts collecting. If the script's banner stops matching, the
+        job does not say "banner changed" — it waits, then dies of timeout.
+        """
+        rc = json.loads(
+            (_ROOT / ".lighthouserc.json").read_text(encoding="utf-8"))
+        collect = rc["ci"]["collect"]
+        assert collect["startServerReadyPattern"] in _load().READY
+
+    def test_the_rc_starts_this_script(self):
+        rc = json.loads(
+            (_ROOT / ".lighthouserc.json").read_text(encoding="utf-8"))
+        assert "serve_docs.py" in rc["ci"]["collect"]["startServerCommand"], (
+            "plain `http.server` is what served the page uncompressed in the "
+            "first place")
+
+    def test_the_port_the_rc_serves_is_the_port_it_audits(self):
+        # Two numbers in one file that have to match, and nothing checked them.
+        rc = json.loads(
+            (_ROOT / ".lighthouserc.json").read_text(encoding="utf-8"))
+        collect = rc["ci"]["collect"]
+        port = collect["startServerCommand"].split("--port")[1].split()[0]
+        for url in collect["url"]:
+            assert ":%s/" % port in url, url