use camino::{Utf8Path, Utf8PathBuf};
use serde::Serialize;
use crate::domain::markdownlint::{CLI2_NAMES, LIBRARY_NAMES, RELATIVE_LINKS_PACKAGE};
use crate::domain::profile::ProfileId;
use crate::domain::rule_id::RuleId;
use crate::error::AppError;
pub const SCHEMA: &str = "sdd.lint/1";
pub const PROVE_SCHEMA: &str = "sdd.lint-prove/1";
const LINKS: RuleId = RuleId::RootLintConfigurationLoadsRelativeLinks;
const COMPOSES: RuleId = RuleId::LintConfigurationComposes;
const DECLARES: RuleId = RuleId::ProjectDeclaresWhatItsGatesJudge;
const LINK_RULE: &str = "relative-links";
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum Edit {
FoldIntoRoot,
ReplaceLink,
LoadRelativeLinks,
EnableRelativeLinks,
AddCompanionCli2,
AddIgnore,
Unknown,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct Finding {
pub path: String,
pub rule: &'static str,
pub edit: Edit,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum ProfileSource {
Recorded,
Flag,
Default,
}
#[derive(Debug, Clone, Serialize)]
pub struct Report {
pub schema: &'static str,
pub target: Utf8PathBuf,
pub profile: ProfileId,
pub profile_source: ProfileSource,
pub findings: Vec<Finding>,
}
fn finding(path: impl Into<String>, rule: RuleId, edit: Edit) -> Finding {
Finding {
path: path.into(),
rule: rule.as_str(),
edit,
}
}
fn profile(
target: &Utf8Path,
flag: Option<ProfileId>,
) -> Result<(ProfileId, ProfileSource), AppError> {
let recorded =
crate::services::installer::recorded_field(target, "profile").and_then(|value| {
ProfileId::every().find(|profile| Some(profile.as_str()) == value.as_str())
});
match (recorded, flag) {
(Some(recorded), Some(asked)) if recorded != asked => Err(AppError::Refused(format!(
"{target} records the {recorded} profile and this report asks for {asked}"
))),
(Some(recorded), _) => Ok((recorded, ProfileSource::Recorded)),
(None, Some(asked)) => Ok((asked, ProfileSource::Flag)),
(None, None) => Ok((ProfileId::Codebase, ProfileSource::Default)),
}
}
fn jsonc(text: &str) -> Option<serde_json::Value> {
let mut out = String::with_capacity(text.len());
let mut chars = text.chars().peekable();
let mut in_string = false;
while let Some(c) = chars.next() {
if in_string {
out.push(c);
if c == '\\' {
if let Some(next) = chars.next() {
out.push(next);
}
} else if c == '"' {
in_string = false;
}
continue;
}
match (c, chars.peek()) {
('"', _) => {
in_string = true;
out.push(c);
}
('/', Some('/')) => {
for skipped in chars.by_ref() {
if skipped == '\n' {
out.push('\n');
break;
}
}
}
('/', Some('*')) => {
chars.next();
let mut last = ' ';
for skipped in chars.by_ref() {
if last == '*' && skipped == '/' {
break;
}
last = skipped;
}
}
_ => out.push(c),
}
}
let trailing = regex::Regex::new(r",(\s*[}\]])").ok()?;
serde_json::from_str(&trailing.replace_all(&out, "$1")).ok()
}
fn read_configuration(path: &Utf8Path) -> Option<serde_json::Value> {
let text = std::fs::read_to_string(path).ok()?;
match path.extension() {
Some("jsonc" | "json") => jsonc(&text),
Some("yaml" | "yml") => yaml_serde::from_str(&text).ok(),
_ => None,
}
}
fn enables(rules: Option<&serde_json::Value>) -> bool {
match rules.and_then(|rules| rules.get(LINK_RULE)) {
Some(serde_json::Value::Bool(on)) => *on,
Some(serde_json::Value::Object(_)) => true,
_ => false,
}
}
fn root_findings(target: &Utf8Path, landed: bool, findings: &mut Vec<Finding>) {
let present = |name: &str| std::fs::symlink_metadata(target.join(name)).is_ok();
let cli2: Vec<&str> = CLI2_NAMES
.into_iter()
.filter(|name| present(name))
.collect();
let library: Vec<&str> = LIBRARY_NAMES
.into_iter()
.filter(|name| present(name))
.collect();
if cli2.is_empty() && library.is_empty() {
if landed {
findings.push(finding(CLI2_NAMES[0], LINKS, Edit::LoadRelativeLinks));
}
return;
}
let Some(effective) = cli2.first() else {
findings.push(finding(CLI2_NAMES[0], LINKS, Edit::AddCompanionCli2));
return library_findings(target, &library, None, findings);
};
let Some(value) = read_configuration(&target.join(effective)) else {
findings.push(finding(*effective, LINKS, Edit::Unknown));
return library_findings(target, &library, None, findings);
};
let loaded = value
.get("customRules")
.and_then(serde_json::Value::as_array)
.is_some_and(|rules| {
rules.iter().any(|rule| {
rule.as_str()
.is_some_and(|rule| rule.contains(RELATIVE_LINKS_PACKAGE))
})
});
if !loaded {
findings.push(finding(*effective, LINKS, Edit::LoadRelativeLinks));
}
library_findings(target, &library, Some((effective, &value)), findings);
}
fn library_findings(
target: &Utf8Path,
library: &[&str],
cli2: Option<(&str, &serde_json::Value)>,
findings: &mut Vec<Finding>,
) {
if let Some(name) = library.first() {
match read_configuration(&target.join(name)) {
Some(rules) if enables(Some(&rules)) => {}
Some(_) => findings.push(finding(*name, LINKS, Edit::EnableRelativeLinks)),
None => findings.push(finding(*name, LINKS, Edit::Unknown)),
}
} else if let Some((name, value)) = cli2
&& !enables(value.get("config"))
{
findings.push(finding(name, LINKS, Edit::EnableRelativeLinks));
}
}
fn root_ignores(target: &Utf8Path) -> Vec<String> {
CLI2_NAMES
.iter()
.find(|name| std::fs::symlink_metadata(target.join(name)).is_ok())
.and_then(|name| read_configuration(&target.join(name)))
.and_then(|value| {
value
.get("ignores")
.and_then(serde_json::Value::as_array)
.cloned()
})
.into_iter()
.flatten()
.filter_map(|entry| entry.as_str().map(String::from))
.collect()
}
fn reserved_findings(target: &Utf8Path, findings: &mut Vec<Finding>) {
use crate::domain::path_filter::{Layer, PathFilter, Pattern};
let Ok(declaration) = crate::domain::instance_config::InstanceConfig::read(target) else {
return;
};
if declaration.reserved.is_empty() {
return;
}
let markdown: Vec<Utf8PathBuf> = walkdir::WalkDir::new(target)
.into_iter()
.filter_entry(|entry| {
let name = entry.file_name().to_string_lossy();
!(entry.depth() > 0
&& entry.file_type().is_dir()
&& crate::gates::PRUNED_DIRS.contains(&name.as_ref()))
})
.filter_map(Result::ok)
.filter(|entry| entry.file_type().is_file())
.filter_map(|entry| {
let path = Utf8Path::from_path(entry.path())?;
let relative = path.strip_prefix(target).ok()?;
(relative.extension() == Some("md")).then(|| relative.to_owned())
})
.collect();
let ignores = root_ignores(target);
for glob in &declaration.reserved {
let Ok(filter) = PathFilter::build(
Vec::new(),
vec![Pattern::new(glob.clone(), Layer::Reserved)],
) else {
continue;
};
let holds_markdown = markdown.iter().any(|path| !filter.judges(path));
if holds_markdown && !ignores.iter().any(|ignored| ignored == glob) {
findings.push(finding(glob.clone(), DECLARES, Edit::AddIgnore));
}
}
}
pub fn report(target: &Utf8Path, flag: Option<ProfileId>) -> Result<Report, AppError> {
let (profile, profile_source) = profile(target, flag)?;
let docs_root = crate::candidate::docs_root_of(profile)?;
let landed = profile_source == ProfileSource::Recorded;
let mut findings = Vec::new();
for path in crate::services::verifier::linked_lint_scan_roots(target, docs_root) {
findings.push(finding(path.to_string(), COMPOSES, Edit::ReplaceLink));
}
for path in
crate::services::verifier::lint_configurations_that_break_composition(target, docs_root)
{
findings.push(finding(path.to_string(), COMPOSES, Edit::FoldIntoRoot));
}
root_findings(target, landed, &mut findings);
if landed {
reserved_findings(target, &mut findings);
}
Ok(Report {
schema: SCHEMA,
target: target.to_owned(),
profile,
profile_source,
findings,
})
}
#[derive(Debug, Clone, Serialize)]
pub struct Run {
pub exit: Option<i32>,
pub cites_rule: bool,
}
#[derive(Debug, Clone, Serialize)]
pub struct Proof {
pub schema: &'static str,
pub command: Vec<String>,
pub broken: Run,
pub valid: Run,
pub ok: bool,
pub rule: &'static str,
}
fn command() -> Vec<String> {
crate::domain::paths::variable(crate::domain::paths::LINT_PROVE_RUNNER_VAR).map_or_else(
|| {
["pre-commit", "run", "markdownlint-cli2", "--files"]
.map(String::from)
.to_vec()
},
|runner| runner.split_whitespace().map(String::from).collect(),
)
}
fn run(target: &Utf8Path, command: &[String], file: &str) -> Result<Run, AppError> {
let (program, args) = command
.split_first()
.ok_or_else(|| AppError::Usage("the lint proof runner names no program".to_string()))?;
let output = std::process::Command::new(program)
.args(args)
.arg(file)
.current_dir(target)
.stdin(std::process::Stdio::null())
.output()
.map_err(|source| {
AppError::Unavailable(format!(
"{program} could not run, so the proof cannot hold the rule: {source}"
))
})?;
let said = format!(
"{}{}",
String::from_utf8_lossy(&output.stdout),
String::from_utf8_lossy(&output.stderr)
);
Ok(Run {
exit: output.status.code(),
cites_rule: said.contains(LINK_RULE),
})
}
pub fn prove(target: &Utf8Path) -> Result<Proof, AppError> {
let name = format!("sdd-lint-proof-{}.md", std::process::id());
let path = target.join(&name);
if std::fs::symlink_metadata(&path).is_ok() {
return Err(AppError::Refused(format!(
"{path} already exists, and the proof writes only a file of its own"
)));
}
let command = command();
let broken = format!("# Proof\n\nA [broken link](./{name}.missing.md).\n");
let valid = format!("# Proof\n\nA [valid link](./{name}).\n");
let result = (|| {
crate::adapters::fs::write_file(&path, broken.as_bytes())?;
let broken = run(target, &command, &name)?;
crate::adapters::fs::write_file(&path, valid.as_bytes())?;
let valid = run(target, &command, &name)?;
Ok::<_, AppError>((broken, valid))
})();
let removed = std::fs::remove_file(&path);
let (broken, valid) = result?;
removed?;
let ok = broken.exit != Some(0) && broken.cites_rule && valid.exit == Some(0);
Ok(Proof {
schema: PROVE_SCHEMA,
command,
broken,
valid,
ok,
rule: LINKS.as_str(),
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn jsonc_reads_comments_and_trailing_commas() {
let value = jsonc(
"// head\n{\n \"customRules\": [\"a//b\", /* x */ \"c\",],\n \"config\": {\"relative-links\": true,},\n}\n",
)
.expect("the JSONC parses");
assert_eq!(value["customRules"][0], "a//b");
assert!(enables(value.get("config")));
}
#[test]
fn the_rule_is_enabled_by_true_or_by_options() {
assert!(enables(Some(
&serde_json::json!({"relative-links": {"root_path": "."}})
)));
assert!(!enables(Some(
&serde_json::json!({"relative-links": false})
)));
assert!(!enables(Some(&serde_json::json!({}))));
assert!(!enables(None));
}
}