1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
// SPDX-License-Identifier: Apache-2.0
//! Context annotation subcommands.
/// Context subcommands.
#[derive(Clone, Debug, clap::Subcommand)]
pub enum ContextCommands {
/// Attach a context annotation to a file, symbol, line range, or state.
Set(ContextSetArgs),
/// Show current context annotations for a file or state target.
Get(ContextGetArgs),
/// List all active context targets.
List(ContextListArgs),
/// Show full revision history for one logical annotation.
History(ContextHistoryArgs),
/// Add a new revision to an existing logical annotation.
Edit(ContextEditArgs),
/// Create a replacement logical annotation and supersede an older one.
Supersede(ContextSupersedeArgs),
/// Remove context annotations.
Rm(ContextRmArgs),
/// Check annotation staleness against current code.
Check(ContextCheckArgs),
/// Suggest low-noise targets that may benefit from context.
Suggest(ContextSuggestArgs),
/// Audit stale, superseded, and duplicate context.
Audit(ContextAuditArgs),
}
#[derive(Clone, Debug, clap::Args)]
pub struct ContextTargetArgs {
/// File path to annotate/query.
#[arg(long, conflicts_with = "state")]
pub path: Option<String>,
/// State/change ID for broader guidance.
#[arg(long, conflicts_with = "path")]
pub state: Option<String>,
}
/// Arguments for `heddle context set`.
#[derive(Clone, Debug, clap::Args)]
pub struct ContextSetArgs {
#[command(flatten)]
pub target: ContextTargetArgs,
/// Annotation scope: "file" (default), "symbol:<name>", or "lines:<start>-<end>".
#[arg(short, long)]
pub scope: Option<String>,
/// Primary annotation kind: constraint, invariant, or rationale.
#[arg(long, default_value = "rationale")]
pub kind: String,
/// Explicit tags for categorization (can be repeated).
#[arg(long)]
pub tag: Vec<String>,
/// Annotation content (inline).
#[arg(short = 'm', long)]
pub message: Option<String>,
/// Read annotation content from a file.
#[arg(long)]
pub file: Option<std::path::PathBuf>,
}
/// Arguments for `heddle context get`.
#[derive(Clone, Debug, clap::Args)]
pub struct ContextGetArgs {
#[command(flatten)]
pub target: ContextTargetArgs,
/// Filter by scope.
#[arg(short, long)]
pub scope: Option<String>,
/// Filter by tag.
#[arg(long)]
pub tag: Option<String>,
/// Read context from an explicit historical ref/state instead of HEAD.
#[arg(long)]
pub r#ref: Option<String>,
}
/// Arguments for `heddle context list`.
#[derive(Clone, Debug, clap::Args)]
pub struct ContextListArgs {
/// Optional path prefix to filter file targets by.
#[arg(long)]
pub prefix: Option<String>,
/// Filter by tag.
#[arg(long)]
pub tag: Option<String>,
/// Read context from an explicit historical ref/state instead of HEAD.
#[arg(long)]
pub r#ref: Option<String>,
/// Include superseded logical annotations in listings.
#[arg(long)]
pub include_superseded: bool,
}
#[derive(Clone, Debug, clap::Args)]
pub struct ContextHistoryArgs {
/// Stable logical annotation ID.
pub annotation_id: String,
/// Read context from an explicit historical ref/state instead of HEAD.
#[arg(long)]
pub r#ref: Option<String>,
}
#[derive(Clone, Debug, clap::Args)]
pub struct ContextEditArgs {
/// Stable logical annotation ID.
pub annotation_id: String,
/// Override the annotation kind for the new revision.
#[arg(long)]
pub kind: Option<String>,
/// Explicit tags for the new revision (can be repeated).
#[arg(long)]
pub tag: Vec<String>,
/// New revision content (inline).
#[arg(short = 'm', long)]
pub message: Option<String>,
/// Read revision content from a file.
#[arg(long)]
pub file: Option<std::path::PathBuf>,
}
#[derive(Clone, Debug, clap::Args)]
pub struct ContextSupersedeArgs {
/// Stable logical annotation ID to supersede.
pub annotation_id: String,
#[command(flatten)]
pub target: ContextTargetArgs,
/// Replacement annotation scope.
#[arg(short, long)]
pub scope: Option<String>,
/// Replacement annotation kind: constraint, invariant, or rationale.
#[arg(long, default_value = "rationale")]
pub kind: String,
/// Explicit tags for the replacement annotation.
#[arg(long)]
pub tag: Vec<String>,
/// Replacement annotation content (inline).
#[arg(short = 'm', long)]
pub message: Option<String>,
/// Read replacement content from a file.
#[arg(long)]
pub file: Option<std::path::PathBuf>,
}
/// Arguments for `heddle context rm`.
#[derive(Clone, Debug, clap::Args)]
pub struct ContextRmArgs {
#[command(flatten)]
pub target: ContextTargetArgs,
/// Remove only annotations matching this scope.
#[arg(short, long)]
pub scope: Option<String>,
/// Remove all annotations for this target.
#[arg(long)]
pub all: bool,
}
/// Arguments for `heddle context check`.
#[derive(Clone, Debug, clap::Args)]
pub struct ContextCheckArgs {
/// File path to check (checks all annotated files if omitted).
#[arg(long)]
pub path: Option<String>,
/// State ID to check broader guidance on.
#[arg(long)]
pub state: Option<String>,
/// Filter by tag.
#[arg(long)]
pub tag: Option<String>,
/// Read context from an explicit historical ref/state instead of HEAD.
#[arg(long)]
pub r#ref: Option<String>,
}
#[derive(Clone, Debug, clap::Args)]
pub struct ContextSuggestArgs {
/// Read suggestions from an explicit historical ref/state instead of HEAD.
#[arg(long)]
pub r#ref: Option<String>,
/// Maximum suggestions to print.
#[arg(short = 'n', long, default_value = "10")]
pub limit: usize,
}
#[derive(Clone, Debug, clap::Args)]
pub struct ContextAuditArgs {
/// Read context from an explicit historical ref/state instead of HEAD.
#[arg(long)]
pub r#ref: Option<String>,
}