Skip to main content

kizz_core/
tasks.rs

1// Copyright (c) 2026 Sakura Industries LLC.
2//
3// SPDX-License-Identifier: AGPL-3.0-only
4
5//! Task blocks in `kizz.md` files.
6//!
7//! A task is a fenced code block, with a backtick or tilde fence, whose info string is
8//! `starlark` followed by targets, task options, or both. After `starlark`, a word with
9//! `=` is a task option and every other word is a target. The options are
10//! `name=<name>`, which names the task with the characters of a target name, uniquely
11//! within its `kizz.md`, and `cache=never`, which makes every command of the task run
12//! as if it were marked `always`. The nearest heading above the block is the task's
13//! heading. A `starlark` block nested in another fenced block is that block's content,
14//! not a task, and a `starlark` block with neither targets nor a name is not a task
15//! either, but gets a warning; its options are still checked.
16
17use std::{
18    fmt,
19    path::{Path, PathBuf},
20};
21
22use kizz_store::TaskId;
23use pulldown_cmark::{CodeBlockKind, Event, Parser, Tag, TagEnd};
24
25use crate::{project::ConfigError, targets::is_valid_target, warning::Warning};
26
27/// The first word of the info string of every task block.
28pub const TASK_LANGUAGE: &str = "starlark";
29
30/// The keys of the task options, in the order output shows them.
31pub const TASK_OPTION_KEYS: &[&str] = &[NAME_KEY, CACHE_KEY];
32
33/// The key of the task option that names a task.
34const NAME_KEY: &str = "name";
35
36/// The key of the task option that chooses how a task's commands are cached.
37const CACHE_KEY: &str = "cache";
38
39/// The one value that the `cache` option accepts.
40const CACHE_NEVER: &str = "never";
41
42/// The rule every task name follows, as error messages state it.
43pub const TASK_NAME_RULE: &str = "task names use only letters, digits, `_`, `.` and `-`";
44
45/// The options of a task block: the words of its info string that hold `=`.
46///
47/// Task options are not part of the task program, so they change no step key.
48#[derive(Debug, Clone, Default, PartialEq, Eq)]
49pub struct TaskOptions {
50    /// The name that `name=<name>` gives the task, if it has one.
51    pub name: Option<String>,
52    /// Whether `cache=never` marks the task, so every command of the task runs as if
53    /// it were marked `always`.
54    pub cache_never: bool,
55}
56
57impl TaskOptions {
58    /// The options in their info-string form, in the order of
59    /// [`TASK_OPTION_KEYS`], such as `name=lint` and `cache=never`.
60    #[must_use]
61    pub fn words(&self) -> Vec<String> {
62        let mut words = Vec::new();
63        if let Some(name) = &self.name {
64            words.push(format!("{NAME_KEY}={name}"));
65        }
66        if self.cache_never {
67            words.push(format!("{CACHE_KEY}={CACHE_NEVER}"));
68        }
69        words
70    }
71}
72
73/// What is wrong with one task option, a configuration error.
74#[derive(Debug, Clone, PartialEq, Eq)]
75pub enum OptionProblem {
76    /// The word starts with `=`, so the option has no key.
77    NoKey,
78    /// The key is not the key of a task option.
79    UnknownKey,
80    /// An earlier word of the same info string already gave this key.
81    RepeatedKey {
82        /// The repeated key.
83        key: String,
84    },
85    /// The option has nothing after its `=`.
86    EmptyValue,
87    /// The `name` option's value is not a valid task name.
88    InvalidName,
89    /// The `cache` option's value is not `never`.
90    InvalidCache,
91    /// An earlier task block of the same `kizz.md` already has this name.
92    DuplicateName {
93        /// The line of that block's opening fence, counting from 1.
94        first_line: usize,
95    },
96}
97
98impl OptionProblem {
99    /// The message of this problem with the option `option`, the word as written.
100    #[must_use]
101    pub fn message(
102        &self,
103        option: &str,
104    ) -> String {
105        match self {
106            Self::NoKey => {
107                format!("task option `{option}` has no key: a task option is a `key=value` word")
108            },
109            Self::UnknownKey => {
110                format!(
111                    "unknown task option `{option}`: the task options are `name=<name>` and \
112                     `cache=never`"
113                )
114            },
115            Self::RepeatedKey { key } => {
116                format!(
117                    "task option `{option}` gives the key `{key}` again, which a block gives once"
118                )
119            },
120            Self::EmptyValue => format!("task option `{option}` has an empty value"),
121            Self::InvalidName => format!("invalid task name in `{option}`: {TASK_NAME_RULE}"),
122            Self::InvalidCache => {
123                format!("invalid value in task option `{option}`: `cache` accepts only `never`")
124            },
125            Self::DuplicateName { first_line } => {
126                format!(
127                    "task option `{option}` gives a name that the task at line {first_line} of \
128                     this file already has, and a name is unique within its kizz.md"
129                )
130            },
131        }
132    }
133}
134
135/// A task: one `starlark` block with targets, a name, or both, in a `kizz.md`.
136#[derive(Debug, Clone, PartialEq, Eq)]
137pub struct Task {
138    /// The task's identity: the absolute path of its `kizz.md` and its position among
139    /// the task blocks of that file.
140    pub id: TaskId,
141    /// The path of the task's `kizz.md`, relative to the directory discovery started
142    /// in.
143    pub relative_file: PathBuf,
144    /// The line of the block's opening fence, counting from 1.
145    pub line: usize,
146    /// The nearest heading above the block, the task's heading, if there is one.
147    pub heading: Option<String>,
148    /// The block's distinct targets, in the order written; empty for a task that
149    /// only its name selects.
150    pub targets: Vec<String>,
151    /// The block's task options.
152    pub options: TaskOptions,
153    /// The block's Starlark source.
154    pub source: String,
155}
156
157impl Task {
158    /// The task as output shows it: `path/kizz.md:LINE (Heading)`.
159    #[must_use]
160    pub fn location(&self) -> String {
161        crate::warning::location(&self.relative_file, self.line, self.heading.as_deref())
162    }
163}
164
165/// What parsing one `kizz.md` found.
166#[derive(Debug, Default)]
167pub struct ParsedFile {
168    /// The tasks, in file order.
169    pub tasks: Vec<Task>,
170    /// The warnings, in file order.
171    pub warnings: Vec<Warning>,
172    /// The configuration errors, in file order.
173    pub errors: Vec<ConfigError>,
174}
175
176/// A `starlark` block whose end has not been reached yet.
177struct OpenBlock {
178    /// The line of the opening fence, counting from 1.
179    line: usize,
180    /// The words of the info string after `starlark`.
181    words: Vec<String>,
182    /// The block's content so far.
183    source: String,
184}
185
186/// Where a block is, as its configuration errors and warnings name it.
187struct BlockPlace<'a> {
188    /// The path of the `kizz.md`, relative to the directory discovery started in.
189    relative_file: &'a Path,
190    /// The line of the block's opening fence, counting from 1.
191    line: usize,
192    /// The nearest heading above the block, if there is one.
193    heading: Option<&'a str>,
194}
195
196impl BlockPlace<'_> {
197    /// The configuration error of the task option `option` at this place.
198    fn option_error(
199        &self,
200        option: &str,
201        problem: OptionProblem,
202    ) -> ConfigError {
203        ConfigError::TaskOption {
204            file: self.relative_file.to_path_buf(),
205            line: self.line,
206            heading: self.heading.map(str::to_owned),
207            option: option.to_owned(),
208            problem,
209        }
210    }
211}
212
213/// Parse the task blocks of one `kizz.md`.
214///
215/// `file` is the absolute path of the `kizz.md`, which identifies its tasks, and
216/// `relative_file` is its path relative to the directory discovery started in, which
217/// messages show.
218#[must_use]
219pub fn parse_tasks(
220    file: &Path,
221    relative_file: &Path,
222    source: &str,
223) -> ParsedFile {
224    let line_starts = line_starts(source);
225    let mut parsed = ParsedFile::default();
226    let mut names: Vec<(String, usize)> = Vec::new();
227    let mut heading: Option<String> = None;
228    let mut open_heading: Option<String> = None;
229    let mut open_block: Option<OpenBlock> = None;
230
231    for (event, range) in Parser::new(source).into_offset_iter() {
232        match event {
233            Event::Start(Tag::Heading { .. }) => open_heading = Some(String::new()),
234            Event::End(TagEnd::Heading(_)) => {
235                if let Some(text) = open_heading.take() {
236                    let text = text.trim();
237                    heading = (!text.is_empty()).then(|| text.to_owned());
238                }
239            },
240            Event::Start(Tag::CodeBlock(CodeBlockKind::Fenced(info))) => {
241                let mut words = info.split_whitespace();
242                if words.next() == Some(TASK_LANGUAGE) {
243                    open_block = Some(OpenBlock {
244                        line: line_of(&line_starts, range.start),
245                        words: words.map(str::to_owned).collect(),
246                        source: String::new(),
247                    });
248                }
249            },
250            Event::Text(text) | Event::Code(text) => {
251                if let Some(block) = open_block.as_mut() {
252                    block.source.push_str(&text);
253                } else if let Some(open) = open_heading.as_mut() {
254                    open.push_str(&text);
255                }
256            },
257            Event::SoftBreak | Event::HardBreak => {
258                if let Some(open) = open_heading.as_mut() {
259                    open.push(' ');
260                }
261            },
262            Event::End(TagEnd::CodeBlock) => {
263                if let Some(block) = open_block.take() {
264                    let place = BlockPlace {
265                        relative_file,
266                        line: block.line,
267                        heading: heading.as_deref(),
268                    };
269                    finish_block(&mut parsed, &mut names, file, &place, block);
270                }
271            },
272            _ => {},
273        }
274    }
275    parsed
276}
277
278/// Read the task option `key=value` into `options`, given the keys that earlier
279/// words of the same info string gave, `seen`, which gains `key`.
280///
281/// # Errors
282///
283/// The [`OptionProblem`] of the option, when it has one; `options` is unchanged.
284fn read_option(
285    key: &str,
286    value: &str,
287    options: &mut TaskOptions,
288    seen: &mut Vec<String>,
289) -> Result<(), OptionProblem> {
290    if key.is_empty() {
291        return Err(OptionProblem::NoKey);
292    }
293    if !TASK_OPTION_KEYS.contains(&key) {
294        return Err(OptionProblem::UnknownKey);
295    }
296    if seen.iter().any(|known| known == key) {
297        return Err(OptionProblem::RepeatedKey {
298            key: key.to_owned(),
299        });
300    }
301    seen.push(key.to_owned());
302    if value.is_empty() {
303        return Err(OptionProblem::EmptyValue);
304    }
305    if key == NAME_KEY {
306        if !is_valid_target(value) {
307            return Err(OptionProblem::InvalidName);
308        }
309        options.name = Some(value.to_owned());
310    } else if value == CACHE_NEVER {
311        options.cache_never = true;
312    } else {
313        return Err(OptionProblem::InvalidCache);
314    }
315    Ok(())
316}
317
318/// Turn a finished `starlark` block into a task, a warning, or configuration errors.
319///
320/// `names` holds the name and fence line of each earlier block of the file that gave
321/// a valid name, and gains this block's.
322fn finish_block(
323    parsed: &mut ParsedFile,
324    names: &mut Vec<(String, usize)>,
325    file: &Path,
326    place: &BlockPlace<'_>,
327    block: OpenBlock,
328) {
329    let mut valid = true;
330    let mut targets: Vec<String> = Vec::new();
331    let mut target_words = 0_usize;
332    let mut options = TaskOptions::default();
333    let mut seen: Vec<String> = Vec::new();
334    let mut name_word: Option<String> = None;
335    for word in block.words {
336        if let Some((key, value)) = word.split_once('=') {
337            match read_option(key, value, &mut options, &mut seen) {
338                Ok(()) if key == NAME_KEY => name_word = Some(word.clone()),
339                Ok(()) => {},
340                Err(problem) => {
341                    valid = false;
342                    parsed.errors.push(place.option_error(&word, problem));
343                },
344            }
345            continue;
346        }
347        target_words = target_words.saturating_add(1);
348        if is_valid_target(&word) {
349            if !targets.contains(&word) {
350                targets.push(word);
351            }
352        } else {
353            valid = false;
354            parsed.errors.push(ConfigError::InvalidTarget {
355                file: place.relative_file.to_path_buf(),
356                line: place.line,
357                heading: place.heading.map(str::to_owned),
358                target: word,
359            });
360        }
361    }
362
363    if target_words == 0 && !seen.iter().any(|key| key == NAME_KEY) {
364        parsed.warnings.push(Warning::UntaggedBlock {
365            file: place.relative_file.to_path_buf(),
366            line: place.line,
367            heading: place.heading.map(str::to_owned),
368        });
369        return;
370    }
371
372    if let (Some(name), Some(word)) = (&options.name, &name_word) {
373        if let Some((_, first_line)) = names.iter().find(|(known, _)| known == name) {
374            valid = false;
375            parsed
376                .errors
377                .push(place.option_error(word, OptionProblem::DuplicateName {
378                    first_line: *first_line,
379                }));
380        } else {
381            names.push((name.clone(), place.line));
382        }
383    }
384    if !valid {
385        return;
386    }
387
388    let Ok(index) = u32::try_from(parsed.tasks.len()) else {
389        parsed.errors.push(ConfigError::TooManyTasks {
390            file: place.relative_file.to_path_buf(),
391        });
392        return;
393    };
394    parsed.tasks.push(Task {
395        id: TaskId {
396            file: file.to_path_buf(),
397            index,
398        },
399        relative_file: place.relative_file.to_path_buf(),
400        line: place.line,
401        heading: place.heading.map(str::to_owned),
402        targets,
403        options,
404        source: block.source,
405    });
406}
407
408impl fmt::Display for TaskOptions {
409    fn fmt(
410        &self,
411        f: &mut fmt::Formatter<'_>,
412    ) -> fmt::Result {
413        f.write_str(&self.words().join(" "))
414    }
415}
416
417/// The byte offsets at which the lines of `source` start.
418fn line_starts(source: &str) -> Vec<usize> {
419    std::iter::once(0)
420        .chain(
421            source
422                .bytes()
423                .enumerate()
424                .filter(|&(_, byte)| byte == b'\n')
425                .map(|(offset, _)| offset.saturating_add(1)),
426        )
427        .collect()
428}
429
430/// The line, counting from 1, that holds the byte at `offset`.
431fn line_of(
432    line_starts: &[usize],
433    offset: usize,
434) -> usize {
435    line_starts.partition_point(|&start| start <= offset)
436}
437
438/// Unit tests for task-block parsing.
439#[cfg(test)]
440#[allow(
441    clippy::disallowed_macros,
442    clippy::disallowed_methods,
443    reason = "test code: the tests assert and lock"
444)]
445mod tests {
446    use std::path::Path;
447
448    use super::{OptionProblem, ParsedFile, TaskOptions, parse_tasks};
449    use crate::{project::ConfigError, warning::Warning};
450
451    /// Parse `source` as `/work/sub/kizz.md`.
452    fn parse(source: &str) -> ParsedFile {
453        parse_tasks(
454            Path::new("/work/sub/kizz.md"),
455            Path::new("sub/kizz.md"),
456            source,
457        )
458    }
459
460    /// The (line, heading, targets) of each task.
461    fn summary(parsed: &ParsedFile) -> Vec<(usize, Option<&str>, Vec<&str>)> {
462        parsed
463            .tasks
464            .iter()
465            .map(|task| {
466                (
467                    task.line,
468                    task.heading.as_deref(),
469                    task.targets.iter().map(String::as_str).collect(),
470                )
471            })
472            .collect()
473    }
474
475    /// The messages of the configuration errors.
476    fn messages(parsed: &ParsedFile) -> Vec<String> {
477        parsed.errors.iter().map(ToString::to_string).collect()
478    }
479
480    /// Backtick and tilde fences are both task blocks, each with the nearest heading
481    /// above it as its heading, and with its fence line, targets, source, and position.
482    #[test]
483    fn backtick_and_tilde_fences_are_tasks() {
484        let parsed = parse(
485            "# Project\n\nIntro.\n\n## Build the library\n\n```starlark ci check\nrun(\"make\")\n```\n\n\
486             ~~~starlark  lint\nrun(\"lint\")\nrun(\"more\")\n~~~\n\n### `fmt` *check*\n\n````starlark fmt\nx = 1\n````\n",
487        );
488        assert!(parsed.errors.is_empty(), "{:?}", parsed.errors);
489        assert!(parsed.warnings.is_empty(), "{:?}", parsed.warnings);
490        assert_eq!(summary(&parsed), [
491            (7, Some("Build the library"), vec!["ci", "check"]),
492            (11, Some("Build the library"), vec!["lint"]),
493            (18, Some("fmt check"), vec!["fmt"]),
494        ]);
495        let sources: Vec<&str> = parsed.tasks.iter().map(|t| t.source.as_str()).collect();
496        assert_eq!(sources, [
497            "run(\"make\")\n",
498            "run(\"lint\")\nrun(\"more\")\n",
499            "x = 1\n"
500        ]);
501        for (index, task) in (0_u32..).zip(&parsed.tasks) {
502            assert_eq!(task.id.file, Path::new("/work/sub/kizz.md"));
503            assert_eq!(task.id.index, index);
504            assert_eq!(task.relative_file, Path::new("sub/kizz.md"));
505            assert_eq!(task.options, TaskOptions::default());
506        }
507        assert_eq!(
508            parsed.tasks[0].location(),
509            "sub/kizz.md:7 (Build the library)"
510        );
511    }
512
513    /// A task with no heading above it has the heading `None`, and its location is the
514    /// file and line alone.
515    #[test]
516    fn a_task_without_a_heading_has_no_heading() {
517        let parsed = parse("```starlark ci\nx = 1\n```\n\n# Later\n");
518        assert_eq!(summary(&parsed), [(1, None, vec!["ci"])]);
519        assert_eq!(parsed.tasks[0].location(), "sub/kizz.md:1");
520    }
521
522    /// A `starlark` block nested in another fenced block is content, not a task, in
523    /// either fence style.
524    #[test]
525    fn nested_fences_are_not_tasks() {
526        let parsed = parse(
527            "# Docs\n\n````markdown\n```starlark ci\nx = 1\n```\n````\n\n\
528             ~~~text\n```starlark ci\n```\n~~~\n\n```text\n~~~starlark ci\n~~~\n```\n\n\
529             ```starlark real\ny = 2\n```\n",
530        );
531        assert!(parsed.warnings.is_empty(), "{:?}", parsed.warnings);
532        assert!(parsed.errors.is_empty(), "{:?}", parsed.errors);
533        assert_eq!(summary(&parsed), [(19, Some("Docs"), vec!["real"])]);
534        assert_eq!(parsed.tasks[0].id.index, 0);
535    }
536
537    /// Blocks in other languages, indented code, and info strings that only start
538    /// with `starlark` are not task blocks, and get no warning.
539    #[test]
540    fn other_blocks_are_not_tasks() {
541        let parsed = parse(
542            "# Other\n\n```python ci\nx = 1\n```\n\n```\nplain\n```\n\n    starlark ci\n\n\
543             ```starlark_ci ci\n```\n\n```Starlark ci\n```\n",
544        );
545        assert!(parsed.tasks.is_empty(), "{:?}", parsed.tasks);
546        assert!(parsed.warnings.is_empty(), "{:?}", parsed.warnings);
547        assert!(parsed.errors.is_empty(), "{:?}", parsed.errors);
548    }
549
550    /// A `starlark` block with neither targets nor a name is not a task and gets a
551    /// warning that names its file, line, and heading; it takes no task position.
552    #[test]
553    fn untagged_blocks_warn_and_are_not_tasks() {
554        let parsed = parse(
555            "# Notes\n\n```starlark\nx = 1\n```\n\n~~~ starlark \n~~~\n\n```starlark ci\n```\n",
556        );
557        assert!(parsed.errors.is_empty(), "{:?}", parsed.errors);
558        assert_eq!(parsed.warnings, [
559            Warning::UntaggedBlock {
560                file: "sub/kizz.md".into(),
561                line: 3,
562                heading: Some("Notes".to_owned()),
563            },
564            Warning::UntaggedBlock {
565                file: "sub/kizz.md".into(),
566                line: 7,
567                heading: Some("Notes".to_owned()),
568            },
569        ]);
570        assert_eq!(
571            parsed.warnings[0].to_string(),
572            "sub/kizz.md:3 (Notes): this starlark block has neither targets nor a name, so it \
573             is not a task"
574        );
575        assert_eq!(summary(&parsed), [(10, Some("Notes"), vec!["ci"])]);
576        assert_eq!(parsed.tasks[0].id.index, 0);
577    }
578
579    /// Invalid target names are configuration errors that name the target, file,
580    /// line, and heading, and their block is not a task.
581    #[test]
582    fn invalid_target_names_are_configuration_errors() {
583        let parsed = parse(
584            "# Release\n\n```starlark ci ship!\n```\n\n## Next\n\n```starlark a/b ok c:d\n```\n\n\
585             ```starlark good\n```\n",
586        );
587        let errors: Vec<String> = parsed.errors.iter().map(ToString::to_string).collect();
588        assert_eq!(errors, [
589            "sub/kizz.md:3 (Release): invalid target name `ship!`: target names use only \
590             letters, digits, `_`, `.` and `-`",
591            "sub/kizz.md:8 (Next): invalid target name `a/b`: target names use only letters, \
592             digits, `_`, `.` and `-`",
593            "sub/kizz.md:8 (Next): invalid target name `c:d`: target names use only letters, \
594             digits, `_`, `.` and `-`",
595        ]);
596        assert!(matches!(
597            &parsed.errors[0],
598            ConfigError::InvalidTarget { target, line: 3, .. } if target == "ship!"
599        ));
600        assert_eq!(summary(&parsed), [(11, Some("Next"), vec!["good"])]);
601    }
602
603    /// Repeated targets on one block are kept once, in the order written.
604    #[test]
605    fn repeated_targets_are_kept_once() {
606        let parsed = parse("```starlark ci check ci\n```\n");
607        assert_eq!(summary(&parsed), [(1, None, vec!["ci", "check"])]);
608    }
609
610    /// Fences inside lists and block quotes are task blocks, with the line of their
611    /// fence, and a setext heading is the heading of the tasks below it.
612    #[test]
613    fn fences_in_containers_and_setext_headings() {
614        let parsed = parse(
615            "Setext title\n============\n\n* item\n\n  ```starlark ci\n  x = 1\n  ```\n\n\
616             > ```starlark check\n> y = 2\n> ```\n",
617        );
618        assert_eq!(summary(&parsed), [
619            (6, Some("Setext title"), vec!["ci"]),
620            (10, Some("Setext title"), vec!["check"]),
621        ]);
622    }
623
624    /// Targets and options mix in any order: a word with `=` is an option, and every
625    /// other word is a target.
626    #[test]
627    fn targets_and_options_in_any_order() {
628        let parsed = parse(
629            "# Lint\n\n```starlark ci name=lint check cache=never\n```\n\n\
630             ```starlark cache=never name=fmt fmt\n```\n\n```starlark name=docs docs\n```\n",
631        );
632        assert!(parsed.errors.is_empty(), "{:?}", parsed.errors);
633        assert!(parsed.warnings.is_empty(), "{:?}", parsed.warnings);
634        assert_eq!(summary(&parsed), [
635            (3, Some("Lint"), vec!["ci", "check"]),
636            (6, Some("Lint"), vec!["fmt"]),
637            (9, Some("Lint"), vec!["docs"]),
638        ]);
639        let options: Vec<&TaskOptions> = parsed.tasks.iter().map(|task| &task.options).collect();
640        assert_eq!(options, [
641            &TaskOptions {
642                name: Some("lint".to_owned()),
643                cache_never: true,
644            },
645            &TaskOptions {
646                name: Some("fmt".to_owned()),
647                cache_never: true,
648            },
649            &TaskOptions {
650                name: Some("docs".to_owned()),
651                cache_never: false,
652            },
653        ]);
654        let words: Vec<String> = parsed
655            .tasks
656            .iter()
657            .map(|task| task.options.to_string())
658            .collect();
659        assert_eq!(words, [
660            "name=lint cache=never",
661            "name=fmt cache=never",
662            "name=docs"
663        ]);
664    }
665
666    /// `name=` takes every valid target name, and `cache=never` alone marks a task
667    /// with targets.
668    #[test]
669    fn valid_names_and_cache_never() {
670        let parsed = parse(
671            "```starlark name=a.b-c_D9\n```\n\n```starlark name=0 ci\n```\n\n\
672             ```starlark ci cache=never\n```\n",
673        );
674        assert!(parsed.errors.is_empty(), "{:?}", parsed.errors);
675        let names: Vec<Option<&str>> = parsed
676            .tasks
677            .iter()
678            .map(|task| task.options.name.as_deref())
679            .collect();
680        assert_eq!(names, [Some("a.b-c_D9"), Some("0"), None]);
681        let never: Vec<bool> = parsed
682            .tasks
683            .iter()
684            .map(|task| task.options.cache_never)
685            .collect();
686        assert_eq!(never, [false, false, true]);
687        assert_eq!(parsed.tasks[2].options.words(), ["cache=never"]);
688    }
689
690    /// An unknown key, a key given twice, an empty or invalid value, an invalid name,
691    /// and a word that starts with `=` are each a configuration error that names the
692    /// file, line, heading, and option, and the block is not a task.
693    #[test]
694    fn option_mistakes_are_configuration_errors() {
695        let parsed = parse(
696            "# Opts\n\n```starlark ci color=red\n```\n\n```starlark ci name=a name=b\n```\n\n\
697             ```starlark ci cache=never cache=never\n```\n\n```starlark ci name=\n```\n\n\
698             ```starlark ci cache=\n```\n\n```starlark ci cache=always\n```\n\n\
699             ```starlark ci name=a/b\n```\n\n```starlark ci =x\n```\n\n```starlark ci name=a=b\n```\n\n\
700             ```starlark good\n```\n",
701        );
702        assert_eq!(messages(&parsed), [
703            "sub/kizz.md:3 (Opts): unknown task option `color=red`: the task options are \
704             `name=<name>` and `cache=never`",
705            "sub/kizz.md:6 (Opts): task option `name=b` gives the key `name` again, which a \
706             block gives once",
707            "sub/kizz.md:9 (Opts): task option `cache=never` gives the key `cache` again, which \
708             a block gives once",
709            "sub/kizz.md:12 (Opts): task option `name=` has an empty value",
710            "sub/kizz.md:15 (Opts): task option `cache=` has an empty value",
711            "sub/kizz.md:18 (Opts): invalid value in task option `cache=always`: `cache` accepts \
712             only `never`",
713            "sub/kizz.md:21 (Opts): invalid task name in `name=a/b`: task names use only \
714             letters, digits, `_`, `.` and `-`",
715            "sub/kizz.md:24 (Opts): task option `=x` has no key: a task option is a `key=value` \
716             word",
717            "sub/kizz.md:27 (Opts): invalid task name in `name=a=b`: task names use only \
718             letters, digits, `_`, `.` and `-`",
719        ]);
720        assert!(matches!(
721            &parsed.errors[1],
722            ConfigError::TaskOption { line: 6, option, problem: OptionProblem::RepeatedKey { key }, .. }
723                if option == "name=b" && key == "name"
724        ));
725        assert!(parsed.warnings.is_empty(), "{:?}", parsed.warnings);
726        assert_eq!(summary(&parsed), [(30, Some("Opts"), vec!["good"])]);
727        assert_eq!(parsed.tasks[0].id.index, 0);
728    }
729
730    /// A name given to two tasks of one file is a configuration error on the later
731    /// one, which names the earlier one's line; the same name in another file is
732    /// another file's business.
733    #[test]
734    fn a_name_given_to_two_tasks_of_one_file_is_an_error() {
735        let parsed = parse(
736            "# One\n\n```starlark ci name=lint\n```\n\n## Two\n\n```starlark check name=lint\n```\n\n\
737             ```starlark name=other\n```\n",
738        );
739        assert_eq!(messages(&parsed), [
740            "sub/kizz.md:8 (Two): task option `name=lint` gives a name that the task at line 3 of \
741             this file already has, and a name is unique within its kizz.md",
742        ]);
743        assert!(matches!(&parsed.errors[0], ConfigError::TaskOption {
744            problem: OptionProblem::DuplicateName { first_line: 3 },
745            ..
746        }));
747        assert_eq!(summary(&parsed), [
748            (3, Some("One"), vec!["ci"]),
749            (11, Some("Two"), Vec::new()),
750        ]);
751        let other = parse_tasks(
752            Path::new("/work/other/kizz.md"),
753            Path::new("other/kizz.md"),
754            "```starlark name=lint\n```\n",
755        );
756        assert!(other.errors.is_empty(), "{:?}", other.errors);
757    }
758
759    /// A block with only a name is a task without targets, and draws no warning.
760    #[test]
761    fn a_block_with_only_a_name_is_a_task_without_targets() {
762        let parsed = parse("# Deploy\n\n```starlark name=deploy\nrun(\"ship\")\n```\n");
763        assert!(parsed.errors.is_empty(), "{:?}", parsed.errors);
764        assert!(parsed.warnings.is_empty(), "{:?}", parsed.warnings);
765        assert_eq!(summary(&parsed), [(3, Some("Deploy"), Vec::new())]);
766        assert_eq!(parsed.tasks[0].options.name.as_deref(), Some("deploy"));
767        assert_eq!(parsed.tasks[0].source, "run(\"ship\")\n");
768    }
769
770    /// A block with only `cache=never` warns as untagged and is not a task, and the
771    /// options of a block without targets or a name are still checked.
772    #[test]
773    fn a_block_with_only_cache_never_warns_and_is_checked() {
774        let parsed =
775            parse("# Odd\n\n```starlark cache=never\n```\n\n```starlark cache=sometimes\n```\n");
776        assert!(parsed.tasks.is_empty(), "{:?}", parsed.tasks);
777        assert_eq!(parsed.warnings, [
778            Warning::UntaggedBlock {
779                file: "sub/kizz.md".into(),
780                line: 3,
781                heading: Some("Odd".to_owned()),
782            },
783            Warning::UntaggedBlock {
784                file: "sub/kizz.md".into(),
785                line: 6,
786                heading: Some("Odd".to_owned()),
787            },
788        ]);
789        assert_eq!(messages(&parsed), [
790            "sub/kizz.md:6 (Odd): invalid value in task option `cache=sometimes`: `cache` \
791             accepts only `never`",
792        ]);
793    }
794}