@aigne/doc-smith 0.8.11 → 0.8.12-beta.1

package/tests/agents/generate/user-review-document-structure.test.mjs

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from "bun:
 import userReviewDocumentStructure from "../../../agents/generate/user-review-document-structure.mjs";
 
 import * as preferencesUtils from "../../../utils/preferences-utils.mjs";
+import * as historyUtils from "../../../utils/history-utils.mjs";
 
 describe("user-review-document-structure", () => {
   let mockOptions;
@@ -61,6 +62,7 @@ describe("user-review-document-structure", () => {
     );
 
     consoleSpy = spyOn(console, "log").mockImplementation(() => {});
+    spyOn(historyUtils, "recordUpdate").mockImplementation(() => {});
 
     // Clear prompts mock call history
     mockOptions.prompts.select.mockClear();

package/tests/agents/update/check-document.test.mjs

@@ -25,7 +25,7 @@ describe("check-document", () => {
     mockOptions = {
       context: {
         agents: {
-          generateAndTranslateDocument: { mockAgent: true },
+          handleDocumentUpdate: { mockAgent: true },
         },
         invoke: mock(async () => ({ mockResult: true })),
       },

package/tests/agents/update/fs-tools/read-file.test.mjs

@@ -1,8 +1,8 @@
+import { afterEach, beforeEach, describe, it } from "bun:test";
 import assert from "node:assert";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, beforeEach, describe, it } from "bun:test";
 import readFile from "../../../../agents/update/fs-tools/read-file.mjs";
 
 describe("read-file tool", () => {
@@ -11,11 +11,13 @@ describe("read-file tool", () => {
   beforeEach(async () => {
     // Create temporary directory for test files
     tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "read-file-test-"));
+    process.chdir(tempDir);
   });
 
   afterEach(async () => {
     // Clean up temporary directory
     await fs.rm(tempDir, { recursive: true, force: true });
+    process.chdir(__dirname);
   });
 
   describe("basic functionality", () => {
@@ -25,13 +27,16 @@ describe("read-file tool", () => {
       await fs.writeFile(filePath, content, "utf8");
 
       const result = await readFile({
-        path: filePath,
+        path: "test.txt",
       });
 
       assert.strictEqual(result.command, "read_file");
       assert.strictEqual(result.error, null);
       assert.strictEqual(result.result.content, content);
-      assert.strictEqual(result.result.metadata.path, filePath);
+      assert.strictEqual(
+        await fs.realpath(result.result.metadata.path),
+        await fs.realpath(filePath),
+      );
       assert.strictEqual(result.result.metadata.mimeType, "text/plain");
       assert.strictEqual(result.result.metadata.isBinary, false);
       assert.strictEqual(result.result.metadata.encoding, "utf8");
@@ -348,15 +353,6 @@ describe("read-file tool", () => {
       assert(result.error.message.includes("required"));
     });
 
-    it("should require absolute path", async () => {
-      const result = await readFile({
-        path: "relative/path.txt",
-      });
-
-      assert.notStrictEqual(result.error, null);
-      assert(result.error.message.includes("absolute"));
-    });
-
     it("should handle non-existent files", async () => {
       const result = await readFile({
         path: path.join(tempDir, "nonexistent.txt"),

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`;
 }

package/utils/history-utils.mjs

@@ -0,0 +1,191 @@
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { parse, stringify } from "yaml";
+import { DOC_SMITH_DIR } from "./constants/index.mjs";
+
+const HISTORY_FILE = "history.yaml";
+
+/**
+ * Check if git is available in the system
+ */
+export function isGitAvailable() {
+  try {
+    execSync("git --version", { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Initialize git repo in DOC_SMITH_DIR if not exists
+ */
+export function ensureGitRepo() {
+  if (!isGitAvailable()) return false;
+
+  const gitDir = join(process.cwd(), DOC_SMITH_DIR, ".git");
+
+  if (!existsSync(gitDir)) {
+    try {
+      const cwd = join(process.cwd(), DOC_SMITH_DIR);
+
+      execSync("git init", { cwd, stdio: "ignore" });
+
+      // Create .gitignore to exclude temporary files
+      const gitignore = "*.tmp\n";
+      writeFileSync(join(cwd, ".gitignore"), gitignore);
+
+      // Initial commit
+      execSync('git add .gitignore && git commit -m "Initialize doc-smith history"', {
+        cwd,
+        stdio: "ignore",
+      });
+
+      console.log("✔ Git history tracking initialized");
+      return true;
+    } catch (error) {
+      console.warn("Failed to initialize git history:", error.message);
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Record update using git commit (if available)
+ */
+function recordUpdateGit({ feedback }) {
+  try {
+    const cwd = join(process.cwd(), DOC_SMITH_DIR);
+
+    // Stage changed files (only if they exist)
+    const filesToAdd = ["docs/", "config.yaml", "preferences.yml", "history.yaml"]
+      .filter((file) => existsSync(join(cwd, file)))
+      .join(" ");
+
+    if (filesToAdd) {
+      execSync(`git add ${filesToAdd}`, {
+        cwd,
+        stdio: "ignore",
+      });
+    }
+
+    // Check if there are changes to commit
+    try {
+      execSync("git diff --cached --quiet", { cwd, stdio: "ignore" });
+      console.log("✔ No update history changes to commit");
+      return; // No changes
+    } catch {
+      // Has changes, continue
+    }
+
+    // Build commit message (only user feedback)
+    const message = feedback;
+
+    // Commit
+    execSync(`git commit -m ${JSON.stringify(message)}`, {
+      cwd,
+      stdio: "ignore",
+    });
+    console.log("✔ Update history committed successfully");
+  } catch (error) {
+    console.warn("Update history commit failed:", error.message);
+  }
+}
+
+/**
+ * Record update in YAML file (always)
+ */
+function recordUpdateYaml({ operation, feedback, documentPath = null }) {
+  try {
+    const docSmithDir = join(process.cwd(), DOC_SMITH_DIR);
+    if (!existsSync(docSmithDir)) {
+      mkdirSync(docSmithDir, { recursive: true });
+    }
+    const historyPath = join(docSmithDir, HISTORY_FILE);
+
+    // Read existing history
+    let history = { entries: [] };
+    if (existsSync(historyPath)) {
+      try {
+        const content = readFileSync(historyPath, "utf8");
+        history = parse(content) || { entries: [] };
+      } catch (error) {
+        console.warn("Failed to read history file:", error.message);
+      }
+    }
+
+    // Create new entry
+    const entry = {
+      timestamp: new Date().toISOString(),
+      operation,
+      feedback,
+    };
+
+    // Add document path if provided
+    if (documentPath) {
+      entry.documentPath = documentPath;
+    }
+
+    // Add to beginning (newest first)
+    history.entries = history.entries || [];
+    history.entries.unshift(entry);
+
+    // Write back
+    const yamlContent = stringify(history, {
+      indent: 2,
+      lineWidth: 100,
+    });
+
+    writeFileSync(historyPath, yamlContent, "utf8");
+  } catch (error) {
+    console.warn("YAML history tracking failed:", error.message);
+  }
+}
+
+/**
+ * Record an update after user feedback
+ * - Always writes to YAML
+ * - Also commits to git if available
+ * @param {Object} params
+ * @param {string} params.operation - Type of operation (e.g., 'document_update', 'structure_update', 'translation_update')
+ * @param {string} params.feedback - User feedback text
+ * @param {string} params.documentPath - Document path - should be a string
+ */
+export function recordUpdate({ operation, feedback, documentPath = null }) {
+  // Skip if no feedback
+  if (!feedback?.trim()) return;
+
+  // Always record in YAML
+  recordUpdateYaml({ operation, feedback, documentPath });
+
+  // Also record in git if available
+  if (isGitAvailable()) {
+    // Initialize git repo on first update if not exists
+    ensureGitRepo();
+    recordUpdateGit({ feedback });
+  } else {
+    console.warn("Git is not available, skipping git based update history");
+  }
+}
+
+/**
+ * Get history entries from YAML
+ */
+export function getHistory() {
+  const historyPath = join(process.cwd(), DOC_SMITH_DIR, HISTORY_FILE);
+
+  if (!existsSync(historyPath)) {
+    return { entries: [] };
+  }
+
+  try {
+    const content = readFileSync(historyPath, "utf8");
+    return parse(content) || { entries: [] };
+  } catch (error) {
+    console.warn("Failed to read history:", error.message);
+    return { entries: [] };
+  }
+}

package/utils/markdown-checker.mjs

@@ -1,11 +1,14 @@
 import fs from "node:fs";
 import path from "node:path";
+import pMap from "p-map";
 import remarkGfm from "remark-gfm";
 import remarkLint from "remark-lint";
 import remarkParse from "remark-parse";
 import { unified } from "unified";
 import { visit } from "unist-util-visit";
 import { VFile } from "vfile";
+import { KROKI_CONCURRENCY } from "./constants/index.mjs";
+import { checkContent, isValidCode } from "./d2-utils.mjs";
 import { validateMermaidSyntax } from "./mermaid-validator.mjs";
 
 /**
@@ -375,6 +378,7 @@ export async function checkMarkdown(markdown, source = "content", options = {})
 
     // Check mermaid code blocks and other custom validations
     const mermaidChecks = [];
+    const d2ChecksList = [];
     visit(ast, "code", (node) => {
       if (node.lang) {
         const line = node.position?.start?.line || "unknown";
@@ -463,6 +467,12 @@ export async function checkMarkdown(markdown, source = "content", options = {})
             specialCharMatch = nodeWithSpecialCharsRegex.exec(mermaidContent);
           }
         }
+        if (isValidCode(node.lang)) {
+          d2ChecksList.push({
+            content: node.value,
+            line,
+          });
+        }
       }
     });
 
@@ -514,6 +524,16 @@ export async function checkMarkdown(markdown, source = "content", options = {})
     // Wait for all mermaid checks to complete
     await Promise.all(mermaidChecks);
 
+    await pMap(
+      d2ChecksList,
+      async ({ content, line }) =>
+        checkContent({ content }).catch((err) => {
+          const errorMessage = err?.message || String(err) || "Unknown d2 syntax error";
+          errorMessages.push(`Found D2 syntax error in ${source} at line ${line}: ${errorMessage}`);
+        }),
+      { concurrency: KROKI_CONCURRENCY },
+    );
+
     // Run markdown linting rules
     await processor.run(ast, file);
 

package/agents/generate/check-d2-diagram-valid.mjs

@@ -1,26 +0,0 @@
-import { checkContent } from "../../utils/d2-utils.mjs";
-
-export default async function checkD2DiagramIsValid({ d2DiagramSourceCode }) {
-  try {
-    await checkContent({ content: d2DiagramSourceCode });
-    return {
-      isValid: true,
-    };
-  } catch (err) {
-    return {
-      isValid: false,
-      error: err.message,
-    };
-  }
-}
-
-checkD2DiagramIsValid.input_schema = {
-  type: "object",
-  properties: {
-    d2DiagramSourceCode: {
-      type: "string",
-      description: "Source code of d2 diagram",
-    },
-  },
-  required: ["d2DiagramSourceCode"],
-};

package/agents/generate/generate-d2-diagram.yaml

@@ -1,23 +0,0 @@
-name: drawD2Diagram
-description: Generate a D2 diagram from document content.
-instructions:
-  - role: system
-    url: ../../prompts/detail/d2-diagram/rules-system.md
-  - role: user
-    url: ../../prompts/detail/d2-diagram/rules-user.md
-input_schema:
-  type: object
-  properties:
-    documentContent:
-      type: string
-      description: Source code of current document (without the D2 diagram)
-  required:
-    - documentContent
-output_schema:
-  type: object
-  properties:
-    d2DiagramSourceCode:
-      type: string
-      description: Source code to draw D2 diagram
-  required:
-    - d2DiagramSourceCode