lean-browser-use 0.0.0-stage → 0.1.0

package/reader/test_reader.py

@@ -0,0 +1,345 @@
+from reader_test_support import *
+
+@checks.mark.parametrize("url", ["file:///etc/passwd", "ftp://example.com", "data:text/html,hello",
+                                 "https://", "https://a:b" + "@" + "example.com", "https://example.com\r/", "http://example.com:bad"])
+def test_refused_url_shapes(url):
+    with checks.raises(reader.ReaderError) as exc:
+        reader.checked_address(url)
+    assert exc.value.code == 2
+    socket.getaddrinfo.assert_not_called()
+
+
+@checks.mark.parametrize("ip", ["127.0.0.1", ".".join(['10', '1', '2', '3']), ".".join(['169', '254', '169', '254']), ".".join(['100', '64', '1', '2']),
+                                "0.0.0.0", ".".join(['192', '168', '1', '1']), ".".join(['224', '0', '0', '1']), "::1", "fe80::1", "::ffff:127.0.0.1"])
+def test_refused_addresses(ip):
+    socket.getaddrinfo.side_effect = None
+    socket.getaddrinfo.return_value = [public_address(ip)]
+    with checks.raises(reader.ReaderError) as exc:
+        reader.checked_address("http://public.example")
+    assert exc.value.code == 2
+
+
+def test_every_dns_answer_checked():
+    socket.getaddrinfo.side_effect = None
+    socket.getaddrinfo.return_value = [public_address(), public_address(".".join(['10', '0', '0', '1']))]
+    with checks.raises(reader.ReaderError) as exc:
+        reader.checked_address("https://public.example")
+    assert exc.value.code == 2
+
+
+def test_dns_failure_is_fetch_exit_10():
+    socket.getaddrinfo.side_effect = socket.gaierror("not found")
+    with checks.raises(reader.ReaderError) as exc:
+        reader.fetch("https://missing.example")
+    assert exc.value.code == 10
+
+
+def test_redirect_refuses_private_target():
+    socket.getaddrinfo.side_effect = None
+    socket.getaddrinfo.return_value = [public_address("127.0.0.1")]
+    with checks.raises(reader.ReaderError) as exc:
+        reader.PublicRedirect().redirect_request(Request("https://public.example"), None,
+                                                 302, "redirect", {}, "http://127.0.0.1")
+    assert exc.value.code == 2
+
+
+def test_redirect_retains_checked_address():
+    socket.getaddrinfo.side_effect = None
+    socket.getaddrinfo.return_value = [public_address()]
+    req = reader.PublicRedirect().redirect_request(Request("https://public.example"), None,
+                                                  302, "redirect", {}, "https://other.example/page")
+    assert req.checked_address == public_address()
+
+
+def test_connector_uses_checked_sockaddr_without_dns():
+    sock = mock.Mock()
+    socket.socket.side_effect = None
+    socket.socket.return_value = sock
+    conn = reader.connection(reader.http.client.HTTPSConnection, "public.example", public_address())
+    assert conn._create_connection(("public.example", 443), 10) is sock
+    sock.connect.assert_called_once_with((PUBLIC_IP, 443))
+    socket.getaddrinfo.assert_not_called()
+
+
+def test_fetch_user_agent_size_bound_and_no_proxy(monkeypatch):
+    response = mock.MagicMock()
+    response.__enter__.return_value = response
+    response.headers.get_content_charset.return_value = "utf-8"
+    response.read.return_value = b"<html>ok</html>"
+    opener = mock.Mock()
+    opener.open.return_value = response
+    build = mock.Mock(return_value=opener)
+    monkeypatch.setattr(reader, "build_opener", build)
+    monkeypatch.setattr(reader, "checked_address", lambda url: public_address())
+    assert reader.fetch("https://public.example") == ("<html>ok</html>", "urllib")
+    req = opener.open.call_args.args[0]
+    assert "Mozilla/" in req.get_header("User-agent")
+    assert req.checked_address == public_address()
+    assert build.call_args.args[0].proxies == {}
+    response.read.assert_called_once_with(reader.FETCH_CAP + 1)
+    response.read.return_value = b"x" * (reader.FETCH_CAP + 1)
+    with checks.raises(reader.ReaderError) as exc:
+        reader.fetch("https://public.example")
+    assert exc.value.code == 10
+
+
+def test_fetch_unknown_charset_uses_utf8_replacement(monkeypatch):
+    response = mock.MagicMock()
+    response.__enter__.return_value = response
+    response.headers.get_content_charset.return_value = "reader-unknown-charset"
+    response.read.return_value = b"<p>caf\xc3\xa9 \xff</p>"
+    opener = mock.Mock()
+    opener.open.return_value = response
+    monkeypatch.setattr(reader, "build_opener", lambda *args: opener)
+    monkeypatch.setattr(reader, "checked_address", lambda url: public_address())
+    assert reader.fetch_urllib("https://public.example") == "<p>café \ufffd</p>"
+
+
+@checks.mark.parametrize("package", ["react", "zod"])
+def test_embedded_npm_two_params(package):
+    spec, _ = compile_npm()
+    result = reader.extract(spec, html(package))
+    assert result[0]["name"] == package
+    assert result[0]["license"] == "MIT"
+    assert result[0]["latest_version"]
+    assert result[0]["weekly_downloads"] > 0
+    assert result[0]["repository_url"].startswith("git+https://github.com/")
+    assert reader.failures(spec, result) == []
+
+
+def test_embedded_detection_and_json_parse():
+    value = {"value": 7}
+    encoded = json.dumps(json.dumps(value))
+    page = ('<script type="application/ld+json">{"@type":"Thing"}</script>'
+            '<script id="__NEXT_DATA__" type="application/json">{"props":{"items":[1]}}</script>'
+            '<script>window.__INITIAL_STATE__ = {"x":2}; alert("ignore");</script>'
+            f'<script>window.__context__ = JSON.parse({encoded});</script>'
+            '<script>window.__BAD_STATE__ = eval("private");</script><h1>Visible</h1>')
+    embedded, trimmed = reader.page_data(page)
+    assert embedded["ld+json:0"]["@type"] == "Thing"
+    assert embedded["__NEXT_DATA__"]["props"]["items"] == [1]
+    assert embedded["__INITIAL_STATE__"] == {"x": 2}
+    assert embedded["__context__"] == value
+    assert "__BAD_STATE__" not in embedded
+    assert "alert" not in trimmed and "<h1>Visible</h1>" in trimmed
+
+
+def test_embedded_list_rows_and_escaped_paths():
+    spec = {"type": "embedded_json", "source": "__NEXT_DATA__", "rows": "props.rows",
+            "paths": {"field": r"nested.key\.with\.dots.0"}}
+    page = '<script id="__NEXT_DATA__">{"props":{"rows":[{"nested":{"key.with.dots":["one"]}},{"nested":{"key.with.dots":["two"]}}]}}</script>'
+    assert reader.extract(spec, page) == [{"field": "one"}, {"field": "two"}]
+    assert reader.extract(spec, "<html></html>") == []
+    assert reader.path_get({"a": []}, "a.9") is None
+
+
+def test_compile_embedded_before_html_and_metadata():
+    spec, rows = compile_npm()
+    assert len(calls()) == 1
+    assert "embedded_json" in calls()[0] and "html" not in calls()[0]
+    for key in ("name", "url_template", "params", "type", "paths", "required", "want", "example",
+                "sample_output", "compiled_at", "compiled_by", "crawl4ai_version", "page_hash", "last_ok", "healed_at", "fetch_method"):
+        assert key in spec
+    assert spec["compiled_by"] == os.environ["READER_COMPILE_CMD"]
+    assert spec["sample_output"] == rows
+    assert spec["healed_at"] is None
+    assert len(spec["page_hash"]) == 64
+
+
+def test_compile_refines_with_named_failures(monkeypatch):
+    monkeypatch.setenv("STUB_MODE", "refine")
+    spec, rows = compile_npm()
+    assert len(calls()) == 2
+    assert calls()[1]["validation_failures"][0] == "row[0].license"
+    assert calls()[1]["validation_failures"][1].startswith("example row not found; nearest row: ")
+    assert "previous_schema" in calls()[1]
+    sample = calls()[1]["failing_row_samples"][0]
+    assert sample["index"] == 0
+    assert json.loads(sample["values"])["name"] == "react"
+    assert sample["outer_html"].startswith("<script")
+    assert len(sample["outer_html"]) <= 600
+    assert reader.failures(spec, rows) == []
+
+
+@checks.mark.parametrize("as_list", [False, True])
+def test_compile_anchor_refines_truncated_names(anchor_compile, capsys, as_list):
+    example = anchor_compile[1]
+    if as_list:
+        example = [example, {"model": "only the first example anchors"}]
+    assert reader.main(["compile", "prices", "--url", "https://public.example", "--want", "model prices",
+                        "--example", json.dumps(example)]) == 0
+    captured = capsys.readouterr()
+    assert json.loads(captured.out) == anchor_compile
+    assert captured.err == ""
+    assert len(calls()) == 2
+    failures = calls()[1]["validation_failures"]
+    assert len(failures) == 1
+    assert failures[0].startswith("example row not found; nearest row: ")
+    assert json.loads(failures[0].split("nearest row: ", 1)[1]) == {
+        "model": "Claude Sonnet 5", "input": 2, "output": 10}
+    assert calls()[1]["previous_schema"]["transforms"]["model"]
+    assert reader.load("prices")["sample_output"] == anchor_compile
+
+
+def test_compile_anchor_failure_keeps_existing_spec(anchor_compile, monkeypatch, capsys):
+    monkeypatch.setenv("STUB_MODE", "anchor-broken")
+    reader.save_json(reader.spec_path("prices"), {"preserved": True})
+    before = reader.spec_path("prices").read_bytes()
+    assert reader.main(["compile", "prices", "--url", "https://public.example", "--want", "model prices",
+                        "--example", json.dumps(anchor_compile[1])]) == 11
+    captured = capsys.readouterr()
+    assert captured.out == ""
+    assert "example row not found; nearest row:" in captured.err
+    assert len(calls()) == 4
+    assert reader.spec_path("prices").read_bytes() == before
+
+
+@checks.mark.parametrize("example,rows", [
+    ({"model": " Claude  Sonnet\t5.5 ", "input": 2}, [{"model": "Claude\nSonnet 5.5", "input": 2.0}]),
+    ({"model": "Claude", "input": 0}, [{"model": "other", "input": 1}, {"model": "Claude", "input": 0.0}]),
+    ({"cache": None}, [{"cache": None}]),
+])
+def test_compile_anchor_normalizes_whitespace_and_numbers(example, rows):
+    assert reader.anchor_failures(example, rows) == []
+
+
+@checks.mark.parametrize("example,rows", [
+    ({"model": "Claude"}, [{"model": "claude"}]),
+    ({"input": 2}, [{"input": "2"}]),
+    ({"input": 1}, [{"input": True}]),
+    ({"cache": None}, [{}]),
+    ({"model": "Claude", "input": 2}, [{"model": "Claude", "input": 1}, {"model": "other", "input": 2}]),
+    ({"model": "Claude"}, []),
+])
+def test_compile_anchor_requires_all_values_in_one_row(example, rows):
+    assert reader.anchor_failures(example, rows)[0].startswith("example row not found; nearest row: ")
+
+
+@checks.mark.parametrize("mode", ["broken", "fail"])
+def test_compile_stops_after_three_refinements(monkeypatch, mode):
+    monkeypatch.setenv("STUB_MODE", mode)
+    with checks.raises(reader.ReaderError) as exc:
+        compile_npm()
+    assert exc.value.code == 11
+    assert "3 refinements" in str(exc.value)
+    assert len(calls()) == (8 if mode == "fail" else 4)
+    assert not reader.spec_path("npm-package").exists()
+
+
+@checks.mark.parametrize("outcome", ["nonzero", "empty", "invalid"])
+def test_compile_retries_command_once_before_refinement(monkeypatch, tmp_path, outcome):
+    command = tmp_path / "flaky.py"
+    command.write_text(f'''import os, runpy, sys
+from pathlib import Path
+log = Path(os.environ["STUB_CALL_LOG"])
+if not log.exists():
+    prompt = sys.stdin.read()
+    import json
+    log.write_text(json.dumps(json.loads(prompt.split("INPUT JSON:\\n", 1)[1])) + "\\n")
+    print("temporary command failure", file=sys.stderr)
+    if {outcome!r} == "nonzero":
+        sys.exit(10)
+    if {outcome!r} == "invalid":
+        print("no schema returned")
+else:
+    runpy.run_path({str(DATA / "compile_stub.py")!r}, run_name="__main__")
+''')
+    monkeypatch.setenv("READER_COMPILE_CMD", shlex.join([sys.executable, str(command)]))
+    spec, rows = compile_npm()
+    assert len(calls()) == 2
+    assert calls()[0] == calls()[1]
+    assert "validation_failures" not in calls()[1]
+    assert reader.failures(spec, rows) == []
+
+
+@checks.mark.parametrize("outcome", ["nonzero", "invalid"])
+def test_compile_retry_limit_and_last_stderr(monkeypatch, tmp_path, outcome):
+    command = tmp_path / "failed.py"
+    command.write_text('''import json, os, sys
+payload = json.loads(sys.stdin.read().split("INPUT JSON:\\n", 1)[1])
+with open(os.environ["STUB_CALL_LOG"], "a") as stream:
+    stream.write(json.dumps(payload) + "\\n")
+print("discard-prefix:" + "x" * 320 + " final command diagnostic", file=sys.stderr)
+print("not JSON")
+sys.exit(int(sys.argv[1]))
+''')
+    monkeypatch.setenv("READER_COMPILE_CMD", shlex.join([
+        sys.executable, str(command), "10" if outcome == "nonzero" else "0"]))
+    with checks.raises(reader.ReaderError) as exc:
+        compile_npm()
+    assert exc.value.code == 11
+    assert len(calls()) == 8
+    for index in range(0, 8, 2):
+        assert calls()[index] == calls()[index + 1]
+    tail = ("discard-prefix:" + "x" * 320 + " final command diagnostic\n")[-300:]
+    assert str(exc.value).endswith("compile stderr: " + tail)
+    assert "discard-prefix" not in str(exc.value)
+
+
+def test_compile_css_refinement_carries_failing_rows(monkeypatch, tmp_path):
+    schema = {"type": "css", "schema": {"name": "prices", "baseSelector": "tr", "fields": [
+        {"name": "model", "selector": ".model", "type": "text"},
+        {"name": "input", "selector": ".input", "type": "text"},
+        {"name": "output", "selector": ".output", "type": "text"}]},
+        "transforms": {"input": "number", "output": "number"}}
+    command = tmp_path / "compile.py"
+    command.write_text('''import json, os, sys
+prompt = sys.stdin.read()
+payload = json.loads(prompt.split("INPUT JSON:\\n", 1)[1])
+with open(os.environ["STUB_CALL_LOG"], "a") as stream:
+    stream.write(json.dumps({"prompt": prompt, "payload": payload}) + "\\n")
+schema = json.loads(sys.argv[1])
+if payload.get("validation_failures"):
+    schema["schema"]["baseSelector"] = "table.prices tr"
+print(json.dumps(schema))
+''')
+    monkeypatch.setenv("READER_COMPILE_CMD", shlex.join([sys.executable, str(command), json.dumps(schema)]))
+    page = ('<table><tr><td>empty row is skipped by extraction</td></tr></table>'
+            '<table class="prices"><tr><td class="model">Claude</td>'
+            '<td class="input">2</td><td class="output">10</td></tr></table><table>')
+    for index in range(5):
+        page += f'<tr><td class="model">Unrelated {index}</td><td>{"x" * 800}</td></tr>'
+    page += '</table>'
+    spec, rows = reader.compile_spec("prices", "https://public.example", {}, "model prices",
+                                     {"model": "Claude", "input": 2, "output": 10}, page)
+    assert rows == [{"model": "Claude", "input": 2, "output": 10}]
+    assert spec["schema"]["baseSelector"] == "table.prices tr"
+    assert len(calls()) == 2
+    refinement = calls()[1]
+    assert "narrow baseSelector so only rows matching the want" in refinement["prompt"]
+    samples = refinement["payload"]["failing_row_samples"]
+    assert len(samples) == 3
+    assert [sample["index"] for sample in samples] == [1, 2, 3]
+    for index, sample in enumerate(samples):
+        assert json.loads(sample["values"]) == {"model": f"Unrelated {index}"}
+        assert f'Unrelated {index}</td>' in sample["outer_html"]
+        assert sample["outer_html"].startswith('<tr>')
+        assert len(sample["outer_html"]) == 600
+        assert len(sample["values"]) <= 600
+
+
+def test_compile_succeeds_on_third_refinement(monkeypatch, tmp_path):
+    command = tmp_path / "compile.py"
+    command.write_text(f'''import os, runpy
+from pathlib import Path
+log = Path(os.environ["STUB_CALL_LOG"])
+count = len(log.read_text().splitlines()) if log.exists() else 0
+os.environ["STUB_MODE"] = "broken" if count < 3 else "npm"
+runpy.run_path({str(DATA / "compile_stub.py")!r}, run_name="__main__")
+''')
+    monkeypatch.setenv("READER_COMPILE_CMD", shlex.join([sys.executable, str(command)]))
+    spec, rows = compile_npm()
+    assert len(calls()) == 4
+    assert reader.failures(spec, rows) == []
+
+
+def test_missing_compile_command_is_exit_11(monkeypatch):
+    monkeypatch.setenv("READER_COMPILE_CMD", "reader-command-does-not-exist")
+    with checks.raises(reader.ReaderError) as exc:
+        compile_npm()
+    assert exc.value.code == 11
+
+
+
+def load_tests(loader, suite, pattern):
+    return checks.suite(globals())

