@aigne/doc-smith 0.8.12-beta → 0.8.12-beta.2

package/tests/agents/update/save-and-translate-document.test.mjs

@@ -0,0 +1,369 @@
+import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from "bun:test";
+import saveAndTranslateDocument from "../../../agents/update/save-and-translate-document.mjs";
+import * as historyUtils from "../../../utils/history-utils.mjs";
+
+describe("save-and-translate-document", () => {
+  let mockOptions;
+  let consoleErrorSpy;
+  let recordUpdateSpy;
+
+  beforeEach(() => {
+    // Reset all mocks
+    mock.restore();
+
+    mockOptions = {
+      prompts: {
+        select: mock(async () => "no"),
+      },
+      context: {
+        agents: {
+          saveSingleDoc: { mockSaveAgent: true },
+          translateMultilingual: { mockTranslateAgent: true },
+        },
+        invoke: mock(async () => ({ mockResult: true })),
+      },
+    };
+
+    consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+    recordUpdateSpy = spyOn(historyUtils, "recordUpdate").mockImplementation(() => {});
+
+    // Clear context mock call history
+    mockOptions.prompts.select.mockClear();
+    mockOptions.context.invoke.mockClear();
+  });
+
+  afterEach(() => {
+    consoleErrorSpy?.mockRestore();
+    recordUpdateSpy?.mockRestore();
+  });
+
+  // INPUT VALIDATION TESTS
+  test("should handle empty or invalid selectedDocs", async () => {
+    const testCases = [
+      { selectedDocs: [], description: "empty array" },
+      { selectedDocs: null, description: "null" },
+      { selectedDocs: undefined, description: "undefined" },
+      { selectedDocs: "not-array", description: "non-array" },
+    ];
+
+    for (const testCase of testCases) {
+      const input = {
+        selectedDocs: testCase.selectedDocs,
+        docsDir: "./docs",
+        translateLanguages: ["en", "zh"],
+        locale: "en",
+      };
+
+      const result = await saveAndTranslateDocument(input, mockOptions);
+
+      expect(result).toEqual({});
+      expect(mockOptions.context.invoke).not.toHaveBeenCalled();
+      expect(mockOptions.prompts.select).not.toHaveBeenCalled();
+    }
+  });
+
+  // SCENARIO 1: NO TRANSLATION CONFIGURATION
+  test("should skip translation when no translation languages configured", async () => {
+    const testCases = [
+      { translateLanguages: null, description: "null" },
+      { translateLanguages: undefined, description: "undefined" },
+      { translateLanguages: [], description: "empty array" },
+      { translateLanguages: ["en"], description: "only current locale" },
+    ];
+
+    for (const testCase of testCases) {
+      const input = {
+        selectedDocs: [
+          {
+            path: "/docs/test.md",
+            content: "# Test Document",
+            translates: {},
+            labels: {},
+            feedback: "Good content",
+          },
+        ],
+        docsDir: "./docs",
+        translateLanguages: testCase.translateLanguages,
+        locale: "en",
+      };
+
+      const result = await saveAndTranslateDocument(input, mockOptions);
+
+      expect(result).toEqual({});
+      expect(mockOptions.prompts.select).not.toHaveBeenCalled();
+      expect(mockOptions.context.invoke).toHaveBeenCalledTimes(1);
+      expect(recordUpdateSpy).toHaveBeenCalledWith({
+        operation: "document_update",
+        feedback: "Good content",
+        documentPath: "/docs/test.md",
+      });
+
+      // Reset mocks for next iteration
+      mockOptions.prompts.select.mockClear();
+      mockOptions.context.invoke.mockClear();
+      recordUpdateSpy.mockClear();
+    }
+  });
+
+  // SCENARIO 2: USER CHOOSES NOT TO TRANSLATE
+  test("should save documents and skip translation when user chooses no", async () => {
+    const input = {
+      selectedDocs: [
+        {
+          path: "/docs/test1.md",
+          content: "# Test Document 1",
+          translates: {},
+          labels: {},
+          feedback: "Update needed",
+        },
+        {
+          path: "/docs/test2.md",
+          content: "# Test Document 2",
+          translates: {},
+          labels: {},
+          feedback: "Second feedback",
+        },
+        {
+          path: "/docs/test3.md",
+          content: "# Test Document 3",
+          translates: {},
+          labels: {},
+          feedback: "   ", // Whitespace only
+        },
+      ],
+      docsDir: "./docs",
+      translateLanguages: ["en", "zh", "ja"],
+      locale: "en",
+    };
+
+    mockOptions.prompts.select.mockResolvedValue("no");
+
+    const result = await saveAndTranslateDocument(input, mockOptions);
+
+    expect(result).toEqual({});
+    expect(mockOptions.prompts.select).toHaveBeenCalledWith({
+      message: "Document update completed. Would you like to translate these documents now?",
+      choices: [
+        {
+          name: "Review documents first, translate later",
+          value: "no",
+        },
+        {
+          name: "Translate now",
+          value: "yes",
+        },
+      ],
+    });
+    expect(mockOptions.context.invoke).toHaveBeenCalledTimes(3); // Only saveDocument calls
+    expect(recordUpdateSpy).toHaveBeenCalledTimes(2); // Only documents with non-empty feedback
+    expect(recordUpdateSpy).toHaveBeenCalledWith({
+      operation: "document_update",
+      feedback: "Update needed",
+      documentPath: "/docs/test1.md",
+    });
+    expect(recordUpdateSpy).toHaveBeenCalledWith({
+      operation: "document_update",
+      feedback: "Second feedback",
+      documentPath: "/docs/test2.md",
+    });
+  });
+
+  // SCENARIO 3: USER CHOOSES TO TRANSLATE
+  test("should save and translate documents when user chooses yes", async () => {
+    const input = {
+      selectedDocs: [
+        {
+          path: "/docs/test1.md",
+          content: "# Test Document 1",
+          translates: {},
+          labels: {},
+          feedback: "Translation needed",
+          title: "Test Document 1",
+        },
+        {
+          path: "/docs/test2.md",
+          content: "# Test Document 2",
+          translates: {},
+          labels: {},
+          title: "Test Document 2",
+        },
+      ],
+      docsDir: "./docs",
+      translateLanguages: ["en", "zh"],
+      locale: "en",
+    };
+
+    mockOptions.prompts.select.mockResolvedValue("yes");
+    mockOptions.context.invoke
+      .mockResolvedValueOnce({ mockSaveResult: true }) // saveDocument 1
+      .mockResolvedValueOnce({ mockSaveResult: true }) // saveDocument 2
+      .mockResolvedValueOnce({ translates: { zh: "# 测试文档 1" } }) // translateMultilingual 1
+      .mockResolvedValueOnce({ translates: { zh: "# 测试文档 2" } }) // translateMultilingual 2
+      .mockResolvedValueOnce({ mockSaveResult: true }) // saveDocument with translation 1
+      .mockResolvedValueOnce({ mockSaveResult: true }); // saveDocument with translation 2
+
+    const result = await saveAndTranslateDocument(input, mockOptions);
+
+    expect(result).toEqual({});
+    expect(mockOptions.prompts.select).toHaveBeenCalledWith({
+      message: "Document update completed. Would you like to translate these documents now?",
+      choices: [
+        {
+          name: "Review documents first, translate later",
+          value: "no",
+        },
+        {
+          name: "Translate now",
+          value: "yes",
+        },
+      ],
+    });
+    expect(mockOptions.context.invoke).toHaveBeenCalledTimes(6);
+
+    // Verify feedback is cleared before translation
+    expect(input.selectedDocs[0].feedback).toBe("");
+    expect(input.selectedDocs[1].feedback).toBe("");
+
+    expect(recordUpdateSpy).toHaveBeenCalledWith({
+      operation: "document_update",
+      feedback: "Translation needed",
+      documentPath: "/docs/test1.md",
+    });
+  });
+
+  // ERROR HANDLING TESTS
+  test("should handle errors gracefully", async () => {
+    // Test saveDocument error
+    const saveErrorInput = {
+      selectedDocs: [
+        {
+          path: "/docs/test1.md",
+          content: "# Test Document 1",
+          translates: {},
+          labels: {},
+          feedback: "Error test",
+        },
+      ],
+      docsDir: "./docs",
+      translateLanguages: ["en", "zh"],
+      locale: "en",
+    };
+
+    mockOptions.prompts.select.mockResolvedValue("no");
+    mockOptions.context.invoke.mockRejectedValue(new Error("Save failed"));
+
+    const saveErrorResult = await saveAndTranslateDocument(saveErrorInput, mockOptions);
+
+    expect(saveErrorResult).toEqual({});
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      "❌ Failed to save document /docs/test1.md:",
+      "Save failed",
+    );
+    expect(recordUpdateSpy).not.toHaveBeenCalled(); // Should not record if save failed
+
+    // Reset mocks
+    mockOptions.prompts.select.mockClear();
+    mockOptions.context.invoke.mockClear();
+    consoleErrorSpy.mockClear();
+    recordUpdateSpy.mockClear();
+
+    // Test translateMultilingual error
+    const translateErrorInput = {
+      selectedDocs: [
+        {
+          path: "/docs/test2.md",
+          content: "# Test Document 2",
+          translates: {},
+          labels: {},
+          title: "Test Document 2",
+        },
+      ],
+      docsDir: "./docs",
+      translateLanguages: ["en", "zh"],
+      locale: "en",
+    };
+
+    mockOptions.prompts.select.mockResolvedValue("yes");
+    mockOptions.context.invoke
+      .mockResolvedValueOnce({ mockSaveResult: true }) // saveDocument succeeds
+      .mockRejectedValueOnce(new Error("Translation failed")); // translateMultilingual fails
+
+    const translateErrorResult = await saveAndTranslateDocument(translateErrorInput, mockOptions);
+
+    expect(translateErrorResult).toEqual({});
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      "❌ Failed to translate document /docs/test2.md:",
+      "Translation failed",
+    );
+    expect(mockOptions.context.invoke).toHaveBeenCalledTimes(2);
+  });
+
+  // EDGE CASES AND INTEGRATION
+  test("should handle edge cases and complex scenarios", async () => {
+    // Test edge cases with different document properties
+    const edgeCaseInput = {
+      selectedDocs: [
+        {
+          path: "/docs/test1.md",
+          content: "# Test Document 1",
+          translates: null, // null translates
+          labels: {},
+          feedback: "", // empty feedback
+        },
+        {
+          path: "/docs/test2.md",
+          content: "# Test Document 2",
+          translates: undefined, // undefined translates
+          labels: {},
+          feedback: "   ", // whitespace feedback
+        },
+        {
+          path: "/docs/test3.md",
+          content: "# Test Document 3",
+          translates: {},
+          labels: {},
+          // no title
+        },
+      ],
+      docsDir: "./docs",
+      translateLanguages: ["en", "zh"],
+      locale: "en",
+    };
+
+    mockOptions.prompts.select.mockResolvedValue("no");
+
+    const edgeCaseResult = await saveAndTranslateDocument(edgeCaseInput, mockOptions);
+
+    expect(edgeCaseResult).toEqual({});
+    expect(mockOptions.context.invoke).toHaveBeenCalledTimes(3);
+    expect(recordUpdateSpy).not.toHaveBeenCalled(); // No valid feedback
+
+    // Reset mocks
+    mockOptions.prompts.select.mockClear();
+    mockOptions.context.invoke.mockClear();
+    recordUpdateSpy.mockClear();
+
+    // Test batch processing with multiple documents
+    const batchInput = {
+      selectedDocs: Array.from({ length: 5 }, (_, i) => ({
+        path: `/docs/batch${i + 1}.md`,
+        content: `# Batch Document ${i + 1}`,
+        translates: {},
+        labels: {},
+        title: `Batch Document ${i + 1}`,
+      })),
+      docsDir: "./docs",
+      translateLanguages: ["en", "zh"],
+      locale: "en",
+    };
+
+    mockOptions.prompts.select.mockResolvedValue("yes");
+    mockOptions.context.invoke.mockResolvedValue({ mockResult: true });
+
+    const batchResult = await saveAndTranslateDocument(batchInput, mockOptions);
+
+    expect(batchResult).toEqual({});
+    // 5 documents * 3 calls each (save, translate, save) = 15 calls
+    expect(mockOptions.context.invoke).toHaveBeenCalledTimes(15);
+  });
+});

