@ryanatkn/gro 0.129.4 → 0.129.6

package/src/lib/input_path.test.ts

@@ -0,0 +1,230 @@
+import {test} from 'uvu';
+import * as assert from 'uvu/assert';
+import {resolve} from 'node:path';
+
+import {
+	to_input_path,
+	to_input_paths,
+	resolve_input_files,
+	get_possible_paths,
+	type Resolved_Input_Path,
+	type Resolved_Input_File,
+} from './input_path.js';
+import {GRO_DIST_DIR, paths} from './paths.js';
+import type {Resolved_Path} from './path.js';
+
+test('to_input_path', () => {
+	assert.is(to_input_path(resolve('foo.ts')), resolve('foo.ts'));
+	assert.is(to_input_path('./foo.ts'), resolve('foo.ts'));
+	assert.is(to_input_path('foo.ts'), 'foo.ts');
+	assert.is(to_input_path('gro/foo'), GRO_DIST_DIR + 'foo');
+	// trailing slashes are preserved:
+	assert.is(to_input_path(resolve('foo/bar/')), resolve('foo/bar/'));
+	assert.is(to_input_path('./foo/bar/'), resolve('foo/bar/'));
+	assert.is(to_input_path('foo/bar/'), 'foo/bar/');
+});
+
+test('to_input_paths', () => {
+	assert.equal(to_input_paths([resolve('foo/bar.ts'), './baz', 'foo']), [
+		resolve('foo/bar.ts'),
+		resolve('baz'),
+		'foo',
+	]);
+});
+
+test('get_possible_paths with an implicit relative path', () => {
+	const input_path = 'src/foo/bar';
+	assert.equal(
+		get_possible_paths(
+			input_path,
+			[resolve('src/foo'), resolve('src/baz'), resolve('src'), resolve('.')],
+			['.ext.ts'],
+		),
+		[
+			{
+				id: resolve('src/foo/src/foo/bar'),
+				input_path: 'src/foo/bar',
+				root_dir: resolve('src/foo'),
+			},
+			{
+				id: resolve('src/foo/src/foo/bar.ext.ts'),
+				input_path: 'src/foo/bar',
+				root_dir: resolve('src/foo'),
+			},
+			{
+				id: resolve('src/baz/src/foo/bar'),
+				input_path: 'src/foo/bar',
+				root_dir: resolve('src/baz'),
+			},
+			{
+				id: resolve('src/baz/src/foo/bar.ext.ts'),
+				input_path: 'src/foo/bar',
+				root_dir: resolve('src/baz'),
+			},
+			{
+				id: resolve('src/src/foo/bar'),
+				input_path: 'src/foo/bar',
+				root_dir: resolve('src'),
+			},
+			{
+				id: resolve('src/src/foo/bar.ext.ts'),
+				input_path: 'src/foo/bar',
+				root_dir: resolve('src'),
+			},
+			{
+				id: resolve('src/foo/bar'),
+				input_path: 'src/foo/bar',
+				root_dir: resolve('.'),
+			},
+			{
+				id: resolve('src/foo/bar.ext.ts'),
+				input_path: 'src/foo/bar',
+				root_dir: resolve('.'),
+			},
+		],
+	);
+});
+
+test('get_possible_paths in the gro directory', () => {
+	const input_path = resolve('src/foo/bar');
+	assert.equal(get_possible_paths(input_path, [], ['.ext.ts']), [
+		{id: input_path, input_path: resolve('src/foo/bar'), root_dir: resolve('src/foo')},
+		{id: input_path + '.ext.ts', input_path: resolve('src/foo/bar'), root_dir: resolve('src/foo')},
+	]);
+});
+
+test('get_possible_paths does not repeat the extension', () => {
+	const input_path = resolve('src/foo/bar.ext.ts');
+	assert.equal(get_possible_paths(input_path, [], ['.ext.ts']), [
+		{id: input_path, input_path: resolve('src/foo/bar.ext.ts'), root_dir: resolve('src/foo')},
+	]);
+});
+
+test('get_possible_paths does not repeat with the same root directory', () => {
+	const input_path = resolve('src/foo/bar.ext.ts');
+	assert.equal(get_possible_paths(input_path, [paths.root, paths.root], ['.ext.ts']), [
+		{id: input_path, input_path: resolve('src/foo/bar.ext.ts'), root_dir: resolve('src/foo')},
+	]);
+});
+
+test('get_possible_paths implied to be a directory by trailing slash', () => {
+	const input_path = resolve('src/foo/bar') + '/';
+	assert.equal(get_possible_paths(input_path, [], ['.ext.ts']), [
+		{id: input_path, input_path: resolve('src/foo/bar') + '/', root_dir: resolve('src/foo')},
+	]);
+});
+
+test('resolve_input_files', () => {
+	const test_files: Record<string, Resolved_Path[]> = {
+		'fake/test1.ext.ts': [
+			{id: 'fake/test1.ext.ts', path: 'fake/test1.ext.ts', is_directory: false},
+		],
+		'fake/test2.ext.ts': [
+			{id: 'fake/test2.ext.ts', path: 'fake/test2.ext.ts', is_directory: false},
+		],
+		'fake/test3': [
+			{id: 'fake/test3', path: 'fake/test3', is_directory: true},
+			{id: 'a.ts', path: 'a.ts', is_directory: false},
+			{id: 'b.ts', path: 'b.ts', is_directory: false},
+		],
+		// duplicate
+		'fake/': [
+			{id: 'fake/test3', path: 'fake/test3', is_directory: true},
+			{id: 'test3/a.ts', path: 'test3/a.ts', is_directory: false},
+		],
+		// duplicate and not
+		fake: [
+			{id: 'fake/test3', path: 'fake/test3', is_directory: true},
+			{id: 'test3/a.ts', path: 'test3/a.ts', is_directory: false},
+			{id: 'test3/c.ts', path: 'test3/c.ts', is_directory: false},
+		],
+		'fake/nomatches': [{id: 'fake/nomatches', path: 'fake/nomatches', is_directory: true}],
+		fake2: [{id: 'test.ext.ts', path: 'test.ext.ts', is_directory: false}],
+	};
+	const a: Resolved_Input_Path = {
+		id: 'fake/test1.ext.ts',
+		is_directory: false,
+		input_path: 'fake/test1.ext.ts',
+		root_dir: process.cwd(),
+	};
+	const b: Resolved_Input_Path = {
+		id: 'fake/test2.ext.ts',
+		is_directory: false,
+		input_path: 'fake/test2',
+		root_dir: process.cwd(),
+	};
+	const c: Resolved_Input_Path = {
+		id: 'fake/test3',
+		is_directory: true,
+		input_path: 'fake/test3',
+		root_dir: process.cwd(),
+	};
+	const d: Resolved_Input_Path = {
+		id: 'fake',
+		is_directory: true,
+		input_path: 'fake',
+		root_dir: process.cwd(),
+	};
+	const e: Resolved_Input_Path = {
+		id: 'fake/nomatches',
+		is_directory: true,
+		input_path: 'fake/nomatches',
+		root_dir: process.cwd(),
+	};
+	// These two have the same id from different directory input paths.
+	const f: Resolved_Input_Path = {
+		id: 'fake2',
+		is_directory: true,
+		input_path: 'fake2',
+		root_dir: process.cwd(),
+	};
+	const g: Resolved_Input_Path = {
+		id: 'fake2',
+		is_directory: true,
+		input_path: './fake2/',
+		root_dir: process.cwd(),
+	};
+	// These two have the same id from different file input paths.
+	const h: Resolved_Input_Path = {
+		id: 'fake3/test.ext.ts',
+		is_directory: false,
+		input_path: 'fake3/test.ext.ts',
+		root_dir: process.cwd(),
+	};
+	const i: Resolved_Input_Path = {
+		id: 'fake3/test.ext.ts',
+		is_directory: false,
+		input_path: 'fake3/test',
+		root_dir: process.cwd(),
+	};
+	const result = resolve_input_files([a, b, c, d, e, f, g, h, i], (dir) => test_files[dir]);
+	const resolved_input_files: Resolved_Input_File[] = [
+		{id: a.id, input_path: a.input_path, resolved_input_path: a},
+		{id: b.id, input_path: b.input_path, resolved_input_path: b},
+		{id: 'fake/test3/a.ts', input_path: c.input_path, resolved_input_path: c},
+		{id: 'fake/test3/b.ts', input_path: c.input_path, resolved_input_path: c},
+		{id: 'fake/test3/c.ts', input_path: d.input_path, resolved_input_path: d},
+		{id: 'fake2/test.ext.ts', input_path: f.input_path, resolved_input_path: f},
+		{id: 'fake3/test.ext.ts', input_path: h.input_path, resolved_input_path: h},
+	];
+	assert.equal(result, {
+		resolved_input_files,
+		resolved_input_files_by_root_dir: new Map([
+			[
+				process.cwd(),
+				[
+					{id: 'fake/test1.ext.ts', input_path: a.input_path, resolved_input_path: a},
+					{id: 'fake/test2.ext.ts', input_path: b.input_path, resolved_input_path: b},
+					{id: 'fake/test3/a.ts', input_path: c.input_path, resolved_input_path: c},
+					{id: 'fake/test3/b.ts', input_path: c.input_path, resolved_input_path: c},
+					{id: 'fake/test3/c.ts', input_path: d.input_path, resolved_input_path: d},
+					{id: 'fake2/test.ext.ts', input_path: f.input_path, resolved_input_path: f},
+					{id: 'fake3/test.ext.ts', input_path: h.input_path, resolved_input_path: h},
+				],
+			],
+		]),
+		input_directories_with_no_files: [e.input_path],
+	});
+});
+
+test.run();

