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 #[serde(skip_serializing_if = "Option::is_none")]
57 pub extraction: Option<String>,
58 /// Canonical rustdoc path when a reexport/root path was resolved via all.html.
59 #[serde(skip_serializing_if = "Option::is_none")]
60 pub resolved_item_path: Option<String>,
61}
62
63/// Single all.html hit.
64#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
65pub struct SearchInCrateHit {
66 /// Symbol or path name from all.html.
67 pub name: String,
68 /// Item kind string (`struct`, `fn`, …).
69 pub kind: String,
70 /// Absolute URL of the item documentation page.
71 pub url: String,
72 /// Match quality score (0 = best). Omitted when query is empty.
73 #[serde(skip_serializing_if = "Option::is_none")]
74 pub score: Option<u8>,
75}
76
77/// search-in-crate result set (`truncated` is true when hits were cut by `--limit`
78/// and/or by `--max-output-bytes` output budget).
79#[derive(Debug, Clone, Serialize, Deserialize)]
80pub struct SearchInCrateData {
81 /// Requested crate name.
82 pub crate_name: String,
83 /// Text filter applied to hits.
84 pub query: String,
85 /// Requested version token.
86 pub version: String,
87 /// Echo of the applied item-type filter when set.
88 #[serde(skip_serializing_if = "Option::is_none")]
89 pub item_type: Option<String>,
90 /// Match mode applied (`exact` | `prefix` | `substring`).
91 pub match_mode: String,
92 /// Total classified hits before the limit.
93 pub total: usize,
94 /// Number of hits actually emitted.
95 pub emitted: usize,
96 /// Emitted hits.
97 pub hits: Vec<SearchInCrateHit>,
98 /// True when the hit list was cut by `--limit` (`total > emitted`).
99 pub truncated: bool,
100 /// Final source URL of the all.html page.
101 pub source_url: String,
102 /// True when the HTTP body was served from the local disk cache.
103 pub cache_hit: bool,
104}
105