feat: twoslash

Author: so1ve

docs/.vitepress/config/shared.ts

@@ -1,13 +1,17 @@
+import { transformerTwoslash } from "@shikijs/vitepress-twoslash";
+import { createFileSystemTypesCache } from "@shikijs/vitepress-twoslash/cache-fs";
 import UnoCSS from "unocss/vite";
 import { defineConfig } from "vitepress";
 import {
 	groupIconMdPlugin,
 	groupIconVitePlugin,
 } from "vitepress-plugin-group-icons";
 
+import { MarkdownTransform, clercImports } from "../plugins/markdownTransform";
+
 export const sharedConfig = defineConfig({
 	title: "Clerc",
-	appearance: "dark",
+	// appearance: "dark",
 	lastUpdated: true,
 	head: [["link", { rel: "icon", href: "/logo.webp", type: "image/webp" }]],
 	themeConfig: {
@@ -30,8 +34,25 @@ export const sharedConfig = defineConfig({
 		config(md) {
 			md.use(groupIconMdPlugin);
 		},
+		codeTransformers: [
+			transformerTwoslash({
+				twoslashOptions: {
+					handbookOptions: {
+						noErrors: true,
+					},
+				},
+				includesMap: new Map([
+					[
+						"imports",
+						`// ---cut-start---\nimport { ${clercImports.join(", ")} } from "clerc";\n// ---cut-end---`,
+					],
+				]),
+				typesCache: createFileSystemTypesCache(),
+			}),
+		],
+		languages: ["js", "jsx", "ts", "tsx"],
 	},
 	vite: {
-		plugins: [groupIconVitePlugin(), UnoCSS()],
+		plugins: [groupIconVitePlugin(), UnoCSS(), MarkdownTransform()],
 	},
 });

docs/.vitepress/plugins/markdownTransform.ts

@@ -0,0 +1,34 @@
+import type { Plugin } from "vitepress";
+
+const TAB_SIZE = 2;
+
+// @keep-sorted
+export const clercImports = [
+	"Clerc",
+	"completionsPlugin",
+	"friendlyErrorPlugin",
+	"helpPlugin",
+	"notFoundPlugin",
+	"strictFlagsPlugin",
+	"versionPlugin",
+];
+
+export const MarkdownTransform = (): Plugin => ({
+	name: "clerc-markdown-transform",
+	enforce: "pre",
+	transform(code, id) {
+		if (!id.endsWith(".md")) {
+			return;
+		}
+
+		return code
+			.replace(/```(ts|typescript)([^\n]*)\n/g, (match, lang, attrs) => {
+				if (!attrs.includes("twoslash")) {
+					attrs += " twoslash";
+				}
+
+				return `\`\`\`${lang}${attrs}\n// @include: imports\n`;
+			})
+			.replace(/\t/g, " ".repeat(TAB_SIZE));
+	},
+});

docs/.vitepress/theme/index.ts

@@ -1,9 +1,15 @@
+import TwoslashFloatingVue from "@shikijs/vitepress-twoslash/client";
+import type { EnhanceAppContext } from "vitepress";
 import Theme from "vitepress/theme";
 
 import "./style.css";
 import "virtual:uno.css";
 import "virtual:group-icons.css";
+import "@shikijs/vitepress-twoslash/style.css";
 
 export default {
 	extends: Theme,
+	enhanceApp({ app }: EnhanceAppContext) {
+		app.use(TwoslashFloatingVue);
+	},
 };

docs/commands.md

@@ -26,9 +26,7 @@ This creates a CLI application named `foo-cli` with a command called `foo`. When
 
 You can add an alias for your command:
 
-```js
-import { Clerc } from "clerc";
-
+```ts
 const cli = Clerc.create()
 	.scriptName("foo-cli")
 	.description("A simple CLI")
@@ -46,9 +44,7 @@ Now both `foo-cli foo` and `foo-cli bar` will output "It works!".
 
 You can add more aliases:
 
-```js
-import { Clerc } from "clerc";
-
+```ts
 const cli = Clerc.create()
 	.scriptName("foo-cli")
 	.description("A simple CLI")
@@ -66,9 +62,7 @@ const cli = Clerc.create()
 
 You can define subcommands by using spaces in the command name:
 
-```js
-import { Clerc } from "clerc";
-
+```ts
 const cli = Clerc.create()
 	.scriptName("foo-cli")
 	.description("A simple CLI")
@@ -84,9 +78,7 @@ const cli = Clerc.create()
 
 You can define a root command (a command with no name) to handle cases when no subcommand is specified:
 
-```js
-import { Clerc } from "clerc";
-
+```ts
 const cli = Clerc.create()
 	.scriptName("foo-cli")
 	.description("A simple CLI")
@@ -120,7 +112,6 @@ Example:
 
 ```ts
 // $ node ./foo-cli.mjs a b c d
-import { Clerc } from "clerc";
 
 const cli = Clerc.create()
 	.scriptName("foo-cli")
@@ -134,16 +125,18 @@ const cli = Clerc.create()
 		],
 	})
 	.on("foo", (ctx) => {
-		ctx.parameters.requiredParameter; // => "a" (string)
-		ctx.parameters.optionalParameter; // => "b" (string | undefined)
-		ctx.parameters.optionalSpread; // => ["c", "d"] (string[])
+		ctx.parameters;
+		//  ^?
+		ctx.parameters.requiredParameter; // => "a"
+		ctx.parameters.optionalParameter; // => "b"
+		ctx.parameters.optionalSpread; // => ["c", "d"]
 	})
 	.parse();
 ```
 
-### End Flag
+### End-of-file
 
-The end flag (`--`) (also known as _option terminator_) allows users to pass a portion of arguments. This is useful for arguments that should be parsed separately from other arguments or arguments that look like options.
+The end-of-file (`--`) (also known as _flag terminator_) allows users to pass a portion of arguments. This is useful for arguments that should be parsed separately from other arguments or arguments that look like flags.
 
 An example is [`npm run`](https://docs.npmjs.com/cli/v8/commands/npm-run-script):
 
@@ -153,13 +146,12 @@ $ npm run <script> -- <script arguments>
 
 The `--` indicates that all arguments after it should be passed to the _script_ rather than _npm_.
 
-You can specify `--` in the `parameters` array to parse option terminator arguments.
+You can specify `--` in the `parameters` array to parse flag terminator arguments.
 
 Example:
 
 ```ts
 // $ node ./foo-cli.mjs echo -- hello world
-import { Clerc } from "clerc";
 
 const cli = Clerc.create()
 	.scriptName("foo-cli")
@@ -169,36 +161,37 @@ const cli = Clerc.create()
 		parameters: ["<script>", "--", "[arguments...]"],
 	})
 	.on("echo", (ctx) => {
-		ctx.parameters.script; // => "echo" (string)
-		ctx.parameters.arguments; // => ["hello", "world"] (string[])
+		ctx.parameters;
+		//  ^?
+		ctx.parameters.script; // => "echo"
+		ctx.parameters.arguments; // => ["hello", "world"]
 	})
 	.parse();
 ```
 
-## Options
+## Flags
 
-_Clerc_'s option parsing is powered by [`@clerc/parser`](https://github.com/clercjs/clerc/blob/main/packages/parser) and has many features:
+_Clerc_'s flag parsing is powered by [`@clerc/parser`](https://github.com/clercjs/clerc/blob/main/packages/parser) and has many features:
 
 - Array and custom types
-- Option delimiters: `--flag value`, `--flag=value`, `--flag:value` and `--flag.value`
+- Flag delimiters: `--flag value`, `--flag=value`, `--flag:value` and `--flag.value`
 - Combined aliases: `-abcd 2` → `-a -b -c -d 2`
-- [Option terminator](https://unix.stackexchange.com/a/11382): pass `--` to end option parsing
+- [End-of-file](https://unix.stackexchange.com/a/11382): pass `--` to end parsing
 
-Options can be specified in the `flags` object property, where the key is the option name and the value is either an option type function or an object describing the option.
+Flags can be specified in the `flags` object property, where the key is the flag name and the value is either an flag type function or an object describing the flag.
 
-It's recommended to use camelCase for option names as it will be interpreted as parsing the equivalent kebab-case option.
+It's recommended to use camelCase for flag names as it will be interpreted as parsing the equivalent kebab-case flag.
 
-The option type function can be any function that accepts a string and returns the parsed value. The default JavaScript constructors should cover most use cases: [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/String), [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/Number), [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean/Boolean), etc.
+The flag type function can be any function that accepts a string and returns the parsed value. The default JavaScript constructors should cover most use cases: [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/String), [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/Number), [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean/Boolean), etc.
 
-The option description object can be used to store additional information about the option, such as `alias`, `default`, and `description`. To accept multiple values for an option, wrap the type function in an array.
+The flag description object can be used to store additional information about the flag, such as `alias`, `default`, and `description`. To accept multiple values for a flag, wrap the type function in an array.
 
 All provided information will be used to generate better help documentation.
 
 Example:
 
 ```ts
 // $ node ./foo-cli.mjs echo --some-boolean --some-string hello --some-number 1 -n 2
-import { Clerc } from "clerc";
 
 const cli = Clerc.create()
 	.scriptName("foo-cli")
@@ -208,12 +201,12 @@ const cli = Clerc.create()
 		flags: {
 			someBoolean: {
 				type: Boolean,
-				description: "Some boolean option",
+				description: "Some boolean flag",
 			},
 
 			someString: {
 				type: String,
-				description: "Some string option",
+				description: "Some string flag",
 				default: "n/a",
 			},
 
@@ -225,37 +218,39 @@ const cli = Clerc.create()
 			},
 
 			object: {
-				type: object,
-				description: "An object option. (e.g. --object.key value)",
+				type: Object,
+				description: "An object flag. (e.g. --object.key value)",
 			},
 
 			counter: {
 				type: [Boolean],
-				description: "A counter option. (e.g. -c -c -c)",
+				description: "A counter flag. (e.g. -c -c -c)",
 			},
 		},
 	})
 	.on("echo", (ctx) => {
-		ctx.flags.someBoolean; // => true (boolean | undefined)
-		ctx.flags.someString; // => "hello" (string)
-		ctx.flags.someNumber; // => [1, 2] (number[])
-		ctx.flags.object; // => { key: "value" } (Record<string, string | boolean>)
-		ctx.flags.counter; // => 2 (number)
+		ctx.flags;
+		//	^?
+		ctx.flags.someBoolean; // => true
+		ctx.flags.someString; // => "hello"
+		ctx.flags.someNumber; // => [1, 2]
+		ctx.flags.object; // => { key: "value" }
+		ctx.flags.counter; // => 2
 	})
 	.parse();
 ```
 
 ## Ignore
 
-Sometimes, you may want to ignore certain arguments or options in the command line input. For example, this usage of `deno`:
+Sometimes, you may want to ignore certain arguments or flags in the command line input. For example, this usage of `deno`:
 
 ```sh
 deno run --allow-read script.ts --flag
 ```
 
 Where `--flag` is passed directly to the script, not to `deno`.
 
-You can achieve this usage by using the `ignore` property to specify which arguments or options to ignore.
+You can achieve this usage by using the `ignore` property to specify which arguments or flags to ignore.
 
 ```ts
 import { Clerc, PARAMETER } from "clerc";
@@ -287,7 +282,8 @@ const cli = Clerc.create()
 	})
 	.on("run", (ctx) => {
 		// Handle script execution
-		ctx.ignored; // => ["--flag"] (string[])
+		ctx.ignored; // => ["--flag"]
+		//	^?
 	})
 	.parse();
 ```

docs/getting-started.md

@@ -39,8 +39,6 @@ $ pnpm add clerc
 Install clerc, and create a file named `cli.mjs`:
 
 ```ts
-import { Clerc } from "clerc";
-
 Clerc.create() // Create a new Clerc instance
 	.scriptName("foo") // CLI script name
 	.description("A foo CLI") // CLI description

docs/interceptors.md

@@ -39,8 +39,6 @@ Attention! When calling `next`, make sure to use `await`, otherwise errors might
 The `interceptor` method accepts either a function or an object:
 
 ```ts
-import { Clerc } from "clerc";
-
 const cli = Clerc.create()
 	.scriptName("foo-cli")
 	.description("A simple CLI")
@@ -70,8 +68,6 @@ Therefore, the execution order is as follows:
 By performing operations after calling `next()`, you can execute some actions after the command handler is called:
 
 ```ts
-import { Clerc } from "clerc";
-
 const cli = Clerc.create()
 	.scriptName("foo-cli")
 	.description("A simple CLI")

docs/official-plugins/plugin-completions.md

@@ -26,12 +26,17 @@ $ pnpm add @clerc/plugin-completions
 
 ## 🚀 Usage
 
-### Basic Usage
+### Import
 
 ```ts
-import { completionsPlugin } from "@clerc/plugin-completions"; // or import directly from clerc
-import { Clerc } from "clerc";
+import { completionsPlugin } from "@clerc/plugin-completions";
+// or import directly from clerc
+import { completionsPlugin } from "clerc";
+```
+
+### Basic Usage
 
+```ts
 const cli = Clerc.create()
 	.scriptName("my-cli")
 	.description("My CLI application")
@@ -95,8 +100,6 @@ The plugin automatically generates complete auto-completion scripts for your CLI
 ### Advanced Configuration
 
 ```ts
-import { completionsPlugin } from "@clerc/plugin-completions"; // or import directly from clerc
-
 const cli = Clerc.create()
 	.scriptName("my-cli")
 	.description("My CLI application")

docs/official-plugins/plugin-friendly-error.md

@@ -26,12 +26,17 @@ $ pnpm add @clerc/plugin-friendly-error
 
 ## 🚀 Usage
 
-### Basic Usage
+### Import
 
 ```ts
-import { friendlyErrorPlugin } from "@clerc/plugin-friendly-error"; // or import directly from clerc
-import { Clerc } from "clerc";
+import { friendlyErrorPlugin } from "@clerc/plugin-friendly-error";
+// or import directly from clerc
+import { friendlyErrorPlugin } from "clerc";
+```
 
+### Basic Usage
+
+```ts
 const cli = Clerc.create()
 	.scriptName("my-cli")
 	.description("My CLI application")