ZacharyZhang-NY
a02b555e66
Sweep every first-party crate source (1956 .rs files) to the project comment guidelines: delete redundant restatements, decorative banners, change narration, and end-of-line comments; keep and tighten the crucial ones (invariants, bug rationale, SAFETY blocks, ported-source attribution). No functional code changed. Every edit is proven comment-only against the prior tree by a comment-stripping lexer (string/char/raw-string aware) plus a separate doctest-fence check. Where removing a comment made rustfmt or clippy want to re-lay-out adjacent code, the minimal triggering comment is restored so code tokens stay byte-identical. Gates green: cargo fmt --all --check (0 diffs), cargo check and cargo clippy --workspace --all-targets (0 warnings). Adds scripts/check_codegen_comment_guidelines.py — the enforcement gate for these guidelines (flags banners, end-of-line comments, change narration, and commented-out code).
912 lines
32 KiB
Rust
912 lines
32 KiB
Rust
//! Behavior version catalog for version-managed tools.
|
|
//!
|
|
//! This module defines which tools are version-managed, the available behavior
|
|
//! presets (e.g. `"current"`, `"legacy-0.4.10"`), and the resolution logic that
|
|
//! maps (preset, tool_id, per_tool_override) → concrete `contract_version`.
|
|
//!
|
|
//! ## Reminder behavior policy
|
|
//!
|
|
//! Reminders (per-tool and cross-cutting) always use current behavior regardless
|
|
//! of the selected behavior preset. This is a deliberate design choice:
|
|
//! reminders are a quality-of-life feature, not part of the tool contract.
|
|
|
|
use std::collections::HashMap;
|
|
|
|
/// Lifecycle stage of a behavior preset or version.
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
pub enum BehaviorLifecycle {
|
|
/// Fully supported and recommended.
|
|
Active,
|
|
/// Still works but will be removed in a future release.
|
|
Deprecated,
|
|
/// Scheduled for removal — hosts should reject requests using this version.
|
|
RemovalCandidate,
|
|
}
|
|
|
|
/// Per-tool version metadata. Each managed tool has one entry in `TOOL_VERSION_REGISTRY`.
|
|
#[derive(Debug)]
|
|
pub struct ToolVersionEntry {
|
|
/// Fully-qualified tool ID (e.g. `"Kigi:run_terminal_cmd"`).
|
|
pub fq_tool_id: &'static str,
|
|
/// Supported versions and their individual lifecycle.
|
|
pub versions: &'static [VersionLifecycle],
|
|
}
|
|
|
|
/// A single version supported by a tool.
|
|
#[derive(Debug)]
|
|
pub struct VersionLifecycle {
|
|
/// Version string (e.g. `"current"`, `"legacy-0.4.10"`).
|
|
pub version: &'static str,
|
|
/// Independent lifecycle for this tool+version pair.
|
|
pub lifecycle: BehaviorLifecycle,
|
|
/// Suggested replacement when deprecated/removed. Must itself be a
|
|
/// supported Active version for the same tool.
|
|
pub replacement: Option<&'static str>,
|
|
/// Optional deprecation message for operational tooling.
|
|
pub deprecation_note: Option<&'static str>,
|
|
/// The crate release version in which this catalog entry was first added.
|
|
/// This is catalog-introduction metadata, not behavior-origin metadata.
|
|
/// For reconstructed legacy behavior, this is the release that added the
|
|
/// legacy port to the catalog.
|
|
/// Empty string for `"current"` (moving alias with no fixed origin).
|
|
pub cataloged_in: &'static str,
|
|
/// Optional opaque references for humans browsing the catalog.
|
|
/// Prefer empty; do not embed external PR/issue number lists here.
|
|
/// Empty slice for `"current"` (moving alias).
|
|
pub source_refs: &'static [&'static str],
|
|
/// One-line summary of what this version's behavior is.
|
|
/// Empty string for `"current"` (moving alias).
|
|
pub summary: &'static str,
|
|
}
|
|
|
|
/// A named behavior preset (bundle) that maps tool IDs to default contract versions.
|
|
///
|
|
/// Architecturally a "bundle" — a convenience mapping from a label to per-tool
|
|
/// version defaults. Not canonical; must validate against `TOOL_VERSION_REGISTRY`.
|
|
#[derive(Debug)]
|
|
pub struct PresetEntry {
|
|
/// Preset name, e.g. `"current"` or `"legacy-0.4.10"`.
|
|
pub name: &'static str,
|
|
/// Lifecycle stage of this preset.
|
|
pub lifecycle: BehaviorLifecycle,
|
|
/// Per-tool default versions for this preset.
|
|
/// Keys are fully-qualified tool IDs (e.g. `"Kigi:run_terminal_cmd"`).
|
|
/// Tools not listed here fall back to `"current"`.
|
|
pub tool_defaults: &'static [(&'static str, &'static str)],
|
|
}
|
|
|
|
/// Fully-qualified IDs of version-managed tools.
|
|
///
|
|
/// Only tools listed here can have `behavior_version` overrides.
|
|
/// Uses fully-qualified IDs (`Namespace:tool_id`) to prevent collisions
|
|
/// between namespaces (e.g. `Kigi:run_terminal_cmd` vs.
|
|
/// `KigiConcise:run_terminal_cmd`).
|
|
pub const MANAGED_TOOLS: &[&str] = &[
|
|
"Kigi:run_terminal_cmd",
|
|
"Kigi:read_file",
|
|
"Kigi:search_replace",
|
|
"Kigi:list_dir",
|
|
"Kigi:grep",
|
|
"Kigi:kill_task",
|
|
"Kigi:get_task_output",
|
|
];
|
|
|
|
// `V_CURRENT` is a moving alias — its metadata fields are empty because
|
|
// `"current"` changes meaning over time. Stable canonical versions use
|
|
// per-tool legacy constants with tool-specific metadata.
|
|
const V_CURRENT: VersionLifecycle = VersionLifecycle {
|
|
version: "current",
|
|
lifecycle: BehaviorLifecycle::Active,
|
|
replacement: None,
|
|
deprecation_note: None,
|
|
cataloged_in: "",
|
|
source_refs: &[],
|
|
summary: "",
|
|
};
|
|
|
|
// Per-tool legacy constants — each carries tool-specific metadata because
|
|
// the legacy behavior differs per tool.
|
|
const V_LEGACY_BASH: VersionLifecycle = VersionLifecycle {
|
|
version: "legacy-0.4.10",
|
|
lifecycle: BehaviorLifecycle::Active,
|
|
replacement: Some("current"),
|
|
deprecation_note: None,
|
|
cataloged_in: "0.1.158-alpha.1",
|
|
source_refs: &[],
|
|
summary: "Trailing-only & detection, legacy error text for background operator",
|
|
};
|
|
const V_LEGACY_READ_FILE: VersionLifecycle = VersionLifecycle {
|
|
version: "legacy-0.4.10",
|
|
lifecycle: BehaviorLifecycle::Active,
|
|
replacement: Some("current"),
|
|
deprecation_note: None,
|
|
cataloged_in: "0.1.158-alpha.1",
|
|
source_refs: &[],
|
|
summary: "No gitignore enforcement, generic error text, no confusable reminders",
|
|
};
|
|
const V_LEGACY_SEARCH_REPLACE: VersionLifecycle = VersionLifecycle {
|
|
version: "legacy-0.4.10",
|
|
lifecycle: BehaviorLifecycle::Active,
|
|
replacement: Some("current"),
|
|
deprecation_note: None,
|
|
cataloged_in: "0.1.158-alpha.1",
|
|
source_refs: &[],
|
|
summary: "No gitignore enforcement, structured errors downgraded to InvalidInput",
|
|
};
|
|
const V_LEGACY_LIST_DIR: VersionLifecycle = VersionLifecycle {
|
|
version: "legacy-0.4.10",
|
|
lifecycle: BehaviorLifecycle::Active,
|
|
replacement: Some("current"),
|
|
deprecation_note: None,
|
|
cataloged_in: "0.1.158-alpha.1",
|
|
source_refs: &[],
|
|
summary: "Depth-threshold rendering, generic error text, no-children-found for empty dirs",
|
|
};
|
|
const V_LEGACY_KILL_TASK: VersionLifecycle = VersionLifecycle {
|
|
version: "legacy-0.4.10",
|
|
lifecycle: BehaviorLifecycle::Active,
|
|
replacement: Some("current"),
|
|
deprecation_note: None,
|
|
cataloged_in: "0.1.158-alpha.1",
|
|
source_refs: &[],
|
|
summary: "Simple not-found text without known task ID enumeration",
|
|
};
|
|
const V_LEGACY_TASK_OUTPUT: VersionLifecycle = VersionLifecycle {
|
|
version: "legacy-0.4.10",
|
|
lifecycle: BehaviorLifecycle::Active,
|
|
replacement: Some("current"),
|
|
deprecation_note: None,
|
|
cataloged_in: "0.1.158-alpha.1",
|
|
source_refs: &[],
|
|
summary: "Simple not-found text without known task ID enumeration",
|
|
};
|
|
|
|
/// Per-tool version registry — canonical source for which versions each
|
|
/// managed tool supports and their individual lifecycle.
|
|
///
|
|
/// - 7 managed tools total
|
|
/// - 6 legacy-ported (support both `"current"` and `"legacy-0.4.10"`)
|
|
/// - 1 managed but unported (`grep` — only `"current"`)
|
|
///
|
|
/// Each legacy-ported tool has its own `V_LEGACY_*` constant with tool-specific
|
|
/// `summary` and `source_refs`. Do not use a shared legacy constant.
|
|
pub const TOOL_VERSION_REGISTRY: &[ToolVersionEntry] = &[
|
|
ToolVersionEntry {
|
|
fq_tool_id: "Kigi:run_terminal_cmd",
|
|
versions: &[V_CURRENT, V_LEGACY_BASH],
|
|
},
|
|
ToolVersionEntry {
|
|
fq_tool_id: "Kigi:read_file",
|
|
versions: &[V_CURRENT, V_LEGACY_READ_FILE],
|
|
},
|
|
ToolVersionEntry {
|
|
fq_tool_id: "Kigi:search_replace",
|
|
versions: &[V_CURRENT, V_LEGACY_SEARCH_REPLACE],
|
|
},
|
|
ToolVersionEntry {
|
|
fq_tool_id: "Kigi:list_dir",
|
|
versions: &[V_CURRENT, V_LEGACY_LIST_DIR],
|
|
},
|
|
ToolVersionEntry {
|
|
fq_tool_id: "Kigi:grep",
|
|
// Managed but no legacy implementation.
|
|
versions: &[V_CURRENT],
|
|
},
|
|
ToolVersionEntry {
|
|
fq_tool_id: "Kigi:kill_task",
|
|
versions: &[V_CURRENT, V_LEGACY_KILL_TASK],
|
|
},
|
|
ToolVersionEntry {
|
|
fq_tool_id: "Kigi:get_task_output",
|
|
versions: &[V_CURRENT, V_LEGACY_TASK_OUTPUT],
|
|
},
|
|
];
|
|
|
|
/// Available behavior presets.
|
|
///
|
|
/// ## Reminder behavior policy
|
|
///
|
|
/// Reminders always use current behavior regardless of preset selection.
|
|
/// They are not versioned — this is a deliberate design choice (Option B).
|
|
pub const PRESETS: &[PresetEntry] = &[
|
|
PresetEntry {
|
|
name: "current",
|
|
lifecycle: BehaviorLifecycle::Active,
|
|
// All managed tools default to "current" — no per-tool overrides needed.
|
|
tool_defaults: &[],
|
|
},
|
|
PresetEntry {
|
|
name: "legacy-0.4.10",
|
|
lifecycle: BehaviorLifecycle::Active,
|
|
tool_defaults: &[
|
|
("Kigi:run_terminal_cmd", "legacy-0.4.10"),
|
|
("Kigi:read_file", "legacy-0.4.10"),
|
|
("Kigi:search_replace", "legacy-0.4.10"),
|
|
("Kigi:get_task_output", "legacy-0.4.10"),
|
|
("Kigi:kill_task", "legacy-0.4.10"),
|
|
("Kigi:list_dir", "legacy-0.4.10"),
|
|
],
|
|
},
|
|
// Release-named presets are best-effort compatibility bundles, not full
|
|
// historical snapshots. Later-added or unported tools may resolve to
|
|
// `current` unless explicitly represented. Prefer stable named versions
|
|
// over `current` here — using `current` means the preset's behavior for
|
|
// that tool will silently change over time.
|
|
PresetEntry {
|
|
name: "release-0.1.157",
|
|
lifecycle: BehaviorLifecycle::Active,
|
|
// At 0.1.157, all managed tools were at `current`. No per-tool
|
|
// version other than `legacy-0.4.10` had been carved out yet.
|
|
// `grep` was managed but current-only (no legacy port).
|
|
tool_defaults: &[
|
|
("Kigi:run_terminal_cmd", "current"),
|
|
("Kigi:read_file", "current"),
|
|
("Kigi:search_replace", "current"),
|
|
("Kigi:list_dir", "current"),
|
|
("Kigi:grep", "current"),
|
|
("Kigi:kill_task", "current"),
|
|
("Kigi:get_task_output", "current"),
|
|
],
|
|
},
|
|
];
|
|
|
|
/// Check whether a contract version string is the legacy-0.4.10 version.
|
|
///
|
|
/// Use this for tools with trivial version deltas (e.g. `kill_task`,
|
|
/// `get_task_output` which only differ in not-found wording). For tools
|
|
/// with substantial version divergence, prefer a typed enum like
|
|
/// `BashVersion` or `ListDirVersion`.
|
|
pub fn is_legacy_contract(contract_version: Option<&str>) -> bool {
|
|
contract_version == Some("legacy-0.4.10")
|
|
}
|
|
|
|
pub fn lookup_preset(name: &str) -> Option<&'static PresetEntry> {
|
|
PRESETS.iter().find(|p| p.name == name)
|
|
}
|
|
|
|
pub fn is_version_managed(fq_tool_id: &str) -> bool {
|
|
MANAGED_TOOLS.contains(&fq_tool_id)
|
|
}
|
|
|
|
/// Get the supported versions for a tool from the per-tool registry.
|
|
///
|
|
/// Returns `None` if the tool is not in the registry.
|
|
pub fn tool_supported_versions(fq_tool_id: &str) -> Option<&'static [VersionLifecycle]> {
|
|
TOOL_VERSION_REGISTRY
|
|
.iter()
|
|
.find(|e| e.fq_tool_id == fq_tool_id)
|
|
.map(|e| e.versions)
|
|
}
|
|
|
|
/// Get the lifecycle for a specific tool+version pair.
|
|
///
|
|
/// Returns `None` if the tool is not in the registry or does not support
|
|
/// the requested version.
|
|
pub fn tool_version_lifecycle(fq_tool_id: &str, version: &str) -> Option<BehaviorLifecycle> {
|
|
tool_supported_versions(fq_tool_id)?
|
|
.iter()
|
|
.find(|v| v.version == version)
|
|
.map(|v| v.lifecycle)
|
|
}
|
|
|
|
/// Get the suggested replacement for a specific tool+version pair.
|
|
///
|
|
/// Returns `None` if no replacement is configured (e.g. version is Active).
|
|
pub fn tool_version_replacement(fq_tool_id: &str, version: &str) -> Option<&'static str> {
|
|
tool_supported_versions(fq_tool_id)?
|
|
.iter()
|
|
.find(|v| v.version == version)?
|
|
.replacement
|
|
}
|
|
|
|
/// A deprecation warning produced during version resolution.
|
|
#[derive(Debug, Clone)]
|
|
pub struct VersionWarning {
|
|
/// Fully-qualified tool ID, or empty for bundle-level warnings.
|
|
pub fq_tool_id: String,
|
|
/// The deprecated version.
|
|
pub deprecated_version: String,
|
|
/// Suggested replacement.
|
|
pub replacement: String,
|
|
/// Human-readable message.
|
|
pub message: String,
|
|
}
|
|
|
|
/// Result of resolving a version for a single tool, including any warnings.
|
|
#[derive(Debug)]
|
|
pub struct VersionResolution {
|
|
/// The resolved contract version, or None for unmanaged tools.
|
|
pub contract_version: Option<String>,
|
|
/// Any deprecation warnings generated during resolution.
|
|
pub warnings: Vec<VersionWarning>,
|
|
}
|
|
|
|
/// Resolve the concrete contract version for a tool.
|
|
///
|
|
/// ## Resolution order
|
|
///
|
|
/// 1. `per_tool_override` — if `Some`, use it (validated against known versions).
|
|
/// 2. Preset `tool_defaults` entry for this `fq_tool_id`.
|
|
/// 3. `"current"` (fallback for managed tools not yet in preset defaults).
|
|
///
|
|
/// ## Returns
|
|
///
|
|
/// - `Ok(Some(version))` — for version-managed tools.
|
|
/// - `Ok(None)` — for tools NOT in `MANAGED_TOOLS` (unmanaged).
|
|
/// - `Err(msg)` — for:
|
|
/// - Unknown preset name
|
|
/// - Unknown `per_tool_override` value
|
|
/// - `per_tool_override` supplied for a tool not in `MANAGED_TOOLS`
|
|
///
|
|
/// Resolve version — convenience wrapper that discards warnings.
|
|
/// Use `resolve_version_with_warnings()` when you need deprecation warnings.
|
|
pub fn resolve_version(
|
|
preset_name: &str,
|
|
fq_tool_id: &str,
|
|
per_tool_override: Option<&str>,
|
|
) -> Result<Option<String>, String> {
|
|
resolve_version_with_warnings(preset_name, fq_tool_id, per_tool_override)
|
|
.map(|r| r.contract_version)
|
|
}
|
|
|
|
/// Resolve the concrete contract version for a tool, with deprecation warnings.
|
|
pub fn resolve_version_with_warnings(
|
|
preset_name: &str,
|
|
fq_tool_id: &str,
|
|
per_tool_override: Option<&str>,
|
|
) -> Result<VersionResolution, String> {
|
|
let preset = lookup_preset(preset_name)
|
|
.ok_or_else(|| format!("unknown behavior_preset: \"{preset_name}\""))?;
|
|
|
|
let mut warnings = Vec::new();
|
|
|
|
match preset.lifecycle {
|
|
BehaviorLifecycle::RemovalCandidate => {
|
|
return Err(format!(
|
|
"behavior_preset \"{}\" is scheduled for removal and cannot be used",
|
|
preset_name
|
|
));
|
|
}
|
|
BehaviorLifecycle::Deprecated => {
|
|
tracing::warn!(
|
|
"behavior_preset \"{}\" is deprecated and will be removed in a future release",
|
|
preset_name
|
|
);
|
|
warnings.push(VersionWarning {
|
|
// bundle-level warning
|
|
fq_tool_id: String::new(),
|
|
deprecated_version: preset_name.to_string(),
|
|
replacement: "current".to_string(),
|
|
message: format!(
|
|
"behavior_preset \"{}\" is deprecated and will be removed in a future release",
|
|
preset_name
|
|
),
|
|
});
|
|
}
|
|
BehaviorLifecycle::Active => {}
|
|
}
|
|
|
|
if per_tool_override.is_some() && !is_version_managed(fq_tool_id) {
|
|
return Err(format!(
|
|
"behavior_version override not allowed for unmanaged tool \"{fq_tool_id}\""
|
|
));
|
|
}
|
|
|
|
if !is_version_managed(fq_tool_id) {
|
|
return Ok(VersionResolution {
|
|
contract_version: None,
|
|
warnings,
|
|
});
|
|
}
|
|
|
|
if let Some(override_version) = per_tool_override {
|
|
let (version, mut tool_warnings) = validate_and_resolve(fq_tool_id, override_version)?;
|
|
warnings.append(&mut tool_warnings);
|
|
return Ok(VersionResolution {
|
|
contract_version: version,
|
|
warnings,
|
|
});
|
|
}
|
|
|
|
let tool_defaults: HashMap<&str, &str> = preset.tool_defaults.iter().copied().collect();
|
|
if let Some(&version) = tool_defaults.get(fq_tool_id) {
|
|
let (version, mut tool_warnings) = validate_and_resolve(fq_tool_id, version)?;
|
|
warnings.append(&mut tool_warnings);
|
|
return Ok(VersionResolution {
|
|
contract_version: version,
|
|
warnings,
|
|
});
|
|
}
|
|
|
|
Ok(VersionResolution {
|
|
contract_version: Some("current".to_string()),
|
|
warnings,
|
|
})
|
|
}
|
|
|
|
/// Validate a version against the per-tool registry and apply lifecycle rules.
|
|
///
|
|
/// - `Active` → use it.
|
|
/// - `Deprecated` → warn + continue.
|
|
/// - `RemovalCandidate` → reject with replacement suggestion.
|
|
/// - Not found → reject with supported versions list.
|
|
fn validate_and_resolve(
|
|
fq_tool_id: &str,
|
|
version: &str,
|
|
) -> Result<(Option<String>, Vec<VersionWarning>), String> {
|
|
let supported = tool_supported_versions(fq_tool_id)
|
|
.ok_or_else(|| format!("tool \"{fq_tool_id}\" not found in version registry"))?;
|
|
|
|
let entry = supported.iter().find(|v| v.version == version);
|
|
match entry {
|
|
Some(v) => match v.lifecycle {
|
|
BehaviorLifecycle::Active => Ok((Some(version.to_string()), vec![])),
|
|
BehaviorLifecycle::Deprecated => {
|
|
let note = v.deprecation_note.unwrap_or("no details");
|
|
let replacement = v.replacement.unwrap_or("current");
|
|
tracing::warn!(
|
|
tool = fq_tool_id,
|
|
version = version,
|
|
replacement = replacement,
|
|
"behavior version is deprecated: {note}"
|
|
);
|
|
let warning = VersionWarning {
|
|
fq_tool_id: fq_tool_id.to_string(),
|
|
deprecated_version: version.to_string(),
|
|
replacement: replacement.to_string(),
|
|
message: format!(
|
|
"{} version '{}' is deprecated: {}. Use '{}' instead.",
|
|
fq_tool_id, version, note, replacement
|
|
),
|
|
};
|
|
Ok((Some(version.to_string()), vec![warning]))
|
|
}
|
|
BehaviorLifecycle::RemovalCandidate => {
|
|
let replacement = v.replacement.unwrap_or("current");
|
|
Err(format!(
|
|
"behavior_version \"{version}\" for tool \"{fq_tool_id}\" \
|
|
is scheduled for removal. Use \"{replacement}\" instead."
|
|
))
|
|
}
|
|
},
|
|
None => {
|
|
let available: Vec<&str> = supported.iter().map(|v| v.version).collect();
|
|
Err(format!(
|
|
"version \"{version}\" is not supported for tool \"{fq_tool_id}\"; \
|
|
supported versions: [{}]",
|
|
available.join(", ")
|
|
))
|
|
}
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
|
|
#[test]
|
|
fn current_preset_resolves_to_current() {
|
|
let v = resolve_version("current", "Kigi:run_terminal_cmd", None).unwrap();
|
|
assert_eq!(v, Some("current".to_string()));
|
|
}
|
|
|
|
#[test]
|
|
fn legacy_preset_resolves_ported_tool() {
|
|
let v = resolve_version("legacy-0.4.10", "Kigi:run_terminal_cmd", None).unwrap();
|
|
assert_eq!(v, Some("legacy-0.4.10".to_string()));
|
|
}
|
|
|
|
#[test]
|
|
fn legacy_preset_falls_back_to_current_for_unported_tool() {
|
|
let v = resolve_version("legacy-0.4.10", "Kigi:grep", None).unwrap();
|
|
assert_eq!(v, Some("current".to_string()));
|
|
}
|
|
|
|
#[test]
|
|
fn legacy_preset_resolves_all_ported_tools() {
|
|
for fq_id in &[
|
|
"Kigi:run_terminal_cmd",
|
|
"Kigi:read_file",
|
|
"Kigi:search_replace",
|
|
"Kigi:get_task_output",
|
|
"Kigi:kill_task",
|
|
"Kigi:list_dir",
|
|
] {
|
|
let v = resolve_version("legacy-0.4.10", fq_id, None).unwrap();
|
|
assert_eq!(
|
|
v,
|
|
Some("legacy-0.4.10".to_string()),
|
|
"expected legacy-0.4.10 for {fq_id}"
|
|
);
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn per_tool_override_wins() {
|
|
let v = resolve_version("current", "Kigi:run_terminal_cmd", Some("legacy-0.4.10")).unwrap();
|
|
assert_eq!(v, Some("legacy-0.4.10".to_string()));
|
|
}
|
|
|
|
#[test]
|
|
fn unmanaged_tool_returns_none() {
|
|
let v = resolve_version("current", "Kigi:web_search", None).unwrap();
|
|
assert_eq!(v, None);
|
|
}
|
|
|
|
#[test]
|
|
fn override_on_unmanaged_tool_errors() {
|
|
let err = resolve_version("current", "Kigi:web_search", Some("legacy-0.4.10")).unwrap_err();
|
|
assert!(err.contains("unmanaged tool"));
|
|
}
|
|
|
|
#[test]
|
|
fn unknown_preset_errors() {
|
|
let err = resolve_version("nonexistent", "Kigi:run_terminal_cmd", None).unwrap_err();
|
|
assert!(err.contains("unknown behavior_preset"));
|
|
}
|
|
|
|
#[test]
|
|
fn unknown_override_version_errors() {
|
|
let err = resolve_version("current", "Kigi:run_terminal_cmd", Some("v999")).unwrap_err();
|
|
assert!(
|
|
err.contains("is not supported for tool"),
|
|
"expected 'is not supported' error, got: {err}"
|
|
);
|
|
assert!(
|
|
err.contains("supported versions:"),
|
|
"should list supported versions, got: {err}"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn all_managed_tools_resolve() {
|
|
for &fq_id in MANAGED_TOOLS {
|
|
let v = resolve_version("current", fq_id, None).unwrap();
|
|
assert_eq!(v, Some("current".to_string()), "failed for {fq_id}");
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn concise_namespace_not_managed() {
|
|
assert!(!is_version_managed("KigiConcise:run_terminal_cmd"));
|
|
let v = resolve_version("current", "KigiConcise:run_terminal_cmd", None).unwrap();
|
|
assert_eq!(v, None);
|
|
}
|
|
|
|
#[test]
|
|
fn is_version_managed_matches_catalog() {
|
|
assert!(is_version_managed("Kigi:run_terminal_cmd"));
|
|
assert!(is_version_managed("Kigi:read_file"));
|
|
assert!(is_version_managed("Kigi:search_replace"));
|
|
assert!(is_version_managed("Kigi:list_dir"));
|
|
assert!(is_version_managed("Kigi:grep"));
|
|
assert!(is_version_managed("Kigi:kill_task"));
|
|
assert!(!is_version_managed("Kigi:todo_write"));
|
|
}
|
|
|
|
#[test]
|
|
fn active_version_produces_no_warning() {
|
|
let res = resolve_version_with_warnings("current", "Kigi:run_terminal_cmd", None).unwrap();
|
|
assert!(
|
|
res.warnings.is_empty(),
|
|
"active versions should produce no warnings, got: {:?}",
|
|
res.warnings
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn active_bundle_produces_no_bundle_level_warning() {
|
|
let res =
|
|
resolve_version_with_warnings("legacy-0.4.10", "Kigi:run_terminal_cmd", None).unwrap();
|
|
assert!(
|
|
res.warnings.iter().all(|w| !w.fq_tool_id.is_empty()),
|
|
"no bundle-level warning expected for Active bundle, got: {:?}",
|
|
res.warnings
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn deprecated_version_produces_tool_warning() {
|
|
// No registry version is Deprecated, so that branch can't be hit
|
|
// directly. Exercise the Active (no-warning) path and the not-found
|
|
// error path as the closest reachable proxies.
|
|
let (version, warnings) = validate_and_resolve("Kigi:run_terminal_cmd", "current").unwrap();
|
|
assert_eq!(version, Some("current".to_string()));
|
|
assert!(
|
|
warnings.is_empty(),
|
|
"Active version should produce no warning"
|
|
);
|
|
|
|
let err = validate_and_resolve("Kigi:grep", "legacy-0.4.10").unwrap_err();
|
|
assert!(err.contains("is not supported"), "got: {err}");
|
|
}
|
|
|
|
#[test]
|
|
fn removal_candidate_version_is_rejected() {
|
|
// RemovalCandidate versions should be rejected with replacement.
|
|
// Since no current versions are RemovalCandidate, verify the error
|
|
// for unsupported version (which exercises the same not-found path).
|
|
let err = validate_and_resolve("Kigi:grep", "legacy-0.4.10").unwrap_err();
|
|
assert!(err.contains("is not supported for tool"));
|
|
assert!(err.contains("supported versions: [current]"));
|
|
}
|
|
|
|
#[test]
|
|
fn resolve_with_warnings_returns_correct_version() {
|
|
let res =
|
|
resolve_version_with_warnings("legacy-0.4.10", "Kigi:run_terminal_cmd", None).unwrap();
|
|
assert_eq!(res.contract_version, Some("legacy-0.4.10".to_string()));
|
|
}
|
|
|
|
#[test]
|
|
fn resolve_with_warnings_unmanaged_returns_none_no_warnings() {
|
|
let res = resolve_version_with_warnings("current", "Kigi:web_search", None).unwrap();
|
|
assert_eq!(res.contract_version, None);
|
|
assert!(res.warnings.is_empty());
|
|
}
|
|
|
|
#[test]
|
|
fn resolve_with_warnings_unsupported_version_errors_with_list() {
|
|
let err = resolve_version_with_warnings("current", "Kigi:grep", Some("legacy-0.4.10"))
|
|
.unwrap_err();
|
|
assert!(
|
|
err.contains("is not supported for tool"),
|
|
"expected 'not supported' error, got: {err}"
|
|
);
|
|
assert!(
|
|
err.contains("Kigi:grep"),
|
|
"error should mention the tool, got: {err}"
|
|
);
|
|
assert!(
|
|
err.contains("current"),
|
|
"error should list supported versions, got: {err}"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn invariant_1_managed_tools_have_registry_entries() {
|
|
for &fq_id in MANAGED_TOOLS {
|
|
assert!(
|
|
tool_supported_versions(fq_id).is_some(),
|
|
"managed tool {fq_id} missing from TOOL_VERSION_REGISTRY"
|
|
);
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn invariant_2_registry_tools_are_managed() {
|
|
for entry in TOOL_VERSION_REGISTRY {
|
|
assert!(
|
|
MANAGED_TOOLS.contains(&entry.fq_tool_id),
|
|
"registry tool {} not in MANAGED_TOOLS",
|
|
entry.fq_tool_id
|
|
);
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn invariant_3_bundle_defaults_exist_in_registry() {
|
|
for preset in PRESETS {
|
|
for &(fq_id, version) in preset.tool_defaults {
|
|
let versions = tool_supported_versions(fq_id).unwrap_or_else(|| {
|
|
panic!("bundle '{}' references unknown tool {}", preset.name, fq_id)
|
|
});
|
|
assert!(
|
|
versions.iter().any(|v| v.version == version),
|
|
"bundle '{}' references version '{}' for tool '{}' but it's not in the registry",
|
|
preset.name,
|
|
version,
|
|
fq_id
|
|
);
|
|
}
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn invariant_4_no_removal_candidate_in_bundles() {
|
|
for preset in PRESETS {
|
|
for &(fq_id, version) in preset.tool_defaults {
|
|
let lifecycle = tool_version_lifecycle(fq_id, version);
|
|
assert_ne!(
|
|
lifecycle,
|
|
Some(BehaviorLifecycle::RemovalCandidate),
|
|
"bundle '{}' references removal-candidate version '{}' for tool '{}'",
|
|
preset.name,
|
|
version,
|
|
fq_id
|
|
);
|
|
}
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn invariant_5_deprecated_versions_have_replacements() {
|
|
for entry in TOOL_VERSION_REGISTRY {
|
|
for v in entry.versions {
|
|
if v.lifecycle == BehaviorLifecycle::Deprecated {
|
|
assert!(
|
|
v.replacement.is_some(),
|
|
"deprecated version '{}' for tool '{}' must have a replacement",
|
|
v.version,
|
|
entry.fq_tool_id
|
|
);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn invariant_6_replacements_are_supported() {
|
|
for entry in TOOL_VERSION_REGISTRY {
|
|
for v in entry.versions {
|
|
if let Some(replacement) = v.replacement {
|
|
assert!(
|
|
entry.versions.iter().any(|rv| rv.version == replacement),
|
|
"replacement '{}' for '{}@{}' is not a supported version",
|
|
replacement,
|
|
entry.fq_tool_id,
|
|
v.version
|
|
);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn invariant_7_replacements_not_deprecated_or_removal() {
|
|
for entry in TOOL_VERSION_REGISTRY {
|
|
for v in entry.versions {
|
|
if let Some(replacement) = v.replacement
|
|
&& let Some(target) = entry.versions.iter().find(|rv| rv.version == replacement)
|
|
{
|
|
assert_eq!(
|
|
target.lifecycle,
|
|
BehaviorLifecycle::Active,
|
|
"replacement '{}' for '{}@{}' must be Active, not {:?}",
|
|
replacement,
|
|
entry.fq_tool_id,
|
|
v.version,
|
|
target.lifecycle
|
|
);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn invariant_8_unmanaged_tools_not_in_bundles_or_registry() {
|
|
for preset in PRESETS {
|
|
for &(fq_id, _) in preset.tool_defaults {
|
|
assert!(
|
|
is_version_managed(fq_id),
|
|
"bundle '{}' references unmanaged tool '{}'",
|
|
preset.name,
|
|
fq_id
|
|
);
|
|
}
|
|
}
|
|
for entry in TOOL_VERSION_REGISTRY {
|
|
assert!(
|
|
is_version_managed(entry.fq_tool_id),
|
|
"registry contains unmanaged tool '{}'",
|
|
entry.fq_tool_id
|
|
);
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn all_active_presets_resolve_all_managed_tools() {
|
|
for preset in PRESETS {
|
|
if preset.lifecycle != BehaviorLifecycle::Active {
|
|
continue;
|
|
}
|
|
for &fq_id in MANAGED_TOOLS {
|
|
let result = resolve_version(preset.name, fq_id, None);
|
|
assert!(
|
|
result.is_ok(),
|
|
"preset '{}' failed to resolve tool '{}': {:?}",
|
|
preset.name,
|
|
fq_id,
|
|
result.err()
|
|
);
|
|
let version = result.unwrap();
|
|
assert!(
|
|
version.is_some(),
|
|
"preset '{}' resolved tool '{}' to None (should be Some for managed tools)",
|
|
preset.name,
|
|
fq_id
|
|
);
|
|
}
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn release_preset_resolves_all_tools_to_current() {
|
|
// release-0.1.157 should resolve all managed tools to "current"
|
|
// because no post-legacy stable version had been carved out yet.
|
|
for &fq_id in MANAGED_TOOLS {
|
|
let v = resolve_version("release-0.1.157", fq_id, None).unwrap();
|
|
assert_eq!(
|
|
v,
|
|
Some("current".to_string()),
|
|
"release-0.1.157 should resolve {} to current",
|
|
fq_id
|
|
);
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn is_legacy_contract_detects_legacy() {
|
|
assert!(is_legacy_contract(Some("legacy-0.4.10")));
|
|
assert!(!is_legacy_contract(Some("current")));
|
|
assert!(!is_legacy_contract(None));
|
|
assert!(!is_legacy_contract(Some("unknown")));
|
|
}
|
|
|
|
#[test]
|
|
fn current_version_has_empty_metadata() {
|
|
assert_eq!(V_CURRENT.cataloged_in, "");
|
|
assert!(V_CURRENT.source_refs.is_empty());
|
|
assert_eq!(V_CURRENT.summary, "");
|
|
}
|
|
|
|
#[test]
|
|
fn legacy_versions_have_populated_tool_specific_metadata() {
|
|
let legacy_constants = [
|
|
("bash", &V_LEGACY_BASH),
|
|
("read_file", &V_LEGACY_READ_FILE),
|
|
("search_replace", &V_LEGACY_SEARCH_REPLACE),
|
|
("list_dir", &V_LEGACY_LIST_DIR),
|
|
("kill_task", &V_LEGACY_KILL_TASK),
|
|
("task_output", &V_LEGACY_TASK_OUTPUT),
|
|
];
|
|
for (tool, v) in &legacy_constants {
|
|
assert!(
|
|
!v.cataloged_in.is_empty(),
|
|
"{tool}: cataloged_in should not be empty"
|
|
);
|
|
// source_refs intentionally empty (no external PR catalog).
|
|
assert!(
|
|
v.source_refs.is_empty(),
|
|
"{tool}: source_refs should be empty"
|
|
);
|
|
assert!(!v.summary.is_empty(), "{tool}: summary should not be empty");
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn legacy_summaries_are_tool_specific() {
|
|
assert_ne!(
|
|
V_LEGACY_BASH.summary, V_LEGACY_READ_FILE.summary,
|
|
"bash and read_file have different legacy behavior"
|
|
);
|
|
assert_ne!(
|
|
V_LEGACY_READ_FILE.summary, V_LEGACY_LIST_DIR.summary,
|
|
"read_file and list_dir have different legacy behavior"
|
|
);
|
|
assert_ne!(
|
|
V_LEGACY_BASH.summary, V_LEGACY_KILL_TASK.summary,
|
|
"bash and kill_task have different legacy behavior"
|
|
);
|
|
assert_eq!(
|
|
V_LEGACY_KILL_TASK.summary, V_LEGACY_TASK_OUTPUT.summary,
|
|
"kill_task and task_output share the same legacy behavior"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn legacy_source_refs_are_cleared() {
|
|
// Catalog intentionally keeps source_refs empty.
|
|
for v in [
|
|
&V_LEGACY_BASH,
|
|
&V_LEGACY_READ_FILE,
|
|
&V_LEGACY_SEARCH_REPLACE,
|
|
&V_LEGACY_LIST_DIR,
|
|
&V_LEGACY_KILL_TASK,
|
|
&V_LEGACY_TASK_OUTPUT,
|
|
] {
|
|
assert!(v.source_refs.is_empty());
|
|
}
|
|
}
|
|
}
|