@aigne/doc-smith 0.4.5 → 0.6.0

package/utils/markdown-checker.mjs

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import path from "node:path";
 import remarkGfm from "remark-gfm";
 import remarkLint from "remark-lint";
 import remarkParse from "remark-parse";
@@ -159,6 +161,72 @@ function checkCodeBlockIndentation(codeBlockContent, codeBlockIndent, source, er
   }
 }
 
+/**
+ * Check for local images and verify their existence
+ * @param {string} markdown - The markdown content
+ * @param {string} source - Source description for error reporting
+ * @param {Array} errorMessages - Array to push error messages to
+ * @param {string} [markdownFilePath] - Path to the markdown file for resolving relative paths
+ * @param {string} [baseDir] - Base directory for resolving relative paths (alternative to markdownFilePath)
+ */
+function checkLocalImages(markdown, source, errorMessages, markdownFilePath, baseDir) {
+  const imageRegex = /!\[([^\]]*)\]\(([^)]+)\)/g;
+  let match;
+
+  while ((match = imageRegex.exec(markdown)) !== null) {
+    const imagePath = match[2].trim();
+    const altText = match[1];
+
+    // Skip external URLs (http/https)
+    if (/^https?:\/\//.test(imagePath)) continue;
+
+    // Skip data URLs
+    if (/^data:/.test(imagePath)) continue;
+
+    // Check if it's a local path
+    if (!imagePath.startsWith("/") && !imagePath.includes("://")) {
+      // It's a relative local path, check if file exists
+      try {
+        let resolvedPath;
+        if (markdownFilePath) {
+          // Resolve relative to the markdown file's directory
+          const markdownDir = path.dirname(markdownFilePath);
+          resolvedPath = path.resolve(markdownDir, imagePath);
+        } else if (baseDir) {
+          // Resolve relative to the provided base directory
+          resolvedPath = path.resolve(baseDir, imagePath);
+        } else {
+          // Fallback to current working directory
+          resolvedPath = path.resolve(imagePath);
+        }
+
+        if (!fs.existsSync(resolvedPath)) {
+          errorMessages.push(
+            `Found invalid local image in ${source}: ![${altText}](${imagePath}) - only valid media resources can be used`,
+          );
+        }
+      } catch {
+        errorMessages.push(
+          `Found invalid local image in ${source}: ![${altText}](${imagePath}) - only valid media resources can be used`,
+        );
+      }
+    } else if (imagePath.startsWith("/")) {
+      // Absolute local path
+      try {
+        if (!fs.existsSync(imagePath)) {
+          errorMessages.push(
+            `Found invalid local image in ${source}: ![${altText}](${imagePath}) - only valid media resources can be used`,
+          );
+        }
+      } catch {
+        errorMessages.push(
+          `Found invalid local image in ${source}: ![${altText}](${imagePath}) - only valid media resources can be used`,
+        );
+      }
+    }
+  }
+}
+
 /**
  * Check content structure and formatting issues
  * @param {string} markdown - The markdown content
@@ -224,7 +292,7 @@ function checkContentStructure(markdown, source, errorMessages) {
   }
 
   // Check if content ends with proper punctuation (indicating completeness)
-  const validEndingPunctuation = [".", "。", ")", "|"];
+  const validEndingPunctuation = [".", "。", ")", "|", "*"];
   const trimmedText = markdown.trim();
   const hasValidEnding = validEndingPunctuation.some((punct) => trimmedText.endsWith(punct));
 
@@ -241,6 +309,8 @@ function checkContentStructure(markdown, source, errorMessages) {
  * @param {string} [source] - Source description for error reporting (e.g., "result")
  * @param {Object} [options] - Additional options for validation
  * @param {Array} [options.allowedLinks] - Set of allowed links for link validation
+ * @param {string} [options.filePath] - Path to the markdown file for resolving relative image paths
+ * @param {string} [options.baseDir] - Base directory for resolving relative image paths (alternative to filePath)
  * @returns {Promise<Array<string>>} - Array of error messages in check-detail-result format
  */
 export async function checkMarkdown(markdown, source = "content", options = {}) {
@@ -248,8 +318,8 @@ export async function checkMarkdown(markdown, source = "content", options = {})
   const errorMessages = [];
 
   try {
-    // Extract allowed links from options
-    const { allowedLinks } = options;
+    // Extract allowed links, file path, and base directory from options
+    const { allowedLinks, filePath, baseDir } = options;
 
     // Create unified processor with markdown parsing and linting
     // Use individual rules instead of presets to have better control
@@ -292,7 +362,10 @@ export async function checkMarkdown(markdown, source = "content", options = {})
       checkDeadLinks(markdown, source, allowedLinks, errorMessages);
     }
 
-    // 2. Check content structure and formatting issues
+    // 2. Check local images existence
+    checkLocalImages(markdown, source, errorMessages, filePath, baseDir);
+
+    // 3. Check content structure and formatting issues
     checkContentStructure(markdown, source, errorMessages);
 
     // Check mermaid code blocks and other custom validations
@@ -319,30 +392,35 @@ export async function checkMarkdown(markdown, source = "content", options = {})
         // Check for backticks in node labels
         const nodeLabelRegex = /[A-Za-z0-9_]+\["([^"]*`[^"]*)"\]|[A-Za-z0-9_]+{"([^}]*`[^}]*)"}/g;
         let match;
