@aigne/doc-smith 0.8.2 → 0.8.4

package/prompts/document/detail-generator.md

@@ -15,9 +15,6 @@
 - 说明要尽可能的详细，如果存在配置项或参数，需要解释每个配置项或参数的含义，如果参数有多个可选值，每种可选值需要解释其含义，并尽可能配上代码示例
 - 参数优先使用 markdown 中的 table 来展示，让内容看上去更整齐，容易阅读
 - 接口/方法调用的说明必须包含 **响应数据示例**
-- 尽可能少的使用 d2 图表，图表中错误的逻辑会导致文档效果更差，绘制 d2 的图表一定要确保可读性和正确性
-- 概览部分，建议包含 d2 图表展示产品架构图
-{% include "d2-chart/rules.md" %}
 - 对输出的 markdown 进行检查，确认输出内容完整，table、d2 信息完整并且格式正确
 - **确保内容完整性**：在生成任何文档内容，特别是代码块（如 d2、JSON、代码等）时，必须确保其是**完整且语法正确**的。在输出完成后，必须进行一次**自我检查**，确认所有的代码块、列表、表格等都已完全闭合且没有中途截断。
 - **代码块原子性**：将每个代码块（例如 ```d2 ... ```）视为一个**不可分割的原子单元**。必须一次性完整生成，从开始标记（```d2）到结束标记（```）之间的所有内容都不能省略或截断。
@@ -29,6 +26,13 @@
 
 </document_rules>
 
+<document_rules>
+
+D2 Diagram Generation Expert Guide:
+{% include "d2-chart/rules.md" %}
+
+</document_rules>
+
 <TONE_STYLE>
 - Documentation should be plain, rigorous and accurate, avoiding grandiose or empty vocabulary
 - You are writing for humans, not algorithms
@@ -42,54 +46,4 @@
   - Use contractions and idioms sparingly to maintain an informal, yet credible tone
   - Blend technical precision with relatable language
   - Be direct: say what happened, why it matters, and how it helps
-
-Example Tone Transformations
-❌ "We’re thrilled to announce our most powerful update yet…"
-✅ "You can now include location and timestamp metadata for each claim, enabling audit-ready transparency."
-
-❌ "Unlock the future of verification."
-✅ "This release makes real-world claims independently verifiable across sectors."
 </TONE_STYLE>
-
-<WORDS_PHRASES_TO_AVOID>
-
-Do not use promotional fluff or filler emotion. Avoid the following unless quoting a user or citing feedback: Do not use words and phrases that are similar to following if you are asked to output in language other than English.
-
-<emotion-words>
-  excited
-  thrilled
-  delighted
-  proud to announce
-  happy to share
-  Overused Adjectives:
-  powerful
-  seamless
-  revolutionary
-  robust
-  amazing
-  significant
-  transformative
-  innovative
-  disruptive
-  groundbreaking
-</emotion-words>
-
-<generic-hype-verbs>
-  unlock
-  unleash
-  empower
-  elevate
-  reimagine
-  transform
-  Empty Marketing Phrases:
-  in today's world
-  at the end of the day
-  best practices
-  end-to-end
-  game changer
-  cutting edge
-</generic-hype-verbs>
-
-➡️ Instead, focus on concrete outcomes and observable benefits.
-Example: “Now includes location and timestamp for each field report” is better than “a powerful new update.”
-</WORDS_PHRASES_TO_AVOID>

package/tests/kroki-utils.test.mjs