package/tests/agents/utils/check-detail-result.test.mjs

@@ -337,6 +337,19 @@ This document demonstrates various programming language code blocks.`;
     });
   });
 
+  describe("D2 syntax validation", () => {
+    test("should handle D2 syntax errors", async () => {
+      const documentStructure = [];
+      const reviewContent =
+        "```d2\n" +
+        "invalid d2 syntax {{\n" + // Malformed D2
+        "```\n\n" +
+        "This has proper structure.";
+      const result = await checkDetailResult({ documentStructure, reviewContent });
+      expect(result.isApproved).toBe(false);
+    });
+  });
+
   describe("Advanced table edge cases", () => {
     test("should handle empty table cells correctly", async () => {
       const documentStructure = [];

package/tests/utils/d2-utils.test.mjs

@@ -14,6 +14,7 @@ import {
   getChart,
   isValidCode,
   saveAssets,
+  wrapCode,
 } from "../../utils/d2-utils.mjs";
 
 describe("d2-utils", () => {
@@ -420,4 +421,17 @@ E -> F
       expect(isValidCode(undefined)).toBe(false);
     });
   });
+
+  describe("wrapCode", () => {
+    test("should return original content when D2 block already exists", () => {
+      const content = "```d2\nA -> B\n```";
+      expect(wrapCode({ content })).toBe(content);
+    });
+
+    test("should wrap plain content in a D2 code block", () => {
+      const content = "A -> B";
+      const expected = "```d2\nA -> B\n```";
+      expect(wrapCode({ content })).toBe(expected);
+    });
+  });
 });

