From 33341a0e92065f2cebe36cca3dec10a9c751b4c2 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 20 Nov 2026 10:51:54 +0800 Subject: [PATCH] feat(cli): `check --refs` validates Markdown reference targets Blueprint section 4.2: reference edges are static, never execution. - For every loaded document, resolve same-document anchors, relative file links and target anchors (analysing referenced files statically without executing them); unresolved targets produce `ref.unresolved` errors with source spans. - External HTTP(S) links are treated as external references, not errors. - `inspect --refs` continues to print the resolved edge graph as JSON. --- crates/cli/src/commands.rs | 46 +++++++++++++++++++++++++++++++++++--- crates/cli/src/main.rs | 5 ++++- 2 files changed, 47 insertions(+), 4 deletions(-) diff --git a/crates/cli/src/commands.rs b/crates/cli/src/commands.rs index 8e1e58d..8864ed4 100644 --- a/crates/cli/src/commands.rs +++ b/crates/cli/src/commands.rs @@ -12,7 +12,7 @@ use serde_json::json; use sha2::{Digest, Sha256}; use crate::args; -use crate::loader::{self, LoadedProject}; +use crate::loader::{self, FileDiagnostic, LoadedProject}; use crate::output; /// Effective sandbox settings from the command line. @@ -148,11 +148,15 @@ fn load_project(file: Option<&Path>, json: bool) -> Result { } /// `marqdo check`. -pub fn check(file: Option<&Path>, json: bool) -> i32 { - let project = match load_project(file, json) { +pub fn check(file: Option<&Path>, json: bool, refs: bool) -> i32 { + let mut project = match load_project(file, json) { Ok(project) => project, Err(code) => return code, }; + if refs { + let ref_diagnostics = validate_refs(&project); + project.diagnostics.extend(ref_diagnostics); + } let errors = output::error_count(&project.diagnostics); if json { output::print_json(&json!({ @@ -311,6 +315,42 @@ pub fn inspect(file: Option<&Path>, flags: &InspectFlags, json: bool) -> i32 { 0 } +/// Validate Markdown reference edges for every loaded document. +/// +/// Links are static references: checking them never executes anything. Broken +/// same-document anchors, missing files and missing target anchors are +/// `ref.unresolved` errors; external HTTP(S) links are accepted as external. +fn validate_refs(project: &LoadedProject) -> Vec { + let mut diagnostics = Vec::new(); + for file in project.files.values() { + let parent = file.path.parent().unwrap_or_else(|| Path::new(".")); + let mut unresolved: Vec = Vec::new(); + file.analysis.document.root.walk(&mut |node| { + let marqdo_markdown::MdKind::Link { url, .. } = &node.kind else { + return; + }; + let (resolved, _, _) = resolve_link(project, &file.analysis.units, parent, url); + if !resolved { + unresolved.push(node.span); + } + }); + for span in unresolved { + diagnostics.push(FileDiagnostic { + module_id: file.module_id.clone(), + path: file.path.clone(), + source: file.source.clone(), + diagnostic: marqdo_value::Diagnostic::error( + marqdo_value::codes::REF_UNRESOLVED, + Some(span), + "reference target could not be resolved", + ) + .with_hint("fix the link target or add the missing heading/file"), + }); + } + } + diagnostics +} + fn summary_json(project: &LoadedProject) -> serde_json::Value { let entry = project.entry_file(); json!({ diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index e75796d..767b1cd 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -149,6 +149,9 @@ struct CallArgs { struct CheckArgs { /// Document to check (defaults to index.mq.md). file: Option, + /// Also validate Markdown reference/link targets (`check --refs`). + #[arg(long)] + refs: bool, /// Machine readable JSON output. #[arg(long)] json: bool, @@ -259,7 +262,7 @@ fn main() { let cli = Cli::parse(); let code = match cli.command { Command::Init(args) => commands::init(args.dir.as_deref()), - Command::Check(args) => commands::check(args.file.as_deref(), args.json), + Command::Check(args) => commands::check(args.file.as_deref(), args.json, args.refs), Command::Inspect(args) => { let flags = commands::InspectFlags { ast: args.ast,