@xylabs/ts-scripts-yarn3 7.4.11 → 7.4.13

package/dist/xy/xyCommonCommands.mjs

@@ -192,18 +192,148 @@ var generateIgnoreFiles = (filename3, pkg) => {
   return succeeded ? 0 : 1;
 };
 
+// src/lib/generateReadmeFiles.ts
+import { execSync } from "child_process";
+import FS from "fs";
+import { readFile, writeFile } from "fs/promises";
+import PATH2 from "path";
+import chalk4 from "chalk";
+function fillTemplate(template, data) {
+  const additionalData = { ...data, safeName: data.name.replaceAll("/", "__").replaceAll("@", "") };
+  return template.replaceAll(/\{\{(.*?)\}\}/g, (_, key) => additionalData[key.trim()] ?? "");
+}
+function generateTypedoc(packageLocation, entryPoints) {
+  const tempDir = PATH2.join(packageLocation, ".temp-typedoc");
+  try {
+    if (!FS.existsSync(tempDir)) {
+      FS.mkdirSync(tempDir, { recursive: true });
+    }
+    const typedocConfig = {
+      disableSources: true,
+      entryPointStrategy: "expand",
+      entryPoints: entryPoints.map((ep) => PATH2.resolve(packageLocation, ep)),
+      excludeExternals: true,
+      excludeInternal: true,
+      excludePrivate: true,
+      githubPages: false,
+      hideBreadcrumbs: true,
+      hideGenerator: true,
+      hidePageTitle: true,
+      out: tempDir,
+      plugin: ["typedoc-plugin-markdown"],
+      readme: "none",
+      skipErrorChecking: true,
+      sort: ["source-order"],
+      theme: "markdown",
+      useCodeBlocks: true
+    };
+    const typedocJsonPath = PATH2.join(tempDir, "typedoc.json");
+    FS.writeFileSync(typedocJsonPath, JSON.stringify(typedocConfig, null, 2));
+    try {
+      execSync(`npx typedoc --options ${typedocJsonPath}`, {
+        cwd: process.cwd(),
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+    } catch {
+      return "";
+    }
+    return consolidateMarkdown(tempDir);
+  } catch {
+    return "";
+  } finally {
+    try {
+      FS.rmSync(tempDir, { force: true, recursive: true });
+    } catch {
+    }
+  }
+}
+function consolidateMarkdown(tempDir) {
+  let consolidated = "## Reference\n\n";
+  const mainReadmePath = PATH2.join(tempDir, "README.md");
+  if (FS.existsSync(mainReadmePath)) {
+    const mainContent = FS.readFileSync(mainReadmePath, "utf8").replace(/^---(.|\n)*?---\n/, "").replace(/^# .+\n/, "").replaceAll(/\]\((.+?)\.md\)/g, "](#$1)");
+    consolidated += mainContent + "\n\n";
+  }
+  consolidated += processDirectory(tempDir);
+  return consolidated.replaceAll(/\n\n\n+/g, "\n\n").replaceAll(/^#### /gm, "### ").replaceAll(/^##### /gm, "#### ").replaceAll(/^###### /gm, "##### ");
+}
+function processDirectory(dir, level = 0) {
+  const indent = "  ".repeat(level);
+  let content = "";
+  try {
+    const items = FS.readdirSync(dir, { withFileTypes: true });
+    for (const item of items) {
+      if (item.isDirectory()) continue;
+      if (item.name === "README.md" || !item.name.endsWith(".md")) continue;
+      const fileContent = FS.readFileSync(PATH2.join(dir, item.name), "utf8").replace(/^---(.|\n)*?---\n/, "");
+      const moduleName = item.name.replace(".md", "");
+      content += `
+
+${indent}### <a id="${moduleName}"></a>${moduleName}
+
+`;
+      content += fileContent.replace(/^# .+\n/, "").replaceAll(/\]\((.+?)\.md\)/g, "](#$1)");
+    }
+    for (const item of items) {
+      if (!item.isDirectory()) continue;
+      if (item.name === "spec" || item.name.includes(".spec")) continue;
+      content += `
+
+${indent}### ${item.name}
+`;
+      content += processDirectory(PATH2.join(dir, item.name), level + 1);
+    }
+  } catch {
+  }
+  return content;
+}
+async function generateReadmeFiles({
+  pkg,
+  templatePath,
+  typedoc = false,
+  verbose
+}) {
+  console.log(chalk4.green("Generate README Files"));
+  const cwd = INIT_CWD() ?? ".";
+  const resolvedTemplatePath = templatePath ?? PATH2.join(cwd, "scripts", "README.template.md");
+  let template;
+  try {
+    template = await readFile(resolvedTemplatePath, "utf8");
+  } catch {
+    console.error(chalk4.red(`Template not found: ${resolvedTemplatePath}`));
+    return 1;
+  }
+  const workspaces = pkg ? [yarnWorkspace(pkg)] : yarnWorkspaces();
+  let failed = false;
+  for (const { location, name } of workspaces) {
+    try {
+      const pkgJsonPath = PATH2.join(location, "package.json");
+      const pkgJson = JSON.parse(await readFile(pkgJsonPath, "utf8"));
+      const typedocContent = typedoc ? generateTypedoc(location, ["src/index*.ts"]) : "";
+      const readmeContent = fillTemplate(template, { ...pkgJson, typedoc: typedocContent });
+      await writeFile(PATH2.join(location, "README.md"), readmeContent);
+      if (verbose) console.log(chalk4.green(`  ${name}`));
+    } catch (ex) {
+      const error = ex;
+      console.warn(chalk4.yellow(`  Skipped ${location}: ${error.message}`));
+      failed = true;
+    }
+  }
+  return failed ? 1 : 0;
+}
+
 // src/lib/runSteps.ts
 import { spawnSync as spawnSync3 } from "child_process";
 import { existsSync as existsSync2 } from "fs";
-import chalk4 from "chalk";
+import chalk5 from "chalk";
 var runSteps = (name, steps, exitOnFail = true, messages) => {
   return safeExit(() => {
     const pkgName = process.env.npm_package_name;
-    console.log(chalk4.green(`${name} [${pkgName}]`));
+    console.log(chalk5.green(`${name} [${pkgName}]`));
     let totalStatus = 0;
     for (const [i, [command, args, config]] of steps.entries()) {
       if (messages?.[i]) {
-        console.log(chalk4.gray(messages?.[i]));
+        console.log(chalk5.gray(messages?.[i]));
       }
       const argList = Array.isArray(args) ? args : args.split(" ");
       if (command === "node" && !existsSync2(argList[0])) {
@@ -232,15 +362,15 @@ import {
   unlinkSync,
   writeFileSync as writeFileSync2
 } from "fs";
-import PATH2 from "path";
-import chalk5 from "chalk";
+import PATH3 from "path";
+import chalk6 from "chalk";
 var syncCommandFiles = (commandsDir) => {
   const templates = claudeCommandTemplates();
   const templateNames = new Set(Object.keys(templates));
   let updated = 0;
   let created = 0;
   for (const [filename3, content] of Object.entries(templates)) {
-    const targetPath = PATH2.resolve(commandsDir, filename3);
+    const targetPath = PATH3.resolve(commandsDir, filename3);
     const existing = existsSync3(targetPath) ? readFileSync3(targetPath, "utf8") : void 0;
     if (existing === content) continue;
     writeFileSync2(targetPath, content, "utf8");
@@ -261,7 +391,7 @@ var removeStaleCommands = (commandsDir, templateNames) => {
   let removed = 0;
   for (const file of existingCommands) {
     if (!templateNames.has(file)) {
-      unlinkSync(PATH2.resolve(commandsDir, file));
+      unlinkSync(PATH3.resolve(commandsDir, file));
       removed++;
     }
   }
@@ -274,14 +404,14 @@ var logCommandsResult = (created, updated, removed) => {
       updated ? `${updated} updated` : "",
       removed ? `${removed} removed` : ""
     ].filter(Boolean);
-    console.log(chalk5.green(`.claude/commands/${XYLABS_COMMANDS_PREFIX}*.md: ${parts.join(", ")}`));
+    console.log(chalk6.green(`.claude/commands/${XYLABS_COMMANDS_PREFIX}*.md: ${parts.join(", ")}`));
   } else {
-    console.log(chalk5.gray(`.claude/commands/${XYLABS_COMMANDS_PREFIX}*.md: already up to date`));
+    console.log(chalk6.gray(`.claude/commands/${XYLABS_COMMANDS_PREFIX}*.md: already up to date`));
   }
 };
 var claudeCommands = () => {
   const cwd = INIT_CWD() ?? process.cwd();
-  const commandsDir = PATH2.resolve(cwd, ".claude", "commands");
+  const commandsDir = PATH3.resolve(cwd, ".claude", "commands");
   mkdirSync(commandsDir, { recursive: true });
   const {
     created,
@@ -302,15 +432,15 @@ import {
   unlinkSync as unlinkSync2,
   writeFileSync as writeFileSync3
 } from "fs";
-import PATH3 from "path";
-import chalk6 from "chalk";
+import PATH4 from "path";
+import chalk7 from "chalk";
 var syncRuleFiles = (rulesDir) => {
   const templates = claudeMdRuleTemplates();
   const templateNames = new Set(Object.keys(templates));
   let updated = 0;
   let created = 0;
   for (const [filename3, content] of Object.entries(templates)) {
-    const targetPath = PATH3.resolve(rulesDir, filename3);
+    const targetPath = PATH4.resolve(rulesDir, filename3);
     const existing = existsSync4(targetPath) ? readFileSync4(targetPath, "utf8") : void 0;
     if (existing === content) continue;
     writeFileSync3(targetPath, content, "utf8");
@@ -331,7 +461,7 @@ var removeStaleRules = (rulesDir, templateNames) => {
   let removed = 0;
   for (const file of existingRules) {
     if (!templateNames.has(file)) {
-      unlinkSync2(PATH3.resolve(rulesDir, file));
+      unlinkSync2(PATH4.resolve(rulesDir, file));
       removed++;
     }
   }
@@ -344,26 +474,26 @@ var logRulesResult = (created, updated, removed) => {
       updated ? `${updated} updated` : "",
       removed ? `${removed} removed` : ""
     ].filter(Boolean);
-    console.log(chalk6.green(`.claude/rules/${XYLABS_RULES_PREFIX}*.md: ${parts.join(", ")}`));
+    console.log(chalk7.green(`.claude/rules/${XYLABS_RULES_PREFIX}*.md: ${parts.join(", ")}`));
   } else {
-    console.log(chalk6.gray(`.claude/rules/${XYLABS_RULES_PREFIX}*.md: already up to date`));
+    console.log(chalk7.gray(`.claude/rules/${XYLABS_RULES_PREFIX}*.md: already up to date`));
   }
 };
 var ensureProjectClaudeMd = (cwd, force) => {
-  const projectPath = PATH3.resolve(cwd, "CLAUDE.md");
+  const projectPath = PATH4.resolve(cwd, "CLAUDE.md");
   if (!existsSync4(projectPath) || force) {
     if (force && existsSync4(projectPath)) {
-      console.log(chalk6.yellow("Overwriting existing CLAUDE.md"));
+      console.log(chalk7.yellow("Overwriting existing CLAUDE.md"));
     }
     writeFileSync3(projectPath, claudeMdProjectTemplate(), "utf8");
-    console.log(chalk6.green("Generated CLAUDE.md"));
+    console.log(chalk7.green("Generated CLAUDE.md"));
   } else {
-    console.log(chalk6.gray("CLAUDE.md already exists (skipped)"));
+    console.log(chalk7.gray("CLAUDE.md already exists (skipped)"));
   }
 };
 var claudeRules = ({ force } = {}) => {
   const cwd = INIT_CWD() ?? process.cwd();
-  const rulesDir = PATH3.resolve(cwd, ".claude", "rules");
+  const rulesDir = PATH4.resolve(cwd, ".claude", "rules");
   mkdirSync2(rulesDir, { recursive: true });
   const {
     created,
@@ -378,10 +508,10 @@ var claudeRules = ({ force } = {}) => {
 
 // src/actions/clean-docs.ts
 import path from "path";
-import chalk7 from "chalk";
+import chalk8 from "chalk";
 var cleanDocs = () => {
   const pkgName = process.env.npm_package_name;
-  console.log(chalk7.green(`Cleaning Docs [${pkgName}]`));
+  console.log(chalk8.green(`Cleaning Docs [${pkgName}]`));
   for (const { location } of yarnWorkspaces()) deleteGlob(path.join(location, "docs"));
   return 0;
 };
@@ -410,7 +540,7 @@ var filename = ".gitignore";
 var gitignoreGen = (pkg) => generateIgnoreFiles(filename, pkg);
 
 // src/actions/gitlint.ts
-import chalk8 from "chalk";
+import chalk9 from "chalk";
 import ParseGitConfig from "parse-git-config";
 var gitlint = () => {
   console.log(`
@@ -421,7 +551,7 @@ Gitlint Start [${process.cwd()}]
   const errors = 0;
   const gitConfig = ParseGitConfig.sync();
   const warn = (message) => {
-    console.warn(chalk8.yellow(`Warning: ${message}`));
+    console.warn(chalk9.yellow(`Warning: ${message}`));
     warnings++;
   };
   if (gitConfig.core.ignorecase) {
@@ -441,13 +571,13 @@ Gitlint Start [${process.cwd()}]
   }
   const resultMessages = [];
   if (valid > 0) {
-    resultMessages.push(chalk8.green(`Passed: ${valid}`));
+    resultMessages.push(chalk9.green(`Passed: ${valid}`));
   }
   if (warnings > 0) {
-    resultMessages.push(chalk8.yellow(`Warnings: ${warnings}`));
+    resultMessages.push(chalk9.yellow(`Warnings: ${warnings}`));
   }
   if (errors > 0) {
-    resultMessages.push(chalk8.red(` Errors: ${errors}`));
+    resultMessages.push(chalk9.red(` Errors: ${errors}`));
   }
   console.warn(`Gitlint Finish [ ${resultMessages.join(" | ")} ]
 `);
@@ -455,8 +585,8 @@ Gitlint Start [${process.cwd()}]
 };
 
 // src/actions/gitlint-fix.ts
-import { execSync } from "child_process";
-import chalk9 from "chalk";
+import { execSync as execSync2 } from "child_process";
+import chalk10 from "chalk";
 import ParseGitConfig2 from "parse-git-config";
 var gitlintFix = () => {
   console.log(`
@@ -464,22 +594,22 @@ Gitlint Fix Start [${process.cwd()}]
 `);
   const gitConfig = ParseGitConfig2.sync();
   if (gitConfig.core.ignorecase) {
-    execSync("git config core.ignorecase false", { stdio: "inherit" });
-    console.warn(chalk9.yellow("\nGitlint Fix: Updated core.ignorecase to be false\n"));
+    execSync2("git config core.ignorecase false", { stdio: "inherit" });
+    console.warn(chalk10.yellow("\nGitlint Fix: Updated core.ignorecase to be false\n"));
   }
   if (gitConfig.core.autocrlf !== false) {
-    execSync("git config core.autocrlf false", { stdio: "inherit" });
-    console.warn(chalk9.yellow("\nGitlint Fix: Updated core.autocrlf to be false\n"));
+    execSync2("git config core.autocrlf false", { stdio: "inherit" });
+    console.warn(chalk10.yellow("\nGitlint Fix: Updated core.autocrlf to be false\n"));
   }
   if (gitConfig.core.eol !== "lf") {
-    execSync("git config core.eol lf", { stdio: "inherit" });
-    console.warn(chalk9.yellow('\nGitlint Fix: Updated core.eol to be "lf"\n'));
+    execSync2("git config core.eol lf", { stdio: "inherit" });
+    console.warn(chalk10.yellow('\nGitlint Fix: Updated core.eol to be "lf"\n'));
   }
   return 1;
 };
 
 // src/actions/license.ts
-import chalk10 from "chalk";
+import chalk11 from "chalk";
 import { init } from "license-checker";
 var license = async (pkg) => {
   const workspaces = yarnWorkspaces();
@@ -504,18 +634,18 @@ var license = async (pkg) => {
     "LGPL-3.0-or-later",
     "Python-2.0"
   ]);
-  console.log(chalk10.green("License Checker"));
+  console.log(chalk11.green("License Checker"));
   return (await Promise.all(
     workspaceList.map(({ location, name }) => {
       return new Promise((resolve) => {
         init({ production: true, start: location }, (error, packages) => {
           if (error) {
-            console.error(chalk10.red(`License Checker [${name}] Error`));
-            console.error(chalk10.gray(error));
+            console.error(chalk11.red(`License Checker [${name}] Error`));
+            console.error(chalk11.gray(error));
             console.log("\n");
             resolve(1);
           } else {
-            console.log(chalk10.green(`License Checker [${name}]`));
+            console.log(chalk11.green(`License Checker [${name}]`));
             let count = 0;
             for (const [name2, info] of Object.entries(packages)) {
               const licenses = Array.isArray(info.licenses) ? info.licenses : [info.licenses];
@@ -531,7 +661,7 @@ var license = async (pkg) => {
                   }
                   if (!orLicenseFound) {
                     count++;
-                    console.warn(chalk10.yellow(`${name2}: Package License not allowed [${license2}]`));
+                    console.warn(chalk11.yellow(`${name2}: Package License not allowed [${license2}]`));
                   }
                 }
               }
@@ -549,6 +679,21 @@ var license = async (pkg) => {
 var filename2 = ".npmignore";
 var npmignoreGen = (pkg) => generateIgnoreFiles(filename2, pkg);
 
+// src/actions/readme-gen.ts
+async function readmeGen({
+  pkg,
+  templatePath,
+  typedoc,
+  verbose
+}) {
+  return await generateReadmeFiles({
+    pkg,
+    templatePath,
+    typedoc,
+    verbose
+  });
+}
+
 // src/actions/retest.ts
 var retest = () => {
   return runSteps("Test", [
@@ -684,6 +829,29 @@ var xyCommonCommands = (args) => {
       if (argv.verbose) console.log("NpmIgnore Gen");
       process.exitCode = npmignoreGen();
     }
+  ).command(
+    "readme-gen [package]",
+    "Readme Gen - Generate README.md files from template",
+    (yargs) => {
+      return packagePositionalParam(yargs).option("template", {
+        alias: "t",
+        description: "Path to README.template.md",
+        type: "string"
+      }).option("typedoc", {
+        default: false,
+        description: "Generate TypeDoc reference sections",
+        type: "boolean"
+      });
+    },
+    async (argv) => {
+      if (argv.verbose) console.log("Readme Gen");
+      process.exitCode = await readmeGen({
+        pkg: argv.package,
+        templatePath: argv.template,
+        typedoc: argv.typedoc,
+        verbose: !!argv.verbose
+      });
+    }
   ).command(
     "retest",
     "Re-Test - Run Jest Tests with cleaned cache",