@ryanatkn/gro 0.129.4 → 0.129.6

package/src/lib/docs/tasks.gen.md.ts

@@ -0,0 +1,90 @@
+import {dirname, relative, basename} from 'node:path';
+import {parse_path_parts, parse_path_segments} from '@ryanatkn/belt/path.js';
+import {strip_start} from '@ryanatkn/belt/string.js';
+
+import {type Gen, to_output_file_name} from '../gen.js';
+import {paths, base_path_to_path_id} from '../paths.js';
+import {log_error_reasons} from '../task_logging.js';
+import {find_tasks, load_tasks, Task_Error} from '../task.js';
+
+// This is the first simple implementation of Gro's automated docs.
+// It combines Gro's gen and task systems
+// to generate a markdown file with a summary of all of Gro's tasks.
+// Other projects that use Gro should be able to import this module
+// or other otherwise get frictionless access to this specific use case,
+// and they should be able to extend or customize it to any degree.
+
+// TODO display more info about each task, including a summary and params
+// TODO needs some cleanup and better APIs - paths are confusing and verbose!
+// TODO add backlinks to every document that links to this one
+
+export const gen: Gen = async ({origin_id, log, config}) => {
+	const found = find_tasks(['.'], [paths.lib], config);
+	if (!found.ok) {
+		log_error_reasons(log, found.reasons);
+		throw new Task_Error(`Failed to generate task docs: ${found.type}`);
+	}
+	const found_tasks = found.value;
+
+	const loaded = await load_tasks(found_tasks);
+	if (!loaded.ok) {
+		log_error_reasons(log, loaded.reasons);
+		throw new Task_Error(`Failed to generate task docs: ${loaded.type}`);
+	}
+	const loaded_tasks = loaded.value;
+	const tasks = loaded_tasks.modules;
+
+	const root_path = parse_path_segments(paths.root).at(-1);
+
+	const origin_dir = dirname(origin_id);
+	const origin_base = basename(origin_id);
+
+	const base_dir = paths.source;
+	const relative_path = strip_start(origin_id, base_dir);
+	const relative_dir = dirname(relative_path);
+
+	// TODO should this be passed in the context, like `defaultOutputFileName`?
+	const output_file_name = to_output_file_name(origin_base);
+
+	// TODO this is GitHub-specific
+	const root_link = `[${root_path}](/../..)`;
+
+	// TODO do we want to use absolute paths instead of relative paths,
+	// because GitHub works with them and it simplifies the code?
+	const path_parts = parse_path_parts(relative_dir).map(
+		(relative_path_part) =>
+			`[${parse_path_segments(relative_path_part).at(-1)}](${
+				relative(origin_dir, base_path_to_path_id(relative_path_part)) || './'
+			})`,
+	);
+	const breadcrumbs =
+		'> <sub>' + [root_link, ...path_parts, output_file_name].join(' / ') + '</sub>';
+
+	// TODO render the footer with the origin_id
+	return `# tasks
+
+${breadcrumbs}
+
+What is a \`Task\`? See [\`task.md\`](./task.md).
+
+## all tasks
+
+${tasks.reduce(
+	(taskList, task) =>
+		taskList +
+		`- [${task.name}](${relative(origin_dir, task.id)})${
+			task.mod.task.summary ? ` - ${task.mod.task.summary}` : ''
+		}\n`,
+	'',
+)}
+## usage
+
+\`\`\`bash
+$ gro some/name
+\`\`\`
+
+${breadcrumbs}
+
+> <sub>generated by [${origin_base}](${origin_base})</sub>
+`;
+};

package/src/lib/docs/tasks.md

