@aigne/doc-smith 0.9.8-alpha.3 → 0.9.8-alpha.4

package/agents/update/check-document.mjs

@@ -1,162 +0,0 @@
-import { access, readFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { TeamAgent } from "@aigne/core";
-import fs from "fs-extra";
-import pMap from "p-map";
-
-import { getFileName } from "../../utils/utils.mjs";
-import checkDetailResult from "../utils/check-detail-result.mjs";
-
-// Get current script directory
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-export default async function checkDocument(
-  {
-    path,
-    docsDir,
-    sourceIds,
-    originalDocumentStructure,
-    documentStructure,
-    modifiedFiles,
-    forceRegenerate,
-    locale,
-    translates = [],
-    ...rest
-  },
-  options,
-) {
-  // Check if the detail file already exists
-  const fileFullName = getFileName(path, locale);
-  const filePath = join(docsDir, fileFullName);
-  let detailGenerated = true;
-  let fileContent = null;
-  try {
-    await access(filePath);
-    // If file exists, read its content for validation
-    fileContent = await readFile(filePath, "utf8");
-  } catch {
-    detailGenerated = false;
-  }
-
-  // Check if sourceIds have changed by comparing with original documentation structure
-  let sourceIdsChanged = false;
-  if (originalDocumentStructure && sourceIds) {
-    // Find the original node in the documentation structure
-    const originalNode = originalDocumentStructure.find((node) => node.path === path);
-
-    if (originalNode?.sourceIds) {
-      const originalSourceIds = originalNode.sourceIds;
-      const currentSourceIds = sourceIds;
-
-      // Compare arrays (order doesn't matter, but content does)
-      if (originalSourceIds.length !== currentSourceIds.length) {
-        sourceIdsChanged = true;
-      } else {
-        // Check if any sourceId is different
-        const originalSet = new Set(originalSourceIds);
-        const currentSet = new Set(currentSourceIds);
-
-        if (originalSet.size !== currentSet.size) {
-          sourceIdsChanged = true;
-        } else {
-          // Check if any element is different
-          for (const sourceId of originalSourceIds) {
-            if (!currentSet.has(sourceId)) {
-              sourceIdsChanged = true;
-              break;
-            }
-          }
-        }
-      }
-    }
-  }
-
-  // If file exists, check content validation
-  let contentValidationFailed = false;
-  let validationResult = {};
-  if (detailGenerated && fileContent && documentStructure) {
-    validationResult = await checkDetailResult({
-      documentStructure,
-      reviewContent: fileContent,
-      docsDir,
-    });
-
-    if (!validationResult.isApproved) {
-      contentValidationFailed = true;
-    }
-  }
-  const translateList = Array.isArray(translates) ? translates : [];
-  const languages = translateList.map((x) => x.language);
-  const lackLanguages = new Set(languages);
-  const skills = [];
-
-  // If file exists, sourceIds haven't changed, source files haven't changed, and content validation passes, no need to regenerate
-  if (detailGenerated && !sourceIdsChanged && !contentValidationFailed && !forceRegenerate) {
-    await pMap(
-      languages,
-      async (x) => {
-        const languageFileName = getFileName(path, x);
-        const languageFilePath = join(docsDir, languageFileName);
-        if (await fs.exists(languageFilePath)) {
-          lackLanguages.delete(x);
-        }
-      },
-      { concurrency: 5 },
-    );
-    if (lackLanguages.size === 0) {
-      return {
-        path,
-        docsDir,
-        ...rest,
-        detailGenerated: true,
-      };
-    }
-    // translations during generation don't need feedback, content is satisfactory
-    rest.content = fileContent;
-  } else {
-    skills.push(options.context.agents["handleDocumentUpdate"]);
-  }
-
-  skills.push(options.context.agents["translateMultilingual"]);
-
-  const teamAgent = TeamAgent.from({
-    name: "generateDocument",
-    skills,
-  });
-  let openAPISpec = null;
-
-  if (options.context?.userContext?.openAPISpec?.sourceId) {
-    const matchingDocument = originalDocumentStructure.find((item) => {
-      if (item.path === path) {
-        return item.sourceIds.find((x) => x === options.context.userContext.openAPISpec.sourceId);
-      }
-      return false;
-    });
-    if (matchingDocument) {
-      openAPISpec = options.context.userContext.openAPISpec;
-    }
-  }
-
-  const result = await options.context.invoke(teamAgent, {
-    ...rest,
-    translates: translateList.filter((x) => lackLanguages.has(x.language)),
-    locale,
-    docsDir,
-    path,
-    sourceIds,
-    originalDocumentStructure,
-    documentStructure,
-    detailFeedback: contentValidationFailed ? validationResult.detailFeedback : "",
-    openAPISpec,
-  });
-
-  return {
-    path,
-    docsDir,
-    ...rest,
-    result,
-  };
-}
-
-checkDocument.taskTitle = "Check if '{{ title }}' needs generate or update";

package/agents/update/check-generate-diagram.mjs

@@ -1,106 +0,0 @@
-import { hasDiagramContent } from "../../utils/check-document-has-diagram.mjs";
-
-const DEFAULT_DIAGRAMMING_EFFORT = 5;
-const MIN_DIAGRAMMING_EFFORT = 0;
-const MAX_DIAGRAMMING_EFFORT = 10;
-
-export default async function checkGenerateDiagram(
-  {
-    documentContent,
-    locale,
-    feedback,
-    detailFeedback,
-    originalContent,
-    diagramming,
-    path,
-    docsDir,
-    shouldUpdateDiagrams,
-  },
-  options,
-) {
-  let content = documentContent;
-  let skipGenerateDiagram = false;
-
-  // If --diagram flag is set and document already has d2 code blocks,
-  // skip preCheck and directly replace existing diagrams
-  // This is because when using --diagram/--diagram-all, the user explicitly wants to update diagrams,
-  // so we should skip the "do we need to generate diagram" check and directly proceed to replacement
-  const hasExistingDiagrams = originalContent && hasDiagramContent(originalContent);
-
-  // Skip preCheck if:
-  // 1. Using --diagram/--diagram-all flag (shouldUpdateDiagrams === true) AND
-  // 2. Document already has d2 code blocks (hasExistingDiagrams === true)
-  // This means user explicitly wants to update existing diagrams, no need to check if diagram is needed
-  const shouldSkipPreCheck = shouldUpdateDiagrams === true && hasExistingDiagrams;
-
-  let preCheckResult = { details: [], content: null };
-  if (!shouldSkipPreCheck) {
-    const preCheckAgent = options.context?.agents?.["preCheckGenerateDiagram"];
-
-    preCheckResult = await options.context.invoke(preCheckAgent, {
-      documentContent,
-      feedback,
-      detailFeedback,
-      previousGenerationContent: originalContent,
-    });
-  }
-
-  const totalScore = (preCheckResult.details || []).reduce((acc, curr) => acc + curr.score, 0);
-  if (![false, "false", "", undefined, null].includes(preCheckResult.content)) {
-    content = preCheckResult.content;
-  }
-
-  let diagrammingEffort = diagramming?.effort
-    ? Number(diagramming?.effort)
-    : DEFAULT_DIAGRAMMING_EFFORT;
-
-  if (Number.isNaN(diagrammingEffort)) {
-    diagrammingEffort = DEFAULT_DIAGRAMMING_EFFORT;
-  } else {
-    diagrammingEffort = Math.min(
-      Math.max(MIN_DIAGRAMMING_EFFORT, diagrammingEffort),
-      MAX_DIAGRAMMING_EFFORT,
-    );
-  }
-
-  // If we skipped preCheck because document has existing diagrams and --diagram flag is set,
-  // we should NOT skip generating diagram (we need to replace existing ones)
-  if (shouldSkipPreCheck) {
-    skipGenerateDiagram = false;
-  } else if (totalScore <= diagrammingEffort) {
-    skipGenerateDiagram = true;
-  }
-
-  if (skipGenerateDiagram) {
-    content = documentContent;
-  } else {
-    try {
-      const generateAgent = options.context?.agents?.["generateDiagram"];
-      const result = await options.context.invoke(generateAgent, {
-        documentContent: content,
-        locale,
-        diagramming: diagramming || {},
-        feedback: feedback || "",
-        originalContent: originalContent || documentContent,
-        path,
-        docsDir,
-      });
-
-      // generateDiagram now returns { content } with image already inserted
-      // The image replaces DIAGRAM_PLACEHOLDER or D2 code blocks
-      if (result?.content) {
-        content = result.content;
-      } else {
-        // Fallback: if no content returned, use original document content
-        content = documentContent;
-      }
-    } catch (error) {
-      skipGenerateDiagram = true;
-      console.log(`⚠️  Skip generate any diagram: ${error.message}`);
-      // On error, return original document content
-      content = documentContent;
-    }
-  }
-
-  return { content };
-}

package/agents/update/check-sync-image-flag.mjs

@@ -1,55 +0,0 @@
-/**
- * Check if --diagram-sync flag is set via command line arguments or environment variable
- * Returns the flag value and passes through all input
- *
- * --diagram-sync: Auto-select all documents with banana images and sync to translations
- */
-export default function checkSyncImageFlag(input) {
-  let shouldSyncImages = false;
-
-  // Check command line arguments first (highest priority)
-  if (process.argv) {
-    const hasSyncImageFlag = process.argv.some((arg) => arg === "--diagram-sync" || arg === "-ds");
-    if (hasSyncImageFlag) {
-      shouldSyncImages = true;
-    }
-  }
-
-  // Check input parameter
-  if (input["diagram-sync"] === true || input.diagramSync === true) {
-    shouldSyncImages = true;
-  }
-
-  // Check environment variable
-  if (process.env.DOC_SMITH_SYNC_IMAGES === "true" || process.env.DOC_SMITH_SYNC_IMAGES === "1") {
-    shouldSyncImages = true;
-  }
-
-  // Return all input plus the flag
-  return {
-    ...input,
-    shouldSyncImages,
-  };
-}
-
-checkSyncImageFlag.input_schema = {
-  type: "object",
-  properties: {
-    "diagram-sync": {
-      type: ["boolean", "string"],
-      description:
-        "Flag to sync images to translations (can also use --diagram-sync CLI arg or DOC_SMITH_SYNC_IMAGES env var)",
-    },
-  },
-};
-
-checkSyncImageFlag.output_schema = {
-  type: "object",
-  properties: {
-    shouldSyncImages: {
-      type: "boolean",
-      description: "Whether to sync images to translations",
-    },
-  },
-  required: ["shouldSyncImages"],
-};

package/agents/update/check-update-is-single.mjs

@@ -1,53 +0,0 @@
-export default async function checkUpdateIsSingle({ selectedDocs, ...rest }, options) {
-  if (!selectedDocs || !Array.isArray(selectedDocs)) {
-    throw new Error("A list of documents to update must be provided.");
-  }
-
-  if (selectedDocs.length === 0) {
-    throw new Error("You must select at least one document to update.");
-  }
-
-  let targetAgent;
-  let agentName;
-
-  if (selectedDocs.length === 1 && !rest.reset) {
-    // Single doc update without reset
-    agentName = "updateSingleDocument";
-    targetAgent = options.context.agents["updateSingleDocument"];
-  } else {
-    agentName = "batchUpdateDocument";
-    targetAgent = options.context.agents["batchUpdateDocument"];
-  }
-
-  if (!targetAgent) {
-    throw new Error(`Sorry, I can't seem to find the "${agentName}" agent.`);
-  }
-
-  try {
-    const result = await options.context.invoke(targetAgent, {
-      selectedDocs,
-      ...rest,
-    });
-
-    // For batch updates, preserve selectedDocs and other context for save-and-translate-document
-    // batchUpdateDocument returns an array of results, but save-and-translate-document needs selectedDocs
-    if (agentName === "batchUpdateDocument") {
-      return {
-        ...rest,
-        selectedDocs, // Preserve selectedDocs for save-and-translate-document.mjs
-        result, // Include the batch update results
-      };
-    }
-
-    // For single document updates, return result as-is
-    return result;
-  } catch (error) {
-    console.error(
-      `Sorry, I encountered an error while trying to run the ${agentName} agent:`,
-      error.message,
-    );
-    throw error;
-  }
-}
-
-checkUpdateIsSingle.taskTitle = "Check document count and route to appropriate update agent";

package/agents/update/document-tools/update-document-content.mjs

@@ -1,303 +0,0 @@
-import { applyPatch } from "diff";
-import {
-  getUpdateDocumentContentInputJsonSchema,
-  getUpdateDocumentContentOutputJsonSchema,
-  validateUpdateDocumentContentInput,
-} from "../../../types/document-schema.mjs";
-import { userContextAt } from "../../../utils/utils.mjs";
-
-export default async function updateDocumentContent(input, options) {
-  // Validate input using Zod schema
-  const validation = validateUpdateDocumentContentInput(input);
-  if (!validation.success) {
-    return {
-      success: false,
-      error: { message: validation.error },
-    };
-  }
-
-  const { diffPatch, path } = validation.data;
-
-  // Get originalContent from shared context using path, fallback to input
-  const contentContext = userContextAt(options, `currentContents.${path}`);
-  let originalContent = contentContext.get();
-
-  if (!originalContent) {
-    originalContent = input.originalContent;
-  }
-
-  try {
-    // Parse and validate diff patch
-    const parsedDiff = parseDiffPatch(diffPatch);
-    if (!parsedDiff.success) {
-      return {
-        success: false,
-        error: { message: parsedDiff.error },
-      };
-    }
-
-    // Check and fix line number issues
-    const fixedDiff = fixLineNumberIssues(originalContent, parsedDiff.hunks);
-    if (!fixedDiff.success) {
-      return {
-        success: false,
-        error: { message: fixedDiff.error },
-      };
-    }
-
-    // Reconstruct the fixed diff patch
-    const fixedPatch = reconstructDiffPatch(fixedDiff.hunks);
-
-    // Apply the diff patch using the diff library
-    const result = applyPatch(originalContent, fixedPatch);
-
-    if (result === false) {
-      return {
-        success: false,
-        error: { message: "Failed to apply patch" },
-      };
-    }
-
-    // Update shared context with new content using path
-    contentContext.set(result);
-
-    return {
-      success: true,
-      updatedContent: `<page_content>
-${result}
-</page_content>`,
-      message:
-        "Document content updated successfully.\nCheck if updatedContent meets user feedback, if so, just return 'success'.",
-    };
-  } catch (error) {
-    return {
-      success: false,
-      error: { message: error.message },
-    };
-  }
-}
-
-function parseDiffPatch(diffPatch) {
-  try {
-    const hunks = [];
-    const lines = diffPatch.split("\n");
-    let currentHunk = null;
-
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-
-      // Parse hunk header: @@ -oldStart,oldCount +newStart,newCount @@
-      const hunkMatch = line.match(/^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@/);
-      if (hunkMatch) {
-        if (currentHunk) {
-          hunks.push(currentHunk);
-        }
-        currentHunk = {
-          oldStart: parseInt(hunkMatch[1], 10),
-          oldCount: parseInt(hunkMatch[2], 10) || 1,
-          newStart: parseInt(hunkMatch[3], 10),
-          newCount: parseInt(hunkMatch[4], 10) || 1,
-          changes: [],
-        };
-        continue;
-      }
-
-      // Parse changes
-      if (currentHunk && line.length > 0) {
-        const changeType = line[0];
-        const content = line.slice(1);
-
-        if (changeType === "-") {
-          currentHunk.changes.push({ type: "remove", content });
-        } else if (changeType === "+") {
-          currentHunk.changes.push({ type: "add", content });
-        } else if (changeType === " ") {
-          currentHunk.changes.push({ type: "context", content });
-        }
-      }
-    }
-
-    if (currentHunk) {
-      hunks.push(currentHunk);
-    }
-
-    if (hunks.length === 0) {
-      return { success: false, error: "No valid hunks found in diff" };
-    }
-
-    return { success: true, hunks };
-  } catch (error) {
-    return { success: false, error: `Failed to parse diff: ${error.message}` };
-  }
-}
-
-function fixLineNumberIssues(originalContent, hunks) {
-  try {
-    const originalLines = originalContent.split("\n");
-    const fixedHunks = [];
-
-    for (const hunk of hunks) {
-      // Extract context and removed lines to find best match
-      const contextAndRemoved = hunk.changes
-        .filter((change) => change.type === "context" || change.type === "remove")
-        .map((change) => change.content);
-
-      if (contextAndRemoved.length === 0) {
-        // No context to match against, keep original
-        fixedHunks.push(hunk);
-        continue;
-      }
-
-      // Find best matching position in original content
-      const bestMatch = findBestMatch(originalLines, contextAndRemoved, hunk.oldStart - 1);
-
-      if (bestMatch.found) {
-        const fixedHunk = {
-          ...hunk,
-          oldStart: bestMatch.position + 1,
-          newStart: bestMatch.position + 1,
-          // Fix line counts based on actual changes
-          oldCount: calculateOldCount(hunk.changes),
-          newCount: calculateNewCount(hunk.changes),
-        };
-        fixedHunks.push(fixedHunk);
-      } else {
-        // Try fuzzy matching
-        const fuzzyMatch = findFuzzyMatch(originalLines, contextAndRemoved);
-        if (fuzzyMatch.found) {
-          const fixedHunk = {
-            ...hunk,
-            oldStart: fuzzyMatch.position + 1,
-            newStart: fuzzyMatch.position + 1,
-            // Fix line counts based on actual changes
-            oldCount: calculateOldCount(hunk.changes),
-            newCount: calculateNewCount(hunk.changes),
-          };
-          fixedHunks.push(fixedHunk);
-        } else {
-          return {
-            success: false,
-            error: `Cannot find matching context for hunk at line ${hunk.oldStart}`,
-          };
-        }
-      }
-    }
-
-    return { success: true, hunks: fixedHunks };
-  } catch (error) {
-    return { success: false, error: `Failed to fix line numbers: ${error.message}` };
-  }
-}
-
-function findBestMatch(originalLines, targetLines, startPosition) {
-  // Try exact match at expected position first
-  if (startPosition >= 0 && startPosition + targetLines.length <= originalLines.length) {
-    let matches = 0;
-    for (let i = 0; i < targetLines.length; i++) {
-      if (originalLines[startPosition + i] === targetLines[i]) {
-        matches++;
-      }
-    }
-
-    if (matches === targetLines.length) {
-      return { found: true, position: startPosition };
-    }
-  }
-
-  // Try nearby positions (within 10 lines)
-  const NEARBY_SEARCH_RANGE = 10; // Maximum number of lines to search before/after expected position
-  for (let offset = 1; offset <= NEARBY_SEARCH_RANGE; offset++) {
-    // Try before
-    const beforePos = startPosition - offset;
-    if (beforePos >= 0 && beforePos + targetLines.length <= originalLines.length) {
-      let matches = 0;
-      for (let i = 0; i < targetLines.length; i++) {
-        if (originalLines[beforePos + i] === targetLines[i]) {
-          matches++;
-        }
-      }
-      if (matches === targetLines.length) {
-        return { found: true, position: beforePos };
-      }
-    }
-
-    // Try after
-    const afterPos = startPosition + offset;
-    if (afterPos >= 0 && afterPos + targetLines.length <= originalLines.length) {
-      let matches = 0;
-      for (let i = 0; i < targetLines.length; i++) {
-        if (originalLines[afterPos + i] === targetLines[i]) {
-          matches++;
-        }
-      }
-      if (matches === targetLines.length) {
-        return { found: true, position: afterPos };
-      }
-    }
-  }
-
-  return { found: false };
-}
-
-function findFuzzyMatch(originalLines, targetLines) {
-  // Find the best partial match
-  let bestMatch = { found: false, position: 0, score: 0 };
-
-  for (let pos = 0; pos <= originalLines.length - targetLines.length; pos++) {
-    let matches = 0;
-    for (let i = 0; i < targetLines.length; i++) {
-      if (originalLines[pos + i] === targetLines[i]) {
-        matches++;
-      }
-    }
-
-    const score = matches / targetLines.length;
-    const FUZZY_MATCH_THRESHOLD = 0.7; // 70% similarity threshold for fuzzy matching
-    if (score > bestMatch.score && score >= FUZZY_MATCH_THRESHOLD) {
-      bestMatch = { found: true, position: pos, score };
-    }
-  }
-
-  return bestMatch;
-}
-
-function calculateOldCount(changes) {
-  const contextCount = changes.filter((c) => c.type === "context").length;
-  const removeCount = changes.filter((c) => c.type === "remove").length;
-  return contextCount + removeCount;
-}
-
-function calculateNewCount(changes) {
-  const contextCount = changes.filter((c) => c.type === "context").length;
-  const addCount = changes.filter((c) => c.type === "add").length;
-  return contextCount + addCount;
-}
-
-function reconstructDiffPatch(hunks) {
-  let patchContent = "";
-
-  for (const hunk of hunks) {
-    // Add hunk header
-    const oldRange = hunk.oldCount === 1 ? hunk.oldStart : `${hunk.oldStart},${hunk.oldCount}`;
-    const newRange = hunk.newCount === 1 ? hunk.newStart : `${hunk.newStart},${hunk.newCount}`;
-    patchContent += `@@ -${oldRange} +${newRange} @@\n`;
-
-    // Add changes
-    for (const change of hunk.changes) {
-      if (change.type === "context") {
-        patchContent += ` ${change.content}\n`;
-      } else if (change.type === "remove") {
-        patchContent += `-${change.content}\n`;
-      } else if (change.type === "add") {
-        patchContent += `+${change.content}\n`;
-      }
-    }
-  }
-
-  return patchContent;
-}
-
-updateDocumentContent.inputSchema = getUpdateDocumentContentInputJsonSchema();
-updateDocumentContent.outputSchema = getUpdateDocumentContentOutputJsonSchema();
-
-updateDocumentContent.description = "Apply diff patch to update markdown document content";