package/tests/utils/docs-finder-utils.test.mjs

@@ -6,6 +6,7 @@ import {
   fileNameToFlatPath,
   findItemByFlatName,
   findItemByPath,
+  generateFileName,
   getActionText,
   getMainLanguageFiles,
   processSelectedFiles,
@@ -633,5 +634,17 @@ describe("docs-finder-utils", () => {
         "⚠️  No documentation structure item found for file: test.md",
       );
     });
+
+    test("fileNameToFlatPath should handle files with multiple language suffixes", () => {
+      expect(fileNameToFlatPath("file.zh-CN.md")).toBe("file");
+      expect(fileNameToFlatPath("file.en-US.md")).toBe("file");
+      expect(fileNameToFlatPath("file.fr-FR.md")).toBe("file");
+    });
+
+    test("generateFileName should handle special characters in flatName", () => {
+      expect(generateFileName("api-v1-guide", "en")).toBe("api-v1-guide.md");
+      expect(generateFileName("api-v1-guide", "zh")).toBe("api-v1-guide.zh.md");
+      expect(generateFileName("test_special-chars", "fr")).toBe("test_special-chars.fr.md");
+    });
   });
 });

package/tests/utils/history-utils.test.mjs

@@ -0,0 +1,178 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { DOC_SMITH_DIR } from "../../utils/constants/index.mjs";
+import { getHistory, isGitAvailable, recordUpdate } from "../../utils/history-utils.mjs";
+
+const TEST_DIR = join(process.cwd(), `${DOC_SMITH_DIR}-test`);
+const ORIGINAL_CWD = process.cwd();
+
+describe("History Utils - Unified", () => {
+  beforeEach(() => {
+    // Clean up test directory
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+    mkdirSync(TEST_DIR, { recursive: true });
+
+    // Change to test directory
+    process.chdir(TEST_DIR);
+  });
+
+  afterEach(() => {
+    // Restore original directory
+    process.chdir(ORIGINAL_CWD);
+
+    // Clean up
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+  });
+
+  test("detects git availability", () => {
+    const hasGit = isGitAvailable();
+    expect(typeof hasGit).toBe("boolean");
+  });
+
+  test("skips recording on empty feedback", () => {
+    recordUpdate({ operation: "document_update", feedback: "" });
+    const history = getHistory();
+    expect(history.entries.length).toBe(0);
+  });
+
+  test("skips recording on whitespace-only feedback", () => {
+    recordUpdate({ operation: "document_update", feedback: "   " });
+    const history = getHistory();
+    expect(history.entries.length).toBe(0);
+  });
+
+  test("records update in YAML", () => {
+    recordUpdate({
+      operation: "structure_update",
+      feedback: "Test feedback",
+    });
+
+    const history = getHistory();
+    expect(history.entries.length).toBe(1);
+    expect(history.entries[0].feedback).toBe("Test feedback");
+    expect(history.entries[0].operation).toBe("structure_update");
+    expect(history.entries[0].timestamp).toBeDefined();
+  });
+
+  test("records document path when provided as string", () => {
+    recordUpdate({
+      operation: "document_update",
+      feedback: "Update document",
+      documentPath: "/getting-started",
+    });
+
+    const history = getHistory();
+    expect(history.entries.length).toBe(1);
+    expect(history.entries[0].documentPath).toBe("/getting-started");
+  });
+
+  test("records single document path for each update", () => {
+    recordUpdate({
+      operation: "document_update",
+      feedback: "Update single document",
+      documentPath: "/getting-started",
+    });
+
+    const history = getHistory();
+    expect(history.entries.length).toBe(1);
+    expect(history.entries[0].feedback).toBe("Update single document");
+    expect(history.entries[0].documentPath).toBe("/getting-started");
+  });
+
+  test("does not include documentPath field when documentPath is null", () => {
+    recordUpdate({
+      operation: "structure_update",
+      feedback: "Update structure",
+      documentPath: null,
+    });
+
+    const history = getHistory();
+    expect(history.entries.length).toBe(1);
+    expect(history.entries[0].documentPath).toBeUndefined();
+  });
+
+  test("maintains chronological order (newest first)", () => {
+    recordUpdate({ operation: "structure_update", feedback: "First" });
+    // Small delay to ensure different timestamps
+    const now = Date.now();
+    while (Date.now() === now) {
+      // Wait for next millisecond
+    }
+    recordUpdate({ operation: "document_update", feedback: "Second" });
+
+    const history = getHistory();
+    expect(history.entries.length).toBe(2);
+    expect(history.entries[0].feedback).toBe("Second");
+    expect(history.entries[1].feedback).toBe("First");
+  });
+
+  test("handles multiple updates", () => {
+    recordUpdate({ operation: "structure_update", feedback: "Update 1" });
+    recordUpdate({ operation: "document_update", feedback: "Update 2", documentPath: "/home" });
+    recordUpdate({ operation: "document_update", feedback: "Update 3", documentPath: "/about" });
+    recordUpdate({
+      operation: "translation_update",
+      feedback: "Update 4",
+      documentPath: "/api",
+    });
+
+    const history = getHistory();
+    expect(history.entries.length).toBe(4);
+    expect(history.entries[0].feedback).toBe("Update 4");
+    expect(history.entries[0].documentPath).toBe("/api");
+    expect(history.entries[1].feedback).toBe("Update 3");
+    expect(history.entries[1].documentPath).toBe("/about");
+    expect(history.entries[2].feedback).toBe("Update 2");
+    expect(history.entries[2].documentPath).toBe("/home");
+    expect(history.entries[3].feedback).toBe("Update 1");
+  });
+
+  test("returns empty history when file does not exist", () => {
+    const history = getHistory();
+    expect(history.entries).toBeDefined();
+    expect(history.entries.length).toBe(0);
+  });
+
+  test("handles corrupted history file gracefully", () => {
+    // Create corrupted YAML file
+    const historyPath = join(process.cwd(), DOC_SMITH_DIR, "history.yaml");
+    mkdirSync(join(process.cwd(), DOC_SMITH_DIR), { recursive: true });
+    writeFileSync(historyPath, "invalid: yaml: content: [[[", "utf8");
+
+    const history = getHistory();
+    expect(history.entries).toBeDefined();
+    expect(history.entries.length).toBe(0);
+  });
+
+  test(`creates ${DOC_SMITH_DIR} directory if not exists`, () => {
+    recordUpdate({
+      operation: "document_update",
+      feedback: "Test",
+    });
+
+    const docSmithDir = join(process.cwd(), DOC_SMITH_DIR);
+    expect(existsSync(docSmithDir)).toBe(true);
+  });
+
+  test("timestamp is in ISO 8601 format", () => {
+    recordUpdate({
+      operation: "structure_update",
+      feedback: "Test timestamp",
+    });
+
+    const history = getHistory();
+    const timestamp = history.entries[0].timestamp;
+
+    // Validate ISO 8601 format
+    expect(timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+
+    // Validate it's a valid date
+    const date = new Date(timestamp);
+    expect(date.toISOString()).toBe(timestamp);
+  });
+});

package/utils/d2-utils.mjs

@@ -195,3 +195,12 @@ export async function ensureTmpDir() {
 export function isValidCode(lang) {
   return lang?.toLowerCase() === "d2";
 }
+
+export function wrapCode({ content }) {
+  const matches = Array.from(content.matchAll(codeBlockRegex));
+  if (matches.length > 0) {
+    return content;
+  }
+
+  return `\`\`\`d2\n${content}\n\`\`\``;
+}

package/utils/docs-finder-utils.mjs

@@ -12,13 +12,22 @@ export function getActionText(isTranslate, baseText) {
   return baseText.replace("{action}", action);
 }
 
+/**
+ * Convert path to flattened name format
+ * @param {string} path - Document path (e.g., "/api/users")
+ * @returns {string} Flattened name (e.g., "api-users")
+ */
+export function pathToFlatName(path) {
+  return path.replace(/^\//, "").replace(/\//g, "-");
+}
+
 /**
  * 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) {
+export function generateFileName(flatName, locale) {
   const isEnglish = locale === "en";
   return isEnglish ? `${flatName}.md` : `${flatName}.${locale}.md`;
 }