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

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>