dirsql 0.4.109__tar.gz → 0.4.111__tar.gz

{dirsql-0.4.109 → dirsql-0.4.111}/Cargo.lock

@@ -573,7 +573,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql"
-version = "0.4.109"
+version = "0.4.111"
 dependencies = [
  "assert_cmd",
  "axum",
@@ -625,7 +625,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.4.109"
+version = "0.4.111"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.4.109 → dirsql-0.4.111}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.4.109
+Version: 0.4.111
 Requires-Dist: bin-shim>=0.1
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index

{dirsql-0.4.109 → dirsql-0.4.111}/docs/reference/cli.md

@@ -237,6 +237,22 @@ On startup the server prints `Running at <host>:<port>` to stdout. It runs
 until it receives `SIGINT` (Ctrl-C) or `SIGTERM`, then drains in-flight
 requests, closes open `/events` streams, and exits.
 
+Pass `--frontend` to serve the bundled dirsql SQL explorer shell at `/` on
+the same origin as the HTTP API. It works offline and prints `Frontend at
+http://<host>:<actual-port>/` without opening a browser. With `--port 0`, the
+printed URL uses the assigned port. The initial shell shows server status;
+query controls are coming in a subsequent update.
+
+```bash
+dirsql server --frontend
+dirsql server --frontend -c .dirsql.toml
+```
+
+The shell reads `GET /frontend/state`: `{"error":null}` when the index is
+ready, or HTTP `503` with `{"error":"<diagnostic>"}` when config loading
+fails. Fix the config and restart the server. Without `--frontend`, the `/`
+and `/frontend/state` routes return `404`.
+
 ### Flags
 
 Config flags are subcommand-local: pass them after `server`