package/src/lib/input_path.ts

@@ -0,0 +1,255 @@
+import {dirname, isAbsolute, join, resolve} from 'node:path';
+import {existsSync, statSync} from 'node:fs';
+import {strip_start} from '@ryanatkn/belt/string.js';
+import {z} from 'zod';
+import type {Flavored} from '@ryanatkn/belt/types.js';
+
+import {GRO_PACKAGE_DIR, GRO_DIST_DIR} from './paths.js';
+import type {Path_Info, Path_Id, Resolved_Path} from './path.js';
+import {search_fs} from './search_fs.js';
+import {TASK_FILE_SUFFIX_JS} from './task.js';
+
+// TODO Flavored doesn't work when used in schemas, use Zod brand instead? problem is ergonomics
+export const Input_Path = z.string();
+export type Input_Path = Flavored<z.infer<typeof Input_Path>, 'Input_Path'>;
+
+export const Raw_Input_Path = z.string();
+export type Raw_Input_Path = Flavored<z.infer<typeof Raw_Input_Path>, 'Raw_Input_Path'>;
+
+/**
+ * Raw input paths are paths that users provide to Gro to reference files for tasks and gen.
+ *
+ * A raw input path can be to a file or directory in the following forms:
+ *
+ * - an absolute path, preserved
+ * - an explicit relative path, e.g. `./src/foo`, resolved to `root_path` which defaults to the cwd
+ * - an implicit relative path, e.g. `src/foo`, preserved
+ * - an implicit relative path prefixed with `gro/`, transformed to absolute in the Gro directory
+ *
+ * Thus, input paths are either absolute or implicitly relative.
+ */
+export const to_input_path = (
+	raw_input_path: Raw_Input_Path,
+	root_path = process.cwd(), // TODO @multiple isn't passed in anywhere, maybe hoist to `invoke_task` and others
+): Input_Path => {
+	if (raw_input_path.startsWith(GRO_PACKAGE_DIR)) {
+		return GRO_DIST_DIR + strip_start(raw_input_path, GRO_PACKAGE_DIR);
+	} else if (raw_input_path[0] === '.') {
+		return resolve(root_path, raw_input_path);
+	}
+	return raw_input_path as Input_Path;
+};
+
+export const to_input_paths = (
+	raw_input_paths: Raw_Input_Path[],
+	root_path?: string, // TODO @multiple isn't passed in anywhere, maybe hoist to `invoke_task` and others
+): Input_Path[] => raw_input_paths.map((p) => to_input_path(p, root_path));
+
+export interface Possible_Path {
+	id: Path_Id;
+	input_path: Input_Path;
+	root_dir: Path_Id;
+}
+
+/**
+ * Gets a list of possible source ids for each input path with `extensions`,
+ * duplicating each under `root_dirs`, without checking the filesystem.
+ */
+export const get_possible_paths = (
+	input_path: Input_Path,
+	root_dirs: Path_Id[],
+	extensions: string[],
+): Possible_Path[] => {
+	const possible_paths: Set<Possible_Path> = new Set();
+
+	const add_possible_paths = (path: string, root_dir: Path_Id) => {
+		// Specifically for paths to the Gro package dist, optimize by only looking for `.task.js`.
+		if (path.startsWith(GRO_DIST_DIR)) {
+			possible_paths.add({
+				id: (path.endsWith('/') || path.endsWith(TASK_FILE_SUFFIX_JS)
+					? path
+					: path + TASK_FILE_SUFFIX_JS) as Path_Id,
+				input_path,
+				root_dir,
+			});
+		} else {
+			possible_paths.add({id: path as Path_Id, input_path, root_dir});
+			if (!path.endsWith('/') && !extensions.some((e) => path.endsWith(e))) {
+				for (const extension of extensions) {
+					possible_paths.add({id: path + extension, input_path, root_dir});
+				}
+			}
+		}
+	};
+
+	if (isAbsolute(input_path)) {
+		// TODO this is hacky because it's the only place we're using sync fs calls (even if they're faster, it's oddly inconsistent),
+		// we probably should just change this function to check the filesystem and not return non-existing paths
+		add_possible_paths(
+			input_path,
+			existsSync(input_path) && statSync(input_path).isDirectory()
+				? input_path
+				: dirname(input_path),
+		);
+	} else {
+		for (const root_dir of root_dirs) {
+			add_possible_paths(join(root_dir, input_path), root_dir);
+		}
+	}
+	return Array.from(possible_paths);
+};
+
+export interface Resolved_Input_Path {
+	input_path: Input_Path;
+	id: Path_Id;
+	is_directory: boolean;
+	root_dir: Path_Id;
+}
+
+export interface Resolved_Input_File {
+	id: Path_Id;
+	input_path: Input_Path;
+	resolved_input_path: Resolved_Input_Path;
+}
+
+export interface Resolved_Input_Paths {
+	resolved_input_paths: Resolved_Input_Path[];
+	possible_paths_by_input_path: Map<Input_Path, Possible_Path[]>;
+	unmapped_input_paths: Input_Path[];
+}
+
+/**
+ * Gets the path data for each input path, checking the filesystem for the possibilities
+ * and stopping at the first existing file or falling back to the first existing directory.
+ * If none is found for an input path, it's added to `unmapped_input_paths`.
+ */
+export const resolve_input_paths = (
+	input_paths: Input_Path[],
+	root_dirs: Path_Id[],
+	extensions: string[],
+): Resolved_Input_Paths => {
+	const resolved_input_paths: Resolved_Input_Path[] = [];
+	const possible_paths_by_input_path: Map<Input_Path, Possible_Path[]> = new Map();
+	const unmapped_input_paths: Input_Path[] = [];
+	for (const input_path of input_paths) {
+		let found_file: [Path_Info, Possible_Path] | null = null;
+		let found_dirs: Array<[Path_Info, Possible_Path]> | null = null;
+		const possible_paths = get_possible_paths(input_path, root_dirs, extensions);
+		possible_paths_by_input_path.set(input_path, possible_paths);
+
+		// Find the first existing file path or fallback to the first directory path.
+		for (const possible_path of possible_paths) {
+			if (!existsSync(possible_path.id)) continue;
+			const stats = statSync(possible_path.id);
+			if (stats.isDirectory()) {
+				found_dirs ??= [];
+				found_dirs.push([{id: possible_path.id, is_directory: stats.isDirectory()}, possible_path]);
+			} else {
+				found_file = [{id: possible_path.id, is_directory: stats.isDirectory()}, possible_path];
+				break;
+			}
+		}
+		if (found_file) {
+			resolved_input_paths.push({
+				input_path,
+				id: found_file[0].id,
+				is_directory: found_file[0].is_directory,
+				root_dir: found_file[1].root_dir,
+			});
+		} else if (found_dirs) {
+			for (const found_dir of found_dirs) {
+				resolved_input_paths.push({
+					input_path,
+					id: found_dir[0].id,
+					is_directory: found_dir[0].is_directory,
+					root_dir: found_dir[1].root_dir,
+				});
+			}
+		} else {
+			unmapped_input_paths.push(input_path);
+		}
+	}
+	return {
+		resolved_input_paths,
+		possible_paths_by_input_path,
+		unmapped_input_paths,
+	};
+};
+
+export interface Resolved_Input_Files {
+	resolved_input_files: Resolved_Input_File[];
+	resolved_input_files_by_root_dir: Map<Path_Id, Resolved_Input_File[]>;
+	input_directories_with_no_files: Input_Path[];
+}
+
+/**
+ * Finds all of the matching files for the given input paths.
+ * De-dupes source ids.
+ */
+export const resolve_input_files = (
+	resolved_input_paths: Resolved_Input_Path[],
+	search: (dir: string) => Resolved_Path[] = search_fs,
+): Resolved_Input_Files => {
+	const resolved_input_files: Resolved_Input_File[] = [];
+	// Add all input paths initially, and remove each when resolved to a file.
+	const existing_path_ids: Set<Path_Id> = new Set();
+
+	let remaining = resolved_input_paths.slice();
+	const handle_found = (input_path: Input_Path, id: Path_Id) => {
+		remaining = remaining.filter(
+			(r) => !(r.id === id || r.input_path === input_path || r.input_path === id), // `r.input_path === id` may be unnecessary
+		);
+	};
+
+	// TODO parallelize but would need to de-dupe and retain order
+	for (const resolved_input_path of resolved_input_paths) {
+		const {input_path, id, is_directory} = resolved_input_path;
+		if (is_directory) {
+			// Handle input paths that resolve to directories.
+			const files = search(id);
+			if (!files.length) continue;
+			const path_ids: Path_Id[] = [];
+			for (const {path, is_directory} of files) {
+				if (is_directory) continue;
+				const path_id = join(id, path);
+				if (!existing_path_ids.has(path_id)) {
+					existing_path_ids.add(path_id);
+					path_ids.push(path_id);
+				}
+				handle_found(input_path, path_id);
+			}
+			if (!path_ids.length) continue;
+			const resolved_input_files_for_input_path: Resolved_Input_File[] = [];
+			for (const path_id of path_ids) {
+				const resolved_input_file: Resolved_Input_File = {
+					id: path_id,
+					input_path,
+					resolved_input_path,
+				};
+				resolved_input_files.push(resolved_input_file);
+				resolved_input_files_for_input_path.push(resolved_input_file);
+			}
+		} else {
+			if (!existing_path_ids.has(id)) {
+				// Handle input paths that resolve to files.
+				existing_path_ids.add(id);
+				const resolved_input_file: Resolved_Input_File = {id, input_path, resolved_input_path};
+				resolved_input_files.push(resolved_input_file);
+			}
+			handle_found(input_path, id);
+		}
+	}
+	return {
+		resolved_input_files,
+		resolved_input_files_by_root_dir: resolved_input_files.reduce((map, resolved_input_file) => {
+			const {root_dir} = resolved_input_file.resolved_input_path;
+			if (map.has(root_dir)) {
+				map.get(root_dir)!.push(resolved_input_file);
+			} else {
+				map.set(root_dir, [resolved_input_file]);
+			}
+			return map;
+		}, new Map<Path_Id, Resolved_Input_File[]>()),
+		input_directories_with_no_files: remaining.map((r) => r.input_path),
+	};
+};