@@ -1,9 +1,12 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdtemp, rmdir } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 
+import Debug from "debug";
+
+import { TMP_ASSETS_DIR } from "../utils/constants.mjs";
 import {
   beforePublishHook,
   checkD2Content,
@@ -238,20 +241,33 @@ E -> F
 
     test("should skip generation if SVG file already exists", async () => {
       const docsDir = path.join(tempDir, "docs");
-      const assetsDir = path.join(docsDir, "../assets/d2");
-      await mkdir(assetsDir, { recursive: true });
-
+      await mkdir(docsDir, { recursive: true });
       const markdown = `\`\`\`d2\nA -> B\n\`\`\``;
 
-      // Pre-create a cached SVG file
-      const testSvgContent = "<svg>test</svg>";
-      await writeFile(path.join(assetsDir, "test.svg"), testSvgContent);
+      // 1. First run to generate the file
+      await saveD2Assets({ markdown, docsDir });
 
-      // This would normally generate the same filename for the same content
-      const result = await saveD2Assets({ markdown, docsDir });
+      // 2. Second run to check if cache is used
+      const debugLogs = [];
+      const originalWrite = process.stderr.write;
+      process.stderr.write = (chunk) => {
+        debugLogs.push(chunk.toString());
+        return true;
+      };
+      Debug.enable("doc-smith");
 
-      expect(typeof result).toBe("string");
-      expect(result).toContain("![](../assets/d2/");
+      try {
+        const result = await saveD2Assets({ markdown, docsDir });
+
+        expect(typeof result).toBe("string");
+        expect(result).toContain(`![](${path.posix.join("..", TMP_ASSETS_DIR, "d2")}`);
+        expect(
+          debugLogs.some((log) => log.includes("Found assets cache, skipping generation")),
+        ).toBe(true);
+      } finally {
+        process.stderr.write = originalWrite;
+        Debug.disable();
+      }
     });
 
     test("should handle D2 generation errors gracefully", async () => {
@@ -273,6 +289,28 @@ E -> F
         global.fetch = originalFetch;
       }
     });
+
+    test("should write .d2 file when debug is enabled", async () => {
+      const docsDir = path.join(tempDir, "docs");
+      await mkdir(docsDir, { recursive: true });
+
+      const markdown = `\`\`\`d2\nA -> B\n\`\`\``;
+
+      // Enable debug mode
+      Debug.enable("doc-smith");
+
+      try {
+        await saveD2Assets({ markdown, docsDir });
+
+        const assetDir = path.join(docsDir, "../", TMP_ASSETS_DIR, "d2");
+        const files = await readdir(assetDir);
+        const d2File = files.find((file) => file.endsWith(".d2"));
+        expect(d2File).toBeDefined();
+      } finally {
+        // Restore debug mode
+        Debug.disable();
+      }
+    });
   });
 
   describe("beforePublishHook", () => {
@@ -350,13 +388,29 @@ E -> F
       // First call should generate
       await checkD2Content({ content });
 
-      // Second call should use cache (should be faster)
-      const startTime = Date.now();
-      await checkD2Content({ content });
-      const endTime = Date.now();
+      // Second call should use cache
+      const debugLogs = [];
+      const originalWrite = process.stderr.write;
+      process.stderr.write = (chunk) => {
+        debugLogs.push(chunk.toString());
+        return true;
+      };
+      Debug.enable("doc-smith");
 
-      // Cache hit should be very fast (< 100ms)
-      expect(endTime - startTime).toBeLessThan(100);
+      try {
+        const startTime = Date.now();
+        await checkD2Content({ content });
+        const endTime = Date.now();
+
+        // Cache hit should be very fast (< 100ms)
+        expect(endTime - startTime).toBeLessThan(100);
+        expect(
+          debugLogs.some((log) => log.includes("Found assets cache, skipping generation")),
+        ).toBe(true);
+      } finally {
+        process.stderr.write = originalWrite;
+        Debug.disable();
+      }
     });
 
     test("should handle generation errors in strict mode", async () => {
@@ -391,6 +445,23 @@ E -> F
         expect(error).toBeDefined();
       }
     });
