@aigne/doc-smith 0.5.1 → 0.7.0

package/utils/constants.mjs

@@ -86,15 +86,27 @@ export const DEFAULT_INCLUDE_PATTERNS = [
   "*.yml",
   "*Dockerfile",
   "*Makefile",
+  // Media files
+  "*.jpg",
+  "*.jpeg",
+  "*.png",
+  "*.gif",
+  "*.bmp",
+  "*.webp",
+  "*.svg",
+  "*.mp4",
+  "*.mov",
+  "*.avi",
+  "*.mkv",
+  "*.webm",
+  "*.m4v",
 ];
 
 export const DEFAULT_EXCLUDE_PATTERNS = [
   "**/aigne-docs/**",
   "**/doc-smith/**",
   "**/.aigne/**",
-  "**/assets/**",
   "**/data/**",
-  "**/images/**",
   "**/public/**",
   "**/static/**",
   "**/vendor/**",
@@ -331,79 +343,8 @@ export const SUPPORTED_FILE_EXTENSIONS = [".txt", ".md", ".json", ".yaml", ".yml
 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",
-      },
-    ],
+    // Note: Most conflicts can be resolved through intelligent document structure planning
+    // Only keeping conflicts that represent fundamental incompatibilities
   },
 
   // Cross-question conflicts (conflicts between different questions)
@@ -471,66 +412,138 @@ export const CONFLICT_RULES = {
         readerKnowledgeLevel: ["emergencyTroubleshooting"],
       },
     },
+  ],
+};
+
+// Conflict resolution rules - defines how to handle conflicts when users select conflicting options
+export const CONFLICT_RESOLUTION_RULES = {
+  // Document purpose conflicts that can be resolved through structure planning
+  documentPurpose: [
     {
-      conditions: {
-        documentPurpose: ["getStarted"],
-        documentationDepth: ["comprehensive"],
-      },
-      severity: "severe",
-      reason: "Quick start tutorials contradict comprehensive coverage documentation",
-      action: "filter",
-      conflictingOptions: {
-        documentationDepth: ["comprehensive"],
-      },
+      conflictItems: ["getStarted", "findAnswers"],
+      strategy: "layered_structure",
+      description: "Quick start and API reference conflict, resolved through layered structure",
     },
     {
-      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"],
-      },
+      conflictItems: ["getStarted", "understandSystem"],
+      strategy: "separate_sections",
+      description:
+        "Quick start and system understanding conflict, resolved through separate sections",
     },
     {
-      conditions: {
-        targetAudienceTypes: ["endUsers"],
-        documentationDepth: ["comprehensive"],
-      },
-      severity: "moderate",
-      reason: "Non-technical users typically do not need comprehensive technical coverage",
-      action: "filter",
-      conflictingOptions: {
-        documentationDepth: ["comprehensive"],
-      },
+      conflictItems: ["completeTasks", "understandSystem"],
+      strategy: "concepts_then_practice",
+      description:
+        "Task guidance and system understanding conflict, resolved through concepts-then-practice structure",
     },
     {
-      conditions: {
-        targetAudienceTypes: ["decisionMakers"],
-        documentationDepth: ["essentialOnly"],
-      },
-      severity: "moderate",
-      reason: "Decision makers may need more comprehensive information to make decisions",
-      action: "filter",
-      conflictingOptions: {
-        documentationDepth: ["essentialOnly"],
-      },
+      conflictItems: ["findAnswers", "solveProblems"],
+      strategy: "reference_with_troubleshooting",
+      description:
+        "API reference and problem solving conflict, resolved through reference with troubleshooting",
     },
+  ],
+
+  // Target audience conflicts that can be resolved through structure planning
+  targetAudienceTypes: [
     {
-      conditions: {
-        readerKnowledgeLevel: ["completeBeginners"],
-        documentationDepth: ["essentialOnly"],
-      },
-      severity: "moderate",
-      reason: "Complete beginners may need more explanations, not just core content",
-      action: "filter",
-      conflictingOptions: {
-        documentationDepth: ["essentialOnly"],
-      },
+      conflictItems: ["endUsers", "developers"],
+      strategy: "separate_user_paths",
+      description: "End users and developers conflict, resolved through separate user paths",
+    },
+    {
+      conflictItems: ["endUsers", "devops"],
+      strategy: "role_based_sections",
+      description: "End users and DevOps conflict, resolved through role-based sections",
+    },
+    {
+      conflictItems: ["developers", "decisionMakers"],
+      strategy: "progressive_disclosure",
+      description:
+        "Developers and decision makers conflict, resolved through progressive disclosure",
     },
   ],
 };
