1use htl::cache;
10mod junit;
11pub mod report;
12mod scaffold;
13
14#[derive(Clone, Copy, PartialEq, Eq, Debug, clap::ValueEnum)]
20enum Format {
21 Text,
23 Json,
26}
27
28#[derive(Clone, Copy, PartialEq, Eq, Debug, clap::ValueEnum)]
31enum CacheModeArg {
32 PerModule,
34 WholeRun,
36}
37
38#[derive(Subcommand)]
39enum TypesCmd {
40 Add {
43 library: String,
45 #[arg(long)]
47 from: Option<PathBuf>,
48 #[arg(long)]
50 force: bool,
51 },
52}
53
54#[derive(Subcommand)]
55enum PkgCmd {
56 Install,
58 Add {
60 name: String,
62 git: String,
64 #[arg(long)]
66 tag: Option<String>,
67 #[arg(long)]
69 rev: Option<String>,
70 #[arg(long)]
72 branch: Option<String>,
73 #[arg(long)]
76 entry: Option<PathBuf>,
77 #[arg(long)]
80 target_dir: Option<PathBuf>,
81 },
82 Update {
84 name: Option<String>,
86 #[arg(long)]
88 dry_run: bool,
89 #[arg(long)]
91 force: bool,
92 },
93 Clean {
95 #[arg(long)]
97 all: bool,
98 },
99 Patch {
102 dep: String,
104 #[arg(long)]
106 force: bool,
107 },
108}
109
110#[derive(Subcommand)]
111enum CacheCmd {
112 Clear {
114 path: Option<PathBuf>,
117 },
118 Status {
120 path: Option<PathBuf>,
123 #[arg(long, value_enum, default_value_t = Format::Text)]
125 format: Format,
126 #[arg(long)]
128 entries: bool,
129 },
130}
131
132#[derive(Subcommand)]
133enum BundleCmd {
134 Info {
137 file: PathBuf,
139 #[arg(long, value_enum, default_value_t = Format::Text)]
141 format: Format,
142 },
143}
144
145impl From<CacheModeArg> for cache::Mode {
146 fn from(m: CacheModeArg) -> Self {
147 match m {
148 CacheModeArg::PerModule => cache::Mode::PerModule,
149 CacheModeArg::WholeRun => cache::Mode::WholeRun,
150 }
151 }
152}
153
154use anyhow::{Context, Result, bail};
155use clap::{Parser, Subcommand};
156use htl::BuildTarget;
157use htl::Htl;
158use htl::bundle::Bundle;
159use htl::project;
163use std::fs;
164use std::path::{Path, PathBuf};
165use std::process::ExitCode;
166
167#[derive(Parser)]
168#[command(
169 name = "htl",
170 version,
171 about = "Teal, hidden: run / check / build .tl on mlua",
172 long_about = "\
173Teal, hidden: run / check / build .tl on mlua.
174
175htl is a toolchain for Teal, and a way to embed one. It type-checks `.tl` sources with \
176Teal's own checker, runs and tests them on an embedded mlua state, formats them, and \
177links them into a single stripped-bytecode bundle. A Rust host embeds the same engine, \
178so the scripts it ships are checked when the host is built rather than when its user \
179first runs one.
180
181The guide, with every command and what a project looks like:
182 https://github.com/ynishi/htl
183
184The API a Rust host holds — `include_tl!`, `#[host_module]`, the run cache:
185 https://docs.rs/htl"
186)]
187struct Cli {
188 #[command(subcommand)]
189 cmd: Cmd,
190}
191
192#[derive(Subcommand)]
193enum Cmd {
194 #[command(after_long_help = "\
200Examples:
201 htl check src every .tl under src/
202 htl check src --strict every warn counts as deny: warnings and lints fail
203 htl check src --lint nil-index=deny,no-any=warn
204 one rule fails the run, another is advice
205 htl check src --lint -tl:hint a warning kind of the Teal compiler silenced
206 htl check --list-lints every rule with its default level, then exit
207 htl check --explain union-exhaustive
208 why the rule exists and how to decide its cases
209
210The store is .htl/cache at the project root, the nearest htl.toml or mlua-pkg.toml above
211the paths; --no-cache skips it, --explain-cache says why a lookup missed.
212Caching: https://github.com/ynishi/htl#caching
213")]
214 Check {
215 paths: Vec<PathBuf>,
216 #[arg(long)]
218 strict: bool,
219 #[arg(long, allow_hyphen_values = true)]
225 lint: Option<String>,
226 #[arg(long)]
228 list_lints: bool,
229 #[arg(long, value_name = "RULE")]
232 explain: Option<String>,
233 #[arg(long, value_enum, default_value_t = Format::Text)]
235 format: Format,
236 #[arg(long)]
238 no_cache: bool,
239 #[arg(long, value_enum)]
241 cache_mode: Option<CacheModeArg>,
242 #[arg(long)]
244 explain_cache: bool,
245 },
246 #[command(after_long_help = "\
250Examples:
251 htl test every .tl that requires htl.test
252 htl test tests --filter parser only tests whose \"suite > name\" contains it
253 htl test --coverage --coverage-lines
254 which lines of each module the suite never reached
255 htl test --junit report.xml also write the run as a JUnit report, for a CI
256")]
257 Test {
258 paths: Vec<PathBuf>,
259 #[arg(long)]
261 filter: Option<String>,
262 #[arg(long, default_value = htl::testing::DEFAULT_LIB)]
264 lib: String,
265 #[arg(long, allow_hyphen_values = true)]
267 lint: Option<String>,
268 #[arg(long)]
270 fail_fast: bool,
271 #[arg(long)]
279 allow_empty: bool,
280 #[arg(short, long)]
282 verbose: bool,
283 #[arg(short, long, conflicts_with = "verbose")]
285 quiet: bool,
286 #[arg(long, value_name = "MS")]
288 slow: Option<f64>,
289 #[arg(long)]
291 update: bool,
292 #[arg(long)]
294 coverage: bool,
295 #[arg(long, requires = "coverage")]
297 coverage_lines: bool,
298 #[arg(long, value_name = "FILE")]
300 lcov: Option<PathBuf>,
301 #[arg(long, value_name = "FILE")]
303 junit: Option<PathBuf>,
304 #[arg(long)]
306 seed: Option<u64>,
307 #[arg(long, value_enum, default_value_t = Format::Text)]
309 format: Format,
310 #[arg(long)]
312 no_cache: bool,
313 #[arg(long)]
315 explain_cache: bool,
316 },
317 #[command(after_long_help = "\
330Examples:
331 htl fix src apply the safe fixes to every .tl under src/
332 htl fix src --diff --dry-run what would change, as a unified diff per file
333 htl fix src --rule forward-ref only that rule's fixes
334 htl fix src --unsafe also the fixes that may change what the program does
335")]
336 Fix {
337 paths: Vec<PathBuf>,
338 #[arg(long, value_delimiter = ',')]
341 rule: Vec<String>,
342 #[arg(long = "unsafe")]
344 unsafe_fixes: bool,
345 #[arg(long)]
347 dry_run: bool,
348 #[arg(long)]
350 diff: bool,
351 #[arg(long)]
353 allow_dirty: bool,
354 #[arg(long)]
356 allow_no_vcs: bool,
357 #[arg(long)]
359 exit_non_zero_on_fix: bool,
360 #[arg(long, value_enum, default_value_t = Format::Text)]
362 format: Format,
363 },
364 Dts {
379 dir: Option<PathBuf>,
381 },
382 #[command(after_long_help = "\
386Examples:
387 htl new hello src/main.tl, a module, tests/, mlua-pkg.toml
388 htl new hello --lib a library: no entry script
389 htl new hello --embed the same, plus a Rust host (--target bin)
390 htl new hello --target cdylib --lib
391 a library behind a C ABI, for a caller that is not Rust
392 htl new hello --embed --htl main
393 built against the unreleased htl (a git pin on main)
394 htl new hello --embed --htl path:../htl
395 built against a local checkout of this repository
396 htl new hello --no-x without the htlx dependency the manifest gets by default
397
398Build targets: https://docs.rs/htl/latest/htl/build_target/enum.BuildTarget.html
399Layout of a project: https://github.com/ynishi/htl#layout-of-a-project-htl-new
400")]
401 New {
402 name: String,
403 #[arg(long)]
405 lib: bool,
406 #[arg(long)]
408 embed: bool,
409 #[arg(long, value_name = "NAME", value_parser = clap::builder::PossibleValuesParser::new(scaffold::target_names()))]
413 target: Option<String>,
414 #[arg(long, value_name = "REQ")]
418 htl: Option<String>,
419 #[arg(long)]
421 no_x: bool,
422 },
423 Init {
425 dir: Option<PathBuf>,
426 #[arg(long)]
427 lib: bool,
428 #[arg(long)]
430 embed: bool,
431 #[arg(long, value_name = "NAME", value_parser = clap::builder::PossibleValuesParser::new(scaffold::target_names()))]
433 target: Option<String>,
434 #[arg(long, value_name = "REQ")]
438 htl: Option<String>,
439 #[arg(long)]
441 no_x: bool,
442 },
443 Pkg {
446 #[command(subcommand)]
447 cmd: PkgCmd,
448 },
449 Types {
451 #[command(subcommand)]
452 cmd: TypesCmd,
453 },
454 Cache {
458 #[command(subcommand)]
459 cmd: CacheCmd,
460 },
461 Fmt {
463 paths: Vec<PathBuf>,
464 #[arg(long)]
466 check: bool,
467 #[arg(long)]
469 indent: Option<usize>,
470 },
471 Gen {
481 file: PathBuf,
482 #[arg(short, long)]
483 out: Option<PathBuf>,
484 },
485 Run {
487 file: PathBuf,
488 #[arg(trailing_var_arg = true)]
489 args: Vec<String>,
490 },
491 #[command(after_long_help = "\
498Examples:
499 htl build src/main.tl -o app.hb
500 the entry's require closure, as one bundle
501 htl build src/main.tl -o app.hb --debug
502 keep line numbers and local names in the bytecode
503 htl build src/main.tl -o app.hb --host mymod
504 leave a module the host provides out of the bundle
505 htl run app.hb run what was built
506
507Caching: https://github.com/ynishi/htl#caching
508")]
509 Build {
516 entry: PathBuf,
520 #[arg(short, long, default_value = "app.hb")]
521 out: PathBuf,
522 #[arg(short, long, default_value = "main")]
524 main: String,
525 #[arg(long)]
527 debug: bool,
528 #[arg(long)]
531 source: bool,
532 #[arg(long, value_delimiter = ',')]
534 extra: Vec<String>,
535 #[arg(long, value_delimiter = ',')]
537 host: Vec<String>,
538 #[arg(long)]
541 no_cache: bool,
542 #[arg(long)]
544 explain_cache: bool,
545 },
546 #[command(after_long_help = "\
551Examples:
552 htl unused modules and dependencies no entry reaches
553 htl unused --exit-non-zero-on-unused
554 the same report, and a non-zero exit for a CI
555 htl unused --format json the same report as one JSON document
556")]
557 Unused {
558 paths: Vec<PathBuf>,
561 #[arg(long, value_enum, default_value_t = Format::Text)]
563 format: Format,
564 #[arg(long)]
566 exit_non_zero_on_unused: bool,
567 #[arg(long)]
570 no_cache: bool,
571 #[arg(long)]
573 explain_cache: bool,
574 },
575 #[command(after_long_help = "\
582Examples:
583 htl resolve mq the chain for require(\"mq\")
584 htl resolve socket.http a name with dots, as a require spells it
585 htl resolve mq --format json the same rows as one JSON document
586
587Exits 1 when the name resolves to nothing, when two files implement it, or when a file of
588the project implements a name the host provides, so a script can ask.
589
590`htl.test` is answered like a host-provided name: no file of the project implements it
591(`htl test` preloads it into the state it runs), and its one row is the declaration the
592binary carries, `provided by the environment`.
593")]
594 Resolve {
595 module: String,
597 path: Option<PathBuf>,
599 #[arg(long, value_enum, default_value_t = Format::Text)]
601 format: Format,
602 },
603 Bundle {
607 #[command(subcommand)]
608 cmd: BundleCmd,
609 },
610}
611
612pub fn command() -> clap::Command {
618 <Cli as clap::CommandFactory>::command()
619}
620
621pub fn run() -> ExitCode {
629 let mut argv: Vec<String> = std::env::args().collect();
631 let is_cargo = Path::new(&argv[0])
632 .file_stem()
633 .and_then(|s| s.to_str())
634 .map(|s| s == "cargo-htl")
635 .unwrap_or(false);
636 if is_cargo && argv.get(1).map(String::as_str) == Some("htl") {
637 argv.remove(1);
638 }
639 match real_main(Cli::parse_from(argv)) {
640 Ok(code) => code,
641 Err(e) => {
642 eprintln!("htl: {e:#}");
643 ExitCode::from(2)
644 }
645 }
646}
647
648fn real_main(cli: Cli) -> Result<ExitCode> {
649 match cli.cmd {
650 Cmd::Check {
651 paths,
652 strict,
653 lint,
654 list_lints,
655 explain,
656 format,
657 no_cache,
658 cache_mode,
659 explain_cache,
660 } => cmd_check(
661 &paths,
662 lint.as_deref(),
663 CheckFlags {
664 strict,
665 list_lints,
666 explain_rule: explain,
667 json: format == Format::Json,
668 use_cache: !no_cache,
669 cache_mode: cache_mode.map(Into::into),
670 explain: explain_cache,
671 },
672 ),
673 Cmd::Fmt {
674 paths,
675 check,
676 indent,
677 } => cmd_fmt(&paths, check, indent),
678 Cmd::Test {
679 paths,
680 filter,
681 lib,
682 lint,
683 fail_fast,
684 allow_empty,
685 verbose,
686 quiet,
687 slow,
688 update,
689 coverage,
690 coverage_lines,
691 lcov,
692 junit,
693 seed,
694 format,
695 no_cache,
696 explain_cache,
697 } => cmd_test(
698 &paths,
699 filter.as_deref(),
700 &lib,
701 lint.as_deref(),
702 TestFlags {
703 fail_fast,
704 allow_empty,
705 verbose,
706 quiet,
707 slow,
708 update,
709 coverage: coverage || lcov.is_some(),
710 coverage_lines,
711 lcov,
712 junit,
713 json: format == Format::Json,
714 no_cache,
715 explain: explain_cache,
716 seed,
717 },
718 ),
719 Cmd::Pkg { cmd } => match cmd {
720 PkgCmd::Install => cmd_pkg_install(),
721 PkgCmd::Add {
722 name,
723 git,
724 tag,
725 rev,
726 branch,
727 entry,
728 target_dir,
729 } => cmd_pkg_add(htl::pkg::mlua_pkg::ops::AddSpec {
730 name,
731 git,
732 tag,
733 rev,
734 branch,
735 entry,
736 target_dir,
737 }),
738 PkgCmd::Update {
739 name,
740 dry_run,
741 force,
742 } => cmd_pkg_update(htl::pkg::mlua_pkg::ops::UpdateOpts {
743 name,
744 dry_run,
745 force,
746 }),
747 PkgCmd::Clean { all } => cmd_pkg_clean(all),
748 PkgCmd::Patch { dep, force } => cmd_pkg_patch(&dep, force),
749 },
750 Cmd::Types { cmd } => match cmd {
751 TypesCmd::Add {
752 library,
753 from,
754 force,
755 } => cmd_types_add(&library, from.as_deref(), force),
756 },
757 Cmd::Cache { cmd } => match cmd {
758 CacheCmd::Clear { path } => cmd_cache_clear(path.as_deref()),
759 CacheCmd::Status {
760 path,
761 format,
762 entries,
763 } => cmd_cache_status(path.as_deref(), format == Format::Json, entries),
764 },
765 Cmd::Dts { dir } => cmd_dts(dir.as_deref()),
766 Cmd::New {
767 name,
768 lib,
769 embed,
770 target,
771 htl,
772 no_x,
773 } => cmd_new(&name, lib, embed, target.as_deref(), htl.as_deref(), no_x),
774 Cmd::Init {
775 dir,
776 lib,
777 embed,
778 target,
779 htl,
780 no_x,
781 } => cmd_init(
782 dir.as_deref(),
783 lib,
784 embed,
785 target.as_deref(),
786 htl.as_deref(),
787 no_x,
788 ),
789 Cmd::Gen { file, out } => cmd_gen(&file, out.as_deref()),
790 Cmd::Run { file, args } => cmd_run(&file, &args),
791 Cmd::Fix {
792 paths,
793 rule,
794 unsafe_fixes,
795 dry_run,
796 diff,
797 allow_dirty,
798 allow_no_vcs,
799 exit_non_zero_on_fix,
800 format,
801 } => cmd_fix(
802 &paths,
803 FixFlags {
804 rule,
805 unsafe_fixes,
806 dry_run: dry_run || diff,
807 diff,
808 allow_dirty,
809 allow_no_vcs,
810 exit_non_zero_on_fix,
811 json: format == Format::Json,
812 },
813 ),
814 Cmd::Build {
815 entry,
816 out,
817 main,
818 debug,
819 source,
820 extra,
821 host,
822 no_cache,
823 explain_cache,
824 } => cmd_build(
825 &entry,
826 &out,
827 &main,
828 htl::link::LinkOptions {
829 debug,
830 source,
831 extra,
832 host,
833 entry_name: None,
834 },
835 BuildCache {
836 use_cache: !no_cache,
837 explain: explain_cache,
838 },
839 ),
840 Cmd::Unused {
841 paths,
842 format,
843 exit_non_zero_on_unused,
844 no_cache,
845 explain_cache,
846 } => cmd_unused(
847 &paths,
848 UnusedFlags {
849 json: format == Format::Json,
850 fail_on_unused: exit_non_zero_on_unused,
851 use_cache: !no_cache,
852 explain: explain_cache,
853 },
854 ),
855 Cmd::Resolve {
856 module,
857 path,
858 format,
859 } => cmd_resolve(&module, path.as_deref(), format == Format::Json),
860 Cmd::Bundle { cmd } => match cmd {
861 BundleCmd::Info { file, format } => cmd_bundle_info(&file, format == Format::Json),
862 },
863 }
864}
865
866fn text_sink() -> project::Sink<report::Out> {
877 project::Sink::new(report::Out::new(false))
878}
879
880fn judged(found: &htl::verdict::Findings, policy: &htl::verdict::Policy) -> String {
884 let mut out = String::new();
885 if policy.capped {
886 return out;
887 }
888 if found.denied > 0 {
889 out.push_str(&format!(", {} at deny", found.denied));
890 }
891 if policy.strict && found.warnings + found.lints > 0 {
892 out.push_str(&format!(
893 ", {} warning(s) and {} lint(s) under strict",
894 found.warnings, found.lints
895 ));
896 }
897 out
898}
899
900fn config_lang(h: &Htl, cfg: &project::Config) -> Result<()> {
906 h.set_lang(&project::lang_of(cfg))
907}
908
909fn config_lints(h: &Htl, cfg: &project::Config) -> Result<htl::lint::Lints> {
910 let spec = cfg
911 .as_ref()
912 .map(|(_, _, c)| c.lint_spec())
913 .unwrap_or_default();
914 let lints = htl::lint::Lints::parse(&spec)?;
915 h.select_lints(lints.selection())?;
916 Ok(lints)
917}
918
919fn auto_dts(start: &Path) -> Result<()> {
930 auto_dts_to(start, true)
931}
932
933fn auto_dts_to(start: &Path, write: bool) -> Result<()> {
937 let mut project = None;
938 if let Some((root, _, cfg)) = load_config(start)? {
939 let model = htl::model::Project::load(&root, cfg)?;
941 let contracts: Vec<_> = model.contracts.iter().map(|c| c.terms.clone()).collect();
942 let (results, problems) = htl::contract::publish_to(&root, &contracts, write);
943 announce_dts_to(&results, &root, write);
944 for p in &problems {
945 eprintln!("dts: {p}");
946 }
947 project = Some(root);
948 }
949 let Some(root) = htl::dts::find_cargo_package_root(start) else {
950 return Ok(());
951 };
952 let results =
953 htl::dts::generate_crate_to(&root, write).map_err(|e| anyhow::anyhow!("htl dts: {e}"))?;
954 announce_dts_to(&results, &root, write);
955 let types_root = project.unwrap_or_else(|| root.clone());
956 let report = dep_dts_to(&root, &types_root, write);
957 announce_dts_to(&report.written, &types_root, write);
958 announce_dep_report(&report, "dts: ");
959 Ok(())
960}
961
962#[derive(Default)]
969struct DepReport {
970 written: Vec<(PathBuf, bool)>,
972 not_written: Vec<String>,
974 left_in_place: Vec<String>,
977 unresolved: Option<String>,
982}
983
984fn dep_dts(cargo_root: &Path, types_root: &Path) -> DepReport {
991 dep_dts_to(cargo_root, types_root, true)
992}
993
994fn dep_dts_to(cargo_root: &Path, types_root: &Path, write: bool) -> DepReport {
996 let decls = match htl::dep_dts::resolve(cargo_root) {
997 Ok(d) => d,
998 Err(e) => {
999 return DepReport {
1000 unresolved: Some(e),
1001 ..DepReport::default()
1002 };
1003 }
1004 };
1005 let types = match decl_root(types_root) {
1008 Ok(t) => t,
1009 Err(e) => {
1010 return DepReport {
1011 unresolved: Some(format!("{e:#}")),
1012 ..DepReport::default()
1013 };
1014 }
1015 };
1016 let left_in_place = htl::dep_dts::orphans(&types, &decls);
1017 let (written, not_written) = htl::dep_dts::materialise_to(&types, &decls, write);
1018 DepReport {
1019 written,
1020 not_written,
1021 left_in_place,
1022 unresolved: None,
1023 }
1024}
1025
1026fn announce_dep_report(report: &DepReport, prefix: &str) {
1031 for p in &report.not_written {
1032 eprintln!("{prefix}not written: {p}");
1033 }
1034 for p in &report.left_in_place {
1035 eprintln!("{prefix}left in place: {p}");
1036 }
1037 if let Some(e) = &report.unresolved {
1038 eprintln!("{prefix}{e}");
1039 }
1040}
1041
1042fn announce_dts_to(results: &[(PathBuf, bool)], root: &Path, wrote: bool) {
1045 for (target, changed) in results {
1046 if *changed {
1047 let target = target.strip_prefix(root).unwrap_or(target).display();
1048 if wrote {
1049 eprintln!("dts: wrote {target}");
1050 } else {
1051 eprintln!(
1052 "dts: would write {target} (dry run: not written; checked against the \
1053 file on disk)"
1054 );
1055 }
1056 }
1057 }
1058}
1059
1060fn cmd_dts(dir: Option<&Path>) -> Result<ExitCode> {
1061 let start = match dir {
1062 Some(d) => d.to_path_buf(),
1063 None => std::env::current_dir()?,
1064 };
1065 let mut results = Vec::new();
1068 let mut failed = false;
1069 let mut project = None;
1070 if let Some((croot, _, cfg)) = load_config(&start)? {
1071 let model = htl::model::Project::load(&croot, cfg)?;
1072 let contracts: Vec<_> = model.contracts.iter().map(|c| c.terms.clone()).collect();
1073 let (published, problems) = htl::contract::publish(&croot, &contracts);
1074 for p in &problems {
1075 eprintln!(" {p}");
1076 }
1077 failed = !problems.is_empty();
1080 results.extend(published);
1081 project = Some(croot);
1082 }
1083 let code = |failed: bool| {
1084 if failed {
1085 ExitCode::FAILURE
1086 } else {
1087 ExitCode::SUCCESS
1088 }
1089 };
1090 let Some(root) = htl::dts::find_cargo_package_root(&start) else {
1091 if results.is_empty() && !failed {
1092 bail!(
1093 "no Cargo.toml with a [package] section, and no ---@contract type to publish, \
1094 at or above {}",
1095 start.display()
1096 );
1097 }
1098 report_dts(&results, &start);
1099 return Ok(code(failed));
1100 };
1101 results.extend(htl::dts::generate_crate(&root).map_err(|e| anyhow::anyhow!("{e}"))?);
1102 let types_root = project.unwrap_or_else(|| root.clone());
1103 let report = dep_dts(&root, &types_root);
1104 announce_dep_report(&report, " ");
1105 failed = failed || !report.not_written.is_empty();
1108 results.extend(report.written);
1109 report_dts(&results, &root);
1110 Ok(code(failed))
1111}
1112
1113fn report_dts(results: &[(PathBuf, bool)], root: &Path) {
1114 let mut written = 0usize;
1115 for (target, w) in results {
1116 let rel = target.strip_prefix(root).unwrap_or(target).display();
1117 eprintln!(" {} {}", if *w { "wrote " } else { "unchanged" }, rel);
1118 written += usize::from(*w);
1119 }
1120 eprintln!(
1121 "htl dts: {} declaration(s) from {}, {} written",
1122 results.len(),
1123 root.display(),
1124 written
1125 );
1126}
1127
1128fn apply_model(
1135 h: &Htl,
1136 cfg: &project::Config,
1137 start: &Path,
1138) -> Result<Option<htl::model::Project>> {
1139 let model = project::model_of(cfg, start)?;
1140 if let Some(m) = &model {
1141 h.apply_model(m, htl::model::View::Source)?;
1142 }
1143 Ok(model)
1144}
1145
1146fn report_scaffold(dir: &Path, written: &[PathBuf], kept: &[PathBuf]) {
1150 let rel = |p: &PathBuf| p.strip_prefix(dir).unwrap_or(p).display().to_string();
1151 for p in written {
1152 eprintln!(" created {}", rel(p));
1153 }
1154 for p in kept {
1155 eprintln!(" kept {} (already there)", rel(p));
1156 }
1157 if kept.is_empty() {
1158 eprintln!(
1159 "htl: {} file(s) written under {}",
1160 written.len(),
1161 dir.display()
1162 );
1163 } else {
1164 eprintln!(
1165 "htl: {} file(s) written, {} kept under {}",
1166 written.len(),
1167 kept.len(),
1168 dir.display()
1169 );
1170 }
1171}
1172
1173fn cmd_new(
1174 name: &str,
1175 lib: bool,
1176 embed: bool,
1177 target: Option<&str>,
1178 htl: Option<&str>,
1179 no_x: bool,
1180) -> Result<ExitCode> {
1181 let dir = PathBuf::from(name);
1182 let pkg_name = dir
1183 .file_name()
1184 .and_then(|s| s.to_str())
1185 .ok_or_else(|| anyhow::anyhow!("invalid project name: {name}"))?
1186 .to_string();
1187 let target = scaffold::resolve_target(target, embed, lib)?;
1191 let htl = scaffold::HtlPin::parse(htl)?;
1192 let opts = scaffold::Options {
1193 lib,
1194 target,
1195 htl,
1196 no_x,
1197 };
1198 let done = scaffold::scaffold(&dir, &pkg_name, &opts, true)?;
1199 report_scaffold(&dir, &done.written, &[]);
1200 let fetch = if opts.writes_htlx() {
1203 "htl pkg install && "
1204 } else {
1205 ""
1206 };
1207 let then = match opts.target.map(|t| t.target) {
1213 Some(BuildTarget::Window) => "htl check . && cargo run",
1214 _ => "htl test",
1215 };
1216 eprintln!("next: cd {} && {fetch}{then}", dir.display());
1217 Ok(ExitCode::SUCCESS)
1218}
1219
1220fn cmd_init(
1221 dir: Option<&Path>,
1222 lib: bool,
1223 embed: bool,
1224 target: Option<&str>,
1225 htl: Option<&str>,
1226 no_x: bool,
1227) -> Result<ExitCode> {
1228 let dir = match dir {
1229 Some(d) => d.to_path_buf(),
1230 None => std::env::current_dir()?,
1231 };
1232 let abs = std::fs::canonicalize(&dir).unwrap_or(dir.clone());
1233 let name = abs
1234 .file_name()
1235 .and_then(|s| s.to_str())
1236 .ok_or_else(|| anyhow::anyhow!("cannot derive a project name from {}", abs.display()))?
1237 .to_string();
1238 let asked_for_a_target = target.is_some() || embed;
1239 let target = scaffold::resolve_target(target, embed, lib)?;
1240 let htl = scaffold::HtlPin::parse(htl)?;
1241 let opts = scaffold::Options {
1242 lib,
1243 target,
1244 htl,
1245 no_x,
1246 };
1247 let done = scaffold::scaffold(&dir, &name, &opts, false)?;
1248 let kept: &[PathBuf] = if asked_for_a_target { &done.kept } else { &[] };
1251 if done.written.is_empty() && kept.is_empty() {
1252 eprintln!("htl init: nothing to do, all scaffold files already exist");
1253 } else {
1254 report_scaffold(&dir, &done.written, kept);
1255 }
1256 Ok(ExitCode::SUCCESS)
1257}
1258
1259fn pkg_project() -> Result<htl::pkg::MluaProject> {
1265 let cwd = std::env::current_dir()?;
1266 let root = htl::model::Project::find_root(&cwd)?.map(|r| r.root);
1267 root.filter(|r| r.join(htl::pkg::MANIFEST_NAME).is_file())
1268 .map(|r| htl::pkg::MluaProject::at(&r))
1269 .with_context(|| {
1270 format!(
1271 "no {} above {}: `htl pkg` runs in a project",
1272 htl::pkg::MANIFEST_NAME,
1273 cwd.display()
1274 )
1275 })
1276}
1277
1278fn decl_root(root: &Path) -> Result<PathBuf> {
1282 let cfg = load_config(root)?;
1283 Ok(project::model_of(&cfg, root)?
1284 .and_then(|m| m.own().roots.decl.clone())
1285 .unwrap_or_else(|| root.join("types")))
1286}
1287
1288fn cmd_pkg_install() -> Result<ExitCode> {
1290 let project = pkg_project()?;
1291 let report = project.install()?;
1292 report_install(&report, &project);
1293 let project = htl::pkg::MluaProject::at(&project.root);
1297 report_types_sync(
1298 &project.sync_types(&decl_root(&project.root)?)?,
1299 &project.root,
1300 );
1301 report_patch_drift(&project);
1302 Ok(ExitCode::SUCCESS)
1303}
1304
1305fn report_install(
1307 report: &htl::pkg::mlua_pkg::ops::InstallReport,
1308 project: &htl::pkg::MluaProject,
1309) {
1310 use htl::pkg::mlua_pkg::ops::Placement;
1311 for w in &report.warnings {
1312 if w.contains("patch_dir") && w.contains("not used") {
1316 continue;
1317 }
1318 eprintln!("warning: {w}");
1319 }
1320 let rel = |p: &Path| {
1321 p.strip_prefix(&project.root)
1322 .unwrap_or(p)
1323 .display()
1324 .to_string()
1325 };
1326 for p in &report.packages {
1327 let sha: String = p.sha.chars().take(7).collect();
1328 let where_it_is = match (&p.placement, p.patched) {
1329 (_, true) => format!("from {}", rel(p.root())),
1330 (Placement::Copied(dest), _) => format!("copied to {}", rel(dest)),
1331 (Placement::Symlink(_), _) => p.entry.display().to_string(),
1332 };
1333 eprintln!(" install {} {sha} ({where_it_is})", p.name);
1334 }
1335 let n = report.packages.len();
1336 if report.transitive > 0 {
1337 eprintln!(
1338 "htl pkg install: {n} package(s), {} of them transitive",
1339 report.transitive
1340 );
1341 } else {
1342 eprintln!("htl pkg install: {n} package(s)");
1343 }
1344}
1345
1346fn cmd_pkg_add(spec: htl::pkg::mlua_pkg::ops::AddSpec) -> Result<ExitCode> {
1354 use htl::pkg::mlua_pkg::ops::AddOutcome;
1355 let cwd = std::env::current_dir()?;
1356 let root = htl::model::Project::find_root(&cwd)?
1357 .map(|r| r.root)
1358 .unwrap_or(cwd);
1359 let project = htl::pkg::MluaProject::at(&root);
1360 let name = spec.name.clone();
1361 let done = project.add(spec)?;
1362 let manifest = project
1363 .manifest
1364 .strip_prefix(&project.root)
1365 .unwrap_or(&project.manifest)
1366 .display();
1367 if done.report.manifest_created {
1368 eprintln!(" created {manifest}");
1369 }
1370 let verb = match done.report.outcome {
1371 AddOutcome::Added => "added",
1372 AddOutcome::Replaced => "updated",
1373 };
1374 eprintln!(" {verb} {name} in {manifest}");
1375 if let Some(dir) = &done.kept_patch_dir {
1376 eprintln!(
1380 " kept patch_dir = {} ({name} is patched)",
1381 dir.display()
1382 );
1383 }
1384 eprintln!("htl pkg add: run `htl pkg install` to fetch it");
1385 Ok(ExitCode::SUCCESS)
1386}
1387
1388fn cmd_pkg_update(opts: htl::pkg::mlua_pkg::ops::UpdateOpts) -> Result<ExitCode> {
1390 use htl::pkg::mlua_pkg::ops::UpdateOutcome;
1391 let project = pkg_project()?;
1392 let dry_run = opts.dry_run;
1393 let report = project.update(opts)?;
1394 if report.entries.is_empty() {
1395 eprintln!("htl pkg update: no dependency selected");
1396 return Ok(ExitCode::SUCCESS);
1397 }
1398 for (name, outcome) in &report.entries {
1399 match outcome {
1400 UpdateOutcome::TagBumped { old, new } => {
1401 eprintln!(" update {name}: tag {old} -> {new}")
1402 }
1403 UpdateOutcome::PrefixResolved { pin, resolved } => eprintln!(
1404 " update {name}: prefix '{pin}' is {resolved} (the manifest keeps the prefix)"
1405 ),
1406 UpdateOutcome::Refresh => eprintln!(" update {name}: refresh (branch or unpinned)"),
1407 UpdateOutcome::Skipped(why) => eprintln!(" skip {name}: {why}"),
1408 }
1409 }
1410 if dry_run {
1411 eprintln!("htl pkg update: dry run; nothing was written");
1412 return Ok(ExitCode::SUCCESS);
1413 }
1414 if let Some(install) = &report.install {
1415 report_install(install, &project);
1416 let project = htl::pkg::MluaProject::at(&project.root);
1417 report_types_sync(
1418 &project.sync_types(&decl_root(&project.root)?)?,
1419 &project.root,
1420 );
1421 report_patch_drift(&project);
1422 }
1423 Ok(ExitCode::SUCCESS)
1424}
1425
1426fn cmd_pkg_clean(all: bool) -> Result<ExitCode> {
1428 use htl::pkg::mlua_pkg::ops::CleanReport;
1429 let project = pkg_project()?;
1430 match project.clean(all)? {
1431 CleanReport::CacheRemoved => eprintln!("htl pkg clean: removed every cached package"),
1432 CleanReport::NoLockfile => {
1433 eprintln!("htl pkg clean: no lockfile, so nothing was ever cached")
1434 }
1435 CleanReport::StaleRemoved { removed: 0 } => eprintln!("htl pkg clean: nothing to remove"),
1436 CleanReport::StaleRemoved { removed } => eprintln!(
1437 "htl pkg clean: removed {removed} cache entr{} the lockfile no longer refers to",
1438 if removed == 1 { "y" } else { "ies" }
1439 ),
1440 }
1441 Ok(ExitCode::SUCCESS)
1442}
1443
1444fn report_patch_drift(project: &htl::pkg::MluaProject) {
1453 let short = |s: &str| s.chars().take(7).collect::<String>();
1454 for s in project.patch_status() {
1455 if s.in_use {
1456 continue;
1457 }
1458 let rel = s
1459 .dir
1460 .strip_prefix(&project.root)
1461 .unwrap_or(&s.dir)
1462 .display();
1463 let why = match (&s.base, &s.locked) {
1464 _ if !s.dir.is_dir() => "the copy is not there".to_string(),
1465 (None, _) => "the lockfile records no revision it was taken from".to_string(),
1466 (Some(b), Some(l)) => {
1467 format!("taken from {}, {} is now at {}", short(b), s.name, short(l))
1468 }
1469 (Some(b), None) => format!("taken from {}, and nothing is locked", short(b)),
1470 };
1471 eprintln!(" patch {rel} is not in use ({why})");
1472 eprintln!(
1473 " carry the change forward: commit it, then `htl pkg patch {}`",
1474 s.name
1475 );
1476 eprintln!(" drop it: remove patch_dir from mlua-pkg.toml and delete {rel}");
1477 }
1478}
1479
1480fn cmd_pkg_patch(dep: &str, force: bool) -> Result<ExitCode> {
1485 let project = pkg_project().context("a patch belongs to a project, so this runs in one")?;
1486 let done = project.patch(dep, force)?;
1487 let report = &done.report;
1488 let rel = report
1489 .patch_dir
1490 .strip_prefix(&project.root)
1491 .unwrap_or(&report.patch_dir);
1492 let verb = if report.created { "patched" } else { "rebuilt" };
1493 let base: String = report.base.chars().take(7).collect();
1494 eprintln!(" {verb} {} ({dep} at {base})", rel.display());
1495 if !done.dropped.is_empty() {
1499 eprintln!(
1500 " dropped {} (the repository's, not the package's)",
1501 done.dropped.join(", ")
1502 );
1503 }
1504 eprintln!("htl: it is the project's code now — edit it, commit it, then `htl pkg install`.");
1505 Ok(ExitCode::SUCCESS)
1506}
1507
1508fn report_types_sync(sync: &htl::pkg::TypesSync, root: &Path) {
1512 let rel = |p: &Path| p.strip_prefix(root).unwrap_or(p).display().to_string();
1513 for (path, dep) in &sync.written {
1514 eprintln!(" types {} (from {dep})", rel(path));
1515 }
1516 for (path, dep) in &sync.taken {
1517 eprintln!(" kept {} ({dep} publishes one too)", rel(path));
1518 }
1519}
1520
1521fn cmd_types_add(library: &str, from: Option<&Path>, force: bool) -> Result<ExitCode> {
1525 let project = pkg_project().context("`types/` is a project's, so this runs in one")?;
1526 let types = decl_root(&project.root)?;
1527 let sync = match from {
1528 Some(dir) => project.add_types_from(dir, library, "local", force, &types)?,
1529 None => project.add_types(library, force, &types)?,
1530 };
1531 report_types_sync(&sync, &project.root);
1532 if sync.written.is_empty() && !sync.taken.is_empty() {
1533 eprintln!("htl: nothing written; --force replaces what is already there");
1534 }
1535 Ok(ExitCode::SUCCESS)
1536}
1537
1538struct UnusedFlags {
1540 json: bool,
1541 fail_on_unused: bool,
1544 use_cache: bool,
1545 explain: bool,
1546}
1547
1548struct CheckFlags {
1550 strict: bool,
1551 list_lints: bool,
1552 explain_rule: Option<String>,
1554 json: bool,
1555 use_cache: bool,
1556 cache_mode: Option<cache::Mode>,
1557 explain: bool,
1558}
1559
1560struct TestFlags {
1561 fail_fast: bool,
1562 allow_empty: bool,
1564 verbose: bool,
1565 quiet: bool,
1566 slow: Option<f64>,
1567 update: bool,
1568 coverage: bool,
1569 coverage_lines: bool,
1570 lcov: Option<PathBuf>,
1572 junit: Option<PathBuf>,
1574 json: bool,
1575 no_cache: bool,
1576 explain: bool,
1577 seed: Option<u64>,
1578}
1579
1580fn print_coverage(cov: &report::CoverageReport, with_lines: bool) {
1581 let width = cov
1582 .modules
1583 .iter()
1584 .map(|m| m.path.len())
1585 .max()
1586 .unwrap_or(4)
1587 .max(5);
1588 for m in &cov.modules {
1589 eprintln!(
1590 "coverage: {:<width$} {:>5}/{:<5} {:5.1}%",
1591 m.path,
1592 m.executed,
1593 m.total,
1594 100.0 * m.executed as f64 / m.total as f64
1595 );
1596 if !m.never_ran.is_empty() {
1597 let names: Vec<String> = m
1598 .never_ran
1599 .iter()
1600 .map(|f| format!("{} ({})", f.name, f.line))
1601 .collect();
1602 eprintln!(" never ran: {}", names.join(", "));
1603 }
1604 if with_lines && !m.unexecuted.is_empty() {
1605 let spans: Vec<String> = m
1606 .unexecuted
1607 .iter()
1608 .map(|(a, b)| {
1609 if a == b {
1610 a.to_string()
1611 } else {
1612 format!("{a}-{b}")
1613 }
1614 })
1615 .collect();
1616 eprintln!(" unexecuted: {}", spans.join(", "));
1617 }
1618 }
1619 if cov.total > 0 {
1620 eprintln!(
1621 "coverage: {:<width$} {:>5}/{:<5} {:5.1}% (statements)",
1622 "total",
1623 cov.executed,
1624 cov.total,
1625 100.0 * cov.executed as f64 / cov.total as f64
1626 );
1627 } else {
1628 eprintln!("coverage: no .tl module reached");
1629 }
1630}
1631
1632fn junit_suite(rep: &htl::testing::FileReport) -> junit::Suite {
1640 let mut left: Vec<&str> = rep.failures.iter().map(String::as_str).collect();
1641 let cases = rep
1642 .tests
1643 .iter()
1644 .map(|t| {
1645 let failure = (!t.ok)
1646 .then(|| {
1647 let head = format!("{}: ", t.name);
1648 let at = left.iter().position(|m| m.starts_with(&head))?;
1649 Some(left.remove(at)[head.len()..].to_string())
1650 })
1651 .flatten();
1652 junit::Case {
1653 name: t.name.clone(),
1654 ms: t.ms,
1655 failure: failure.or_else(|| (!t.ok).then(|| "failed".to_string())),
1658 }
1659 })
1660 .collect();
1661 let error = if !rep.check.ok() {
1662 Some(junit::Error {
1663 message: "type check failed".to_string(),
1664 kind: "check",
1665 body: rep
1666 .check
1667 .error_items
1668 .iter()
1669 .map(|d| d.clone().spelled().to_string())
1670 .collect::<Vec<_>>()
1671 .join("\n"),
1672 })
1673 } else {
1674 rep.error.as_ref().map(|e| junit::Error {
1675 message: e.clone(),
1676 kind: "error",
1677 body: e.clone(),
1678 })
1679 };
1680 junit::Suite {
1681 file: htl::diagnostic::display_path(&rep.path),
1682 duration_ms: rep.duration_ms,
1683 error,
1684 cases,
1685 }
1686}
1687
1688fn cmd_test(
1689 paths: &[PathBuf],
1690 filter: Option<&str>,
1691 lib: &str,
1692 lint: Option<&str>,
1693 flags: TestFlags,
1694) -> Result<ExitCode> {
1695 let paths = if paths.is_empty() {
1696 vec![PathBuf::from(".")]
1697 } else {
1698 paths.to_vec()
1699 };
1700 if let Some(first) = paths.first() {
1701 auto_dts(first)?;
1702 }
1703 let cfg = load_config(&paths[0])?;
1707 let model = project::model_of(&cfg, &paths[0])?;
1708 let skip = project::not_walked(model.as_ref(), &paths, htl::model::Purpose::Test);
1709 let files = htl::testing::discover_tests_for(&paths, &skip, lib)?;
1710 project::refuse_flat_root(model.as_ref(), &paths, &files)?;
1713 let empty = files.is_empty();
1717 if empty {
1718 eprintln!("htl test: no test files found (looked for .tl files that require(\"{lib}\"))");
1719 }
1720 let opts = project::TestOptions {
1721 config: &cfg,
1722 model: model.as_ref(),
1723 lint,
1724 lib,
1725 filter,
1726 run: htl::testing::RunOptions {
1727 fail_fast: flags.fail_fast,
1728 update_snapshots: flags.update,
1729 coverage: flags.coverage,
1730 seed: flags.seed,
1732 async_: Default::default(),
1734 lang: Default::default(),
1735 },
1736 cache: project::cache_options(
1737 !flags.no_cache,
1738 Some(cache::Mode::PerModule),
1739 &cfg,
1740 flags.explain,
1741 ),
1742 };
1743
1744 let mut sink = project::Sink::new(report::Out::new(flags.json));
1745 let mut json_files: Vec<report::TestFile> = Vec::new();
1746 let mut junit_suites: Vec<junit::Suite> = Vec::new();
1747 let rep = if empty {
1751 project::TestReport {
1754 files: Vec::new(),
1755 ran: 0,
1756 passed: 0,
1757 failed: 0,
1758 files_with_errors: 0,
1759 replayed: 0,
1760 seed: flags.seed.unwrap_or(0),
1761 duration_ms: 0.0,
1762 coverage: None,
1763 }
1764 } else {
1765 project::test(&mut sink, &files, &opts, &mut |rep, sink| {
1766 if flags.json {
1767 json_files.push(report::TestFile::from_report(rep, sink.out().take()));
1768 }
1769 if flags.junit.is_some() {
1770 junit_suites.push(junit_suite(rep));
1771 }
1772 let f = htl::diagnostic::display_path(&rep.path);
1774 let tag = if rep.ok() { "ok " } else { "FAIL" };
1775 let detail = if !rep.check.ok() {
1776 "type check failed".to_string()
1777 } else if let Some(e) = &rep.error {
1778 format!("error: {}", e.lines().next().unwrap_or_default())
1781 } else if rep.file_level {
1782 "ran to completion (no test library used)".to_string()
1783 } else {
1784 format!("{} passed, {} failed", rep.passed, rep.failed)
1785 };
1786 let show_file = !flags.json && (!flags.quiet || !rep.ok());
1789 if show_file {
1790 eprintln!("{tag} {f} ({detail}, {:.0} ms)", rep.duration_ms);
1791 if let Some(e) = &rep.error {
1792 for line in e.lines().skip(1) {
1793 eprintln!(" {line}");
1794 }
1795 }
1796 }
1797 for tr in &rep.tests {
1798 let slow = flags.slow.is_some_and(|ms| tr.ms >= ms);
1799 if !flags.json && (flags.verbose || slow) {
1800 if flags.quiet && !show_file {
1801 eprintln!("slow {f} {} ({:.1} ms)", tr.name, tr.ms);
1803 continue;
1804 }
1805 let mark = if tr.ok { "ok " } else { "FAIL" };
1806 let note = if slow && !flags.verbose {
1807 " [slow]"
1808 } else {
1809 ""
1810 };
1811 eprintln!(" {mark} {} ({:.1} ms){note}", tr.name, tr.ms);
1812 }
1813 }
1814 if !flags.json {
1815 for m in &rep.failures {
1816 eprintln!(" - {m}");
1817 }
1818 for p in &rep.snapshots_written {
1820 eprintln!(
1821 "snapshot written: {}",
1822 htl::diagnostic::display_path(Path::new(p))
1823 );
1824 }
1825 for p in &rep.snapshots_updated {
1826 eprintln!(
1827 "snapshot updated: {}",
1828 htl::diagnostic::display_path(Path::new(p))
1829 );
1830 }
1831 }
1832 })?
1833 };
1834
1835 if let Some(out) = &flags.junit {
1836 std::fs::write(out, junit::document(&junit_suites, rep.duration_ms))
1839 .with_context(|| format!("writing {}", out.display()))?;
1840 }
1841 if let (Some(out), Some(cov)) = (&flags.lcov, &rep.coverage) {
1842 let root = match &cfg {
1845 Some((dir, _, _)) => dir.clone(),
1846 None => std::env::current_dir()?,
1847 };
1848 let root = std::fs::canonicalize(&root).unwrap_or(root);
1849 std::fs::write(out, cov.lcov(&root))
1850 .with_context(|| format!("writing {}", out.display()))?;
1851 }
1852 let ok = rep.ok() && (!empty || flags.allow_empty);
1855 if flags.json {
1856 let summary = report::TestSummary {
1857 files: rep.files.len(),
1858 files_run: rep.ran,
1859 passed: rep.passed,
1860 failed: rep.failed,
1861 files_with_errors: rep.files_with_errors,
1862 replayed: rep.replayed,
1863 duration_ms: rep.duration_ms,
1864 ok,
1865 seed: rep.seed,
1866 };
1867 report::emit(&report::TestReport {
1868 files: json_files,
1869 summary,
1870 coverage: rep.coverage,
1871 })?;
1872 } else if !empty || flags.allow_empty {
1873 if let Some(cov) = &rep.coverage {
1875 print_coverage(cov, flags.coverage_lines);
1876 if let Some(out) = &flags.lcov {
1877 eprintln!("coverage: lcov written to {}", out.display());
1878 }
1879 }
1880 eprintln!(
1881 "htl test: {} file(s), {} passed, {} failed, {} file(s) with errors{}{} ({:.0} ms)",
1882 rep.ran,
1883 rep.passed,
1884 rep.failed,
1885 rep.files_with_errors,
1886 if rep.skipped() > 0 {
1887 format!(", {} file(s) not run (--fail-fast)", rep.skipped())
1888 } else {
1889 String::new()
1890 },
1891 if rep.replayed > 0 {
1893 format!(", {} checked from cache", rep.replayed)
1894 } else {
1895 String::new()
1896 },
1897 rep.duration_ms
1898 );
1899 if !empty {
1903 eprintln!(
1904 "htl test: seed {} (repeat with --seed {})",
1905 rep.seed, rep.seed
1906 );
1907 }
1908 }
1909 Ok(if ok {
1910 ExitCode::SUCCESS
1911 } else {
1912 ExitCode::FAILURE
1913 })
1914}
1915
1916fn report_patched(paths: &[PathBuf]) {
1922 let roots: Vec<PathBuf> = paths
1923 .iter()
1924 .filter_map(|p| std::fs::canonicalize(p).ok())
1925 .collect();
1926 let cwd = std::env::current_dir().unwrap_or_default();
1927 let Some(project) = paths
1930 .first()
1931 .and_then(|p| htl::model::Project::find_root(p).ok().flatten())
1932 .map(|r| r.root)
1933 .filter(|r| r.join(htl::pkg::MANIFEST_NAME).is_file())
1934 .map(|r| htl::pkg::MluaProject::at(&r))
1935 else {
1936 return;
1937 };
1938 for p in &project.patches {
1939 let canon = std::fs::canonicalize(&p.dir).unwrap_or_else(|_| p.dir.clone());
1940 if !roots.iter().any(|r| canon.starts_with(r)) {
1941 continue;
1942 }
1943 let shown = p.dir.strip_prefix(&cwd).unwrap_or(&p.dir);
1944 eprintln!(" patched {} ({})", shown.display(), p.name);
1945 }
1946}
1947
1948fn load_config(first: &Path) -> Result<project::Config> {
1960 let cfg = project::config_of(first)?;
1961 if let Some((_, path, c)) = &cfg {
1962 htl::config::check_toolchain(c, path, env!("CARGO_PKG_VERSION"))?;
1963 }
1964 Ok(cfg)
1965}
1966
1967fn warn_cargo_htl_mismatch(first: &Path) {
1994 let Some(root) = htl::dts::find_cargo_package_root(first) else {
1995 return;
1996 };
1997 let Ok(text) = fs::read_to_string(root.join("Cargo.toml")) else {
1998 return;
1999 };
2000 let Ok(manifest) = text.parse::<toml::Table>() else {
2001 return;
2002 };
2003 let Some(dep) = manifest.get("dependencies").and_then(|d| d.get("htl")) else {
2004 return;
2005 };
2006 let req_text = match dep {
2007 toml::Value::String(s) => s.as_str(),
2008 toml::Value::Table(t) => match t.get("version").and_then(toml::Value::as_str) {
2009 Some(s) => s,
2010 None => return,
2011 },
2012 _ => return,
2013 };
2014 let running = env!("CARGO_PKG_VERSION");
2015 let (Ok(req), Ok(version)) = (
2016 semver::VersionReq::parse(req_text),
2017 semver::Version::parse(running),
2018 ) else {
2019 return;
2020 };
2021 if req.matches(&version) {
2022 return;
2023 }
2024 eprintln!(
2027 "htl {running}; Cargo.toml asks for htl {req_text} — the crate and the CLI are \
2028 meant to move together (cargo install htl-cli --version {req_text}, or bump the \
2029 dependency)"
2030 );
2031}
2032
2033fn cmd_fmt(paths: &[PathBuf], check: bool, indent: Option<usize>) -> Result<ExitCode> {
2034 let paths = if paths.is_empty() {
2035 vec![PathBuf::from(".")]
2036 } else {
2037 paths.to_vec()
2038 };
2039 let cfg = load_config(&paths[0])?;
2040 let indent = indent
2041 .or_else(|| cfg.as_ref().and_then(|(_, _, c)| c.fmt.indent))
2042 .unwrap_or(3);
2043 let h = Htl::new()?;
2044 config_lang(&h, &cfg)?;
2045 let model = project::model_of(&cfg, &paths[0])?;
2049 let skip = project::not_walked(model.as_ref(), &paths, htl::model::Purpose::Own);
2050 let files = htl::collect_tl_skipping(&paths, &skip)?;
2051 let (mut changed, mut failed) = (0usize, 0usize);
2052 for f in &files {
2053 let before = fs::read_to_string(f).with_context(|| format!("reading {}", f.display()))?;
2054 let after = match h.format_file(f, indent) {
2055 Ok(s) => s,
2056 Err(e) => {
2057 eprintln!("error: {e}");
2058 failed += 1;
2059 continue;
2060 }
2061 };
2062 if after != before {
2063 changed += 1;
2064 if check {
2065 eprintln!("would reformat: {}", f.display());
2066 } else {
2067 fs::write(f, after).with_context(|| format!("writing {}", f.display()))?;
2068 eprintln!("reformatted: {}", f.display());
2069 }
2070 }
2071 }
2072 eprintln!(
2073 "htl fmt: {} file(s), {} {}, {} failed",
2074 files.len(),
2075 changed,
2076 if check { "would change" } else { "reformatted" },
2077 failed
2078 );
2079 let fail = failed > 0 || (check && changed > 0);
2080 Ok(if fail {
2081 ExitCode::FAILURE
2082 } else {
2083 ExitCode::SUCCESS
2084 })
2085}
2086
2087struct FixFlags {
2088 rule: Vec<String>,
2089 unsafe_fixes: bool,
2090 dry_run: bool,
2091 diff: bool,
2092 allow_dirty: bool,
2093 allow_no_vcs: bool,
2094 exit_non_zero_on_fix: bool,
2095 json: bool,
2096}
2097
2098fn cmd_fix(paths: &[PathBuf], flags: FixFlags) -> Result<ExitCode> {
2099 use htl::fix::{FixOptions, fix_file, git_dirty, unified_diff};
2100 let paths = if paths.is_empty() {
2101 vec![PathBuf::from(".")]
2102 } else {
2103 paths.to_vec()
2104 };
2105 let cfg = load_config(&paths[0])?;
2106 auto_dts_to(&paths[0], !flags.dry_run)?;
2108 let model = project::model_of(&cfg, &paths[0])?;
2109 let scope = project::Scope::new(&cfg, model.as_ref(), &paths[0], None)?;
2112 let h = project::checker(
2113 model.as_ref(),
2114 scope.lints.selection(),
2115 &project::lang_of(&cfg),
2116 )?;
2117 let opts = FixOptions {
2118 unsafe_fixes: flags.unsafe_fixes,
2119 promoted: cfg
2120 .as_ref()
2121 .map(|(_, _, c)| c.fix.unsafe_.clone())
2122 .unwrap_or_default(),
2123 disabled: cfg
2124 .as_ref()
2125 .map(|(_, _, c)| c.fix.disable.clone())
2126 .unwrap_or_default(),
2127 only: flags.rule.clone(),
2128 dry_run: flags.dry_run,
2129 };
2130 opts.validate()?;
2133 let skip = project::not_walked(model.as_ref(), &paths, htl::model::Purpose::Own);
2137 let (files, outside) = project::held_by_modules(
2139 model.as_ref(),
2140 &paths,
2141 htl::collect_tl_skipping(&paths, &skip)?,
2142 )?;
2143 if let Some(note) = project::outside_modules_note(model.as_ref(), &outside, "fixed") {
2144 eprintln!("htl fix: {note}");
2145 }
2146 let check_skip = project::not_walked(model.as_ref(), &paths, htl::model::Purpose::Check);
2150 let checked_only: Vec<PathBuf> = project::held_by_modules(
2151 model.as_ref(),
2152 &paths,
2153 htl::collect_tl_skipping(&paths, &check_skip)?,
2154 )?
2155 .0
2156 .into_iter()
2157 .filter(|f| !files.contains(f))
2158 .collect();
2159
2160 if !flags.dry_run {
2162 let mut dirty = Vec::new();
2163 let mut no_vcs = Vec::new();
2164 for f in &files {
2165 match git_dirty(f)? {
2166 Some(true) => dirty.push(f.clone()),
2167 Some(false) => {}
2168 None => no_vcs.push(f.clone()),
2169 }
2170 }
2171 if !dirty.is_empty() && !flags.allow_dirty {
2172 bail!(
2173 "htl fix rewrites files in place and relies on git to undo it; these have uncommitted changes:\n {}\ncommit or stash them, or pass --allow-dirty",
2174 dirty
2175 .iter()
2176 .map(|p| p.display().to_string())
2177 .collect::<Vec<_>>()
2178 .join("\n ")
2179 );
2180 }
2181 if !no_vcs.is_empty() && !flags.allow_no_vcs {
2182 bail!(
2183 "htl fix rewrites files in place and relies on git to undo it; these are not in a git repository:\n {}\npass --allow-no-vcs to proceed without that safety net",
2184 no_vcs
2185 .iter()
2186 .map(|p| p.display().to_string())
2187 .collect::<Vec<_>>()
2188 .join("\n ")
2189 );
2190 }
2191 }
2192
2193 let mut sink = project::Sink::new(report::Out::new(flags.json));
2194 sink.judge_by(scope.lints.selection());
2196 let origins = project::Origins::new(model.as_ref());
2200 let walk = scope.walk(&cfg, model.as_ref(), &origins);
2201 let walked: Vec<PathBuf> = files.iter().chain(&checked_only).cloned().collect();
2202 sink.walking(&walked);
2203 let (mut applied, mut skipped, mut json_files) = (Vec::new(), Vec::new(), Vec::new());
2204 let (mut changed, mut deferred, mut reverted) = (0usize, 0usize, 0usize);
2205 let mut found = htl::verdict::Findings::default();
2206 let mut infos: Vec<(PathBuf, htl::CheckInfo)> = Vec::with_capacity(walked.len());
2207 for f in &files {
2208 let saved = h.search_path()?;
2211 project::file_view(&h, model.as_ref(), f)?;
2212 let before = if flags.diff {
2213 std::fs::read_to_string(f).ok()
2214 } else {
2215 None
2216 };
2217 let out = fix_file(&h, f, &opts)?;
2218 if out.contents.is_some() {
2219 changed += 1;
2220 }
2221 deferred += out.deferred;
2222 if out.reverted.is_some() {
2223 reverted += 1;
2224 }
2225 if !flags.json {
2226 for a in &out.applied {
2227 eprintln!(
2228 "fixed: {}:{}: {} ({}{})",
2229 project::display_path(f),
2230 a.line,
2231 a.rule,
2232 a.applicability.as_str(),
2233 if flags.dry_run { ", not written" } else { "" }
2234 );
2235 }
2236 for s in &out.skipped {
2237 eprintln!(
2238 "skipped: {}:{}: {} — {}",
2239 project::display_path(f),
2240 s.line,
2241 s.rule,
2242 s.reason
2243 );
2244 }
2245 if let Some(r) = &out.reverted {
2246 eprintln!("reverted: {}: {r}", project::display_path(f));
2247 }
2248 if let Some(o) = &out.oscillation {
2249 eprintln!(
2250 "stopped: {}: fixes of {o} undo each other",
2251 project::display_path(f)
2252 );
2253 }
2254 if out.deferred > 0 {
2255 eprintln!(
2256 "deferred: {}: {} edit(s) overlapped applied ones; run htl fix again",
2257 project::display_path(f),
2258 out.deferred
2259 );
2260 }
2261 if flags.diff
2262 && let (Some(b), Some(a)) = (&before, &out.contents)
2263 {
2264 print!("{}", unified_diff(&project::display_path(f), b, a));
2265 }
2266 if flags.diff
2269 && let (Some(b), Some(s)) = (
2270 out.contents.as_ref().or(before.as_ref()),
2271 out.suggested.as_ref(),
2272 )
2273 {
2274 print!(
2275 "{}",
2276 unified_diff(&format!("{} (suggested)", project::display_path(f)), b, s)
2277 );
2278 }
2279 }
2280 found.lints += project::file_findings(&h, &mut sink, f, &out.check, &walk)?;
2283 h.set_search_path(&saved)?;
2284 found.errors += out.check.errors.len();
2285 found.warnings += out.check.warnings.len();
2286 infos.push((f.clone(), out.check.clone()));
2287 if flags.json {
2288 applied.extend(out.applied.iter().map(|a| report::FixApplied {
2289 file: project::display_path(f),
2290 line: a.line,
2291 rule: a.rule.clone(),
2292 applicability: a.applicability.as_str(),
2293 pass: a.pass,
2294 }));
2295 skipped.extend(out.skipped.iter().map(|s| report::FixSkipped {
2296 file: project::display_path(f),
2297 line: s.line,
2298 rule: s.rule.clone(),
2299 reason: s.reason.clone(),
2300 }));
2301 json_files.push(report::FixFile {
2302 path: project::display_path(f),
2303 changed: out.contents.is_some(),
2304 deferred: out.deferred,
2305 reverted: out.reverted.clone(),
2306 oscillation: out.oscillation.clone(),
2307 diagnostics: sink.out().take(),
2308 });
2309 }
2310 }
2311 for f in &checked_only {
2313 let m = project::check_one(&h, &mut sink, f, &walk)?;
2314 found.errors += m.errors;
2315 found.warnings += m.warnings;
2316 found.lints += m.lints;
2317 infos.push((f.clone(), m.requires_only()));
2318 if flags.json {
2319 json_files.push(report::FixFile {
2320 path: project::display_path(f),
2321 changed: false,
2322 deferred: 0,
2323 reverted: None,
2324 oscillation: None,
2325 diagnostics: sink.out().take(),
2326 });
2327 }
2328 }
2329 let mut whole = scope.whole(&cfg, model.as_ref());
2332 whole.publish = !flags.dry_run;
2333 let w = project::project_findings(&mut sink, &whole, &infos);
2334 found.errors += w.errors;
2335 found.lints += w.lints;
2336 let project_diagnostics = if flags.json {
2337 sink.out().take()
2338 } else {
2339 Vec::new()
2340 };
2341 found.errors += sink.dependency_error_count();
2344 found.denied = sink.denied();
2345 let policy = htl::verdict::Policy::resolve(cfg.as_ref().map(|(_, _, c)| c), false);
2347 let errors_remaining = found.errors;
2348 let n_applied = if flags.json { applied.len() } else { 0 };
2349 let fail =
2350 htl::verdict::verdict(&found, &policy) || (flags.exit_non_zero_on_fix && changed > 0);
2351 if flags.json {
2352 let n_skipped = skipped.len();
2353 report::emit(&report::FixReport {
2354 dry_run: flags.dry_run,
2355 applied,
2356 skipped,
2357 files: json_files,
2358 summary: report::FixSummary {
2359 files: files.len(),
2360 files_changed: changed,
2361 applied: n_applied,
2362 skipped: n_skipped,
2363 deferred,
2364 reverted,
2365 errors_remaining,
2366 warnings: found.warnings,
2367 lints: found.lints,
2368 denied: found.denied,
2369 strict: policy.strict,
2370 ok: !fail,
2371 },
2372 diagnostics: project_diagnostics,
2373 })?;
2374 } else {
2375 let judged = judged(&found, &policy);
2379 eprintln!(
2380 "htl fix: {} file(s){}, {} changed{}, {} error(s) remaining{}{}",
2381 files.len(),
2382 if checked_only.is_empty() {
2383 String::new()
2384 } else {
2385 format!(" + {} checked in patched dependencies", checked_only.len())
2386 },
2387 changed,
2388 if flags.dry_run {
2389 " (dry run, nothing written)"
2390 } else {
2391 ""
2392 },
2393 errors_remaining,
2394 judged,
2395 if deferred > 0 {
2396 format!(", {deferred} deferred")
2397 } else {
2398 String::new()
2399 }
2400 );
2401 }
2402 Ok(if fail {
2403 ExitCode::FAILURE
2404 } else {
2405 ExitCode::SUCCESS
2406 })
2407}
2408
2409fn cmd_check(paths: &[PathBuf], lint: Option<&str>, flags: CheckFlags) -> Result<ExitCode> {
2421 let CheckFlags {
2422 list_lints,
2423 json,
2424 use_cache,
2425 cache_mode,
2426 explain,
2427 ..
2428 } = flags;
2429 let mut sink = project::Sink::new(report::Out::new(json));
2430 let paths = if paths.is_empty() {
2431 vec![PathBuf::from(".")]
2432 } else {
2433 paths.to_vec()
2434 };
2435 if let Some(rule) = flags.explain_rule.as_deref() {
2444 let Some(r) = htl::lint::explained(rule) else {
2445 eprintln!("unknown lint rule: {rule}");
2446 return Ok(ExitCode::from(2));
2447 };
2448 println!("{} (default: {})\n\n{}", r.name, r.default, r.explain);
2449 return Ok(ExitCode::SUCCESS);
2450 }
2451 if list_lints {
2452 let width = htl::lint::rule_names()
2457 .iter()
2458 .map(|r| r.len())
2459 .max()
2460 .unwrap_or(0);
2461 for (name, level) in htl::lint::rule_defaults() {
2462 println!("{name:width$} {level}");
2463 }
2464 return Ok(ExitCode::SUCCESS);
2468 }
2469 let cfg = load_config(&paths[0])?;
2471 warn_cargo_htl_mismatch(&paths[0]);
2472 let policy = htl::verdict::Policy::resolve(cfg.as_ref().map(|(_, _, c)| c), flags.strict);
2473 if let Some(first) = paths.first() {
2477 auto_dts(first)?;
2478 }
2479 let walk_model = project::model_of(&cfg, &paths[0])?;
2484 if walk_model.is_none()
2489 && let Some(dir) = paths.iter().find(|p| p.is_dir())
2490 {
2491 bail!(
2492 "no {} or {} in {} or any directory above it: a directory is checked as a \
2493 project. Run `htl init` there to make it one, or name the .tl files to check \
2494 each on its own",
2495 htl::config::CONFIG_NAME,
2496 htl::pkg::MANIFEST_NAME,
2497 fs::canonicalize(dir)
2500 .unwrap_or_else(|_| dir.clone())
2501 .display()
2502 );
2503 }
2504 let skip = project::not_walked(walk_model.as_ref(), &paths, htl::model::Purpose::Check);
2505 let (files, outside) = project::held_by_modules(
2506 walk_model.as_ref(),
2507 &paths,
2508 htl::collect_tl_skipping(&paths, &skip)?,
2509 )?;
2510 if let Some(note) = project::outside_modules_note(walk_model.as_ref(), &outside, "checked") {
2511 eprintln!("htl check: {note}");
2512 }
2513 if !json {
2514 report_patched(&paths);
2515 }
2516
2517 let rep = project::check(
2521 &mut sink,
2522 &files,
2523 &project::Options {
2524 paths: &paths,
2525 config: &cfg,
2526 model: walk_model.as_ref(),
2527 lint,
2528 cache: project::cache_options(use_cache, cache_mode, &cfg, explain),
2529 },
2530 )?;
2531 let fail = report_check(
2532 sink.out(),
2533 json,
2534 &rep,
2535 &policy,
2536 patched_files(walk_model.as_ref(), &rep.files),
2537 )?;
2538 Ok(if fail {
2539 ExitCode::FAILURE
2540 } else {
2541 ExitCode::SUCCESS
2542 })
2543}
2544
2545fn cmd_unused(paths: &[PathBuf], flags: UnusedFlags) -> Result<ExitCode> {
2552 let UnusedFlags {
2553 json,
2554 fail_on_unused,
2555 use_cache,
2556 explain,
2557 } = flags;
2558 let paths = if paths.is_empty() {
2559 vec![PathBuf::from(".")]
2560 } else {
2561 paths.to_vec()
2562 };
2563 let cfg = load_config(&paths[0])?;
2564 auto_dts(&paths[0])?;
2567 let model = project::model_of(&cfg, &paths[0])?;
2568 let rep = htl::unused::unused(&htl::unused::Options {
2569 paths: &paths,
2570 config: &cfg,
2571 model: model.as_ref(),
2572 cache: project::cache_options(use_cache, None, &cfg, explain),
2573 })?;
2574 let s = &rep.summary;
2575 if json {
2576 report::emit(&rep)?;
2577 } else if s.no_entry {
2578 eprintln!(
2579 "htl unused: nothing to start from, so nothing is reported. An entry is \
2580 main.tl in the source root ([layout] source) or beside the manifest, a test file, a module under a [[contract]] directory, or a name \
2581 in [build] extra / host"
2582 );
2583 } else {
2584 if s.check_errors > 0 {
2585 eprintln!(
2586 "htl unused: {} error(s) in the check this graph comes from — what those \
2587 files require is missing from it (htl check)",
2588 s.check_errors
2589 );
2590 }
2591 for m in &rep.modules {
2592 match &m.module {
2593 Some(n) => eprintln!("module: {} ({n})", m.path),
2594 None => eprintln!("module: {}", m.path),
2595 }
2596 }
2597 for d in &rep.dependencies {
2598 eprintln!("dependency: {}", d.name);
2599 }
2600 eprintln!(
2601 "htl unused: {}, {} [{} considered, {} reached, {}]",
2602 count(s.modules, "module", "modules"),
2603 count(s.dependencies, "dependency", "dependencies"),
2604 s.considered,
2605 s.reached,
2606 count(s.entries, "entry", "entries"),
2607 );
2608 }
2609 Ok(if fail_on_unused && !s.ok {
2610 ExitCode::FAILURE
2611 } else {
2612 ExitCode::SUCCESS
2613 })
2614}
2615
2616fn cmd_resolve(module: &str, path: Option<&Path>, json: bool) -> Result<ExitCode> {
2625 let start = path.unwrap_or(Path::new("."));
2626 let cfg = load_config(start)?;
2627 auto_dts(start)?;
2631 let h = Htl::new()?;
2632 h.install_std()?;
2635 let model = apply_model(&h, &cfg, start)?;
2636 let rep = htl::resolve::resolve(
2637 &h,
2638 module,
2639 cfg.as_ref().map(|(r, _, _)| r.as_path()),
2640 model.as_ref(),
2641 )?;
2642 if json {
2643 report::emit(&rep)?;
2644 } else {
2645 print_resolution(&rep);
2646 }
2647 Ok(if rep.summary.ok {
2648 ExitCode::SUCCESS
2649 } else {
2650 ExitCode::FAILURE
2651 })
2652}
2653
2654fn print_resolution(r: &htl::resolve::Resolution) {
2658 let ambiguous = r
2659 .candidates
2660 .iter()
2661 .any(|c| c.status == htl::resolve::Status::Ambiguous);
2662 let typed_by = r
2666 .read
2667 .as_ref()
2668 .map(|d| format!(", typed by {d}"))
2669 .unwrap_or_default();
2670 match (&r.read, &r.error, &r.provided_by) {
2671 (_, Some(e), _) => println!("htl resolve {}: error: {e}", r.module),
2672 (Some(read), None, Some(by)) if r.provider == Some(htl::model::Provider::Declared) => {
2676 println!(
2677 "htl resolve {}: {read}, provided by the environment ({by})",
2678 r.module
2679 )
2680 }
2681 (_, None, Some(by)) => {
2682 println!(
2683 "htl resolve {}: provided by the host ({by}){typed_by}",
2684 r.module
2685 )
2686 }
2687 (Some(read), None, None) => println!("htl resolve {}: {read}", r.module),
2688 (None, None, None) if ambiguous => println!(
2689 "htl resolve {}: more than one module implements it, and no order picks one",
2690 r.module
2691 ),
2692 (None, None, None) => println!(
2693 "htl resolve {}: nothing in the project or on the search path answers require(\"{}\")",
2694 r.module, r.module
2695 ),
2696 }
2697 if !r.candidates.is_empty() {
2698 let w = |f: fn(&htl::resolve::Candidate) -> usize, head: usize| {
2699 r.candidates.iter().map(f).max().unwrap_or(0).max(head)
2700 };
2701 let file = w(|c| c.path.len(), 4);
2702 let kind = w(|c| c.kind.as_str().len(), 4);
2703 let read_at = r
2704 .candidates
2705 .iter()
2706 .find(|c| c.status == htl::resolve::Status::Read)
2707 .map(|c| c.order);
2708 println!();
2709 println!(" order {:file$} {:kind$} status", "file", "kind");
2710 for c in &r.candidates {
2711 let status = match (c.status, c.shadowed_by, read_at) {
2712 (htl::resolve::Status::Shadowed, Some(by), _) => format!("shadowed by {by}"),
2713 (htl::resolve::Status::Runtime, _, Some(by)) => format!("runtime, typed by {by}"),
2715 (s, _, _) => s.as_str().to_string(),
2716 };
2717 let origin = match &c.origin {
2718 Some(o) => format!(" ({})", o.describe()),
2719 None => String::new(),
2720 };
2721 println!(
2722 " {:<5} {:file$} {:kind$} {status}{origin}",
2723 c.order,
2724 c.path,
2725 c.kind.as_str()
2726 );
2727 }
2728 }
2729 println!();
2730 match r.answered_by {
2731 htl::resolve::AnsweredBy::Model => println!(" answered by the project model"),
2732 htl::resolve::AnsweredBy::Path => {
2735 println!(" searched, in order: {}", r.searched.join(", "))
2736 }
2737 }
2738}
2739
2740fn count(n: usize, one: &str, many: &str) -> String {
2743 format!("{n} {}", if n == 1 { one } else { many })
2744}
2745
2746fn cmd_cache_clear(path: Option<&Path>) -> Result<ExitCode> {
2756 let root = cache_root(path)?;
2757 let dir = root.join(".htl").join("cache");
2758 if !dir.is_dir() {
2759 eprintln!("htl cache: nothing stored at {}", dir.display());
2760 return Ok(ExitCode::SUCCESS);
2761 }
2762 let n = fs::read_dir(&dir)
2763 .map(|rd| {
2764 rd.flatten()
2765 .filter(|e| e.path().extension().is_some_and(|x| x == "json"))
2766 .count()
2767 })
2768 .unwrap_or(0);
2769 fs::remove_dir_all(&dir).with_context(|| format!("removing {}", dir.display()))?;
2770 eprintln!(
2771 "htl cache: removed {n} {} from {}",
2772 if n == 1 { "entry" } else { "entries" },
2773 dir.display()
2774 );
2775 Ok(ExitCode::SUCCESS)
2776}
2777
2778fn cache_root(path: Option<&Path>) -> Result<PathBuf> {
2781 let start = path.unwrap_or(Path::new("."));
2782 let model = htl::model::Project::find_root(start)?.map(|r| r.root);
2783 Ok(model.unwrap_or_else(|| std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."))))
2784}
2785
2786fn cmd_cache_status(path: Option<&Path>, json: bool, list_entries: bool) -> Result<ExitCode> {
2792 let c = cache::describe(&cache_root(path)?);
2793 if json {
2794 report::emit(&c)?;
2795 return Ok(ExitCode::SUCCESS);
2796 }
2797
2798 if c.entries.is_empty() {
2799 println!("htl cache: empty ({})", c.dir);
2800 return Ok(ExitCode::SUCCESS);
2801 }
2802 let mut by_kind: std::collections::BTreeMap<&str, (usize, u64)> = Default::default();
2803 for e in &c.entries {
2804 let slot = by_kind.entry(e.kind.as_str()).or_default();
2805 slot.0 += 1;
2806 slot.1 += e.bytes;
2807 }
2808 println!(
2809 "htl cache: {} entries, {} at {}",
2810 c.entries.len(),
2811 human_bytes(c.bytes),
2812 c.dir
2813 );
2814 for (kind, (n, bytes)) in &by_kind {
2815 let what = match *kind {
2816 cache::CHECK => "checked modules",
2817 cache::GEN => "checked and generated test files (htl test)",
2818 cache::MODULE => "generated modules (htl test / build, include_bundle!)",
2819 cache::RUN => "whole runs",
2820 _ => "entries this build cannot read",
2821 };
2822 println!(" {n:>5} {what} ({})", human_bytes(*bytes));
2823 }
2824 if let (Some(min), Some(max)) = (
2825 c.entries.iter().map(|e| e.age_secs).min(),
2826 c.entries.iter().map(|e| e.age_secs).max(),
2827 ) {
2828 println!(
2829 " last used between {} and {} ago",
2830 human_age(min),
2831 human_age(max)
2832 );
2833 }
2834 if list_entries {
2835 println!();
2836 for e in &c.entries {
2837 println!(
2838 " {:<6} {:>8} {}",
2839 e.kind,
2840 human_bytes(e.bytes),
2841 e.subjects.join(", ")
2842 );
2843 }
2844 }
2845 Ok(ExitCode::SUCCESS)
2846}
2847
2848fn human_bytes(n: u64) -> String {
2849 if n >= 1 << 20 {
2850 format!("{:.1} MB", n as f64 / (1u64 << 20) as f64)
2851 } else if n >= 1 << 10 {
2852 format!("{:.0} KB", n as f64 / (1u64 << 10) as f64)
2853 } else {
2854 format!("{n} B")
2855 }
2856}
2857
2858fn human_age(secs: u64) -> String {
2859 match secs {
2860 s if s < 90 => format!("{s}s"),
2861 s if s < 5400 => format!("{}m", s / 60),
2862 s if s < 172_800 => format!("{}h", s / 3600),
2863 s => format!("{}d", s / 86_400),
2864 }
2865}
2866
2867fn patched_files(model: Option<&htl::model::Project>, files: &[PathBuf]) -> usize {
2873 let Some(model) = model else {
2874 return 0;
2875 };
2876 if !model
2877 .modules
2878 .iter()
2879 .any(|m| m.owner == htl::model::Owner::Patched)
2880 {
2881 return 0;
2882 }
2883 files
2884 .iter()
2885 .filter(|f| {
2886 model
2887 .home_of(f)
2888 .is_some_and(|m| m.owner == htl::model::Owner::Patched)
2889 })
2890 .count()
2891}
2892
2893fn report_check(
2902 out: &mut report::Out,
2903 json: bool,
2904 rep: &project::Report,
2905 policy: &htl::verdict::Policy,
2906 patched: usize,
2907) -> Result<bool> {
2908 let (files, replayed) = (rep.files.len(), rep.replayed);
2909 let (errors, warnings, lints) = (rep.errors, rep.warnings, rep.lints);
2910 let strict = policy.strict;
2911 let fail = htl::verdict::verdict(&rep.findings(), policy);
2912 let all_cached = rep.all_cached();
2913 if json {
2914 report::emit(&report::CheckReport {
2915 files,
2916 patched,
2917 diagnostics: out.take(),
2918 summary: report::CheckSummary {
2919 errors,
2920 warnings,
2921 lints,
2922 denied: rep.denied,
2923 strict,
2924 ok: !fail,
2925 cached: all_cached,
2926 replayed,
2927 },
2928 })?;
2929 } else {
2930 let cached = if all_cached {
2932 " [cached]".to_string()
2933 } else if replayed > 0 {
2934 format!(" [{replayed}/{files} cached]")
2935 } else {
2936 String::new()
2937 };
2938 let denied = match rep.denied {
2943 0 => String::new(),
2944 n => format!(", {n} at deny"),
2945 };
2946 let counted = match patched {
2950 0 => format!("{files} file(s)"),
2951 n => format!("{} file(s) + {n} in patched dependencies", files - n),
2952 };
2953 for rule in out.rules_said() {
2958 if htl::lint::explained(rule).is_some() {
2959 eprintln!("htl check --explain {rule}");
2960 }
2961 }
2962 eprintln!(
2963 "htl check: {counted}, {errors} error(s), {warnings} warning(s), {lints} lint(s){denied}{}{cached}",
2964 if strict { " [strict]" } else { "" }
2965 );
2966 }
2967 Ok(fail)
2968}
2969
2970fn cmd_gen(file: &Path, out: Option<&Path>) -> Result<ExitCode> {
2971 let h = Htl::new()?;
2972 auto_dts(file)?;
2973 let cfg = load_config(file)?;
2977 config_lints(&h, &cfg)?;
2978 config_lang(&h, &cfg)?;
2979 let model = apply_model(&h, &cfg, file)?;
2980 project::file_view(&h, model.as_ref(), file)?;
2981 h.install_std()?;
2982 let (code, c) = h.gen_lua(file)?;
2983 text_sink().checkinfo(&c);
2984 let (Some(code), false) = (code, runs_fail(&c)) else {
2987 return Ok(ExitCode::FAILURE);
2988 };
2989 match out {
2993 Some(p) => fs::write(p, code).with_context(|| format!("writing {}", p.display()))?,
2994 None => print!("{code}"),
2995 }
2996 Ok(ExitCode::SUCCESS)
2997}
2998
2999fn cmd_run(file: &Path, args: &[String]) -> Result<ExitCode> {
3000 let bytes = fs::read(file).with_context(|| format!("reading {}", file.display()))?;
3001 let h = Htl::new()?;
3002 auto_dts(file)?;
3003 let cfg = load_config(file)?;
3008 config_lints(&h, &cfg)?;
3009 config_lang(&h, &cfg)?;
3010 h.configure_async(async_config(&cfg))?;
3011 let model = apply_model(&h, &cfg, file)?;
3012 h.install_test_lib()?;
3013 h.install_std()?;
3014 h.install_task_lib()?;
3015 if Bundle::is_bundle(&bytes) {
3016 let b = Bundle::decode(&bytes)?;
3017 let main = h.load_bundle(&b, args)?;
3020 return run_root(&h, Entry::Main(main), args);
3021 }
3022 project::file_view(&h, model.as_ref(), file)?;
3024 h.install_searcher()?;
3025 h.set_arg(&file.to_string_lossy(), args)?;
3026 let (code, c) = h.gen_lua(file)?;
3027 text_sink().checkinfo(&c);
3028 let (Some(code), false) = (code, runs_fail(&c)) else {
3030 return Ok(ExitCode::FAILURE);
3031 };
3032 run_root(
3033 &h,
3034 Entry::Chunk {
3035 code,
3036 name: format!("@{}", file.display()),
3037 },
3038 args,
3039 )
3040}
3041
3042enum Entry {
3044 Chunk { code: String, name: String },
3045 Main(htl::mlua::Function),
3046}
3047
3048fn async_config(cfg: &project::Config) -> &htl::config::AsyncConfig {
3050 static DEFAULT: htl::config::AsyncConfig = htl::config::AsyncConfig {
3051 grace_ms: None,
3052 preempt: None,
3053 };
3054 match cfg {
3055 Some((_, _, c)) => &c.async_,
3056 None => &DEFAULT,
3057 }
3058}
3059
3060fn run_root(h: &Htl, entry: Entry, args: &[String]) -> Result<ExitCode> {
3077 let token = htl::mlua_isle::runtime::CancelToken::new();
3078 {
3079 let token = token.clone();
3080 std::thread::Builder::new()
3081 .name("htl-ctrl-c".into())
3082 .spawn(move || {
3083 let Ok(rt) = tokio::runtime::Builder::new_current_thread()
3084 .enable_all()
3085 .build()
3086 else {
3087 return;
3088 };
3089 rt.block_on(async {
3090 if tokio::signal::ctrl_c().await.is_ok() {
3091 token.cancel();
3092 }
3093 if tokio::signal::ctrl_c().await.is_ok() {
3094 std::process::exit(130);
3095 }
3096 });
3097 })
3098 .context("starting the Ctrl-C watcher")?;
3099 }
3100 let rt = tokio::runtime::Builder::new_current_thread()
3101 .enable_all()
3102 .build()
3103 .context("building the executor's runtime")?;
3104 let local = tokio::task::LocalSet::new();
3105 let out = local.block_on(&rt, async {
3106 match entry {
3107 Entry::Chunk { code, name } => h.run_async(&code, &name, args, &token).await,
3108 Entry::Main(main) => {
3109 let va: htl::mlua::Variadic<String> = args.iter().cloned().collect();
3110 h.call_async(main, va, &token).await.map(|_| ())
3111 }
3112 }
3113 });
3114 Ok(match out {
3115 Ok(()) => ExitCode::SUCCESS,
3116 Err(e) if htl::is_cancelled(&e) => {
3117 eprintln!("htl run: interrupted");
3118 ExitCode::from(130)
3119 }
3120 Err(e) => {
3121 eprintln!("{}", htl::developer_message(&e));
3122 ExitCode::FAILURE
3123 }
3124 })
3125}
3126
3127fn runs_fail(c: &htl::CheckInfo) -> bool {
3131 htl::verdict::verdict(
3132 &htl::verdict::Findings {
3133 errors: c.errors.len(),
3134 warnings: c.warnings.len(),
3135 lints: c.lints.len(),
3136 denied: 0,
3137 },
3138 &htl::verdict::Policy::ERRORS_ONLY,
3139 )
3140}
3141
3142struct BuildCache {
3147 use_cache: bool,
3148 explain: bool,
3149}
3150
3151fn cmd_build(
3152 entry: &Path,
3153 out: &Path,
3154 main: &str,
3155 mut opts: htl::link::LinkOptions,
3156 cache_flags: BuildCache,
3157) -> Result<ExitCode> {
3158 let h = Htl::new()?;
3159 auto_dts(entry)?;
3160 h.install_std()?;
3164 let cfg = load_config(entry)?;
3165 let lints = config_lints(&h, &cfg)?;
3168 config_lang(&h, &cfg)?;
3169 let policy = htl::verdict::Policy::resolve(cfg.as_ref().map(|(_, _, c)| c), false);
3170 let model = apply_model(&h, &cfg, entry)?;
3171 if let Some(m) = &model {
3175 opts.host.extend(m.provided().map(|(n, _)| n.to_string()));
3176 }
3177 if let Some((_, _, cfg)) = &cfg {
3178 opts.extra.extend(cfg.build.extra.iter().cloned());
3179 opts.host.extend(cfg.build.host.iter().cloned());
3180 if let Some(t) = cfg.build.target.filter(|t| *t != BuildTarget::Hb) {
3186 eprintln!(
3187 "htl build: this project's target is `{}` — what runs its output is {} — and `htl build` writes a `.hb` bundle, which is the `hb` target. Build it with `cargo build`; to bundle its scripts anyway, drop `[build] target` from htl.toml.",
3188 t.name(),
3189 t.runs_it()
3190 );
3191 return Ok(ExitCode::FAILURE);
3192 }
3193 }
3194 if entry.is_dir() {
3195 if cache_flags.explain {
3196 eprintln!("htl cache: the directory form of `htl build` is not cached");
3197 }
3198 let skip = project::not_walked(
3201 model.as_ref(),
3202 &[entry.to_path_buf()],
3203 htl::model::Purpose::Check,
3204 );
3205 return cmd_build_dir(&h, entry, out, main, &opts, &skip, &cfg);
3206 }
3207 project::file_view(&h, model.as_ref(), entry)?;
3208 opts.entry_name = model.as_ref().and_then(|m| m.locate(entry).map(|p| p.name));
3211 let root = project::store_root(model.as_ref());
3217 let spec = cfg
3218 .as_ref()
3219 .map(|(_, _, c)| c.lint_spec())
3220 .unwrap_or_default();
3221 let lint = (!spec.is_empty()).then_some(spec.as_str());
3222 let cache_opts = project::cache_options(
3223 cache_flags.use_cache,
3224 Some(cache::Mode::PerModule),
3225 &cfg,
3226 cache_flags.explain,
3227 );
3228 let store = project::with_model(
3229 project::store(&root, cache_opts, None, "htl build"),
3230 model.as_ref(),
3231 );
3232 let link_store = store.as_ref().map(|c| htl::link::LinkStore {
3233 cache: c,
3234 lint,
3235 root: &root,
3236 config: cfg.as_ref().map(|(_, p, c)| (p.as_path(), c)),
3237 });
3238 let linked = htl::link::link_with(&h, entry, &opts, link_store)?;
3239 project::explain_cache(store.as_ref(), cache_opts);
3240 let mut sink = text_sink();
3243 sink.judge_by(lints.selection());
3244 for (p, c) in &linked.checks {
3245 sink.checkinfo(&linked.reported(p, c));
3246 }
3247 let n_err = linked.errors.len();
3248 let found = htl::verdict::Findings {
3249 errors: n_err,
3250 warnings: linked.checks.iter().map(|(_, c)| c.warnings.len()).sum(),
3251 lints: linked.lints.len(),
3252 denied: sink.denied(),
3253 };
3254 for d in &linked.link_errors {
3257 sink.diagnostic(d);
3258 }
3259 if htl::verdict::verdict(&found, &policy) {
3260 eprintln!(
3261 "htl build: {n_err} error(s){}, bundle not written",
3262 judged(&found, &policy)
3263 );
3264 return Ok(ExitCode::FAILURE);
3265 }
3266 let buf = linked.bundle()?.encode();
3267 fs::write(out, &buf).with_context(|| format!("writing {}", out.display()))?;
3268 let typed = linked.modules.iter().filter(|m| m.typed).count();
3269 let cached = if typed > 0 && linked.cached == typed {
3272 " [cached]".to_string()
3273 } else if linked.cached > 0 {
3274 format!(" [{}/{typed} cached]", linked.cached)
3275 } else {
3276 String::new()
3277 };
3278 eprintln!(
3279 "htl build: {} module(s) ({typed} typed, {} lua) -> {} ({} bytes{}{}){cached}",
3280 linked.modules.len(),
3281 linked.modules.len() - typed,
3282 out.display(),
3283 buf.len(),
3284 if opts.source {
3285 ", source"
3286 } else {
3287 ", bytecode"
3288 },
3289 if opts.debug { " with debug info" } else { "" }
3290 );
3291 if !linked.host_modules.is_empty() {
3292 eprintln!(
3293 "htl build: host must provide: {}",
3294 linked.host_modules.join(", ")
3295 );
3296 }
3297 Ok(ExitCode::SUCCESS)
3298}
3299
3300fn cmd_build_dir(
3302 h: &Htl,
3303 dir: &Path,
3304 out: &Path,
3305 entry: &str,
3306 opts: &htl::link::LinkOptions,
3307 skip: &[PathBuf],
3308 cfg: &project::Config,
3309) -> Result<ExitCode> {
3310 let lints = config_lints(h, cfg)?;
3312 config_lang(h, cfg)?;
3313 let policy = &htl::verdict::Policy::resolve(cfg.as_ref().map(|(_, _, c)| c), false);
3314 h.add_path(dir)?;
3315 let files = htl::collect_tl_skipping(&[dir.to_path_buf()], skip)?;
3316 let mut b = Bundle {
3317 entry: entry.to_string(),
3318 htl_version: env!("CARGO_PKG_VERSION").into(),
3319 ..Default::default()
3320 };
3321 let mut found = htl::verdict::Findings::default();
3322 let mut sink = text_sink();
3323 sink.judge_by(lints.selection());
3324 for f in &files {
3325 let rel = f.strip_prefix(dir).unwrap_or(f);
3327 let name = htl::naming::name_of("", rel)
3328 .with_context(|| format!("cannot derive a module name for {}", f.display()))?;
3329 let (code, c) = h.gen_lua(f)?;
3330 sink.checkinfo(&c);
3331 found.errors += c.errors.len();
3332 found.warnings += c.warnings.len();
3333 found.lints += c.lints.len();
3334 let Some(code) = code else { continue };
3335 let (kind, payload) = if opts.source {
3336 (htl::bundle::Kind::Source, code.into_bytes())
3337 } else {
3338 (
3339 htl::bundle::Kind::Bytecode,
3340 h.compile_with(&name, &code, !opts.debug)?,
3341 )
3342 };
3343 b.modules.push(htl::bundle::Module {
3344 name,
3345 kind,
3346 payload,
3347 });
3348 }
3349 found.denied = sink.denied();
3350 if htl::verdict::verdict(&found, policy) {
3351 eprintln!(
3352 "htl build: {} error(s){}, bundle not written",
3353 found.errors,
3354 judged(&found, policy)
3355 );
3356 return Ok(ExitCode::FAILURE);
3357 }
3358 if b.module(entry).is_none() {
3359 bail!(
3360 "entry module '{entry}' not found among {} module(s)",
3361 b.modules.len()
3362 );
3363 }
3364 if !opts.source {
3365 b.fingerprint = h.fingerprint()?;
3366 }
3367 let buf = b.encode();
3368 fs::write(out, &buf).with_context(|| format!("writing {}", out.display()))?;
3369 eprintln!(
3370 "htl build: {} module(s) -> {} ({} bytes)",
3371 b.modules.len(),
3372 out.display(),
3373 buf.len()
3374 );
3375 Ok(ExitCode::SUCCESS)
3376}
3377
3378#[derive(serde::Serialize)]
3385struct BundleInfo {
3386 file: String,
3387 format: u8,
3388 htl_version: Option<String>,
3389 payload: &'static str,
3391 lua: Option<htl::bundle::LuaHeader>,
3392 entry: String,
3393 modules: Vec<BundleModuleInfo>,
3394 host_modules: Vec<String>,
3395}
3396
3397#[derive(serde::Serialize)]
3398struct BundleModuleInfo {
3399 name: String,
3400 kind: &'static str,
3401 bytes: usize,
3402}
3403
3404fn cmd_bundle_info(file: &Path, json: bool) -> Result<ExitCode> {
3405 let bytes = fs::read(file).with_context(|| format!("reading {}", file.display()))?;
3406 let Some(format) = htl::bundle::format_version(&bytes) else {
3407 bail!("{} is not an htl bundle (bad magic)", file.display());
3408 };
3409 let b = Bundle::decode(&bytes)?;
3410 let kind_name = |k: htl::bundle::Kind| match k {
3411 htl::bundle::Kind::Bytecode => "bytecode",
3412 htl::bundle::Kind::Source => "source",
3413 };
3414 let payload = match (
3415 b.modules
3416 .iter()
3417 .any(|m| m.kind == htl::bundle::Kind::Bytecode),
3418 b.modules
3419 .iter()
3420 .any(|m| m.kind == htl::bundle::Kind::Source),
3421 ) {
3422 (true, true) => "mixed",
3423 (false, true) => "source",
3424 _ => "bytecode",
3426 };
3427 let info = BundleInfo {
3428 file: file.display().to_string(),
3429 format,
3430 htl_version: (!b.htl_version.is_empty()).then(|| b.htl_version.clone()),
3431 payload,
3432 lua: htl::bundle::LuaHeader::parse(&b.fingerprint),
3433 entry: b.entry.clone(),
3434 modules: b
3435 .modules
3436 .iter()
3437 .map(|m| BundleModuleInfo {
3438 name: m.name.clone(),
3439 kind: kind_name(m.kind),
3440 bytes: m.payload.len(),
3441 })
3442 .collect(),
3443 host_modules: b.host_modules.clone(),
3444 };
3445 if json {
3446 report::emit(&info)?;
3447 return Ok(ExitCode::SUCCESS);
3448 }
3449
3450 println!(
3451 "{}: htl bundle, format {}, built by {}",
3452 info.file,
3453 info.format,
3454 match &info.htl_version {
3455 Some(v) => format!("htl {v}"),
3456 None => "htl (version not recorded)".to_string(),
3457 }
3458 );
3459 println!(" payload: {}", info.payload);
3460 let lua = match &info.lua {
3461 Some(h) => h.to_string(),
3462 None if !b.fingerprint.is_empty() => {
3463 format!("unreadable fingerprint ({} bytes)", b.fingerprint.len())
3464 }
3465 None if info.format == 1 => {
3466 "not recorded (a format 1 bundle carries no fingerprint)".into()
3467 }
3468 None => "any (source payload, no bytecode to bind)".into(),
3469 };
3470 println!(" lua: {lua}");
3471 println!(" entry: {}", info.entry);
3472 let modules: Vec<String> = info
3473 .modules
3474 .iter()
3475 .map(|m| {
3476 if info.payload == "mixed" {
3477 format!("{} ({})", m.name, m.kind)
3478 } else {
3479 m.name.clone()
3480 }
3481 })
3482 .collect();
3483 println!(
3484 " modules: {}",
3485 if modules.is_empty() {
3486 "(none)".to_string()
3487 } else {
3488 modules.join(", ")
3489 }
3490 );
3491 println!(
3492 " host: {}",
3493 if info.host_modules.is_empty() {
3494 "(none)".to_string()
3495 } else {
3496 info.host_modules.join(", ")
3497 }
3498 );
3499 Ok(ExitCode::SUCCESS)
3500}