-        while ((match = nodeLabelRegex.exec(mermaidContent)) !== null) {
+        match = nodeLabelRegex.exec(mermaidContent);
+        while (match !== null) {
           const label = match[1] || match[2];
           errorMessages.push(
             `Found backticks in Mermaid node label in ${source} at line ${line}: "${label}" - backticks in node labels cause rendering issues in Mermaid diagrams`,
           );
+          match = nodeLabelRegex.exec(mermaidContent);
         }
 
         // Check for numbered list format in edge descriptions
         const edgeDescriptionRegex = /--\s*"([^"]*)"\s*-->/g;
         let edgeMatch;
-        while ((edgeMatch = edgeDescriptionRegex.exec(mermaidContent)) !== null) {
+        edgeMatch = edgeDescriptionRegex.exec(mermaidContent);
+        while (edgeMatch !== null) {
           const description = edgeMatch[1];
           if (/^\d+\.\s/.test(description)) {
             errorMessages.push(
               `Unsupported markdown: list - Found numbered list format in Mermaid edge description in ${source} at line ${line}: "${description}" - numbered lists in edge descriptions are not supported`,
             );
           }
+          edgeMatch = edgeDescriptionRegex.exec(mermaidContent);
         }
 
         // Check for numbered list format in node labels (for both [] and {} syntax)
         const nodeLabelWithNumberRegex =
           /[A-Za-z0-9_]+\["([^"]*\d+\.\s[^"]*)"\]|[A-Za-z0-9_]+{"([^}]*\d+\.\s[^}]*)"}/g;
         let numberMatch;
-        while ((numberMatch = nodeLabelWithNumberRegex.exec(mermaidContent)) !== null) {
+        numberMatch = nodeLabelWithNumberRegex.exec(mermaidContent);
+        while (numberMatch !== null) {
           const label = numberMatch[1] || numberMatch[2];
           // Check if the label contains numbered list format
           if (/\d+\.\s/.test(label)) {
@@ -350,12 +428,14 @@ export async function checkMarkdown(markdown, source = "content", options = {})
               `Unsupported markdown: list - Found numbered list format in Mermaid node label in ${source} at line ${line}: "${label}" - numbered lists in node labels cause rendering issues`,
             );
           }
+          numberMatch = nodeLabelWithNumberRegex.exec(mermaidContent);
         }
 
         // Check for special characters in node labels that should be quoted
         const nodeWithSpecialCharsRegex = /([A-Za-z0-9_]+)\[([^\]]*[(){}:;,\-\s.][^\]]*)\]/g;
         let specialCharMatch;
-        while ((specialCharMatch = nodeWithSpecialCharsRegex.exec(mermaidContent)) !== null) {
+        specialCharMatch = nodeWithSpecialCharsRegex.exec(mermaidContent);
+        while (specialCharMatch !== null) {
           const nodeId = specialCharMatch[1];
           const label = specialCharMatch[2];
 
@@ -373,6 +453,7 @@ export async function checkMarkdown(markdown, source = "content", options = {})
               );
             }
           }
+          specialCharMatch = nodeWithSpecialCharsRegex.exec(mermaidContent);
         }
       }
     });
