@aigne/doc-smith 0.9.7 → 0.9.8-alpha.1

package/utils/image-compress.mjs

@@ -0,0 +1,75 @@
+import sharp from "sharp";
+import path from "node:path";
+import { debug } from "./debug.mjs";
+
+/**
+ * Compress an image using sharp
+ * Supports JPEG, PNG, and WebP formats
+ * @param {string} inputPath - Path to the input image file
+ * @param {object} options - Compression options
+ * @param {number} options.quality - Compression quality (0-100, default: 80)
+ * @param {string} options.outputFormat - Output format: 'jpeg', 'png', 'webp' (default: auto-detect from input)
+ * @param {string} options.outputPath - Output path for compressed image (if not provided, creates temp file)
+ * @returns {Promise<string>} - Path to the compressed image (outputPath if provided, or temp path, or inputPath if compression fails)
+ */
+export async function compressImage(inputPath, options = {}) {
+  const { quality = 80, outputFormat, outputPath } = options;
+
+  try {
+    const inputExt = path.extname(inputPath).toLowerCase();
+
+    // Determine output format
+    let format = outputFormat;
+    if (!format) {
+      // Auto-detect from input extension
+      if (inputExt === ".jpg" || inputExt === ".jpeg") {
+        format = "jpeg";
+      } else if (inputExt === ".png") {
+        format = "png";
+      } else if (inputExt === ".webp") {
+        format = "webp";
+      } else {
+        // Default to JPEG for unknown formats
+        format = "jpeg";
+        debug(`Unknown image format ${inputExt}, defaulting to JPEG`);
+      }
+    }
+
+    // Determine output path
+    let finalOutputPath = outputPath;
+    if (!finalOutputPath) {
+      // If no output path provided, create temp file in same directory as input
+      const outputExt = format === "jpeg" ? ".jpg" : format === "png" ? ".png" : ".webp";
+      const inputDir = path.dirname(inputPath);
+      const inputBase = path.basename(inputPath, path.extname(inputPath));
+      finalOutputPath = path.join(inputDir, `${inputBase}.compressed${outputExt}`);
+    }
+
+    // Create sharp instance and compress
+    let sharpInstance = sharp(inputPath);
+
+    // Apply format-specific compression options
+    if (format === "jpeg") {
+      // mozjpeg is a valid sharp option for better JPEG compression
+      const jpegOptions = { quality, mozjpeg: true };
+      sharpInstance = sharpInstance.jpeg(jpegOptions);
+    } else if (format === "png") {
+      sharpInstance = sharpInstance.png({ quality, compressionLevel: 9 });
+    } else if (format === "webp") {
+      sharpInstance = sharpInstance.webp({ quality });
+    }
+
+    // Write compressed image directly to output path
+    await sharpInstance.toFile(finalOutputPath);
+
+    debug(
+      `✅ Image compressed: ${inputPath} -> ${finalOutputPath} (format: ${format}, quality: ${quality})`,
+    );
+
+    return finalOutputPath;
+  } catch (error) {
+    debug(`⚠️  Failed to compress image ${inputPath}: ${error.message}`);
+    // Return original path if compression fails
+    return inputPath;
+  }
+}

package/utils/kroki-utils.mjs

@@ -15,6 +15,7 @@ import {
   TMP_DIR,
 } from "./constants/index.mjs";
 import { getContentHash } from "./utils.mjs";
+import { d2CodeBlockRegex } from "./d2-utils.mjs";
 
 const debug = Debug("doc-smith");
 
@@ -59,11 +60,9 @@ export async function saveD2Assets({ markdown, docsDir }) {
     return markdown;
   }
 
