1use camino::{Utf8Path, Utf8PathBuf};
18use serde::Serialize;
19
20use crate::domain::markdownlint::{CLI2_NAMES, LIBRARY_NAMES, RELATIVE_LINKS_PACKAGE};
21use crate::domain::profile::ProfileId;
22use crate::domain::rule_id::RuleId;
23use crate::error::AppError;
24
25pub const SCHEMA: &str = "sdd.lint/1";
27
28pub const PROVE_SCHEMA: &str = "sdd.lint-prove/1";
30
31const LINKS: RuleId = RuleId::RootLintConfigurationLoadsRelativeLinks;
33
34const COMPOSES: RuleId = RuleId::LintConfigurationComposes;
36
37const DECLARES: RuleId = RuleId::ProjectDeclaresWhatItsGatesJudge;
39
40const LINK_RULE: &str = "relative-links";
42
43#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
45#[serde(rename_all = "kebab-case")]
46pub enum Edit {
47 FoldIntoRoot,
49 ReplaceLink,
51 LoadRelativeLinks,
53 EnableRelativeLinks,
55 AddCompanionCli2,
58 AddIgnore,
60 Unknown,
62}
63
64#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
66pub struct Finding {
67 pub path: String,
70 pub rule: &'static str,
72 pub edit: Edit,
74}
75
76#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
78#[serde(rename_all = "kebab-case")]
79pub enum ProfileSource {
80 Recorded,
82 Flag,
84 Default,
86}
87
88#[derive(Debug, Clone, Serialize)]
90pub struct Report {
91 pub schema: &'static str,
93 pub target: Utf8PathBuf,
95 pub profile: ProfileId,
97 pub profile_source: ProfileSource,
99 pub findings: Vec<Finding>,
101}
102
103fn finding(path: impl Into<String>, rule: RuleId, edit: Edit) -> Finding {
104 Finding {
105 path: path.into(),
106 rule: rule.as_str(),
107 edit,
108 }
109}
110
111fn profile(
113 target: &Utf8Path,
114 flag: Option<ProfileId>,
115) -> Result<(ProfileId, ProfileSource), AppError> {
116 let recorded =
117 crate::services::installer::recorded_field(target, "profile").and_then(|value| {
118 ProfileId::every().find(|profile| Some(profile.as_str()) == value.as_str())
119 });
120 match (recorded, flag) {
121 (Some(recorded), Some(asked)) if recorded != asked => Err(AppError::Refused(format!(
122 "{target} records the {recorded} profile and this report asks for {asked}"
123 ))),
124 (Some(recorded), _) => Ok((recorded, ProfileSource::Recorded)),
125 (None, Some(asked)) => Ok((asked, ProfileSource::Flag)),
126 (None, None) => Ok((ProfileId::Codebase, ProfileSource::Default)),
127 }
128}
129
130fn jsonc(text: &str) -> Option<serde_json::Value> {
132 let mut out = String::with_capacity(text.len());
133 let mut chars = text.chars().peekable();
134 let mut in_string = false;
135 while let Some(c) = chars.next() {
136 if in_string {
137 out.push(c);
138 if c == '\\' {
139 if let Some(next) = chars.next() {
140 out.push(next);
141 }
142 } else if c == '"' {
143 in_string = false;
144 }
145 continue;
146 }
147 match (c, chars.peek()) {
148 ('"', _) => {
149 in_string = true;
150 out.push(c);
151 }
152 ('/', Some('/')) => {
153 for skipped in chars.by_ref() {
154 if skipped == '\n' {
155 out.push('\n');
156 break;
157 }
158 }
159 }
160 ('/', Some('*')) => {
161 chars.next();
162 let mut last = ' ';
163 for skipped in chars.by_ref() {
164 if last == '*' && skipped == '/' {
165 break;
166 }
167 last = skipped;
168 }
169 }
170 _ => out.push(c),
171 }
172 }
173 let trailing = regex::Regex::new(r",(\s*[}\]])").ok()?;
174 serde_json::from_str(&trailing.replace_all(&out, "$1")).ok()
175}
176
177fn read_configuration(path: &Utf8Path) -> Option<serde_json::Value> {
179 let text = std::fs::read_to_string(path).ok()?;
180 match path.extension() {
181 Some("jsonc" | "json") => jsonc(&text),
182 Some("yaml" | "yml") => yaml_serde::from_str(&text).ok(),
183 _ => None,
184 }
185}
186
187fn enables(rules: Option<&serde_json::Value>) -> bool {
189 match rules.and_then(|rules| rules.get(LINK_RULE)) {
190 Some(serde_json::Value::Bool(on)) => *on,
191 Some(serde_json::Value::Object(_)) => true,
192 _ => false,
193 }
194}
195
196fn root_findings(target: &Utf8Path, landed: bool, findings: &mut Vec<Finding>) {
200 let present = |name: &str| std::fs::symlink_metadata(target.join(name)).is_ok();
201 let cli2: Vec<&str> = CLI2_NAMES
202 .into_iter()
203 .filter(|name| present(name))
204 .collect();
205 let library: Vec<&str> = LIBRARY_NAMES
206 .into_iter()
207 .filter(|name| present(name))
208 .collect();
209 if cli2.is_empty() && library.is_empty() {
210 if landed {
212 findings.push(finding(CLI2_NAMES[0], LINKS, Edit::LoadRelativeLinks));
213 }
214 return;
215 }
216 let Some(effective) = cli2.first() else {
219 findings.push(finding(CLI2_NAMES[0], LINKS, Edit::AddCompanionCli2));
220 return library_findings(target, &library, None, findings);
221 };
222 let Some(value) = read_configuration(&target.join(effective)) else {
223 findings.push(finding(*effective, LINKS, Edit::Unknown));
224 return library_findings(target, &library, None, findings);
225 };
226 let loaded = value
227 .get("customRules")
228 .and_then(serde_json::Value::as_array)
229 .is_some_and(|rules| {
230 rules.iter().any(|rule| {
231 rule.as_str()
232 .is_some_and(|rule| rule.contains(RELATIVE_LINKS_PACKAGE))
233 })
234 });
235 if !loaded {
236 findings.push(finding(*effective, LINKS, Edit::LoadRelativeLinks));
237 }
238 library_findings(target, &library, Some((effective, &value)), findings);
239}
240
241fn library_findings(
243 target: &Utf8Path,
244 library: &[&str],
245 cli2: Option<(&str, &serde_json::Value)>,
246 findings: &mut Vec<Finding>,
247) {
248 if let Some(name) = library.first() {
251 match read_configuration(&target.join(name)) {
252 Some(rules) if enables(Some(&rules)) => {}
253 Some(_) => findings.push(finding(*name, LINKS, Edit::EnableRelativeLinks)),
254 None => findings.push(finding(*name, LINKS, Edit::Unknown)),
255 }
256 } else if let Some((name, value)) = cli2
257 && !enables(value.get("config"))
258 {
259 findings.push(finding(name, LINKS, Edit::EnableRelativeLinks));
260 }
261}
262
263fn root_ignores(target: &Utf8Path) -> Vec<String> {
266 CLI2_NAMES
267 .iter()
268 .find(|name| std::fs::symlink_metadata(target.join(name)).is_ok())
269 .and_then(|name| read_configuration(&target.join(name)))
270 .and_then(|value| {
271 value
272 .get("ignores")
273 .and_then(serde_json::Value::as_array)
274 .cloned()
275 })
276 .into_iter()
277 .flatten()
278 .filter_map(|entry| entry.as_str().map(String::from))
279 .collect()
280}
281
282fn reserved_findings(target: &Utf8Path, findings: &mut Vec<Finding>) {
284 use crate::domain::path_filter::{Layer, PathFilter, Pattern};
285
286 let Ok(declaration) = crate::domain::instance_config::InstanceConfig::read(target) else {
287 return;
288 };
289 if declaration.reserved.is_empty() {
290 return;
291 }
292 let markdown: Vec<Utf8PathBuf> = walkdir::WalkDir::new(target)
293 .into_iter()
294 .filter_entry(|entry| {
295 let name = entry.file_name().to_string_lossy();
296 !(entry.depth() > 0
297 && entry.file_type().is_dir()
298 && crate::gates::PRUNED_DIRS.contains(&name.as_ref()))
299 })
300 .filter_map(Result::ok)
301 .filter(|entry| entry.file_type().is_file())
302 .filter_map(|entry| {
303 let path = Utf8Path::from_path(entry.path())?;
304 let relative = path.strip_prefix(target).ok()?;
305 (relative.extension() == Some("md")).then(|| relative.to_owned())
306 })
307 .collect();
308 let ignores = root_ignores(target);
309 for glob in &declaration.reserved {
310 let Ok(filter) = PathFilter::build(
311 Vec::new(),
312 vec![Pattern::new(glob.clone(), Layer::Reserved)],
313 ) else {
314 continue;
315 };
316 let holds_markdown = markdown.iter().any(|path| !filter.judges(path));
317 if holds_markdown && !ignores.iter().any(|ignored| ignored == glob) {
318 findings.push(finding(glob.clone(), DECLARES, Edit::AddIgnore));
319 }
320 }
321}
322
323pub fn report(target: &Utf8Path, flag: Option<ProfileId>) -> Result<Report, AppError> {
332 let (profile, profile_source) = profile(target, flag)?;
333 let docs_root = crate::candidate::docs_root_of(profile)?;
334 let landed = profile_source == ProfileSource::Recorded;
335 let mut findings = Vec::new();
336 for path in crate::services::verifier::linked_lint_scan_roots(target, docs_root) {
337 findings.push(finding(path.to_string(), COMPOSES, Edit::ReplaceLink));
338 }
339 for path in
340 crate::services::verifier::lint_configurations_that_break_composition(target, docs_root)
341 {
342 findings.push(finding(path.to_string(), COMPOSES, Edit::FoldIntoRoot));
343 }
344 root_findings(target, landed, &mut findings);
345 if landed {
346 reserved_findings(target, &mut findings);
347 }
348 Ok(Report {
349 schema: SCHEMA,
350 target: target.to_owned(),
351 profile,
352 profile_source,
353 findings,
354 })
355}
356
357#[derive(Debug, Clone, Serialize)]
359pub struct Run {
360 pub exit: Option<i32>,
362 pub cites_rule: bool,
364}
365
366#[derive(Debug, Clone, Serialize)]
368pub struct Proof {
369 pub schema: &'static str,
371 pub command: Vec<String>,
373 pub broken: Run,
375 pub valid: Run,
377 pub ok: bool,
380 pub rule: &'static str,
382}
383
384fn command() -> Vec<String> {
387 crate::domain::paths::variable(crate::domain::paths::LINT_PROVE_RUNNER_VAR).map_or_else(
388 || {
389 ["prek", "run", "markdownlint-cli2", "--files"]
390 .map(String::from)
391 .to_vec()
392 },
393 |runner| runner.split_whitespace().map(String::from).collect(),
394 )
395}
396
397fn run(target: &Utf8Path, command: &[String], file: &str) -> Result<Run, AppError> {
399 let (program, args) = command
400 .split_first()
401 .ok_or_else(|| AppError::Usage("the lint proof runner names no program".to_string()))?;
402 let output = std::process::Command::new(program)
403 .args(args)
404 .arg(file)
405 .current_dir(target)
406 .stdin(std::process::Stdio::null())
407 .output()
408 .map_err(|source| {
409 AppError::Unavailable(format!(
410 "{program} could not run, so the proof cannot hold the rule: {source}"
411 ))
412 })?;
413 let said = format!(
414 "{}{}",
415 String::from_utf8_lossy(&output.stdout),
416 String::from_utf8_lossy(&output.stderr)
417 );
418 Ok(Run {
419 exit: output.status.code(),
420 cites_rule: said.contains(LINK_RULE),
421 })
422}
423
424pub fn prove(target: &Utf8Path) -> Result<Proof, AppError> {
433 let name = format!("sdd-lint-proof-{}.md", std::process::id());
434 let path = target.join(&name);
435 if std::fs::symlink_metadata(&path).is_ok() {
436 return Err(AppError::Refused(format!(
437 "{path} already exists, and the proof writes only a file of its own"
438 )));
439 }
440 let command = command();
441 let broken = format!("# Proof\n\nA [broken link](./{name}.missing.md).\n");
442 let valid = format!("# Proof\n\nA [valid link](./{name}).\n");
443 let result = (|| {
444 crate::adapters::fs::write_file(&path, broken.as_bytes())?;
445 let broken = run(target, &command, &name)?;
446 crate::adapters::fs::write_file(&path, valid.as_bytes())?;
447 let valid = run(target, &command, &name)?;
448 Ok::<_, AppError>((broken, valid))
449 })();
450 let removed = std::fs::remove_file(&path);
451 let (broken, valid) = result?;
452 removed?;
453 let ok = broken.exit != Some(0) && broken.cites_rule && valid.exit == Some(0);
454 Ok(Proof {
455 schema: PROVE_SCHEMA,
456 command,
457 broken,
458 valid,
459 ok,
460 rule: LINKS.as_str(),
461 })
462}
463
464#[cfg(test)]
465mod tests {
466 use super::*;
467
468 #[test]
469 fn jsonc_reads_comments_and_trailing_commas() {
470 let value = jsonc(
471 "// head\n{\n \"customRules\": [\"a//b\", /* x */ \"c\",],\n \"config\": {\"relative-links\": true,},\n}\n",
472 )
473 .expect("the JSONC parses");
474 assert_eq!(value["customRules"][0], "a//b");
475 assert!(enables(value.get("config")));
476 }
477
478 #[test]
479 fn the_rule_is_enabled_by_true_or_by_options() {
480 assert!(enables(Some(
481 &serde_json::json!({"relative-links": {"root_path": "."}})
482 )));
483 assert!(!enables(Some(
484 &serde_json::json!({"relative-links": false})
485 )));
486 assert!(!enables(Some(&serde_json::json!({}))));
487 assert!(!enables(None));
488 }
489}