+
+// Resolution strategy descriptions
+export const RESOLUTION_STRATEGIES = {
+  layered_structure: (items) =>
+    `Detected "${items.join('" and "')}" purpose conflict. Resolution strategy: Create layered document structure
+- Quick start section: Uses "get started" style - optimizes for speed, key steps, working examples, skips complex edge cases
+- API reference section: Uses "find answers" style - comprehensive coverage, searchability, rich examples, skips narrative flow
+- Ensure sections complement rather than conflict with each other`,
+
+  separate_sections: (items) =>
+    `Detected "${items.join('" and "')}" purpose conflict. Resolution strategy: Create separate sections
+- Quick start section: Uses "get started" style - focuses on practical operations, completable within 30 minutes
+- System understanding section: Uses "understand system" style - dedicated to explaining architecture, concepts, design decision rationale
+- Meet different depth needs through clear section separation`,
+
+  concepts_then_practice: (items) =>
+    `Detected "${items.join('" and "')}" purpose conflict. Resolution strategy: Use progressive "concepts-then-practice" structure
+- Concepts section: Uses "understand system" style - first explains core concepts and architecture principles
+- Practice section: Uses "complete tasks" style - then provides specific step guidance and practical scenarios
+- Ensure smooth transition between theory and practice`,
+
+  reference_with_troubleshooting: (items) =>
+    `Detected "${items.join('" and "')}" purpose conflict. Resolution strategy: Integrate troubleshooting into API reference
+- API reference section: Uses "find answers" style - comprehensive feature documentation and parameter descriptions
+- Troubleshooting section: Uses "solve problems" style - add common issues and diagnostic methods for each feature
+- Create dedicated problem diagnosis index for quick location`,
+
+  separate_user_paths: (items) =>
+    `Detected "${items.join('" and "')}" audience conflict. Resolution strategy: Create separate user paths
+- User guide path: Uses "end users" style - simple language, UI operations, screenshot instructions, business outcome oriented
+- Developer guide path: Uses "developers" style - code-first, technical precision, SDK examples, configuration snippets
+- Provide clear path navigation for users to choose appropriate entry point`,
+
+  role_based_sections: (items) =>
+    `Detected "${items.join('" and "')}" audience conflict. Resolution strategy: Organize content by role
+- Create dedicated sections for different roles, each section uses corresponding audience style
+- Ensure content depth and expression precisely match the needs and background of corresponding audience
+- Provide cross-references between sections to facilitate collaborative understanding between roles`,
+
+  progressive_disclosure: (items) =>
+    `Detected "${items.join('" and "')}" audience conflict. Resolution strategy: Use progressive information disclosure
+- Overview level: Uses "decision makers" style - high-level architecture diagrams, decision points, business value
+- Detail level: Uses "developers" style - technical implementation details, code examples, best practices
+- Ensure smooth transition from strategic to tactical`,
+};
+
+export const D2_CONFIG = `vars: {
+  d2-config: {
+    layout-engine: elk
+    theme-id: 0
+    theme-overrides: {
+      N1: "#2AA7A1"
+      N2: "#73808C"
+
+      N4: "#FFFFFF"
+      N5: "#FAFBFC"
+
+      N7: "#ffffff"
+
+      B1: "#8EDDD9"
+      B2: "#C9DCE6"
+      B3: "#EEF9F9"
+      B4: "#F7F8FA"
+      B5: "#FCFDFD"
+      B6: "#E3E9F0"
+
+
+      AA2: "#9EB7C5"
+      AA4: "#E3EBF2"
+      AA5: "#F6FAFC"
+
+      AB4: "#B8F1F6"
+      AB5: "#E3F8FA"
+    }
+  }
+}`;
+
+export const KROKI_CONCURRENCY = 5;
+export const FILE_CONCURRENCY = 3;
+export const TMP_DIR = ".tmp";
+export const TMP_DOCS_DIR = "docs";
+
+export const TMP_ASSETS_DIR = "assets";

package/utils/kroki-utils.mjs

