Improve Windows snippet rendering fallback

Author: mniinio

package.json

@@ -26,7 +26,7 @@
     "./method/station-criteria.json": "./src/data/method/station-criteria.json"
   },
   "scripts": {
-    "test": "node scripts/validate.mjs",
+    "test": "node scripts/validate.mjs && node scripts/test-print-method-snippet.mjs",
     "release:create-apiops:pack": "npm pack --workspace packages/create-apiops",
     "release:create-apiops:publish": "npm publish --workspace packages/create-apiops --access public",
     "check:packaging:skills": "node scripts/check-packaging-skills.mjs",

packages/create-apiops/template/scripts/print-method-snippet.js

@@ -1,5 +1,7 @@
 import fs from "fs";
 import path from "path";
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
 
 function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, "utf8"));
@@ -29,7 +31,7 @@ function resolveSnippetPath(snippet, locale) {
   return fs.existsSync(localized) ? localized : path.join(base, snippet);
 }
 
-function toAscii(text) {
+export function toAscii(text) {
   return text
     .replace(/\r\n/g, "\n")
     .replace(/\uFEFF/g, "")
@@ -41,47 +43,97 @@ function toAscii(text) {
     .replace(/[–—]/g, "-");
 }
 
-function printUsage() {
-  console.error(
-    "Usage: node scripts/print-method-snippet.js <resource-id> [locale] [--ascii]",
+export function getActiveWindowsCodePage() {
+  const override = process.env.APIOPS_WINDOWS_CODEPAGE;
+  if (override) {
+    return Number.parseInt(override, 10);
+  }
+
+  const result = spawnSync(
+    process.env.ComSpec || "cmd.exe",
+    ["/d", "/s", "/c", "chcp"],
+    {
+      encoding: "utf8",
+      windowsHide: true,
+    },
   );
+
+  const output = `${result.stdout || ""}\n${result.stderr || ""}`;
+  const match = output.match(/(\d{3,5})/);
+  return match ? Number.parseInt(match[1], 10) : null;
 }
 
-const args = process.argv.slice(2);
-const ascii = args.includes("--ascii");
-const positional = args.filter((arg) => arg !== "--ascii");
-const resourceId = positional[0];
-const locale = positional[1] || "en";
+export function shouldUseAsciiFallback(forceAscii, forceUnicode) {
+  if (forceAscii) {
+    return true;
+  }
 
-if (!resourceId) {
-  printUsage();
-  process.exit(1);
-}
+  if (forceUnicode) {
+    return false;
+  }
 
-const resources = readJson(resolveMethodFile("resources.json")).resources;
-const resource = resources.find((entry) => entry.id === resourceId);
+  const isWindows = process.platform === "win32" || process.env.APIOPS_FORCE_WINDOWS === "1";
+  if (!isWindows) {
+    return false;
+  }
 
-if (!resource) {
-  console.error(`Unknown resource id: ${resourceId}`);
-  process.exit(1);
+  const codePage = getActiveWindowsCodePage();
+  return codePage !== null && codePage !== 65001;
 }
 
-if (!resource.snippet) {
-  console.error(`Resource ${resourceId} does not define a snippet`);
-  process.exit(1);
+function printUsage() {
+  console.error(
+    "Usage: node scripts/print-method-snippet.js <resource-id> [locale] [--ascii] [--unicode]",
+  );
 }
 
-const snippetPath = resolveSnippetPath(resource.snippet, locale);
+export function renderSnippet(resourceId, locale = "en", options = {}) {
+  const resources = readJson(resolveMethodFile("resources.json")).resources;
+  const resource = resources.find((entry) => entry.id === resourceId);
+
+  if (!resource) {
+    throw new Error(`Unknown resource id: ${resourceId}`);
+  }
+
+  if (!resource.snippet) {
+    throw new Error(`Resource ${resourceId} does not define a snippet`);
+  }
+
+  const snippetPath = resolveSnippetPath(resource.snippet, locale);
+  if (!fs.existsSync(snippetPath)) {
+    throw new Error(`Snippet not found: ${snippetPath}`);
+  }
 
-if (!fs.existsSync(snippetPath)) {
-  console.error(`Snippet not found: ${snippetPath}`);
-  process.exit(1);
+  let content = fs.readFileSync(snippetPath, "utf8");
+  if (shouldUseAsciiFallback(options.forceAscii, options.forceUnicode)) {
+    content = toAscii(content);
+  }
+
+  return content;
 }
 
-let content = fs.readFileSync(snippetPath, "utf8");
+function main() {
+  const args = process.argv.slice(2);
+  const forceAscii = args.includes("--ascii");
+  const forceUnicode = args.includes("--unicode");
+  const positional = args.filter((arg) => arg !== "--ascii" && arg !== "--unicode");
+  const resourceId = positional[0];
+  const locale = positional[1] || "en";
+
+  if (!resourceId) {
+    printUsage();
+    process.exit(1);
+  }
 
-if (ascii) {
-  content = toAscii(content);
+  try {
+    const content = renderSnippet(resourceId, locale, { forceAscii, forceUnicode });
+    process.stdout.write(content, "utf8");
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
 }
 
-process.stdout.write(content);
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

scripts/test-print-method-snippet.mjs

@@ -0,0 +1,50 @@
+import { mkdtempSync, mkdirSync, cpSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { renderSnippet } from "../packages/create-apiops/template/scripts/print-method-snippet.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const repoRoot = resolve(__dirname, "..");
+const tempRoot = mkdtempSync(join(tmpdir(), "print-method-snippet-"));
+const fixturePkgRoot = join(tempRoot, "node_modules", "apiops-cycles-method-data");
+const previousCwd = process.cwd();
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+try {
+  mkdirSync(join(fixturePkgRoot, "src", "data", "method"), { recursive: true });
+  mkdirSync(join(fixturePkgRoot, "src", "snippets"), { recursive: true });
+  cpSync(resolve(repoRoot, "src", "data", "method", "resources.json"), join(fixturePkgRoot, "src", "data", "method", "resources.json"));
+  cpSync(resolve(repoRoot, "src", "snippets", "api-audit-checklist.md"), join(fixturePkgRoot, "src", "snippets", "api-audit-checklist.md"));
+
+  process.chdir(tempRoot);
+
+  const unicodeOutput = renderSnippet("api-audit-checklist", "en", { forceUnicode: true });
+  assert(unicodeOutput.includes("### ✅ Concept is Ready When..."), "Expected forced Unicode output to keep checklist symbols.");
+  assert(unicodeOutput.includes("### 🧪 API Design Prototype is Ready When..."), "Expected forced Unicode output to keep prototype heading.");
+
+  const explicitAsciiOutput = renderSnippet("api-audit-checklist", "en", { forceAscii: true });
+  assert(explicitAsciiOutput.includes("### [OK] Concept is Ready When..."), "Expected --ascii output to replace heading symbols.");
+  assert(explicitAsciiOutput.includes("| API is based on clear business needs                   | API9:2019            | [X]"), "Expected --ascii output to replace checklist cross marks.");
+
+  process.env.APIOPS_FORCE_WINDOWS = "1";
+  process.env.APIOPS_WINDOWS_CODEPAGE = "437";
+  const simulatedWindowsOutput = renderSnippet("api-audit-checklist", "en");
+  assert(simulatedWindowsOutput.includes("### [OK] Concept is Ready When..."), "Expected Windows non-UTF-8 fallback to use ASCII automatically.");
+  assert(simulatedWindowsOutput.includes("### [Prod] API Is Maintainable in Production When..."), "Expected production heading to remain readable in fallback mode.");
+
+  delete process.env.APIOPS_FORCE_WINDOWS;
+  delete process.env.APIOPS_WINDOWS_CODEPAGE;
+  console.log("print-method-snippet regression test passed.");
+} finally {
+  delete process.env.APIOPS_FORCE_WINDOWS;
+  delete process.env.APIOPS_WINDOWS_CODEPAGE;
+  process.chdir(previousCwd);
+  rmSync(tempRoot, { recursive: true, force: true });
+}