@@ -0,0 +1,37 @@
+# tasks
+
+> <sub>[gro](/../..) / [lib](..) / [docs](./) / tasks.md</sub>
+
+What is a `Task`? See [`task.md`](./task.md).
+
+## all tasks
+
+- [build](../build.task.ts) - build the project
+- [changeset](../changeset.task.ts) - call changeset with gro patterns
+- [check](../check.task.ts) - check that everything is ready to commit
+- [clean](../clean.task.ts) - remove temporary dev and build files, and optionally prune git branches
+- [commit](../commit.task.ts) - commit and push to a new branch
+- [deploy](../deploy.task.ts) - deploy to a branch
+- [dev](../dev.task.ts) - start SvelteKit and other dev plugins
+- [format](../format.task.ts) - format source files
+- [gen](../gen.task.ts) - run code generation scripts
+- [lint](../lint.task.ts) - run eslint
+- [publish](../publish.task.ts) - bump version, publish to npm, and git push
+- [reinstall](../reinstall.task.ts) - refreshes package-lock.json with the latest and cleanest deps
+- [release](../release.task.ts) - publish and deploy
+- [resolve](../resolve.task.ts) - diagnostic that logs resolved filesystem info for the given input paths
+- [run](../run.task.ts) - execute a file with the loader, like `node` but works for TypeScript
+- [sync](../sync.task.ts) - run `gro gen`, update `package.json`, and optionally `npm i` to sync up
+- [test](../test.task.ts) - run tests with uvu
+- [typecheck](../typecheck.task.ts) - run tsc on the project without emitting any files
+- [upgrade](../upgrade.task.ts) - upgrade deps
+
+## usage
+
+```bash
+$ gro some/name
+```
+
+> <sub>[gro](/../..) / [lib](..) / [docs](./) / tasks.md</sub>
+
+> <sub>generated by [tasks.gen.md.ts](tasks.gen.md.ts)</sub>

package/src/lib/docs/test.md

