kizz_core/warning.rs
1// Copyright (c) 2026 Sakura Industries LLC.
2//
3// SPDX-License-Identifier: AGPL-3.0-only
4
5//! Warnings found while discovering `kizz.md` files and parsing their task blocks.
6//!
7//! A warning never stops kizz, but it is probably a mistake, so the command line
8//! shows every warning loudly and repeats it in its final summary.
9
10use std::{
11 fmt,
12 path::{Path, PathBuf},
13};
14
15/// A problem found during discovery or parsing that does not stop kizz.
16///
17/// Every path is relative to the directory discovery started in.
18#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
19pub enum Warning {
20 /// A symbolic link that would make the walk recurse into one of its own parent
21 /// directories, so discovery skipped it.
22 RecursiveLink {
23 /// The symbolic link that was skipped.
24 link: PathBuf,
25 /// The parent directory the link leads back to.
26 ancestor: PathBuf,
27 },
28 /// A directory or file that discovery could not read, so any `kizz.md` in or
29 /// behind it was not found.
30 Unreadable {
31 /// The path that could not be read.
32 path: PathBuf,
33 /// Why it could not be read.
34 reason: String,
35 },
36 /// A `starlark` block with neither targets nor a name, which is not a task.
37 UntaggedBlock {
38 /// The `kizz.md` that holds the block.
39 file: PathBuf,
40 /// The line of the block's opening fence, counting from 1.
41 line: usize,
42 /// The nearest heading above the block, if there is one.
43 heading: Option<String>,
44 },
45}
46
47impl fmt::Display for Warning {
48 fn fmt(
49 &self,
50 f: &mut fmt::Formatter<'_>,
51 ) -> fmt::Result {
52 match self {
53 Self::RecursiveLink { link, ancestor } => {
54 write!(
55 f,
56 "skipped the symbolic link {}: it leads back to {}, one of its own parent \
57 directories, so following it would recurse",
58 shown(link),
59 shown(ancestor)
60 )
61 },
62 Self::Unreadable { path, reason } => {
63 write!(
64 f,
65 "could not read {}: {reason}; any kizz.md in or behind it was not found",
66 shown(path)
67 )
68 },
69 Self::UntaggedBlock {
70 file,
71 line,
72 heading,
73 } => {
74 write!(
75 f,
76 "{}: this starlark block has neither targets nor a name, so it is not a task",
77 location(file, *line, heading.as_deref())
78 )
79 },
80 }
81 }
82}
83
84/// A path relative to the discovery root as output shows it, with `.` for the root
85/// itself.
86#[must_use]
87pub fn shown(path: &Path) -> String {
88 if path.as_os_str().is_empty() {
89 ".".to_owned()
90 } else {
91 path.display().to_string()
92 }
93}
94
95/// A place in a `kizz.md` as output shows it: `path/kizz.md:LINE (Heading)`, or
96/// `path/kizz.md:LINE` when no heading is above it.
97#[must_use]
98pub fn location(
99 file: &Path,
100 line: usize,
101 heading: Option<&str>,
102) -> String {
103 match heading {
104 Some(heading) => format!("{}:{line} ({heading})", shown(file)),
105 None => format!("{}:{line}", shown(file)),
106 }
107}