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(short, long)]
273 verbose: bool,
274 #[arg(short, long, conflicts_with = "verbose")]
276 quiet: bool,
277 #[arg(long, value_name = "MS")]
279 slow: Option<f64>,
280 #[arg(long)]
282 update: bool,
283 #[arg(long)]
285 coverage: bool,
286 #[arg(long, requires = "coverage")]
288 coverage_lines: bool,
289 #[arg(long, value_name = "FILE")]
291 lcov: Option<PathBuf>,
292 #[arg(long, value_name = "FILE")]
294 junit: Option<PathBuf>,
295 #[arg(long)]
297 seed: Option<u64>,
298 #[arg(long, value_enum, default_value_t = Format::Text)]
300 format: Format,
301 #[arg(long)]
303 no_cache: bool,
304 #[arg(long)]
306 explain_cache: bool,
307 },
308 #[command(after_long_help = "\
321Examples:
322 htl fix src apply the safe fixes to every .tl under src/
323 htl fix src --diff --dry-run what would change, as a unified diff per file
324 htl fix src --rule forward-ref only that rule's fixes
325 htl fix src --unsafe also the fixes that may change what the program does
326")]
327 Fix {
328 paths: Vec<PathBuf>,
329 #[arg(long, value_delimiter = ',')]
332 rule: Vec<String>,
333 #[arg(long = "unsafe")]
335 unsafe_fixes: bool,
336 #[arg(long)]
338 dry_run: bool,
339 #[arg(long)]
341 diff: bool,
342 #[arg(long)]
344 allow_dirty: bool,
345 #[arg(long)]
347 allow_no_vcs: bool,
348 #[arg(long)]
350 exit_non_zero_on_fix: bool,
351 #[arg(long, value_enum, default_value_t = Format::Text)]
353 format: Format,
354 },
355 Dts {
370 dir: Option<PathBuf>,
372 },
373 #[command(after_long_help = "\
377Examples:
378 htl new hello src/main.tl, a module, tests/, mlua-pkg.toml
379 htl new hello --lib a library: no entry script
380 htl new hello --embed the same, plus a Rust host (--target bin)
381 htl new hello --target cdylib --lib
382 a library behind a C ABI, for a caller that is not Rust
383 htl new hello --embed --htl main
384 built against the unreleased htl (a git pin on main)
385 htl new hello --embed --htl path:../htl
386 built against a local checkout of this repository
387 htl new hello --no-x without the htlx dependency the manifest gets by default
388
389Build targets: https://docs.rs/htl/latest/htl/build_target/enum.BuildTarget.html
390Layout of a project: https://github.com/ynishi/htl#layout-of-a-project-htl-new
391")]
392 New {
393 name: String,
394 #[arg(long)]
396 lib: bool,
397 #[arg(long)]
399 embed: bool,
400 #[arg(long, value_name = "NAME", value_parser = clap::builder::PossibleValuesParser::new(scaffold::target_names()))]
404 target: Option<String>,
405 #[arg(long, value_name = "REQ")]
409 htl: Option<String>,
410 #[arg(long)]
412 no_x: bool,
413 },
414 Init {
416 dir: Option<PathBuf>,
417 #[arg(long)]
418 lib: bool,
419 #[arg(long)]
421 embed: bool,
422 #[arg(long, value_name = "NAME", value_parser = clap::builder::PossibleValuesParser::new(scaffold::target_names()))]
424 target: Option<String>,
425 #[arg(long, value_name = "REQ")]
429 htl: Option<String>,
430 #[arg(long)]
432 no_x: bool,
433 },
434 Pkg {
437 #[command(subcommand)]
438 cmd: PkgCmd,
439 },
440 Types {
442 #[command(subcommand)]
443 cmd: TypesCmd,
444 },
445 Cache {
449 #[command(subcommand)]
450 cmd: CacheCmd,
451 },
452 Fmt {
454 paths: Vec<PathBuf>,
455 #[arg(long)]
457 check: bool,
458 #[arg(long)]
460 indent: Option<usize>,
461 },
462 Gen {
464 file: PathBuf,
465 #[arg(short, long)]
466 out: Option<PathBuf>,
467 },
468 Run {
470 file: PathBuf,
471 #[arg(trailing_var_arg = true)]
472 args: Vec<String>,
473 },
474 #[command(after_long_help = "\
481Examples:
482 htl build src/main.tl -o app.hb
483 the entry's require closure, as one bundle
484 htl build src/main.tl -o app.hb --debug
485 keep line numbers and local names in the bytecode
486 htl build src/main.tl -o app.hb --host mymod
487 leave a module the host provides out of the bundle
488 htl run app.hb run what was built
489
490Caching: https://github.com/ynishi/htl#caching
491")]
492 Build {
499 entry: PathBuf,
503 #[arg(short, long, default_value = "app.hb")]
504 out: PathBuf,
505 #[arg(short, long, default_value = "main")]
507 main: String,
508 #[arg(long)]
510 debug: bool,
511 #[arg(long)]
514 source: bool,
515 #[arg(long, value_delimiter = ',')]
517 extra: Vec<String>,
518 #[arg(long, value_delimiter = ',')]
520 host: Vec<String>,
521 #[arg(long)]
524 no_cache: bool,
525 #[arg(long)]
527 explain_cache: bool,
528 },
529 #[command(after_long_help = "\
534Examples:
535 htl unused modules and dependencies no entry reaches
536 htl unused --exit-non-zero-on-unused
537 the same report, and a non-zero exit for a CI
538 htl unused --format json the same report as one JSON document
539")]
540 Unused {
541 paths: Vec<PathBuf>,
544 #[arg(long, value_enum, default_value_t = Format::Text)]
546 format: Format,
547 #[arg(long)]
549 exit_non_zero_on_unused: bool,
550 #[arg(long)]
553 no_cache: bool,
554 #[arg(long)]
556 explain_cache: bool,
557 },
558 #[command(after_long_help = "\
565Examples:
566 htl resolve mq the chain for require(\"mq\")
567 htl resolve socket.http a name with dots, as a require spells it
568 htl resolve mq --format json the same rows as one JSON document
569
570Exits 1 when the name resolves to nothing, when two files implement it, or when a file of
571the project implements a name the host provides, so a script can ask.
572
573`htl.test` is answered like a host-provided name: no file of the project implements it
574(`htl test` preloads it into the state it runs), and its one row is the declaration the
575binary carries, `provided by the environment`.
576")]
577 Resolve {
578 module: String,
580 path: Option<PathBuf>,
582 #[arg(long, value_enum, default_value_t = Format::Text)]
584 format: Format,
585 },
586 Bundle {
590 #[command(subcommand)]
591 cmd: BundleCmd,
592 },
593}
594
595pub fn command() -> clap::Command {
601 <Cli as clap::CommandFactory>::command()
602}
603
604pub fn run() -> ExitCode {
612 let mut argv: Vec<String> = std::env::args().collect();
614 let is_cargo = Path::new(&argv[0])
615 .file_stem()
616 .and_then(|s| s.to_str())
617 .map(|s| s == "cargo-htl")
618 .unwrap_or(false);
619 if is_cargo && argv.get(1).map(String::as_str) == Some("htl") {
620 argv.remove(1);
621 }
622 match real_main(Cli::parse_from(argv)) {
623 Ok(code) => code,
624 Err(e) => {
625 eprintln!("htl: {e:#}");
626 ExitCode::from(2)
627 }
628 }
629}
630
631fn real_main(cli: Cli) -> Result<ExitCode> {
632 match cli.cmd {
633 Cmd::Check {
634 paths,
635 strict,
636 lint,
637 list_lints,
638 explain,
639 format,
640 no_cache,
641 cache_mode,
642 explain_cache,
643 } => cmd_check(
644 &paths,
645 lint.as_deref(),
646 CheckFlags {
647 strict,
648 list_lints,
649 explain_rule: explain,
650 json: format == Format::Json,
651 use_cache: !no_cache,
652 cache_mode: cache_mode.map(Into::into),
653 explain: explain_cache,
654 },
655 ),
656 Cmd::Fmt {
657 paths,
658 check,
659 indent,
660 } => cmd_fmt(&paths, check, indent),
661 Cmd::Test {
662 paths,
663 filter,
664 lib,
665 lint,
666 fail_fast,
667 verbose,
668 quiet,
669 slow,
670 update,
671 coverage,
672 coverage_lines,
673 lcov,
674 junit,
675 seed,
676 format,
677 no_cache,
678 explain_cache,
679 } => cmd_test(
680 &paths,
681 filter.as_deref(),
682 &lib,
683 lint.as_deref(),
684 TestFlags {
685 fail_fast,
686 verbose,
687 quiet,
688 slow,
689 update,
690 coverage: coverage || lcov.is_some(),
691 coverage_lines,
692 lcov,
693 junit,
694 json: format == Format::Json,
695 no_cache,
696 explain: explain_cache,
697 seed,
698 },
699 ),
700 Cmd::Pkg { cmd } => match cmd {
701 PkgCmd::Install => cmd_pkg_install(),
702 PkgCmd::Add {
703 name,
704 git,
705 tag,
706 rev,
707 branch,
708 entry,
709 target_dir,
710 } => cmd_pkg_add(htl::pkg::mlua_pkg::ops::AddSpec {
711 name,
712 git,
713 tag,
714 rev,
715 branch,
716 entry,
717 target_dir,
718 }),
719 PkgCmd::Update {
720 name,
721 dry_run,
722 force,
723 } => cmd_pkg_update(htl::pkg::mlua_pkg::ops::UpdateOpts {
724 name,
725 dry_run,
726 force,
727 }),
728 PkgCmd::Clean { all } => cmd_pkg_clean(all),
729 PkgCmd::Patch { dep, force } => cmd_pkg_patch(&dep, force),
730 },
731 Cmd::Types { cmd } => match cmd {
732 TypesCmd::Add {
733 library,
734 from,
735 force,
736 } => cmd_types_add(&library, from.as_deref(), force),
737 },
738 Cmd::Cache { cmd } => match cmd {
739 CacheCmd::Clear { path } => cmd_cache_clear(path.as_deref()),
740 CacheCmd::Status {
741 path,
742 format,
743 entries,
744 } => cmd_cache_status(path.as_deref(), format == Format::Json, entries),
745 },
746 Cmd::Dts { dir } => cmd_dts(dir.as_deref()),
747 Cmd::New {
748 name,
749 lib,
750 embed,
751 target,
752 htl,
753 no_x,
754 } => cmd_new(&name, lib, embed, target.as_deref(), htl.as_deref(), no_x),
755 Cmd::Init {
756 dir,
757 lib,
758 embed,
759 target,
760 htl,
761 no_x,
762 } => cmd_init(
763 dir.as_deref(),
764 lib,
765 embed,
766 target.as_deref(),
767 htl.as_deref(),
768 no_x,
769 ),
770 Cmd::Gen { file, out } => cmd_gen(&file, out.as_deref()),
771 Cmd::Run { file, args } => cmd_run(&file, &args),
772 Cmd::Fix {
773 paths,
774 rule,
775 unsafe_fixes,
776 dry_run,
777 diff,
778 allow_dirty,
779 allow_no_vcs,
780 exit_non_zero_on_fix,
781 format,
782 } => cmd_fix(
783 &paths,
784 FixFlags {
785 rule,
786 unsafe_fixes,
787 dry_run: dry_run || diff,
788 diff,
789 allow_dirty,
790 allow_no_vcs,
791 exit_non_zero_on_fix,
792 json: format == Format::Json,
793 },
794 ),
795 Cmd::Build {
796 entry,
797 out,
798 main,
799 debug,
800 source,
801 extra,
802 host,
803 no_cache,
804 explain_cache,
805 } => cmd_build(
806 &entry,
807 &out,
808 &main,
809 htl::link::LinkOptions {
810 debug,
811 source,
812 extra,
813 host,
814 entry_name: None,
815 },
816 BuildCache {
817 use_cache: !no_cache,
818 explain: explain_cache,
819 },
820 ),
821 Cmd::Unused {
822 paths,
823 format,
824 exit_non_zero_on_unused,
825 no_cache,
826 explain_cache,
827 } => cmd_unused(
828 &paths,
829 UnusedFlags {
830 json: format == Format::Json,
831 fail_on_unused: exit_non_zero_on_unused,
832 use_cache: !no_cache,
833 explain: explain_cache,
834 },
835 ),
836 Cmd::Resolve {
837 module,
838 path,
839 format,
840 } => cmd_resolve(&module, path.as_deref(), format == Format::Json),
841 Cmd::Bundle { cmd } => match cmd {
842 BundleCmd::Info { file, format } => cmd_bundle_info(&file, format == Format::Json),
843 },
844 }
845}
846
847fn text_sink() -> project::Sink<report::Out> {
858 project::Sink::new(report::Out::new(false))
859}
860
861fn judged(found: &htl::verdict::Findings, policy: &htl::verdict::Policy) -> String {
865 let mut out = String::new();
866 if policy.capped {
867 return out;
868 }
869 if found.denied > 0 {
870 out.push_str(&format!(", {} at deny", found.denied));
871 }
872 if policy.strict && found.warnings + found.lints > 0 {
873 out.push_str(&format!(
874 ", {} warning(s) and {} lint(s) under strict",
875 found.warnings, found.lints
876 ));
877 }
878 out
879}
880
881fn config_lang(h: &Htl, cfg: &project::Config) -> Result<()> {
887 h.set_lang(&project::lang_of(cfg))
888}
889
890fn config_lints(h: &Htl, cfg: &project::Config) -> Result<htl::lint::Lints> {
891 let spec = cfg
892 .as_ref()
893 .map(|(_, _, c)| c.lint_spec())
894 .unwrap_or_default();
895 let lints = htl::lint::Lints::parse(&spec)?;
896 h.select_lints(lints.selection())?;
897 Ok(lints)
898}
899
900fn auto_dts(start: &Path) -> Result<()> {
911 auto_dts_to(start, true)
912}
913
914fn auto_dts_to(start: &Path, write: bool) -> Result<()> {
918 let mut project = None;
919 if let Some((root, _, cfg)) = load_config(start)? {
920 let model = htl::model::Project::load(&root, cfg)?;
922 let contracts: Vec<_> = model.contracts.iter().map(|c| c.terms.clone()).collect();
923 let (results, problems) = htl::contract::publish_to(&root, &contracts, write);
924 announce_dts_to(&results, &root, write);
925 for p in &problems {
926 eprintln!("dts: {p}");
927 }
928 project = Some(root);
929 }
930 let Some(root) = htl::dts::find_cargo_package_root(start) else {
931 return Ok(());
932 };
933 let results =
934 htl::dts::generate_crate_to(&root, write).map_err(|e| anyhow::anyhow!("htl dts: {e}"))?;
935 announce_dts_to(&results, &root, write);
936 let types_root = project.unwrap_or_else(|| root.clone());
937 let report = dep_dts_to(&root, &types_root, write);
938 announce_dts_to(&report.written, &types_root, write);
939 announce_dep_report(&report, "dts: ");
940 Ok(())
941}
942
943#[derive(Default)]
950struct DepReport {
951 written: Vec<(PathBuf, bool)>,
953 not_written: Vec<String>,
955 left_in_place: Vec<String>,
958 unresolved: Option<String>,
963}
964
965fn dep_dts(cargo_root: &Path, types_root: &Path) -> DepReport {
972 dep_dts_to(cargo_root, types_root, true)
973}
974
975fn dep_dts_to(cargo_root: &Path, types_root: &Path, write: bool) -> DepReport {
977 let decls = match htl::dep_dts::resolve(cargo_root) {
978 Ok(d) => d,
979 Err(e) => {
980 return DepReport {
981 unresolved: Some(e),
982 ..DepReport::default()
983 };
984 }
985 };
986 let types = match decl_root(types_root) {
989 Ok(t) => t,
990 Err(e) => {
991 return DepReport {
992 unresolved: Some(format!("{e:#}")),
993 ..DepReport::default()
994 };
995 }
996 };
997 let left_in_place = htl::dep_dts::orphans(&types, &decls);
998 let (written, not_written) = htl::dep_dts::materialise_to(&types, &decls, write);
999 DepReport {
1000 written,
1001 not_written,
1002 left_in_place,
1003 unresolved: None,
1004 }
1005}
1006
1007fn announce_dep_report(report: &DepReport, prefix: &str) {
1012 for p in &report.not_written {
1013 eprintln!("{prefix}not written: {p}");
1014 }
1015 for p in &report.left_in_place {
1016 eprintln!("{prefix}left in place: {p}");
1017 }
1018 if let Some(e) = &report.unresolved {
1019 eprintln!("{prefix}{e}");
1020 }
1021}
1022
1023fn announce_dts_to(results: &[(PathBuf, bool)], root: &Path, wrote: bool) {
1026 for (target, changed) in results {
1027 if *changed {
1028 let target = target.strip_prefix(root).unwrap_or(target).display();
1029 if wrote {
1030 eprintln!("dts: wrote {target}");
1031 } else {
1032 eprintln!(
1033 "dts: would write {target} (dry run: not written; checked against the \
1034 file on disk)"
1035 );
1036 }
1037 }
1038 }
1039}
1040
1041fn cmd_dts(dir: Option<&Path>) -> Result<ExitCode> {
1042 let start = match dir {
1043 Some(d) => d.to_path_buf(),
1044 None => std::env::current_dir()?,
1045 };
1046 let mut results = Vec::new();
1049 let mut failed = false;
1050 let mut project = None;
1051 if let Some((croot, _, cfg)) = load_config(&start)? {
1052 let model = htl::model::Project::load(&croot, cfg)?;
1053 let contracts: Vec<_> = model.contracts.iter().map(|c| c.terms.clone()).collect();
1054 let (published, problems) = htl::contract::publish(&croot, &contracts);
1055 for p in &problems {
1056 eprintln!(" {p}");
1057 }
1058 failed = !problems.is_empty();
1061 results.extend(published);
1062 project = Some(croot);
1063 }
1064 let code = |failed: bool| {
1065 if failed {
1066 ExitCode::FAILURE
1067 } else {
1068 ExitCode::SUCCESS
1069 }
1070 };
1071 let Some(root) = htl::dts::find_cargo_package_root(&start) else {
1072 if results.is_empty() && !failed {
1073 bail!(
1074 "no Cargo.toml with a [package] section, and no ---@contract type to publish, \
1075 at or above {}",
1076 start.display()
1077 );
1078 }
1079 report_dts(&results, &start);
1080 return Ok(code(failed));
1081 };
1082 results.extend(htl::dts::generate_crate(&root).map_err(|e| anyhow::anyhow!("{e}"))?);
1083 let types_root = project.unwrap_or_else(|| root.clone());
1084 let report = dep_dts(&root, &types_root);
1085 announce_dep_report(&report, " ");
1086 failed = failed || !report.not_written.is_empty();
1089 results.extend(report.written);
1090 report_dts(&results, &root);
1091 Ok(code(failed))
1092}
1093
1094fn report_dts(results: &[(PathBuf, bool)], root: &Path) {
1095 let mut written = 0usize;
1096 for (target, w) in results {
1097 let rel = target.strip_prefix(root).unwrap_or(target).display();
1098 eprintln!(" {} {}", if *w { "wrote " } else { "unchanged" }, rel);
1099 written += usize::from(*w);
1100 }
1101 eprintln!(
1102 "htl dts: {} declaration(s) from {}, {} written",
1103 results.len(),
1104 root.display(),
1105 written
1106 );
1107}
1108
1109fn apply_model(
1116 h: &Htl,
1117 cfg: &project::Config,
1118 start: &Path,
1119) -> Result<Option<htl::model::Project>> {
1120 let model = project::model_of(cfg, start)?;
1121 if let Some(m) = &model {
1122 h.apply_model(m, htl::model::View::Source)?;
1123 }
1124 Ok(model)
1125}
1126
1127fn report_scaffold(dir: &Path, written: &[PathBuf], kept: &[PathBuf]) {
1131 let rel = |p: &PathBuf| p.strip_prefix(dir).unwrap_or(p).display().to_string();
1132 for p in written {
1133 eprintln!(" created {}", rel(p));
1134 }
1135 for p in kept {
1136 eprintln!(" kept {} (already there)", rel(p));
1137 }
1138 if kept.is_empty() {
1139 eprintln!(
1140 "htl: {} file(s) written under {}",
1141 written.len(),
1142 dir.display()
1143 );
1144 } else {
1145 eprintln!(
1146 "htl: {} file(s) written, {} kept under {}",
1147 written.len(),
1148 kept.len(),
1149 dir.display()
1150 );
1151 }
1152}
1153
1154fn cmd_new(
1155 name: &str,
1156 lib: bool,
1157 embed: bool,
1158 target: Option<&str>,
1159 htl: Option<&str>,
1160 no_x: bool,
1161) -> Result<ExitCode> {
1162 let dir = PathBuf::from(name);
1163 let pkg_name = dir
1164 .file_name()
1165 .and_then(|s| s.to_str())
1166 .ok_or_else(|| anyhow::anyhow!("invalid project name: {name}"))?
1167 .to_string();
1168 let target = scaffold::resolve_target(target, embed, lib)?;
1172 let htl = scaffold::HtlPin::parse(htl)?;
1173 let opts = scaffold::Options {
1174 lib,
1175 target,
1176 htl,
1177 no_x,
1178 };
1179 let done = scaffold::scaffold(&dir, &pkg_name, &opts, true)?;
1180 report_scaffold(&dir, &done.written, &[]);
1181 let fetch = if opts.writes_htlx() {
1184 "htl pkg install && "
1185 } else {
1186 ""
1187 };
1188 let then = match opts.target.map(|t| t.target) {
1194 Some(BuildTarget::Window) => "htl check . && cargo run",
1195 _ => "htl test",
1196 };
1197 eprintln!("next: cd {} && {fetch}{then}", dir.display());
1198 Ok(ExitCode::SUCCESS)
1199}
1200
1201fn cmd_init(
1202 dir: Option<&Path>,
1203 lib: bool,
1204 embed: bool,
1205 target: Option<&str>,
1206 htl: Option<&str>,
1207 no_x: bool,
1208) -> Result<ExitCode> {
1209 let dir = match dir {
1210 Some(d) => d.to_path_buf(),
1211 None => std::env::current_dir()?,
1212 };
1213 let abs = std::fs::canonicalize(&dir).unwrap_or(dir.clone());
1214 let name = abs
1215 .file_name()
1216 .and_then(|s| s.to_str())
1217 .ok_or_else(|| anyhow::anyhow!("cannot derive a project name from {}", abs.display()))?
1218 .to_string();
1219 let asked_for_a_target = target.is_some() || embed;
1220 let target = scaffold::resolve_target(target, embed, lib)?;
1221 let htl = scaffold::HtlPin::parse(htl)?;
1222 let opts = scaffold::Options {
1223 lib,
1224 target,
1225 htl,
1226 no_x,
1227 };
1228 let done = scaffold::scaffold(&dir, &name, &opts, false)?;
1229 let kept: &[PathBuf] = if asked_for_a_target { &done.kept } else { &[] };
1232 if done.written.is_empty() && kept.is_empty() {
1233 eprintln!("htl init: nothing to do, all scaffold files already exist");
1234 } else {
1235 report_scaffold(&dir, &done.written, kept);
1236 }
1237 Ok(ExitCode::SUCCESS)
1238}
1239
1240fn pkg_project() -> Result<htl::pkg::MluaProject> {
1246 let cwd = std::env::current_dir()?;
1247 let root = htl::model::Project::find_root(&cwd)?.map(|r| r.root);
1248 root.filter(|r| r.join(htl::pkg::MANIFEST_NAME).is_file())
1249 .map(|r| htl::pkg::MluaProject::at(&r))
1250 .with_context(|| {
1251 format!(
1252 "no {} above {}: `htl pkg` runs in a project",
1253 htl::pkg::MANIFEST_NAME,
1254 cwd.display()
1255 )
1256 })
1257}
1258
1259fn decl_root(root: &Path) -> Result<PathBuf> {
1263 let cfg = load_config(root)?;
1264 Ok(project::model_of(&cfg, root)?
1265 .and_then(|m| m.own().roots.decl.clone())
1266 .unwrap_or_else(|| root.join("types")))
1267}
1268
1269fn cmd_pkg_install() -> Result<ExitCode> {
1271 let project = pkg_project()?;
1272 let report = project.install()?;
1273 report_install(&report, &project);
1274 let project = htl::pkg::MluaProject::at(&project.root);
1278 report_types_sync(
1279 &project.sync_types(&decl_root(&project.root)?)?,
1280 &project.root,
1281 );
1282 report_patch_drift(&project);
1283 Ok(ExitCode::SUCCESS)
1284}
1285
1286fn report_install(
1288 report: &htl::pkg::mlua_pkg::ops::InstallReport,
1289 project: &htl::pkg::MluaProject,
1290) {
1291 use htl::pkg::mlua_pkg::ops::Placement;
1292 for w in &report.warnings {
1293 if w.contains("patch_dir") && w.contains("not used") {
1297 continue;
1298 }
1299 eprintln!("warning: {w}");
1300 }
1301 let rel = |p: &Path| {
1302 p.strip_prefix(&project.root)
1303 .unwrap_or(p)
1304 .display()
1305 .to_string()
1306 };
1307 for p in &report.packages {
1308 let sha: String = p.sha.chars().take(7).collect();
1309 let where_it_is = match (&p.placement, p.patched) {
1310 (_, true) => format!("from {}", rel(p.root())),
1311 (Placement::Copied(dest), _) => format!("copied to {}", rel(dest)),
1312 (Placement::Symlink(_), _) => p.entry.display().to_string(),
1313 };
1314 eprintln!(" install {} {sha} ({where_it_is})", p.name);
1315 }
1316 let n = report.packages.len();
1317 if report.transitive > 0 {
1318 eprintln!(
1319 "htl pkg install: {n} package(s), {} of them transitive",
1320 report.transitive
1321 );
1322 } else {
1323 eprintln!("htl pkg install: {n} package(s)");
1324 }
1325}
1326
1327fn cmd_pkg_add(spec: htl::pkg::mlua_pkg::ops::AddSpec) -> Result<ExitCode> {
1335 use htl::pkg::mlua_pkg::ops::AddOutcome;
1336 let cwd = std::env::current_dir()?;
1337 let root = htl::model::Project::find_root(&cwd)?
1338 .map(|r| r.root)
1339 .unwrap_or(cwd);
1340 let project = htl::pkg::MluaProject::at(&root);
1341 let name = spec.name.clone();
1342 let done = project.add(spec)?;
1343 let manifest = project
1344 .manifest
1345 .strip_prefix(&project.root)
1346 .unwrap_or(&project.manifest)
1347 .display();
1348 if done.report.manifest_created {
1349 eprintln!(" created {manifest}");
1350 }
1351 let verb = match done.report.outcome {
1352 AddOutcome::Added => "added",
1353 AddOutcome::Replaced => "updated",
1354 };
1355 eprintln!(" {verb} {name} in {manifest}");
1356 if let Some(dir) = &done.kept_patch_dir {
1357 eprintln!(
1361 " kept patch_dir = {} ({name} is patched)",
1362 dir.display()
1363 );
1364 }
1365 eprintln!("htl pkg add: run `htl pkg install` to fetch it");
1366 Ok(ExitCode::SUCCESS)
1367}
1368
1369fn cmd_pkg_update(opts: htl::pkg::mlua_pkg::ops::UpdateOpts) -> Result<ExitCode> {
1371 use htl::pkg::mlua_pkg::ops::UpdateOutcome;
1372 let project = pkg_project()?;
1373 let dry_run = opts.dry_run;
1374 let report = project.update(opts)?;
1375 if report.entries.is_empty() {
1376 eprintln!("htl pkg update: no dependency selected");
1377 return Ok(ExitCode::SUCCESS);
1378 }
1379 for (name, outcome) in &report.entries {
1380 match outcome {
1381 UpdateOutcome::TagBumped { old, new } => {
1382 eprintln!(" update {name}: tag {old} -> {new}")
1383 }
1384 UpdateOutcome::PrefixResolved { pin, resolved } => eprintln!(
1385 " update {name}: prefix '{pin}' is {resolved} (the manifest keeps the prefix)"
1386 ),
1387 UpdateOutcome::Refresh => eprintln!(" update {name}: refresh (branch or unpinned)"),
1388 UpdateOutcome::Skipped(why) => eprintln!(" skip {name}: {why}"),
1389 }
1390 }
1391 if dry_run {
1392 eprintln!("htl pkg update: dry run; nothing was written");
1393 return Ok(ExitCode::SUCCESS);
1394 }
1395 if let Some(install) = &report.install {
1396 report_install(install, &project);
1397 let project = htl::pkg::MluaProject::at(&project.root);
1398 report_types_sync(
1399 &project.sync_types(&decl_root(&project.root)?)?,
1400 &project.root,
1401 );
1402 report_patch_drift(&project);
1403 }
1404 Ok(ExitCode::SUCCESS)
1405}
1406
1407fn cmd_pkg_clean(all: bool) -> Result<ExitCode> {
1409 use htl::pkg::mlua_pkg::ops::CleanReport;
1410 let project = pkg_project()?;
1411 match project.clean(all)? {
1412 CleanReport::CacheRemoved => eprintln!("htl pkg clean: removed every cached package"),
1413 CleanReport::NoLockfile => {
1414 eprintln!("htl pkg clean: no lockfile, so nothing was ever cached")
1415 }
1416 CleanReport::StaleRemoved { removed: 0 } => eprintln!("htl pkg clean: nothing to remove"),
1417 CleanReport::StaleRemoved { removed } => eprintln!(
1418 "htl pkg clean: removed {removed} cache entr{} the lockfile no longer refers to",
1419 if removed == 1 { "y" } else { "ies" }
1420 ),
1421 }
1422 Ok(ExitCode::SUCCESS)
1423}
1424
1425fn report_patch_drift(project: &htl::pkg::MluaProject) {
1434 let short = |s: &str| s.chars().take(7).collect::<String>();
1435 for s in project.patch_status() {
1436 if s.in_use {
1437 continue;
1438 }
1439 let rel = s
1440 .dir
1441 .strip_prefix(&project.root)
1442 .unwrap_or(&s.dir)
1443 .display();
1444 let why = match (&s.base, &s.locked) {
1445 _ if !s.dir.is_dir() => "the copy is not there".to_string(),
1446 (None, _) => "the lockfile records no revision it was taken from".to_string(),
1447 (Some(b), Some(l)) => {
1448 format!("taken from {}, {} is now at {}", short(b), s.name, short(l))
1449 }
1450 (Some(b), None) => format!("taken from {}, and nothing is locked", short(b)),
1451 };
1452 eprintln!(" patch {rel} is not in use ({why})");
1453 eprintln!(
1454 " carry the change forward: commit it, then `htl pkg patch {}`",
1455 s.name
1456 );
1457 eprintln!(" drop it: remove patch_dir from mlua-pkg.toml and delete {rel}");
1458 }
1459}
1460
1461fn cmd_pkg_patch(dep: &str, force: bool) -> Result<ExitCode> {
1466 let project = pkg_project().context("a patch belongs to a project, so this runs in one")?;
1467 let done = project.patch(dep, force)?;
1468 let report = &done.report;
1469 let rel = report
1470 .patch_dir
1471 .strip_prefix(&project.root)
1472 .unwrap_or(&report.patch_dir);
1473 let verb = if report.created { "patched" } else { "rebuilt" };
1474 let base: String = report.base.chars().take(7).collect();
1475 eprintln!(" {verb} {} ({dep} at {base})", rel.display());
1476 if !done.dropped.is_empty() {
1480 eprintln!(
1481 " dropped {} (the repository's, not the package's)",
1482 done.dropped.join(", ")
1483 );
1484 }
1485 eprintln!("htl: it is the project's code now — edit it, commit it, then `htl pkg install`.");
1486 Ok(ExitCode::SUCCESS)
1487}
1488
1489fn report_types_sync(sync: &htl::pkg::TypesSync, root: &Path) {
1493 let rel = |p: &Path| p.strip_prefix(root).unwrap_or(p).display().to_string();
1494 for (path, dep) in &sync.written {
1495 eprintln!(" types {} (from {dep})", rel(path));
1496 }
1497 for (path, dep) in &sync.taken {
1498 eprintln!(" kept {} ({dep} publishes one too)", rel(path));
1499 }
1500}
1501
1502fn cmd_types_add(library: &str, from: Option<&Path>, force: bool) -> Result<ExitCode> {
1506 let project = pkg_project().context("`types/` is a project's, so this runs in one")?;
1507 let types = decl_root(&project.root)?;
1508 let sync = match from {
1509 Some(dir) => project.add_types_from(dir, library, "local", force, &types)?,
1510 None => project.add_types(library, force, &types)?,
1511 };
1512 report_types_sync(&sync, &project.root);
1513 if sync.written.is_empty() && !sync.taken.is_empty() {
1514 eprintln!("htl: nothing written; --force replaces what is already there");
1515 }
1516 Ok(ExitCode::SUCCESS)
1517}
1518
1519struct UnusedFlags {
1521 json: bool,
1522 fail_on_unused: bool,
1525 use_cache: bool,
1526 explain: bool,
1527}
1528
1529struct CheckFlags {
1531 strict: bool,
1532 list_lints: bool,
1533 explain_rule: Option<String>,
1535 json: bool,
1536 use_cache: bool,
1537 cache_mode: Option<cache::Mode>,
1538 explain: bool,
1539}
1540
1541struct TestFlags {
1542 fail_fast: bool,
1543 verbose: bool,
1544 quiet: bool,
1545 slow: Option<f64>,
1546 update: bool,
1547 coverage: bool,
1548 coverage_lines: bool,
1549 lcov: Option<PathBuf>,
1551 junit: Option<PathBuf>,
1553 json: bool,
1554 no_cache: bool,
1555 explain: bool,
1556 seed: Option<u64>,
1557}
1558
1559fn print_coverage(cov: &report::CoverageReport, with_lines: bool) {
1560 let width = cov
1561 .modules
1562 .iter()
1563 .map(|m| m.path.len())
1564 .max()
1565 .unwrap_or(4)
1566 .max(5);
1567 for m in &cov.modules {
1568 eprintln!(
1569 "coverage: {:<width$} {:>5}/{:<5} {:5.1}%",
1570 m.path,
1571 m.executed,
1572 m.total,
1573 100.0 * m.executed as f64 / m.total as f64
1574 );
1575 if !m.never_ran.is_empty() {
1576 let names: Vec<String> = m
1577 .never_ran
1578 .iter()
1579 .map(|f| format!("{} ({})", f.name, f.line))
1580 .collect();
1581 eprintln!(" never ran: {}", names.join(", "));
1582 }
1583 if with_lines && !m.unexecuted.is_empty() {
1584 let spans: Vec<String> = m
1585 .unexecuted
1586 .iter()
1587 .map(|(a, b)| {
1588 if a == b {
1589 a.to_string()
1590 } else {
1591 format!("{a}-{b}")
1592 }
1593 })
1594 .collect();
1595 eprintln!(" unexecuted: {}", spans.join(", "));
1596 }
1597 }
1598 if cov.total > 0 {
1599 eprintln!(
1600 "coverage: {:<width$} {:>5}/{:<5} {:5.1}% (statements)",
1601 "total",
1602 cov.executed,
1603 cov.total,
1604 100.0 * cov.executed as f64 / cov.total as f64
1605 );
1606 } else {
1607 eprintln!("coverage: no .tl module reached");
1608 }
1609}
1610
1611fn junit_suite(rep: &htl::testing::FileReport) -> junit::Suite {
1619 let mut left: Vec<&str> = rep.failures.iter().map(String::as_str).collect();
1620 let cases = rep
1621 .tests
1622 .iter()
1623 .map(|t| {
1624 let failure = (!t.ok)
1625 .then(|| {
1626 let head = format!("{}: ", t.name);
1627 let at = left.iter().position(|m| m.starts_with(&head))?;
1628 Some(left.remove(at)[head.len()..].to_string())
1629 })
1630 .flatten();
1631 junit::Case {
1632 name: t.name.clone(),
1633 ms: t.ms,
1634 failure: failure.or_else(|| (!t.ok).then(|| "failed".to_string())),
1637 }
1638 })
1639 .collect();
1640 let error = if !rep.check.ok() {
1641 Some(junit::Error {
1642 message: "type check failed".to_string(),
1643 kind: "check",
1644 body: rep
1645 .check
1646 .error_items
1647 .iter()
1648 .map(|d| d.clone().spelled().to_string())
1649 .collect::<Vec<_>>()
1650 .join("\n"),
1651 })
1652 } else {
1653 rep.error.as_ref().map(|e| junit::Error {
1654 message: e.clone(),
1655 kind: "error",
1656 body: e.clone(),
1657 })
1658 };
1659 junit::Suite {
1660 file: htl::diagnostic::display_path(&rep.path),
1661 duration_ms: rep.duration_ms,
1662 error,
1663 cases,
1664 }
1665}
1666
1667fn cmd_test(
1668 paths: &[PathBuf],
1669 filter: Option<&str>,
1670 lib: &str,
1671 lint: Option<&str>,
1672 flags: TestFlags,
1673) -> Result<ExitCode> {
1674 let paths = if paths.is_empty() {
1675 vec![PathBuf::from(".")]
1676 } else {
1677 paths.to_vec()
1678 };
1679 if let Some(first) = paths.first() {
1680 auto_dts(first)?;
1681 }
1682 let cfg = load_config(&paths[0])?;
1686 let model = project::model_of(&cfg, &paths[0])?;
1687 let skip = project::not_walked(model.as_ref(), &paths, htl::model::Purpose::Test);
1688 let files = htl::testing::discover_tests_for(&paths, &skip, lib)?;
1689 project::refuse_flat_root(model.as_ref(), &paths, &files)?;
1692 if files.is_empty() {
1693 eprintln!("htl test: no test files found (looked for .tl files that require(\"{lib}\"))");
1694 return Ok(ExitCode::FAILURE);
1695 }
1696 let opts = project::TestOptions {
1697 config: &cfg,
1698 model: model.as_ref(),
1699 lint,
1700 lib,
1701 filter,
1702 run: htl::testing::RunOptions {
1703 fail_fast: flags.fail_fast,
1704 update_snapshots: flags.update,
1705 coverage: flags.coverage,
1706 seed: flags.seed,
1708 async_: Default::default(),
1710 lang: Default::default(),
1711 },
1712 cache: project::cache_options(
1713 !flags.no_cache,
1714 Some(cache::Mode::PerModule),
1715 &cfg,
1716 flags.explain,
1717 ),
1718 };
1719
1720 let mut sink = project::Sink::new(report::Out::new(flags.json));
1721 let mut json_files: Vec<report::TestFile> = Vec::new();
1722 let mut junit_suites: Vec<junit::Suite> = Vec::new();
1723 let rep = project::test(&mut sink, &files, &opts, &mut |rep, sink| {
1727 if flags.json {
1728 json_files.push(report::TestFile::from_report(rep, sink.out().take()));
1729 }
1730 if flags.junit.is_some() {
1731 junit_suites.push(junit_suite(rep));
1732 }
1733 let f = htl::diagnostic::display_path(&rep.path);
1735 let tag = if rep.ok() { "ok " } else { "FAIL" };
1736 let detail = if !rep.check.ok() {
1737 "type check failed".to_string()
1738 } else if let Some(e) = &rep.error {
1739 format!("error: {}", e.lines().next().unwrap_or_default())
1742 } else if rep.file_level {
1743 "ran to completion (no test library used)".to_string()
1744 } else {
1745 format!("{} passed, {} failed", rep.passed, rep.failed)
1746 };
1747 let show_file = !flags.json && (!flags.quiet || !rep.ok());
1750 if show_file {
1751 eprintln!("{tag} {f} ({detail}, {:.0} ms)", rep.duration_ms);
1752 if let Some(e) = &rep.error {
1753 for line in e.lines().skip(1) {
1754 eprintln!(" {line}");
1755 }
1756 }
1757 }
1758 for tr in &rep.tests {
1759 let slow = flags.slow.is_some_and(|ms| tr.ms >= ms);
1760 if !flags.json && (flags.verbose || slow) {
1761 if flags.quiet && !show_file {
1762 eprintln!("slow {f} {} ({:.1} ms)", tr.name, tr.ms);
1764 continue;
1765 }
1766 let mark = if tr.ok { "ok " } else { "FAIL" };
1767 let note = if slow && !flags.verbose {
1768 " [slow]"
1769 } else {
1770 ""
1771 };
1772 eprintln!(" {mark} {} ({:.1} ms){note}", tr.name, tr.ms);
1773 }
1774 }
1775 if !flags.json {
1776 for m in &rep.failures {
1777 eprintln!(" - {m}");
1778 }
1779 for p in &rep.snapshots_written {
1781 eprintln!(
1782 "snapshot written: {}",
1783 htl::diagnostic::display_path(Path::new(p))
1784 );
1785 }
1786 for p in &rep.snapshots_updated {
1787 eprintln!(
1788 "snapshot updated: {}",
1789 htl::diagnostic::display_path(Path::new(p))
1790 );
1791 }
1792 }
1793 })?;
1794
1795 if let Some(out) = &flags.junit {
1796 std::fs::write(out, junit::document(&junit_suites, rep.duration_ms))
1799 .with_context(|| format!("writing {}", out.display()))?;
1800 }
1801 if let (Some(out), Some(cov)) = (&flags.lcov, &rep.coverage) {
1802 let root = match &cfg {
1805 Some((dir, _, _)) => dir.clone(),
1806 None => std::env::current_dir()?,
1807 };
1808 let root = std::fs::canonicalize(&root).unwrap_or(root);
1809 std::fs::write(out, cov.lcov(&root))
1810 .with_context(|| format!("writing {}", out.display()))?;
1811 }
1812 let ok = rep.ok();
1813 if flags.json {
1814 let summary = report::TestSummary {
1815 files: rep.files.len(),
1816 files_run: rep.ran,
1817 passed: rep.passed,
1818 failed: rep.failed,
1819 files_with_errors: rep.files_with_errors,
1820 replayed: rep.replayed,
1821 duration_ms: rep.duration_ms,
1822 ok,
1823 seed: rep.seed,
1824 };
1825 report::emit(&report::TestReport {
1826 files: json_files,
1827 summary,
1828 coverage: rep.coverage,
1829 })?;
1830 } else {
1831 if let Some(cov) = &rep.coverage {
1832 print_coverage(cov, flags.coverage_lines);
1833 if let Some(out) = &flags.lcov {
1834 eprintln!("coverage: lcov written to {}", out.display());
1835 }
1836 }
1837 eprintln!(
1838 "htl test: {} file(s), {} passed, {} failed, {} file(s) with errors{}{} ({:.0} ms)",
1839 rep.ran,
1840 rep.passed,
1841 rep.failed,
1842 rep.files_with_errors,
1843 if rep.skipped() > 0 {
1844 format!(", {} file(s) not run (--fail-fast)", rep.skipped())
1845 } else {
1846 String::new()
1847 },
1848 if rep.replayed > 0 {
1850 format!(", {} checked from cache", rep.replayed)
1851 } else {
1852 String::new()
1853 },
1854 rep.duration_ms
1855 );
1856 eprintln!(
1859 "htl test: seed {} (repeat with --seed {})",
1860 rep.seed, rep.seed
1861 );
1862 }
1863 Ok(if ok {
1864 ExitCode::SUCCESS
1865 } else {
1866 ExitCode::FAILURE
1867 })
1868}
1869
1870fn report_patched(paths: &[PathBuf]) {
1876 let roots: Vec<PathBuf> = paths
1877 .iter()
1878 .filter_map(|p| std::fs::canonicalize(p).ok())
1879 .collect();
1880 let cwd = std::env::current_dir().unwrap_or_default();
1881 let Some(project) = paths
1884 .first()
1885 .and_then(|p| htl::model::Project::find_root(p).ok().flatten())
1886 .map(|r| r.root)
1887 .filter(|r| r.join(htl::pkg::MANIFEST_NAME).is_file())
1888 .map(|r| htl::pkg::MluaProject::at(&r))
1889 else {
1890 return;
1891 };
1892 for p in &project.patches {
1893 let canon = std::fs::canonicalize(&p.dir).unwrap_or_else(|_| p.dir.clone());
1894 if !roots.iter().any(|r| canon.starts_with(r)) {
1895 continue;
1896 }
1897 let shown = p.dir.strip_prefix(&cwd).unwrap_or(&p.dir);
1898 eprintln!(" patched {} ({})", shown.display(), p.name);
1899 }
1900}
1901
1902fn load_config(first: &Path) -> Result<project::Config> {
1914 let cfg = project::config_of(first)?;
1915 if let Some((_, path, c)) = &cfg {
1916 htl::config::check_toolchain(c, path, env!("CARGO_PKG_VERSION"))?;
1917 }
1918 Ok(cfg)
1919}
1920
1921fn warn_cargo_htl_mismatch(first: &Path) {
1948 let Some(root) = htl::dts::find_cargo_package_root(first) else {
1949 return;
1950 };
1951 let Ok(text) = fs::read_to_string(root.join("Cargo.toml")) else {
1952 return;
1953 };
1954 let Ok(manifest) = text.parse::<toml::Table>() else {
1955 return;
1956 };
1957 let Some(dep) = manifest.get("dependencies").and_then(|d| d.get("htl")) else {
1958 return;
1959 };
1960 let req_text = match dep {
1961 toml::Value::String(s) => s.as_str(),
1962 toml::Value::Table(t) => match t.get("version").and_then(toml::Value::as_str) {
1963 Some(s) => s,
1964 None => return,
1965 },
1966 _ => return,
1967 };
1968 let running = env!("CARGO_PKG_VERSION");
1969 let (Ok(req), Ok(version)) = (
1970 semver::VersionReq::parse(req_text),
1971 semver::Version::parse(running),
1972 ) else {
1973 return;
1974 };
1975 if req.matches(&version) {
1976 return;
1977 }
1978 eprintln!(
1981 "htl {running}; Cargo.toml asks for htl {req_text} — the crate and the CLI are \
1982 meant to move together (cargo install htl-cli --version {req_text}, or bump the \
1983 dependency)"
1984 );
1985}
1986
1987fn cmd_fmt(paths: &[PathBuf], check: bool, indent: Option<usize>) -> Result<ExitCode> {
1988 let paths = if paths.is_empty() {
1989 vec![PathBuf::from(".")]
1990 } else {
1991 paths.to_vec()
1992 };
1993 let cfg = load_config(&paths[0])?;
1994 let indent = indent
1995 .or_else(|| cfg.as_ref().and_then(|(_, _, c)| c.fmt.indent))
1996 .unwrap_or(3);
1997 let h = Htl::new()?;
1998 config_lang(&h, &cfg)?;
1999 let model = project::model_of(&cfg, &paths[0])?;
2003 let skip = project::not_walked(model.as_ref(), &paths, htl::model::Purpose::Own);
2004 let files = htl::collect_tl_skipping(&paths, &skip)?;
2005 let (mut changed, mut failed) = (0usize, 0usize);
2006 for f in &files {
2007 let before = fs::read_to_string(f).with_context(|| format!("reading {}", f.display()))?;
2008 let after = match h.format_file(f, indent) {
2009 Ok(s) => s,
2010 Err(e) => {
2011 eprintln!("error: {e}");
2012 failed += 1;
2013 continue;
2014 }
2015 };
2016 if after != before {
2017 changed += 1;
2018 if check {
2019 eprintln!("would reformat: {}", f.display());
2020 } else {
2021 fs::write(f, after).with_context(|| format!("writing {}", f.display()))?;
2022 eprintln!("reformatted: {}", f.display());
2023 }
2024 }
2025 }
2026 eprintln!(
2027 "htl fmt: {} file(s), {} {}, {} failed",
2028 files.len(),
2029 changed,
2030 if check { "would change" } else { "reformatted" },
2031 failed
2032 );
2033 let fail = failed > 0 || (check && changed > 0);
2034 Ok(if fail {
2035 ExitCode::FAILURE
2036 } else {
2037 ExitCode::SUCCESS
2038 })
2039}
2040
2041struct FixFlags {
2042 rule: Vec<String>,
2043 unsafe_fixes: bool,
2044 dry_run: bool,
2045 diff: bool,
2046 allow_dirty: bool,
2047 allow_no_vcs: bool,
2048 exit_non_zero_on_fix: bool,
2049 json: bool,
2050}
2051
2052fn cmd_fix(paths: &[PathBuf], flags: FixFlags) -> Result<ExitCode> {
2053 use htl::fix::{FixOptions, fix_file, git_dirty, unified_diff};
2054 let paths = if paths.is_empty() {
2055 vec![PathBuf::from(".")]
2056 } else {
2057 paths.to_vec()
2058 };
2059 let cfg = load_config(&paths[0])?;
2060 auto_dts_to(&paths[0], !flags.dry_run)?;
2062 let model = project::model_of(&cfg, &paths[0])?;
2063 let scope = project::Scope::new(&cfg, model.as_ref(), &paths[0], None)?;
2066 let h = project::checker(
2067 model.as_ref(),
2068 scope.lints.selection(),
2069 &project::lang_of(&cfg),
2070 )?;
2071 let opts = FixOptions {
2072 unsafe_fixes: flags.unsafe_fixes,
2073 promoted: cfg
2074 .as_ref()
2075 .map(|(_, _, c)| c.fix.unsafe_.clone())
2076 .unwrap_or_default(),
2077 disabled: cfg
2078 .as_ref()
2079 .map(|(_, _, c)| c.fix.disable.clone())
2080 .unwrap_or_default(),
2081 only: flags.rule.clone(),
2082 dry_run: flags.dry_run,
2083 };
2084 opts.validate()?;
2087 let skip = project::not_walked(model.as_ref(), &paths, htl::model::Purpose::Own);
2091 let (files, outside) = project::held_by_modules(
2093 model.as_ref(),
2094 &paths,
2095 htl::collect_tl_skipping(&paths, &skip)?,
2096 )?;
2097 if let Some(note) = project::outside_modules_note(model.as_ref(), &outside, "fixed") {
2098 eprintln!("htl fix: {note}");
2099 }
2100 let check_skip = project::not_walked(model.as_ref(), &paths, htl::model::Purpose::Check);
2104 let checked_only: Vec<PathBuf> = project::held_by_modules(
2105 model.as_ref(),
2106 &paths,
2107 htl::collect_tl_skipping(&paths, &check_skip)?,
2108 )?
2109 .0
2110 .into_iter()
2111 .filter(|f| !files.contains(f))
2112 .collect();
2113
2114 if !flags.dry_run {
2116 let mut dirty = Vec::new();
2117 let mut no_vcs = Vec::new();
2118 for f in &files {
2119 match git_dirty(f)? {
2120 Some(true) => dirty.push(f.clone()),
2121 Some(false) => {}
2122 None => no_vcs.push(f.clone()),
2123 }
2124 }
2125 if !dirty.is_empty() && !flags.allow_dirty {
2126 bail!(
2127 "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",
2128 dirty
2129 .iter()
2130 .map(|p| p.display().to_string())
2131 .collect::<Vec<_>>()
2132 .join("\n ")
2133 );
2134 }
2135 if !no_vcs.is_empty() && !flags.allow_no_vcs {
2136 bail!(
2137 "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",
2138 no_vcs
2139 .iter()
2140 .map(|p| p.display().to_string())
2141 .collect::<Vec<_>>()
2142 .join("\n ")
2143 );
2144 }
2145 }
2146
2147 let mut sink = project::Sink::new(report::Out::new(flags.json));
2148 sink.judge_by(scope.lints.selection());
2150 let origins = project::Origins::new(model.as_ref());
2154 let walk = scope.walk(&cfg, model.as_ref(), &origins);
2155 let walked: Vec<PathBuf> = files.iter().chain(&checked_only).cloned().collect();
2156 sink.walking(&walked);
2157 let (mut applied, mut skipped, mut json_files) = (Vec::new(), Vec::new(), Vec::new());
2158 let (mut changed, mut deferred, mut reverted) = (0usize, 0usize, 0usize);
2159 let mut found = htl::verdict::Findings::default();
2160 let mut infos: Vec<(PathBuf, htl::CheckInfo)> = Vec::with_capacity(walked.len());
2161 for f in &files {
2162 let saved = h.search_path()?;
2165 project::file_view(&h, model.as_ref(), f)?;
2166 let before = if flags.diff {
2167 std::fs::read_to_string(f).ok()
2168 } else {
2169 None
2170 };
2171 let out = fix_file(&h, f, &opts)?;
2172 if out.contents.is_some() {
2173 changed += 1;
2174 }
2175 deferred += out.deferred;
2176 if out.reverted.is_some() {
2177 reverted += 1;
2178 }
2179 if !flags.json {
2180 for a in &out.applied {
2181 eprintln!(
2182 "fixed: {}:{}: {} ({}{})",
2183 project::display_path(f),
2184 a.line,
2185 a.rule,
2186 a.applicability.as_str(),
2187 if flags.dry_run { ", not written" } else { "" }
2188 );
2189 }
2190 for s in &out.skipped {
2191 eprintln!(
2192 "skipped: {}:{}: {} — {}",
2193 project::display_path(f),
2194 s.line,
2195 s.rule,
2196 s.reason
2197 );
2198 }
2199 if let Some(r) = &out.reverted {
2200 eprintln!("reverted: {}: {r}", project::display_path(f));
2201 }
2202 if let Some(o) = &out.oscillation {
2203 eprintln!(
2204 "stopped: {}: fixes of {o} undo each other",
2205 project::display_path(f)
2206 );
2207 }
2208 if out.deferred > 0 {
2209 eprintln!(
2210 "deferred: {}: {} edit(s) overlapped applied ones; run htl fix again",
2211 project::display_path(f),
2212 out.deferred
2213 );
2214 }
2215 if flags.diff
2216 && let (Some(b), Some(a)) = (&before, &out.contents)
2217 {
2218 print!("{}", unified_diff(&project::display_path(f), b, a));
2219 }
2220 if flags.diff
2223 && let (Some(b), Some(s)) = (
2224 out.contents.as_ref().or(before.as_ref()),
2225 out.suggested.as_ref(),
2226 )
2227 {
2228 print!(
2229 "{}",
2230 unified_diff(&format!("{} (suggested)", project::display_path(f)), b, s)
2231 );
2232 }
2233 }
2234 found.lints += project::file_findings(&h, &mut sink, f, &out.check, &walk)?;
2237 h.set_search_path(&saved)?;
2238 found.errors += out.check.errors.len();
2239 found.warnings += out.check.warnings.len();
2240 infos.push((f.clone(), out.check.clone()));
2241 if flags.json {
2242 applied.extend(out.applied.iter().map(|a| report::FixApplied {
2243 file: project::display_path(f),
2244 line: a.line,
2245 rule: a.rule.clone(),
2246 applicability: a.applicability.as_str(),
2247 pass: a.pass,
2248 }));
2249 skipped.extend(out.skipped.iter().map(|s| report::FixSkipped {
2250 file: project::display_path(f),
2251 line: s.line,
2252 rule: s.rule.clone(),
2253 reason: s.reason.clone(),
2254 }));
2255 json_files.push(report::FixFile {
2256 path: project::display_path(f),
2257 changed: out.contents.is_some(),
2258 deferred: out.deferred,
2259 reverted: out.reverted.clone(),
2260 oscillation: out.oscillation.clone(),
2261 diagnostics: sink.out().take(),
2262 });
2263 }
2264 }
2265 for f in &checked_only {
2267 let m = project::check_one(&h, &mut sink, f, &walk)?;
2268 found.errors += m.errors;
2269 found.warnings += m.warnings;
2270 found.lints += m.lints;
2271 infos.push((f.clone(), m.requires_only()));
2272 if flags.json {
2273 json_files.push(report::FixFile {
2274 path: project::display_path(f),
2275 changed: false,
2276 deferred: 0,
2277 reverted: None,
2278 oscillation: None,
2279 diagnostics: sink.out().take(),
2280 });
2281 }
2282 }
2283 let mut whole = scope.whole(&cfg, model.as_ref());
2286 whole.publish = !flags.dry_run;
2287 let w = project::project_findings(&mut sink, &whole, &infos);
2288 found.errors += w.errors;
2289 found.lints += w.lints;
2290 let project_diagnostics = if flags.json {
2291 sink.out().take()
2292 } else {
2293 Vec::new()
2294 };
2295 found.errors += sink.dependency_error_count();
2298 found.denied = sink.denied();
2299 let policy = htl::verdict::Policy::resolve(cfg.as_ref().map(|(_, _, c)| c), false);
2301 let errors_remaining = found.errors;
2302 let n_applied = if flags.json { applied.len() } else { 0 };
2303 let fail =
2304 htl::verdict::verdict(&found, &policy) || (flags.exit_non_zero_on_fix && changed > 0);
2305 if flags.json {
2306 let n_skipped = skipped.len();
2307 report::emit(&report::FixReport {
2308 dry_run: flags.dry_run,
2309 applied,
2310 skipped,
2311 files: json_files,
2312 summary: report::FixSummary {
2313 files: files.len(),
2314 files_changed: changed,
2315 applied: n_applied,
2316 skipped: n_skipped,
2317 deferred,
2318 reverted,
2319 errors_remaining,
2320 warnings: found.warnings,
2321 lints: found.lints,
2322 denied: found.denied,
2323 strict: policy.strict,
2324 ok: !fail,
2325 },
2326 diagnostics: project_diagnostics,
2327 })?;
2328 } else {
2329 let judged = judged(&found, &policy);
2333 eprintln!(
2334 "htl fix: {} file(s){}, {} changed{}, {} error(s) remaining{}{}",
2335 files.len(),
2336 if checked_only.is_empty() {
2337 String::new()
2338 } else {
2339 format!(" + {} checked in patched dependencies", checked_only.len())
2340 },
2341 changed,
2342 if flags.dry_run {
2343 " (dry run, nothing written)"
2344 } else {
2345 ""
2346 },
2347 errors_remaining,
2348 judged,
2349 if deferred > 0 {
2350 format!(", {deferred} deferred")
2351 } else {
2352 String::new()
2353 }
2354 );
2355 }
2356 Ok(if fail {
2357 ExitCode::FAILURE
2358 } else {
2359 ExitCode::SUCCESS
2360 })
2361}
2362
2363fn cmd_check(paths: &[PathBuf], lint: Option<&str>, flags: CheckFlags) -> Result<ExitCode> {
2375 let CheckFlags {
2376 list_lints,
2377 json,
2378 use_cache,
2379 cache_mode,
2380 explain,
2381 ..
2382 } = flags;
2383 let mut sink = project::Sink::new(report::Out::new(json));
2384 let paths = if paths.is_empty() {
2385 vec![PathBuf::from(".")]
2386 } else {
2387 paths.to_vec()
2388 };
2389 if let Some(rule) = flags.explain_rule.as_deref() {
2398 let Some(r) = htl::lint::explained(rule) else {
2399 eprintln!("unknown lint rule: {rule}");
2400 return Ok(ExitCode::from(2));
2401 };
2402 println!("{} (default: {})\n\n{}", r.name, r.default, r.explain);
2403 return Ok(ExitCode::SUCCESS);
2404 }
2405 if list_lints {
2406 let width = htl::lint::rule_names()
2411 .iter()
2412 .map(|r| r.len())
2413 .max()
2414 .unwrap_or(0);
2415 for (name, level) in htl::lint::rule_defaults() {
2416 println!("{name:width$} {level}");
2417 }
2418 return Ok(ExitCode::SUCCESS);
2422 }
2423 let cfg = load_config(&paths[0])?;
2425 warn_cargo_htl_mismatch(&paths[0]);
2426 let policy = htl::verdict::Policy::resolve(cfg.as_ref().map(|(_, _, c)| c), flags.strict);
2427 if let Some(first) = paths.first() {
2431 auto_dts(first)?;
2432 }
2433 let walk_model = project::model_of(&cfg, &paths[0])?;
2438 if walk_model.is_none()
2443 && let Some(dir) = paths.iter().find(|p| p.is_dir())
2444 {
2445 bail!(
2446 "no {} or {} in {} or any directory above it: a directory is checked as a \
2447 project. Run `htl init` there to make it one, or name the .tl files to check \
2448 each on its own",
2449 htl::config::CONFIG_NAME,
2450 htl::pkg::MANIFEST_NAME,
2451 fs::canonicalize(dir)
2454 .unwrap_or_else(|_| dir.clone())
2455 .display()
2456 );
2457 }
2458 let skip = project::not_walked(walk_model.as_ref(), &paths, htl::model::Purpose::Check);
2459 let (files, outside) = project::held_by_modules(
2460 walk_model.as_ref(),
2461 &paths,
2462 htl::collect_tl_skipping(&paths, &skip)?,
2463 )?;
2464 if let Some(note) = project::outside_modules_note(walk_model.as_ref(), &outside, "checked") {
2465 eprintln!("htl check: {note}");
2466 }
2467 if !json {
2468 report_patched(&paths);
2469 }
2470
2471 let rep = project::check(
2475 &mut sink,
2476 &files,
2477 &project::Options {
2478 paths: &paths,
2479 config: &cfg,
2480 model: walk_model.as_ref(),
2481 lint,
2482 cache: project::cache_options(use_cache, cache_mode, &cfg, explain),
2483 },
2484 )?;
2485 let fail = report_check(
2486 sink.out(),
2487 json,
2488 &rep,
2489 &policy,
2490 patched_files(walk_model.as_ref(), &rep.files),
2491 )?;
2492 Ok(if fail {
2493 ExitCode::FAILURE
2494 } else {
2495 ExitCode::SUCCESS
2496 })
2497}
2498
2499fn cmd_unused(paths: &[PathBuf], flags: UnusedFlags) -> Result<ExitCode> {
2506 let UnusedFlags {
2507 json,
2508 fail_on_unused,
2509 use_cache,
2510 explain,
2511 } = flags;
2512 let paths = if paths.is_empty() {
2513 vec![PathBuf::from(".")]
2514 } else {
2515 paths.to_vec()
2516 };
2517 let cfg = load_config(&paths[0])?;
2518 auto_dts(&paths[0])?;
2521 let model = project::model_of(&cfg, &paths[0])?;
2522 let rep = htl::unused::unused(&htl::unused::Options {
2523 paths: &paths,
2524 config: &cfg,
2525 model: model.as_ref(),
2526 cache: project::cache_options(use_cache, None, &cfg, explain),
2527 })?;
2528 let s = &rep.summary;
2529 if json {
2530 report::emit(&rep)?;
2531 } else if s.no_entry {
2532 eprintln!(
2533 "htl unused: nothing to start from, so nothing is reported. An entry is \
2534 main.tl in the source root ([layout] source) or beside the manifest, a test file, a module under a [[contract]] directory, or a name \
2535 in [build] extra / host"
2536 );
2537 } else {
2538 if s.check_errors > 0 {
2539 eprintln!(
2540 "htl unused: {} error(s) in the check this graph comes from — what those \
2541 files require is missing from it (htl check)",
2542 s.check_errors
2543 );
2544 }
2545 for m in &rep.modules {
2546 match &m.module {
2547 Some(n) => eprintln!("module: {} ({n})", m.path),
2548 None => eprintln!("module: {}", m.path),
2549 }
2550 }
2551 for d in &rep.dependencies {
2552 eprintln!("dependency: {}", d.name);
2553 }
2554 eprintln!(
2555 "htl unused: {}, {} [{} considered, {} reached, {}]",
2556 count(s.modules, "module", "modules"),
2557 count(s.dependencies, "dependency", "dependencies"),
2558 s.considered,
2559 s.reached,
2560 count(s.entries, "entry", "entries"),
2561 );
2562 }
2563 Ok(if fail_on_unused && !s.ok {
2564 ExitCode::FAILURE
2565 } else {
2566 ExitCode::SUCCESS
2567 })
2568}
2569
2570fn cmd_resolve(module: &str, path: Option<&Path>, json: bool) -> Result<ExitCode> {
2579 let start = path.unwrap_or(Path::new("."));
2580 let cfg = load_config(start)?;
2581 auto_dts(start)?;
2585 let h = Htl::new()?;
2586 h.install_std()?;
2589 let model = apply_model(&h, &cfg, start)?;
2590 let rep = htl::resolve::resolve(
2591 &h,
2592 module,
2593 cfg.as_ref().map(|(r, _, _)| r.as_path()),
2594 model.as_ref(),
2595 )?;
2596 if json {
2597 report::emit(&rep)?;
2598 } else {
2599 print_resolution(&rep);
2600 }
2601 Ok(if rep.summary.ok {
2602 ExitCode::SUCCESS
2603 } else {
2604 ExitCode::FAILURE
2605 })
2606}
2607
2608fn print_resolution(r: &htl::resolve::Resolution) {
2612 let ambiguous = r
2613 .candidates
2614 .iter()
2615 .any(|c| c.status == htl::resolve::Status::Ambiguous);
2616 let typed_by = r
2620 .read
2621 .as_ref()
2622 .map(|d| format!(", typed by {d}"))
2623 .unwrap_or_default();
2624 match (&r.read, &r.error, &r.provided_by) {
2625 (_, Some(e), _) => println!("htl resolve {}: error: {e}", r.module),
2626 (Some(read), None, Some(by)) if r.provider == Some(htl::model::Provider::Declared) => {
2630 println!(
2631 "htl resolve {}: {read}, provided by the environment ({by})",
2632 r.module
2633 )
2634 }
2635 (_, None, Some(by)) => {
2636 println!(
2637 "htl resolve {}: provided by the host ({by}){typed_by}",
2638 r.module
2639 )
2640 }
2641 (Some(read), None, None) => println!("htl resolve {}: {read}", r.module),
2642 (None, None, None) if ambiguous => println!(
2643 "htl resolve {}: more than one module implements it, and no order picks one",
2644 r.module
2645 ),
2646 (None, None, None) => println!(
2647 "htl resolve {}: nothing in the project or on the search path answers require(\"{}\")",
2648 r.module, r.module
2649 ),
2650 }
2651 if !r.candidates.is_empty() {
2652 let w = |f: fn(&htl::resolve::Candidate) -> usize, head: usize| {
2653 r.candidates.iter().map(f).max().unwrap_or(0).max(head)
2654 };
2655 let file = w(|c| c.path.len(), 4);
2656 let kind = w(|c| c.kind.as_str().len(), 4);
2657 let read_at = r
2658 .candidates
2659 .iter()
2660 .find(|c| c.status == htl::resolve::Status::Read)
2661 .map(|c| c.order);
2662 println!();
2663 println!(" order {:file$} {:kind$} status", "file", "kind");
2664 for c in &r.candidates {
2665 let status = match (c.status, c.shadowed_by, read_at) {
2666 (htl::resolve::Status::Shadowed, Some(by), _) => format!("shadowed by {by}"),
2667 (htl::resolve::Status::Runtime, _, Some(by)) => format!("runtime, typed by {by}"),
2669 (s, _, _) => s.as_str().to_string(),
2670 };
2671 let origin = match &c.origin {
2672 Some(o) => format!(" ({})", o.describe()),
2673 None => String::new(),
2674 };
2675 println!(
2676 " {:<5} {:file$} {:kind$} {status}{origin}",
2677 c.order,
2678 c.path,
2679 c.kind.as_str()
2680 );
2681 }
2682 }
2683 println!();
2684 match r.answered_by {
2685 htl::resolve::AnsweredBy::Model => println!(" answered by the project model"),
2686 htl::resolve::AnsweredBy::Path => {
2689 println!(" searched, in order: {}", r.searched.join(", "))
2690 }
2691 }
2692}
2693
2694fn count(n: usize, one: &str, many: &str) -> String {
2697 format!("{n} {}", if n == 1 { one } else { many })
2698}
2699
2700fn cmd_cache_clear(path: Option<&Path>) -> Result<ExitCode> {
2710 let root = cache_root(path)?;
2711 let dir = root.join(".htl").join("cache");
2712 if !dir.is_dir() {
2713 eprintln!("htl cache: nothing stored at {}", dir.display());
2714 return Ok(ExitCode::SUCCESS);
2715 }
2716 let n = fs::read_dir(&dir)
2717 .map(|rd| {
2718 rd.flatten()
2719 .filter(|e| e.path().extension().is_some_and(|x| x == "json"))
2720 .count()
2721 })
2722 .unwrap_or(0);
2723 fs::remove_dir_all(&dir).with_context(|| format!("removing {}", dir.display()))?;
2724 eprintln!(
2725 "htl cache: removed {n} {} from {}",
2726 if n == 1 { "entry" } else { "entries" },
2727 dir.display()
2728 );
2729 Ok(ExitCode::SUCCESS)
2730}
2731
2732fn cache_root(path: Option<&Path>) -> Result<PathBuf> {
2735 let start = path.unwrap_or(Path::new("."));
2736 let model = htl::model::Project::find_root(start)?.map(|r| r.root);
2737 Ok(model.unwrap_or_else(|| std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."))))
2738}
2739
2740fn cmd_cache_status(path: Option<&Path>, json: bool, list_entries: bool) -> Result<ExitCode> {
2746 let c = cache::describe(&cache_root(path)?);
2747 if json {
2748 report::emit(&c)?;
2749 return Ok(ExitCode::SUCCESS);
2750 }
2751
2752 if c.entries.is_empty() {
2753 println!("htl cache: empty ({})", c.dir);
2754 return Ok(ExitCode::SUCCESS);
2755 }
2756 let mut by_kind: std::collections::BTreeMap<&str, (usize, u64)> = Default::default();
2757 for e in &c.entries {
2758 let slot = by_kind.entry(e.kind.as_str()).or_default();
2759 slot.0 += 1;
2760 slot.1 += e.bytes;
2761 }
2762 println!(
2763 "htl cache: {} entries, {} at {}",
2764 c.entries.len(),
2765 human_bytes(c.bytes),
2766 c.dir
2767 );
2768 for (kind, (n, bytes)) in &by_kind {
2769 let what = match *kind {
2770 cache::CHECK => "checked modules",
2771 cache::GEN => "checked and generated test files (htl test)",
2772 cache::MODULE => "generated modules (htl test / build, include_bundle!)",
2773 cache::RUN => "whole runs",
2774 _ => "entries this build cannot read",
2775 };
2776 println!(" {n:>5} {what} ({})", human_bytes(*bytes));
2777 }
2778 if let (Some(min), Some(max)) = (
2779 c.entries.iter().map(|e| e.age_secs).min(),
2780 c.entries.iter().map(|e| e.age_secs).max(),
2781 ) {
2782 println!(
2783 " last used between {} and {} ago",
2784 human_age(min),
2785 human_age(max)
2786 );
2787 }
2788 if list_entries {
2789 println!();
2790 for e in &c.entries {
2791 println!(
2792 " {:<6} {:>8} {}",
2793 e.kind,
2794 human_bytes(e.bytes),
2795 e.subjects.join(", ")
2796 );
2797 }
2798 }
2799 Ok(ExitCode::SUCCESS)
2800}
2801
2802fn human_bytes(n: u64) -> String {
2803 if n >= 1 << 20 {
2804 format!("{:.1} MB", n as f64 / (1u64 << 20) as f64)
2805 } else if n >= 1 << 10 {
2806 format!("{:.0} KB", n as f64 / (1u64 << 10) as f64)
2807 } else {
2808 format!("{n} B")
2809 }
2810}
2811
2812fn human_age(secs: u64) -> String {
2813 match secs {
2814 s if s < 90 => format!("{s}s"),
2815 s if s < 5400 => format!("{}m", s / 60),
2816 s if s < 172_800 => format!("{}h", s / 3600),
2817 s => format!("{}d", s / 86_400),
2818 }
2819}
2820
2821fn patched_files(model: Option<&htl::model::Project>, files: &[PathBuf]) -> usize {
2827 let Some(model) = model else {
2828 return 0;
2829 };
2830 if !model
2831 .modules
2832 .iter()
2833 .any(|m| m.owner == htl::model::Owner::Patched)
2834 {
2835 return 0;
2836 }
2837 files
2838 .iter()
2839 .filter(|f| {
2840 model
2841 .home_of(f)
2842 .is_some_and(|m| m.owner == htl::model::Owner::Patched)
2843 })
2844 .count()
2845}
2846
2847fn report_check(
2856 out: &mut report::Out,
2857 json: bool,
2858 rep: &project::Report,
2859 policy: &htl::verdict::Policy,
2860 patched: usize,
2861) -> Result<bool> {
2862 let (files, replayed) = (rep.files.len(), rep.replayed);
2863 let (errors, warnings, lints) = (rep.errors, rep.warnings, rep.lints);
2864 let strict = policy.strict;
2865 let fail = htl::verdict::verdict(&rep.findings(), policy);
2866 let all_cached = rep.all_cached();
2867 if json {
2868 report::emit(&report::CheckReport {
2869 files,
2870 patched,
2871 diagnostics: out.take(),
2872 summary: report::CheckSummary {
2873 errors,
2874 warnings,
2875 lints,
2876 denied: rep.denied,
2877 strict,
2878 ok: !fail,
2879 cached: all_cached,
2880 replayed,
2881 },
2882 })?;
2883 } else {
2884 let cached = if all_cached {
2886 " [cached]".to_string()
2887 } else if replayed > 0 {
2888 format!(" [{replayed}/{files} cached]")
2889 } else {
2890 String::new()
2891 };
2892 let denied = match rep.denied {
2897 0 => String::new(),
2898 n => format!(", {n} at deny"),
2899 };
2900 let counted = match patched {
2904 0 => format!("{files} file(s)"),
2905 n => format!("{} file(s) + {n} in patched dependencies", files - n),
2906 };
2907 for rule in out.rules_said() {
2912 if htl::lint::explained(rule).is_some() {
2913 eprintln!("htl check --explain {rule}");
2914 }
2915 }
2916 eprintln!(
2917 "htl check: {counted}, {errors} error(s), {warnings} warning(s), {lints} lint(s){denied}{}{cached}",
2918 if strict { " [strict]" } else { "" }
2919 );
2920 }
2921 Ok(fail)
2922}
2923
2924fn cmd_gen(file: &Path, out: Option<&Path>) -> Result<ExitCode> {
2925 let h = Htl::new()?;
2926 auto_dts(file)?;
2927 let cfg = load_config(file)?;
2931 config_lints(&h, &cfg)?;
2932 config_lang(&h, &cfg)?;
2933 let model = apply_model(&h, &cfg, file)?;
2934 project::file_view(&h, model.as_ref(), file)?;
2935 h.install_std()?;
2936 let (code, c) = h.gen_lua(file)?;
2937 text_sink().checkinfo(&c);
2938 let (Some(code), false) = (code, runs_fail(&c)) else {
2941 return Ok(ExitCode::FAILURE);
2942 };
2943 match out {
2947 Some(p) => fs::write(p, code).with_context(|| format!("writing {}", p.display()))?,
2948 None => print!("{code}"),
2949 }
2950 Ok(ExitCode::SUCCESS)
2951}
2952
2953fn cmd_run(file: &Path, args: &[String]) -> Result<ExitCode> {
2954 let bytes = fs::read(file).with_context(|| format!("reading {}", file.display()))?;
2955 let h = Htl::new()?;
2956 auto_dts(file)?;
2957 let cfg = load_config(file)?;
2962 config_lints(&h, &cfg)?;
2963 config_lang(&h, &cfg)?;
2964 h.configure_async(async_config(&cfg))?;
2965 let model = apply_model(&h, &cfg, file)?;
2966 h.install_test_lib()?;
2967 h.install_std()?;
2968 h.install_task_lib()?;
2969 if Bundle::is_bundle(&bytes) {
2970 let b = Bundle::decode(&bytes)?;
2971 let main = h.load_bundle(&b, args)?;
2974 return run_root(&h, Entry::Main(main), args);
2975 }
2976 project::file_view(&h, model.as_ref(), file)?;
2978 h.install_searcher()?;
2979 h.set_arg(&file.to_string_lossy(), args)?;
2980 let (code, c) = h.gen_lua(file)?;
2981 text_sink().checkinfo(&c);
2982 let (Some(code), false) = (code, runs_fail(&c)) else {
2984 return Ok(ExitCode::FAILURE);
2985 };
2986 run_root(
2987 &h,
2988 Entry::Chunk {
2989 code,
2990 name: format!("@{}", file.display()),
2991 },
2992 args,
2993 )
2994}
2995
2996enum Entry {
2998 Chunk { code: String, name: String },
2999 Main(htl::mlua::Function),
3000}
3001
3002fn async_config(cfg: &project::Config) -> &htl::config::AsyncConfig {
3004 static DEFAULT: htl::config::AsyncConfig = htl::config::AsyncConfig {
3005 grace_ms: None,
3006 preempt: None,
3007 };
3008 match cfg {
3009 Some((_, _, c)) => &c.async_,
3010 None => &DEFAULT,
3011 }
3012}
3013
3014fn run_root(h: &Htl, entry: Entry, args: &[String]) -> Result<ExitCode> {
3031 let token = htl::mlua_isle::runtime::CancelToken::new();
3032 {
3033 let token = token.clone();
3034 std::thread::Builder::new()
3035 .name("htl-ctrl-c".into())
3036 .spawn(move || {
3037 let Ok(rt) = tokio::runtime::Builder::new_current_thread()
3038 .enable_all()
3039 .build()
3040 else {
3041 return;
3042 };
3043 rt.block_on(async {
3044 if tokio::signal::ctrl_c().await.is_ok() {
3045 token.cancel();
3046 }
3047 if tokio::signal::ctrl_c().await.is_ok() {
3048 std::process::exit(130);
3049 }
3050 });
3051 })
3052 .context("starting the Ctrl-C watcher")?;
3053 }
3054 let rt = tokio::runtime::Builder::new_current_thread()
3055 .enable_all()
3056 .build()
3057 .context("building the executor's runtime")?;
3058 let local = tokio::task::LocalSet::new();
3059 let out = local.block_on(&rt, async {
3060 match entry {
3061 Entry::Chunk { code, name } => h.run_async(&code, &name, args, &token).await,
3062 Entry::Main(main) => {
3063 let va: htl::mlua::Variadic<String> = args.iter().cloned().collect();
3064 h.call_async(main, va, &token).await.map(|_| ())
3065 }
3066 }
3067 });
3068 Ok(match out {
3069 Ok(()) => ExitCode::SUCCESS,
3070 Err(e) if htl::is_cancelled(&e) => {
3071 eprintln!("htl run: interrupted");
3072 ExitCode::from(130)
3073 }
3074 Err(e) => {
3075 eprintln!("{}", htl::developer_message(&e));
3076 ExitCode::FAILURE
3077 }
3078 })
3079}
3080
3081fn runs_fail(c: &htl::CheckInfo) -> bool {
3085 htl::verdict::verdict(
3086 &htl::verdict::Findings {
3087 errors: c.errors.len(),
3088 warnings: c.warnings.len(),
3089 lints: c.lints.len(),
3090 denied: 0,
3091 },
3092 &htl::verdict::Policy::ERRORS_ONLY,
3093 )
3094}
3095
3096struct BuildCache {
3101 use_cache: bool,
3102 explain: bool,
3103}
3104
3105fn cmd_build(
3106 entry: &Path,
3107 out: &Path,
3108 main: &str,
3109 mut opts: htl::link::LinkOptions,
3110 cache_flags: BuildCache,
3111) -> Result<ExitCode> {
3112 let h = Htl::new()?;
3113 auto_dts(entry)?;
3114 h.install_std()?;
3118 let cfg = load_config(entry)?;
3119 let lints = config_lints(&h, &cfg)?;
3122 config_lang(&h, &cfg)?;
3123 let policy = htl::verdict::Policy::resolve(cfg.as_ref().map(|(_, _, c)| c), false);
3124 let model = apply_model(&h, &cfg, entry)?;
3125 if let Some(m) = &model {
3129 opts.host.extend(m.provided().map(|(n, _)| n.to_string()));
3130 }
3131 if let Some((_, _, cfg)) = &cfg {
3132 opts.extra.extend(cfg.build.extra.iter().cloned());
3133 opts.host.extend(cfg.build.host.iter().cloned());
3134 if let Some(t) = cfg.build.target.filter(|t| *t != BuildTarget::Hb) {
3140 eprintln!(
3141 "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.",
3142 t.name(),
3143 t.runs_it()
3144 );
3145 return Ok(ExitCode::FAILURE);
3146 }
3147 }
3148 if entry.is_dir() {
3149 if cache_flags.explain {
3150 eprintln!("htl cache: the directory form of `htl build` is not cached");
3151 }
3152 let skip = project::not_walked(
3155 model.as_ref(),
3156 &[entry.to_path_buf()],
3157 htl::model::Purpose::Check,
3158 );
3159 return cmd_build_dir(&h, entry, out, main, &opts, &skip, &cfg);
3160 }
3161 project::file_view(&h, model.as_ref(), entry)?;
3162 opts.entry_name = model.as_ref().and_then(|m| m.locate(entry).map(|p| p.name));
3165 let root = project::store_root(model.as_ref());
3171 let spec = cfg
3172 .as_ref()
3173 .map(|(_, _, c)| c.lint_spec())
3174 .unwrap_or_default();
3175 let lint = (!spec.is_empty()).then_some(spec.as_str());
3176 let cache_opts = project::cache_options(
3177 cache_flags.use_cache,
3178 Some(cache::Mode::PerModule),
3179 &cfg,
3180 cache_flags.explain,
3181 );
3182 let store = project::with_model(
3183 project::store(&root, cache_opts, None, "htl build"),
3184 model.as_ref(),
3185 );
3186 let link_store = store.as_ref().map(|c| htl::link::LinkStore {
3187 cache: c,
3188 lint,
3189 root: &root,
3190 config: cfg.as_ref().map(|(_, p, c)| (p.as_path(), c)),
3191 });
3192 let linked = htl::link::link_with(&h, entry, &opts, link_store)?;
3193 project::explain_cache(store.as_ref(), cache_opts);
3194 let mut sink = text_sink();
3197 sink.judge_by(lints.selection());
3198 for (p, c) in &linked.checks {
3199 sink.checkinfo(&linked.reported(p, c));
3200 }
3201 let n_err = linked.errors.len();
3202 let found = htl::verdict::Findings {
3203 errors: n_err,
3204 warnings: linked.checks.iter().map(|(_, c)| c.warnings.len()).sum(),
3205 lints: linked.lints.len(),
3206 denied: sink.denied(),
3207 };
3208 for d in &linked.link_errors {
3211 sink.diagnostic(d);
3212 }
3213 if htl::verdict::verdict(&found, &policy) {
3214 eprintln!(
3215 "htl build: {n_err} error(s){}, bundle not written",
3216 judged(&found, &policy)
3217 );
3218 return Ok(ExitCode::FAILURE);
3219 }
3220 let buf = linked.bundle()?.encode();
3221 fs::write(out, &buf).with_context(|| format!("writing {}", out.display()))?;
3222 let typed = linked.modules.iter().filter(|m| m.typed).count();
3223 let cached = if typed > 0 && linked.cached == typed {
3226 " [cached]".to_string()
3227 } else if linked.cached > 0 {
3228 format!(" [{}/{typed} cached]", linked.cached)
3229 } else {
3230 String::new()
3231 };
3232 eprintln!(
3233 "htl build: {} module(s) ({typed} typed, {} lua) -> {} ({} bytes{}{}){cached}",
3234 linked.modules.len(),
3235 linked.modules.len() - typed,
3236 out.display(),
3237 buf.len(),
3238 if opts.source {
3239 ", source"
3240 } else {
3241 ", bytecode"
3242 },
3243 if opts.debug { " with debug info" } else { "" }
3244 );
3245 if !linked.host_modules.is_empty() {
3246 eprintln!(
3247 "htl build: host must provide: {}",
3248 linked.host_modules.join(", ")
3249 );
3250 }
3251 Ok(ExitCode::SUCCESS)
3252}
3253
3254fn cmd_build_dir(
3256 h: &Htl,
3257 dir: &Path,
3258 out: &Path,
3259 entry: &str,
3260 opts: &htl::link::LinkOptions,
3261 skip: &[PathBuf],
3262 cfg: &project::Config,
3263) -> Result<ExitCode> {
3264 let lints = config_lints(h, cfg)?;
3266 config_lang(h, cfg)?;
3267 let policy = &htl::verdict::Policy::resolve(cfg.as_ref().map(|(_, _, c)| c), false);
3268 h.add_path(dir)?;
3269 let files = htl::collect_tl_skipping(&[dir.to_path_buf()], skip)?;
3270 let mut b = Bundle {
3271 entry: entry.to_string(),
3272 htl_version: env!("CARGO_PKG_VERSION").into(),
3273 ..Default::default()
3274 };
3275 let mut found = htl::verdict::Findings::default();
3276 let mut sink = text_sink();
3277 sink.judge_by(lints.selection());
3278 for f in &files {
3279 let rel = f.strip_prefix(dir).unwrap_or(f);
3281 let name = htl::naming::name_of("", rel)
3282 .with_context(|| format!("cannot derive a module name for {}", f.display()))?;
3283 let (code, c) = h.gen_lua(f)?;
3284 sink.checkinfo(&c);
3285 found.errors += c.errors.len();
3286 found.warnings += c.warnings.len();
3287 found.lints += c.lints.len();
3288 let Some(code) = code else { continue };
3289 let (kind, payload) = if opts.source {
3290 (htl::bundle::Kind::Source, code.into_bytes())
3291 } else {
3292 (
3293 htl::bundle::Kind::Bytecode,
3294 h.compile_with(&name, &code, !opts.debug)?,
3295 )
3296 };
3297 b.modules.push(htl::bundle::Module {
3298 name,
3299 kind,
3300 payload,
3301 });
3302 }
3303 found.denied = sink.denied();
3304 if htl::verdict::verdict(&found, policy) {
3305 eprintln!(
3306 "htl build: {} error(s){}, bundle not written",
3307 found.errors,
3308 judged(&found, policy)
3309 );
3310 return Ok(ExitCode::FAILURE);
3311 }
3312 if b.module(entry).is_none() {
3313 bail!(
3314 "entry module '{entry}' not found among {} module(s)",
3315 b.modules.len()
3316 );
3317 }
3318 if !opts.source {
3319 b.fingerprint = h.fingerprint()?;
3320 }
3321 let buf = b.encode();
3322 fs::write(out, &buf).with_context(|| format!("writing {}", out.display()))?;
3323 eprintln!(
3324 "htl build: {} module(s) -> {} ({} bytes)",
3325 b.modules.len(),
3326 out.display(),
3327 buf.len()
3328 );
3329 Ok(ExitCode::SUCCESS)
3330}
3331
3332#[derive(serde::Serialize)]
3339struct BundleInfo {
3340 file: String,
3341 format: u8,
3342 htl_version: Option<String>,
3343 payload: &'static str,
3345 lua: Option<htl::bundle::LuaHeader>,
3346 entry: String,
3347 modules: Vec<BundleModuleInfo>,
3348 host_modules: Vec<String>,
3349}
3350
3351#[derive(serde::Serialize)]
3352struct BundleModuleInfo {
3353 name: String,
3354 kind: &'static str,
3355 bytes: usize,
3356}
3357
3358fn cmd_bundle_info(file: &Path, json: bool) -> Result<ExitCode> {
3359 let bytes = fs::read(file).with_context(|| format!("reading {}", file.display()))?;
3360 let Some(format) = htl::bundle::format_version(&bytes) else {
3361 bail!("{} is not an htl bundle (bad magic)", file.display());
3362 };
3363 let b = Bundle::decode(&bytes)?;
3364 let kind_name = |k: htl::bundle::Kind| match k {
3365 htl::bundle::Kind::Bytecode => "bytecode",
3366 htl::bundle::Kind::Source => "source",
3367 };
3368 let payload = match (
3369 b.modules
3370 .iter()
3371 .any(|m| m.kind == htl::bundle::Kind::Bytecode),
3372 b.modules
3373 .iter()
3374 .any(|m| m.kind == htl::bundle::Kind::Source),
3375 ) {
3376 (true, true) => "mixed",
3377 (false, true) => "source",
3378 _ => "bytecode",
3380 };
3381 let info = BundleInfo {
3382 file: file.display().to_string(),
3383 format,
3384 htl_version: (!b.htl_version.is_empty()).then(|| b.htl_version.clone()),
3385 payload,
3386 lua: htl::bundle::LuaHeader::parse(&b.fingerprint),
3387 entry: b.entry.clone(),
3388 modules: b
3389 .modules
3390 .iter()
3391 .map(|m| BundleModuleInfo {
3392 name: m.name.clone(),
3393 kind: kind_name(m.kind),
3394 bytes: m.payload.len(),
3395 })
3396 .collect(),
3397 host_modules: b.host_modules.clone(),
3398 };
3399 if json {
3400 report::emit(&info)?;
3401 return Ok(ExitCode::SUCCESS);
3402 }
3403
3404 println!(
3405 "{}: htl bundle, format {}, built by {}",
3406 info.file,
3407 info.format,
3408 match &info.htl_version {
3409 Some(v) => format!("htl {v}"),
3410 None => "htl (version not recorded)".to_string(),
3411 }
3412 );
3413 println!(" payload: {}", info.payload);
3414 let lua = match &info.lua {
3415 Some(h) => h.to_string(),
3416 None if !b.fingerprint.is_empty() => {
3417 format!("unreadable fingerprint ({} bytes)", b.fingerprint.len())
3418 }
3419 None if info.format == 1 => {
3420 "not recorded (a format 1 bundle carries no fingerprint)".into()
3421 }
3422 None => "any (source payload, no bytecode to bind)".into(),
3423 };
3424 println!(" lua: {lua}");
3425 println!(" entry: {}", info.entry);
3426 let modules: Vec<String> = info
3427 .modules
3428 .iter()
3429 .map(|m| {
3430 if info.payload == "mixed" {
3431 format!("{} ({})", m.name, m.kind)
3432 } else {
3433 m.name.clone()
3434 }
3435 })
3436 .collect();
3437 println!(
3438 " modules: {}",
3439 if modules.is_empty() {
3440 "(none)".to_string()
3441 } else {
3442 modules.join(", ")
3443 }
3444 );
3445 println!(
3446 " host: {}",
3447 if info.host_modules.is_empty() {
3448 "(none)".to_string()
3449 } else {
3450 info.host_modules.join(", ")
3451 }
3452 );
3453 Ok(ExitCode::SUCCESS)
3454}