diff --git a/docs/en/querying.md b/docs/en/querying.md index b318019..f8b3d10 100644 --- a/docs/en/querying.md +++ b/docs/en/querying.md @@ -72,6 +72,32 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}' `min_size` is the minimum candidate size in bytes and defaults to `0`. Select the target device with the command-level `--device` option, not inside `--params`. +## Parameter Validation + +`--params` is validated against the template before any SQL is rendered: + +- Every key must be a parameter the template declares. Unknown keys are + rejected instead of ignored, so a misspelled filter such as `min_sze` fails + with `Unknown parameter(s) for template 'leak_detection': min_sze (accepted: + min_size, limit)` rather than silently returning unfiltered results. +- Values are converted to the declared type (`int`, `float`, `str`, `bool`). +- Parameters that are rendered into SQL as identifiers or keywords, such as + `order_by` and `order_dir`, accept only the values listed under + `[choices: ...]` in `--template-info`. String choices match + case-insensitively and render with the declared spelling (`desc` becomes + `DESC`); anything else is rejected before it reaches the database. + +```bash +pt-snap query --template-info allocation +# order_by: str (optional) [choices: id, allocated, active, reserved] [default: id] +# order_dir: str (optional) [choices: ASC, DESC] [default: ASC] + +pt-snap query --template-use allocation --params '{"order_by": "reserved", "order_dir": "desc"}' -n 5 +``` + +The same rules apply to `SnapshotAnalyzer.execute_query()` and the MCP +`execute_query` tool, which raise `TemplateRenderError` with the same message. + ## Peak Memory Attribution Workflow These additions productize the common "find the peak, then explain what was live at that moment" workflow. @@ -202,6 +228,7 @@ hexadecimal address strings are required. Query templates are defined in YAML format with: - `version`: Template version - `queries`: Query definitions with description, supported devices, parameters, SQL (Jinja2 templated), and output schema +- Each parameter declares `type`, `default`, `required`, `description`, and optionally `choices`, a closed list of accepted values that is mandatory for parameters rendered as SQL identifiers or keywords When passed explicitly to `ResultMapper`, recognized mapping types are `int`, `float`, `str`, `bool`, `hex`, and `datetime`; `datetime` is currently a diff --git a/docs/zh/querying.md b/docs/zh/querying.md index 10fa4eb..6c85357 100644 --- a/docs/zh/querying.md +++ b/docs/zh/querying.md @@ -72,6 +72,31 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}' `min_size` 表示候选泄漏的最小字节数,默认值为 `0`。目标设备应通过命令级 `--device` 选项指定,而不是放进 `--params`。 +## 参数校验 + +`--params` 会在渲染任何 SQL 之前按模板定义进行校验: + +- 每个键都必须是模板声明的参数。未声明的键会被拒绝而不是忽略,因此把 + `min_size` 拼成 `min_sze` 会得到 `Unknown parameter(s) for template + 'leak_detection': min_sze (accepted: min_size, limit)`,而不是悄悄返回一份 + 未过滤的结果。 +- 值会按声明的类型(`int`、`float`、`str`、`bool`)转换。 +- 会被当作 SQL 标识符或关键字渲染的参数(如 `order_by`、`order_dir`)只接受 + `--template-info` 中 `[choices: ...]` 列出的取值。字符串取值不区分大小写, + 并按声明的写法渲染(`desc` 会变成 `DESC`);其他任何值都会在到达数据库之前 + 被拒绝。 + +```bash +pt-snap query --template-info allocation +# order_by: str (optional) [choices: id, allocated, active, reserved] [default: id] +# order_dir: str (optional) [choices: ASC, DESC] [default: ASC] + +pt-snap query --template-use allocation --params '{"order_by": "reserved", "order_dir": "desc"}' -n 5 +``` + +`SnapshotAnalyzer.execute_query()` 和 MCP 的 `execute_query` 工具遵循同样的规则, +并以相同的错误信息抛出 `TemplateRenderError`。 + ## 峰值内存归因工作流 这些新增能力把“先找到峰值,再解释峰值时刻哪些内存仍然活跃”的手工分析流程产品化了。 @@ -194,6 +219,7 @@ CLI、Python API 和 MCP 的查询结果包含原始 SQLite 值。模板的 `out 查询模板使用 YAML 格式定义,包含: - `version`: 模板版本 - `queries`: 查询定义,包含描述、支持的设备、参数、SQL(Jinja2 模板语法)和输出 schema +- 每个参数声明 `type`、`default`、`required`、`description`,以及可选的 `choices`(允许取值的封闭列表;会被渲染为 SQL 标识符或关键字的参数必须声明它) 显式传给 `ResultMapper` 时,可识别的映射类型包括 `int`、`float`、`str`、 `bool`、`hex` 和 `datetime`;当前 `datetime` 只是透传声明,不执行解析。 diff --git a/src/pt_snap_cli/api.py b/src/pt_snap_cli/api.py index 887cad3..683b142 100644 --- a/src/pt_snap_cli/api.py +++ b/src/pt_snap_cli/api.py @@ -132,6 +132,7 @@ def get_template_info(self, name: str) -> dict[str, Any] | None: "default": param.default, "required": param.required, "description": param.description, + "choices": param.choices, } for param_name, param in info.parameters.items() }, diff --git a/src/pt_snap_cli/cli.py b/src/pt_snap_cli/cli.py index 497cae2..4c3e743 100644 --- a/src/pt_snap_cli/cli.py +++ b/src/pt_snap_cli/cli.py @@ -425,13 +425,18 @@ def query_database( if info.parameters: for param_name, param_details in info.parameters.items(): required_str = " (required)" if param_details.required else " (optional)" + choices_str = ( + f" [choices: {', '.join(str(choice) for choice in param_details.choices)}]" + if param_details.choices + else "" + ) default_str = ( f" [default: {param_details.default}]" if param_details.default is not None else "" ) typer.secho( - f" {param_name}: {param_details.type}{required_str}{default_str}", + f" {param_name}: {param_details.type}{required_str}{choices_str}{default_str}", fg=typer.colors.YELLOW, ) typer.echo(f" {param_details.description}") @@ -457,9 +462,12 @@ def query_database( param_details.default if param_details.default is not None else 0.0 ) elif param_details.type == "str": - example_params[param_name] = ( - param_details.default if param_details.default is not None else "example" - ) + if param_details.default is not None: + example_params[param_name] = param_details.default + elif param_details.choices: + example_params[param_name] = param_details.choices[0] + else: + example_params[param_name] = "example" elif param_details.type == "bool": example_params[param_name] = True if example_params: diff --git a/src/pt_snap_cli/core/models.py b/src/pt_snap_cli/core/models.py index 65e1e84..9231bb8 100644 --- a/src/pt_snap_cli/core/models.py +++ b/src/pt_snap_cli/core/models.py @@ -72,6 +72,7 @@ class TemplateParameter: default: object | None required: bool description: str + choices: list[object] | None = None @dataclass(frozen=True) diff --git a/src/pt_snap_cli/core/query_service.py b/src/pt_snap_cli/core/query_service.py index b4a2e95..4c5dee3 100644 --- a/src/pt_snap_cli/core/query_service.py +++ b/src/pt_snap_cli/core/query_service.py @@ -108,6 +108,7 @@ def get_template_info(self, name: str) -> TemplateInfo: default=param_details["default"], required=param_details["required"], description=param_details["description"], + choices=param_details.get("choices"), ) for param_name, param_details in info["parameters"].items() }, diff --git a/src/pt_snap_cli/query/AGENTS.md b/src/pt_snap_cli/query/AGENTS.md index b3d6494..72912d4 100644 --- a/src/pt_snap_cli/query/AGENTS.md +++ b/src/pt_snap_cli/query/AGENTS.md @@ -32,6 +32,7 @@ - Variant SQL is selected from `Context.callstack_layout`; unknown or conflicting layouts must fail variant templates with a layout-specific error rather than a generic re-import message. Non-variant templates keep working. +- `QueryTemplate.validate_params()` rejects undeclared parameter names and enforces `QueryParameter.choices`; extra render-context variables (`device_id`, table names, the pushed-down `limit`) are injected by `QueryExecutor.render()` after validation, not passed through `params`. ### Testing Requirements - Run `pytest tests/query` for query subsystem changes; real SQLite template semantics live in `test_peak_memory_templates.py`, `test_callstack_schema_compat.py`, and `test_query_max_rows_pushdown.py`. diff --git a/src/pt_snap_cli/query/config.py b/src/pt_snap_cli/query/config.py index b2486b8..2158f1c 100644 --- a/src/pt_snap_cli/query/config.py +++ b/src/pt_snap_cli/query/config.py @@ -20,6 +20,35 @@ class QueryParameter: default: Any = None required: bool = False description: str = "" + # Closed set of accepted values. Required for parameters that are rendered + # into SQL as identifiers or keywords (e.g. ORDER BY column / direction), + # where the type alone cannot bound what reaches the database. + choices: list[Any] | None = None + + def __post_init__(self) -> None: + if self.choices is None: + return + if not isinstance(self.choices, list) or not self.choices: + raise ValueError(f"Parameter '{self.name}' choices must be a non-empty list") + if self.default is None: + return + matched = self._match_choice(self.default) + if matched is None: + raise ValueError( + f"Parameter '{self.name}' default {self.default!r} is not one of its choices" + ) + self.default = matched + + def _match_choice(self, value: Any) -> Any | None: + """Return the canonical choice equal to ``value``, or None when not allowed.""" + if self.choices is None: + return value + if self.type == "str" and isinstance(value, str): + for choice in self.choices: + if isinstance(choice, str) and choice.lower() == value.lower(): + return choice + return None + return value if value in self.choices else None def validate(self, value: Any) -> Any: """Validate and convert parameter value. @@ -28,11 +57,14 @@ def validate(self, value: Any) -> Any: value: Value to validate. Returns: - Converted value. + Converted value. For ``str`` parameters with ``choices`` the + canonical spelling from ``choices`` is returned, so case-insensitive + input (``"desc"``) renders as declared (``"DESC"``). Raises: TypeError: If value cannot be converted to expected type. - ValueError: If required parameter is missing. + ValueError: If required parameter is missing or the value is not one + of the declared choices. """ if value is None: if self.required: @@ -48,12 +80,20 @@ def validate(self, value: Any) -> Any: converter = type_converters.get(self.type, str) try: - return converter(value) + converted = converter(value) except (ValueError, TypeError) as e: raise TypeError( f"Parameter '{self.name}' cannot be converted to {self.type}: {e}" ) from e + if self.choices is None: + return converted + matched = self._match_choice(converted) + if matched is None: + allowed = ", ".join(str(choice) for choice in self.choices) + raise ValueError(f"Parameter '{self.name}' must be one of: {allowed} (got {value!r})") + return matched + @dataclass class QueryTemplate: @@ -91,18 +131,26 @@ def validate_params(self, params: dict[str, Any]) -> dict[str, Any]: Validated and converted parameters. Raises: - ValueError: If required parameter is missing. + ValueError: If a required parameter is missing, a value is not one + of the parameter's declared choices, or ``params`` contains a + name the template does not declare. Unknown names are rejected + rather than ignored so that a misspelled filter cannot silently + widen a query. TypeError: If parameter type is invalid. """ + unknown = sorted(name for name in params if name not in self.parameters) + if unknown: + accepted = ", ".join(self.parameters) if self.parameters else "none" + raise ValueError( + f"Unknown parameter(s) for template '{self.name}': {', '.join(unknown)} " + f"(accepted: {accepted})" + ) + validated = {} for name, param_def in self.parameters.items(): value = params.get(name) validated[name] = param_def.validate(value) - for name, value in params.items(): - if name not in self.parameters: - validated[name] = value - return validated @classmethod @@ -125,6 +173,7 @@ def from_dict(cls, data: dict[str, Any], default_category: str | None = None) -> default=param_data.get("default"), required=param_data.get("required", False), description=param_data.get("description", ""), + choices=param_data.get("choices"), ) template_name = data.get("name", "") diff --git a/src/pt_snap_cli/query/registry.py b/src/pt_snap_cli/query/registry.py index b0662bc..e1bd61d 100644 --- a/src/pt_snap_cli/query/registry.py +++ b/src/pt_snap_cli/query/registry.py @@ -204,6 +204,7 @@ def get_template_info(name: str) -> dict[str, Any] | None: "default": param.default, "required": param.required, "description": param.description, + "choices": param.choices, } for param_name, param in template.parameters.items() }, diff --git a/src/pt_snap_cli/query/templates/AGENTS.md b/src/pt_snap_cli/query/templates/AGENTS.md index bb0f3dc..a9be153 100644 --- a/src/pt_snap_cli/query/templates/AGENTS.md +++ b/src/pt_snap_cli/query/templates/AGENTS.md @@ -23,6 +23,8 @@ ### Working In This Directory - Keep each YAML template's `queries` entry name aligned with the file/topic and documented template name. - Include accurate parameter defaults, required flags, descriptions, and output schema entries. +- Any parameter rendered as a SQL identifier or keyword (`order_by`, `order_dir`, or similar) must declare `choices`; `order_by` choices must be columns present in `output_schema`. `tests/query/test_registry.py` enforces this for packaged templates. Empty `choices`, a non-list `choices`, or a default outside the list raise at `QueryParameter` construction; `_load_yaml_templates` warns and skips that YAML file, so the template is absent rather than listed. +- Callers cannot pass undeclared parameters; `QueryTemplate.validate_params()` rejects unknown names, so declare every input the SQL reads. - Use Jinja variables provided by `QueryExecutor`, especially device-specific table names. - Make ranked/grouped results deterministic with explicit tie-breakers and keep every selected result column in `output_schema`. diff --git a/src/pt_snap_cli/query/templates/basic/allocation.yaml b/src/pt_snap_cli/query/templates/basic/allocation.yaml index ea5e13b..b7f495d 100644 --- a/src/pt_snap_cli/query/templates/basic/allocation.yaml +++ b/src/pt_snap_cli/query/templates/basic/allocation.yaml @@ -34,11 +34,13 @@ queries: type: str default: "id" required: false + choices: [id, allocated, active, reserved] description: Column to order by order_dir: type: str default: "ASC" required: false + choices: [ASC, DESC] description: Sort direction (ASC or DESC) limit: type: int diff --git a/src/pt_snap_cli/query/templates/basic/block.yaml b/src/pt_snap_cli/query/templates/basic/block.yaml index d94d3a0..0a6a2a6 100644 --- a/src/pt_snap_cli/query/templates/basic/block.yaml +++ b/src/pt_snap_cli/query/templates/basic/block.yaml @@ -69,11 +69,13 @@ queries: type: str default: "size" required: false + choices: [id, address, size, requestedSize, state, allocEventId, freeEventId] description: Column to order by order_dir: type: str default: "DESC" required: false + choices: [ASC, DESC] description: Sort direction (ASC or DESC) limit: type: int diff --git a/src/pt_snap_cli/query/templates/basic/event.yaml b/src/pt_snap_cli/query/templates/basic/event.yaml index 8d7ad5f..a182abf 100644 --- a/src/pt_snap_cli/query/templates/basic/event.yaml +++ b/src/pt_snap_cli/query/templates/basic/event.yaml @@ -59,11 +59,13 @@ queries: type: str default: "id" required: false + choices: [id, action, address, size, stream, allocated, active, reserved, callstack] description: Column to order by order_dir: type: str default: "ASC" required: false + choices: [ASC, DESC] description: Sort direction (ASC or DESC) limit: type: int diff --git a/src/pt_snap_cli/query/templates/statistical/active_blocks_at_event.yaml b/src/pt_snap_cli/query/templates/statistical/active_blocks_at_event.yaml index a0bddda..227f470 100644 --- a/src/pt_snap_cli/query/templates/statistical/active_blocks_at_event.yaml +++ b/src/pt_snap_cli/query/templates/statistical/active_blocks_at_event.yaml @@ -23,11 +23,13 @@ queries: type: str default: "size" required: false + choices: [size, requestedSize, allocEventId, freeEventId, id] description: Sort key (size, requestedSize, allocEventId, freeEventId, id) order_dir: type: str default: "DESC" required: false + choices: [ASC, DESC] description: Sort direction (ASC or DESC) limit: type: int diff --git a/tests/query/test_config.py b/tests/query/test_config.py index 0a49148..e6bf7a0 100644 --- a/tests/query/test_config.py +++ b/tests/query/test_config.py @@ -48,6 +48,53 @@ def test_validate_invalid_type(self): with pytest.raises(TypeError): param.validate("not a number") + def test_validate_choices_accepts_declared_value(self): + param = QueryParameter(name="order_by", type="str", default="id", choices=["id", "size"]) + assert param.validate("size") == "size" + + def test_validate_str_choices_are_case_insensitive_and_canonical(self): + param = QueryParameter(name="order_dir", type="str", default="ASC", choices=["ASC", "DESC"]) + assert param.validate("desc") == "DESC" + assert param.validate("Asc") == "ASC" + + def test_validate_choices_rejects_undeclared_value(self): + param = QueryParameter(name="order_by", type="str", default="id", choices=["id", "size"]) + with pytest.raises( + ValueError, match=r"'order_by' must be one of: id, size \(got '\(SELECT 1\)'\)" + ): + param.validate("(SELECT 1)") + + def test_validate_int_choices_match_after_conversion(self): + param = QueryParameter(name="level", type="int", default=1, choices=[1, 2, 3]) + assert param.validate("2") == 2 + with pytest.raises(ValueError, match="'level' must be one of: 1, 2, 3"): + param.validate("4") + + def test_validate_missing_optional_with_choices_returns_default(self): + param = QueryParameter(name="order_dir", type="str", default="ASC", choices=["ASC", "DESC"]) + assert param.validate(None) == "ASC" + + def test_choices_default_is_canonicalized(self): + param = QueryParameter( + name="order_dir", type="str", default="desc", choices=["ASC", "DESC"] + ) + assert param.default == "DESC" + assert param.validate(None) == "DESC" + + def test_optional_choices_without_default_may_be_omitted(self): + param = QueryParameter(name="order_by", type="str", choices=["id", "size"]) + assert param.validate(None) is None + + def test_choices_default_must_be_a_choice(self): + with pytest.raises(ValueError, match="default 'name' is not one of its choices"): + QueryParameter(name="order_by", type="str", default="name", choices=["id", "size"]) + + def test_choices_must_be_a_non_empty_list(self): + with pytest.raises(ValueError, match="choices must be a non-empty list"): + QueryParameter(name="order_by", type="str", choices=[]) + with pytest.raises(ValueError, match="choices must be a non-empty list"): + QueryParameter(name="order_by", type="str", choices="id") + class TestQueryTemplate: def test_from_dict(self): @@ -151,6 +198,74 @@ def test_from_dict_rejects_query_and_query_variants(self): } ) + def test_validate_params_rejects_unknown_parameter(self): + """A misspelled filter must fail loudly instead of silently widening the query.""" + template = QueryTemplate( + name="leak_detection", + parameters={ + "min_size": QueryParameter(name="min_size", type="int", default=0), + "limit": QueryParameter(name="limit", type="int", default=-1), + }, + ) + with pytest.raises( + ValueError, + match=( + r"Unknown parameter\(s\) for template 'leak_detection': min_sze " + r"\(accepted: min_size, limit\)" + ), + ): + template.validate_params({"min_sze": 1024}) + + def test_validate_params_lists_every_unknown_parameter_sorted(self): + template = QueryTemplate( + name="test", + parameters={"min_size": QueryParameter(name="min_size", type="int", default=0)}, + ) + with pytest.raises(ValueError, match=r"test': a_param, z_param \(accepted: min_size\)"): + template.validate_params({"z_param": 1, "a_param": 2, "min_size": 3}) + + def test_validate_params_rejects_unknown_when_template_declares_none(self): + template = QueryTemplate(name="test", parameters={}) + with pytest.raises(ValueError, match=r"test': device_id \(accepted: none\)"): + template.validate_params({"device_id": 0}) + + def test_validate_params_applies_choices(self): + template = QueryTemplate( + name="test", + parameters={ + "order_by": QueryParameter( + name="order_by", type="str", default="id", choices=["id", "size"] + ), + "order_dir": QueryParameter( + name="order_dir", type="str", default="ASC", choices=["ASC", "DESC"] + ), + }, + ) + assert template.validate_params({"order_by": "size", "order_dir": "desc"}) == { + "order_by": "size", + "order_dir": "DESC", + } + with pytest.raises(ValueError, match="'order_dir' must be one of: ASC, DESC"): + template.validate_params({"order_dir": "SIDEWAYS"}) + + def test_from_dict_reads_choices(self): + template = QueryTemplate.from_dict( + { + "name": "test_query", + "parameters": { + "order_dir": { + "type": "str", + "default": "ASC", + "choices": ["ASC", "DESC"], + }, + "min_size": {"type": "int", "default": 0}, + }, + "query": "SELECT 1", + } + ) + assert template.parameters["order_dir"].choices == ["ASC", "DESC"] + assert template.parameters["min_size"].choices is None + class TestQueryConfig: def test_load_yaml_from_string(self): diff --git a/tests/query/test_registry.py b/tests/query/test_registry.py index a298882..dc796b6 100644 --- a/tests/query/test_registry.py +++ b/tests/query/test_registry.py @@ -1,9 +1,14 @@ """Tests for query registry.""" +from pathlib import Path + +import pytest + from pt_snap_cli.query.config import QueryParameter, QueryTemplate from pt_snap_cli.query.registry import ( QueryRegistry, _load_all_templates, + _load_yaml_templates, get_query, get_template_info, list_by_category, @@ -233,6 +238,72 @@ def test_block_template_schema_includes_every_selected_column(self): "freeEventId", ] + def test_packaged_sql_fragment_parameters_declare_choices(self): + """Regression for issue #120. + + ``order_by`` / ``order_dir`` are rendered into SQL as an identifier and a + keyword, so a bare ``str`` type would let any SQL fragment reach the + database. Every packaged template that exposes them must bound them + with ``choices`` drawn from its own output columns. + """ + checked = 0 + for name in list_queries(): + template = get_query(name) + assert template is not None + columns = {column["column"] for column in template.output_schema} + for param_name in ("order_by", "order_dir"): + param = template.parameters.get(param_name) + if param is None: + continue + checked += 1 + assert param.choices, f"{name}.{param_name} must declare choices" + if param_name == "order_dir": + assert param.choices == ["ASC", "DESC"], f"{name}.order_dir choices" + else: + unknown = set(param.choices) - columns + assert not unknown, f"{name}.order_by choices not in output_schema: {unknown}" + assert ( + checked >= 8 + ), "expected order_by/order_dir on allocation, block, event, active_blocks" + + def test_invalid_choices_yaml_is_warned_and_skipped(self, tmp_path: Path) -> None: + yaml_file = tmp_path / "broken_choices.yaml" + yaml_file.write_text( + "\n".join( + [ + 'version: "1.0"', + "queries:", + " broken_choices:", + " description: empty choices must not register", + " parameters:", + " order_dir:", + " type: str", + " default: ASC", + " choices: []", + " query: SELECT 1", + "", + ] + ), + encoding="utf-8", + ) + + with pytest.warns(UserWarning, match="Failed to load query template from"): + _load_yaml_templates(tmp_path) + + assert get_query("broken_choices") is None + + def test_template_info_exposes_choices(self): + info = get_template_info("allocation") + assert info is not None + assert info["parameters"]["order_by"]["choices"] == [ + "id", + "allocated", + "active", + "reserved", + ] + assert info["parameters"]["order_dir"]["choices"] == ["ASC", "DESC"] + assert info["parameters"]["limit"]["choices"] is None + def test_list_by_category_with_details(self): register_query( QueryTemplate( diff --git a/tests/test_cli.py b/tests/test_cli.py index 7c61261..19f2676 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -454,6 +454,55 @@ def test_template_info_with_complex_parameters(self, sample_db: Path) -> None: assert "(optional)" in result.stdout assert "[default:" in result.stdout + def test_template_info_shows_choices(self, sample_db: Path) -> None: + from pt_snap_cli.query.config import QueryParameter + + register_query( + QueryTemplate( + name="ordered", + query="SELECT 1 ORDER BY {{ order_by }} {{ order_dir }}", + parameters={ + "order_by": QueryParameter( + name="order_by", type="str", default="id", choices=["id", "size"] + ), + "order_dir": QueryParameter( + name="order_dir", type="str", default="ASC", choices=["ASC", "DESC"] + ), + "limit": QueryParameter(name="limit", type="int", default=-1), + }, + ) + ) + + result = runner.invoke(app, ["query", str(sample_db), "--template-info", "ordered"]) + + assert result.exit_code == 0 + output = unstyle(result.stdout) + assert " order_by: str (optional) [choices: id, size] [default: id]" in output + assert " order_dir: str (optional) [choices: ASC, DESC] [default: ASC]" in output + assert " limit: int (optional) [default: -1]" in output + + def test_template_info_example_uses_first_choice_when_str_has_no_default( + self, sample_db: Path + ) -> None: + from pt_snap_cli.query.config import QueryParameter + + register_query( + QueryTemplate( + name="choice_example", + query="SELECT 1 ORDER BY {{ order_by }}", + parameters={ + "order_by": QueryParameter(name="order_by", type="str", choices=["id", "size"]), + }, + ) + ) + + result = runner.invoke(app, ["query", str(sample_db), "--template-info", "choice_example"]) + + assert result.exit_code == 0 + output = unstyle(result.stdout) + assert '"order_by": "id"' in output + assert '"order_by": "example"' not in output + def test_template_info_without_parameters(self, sample_db: Path) -> None: """Test template info with no parameters.""" template = QueryTemplate( @@ -959,6 +1008,93 @@ def test_query_invalid_parameter_type_is_controlled(self, sample_db: Path) -> No assert "Error executing query" in result.stdout assert "cannot be converted to int" in result.stdout + def test_query_unknown_parameter_is_rejected(self, sample_db: Path) -> None: + """Regression for issue #120: a misspelled filter must not be silently dropped.""" + from pt_snap_cli.query.config import QueryParameter + + register_query( + QueryTemplate( + name="filtered", + query="SELECT * FROM trace_entry_0 WHERE size >= {{ min_size }}", + parameters={"min_size": QueryParameter(name="min_size", type="int", default=0)}, + ) + ) + + result = runner.invoke( + app, + ["query", str(sample_db), "--template-use", "filtered", "--params", '{"min_sze": 1}'], + ) + + assert result.exit_code == 1 + assert "Error executing query" in result.stdout + assert "Unknown parameter(s) for template 'filtered': min_sze (accepted: min_size)" in ( + result.stdout + ) + + def test_query_sql_fragment_parameter_outside_choices_is_rejected( + self, sample_db: Path + ) -> None: + """Regression for issue #120: ORDER BY inputs are bounded before rendering.""" + from pt_snap_cli.query.config import QueryParameter + + register_query( + QueryTemplate( + name="ordered", + query="SELECT * FROM trace_entry_0 ORDER BY {{ order_by }} {{ order_dir }}", + parameters={ + "order_by": QueryParameter( + name="order_by", type="str", default="id", choices=["id", "size"] + ), + "order_dir": QueryParameter( + name="order_dir", type="str", default="ASC", choices=["ASC", "DESC"] + ), + }, + ) + ) + + injected = runner.invoke( + app, + [ + "query", + str(sample_db), + "--template-use", + "ordered", + "--params", + '{"order_by": "(SELECT name FROM sqlite_master LIMIT 1)"}', + ], + ) + assert injected.exit_code == 1 + assert "Parameter 'order_by' must be one of: id, size" in injected.stdout + assert "syntax error" not in injected.stdout + + bad_direction = runner.invoke( + app, + [ + "query", + str(sample_db), + "--template-use", + "ordered", + "--params", + '{"order_dir": "UP"}', + ], + ) + assert bad_direction.exit_code == 1 + assert "Parameter 'order_dir' must be one of: ASC, DESC (got 'UP')" in bad_direction.stdout + + accepted = runner.invoke( + app, + [ + "query", + str(sample_db), + "--template-use", + "ordered", + "--params", + '{"order_by": "size", "order_dir": "desc"}', + ], + ) + assert accepted.exit_code == 0 + assert "Found 1 results" in accepted.stdout + def test_query_list_by_category(self, sample_db: Path) -> None: """Test 'query --list --category basic' filters by category.""" register_query( diff --git a/tests/test_contract_cli_mcp.py b/tests/test_contract_cli_mcp.py index 9273c52..bb524b4 100644 --- a/tests/test_contract_cli_mcp.py +++ b/tests/test_contract_cli_mcp.py @@ -186,11 +186,16 @@ def _normalize_cli_template_info(output: str) -> dict[str, object]: if "[default: " in metadata: default_text = metadata.split("[default: ", 1)[1].removesuffix("]") default = _coerce_cli_default(default_text) + choices = None + if "[choices: " in metadata: + choices_text = metadata.split("[choices: ", 1)[1].split("]", 1)[0] + choices = [_coerce_cli_default(item) for item in choices_text.split(", ")] info["parameters"][name] = { "type": param_type, "default": default, "required": required, "description": "", + "choices": choices, } current_param = name elif section == "parameters" and current_param and line.startswith(" "): @@ -273,17 +278,24 @@ def test_template_info_contract_matches_cli_and_mcp_semantics( ) -> None: cli_result = runner.invoke( app, - ["query", str(contract_db), "--template-info", "leak_detection"], + ["query", str(contract_db), "--template-info", "allocation"], ) assert cli_result.exit_code == 0 - assert "Category: business" in cli_result.stdout - assert "Devices: all, 0, 1" in cli_result.stdout + assert "Category: basic" in cli_result.stdout + assert "Devices: all" in cli_result.stdout server = _set_mcp_focus(mcp_server, contract_db) cli_info = _normalize_cli_template_info(cli_result.stdout) - mcp_info = server.get_template_info("leak_detection") + mcp_info = server.get_template_info("allocation") assert cli_info == mcp_info + assert cli_info["parameters"]["order_by"]["choices"] == [ + "id", + "allocated", + "active", + "reserved", + ] + assert cli_info["parameters"]["order_dir"]["choices"] == ["ASC", "DESC"] def test_leak_detection_template_does_not_advertise_device_id( @@ -421,6 +433,52 @@ def test_missing_focus_error_contract_matches_cli_and_mcp_semantics( assert str(exc_info.value) == "No database configured. Call set_focus() first." +def test_unknown_parameter_error_contract_matches_cli_and_mcp_semantics( + contract_db: Path, mcp_server: ModuleType +) -> None: + """Regression for issue #120: both surfaces reject undeclared parameters identically.""" + cli_result = runner.invoke( + app, + [ + "query", + str(contract_db), + "--template-use", + "leak_detection", + "--params", + '{"min_sze": 1024}', + ], + ) + assert cli_result.exit_code == 1 + + server = _set_mcp_focus(mcp_server, contract_db) + with pytest.raises(TemplateRenderError) as exc_info: + server.execute_query("leak_detection", params={"min_sze": 1024}) + + assert "Unknown parameter(s) for template 'leak_detection': min_sze" in str(exc_info.value) + assert str(exc_info.value) in cli_result.stdout + + +def test_choices_error_contract_matches_cli_and_mcp_semantics( + contract_db: Path, mcp_server: ModuleType +) -> None: + """Regression for issue #120: SQL fragment parameters are bounded on both surfaces.""" + params = {"order_by": "(SELECT 1)", "order_dir": "ASC"} + cli_result = runner.invoke( + app, + ["query", str(contract_db), "--template-use", "allocation", "--params", json.dumps(params)], + ) + assert cli_result.exit_code == 1 + + server = _set_mcp_focus(mcp_server, contract_db) + with pytest.raises(TemplateRenderError) as exc_info: + server.execute_query("allocation", params=params) + + assert "Parameter 'order_by' must be one of: id, allocated, active, reserved" in str( + exc_info.value + ) + assert str(exc_info.value) in cli_result.stdout + + def test_missing_template_error_contract_matches_cli_and_mcp_semantics( mcp_server: ModuleType, ) -> None: