@aigne/doc-smith 0.3.1 → 0.4.0

package/utils/docs-finder-utils.mjs

@@ -0,0 +1,258 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * Get action-specific text based on isTranslate flag
+ * @param {boolean} isTranslate - Whether this is a translation action
+ * @param {string} baseText - Base text template with {action} placeholder
+ * @returns {string} Text with action replaced
+ */
+export function getActionText(isTranslate, baseText) {
+  const action = isTranslate ? "translate" : "update";
+  return baseText.replace("{action}", action);
+}
+
+/**
+ * Generate filename based on flattened path and locale
+ * @param {string} flatName - Flattened path name
+ * @param {string} locale - Main language locale (e.g., 'en', 'zh', 'fr')
+ * @returns {string} Generated filename
+ */
+function generateFileName(flatName, locale) {
+  const isEnglish = locale === "en";
+  return isEnglish ? `${flatName}.md` : `${flatName}.${locale}.md`;
+}
+
+/**
+ * Find a single item by path in structure plan result and read its content
+ * @param {Array} structurePlanResult - Array of structure plan 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
+ * @param {string} locale - Main language locale (e.g., 'en', 'zh', 'fr')
+ * @returns {Promise<Object|null>} Found item with content or null
+ */
+export async function findItemByPath(
+  structurePlanResult,
+  docPath,
+  boardId,
+  docsDir,
+  locale = "en",
+) {
+  let foundItem = null;
+  let fileName = null;
+
+  // Check if docPath is a .md filename
+  if (docPath.endsWith(".md")) {
+    fileName = docPath;
+    const flatName = fileNameToFlatPath(docPath);
+    foundItem = findItemByFlatName(structurePlanResult, flatName);
+  } else {
+    // First try direct path matching
+    foundItem = structurePlanResult.find((item) => item.path === docPath);
+
+    // If not found and boardId is provided, try boardId-flattenedPath format matching
+    if (!foundItem && boardId) {
+      // Check if path starts with boardId followed by a dash
+      if (docPath.startsWith(`${boardId}-`)) {
+        // Extract the flattened path part after boardId-
+        const flattenedPath = docPath.substring(boardId.length + 1);
+
+        // Find item by comparing flattened paths
+        foundItem = structurePlanResult.find((item) => {
+          // Convert item.path to flattened format (replace / with -)
+          const itemFlattenedPath = item.path.replace(/^\//, "").replace(/\//g, "-");
+          return itemFlattenedPath === flattenedPath;
+        });
+      }
+    }
+
+    // Generate filename from found item path
+    if (foundItem) {
+      const itemFlattenedPath = foundItem.path.replace(/^\//, "").replace(/\//g, "-");
+      fileName = generateFileName(itemFlattenedPath, locale);
+    }
+  }
+
+  if (!foundItem) {
+    return null;
+  }
+
+  // Read file content if docsDir is provided
+  let content = null;
+  if (docsDir && fileName) {
+    content = await readFileContent(docsDir, fileName);
+  }
+
+  // Return item with content
+  const result = {
+    ...foundItem,
+  };
+
+  if (content !== null) {
+    result.content = content;
+  }
+
+  return result;
+}
+
+/**
+ * Read file content from docs directory
+ * @param {string} docsDir - Docs directory path
+ * @param {string} fileName - File name to read
+ * @returns {Promise<string|null>} File content or null if failed
+ */
+export async function readFileContent(docsDir, fileName) {
+  try {
+    const filePath = join(docsDir, fileName);
+    return await readFile(filePath, "utf-8");
+  } catch (readError) {
+    console.warn(`⚠️  Could not read content from ${fileName}:`, readError.message);
+    return null;
+  }
+}
+
+/**
+ * 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
+ */
+export async function getMainLanguageFiles(docsDir, locale, structurePlanResult = null) {
+  const files = await readdir(docsDir);
+
+  // Filter for main language .md files (exclude _sidebar.md)
+  const filteredFiles = files.filter((file) => {
+    // Skip non-markdown files and _sidebar.md
+    if (!file.endsWith(".md") || file === "_sidebar.md") {
+      return false;
+    }
+
+    // If main language is English, return files without language suffix
+    if (locale === "en") {
+      // Return files that don't have language suffixes (e.g., overview.md, not overview.zh.md)
+      return !file.match(/\.\w+(-\w+)?\.md$/);
+    } else {
+      // For non-English main language, return files with the exact locale suffix
+      const localePattern = new RegExp(`\\.${locale}\\.md$`);
+      return localePattern.test(file);
+    }
+  });
+
+  // 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
+    const orderMap = new Map();
+    structurePlanResult.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
+    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 (orderA !== undefined && orderB !== undefined) {
+        return orderA - orderB;
+      }
+
+      // If only one file is in the structure plan, it comes first
+      if (orderA !== undefined) return -1;
+      if (orderB !== undefined) return 1;
+
+      // If neither file is in the structure plan, maintain alphabetical order
+      return a.localeCompare(b);
+    });
+  }
+
+  // If no structurePlanResult provided, return files in alphabetical order
+  return filteredFiles.sort();
+}
+
+/**
+ * Convert filename to flattened path format
+ * @param {string} fileName - File name to convert
+ * @returns {string} Flattened path without .md extension and language suffix
+ */
+export function fileNameToFlatPath(fileName) {
+  // Remove .md extension first
+  let flatName = fileName.replace(/\.md$/, "");
+
+  // Remove language suffix if present (e.g., .zh, .zh-CN, .fr, etc.)
+  flatName = flatName.replace(/\.\w+(-\w+)?$/, "");
+
+  return flatName;
+}
+
+/**
+ * Find structure plan item by flattened file name
+ * @param {Array} structurePlanResult - Array of structure plan items
+ * @param {string} flatName - Flattened file name
+ * @returns {Object|null} Found item or null
+ */
+export function findItemByFlatName(structurePlanResult, flatName) {
+  return structurePlanResult.find((item) => {
+    const itemFlattenedPath = item.path.replace(/^\//, "").replace(/\//g, "-");
+    return itemFlattenedPath === 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 {string} docsDir - Docs directory path
+ * @returns {Promise<Object[]>} Array of found items with content
+ */
+export async function processSelectedFiles(selectedFiles, structurePlanResult, docsDir) {
+  const foundItems = [];
+
+  for (const selectedFile of selectedFiles) {
+    // Read the selected .md file content
+    const selectedFileContent = await readFileContent(docsDir, selectedFile);
+
+    // Convert filename back to path
+    const flatName = fileNameToFlatPath(selectedFile);
+
+    // Try to find matching item by comparing flattened paths
+    const foundItemByFile = findItemByFlatName(structurePlanResult, flatName);
+
+    if (foundItemByFile) {
+      const result = {
+        ...foundItemByFile,
+      };
+
+      // Add content if we read it from user selection
+      if (selectedFileContent !== null) {
+        result.content = selectedFileContent;
+      }
+
+      foundItems.push(result);
+    } else {
+      console.warn(`⚠️  No structure plan item found for file: ${selectedFile}`);
+    }
+  }
+
+  return foundItems;
+}
+
+/**
+ * Add feedback to all items in the array
+ * @param {Object[]} items - Array of items to add feedback to
+ * @param {string} feedback - Feedback text to add
+ * @returns {Object[]} Items with feedback added
+ */
+export function addFeedbackToItems(items, feedback) {
+  if (!feedback?.trim()) {
+    return items;
+  }
+
+  return items.map((item) => ({
+    ...item,
+    feedback: feedback.trim(),
+  }));
+}

package/utils/markdown-checker.mjs

@@ -224,10 +224,13 @@ function checkContentStructure(markdown, source, errorMessages) {
   }
 
   // Check if content ends with proper punctuation (indicating completeness)
+  const validEndingPunctuation = [".", "。", ")", "|"];
   const trimmedText = markdown.trim();
-  if (trimmedText.length > 0 && !trimmedText.endsWith(".") && !trimmedText.endsWith("。")) {
+  const hasValidEnding = validEndingPunctuation.some((punct) => trimmedText.endsWith(punct));
+
+  if (trimmedText.length > 0 && !hasValidEnding) {
     errorMessages.push(
-      `Found incomplete content in ${source}: content does not end with proper punctuation (. or 。). Please return the complete content`,
+      `Found incomplete content in ${source}: content does not end with proper punctuation (${validEndingPunctuation.join(", ")}). Please return the complete content`,
     );
   }
 }

package/utils/utils.mjs

@@ -7,10 +7,11 @@ import {
   DEFAULT_EXCLUDE_PATTERNS,
   DEFAULT_INCLUDE_PATTERNS,
   DOCUMENT_STYLES,
-  TARGET_AUDIENCES,
-  READER_KNOWLEDGE_LEVELS,
   DOCUMENTATION_DEPTH,
+  SUPPORTED_FILE_EXTENSIONS,
+  READER_KNOWLEDGE_LEVELS,
   SUPPORTED_LANGUAGES,
+  TARGET_AUDIENCES,
 } from "./constants.mjs";
 
 /**
@@ -338,9 +339,140 @@ export async function loadConfigFromFile() {
 /**
  * Save value to config.yaml file
  * @param {string} key - The config key to save
- * @param {string} value - The value to save
+ * @param {string|Array} value - The value to save (can be string or array)
  * @param {string} [comment] - Optional comment to add above the key
  */
+/**
+ * Handle array value formatting and updating in YAML config
+ * @param {string} key - The configuration key
+ * @param {Array} value - The array value to save
+ * @param {string} comment - Optional comment
+ * @param {string} fileContent - Current file content
+ * @returns {string} Updated file content
+ */
+function handleArrayValueUpdate(key, value, comment, fileContent) {
+  // Format array value
+  const formattedValue =
+    value.length === 0 ? `${key}: []` : `${key}:\n${value.map((item) => `  - ${item}`).join("\n")}`;
+
+  const lines = fileContent.split("\n");
+
+  // Find the start line of the key
+  const keyStartIndex = lines.findIndex((line) => line.match(new RegExp(`^${key}:\\s*`)));
+
+  if (keyStartIndex !== -1) {
+    // Find the end of the array (next non-indented line or end of file)
+    let keyEndIndex = keyStartIndex;
+    for (let i = keyStartIndex + 1; i < lines.length; i++) {
+      const line = lines[i].trim();
+      // If line is empty, starts with comment, or doesn't start with "- ", it's not part of the array
+      if (line === "" || line.startsWith("#") || (!line.startsWith("- ") && !line.match(/^\w+:/))) {
+        if (!line.startsWith("- ")) {
+          keyEndIndex = i - 1;
+          break;
+        }
+      } else if (line.match(/^\w+:/)) {
+        // Found another key, stop here
+        keyEndIndex = i - 1;
+        break;
+      } else if (line.startsWith("- ")) {
+        keyEndIndex = i;
+      }
+    }
+
+    // If we reached the end of file
+    if (keyEndIndex === keyStartIndex) {
+      // Check if the value is on the same line
+      const keyLine = lines[keyStartIndex];
+      if (keyLine.includes("[") || !keyLine.endsWith(":")) {
+        keyEndIndex = keyStartIndex;
+      } else {
+        // Find the actual end of the array
+        for (let i = keyStartIndex + 1; i < lines.length; i++) {
+          const line = lines[i].trim();
+          if (line.startsWith("- ")) {
+            keyEndIndex = i;
+          } else if (line !== "" && !line.startsWith("#")) {
+            break;
+          }
+        }
+      }
+    }
+
+    // Replace the entire array section
+    const replacementLines = formattedValue.split("\n");
+    lines.splice(keyStartIndex, keyEndIndex - keyStartIndex + 1, ...replacementLines);
+
+    // Add comment if provided and not already present
+    if (comment && keyStartIndex > 0 && !lines[keyStartIndex - 1].trim().startsWith("# ")) {
+      lines.splice(keyStartIndex, 0, `# ${comment}`);
+    }
+
+    return lines.join("\n");
+  } else {
+    // Add new array to end of file
+    let updatedContent = fileContent;
+    if (updatedContent && !updatedContent.endsWith("\n")) {
+      updatedContent += "\n";
+    }
+
+    // Add comment if provided
+    if (comment) {
+      updatedContent += `# ${comment}\n`;
+    }
+
+    updatedContent += `${formattedValue}\n`;
+    return updatedContent;
+  }
+}
+
+/**
+ * Handle string value formatting and updating in YAML config
+ * @param {string} key - The configuration key
+ * @param {string} value - The string value to save
+ * @param {string} comment - Optional comment
+ * @param {string} fileContent - Current file content
+ * @returns {string} Updated file content
+ */
+function handleStringValueUpdate(key, value, comment, fileContent) {
+  const formattedValue = `${key}: "${value}"`;
+  const lines = fileContent.split("\n");
+
+  // Handle string values (original logic)
+  const keyRegex = new RegExp(`^${key}:\\s*.*$`);
+  const keyIndex = lines.findIndex((line) => keyRegex.test(line));
+
+  if (keyIndex !== -1) {
+    // Replace existing key line
+    lines[keyIndex] = formattedValue;
+
+    // Add comment if provided and not already present
+    if (comment) {
+      const hasCommentAbove = keyIndex > 0 && lines[keyIndex - 1].trim().startsWith("# ");
+      if (!hasCommentAbove) {
+        // Add comment above the key if it doesn't already have one
+        lines.splice(keyIndex, 0, `# ${comment}`);
+      }
+    }
+
+    return lines.join("\n");
+  } else {
+    // Add key to the end of file
+    let updatedContent = fileContent;
+    if (updatedContent && !updatedContent.endsWith("\n")) {
+      updatedContent += "\n";
+    }
+
+    // Add comment if provided
+    if (comment) {
+      updatedContent += `# ${comment}\n`;
+    }
+
+    updatedContent += `${formattedValue}\n`;
+    return updatedContent;
+  }
+}
+
 export async function saveValueToConfig(key, value, comment) {
   if (value === undefined) {
     return; // Skip if value is undefined
@@ -360,39 +492,15 @@ export async function saveValueToConfig(key, value, comment) {
       fileContent = await fs.readFile(configPath, "utf8");
     }
 
-    // Check if key already exists in the file
-    const lines = fileContent.split("\n");
-    const keyRegex = new RegExp(`^${key}:\\s*.*$`);
-    const newKeyLine = `${key}: "${value}"`;
-
-    const keyIndex = lines.findIndex((line) => keyRegex.test(line));
-
-    if (keyIndex !== -1) {
-      // Replace existing key line
-      lines[keyIndex] = newKeyLine;
-      fileContent = lines.join("\n");
-
-      // Add comment if provided and not already present
-      if (comment && keyIndex > 0 && !lines[keyIndex - 1].trim().startsWith("# ")) {
-        // Add comment above the key if it doesn't already have one
-        lines.splice(keyIndex, 0, `# ${comment}`);
-        fileContent = lines.join("\n");
-      }
+    // Use extracted helper functions for better maintainability
+    let updatedContent;
+    if (Array.isArray(value)) {
+      updatedContent = handleArrayValueUpdate(key, value, comment, fileContent);
     } else {
-      // Add key to the end of file
-      if (fileContent && !fileContent.endsWith("\n")) {
-        fileContent += "\n";
-      }
-
-      // Add comment if provided
-      if (comment) {
-        fileContent += `# ${comment}\n`;
-      }
-
-      fileContent += `${newKeyLine}\n`;
+      updatedContent = handleStringValueUpdate(key, value, comment, fileContent);
     }
 
-    await fs.writeFile(configPath, fileContent);
+    await fs.writeFile(configPath, updatedContent);
   } catch (error) {
     console.warn(`Failed to save ${key} to config.yaml:`, error.message);
   }
@@ -719,9 +827,21 @@ export function processConfigFields(config) {
   const allRulesContent = [];
 
   // Check if original rules field has content
-  const existingRules = config.rules?.trim();
-  if (existingRules) {
-    allRulesContent.push(existingRules);
+  if (config.rules) {
+    if (typeof config.rules === "string") {
+      const existingRules = config.rules.trim();
+      if (existingRules) {
+        allRulesContent.push(existingRules);
+      }
+    } else if (Array.isArray(config.rules)) {
+      // Handle array of rules - join them with newlines
+      const rulesText = config.rules
+        .filter((rule) => typeof rule === "string" && rule.trim())
+        .join("\n\n");
+      if (rulesText) {
+        allRulesContent.push(rulesText);
+      }
+    }
   }
 
   // Process document purpose (array)
@@ -798,6 +918,101 @@ export function processConfigFields(config) {
   return processed;
 }
 
+/**
+ * Recursively resolves file references in a configuration object.
+ *
+ * This function traverses the input object, array, or string recursively. Any string value that starts
+ * with '@' is treated as a file reference, and the file's content is loaded asynchronously. Supported
+ * file formats include .txt, .md, .json, .yaml, and .yml. For .json and .yaml/.yml files, the content
+ * is parsed into objects; for .txt and .md, the raw string is returned.
+ *
+ * If a file cannot be loaded (e.g., does not exist, is of unsupported type, or parsing fails), the
+ * original string value (with '@' prefix) is returned in place of the file content.
+ *
+ * The function processes nested arrays and objects recursively, returning a new structure with file
+ * contents loaded in place of references. The input object is not mutated.
+ *
+ * Examples of supported file reference formats:
+ *   - "@notes.txt"
+ *   - "@docs/readme.md"
+ *   - "@config/settings.json"
+ *   - "@data.yaml"
+ *
+ * @param {any} obj - The configuration object, array, or string to process.
+ * @param {string} basePath - Base path for resolving relative file paths (defaults to process.cwd()).
+ * @returns {Promise<any>} - The processed configuration with file content loaded in place of references.
+ */
+export async function resolveFileReferences(obj, basePath = process.cwd()) {
+  if (typeof obj === "string" && obj.startsWith("@")) {
+    return await loadFileContent(obj.slice(1), basePath);
+  }
+
+  if (Array.isArray(obj)) {
+    return Promise.all(obj.map((item) => resolveFileReferences(item, basePath)));
+  }
+
+  if (obj && typeof obj === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = await resolveFileReferences(value, basePath);
+    }
+    return result;
+  }
+
+  return obj;
+}
+
+/**
+ * Load content from a file path
+ * @param {string} filePath - The file path to load
+ * @param {string} basePath - Base path for resolving relative paths
+ * @returns {Promise<any>} - The loaded content or original path if loading fails
+ */
+async function loadFileContent(filePath, basePath) {
+  try {
+    // Resolve path - if absolute, use as is; if relative, resolve from basePath
+    const resolvedPath = path.isAbsolute(filePath) ? filePath : path.resolve(basePath, filePath);
+
+    // Check if file exists
+    if (!existsSync(resolvedPath)) {
+      return `@${filePath}`; // Return original value if file doesn't exist
+    }
+
+    // Check file extension
+    const ext = path.extname(resolvedPath).toLowerCase();
+
+    if (!SUPPORTED_FILE_EXTENSIONS.includes(ext)) {
+      return `@${filePath}`; // Return original value if unsupported file type
+    }
+
+    // Read file content
+    const content = await fs.readFile(resolvedPath, "utf-8");
+
+    // Parse JSON/YAML files
+    if (ext === ".json") {
+      try {
+        return JSON.parse(content);
+      } catch {
+        return content; // Return raw string if JSON parsing fails
+      }
+    }
+
+    if (ext === ".yaml" || ext === ".yml") {
+      try {
+        return parse(content);
+      } catch {
+        return content; // Return raw string if YAML parsing fails
+      }
+    }
+
+    // Return raw content for .txt and .md files
+    return content;
+  } catch {
+    // Return original value if any error occurs
+    return `@${filePath}`;
+  }
+}
+
 /**
  * Detect system language and map to supported language code
  * @returns {string} - Supported language code (defaults to 'en' if detection fails or unsupported)