@opensyntaxhq/autodocs-plugin-examples 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,9 @@
+import { Plugin } from '@opensyntaxhq/autodocs-core';
+
+interface ExamplesPluginOptions {
+    validate?: boolean;
+    outputDir?: string;
+}
+declare function examplesPlugin(options?: ExamplesPluginOptions): Plugin;
+
+export { type ExamplesPluginOptions, examplesPlugin as default, examplesPlugin };

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { Plugin } from '@opensyntaxhq/autodocs-core';
+
+interface ExamplesPluginOptions {
+    validate?: boolean;
+    outputDir?: string;
+}
+declare function examplesPlugin(options?: ExamplesPluginOptions): Plugin;
+
+export { type ExamplesPluginOptions, examplesPlugin as default, examplesPlugin };

package/dist/index.js

@@ -0,0 +1,254 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => examplesPlugin,
+  examplesPlugin: () => examplesPlugin
+});
+module.exports = __toCommonJS(index_exports);
+var import_promises6 = __toESM(require("fs/promises"));
+var import_os = __toESM(require("os"));
+var import_path10 = __toESM(require("path"));
+var import_typescript7 = __toESM(require("typescript"));
+
+// ../../core/src/parser/index.ts
+var import_typescript = __toESM(require("typescript"));
+var import_path = __toESM(require("path"));
+var import_fs = __toESM(require("fs"));
+
+// ../../core/src/extractor/index.ts
+var import_typescript5 = __toESM(require("typescript"));
+var import_path3 = __toESM(require("path"));
+
+// ../../core/src/parser/utils.ts
+var import_typescript2 = __toESM(require("typescript"));
+
+// ../../core/src/extractor/serializers.ts
+var import_typescript4 = __toESM(require("typescript"));
+var import_crypto = __toESM(require("crypto"));
+var import_path2 = __toESM(require("path"));
+
+// ../../core/src/extractor/utils.ts
+var import_typescript3 = __toESM(require("typescript"));
+
+// ../../core/src/generators/json/index.ts
+var import_promises = __toESM(require("fs/promises"));
+var import_path4 = __toESM(require("path"));
+
+// ../../core/src/version.ts
+var VERSION = "1.0.0";
+
+// ../../core/src/generators/markdown/index.ts
+var import_promises2 = __toESM(require("fs/promises"));
+var import_path5 = __toESM(require("path"));
+
+// ../../core/src/generators/html/index.ts
+var import_promises3 = __toESM(require("fs/promises"));
+var import_path6 = __toESM(require("path"));
+
+// ../../core/src/cache/FileCache.ts
+var import_promises4 = __toESM(require("fs/promises"));
+var import_path7 = __toESM(require("path"));
+var import_crypto2 = __toESM(require("crypto"));
+
+// ../../core/src/cache/incremental.ts
+var import_typescript6 = __toESM(require("typescript"));
+var import_path8 = __toESM(require("path"));
+var import_fs2 = __toESM(require("fs"));
+
+// ../../core/src/deploy/static.ts
+var import_promises5 = __toESM(require("fs/promises"));
+var import_path9 = __toESM(require("path"));
+
+// src/index.ts
+function examplesPlugin(options = {}) {
+  const records = [];
+  return {
+    name: "@opensyntaxhq/autodocs-plugin-examples",
+    version: VERSION,
+    async afterExtract(docs) {
+      for (const entry of docs) {
+        const examples = entry.documentation?.examples;
+        if (!examples || examples.length === 0) {
+          continue;
+        }
+        for (const [index, example] of examples.entries()) {
+          if (options.validate) {
+            await validateExample(example, entry);
+          }
+          records.push({
+            entryId: entry.id,
+            entryName: entry.name,
+            index,
+            language: example.language,
+            code: example.code
+          });
+        }
+      }
+      return docs;
+    },
+    async afterGenerate(outputDir) {
+      if (!options.outputDir || records.length === 0) {
+        return;
+      }
+      const examplesDir = import_path10.default.isAbsolute(options.outputDir) ? options.outputDir : import_path10.default.join(outputDir, options.outputDir);
+      await import_promises6.default.mkdir(examplesDir, { recursive: true });
+      for (const record of records) {
+        const exampleNumber = record.index + 1;
+        const baseName = `${slugify(record.entryName)}__example-${exampleNumber.toString()}`;
+        const extension = languageToExtension(record.language);
+        const fileName = `${baseName}.${extension}`;
+        const filePath = import_path10.default.join(examplesDir, fileName);
+        await import_promises6.default.writeFile(filePath, record.code, "utf-8");
+        record.filePath = fileName;
+      }
+      const indexPayload = records.map((record) => ({
+        entryId: record.entryId,
+        entryName: record.entryName,
+        index: record.index,
+        language: record.language,
+        file: record.filePath
+      }));
+      await import_promises6.default.writeFile(
+        import_path10.default.join(examplesDir, "examples.json"),
+        JSON.stringify(indexPayload, null, 2),
+        "utf-8"
+      );
+    }
+  };
+}
+async function validateExample(example, entry) {
+  const tempDir = await import_promises6.default.mkdtemp(import_path10.default.join(import_os.default.tmpdir(), "autodocs-example-"));
+  const extension = languageToExtension(example.language);
+  const tempFile = import_path10.default.join(tempDir, `example.${extension}`);
+  try {
+    const normalized = example.code.endsWith("\n") ? example.code : `${example.code}
+`;
+    const stub = buildEntryStub(entry, normalized);
+    const wrapped = `${stub}${normalized}export {};
+`;
+    await import_promises6.default.writeFile(tempFile, wrapped, "utf-8");
+    const program = import_typescript7.default.createProgram([tempFile], {
+      noEmit: true,
+      skipLibCheck: true,
+      target: import_typescript7.default.ScriptTarget.ES2022
+    });
+    const diagnostics = import_typescript7.default.getPreEmitDiagnostics(program);
+    if (diagnostics.length > 0) {
+      const errors = diagnostics.map((d) => {
+        const message = typeof d.messageText === "string" ? d.messageText : d.messageText.messageText;
+        return message;
+      });
+      throw new Error(`TypeScript errors:
+${errors.join("\n")}`);
+    }
+  } finally {
+    try {
+      await import_promises6.default.unlink(tempFile);
+      await import_promises6.default.rmdir(tempDir);
+    } catch {
+    }
+  }
+}
+function buildEntryStub(entry, code) {
+  const name = entry.name;
+  if (!isValidIdentifier(name)) {
+    return "";
+  }
+  const escaped = escapeRegExp(name);
+  const usagePattern = new RegExp(`\\b${escaped}\\b`);
+  if (!usagePattern.test(code)) {
+    return "";
+  }
+  if (hasDeclaration(code, escaped)) {
+    return "";
+  }
+  switch (entry.kind) {
+    case "class":
+      return `declare class ${name} {}
+`;
+    case "enum":
+      return `declare enum ${name} {}
+`;
+    case "interface":
+      return `interface ${name} {}
+`;
+    case "type":
+      return `type ${name} = any;
+`;
+    case "function":
+      return `declare function ${name}(...args: any[]): any;
+`;
+    case "variable":
+      return `declare const ${name}: any;
+`;
+    default:
+      return `declare const ${name}: any;
+`;
+  }
+}
+function hasDeclaration(code, escapedName) {
+  const patterns = [
+    `\\bimport\\s+[^;]*\\b${escapedName}\\b`,
+    `\\bimport\\s+\\{[^}]*\\b${escapedName}\\b[^}]*\\}\\s+from`,
+    `\\bimport\\s+${escapedName}\\s+from`,
+    `\\bfunction\\s+${escapedName}\\b`,
+    `\\bclass\\s+${escapedName}\\b`,
+    `\\binterface\\s+${escapedName}\\b`,
+    `\\btype\\s+${escapedName}\\b`,
+    `\\bconst\\s+${escapedName}\\b`,
+    `\\blet\\s+${escapedName}\\b`,
+    `\\bvar\\s+${escapedName}\\b`,
+    `\\benum\\s+${escapedName}\\b`,
+    `\\bexport\\s+(?:default\\s+)?(?:function|class|const|let|var|enum|interface|type)\\s+${escapedName}\\b`
+  ];
+  return patterns.some((pattern) => new RegExp(pattern).test(code));
+}
+function isValidIdentifier(name) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function slugify(value) {
+  return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)+/g, "");
+}
+function languageToExtension(language) {
+  const normalized = language.toLowerCase();
+  if (normalized === "tsx") return "tsx";
+  if (normalized === "javascript" || normalized === "js") return "js";
+  if (normalized === "typescript" || normalized === "ts") return "ts";
+  return "txt";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  examplesPlugin
+});