package/src/lib/invoke.ts

@@ -0,0 +1,27 @@
+import {attach_process_error_handlers} from '@ryanatkn/belt/process.js';
+
+import {invoke_task} from './invoke_task.js';
+import {to_task_args} from './args.js';
+import {load_config} from './config.js';
+import {sveltekit_sync_if_obviously_needed} from './sveltekit_helpers.js';
+
+/*
+
+This module invokes the Gro CLI which in turn invokes tasks.
+Tasks are the CLI's primary concept.
+To learn more about them, see `src/lib/docs/task.md`.
+
+When the CLI is invoked it passes the first CLI arg as `task_name` to `invoke_task`,
+and the rest of the args are forwarded to the task's `run` function.
+
+*/
+
+// handle uncaught errors
+attach_process_error_handlers((err) =>
+	err?.constructor?.name === 'Task_Error' ? 'Task_Error' : null,
+);
+
+await sveltekit_sync_if_obviously_needed();
+
+const {task_name, args} = to_task_args();
+await invoke_task(task_name, args, await load_config());

package/src/lib/invoke_task.ts

@@ -0,0 +1,116 @@
+import {cyan, red, gray} from '@ryanatkn/belt/styletext.js';
+import {System_Logger, print_log_label} from '@ryanatkn/belt/log.js';
+import {create_stopwatch, Timings} from '@ryanatkn/belt/timings.js';
+import {print_ms, print_timings} from '@ryanatkn/belt/print.js';
+
+import {to_forwarded_args, type Args} from './args.js';
+import {run_task} from './run_task.js';
+import {to_input_path, Raw_Input_Path} from './input_path.js';
+import {find_tasks, load_tasks} from './task.js';
+import {load_gro_package_json} from './package_json.js';
+import {log_tasks, log_error_reasons} from './task_logging.js';
+import type {Gro_Config} from './config.js';
+
+/**
+ * Invokes Gro tasks by name using the filesystem as the source.
+ *
+ * When a task is invoked,
+ * Gro first searches for tasks in the current working directory.
+ * and falls back to searching Gro's directory, if the two are different.
+ * See `src/lib/input_path.ts` for info about what "task_name" can refer to.
+ * If it matches a directory, all of the tasks within it are logged,
+ * both in the current working directory and Gro.
+ *
+ * This code is particularly hairy because
+ * we're accepting a wide range of user input
+ * and trying to do the right thing.
+ * Precise error messages are especially difficult and
+ * there are some subtle differences in the complex logical branches.
+ * The comments describe each condition.
+ *
+ * @param task_name - The name of the task to invoke.
+ * @param args - The CLI args to pass to the task.
+ * @param config - The Gro configuration.
+ * @param initial_timings - The timings to use for the top-level task, `null` for composed tasks.
+ */
+export const invoke_task = async (
+	task_name: Raw_Input_Path,
+	args: Args | undefined,
+	config: Gro_Config,
+	initial_timings: Timings | null = null,
+): Promise<void> => {
+	const log = new System_Logger(print_log_label(task_name || 'gro'));
+	log.info('invoking', task_name ? cyan(task_name) : 'gro');
+
+	const timings = initial_timings ?? new Timings();
+
+	const total_timing = create_stopwatch();
+	const finish = () => {
+		if (!initial_timings) return; // print timings only for the top-level task
+		print_timings(timings, log);
+		log.info(`🕒 ${print_ms(total_timing())}`);
+	};
+
+	// Check if the caller just wants to see the version.
+	if (!task_name && (args?.version || args?.v)) {
+		const gro_package_json = load_gro_package_json();
+		log.info(`${gray('v')}${cyan(gro_package_json.version)}`);
+		finish();
+		return;
+	}
+
+	// Resolve the input path for the provided task name.
+	const input_path = to_input_path(task_name);
+
+	const {task_root_dirs} = config;
+
+	// Find the task or directory specified by the `input_path`.
+	// Fall back to searching the Gro directory as well.
+	const found = find_tasks([input_path], task_root_dirs, config);
+	if (!found.ok) {
+		log_error_reasons(log, found.reasons);
+		process.exit(1);
+	}
+
+	// Found a match either in the current working directory or Gro's directory.
+	const found_tasks = found.value;
+	const {resolved_input_files} = found_tasks;
+
+	// Load the task module.
+	const loaded = await load_tasks(found_tasks);
+	if (!loaded.ok) {
+		log_error_reasons(log, loaded.reasons);
+		process.exit(1);
+	}
+	const loaded_tasks = loaded.value;
+
+	if (resolved_input_files.length > 1 || resolved_input_files[0].resolved_input_path.is_directory) {
+		// The input path matches a directory. Log the tasks but don't run them.
+		log_tasks(log, loaded_tasks);
+		finish();
+		return;
+	}
+
+	// The input path matches a file that's presumable a task, so load and run it.
+	if (loaded_tasks.modules.length !== 1) throw Error('expected one loaded task'); // run only one task at a time
+	const task = loaded_tasks.modules[0];
+	log.info(`→ ${cyan(task.name)} ${(task.mod.task.summary && gray(task.mod.task.summary)) ?? ''}`);
+
+	const timing_to_run_task = timings.start('run task ' + task_name);
+	const result = await run_task(
+		task,
+		{...args, ...to_forwarded_args(`gro ${task.name}`)},
+		invoke_task,
+		config,
+		timings,
+	);
+	timing_to_run_task();
+	if (!result.ok) {
+		log.info(`${red('🞩')} ${cyan(task.name)}`);
+		log_error_reasons(log, [result.reason]);
+		throw result.error;
+	}
+	log.info(`✓ ${cyan(task.name)}`);
+
+	finish();
+};

