Skip to main content

docsrs_cli/docs_rs/
types.rs

1//! Wire payloads for docs.rs operations (JSON data contracts).
2
3use serde::{Deserialize, Serialize};
4
5/// Crate overview (rustdoc crate docblock, not git README).
6#[derive(Debug, Clone, Serialize, Deserialize)]
7pub struct ReadmeData {
8    /// Requested crate name.
9    pub crate_name: String,
10    /// Requested version token.
11    pub version: String,
12    /// Version resolved by docs.rs redirects when known.
13    #[serde(skip_serializing_if = "Option::is_none")]
14    pub resolved_version: Option<String>,
15    /// Markdown extracted from the crate overview.
16    pub markdown: String,
17    /// True when the overview body is empty.
18    pub empty: bool,
19    /// True when output was truncated by `max_output_bytes`.
20    pub truncated: bool,
21    /// Final source URL of the HTML page.
22    pub source_url: String,
23    /// True when the HTTP body was served from the local disk cache.
24    pub cache_hit: bool,
25}
26
27/// Typed item documentation payload.
28#[derive(Debug, Clone, Serialize, Deserialize)]
29pub struct GetItemData {
30    /// Requested crate name.
31    pub crate_name: String,
32    /// Normalized item kind string.
33    pub item_type: String,
34    /// Requested item path.
35    pub item_path: String,
36    /// Last path segment (leaf name) for agent convenience.
37    pub item_name: String,
38    /// Requested version token.
39    pub version: String,
40    /// Version resolved by docs.rs redirects when known.
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub resolved_version: Option<String>,
43    /// Markdown extracted from the item page.
44    pub markdown: String,
45    /// True when the item body is empty.
46    pub empty: bool,
47    /// True when output was truncated by `max_output_bytes`.
48    pub truncated: bool,
49    /// Final source URL of the HTML page.
50    pub source_url: String,
51    /// Page title when available.
52    pub title: String,
53    /// True when the HTTP body was served from the local disk cache.
54    pub cache_hit: bool,
55    /// How markdown was scoped for associated methods. Success path is `method` only (1.2.0+ fail-closed; missing anchors are errors).
56    ///
57    /// Read this as "the markdown came from the member anchor", never as "the
58    /// member is a function". It reports `method` for every anchor family,
59    /// including `variant.` and `structfield.`, which is why
60    /// [`Self::anchor_family`] exists.
61    #[serde(skip_serializing_if = "Option::is_none")]
62    pub extraction: Option<String>,
63    /// Rustdoc anchor family the markdown was actually scoped to.
64    ///
65    /// One of `method`, `tymethod`, `associatedtype`, `associatedconstant`,
66    /// `variant` or `structfield`, derived from the anchor id that matched on
67    /// the page rather than from the requested kind.
68    ///
69    /// Added instead of correcting [`Self::extraction`] because agents already
70    /// assert `extraction == "method"` to reject a parent-page false success
71    /// (see `src/docs_rs/html/extract.rs`); changing that value would break them
72    /// silently, while an absent field is a shape every reader already handles.
73    #[serde(skip_serializing_if = "Option::is_none")]
74    pub anchor_family: Option<String>,
75    /// Canonical rustdoc path when a reexport/root path was resolved via all.html.
76    #[serde(skip_serializing_if = "Option::is_none")]
77    pub resolved_item_path: Option<String>,
78}
79
80/// Single all.html hit.
81#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
82pub struct SearchInCrateHit {
83    /// Symbol or path name from all.html.
84    pub name: String,
85    /// Item kind string (`struct`, `fn`, …).
86    pub kind: String,
87    /// Absolute URL of the item documentation page.
88    pub url: String,
89    /// Match quality score (0 = best). Omitted when query is empty.
90    #[serde(skip_serializing_if = "Option::is_none")]
91    pub score: Option<u8>,
92}
93
94/// search-in-crate result set (`truncated` is true when hits were cut by `--limit`
95/// and/or by `--max-output-bytes` output budget).
96#[derive(Debug, Clone, Serialize, Deserialize)]
97pub struct SearchInCrateData {
98    /// Requested crate name.
99    pub crate_name: String,
100    /// Text filter applied to hits.
101    pub query: String,
102    /// Requested version token.
103    pub version: String,
104    /// Echo of the applied item-type filter when set.
105    #[serde(skip_serializing_if = "Option::is_none")]
106    pub item_type: Option<String>,
107    /// Match mode applied (`exact` | `prefix` | `substring`).
108    pub match_mode: String,
109    /// Hits the upstream index classified, before `--limit`.
110    ///
111    /// Describes docs.rs, not this envelope, so agent-native reduction leaves it
112    /// alone: it is the only count that survives a filter intact.
113    pub total: usize,
114    /// Length of the emitted `hits` array.
115    ///
116    /// Listed in [`crate::agent_ops::EMITTED_COUNT_KEYS`], so reduction rewrites it
117    /// whenever it shrinks the array. A field that names the array has to follow it.
118    pub emitted: usize,
119    /// Emitted hits.
120    pub hits: Vec<SearchInCrateHit>,
121    /// True when the hit list was cut by `--limit` (`total > emitted`).
122    pub truncated: bool,
123    /// Final source URL of the all.html page.
124    pub source_url: String,
125    /// True when the HTTP body was served from the local disk cache.
126    pub cache_hit: bool,
127}