@@ -431,7 +512,6 @@ export async function checkMarkdown(markdown, source = "content", options = {})
     // Format messages in check-detail-result style
     file.messages.forEach((message) => {
       const line = message.line || "unknown";
-      const _column = message.column || "unknown";
       const reason = message.reason || "Unknown markdown issue";
       const ruleId = message.ruleId || message.source || "markdown";
 

package/utils/preferences-utils.mjs

@@ -0,0 +1,175 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse, stringify } from "yaml";
+
+const PREFERENCES_DIR = ".aigne/doc-smith";
+const PREFERENCES_FILE = "preferences.yml";
+
+/**
+ * Generate a random preference ID
+ * @returns {string} Random ID with pref_ prefix
+ */
+function generatePreferenceId() {
+  return `pref_${randomBytes(8).toString("hex")}`;
+}
+
+/**
+ * Get the full path to the preferences file
+ * @returns {string} Full path to preferences.yml
+ */
+function getPreferencesFilePath() {
+  return join(process.cwd(), PREFERENCES_DIR, PREFERENCES_FILE);
+}
+
+/**
+ * Ensure the preferences directory exists
+ */
+function ensurePreferencesDir() {
+  const preferencesDir = join(process.cwd(), PREFERENCES_DIR);
+  if (!existsSync(preferencesDir)) {
+    mkdirSync(preferencesDir, { recursive: true });
+  }
+}
+
+/**
+ * Read existing preferences from file
+ * @returns {Object} Preferences object with rules array
+ */
+export function readPreferences() {
+  const filePath = getPreferencesFilePath();
+
+  if (!existsSync(filePath)) {
+    return { rules: [] };
+  }
+
+  try {
+    const content = readFileSync(filePath, "utf8");
+    const preferences = parse(content);
+    return preferences || { rules: [] };
+  } catch (error) {
+    console.warn(`Warning: Failed to read preferences file at ${filePath}: ${error.message}`);
+    return { rules: [] };
+  }
+}
+
+/**
+ * Write preferences to file
+ * @param {Object} preferences - Preferences object to save
+ */
+export function writePreferences(preferences) {
+  ensurePreferencesDir();
+  const filePath = getPreferencesFilePath();
+
+  try {
+    const yamlContent = stringify(preferences, {
+      indent: 2,
+      lineWidth: 120,
+    });
+
+    writeFileSync(filePath, yamlContent, "utf8");
+  } catch (error) {
+    throw new Error(`Failed to write preferences file: ${error.message}`);
+  }
+}
+
+/**
+ * Add a new preference rule
+ * @param {Object} ruleData - Rule data from feedbackRefiner
+ * @param {string} ruleData.rule - The rule text
+ * @param {string} ruleData.scope - Rule scope (global, structure, document, translation)
+ * @param {boolean} ruleData.limitToInputPaths - Whether to limit to input paths
+ * @param {string} feedback - Original user feedback
+ * @param {string[]} [paths] - Optional paths to save with the rule
+ * @returns {Object} The created preference rule
+ */
+export function addPreferenceRule(ruleData, feedback, paths = []) {
+  const preferences = readPreferences();
+
+  const newRule = {
+    id: generatePreferenceId(),
+    active: true,
+    scope: ruleData.scope,
+    rule: ruleData.rule,
+    feedback: feedback,
+    createdAt: new Date().toISOString(),
+  };
+
+  // Add paths if limitToInputPaths is true and paths are provided
+  if (ruleData.limitToInputPaths && paths && paths.length > 0) {
+    newRule.paths = paths;
+  }
+
+  // Add the new rule to the beginning of the array (newest first)
+  preferences.rules.unshift(newRule);
+
+  writePreferences(preferences);
+
+  return newRule;
+}
+
+/**
+ * Get all active preference rules for a specific scope
+ * @param {string} scope - The scope to filter by (global, structure, document, translation)
+ * @param {string[]} [currentPaths] - Current paths to match against rules with path restrictions
+ * @returns {Object[]} Array of matching active rules
+ */
+export function getActiveRulesForScope(scope, currentPaths = []) {
+  const preferences = readPreferences();
+
+  return preferences.rules.filter((rule) => {
+    // Must be active and match scope
+    if (!rule.active || rule.scope !== scope) {
+      return false;
+    }
+
+    // If rule has path restrictions, check if any current path matches
+    if (rule.paths && rule.paths.length > 0) {
+      if (currentPaths.length === 0) {
+        return false; // Rule has path restrictions but no current paths provided
+      }
+
+      // Check if any current path matches any rule path pattern
+      return currentPaths.some((currentPath) => rule.paths.includes(currentPath));
+    }
+
+    return true; // No path restrictions, include the rule
+  });
+}
+
+/**
+ * Deactivate a preference rule by ID
+ * @param {string} ruleId - The ID of the rule to deactivate
+ * @returns {boolean} True if rule was found and deactivated
+ */
+export function deactivateRule(ruleId) {
+  const preferences = readPreferences();
+  const rule = preferences.rules.find((r) => r.id === ruleId);
+
+  if (rule) {
+    rule.active = false;
+    writePreferences(preferences);
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Remove a preference rule by ID
+ * @param {string} ruleId - The ID of the rule to remove
+ * @returns {boolean} True if rule was found and removed
+ */
+export function removeRule(ruleId) {
+  const preferences = readPreferences();
+  const initialLength = preferences.rules.length;
+
+  preferences.rules = preferences.rules.filter((r) => r.id !== ruleId);
+
+  if (preferences.rules.length < initialLength) {
+    writePreferences(preferences);
+    return true;
+  }
+
+  return false;
+}

package/utils/utils.mjs

@@ -8,8 +8,8 @@ import {
   DEFAULT_INCLUDE_PATTERNS,
   DOCUMENT_STYLES,
   DOCUMENTATION_DEPTH,
-  SUPPORTED_FILE_EXTENSIONS,
   READER_KNOWLEDGE_LEVELS,
+  SUPPORTED_FILE_EXTENSIONS,
   SUPPORTED_LANGUAGES,
   TARGET_AUDIENCES,
 } from "./constants.mjs";
@@ -149,8 +149,8 @@ export function getCurrentGitHead() {
  * @param {string} gitHead - The current git HEAD commit hash
  */
 export async function saveGitHeadToConfig(gitHead) {
-  if (!gitHead) {
-    return; // Skip if no git HEAD available
+  if (!gitHead || process.env.NODE_ENV === 'test' || process.env.BUN_TEST) {
+    return; // Skip if no git HEAD available or in test environment
   }
 
   try {