package/reader/test_reader_1.py

@@ -0,0 +1,309 @@
+from reader_test_support import *
+
+def test_validation_each_row_example_keys_and_numeric():
+    spec = {"required": ["name", "input"], "example": {"name": "Claude", "input": 1, "cache": None}}
+    assert reader.failures(spec, [{"name": "Claude", "input": 0, "cache": None}]) == []
+    result = reader.failures(spec, [{"name": "Claude", "input": 1, "cache": None}, {"name": " ", "input": "$2"}])
+    assert set(result) == {"row[1].name", "row[1].cache", "row[1].input must be numeric"}
+    assert "list rows >= 1" in reader.failures(spec, [])
+    assert reader.failures(spec, ["invalid"])
+
+
+def test_optional_numeric_fields_allow_null_but_keep_example_keys():
+    spec = {"required": ["model", "input", "output"],
+            "example": {"model": "Claude", "input": 2, "output": 10,
+                        "cache_write": 2.5, "cache_read": 0.2}}
+    row = {"model": "Claude", "input": 2, "output": 10, "cache_write": None, "cache_read": None}
+    assert reader.failures(spec, [row]) == []
+    assert reader.failures(spec, [{**row, "cache_read": "0.2"}]) == ["row[0].cache_read must be numeric"]
+    assert reader.failures(spec, [{**row, "input": None}]) == ["row[0].input"]
+    del row["cache_read"]
+    assert reader.failures(spec, [row]) == ["row[0].cache_read"]
+
+
+@checks.mark.parametrize("value", [None, "", "   ", "x", "ab", 0, 2.5, False, [], {}])
+def test_copy_check_skips_null_empty_short_strings_and_numbers(value):
+    spec = {"required": ["name"], "example": {"first": "example one", "second": "example two"}}
+    assert reader.failures(spec, [{"name": "row", "first": value, "second": value}]) == []
+
+
+def test_free_model_equal_numeric_prices_are_valid():
+    spec = {"required": ["model", "input", "output"],
+            "example": {"model": "paid", "input": 2, "output": 10}}
+    assert reader.failures(spec, [{"model": "free", "input": 0, "output": 0}]) == []
+
+
+@checks.mark.parametrize("example", [
+    {"version": "1.2.3", "license": "MIT"},
+    [{"version": "1.2.3", "license": "MIT"}],
+])
+def test_validation_rejects_cross_field_value_in_each_row(example):
+    spec = {"required": ["version", "license"], "example": example}
+    rows = [{"version": "4.6.7", "license": "MIT"},
+            {"version": "4.6.7", "license": "4.6.7"}]
+    assert reader.failures(spec, rows) == [
+        "row[1].license equals version; example values differ"]
+
+
+@checks.mark.parametrize("example", [None, {}, {"version": "same", "license": "same"}])
+def test_validation_allows_equal_values_without_differing_example(example):
+    spec = {"required": ["version", "license"], "example": example}
+    assert reader.failures(spec, [{"version": "same", "license": "same"}]) == []
+
+
+@checks.mark.parametrize("value, expected", [("144,621,339", 144621339), (0, 0),
+                                           ("1.25", 1.25), ("inf", None)])
+def test_number_transform_preserves_integral_type(value, expected):
+    row = reader.normalize([{"weekly_downloads": value}], {"weekly_downloads": "number"})[0]
+    assert row["weekly_downloads"] == expected
+    assert type(row["weekly_downloads"]) is type(expected)
+
+
+def test_cross_field_mismatch_heals_once_and_no_heal_exits_12(monkeypatch):
+    spec, _ = compile_npm()
+    spec["paths"]["license"] = spec["paths"]["latest_version"]
+    reader.save(spec)
+    monkeypatch.setattr(reader, "fetch", lambda url, **kwargs: (html(), "urllib"))
+    before = len(calls())
+    with checks.raises(reader.ReaderError) as exc:
+        reader.run_spec(reader.load("npm-package"), {}, True)
+    assert exc.value.code == 12
+    assert "latest_version equals license" in str(exc.value)
+    assert len(calls()) == before
+    result = reader.run_spec(reader.load("npm-package"), {}, False)
+    assert result["rows"][0]["license"] == "MIT"
+    assert len(calls()) == before + 1
+    assert reader.load("npm-package")["healed_at"]
+
+
+def test_run_and_heal_leave_shipped_specs_byte_for_byte_unchanged(monkeypatch):
+    spec, _ = compile_npm()
+    reader.save(spec)
+    spec["name"] = "broken"
+    spec["paths"]["license"] = "broken.path"
+    reader.save(spec)
+    directory = reader.spec_path("unused").parent
+
+    def hashes():
+        return {str(path): hashlib.sha256(path.read_bytes()).hexdigest()
+                for path in directory.rglob("*") if path.is_file()}
+
+    before = hashes()
+    monkeypatch.setattr(reader, "fetch", lambda url, **kwargs: (html(), "crwl"))
+    monkeypatch.setattr(reader, "now", lambda: "2026-10-23T12:00:00+00:00")
+    assert reader.main(["run", "npm-package"]) == 0
+    assert hashes() == before
+    state = json.loads(reader.state_path("npm-package").read_text())
+    assert state == {"last_ok": reader.now(), "healed_at": None,
+                     "fetch_method": "crwl", "page_hash": reader.page_hash(html())}
+    assert not reader.override_path("npm-package").exists()
+    assert reader.main(["run", "broken"]) == 0
+    assert hashes() == before
+    assert reader.override_path("broken").exists()
+    assert reader.load("broken")["healed_at"] == reader.now()
+    assert json.loads(reader.state_path("broken").read_text())["healed_at"] == reader.now()
+    # A later successful run uses the healed rules without another compile.
+    before_calls = len(calls())
+    assert reader.main(["run", "broken"]) == 0
+    assert len(calls()) == before_calls
+    assert hashes() == before
+
+
+def test_state_default_and_override_precedence(monkeypatch, tmp_path):
+    monkeypatch.delenv("READER_STATE_DIR")
+    monkeypatch.setattr(reader.Path, "home", lambda: tmp_path)
+    assert reader.state_path("npm-package") == tmp_path / ".cache/lean-browser-use/reader/npm-package.json"
+    spec, _ = compile_npm()
+    reader.save(spec)
+    healed = {**spec, "want": "healed request"}
+    reader.save(healed, runtime=True)
+    assert reader.load("npm-package")["want"] == "healed request"
+    reader.save_state(healed, html(), "crwl")
+    assert reader.load("npm-package")["fetch_method"] == "crwl"
+    # An explicit compile supersedes stale healed rules and fetch preferences.
+    reader.save(spec)
+    assert not reader.override_path("npm-package").exists()
+    assert not reader.state_path("npm-package").exists()
+    assert reader.load("npm-package")["want"] == spec["want"]
+
+
+def test_ls_reports_source_and_includes_state_only_specs(capsys):
+    spec, _ = compile_npm()
+    reader.save(spec)
+    assert reader.main(["ls"]) == 0
+    assert str(reader.spec_path("npm-package")) in capsys.readouterr().out
+    reader.save(spec, runtime=True)
+    spec["name"] = "state-only"
+    reader.save(spec, runtime=True)
+    assert reader.main(["ls"]) == 0
+    lines = capsys.readouterr().out.splitlines()
+    assert lines[0].endswith("\tsource")
+    assert len(lines) == 3
+    assert lines[1].endswith(str(reader.override_path("npm-package")))
+    assert lines[2].endswith(str(reader.override_path("state-only")))
+
+
+def test_run_valid_spec_never_calls_compile(monkeypatch):
+    spec, _ = compile_npm()
+    reader.save(spec)
+    before = len(calls())
+    fetch = mock.Mock(return_value=(html("zod"), "urllib"))
+    monkeypatch.setattr(reader, "fetch", fetch)
+    compiler = mock.Mock(side_effect=AssertionError("run must use no AI"))
+    monkeypatch.setattr(reader, "compile_spec", compiler)
+    result = reader.run_spec(reader.load("npm-package"), {"name": "zod"}, False)
+    assert result["rows"][0]["name"] == "zod"
+    assert result["meta"] == {"fetch_method": "urllib"}
+    fetch.assert_called_once_with("https://www.npmjs.com/package/zod", preferred="urllib")
+    compiler.assert_not_called()
+    assert len(calls()) == before
+    assert reader.load("npm-package")["last_ok"]
+
+
+@checks.mark.parametrize("heal", [False, True])
+def test_run_and_heal_ignore_stale_example(monkeypatch, capsys, heal):
+    spec, _ = compile_npm()
+    if heal:
+        spec["paths"]["license"] = "broken.selector"
+    reader.save(spec)
+    page = html().replace('"19.2.0"', '"20.0.0"')
+    monkeypatch.setattr(reader, "fetch", lambda url, **kwargs: (page, "urllib"))
+    before = len(calls())
+    assert reader.main(["run", "npm-package"]) == 0
+    captured = capsys.readouterr()
+    assert json.loads(captured.out)["rows"][0]["latest_version"] == "20.0.0"
+    assert captured.err == ""
+    assert len(calls()) == before + int(heal)
+    saved = reader.load("npm-package")
+    assert saved["example"]["latest_version"] == "19.2.0"
+    assert bool(saved["healed_at"]) == heal
+
+
+def test_run_heals_once_and_no_heal_second_break(monkeypatch):
+    spec, _ = compile_npm()
+    spec["paths"]["license"] = "broken.selector"
+    reader.save(spec)
+    monkeypatch.setattr(reader, "fetch", lambda url, **kwargs: (html(), "crwl"))
+    before = len(calls())
+    result = reader.run_spec(reader.load("npm-package"), {}, False)
+    assert result["rows"][0]["license"] == "MIT"
+    assert result["meta"] == {"fetch_method": "crwl"}
+    assert len(calls()) == before + 1
+    saved = reader.load("npm-package")
+    assert saved["healed_at"]
+    assert saved["fetch_method"] == "crwl"
+    saved["paths"]["license"] = "second.break"
+    reader.save(saved, runtime=True)
+    with checks.raises(reader.ReaderError) as exc:
+        reader.run_spec(reader.load("npm-package"), {}, True)
+    assert exc.value.code == 12
+    assert "license" in str(exc.value)
+    assert len(calls()) == before + 1
+
+
+def test_failed_heal_keeps_old_spec_and_exits_12(monkeypatch):
+    spec, _ = compile_npm()
+    spec["paths"]["license"] = "broken"
+    reader.save(spec)
+    before = reader.spec_path("npm-package").read_bytes()
+    monkeypatch.setattr(reader, "fetch", lambda url, **kwargs: (html(), "urllib"))
+    monkeypatch.setenv("STUB_MODE", "broken")
+    with checks.raises(reader.ReaderError) as exc:
+        reader.run_spec(reader.load("npm-package"), {}, False)
+    assert exc.value.code == 12
+    assert "license" in str(exc.value)
+    assert len(calls()) == 5  # initial compile plus one compile cycle of 4 attempts
+    assert reader.spec_path("npm-package").read_bytes() == before
+
+
+def test_run_fetch_failure_skips_heal(monkeypatch):
+    spec, _ = compile_npm()
+    monkeypatch.setattr(reader, "fetch", mock.Mock(side_effect=reader.ReaderError(10, "offline")))
+    with checks.raises(reader.ReaderError) as exc:
+        reader.run_spec(spec, {}, False)
+    assert exc.value.code == 10
+    assert len(calls()) == 1
+
+
+def test_css_subprocess_contract_and_snapshot(monkeypatch):
+    spec = json.loads((DATA / "pricing-schema.json").read_text())
+
+    def crwl(command, **kwargs):
+        assert command == [reader.crawl4ai_python(), str(ROOT / "crawl_helper.py"), "css"]
+        assert json.loads(kwargs["input"]) == {"html": "<html>snapshot</html>", "schema": spec["schema"]}
+        rows = [
+            {"model": "Claude Sonnet 5.5 Description", "input": "$2 / MTok", "output": "$10 / MTok",
+             "cache_write_5m": "$2.5", "cache_write_1h": "$4", "cache_read": "$0.10"}]
+        return subprocess.CompletedProcess(command, 0, json.dumps({"rows": rows}), "")
+
+    monkeypatch.setattr(reader.subprocess, "run", crwl)
+    result = reader.extract(spec, "<html>snapshot</html>")
+    assert result[0]["model"] == "Claude Sonnet 5.5"
+    assert result[0]["input"] == 2 and result[0]["output"] == 10
+    assert reader.failures(spec, result) == []
+
+
+def test_real_crawl4ai_pricing_snapshot():
+    if not Path(reader.crawl4ai_python()).exists() and not reader.shutil.which(reader.crawl4ai_python()):
+        checks.skip("optional crawl4ai integration; subprocess contract is tested separately")
+    spec = json.loads((DATA / "pricing-schema.json").read_text())
+    result = reader.extract(spec, (DATA / "claude-pricing.html").read_text())
+    assert len(result) == 16
+    assert len({row["model"] for row in result}) == 16
+    assert reader.failures(spec, result) == []
+    by_name = {row["model"]: row for row in result}
+    assert (by_name["Claude Fable 5.1"]["input"], by_name["Claude Fable 5.1"]["output"]) == (10, 50)
+    assert (by_name["Claude Sonnet 5.5"]["input"], by_name["Claude Sonnet 5.5"]["output"]) == (2, 10)
+
+
+def test_proxy_connector_uses_checked_sockaddr_without_dns(monkeypatch):
+    monkeypatch.setattr(socket, "socket", REAL_SOCKET)
+
+    async def check():
+        sock = mock.Mock()
+        create = mock.Mock(return_value=sock)
+        monkeypatch.setattr(socket, "socket", create)
+        connect = mock.AsyncMock()
+        monkeypatch.setattr(asyncio.get_running_loop(), "sock_connect", connect)
+        streams = (mock.Mock(), mock.Mock())
+        opened = mock.AsyncMock(return_value=streams)
+        monkeypatch.setattr(asyncio, "open_connection", opened)
+        assert await helper["pinned_connection"](public_address()) == streams
+        create.assert_called_once_with(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_TCP)
+        sock.setblocking.assert_called_once_with(False)
+        connect.assert_awaited_once_with(sock, (PUBLIC_IP, 443))
+        opened.assert_awaited_once_with(sock=sock)
+        socket.getaddrinfo.assert_not_called()
+
+    asyncio.run(check())
+
+
+@checks.mark.parametrize("raw_request", [b"GET http://public.example/ HTTP/1.1\r\n\r\n",
+                                       b"CONNECT public.example:443 HTTP/1.1\r\n\r\n"])
+@checks.mark.parametrize("addresses", [[], [public_address(), public_address("127.0.0.1")],
+                                      [public_address(".".join(['169', '254', '169', '254']))]])
+def test_proxy_refuses_unresolved_or_nonpublic_targets(monkeypatch, raw_request, addresses):
+    monkeypatch.setattr(socket, "socket", REAL_SOCKET)
+    socket.getaddrinfo.side_effect = None
+    socket.getaddrinfo.return_value = addresses
+    connector = mock.AsyncMock(side_effect=AssertionError("refused address must never connect"))
+    monkeypatch.setitem(helper["FilteringProxy"].handle.__globals__, "pinned_connection", connector)
+
+    async def check():
+        async with helper["FilteringProxy"]() as proxy:
+            source, client = await asyncio.open_connection("127.0.0.1", proxy.port)
+            client.write(raw_request)
+            await client.drain()
+            assert (await source.read()).startswith(b"HTTP/1.1 502")
+            assert len(proxy.blocked) == 1
+            assert "non-public" in proxy.blocked[0] or "no addresses" in proxy.blocked[0]
+            connector.assert_not_called()
+            client.close()
+            await client.wait_closed()
+
+    asyncio.run(asyncio.wait_for(check(), 10))
+
+
+
+def load_tests(loader, suite, pattern):
+    return checks.suite(globals())