argsbarg 5.0.1 → 5.0.3

package/src/parse.test.ts

@@ -31,6 +31,7 @@ import {
 } from "./test-fixtures.ts";
 import { cliValidateProgram } from "./validate.ts";
 
+/** Tests that bundled short presence flags. */
 test("bundled short presence flags", () => {
   const root = testProgram({
     key: "app",
@@ -64,6 +65,7 @@ test("bundled short presence flags", () => {
   expect(pr.opts.b).toBe("1");
 });
 
+/** Tests that long option equals. */
 test("long option equals", () => {
   const root = testProgram({
     key: "app",
@@ -89,6 +91,7 @@ test("long option equals", () => {
   expect(pr.opts.name).toBe("pat");
 });
 
+/** Tests that fallback missing or unknown root flags. */
 test("fallback missing or unknown root flags", () => {
   const root = testProgram({
     key: "app",
@@ -141,6 +144,7 @@ test("implicit help empty", () => {
   expect(pr.helpExplicit).toBe(false);
 });
 
+/** Invalid number post validate. */
 test("invalid number post validate", () => {
   const root = testProgram({
     key: "app",
@@ -167,6 +171,7 @@ test("invalid number post validate", () => {
   expect(pr.errorMsg).toContain("Invalid number");
 });
 
+/** Supports scientific notation in numbers. */
 test("supports scientific notation in numbers", () => {
   const root = testProgram({
     key: "app",
@@ -193,6 +198,7 @@ test("supports scientific notation in numbers", () => {
   expect(Number(pr.opts.n)).toBe(12300);
 });
 
+/** Completion scripts contain app name. */
 test("completion scripts contain app name", () => {
   const root = testProgram({
     key: "myapp",
@@ -210,6 +216,7 @@ test("completion scripts contain app name", () => {
   expect(zsh).toContain("hello:Say hello.");
 });
 
+/** Completion scripts do not emit invalid bash substitutions. */
 test("completion scripts do not emit invalid bash substitutions", () => {
   const root = testProgram({
     key: "app",
@@ -221,6 +228,7 @@ test("completion scripts do not emit invalid bash substitutions", () => {
   expect(bash).not.toContain("${${");
 });
 
+/** Completion scripts escape shell-sensitive command text in zsh. */
 test("completion scripts escape shell-sensitive command text in zsh", () => {
   const root = testProgram({
     key: "app",
@@ -238,6 +246,7 @@ test("completion scripts escape shell-sensitive command text in zsh", () => {
   expect(zsh).toContain("quote'\\''cmd:Say '\\''hello'\\'' and keep going.");
 });
 
+/** Completion scripts keep dotted app names in registration names. */
 test("completion scripts keep dotted app names in registration names", () => {
   const root = testProgram({
     key: "minimal.ts",
@@ -253,6 +262,7 @@ test("completion scripts keep dotted app names in registration names", () => {
   expect(zsh).toContain("compdef _minimal_ts minimal.ts");
 });
 
+/** Tests that trailing options after bounded positionals. */
 test("trailing options after bounded positionals", () => {
   const root = testProgram({
     key: "app",
@@ -286,6 +296,7 @@ test("trailing options after bounded positionals", () => {
   expect(pr.opts.verbose).toBe("1");
 });
 
+/** Tests that trailing options include parent-scoped flags. */
 test("trailing options include parent-scoped flags", () => {
   const root = testProgram({
     key: "app",
@@ -338,6 +349,7 @@ test("trailing options include parent-scoped flags", () => {
   expect(pr.opts.json).toBe("1");
 });
 
+/** Varargs tail parses trailing options. */
 test("varargs tail parses trailing options", () => {
   const root = testProgram({
     key: "app",
@@ -373,6 +385,7 @@ test("varargs tail parses trailing options", () => {
   expect(pr.opts.json).toBe("1");
 });
 
+/** Stops parsing options at --. */
 test("stops parsing options at --", () => {
   const root = testProgram({
     key: "app",
@@ -411,6 +424,7 @@ test("stops parsing options at --", () => {
   expect(pr.args).toEqual(["--name", "bob", "-x"]);
 });
 
+/** Missing required option returns error. */
 test("missing required option returns error", () => {
   const root = testProgram({
     key: "app",
@@ -437,6 +451,7 @@ test("missing required option returns error", () => {
   expect(pr.errorMsg).toContain("Missing required option: --req");
 });
 
+/** Provided required option parses ok. */
 test("provided required option parses ok", () => {
   const root = testProgram({
     key: "app",
@@ -463,6 +478,7 @@ test("provided required option parses ok", () => {
   expect(pr.opts.req).toBe("val");
 });
 
+/** Tests that presence option cannot be required. */
 test("presence option cannot be required", () => {
   const root = testProgram({
     key: "app",
@@ -499,6 +515,7 @@ test("leaf completion help prints correctly", async () => {
   expect(stderr.toString()).toBe("");
 });
 
+/** Docs schema exports JSON for nested CLIs. */
 test("docs schema exports JSON for nested CLIs", async () => {
   const { stdout, stderr, exitCode } = await $`bun run examples/nested.ts docs schema`
     .nothrow()
@@ -517,6 +534,7 @@ test("docs schema exports JSON for nested CLIs", async () => {
   expect(lookup.positionals[0].name).toBe("path");
 });
 
+/** Docs schema exports JSON for leaf roots. */
 test("docs schema exports JSON for leaf roots", async () => {
   const { stdout, exitCode } = await $`bun run examples/minimal.ts docs schema`.nothrow().quiet();
   expect(exitCode).toBe(0);
@@ -545,6 +563,7 @@ test("leaf root help omits hidden completion built-in", async () => {
   expect(stdout.toString()).toContain("configure");
 });
 
+/** Root --schema is no longer a flag. */
 test("root --schema is no longer a flag", () => {
   const root = testProgram({
     key: "app",
@@ -567,6 +586,7 @@ test("root --schema is no longer a flag", () => {
   expect(pr.kind).not.toBe(ParseKind.Ok);
 });
 
+/** CliSchemaJson omits handlers and completion built-ins. */
 test("cliSchemaJson omits handlers and completion built-ins", () => {
   const root = testProgram({
     key: "app",
@@ -597,6 +617,7 @@ test("cliSchemaJson omits handlers and completion built-ins", () => {
   expect(schema).not.toHaveProperty("handler");
 });
 
+/** CliSchemaExport resolves program key in install notes. */
 test("cliSchemaExport resolves program key in install notes", () => {
   const root = testProgram({
     key: "myapp",
@@ -616,6 +637,7 @@ test("cliSchemaExport resolves program key in install notes", () => {
   expect(json).toContain("brew install");
 });
 
+/** CliSchemaExport resolves {argsbarg:program} in consumer notes. */
 test("cliSchemaExport resolves {argsbarg:program} in consumer notes", () => {
   const root = testProgram({
     key: "myapp",
@@ -635,6 +657,7 @@ test("cliSchemaExport resolves {argsbarg:program} in consumer notes", () => {
   expect(schema.commands[0].notes).toBe("Run `myapp run` to start.");
 });
 
+/** Docs help lists schema, api, and skill subcommands. */
 test("docs help lists schema, api, and skill subcommands", () => {
   const root = testProgram({
     key: "app",
@@ -661,6 +684,7 @@ test("docs help lists schema, api, and skill subcommands", () => {
   expect(help).toContain("reference agent SKILL");
 });
 
+/** Root help omits legacy --schema flag. */
 test("root help omits legacy --schema flag", () => {
   const root = testProgram({
     key: "app",
@@ -678,6 +702,7 @@ test("root help omits legacy --schema flag", () => {
   expect(help).not.toContain("--schema");
 });
 
+/** Root help shows agent docs hint when docs enabled. */
 test("root help shows agent docs hint when docs enabled", () => {
   const root = testProgram({
     key: "myapp",
@@ -706,6 +731,7 @@ test("root help omits agent hint when docs disabled", () => {
   expect(help).not.toContain("docs skill");
 });
 
+/** Root help includes program notes and agent hint. */
 test("root help includes program notes and agent hint", () => {
   const root = testProgram({
     key: "myapp",
@@ -750,6 +776,7 @@ test("cliValidateProgram rejects Enum with duplicate choices", () => {
   expect(() => cliValidateProgram(root)).toThrow(/choices must be distinct/);
 });
 
+/** McpTool.description override wins without env suffix. */
 test("mcpTool.description override wins without env suffix", () => {
   const root = testProgram({
     key: "app",
@@ -778,6 +805,7 @@ test("cliValidateProgram requires program.appConfig description", () => {
   expect(() => cliValidateProgram(root)).toThrow(/description must be a non-empty string/);
 });
 
+/** CliValidateProgram rejects duplicate mcpResources URIs. */
 test("cliValidateProgram rejects duplicate mcpResources URIs", () => {
   const root = testProgram({
     key: "app",
@@ -837,6 +865,7 @@ test("cliValidateProgram rejects resource URI matching default schema URI", () =
   expect(() => cliValidateProgram(root)).toThrow(/conflicts with built-in schema resource/);
 });
 
+/** CliValidateProgram rejects resource URI matching schemaResourceUri. */
 test("cliValidateProgram rejects resource URI matching schemaResourceUri", () => {
   const root = testProgram({
     key: "app",
@@ -851,6 +880,7 @@ test("cliValidateProgram rejects resource URI matching schemaResourceUri", () =>
   expect(() => cliValidateProgram(root)).toThrow(/conflicts with built-in schema resource/);
 });
 
+/** CliValidateProgram rejects resource URI matching auto docs topic. */
 test("cliValidateProgram rejects resource URI matching auto docs topic", () => {
   const root = testProgram({
     key: "app",
@@ -865,6 +895,7 @@ test("cliValidateProgram rejects resource URI matching auto docs topic", () => {
   expect(() => cliValidateProgram(root)).toThrow(/conflicts with auto docs topic resource/);
 });
 
+/** AllMcpResources includes custom resources. */
 test("allMcpResources includes custom resources", () => {
   const root = testProgram({
     key: "app",
@@ -880,6 +911,7 @@ test("allMcpResources includes custom resources", () => {
   expect(resources.map((r) => r.uri)).toContain("test://x");
 });
 
+/** AllMcpResources includes docs topic resources. */
 test("allMcpResources includes docs topic resources", () => {
   const root = testProgram({
     key: "app",
@@ -894,6 +926,7 @@ test("allMcpResources includes docs topic resources", () => {
   expect(readme?.load()).toBe("# hi\n");
 });
 
+/** ApplyShellEnv merges PATH and preserves host vars. */
 test("applyShellEnv merges PATH and preserves host vars", () => {
   const origPath = process.env.PATH ?? "";
   const origHome = process.env.HOME;
@@ -913,6 +946,7 @@ test("applyShellEnv merges PATH and preserves host vars", () => {
   delete process.env.NEWVAR;
 });
 
+/** Enum completions list choices in bash script. */
 test("Enum completions list choices in bash script", () => {
   const root = testProgram({
     key: "app",
@@ -942,6 +976,7 @@ test("nested fallback routes to default when argv exhausted at router", () => {
   expect(pr.path).toEqual(["docs", "guide"]);
 });
 
+/** Nested fallback MissingOrUnknown routes unknown token to default. */
 test("nested fallback MissingOrUnknown routes unknown token to default", () => {
   const root = testProgram({
     key: "app",
@@ -991,6 +1026,7 @@ test("nested fallback MissingOnly errors on unknown subcommand", () => {
   expect(pr.errorMsg).toContain("Unknown subcommand");
 });
 
+/** CliValidateProgram rejects invalid nested fallbackCommand. */
 test("cliValidateProgram rejects invalid nested fallbackCommand", () => {
   const root = testProgram({
     key: "app",
@@ -1106,6 +1142,7 @@ test("mcpToolCallToArgv empty array varargs errors when required", () => {
 
 // ── Skills ────────────────────────────────────────────────────────────────────
 
+/** Configure config on non-root node is rejected. */
 test("configure config on non-root node is rejected", () => {
   const root = {
     key: "app",
@@ -1134,6 +1171,7 @@ test("configure.prefix is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/configure\.prefix removed/);
 });
 
+/** Tests that generateSkillBundle includes frontmatter and compact command index. */
 test("generateSkillBundle includes frontmatter and compact command index", () => {
   const bundle = generateSkillBundle(nestedMcpFixture, "cursor");
   expect(bundle.dirName).toBe("nested_ts");
@@ -1154,6 +1192,7 @@ test("generateSkillBundle includes frontmatter and compact command index", () =>
   expect(bundle.referenceMd).not.toContain("```json");
 });
 
+/** Tests that generatePluginSkillBundle is MCP routing stub without shell catalog. */
 test("generatePluginSkillBundle is MCP routing stub without shell catalog", () => {
   const bundle = generatePluginSkillBundle(nestedMcpFixture);
   expect(bundle.dirName).toBe("nested_ts");
@@ -1168,6 +1207,7 @@ test("generatePluginSkillBundle is MCP routing stub without shell catalog", () =
   expect(bundle.skillMd).not.toContain("## Commands");
 });
 
+/** CliSkillInstall writes project Cursor skill files. */
 test("cliSkillInstall writes project Cursor skill files", () => {
   const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-"));
   const prev = process.cwd();
@@ -1192,6 +1232,7 @@ test("cliSkillInstall writes project Cursor skill files", () => {
   }
 });
 
+/** CliSkillInstall global uses HOME skills directory. */
 test("cliSkillInstall global uses HOME skills directory", () => {
   const home = mkdtempSync(join(tmpdir(), "argsbarg-home-"));
   const prevHome = process.env.HOME;
@@ -1210,6 +1251,7 @@ test("cliSkillInstall global uses HOME skills directory", () => {
   }
 });
 
+/** CliSkillInstall rimraf overwrites existing directory. */
 test("cliSkillInstall rimraf overwrites existing directory", () => {
   const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-dup-"));
   const prev = process.cwd();
@@ -1228,6 +1270,7 @@ test("cliSkillInstall rimraf overwrites existing directory", () => {
   }
 });
 
+/** CliSkillInstall claude target uses .claude/skills. */
 test("cliSkillInstall claude target uses .claude/skills", () => {
   const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-claude-"));
   const prev = process.cwd();