-  const codeBlockRegex = /```d2.*\n([\s\S]*?)```/g;
-
   const { replaced } = await runIterator({
     input: markdown,
-    regexp: codeBlockRegex,
+    regexp: d2CodeBlockRegex,
     replace: true,
     fn: async ([_match, _code]) => {
       const assetDir = path.join(docsDir, "../", TMP_ASSETS_DIR, "d2");

package/utils/load-config.mjs

@@ -26,6 +26,35 @@ export default async function loadConfig({ config, appUrl }) {
     // Resolve file references (@ prefixed values)
     parsedConfig = await resolveFileReferences(parsedConfig);
 
+    // Read DOC-SMITH.md if exists in current working directory
+    const docSmithVariants = ["DOC-SMITH.md", "doc-smith.md", "DocSmith.md"];
+    let docSmithContent = "";
+    for (const variant of docSmithVariants) {
+      const docSmithPath = path.join(process.cwd(), variant);
+      try {
+        const content = await fs.readFile(docSmithPath, "utf-8");
+        if (content && content.trim()) {
+          docSmithContent = content.trim();
+          console.log(`✓ Found ${chalk.cyan(variant)}, custom rules loaded`);
+          break; // Use the first found file
+        }
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          // File exists but can't be read (permission issue, etc.)
+          console.warn(`⚠️  Found ${variant} but failed to read: ${error.message}`);
+        }
+        // ENOENT means file doesn't exist, continue to next variant
+      }
+    }
+
+    // Append DOC-SMITH content to rules if found
+    if (docSmithContent) {
+      const existingRules = parsedConfig.rules || "";
+      parsedConfig.rules = existingRules
+        ? `${existingRules}\n\n${docSmithContent}`
+        : docSmithContent;
+    }
+
     if (appUrl) {
       parsedConfig.appUrl = appUrl.includes("://") ? appUrl : `https://${appUrl}`;
     }

package/utils/sync-diagram-to-translations.mjs

@@ -0,0 +1,262 @@
+import { readdirSync } from "node:fs";
+import { readFileContent } from "./docs-finder-utils.mjs";
+import { debug } from "./debug.mjs";
+import path from "node:path";
+import fs from "fs-extra";
+import { d2CodeBlockRegex, diagramImageWithPathRegex } from "./d2-utils.mjs";
+
+/**
+ * Find all translation files for a document
+ * @param {string} docPath - Document path (e.g., "/guides/getting-started")
+ * @param {string} docsDir - Documentation directory
+ * @param {string} locale - Main language locale (e.g., "en")
+ * @returns {Promise<Array<{language: string, fileName: string}>>} - Array of translation file info
+ */
+async function findTranslationFiles(docPath, docsDir, locale) {
+  // Convert path to flat filename format
+  const flatName = docPath.replace(/^\//, "").replace(/\//g, "-");
+
+  try {
+    const files = readdirSync(docsDir);
+    const translationFiles = [];
+    const mainFileName = locale === "en" ? `${flatName}.md` : `${flatName}.${locale}.md`;
+
+    // Filter files to find translation files matching the pattern
+    for (const file of files) {
+      if (!file.endsWith(".md")) continue;
+      if (file === mainFileName) continue; // Skip main language file
+
+      // Case 1: File without language suffix (xxx.md) - this is English translation when main language is not English
+      if (file === `${flatName}.md` && locale !== "en") {
+        translationFiles.push({
+          language: "en",
+          fileName: file,
+        });
+        continue;
+      }
+
+      // Case 2: File with language suffix (xxx.{lang}.md) - all other translations
+      if (file.startsWith(`${flatName}.`) && file.match(/\.\w+(-\w+)?\.md$/)) {
+        const langMatch = file.match(/\.(\w+(-\w+)?)\.md$/);
+        if (langMatch && langMatch[1] !== locale) {
+          translationFiles.push({
+            language: langMatch[1],
+            fileName: file,
+          });
+        }
+      }
+    }
+
+    return translationFiles;
+  } catch (error) {
+    debug(`⚠️  Could not read translation files from ${docsDir}: ${error.message}`);
+    return [];
+  }
+}
+
+/**
+ * Extract diagram image paths from content
+ * @param {string} content - Document content
+ * @returns {Array<{path: string, fullMatch: string, index: number}>} - Array of diagram image info
+ */
+function extractDiagramImagePaths(content) {
+  const images = [];
+  const matches = Array.from(content.matchAll(diagramImageWithPathRegex));
+
+  for (const match of matches) {
+    images.push({
+      path: match[1],
+      fullMatch: match[0],
+      index: match.index,
+    });
+  }
+
+  return images;
+}
+
+/**
+ * Replace diagram images in translation files
+ * @param {string} mainContent - Main document content (already updated)
+ * @param {string} docPath - Document path
+ * @param {string} docsDir - Documentation directory
+ * @param {string} locale - Main language locale
+ * @param {string} operationType - Operation type: "delete", "add", "update", or "sync" (default)
+ * @returns {Promise<{updated: number, skipped: number, errors: Array}>} - Sync result
+ */
+export async function syncDiagramToTranslations(
+  mainContent,
+  docPath,
+  docsDir,
+  locale = "en",
+  operationType = "sync",
+) {
+  const result = {
+    updated: 0,
+    skipped: 0,
+    errors: [],
+  };
+
+  // Find all translation files
+  const translationFiles = await findTranslationFiles(docPath, docsDir, locale);
+
+  if (translationFiles.length === 0) {
+    debug("ℹ️  No translation files found, skipping sync");
+    return result;
+  }
+
+  // Extract diagram images from updated main content
+  const mainImages = extractDiagramImagePaths(mainContent);
+
+  // If no diagrams in main content and operation is not delete, skip sync
+  // For delete operations, we need to process translations even if main has 0 diagrams
+  // to remove diagrams from translation files
+  if (mainImages.length === 0 && operationType !== "delete") {
+    debug("ℹ️  No diagram images in main content, skipping sync");
+    return result;
+  }
+
+  // Process each translation file
+  for (const { fileName } of translationFiles) {
+    try {
+      const translationFilePath = path.join(docsDir, fileName);
+      const translationContent = await readFileContent(docsDir, fileName);
+
+      // Check for null or undefined (file read failure), but allow empty string (valid content)
+      if (translationContent === null || translationContent === undefined) {
+        debug(`⚠️  Could not read translation file: ${fileName}`);
+        result.skipped++;
+        continue;
+      }
+
+      let hasChanges = false;
+      let updatedContent = translationContent;
+
+      // Strategy 1: Replace D2 code blocks with AI images (if main doc switched from D2 to AI)
+      const translationD2Blocks = Array.from(translationContent.matchAll(d2CodeBlockRegex));
+      if (translationD2Blocks.length > 0 && mainImages.length > 0) {
+        // If main doc has AI images and translation has D2 blocks, replace them by index
+        for (let i = 0; i < Math.min(translationD2Blocks.length, mainImages.length); i++) {
+          const d2Match = translationD2Blocks[i];
+          const mainImage = mainImages[i];
+
+          if (d2Match && mainImage) {
+            // Replace D2 block with AI image from main doc
+            updatedContent = updatedContent.replace(d2Match[0], mainImage.fullMatch);
+            hasChanges = true;
+            debug(`🔄 Replaced D2 block with AI image in ${fileName} (index ${i})`);
+          }
+        }
+      }
+
+      // Strategy 2: Replace old image paths with new ones (if paths changed)
+      const translationImages = extractDiagramImagePaths(updatedContent); // Re-extract after D2 replacement
+      if (mainImages.length > 0) {
+        for (let i = 0; i < Math.min(translationImages.length, mainImages.length); i++) {
+          const translationImage = translationImages[i];
+          const mainImage = mainImages[i];
+
+          // If image path changed, update it
+          if (translationImage && mainImage && translationImage.path !== mainImage.path) {
+            // Replace old image path with new one (escape special regex characters)
+            const escapedPath = translationImage.path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            const oldImagePattern = new RegExp(
+              `<!--\\s*DIAGRAM_IMAGE_START:[^>]+-->\\s*!\\[[^\\]]*\\]\\(${escapedPath}\\)\\s*<!--\\s*DIAGRAM_IMAGE_END\\s*-->`,
+              "g",
+            );
+            updatedContent = updatedContent.replace(oldImagePattern, mainImage.fullMatch);
+            hasChanges = true;
+            debug(
+              `🔄 Updated image path in ${fileName} (index ${i}): ${translationImage.path} -> ${mainImage.path}`,
+            );
+          }
+        }
+      }
+
+      // Strategy 3: If translation has fewer images than main, add missing ones
+      // (This handles cases where new diagrams were added)
+      let finalTranslationImages = extractDiagramImagePaths(updatedContent); // Re-extract after all replacements
+      if (mainImages.length > 0 && finalTranslationImages.length < mainImages.length) {
+        // Find the last diagram position in updated content
+        const lastDiagramIndex =
+          finalTranslationImages.length > 0
+            ? finalTranslationImages[finalTranslationImages.length - 1].index +
+              finalTranslationImages[finalTranslationImages.length - 1].fullMatch.length
+            : updatedContent.length;
+
+        // Add missing images after the last diagram
+        const missingImages = mainImages.slice(finalTranslationImages.length);
+        const imagesToAdd = missingImages.map((img) => img.fullMatch).join("\n\n");
+
+        updatedContent =
+          updatedContent.slice(0, lastDiagramIndex) +
+          "\n\n" +
+          imagesToAdd +
+          "\n\n" +
+          updatedContent.slice(lastDiagramIndex);
+        hasChanges = true;
+        debug(`➕ Added ${missingImages.length} missing diagram(s) to ${fileName}`);
+        // Re-extract after adding images
+        finalTranslationImages = extractDiagramImagePaths(updatedContent);
+      }
+
+      // Strategy 4: If translation has more images than main, remove excess ones
+      // (This handles cases where diagrams were deleted from main document, including all diagrams)
+      if (finalTranslationImages.length > mainImages.length) {
+        // Remove excess images from translation (keep only the first N images matching main)
+        // Process from end to start to preserve indices
+        const excessCount = finalTranslationImages.length - mainImages.length;
+        for (let i = finalTranslationImages.length - 1; i >= mainImages.length; i--) {
+          const imageToRemove = finalTranslationImages[i];
+          const before = updatedContent.substring(0, imageToRemove.index);
+          const after = updatedContent.substring(
+            imageToRemove.index + imageToRemove.fullMatch.length,
+          );
+          // Remove the image and clean up extra newlines
+          updatedContent = `${before.replace(/\n+$/, "")}\n${after.replace(/^\n+/, "")}`;
+          hasChanges = true;
+        }
+        debug(`➖ Removed ${excessCount} excess diagram(s) from ${fileName}`);
+      }
+
+      // Strategy 5: Remove D2 code blocks from translation if main has no diagrams
+      // (This handles cases where all diagrams were deleted from main document)
+      if (mainImages.length === 0) {
+        // Re-extract D2 blocks from updated content (in case some were already replaced)
+        const remainingD2Blocks = Array.from(updatedContent.matchAll(d2CodeBlockRegex));
+        if (remainingD2Blocks.length > 0) {
+          // Remove all D2 code blocks from translation
+          // Process from end to start to preserve indices
+          for (let i = remainingD2Blocks.length - 1; i >= 0; i--) {
+            const d2Match = remainingD2Blocks[i];
+            const before = updatedContent.substring(0, d2Match.index);
+            const after = updatedContent.substring(d2Match.index + d2Match[0].length);
+            // Remove the D2 block and clean up extra newlines
+            updatedContent = `${before.replace(/\n+$/, "")}\n${after.replace(/^\n+/, "")}`;
+            hasChanges = true;
+          }
+          // Clean up extra newlines
+          updatedContent = updatedContent.replace(/\n{3,}/g, "\n\n");
+          debug(`➖ Removed ${remainingD2Blocks.length} D2 code block(s) from ${fileName}`);
+        }
+      }
+
+      // Save updated translation file if there were changes
+      if (hasChanges) {
+        await fs.writeFile(translationFilePath, updatedContent, "utf8");
+        result.updated++;
+        debug(`✅ Synced diagram images to ${fileName}`);
+      } else {
+        result.skipped++;
+        debug(`⏭️  No changes needed for ${fileName}`);
+      }
+    } catch (error) {
+      debug(`❌ Error syncing diagram to ${fileName}: ${error.message}`);
+      result.errors.push({
+        file: fileName,
+        error: error.message,
+      });
+    }
+  }
+
+  return result;
+}

package/utils/utils.mjs

@@ -302,10 +302,18 @@ export function hasFileChangesBetweenCommits(
     return addedOrDeletedFiles.some((filePath) => {
       // Check if file matches any include pattern
       const matchesInclude = includePatterns.some((pattern) => {
+        // Skip empty patterns
+        if (!pattern || !pattern.trim()) {
+          return false;
+        }
         // First escape all regex special characters except * and ?
         const escapedPattern = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
         // Then convert glob wildcards to regex
         const regexPattern = escapedPattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+        // Only create regex if pattern is not empty
+        if (!regexPattern) {
+          return false;
+        }
         const regex = new RegExp(regexPattern);
         return regex.test(filePath);
       });
@@ -316,10 +324,18 @@ export function hasFileChangesBetweenCommits(
 
       // Check if file matches any exclude pattern
       const matchesExclude = excludePatterns.some((pattern) => {
+        // Skip empty patterns
+        if (!pattern || !pattern.trim()) {
+          return false;
+        }
         // First escape all regex special characters except * and ?
         const escapedPattern = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
         // Then convert glob wildcards to regex
         const regexPattern = escapedPattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+        // Only create regex if pattern is not empty
+        if (!regexPattern) {
+          return false;
+        }
         const regex = new RegExp(regexPattern);
         return regex.test(filePath);
       });
@@ -370,6 +386,10 @@ export async function loadConfigFromFile() {
  * @returns {string} Updated file content
  */
 function handleArrayValueUpdate(key, value, comment, fileContent) {
+  // Skip if key is empty to avoid "Empty regular expressions are not allowed" error
+  if (!key || !key.trim()) {
+    return fileContent;
+  }
   // Use yaml library to safely serialize the key-value pair
   const yamlObject = { [key]: value };
   const yamlContent = yamlStringify(yamlObject).trim();
@@ -455,6 +475,10 @@ function handleArrayValueUpdate(key, value, comment, fileContent) {
  * @returns {string} Updated file content
  */
 function handleStringValueUpdate(key, value, comment, fileContent) {
+  // Skip if key is empty to avoid "Empty regular expressions are not allowed" error
+  if (!key || !key.trim()) {
+    return fileContent;
+  }
   // Use yaml library to safely serialize the key-value pair
   const yamlObject = { [key]: value };
   const yamlContent = yamlStringify(yamlObject).trim();

package/agents/create/check-diagram.mjs

@@ -1,40 +0,0 @@
-import { checkContent } from "../../utils/d2-utils.mjs";
-
-export default async function checkD2DiagramIsValid({ diagramSourceCode }) {
-  try {
-    await checkContent({ content: diagramSourceCode });
-    return {
-      isValid: true,
-    };
-  } catch (err) {
-    return {
-      isValid: false,
-      diagramError: err.message,
-    };
-  }
-}
-
-checkD2DiagramIsValid.input_schema = {
-  type: "object",
-  properties: {
-    diagramSourceCode: {
-      type: "string",
-      description: "Source code of d2 diagram",
-    },
-  },
-  required: ["diagramSourceCode"],
-};
-checkD2DiagramIsValid.output_schema = {
-  type: "object",
-  properties: {
-    isValid: {
-      type: "boolean",
-      description: "Indicates whether the provided d2 diagram source passes validation",
-    },
-    error: {
-      type: "string",
-      description: "Validation error details when the diagram does not pass",
-    },
-  },
-  required: ["isValid"],
-};

package/agents/create/draw-diagram.yaml

@@ -1,27 +0,0 @@
-name: drawDiagram
-description: Generate a D2 diagram from document content.
-instructions:
-  - role: system
-    url: ../../prompts/detail/diagram/system-prompt.md
-  - role: user
-    url: ../../prompts/detail/diagram/user-prompt.md
-input_schema:
-  type: object
-  properties:
-    documentContent:
-      type: string
-      description: The **raw text content** of the current document. (**Note:** This is the original document and **does not include** any diagram source code.)
-    locale:
-      type: string
-      description: Language for diagram labels and text
-      default: en
-  required:
-    - documentContent
-output_schema:
-  type: object
-  properties:
-    diagramSourceCode:
-      type: string
-      description: The **diagram source code** generated from the input text.
-  required:
-    - diagramSourceCode

package/agents/create/merge-diagram.yaml

@@ -1,39 +0,0 @@
-name: mergeDiagramToDocument
-description: Merge Diagram source code into document
-instructions: |
-  You are an AI assistant that helps to merge d2 diagram into document.
-
-  <detail_data_source>
-  {{ content }}
-  </detail_data_source>
-
-  <diagram_source_code>
-  {{ diagramSourceCode }}
-  </diagram_source_code>
-
-  Given the source content of a document and the D2 diagram source code, your task is to:
-  - **Keep the original content as soon as possible.**
-  - D2 diagram source code should wrap by ```d2 and ``` in markdown format.
-  - Should find proper position to insert the D2 diagram in the document, usually after the first paragraph or after the section that describes the diagram.
-  - If there is no suitable position, append it to the end of the document.
-  - If there is no D2 diagram source code, return the original document content without any changes.
-input_schema:
-  type: object
-  properties:
-    content:
-      type: string
-      description: Source content of the document
-    diagramSourceCode:
-      type: string
-      description: Source content of D2 Diagram
-  required:
-    - content
-    - diagramSourceCode
-output_schema:
-  type: object
-  properties:
-    content:
-      type: string
-      description: Merged content of the document with D2 diagram
-  required:
-    - content

package/agents/create/wrap-diagram-code.mjs

@@ -1,35 +0,0 @@
-import { wrapCode } from "../../utils/d2-utils.mjs";
-
-export default async function wrapDiagramCode({ diagramSourceCode }) {
-  try {
-    const result = await wrapCode({ content: diagramSourceCode });
-    return {
-      diagramSourceCode: result,
-    };
-  } catch {
-    return {
-      diagramSourceCode,
-    };
-  }
-}
-
-wrapDiagramCode.input_schema = {
-  type: "object",
-  properties: {
-    diagramSourceCode: {
-      type: "string",
-      description: "Source code of d2 diagram",
-    },
-  },
-  required: ["diagramSourceCode"],
-};
-wrapDiagramCode.output_schema = {
-  type: "object",
-  properties: {
-    diagramSourceCode: {
-      type: "string",
-      description: "Source code of d2 diagram",
-    },
-  },
-  required: ["diagramSourceCode"],
-};