@readme/cli 0.1.0 → 0.2.0

package/src/utils/reporter.js

@@ -1,30 +1,40 @@
-import { execSync } from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
-import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
-import ora from "ora";
-import * as styles from "./styles.js";
-import { hasClaude } from "./claude.js";
-import { hasGithubRemote, hasGithubWorkflow, getWorkflowVersion, WORKFLOW_VERSION, detectPlatform, hasReadmeWorkflow, PLATFORMS } from "./git.js";
-import { getRandomTip } from "./tips.js";
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import ora from 'ora';
+
+import { hasClaude } from './claude.js';
+import {
+  hasGithubRemote,
+  hasGithubWorkflow,
+  getWorkflowVersion,
+  WORKFLOW_VERSION,
+  detectPlatform,
+  hasReadmeWorkflow,
+  PLATFORMS,
+} from './git.js';
+import * as styles from './styles.js';
+import { getRandomTip } from './tips.js';
 
 const require = createRequire(import.meta.url);
 
 const isRunningInClaude = !!process.env.CLAUDECODE;
 
 const CATEGORY_LABELS = {
-  custom_blocks: "custom blocks",
-  docs: "docs",
-  reference: "reference",
-  custom_pages: "custom pages",
-  recipes: "recipes",
+  custom_blocks: 'custom blocks',
+  docs: 'docs',
+  reference: 'reference',
+  custom_pages: 'custom pages',
+  recipes: 'recipes',
 };
 
 function categorize(files) {
   const counts = new Map();
   for (const file of files) {
-    const dir = file.split("/")[0];
+    const dir = file.split('/')[0];
     const label = CATEGORY_LABELS[dir] || dir;
     counts.set(label, (counts.get(label) || 0) + 1);
   }
@@ -32,8 +42,8 @@ function categorize(files) {
 }
 
 function splitResults(results) {
-  const errors = results.filter((r) => r.severity !== "warning");
-  const warnings = results.filter((r) => r.severity === "warning");
+  const errors = results.filter(r => r.severity !== 'warning');
+  const warnings = results.filter(r => r.severity === 'warning');
   return { errors, warnings };
 }
 
@@ -43,17 +53,15 @@ function splitResults(results) {
  */
 function styleMessage(message, color) {
   // Strip "(fixed)" suffix — handled separately via the icon.
-  const isFixed = message.endsWith("(fixed)");
-  const raw = isFixed ? message.slice(0, -"(fixed)".length).trimEnd() : message;
+  const isFixed = message.endsWith('(fixed)');
+  const raw = isFixed ? message.slice(0, -'(fixed)'.length).trimEnd() : message;
 
-  const colonIdx = raw.indexOf(":");
+  const colonIdx = raw.indexOf(':');
   let styled;
 
   if (colonIdx !== -1) {
     const title = raw.slice(0, colonIdx);
-    const detail = raw
-      .slice(colonIdx + 1)
-      .replace(/"([^"]+)"/g, (_, val) => styles.bold(`"${val}"`));
+    const detail = raw.slice(colonIdx + 1).replace(/"([^"]+)"/g, (_, val) => styles.bold(`"${val}"`));
     styled = `${color(title)}:${detail}`;
   } else {
     // No colon — highlight quoted values, keep rest normal.
@@ -65,20 +73,20 @@ function styleMessage(message, color) {
 
 function summaryLine(errorCount, warningCount) {
   const parts = [];
-  if (errorCount > 0)
-    parts.push(`${errorCount} ${errorCount === 1 ? "error" : "errors"}`);
-  if (warningCount > 0)
-    parts.push(
-      `${warningCount} ${warningCount === 1 ? "warning" : "warnings"}`,
-    );
-  return parts.join(" and ");
+  if (errorCount > 0) {
+    parts.push(`${errorCount} ${errorCount === 1 ? 'error' : 'errors'}`);
+  }
+  if (warningCount > 0) {
+    parts.push(`${warningCount} ${warningCount === 1 ? 'warning' : 'warnings'}`);
+  }
+  return parts.join(' and ');
 }
 
 /**
  * Human-readable reporter with an animated spinner.
  */
 export function createHumanReporter() {
-  const spinner = ora({ text: "Running linting...", color: "blue" }).start();
+  const spinner = ora({ text: 'Running linting...', color: 'blue' }).start();
 
   return {
     onFile(relativePath) {
@@ -90,13 +98,11 @@ export function createHumanReporter() {
     },
 
     finish(total, results, files, { fix, gitRoot } = {}) {
-      spinner.suffixText = "";
+      spinner.suffixText = '';
 
       const { errors, warnings } = splitResults(results);
       const categories = categorize(files);
-      const breakdown = categories
-        .map(([label, count]) => `${count} ${label}`)
-        .join(styles.dim(" · "));
+      const breakdown = categories.map(([label, count]) => `${count} ${label}`).join(styles.dim(' · '));
 
       if (errors.length === 0 && warnings.length === 0) {
         spinner.succeed(`${total} files checked — all good!`);
@@ -105,9 +111,7 @@ export function createHumanReporter() {
       }
 
       if (errors.length > 0) {
-        spinner.fail(
-          `${summaryLine(errors.length, warnings.length)} in ${total} files`,
-        );
+        spinner.fail(`${summaryLine(errors.length, warnings.length)} in ${total} files`);
       } else {
         spinner.warn(`${summaryLine(0, warnings.length)} in ${total} files`);
       }
@@ -124,32 +128,29 @@ export function createHumanReporter() {
       for (const [file, fileResults] of grouped) {
         console.log(`  ${styles.bold(file)}`);
         for (const r of fileResults) {
-          const baseColor = r.severity === "warning" ? styles.warn : styles.err;
-          const isFixed = r.message.endsWith("(fixed)");
+          const baseColor = r.severity === 'warning' ? styles.warn : styles.err;
+          const isFixed = r.message.endsWith('(fixed)');
           const color = isFixed ? styles.success : baseColor;
           const styled = styleMessage(r.message, color);
-          const icon = isFixed ? styles.success("✔") : baseColor("●");
+          const icon = isFixed ? styles.success('✔') : baseColor('●');
           console.log(`    ${icon} ${styled}`);
         }
         console.log();
       }
 
       // Tips section.
-      const fixable = !fix
-        ? results.filter((r) => r.fixable && !r.message.endsWith("(fixed)"))
-        : [];
-      const unfixed = results.filter((r) => !r.message.endsWith("(fixed)"));
-      const showTips =
-        fixable.length > 0 || (unfixed.length > 0 && !isRunningInClaude);
+      const fixable = !fix ? results.filter(r => r.fixable && !r.message.endsWith('(fixed)')) : [];
+      const unfixed = results.filter(r => !r.message.endsWith('(fixed)'));
+      const showTips = fixable.length > 0 || (unfixed.length > 0 && !isRunningInClaude);
 
       if (showTips) {
-        console.log(`  ${styles.dim("─".repeat(40))}`);
+        console.log(`  ${styles.dim('─'.repeat(40))}`);
         console.log();
       }
 
       if (fixable.length > 0) {
         console.log(
-          `  ${styles.dim("Run")} ${styles.binName()} lint --fix ${styles.dim("to automatically fix some of these.")}`,
+          `  ${styles.dim('Run')} ${styles.binName()} lint --fix ${styles.dim('to automatically fix some of these.')}`,
         );
         console.log();
       }
@@ -159,9 +160,7 @@ export function createHumanReporter() {
         const workflowVersion = gitRoot ? getWorkflowVersion(gitRoot) : null;
         const detection = gitRoot ? detectPlatform(gitRoot) : { recommended: null };
         const detectedPlatform = detection.recommended;
-        const hasCiWorkflow = detectedPlatform && gitRoot
-          ? hasReadmeWorkflow(gitRoot, detectedPlatform)
-          : true;
+        const hasCiWorkflow = detectedPlatform && gitRoot ? hasReadmeWorkflow(gitRoot, detectedPlatform) : true;
         const tip = getRandomTip({
           isRunningInClaude,
           hasClaude: hasClaude(),
@@ -177,39 +176,36 @@ export function createHumanReporter() {
 
       // When running inside Claude, output instructions and structured issue list.
       if (isRunningInClaude && unfixed.length > 0) {
-        const cliRoot = path.join(
-          path.dirname(fileURLToPath(import.meta.url)),
-          "../..",
-        );
+        const cliRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), '../..');
 
         const gitFormatDir = path.dirname(require.resolve('@readmeio/git-format/package.json'));
-        const claudeMdPath = path.join(gitFormatDir, "CLAUDE.md");
-        const toolsMdPath = path.join(cliRoot, "vendor/TOOLS.md");
-        const schemaPath = path.join(gitFormatDir, "frontmatter.schema.json");
+        const claudeMdPath = path.join(gitFormatDir, 'CLAUDE.md');
+        const toolsMdPath = path.join(cliRoot, 'vendor/TOOLS.md');
+        const schemaPath = path.join(gitFormatDir, 'frontmatter.schema.json');
 
-        console.log("\n<claude-instructions>");
+        console.log('\n<claude-instructions>');
 
         if (fs.existsSync(toolsMdPath)) {
-          console.log(fs.readFileSync(toolsMdPath, "utf-8"));
+          console.log(fs.readFileSync(toolsMdPath, 'utf-8'));
         }
 
         if (fs.existsSync(claudeMdPath)) {
-          console.log(fs.readFileSync(claudeMdPath, "utf-8"));
+          console.log(fs.readFileSync(claudeMdPath, 'utf-8'));
         }
 
         if (fs.existsSync(schemaPath)) {
-          console.log("\n## Frontmatter JSON Schema\n");
-          console.log("```json");
-          console.log(fs.readFileSync(schemaPath, "utf-8"));
-          console.log("```");
+          console.log('\n## Frontmatter JSON Schema\n');
+          console.log('```json');
+          console.log(fs.readFileSync(schemaPath, 'utf-8'));
+          console.log('```');
         }
 
-        console.log("</claude-instructions>\n");
-        console.log("<issues>");
+        console.log('</claude-instructions>\n');
+        console.log('<issues>');
         for (const r of unfixed) {
           console.log(`- [${r.severity}] ${r.file}: ${r.message}`);
         }
-        console.log("</issues>");
+        console.log('</issues>');
       }
     },
   };
@@ -228,35 +224,36 @@ export function createGithubReporter() {
       const all = [...errors, ...warnings];
 
       // Build file links using GitHub Actions env vars
-      const serverUrl = process.env.GITHUB_SERVER_URL || "https://github.com";
-      const repo = process.env.GITHUB_REPOSITORY || "";
-      const sha = process.env.GITHUB_SHA || "";
+      const serverUrl = process.env.GITHUB_SERVER_URL || 'https://github.com';
+      const repo = process.env.GITHUB_REPOSITORY || '';
+      const sha = process.env.GITHUB_SHA || '';
       const canLink = repo && sha;
 
       function fileLink(filePath) {
-        const name = filePath.split("/").pop();
+        const name = filePath.split('/').pop();
         if (canLink) {
-          const encoded = filePath.split("/").map(encodeURIComponent).join("/");
+          const encoded = filePath.split('/').map(encodeURIComponent).join('/');
           return `[\`${name}\`](${serverUrl}/${repo}/blob/${sha}/${encoded})`;
         }
         return `\`${name}\``;
       }
 
-      let body = "<!-- readme-lint-results -->\n";
-      body += "## ReadMe Docs Lint\n\n";
+      let body = '<!-- readme-lint-results -->\n';
+      body += '## ReadMe Docs Lint\n\n';
 
       if (all.length === 0) {
-        body += "> **All checks passed!** No lint issues found.\n";
+        body += '> **All checks passed!** No lint issues found.\n';
       } else {
-        body += "| File | Message |\n";
-        body += "|------|--------|\n";
+        body += '| File | Message |\n';
+        body += '|------|--------|\n';
         for (const r of all) {
-          const isError = r.severity !== "warning";
-          const label = isError ? "\u{1F534} **Error:**" : "\u{1F7E1} **Warning:**";
+          const isError = r.severity !== 'warning';
+          const label = isError ? '\u{1F534} **Error:**' : '\u{1F7E1} **Warning:**';
           body += `| ${fileLink(r.file)} | ${label} ${r.message} |\n`;
         }
-        body += "\n";
-        body += "> \u{1F4A1} **Tip:** Run `npx @readme/cli lint --fix` locally to automatically fix some of these issues.\n\n";
+        body += '\n';
+        body +=
+          '> \u{1F4A1} **Tip:** Run `npx @readme/cli lint --fix` locally to automatically fix some of these issues.\n\n';
       }
 
       // OAS change detection
@@ -265,25 +262,25 @@ export function createGithubReporter() {
         try {
           const changed = execSync(
             `git diff --name-only ${baseSha}..HEAD -- 'reference/*.json' 'reference/*.yaml' 'reference/*.yml'`,
-            { cwd: gitRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] },
+            { cwd: gitRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] },
           ).trim();
 
           if (changed) {
-            const files = changed.split("\n");
-            body += "### OAS Changes Detected\n\n";
-            body += "The following OpenAPI spec files were changed in this PR:\n\n";
+            const files = changed.split('\n');
+            body += '### OAS Changes Detected\n\n';
+            body += 'The following OpenAPI spec files were changed in this PR:\n\n';
             for (const f of files) {
               body += `- ${fileLink(f)}\n`;
             }
-            body += "\nRun `npx @readme/cli oas:sync` to sync these changes to ReadMe.\n\n";
+            body += '\nRun `npx @readme/cli oas:sync` to sync these changes to ReadMe.\n\n';
           }
         } catch {
           // git diff failed — skip OAS section silently
         }
       }
 
-      body += "---\n";
-      body += "\u{1F989} Powered by [ReadMe](https://readme.com)\n";
+      body += '---\n';
+      body += '\u{1F989} Powered by [ReadMe](https://readme.com)\n';
 
       console.log(body);
     },

package/src/utils/setup-templates.js

@@ -313,11 +313,17 @@ tasks:
 
 export function templateFor(platform, opts = {}) {
   switch (platform) {
-    case 'github':    return githubWorkflow(opts);
-    case 'gitlab':    return gitlabWorkflow();
-    case 'bitbucket': return bitbucketWorkflow();
-    case 'circleci':  return circleciWorkflow();
-    case 'rwx':       return rwxWorkflow();
-    default: throw new Error(`Unknown platform: ${platform}`);
+    case 'github':
+      return githubWorkflow(opts);
+    case 'gitlab':
+      return gitlabWorkflow();
+    case 'bitbucket':
+      return bitbucketWorkflow();
+    case 'circleci':
+      return circleciWorkflow();
+    case 'rwx':
+      return rwxWorkflow();
+    default:
+      throw new Error(`Unknown platform: ${platform}`);
   }
 }

package/src/utils/styles.js

@@ -1,5 +1,6 @@
-import path from 'node:path';
 import { createRequire } from 'node:module';
+import path from 'node:path';
+
 import chalk from 'chalk';
 
 /** Returns the CLI name depending on how it was invoked (e.g. "readme", "readme_", or "npx @readme/cli"). */