@aigne/doc-smith 0.2.5 → 0.2.8

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.2.8](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.7...v0.2.8) (2025-08-13)
+
+
+### Miscellaneous Chores
+
+* release 0.2.8 ([da19bc0](https://github.com/AIGNE-io/aigne-doc-smith/commit/da19bc0b2c6c4e5fddaff84b4fa85c9d495b3ba0))
+
+## [0.2.7](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.6...v0.2.7) (2025-08-12)
+
+
+### Bug Fixes
+
+* polish detail check ([#21](https://github.com/AIGNE-io/aigne-doc-smith/issues/21)) ([0268732](https://github.com/AIGNE-io/aigne-doc-smith/commit/02687329c3507b73f9cbf1aa2ff1b87921452516))
+
+
+### Miscellaneous Chores
+
+* release 0.2.7 ([3b807fe](https://github.com/AIGNE-io/aigne-doc-smith/commit/3b807fed833a5160931747bce37aac00cf11d9ac))
+
+## [0.2.6](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.5...v0.2.6) (2025-08-12)
+
+
+### Miscellaneous Chores
+
+* release 0.2.6 ([c5b5ea5](https://github.com/AIGNE-io/aigne-doc-smith/commit/c5b5ea5c404d44f3b0d420f0b57e4ae64ae5d624))
+
 ## [0.2.5](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.4...v0.2.5) (2025-08-08)
 
 

package/README.md

@@ -206,6 +206,7 @@ aigne doc publish --appUrl https://your-discuss-kit-instance.com
 npx --no doc-smith run --entry-agent init
 npx --no doc-smith run --entry-agent generate
 npx --no doc-smith run --entry-agent update 
+npx --no doc-smith run --entry-agent retranslate 
 npx --no doc-smith run --entry-agent publish
 ```
 

package/agents/check-detail-result.mjs

@@ -1,11 +1,6 @@
-export default async function checkDetailResult({
-  structurePlan,
-  reviewContent,
-}) {
-  const linkRegex = /(?<!\!)\[([^\]]+)\]\(([^)]+)\)/g;
-  const tableSeparatorRegex = /^\s*\|\s*-+\s*\|\s*$/;
-  const codeBlockRegex = /^\s+```(?:\w+)?$/;
+import { checkMarkdown } from "../utils/markdown-checker.mjs";
 
+export default async function checkDetailResult({ structurePlan, reviewContent }) {
   let isApproved = true;
   const detailFeedback = [];
 
@@ -25,141 +20,20 @@ export default async function checkDetailResult({
     allowedLinks.add(flatPath);
   });
 
-  const checkLinks = (text, source) => {
-    let match;
-    while ((match = linkRegex.exec(text)) !== null) {
-      const link = match[2];
-      const trimLink = link.trim();
+  // Run comprehensive markdown validation with all checks
+  try {
+    const markdownErrors = await checkMarkdown(reviewContent, "result", {
+      allowedLinks,
+    });
 
-      // Only check links that processContent would process
-      // Exclude external links and mailto
-      if (/^(https?:\/\/|mailto:)/.test(trimLink)) continue;
-
-      // Preserve anchors
-      const [path, hash] = trimLink.split("#");
-
-      // Only process relative paths or paths starting with /
-      if (!path) continue;
-
-      // Check if this link is in the allowed links set
-      if (!allowedLinks.has(trimLink)) {
-        isApproved = false;
-        detailFeedback.push(
-          `Found a dead link in ${source}: [${match[1]}](${trimLink}), ensure the link exists in the structure plan path`
-        );
-      }
-    }
-  };
-
-  const performAllChecks = (text, source) => {
-    // Split text into lines once and perform all checks in a single pass
-    const lines = text.split("\n");
-
-    // State variables for different checks
-    let inCodeBlock = false;
-    let codeBlockIndentLevel = 0;
-    let codeBlockStartLine = 0;
-    let inMermaidBlock = false;
-    let mermaidStartLine = 0;
-
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      const lineNumber = i + 1;
-
-      // Check table separators
-      if (tableSeparatorRegex.test(line)) {
-        isApproved = false;
-        detailFeedback.push(
-          `Found an incorrect table separator in ${source} at line ${lineNumber}: ${line.trim()}`
-        );
-      }
-
-      // Check code block markers and indentation
-      if (codeBlockRegex.test(line)) {
-        if (!inCodeBlock) {
-          // Starting a new code block
-          inCodeBlock = true;
-          codeBlockStartLine = lineNumber;
-          // Calculate indentation level of the code block marker
-          const match = line.match(/^(\s*)(```)/);
-          codeBlockIndentLevel = match ? match[1].length : 0;
-        } else {
-          // Ending the code block
-          inCodeBlock = false;
-          codeBlockIndentLevel = 0;
-        }
-      } else if (inCodeBlock) {
-        // If we're inside a code block, check if content has proper indentation
-        const contentIndentLevel = line.match(/^(\s*)/)[1].length;
-
-        // If code block marker has indentation, content should have at least the same indentation
-        if (
-          codeBlockIndentLevel > 0 &&
-          contentIndentLevel < codeBlockIndentLevel
-        ) {
-          isApproved = false;
-          detailFeedback.push(
-            `Found code block with inconsistent indentation in ${source} at line ${codeBlockStartLine}: code block marker has ${codeBlockIndentLevel} spaces indentation but content at line ${lineNumber} has only ${contentIndentLevel} spaces indentation`
-          );
-          // Reset to avoid multiple errors for the same code block
-          inCodeBlock = false;
-          codeBlockIndentLevel = 0;
-        }
-      }
-
-      // Check mermaid block markers
-      if (/^\s*```mermaid\s*$/.test(line)) {
-        inMermaidBlock = true;
-        mermaidStartLine = lineNumber;
-      } else if (inMermaidBlock && /^\s*```\s*$/.test(line)) {
-        inMermaidBlock = false;
-      } else if (inMermaidBlock) {
-        // If we're inside a mermaid block, check for backticks in node labels
-        // Check for node definitions with backticks in labels
-        // Pattern: A["label with backticks"] or A{"label with backticks"}
-        const nodeLabelRegex =
-          /[A-Za-z0-9_]+\["([^"]*`[^"]*)"\]|[A-Za-z0-9_]+{"([^}]*`[^}]*)"}/g;
-        let match;
-
-        while ((match = nodeLabelRegex.exec(line)) !== null) {
-          const label = match[1] || match[2];
-          isApproved = false;
-          detailFeedback.push(
-            `Found backticks in Mermaid node label in ${source} at line ${lineNumber}: "${label}" - backticks in node labels cause rendering issues in Mermaid diagrams`
-          );
-        }
-
-        // Check for edge descriptions with numbered list format
-        // Pattern: -- "1. description" --> or similar variants
-        const edgeDescriptionRegex = /--\s*"([^"]*)"\s*-->/g;
-        let edgeMatch;
-
-        while ((edgeMatch = edgeDescriptionRegex.exec(line)) !== null) {
-          const description = edgeMatch[1];
-          // Check if description starts with number followed by period
-          if (/^\d+\.\s/.test(description)) {
-            isApproved = false;
-            detailFeedback.push(
-              `Unsupported markdown: list - Found numbered list format in Mermaid edge description in ${source} at line ${lineNumber}: "${description}" - numbered lists in edge descriptions are not supported`
-            );
-          }
-        }
-      }
-    }
-
-    // Check single line content (this needs to be done after the loop)
-    const newlineCount = (text.match(/\n/g) || []).length;
-    if (newlineCount === 0 && text.trim().length > 0) {
+    if (markdownErrors.length > 0) {
       isApproved = false;
-      detailFeedback.push(
-        `Found single line content in ${source}: content appears to be on only one line, check for missing line breaks`
-      );
+      detailFeedback.push(...markdownErrors);
     }
-  };
-
-  // Check content
-  checkLinks(reviewContent, "result");
-  performAllChecks(reviewContent, "result");
+  } catch (error) {
+    isApproved = false;
+    detailFeedback.push(`Found markdown validation error in result: ${error.message}`);
+  }
 
   return {
     isApproved,

package/agents/check-detail.mjs

@@ -2,8 +2,8 @@ import { access, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { TeamAgent } from "@aigne/core";
-import checkDetailResult from "./check-detail-result.mjs";
 import { hasSourceFilesChanged } from "../utils/utils.mjs";
+import checkDetailResult from "./check-detail-result.mjs";
 
 // Get current script directory
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -20,7 +20,7 @@ export default async function checkDetail(
     forceRegenerate,
     ...rest
   },
-  options
+  options,
 ) {
   // Check if the detail file already exists
   const flatName = path.replace(/^\//, "").replace(/\//g, "-");
@@ -41,11 +41,9 @@ export default async function checkDetail(
   let sourceIdsChanged = false;
   if (originalStructurePlan && sourceIds) {
     // Find the original node in the structure plan
-    const originalNode = originalStructurePlan.find(
-      (node) => node.path === path
-    );
+    const originalNode = originalStructurePlan.find((node) => node.path === path);
 
-    if (originalNode && originalNode.sourceIds) {
+    if (originalNode?.sourceIds) {
       const originalSourceIds = originalNode.sourceIds;
       const currentSourceIds = sourceIds;
 

package/agents/check-structure-plan.mjs

@@ -1,11 +1,14 @@
 import {
   getCurrentGitHead,
+  getProjectInfo,
   hasFileChangesBetweenCommits,
+  loadConfigFromFile,
+  saveValueToConfig,
 } from "../utils/utils.mjs";
 
 export default async function checkStructurePlan(
-  { originalStructurePlan, feedback, lastGitHead, forceRegenerate, ...rest },
-  options
+  { originalStructurePlan, feedback, lastGitHead, ...rest },
+  options,
 ) {
   // Check if we need to regenerate structure plan
   let shouldRegenerate = false;
@@ -20,10 +23,7 @@ export default async function checkStructurePlan(
       // Check if there are relevant file changes since last generation
       const currentGitHead = getCurrentGitHead();
       if (currentGitHead && currentGitHead !== lastGitHead) {
-        const hasChanges = hasFileChangesBetweenCommits(
-          lastGitHead,
-          currentGitHead
-        );
+        const hasChanges = hasFileChangesBetweenCommits(lastGitHead, currentGitHead);
         if (hasChanges) {
           shouldRegenerate = true;
         }
@@ -38,17 +38,13 @@ export default async function checkStructurePlan(
         1. 对于新增的内容，可以根据需要新增节点，或补充到原有节点展示
         2. 谨慎删除节点，除非节点关联 sourceIds 都被删除了
         3. 不能修改原有节点的 path
+        4. 根据最新的 Data Sources 按需要更新节点的 sourceIds，如没有大的变化，可以不更新。
       `;
     }
   }
 
   // If no regeneration needed, return original structure plan
-  if (
-    originalStructurePlan &&
-    !feedback &&
-    !shouldRegenerate &&
-    !forceRegenerate
-  ) {
+  if (originalStructurePlan && !feedback && !shouldRegenerate) {
     return {
       structurePlan: originalStructurePlan,
     };
@@ -62,9 +58,57 @@ export default async function checkStructurePlan(
     ...rest,
   });
 
+  let message = "";
+
+  // Check and save project information if user hasn't modified it
+  if (result.projectName || result.projectDesc) {
+    try {
+      const currentConfig = await loadConfigFromFile();
+      const projectInfo = await getProjectInfo();
+
+      // Check if user has modified project information
+      const userModifiedProjectName =
+        currentConfig?.projectName && currentConfig.projectName !== projectInfo.name;
+      const userModifiedProjectDesc =
+        currentConfig?.projectDesc && currentConfig.projectDesc !== projectInfo.description;
+
+      // If user hasn't modified project info and it's not from GitHub, save AI output
+      if (!userModifiedProjectName && !userModifiedProjectDesc) {
+        let hasUpdated = false;
+        // Don't update if the current info is from GitHub (meaningful repository info)
+        if (
+          result.projectName &&
+          result.projectName !== projectInfo.name &&
+          !projectInfo.fromGitHub
+        ) {
+          await saveValueToConfig("projectName", result.projectName);
+          message += `Project name: \`${result.projectName}\``;
+          hasUpdated = true;
+        }
+
+        if (
+          result.projectDesc &&
+          result.projectDesc !== projectInfo.description &&
+          !projectInfo.fromGitHub
+        ) {
+          await saveValueToConfig("projectDesc", result.projectDesc);
+          message += `\nProject description: \`${result.projectDesc}\``;
+          hasUpdated = true;
+        }
+
+        if (hasUpdated) {
+          message = `\n### Auto-updated Project Info to \`.aigne/doc-smith/config.yaml\`\n\n${message}\n\n`;
+        }
+      }
+    } catch (error) {
+      console.warn("Failed to check/save project information:", error.message);
+    }
+  }
+
   return {
     ...result,
     feedback: "", // clear feedback
+    projectInfoMessage: message,
     originalStructurePlan: originalStructurePlan
       ? originalStructurePlan
       : JSON.parse(JSON.stringify(result.structurePlan || [])),

package/agents/detail-generator-and-translate.yaml

@@ -15,9 +15,15 @@ skills:
     reflection:
       reviewer: ./check-detail-result.mjs
       is_approved: isApproved
-      max_iterations: 3
+      max_iterations: 5
       return_last_on_max_iterations: true
     task_title: Generate detail for '{{ title }}'
+  - type: transform
+    jsonata: |
+      $merge([
+        $,
+        { "feedback": "" }
+      ])
   - ./batch-translate.yaml
   - ./save-single-doc.mjs
 input_schema:

package/agents/detail-regenerator.yaml

@@ -27,7 +27,9 @@ skills:
       ])
   - ./find-item-by-path.mjs
   - ./format-structure-plan.mjs
-  - ./detail-generator-and-translate.yaml
+  - url: ./detail-generator-and-translate.yaml
+    default_input:
+      isShowMessage: true
 input_schema:
   type: object
   properties:

package/agents/docs-generator.yaml

@@ -30,7 +30,8 @@ skills:
                 'translates': [$map(translateLanguages, function($lang) { {"language": $lang} })]
               }
             ])
-          })
+          }),
+          "datasources": ""
         }
       ])
   - ./format-structure-plan.mjs

package/agents/find-item-by-path.mjs

@@ -1,11 +1,25 @@
-import { readdir } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 
+// Helper function to get action-specific text based on isTranslate flag
+function getActionText(isTranslate, baseText) {
+  const action = isTranslate ? "retranslate" : "update";
+  return baseText.replace("{action}", action);
+}
+
 export default async function findItemByPath(
-  { "doc-path": docPath, structurePlanResult, boardId, docsDir },
+  {
+    "doc-path": docPath,
+    structurePlanResult,
+    boardId,
+    docsDir,
+    isTranslate,
+    feedback,
+  },
   options
 ) {
   let foundItem = null;
+  let selectedFileContent = null;
 
   // If docPath is empty, let user select from available documents
   if (!docPath) {
@@ -22,15 +36,13 @@ export default async function findItemByPath(
       );
 
       if (mainLanguageFiles.length === 0) {
-        throw new Error(
-          "Please provide a doc-path parameter to specify which document to update"
-        );
+        throw new Error("No documents found in the docs directory");
       }
 
       // Let user select a file
       const selectedFile = await options.prompts.search({
-        message: "Select a document to update:",
-        source: async (input, { signal }) => {
+        message: getActionText(isTranslate, "Select a document to {action}:"),
+        source: async (input) => {
           if (!input || input.trim() === "") {
             return mainLanguageFiles.map((file) => ({
               name: file,
@@ -51,9 +63,19 @@ export default async function findItemByPath(
       });
 
       if (!selectedFile) {
-        throw new Error(
-          "Please provide a doc-path parameter to specify which document to update"
+        throw new Error("No document selected");
+      }
+
+      // Read the selected .md file content
+      try {
+        const selectedFilePath = join(docsDir, selectedFile);
+        selectedFileContent = await readFile(selectedFilePath, "utf-8");
+      } catch (readError) {
+        console.warn(
+          `⚠️  Could not read content from ${selectedFile}:`,
+          readError.message
         );
+        selectedFileContent = null;
       }
 
       // Convert filename back to path
@@ -71,15 +93,17 @@ export default async function findItemByPath(
         return itemFlattenedPath === flatName;
       });
       if (!foundItemByFile) {
-        throw new Error(
-          "Please provide a doc-path parameter to specify which document to update"
-        );
+        throw new Error("No document found");
       }
 
       docPath = foundItemByFile.path;
     } catch (error) {
+      console.error(error);
       throw new Error(
-        "Please provide a doc-path parameter to specify which document to update"
+        getActionText(
+          isTranslate,
+          "Please provide a doc-path parameter to specify which document to {action}"
+        )
       );
     }
   }
@@ -111,8 +135,33 @@ export default async function findItemByPath(
     );
   }
 
-  // Merge the found item with originalStructurePlan
-  return {
+  // Prompt for feedback if not provided
+  let userFeedback = feedback;
+  if (!userFeedback) {
+    const feedbackMessage = getActionText(
+      isTranslate,
+      "Please provide feedback for the {action} (press Enter to skip):"
+    );
+
+    userFeedback = await options.prompts.input({
+      message: feedbackMessage,
+    });
+  }
+
+  // Merge the found item with originalStructurePlan and add content if available
+  const result = {
     ...foundItem,
   };
+
+  // Add content if we read it from user selection
+  if (selectedFileContent !== null) {
+    result.content = selectedFileContent;
+  }
+
+  // Add feedback to result if provided
+  if (userFeedback?.trim()) {
+    result.feedback = userFeedback.trim();
+  }
+
+  return result;
 }

package/agents/input-generator.mjs

@@ -1,15 +1,19 @@
-import { writeFile, mkdir, readFile } from "node:fs/promises";
-import { join, dirname } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import chalk from "chalk";
-import { validatePath, getAvailablePaths } from "../utils/utils.mjs";
 import {
-  SUPPORTED_LANGUAGES,
   DOCUMENT_STYLES,
+  SUPPORTED_LANGUAGES,
   TARGET_AUDIENCES,
 } from "../utils/constants.mjs";
+import {
+  getAvailablePaths,
+  getProjectInfo,
+  validatePath,
+} from "../utils/utils.mjs";
 
 // UI constants
-const PRESS_ENTER_TO_FINISH = "Press Enter to finish";
+const _PRESS_ENTER_TO_FINISH = "Press Enter to finish";
 
 /**
  * Guide users through multi-turn dialogue to collect information and generate YAML configuration
@@ -129,7 +133,7 @@ export default async function init(
   while (true) {
     const selectedPath = await options.prompts.search({
       message: "Path:",
-      source: async (input, { signal }) => {
+      source: async (input) => {
         if (!input || input.trim() === "") {
           return [
             {
@@ -180,6 +184,12 @@ export default async function init(
   // If no paths entered, use default
   input.sourcesPath = sourcePaths.length > 0 ? sourcePaths : ["./"];
 
+  // Save project info to config
+  const projectInfo = await getProjectInfo();
+  input.projectName = projectInfo.name;
+  input.projectDesc = projectInfo.description;
+  input.projectLogo = projectInfo.icon;
+
   // Generate YAML content
   const yamlContent = generateYAML(input, outputPath);
 
@@ -193,13 +203,17 @@ export default async function init(
 
     await writeFile(filePath, yamlContent, "utf8");
     console.log(`\n🎉 Configuration saved to: ${chalk.cyan(filePath)}`);
+    // Print YAML content for user review
+    console.log(chalk.cyan("---"));
+    console.log(chalk.cyan(yamlContent));
+    console.log(chalk.cyan("---"));
     console.log(
-      "💡 You can edit the configuration file anytime to modify settings."
+      "💡 You can edit the configuration file anytime to modify settings.\n"
     );
     console.log(
       `🚀 Run ${chalk.cyan(
         "'aigne doc generate'"
-      )} to start documentation generation!`
+      )} to start documentation generation!\n`
     );
 
     return {};
@@ -215,15 +229,21 @@ export default async function init(
 /**
  * Generate YAML configuration content
  * @param {Object} input - Input object
- * @param {string} outputPath - Output path for directory configuration
  * @returns {string} YAML string
  */
-function generateYAML(input, outputPath) {
+function generateYAML(input) {
   let yaml = "";
 
+  // Add project information at the beginning
+  yaml += `# Project information for documentation publishing\n`;
+  yaml += `projectName: ${input.projectName || ""}\n`;
+  yaml += `projectDesc: ${input.projectDesc || ""}\n`;
+  yaml += `projectLogo: ${input.projectLogo || ""}\n`;
+  yaml += `\n`;
+
   // Add rules (required field)
   yaml += `rules: |\n`;
-  if (input.rules && input.rules.trim()) {
+  if (input.rules?.trim()) {
     yaml += `  ${input.rules.split("\n").join("\n  ")}\n\n`;
   } else {
     yaml += `  \n\n`;