@aigne/doc-smith 0.8.6 → 0.8.7

package/utils/conflict-detector.mjs

@@ -72,7 +72,7 @@ export function getFilteredOptions(targetQuestion, currentSelections, allOptions
 }
 
 /**
- * Detect conflicts in user configuration selections that can be resolved through structure planning
+ * Detect conflicts in user configuration selections that can be resolved through document structure
  * @param {Object} config - User configuration
  * @returns {Array} Array of detected conflicts with resolution strategies
  */

package/utils/constants.mjs

@@ -345,7 +345,7 @@ export const SUPPORTED_FILE_EXTENSIONS = [".txt", ".md", ".json", ".yaml", ".yml
 export const CONFLICT_RULES = {
   // Internal conflicts within the same question (multi-select conflicts)
   internalConflicts: {
-    // Note: Most conflicts can be resolved through intelligent document structure planning
+    // Note: Most conflicts can be resolved through intelligent document structure
     // Only keeping conflicts that represent fundamental incompatibilities
   },
 
@@ -419,7 +419,7 @@ export const CONFLICT_RULES = {
 
 // Conflict resolution rules - defines how to handle conflicts when users select conflicting options
 export const CONFLICT_RESOLUTION_RULES = {
-  // Document purpose conflicts that can be resolved through structure planning
+  // Document purpose conflicts that can be resolved through document structure
   documentPurpose: [
     {
       conflictItems: ["getStarted", "findAnswers"],
@@ -446,7 +446,7 @@ export const CONFLICT_RESOLUTION_RULES = {
     },
   ],
 
-  // Target audience conflicts that can be resolved through structure planning
+  // Target audience conflicts that can be resolved through document structure
   targetAudienceTypes: [
     {
       conflictItems: ["endUsers", "developers"],
@@ -534,7 +534,9 @@ export const D2_CONFIG = `vars: {
 }`;
 
 export const KROKI_CONCURRENCY = 5;
+export const D2_CONCURRENCY = 10;
 export const FILE_CONCURRENCY = 3;
+export const DOC_SMITH_DIR = ".aigne/doc-smith";
 export const TMP_DIR = ".tmp";
 export const TMP_DOCS_DIR = "docs";
 

package/utils/d2-utils.mjs

@@ -0,0 +1,194 @@
+import path from "node:path";
+
+import { D2 } from "@terrastruct/d2";
+import Debug from "debug";
+import fs from "fs-extra";
+import { glob } from "glob";
+import pMap from "p-map";
+
+import {
+  D2_CONCURRENCY,
+  D2_CONFIG,
+  DOC_SMITH_DIR,
+  FILE_CONCURRENCY,
+  TMP_ASSETS_DIR,
+  TMP_DIR,
+} from "./constants.mjs";
+import { iconMap } from "./icon-map.mjs";
+import { getContentHash } from "./utils.mjs";
+
+const debug = Debug("doc-smith");
+
+export async function getChart({ content, strict }) {
+  const d2 = new D2();
+  const iconUrlList = Object.keys(iconMap);
+  const escapedUrls = iconUrlList.map((url) => url.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  const regexPattern = escapedUrls.join("|");
+  const regex = new RegExp(regexPattern, "g");
+
+  const contentWithBase64Img = content.replace(regex, (match) => {
+    return iconMap[match];
+  });
+  try {
+    const { diagram, renderOptions, graph } = await d2.compile(contentWithBase64Img);
+
+    // Ignore stroke-dash in sequence diagram
+    if (
+      graph?.root?.attributes?.shape &&
+      graph.root.attributes.shape.value !== "sequence_diagram"
+    ) {
+      // Save first level container
+      const firstLevelContainer = new Set();
+      diagram.shapes.forEach((x) => {
+        const idList = x.id.split(".");
+        if (idList.length > 1) {
+          const targetShape = diagram.shapes.find((x) => x.id === idList[0]);
+          if (targetShape && !["c4-person", "cylinder", "queue"].includes(targetShape.type)) {
+            firstLevelContainer.add(targetShape);
+          }
+        }
+      });
+      firstLevelContainer.forEach((shape) => {
+        if (!shape.strokeDash) {
+          // NOTICE: The data structure here is different from the d2 source code.
+          shape.strokeDash = 3;
+        }
+      });
+    }
+
+    const svg = await d2.render(diagram, renderOptions);
+
+    return svg;
+  } catch (err) {
+    if (strict) throw err;
+
+    console.error("Failed to generate D2 chart. Content:", content, "Error:", err);
+    return null;
+  } finally {
+    d2.worker.terminate();
+  }
+}
+
+// Helper: save d2 svg assets alongside document
+export async function saveAssets({ markdown, docsDir }) {
+  if (!markdown) {
+    return markdown;
+  }
+
+  const codeBlockRegex = /```d2.*\n([\s\S]*?)```/g;
+
+  const { replaced } = await runIterator({
+    input: markdown,
+    regexp: codeBlockRegex,
+    replace: true,
+    fn: async ([_match, _code]) => {
+      const assetDir = path.join(docsDir, "../", TMP_ASSETS_DIR, "d2");
+      await fs.ensureDir(assetDir);
+      const d2Content = [D2_CONFIG, _code].join("\n");
+      const fileName = `${getContentHash(d2Content)}.svg`;
+      const svgPath = path.join(assetDir, fileName);
+
+      if (await fs.pathExists(svgPath)) {
+        debug("Found assets cache, skipping generation", svgPath);
+      } else {
+        try {
+          debug("start generate d2 chart", svgPath);
+          if (debug.enabled) {
+            const d2FileName = `${getContentHash(d2Content)}.d2`;
+            const d2Path = path.join(assetDir, d2FileName);
+            await fs.writeFile(d2Path, d2Content, { encoding: "utf8" });
+          }
+
+          const svg = await getChart({ content: d2Content });
+          if (svg) {
+            await fs.writeFile(svgPath, svg, { encoding: "utf8" });
+          }
+        } catch (error) {
+          debug("Failed to generate D2 chart. Content:", d2Content, "Error:", error);
+          return _code;
+        }
+      }
+      return `![](${path.posix.join("..", TMP_ASSETS_DIR, "d2", fileName)})`;
+    },
+    options: { concurrency: D2_CONCURRENCY },
+  });
+
+  return replaced;
+}
+
+export async function beforePublishHook({ docsDir }) {
+  // Example: process each markdown file (replace with your logic)
+  const mdFilePaths = await glob("**/*.md", { cwd: docsDir });
+  await pMap(
+    mdFilePaths,
+    async (filePath) => {
+      let finalContent = await fs.readFile(path.join(docsDir, filePath), { encoding: "utf8" });
+      finalContent = await saveAssets({ markdown: finalContent, docsDir });
+
+      await fs.writeFile(path.join(docsDir, filePath), finalContent, { encoding: "utf8" });
+    },
+    { concurrency: FILE_CONCURRENCY },
+  );
+}
+
+async function runIterator({ input, regexp, fn = () => {}, options, replace = false }) {
+  if (!input) return input;
+  const matches = [...input.matchAll(regexp)];
+  const results = [];
+  await pMap(
+    matches,
+    async (...args) => {
+      const resultItem = await fn(...args);
+      results.push(resultItem);
+    },
+    options,
+  );
+
+  let replaced = input;
+  if (replace) {
+    let index = 0;
+    replaced = replaced.replace(regexp, () => {
+      return results[index++];
+    });
+  }
+
+  return {
+    results,
+    replaced,
+  };
+}
+
+export async function checkContent({ content }) {
+  await ensureTmpDir();
+  const assetDir = path.join(DOC_SMITH_DIR, TMP_DIR, TMP_ASSETS_DIR, "d2");
+  await fs.ensureDir(assetDir);
+  const d2Content = [D2_CONFIG, content].join("\n");
+  const fileName = `${getContentHash(d2Content)}.svg`;
+  const svgPath = path.join(assetDir, fileName);
+
+  if (debug.enabled) {
+    const d2FileName = `${getContentHash(d2Content)}.d2`;
+    const d2Path = path.join(assetDir, d2FileName);
+    await fs.writeFile(d2Path, d2Content, { encoding: "utf8" });
+  }
+
+  if (await fs.pathExists(svgPath)) {
+    debug("Found assets cache, skipping generation", svgPath);
+    return;
+  }
+
+  const svg = await getChart({ content: d2Content, strict: true });
+  await fs.writeFile(svgPath, svg, { encoding: "utf8" });
+}
+
+export async function ensureTmpDir() {
+  const tmpDir = path.join(DOC_SMITH_DIR, TMP_DIR);
+  if (!(await fs.pathExists(path.join(tmpDir, ".gitignore")))) {
+    await fs.ensureDir(tmpDir);
+    await fs.writeFile(path.join(tmpDir, ".gitignore"), "**/*", { encoding: "utf8" });
+  }
+}
+
+export function isValidCode(lang) {
+  return lang?.toLowerCase() === "d2";
+}

package/utils/docs-finder-utils.mjs

@@ -24,8 +24,8 @@ function generateFileName(flatName, locale) {
 }
 
 /**
- * Find a single item by path in structure plan result and read its content
- * @param {Array} structurePlanResult - Array of structure plan items
+ * Find a single item by path in document structure result and read its content
+ * @param {Array} documentExecutionStructure - Array of document structure items
  * @param {string} docPath - Document path to find (supports .md filenames)
  * @param {string} boardId - Board ID for fallback matching
  * @param {string} docsDir - Docs directory path for reading content
@@ -33,7 +33,7 @@ function generateFileName(flatName, locale) {
  * @returns {Promise<Object|null>} Found item with content or null
  */
 export async function findItemByPath(
-  structurePlanResult,
+  documentExecutionStructure,
   docPath,
   boardId,
   docsDir,
@@ -46,10 +46,10 @@ export async function findItemByPath(
   if (docPath.endsWith(".md")) {
     fileName = docPath;
     const flatName = fileNameToFlatPath(docPath);
-    foundItem = findItemByFlatName(structurePlanResult, flatName);
+    foundItem = findItemByFlatName(documentExecutionStructure, flatName);
   } else {
     // First try direct path matching
-    foundItem = structurePlanResult.find((item) => item.path === docPath);
+    foundItem = documentExecutionStructure.find((item) => item.path === docPath);
 
     // If not found and boardId is provided, try boardId-flattenedPath format matching
     if (!foundItem && boardId) {
@@ -59,7 +59,7 @@ export async function findItemByPath(
         const flattenedPath = docPath.substring(boardId.length + 1);
 
         // Find item by comparing flattened paths
-        foundItem = structurePlanResult.find((item) => {
+        foundItem = documentExecutionStructure.find((item) => {
           // Convert item.path to flattened format (replace / with -)
           const itemFlattenedPath = item.path.replace(/^\//, "").replace(/\//g, "-");
           return itemFlattenedPath === flattenedPath;
@@ -116,10 +116,10 @@ export async function readFileContent(docsDir, fileName) {
  * Get main language markdown files from docs directory
  * @param {string} docsDir - Docs directory path
  * @param {string} locale - Main language locale (e.g., 'en', 'zh', 'fr')
- * @param {Array} structurePlanResult - Array of structure plan items to determine file order
- * @returns {Promise<string[]>} Array of main language .md files ordered by structurePlanResult
+ * @param {Array} documentExecutionStructure - Array of document structure items to determine file order
+ * @returns {Promise<string[]>} Array of main language .md files ordered by documentExecutionStructure
  */
-export async function getMainLanguageFiles(docsDir, locale, structurePlanResult = null) {
+export async function getMainLanguageFiles(docsDir, locale, documentExecutionStructure = null) {
   const files = await readdir(docsDir);
 
   // Filter for main language .md files (exclude _sidebar.md)
@@ -140,36 +140,36 @@ export async function getMainLanguageFiles(docsDir, locale, structurePlanResult
     }
   });
 
-  // If structurePlanResult is provided, sort files according to the order in structurePlanResult
-  if (structurePlanResult && Array.isArray(structurePlanResult)) {
-    // Create a map from flat file name to structure plan order
+  // If documentExecutionStructure is provided, sort files according to the order in documentExecutionStructure
+  if (documentExecutionStructure && Array.isArray(documentExecutionStructure)) {
+    // Create a map from flat file name to document structure order
     const orderMap = new Map();
-    structurePlanResult.forEach((item, index) => {
+    documentExecutionStructure.forEach((item, index) => {
       const itemFlattenedPath = item.path.replace(/^\//, "").replace(/\//g, "-");
       const expectedFileName = generateFileName(itemFlattenedPath, locale);
       orderMap.set(expectedFileName, index);
     });
 
-    // Sort filtered files based on their order in structurePlanResult
+    // Sort filtered files based on their order in documentExecutionStructure
     return filteredFiles.sort((a, b) => {
       const orderA = orderMap.get(a);
       const orderB = orderMap.get(b);
 
-      // If both files are in the structure plan, sort by order
+      // If both files are in the document structure, sort by order
       if (orderA !== undefined && orderB !== undefined) {
         return orderA - orderB;
       }
 
-      // If only one file is in the structure plan, it comes first
+      // If only one file is in the document structure, it comes first
       if (orderA !== undefined) return -1;
       if (orderB !== undefined) return 1;
 
-      // If neither file is in the structure plan, maintain alphabetical order
+      // If neither file is in the document structure, maintain alphabetical order
       return a.localeCompare(b);
     });
   }
 
-  // If no structurePlanResult provided, return files in alphabetical order
+  // If no documentExecutionStructure provided, return files in alphabetical order
   return filteredFiles.sort();
 }
 
@@ -189,13 +189,13 @@ export function fileNameToFlatPath(fileName) {
 }
 
 /**
- * Find structure plan item by flattened file name
- * @param {Array} structurePlanResult - Array of structure plan items
+ * Find document structure item by flattened file name
+ * @param {Array} documentExecutionStructure - Array of document structure items
  * @param {string} flatName - Flattened file name
  * @returns {Object|null} Found item or null
  */
-export function findItemByFlatName(structurePlanResult, flatName) {
-  return structurePlanResult.find((item) => {
+export function findItemByFlatName(documentExecutionStructure, flatName) {
+  return documentExecutionStructure.find((item) => {
     const itemFlattenedPath = item.path.replace(/^\//, "").replace(/\//g, "-");
     return itemFlattenedPath === flatName;
   });
@@ -204,11 +204,11 @@ export function findItemByFlatName(structurePlanResult, flatName) {
 /**
  * Process selected files and convert to found items with content
  * @param {string[]} selectedFiles - Array of selected file names
- * @param {Array} structurePlanResult - Array of structure plan items
+ * @param {Array} documentExecutionStructure - Array of document structure items
  * @param {string} docsDir - Docs directory path
  * @returns {Promise<Object[]>} Array of found items with content
  */
-export async function processSelectedFiles(selectedFiles, structurePlanResult, docsDir) {
+export async function processSelectedFiles(selectedFiles, documentExecutionStructure, docsDir) {
   const foundItems = [];
 
   for (const selectedFile of selectedFiles) {
@@ -219,7 +219,7 @@ export async function processSelectedFiles(selectedFiles, structurePlanResult, d
     const flatName = fileNameToFlatPath(selectedFile);
 
     // Try to find matching item by comparing flattened paths
-    const foundItemByFile = findItemByFlatName(structurePlanResult, flatName);
+    const foundItemByFile = findItemByFlatName(documentExecutionStructure, flatName);
 
     if (foundItemByFile) {
       const result = {
@@ -233,7 +233,7 @@ export async function processSelectedFiles(selectedFiles, structurePlanResult, d
 
       foundItems.push(result);
     } else {
-      console.warn(`⚠️  No structure plan item found for file: ${selectedFile}`);
+      console.warn(`⚠️  No document structure item found for file: ${selectedFile}`);
     }
   }