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}