package/src/lib/lint.task.ts

@@ -0,0 +1,38 @@
+import {print_spawn_result} from '@ryanatkn/belt/process.js';
+import {z} from 'zod';
+
+import {Task_Error, type Task} from './task.js';
+import {serialize_args, to_forwarded_args} from './args.js';
+import {find_cli, spawn_cli} from './cli.js';
+
+const ESLINT_CLI = 'eslint';
+
+export const Args = z
+	.object({
+		_: z.array(z.string(), {description: 'paths to serve'}).default([]),
+		eslint_cli: z.string({description: 'the ESLint CLI to use'}).default(ESLINT_CLI),
+	})
+	.strict();
+export type Args = z.infer<typeof Args>;
+
+export const task: Task<Args> = {
+	summary: 'run eslint',
+	Args,
+	run: async ({log, args}): Promise<void> => {
+		const {_, eslint_cli} = args;
+
+		const found_eslint_cli = find_cli(eslint_cli);
+		if (!found_eslint_cli) {
+			// TODO maybe make this an option?
+			log.info('ESLint is not installed; skipping linting');
+			return;
+		}
+
+		const forwarded_args = {_, 'max-warnings': 0, ...to_forwarded_args(eslint_cli)};
+		const serialized_args = serialize_args(forwarded_args);
+		const eslintResult = await spawn_cli(found_eslint_cli, serialized_args, log);
+		if (!eslintResult?.ok) {
+			throw new Task_Error(`ESLint found some problems. ${print_spawn_result(eslintResult!)}`);
+		}
+	},
+};