@@ -247,6 +263,7 @@ Config flags are subcommand-local: pass them after `server`
 | `-c, --config <path>` | none | Path to a [config file](./config.md). **Repeatable** (`-c a -c b`): the configs load and merge in argv order — see [Composing multiple configs](./config.md#composing-multiple-configs). The index root is the **invocation directory** (the current working directory) and governs path-tables; a config's `[[table]]` globs anchor at **that config's own directory** (see [glob anchor](./config.md#glob-anchor)), so `--config /elsewhere/.dirsql.toml` indexes `/elsewhere`, from any working directory. With none given, **no named tables are defined** — query the filesystem with a [path-table](./path-tables.md) (`FROM './'`). A `./.dirsql.toml` on disk is **not** auto-loaded; pass it explicitly. A `-c` naming a file that does not exist is an [error](#degraded-mode). |
 | `--host <addr>` | `localhost` | Bind address. |
 | `--port <n>` | `7117` | TCP port to bind. |
+| `--frontend` | off | Serve the bundled SQL explorer shell and print its URL. |
 | `--cors-origin <origin>` | off | Let browser pages on `<origin>` (an exact origin such as `http://localhost:3202`, or `*` for any) call `/query` and open `/events`. See [Cross-origin requests](#cross-origin-requests). |
 | `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches under the platform cache directory (`$XDG_CACHE_HOME/dirsql/<root hash>/cache.db` on Linux), outside the root; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
 | `--no-ignore` | off | Scan files a `.gitignore` would hide. [Path-tables](./path-tables.md#skip-rules) respect `.gitignore` files by default; this flag restores the full walk. The built-in `.git` skip and configured `ignore` patterns still apply. Also available on [`dirsql query`](#dirsql-query). |

{dirsql-0.4.109 → dirsql-0.4.111}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.4.109"
+version = "0.4.111"
 # abi3 note: the `abi3-py310` pyo3 feature (below) builds ONE stable-ABI
 # `cp310-abi3` wheel per platform that loads on every CPython >= 3.10
 # (matching `pyproject.toml`'s `requires-python = ">=3.10"`), instead of

{dirsql-0.4.109/packages/rust → dirsql-0.4.111/packages/python}/docs/reference/cli.md

@@ -237,6 +237,22 @@ On startup the server prints `Running at <host>:<port>` to stdout. It runs
 until it receives `SIGINT` (Ctrl-C) or `SIGTERM`, then drains in-flight
 requests, closes open `/events` streams, and exits.
 
+Pass `--frontend` to serve the bundled dirsql SQL explorer shell at `/` on
+the same origin as the HTTP API. It works offline and prints `Frontend at
+http://<host>:<actual-port>/` without opening a browser. With `--port 0`, the
+printed URL uses the assigned port. The initial shell shows server status;
+query controls are coming in a subsequent update.
+
+```bash
+dirsql server --frontend
+dirsql server --frontend -c .dirsql.toml
+```
+
+The shell reads `GET /frontend/state`: `{"error":null}` when the index is
+ready, or HTTP `503` with `{"error":"<diagnostic>"}` when config loading
+fails. Fix the config and restart the server. Without `--frontend`, the `/`
+and `/frontend/state` routes return `404`.
+
 ### Flags
 
 Config flags are subcommand-local: pass them after `server`
@@ -247,6 +263,7 @@ Config flags are subcommand-local: pass them after `server`
 | `-c, --config <path>` | none | Path to a [config file](./config.md). **Repeatable** (`-c a -c b`): the configs load and merge in argv order — see [Composing multiple configs](./config.md#composing-multiple-configs). The index root is the **invocation directory** (the current working directory) and governs path-tables; a config's `[[table]]` globs anchor at **that config's own directory** (see [glob anchor](./config.md#glob-anchor)), so `--config /elsewhere/.dirsql.toml` indexes `/elsewhere`, from any working directory. With none given, **no named tables are defined** — query the filesystem with a [path-table](./path-tables.md) (`FROM './'`). A `./.dirsql.toml` on disk is **not** auto-loaded; pass it explicitly. A `-c` naming a file that does not exist is an [error](#degraded-mode). |
 | `--host <addr>` | `localhost` | Bind address. |
 | `--port <n>` | `7117` | TCP port to bind. |
+| `--frontend` | off | Serve the bundled SQL explorer shell and print its URL. |
 | `--cors-origin <origin>` | off | Let browser pages on `<origin>` (an exact origin such as `http://localhost:3202`, or `*` for any) call `/query` and open `/events`. See [Cross-origin requests](#cross-origin-requests). |
 | `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches under the platform cache directory (`$XDG_CACHE_HOME/dirsql/<root hash>/cache.db` on Linux), outside the root; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
 | `--no-ignore` | off | Scan files a `.gitignore` would hide. [Path-tables](./path-tables.md#skip-rules) respect `.gitignore` files by default; this flag restores the full walk. The built-in `.git` skip and configured `ignore` patterns still apply. Also available on [`dirsql query`](#dirsql-query). |

dirsql-0.4.111/packages/python/e2e-attestations/bot-1464-fastest-native-1008.json

@@ -0,0 +1,7 @@
+{
+  "command": "just test-e2e",
+  "ran_at": 1791551036,
+  "exit_code": 0,
+  "commit": "30fee35315cbb6f971956415d71be398c0c9d46e",
+  "branch": "bot/1464-fastest-native-1008"
+}

dirsql-0.4.111/packages/python/e2e-attestations/bot-1469-ci-speed-sanity-1009.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/release_speed_test.py -x -q",
+  "ran_at": 1791556899,
+  "exit_code": 0,
+  "commit": "f4ef45b80656a68f454aafdcacc9b56cd555b917",
+  "branch": "bot/1469-ci-speed-sanity-1009"
+}

dirsql-0.4.111/packages/python/e2e-attestations/bot-1470-perf-suite-1009.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/glob_speed_recursive_test.py tests/e2e/stat_speed_test.py -x -q",
+  "ran_at": 1791558371,
+  "exit_code": 0,
+  "commit": "51dddeda464183ef6bd032221984298ce1437184",
+  "branch": "bot/1470-perf-suite-1009"
+}

dirsql-0.4.111/packages/python/e2e-attestations/bot-1503-bench-watch-1011.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m tests.e2e.bench_suite --pairs 5 --out /tmp/bench-1503 -k watch",
+  "ran_at": 1791769095,
+  "exit_code": 0,
+  "commit": "409ebb5a7e1da55d1516983fcd936cae7fdc952c",
+  "branch": "bot/1503-bench-watch-1011"
+}

dirsql-0.4.111/packages/python/e2e-attestations/bot-issue-1486-frontend-20261009.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/cli_version_test.py tests/e2e/query_contract_test.py tests/e2e/fanout_test.py tests/e2e/extension_package_test.py -x -q",
+  "ran_at": 1791556016,
+  "exit_code": 0,
+  "commit": "fc84f87effcd648162d3c143d308bc0c24222dcb",
+  "branch": "bot/issue-1486-frontend-20261009"
+}

dirsql-0.4.111/packages/python/e2e-attestations/bot-speed-parse-paths-1009.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/frontmatter_parse_speed_test.py tests/e2e/jsonl_parse_speed_test.py tests/e2e/on_file_query_test.py tests/e2e/query_contract_test.py tests/e2e/fanout_test.py tests/e2e/declared_table_name_test.py tests/e2e/use_case_dossier_test.py tests/e2e/use_case_join_test.py tests/e2e/use_case_notebook_test.py tests/e2e/use_case_transcripts_test.py -x -q -s",
+  "ran_at": 1791560842,
+  "exit_code": 0,
+  "commit": "d5ea2e249e40f6b64e6eb1f799fc47d8290b795e",
+  "branch": "bot/speed-parse-paths-1009"
+}

dirsql-0.4.111/packages/python/e2e-attestations/bot-speed-walk-sched-1009.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/glob_speed_depth_bound_test.py tests/e2e/glob_speed_one_level_test.py tests/e2e/glob_speed_recursive_test.py tests/e2e/glob_speed_symlink_test.py -x -q",
+  "ran_at": 1791561608,
+  "exit_code": 0,
+  "commit": "d4ace79bbd16978ba199811907976d240ca55507",
+  "branch": "bot/speed-walk-sched-1009"
+}

dirsql-0.4.111/packages/python/tests/e2e/bench_report.py

@@ -0,0 +1,97 @@
+"""Records, report and markdown for the performance suite (`just bench-suite`)."""
+
+from __future__ import annotations
+
+import json
+import statistics
+from pathlib import Path
+
+RECORDS = "cases.jsonl"
+
+
+def ratio_stats(ratios):
+    low, high = min(ratios), max(ratios)
+    median = statistics.median(ratios)
+    return {"min": low, "median": median, "max": high, "spread": (high - low) / median}
+
+
+def case_record(name, result, startup):
+    natives = {}
+    for native, seconds in result.native_seconds.items():
+        net = [s - startup.native for s in seconds]
+        natives[native] = {
+            "native_median_s": statistics.median(seconds),
+            "ratio": ratio_stats(
+                [(d - startup.dirsql) / n for d, n in zip(result.dirsql_seconds, net)]
+            ),
+        }
+    return {
+        "name": name,
+        "pairs": len(result.dirsql_seconds),
+        "fastest": result.fastest,
+        "ratio_vs_fastest": natives[result.fastest]["ratio"]["median"],
+        "dirsql_median_s": statistics.median(result.dirsql_seconds),
+        "startup": {"dirsql": startup.dirsql, "native": startup.native},
+        "natives": natives,
+        "skipped": list(result.skipped),
+    }
+
+
+def build_report(records, meta):
+    return {**meta, "cases": sorted(records, key=lambda c: c["name"])}
+
+
+def append_record(out, record):
+    with (Path(out) / RECORDS).open("a") as file:
+        file.write(json.dumps(record) + "\n")
+
+
+def read_records(out):
+    lines = (Path(out) / RECORDS).read_text().splitlines()
+    return [json.loads(line) for line in lines]
+
+
+def render_markdown(report):
+    machine = ", ".join(f"{k}: {v}" for k, v in report["machine"].items())
+    versions = ", ".join(f"{k}: {v}" for k, v in report["versions"].items())
+    lines = [
+        "# dirsql performance suite",
+        "",
+        f"- Commit: {report['commit']}",
+        f"- Date: {report['date']}",
+        f"- Machine: {machine}",
+        f"- Versions: {versions}",
+        (
+            f"- Method: {report['pairs']} paired runs per case, interleaved; ratios"
+            " are dirsql over the native after each side's startup, median across"
+            " pairs"
+        ),
+        "",
+        "| Case | Fastest native | dirsql / fastest | Spread | vs 1.0x |",
+        "|---|---|---|---|---|",
+    ]
+    for case in report["cases"]:
+        stats = case["natives"][case["fastest"]]["ratio"]
+        verdict = "over" if case["ratio_vs_fastest"] > 1.0 else "ok"
+        lines.append(
+            f"| {case['name']} | {case['fastest']} | {case['ratio_vs_fastest']:.2f}x"
+            f" | {stats['spread']:.0%} | {verdict} |"
+        )
+    for case in report["cases"]:
+        lines += [
+            "",
+            f"## {case['name']}",
+            "",
+            f"dirsql median {case['dirsql_median_s']:.3f}s",
+            "",
+            "| Native | Median s | dirsql / native | Min | Max | Spread |",
+            "|---|---|---|---|---|---|",
+        ]
+        for native, data in sorted(case["natives"].items()):
+            r = data["ratio"]
+            lines.append(
+                f"| {native} | {data['native_median_s']:.3f} | {r['median']:.2f}x"
+                f" | {r['min']:.2f}x | {r['max']:.2f}x | {r['spread']:.0%} |"
+            )
+        lines += [f"- {tool} (not installed)" for tool in case["skipped"]]
+    return "\n".join(lines) + "\n"

dirsql-0.4.111/packages/python/tests/e2e/bench_suite.py

@@ -0,0 +1,115 @@
+"""Entry point for `just bench-suite`.
+
+Runs every speed-of-light case with every native timed in each paired,
+interleaved run, then writes `report.json` and `report.md` beside the raw
+per-case records. The cases are the e2e tests themselves, so the suite and the
+ratchet never disagree on what a case is.
+
+    python -m tests.e2e.bench_suite --pairs 100 --out /tmp/bench [-k expr]
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from .bench_report import build_report, read_records, render_markdown
+
+HERE = Path(__file__).parent
+TOOLS = (
+    ("bash", ["bash", "--version"]),
+    ("find", ["find", "--version"]),
+    ("fd", ["fd", "--version"]),
+    ("rg", ["rg", "--version"]),
+    ("xargs", ["xargs", "--version"]),
+    ("inotifywait", ["inotifywait", "--help"]),
+)
+
+
+def case_files(directory=HERE):
+    return sorted(
+        path
+        for path in directory.glob("*_test.py")
+        if "assert_speed_of_light" in path.read_text()
+    )
+
+
+def first_line(argv):
+    if shutil.which(argv[0]) is None:
+        return None
+    proc = subprocess.run(argv, capture_output=True, text=True, check=False)
+    lines = (proc.stdout or proc.stderr).splitlines()
+    return lines[0].strip() if lines else None
+
+
+def cpu_model():
+    try:
+        for line in Path("/proc/cpuinfo").read_text().splitlines():
+            if line.startswith("model name"):
+                return line.split(":", 1)[1].strip()
+    except OSError:
+        pass
+    return platform.processor() or "unknown"
+
+
+def git_commit():
+    proc = subprocess.run(
+        ["git", "rev-parse", "HEAD"], capture_output=True, text=True, check=False
+    )
+    return proc.stdout.strip() or "unknown"
+
+
+def metadata(pairs):
+    versions = {}
+    for name, argv in TOOLS:
+        versions[name] = first_line(argv)
+    return {
+        "commit": git_commit(),
+        "date": datetime.datetime.now(datetime.timezone.utc).strftime(
+            "%Y-%m-%dT%H:%M:%SZ"
+        ),
+        "machine": {
+            "platform": platform.platform(),
+            "cpu": cpu_model(),
+            "cpus": os.cpu_count(),
+        },
+        "versions": {k: v for k, v in versions.items() if v},
+        "pairs": pairs,
+    }
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--pairs", type=int, default=100)
+    parser.add_argument("--out", type=Path, required=True)
+    parser.add_argument("-k", default="")
+    args = parser.parse_args(argv)
+    args.out.mkdir(parents=True, exist_ok=True)
+    (args.out / "cases.jsonl").unlink(missing_ok=True)
+    env = {
+        **os.environ,
+        "DIRSQL_BENCH_PAIRS": str(args.pairs),
+        "DIRSQL_BENCH_OUT": str(args.out),
+    }
+    pytest = [sys.executable, "-m", "pytest", "-q", "-s", "-p", "no:cacheprovider"]
+    if args.k:
+        pytest += ["-k", args.k]
+    code = subprocess.run(
+        pytest + [str(p) for p in case_files()], env=env, check=False
+    ).returncode
+    report = build_report(read_records(args.out), metadata(args.pairs))
+    (args.out / "report.json").write_text(json.dumps(report, indent=2) + "\n")
+    (args.out / "report.md").write_text(render_markdown(report))
+    print(f"wrote {args.out}/report.json and {args.out}/report.md")
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())