querysource 4.5.16__tar.gz → 5.0.0__tar.gz

{querysource-4.5.16 → querysource-5.0.0}/.claude/agents/sdd-coder.md

@@ -121,7 +121,9 @@ VERIFICATION CHECKLIST for TASK-<NNN>:
 If ANY check fails, fix it or STOP and report.
 
 ### e) Validate
-- Run linting (`ruff check`) on the files you touched and fix issues.
+- Do NOT run `ruff`/`black` or spend turns on style: the engine runs `ruff check --fix` plus the
+  repo formatter on your committed files at merge time and commits the result itself. Style debt
+  that remains is fixed once, feature-wide, by `/sdd-done`.
 - Run THIS task's acceptance-criteria tests.
 - If stuck after 3 attempts, stop and report the failure clearly instead of
   committing broken code — the orchestrator treats an unresolved failure as

{querysource-4.5.16 → querysource-5.0.0}/.claude/agents/sdd-worker.md

@@ -244,6 +244,9 @@ consolidate, and own SDD state. Coders (`sdd-coder`) run one task each in their
      green → step (g) of the Fallback loop for this task, with a Completion Note that ends with
      `Seat: <seat_label> · Backend: <backend> · Model: <model> · Attempts: <n> · Duration: <sum duration_s> · Tokens: <usage>`
      taken from `attempts[*]`; red → treat as `failed`.
+     The engine already ran `ruff check --fix` + the repo formatter and committed it (`lint.commit`). Fix ONLY
+     `lint.errors` (syntax errors / undefined names) in this worktree; ignore `lint.residual` — style debt is
+     fixed once, feature-wide, by `/sdd-done`. Never run `ruff`/`black` per task yourself.
    - `merge_conflict` → `git merge <branch>` in this worktree, resolve, commit, then `coder_merge(task_id)` again.
    - `failed` with `diagnostics` starting `branch_not_merged:` → the engine merged nothing (it never answers
      `merged` unless the branch is an ancestor of the feature branch). Run
@@ -295,7 +298,9 @@ VERIFICATION CHECKLIST for TASK-<NNN>:
 If ANY check fails, fix or STOP.
 
 ### e) Validate (in worktree)
-- Run linting and fix issues.
+- Lint mechanically, never by hand (this path has no engine to do it): `ruff check --fix <task .py files>`, then
+  `black <task .py files>` only if `pyproject.toml` has `[tool.black]`. Fix only syntax errors / undefined names
+  (`ruff check --select E9,F63,F7,F82`); leave remaining style findings to `/sdd-done`.
 - Run acceptance-criteria tests.
 - If stuck after 3 attempts, mark as `"done-with-issues"`.
 

{querysource-4.5.16 → querysource-5.0.0}/.claude/commands/sdd-done.md

@@ -115,6 +115,35 @@ test -f <worktree-path>/<filepath>
 its acceptance-criteria tests during `/sdd-start` or `sdd-worker` execution.
 Re-running them at close time adds latency without new signal.
 
+### 4.5. Full Lint Pass (once per feature)
+
+Per-task lint is engine-owned and only auto-fixes (`sdd-coder` engine, merge
+boundary). This step is the ONE place the repo's full ruff rule set is enforced
+for the feature — never per task. With `--dry-run`, run only the final
+`ruff check` and report; do not fix or commit.
+
+```bash
+WT="<worktree-path>"
+git -C "$WT" fetch origin <base_branch>
+mapfile -t PY < <(git -C "$WT" diff --name-only --diff-filter=ACMR "origin/<base_branch>...HEAD" -- '*.py')
+if [ ${#PY[@]} -gt 0 ]; then
+  (cd "$WT" && ruff check --fix --exit-zero --quiet "${PY[@]}")
+  if grep -q '^\[tool\.black\]' "$WT/pyproject.toml"; then (cd "$WT" && black -q "${PY[@]}"); fi
+  git -C "$WT" add -- "${PY[@]}"
+  git -C "$WT" diff --cached --quiet || git -C "$WT" commit -m "style(<slug>): FEAT-<ID> — full lint pass"
+  (cd "$WT" && ruff check --output-format concise "${PY[@]}")
+fi
+```
+
+Then fix what `ruff check` still reports, in those files only (pre-existing
+violations in a touched file included — that is deliberate code improvement):
+- Keep each fix behavior-neutral; when one is not (e.g. narrowing a blind
+  `except Exception`), run the tests of the touched module before committing.
+- Commit as `style(<slug>): FEAT-<ID> — lint fixes`.
+- A finding you cannot fix safely goes under **Lint residual** in the report.
+  Residual syntax errors / undefined names (`E9`, `F63`, `F7`, `F82`) are merge
+  blockers: they turn Step 6 into the "issues" branch. Other residue does not.
+
 ### 5. Build Verification Report
 Classify each task:
 