@@ -0,0 +1,162 @@
+import path from "node:path";
+
+import fs from "fs-extra";
+import { glob } from "glob";
+import pMap from "p-map";
+import { joinURL } from "ufo";
+
+import {
+  D2_CONFIG,
+  FILE_CONCURRENCY,
+  KROKI_CONCURRENCY,
+  TMP_ASSETS_DIR,
+  TMP_DIR,
+} from "./constants.mjs";
+import { getContentHash } from "./utils.mjs";
+
+export async function getChart({ chart = "d2", format = "svg", content, strict }) {
+  const baseUrl = "https://chart.abtnet.io";
+
+  try {
+    const res = await fetch(joinURL(baseUrl, chart, format), {
+      method: "POST",
+      body: content,
+      headers: {
+        Accept: "image/svg+xml",
+        "Content-Type": "text/plain",
+      },
+    });
+    if (strict && !res.ok) {
+      throw new Error(`Failed to fetch chart: ${res.status} ${res.statusText}`);
+    }
+
+    const data = await res.text();
+    return data;
+  } catch (err) {
+    if (strict) throw err;
+
+    console.error("Failed to generate chart from:", baseUrl, err);
+    return null;
+  }
+}
+
+export async function getD2Svg({ content, strict = false }) {
+  const svgContent = await getChart({
+    chart: "d2",
+    format: "svg",
+    content,
+    strict,
+  });
+  return svgContent;
+}
+
+// Helper: save d2 svg assets alongside document
+export async function saveD2Assets({ markdown, docsDir }) {
+  const codeBlockRegex = /```d2\n([\s\S]*?)```/g;
+
+  const { replaced } = await runIterator({
+    input: markdown,
+    regexp: codeBlockRegex,
+    replace: true,
+    fn: async ([_match, _code]) => {
+      const assetDir = path.join(docsDir, "../", TMP_ASSETS_DIR, "d2");
+      await fs.ensureDir(assetDir);
+      const d2Content = [D2_CONFIG, _code].join("\n");
+      const fileName = `${getContentHash(d2Content)}.svg`;
+      const svgPath = path.join(assetDir, fileName);
+
+      if (await fs.pathExists(svgPath)) {
+        if (process.env.DEBUG) {
+          console.log("Found assets cache, skipping generation", svgPath);
+        }
+      } else {
+        if (process.env.DEBUG) {
+          console.log("start generate d2 chart", svgPath);
+        }
+        try {
+          const svg = await getD2Svg({ content: d2Content });
+          if (svg) {
+            await fs.writeFile(svgPath, svg, { encoding: "utf8" });
+          }
+        } catch (error) {
+          if (process.env.DEBUG) {
+            console.warn("Failed to generate D2 chart:", error);
+          }
+          return _code;
+        }
+      }
+      return `![](../${TMP_ASSETS_DIR}/d2/${fileName})`;
+    },
+    options: { concurrency: KROKI_CONCURRENCY },
+  });
+
+  return replaced;
+}
+
+export async function beforePublishHook({ docsDir }) {
+  // Example: process each markdown file (replace with your logic)
+  const mdFilePaths = await glob("**/*.md", { cwd: docsDir });
+  await pMap(
+    mdFilePaths,
+    async (filePath) => {
+      let finalContent = await fs.readFile(path.join(docsDir, filePath), { encoding: "utf8" });
+      finalContent = await saveD2Assets({ markdown: finalContent, docsDir });
+
+      await fs.writeFile(path.join(docsDir, filePath), finalContent, { encoding: "utf8" });
+    },
+    { concurrency: FILE_CONCURRENCY },
+  );
+}
+
+async function runIterator({ input, regexp, fn = () => {}, options, replace = false }) {
+  if (!input) return input;
+  const matches = [...input.matchAll(regexp)];
+  const results = [];
+  await pMap(
+    matches,
+    async (...args) => {
+      const resultItem = await fn(...args);
+      results.push(resultItem);
+    },
+    options,
+  );
+
+  let replaced = input;
+  if (replace) {
+    let index = 0;
+    replaced = replaced.replace(regexp, () => {
+      return results[index++];
+    });
+  }
+
+  return {
+    results,
+    replaced,
+  };
+}
+
+export async function checkD2Content({ content }) {
+  await ensureTmpDir();
+  const assetDir = path.join(".aigne", "doc-smith", TMP_DIR, TMP_ASSETS_DIR, "d2");
+  await fs.ensureDir(assetDir);
+  const d2Content = [D2_CONFIG, content].join("\n");
+  const fileName = `${getContentHash(d2Content)}.svg`;
+  const svgPath = path.join(assetDir, fileName);
+  if (await fs.pathExists(svgPath)) {
+    if (process.env.DEBUG) {
+      console.log("Found assets cache, skipping generation", svgPath);
+    }
+    return;
+  }
+
+  const svg = await getD2Svg({ content: d2Content, strict: true });
+  await fs.writeFile(svgPath, svg, { encoding: "utf8" });
+}
+
+export async function ensureTmpDir() {
+  const tmpDir = path.join(".aigne", "doc-smith", TMP_DIR);
+  if (!(await fs.pathExists(path.join(tmpDir, ".gitignore")))) {
+    await fs.ensureDir(tmpDir);
+    await fs.writeFile(path.join(tmpDir, ".gitignore"), "**/*", { encoding: "utf8" });
+  }
+}