@ryanatkn/gro 0.160.0 → 0.161.0

package/src/lib/package_json.ts

@@ -1,10 +1,10 @@
 import {z} from 'zod';
 import {join} from 'node:path';
 import {readFileSync, writeFileSync} from 'node:fs';
-import {count_graphemes, plural, strip_end} from '@ryanatkn/belt/string.js';
+import {plural, strip_end} from '@ryanatkn/belt/string.js';
 import type {Logger} from '@ryanatkn/belt/log.js';
-import type {Flavored} from '@ryanatkn/belt/types.js';
 import {styleText as st} from 'node:util';
+import {Package_Json, Package_Json_Exports} from '@ryanatkn/belt/package_json.js';
 
 import {paths, gro_paths, IS_THIS_GRO, replace_extension} from './paths.ts';
 import {SVELTEKIT_DIST_DIRNAME} from './constants.ts';
@@ -12,143 +12,6 @@ import {search_fs} from './search_fs.ts';
 import {has_sveltekit_library} from './sveltekit_helpers.ts';
 import {GITHUB_REPO_MATCHER} from './github.ts';
 
-// TODO @many belongs elsewhere
-export const Url = z.string();
-export type Url = Flavored<z.infer<typeof Url>, 'Url'>;
-
-// TODO @many belongs elsewhere
-export const Email = z.string();
-export type Email = Flavored<z.infer<typeof Email>, 'Email'>;
-
-// TODO move this where?
-export const transform_empty_object_to_undefined = <T>(val: T): T | undefined => {
-	if (val && Object.keys(val).length === 0) {
-		return;
-	}
-	return val;
-};
-
-export const Package_Json_Repository = z.union([
-	z.string(),
-	z
-		.object({
-			type: z.string(),
-			url: Url,
-			directory: z.string().optional(),
-		})
-		.passthrough(),
-]);
-export type Package_Json_Repository = z.infer<typeof Package_Json_Repository>;
-
-export const Package_Json_Author = z.union([
-	z.string(),
-	z
-		.object({
-			name: z.string(),
-			email: Email.optional(),
-			url: Url.optional(),
-		})
-		.passthrough(),
-]);
-export type Package_Json_Author = z.infer<typeof Package_Json_Author>;
-
-export const Package_Json_Funding = z.union([
-	z.string(),
-	z
-		.object({
-			type: z.string(),
-			url: Url,
-		})
-		.passthrough(),
-]);
-export type Package_Json_Funding = z.infer<typeof Package_Json_Funding>;
-
-// Helper to create a recursive type that represents export conditions and values
-const create_export_value_schema = (): z.ZodType => {
-	return z.lazy(() => z.union([z.string(), z.null(), z.record(z.lazy(() => export_value_schema))]));
-};
-
-// The base export value schema that can be a string, null, or nested conditions
-const export_value_schema = create_export_value_schema();
-export const Export_Value = export_value_schema;
-export type Export_Value = z.infer<typeof Export_Value>;
-
-// Package exports can be:
-// 1. A string (shorthand for main export)
-// 2. null (to block exports)
-// 3. A record of export conditions/paths
-export const Package_Json_Exports = z.union([z.string(), z.null(), z.record(export_value_schema)]);
-export type Package_Json_Exports = z.infer<typeof Package_Json_Exports>;
-
-/**
- * @see https://docs.npmjs.com/cli/v10/configuring-npm/package-json
- */
-export const Package_Json = z
-	.object({
-		// according to the npm docs, `name` and `version` are the only required properties
-		name: z.string(),
-		version: z.string(),
-		private: z.boolean({description: 'disallow publishing to the configured registry'}).optional(),
-		public: z
-			.boolean({
-				description:
-					'a Gro extension that enables publishing `.well-known/package.json` and `.well-known/src`',
-			})
-			.optional(),
-		description: z.string().optional(),
-		motto: z
-			.string({description: "a Gro extension that's a short phrase that represents this project"})
-			.optional(),
-		glyph: z
-			.string({
-				description:
-					"a Gro extension that's a single unicode character that represents this project",
-			})
-			.refine((v) => count_graphemes(v) === 1, 'must be a single unicode character')
-			.optional(),
-		logo: z
-			.string({
-				description:
-					"a Gro extension that's a link relative to the `homepage` to an image that represents this project",
-			})
-			.optional(),
-		logo_alt: z
-			.string({description: "a Gro extension that's the alt text for the `logo`"})
-			.optional(),
-		license: z.string().optional(),
-		scripts: z.record(z.string()).optional(),
-		homepage: Url.optional(),
-		author: z.union([z.string(), Package_Json_Author.optional()]),
-		repository: z.union([z.string(), Url, Package_Json_Repository]).optional(),
-		contributors: z.array(z.union([z.string(), Package_Json_Author])).optional(),
-		bugs: z
-			.union([z.string(), z.object({url: Url.optional(), email: Email.optional()}).passthrough()])
-			.optional(),
-		funding: z
-			.union([Url, Package_Json_Funding, z.array(z.union([Url, Package_Json_Funding]))])
-			.optional(),
-		keywords: z.array(z.string()).optional(),
-
-		type: z.string().optional(),
-		engines: z.record(z.string()).optional(),
-		os: z.array(z.string()).optional(),
-		cpu: z.array(z.string()).optional(),
-
-		dependencies: z.record(z.string()).optional(),
-		devDependencies: z.record(z.string()).optional(),
-		peerDependencies: z.record(z.string()).optional(),
-		peerDependenciesMeta: z.record(z.object({optional: z.boolean()})).optional(),
-		optionalDependencies: z.record(z.string()).optional(),
-
-		bin: z.record(z.string()).optional(),
-		sideEffects: z.array(z.string()).optional(),
-		files: z.array(z.string()).optional(),
-		main: z.string().optional(),
-		exports: Package_Json_Exports.transform(transform_empty_object_to_undefined).optional(),
-	})
-	.passthrough();
-export type Package_Json = z.infer<typeof Package_Json>;
-
 export type Map_Package_Json = (
 	package_json: Package_Json,
 ) => Package_Json | null | Promise<Package_Json | null>;