@@ -130,6 +159,7 @@ Worktree: .claude/worktrees/feat-<ID>-<slug>
 Branch: feat-<ID>-<slug>
 Commits found: <N>
 Tasks: <total> total, <verified> verified, <partial> partial, <missing> missing
+Lint: <autofixed files> auto-fixed, <fixed> hand-fixed, <residual> residual (<blocking> blocking)
 
   ✅ TASK-096 — Scene Editor Refactor
      Commits: feat(videoreel): TASK-096 — Scene Editor Refactor (abc1234)

{querysource-4.5.16 → querysource-5.0.0}/.claude/commands/sdd-spec.md

@@ -537,9 +537,17 @@ stay with the thinking model — eligibility never delegates a design choice.
 
 **Worktree hint (new section in spec):**
 Include a `## Worktree Strategy` section in the spec with:
-- Default isolation unit: `per-spec` or `per-task`.
-- If `per-spec`: all tasks run sequentially in one worktree.
-- If mixed: list which tasks are parallelizable and why.
+- Isolation: always ONE feature worktree per spec; the `sdd-coder` engine gives
+  each task its own sub-worktree inside it. Do not write "tasks run
+  sequentially" — that is not an isolation choice, and `/sdd-task` must not
+  turn it into a dependency chain.
+- Module dependency graph: which modules need which (M2 → M1 because M2 imports
+  M1's `<symbol>`), with the evidence. Modules without an edge between them
+  are expected to run concurrently.
+- Shared files: files more than one module modifies (their tasks get serialized).
+- Exclusive resources: steps that mutate shared state outside a module's own
+  files (extension rebuild, lockfile, migration) — their tasks become
+  `parallel: false`.
 - Cross-feature dependencies: list any specs that must be merged first.
 
 ### 6. Commit the Spec
@@ -588,7 +596,7 @@ git commit -m "sdd: add spec for FEAT-<ID> — <feature-name>"
 ✅ Spec created and committed: sdd/specs/<feature-name>.spec.md
 
    Feature ID: FEAT-<ID>
-   Isolation: per-spec (sequential tasks) | mixed (some parallel tasks)
+   Module graph: <M> modules, <E> dependency edges, exclusive: <modules or "none">
    Design research: <N> suggestions — <C> confirmed / <R> rejected / <E> escalated   (model <MODEL>)
    # or:  Design research: skipped (<SKIP_REASON>)
 

{querysource-4.5.16 → querysource-5.0.0}/.claude/commands/sdd-task.md

@@ -16,7 +16,9 @@ Decompose an approved Feature Specification into atomic, assignable implementati
   **Implementation Blueprint** (executor-ready per-file code blocks + why +
   `FILL IN` checklist, see §3). Blueprints stop at the mechanical parts;
   branches, edge cases and test bodies stay as `FILL IN` stubs.
-- Mark tasks that can run in parallel worktrees with `parallel: true`.
+- Build the task graph by §3's **Task graph rules** — `depends_on` is the only
+  ordering, `parallel: false` means *exclusive* — and run
+  `scripts/sdd/check_task_graph.py` on the index before committing (§4b).
 - **`TASK-<NNN>` numbers are reserved via `scripts/sdd/reserve_ids.py`
   (FEAT-387), never hand-computed by scanning existing files for the
   highest number in use.** That scan-and-increment approach has no lock
@@ -93,11 +95,37 @@ Analyze the spec and identify atomic tasks:
 - Order tasks to respect implementation dependencies.
 - Aim for tasks completable in 1–4 hours each.
 
-**Parallelism analysis:**
-- Identify tasks within the spec that share NO files or imports with other tasks.
-- Mark those tasks as `parallel: true` — they CAN run in separate worktrees.
-- Tasks that import/extend code from a prior task in the same spec are `parallel: false` (default).
-- Document the rationale in the `parallelism_notes` field.
+**Task graph rules (`depends_on`, `parallel`, `parallelism_notes`):**
+
+Every task runs in its own sub-worktree, dispatched by the `sdd-coder` engine as
+soon as its `depends_on` are done; tasks whose dependencies are met run
+**concurrently**. So the graph, not the prose, decides how long a feature takes
+(querysource FEAT-147: 18 tasks chained 1→2→…→18 with one copy-pasted
+rationale ran strictly in series for ~7 h).
+
+- **`depends_on` is the ONLY ordering.** Add `B depends_on A` only with evidence:
+  - B imports, calls, extends or tests a symbol A **creates**; or
+  - B consumes a file/table/config/fixture A creates; or
+  - B and A both **modify the same file** (serialize them: the lower id first).
+
+  Never add an edge because tasks share a module, a spec section or a "phase", or
+  "to be safe". A spec that says tasks run *sequentially* or *per-spec* means ONE
+  feature worktree — it is NOT a dependency chain. Transitive edges may be
+  omitted.
+- **`parallel` defaults to `true`.** Set `parallel: false` (*exclusive* — never
+  dispatched alongside any other task, even with its dependencies met) only when
+  the task mutates shared state **outside its declared files**: rebuilding
+  compiled extensions (Cython `make build-inplace`, maturin), editing dependency
+  manifests or lockfiles (`pyproject.toml`, `uv.lock`), running DDL/migrations
+  against a shared database, regenerating shared generated code, or changing a
+  `conftest.py` other tasks' tests load.
+- **`parallelism_notes` is per task and names its evidence**: for each
+  `depends_on` edge, the dependency id plus the symbol/file it needs
+  (`"imports TenantRegistry from TASK-716 (querysource/tenants.py)"`); for an
+  exclusive task, the shared resource. Identical notes on several tasks is a
+  defect.
+- Write `"parallel_semantics": "exclusive"` in the index header (see schema) —
+  without it the engine ignores every `parallel` flag.
 
 **CRITICAL — Codebase Contract per Task (Anti-Hallucination):**
 For EACH task, you MUST populate its `## Codebase Contract` section:
@@ -225,6 +253,7 @@ and ignored by all FEAT-145 commands). Schema:
   "base_branch": "dev",
   "created_at": "<ISO-8601>",
   "completed_at": null,
+  "parallel_semantics": "exclusive",
   "tasks": [
     {
       "id": "TASK-<NNN>",
@@ -237,8 +266,8 @@ and ignored by all FEAT-145 commands). Schema:
       "priority": "<high|medium|low>",
       "effort": "<S|M|L|XL>",
       "depends_on": [],
-      "parallel": false,
-      "parallelism_notes": "<rationale>",
+      "parallel": true,
+      "parallelism_notes": "<per-task evidence: 'needs <symbol> from TASK-<X> (<file>)' | exclusive resource>",
       "assigned_to": null,
       "started_at": null,
       "completed_at": null,
@@ -251,7 +280,9 @@ and ignored by all FEAT-145 commands). Schema:
 **Header fields (`type`, `base_branch`)** are populated from the spec's
 frontmatter (resolved in §1 above). If `sdd/tasks/index/<feature>.json`
 already exists (created by the migration script for older specs), append
-the new tasks to its `tasks[]` array — do NOT overwrite the header.
+the new tasks to its `tasks[]` array — do NOT overwrite the header. Do not add
+`parallel_semantics` to an existing header whose tasks were written before these
+rules: their `parallel: false` meant something else and would serialize them.
 
 **Index location helper:**
 ```bash
@@ -285,6 +316,24 @@ complete. `design_complete: true` is a declaration the task author signs.
 - Omit the section entirely when the task is not eligible. Most tasks are not,
   and that is the normal, expected route.
 
+### 4b. Validate the Task Graph
+
+Run the deterministic graph check on the index you just wrote:
+
+```bash
+python -m scripts.sdd.check_task_graph sdd/tasks/index/<feature-slug>.json
+```
+
+- **Errors** (exit 1) block the commit: `file-overlap` (two tasks declare the
+  same file with no dependency path between them — they would run concurrently
+  and conflict), `unknown-dependency`, `cycle`. Fix the graph, re-run.
+- **Every warning is resolved, not ignored**: `unjustified-edge` → remove the
+  edge, or write its evidence in `parallelism_notes` (naming the dependency id);
+  `possible-missing-dependency` → add the edge or confirm the reference is not
+  a use; `duplicate-notes` / `exclusive-without-notes` → write per-task notes.
+- Copy the report's first line (`<N> tasks, <W> waves, max width <M>`) into the
+  §6 output. A width of 1 on a multi-task feature needs a one-line justification.
+
 ### 5. Commit Tasks and Per-Spec Index to `<BASE>`
 
 > **CRITICAL — Only commit the per-spec index and the new task files. NEVER
@@ -331,6 +380,7 @@ Tasks created:
   HOTFIX-<JIRA-KEY>-<N> — <title> [<priority>/<effort>]  # hotfix
 
 Blueprints: <N>/<N> tasks carry an Implementation Blueprint
+Graph:      <N> tasks, <W> waves, max width <M>; exclusive: <ids or "none">
 Delegated:  <D>/<N> tasks carry a Delegation Contract (targeted writer)
             TASK-<NNN>, TASK-<NNN>          # list them, or "none"
 

{querysource-4.5.16 → querysource-5.0.0}/CHANGES.rst

@@ -1,6 +1,25 @@
 Unreleased
 ==========
 
+Describe API for query slugs (FEAT-148)
+---------------------------------------
+
+New read-only endpoints for discovering stored query slugs without executing them:
+``GET /api/v1/queries/describe`` (paginated list), ``GET /api/v1/queries/{slug}/describe``
+(definition + typed variables), ``GET /api/v1/queries/{slug}/columns`` (prepared, never
+executed) and ``GET /api/v1/queries/vocabulary`` (relative-date keywords).
+
+Tenant-scoped endpoints (when FEAT-147 tenant registry is enabled):
+``GET /api/v1/{tenant}/queries/describe``, ``GET /api/v1/{tenant}/queries/{slug}/describe``,
+and ``GET /api/v1/{tenant}/queries/{slug}/columns`` serve per-tenant definitions via the tenant
+registry. Access control, redaction, and all pagination/filtering rules apply identically.
+
+- Access rules: Requires a principal (session or sessionless authz). List visibility requires ``slug:list`` or ``slug:execute``; detail and columns require ``slug:describe`` or ``slug:execute``. Denials return ``404`` to prevent enumeration.
+- Redaction: Sensitive fields (like ``query_raw``) are redacted unless the principal has ``slug:describe_raw``. Admin-only fields (like ``dwh_info``, ``cache_options``) are visible only to superusers or members of ``QS_DESCRIBE_ADMIN_GROUPS``.
+- Configuration: Configured via ``QS_DESCRIBE_MAX_SCAN`` (default 10000), ``QS_DESCRIBE_ADMIN_GROUPS`` (default admin,superuser), and ``QS_DESCRIBE_COLUMNS_TIMEOUT`` (default 5).
+- Policy: Default policies in ``policies/defaults.yaml`` (such as ``admin_full_access``) are updated to grant ``slug:describe`` and ``slug:describe_raw``.
+- Behaviour change: Relative-date keywords (``TODAY``, ``YESTERDAY``, ``FDOM``, ``LDOM``, ``CURRENT_YEAR``, ``CURRENT_MONTH``, ``LAST_YEAR``) now resolve consistently on raw-query providers for untyped and date/datetime/timestamp conditions. Environment overrides for ``UDF_LIST``, ``PG_CONSTANTS``, and ``PG_UDF`` now accept comma-separated values.
+
 Row-oriented outputs — DataFrame results and swallowed errors
 -------------------------------------------------------------
 

{querysource-4.5.16/querysource.egg-info → querysource-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: querysource
-Version: 4.5.16
+Version: 5.0.0
 Summary: Aiohttp web service for querying several databases easily
 Author-email: Jesus Lara <jesuslarag@gmail.com>
 License: BSD-3-Clause

{querysource-4.5.16 → querysource-5.0.0}/generated/Query.json

@@ -45,6 +45,13 @@
       "default": null,
       "required": false,
       "description": "Address of the remote qworker to use for this query, in ``host:port`` format (e.g. ``qworker1.internal:8888``). Overrides the central ``QWORKER_HOST`` / ``QWORKER_PORT`` settings. Only relevant when ``remote: true``. If no port is specified, QWORKER_PORT is used as the fallback (default: 8888)."
+    },
+    {
+      "name": "tenant",
+      "type": "str",
+      "default": null,
+      "required": false,
+      "description": "Tenant owner for this query. If omitted, inherits from parent or uses the configured default store. If explicitly ``null``, uses the legacy store. If a string, selects that exact tenant from the allowlist. Examples: ``null`` (legacy), ``client_a`` (explicit tenant)."
     }
   ],
   "json_schema": {
@@ -76,6 +83,11 @@
       "worker": {
         "type": "string",
         "description": "Address of the remote qworker to use for this query, in ``host:port`` format (e.g. ``qworker1.internal:8888``). Overrides the central ``QWORKER_HOST`` / ``QWORKER_PORT`` settings. Only relevant when ``remote: true``. If no port is specified, QWORKER_PORT is used as the fallback (default: 8888)."
+      },
+      "tenant": {
+        "type": "string",
+        "description": "Tenant owner for this query. If omitted, inherits from parent or uses the configured default store. If explicitly ``null``, uses the legacy store. If a string, selects that exact tenant from the allowlist. Examples: ``null`` (legacy), ``client_a`` (explicit tenant).",
+        "default": null
       }
     },
     "oneOf": [
@@ -94,6 +106,6 @@
     "additionalProperties": true,
     "description": "A single entry under the MultiQS ``queries:`` block. Must provide either ``slug`` or ``query`` (but not both)."
   },
-  "example": "{\n  \"queries\": {\n    \"stores\": {\n      \"query\": \"select * from hisense.stores\",\n      \"driver\": \"pg\"\n    },\n    \"products\": {\n      \"slug\": \"all_products\"\n    },\n    \"remote_orders\": {\n      \"slug\": \"daily_orders\",\n      \"remote\": true,\n      \"worker\": \"qworker1.internal:8888\",\n      \"store_id\": 42\n    }\n  }\n}",
+  "example": "{\n  \"queries\": {\n    \"stores\": {\n      \"query\": \"select * from hisense.stores\",\n      \"driver\": \"pg\"\n    },\n    \"products\": {\n      \"slug\": \"all_products\"\n    },\n    \"remote_orders\": {\n      \"slug\": \"daily_orders\",\n      \"remote\": true,\n      \"worker\": \"qworker1.internal:8888\",\n      \"store_id\": 42\n    },\n    \"tenant_sales\": {\n      \"slug\": \"sales_report\",\n      \"tenant\": \"client_a\"\n    }\n  }\n}",
   "icon": "database"
 }

{querysource-4.5.16 → querysource-5.0.0}/policies/defaults.yaml

@@ -24,6 +24,8 @@ policies:
       - "driver:use"
       - "driver:list"
       - "raw_query:execute"
+      - "slug:describe"
+      - "slug:describe_raw"
     subjects:
       groups:
         - superuser

{querysource-4.5.16 → querysource-5.0.0}/pyproject.toml

@@ -211,6 +211,69 @@ filterwarnings = [
     'ignore:The loop argument is deprecated since Python 3\.8, and scheduled for removal in Python 3\.10:DeprecationWarning:asyncio',
 ]
 
+# ---------------------------------------------------------------------------
+# Formatting (black) and linting (ruff)
+# ---------------------------------------------------------------------------
+# black formats, ruff lints (no `ruff format`). Both use 120 columns, matching
+# tox.ini's [flake8]/[pep8] max-line-length. The sdd-coder engine runs
+# `ruff check --fix` + black on each task's files at merge time; `/sdd-done`
+# fixes the remaining findings in the files a feature touches.
+[tool.black]
+line-length = 120
+# Floor of requires-python (>=3.10.1) plus the venv's 3.11; formatting for
+# 3.10 is valid on every supported interpreter and keeps black's AST safety
+# check on when run from an older venv.
+target-version = ["py310", "py311"]
+extend-exclude = '''
+/(
+    \.claude/worktrees
+  | build
+  | generated
+  | rust
+)/
+'''
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+src = ["."]
+extend-exclude = [".claude/worktrees", "*.ipynb", "build", "generated", "rust"]
+
+[tool.ruff.lint]
+# Pinned explicitly: ruff >= 0.16 widened its implicit default rule set, so an
+# unconfigured repo's findings drifted with the tool version.
+select = [
+    "E4", "E7", "E9", "F",  # pycodestyle errors + pyflakes (real defects)
+    "B",      # flake8-bugbear
+    "ASYNC",  # blocking calls inside async def
+    "UP",     # pyupgrade (minus the annotation rewrites below)
+    "I",      # import sorting (black-compatible)
+    "PIE",    # no-op placeholders, duplicate enum values
+    "C4",     # comprehension misuse
+    "LOG",    # logging calls outside handlers / root logger
+    "DTZ",    # naive datetimes (scheduler, caches, tenants)
+]
+ignore = [
+    # python-datamodel 0.11 (datamodel.BaseModel) cannot evaluate PEP 604/585
+    # annotations at runtime: `a: int | None` raises "Expected type, got
+    # types.UnionType" and `Optional[tuple[int, ...]]` fails to parse. The
+    # auto-fixes for these would break models, so typing.Optional/List stay.
+    "UP006", "UP007", "UP035", "UP045",
+    # `timeout` parameters on async APIs are part of the public surface.
+    "ASYNC109",
+    # `dict(a=1)` vs `{"a": 1}` is taste, not a defect.
+    "C408",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["querysource"]
+
+[tool.ruff.lint.per-file-ignores]
+"**/__init__.py" = ["F401", "F403", "F405"]
+"tests/**/*.py" = ["F401", "F811", "F841", "B011", "B017", "ASYNC230", "ASYNC240"]
+"**/conftest.py" = ["F401", "F403"]
+"examples/**/*.py" = ["F401", "F841", "E402"]
+
 # ---------------------------------------------------------------------------
 # Maturin (Rust extension) — configured in rust/pyproject.toml.
 # Invoke via: maturin develop --release --manifest-path rust/Cargo.toml

{querysource-4.5.16 → querysource-5.0.0}/querysource/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '4.5.16'
-__version_tuple__ = version_tuple = (4, 5, 16)
+__version__ = version = '5.0.0'
+__version_tuple__ = version_tuple = (5, 0, 0)
 
-__commit_id__ = commit_id = 'g545b899f2'
+__commit_id__ = commit_id = 'gaebc55c28'