@aigne/doc-smith 0.2.11 → 0.3.1

package/utils/constants.mjs

@@ -9,6 +9,8 @@ export const DEFAULT_INCLUDE_PATTERNS = [
   "*.jsx",
   "*.ts",
   "*.tsx",
+  "*.mjs",
+  "*.mts",
   // C/C++
   "*.c",
   "*.cc",
@@ -87,16 +89,16 @@ export const DEFAULT_INCLUDE_PATTERNS = [
 ];
 
 export const DEFAULT_EXCLUDE_PATTERNS = [
-  "aigne-docs/**",
-  "doc-smith/**",
-  ".aigne/**",
-  "assets/**",
-  "data/**",
-  "images/**",
-  "public/**",
-  "static/**",
+  "**/aigne-docs/**",
+  "**/doc-smith/**",
+  "**/.aigne/**",
+  "**/assets/**",
+  "**/data/**",
+  "**/images/**",
+  "**/public/**",
+  "**/static/**",
   "**/vendor/**",
-  "temp/**",
+  "**/temp/**",
   "**/*docs/**",
   "**/*doc/**",
   "**/*venv/**",
@@ -122,6 +124,13 @@ export const DEFAULT_EXCLUDE_PATTERNS = [
   "**/*node_modules/**",
   "*.log",
   "**/*test.*",
+  "**/pnpm-lock.yaml",
+  "**/yarn.lock",
+  "**/package-lock.json",
+  "**/pnpm-lock.json",
+  "**/bun.lockb",
+  "**/bun.lock",
+  "**/bun.lockb",
 ];
 
 // Supported languages for documentation
@@ -140,33 +149,385 @@ export const SUPPORTED_LANGUAGES = [
   { code: "ar", label: "العربية (ar)", sample: "مرحبا" },
 ];
 
-// Predefined document generation styles
+// Predefined document generation styles based on primary purpose
 export const DOCUMENT_STYLES = {
-  userGuide: {
-    name: "User Guide",
-    rules: "Scenario-based; step-by-step; plain language; outcomes & cautions.",
+  getStarted: {
+    name: "Get started quickly",
+    description: "Help new users go from zero to working in <30 minutes",
+    content:
+      "Optimizes for: Speed, essential steps, working examples.\nSkips: Complex edge cases, theoretical background.",
   },
-  developerDocs: {
-    name: "Developer Docs",
-    rules: "Steps-first; copy-paste examples; minimal context; active 'you'.",
+  completeTasks: {
+    name: "Complete specific tasks",
+    description: "Guide users through common workflows and use cases",
+    content:
+      "Optimizes for: Step-by-step instructions, practical scenarios.\nSkips: Deep technical internals, getting started basics.",
   },
-  apiReference: {
-    name: "API Reference",
-    rules: "Exact & skimmable; schema-first; clear params/errors/examples.",
+  findAnswers: {
+    name: "Find answers fast",
+    description: "Provide searchable reference for all features and APIs",
+    content:
+      "Optimizes for: Comprehensive coverage, searchability, examples.\n Skips: Narrative flow, beginner explanations.",
   },
-  custom: {
-    name: "Custom Rules",
-    rules: "Enter your own documentation generation rules",
+  understandSystem: {
+    name: "Understand the system",
+    description: "Explain how it works, why design decisions were made",
+    content:
+      "Optimizes for: Architecture, concepts, decision rationale.\nSkips: Quick wins, copy-paste solutions.",
+  },
+  solveProblems: {
+    name: "Solve problems",
+    description: "Help users troubleshoot and fix issues",
+    content:
+      "Optimizes for: Error scenarios, diagnostics, solutions.\nSkips: Happy path tutorials, feature overviews.",
+  },
+  mixedPurpose: {
+    name: "Mix of above",
+    description: "Comprehensive documentation covering multiple needs",
+    content:
+      "Optimizes for: Balanced coverage, multiple entry points.\nTrade-off: Longer, requires good navigation.",
   },
 };
 
-// Predefined target audiences
+// Predefined target audiences based on who will read the documentation most often
 export const TARGET_AUDIENCES = {
-  generalUsers: "General Users",
-  actionFirst: "Developers, Implementation Engineers, DevOps",
-  conceptFirst: "Architects, Technical Leads, Developers interested in principles",
-  custom: "Enter your own target audience",
+  endUsers: {
+    name: "End users (non-technical)",
+    description: "People who use the product but don't code",
+    content:
+      "Writing: Plain language, UI-focused, avoid technical terms.\nExamples: Screenshots, step-by-step clicks, business outcomes.",
+  },
+  developers: {
+    name: "Developers integrating",
+    description: "Engineers adding this to their projects",
+    content:
+      "Writing: Code-first, copy-paste ready, technical accuracy.\nExamples: SDK usage, API calls, configuration snippets.",
+  },
+  devops: {
+    name: "DevOps/Infrastructure",
+    description: "Teams deploying, monitoring, maintaining systems",
+    content:
+      "Writing: Operations-focused, troubleshooting emphasis.\nExamples: Deployment configs, monitoring setup, scaling guides.",
+  },
+  decisionMakers: {
+    name: "Technical decision makers",
+    description: "Architects, leads evaluating or planning implementation",
+    content:
+      "Writing: High-level first, drill-down details available.\nExamples: Architecture diagrams, comparison tables, trade-offs.",
+  },
+  supportTeams: {
+    name: "Support teams",
+    description: "People helping others use the product",
+    content:
+      "Writing: Diagnostic-focused, common issues prominent.\nExamples: Troubleshooting flows, FAQ format, escalation paths.",
+  },
+  mixedTechnical: {
+    name: "Mixed technical audience",
+    description: "Developers, DevOps, and technical users",
+    content:
+      "Writing: Layered complexity, multiple entry points.\nExamples: Progressive disclosure, role-based navigation.",
+  },
+};
+
+// Reader knowledge level - what do readers typically know when they arrive?
+export const READER_KNOWLEDGE_LEVELS = {
+  completeBeginners: {
+    name: "Complete beginners",
+    description: "New to this domain/technology entirely",
+    content:
+      "Content: Define terms, explain concepts, assume nothing.\nStructure: Linear progression, prerequisite checks.\nTone: Patient, educational, confidence-building.",
+  },
+  domainFamiliar: {
+    name: "Domain-familiar, tool-new",
+    description: "Know the problem space, new to this specific solution",
+    content:
+      'Content: Focus on differences, migration, unique features.\nStructure: Comparison-heavy, "coming from X" sections.\nTone: Efficient, highlight advantages, skip basics.',
+  },
+  experiencedUsers: {
+    name: "Experienced users",
+    description: "Regular users needing reference/advanced topics",
+    content:
+      "Content: Dense information, edge cases, performance tips.\nStructure: Reference-style, searchable, task-oriented.\nTone: Concise, technical precision, assume competence.",
+  },
+  emergencyTroubleshooting: {
+    name: "Emergency/troubleshooting",
+    description: "Something's broken, need to fix it quickly",
+    content:
+      "Content: Symptom → diagnosis → solution format.\nStructure: Problem-first, solution-prominent, escalation paths.\nTone: Clear, actionable, confidence-inspiring.",
+  },
+  exploringEvaluating: {
+    name: "Exploring/evaluating",
+    description: "Trying to understand if this fits their needs",
+    content:
+      "Content: Use cases, comparisons, getting started quickly.\nStructure: Multiple entry points, progressive commitment.\nTone: Persuasive but honest, show value quickly.",
+  },
+};
+
+// Documentation depth - how comprehensive should the documentation be?
+export const DOCUMENTATION_DEPTH = {
+  essentialOnly: {
+    name: "Essential only",
+    description: "Cover the 80% use cases, keep it concise",
+    content:
+      "Scope: Core features, happy paths, common patterns.\nLength: Shorter sections, key examples only.\nMaintenance: Easier to keep current.",
+  },
+  balancedCoverage: {
+    name: "Balanced coverage",
+    description: "Good depth with practical examples [RECOMMENDED]",
+    content:
+      "Scope: Most features, some edge cases, multiple examples.\nLength: Moderate sections, varied example types.\nMaintenance: Reasonable update burden.",
+  },
+  comprehensive: {
+    name: "Comprehensive",
+    description: "Cover all features, edge cases, and advanced scenarios",
+    content:
+      "Scope: Everything, all parameters, extensive examples.\nLength: Detailed sections, comprehensive coverage.\nMaintenance: Higher update complexity.",
+  },
+  aiDecide: {
+    name: "Let AI decide",
+    description: "Analyze code complexity and suggest appropriate depth",
+    content:
+      "Scope: Adaptive based on codebase analysis.\nAI considers: API surface area, complexity, existing patterns.",
+  },
+};
+
+// Purpose to Knowledge Level mapping for default suggestions
+export const PURPOSE_TO_KNOWLEDGE_MAPPING = {
+  getStarted: "completeBeginners", // Get started → Complete beginners
+  findAnswers: "experiencedUsers", // Find answers → Experienced users
+  solveProblems: "emergencyTroubleshooting", // Solve problems → Emergency/troubleshooting
+  exploringEvaluating: "exploringEvaluating", // Exploring → Exploring/evaluating
+};
+
+// Documentation Depth recommendation logic
+export const DEPTH_RECOMMENDATION_LOGIC = {
+  // Purpose-based recommendations (highest priority)
+  purposes: {
+    getStarted: "essentialOnly", // Get started → Essential
+  },
+  // Audience-based recommendations (medium priority)
+  audiences: {
+    decisionMakers: "balancedCoverage", // Decision makers → Balanced
+  },
+  // Knowledge level-based recommendations (lowest priority)
+  knowledgeLevels: {
+    experiencedUsers: "comprehensive", // Experienced users → Comprehensive
+  },
 };
 
 // Component mount point ID for Discuss Kit
 export const DISCUSS_KIT_DID = "z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu";
+
+// Discuss Kit related URLs
+export const DISCUSS_KIT_STORE_URL =
+  "https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu";
+export const BLOCKLET_ADD_COMPONENT_DOCS =
+  "https://www.arcblock.io/docs/blocklet-developer/en/7zbw0GQXgcD6sCcjVfwqqT2s";
+
+// Conflict rules configuration for documentation generation
+export const CONFLICT_RULES = {
+  // Internal conflicts within the same question (multi-select conflicts)
+  internalConflicts: {
+    documentPurpose: [
+      {
+        conflictItems: ["getStarted", "findAnswers"],
+        severity: "severe",
+        reason:
+          "Quick start guide (skips complex cases) conflicts with comprehensive API reference (skips beginner explanations)",
+        suggestion: "Choose one as primary goal, or consider creating layered documentation",
+      },
+      {
+        conflictItems: ["getStarted", "understandSystem"],
+        severity: "severe",
+        reason: "30-minute quick start conflicts with deep architectural concept explanations",
+        suggestion: "Consider creating separate quick start and architecture design docs",
+      },
+      {
+        conflictItems: ["completeTasks", "understandSystem"],
+        severity: "moderate",
+        reason:
+          "Practical task guidance and theoretical concept explanation have different focuses",
+        suggestion:
+          "Can be handled through layered document structure: concepts first, then practice",
+      },
+      {
+        conflictItems: ["getStarted", "solveProblems"],
+        severity: "moderate",
+        reason:
+          "Quick start (success cases) and troubleshooting (error scenarios) have different focuses",
+        suggestion: "Create separate tutorial and troubleshooting guides",
+      },
+      {
+        conflictItems: ["findAnswers", "solveProblems"],
+        severity: "moderate",
+        reason: "API reference and diagnostic documentation have different organizational logic",
+        suggestion: "Add troubleshooting section to reference documentation",
+      },
+    ],
+    targetAudienceTypes: [
+      {
+        conflictItems: ["endUsers", "developers"],
+        severity: "severe",
+        reason:
+          "Non-technical users (avoid technical terms) conflict with developers (code-first approach)",
+        suggestion:
+          "Create separate documentation for different audiences or use layered content design",
+      },
+      {
+        conflictItems: ["endUsers", "devops"],
+        severity: "severe",
+        reason: "Non-technical users and operations technical personnel have very different needs",
+        suggestion: "Consider creating separate user guides and operations documentation",
+      },
+      {
+        conflictItems: ["endUsers", "decisionMakers"],
+        severity: "severe",
+        reason:
+          "Non-technical users (simple language) and decision makers (architecture diagrams) have different needs",
+        suggestion: "Create high-level overview for management and user operation manuals",
+      },
+      {
+        conflictItems: ["developers", "decisionMakers"],
+        severity: "moderate",
+        reason:
+          "Developers (code details) and decision makers (high-level overview) have different focus areas",
+        suggestion: "Use progressive disclosure: high-level first, then details",
+      },
+      {
+        conflictItems: ["supportTeams", "decisionMakers"],
+        severity: "moderate",
+        reason:
+          "Support teams (problem diagnosis) and decision makers (architecture decisions) have different focus areas",
+        suggestion: "Include operational considerations in decision documentation",
+      },
+    ],
+  },
+
+  // Cross-question conflicts (conflicts between different questions)
+  crossConflicts: [
+    {
+      conditions: {
+        documentPurpose: ["getStarted"],
+        readerKnowledgeLevel: ["experiencedUsers"],
+      },
+      severity: "severe",
+      reason:
+        "Quick start tutorials are not suitable for experienced users who need advanced features and best practices",
+      action: "filter",
+      conflictingOptions: {
+        readerKnowledgeLevel: ["experiencedUsers"],
+      },
+    },
+    {
+      conditions: {
+        documentPurpose: ["findAnswers"],
+        readerKnowledgeLevel: ["completeBeginners"],
+      },
+      severity: "severe",
+      reason:
+        "API reference documentation skips beginner explanations and is not suitable for complete beginners",
+      action: "filter",
+      conflictingOptions: {
+        readerKnowledgeLevel: ["completeBeginners"],
+      },
+    },
+    {
+      conditions: {
+        documentPurpose: ["understandSystem"],
+        readerKnowledgeLevel: ["emergencyTroubleshooting"],
+      },
+      severity: "severe",
+      reason:
+        "System architecture explanations are not suitable for emergency troubleshooting scenarios",
+      action: "filter",
+      conflictingOptions: {
+        readerKnowledgeLevel: ["emergencyTroubleshooting"],
+      },
+    },
+    {
+      conditions: {
+        targetAudienceTypes: ["endUsers"],
+        readerKnowledgeLevel: ["experiencedUsers"],
+      },
+      severity: "severe",
+      reason: "Non-technical users are typically not experienced technical users",
+      action: "filter",
+      conflictingOptions: {
+        readerKnowledgeLevel: ["experiencedUsers"],
+      },
+    },
+    {
+      conditions: {
+        targetAudienceTypes: ["decisionMakers"],
+        readerKnowledgeLevel: ["emergencyTroubleshooting"],
+      },
+      severity: "severe",
+      reason: "Decision makers typically do not directly handle emergency technical failures",
+      action: "filter",
+      conflictingOptions: {
+        readerKnowledgeLevel: ["emergencyTroubleshooting"],
+      },
+    },
+    {
+      conditions: {
+        documentPurpose: ["getStarted"],
+        documentationDepth: ["comprehensive"],
+      },
+      severity: "severe",
+      reason: "Quick start tutorials contradict comprehensive coverage documentation",
+      action: "filter",
+      conflictingOptions: {
+        documentationDepth: ["comprehensive"],
+      },
+    },
+    {
+      conditions: {
+        documentPurpose: ["solveProblems"],
+        documentationDepth: ["essentialOnly"],
+      },
+      severity: "moderate",
+      reason:
+        "Troubleshooting usually needs to cover edge cases, basic content alone may not be sufficient",
+      action: "filter",
+      conflictingOptions: {
+        documentationDepth: ["essentialOnly"],
+      },
+    },
+    {
+      conditions: {
+        targetAudienceTypes: ["endUsers"],
+        documentationDepth: ["comprehensive"],
+      },
+      severity: "moderate",
+      reason: "Non-technical users typically do not need comprehensive technical coverage",
+      action: "filter",
+      conflictingOptions: {
+        documentationDepth: ["comprehensive"],
+      },
+    },
+    {
+      conditions: {
+        targetAudienceTypes: ["decisionMakers"],
+        documentationDepth: ["essentialOnly"],
+      },
+      severity: "moderate",
+      reason: "Decision makers may need more comprehensive information to make decisions",
+      action: "filter",
+      conflictingOptions: {
+        documentationDepth: ["essentialOnly"],
+      },
+    },
+    {
+      conditions: {
+        readerKnowledgeLevel: ["completeBeginners"],
+        documentationDepth: ["essentialOnly"],
+      },
+      severity: "moderate",
+      reason: "Complete beginners may need more explanations, not just core content",
+      action: "filter",
+      conflictingOptions: {
+        documentationDepth: ["essentialOnly"],
+      },
+    },
+  ],
+};

package/utils/markdown-checker.mjs

@@ -335,6 +335,20 @@ export async function checkMarkdown(markdown, source = "content", options = {})
           }
         }
 
+        // 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) {
+          const label = numberMatch[1] || numberMatch[2];
+          // Check if the label contains numbered list format
+          if (/\d+\.\s/.test(label)) {
+            errorMessages.push(
+              `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`,
+            );
+          }
+        }
+
         // Check for special characters in node labels that should be quoted
         const nodeWithSpecialCharsRegex = /([A-Za-z0-9_]+)\[([^\]]*[(){}:;,\-\s.][^\]]*)\]/g;
         let specialCharMatch;

package/utils/utils.mjs

@@ -2,9 +2,16 @@ import { execSync } from "node:child_process";
 import { accessSync, constants, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import chalk from "chalk";
 import { parse } from "yaml";
-import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_INCLUDE_PATTERNS } from "./constants.mjs";
+import {
+  DEFAULT_EXCLUDE_PATTERNS,
+  DEFAULT_INCLUDE_PATTERNS,
+  DOCUMENT_STYLES,
+  TARGET_AUDIENCES,
+  READER_KNOWLEDGE_LEVELS,
+  DOCUMENTATION_DEPTH,
+  SUPPORTED_LANGUAGES,
+} from "./constants.mjs";
 
 /**
  * Normalize path to absolute path for consistent comparison
@@ -94,7 +101,6 @@ export async function saveDocWithTranslations({
 
       await fs.writeFile(mainFilePath, finalContent, "utf8");
       results.push({ path: mainFilePath, success: true });
-      console.log(chalk.green(`Saved: ${chalk.cyan(mainFilePath)}`));
     }
 
     // Process all translations
@@ -113,7 +119,6 @@ export async function saveDocWithTranslations({
 
       await fs.writeFile(translatePath, finalTranslationContent, "utf8");
       results.push({ path: translatePath, success: true });
-      console.log(chalk.green(`Saved: ${chalk.cyan(translatePath)}`));
     }
   } catch (err) {
     results.push({ path: docPath, success: false, error: err.message });
@@ -703,3 +708,144 @@ export async function getProjectInfo() {
     fromGitHub,
   };
 }
+
+/**
+ * Process configuration fields - convert keys to actual content
+ * @param {Object} config - Parsed configuration
+ * @returns {Object} Processed configuration with content fields
+ */
+export function processConfigFields(config) {
+  const processed = {};
+  const allRulesContent = [];
+
+  // Check if original rules field has content
+  const existingRules = config.rules?.trim();
+  if (existingRules) {
+    allRulesContent.push(existingRules);
+  }
+
+  // Process document purpose (array)
+  let purposeContents = "";
+  if (config.documentPurpose && Array.isArray(config.documentPurpose)) {
+    purposeContents = config.documentPurpose
+      .map((key) => DOCUMENT_STYLES[key]?.content)
+      .filter(Boolean)
+      .join("\n\n");
+
+    if (purposeContents) {
+      allRulesContent.push(purposeContents);
+    }
+  }
+
+  // Process target audience types (array)
+  let audienceContents = "";
+  let audienceNames = "";
+  if (config.targetAudienceTypes && Array.isArray(config.targetAudienceTypes)) {
+    // Get content for rules
+    audienceContents = config.targetAudienceTypes
+      .map((key) => TARGET_AUDIENCES[key]?.content)
+      .filter(Boolean)
+      .join("\n\n");
+
+    // Get names for targetAudience field
+    audienceNames = config.targetAudienceTypes
+      .map((key) => TARGET_AUDIENCES[key]?.name)
+      .filter(Boolean)
+      .join(", ");
+
+    if (audienceContents) {
+      allRulesContent.push(audienceContents);
+    }
+
+    if (audienceNames) {
+      // Check if original targetAudience field has content
+      const existingTargetAudience = config.targetAudience?.trim();
+      const newAudienceNames = audienceNames;
+
+      if (existingTargetAudience) {
+        processed.targetAudience = `${existingTargetAudience}\n\n${newAudienceNames}`;
+      } else {
+        processed.targetAudience = newAudienceNames;
+      }
+    }
+  }
+
+  // Process reader knowledge level (single value)
+  let knowledgeContent = "";
+  if (config.readerKnowledgeLevel) {
+    knowledgeContent = READER_KNOWLEDGE_LEVELS[config.readerKnowledgeLevel]?.content;
+    if (knowledgeContent) {
+      processed.readerKnowledgeContent = knowledgeContent;
+      allRulesContent.push(`Reader Knowledge Level:\n${knowledgeContent}`);
+    }
+  }
+
+  // Process documentation depth (single value)
+  let depthContent = "";
+  if (config.documentationDepth) {
+    depthContent = DOCUMENTATION_DEPTH[config.documentationDepth]?.content;
+    if (depthContent) {
+      processed.documentationDepthContent = depthContent;
+      allRulesContent.push(`Documentation Depth:\n${depthContent}`);
+    }
+  }
+
+  // Combine all content into rules field
+  if (allRulesContent.length > 0) {
+    processed.rules = allRulesContent.join("\n\n");
+  }
+
+  return processed;
+}
+
+/**
+ * Detect system language and map to supported language code
+ * @returns {string} - Supported language code (defaults to 'en' if detection fails or unsupported)
+ */
+export function detectSystemLanguage() {
+  try {
+    // Try multiple methods to detect system language
+    let systemLocale = null;
+
+    // Method 1: Environment variables (most reliable on Unix systems)
+    systemLocale = process.env.LANG || process.env.LANGUAGE || process.env.LC_ALL;
+
+    // Method 2: Node.js Intl API (fallback)
+    if (!systemLocale) {
+      try {
+        systemLocale = Intl.DateTimeFormat().resolvedOptions().locale;
+      } catch (_error) {
+        // Intl API failed, continue to fallback
+      }
+    }
+
+    if (!systemLocale) {
+      return "en"; // Default fallback
+    }
+
+    // Extract language code from locale (e.g., 'zh_CN' -> 'zh', 'en_US' -> 'en')
+    const langCode = systemLocale.split(/[-_]/)[0].toLowerCase();
+
+    // Map to supported language codes
+    const supportedLang = SUPPORTED_LANGUAGES.find((lang) => lang.code === langCode);
+    if (supportedLang) {
+      return supportedLang.code;
+    }
+
+    // Handle special cases for Chinese variants
+    if (langCode === "zh") {
+      // Check for Traditional Chinese indicators
+      const fullLocale = systemLocale.toLowerCase();
+      if (fullLocale.includes("tw") || fullLocale.includes("hk") || fullLocale.includes("mo")) {
+        return "zh-TW";
+      }
+      return "zh"; // Default to Simplified Chinese
+    }
+
+    // Return default if no match found
+    return "en";
+  } catch (_error) {
+    // Any error in detection, return default
+    return "en";
+  }
+}