@ryanatkn/gro 0.129.6 → 0.129.8

package/src/lib/docs/config.md

@@ -1,213 +0,0 @@
-# config
-
-Gro supports SvelteKit apps, Node libraries, and Node servers with minimal abstraction
-with the help of an optional config file that lives at the root `gro.config.ts`.
-If a project does not define a config, Gro imports a default config from
-[`src/lib/gro.config.default.ts`](/src/lib/gro.config.default.ts),
-which looks at your project for the familiar patterns and tries to do the right thing.
-
-> The [default config](/src/lib/gro.config.default.ts)
-> detects three types of projects that can coexist in one repo:
-> SvelteKit frontends,
-> Node libraries with [`@sveltejs/package`](https://kit.svelte.dev/docs/packaging),
-> and Node servers.
-
-See [`src/lib/config.ts`](/src/lib/config.ts) for the config types and implementation.
-
-## examples
-
-[The default config](/src/lib/gro.config.default.ts)
-is used for projects that do not define `gro.config.ts`.
-It's also passed as the first argument to `Create_Gro_Config`.
-
-A simple config that does nothing:
-
-```ts
-// gro.config.ts
-import type {Create_Gro_Config} from '@ryanatkn/gro';
-
-const config: Create_Gro_Config = async (cfg) => {
-	// mutate `cfg` or return a new object
-	return cfg;
-};
-
-export default config;
-```
-
-The default export of a Gro config is `Gro_Config | Create_Gro_Config`:
-
-```ts
-export interface Create_Gro_Config {
-	(base_config: Gro_Config): Raw_Gro_Config | Promise<Raw_Gro_Config>;
-}
-
-// The strict variant that's used internally and exposed to users in tasks and elsewhere.
-export interface Gro_Config {
-	plugins: Create_Config_Plugins;
-	map_package_json: Map_Package_Json | null;
-	task_root_dirs: Path_Id[];
-	search_filters: Path_Filter[];
-}
-
-// The relaxed variant that users can provide. Superset of `Gro_Config`.
-export interface Raw_Gro_Config {
-	plugins?: Create_Config_Plugins;
-	map_package_json?: Map_Package_Json | null;
-	task_root_dirs?: string[];
-	search_filters?: Path_Filter | Path_Filter[] | null;
-}
-```
-
-To define a user config that overrides the default plugins:
-
-```ts
-import type {Create_Gro_Config} from '@ryanatkn/gro';
-import {gro_plugin_sveltekit_app} from '@ryanatkn/gro/gro_plugin_sveltekit_app.js';
-
-const config: Create_Gro_Config = async (cfg) => {
-	// `cfg`, which has type `Gro_Config` and is equal to `create_empty_config()`,
-	// can be mutated or you can return your own.
-	// A return value is required to avoid potential errors and reduce ambiguity.
-
-	// example setting your own plugins):
-	cfg.plugins = async () => [
-		gro_plugin_sveltekit_app(),
-		(await import('./src/custom_plugin.js')).plugin(),
-	];
-
-	// example extending the default plugins:
-	const get_base_plugins = cfg.plugins;
-	cfg.plugins = async (ctx) => {
-		// replace a base plugin with `import {replace_plugin} from '@ryanatkn/gro';`:
-		const updated_plugins = replace_plugin(
-			await get_base_plugins(ctx),
-			gro_plugin_sveltekit_app({
-				// host_target?: Host_Target;
-				// well_known_package_json?: boolean | Map_Package_Json;
-			}),
-			// 'gro_plugin_sveltekit_app', // optional name if they don't match
-		);
-		return updated_plugins.concat(create_some_custom_plugin());
-	};
-
-	return cfg; // return type is `Raw_Gro_Config`, which is a relaxed superset of `Gro_Config`
-};
-
-export default config;
-```
-
-You can also export a config object and use `create_empty_config` to get the defaults:
-
-```ts
-import {create_empty_config} from '@ryanatkn/gro/config.js';
-
-const config = create_empty_config();
-
-// config.plugins = ...;
-// config.map_package_json = ...;
-// config.task_root_dirs = ...;
-// config.search_filters = ...;
-
-export default config;
-```
-
-See also [Gro's own internal config](/gro.config.ts).
-
-## `plugins`
-
-The `plugins` property is a function that returns an array of `Plugin` instances.
-Read more about plugins and the `Plugin` in
-[plugin.md](plugin.md), [dev.md](dev.md#plugin), and [build.md](build.md#plugin).
-
-```ts
-export interface Create_Config_Plugins<T_Plugin_Context extends Plugin_Context = Plugin_Context> {
-	(
-		ctx: T_Plugin_Context,
-	):
-		| (Plugin<T_Plugin_Context> | null | Array<Plugin<T_Plugin_Context> | null>)
-		| Promise<Plugin<T_Plugin_Context> | null | Array<Plugin<T_Plugin_Context> | null>>;
-}
-```
-
-## `map_package_json`
-
-The Gro config option `map_package_json` hooks into Gro's `package.json` automations.
-The `gro sync` task, which is called during the dev and build tasks among others,
-performs several steps to get a project's state ready,
-including `svelte-kit sync` and `package.json` automations.
-When the `map_package_json` config value is truthy,
-Gro outputs a mapped version of the root `package.json`.
-
-> The `gro check` task integrates with `map_package_json` to ensure everything is synced.
-
-The main purpose of `map_package_json` is to automate
-the `"exports"` property of your root `package.json`.
-The motivation is to streamline package publishing by supplementing
-[`@sveltejs/package`](https://kit.svelte.dev/docs/packaging).
-
-By default `package_json.exports` includes everything from `$lib/`
-except for some ignored files like tests and markdown,
-and you can provide your own `map_package_json` hook to
-mutate the `package_json`, return new data, or return `null` to be a no-op.
-
-Typical usage modifies `package_json.exports` during this step to define the public API.
-
-### using `map_package_json`
-
-```ts
-// gro.config.ts
-const config: Gro_Config = {
-	// ...other config
-
-	// disable mapping `package.json` with automated `exports`:
-	map_package_json: null,
-
-	// mutate anything and return the final config (can be async):
-	map_package_json: (package_json) => {
-		// example setting `exports`:
-		package_json.exports = {
-			'.': {
-				default: './dist/index.js',
-				types: './dist/index.d.ts',
-			},
-			'./example.js': {
-				default: './dist/example.js',
-				types: './dist/example.d.ts',
-			},
-			'./Example.svelte': {
-				svelte: './dist/Example.svelte',
-				types: './dist/Example.svelte.d.ts',
-			},
-		};
-		// example filtering `exports`:
-		package_json.exports = Object.fromEntries(
-			Object.entries(package_json.exports).filter(/* ... */),
-		);
-		return package_json; // returning `null` is a no-op
-	},
-};
-
-export interface Map_Package_Json {
-	(package_json: Package_Json): Package_Json | null | Promise<Package_Json | null>;
-}
-```
-
-## `task_root_dirs`
-
-The Gro config option `task_root_dirs` allows customizing Gro's task resolution.
-When calling `gro [input_path]`, absolute and explicitly relative paths starting with `.`
-are resolved according to normal filesystem rules,
-but non-explicit input paths, like `foo`, are resolved by searching
-through `task_root_dirs` in order until a matching file or directory is found on the filesystem.
-
-The default task paths are `./src/lib`, then `.`, and then Gro's dist directory.
-
-## `search_filters`
-
-The Gro config option `search_filters` allows customizing
-how Gro searches for tasks and genfiles on the filesystem.
-Directories and files are included if they pass all of these filters.
-
-By default, it uses the `DEFAULT_SEARCH_EXCLUDER` to exclude
-dot-prefixed directories, node_modules,
-and the build and dist directories for SvelteKit and Gro.

package/src/lib/docs/deploy.md

@@ -1,32 +0,0 @@
-# deploy
-
-The [`gro deploy`](/src/lib/deploy.task.ts)
-task was originally designed to support static deployments to
-[GitHub pages](https://pages.github.com/),
-but what it actually does is just [build](./build.md) and push to a branch.
-
-Importantly, Gro **destructively force pushes** to the `--target` branch, `deploy` by default.
-This is because Gro treats your deployment
-branch as disposable, able to be deleted or squashed or whatever whenever.
-Internally, `gro deploy` uses [git worktree](https://git-scm.com/docs/git-worktree)
-for tidiness.
-
-```bash
-gro deploy # prepare build/ and commit it to the `deploy` branch, then push to go live
-gro deploy --source my-branch # deploy from `my-branch` instead of the default `main`
-
-# deploy to `custom-deploy-branch` instead of the default `deploy`
-# WARNING! this force pushes to the target branch!
-gro deploy --target custom-deploy-branch
-# the above actually fails because force pushing is destructive, so add `--force` to be extra clear:
-gro deploy --target custom-deploy-branch --force
-# TODO maybe it should be `--dangerous-target-branch` instead of `--target` and `--force`?
-
-gro deploy --dry # prepare build/ but don't commit or push
-gro deploy --clean # if something goes wrong, use this to reset git and gro state
-```
-
-Run `gro deploy --help` or see [`src/lib/deploy.task.ts`](/src/lib/deploy.task.ts) for the details.
-
-For needs more advanced than pushing to a remote branch,
-projects can implement a custom `src/lib/deploy.task.ts`.

package/src/lib/docs/dev.md

@@ -1,40 +0,0 @@
-# dev
-
-Gro is designed to extend [SvelteKit](https://github.com/sveltejs/kit)
-with helpful tools. It supports:
-
-- frontends with SvelteKit and [Vite](https://github.com/vitejs/vite)
-- Node libraries
-- Node servers
-
-## usage
-
-```bash
-gro dev
-gro dev --no-watch # outputs dev artifacts and exits without watch mode
-```
-
-To configure a project, see [the config docs](config.md).
-
-## plugin
-
-`Plugin`s are objects that customize the behavior of `gro build` and `gro dev`.
-See [plugin.md](plugin.md) to learn more.
-
-## todo
-
-- [x] basics
-- [ ] add API using esbuild to optionally bundle specific pieces to speed up development
-- [ ] livereload CSS (and fix pop-in during dev)
-- [ ] HMR
-- [ ] probably support Rollup plugins in development, but how?
-- [ ] improve loading speed with `cache-control: immutable` and
-      [import maps](https://github.com/WICG/import-maps/)
-      (on my machine Firefox is much slower than Chrome
-      handling a module import waterfall, locally, and http2 didn't help)
-
-<p align="center">
-  <a href="https://github.com/ryanatkn/gro">
-    <img src="static/logo.svg" alt="a pixelated green oak acorn with a glint of sun" width="192" height="192">
-  </a>
-</p>

package/src/lib/docs/gen.md

@@ -1,269 +0,0 @@
-# gen
-
-> automated codegen by convention for
-> [Gro](https://github.com/ryanatkn/gro)
-
-## motivation
-
-The [`gro gen` task](/src/lib/gen.task.ts) helps us enhance our projects
-with convention-based code/data/file generation (codegen) techniques.
-
-Why? Codegen can produce cool results and unhalting pain.
-Used well, codegen can improve performance, flexibility, consistency, and development speed.
-As developers, automating our work is a natural thing to do,
-and whether or not it's a wise thing to do,
-`gro gen` can bring automation deeper into our code authoring workflows.
-
-By convention, `gro gen` looks through `src/`
-for any TypeScript files with `.gen.` in the file name,
-and it outputs a file stripped of `.gen.` to the same directory.
-The `*.gen.*` origin files export a `gen` function
-More flexibility is available when needed
-including multiple custom output files.
-
-`gen` is implemented as [a task](/src/lib/gen.task.ts)
-and [a plugin](/src/lib/gro_plugin_gen.ts),
-and runs only during development, not for production builds.
-
-Normally you'll want to commit generated files to git,
-but you can always gitignore a specific pattern like `*.ignore.*`
-and name the output files accordingly.
-
-Integrating codegen into our development process
-is a simple idea with vast potential.
-It lets us have a single source of truth for data
-without compromising any of our code's runtime characteristics.
-We can generate documentation, types,
-`index.ts` files exporting directories,
-data for a UI,
-validators, tests, fakes,
-and more by introspecting our data at buildtime,
-which speeds up development
-The goal is to leverage automation to increase the power we wield over our code
-with a straightforward developer experience.
-Ergonomics are key to unlocking codegen's full potential.
-
-**Be aware** — this is a sharp tool! It should be used sparingly, only when it's a clear win.
-It adds a layer of indirection between the code you write and run,
-and it's possible to tie yourself into knots with dependencies.
-Also, you could introduce security vulnerabilities
-if you fail to escape certain inputs,
-There's no support for sourcemaps yet, and I have no plans for them.
-(I would accept contributions, but I think it's a hard problem to do well,
-and I don't know what the payoffs would be)
-
-> ⚠️ Generated files should never be edited directly,
-> because the next time `gro gen` or `gro sync` runs,
-> any uncommitted changes will be lost!
-> I considered making `gen` only write to files that have no uncommitted changes,
-> but that would impede many workflows,
-> and I don't want to nudge users towards a habit of always adding an override flag.
-> I can see one possible improvement that lets the user
-> opt into making gen write only to unchanged files for those workflows that don't mind it,
-> so if you would like to see that or something similar,
-> please open an issue or [share your thoughts on Discord](https://discord.gg/YU5tyeK72X).
-
-Inspirations include Lisp macros, the
-[Svelte](https://github.com/sveltejs/svelte) compiler,
-and [Zig](https://github.com/ziglang/zig)'s comptime.
-(but `gro gen` is far more primitive)
-
-## usage
-
-The `gro gen` task looks for any files with `.gen.`
-in the file name and tries to call an exported `gen`
-function to generate one or more output files,
-and then it writes the results to the filesystem.
-
-```bash
-gro gen # runs codegen for all *.gen.* files in src/
-gro gen --check # exits with error code 1 if anything is new or different; no-op to the fs
-```
-
-> in the following examples,
-> but it makes for a better DX
-
-### generate arbitrary TypeScript
-
-Given `src/script.gen.ts`:
-
-```ts
-import type {Gen} from '@ryanatkn/gro';
-
-export const gen: Gen = () => {
-	const message = 'generated';
-	return `console.log('${message} a ${typeof message}')`;
-};
-```
-
-Outputs `src/script.ts`:
-
-```ts
-console.log('generated a string');
-```
-
-### gen context
-
-The `Gen` function receives one argument, the `Gen_Context` object:
-
-```ts
-export interface Gen_Context {
-	config: Gro_Config;
-	sveltekit_config: Parsed_Sveltekit_Config;
-	/**
-	 * Same as `import.meta.url` but in path form.
-	 */
-	origin_id: Path_Id;
-	log: Logger;
-}
-// export const gen: Gen = ({config, origin_id, log}) => {
-```
-
-### generate other filetypes
-
-Files with any extension can be generated without configuration.
-If the origin file name ends with the pattern `.gen.*.ts`,
-the default output file name is stripped of its trailing `.ts`.
-
-Given `src/markup.gen.html.ts`:
-
-```ts
-import type {Gen} from '@ryanatkn/gro';
-
-export const gen: Gen = () => {
-	const body = 'hi';
-	return `
-		<!DOCTYPE html>
-		<html>
-			<body>
-				${body}
-			</body>
-		</html>
-	`;
-};
-```
-
-Outputs `src/markup.html`:
-
-```html
-<!doctype html>
-<html>
-	<body>
-		hi
-	</body>
-</html>
-```
-
-### generate a custom file name or write to a different directory
-
-The `gen` function can return an object with custom configuration.
-
-Given `src/somewhere/originalName.gen.ts`:
-
-```ts
-import type {Gen} from '@ryanatkn/gro';
-
-export const gen: Gen = () => {
-	const message = 'output path can be relative and name can be anything';
-	return {
-		content: `console.log('${message}')`,
-		filename: '../elsewhere/otherName.ts',
-		format: optional_boolean_that_defaults_to_true,
-	};
-};
-```
-
-Outputs `src/elsewhere/otherName.ts`:
-
-```ts
-console.log('output path can be relative and name can be anything');
-```
-
-### generate multiple custom files
-
-The `gen` function can also return an array of files.
-
-Given `src/thing.gen.ts`:
-
-```ts
-import type {Gen} from '@ryanatkn/gro';
-
-export const gen: Gen = () => {
-	const fieldValue = 1;
-	return [
-		{
-			content: `
-				import {Thing} from './index';
-				export const isThing = (t: any): t is Thing => t?.field === ${fieldValue};
-			`,
-		},
-		{
-			content: `export interface Thing { field: ${typeof fieldValue} }`,
-			filename: 'types.ts',
-		},
-		{
-			content: `{"field": ${fieldValue}}`,
-			filename: 'data/thing.json',
-		},
-	];
-};
-```
-
-Outputs `src/thing.ts`:
-
-```ts
-import type {Thing} from './index.js';
-export const isThing = (t: any): t is Thing => t?.field === 1;
-```
-
-and `src/types.ts`:
-
-```ts
-export interface Thing {
-	field: number;
-}
-```
-
-and `src/data/thing.json`:
-
-```json
-{
-	"field": 1
-}
-```
-
-It's often helpful to check if any generated files are new or have changed.
-We don't want to forget to regenerate files before committing or publishing!
-The `check` CLI argument can be passed to perform this check
-instead of writing the generated files to disk.
-
-```bash
-gro gen --check # exits with error code 1 if anything is new or different; no-op to the fs
-```
-
-or in code:
-
-```ts
-import type {Task} from '@ryanatkn/gro';
-
-export const task: Task = {
-	run: async ({args, invoke_task}) => {
-		// this throws a `Task_Error` if anything is new or different
-		await invoke_task('gen', {...args, check: true});
-	},
-};
-```
-
-Gro uses this in [`check.task.ts`](/src/lib/check.task.ts)
-which is called during `gro publish`, and it's recommended in CI.
-(see [Gro's example `check.yml`](/.github/workflows/check.yml))
-
-## todo
-
-- [x] basic functionality
-- [x] format output with Prettier
-- [x] [watch mode and build integration](https://github.com/ryanatkn/gro/pull/283),
-      opt out with `watch: false` for expensive gen use cases
-- [ ] change the exported `gen` function to an object with a `summary` and other properties like `watch`
-- [ ] support generating non-text files
-- [ ] think about how to handle gen file dependency graphs (generated files as inputs to gen files)

package/src/lib/docs/gro_plugin_sveltekit_app.md

@@ -1,113 +0,0 @@
-# SvelteKit app plugin
-
-Gro's [SvelteKit app plugin](/src/lib/gro_plugin_sveltekit_app.ts)
-calls `vite dev` and `vite build` with some additional behaviors.
-
-```ts
-// gro.config.ts
-import type {Gro_ConfigCreator} from '@ryanatkn/gro';
-import {gro_plugin_sveltekit_app} from '@ryanatkn/gro/gro_plugin_sveltekit_app.js';
-
-const config: Gro_ConfigCreator = async (cfg) => {
-	cfg.plugins = async () => [
-		// this is included in the default config for SvelteKit projects:
-		gro_plugin_sveltekit_app({
-			// host_target?: Host_Target;
-			// well_known_package_json?: boolean | Map_Package_Json;
-			// well_known_src_json?: boolean | Map_Src_Json;
-			// well_known_src_files?: boolean | Copy_File_Filter;
-		}),
-	];
-	return cfg;
-};
-
-export default config;
-
-// src/lib/gro_plugin_sveltekit_app.ts
-export type Host_Target = 'github_pages' | 'static' | 'node';
-
-export interface Copy_File_Filter {
-	(file_path: string): boolean | Promise<boolean>;
-}
-
-// src/lib/package_json.ts
-export interface Map_Package_Json {
-	(package_json: Package_Json): Package_Json | null | Promise<Package_Json | null>;
-}
-
-// src/lib/src_json.ts
-export interface Map_Src_Json {
-	(src_json: Src_Json): Src_Json | null | Promise<Src_Json | null>;
-}
-```
-
-## `host_target`
-
-When `host_target` is the default value `'github_pages'`,
-a `.nojekyll` file is included in the build to tell GitHub Pages not to process it with Jekyll.
-
-## `well_known_package_json`
-
-If your root `package.json` has `"public": true`
-(telling Gro it's a [public package](./package_json.md#public-packages)),
-by default Gro copies `.well-known/package.json` to `static/` during `vite build`,
-so it's included in the SvelteKit build output.
-The motivation is to provide conventional package metadata to web users and tools.
-(more details below)
-
-> ⚠️ Outputting `.well-known/package.json` will surprise some users
-> and could result in information leaks that compromise privacy or security.
-> The feature is enabled only when your root `package.json` has `"public": true`.
-> Templates that default to public should prominently warn their users.
-
-By default the root `package.json` is copied without modifications,
-and you can provide your own `well_known_package_json` option to
-mutate the `package_json`, return new data, or return `null` to be a no-op.
-
-> Writing to `.well-known/package.json` is unstandardized behavior that
-> extends [Well-known URIs](https://wikipedia.org/wiki/Well-known_URIs) for Node packages
-> to provide conventional metadata for deployed websites.
-> [Mastodon](<https://en.wikipedia.org/wiki/Mastodon_(social_network)>) uses
-> [WebFinger](https://en.wikipedia.org/wiki/WebFinger) which uses `.well-known` for discovery.
-> One difference is that SvelteKit outputs static files relative to the configured `base` path,
-> so the `.well-known` directory may not be in the root `/`.
-> This is useful because it enables websites to provide metadata even when hosted in a namespaced
-> path like `username.github.io/projectname/.well-known`.
-
-Why publish this metadata to the web instead of relying on the git repo as the only source of truth?
-
-- we want to give all web users and tools access to discoverable package metadata
-- metadata is a much lighter dependency than an entire repo
-- some repos are deployed to multiple websites with metadata differences
-- some repos like monorepos have multiple `package.json` files
-- we don't want to force a dependency on git, the bespoke URLs of forge hosts like GitHub,
-  or any particular toolchains
-- the git repo is still the source of truth, but Gro adds a build step for project metadata,
-  giving devs full control over the published artifacts
-  instead of coupling metadata directly to a source repo's `package.json`
-
-## `well_known_src_json`
-
-If your root `package.json` has `"public": true`,
-by default Gro creates `.well-known/src.json` and `.well-known/src/`
-in `static/` during `vite build`,
-so they're included in the SvelteKit build output.
-More [about public packages](./package_json.md#public-packages).
-
-This can be customized with `well_known_src_json`.
-Setting it to `false` disables the feature, and `true` enables it.
-Setting it to a function maps the final `src.json` value - returning `null` disables it.
-
-The `.well-known/src.json` file contains more details about
-the `package.json`'s `exports`, like exported identifier names and types.
-It maps each export to a source file in `.well-known/src/`.
-
-## `well_known_src_files`
-
-The contents of your `src/` directory can be included in the output
-if you want your app's source code to be available the same as the built files.
-This is disabled by default.
-If `well_known_src_files` is truthy,
-the plugin copies `src/` to `static/.well-known/src/` during `vite build`.
-Passing `true` uses the same filter as `exports` in `package.json` by default,
-and it also accepts a custom filter function.