1use 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
27pub const TASK_LANGUAGE: &str = "starlark";
29
30pub const TASK_OPTION_KEYS: &[&str] = &[NAME_KEY, CACHE_KEY];
32
33const NAME_KEY: &str = "name";
35
36const CACHE_KEY: &str = "cache";
38
39const CACHE_NEVER: &str = "never";
41
42pub const TASK_NAME_RULE: &str = "task names use only letters, digits, `_`, `.` and `-`";
44
45#[derive(Debug, Clone, Default, PartialEq, Eq)]
49pub struct TaskOptions {
50 pub name: Option<String>,
52 pub cache_never: bool,
55}
56
57impl TaskOptions {
58 #[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#[derive(Debug, Clone, PartialEq, Eq)]
75pub enum OptionProblem {
76 NoKey,
78 UnknownKey,
80 RepeatedKey {
82 key: String,
84 },
85 EmptyValue,
87 InvalidName,
89 InvalidCache,
91 DuplicateName {
93 first_line: usize,
95 },
96}
97
98impl OptionProblem {
99 #[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#[derive(Debug, Clone, PartialEq, Eq)]
137pub struct Task {
138 pub id: TaskId,
141 pub relative_file: PathBuf,
144 pub line: usize,
146 pub heading: Option<String>,
148 pub targets: Vec<String>,
151 pub options: TaskOptions,
153 pub source: String,
155}
156
157impl Task {
158 #[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#[derive(Debug, Default)]
167pub struct ParsedFile {
168 pub tasks: Vec<Task>,
170 pub warnings: Vec<Warning>,
172 pub errors: Vec<ConfigError>,
174}
175
176struct OpenBlock {
178 line: usize,
180 words: Vec<String>,
182 source: String,
184}
185
186struct BlockPlace<'a> {
188 relative_file: &'a Path,
190 line: usize,
192 heading: Option<&'a str>,
194}
195
196impl BlockPlace<'_> {
197 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#[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
278fn 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
318fn 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
417fn 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
430fn line_of(
432 line_starts: &[usize],
433 offset: usize,
434) -> usize {
435 line_starts.partition_point(|&start| start <= offset)
436}
437
438#[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 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 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 fn messages(parsed: &ParsedFile) -> Vec<String> {
477 parsed.errors.iter().map(ToString::to_string).collect()
478 }
479
480 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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 #[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}