+
+    test("should write .d2 file when debug is enabled", async () => {
+      const content = "A -> B: debug test";
+
+      Debug.enable("doc-smith");
+
+      try {
+        await checkD2Content({ content });
+
+        const assetDir = path.join(process.cwd(), ".aigne", "doc-smith", ".tmp", "assets", "d2");
+        const files = await readdir(assetDir);
+        const d2File = files.find((file) => file.endsWith(".d2"));
+        expect(d2File).toBeDefined();
+      } finally {
+        Debug.disable();
+      }
+    });
   });
 
   describe("ensureTmpDir", () => {

package/utils/constants.mjs

@@ -513,7 +513,21 @@ export const RESOLUTION_STRATEGIES = {
 export const D2_CONFIG = `vars: {
   d2-config: {
     layout-engine: elk
-    theme-id: 8
+    theme-id: 105
+    theme-overrides: {
+      N1: "#18181B"
+      N2: "#421E0B"
+      N4: "#E6E8EC"
+      N5: "#E6E8EC"
+
+      B3: "#FFE9D1"
+      B4: "transparent"
+
+      AA2: "#421E0B"
+      AA4: "#FFE9D1"
+
+      AB4: "#FBF4E4"
+    }
   }
 }`;
 

package/utils/kroki-utils.mjs

@@ -1,5 +1,6 @@
 import path from "node:path";
 
+import Debug from "debug";
 import fs from "fs-extra";
 import { glob } from "glob";
 import pMap from "p-map";
@@ -14,6 +15,8 @@ import {
 } from "./constants.mjs";
 import { getContentHash } from "./utils.mjs";
 
+const debug = Debug("doc-smith");
+
 export async function getChart({ chart = "d2", format = "svg", content, strict }) {
   const baseUrl = "https://chart.abtnet.io";
 
@@ -56,7 +59,7 @@ export async function saveD2Assets({ markdown, docsDir }) {
     return markdown;
   }
 
-  const codeBlockRegex = /```d2\n([\s\S]*?)```/g;
+  const codeBlockRegex = /```d2.*\n([\s\S]*?)```/g;
 
   const { replaced } = await runIterator({
     input: markdown,
@@ -70,26 +73,26 @@ export async function saveD2Assets({ markdown, docsDir }) {
       const svgPath = path.join(assetDir, fileName);
 
       if (await fs.pathExists(svgPath)) {
-        if (process.env.DEBUG) {
-          console.log("Found assets cache, skipping generation", svgPath);
-        }
+        debug("Found assets cache, skipping generation", svgPath);
       } else {
-        if (process.env.DEBUG) {
-          console.log("start generate d2 chart", svgPath);
-        }
         try {
+          debug("start generate d2 chart", svgPath);
+          if (debug.enabled) {
+            const d2FileName = `${getContentHash(d2Content)}.d2`;
+            const d2Path = path.join(assetDir, d2FileName);
+            await fs.writeFile(d2Path, d2Content, { encoding: "utf8" });
+          }
+
           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);
-          }
+          debug("Failed to generate D2 chart:", error);
           return _code;
         }
       }
-      return `![](../${TMP_ASSETS_DIR}/d2/${fileName})`;
+      return `![](${path.posix.join("..", TMP_ASSETS_DIR, "d2", fileName)})`;
     },
     options: { concurrency: KROKI_CONCURRENCY },
   });
@@ -146,10 +149,15 @@ export async function checkD2Content({ content }) {
   const d2Content = [D2_CONFIG, content].join("\n");
   const fileName = `${getContentHash(d2Content)}.svg`;
   const svgPath = path.join(assetDir, fileName);
+
+  if (debug.enabled) {
+    const d2FileName = `${getContentHash(d2Content)}.d2`;
+    const d2Path = path.join(assetDir, d2FileName);
+    await fs.writeFile(d2Path, d2Content, { encoding: "utf8" });
+  }
+
   if (await fs.pathExists(svgPath)) {
-    if (process.env.DEBUG) {
-      console.log("Found assets cache, skipping generation", svgPath);
-    }
+    debug("Found assets cache, skipping generation", svgPath);
     return;
   }
 

package/utils/markdown-checker.mjs

@@ -243,7 +243,7 @@ function checkLocalImages(markdown, source, errorMessages, markdownFilePath, bas
  */
 function checkContentStructure(markdown, source, errorMessages) {
   const lines = markdown.split("\n");
-  const allCodeBlockRegex = /^\s*```(?:[a-zA-Z0-9_,\-+.#/:=]+)?$/;
+  const allCodeBlockRegex = /^\s*```.*$/;
 
   // State variables for different checks
   let inCodeBlock = false;

package/utils/utils.mjs

@@ -1158,6 +1158,7 @@ export function detectSystemLanguage() {
   }
 }
 
-export function getContentHash(str) {
-  return crypto.createHash("sha256").update(str).digest("hex");
+export function getContentHash(str, { trim = true } = {}) {
+  const input = trim && typeof str === "string" ? str.trim() : str;
+  return crypto.createHash("sha256").update(input).digest("hex");
 }

package/prompts/document/d2-chart/diy-examples.md

@@ -1,44 +0,0 @@
-- 结构图示例：
-  ```d2
-  App: Application
-  API: API Server
-  DB: Database
-
-  App -> API: 调用
-  API -> DB: 读写数据
-  ```
-- 流程图示例：
-  ```d2
-  start: 开始
-  input: 用户输入
-  process: 处理数据
-  output: 输出结果
-  end: 结束
-
-  start -> input -> process -> output -> end
-  ```
-- 时序图示例：
-  ```d2
-  User: 用户
-  Service: 服务
-  DB: 数据库
-
-  User -> Service: 请求
-  Service -> DB: 查询
-  DB -> Service: 返回数据
-  Service -> User: 响应
-  ```
-- 决策树示例：
-  ```d2
-  start: 开始
-  check: 是否有效？
-  yes: 是
-  no: 否
-  end: 结束
-
-  start -> check
-  check -> yes: 有效
-  check -> no: 无效
-  yes -> end
-  no -> end
-  ```

package/prompts/document/d2-chart/shape-rules.md

@@ -1,182 +0,0 @@
-# D2 图表绘制 Shape 选择指南与 Prompt 模板
-
-## 一、D2 Shape 类型与使用场景
-
-### 基础 Shape 类型
-- **rectangle** (默认): 通用节点、组件、系统模块
-- **square**: 数据库、存储、配置项
-- **circle**: 用户、角色、状态节点
-- **oval**: 开始/结束节点、事件
-- **diamond**: 决策节点、条件判断
-- **parallelogram**: 输入/输出、数据流
-- **hexagon**: 准备、预处理步骤
-- **cylinder**: 数据库、数据存储
-- **queue**: 消息队列、缓冲区
-- **package**: 模块、包、容器
-- **step**: 流程步骤
-- **callout**: 注释、说明
-- **stored_data**: 存储的数据
-- **person**: 用户、角色
-- **diamond**: 判断、网关
-- **document**: 文档、报告
-- **multiple_document**: 多个文档
-- **class**: 类定义
-- **sql_table**: 数据库表
-- **image**: 图片、媒体
-
-## 二、针对不同图表类型的 Prompt 模板
-
-### 1. 系统架构图 Prompt
-```
-请使用 D2 语法绘制系统架构图，遵循以下 shape 选择规则：
-- 用户/角色使用 person 或 circle
-- 前端应用使用 rectangle
-- API/服务使用 rectangle 
-- 数据库使用 cylinder 或 sql_table
-- 缓存使用 queue
-- 外部服务使用 package
-- 负载均衡器使用 diamond
-
-示例结构：
-用户 -> 前端 -> API网关 -> 微服务 -> 数据库
-```
-
-### 2. 流程图 Prompt
-```
-请使用 D2 语法绘制流程图，严格按照以下 shape 约定：
-- 开始/结束节点：oval
-- 处理步骤：rectangle
-- 判断节点：diamond
-- 输入/输出：parallelogram
-- 准备步骤：hexagon
-- 文档生成：document
-- 数据存储：cylinder
-
-连接线使用箭头表示流向，判断节点要标注 yes/no 分支。
-```
-
-### 3. 数据流图 Prompt
-```
-使用 D2 绘制数据流图，shape 选择原则：
-- 外部实体：square
-- 数据处理：circle
-- 数据存储：stored_data 或 cylinder
-- 数据流：带标签的箭头连接
-- 数据文件：document
-
-确保数据流方向清晰，标注数据类型和流向。
-```
-
-### 4. 组织架构图 Prompt
-```
-创建组织架构图，使用以下 D2 shape 规范：
-- 高层管理：person (设置较大尺寸)
-- 部门负责人：person
-- 团队/部门：package
-- 具体角色：circle
-- 外部合作方：rectangle (虚线边框)
-
-使用层次布局，体现汇报关系。
-```
-
-## 三、通用优化 Prompt 模板
-
-### 基础模板
-```
-请使用 D2 语法创建 [图表类型]，要求：
-
-1. **Shape 选择原则**：
-   - 根据元素功能选择最合适的 shape
-   - 保持同类元素使用相同 shape
-   - 重要元素可以使用特殊 shape 突出
-
-2. **样式要求**：
-   - 使用合适的颜色区分不同类型的元素
-   - 重要路径使用加粗或特殊颜色
-   - 添加适当的标签和注释
-
-3. **布局优化**：
-   - 使用合理的布局算法 (dagre, elk等)
-   - 避免连线交叉
-   - 保持整体美观和可读性
-
-4. **语法规范**：
-   - 使用正确的 D2 语法
-   - 节点命名简洁明了
-   - 连接关系清晰表达
-
-请提供完整的 D2 代码。
-```
-
-### 高级定制模板
-```
-创建专业级 D2 图表，具体要求：
-
-**图表信息**：[描述你要创建的图表]
-
-**定制要求**：
-1. **Shape 策略**：
-   - 为每种元素类型指定最佳 shape
-   - 列出 shape 选择理由
-   - 确保视觉一致性
-
-2. **颜色方案**：
-   - 使用企业级配色
-   - 不同模块用不同颜色区分
-   - 突出关键路径
-
-3. **高级功能**：
-   - 添加图标 (如需要)
-   - 使用容器分组相关元素
-   - 添加交互提示 (tooltip)
-
-4. **性能考虑**：
-   - 节点数量控制在合理范围
-   - 避免过于复杂的嵌套
-
-输出格式：
-- D2 代码
-- Shape 选择说明
-- 使用建议
-```
-
-## 四、特定场景 Prompt 示例
-
-### 网络拓扑图
-```
-绘制网络拓扑图，shape 使用规范：
-- 路由器：diamond
-- 交换机：rectangle  
-- 服务器：rectangle (填充色)
-- 终端设备：circle
-- 防火墙：hexagon
-- 云服务：package
-- 网络连接：实线
-- 无线连接：虚线
-```
-
-### 微服务架构图
-```
-设计微服务架构图：
-- API Gateway：diamond
-- 微服务：rectangle
-- 数据库：cylinder
-- 缓存：queue
-- 消息队列：queue (不同颜色)
-- 负载均衡：parallelogram
-- 监控服务：circle
-- 外部服务：package (虚线边框)
-```
-
-### 业务流程图
-```
-业务流程建模：
-- 开始事件：oval (绿色)
-- 结束事件：oval (红色)  
-- 用户任务：rectangle
-- 系统任务：rectangle (不同颜色)
-- 网关决策：diamond
-- 并行网关：diamond (特殊标记)
-- 数据对象：document
-- 消息流：虚线箭头
-```