Skip to main content

ask/skills/
spec_key.rs

1//! Filesystem-safe encoding of a resolved library spec, used as the top-level
2//! directory name under `.ask/skills/<spec-key>/`. Rust port of
3//! `skills/spec-key.ts`.
4//!
5//! Only `/` and `:` — the structural separators that collide with path syntax
6//! — are rewritten to `__`. `@` is kept as-is so scoped npm packages stay
7//! human-readable.
8//!
9//! ```text
10//! { npm, next, 14.2.3 }        → npm__next__14.2.3
11//! { npm, @vercel/ai, 5.0.0 }   → npm__@vercel__ai__5.0.0
12//! { github, vercel/ai, v5.0.0} → github__vercel__ai__v5.0.0
13//! ```
14
15/// A decoded spec-key: ecosystem prefix, package name (or `owner/repo`), and
16/// resolved version / git ref.
17#[derive(Debug, Clone, PartialEq, Eq)]
18pub struct SpecKeyInput {
19    pub ecosystem: String,
20    pub name: String,
21    pub version: String,
22}
23
24/// Rewrite the two structural separators (`/` and `:`) to `__`. Errors on an
25/// empty part (parity with `encodePart`'s throw).
26fn encode_part(value: &str) -> anyhow::Result<String> {
27    if value.is_empty() {
28        anyhow::bail!("spec-key part must be non-empty");
29    }
30    Ok(value.replace(['/', ':'], "__"))
31}
32
33/// Encode a [`SpecKeyInput`] into `ecosystem__name__version` with separators
34/// rewritten. Parity with `encodeSpecKey`.
35pub fn encode_spec_key(input: &SpecKeyInput) -> anyhow::Result<String> {
36    Ok([
37        encode_part(&input.ecosystem)?,
38        encode_part(&input.name)?,
39        encode_part(&input.version)?,
40    ]
41    .join("__"))
42}
43
44/// Reverse of [`encode_spec_key`]. Splits on `__`; the canonical layout is
45/// `[ecosystem, …name parts, version]` (≥3 segments). Name parts re-join with
46/// `/`. Parity with `decodeSpecKey`.
47pub fn decode_spec_key(key: &str) -> anyhow::Result<SpecKeyInput> {
48    let segments: Vec<&str> = key.split("__").collect();
49    if segments.len() < 3 {
50        anyhow::bail!("malformed spec-key (needs at least 3 segments): {key}");
51    }
52    let ecosystem = segments[0];
53    let version = *segments.last().unwrap();
54    let name = segments[1..segments.len() - 1].join("/");
55    if ecosystem.is_empty() || name.is_empty() || version.is_empty() {
56        anyhow::bail!("malformed spec-key (empty segment): {key}");
57    }
58    Ok(SpecKeyInput {
59        ecosystem: ecosystem.to_string(),
60        name,
61        version: version.to_string(),
62    })
63}
64
65#[cfg(test)]
66mod tests {
67    use super::*;
68
69    fn k(e: &str, n: &str, v: &str) -> SpecKeyInput {
70        SpecKeyInput {
71            ecosystem: e.to_string(),
72            name: n.to_string(),
73            version: v.to_string(),
74        }
75    }
76
77    #[test]
78    fn encode_examples() {
79        assert_eq!(
80            encode_spec_key(&k("npm", "next", "14.2.3")).unwrap(),
81            "npm__next__14.2.3"
82        );
83        assert_eq!(
84            encode_spec_key(&k("npm", "@vercel/ai", "5.0.0")).unwrap(),
85            "npm__@vercel__ai__5.0.0"
86        );
87        assert_eq!(
88            encode_spec_key(&k("github", "vercel/ai", "v5.0.0")).unwrap(),
89            "github__vercel__ai__v5.0.0"
90        );
91    }
92
93    #[test]
94    fn encode_rejects_empty_part() {
95        assert!(encode_spec_key(&k("", "n", "v")).is_err());
96    }
97
98    #[test]
99    fn decode_roundtrips_scoped_and_github() {
100        assert_eq!(
101            decode_spec_key("npm__next__14.2.3").unwrap(),
102            k("npm", "next", "14.2.3")
103        );
104        // Scoped npm: name parts re-join with `/`.
105        assert_eq!(
106            decode_spec_key("github__vercel__ai__v5.0.0").unwrap(),
107            k("github", "vercel/ai", "v5.0.0")
108        );
109    }
110
111    #[test]
112    fn decode_rejects_short_key() {
113        assert!(decode_spec_key("npm__next").is_err());
114    }
115}