convex 1.40.0 → 1.41.0

package/src/cli/lib/generateDocs.test.ts

@@ -0,0 +1,326 @@
+import { describe, it, expect } from "vitest";
+import { Command } from "@commander-js/extra-typings";
+import { generateDocs, replaceBullets } from "./generateDocs.js";
+
+function makeFakeRoot() {
+  const greet = new Command("greet")
+    .description("Print a greeting")
+    .argument("<name>", "Who to greet")
+    .option("-l, --loud", "Shout the greeting");
+
+  const itemAdd = new Command("add")
+    .description("Add an item")
+    .argument("<name>", "Item name")
+    .option("--qty <n>", "Quantity");
+
+  const itemList = new Command("list").alias("ls").description("List items");
+
+  // A sub-subcommand whose leaf name (`create`) collides with `item add`'s
+  // sibling group leaf — exercises unique anchor generation for nesting.
+  const tokenCreate = new Command("create").description("Create a token");
+  const token = new Command("token")
+    .description("Manage tokens")
+    .addCommand(tokenCreate);
+
+  const itemCreate = new Command("create").description("Create an item");
+
+  const item = new Command("item")
+    .description("Manage items")
+    .addCommand(itemAdd)
+    .addCommand(itemList)
+    .addCommand(itemCreate)
+    .addCommand(token);
+
+  // A description whose body is an indented numbered list, like `convex dev`.
+  // These steps must render as a real ordered list, not bullets wrapping
+  // ordered-list items (which renders as roman numerals).
+  const steps = new Command("steps")
+    // Has no registered arguments, so its custom `.usage()` is preserved
+    // verbatim in the generated Usage line.
+    .usage("<command> [options]")
+    .description(
+      "Do things in order\n\n" + "  1. First step\n" + "  2. Second step\n",
+    );
+
+  // Mixes a code-span placeholder (must stay literal, no backslash) with a
+  // bare prose placeholder (must be escaped so MDX doesn't parse it as JSX).
+  const escape = new Command("escape").description(
+    "The positional `<nameOrToken>` is set by --team <team_slug>",
+  );
+
+  // Exercises rendering `npx convex ...` code spans in list items as copy
+  // buttons, while leaving code spans in plain prose lines untouched.
+  const envLike = new Command("envLike").description(
+    "- Set a variable: `npx convex env set NAME 'value'`\n" +
+      "Unrelated span: `npx convex run foo`",
+  );
+
+  // A description with a 3-level nested bullet list followed by a prose-led
+  // numbered list, like `convex deploy`. The nested sub-items (indented 2 and 4
+  // spaces) must keep their nesting, while the prose-led numbered list must be
+  // dedented to the left margin so it interrupts the paragraph.
+  const nested = new Command("nested").description(
+    [
+      "Pick a target like this:",
+      "- If FOO is set, use the default.",
+      "- If BAR is set, use its deployment.",
+      "  - When it's a preview key, deploy to a preview deployment:",
+      "    - with the current Git branch name in CI",
+      "    - or with the name from `--preview-name`",
+      "",
+      "Then it will:",
+      "  1. Typecheck your functions.",
+      "  2. Push to the deployment.",
+    ].join("\n"),
+  );
+
+  const secret = new Command("secret").description("Hidden command");
+
+  // Overrides `.usage()` to show its args as required (for nicer `--help`)
+  // even though they're registered as optional. The docs must reflect the
+  // registered optionality, not the override.
+  const config = new Command("config")
+    .description("Set config")
+    .usage("[options] <key> <value>")
+    .argument("[key]", "The config key")
+    .argument("[value]", "The value; omit to set interactively");
+
+  return new Command("fake")
+    .description("A fake CLI for testing generateDocs")
+    .usage("<command> [options]")
+    .addCommand(greet)
+    .addCommand(item)
+    .addCommand(config)
+    .addCommand(steps)
+    .addCommand(escape)
+    .addCommand(envLike)
+    .addCommand(nested)
+    .addCommand(secret, { hidden: true });
+}
+
+describe("generateDocs", () => {
+  it("creates one file per visible main command and no root index", () => {
+    const docs = generateDocs(makeFakeRoot());
+    const paths = Object.keys(docs).sort();
+    expect(paths).toEqual([
+      "config.mdx",
+      "envLike.mdx",
+      "escape.mdx",
+      "greet.mdx",
+      "item.mdx",
+      "nested.mdx",
+      "steps.mdx",
+    ]);
+    expect(docs["index.mdx"]).toBeUndefined();
+  });
+
+  it("does not emit a file for hidden subcommands", () => {
+    const docs = generateDocs(makeFakeRoot());
+    expect(docs["secret.mdx"]).toBeUndefined();
+  });
+
+  it("renders the command name as a heading with the npx prefix", () => {
+    const docs = generateDocs(makeFakeRoot());
+    expect(docs["greet.mdx"]).toContain("# `npx fake greet`");
+    expect(docs["greet.mdx"]).toContain("Print a greeting");
+  });
+
+  it("includes a @generated marker comment in every file", () => {
+    const docs = generateDocs(makeFakeRoot());
+    for (const md of Object.values(docs)) {
+      expect(md).toContain(
+        "{/* @generated from the command definitions, do not edit manually (run `just regenerate-cli-docs` to regenerate) */}",
+      );
+    }
+  });
+
+  it("emits sidebar_position frontmatter matching command definition order", () => {
+    const docs = generateDocs(makeFakeRoot());
+    expect(docs["greet.mdx"]).toMatch(/^---\nsidebar_position: 1\n/);
+    expect(docs["item.mdx"]).toMatch(/^---\nsidebar_position: 2\n/);
+  });
+
+  it("emits a title frontmatter with the full npx command so the page <title> isn't just the file name", () => {
+    const docs = generateDocs(makeFakeRoot());
+    expect(docs["greet.mdx"]).toMatch(/\ntitle: "npx fake greet"\n/);
+    expect(docs["item.mdx"]).toMatch(/\ntitle: "npx fake item"\n/);
+  });
+
+  it("emits a description frontmatter carrying the command summary", () => {
+    const docs = generateDocs(makeFakeRoot());
+    expect(docs["greet.mdx"]).toMatch(/\ndescription: "Print a greeting"\n/);
+    expect(docs["item.mdx"]).toMatch(/\ndescription: "Manage items"\n/);
+  });
+
+  it("uses `npx` in usage lines", () => {
+    const md = generateDocs(makeFakeRoot())["greet.mdx"];
+    expect(md).toMatch(/```sh\nnpx fake greet/);
+  });
+
+  it("documents arguments and options", () => {
+    const md = generateDocs(makeFakeRoot())["greet.mdx"];
+    expect(md).toContain("## Arguments");
+    expect(md).toContain("<name>");
+    expect(md).toContain("Who to greet");
+    expect(md).toContain("## Options");
+    expect(md).toContain("-l, --loud");
+  });
+
+  it("renders descendant subcommands as h2 sections with an id matching the leaf name", () => {
+    const md = generateDocs(makeFakeRoot())["item.mdx"];
+    expect(md).toContain("## `npx fake item add` \\{#add}");
+    expect(md).toContain("## `npx fake item list` \\{#list}");
+    expect(md).toContain("### Usage");
+  });
+
+  it("documents aliases for nested subcommands inside the main command file", () => {
+    const md = generateDocs(makeFakeRoot())["item.mdx"];
+    expect(md).toContain("### Aliases");
+    expect(md).toContain("`ls`");
+  });
+
+  it("links nested subcommand list entries to in-page anchors", () => {
+    const md = generateDocs(makeFakeRoot())["item.mdx"];
+    expect(md).toContain("## Subcommands");
+    expect(md).toContain("[`npx fake item add`](#add)");
+    expect(md).toContain("[`npx fake item list`](#list)");
+  });
+
+  it("gives sub-subcommands a path-based anchor so leaf names don't collide", () => {
+    const md = generateDocs(makeFakeRoot())["item.mdx"];
+    // `item create` keeps the bare leaf anchor...
+    expect(md).toContain("## `npx fake item create` \\{#create}");
+    // ...while `item token create` is namespaced to avoid a duplicate `#create`.
+    expect(md).toContain("### `npx fake item token create` \\{#token-create}");
+    expect(md).not.toContain("`npx fake item token create` \\{#create}");
+  });
+
+  it("renders sub-subcommands at a deeper heading level than their parent group", () => {
+    const md = generateDocs(makeFakeRoot())["item.mdx"];
+    // `item token` is a direct subcommand (h2)...
+    expect(md).toContain("## `npx fake item token` \\{#token}");
+    // ...and its child `item token create` nests one level deeper (h3).
+    expect(md).toContain("### `npx fake item token create` \\{#token-create}");
+  });
+
+  it("produces unique heading anchor ids within a file", () => {
+    const md = generateDocs(makeFakeRoot())["item.mdx"];
+    const anchors = [...md.matchAll(/\\\{#([\w-]+)}/g)].map((m) => m[1]);
+    expect(new Set(anchors).size).toBe(anchors.length);
+  });
+
+  it("links sub-subcommand list entries to their path-based anchors", () => {
+    const md = generateDocs(makeFakeRoot())["item.mdx"];
+    // `token` is a direct child of `item`, listed in item's Subcommands.
+    expect(md).toContain("[`npx fake item token`](#token)");
+  });
+
+  it("derives the usage line from registered argument optionality, ignoring a conflicting .usage() override", () => {
+    const md = generateDocs(makeFakeRoot())["config.mdx"];
+    // The command overrides .usage() with `<key> <value>`, but the args are
+    // registered as optional, so the Usage line must match the Arguments
+    // section (`[key]`/`[value]`) rather than the override.
+    expect(md).toContain("```sh\nnpx fake config [options] [key] [value]\n```");
+    expect(md).not.toContain("<key> <value>");
+    expect(md).toContain("`[key]`");
+    expect(md).toContain("`[value]`");
+  });
+
+  it("keeps the .usage() override for commands with no registered arguments", () => {
+    // `steps` has no positional args, so its custom `<command> [options]`
+    // usage is preserved verbatim.
+    const md = generateDocs(makeFakeRoot())["steps.mdx"];
+    expect(md).toContain("```sh\nnpx fake steps <command> [options]\n```");
+  });
+
+  it("renders an indented numbered description as an ordered list, not bullets", () => {
+    const md = generateDocs(makeFakeRoot())["steps.mdx"];
+    expect(md).toContain("1. First step");
+    expect(md).toContain("2. Second step");
+    // Must not wrap the ordered-list items in bullets (renders as roman numerals).
+    expect(md).not.toContain("- 1. First step");
+  });
+
+  it("preserves the nesting of a multi-level list that follows list items", () => {
+    const md = generateDocs(makeFakeRoot())["nested.mdx"];
+    // Top-level items stay at the left margin.
+    expect(md).toContain("\n- If BAR is set, use its deployment.\n");
+    // The 2-space sub-item stays nested under its parent (not flattened to the
+    // left margin, which was the bug when deeper-indented lines flushed early).
+    expect(md).toContain(
+      "\n  - When it's a preview key, deploy to a preview deployment:\n",
+    );
+    expect(md).not.toContain("\n- When it's a preview key");
+    // The 4-space sub-sub-items keep their deeper nesting.
+    expect(md).toContain("\n    - with the current Git branch name in CI\n");
+    expect(md).toContain("\n    - or with the name from `--preview-name`\n");
+  });
+
+  it("dedents a prose-led numbered list to the left margin so it interrupts the paragraph", () => {
+    const md = generateDocs(makeFakeRoot())["nested.mdx"];
+    // The numbered list follows prose ("Then it will:"), so it must be dedented
+    // to the left margin to render as an ordered list rather than collapsing
+    // into the preceding paragraph.
+    expect(md).toContain("\n1. Typecheck your functions.\n");
+    expect(md).toContain("\n2. Push to the deployment.\n");
+    expect(md).not.toContain("  1. Typecheck your functions.");
+  });
+
+  it("escapes JSX-like placeholders in prose but leaves inline code spans alone", () => {
+    const md = generateDocs(makeFakeRoot())["escape.mdx"];
+    // Inside backticks `<nameOrToken>` is already literal — no backslash.
+    expect(md).toContain("`<nameOrToken>`");
+    expect(md).not.toContain("`\\<nameOrToken>`");
+    // In prose, the bare placeholder is escaped so MDX won't parse it as a tag.
+    expect(md).toContain("--team \\<team_slug>");
+  });
+
+  it("renders `npx convex ...` code spans in list items as CodeWithCopyButton, leaving prose spans as code", () => {
+    const md = generateDocs(makeFakeRoot())["envLike.mdx"];
+    // Commands in list items become copy buttons.
+    expect(md).toContain(
+      `<CodeWithCopyButton text={"npx convex env set NAME 'value'"} />`,
+    );
+    // Code spans outside of list items stay as inline code.
+    expect(md).toContain("`npx convex run foo`");
+    expect(md).not.toContain(`text={"npx convex run foo"}`);
+  });
+});
+
+describe("replaceBullets", () => {
+  it("replaces a leading `• ` bullet with `- `", () => {
+    expect(replaceBullets("• an item")).toBe("- an item");
+  });
+
+  it("preserves leading indentation", () => {
+    expect(replaceBullets("  • an item")).toBe("  - an item");
+    expect(replaceBullets("    • a deeper item")).toBe("    - a deeper item");
+  });
+
+  it("replaces bullets on every line of a multi-line string", () => {
+    const input = "• first\n• second\n  • nested";
+    expect(replaceBullets(input)).toBe("- first\n- second\n  - nested");
+  });
+
+  it("leaves lines without a `• ` bullet untouched", () => {
+    const input = "Plain prose\nAnother line";
+    expect(replaceBullets(input)).toBe(input);
+  });
+
+  it("only replaces bullets at the start of a line, not mid-line", () => {
+    expect(replaceBullets("a • b")).toBe("a • b");
+  });
+
+  it("requires a space after the bullet", () => {
+    expect(replaceBullets("•noSpace")).toBe("•noSpace");
+  });
+
+  it("collapses only the single space following the bullet", () => {
+    // Extra spaces after the `• ` are preserved.
+    expect(replaceBullets("•  two spaces")).toBe("-  two spaces");
+  });
+
+  it("returns an empty string unchanged", () => {
+    expect(replaceBullets("")).toBe("");
+  });
+});