Files
rdbms-playground/src/friendly/keys.rs
T
claude@clouddev1 f1ff5970bf Hint: pedagogical Form-A pointer at Form B's first value slot
Handoff-12 §2.2: Form B `insert into T values (…)` silently skips
auto-generated columns from the value list, so a user who wants to
set a serial/shortid column explicitly could only discover Form A by
reading help. Now the hint at the first Form B value slot appends a
note naming the skipped column(s) and pointing at the explicit-column
form.

hint_resolution_at_input derives the skipped columns from the
post-walk WalkContext (Form B = no user_listed_columns + table has
serial/shortid columns) and reports them on HintResolution; the note
fires only at the first slot so it doesn't repeat at every comma.
ambient_hint composes it onto the per-column prose.
2026-05-15 21:30:03 +00:00

575 lines
22 KiB
Rust

//! Per-category catalog key schemas (ADR-0019 §8.3).
//!
//! Every catalog key the friendly-error layer references at
//! runtime is enumerated here together with its expected
//! placeholder set. The validator
//! (`tests::keys_validate_against_catalog`) walks this list and
//! asserts:
//!
//! - the key exists in the catalog;
//! - every placeholder declared here appears at least once in
//! the template;
//! - no placeholder appears in the template that isn't declared
//! here (catches typos in either direction);
//! - every catalog key (outside the `_test.*` sanity group) is
//! declared here (catches dead YAML entries).
//!
//! Adding a new translation site is a two-step change: add the
//! key + placeholders here, add the YAML entry. Either alone
//! fails the validator.
//!
//! ## Convention
//!
//! Each error entry in the catalog has:
//!
//! - a `.headline` template — used in both short and verbose
//! modes;
//! - optionally a `.hint` template — surfaced only in verbose
//! mode.
//!
//! Single-line errors (object-not-found, already-exists,
//! invalid-value) have no hint; the headline carries the whole
//! message.
//!
//! Other categories (`help.*`, `ok.*`, `client_side.*`,
//! `replay.*`, `parse.*`, modal labels, …) get added to this
//! list as the migration sweep (ADR-0019 §9) lands them.
/// `(key, expected_placeholders)`. Sorted by key for grep-ability.
pub const KEYS_AND_PLACEHOLDERS: &[(&str, &[&str])] = &[
// ---- Already-exists collisions (anchor: "already exists") ----
("error.already_exists.column.headline", &["table", "column"]),
("error.already_exists.relationship.headline", &["name"]),
("error.already_exists.table.headline", &["name"]),
// ---- CHECK violations ----
("error.check.insert.headline", &["table", "column"]),
("error.check.insert.hint", &["column"]),
("error.check.update.headline", &["table", "column"]),
("error.check.update.hint", &["column"]),
// ---- FK violations (anchor: "referenced by") ----
(
"error.foreign_key.child_side.insert.headline",
&["parent_table", "parent_column", "value"],
),
(
"error.foreign_key.child_side.insert.hint",
&["parent_table", "parent_column"],
),
(
"error.foreign_key.child_side.update.headline",
&["parent_table", "parent_column", "value"],
),
(
"error.foreign_key.child_side.update.hint",
&["parent_table", "parent_column"],
),
(
"error.foreign_key.parent_side.delete.headline",
&["table", "child_table"],
),
("error.foreign_key.parent_side.delete.hint", &[]),
(
"error.foreign_key.parent_side.update.headline",
&["table", "child_table"],
),
("error.foreign_key.parent_side.update.hint", &[]),
// ---- Generic engine refusal ----
("error.generic.headline", &["operation"]),
("error.generic.hint", &["table"]),
// ---- Invalid-value errors (pre-engine, single-line) ----
(
"error.invalid_value.arity.headline",
&["expected", "actual"],
),
("error.invalid_value.empty_insert.headline", &[]),
("error.invalid_value.empty_update.headline", &[]),
// ---- Not-found errors (anchor: "no such ...") ----
("error.not_found.column.headline", &["table", "column"]),
("error.not_found.column_unqualified.headline", &["column"]),
("error.not_found.relationship.headline", &["name"]),
("error.not_found.table.headline", &["name"]),
// ---- NOT NULL violations ----
("error.not_null.insert.headline", &["table", "column"]),
("error.not_null.insert.hint", &["column"]),
("error.not_null.update.headline", &["table", "column"]),
("error.not_null.update.hint", &["column"]),
// ---- Type mismatch ----
(
"error.type_mismatch.change_column.headline",
&["table", "column", "src_type", "target_type"],
),
(
"error.type_mismatch.change_column.hint",
&["target_type"],
),
(
"error.type_mismatch.insert.headline",
&["value", "expected_type"],
),
(
"error.type_mismatch.insert.hint",
&["table", "column", "expected_type"],
),
(
"error.type_mismatch.update.headline",
&["value", "expected_type"],
),
(
"error.type_mismatch.update.hint",
&["table", "column", "expected_type"],
),
// ---- Help text ----
("help.cli_banner", &[]),
("help.in_app_body", &[]),
// ---- Hint panel ambient typing assistance (ADR-0022 §6) ----
("hint.ambient_complete", &[]),
(
"hint.ambient_error_with_usage",
&["message", "usage"],
),
("hint.ambient_expected", &["expected"]),
(
"hint.ambient_invalid_ident",
&["kind", "found"],
),
("hint.ambient_typing_name", &[]),
("hint.value_literal_slot", &[]),
(
"hint.ambient_typing_name_then",
&["next"],
),
// Per-column-type value-slot hints (ADR-0024 §Phase D).
("hint.value_slot_blob", &[]),
("hint.value_slot_bool", &[]),
("hint.value_slot_date", &[]),
("hint.value_slot_datetime", &[]),
("hint.value_slot_decimal", &[]),
("hint.value_slot_int", &[]),
("hint.value_slot_real", &[]),
("hint.value_slot_serial", &[]),
("hint.value_slot_shortid", &[]),
("hint.value_slot_text", &[]),
("hint.value_slot_for_column", &["column", "detail"]),
("hint.value_slot_autogen_skipped", &["columns"]),
// ---- Parse error rendering ----
("parse.available_commands", &["commands"]),
("parse.caret", &["padding"]),
// Custom (try_map / source-slice) error messages raised
// by the DSL parser. See `parse.custom.*` in the catalog.
("parse.custom.bind_type_mismatch", &["found", "expected"]),
("parse.custom.change_column_flags_exclusive", &[]),
("parse.custom.create_table_needs_pk", &[]),
("parse.custom.insert_form_a_missing_values", &["columns"]),
("parse.custom.on_action_specified_twice", &["target"]),
("parse.custom.replay_path_expected", &[]),
("parse.custom.unknown_action", &["found", "expected"]),
("parse.custom.unknown_type", &["found", "expected"]),
("parse.empty", &[]),
("parse.error", &["detail"]),
("parse.error_wrapper", &["detail"]),
// Per-command usage templates (ADR-0021 §1). One key per
// command. Multi-entry families (`add`, `drop`, `show`)
// each have multiple keys. Templates are pure prose with
// no placeholders — the renderer prepends "usage: " in
// code, not the catalog, because spacing is alignment-
// sensitive in the multi-entry case.
("parse.usage.add_column", &[]),
("parse.usage.add_relationship", &[]),
("parse.usage.change_column", &[]),
("parse.usage.create_table", &[]),
("parse.usage.delete", &[]),
("parse.usage.drop_column", &[]),
("parse.usage.drop_relationship", &[]),
("parse.usage.drop_table", &[]),
("parse.usage.insert", &[]),
("parse.usage.rename_column", &[]),
("parse.usage.export", &[]),
("parse.usage.help", &[]),
("parse.usage.import", &[]),
("parse.usage.load", &[]),
("parse.usage.messages", &[]),
("parse.usage.mode", &[]),
("parse.usage.new", &[]),
("parse.usage.quit", &[]),
("parse.usage.rebuild", &[]),
("parse.usage.replay", &[]),
("parse.usage.save", &[]),
("parse.usage.show_data", &[]),
("parse.usage.show_table", &[]),
("parse.usage.update", &[]),
// ---- Project lifecycle event notes ----
("project.export_failed", &["error"]),
("project.export_ok", &["path"]),
("project.export_usage", &[]),
("project.import_empty_target", &[]),
("project.import_usage", &[]),
("project.import_zip_missing", &["path"]),
("persistence.csv.empty", &[]),
("persistence.csv.invalid_utf8", &[]),
("persistence.csv.unterminated_quote", &[]),
("persistence.encode", &["kind", "path", "message"]),
("persistence.io", &["operation", "path", "source"]),
("persistence.migrate.bad_output", &["detail"]),
("persistence.migrate.io", &["path", "source"]),
(
"persistence.migrate.newer_than_supported",
&["file", "latest"],
),
("persistence.migrate.no_migrator", &["version"]),
("persistence.migrate.step_failed", &["from", "to", "source"]),
("persistence.migrate.version_parse", &["detail"]),
("persistence.yaml.syntax", &["detail"]),
("persistence.yaml.unknown_action", &["raw"]),
("persistence.yaml.unknown_type", &["table", "column", "raw"]),
("persistence.yaml.unsupported_version", &["version"]),
("project.already_exists", &["path"]),
("project.data_root_unavailable", &[]),
("project.io", &["path", "source"]),
("project.load_path_missing", &["path"]),
("project.lock.already_held", &["pid", "hostname", "path"]),
("project.lock.read", &["path", "source"]),
("project.lock.write", &["path", "source"]),
("project.naming.too_many_collisions", &["attempts"]),
("project.naming.wordlist_too_small", &["count"]),
("project.not_a_project", &["path"]),
("project.path_not_found", &["path"]),
("project.safe_delete.io", &["path", "source"]),
("project.safe_delete.refused", &["path", "reason"]),
("project.user_name.empty", &[]),
("project.user_name.invalid_char", &["ch"]),
("project.user_name.leading_dot", &[]),
("project.resume_no_previous", &["data_root"]),
("project.resume_recorded_missing", &["path"]),
("project.saveas_target_exists", &["path"]),
("project.rebuild_failed", &["error"]),
("project.rebuild_ok", &["summary"]),
("project.switch_failed", &["error"]),
("project.switched_ok", &["display_name"]),
// ---- Advanced-mode placeholder ----
("advanced_mode.not_implemented", &["input"]),
(
"cli.invalid_value",
&["flag", "value", "expected"],
),
("cli.missing_value", &["flag"]),
("cli.multiple_paths", &["first", "second"]),
("cli.resume_with_path", &[]),
("cli.unknown_argument", &["arg"]),
(
"archive.export_sequence_exhausted",
&["project", "target_dir", "limit"],
),
("archive.import_collision_exhausted", &["path", "limit"]),
("archive.invalid_zip", &["detail"]),
("archive.io", &["path", "source"]),
("archive.multiple_top_folders", &[]),
("archive.not_a_project_archive", &[]),
("archive.unsafe_entry", &["entry"]),
("archive.zip", &["path", "message"]),
// ---- DSL failure wrapper / running echo ----
("dsl.failed", &["verb", "subject", "rendered"]),
("dsl.running", &["input"]),
// ---- Persistence-fatal banner ----
("fatal.persistence", &["operation", "path", "message"]),
// ---- Modal labels ----
("modal.generic_cancelled", &["title"]),
("modal.load_cancelled", &[]),
("modal.load_picker_empty", &[]),
("modal.load_picker_nothing", &[]),
("modal.load_picker_path_prompt", &[]),
("modal.load_picker_title", &[]),
("modal.path_entry_empty_name", &[]),
("modal.path_entry_empty_path", &[]),
("modal.rebuild_cancelled", &[]),
("modal.rebuild_confirm_prompt", &[]),
("modal.rebuild_confirm_title", &[]),
// ---- Status bar + panels ----
("panel.hint_empty", &[]),
("panel.hint_title", &[]),
("panel.output_title", &[]),
("panel.tables_empty", &[]),
("panel.tables_title", &[]),
("status.no_project", &[]),
("status.project_label", &[]),
("value.format", &["column", "message"]),
("value.type_mismatch", &["column", "expected_human", "got"]),
// ---- Save / save-as surfaces ----
("save.already_saved", &[]),
("save.path_prompt", &[]),
("save.title_as", &[]),
("save.title_save", &[]),
// ---- Shortcut hint labels ----
("shortcut.advanced_once", &[]),
("shortcut.back_to_list", &[]),
("shortcut.browse_path", &[]),
("shortcut.cancel", &[]),
("shortcut.cancel_one_shot", &[]),
("shortcut.confirm", &[]),
("shortcut.load", &[]),
("shortcut.no", &[]),
("shortcut.quit", &[]),
("shortcut.select", &[]),
("shortcut.submit", &[]),
("shortcut.switch", &[]),
("shortcut.yes", &[]),
// ---- mode / messages banners ----
("messages.set_short", &[]),
("messages.set_verbose", &[]),
("messages.show", &["current"]),
("messages.unknown", &["value"]),
("mode.label_advanced", &[]),
("mode.label_advanced_one_shot", &[]),
("mode.label_simple", &[]),
("mode.set_advanced", &[]),
("mode.set_simple", &[]),
("mode.show_advanced", &[]),
("mode.show_simple", &[]),
("mode.unknown", &["value"]),
("mode.usage", &[]),
// ---- DbError Display fallback ----
("db.error.invalid_value", &["detail"]),
("db.error.io", &["detail"]),
(
"db.error.persistence_fatal",
&["operation", "path", "message"],
),
(
"db.error.rebuild_row_failed",
&["row_number", "csv_path", "table", "detail"],
),
("db.error.sqlite", &["message"]),
("db.error.unsupported", &["detail"]),
("db.error.worker_gone", &[]),
// ---- Cascade-effect summaries (per ADR-0014) ----
("db.cascade.action_blocked", &[]),
("db.cascade.action_deleted", &[]),
("db.cascade.action_set_null", &[]),
(
"db.cascade.summary",
&["count", "action", "child_table", "rel", "on_delete"],
),
// ---- change-column dry-run diagnostics (per ADR-0017) ----
("db.diagnostic.force_conversion_hint", &[]),
("db.diagnostic.header_becomes", &[]),
("db.diagnostic.header_from", &[]),
("db.diagnostic.header_reason", &[]),
("db.diagnostic.header_source_rows", &["pk_label"]),
("db.diagnostic.header_source_values", &[]),
("db.diagnostic.header_to", &[]),
("db.diagnostic.header_value", &[]),
(
"db.diagnostic.incompatible_summary",
&["table", "column", "src_ty", "target_ty", "total"],
),
(
"db.diagnostic.lossy_summary",
&["table", "column", "src_ty", "target_ty", "total"],
),
(
"db.diagnostic.uniqueness_summary",
&["table", "column", "src_ty", "target_ty", "total"],
),
// ---- DSL command success summaries (ADR-0019 §9 sweep) ----
("ok.rows_deleted", &["count"]),
("ok.rows_inserted", &["count"]),
("ok.rows_updated", &["count"]),
("ok.summary", &["verb", "subject"]),
// ---- Client-side success notes (ADR-0017 §6, ADR-0018 §9) ----
("client_side.auto_fill_add_serial", &["count"]),
("client_side.auto_fill_add_shortid", &["count"]),
("client_side.auto_fill_transition", &["count", "kind"]),
("client_side.transformed", &["count"]),
("client_side.transformed_lossy", &["count", "lossy"]),
// ---- Replay command surfaces (ADR-0019 §9 sweep) ----
("replay.command_echo", &["command"]),
("replay.completed", &["path", "count"]),
("replay.error_could_not_open", &["path", "detail"]),
("replay.error_nested", &[]),
("replay.error_parse", &["detail"]),
("replay.failed_at_line", &["path", "line_number", "error"]),
("replay.failed_open", &["path", "error"]),
// ---- UNIQUE violations (anchor: "already has the value") ----
(
"error.unique.insert.headline",
&["table", "column", "value"],
),
("error.unique.insert.hint", &["table", "column"]),
("error.unique.pk.insert.headline", &["table", "value"]),
("error.unique.pk.insert.hint", &[]),
("error.unique.pk.update.headline", &["table", "value"]),
("error.unique.pk.update.hint", &[]),
(
"error.unique.update.headline",
&["table", "column", "value"],
),
("error.unique.update.hint", &["table", "column"]),
];
#[cfg(test)]
mod tests {
use super::KEYS_AND_PLACEHOLDERS;
use crate::friendly::format::catalog;
use std::collections::HashSet;
// The pre-Phase-F `keyword_and_punct_have_complete_token_vocabulary`
// test cross-checked the `Keyword` / `Punct` enums against
// `parse.token.keyword.*` / `parse.token.punct.*` catalog
// keys. With those enums deleted (ADR-0024 §migration Phase F)
// and the walker rendering keyword wording via
// `format!("`{word}`")`, the catalog entries survive only as
// historic vocabulary; the `keys_validate_against_catalog`
// test below still asserts every key in `KEYS_AND_PLACEHOLDERS`
// resolves and vice versa, which keeps the catalog itself
// honest. The dead entries collapse in ADR-0024 §cleanup-pass.
/// Walks `KEYS_AND_PLACEHOLDERS` and verifies every entry
/// matches the catalog. ADR-0019 §8.6.
///
/// Checks:
/// 1. every declared key exists in the catalog;
/// 2. every declared placeholder appears in the template;
/// 3. every placeholder used is declared (catches typos);
/// 4. every catalog key (outside `_test.*`) is declared
/// (catches dead YAML entries);
/// 5. no template contains a format specifier
/// (`{name:...}`); ADR-0019 §8.4 forbids these;
/// 6. no template contains forbidden engine vocabulary
/// (ADR-0002 user-facing posture; same forbidden list
/// as `tests/engine_vocabulary_audit.rs`).
#[test]
fn keys_validate_against_catalog() {
let cat = catalog();
let mut errors: Vec<String> = Vec::new();
for (key, expected) in KEYS_AND_PLACEHOLDERS {
let Some(template) = cat.get(key) else {
errors.push(format!("catalog missing key `{key}`"));
continue;
};
// Placeholder set check (declared ↔ used).
let actual = collect_placeholders(template);
let expected_set: HashSet<&str> = expected.iter().copied().collect();
for name in &expected_set {
if !actual.contains(*name) {
errors.push(format!(
"key `{key}`: declared placeholder `{{{name}}}` is not used in template:\n{template}"
));
}
}
for name in &actual {
if !expected_set.contains(name.as_str()) {
errors.push(format!(
"key `{key}`: template uses `{{{name}}}` but it isn't declared in keys.rs:\n{template}"
));
}
}
// Format-specifier check (ADR-0019 §8.4). Look for
// `{name:...}` shapes — the substitute helper would
// panic at runtime, but catching it at test time
// means we never ship a binary that can hit that
// panic.
if has_format_specifier(template) {
errors.push(format!(
"key `{key}`: template contains a `{{name:...}}` format specifier:\n{template}"
));
}
// Engine-vocabulary check (ADR-0002 user-facing
// posture, regression-tested in
// tests/engine_vocabulary_audit.rs).
for needle in FORBIDDEN_ENGINE_VOCABULARY {
if template.contains(needle) {
errors.push(format!(
"key `{key}`: template contains forbidden token `{needle}`:\n{template}"
));
}
}
}
let declared: HashSet<&str> =
KEYS_AND_PLACEHOLDERS.iter().map(|(k, _)| *k).collect();
for key in cat.keys() {
if key.starts_with("_test.") {
continue;
}
if !declared.contains(key) {
errors.push(format!(
"catalog has key `{key}` but it isn't declared in keys::KEYS_AND_PLACEHOLDERS"
));
}
}
assert!(
errors.is_empty(),
"catalog validation failed:\n {}",
errors.join("\n ")
);
}
/// Mirror of `tests/engine_vocabulary_audit.rs::FORBIDDEN`,
/// duplicated here so the catalog validator is self-contained
/// (no dependency on the integration-test binary).
const FORBIDDEN_ENGINE_VOCABULARY: &[&str] = &[
"SQLite", "sqlite", "rusqlite", "STRICT", "PRAGMA",
];
/// Detect a `{name:...}` format-specifier placeholder.
/// Doubled braces `{{` / `}}` are escapes — must skip them.
fn has_format_specifier(template: &str) -> bool {
let mut chars = template.chars().peekable();
while let Some(c) = chars.next() {
if c == '{' {
if chars.peek() == Some(&'{') {
chars.next();
continue;
}
while let Some(&nc) = chars.peek() {
if nc == '}' {
break;
}
if nc == ':' {
return true;
}
chars.next();
}
} else if c == '}' && chars.peek() == Some(&'}') {
chars.next();
}
}
false
}
/// Walk `template` and pull out every `{name}` placeholder.
/// Mirrors the substitution helper's parse — if the helper
/// accepts a placeholder, this collects it.
fn collect_placeholders(template: &str) -> HashSet<String> {
let mut out = HashSet::new();
let mut chars = template.chars().peekable();
while let Some(c) = chars.next() {
if c == '{' {
if chars.peek() == Some(&'{') {
chars.next();
continue;
}
let mut name = String::new();
while let Some(&nc) = chars.peek() {
if nc == '}' {
chars.next();
break;
}
chars.next();
name.push(nc);
}
if !name.is_empty() && !name.contains(':') {
out.insert(name);
}
} else if c == '}' && chars.peek() == Some(&'}') {
chars.next();
}
}
out
}
}