Skip to content

feat(query): reject undeclared parameters and bound SQL-fragment parameters with choices - #126

Merged
codeasier merged 2 commits into
mainfrom
feat/issue-120-template-param-validation
Sep 18, 2026
Merged

codeasier merged 2 commits into
mainfrom
feat/issue-120-template-param-validation

Conversation

@codeasier

Copy link
Copy Markdown
Owner

📝 Description

Two gaps in template parameter validation (src/pt_snap_cli/query/config.py):

  1. Undeclared parameters were silently passed through. validate_params() copied any unknown key into the render context, so a misspelled filter ({"min_sze": 1024}) produced an unfiltered result set with no diagnostic.
  2. str parameters were interpolated into SQL verbatim. order_by / order_dir in allocation, block, event, and active_blocks_at_event accepted arbitrary fragments — a subquery in order_by executed successfully, and an invalid order_dir surfaced as a raw SQLite syntax error.

The database is opened mode=ro and sqlite3 executes a single statement, so this was not a write path. It is a robustness and agent-safety fix: the MCP execute_query tool exposes these parameters to prompt-driven callers, and "silently wrong results" is the worst failure mode for a diagnostic tool.

Changes

  • QueryParameter.choices (optional list). Checked after type conversion; str choices match case-insensitively and return the declared spelling (desc → DESC). A default that is not one of the choices, or an empty/non-list choices, fails at template load.
  • QueryTemplate.validate_params() raises ValueError naming every unknown parameter and the accepted set, e.g. Unknown parameter(s) for template 'leak_detection': min_sze (accepted: min_size, limit). QueryExecutor.render() already wraps this into TemplateRenderError, so CLI/API/MCP semantics stay aligned.
  • Packaged templates: order_by choices are each template's own output columns; order_dir is [ASC, DESC]. active_blocks_at_event already whitelisted inside Jinja (falling back to size silently) — it now reports invalid input instead of falling back.
  • choices is exposed end-to-end: registry.get_template_info → TemplateParameter → QueryService → SnapshotAnalyzer.get_template_info / MCP → CLI --template-info (order_by: str (optional) [choices: id, allocated, active, reserved] [default: id]).
  • Docs: new "Parameter Validation" section in docs/en/querying.md and docs/zh/querying.md; query/AGENTS.md and query/templates/AGENTS.md record the new template rules.

Before / after on a real fixture database

$ pt-snap query DB --template-use leak_detection --params '{"min_sze": 999999999999}' -n 2
before: Found 325 results, showing 2:            # filter silently dropped
after:  Error executing query: Failed to validate parameters for template 'leak_detection': Unknown parameter(s) for template 'leak_detection': min_sze (accepted: min_size, limit)

$ pt-snap query DB --template-use allocation --params '{"order_by": "(SELECT name FROM sqlite_master ... LIMIT 1)"}' -n 1
before: Found 8189 results, showing 1:           # subquery executed
after:  ... Parameter 'order_by' must be one of: id, allocated, active, reserved (got '(SELECT name FROM sqlite_master ... LIMIT 1)')

$ pt-snap query DB --template-use allocation --params '{"order_dir": "SIDEWAYS"}' -n 1
before: Error executing query: Query execution failed: near "SIDEWAYS": syntax error
after:  ... Parameter 'order_dir' must be one of: ASC, DESC (got 'SIDEWAYS')

$ pt-snap query DB --template-use allocation --params '{"order_by": "reserved", "order_dir": "desc"}' -n 1
after:  Found 8189 results, showing 1:           # valid input, lowercase direction accepted

Compatibility