@@ -0,0 +1,52 @@
+# test
+
+Gro integrates [`uvu`](https://github.com/lukeed/uvu) for tests:
+
+```bash
+gro test # run all tests with Gro's default `*.test.ts` pattern
+gro test thing.test somedir test/a.+b # run tests matching regexp patterns
+```
+
+> Running `gro test [...args]` calls `uvu`'s `parse` and `run` helpers
+> inside Gro's normal [task context](/src/lib/docs/task.md) instead of using the `uvu` CLI.
+> Gro typically defers to a tool's CLI, so it can transparently forward args without wrapping,
+> but in this case `uvu` doesn't support [loaders](https://nodejs.org/api/esm.html#loaders)
+> for running TypeScript files directly.
+> `uvu` does support require hooks, but Gro prefers the loader API.
+
+Like other tasks, use `--help` to see the args info:
+
+```bash
+gro test --help
+```
+
+outputs:
+
+```
+gro test: run tests
+[...args]  string[]           ["\\.test\\.ts$"]  file patterns to test
+bail       boolean            false              the bail option to uvu run, exit immediately on failure
+cwd        string             undefined          the cwd option to uvu parse
+ignore     string | string[]  undefined          the ignore option to uvu parse
+```
+
+[`gro test`](/src/lib/test.task.ts) runs all `*.test.ts`
+files in your project by default using the regexp `"\\.test\\.ts$"`.
+So to add a new test, create a new file:
+
+```ts
+// by convention, create `src/lib/thing.ts`
+// to test `src/lib/thing.test.ts`
+import {test} from 'uvu';
+import * as assert from 'uvu/assert';
+
+import {thing} from '$lib/thing.js';
+
+test('the thing', async () => {
+	assert.equal(thing, {expected: true});
+});
+
+test.run();
+```
+
+See [the `uvu` docs](https://github.com/lukeed/uvu) for more.

package/src/lib/env.ts

@@ -0,0 +1,75 @@
+import dotenv from 'dotenv';
+import {resolve} from 'node:path';
+import {existsSync, readFileSync} from 'node:fs';
+
+export const load_env = (
+	dev: boolean,
+	visibility: 'public' | 'private',
+	public_prefix: string,
+	private_prefix: string,
+	env_dir?: string,
+	env_files = ['.env', '.env.' + (dev ? 'development' : 'production')],
+	ambient_env = process.env,
+): Record<string, string> => {
+	const envs: Array<Record<string, string | undefined>> = env_files
+		.map((path) => load(env_dir === undefined ? path : resolve(env_dir, path)))
+		.filter((v) => v !== undefined);
+	envs.push(ambient_env);
+	return merge_envs(envs, visibility, public_prefix, private_prefix);
+};
+
+const load = (path: string): Record<string, string> | undefined => {
+	if (!existsSync(path)) return;
+	const loaded = readFileSync(path, 'utf8');
+	return dotenv.parse(loaded);
+};
+
+export const merge_envs = (
+	envs: Array<Record<string, string | undefined>>,
+	visibility: 'public' | 'private',
+	public_prefix: string,
+	private_prefix: string,
+): Record<string, string> => {
+	const env: Record<string, string> = {};
+
+	for (const e of envs) {
+		for (const key in e) {
+			if (
+				(visibility === 'private' && is_private_env(key, public_prefix, private_prefix)) ||
+				(visibility === 'public' && is_public_env(key, public_prefix, private_prefix))
+			) {
+				const value = e[key];
+				if (value !== undefined) env[key] = value;
+			}
+		}
+	}
+
+	return env;
+};
+
+export const is_private_env = (
+	key: string,
+	public_prefix: string,
+	private_prefix: string,
+): boolean =>
+	key.startsWith(private_prefix) && (public_prefix === '' || !key.startsWith(public_prefix));
+
+export const is_public_env = (
+	key: string,
+	public_prefix: string,
+	private_prefix: string,
+): boolean =>
+	key.startsWith(public_prefix) && (private_prefix === '' || !key.startsWith(private_prefix));
+
+/**
+ * Loads a single env value without merging it into `process.env`.
+ * By default searches process.env, then a local `.env` if one exists, then `../.env` if it exists.
+ */
+export const load_from_env = (key: string, paths = ['.env', '../.env']): string | undefined => {
+	if (process.env[key]) return process.env[key];
+	for (const path of paths) {
+		const env = load(path);
+		if (env?.[key]) return env[key];
+	}
+	return undefined;
+};

package/src/lib/esbuild_helpers.ts

@@ -0,0 +1,50 @@
+import {yellow, red} from '@ryanatkn/belt/styletext.js';
+import type {Logger} from '@ryanatkn/belt/log.js';
+import type * as esbuild from 'esbuild';
+
+import type {Parsed_Sveltekit_Config} from './sveltekit_config.js';
+
+export const print_build_result = (log: Logger, build_result: esbuild.BuildResult): void => {
+	for (const error of build_result.errors) {
+		log.error(red('esbuild error'), error);
+	}
+	for (const warning of build_result.warnings) {
+		log.warn(yellow('esbuild warning'), warning);
+	}
+};
+
+// This concatenates weirdly to avoid a SvelteKit warning,
+// because SvelteKit detects usage as a string and not the AST.
+const import_meta_env = 'import.' + 'meta.env.'; // eslint-disable-line no-useless-concat
+
+/**
+ * Creates an esbuild `define` shim for Vite's `import.meta\.env`.
+ * @see https://esbuild.github.io/api/#define
+ * @param dev
+ * @param base_url - best-effort shim from SvelteKit's `base` to Vite's `import.meta\.env.BASE_URL`
+ * @param ssr
+ * @param mode
+ * @returns
+ */
+export const to_define_import_meta_env = (
+	dev: boolean,
+	base_url: Parsed_Sveltekit_Config['base_url'],
+	ssr = true,
+	mode = dev ? 'development' : 'production',
+): Record<string, string> => ({
+	// see `import_meta_env` for why this is defined weirdly instead of statically
+	[import_meta_env + 'DEV']: JSON.stringify(dev),
+	[import_meta_env + 'PROD']: JSON.stringify(!dev),
+	[import_meta_env + 'SSR']: JSON.stringify(ssr),
+	[import_meta_env + 'MODE']: JSON.stringify(mode),
+	// it appears SvelteKit's `''` translates to Vite's `'/'`, so this intentionally falls back for falsy values, not just undefined
+	[import_meta_env + 'BASE_URL']: JSON.stringify(base_url || '/'), // eslint-disable-line @typescript-eslint/prefer-nullish-coalescing
+});
+
+export const ts_transform_options: esbuild.TransformOptions = {
+	target: 'esnext',
+	format: 'esm',
+	loader: 'ts',
+	charset: 'utf8',
+	// TODO load local tsconfig
+};

package/src/lib/esbuild_plugin_external_worker.ts

@@ -0,0 +1,92 @@
+import * as esbuild from 'esbuild';
+import type {Logger} from '@ryanatkn/belt/log.js';
+import {basename} from 'node:path';
+import type {CompileOptions, PreprocessorGroup, ModuleCompileOptions} from 'svelte/compiler';
+
+import {print_build_result, to_define_import_meta_env} from './esbuild_helpers.js';
+import {resolve_specifier} from './resolve_specifier.js';
+import {esbuild_plugin_sveltekit_shim_alias} from './esbuild_plugin_sveltekit_shim_alias.js';
+import {esbuild_plugin_sveltekit_shim_env} from './esbuild_plugin_sveltekit_shim_env.js';
+import {esbuild_plugin_sveltekit_shim_app} from './esbuild_plugin_sveltekit_shim_app.js';
+import {esbuild_plugin_sveltekit_local_imports} from './esbuild_plugin_sveltekit_local_imports.js';
+import {esbuild_plugin_svelte} from './esbuild_plugin_svelte.js';
+import type {Parsed_Sveltekit_Config} from './sveltekit_config.js';
+import type {Path_Id} from './path.js';
+
+export interface Options {
+	dev: boolean;
+	build_options: esbuild.BuildOptions;
+	dir?: string;
+	svelte_compile_options?: CompileOptions;
+	svelte_compile_module_options?: ModuleCompileOptions;
+	svelte_preprocessors?: PreprocessorGroup | PreprocessorGroup[];
+	alias?: Record<string, string>;
+	base_url?: Parsed_Sveltekit_Config['base_url'];
+	assets_url?: Parsed_Sveltekit_Config['assets_url'];
+	public_prefix?: string;
+	private_prefix?: string;
+	env_dir?: string;
+	env_files?: string[];
+	ambient_env?: Record<string, string>;
+	log?: Logger;
+}
+
+export const esbuild_plugin_external_worker = ({
+	dev,
+	build_options,
+	dir = process.cwd(),
+	svelte_compile_options,
+	svelte_preprocessors,
+	svelte_compile_module_options,
+	alias,
+	base_url,
+	assets_url,
+	public_prefix,
+	private_prefix,
+	env_dir,
+	env_files,
+	ambient_env,
+	log,
+}: Options): esbuild.Plugin => ({
+	name: 'external_worker',
+	setup: (build) => {
+		const builds: Map<string, Promise<esbuild.BuildResult>> = new Map();
+		const build_worker = async (path_id: Path_Id): Promise<esbuild.BuildResult> => {
+			if (builds.has(path_id)) return builds.get(path_id)!;
+			const building = esbuild.build({
+				entryPoints: [path_id],
+				plugins: [
+					esbuild_plugin_sveltekit_shim_app({dev, base_url, assets_url}),
+					esbuild_plugin_sveltekit_shim_env({
+						dev,
+						public_prefix,
+						private_prefix,
+						env_dir,
+						env_files,
+						ambient_env,
+					}),
+					esbuild_plugin_sveltekit_shim_alias({dir, alias}),
+					esbuild_plugin_svelte({
+						dir,
+						svelte_compile_options,
+						svelte_compile_module_options,
+						svelte_preprocessors,
+					}),
+					esbuild_plugin_sveltekit_local_imports(),
+				],
+				define: to_define_import_meta_env(dev, base_url),
+				...build_options,
+			});
+			builds.set(path_id, building);
+			return building;
+		};
+
+		build.onResolve({filter: /\.worker(|\.js|\.ts)$/u}, async ({path, resolveDir}) => {
+			const parsed = resolve_specifier(path, resolveDir);
+			const {specifier, path_id, namespace} = parsed;
+			const build_result = await build_worker(path_id);
+			if (log) print_build_result(log, build_result);
+			return {path: './' + basename(specifier), external: true, namespace};
+		});
+	},
+});

package/src/lib/esbuild_plugin_svelte.test.ts

@@ -0,0 +1,88 @@
+import {test} from 'uvu';
+import * as assert from 'uvu/assert';
+import * as esbuild from 'esbuild';
+import {readFile, rm} from 'node:fs/promises';
+
+import {esbuild_plugin_svelte} from './esbuild_plugin_svelte.js';
+
+test('build for the client', async () => {
+	const outfile = './src/fixtures/modules/some_test_server_bundle_DELETEME.js';
+	const built = await esbuild.build({
+		entryPoints: ['./src/fixtures/modules/some_test_server.ts'],
+		plugins: [esbuild_plugin_svelte()],
+		outfile,
+		format: 'esm',
+		platform: 'node',
+		packages: 'external',
+		bundle: true,
+		target: 'esnext',
+	});
+	assert.is(built.errors.length, 0);
+	assert.is(built.warnings.length, 0);
+
+	const built_output = await readFile(outfile, 'utf8');
+	assert.is(
+		built_output,
+		`// src/fixtures/modules/some_test_svelte_ts.svelte.ts
+import * as $ from "svelte/internal/client";
+var Some_Test_Svelte_Ts = class {
+  #a = $.source("ok");
+  get a() {
+    return $.get(this.#a);
+  }
+  set a(value) {
+    $.set(this.#a, $.proxy(value));
+  }
+};
+
+// src/fixtures/modules/some_test_server.ts
+var some_test_server = "some_test_server";
+var Rexported_Some_Test_Svelte_Ts = Some_Test_Svelte_Ts;
+export {
+  Rexported_Some_Test_Svelte_Ts,
+  some_test_server
+};
+`,
+	);
+
+	await rm(outfile); // TODO could be cleaner
+});
+
+test('build for the server', async () => {
+	const outfile = './src/fixtures/modules/some_test_client_bundle_DELETEME.js';
+	const built = await esbuild.build({
+		entryPoints: ['./src/fixtures/modules/some_test_server.ts'],
+		plugins: [esbuild_plugin_svelte({svelte_compile_module_options: {generate: 'server'}})],
+		outfile,
+		format: 'esm',
+		platform: 'node',
+		packages: 'external',
+		bundle: true,
+		target: 'esnext',
+	});
+	assert.is(built.errors.length, 0);
+	assert.is(built.warnings.length, 0);
+
+	const built_output = await readFile(outfile, 'utf8');
+	assert.is(
+		built_output,
+		`// src/fixtures/modules/some_test_svelte_ts.svelte.ts
+import * as $ from "svelte/internal/server";
+var Some_Test_Svelte_Ts = class {
+  a = "ok";
+};
+
+// src/fixtures/modules/some_test_server.ts
+var some_test_server = "some_test_server";
+var Rexported_Some_Test_Svelte_Ts = Some_Test_Svelte_Ts;
+export {
+  Rexported_Some_Test_Svelte_Ts,
+  some_test_server
+};
+`,
+	);
+
+	await rm(outfile); // TODO could be cleaner
+});
+
+test.run();

package/src/lib/esbuild_plugin_svelte.ts

@@ -0,0 +1,108 @@
+import type * as esbuild from 'esbuild';
+import {
+	compile,
+	compileModule,
+	preprocess,
+	type CompileOptions,
+	type ModuleCompileOptions,
+	type PreprocessorGroup,
+} from 'svelte/compiler';
+import {readFile} from 'node:fs/promises';
+import {relative} from 'node:path';
+
+import {SVELTE_MATCHER, SVELTE_RUNES_MATCHER} from './svelte_helpers.js';
+
+export interface Options {
+	dir?: string;
+	svelte_compile_options?: CompileOptions;
+	svelte_compile_module_options?: ModuleCompileOptions;
+	svelte_preprocessors?: PreprocessorGroup | PreprocessorGroup[];
+}
+
+export const esbuild_plugin_svelte = (options: Options = {}): esbuild.Plugin => {
+	const {
+		dir = process.cwd(),
+		svelte_compile_options = {},
+		svelte_compile_module_options = {},
+		svelte_preprocessors,
+	} = options;
+	return {
+		name: 'svelte',
+		setup: (build) => {
+			build.onLoad({filter: SVELTE_RUNES_MATCHER}, async ({path}) => {
+				const source = await readFile(path, 'utf8');
+				try {
+					const filename = relative(dir, path);
+					const {js, warnings} = compileModule(source, {
+						filename,
+						...svelte_compile_module_options,
+					});
+					const contents = js.code + '//# sourceMappingURL=' + js.map.toUrl();
+					return {
+						contents,
+						warnings: warnings.map((w) => convert_svelte_message_to_esbuild(filename, source, w)),
+					};
+				} catch (err) {
+					return {errors: [convert_svelte_message_to_esbuild(path, source, err)]};
+				}
+			});
+			build.onLoad({filter: SVELTE_MATCHER}, async ({path}) => {
+				let source = await readFile(path, 'utf8');
+				try {
+					const filename = relative(dir, path);
+					const preprocessed = svelte_preprocessors
+						? await preprocess(source, svelte_preprocessors, {filename})
+						: null;
+					// TODO handle preprocessor sourcemaps, same as in loader - merge?
+					if (preprocessed?.code) source = preprocessed.code;
+					const {js, warnings} = compile(source, {
+						filename,
+						...svelte_compile_options,
+					});
+					const contents = js.code + '//# sourceMappingURL=' + js.map.toUrl();
+					return {
+						contents,
+						warnings: warnings.map((w) => convert_svelte_message_to_esbuild(filename, source, w)),
+					};
+				} catch (err) {
+					return {errors: [convert_svelte_message_to_esbuild(path, source, err)]};
+				}
+			});
+		},
+	};
+};
+
+/**
+ * Following the example in the esbuild docs:
+ * https://esbuild.github.io/plugins/#svelte-plugin
+ */
+const convert_svelte_message_to_esbuild = (
+	path: string,
+	source: string,
+	{message, start, end}: SvelteError,
+): esbuild.PartialMessage => {
+	let location: esbuild.PartialMessage['location'] = null;
+	if (start && end) {
+		const lineText = source.split(/\r\n|\r|\n/gu)[start.line - 1];
+		const lineEnd = start.line === end.line ? end.column : lineText.length;
+		location = {
+			file: path,
+			line: start.line,
+			lineText,
+			column: start.column,
+			length: lineEnd - start.column,
+		};
+	}
+	return {text: message, location};
+};
+
+// these are not exported by Svelte
+interface SvelteError {
+	message: string;
+	start?: LineInfo;
+	end?: LineInfo;
+}
+interface LineInfo {
+	line: number;
+	column: number;
+}

package/src/lib/esbuild_plugin_sveltekit_local_imports.ts

@@ -0,0 +1,31 @@
+import type * as esbuild from 'esbuild';
+import {readFile} from 'node:fs/promises';
+import {dirname} from 'node:path';
+
+import {resolve_specifier} from './resolve_specifier.js';
+
+/**
+ * Adds support for imports to both `.ts` and `.js`,
+ * as well as imports without extensions that resolve to `.js` or `.ts`.
+ * Prefers `.ts` over any `.js`, and falls back to `.ts` if no file is found.
+ */
+export const esbuild_plugin_sveltekit_local_imports = (): esbuild.Plugin => ({
+	name: 'sveltekit_local_imports',
+	setup: (build) => {
+		build.onResolve({filter: /^(\/|\.)/u}, (args) => {
+			const {path, importer} = args;
+			if (!importer) return {path};
+			const {path_id, namespace} = resolve_specifier(path, dirname(importer));
+			return {path: path_id, namespace}; // `namespace` may be `undefined`, but esbuild needs the absolute path for json etc
+		});
+		build.onLoad({filter: /.*/u, namespace: 'sveltekit_local_imports_ts'}, async ({path}) => ({
+			contents: await readFile(path),
+			loader: 'ts',
+			resolveDir: dirname(path),
+		}));
+		build.onLoad({filter: /.*/u, namespace: 'sveltekit_local_imports_js'}, async ({path}) => ({
+			contents: await readFile(path),
+			resolveDir: dirname(path),
+		}));
+	},
+});

package/src/lib/esbuild_plugin_sveltekit_shim_alias.ts

@@ -0,0 +1,25 @@
+import type * as esbuild from 'esbuild';
+import {escape_regexp} from '@ryanatkn/belt/regexp.js';
+import {join} from 'node:path';
+
+export interface Options {
+	dir?: string;
+	alias?: Record<string, string>;
+}
+
+export const esbuild_plugin_sveltekit_shim_alias = ({
+	dir = process.cwd(),
+	alias,
+}: Options): esbuild.Plugin => ({
+	name: 'sveltekit_shim_alias',
+	setup: (build) => {
+		const aliases: Record<string, string> = {$lib: 'src/lib', ...alias};
+		const alias_regexp_prefixes = Object.keys(aliases).map((a) => escape_regexp(a));
+		const filter = new RegExp('^(' + alias_regexp_prefixes.join('|') + ')', 'u');
+		build.onResolve({filter}, async (args) => {
+			const {path, ...rest} = args;
+			const prefix = filter.exec(path)![1];
+			return build.resolve(join(dir, aliases[prefix] + path.substring(prefix.length)), rest);
+		});
+	},
+});