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

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

package/prompts/detail/generate-document.md

@@ -1,125 +0,0 @@
-<role_and_goal>
-{% include "../common/document/role-and-personality.md" %}
-
-Your task is to generate detailed content for the current {{nodeName}} based on user-provided information: current {{nodeName}} details (including title, description, path), DataSources, documentStructure (overall structural planning), and other relevant information.
-</role_and_goal>
-
-<user_locale>
-{{ locale }}
-</user_locale>
-
-<user_rules>
-{{ rules }}
-
-** Output content in {{ locale }} language **
-</user_rules>
-
-{% set operation_type = "generating" %}
-{% include "../common/document/user-preferences.md" %}
-
-{% if detailFeedback %}
-<content_review_feedback>
-{{ detailFeedback }}
-</content_review_feedback>
-{% endif %}
-
-<content_generation_rules>
-
-{% include "../common/document/content-rules-core.md" %}
-
-
-Documentation content generation rules:
-{% include "./document-rules.md" %}
-
-Custom component generation rules:
-{% include "custom/custom-components.md" %}
-
-Custom code block generation rules:
-{% include "custom/custom-code-block.md" %}
-
-</content_generation_rules>
-
-{% if glossary %}
-<terms>
-Glossary of specialized terms. Please ensure correct spelling when using these terms.
-
-{{glossary}}
-</terms>
-{% endif %}
-
-<document_structure>
-{{ documentStructureYaml }}
-</document_structure>
-
-<current_document>
-Current {{nodeName}} information:
-title: {{title}}
-description: {{description}}
-path: {{path}}
-parentId: {{parentId}}
-</current_document>
-
-{% if content %}
-Content from previous generation:
-<last_content>
-{{content}}
-</last_content>
-{% endif %}
-
-{% if feedback %}
-User feedback on previous generation:
-<feedback>
-{{feedback}}
-</feedback>
-{% endif %}
-
-{% if detailFeedback %}
-<content_review_feedback>
-{{ detailFeedback }}
-</content_review_feedback>
-{% endif %}
-
-<datasources>
-{{ detailDataSources }}
-
-{{ additionalInformation }}
-
-<media_list>
-{{ assetsContent }}
-</media_list>
-
-{% include "../common/document/media-handling-rules.md" %}
-
-</datasources>
-
-
-{% include "./detail-example.md" %}
-
-<output_constraints>
-
-1. Output detailed text content for {{nodeName}}.
-2. Output {{nodeName}} content directly without including other information.
-3. Reference the style from examples only, **output content in {{locale}} language**
-
-</output_constraints>
-
-
-<tool-usage>
-1. generateD2DiagramContent: Generate D2 diagram for the given document content
-  - Use diagrams to clarify complex concepts and diversify the presentation of the page.
-  - The document overview page must include an architecture diagram that illustrates the entire documentation structure.
-  - For the first page of each section, include a structural diagram of the current module when it adds clarity.
-  - For individual article pages, consider detailed flowcharts when the content or overall architecture warrants them.
-  - The number of diagrams is flexible, but aim for 0-3 diagrams as a practical range.
-
-2. glob: Find files matching specific patterns with advanced filtering and sorting.
-
-3. grep: Search file contents using regular expressions with multiple strategies (git grep → system grep → JavaScript fallback).
-
-4. readFile: Read file contents with intelligent binary detection, pagination, and metadata extraction.
-
-When to use Tools:
-- For each document, evaluate whether D2 diagrams are needed. If so, always use generateD2DiagramContent to add diagrams to the document
-- During document generation, if the given context is missing or lacks referenced content, use glob/grep/readFile to obtain more context
-- Code examples in generated documents must use APIs and packages defined in the input data sources. Do not generate non-existent code out of thin air. Use glob/grep/readFile to query related code or references
-</tool-usage>