Callers that relied on unknown keys being ignored now get an error. I audited every --params example in skills/*/SKILL.md, docs/, and ReportService; all pass only declared parameters. tests/test_cli.py::test_query_with_params already tolerated either outcome (exit_code in [0, 1]) and is unchanged.

🔗 Related Issue

Fixes #120

🧪 Testing

  • Tests added/updated
  • Manual testing completed

New tests (19): QueryParameter choices semantics and load-time checks, validate_params unknown-name rejection, from_dict reading choices, a registry invariant that every packaged order_by/order_dir declares choices within output_schema, CLI error output and --template-info rendering, and two CLI/MCP contract tests asserting identical error text for unknown parameters and out-of-choices values. The contract test's CLI parser learned the [choices: ...] token so cli_info == mcp_info stays an exact comparison.

Full suite (macOS, Python 3.13.11): 788 passed, 1 xfailed. ruff check . and black --check . clean.

Per AGENTS.md change routing for templates, the YAML, config.py, registry.py, executor.py (no change needed — it already normalizes ValueError to TemplateRenderError), core/query_service.py, CLI/MCP presentation, and focused tests were reviewed together.

✅ Checklist

  • Code follows project guidelines
  • Documentation updated (if applicable)
  • No new warnings introduced
  • Changes tested locally

Snapshot Runtime Provenance

  • Snapshot provenance evaluation completed when snapshot runtime files change
    Snapshot provenance decision: no-update
    Snapshot provenance no-update reason: This PR changes the query subsystem, core models, CLI/API presentation, templates, docs, and tests; no files under src/pt_snap_cli/snapshot/ are touched.

…meters with choices

QueryTemplate.validate_params() passed any undeclared key straight into
the Jinja2 render context, so a misspelled filter such as `min_sze` was
silently ignored and the query returned unfiltered rows. Separately, `str`
parameters were interpolated into SQL verbatim; `order_by` / `order_dir`
in the allocation, block, event, and active_blocks_at_event templates
therefore accepted arbitrary fragments (including subqueries) and surfaced
invalid values as raw SQLite syntax errors. The database is opened
read-only and sqlite3 executes one statement at a time, so this was a
robustness and agent-safety gap rather than a write path, but the MCP
`execute_query` tool exposes those parameters to prompt-driven callers.

- QueryParameter gains an optional `choices` list. Values are checked after
  type conversion; `str` choices match case-insensitively and return the
  declared spelling. Defaults must be one of the choices, enforced at load.
- validate_params() raises ValueError listing every unknown name and the
  accepted parameters instead of passing them through.
- The four packaged templates with ORDER BY inputs declare `choices`
  drawn from their output columns and `[ASC, DESC]`.
- `choices` flows through registry.get_template_info, TemplateParameter,
  QueryService, SnapshotAnalyzer/MCP, and the CLI `--template-info`
  line (`[choices: ...]`).
- Tests cover the parameter rules, a registry invariant that packaged
  order_by/order_dir parameters declare choices within output_schema,
  CLI error output, and CLI/MCP contract parity for both error kinds.
- User guides (en/zh) document parameter validation; query AGENTS.md
  files record the new template requirements.

Fixes #120

@codeasier codeasier left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

交叉评审结果(3 位独立评审员 + 父会话逐条核验)

核心改动核验成立:未知参数拒绝是 fail-closed 的,且在 CLI/API/MCP 统一归一化为 TemplateRenderError;order_by/order_dir 的 choices 与各模板 output_schema 一致;executor 注入的上下文(device_id / 表名 / limit)在校验之后应用;所有第一方调用方(ReportService、skills、docs 示例、既有测试)均只传声明过的参数。

无 critical/high/medium 发现,以下 4 条均为 Low(打磨项,非阻塞),详见行内评论:

  1. 缺省值路径绕过 choices 约束与规范化(query/config.py)
  2. 非法 choices 实际是警告后跳过,而非 PR 描述所称的 "fails at template load"(query/config.py + query/registry.py:316-323)
  3. 契约测试新增的 [choices: ...] 解析分支从未被实际覆盖(test_contract_cli_mcp.py)
  4. --template-info 的 Example Usage 生成器可能输出非法示例(cli.py)

备注:_match_choice 以 None 兼作"未匹配"哨兵(纯理论问题);打包模板不变量测试只覆盖字面名 order_by/order_dir,比 AGENTS.md 规则略窄。

Comment thread src/pt_snap_cli/query/config.py Resolved
Comment thread src/pt_snap_cli/query/config.py Resolved
Comment thread tests/test_contract_cli_mcp.py Resolved
Comment thread src/pt_snap_cli/cli.py Resolved
Default values with choices now use the declared spelling, --template-info
examples pick a real choice, and the CLI/MCP contract uses allocation so
the choices parser is actually compared.
@codeasier
codeasier force-pushed the feat/issue-120-template-param-validation branch from 5c58ee5 to 2e41fbe Compare September 18, 2026 13:14
@codeasier
codeasier merged commit c41cadb into main Sep 18, 2026
6 checks passed
@codeasier
codeasier deleted the feat/issue-120-template-param-validation branch October 3, 2026 19:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE] 收紧查询模板参数校验:拒绝未声明参数,为 str 型 SQL 片段参数(order_by/order_dir)增加白名单

1 participant