@@ -331,7 +194,7 @@ const parse_package_json = (schema: typeof Package_Json, value: any): Package_Js
 };
 
 // TODO maybe extract to zod helpers? see also everything in `task_logging.ts`
-const parse_or_throw_formatted_error = <T extends z.ZodTypeAny>(
+const parse_or_throw_formatted_error = <T extends z.ZodType>(
 	name: string,
 	schema: T,
 	value: any,

package/src/lib/parse_exports.ts

@@ -2,23 +2,15 @@ import ts from 'typescript';
 import {extname} from 'node:path';
 import type {Flavored} from '@ryanatkn/belt/types.js';
 import type {Logger} from '@ryanatkn/belt/log.js';
+import type {Src_Module_Declaration_Kind} from '@ryanatkn/belt/src_json.js';
 
 import type {Path_Id} from './path.ts';
 import {TS_MATCHER} from './constants.ts';
 import {Parse_Exports_Context} from './parse_exports_context.ts';
 
-export type Declaration_Kind =
-	| 'type'
-	| 'function'
-	| 'variable' // TODO maybe expand this to have literals/primitives?
-	| 'class'
-	| 'component'
-	| 'json'
-	| 'css';
-
 export interface Declaration {
 	name: string;
-	kind: Declaration_Kind | null;
+	kind: Src_Module_Declaration_Kind | null;
 }
 
 export type Export_Declaration = Flavored<Declaration, 'Export_Declaration'>;

package/src/lib/parse_exports_context.ts

@@ -1,7 +1,8 @@
 import ts from 'typescript';
 import type {Logger} from '@ryanatkn/belt/log.js';
+import type {Src_Module_Declaration_Kind} from '@ryanatkn/belt/src_json.js';
 
-import type {Declaration_Kind, Export_Declaration} from './parse_exports.ts';
+import type {Export_Declaration} from './parse_exports.ts';
 
 /**
  * A class to track export context and determine export kinds.
@@ -12,7 +13,7 @@ export class Parse_Exports_Context {
 	// Map of source file paths to their symbols
 	readonly #file_symbols: Map<string, ts.Symbol> = new Map();
 	// Cache for resolved symbols to avoid repeated resolution
-	readonly #symbol_kind_cache: Map<ts.Symbol, Declaration_Kind> = new Map();
+	readonly #symbol_kind_cache: Map<ts.Symbol, Src_Module_Declaration_Kind> = new Map();
 
 	readonly log: Logger | undefined;
 	debug = process.env.DEBUG_EXPORTS === 'true';
@@ -74,7 +75,10 @@ export class Parse_Exports_Context {
 	/**
 	 * Determine the kind of an export based on its symbol.
 	 */
-	#determine_export_kind(source_file: ts.SourceFile, symbol: ts.Symbol): Declaration_Kind {
+	#determine_export_kind(
+		source_file: ts.SourceFile,
+		symbol: ts.Symbol,
+	): Src_Module_Declaration_Kind {
 		// Check if this is a type-only export (no value export)
 		if (this.#is_type_only_export(source_file, symbol)) {
 			return 'type';
@@ -114,7 +118,7 @@ export class Parse_Exports_Context {
 	/**
 	 * Infer the declaration kind from a symbol's declaration and type information.
 	 */
-	#infer_declaration_kind(symbol: ts.Symbol): Declaration_Kind {
+	#infer_declaration_kind(symbol: ts.Symbol): Src_Module_Declaration_Kind {
 		// Check symbol flags first for direct type matching
 		if (this.#is_class_symbol(symbol)) {
 			return 'class';
@@ -181,7 +185,7 @@ export class Parse_Exports_Context {
 	/**
 	 * Infer the declaration kind from a specific declaration node.
 	 */
-	#infer_kind_from_declaration(decl: ts.Declaration): Declaration_Kind | null {
+	#infer_kind_from_declaration(decl: ts.Declaration): Src_Module_Declaration_Kind | null {
 		if (ts.isFunctionDeclaration(decl)) {
 			return 'function';
 		}

package/src/lib/publish.task.ts

@@ -19,32 +19,39 @@ import {
 } from './git.ts';
 import {CHANGESET_CLI} from './changeset_helpers.ts';
 
-export const Args = z
-	.object({
-		branch: Git_Branch.describe('branch to publish from').default('main'),
-		origin: Git_Origin.describe('git origin to publish from').default('origin'),
-		changelog: z
-			.string({description: 'file name and path of the changelog'})
-			.default('CHANGELOG.md'),
-		preserve_changelog: z
-			.boolean({
-				description:
-					'opt out of linkifying and formatting the changelog from @changesets/changelog-git',
-			})
-			.default(false),
-		optional: z.boolean({description: 'exit gracefully if there are no changesets'}).default(false),
-		dry: z
-			.boolean({description: 'build and prepare to publish without actually publishing'})
-			.default(false),
-		check: z.boolean({description: 'dual of no-check'}).default(true),
-		'no-check': z.boolean({description: 'opt out of checking before publishing'}).default(false),
-		build: z.boolean({description: 'dual of no-build'}).default(true),
-		'no-build': z.boolean({description: 'opt out of building'}).default(false),
-		pull: z.boolean({description: 'dual of no-pull'}).default(true),
-		'no-pull': z.boolean({description: 'opt out of git pull'}).default(false),
-		changeset_cli: z.string({description: 'the changeset CLI to use'}).default(CHANGESET_CLI),
-	})
-	.strict();
+export const Args = z.strictObject({
+	branch: Git_Branch.describe('branch to publish from').default('main'),
+	origin: Git_Origin.describe('git origin to publish from').default('origin'),
+	changelog: z
+		.string()
+		.meta({description: 'file name and path of the changelog'})
+		.default('CHANGELOG.md'),
+	preserve_changelog: z
+		.boolean()
+		.meta({
+			description:
+				'opt out of linkifying and formatting the changelog from @changesets/changelog-git',
+		})
+		.default(false),
+	optional: z
+		.boolean()
+		.meta({description: 'exit gracefully if there are no changesets'})
+		.default(false),
+	dry: z
+		.boolean()
+		.meta({description: 'build and prepare to publish without actually publishing'})
+		.default(false),
+	check: z.boolean().meta({description: 'dual of no-check'}).default(true),
+	'no-check': z
+		.boolean()
+		.meta({description: 'opt out of checking before publishing'})
+		.default(false),
+	build: z.boolean().meta({description: 'dual of no-build'}).default(true),
+	'no-build': z.boolean().meta({description: 'opt out of building'}).default(false),
+	pull: z.boolean().meta({description: 'dual of no-pull'}).default(true),
+	'no-pull': z.boolean().meta({description: 'opt out of git pull'}).default(false),
+	changeset_cli: z.string().meta({description: 'the changeset CLI to use'}).default(CHANGESET_CLI),
+});
 export type Args = z.infer<typeof Args>;
 
 export const task: Task<Args> = {

package/src/lib/reinstall.task.ts

@@ -5,7 +5,7 @@ import {rm} from 'node:fs/promises';
 import {Task_Error, type Task} from './task.ts';
 import {LOCKFILE_FILENAME, NODE_MODULES_DIRNAME} from './constants.ts';
 
-export const Args = z.object({}).strict();
+export const Args = z.strictObject({});
 export type Args = z.infer<typeof Args>;
 
 export const task: Task<Args> = {
@@ -30,6 +30,7 @@ export const task: Task<Args> = {
 			);
 		}
 
+		// TODO this relies on npm behavior that changed in v11
 		// Deleting the lockfile and reinstalling cleans the lockfile of unnecessary dep noise,
 		// like esbuild's many packages for each platform.
 		await rm(LOCKFILE_FILENAME);

package/src/lib/release.task.ts

@@ -4,7 +4,7 @@ import type {Task} from './task.ts';
 import {has_sveltekit_library, has_sveltekit_app} from './sveltekit_helpers.ts';
 import {load_package_json} from './package_json.ts';
 
-export const Args = z.object({}).strict();
+export const Args = z.strictObject({});
 export type Args = z.infer<typeof Args>;
 
 export const task: Task<Args> = {

package/src/lib/resolve.task.ts

@@ -4,12 +4,10 @@ import {styleText as st} from 'node:util';
 import {TASK_FILE_SUFFIXES, type Task} from './task.ts';
 import {resolve_input_paths, to_input_paths} from './input_path.ts';
 
-export const Args = z
-	.object({
-		_: z.array(z.string(), {description: 'the input paths to resolve'}).default(['']),
-		verbose: z.boolean({description: 'log diagnostics'}).default(false),
-	})
-	.strict();
+export const Args = z.strictObject({
+	_: z.array(z.string()).meta({description: 'the input paths to resolve'}).default(['']),
+	verbose: z.boolean().meta({description: 'log diagnostics'}).default(false),
+});
 export type Args = z.infer<typeof Args>;
 
 export const task: Task<Args> = {

package/src/lib/run.task.ts

@@ -5,13 +5,16 @@ import {existsSync} from 'node:fs';
 import {Task_Error, type Task} from './task.ts';
 import {resolve_gro_module_path, spawn_with_loader} from './gro_helpers.ts';
 
-export const Args = z
-	.object({
-		_: z
-			.array(z.string(), {description: 'the file path to run and other node CLI args'})
-			.default([]),
-	})
-	.strict();
+// TODO maybe delete this? if misused is a security risk,
+// and I'm not using it for anything that couldn't be done with Node directly atm.
+// It could potentially be more useful if I keep building on the task system.
+
+export const Args = z.strictObject({
+	_: z
+		.array(z.string())
+		.meta({description: 'the file path to run and other node CLI args'})
+		.default([]),
+});
 export type Args = z.infer<typeof Args>;
 
 export const task: Task<Args> = {

package/src/lib/run_task.ts

@@ -2,6 +2,7 @@ import {styleText as st} from 'node:util';
 import {print_log_label} from '@ryanatkn/belt/print.js';
 import {System_Logger} from '@ryanatkn/belt/log.js';
 import type {Timings} from '@ryanatkn/belt/timings.js';
+import z from 'zod';
 
 import {parse_args, type Args} from './args.ts';
 import type {invoke_task as base_invoke_task} from './invoke_task.ts';
@@ -43,8 +44,9 @@ export const run_task = async (
 	if (task.Args) {
 		const parsed = parse_args(unparsed_args, task.Args);
 		if (!parsed.success) {
-			log.error(st('red', `Args validation failed:`), '\n', parsed.error.format());
-			throw new Task_Error(`Task args failed validation`);
+			throw new Task_Error(
+				`Failed task args validation for task '${task_meta.name}':\n${z.prettifyError(parsed.error)}`,
+			);
 		}
 		args = parsed.data;
 	}

package/src/lib/src_json.ts

@@ -1,65 +1,13 @@
-import {z} from 'zod';
 import {join, extname} from 'node:path';
 import {ensure_end, strip_start} from '@ryanatkn/belt/string.js';
 import {existsSync} from 'node:fs';
 import ts from 'typescript';
+import type {Package_Json, Package_Json_Exports} from '@ryanatkn/belt/package_json.js';
+import {Src_Json, Src_Modules} from '@ryanatkn/belt/src_json.js';
 
 import {paths, replace_extension} from './paths.ts';
-import {
-	transform_empty_object_to_undefined,
-	type Package_Json,
-	type Package_Json_Exports,
-} from './package_json.ts';
 import {parse_exports} from './parse_exports.ts';
 
-export const Src_Module_Declaration_Kind = z.enum([
-	'type',
-	'function',
-	'variable',
-	'class',
-	'component',
-	'json',
-	'css',
-]);
-export type Src_Module_Declaration_Kind = z.infer<typeof Src_Module_Declaration_Kind>;
-
-// TODO @many rename to prefix with `Src_Json_`?
-export const Src_Module_Declaration = z
-	.object({
-		name: z.string(), // the export identifier
-		// TODO these are poorly named, and they're somewhat redundant with `kind`,
-		// they were added to distinguish `VariableDeclaration` functions and non-functions
-		kind: Src_Module_Declaration_Kind.nullable(),
-		// code: z.string(), // TODO experiment with `getType().getText()`, some of them return the same as `name`
-	})
-	.passthrough();
-export type Src_Module_Declaration = z.infer<typeof Src_Module_Declaration>;
-
-// TODO @many rename to prefix with `Src_Json_`?
-export const Src_Module = z
-	.object({
-		path: z.string(),
-		declarations: z.array(Src_Module_Declaration).optional(),
-	})
-	.passthrough();
-export type Src_Module = z.infer<typeof Src_Module>;
-
-// TODO @many rename to prefix with `Src_Json_`?
-export const Src_Modules = z.record(Src_Module);
-export type Src_Modules = z.infer<typeof Src_Modules>;
-
-/**
- * @see https://github.com/ryanatkn/gro/blob/main/src/docs/gro_plugin_sveltekit_app.md#well-known-src
- */
-export const Src_Json = z
-	.object({
-		name: z.string(), // same as Package_Json
-		version: z.string(), // same as Package_Json
-		modules: Src_Modules.transform(transform_empty_object_to_undefined).optional(),
-	})
-	.passthrough();
-export type Src_Json = z.infer<typeof Src_Json>;
-
 export type Map_Src_Json = (src_json: Src_Json) => Src_Json | null | Promise<Src_Json | null>;
 
 export const create_src_json = (package_json: Package_Json, lib_path?: string): Src_Json =>
@@ -134,11 +82,7 @@ export const to_src_modules = (
 	for (const {export_key, file_path} of file_paths) {
 		const relative_path = file_path.replace(ensure_end(lib_path, '/'), '');
 
-		// Use parse_exports for all file types
-		const declarations = parse_exports(file_path, program).map(({name, kind}) => ({
-			name,
-			kind: kind as Src_Module_Declaration_Kind | null,
-		}));
+		const declarations = parse_exports(file_path, program).map(({name, kind}) => ({name, kind}));
 
 		result[export_key] = declarations.length
 			? {

package/src/lib/sveltekit_helpers.ts

@@ -2,8 +2,9 @@ import type {Result} from '@ryanatkn/belt/result.js';
 import {existsSync} from 'node:fs';
 import type {Logger} from '@ryanatkn/belt/log.js';
 import {join} from 'node:path';
+import type {Package_Json} from '@ryanatkn/belt/package_json.js';
 
-import {Package_Json, has_dep} from './package_json.ts';
+import {has_dep} from './package_json.ts';
 import {default_svelte_config, type Parsed_Svelte_Config} from './svelte_config.ts';
 import {SVELTE_CONFIG_FILENAME, SVELTEKIT_DEV_DIRNAME, PM_CLI_DEFAULT} from './constants.ts';
 import {find_cli, spawn_cli, to_cli_name, type Cli} from './cli.ts';

package/src/lib/sveltekit_shim_app_paths.ts

@@ -8,9 +8,12 @@
  * @see https://github.com/nodejs/loaders for details about the forthcoming virtual file support
  */
 
-import type {resolveRoute as base_resolveRoute} from '$app/paths';
+import type {resolve as base_resolve, resolveRoute as base_resolveRoute} from '$app/paths';
 import {noop} from '@ryanatkn/belt/function.js';
 
 export const assets = '';
+/** @deprecated */
 export const base = '';
-export const resolveRoute: typeof base_resolveRoute = noop;
+export const resolve: typeof base_resolve = (v) => ('/' + v.replace(/^\//, '')) as any; // TODO needs to use SvelteKit config base, should we just import it?
+/** @deprecated */
+export const resolveRoute: typeof base_resolveRoute = noop; // eslint-disable-line @typescript-eslint/no-deprecated

package/src/lib/sveltekit_shim_app_state.ts

@@ -24,7 +24,7 @@ export const page: typeof base_page = {
 	route: {id: null},
 	state: {},
 	status: -1,
-	url: new URL('https://github.com/ryanatkn/gro'),
+	url: new URL('https://github.com/ryanatkn/gro') as any,
 };
 
 export const updated: typeof base_updated = {

package/src/lib/sync.task.ts

@@ -5,18 +5,16 @@ import {Task_Error, type Task} from './task.ts';
 import {sync_package_json} from './package_json.ts';
 import {sveltekit_sync} from './sveltekit_helpers.ts';
 
-export const Args = z
-	.object({
-		sveltekit: z.boolean({description: 'dual of no-sveltekit'}).default(true),
-		'no-sveltekit': z.boolean({description: 'opt out of svelte-kit sync'}).default(false),
-		package_json: z.boolean({description: 'dual of no-package_json'}).default(true),
-		'no-package_json': z.boolean({description: 'opt out of package.json sync'}).default(false),
-		gen: z.boolean({description: 'dual of no-gen'}).default(true),
-		'no-gen': z.boolean({description: 'opt out of running gen'}).default(false),
-		install: z.boolean({description: 'dual of no-install'}).default(true),
-		'no-install': z.boolean({description: 'opt out of installing packages'}).default(false),
-	})
-	.strict();
+export const Args = z.strictObject({
+	sveltekit: z.boolean().meta({description: 'dual of no-sveltekit'}).default(true),
+	'no-sveltekit': z.boolean().meta({description: 'opt out of svelte-kit sync'}).default(false),
+	package_json: z.boolean().meta({description: 'dual of no-package_json'}).default(true),
+	'no-package_json': z.boolean().meta({description: 'opt out of package.json sync'}).default(false),
+	gen: z.boolean().meta({description: 'dual of no-gen'}).default(true),
+	'no-gen': z.boolean().meta({description: 'opt out of running gen'}).default(false),
+	install: z.boolean().meta({description: 'dual of no-install'}).default(true),
+	'no-install': z.boolean().meta({description: 'opt out of installing packages'}).default(false),
+});
 export type Args = z.infer<typeof Args>;
 
 export const task: Task<Args> = {

package/src/lib/task.ts

@@ -23,8 +23,8 @@ import {load_modules, type Load_Modules_Failure, type Module_Meta} from './modul
 import type {Filer} from './filer.ts';
 
 export interface Task<
-	T_Args = Args, // same as `z.infer<typeof Args>`
-	T_Args_Schema extends z.ZodType = z.ZodType,
+	T_Args = Args,
+	T_Args_Schema extends z.ZodType<Args, Args> = z.ZodType<Args, Args>, // TODO improve type? separate input/output?
 	T_Return = unknown,
 > {
 	run: (ctx: Task_Context<T_Args>) => T_Return | Promise<T_Return>; // TODO unused return value