Skip to main content

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}