package/dist/index.mjs

@@ -0,0 +1,219 @@
+// src/index.ts
+import fs8 from "fs/promises";
+import os from "os";
+import path10 from "path";
+import ts7 from "typescript";
+
+// ../../core/src/parser/index.ts
+import ts from "typescript";
+import path from "path";
+import fs from "fs";
+
+// ../../core/src/extractor/index.ts
+import ts5 from "typescript";
+import path3 from "path";
+
+// ../../core/src/parser/utils.ts
+import ts2 from "typescript";
+
+// ../../core/src/extractor/serializers.ts
+import ts4 from "typescript";
+import crypto from "crypto";
+import path2 from "path";
+
+// ../../core/src/extractor/utils.ts
+import ts3 from "typescript";
+
+// ../../core/src/generators/json/index.ts
+import fs2 from "fs/promises";
+import path4 from "path";
+
+// ../../core/src/version.ts
+var VERSION = "1.0.0";
+
+// ../../core/src/generators/markdown/index.ts
+import fs3 from "fs/promises";
+import path5 from "path";
+
+// ../../core/src/generators/html/index.ts
+import fs4 from "fs/promises";
+import path6 from "path";
+
+// ../../core/src/cache/FileCache.ts
+import fs5 from "fs/promises";
+import path7 from "path";
+import crypto2 from "crypto";
+
+// ../../core/src/cache/incremental.ts
+import ts6 from "typescript";
+import path8 from "path";
+import fs6 from "fs";
+
+// ../../core/src/deploy/static.ts
+import fs7 from "fs/promises";
+import path9 from "path";
+
+// src/index.ts
+function examplesPlugin(options = {}) {
+  const records = [];
+  return {
+    name: "@opensyntaxhq/autodocs-plugin-examples",
+    version: VERSION,
+    async afterExtract(docs) {
+      for (const entry of docs) {
+        const examples = entry.documentation?.examples;
+        if (!examples || examples.length === 0) {
+          continue;
+        }
+        for (const [index, example] of examples.entries()) {
+          if (options.validate) {
+            await validateExample(example, entry);
+          }
+          records.push({
+            entryId: entry.id,
+            entryName: entry.name,
+            index,
+            language: example.language,
+            code: example.code
+          });
+        }
+      }
+      return docs;
+    },
+    async afterGenerate(outputDir) {
+      if (!options.outputDir || records.length === 0) {
+        return;
+      }
+      const examplesDir = path10.isAbsolute(options.outputDir) ? options.outputDir : path10.join(outputDir, options.outputDir);
+      await fs8.mkdir(examplesDir, { recursive: true });
+      for (const record of records) {
+        const exampleNumber = record.index + 1;
+        const baseName = `${slugify(record.entryName)}__example-${exampleNumber.toString()}`;
+        const extension = languageToExtension(record.language);
+        const fileName = `${baseName}.${extension}`;
+        const filePath = path10.join(examplesDir, fileName);
+        await fs8.writeFile(filePath, record.code, "utf-8");
+        record.filePath = fileName;
+      }
+      const indexPayload = records.map((record) => ({
+        entryId: record.entryId,
+        entryName: record.entryName,
+        index: record.index,
+        language: record.language,
+        file: record.filePath
+      }));
+      await fs8.writeFile(
+        path10.join(examplesDir, "examples.json"),
+        JSON.stringify(indexPayload, null, 2),
+        "utf-8"
+      );
+    }
+  };
+}
+async function validateExample(example, entry) {
+  const tempDir = await fs8.mkdtemp(path10.join(os.tmpdir(), "autodocs-example-"));
+  const extension = languageToExtension(example.language);
+  const tempFile = path10.join(tempDir, `example.${extension}`);
+  try {
+    const normalized = example.code.endsWith("\n") ? example.code : `${example.code}
+`;
+    const stub = buildEntryStub(entry, normalized);
+    const wrapped = `${stub}${normalized}export {};
+`;
+    await fs8.writeFile(tempFile, wrapped, "utf-8");
+    const program = ts7.createProgram([tempFile], {
+      noEmit: true,
+      skipLibCheck: true,
+      target: ts7.ScriptTarget.ES2022
+    });
+    const diagnostics = ts7.getPreEmitDiagnostics(program);
+    if (diagnostics.length > 0) {
+      const errors = diagnostics.map((d) => {
+        const message = typeof d.messageText === "string" ? d.messageText : d.messageText.messageText;
+        return message;
+      });
+      throw new Error(`TypeScript errors:
+${errors.join("\n")}`);
+    }
+  } finally {
+    try {
+      await fs8.unlink(tempFile);
+      await fs8.rmdir(tempDir);
+    } catch {
+    }
+  }
+}
+function buildEntryStub(entry, code) {
+  const name = entry.name;
+  if (!isValidIdentifier(name)) {
+    return "";
+  }
+  const escaped = escapeRegExp(name);
+  const usagePattern = new RegExp(`\\b${escaped}\\b`);
+  if (!usagePattern.test(code)) {
+    return "";
+  }
+  if (hasDeclaration(code, escaped)) {
+    return "";
+  }
+  switch (entry.kind) {
+    case "class":
+      return `declare class ${name} {}
+`;
+    case "enum":
+      return `declare enum ${name} {}
+`;
+    case "interface":
+      return `interface ${name} {}
+`;
+    case "type":
+      return `type ${name} = any;
+`;
+    case "function":
+      return `declare function ${name}(...args: any[]): any;
+`;
+    case "variable":
+      return `declare const ${name}: any;
+`;
+    default:
+      return `declare const ${name}: any;
+`;
+  }
+}
+function hasDeclaration(code, escapedName) {
+  const patterns = [
+    `\\bimport\\s+[^;]*\\b${escapedName}\\b`,
+    `\\bimport\\s+\\{[^}]*\\b${escapedName}\\b[^}]*\\}\\s+from`,
+    `\\bimport\\s+${escapedName}\\s+from`,
+    `\\bfunction\\s+${escapedName}\\b`,
+    `\\bclass\\s+${escapedName}\\b`,
+    `\\binterface\\s+${escapedName}\\b`,
+    `\\btype\\s+${escapedName}\\b`,
+    `\\bconst\\s+${escapedName}\\b`,
+    `\\blet\\s+${escapedName}\\b`,
+    `\\bvar\\s+${escapedName}\\b`,
+    `\\benum\\s+${escapedName}\\b`,
+    `\\bexport\\s+(?:default\\s+)?(?:function|class|const|let|var|enum|interface|type)\\s+${escapedName}\\b`
+  ];
+  return patterns.some((pattern) => new RegExp(pattern).test(code));
+}
+function isValidIdentifier(name) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function slugify(value) {
+  return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)+/g, "");
+}
+function languageToExtension(language) {
+  const normalized = language.toLowerCase();
+  if (normalized === "tsx") return "tsx";
+  if (normalized === "javascript" || normalized === "js") return "js";
+  if (normalized === "typescript" || normalized === "ts") return "ts";
+  return "txt";
+}
+export {
+  examplesPlugin as default,
+  examplesPlugin
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@opensyntaxhq/autodocs-plugin-examples",
+  "version": "1.0.0",
+  "license": "Apache-2.0",
+  "description": "Code example validation and extraction plugin for Autodocs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OpenSyntaxHQ/autodocs.git",
+    "directory": "packages/plugins/examples"
+  },
+  "bugs": {
+    "url": "https://github.com/OpenSyntaxHQ/autodocs/issues"
+  },
+  "homepage": "https://github.com/OpenSyntaxHQ/autodocs",
+  "keywords": [
+    "autodocs",
+    "plugin",
+    "examples",
+    "documentation"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint .",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "typescript": "^5.9.0"
+  },
+  "peerDependencies": {
+    "@opensyntaxhq/autodocs-core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@opensyntaxhq/autodocs-core": "^1.0.0",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0"
+  }
+}