feat: create script to generate CLI reference docs (#1015)

Author: davidturnbull

.changeset/witty-radios-admire.md

@@ -0,0 +1,2 @@
+---
+---

packages/cli/src/cli/cmd/logout.ts

@@ -10,7 +10,7 @@ import {
 
 export default new Command()
   .command("logout")
-  .description("Sign out from Lingo.dev API")
+  .description("Log out from Lingo.dev API")
   .helpOption("-h, --help", "Show help")
   .action(async () => {
     try {

pnpm-lock.yaml

@@ -5,3 +5,4 @@ packages:
   - "./legacy/*"
   - "./action"
   - "./php/*"
+  - "./scripts/*"

pnpm-workspace.yaml

@@ -0,0 +1,26 @@
+# scripts/docs
+
+## Introduction
+
+This directory contains scripts for generating documentation from the Lingo.dev source code.
+
+## generate-cli-docs
+
+This script generates reference documentation for **Lingo.dev CLI**.
+
+### Usage
+
+```bash
+pnpm --filter docs run generate-cli-docs [output_file_path]
+```
+
+### How it works
+
+1. Loads the CLI program from the `cli` package.
+2. Walks through all commands and subcommands.
+3. Generates a Markdown file with the complete command reference.
+
+### Notes
+
+- When running inside a GitHub Action, this script comments on the PR with the Markdown content.
+- When running outside of a GitHub action, the script writes the Markdown file to disk.

scripts/docs/README.md

@@ -0,0 +1,17 @@
+{
+  "name": "docs",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "generate-cli-docs": "tsx ./src/generate-cli-docs.ts"
+  },
+  "devDependencies": {
+    "@octokit/rest": "^20.1.2",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^24.0.10",
+    "commander": "^12.0.0",
+    "remark-stringify": "^11.0.0",
+    "tsx": "^4.7.1",
+    "unified": "^11.0.4"
+  }
+}

scripts/docs/package.json

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+import type { Command } from "commander";
+import { existsSync } from "fs";
+import { mkdir, writeFile } from "fs/promises";
+import type { Root } from "mdast";
+import { resolve, dirname } from "path";
+import remarkStringify from "remark-stringify";
+import { unified } from "unified";
+import { pathToFileURL } from "url";
+import { createOrUpdateGitHubComment, getRepoRoot } from "./utils";
+
+async function getProgram(repoRoot: string): Promise<Command> {
+  const filePath = resolve(
+    repoRoot,
+    "packages",
+    "cli",
+    "src",
+    "cli",
+    "index.ts",
+  );
+
+  if (!existsSync(filePath)) {
+    throw new Error(`CLI source file not found at ${filePath}`);
+  }
+
+  const cliModule = (await import(pathToFileURL(filePath).href)) as {
+    default: Command;
+  };
+
+  return cliModule.default;
+}
+
+function buildMarkdown(program: Command): string {
+  const mdast: Root = {
+    type: "root",
+    children: [
+      {
+        type: "paragraph",
+        children: [
+          {
+            type: "text",
+            value:
+              "This page contains the complete list of commands available via ",
+          },
+          {
+            type: "strong",
+            children: [{ type: "text", value: "Lingo.dev CLI" }],
+          },
+          {
+            type: "text",
+            value: ". To access this documentation from the CLI itself, run ",
+          },
+          {
+            type: "inlineCode",
+            value: "npx lingo.dev@latest --help",
+          },
+          {
+            type: "text",
+            value: ".",
+          },
+        ],
+      },
+    ],
+  };
+
+  const helper = program.createHelp();
+  const visited = new Set<Command>();
+
+  type WalkOptions = {
+    cmd: Command;
+    parents: string[];
+  };
+
+  function walk({ cmd, parents }: WalkOptions): void {
+    if (visited.has(cmd)) {
+      return;
+    }
+
+    visited.add(cmd);
+
+    const commandPath = [...parents, cmd.name()].join(" ").trim();
+
+    // Heading for this command
+    mdast.children.push({
+      type: "heading",
+      depth: 2,
+      children: [{ type: "inlineCode", value: commandPath || cmd.name() }],
+    });
+
+    // Code block containing the help output
+    mdast.children.push({
+      type: "code",
+      lang: "bash",
+      value: helper.formatHelp(cmd, helper).trimEnd(),
+    });
+
+    cmd.commands.forEach((sub: Command) => {
+      walk({ cmd: sub, parents: [...parents, cmd.name()] });
+    });
+  }
+
+  walk({ cmd: program, parents: [] });
+
+  return unified().use(remarkStringify).stringify(mdast);
+}
+
+async function main(): Promise<void> {
+  const repoRoot = getRepoRoot();
+  const commentMarker = "<!-- generate-cli-docs -->";
+
+  console.log("🔄 Generating CLI docs...");
+  const cli = await getProgram(repoRoot);
+  const markdown = buildMarkdown(cli);
+
+  const isGitHubAction = Boolean(process.env.GITHUB_ACTIONS);
+
+  if (isGitHubAction) {
+    console.log("💬 Commenting on GitHub PR...");
+
+    const mdast: Root = {
+      type: "root",
+      children: [
+        { type: "html", value: commentMarker },
+        {
+          type: "paragraph",
+          children: [
+            {
+              type: "text",
+              value:
+                "Your PR affects Lingo.dev CLI and, as a result, may affect the auto-generated reference documentation that will be published to the documentation website. Please review the output below to ensure that the changes are correct.",
+            },
+          ],
+        },
+        { type: "html", value: "<details>" },
+        { type: "html", value: "<summary>Lingo.dev CLI Commands</summary>" },
+        { type: "code", lang: "markdown", value: markdown },
+        { type: "html", value: "</details>" },
+      ],
+    };
+
+    const body = unified()
+      .use([[remarkStringify, { fence: "~" }]])
+      .stringify(mdast)
+      .toString();
+
+    await createOrUpdateGitHubComment({
+      commentMarker,
+      body,
+    });
+
+    return;
+  }
+
+  const outputArg = process.argv[2];
+
+  if (!outputArg) {
+    throw new Error(
+      "Output file path is required. Usage: generate-cli-docs <output-path>",
+    );
+  }
+
+  const outputFilePath = resolve(process.cwd(), outputArg);
+
+  console.log(`💾 Saving to ${outputFilePath}...`);
+  await mkdir(dirname(outputFilePath), { recursive: true });
+  await writeFile(outputFilePath, markdown, "utf8");
+  console.log(`✅ Saved to ${outputFilePath}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

scripts/docs/src/generate-cli-docs.ts

@@ -0,0 +1,126 @@
+import { existsSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { readFileSync } from "fs";
+import { Octokit } from "@octokit/rest";
+
+export function getRepoRoot(): string {
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+  let currentDir = __dirname;
+
+  while (currentDir !== path.parse(currentDir).root) {
+    if (existsSync(path.join(currentDir, ".git"))) {
+      return currentDir;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+
+  throw new Error("Could not find project root");
+}
+
+export function getGitHubToken() {
+  const token = process.env.GITHUB_TOKEN;
+
+  if (!token) {
+    throw new Error("GITHUB_TOKEN environment variable is required.");
+  }
+
+  return token;
+}
+
+export function getGitHubRepo() {
+  const repository = process.env.GITHUB_REPOSITORY;
+
+  if (!repository) {
+    throw new Error("GITHUB_REPOSITORY environment variable is missing.");
+  }
+
+  const [_, repo] = repository.split("/");
+
+  return repo;
+}
+
+export function getGitHubOwner() {
+  const repository = process.env.GITHUB_REPOSITORY;
+
+  if (!repository) {
+    throw new Error("GITHUB_REPOSITORY environment variable is missing.");
+  }
+
+  const [owner] = repository.split("/");
+
+  return owner;
+}
+
+export function getGitHubPRNumber() {
+  const prNumber = process.env.PR_NUMBER;
+
+  if (prNumber) {
+    return Number(prNumber);
+  }
+
+  const eventPath = process.env.GITHUB_EVENT_PATH;
+
+  if (eventPath && existsSync(eventPath)) {
+    try {
+      const eventData = JSON.parse(readFileSync(eventPath, "utf8"));
+      return Number(eventData.pull_request?.number);
+    } catch (err) {
+      console.warn("Failed to parse GITHUB_EVENT_PATH JSON:", err);
+    }
+  }
+
+  throw new Error("Could not determine pull request number.");
+}
+
+export type GitHubCommentOptions = {
+  commentMarker: string;
+  body: string;
+};
+
+export async function createOrUpdateGitHubComment(
+  options: GitHubCommentOptions,
+): Promise<void> {
+  const token = getGitHubToken();
+  const owner = getGitHubOwner();
+  const repo = getGitHubRepo();
+  const prNumber = getGitHubPRNumber();
+
+  const octokit = new Octokit({ auth: token });
+
+  const commentsResponse = await octokit.rest.issues.listComments({
+    owner,
+    repo,
+    issue_number: prNumber,
+    per_page: 100,
+  });
+
+  const comments = commentsResponse.data;
+
+  const existing = comments.find((c) => {
+    if (!c.body) {
+      return false;
+    }
+    return c.body.startsWith(options.commentMarker);
+  });
+
+  if (existing) {
+    console.log(`Updating existing comment (id: ${existing.id}).`);
+    await octokit.rest.issues.updateComment({
+      owner,
+      repo,
+      comment_id: existing.id,
+      body: options.body,
+    });
+    return;
+  }
+
+  console.log("Creating new comment.");
+  await octokit.rest.issues.createComment({
+    owner,
+    repo,
+    issue_number: prNumber,
+    body: options.body,
+  });
+}

scripts/docs/src/utils.ts

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "build",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "moduleResolution": "Bundler",
+    "module": "ESNext",
+    "target": "ESNext",
+    "allowUnreachableCode": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": ["src/**/*.spec.ts", "src/**/*.spec.tsx"]
+}