@ryanatkn/gro 0.129.6 → 0.129.7

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

@@ -1,90 +0,0 @@
-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

@@ -1,37 +0,0 @@
-# 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

@@ -1,52 +0,0 @@
-# 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.