@aigne/doc-smith 0.9.7-beta → 0.9.7-beta.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.9.7-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.7-beta...v0.9.7-beta.1) (2025-11-27)
+
+
+### Bug Fixes
+
+* **ci:** ensure pipeline fails on test failures ([#328](https://github.com/AIGNE-io/aigne-doc-smith/issues/328)) ([56fb4d5](https://github.com/AIGNE-io/aigne-doc-smith/commit/56fb4d5259a21a6cf76f67c6ac5a43a7c1403b99))
+* supports admonition syntax ([#338](https://github.com/AIGNE-io/aigne-doc-smith/issues/338)) ([db19661](https://github.com/AIGNE-io/aigne-doc-smith/commit/db19661e1c2d654181d932e0834e7e011a3ad8a5))
+
 ## [0.9.7-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.6...v0.9.7-beta) (2025-11-25)
 
 

package/agents/create/merge-diagram.yaml

@@ -36,5 +36,4 @@ output_schema:
       type: string
       description: Merged content of the document with D2 diagram
   required:
-    - content
-
+    - content

package/agents/update/check-document.mjs

@@ -87,7 +87,8 @@ export default async function checkDocument(
       contentValidationFailed = true;
     }
   }
-  const languages = translates.map((x) => x.language);
+  const translateList = Array.isArray(translates) ? translates : [];
+  const languages = translateList.map((x) => x.language);
   const lackLanguages = new Set(languages);
   const skills = [];
 
@@ -140,7 +141,7 @@ export default async function checkDocument(
 
   const result = await options.context.invoke(teamAgent, {
     ...rest,
-    translates: translates.filter((x) => lackLanguages.has(x.language)),
+    translates: translateList.filter((x) => lackLanguages.has(x.language)),
     locale,
     docsDir,
     path,

package/agents/update/check-generate-diagram.mjs

@@ -1,4 +1,4 @@
-import { DIAGRAM_PLACEHOLDER } from "../../utils/d2-utils.mjs";
+import { DIAGRAM_PLACEHOLDER, replacePlaceholderWithD2 } from "../../utils/d2-utils.mjs";
 
 const DEFAULT_DIAGRAMMING_EFFORT = 5;
 const MIN_DIAGRAMMING_EFFORT = 0;
@@ -68,7 +68,10 @@ export default async function checkGenerateDiagram(
 
     if (diagramSourceCode && !skipGenerateDiagram) {
       if (content.includes(DIAGRAM_PLACEHOLDER)) {
-        content = content.replace(DIAGRAM_PLACEHOLDER, diagramSourceCode);
+        content = replacePlaceholderWithD2({
+          content,
+          diagramSourceCode,
+        });
       } else {
         const mergeAgent = options.context?.agents?.["mergeDiagramToDocument"];
         ({ content } = await options.context.invoke(mergeAgent, {

package/agents/update/update-single/update-single-document-detail.mjs

@@ -1,7 +1,11 @@
 import { AIAgent } from "@aigne/core";
 import { pick } from "@aigne/core/utils/type-utils.js";
 import z from "zod";
-import { DIAGRAM_PLACEHOLDER, replacePlaceholder } from "../../../utils/d2-utils.mjs";
+import {
+  DIAGRAM_PLACEHOLDER,
+  replaceD2WithPlaceholder,
+  replacePlaceholderWithD2,
+} from "../../../utils/d2-utils.mjs";
 import { userContextAt } from "../../../utils/utils.mjs";
 
 async function getIntentType(input, options) {
@@ -64,7 +68,7 @@ async function addDiagram(input, options) {
 async function updateDiagram(input, options) {
   const contentContext = userContextAt(options, `currentContents.${input.path}`);
   const currentContent = contentContext.get();
-  let [content, previousDiagramContent] = replacePlaceholder({
+  let [content, previousDiagramContent] = replaceD2WithPlaceholder({
     content: currentContent,
   });
   const generateAgent = options.context?.agents?.["generateDiagram"];
@@ -74,7 +78,10 @@ async function updateDiagram(input, options) {
     previousDiagramContent,
     feedback: input.feedback,
   });
-  content = content.replace(DIAGRAM_PLACEHOLDER, diagramSourceCode);
+  content = replacePlaceholderWithD2({
+    content,
+    diagramSourceCode,
+  });
   contentContext.set(content);
   await saveDoc(input, options, { content });
   return { content };
@@ -83,7 +90,7 @@ async function updateDiagram(input, options) {
 async function deleteDiagram(input, options) {
   const contentContext = userContextAt(options, `currentContents.${input.path}`);
   const currentContent = contentContext.get();
-  const [documentContent] = replacePlaceholder({
+  const [documentContent] = replaceD2WithPlaceholder({
     content: currentContent,
   });
   const instructions = `<role>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.9.7-beta",
+  "version": "0.9.7-beta.1",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
@@ -24,10 +24,10 @@
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "Elastic-2.0",
   "dependencies": {
-    "@aigne/cli": "^1.54.1",
-    "@aigne/core": "^1.67.0",
-    "@aigne/publish-docs": "^0.13.1",
-    "@blocklet/payment-broker-client": "^1.22.12",
+    "@aigne/cli": "^1.56.0",
+    "@aigne/core": "^1.69.0",
+    "@aigne/publish-docs": "^0.14.1",
+    "@blocklet/payment-broker-client": "^1.22.24",
     "@terrastruct/d2": "^0.1.33",
     "chalk": "^5.5.0",
     "debug": "^4.4.1",
@@ -66,10 +66,12 @@
     "@biomejs/biome": "^2.2.4"
   },
   "scripts": {
-    "test": "bun test",
-    "test:coverage2": "bun test --coverage",
-    "test:coverage": "bun test --coverage --coverage-reporter=lcov --coverage-reporter=text",
-    "test:watch": "bun test --watch",
+    "test": "bun test --preload ./tests/setup/mock-process-exit.mjs",
+    "test:coverage2": "bun test --preload ./tests/setup/mock-process-exit.mjs --coverage",
+    "test:coverage": "bun test --preload ./tests/setup/mock-process-exit.mjs --coverage --coverage-reporter=lcov --coverage-reporter=text",
+    "test:deploy": "bun test --preload ./tests/setup/mock-process-exit.mjs tests/utils/deploy.test.mjs --coverage --coverage-reporter=text",
+    "test:user-review": "bun test --preload ./tests/setup/mock-process-exit.mjs tests/agents/update/user-review-document.test.mjs --coverage --coverage-reporter=lcov --coverage-reporter=text",
+    "test:watch": "bun test --preload ./tests/setup/mock-process-exit.mjs --watch",
     "lint": "biome lint && biome format",
     "update:deps": "npx -y taze major -r -w -f -n '/@abtnode|@aigne|@arcblock|@blocklet|@did-connect|@did-pay|@did-space|@nft-store|@nft-studio|@ocap/' && pnpm install && pnpm run deduplicate",
     "deduplicate": "pnpm dedupe",

package/prompts/common/document/markdown-syntax-rules.md

@@ -0,0 +1,65 @@
+<markdown_syntax_rules>
+
+## Markdown Syntax Standard
+
+### Allowed Syntax
+
+**Inline** (used within text):
+
+- Emphasis: `**bold**`, `*italic*`, `~~strikethrough~~`
+- Links: `[text](url)`
+- Images: `![alt](url)`
+- Inline Code: `` `code` ``
+
+**Block** (standalone blocks):
+
+- Headings: `#`, `##`, `###`, etc.
+- Lists: `- item`, `1. item`
+- Task Lists: `- [ ]`, `- [x]`
+- Blockquotes: `> quote`
+- Code Block: ` ```language ... ``` `
+- Tables: `| col | col |` with `|---|---|` separator
+- Horizontal Rule: `---`
+- Admonition: `:::severity ... :::`
+
+### Prohibited Syntax
+
+The following are **strictly forbidden**:
+
+- Footnotes: `[^1]: note text`
+- Math/LaTeX: `$inline$`, `$$ block $$`
+- Highlight: `==highlighted==`
+- Subscript/Superscript: `H~2~O`, `X^2^`
+- Abbreviations: `*[HTML]: Hyper Text Markup Language`
+
+### Link Rules
+
+- Links must reference valid external URLs or paths from the document structure
+- Use absolute paths from the documentation structure for internal links
+
+### Table Formatting Rules
+
+- Separator row (`|---|---|---|`) must match the exact column count of header row
+- Each row must have the same number of columns
+- Use tables for predefined values (e.g., status types, options) or term definitions
+- Validate table structure before output
+
+### Code Block Rules
+
+- Ensure code blocks are properly closed
+- Generate complete, syntactically correct code (JSON, etc.)
+- Perform self-validation to ensure all code blocks, lists, and tables are properly closed without truncation
+
+### Block-Level Elements
+
+Block-level elements are standalone content blocks that must be visually separated from surrounding content.
+
+Block-Level Element List:
+
+- Admonition: `:::severity ... :::`
+- Code Block: ` ```language ... ``` `
+- Custom Components: `<x-cards>`, `<x-card>`, `<x-field-group>`, etc.
+
+**Spacing Rule:** Always insert a blank line before and after any block-level element when it is **adjacent to** other Markdown content (headings, paragraphs, lists, etc.).
+
+</markdown_syntax_rules>

package/prompts/detail/custom/admonition-usage-rules.md

@@ -0,0 +1,94 @@
+<admonition_syntax_rules>
+
+## Admonition Syntax Rules
+
+Admonition is a Markdown block extension used to highlight important information. Use it sparingly.
+
+### Syntax Structure
+
+```
+:::severity
+content
+:::
+```
+
+### Syntax Rules
+
+The `severity` is **required** and must be one of the following:
+
+- `success`: Positive outcome or best practice
+- `info`: General tips
+- `warning`: Cautions or potential issues
+- `error`: Critical risks or breaking operations
+
+The `content` is **required** and MUST strictly comply with the rules below:
+
+- The `content` MUST be plain text only
+- The `content` MUST be a single paragraph (no line breaks).
+- Nesting any blocks or Admonitions is forbidden.
+- Recommended length: within 200 characters.
+
+### Usage Guidelines
+
+- Use sparingly, only for messages that truly require user attention
+- Do not use Admonition if the content needs any Markdown syntax from <markdown_syntax_rules> — use regular paragraphs instead
+- Keep the text short, clear, and actionable
+- Choose the severity level according to the importance of the message
+
+### Good Examples
+
+1. All four severity types:
+
+```md
+:::success
+Your configuration is complete.
+:::
+
+:::info
+Environment variables can override this setting.
+:::
+
+:::warning
+This API will be removed in v3.0.
+:::
+
+:::error
+Never commit API keys to version control.
+:::
+```
+
+### Bad Examples
+1. Contains Markdown Syntax:
+
+```md
+:::info
+No **bold**, *italic*, or `inline code` allowed.
+:::
+
+:::warning
+No [links](https://example.com) allowed.
+:::
+
+:::info
+- No lists
+- Or bullet points
+:::
+
+:::error
+```sh
+npm i
+```
+:::
+```
+
+2. Multi-paragraph:
+
+```md
+:::warning
+No multi-paragraph.
+
+Like this.
+:::
+```
+
+</admonition_syntax_rules>

package/prompts/detail/custom/custom-components/x-card-usage-rules.md

@@ -18,7 +18,7 @@ XCard is individual link display card, suitable for displaying individual links
 ### Children
 
 - Must be written within `<x-card>...</x-card>` children.
-- **Plain Text Only**: All markdown formatting is prohibited, including inline formats like `code`, **bold**, _italic_, [links](), and block-level formats like headers (# ##), lists (- \*), code blocks (```), tables (|), and any other markdown syntax. Only plain text content is allowed.
+- Plain Text Only: Do not use any Markdown syntax (see `<markdown_syntax_rules>` for the full list).
 
 ### Good Examples
 

package/prompts/detail/custom/custom-components/x-field-desc-usage-rules.md

@@ -17,6 +17,11 @@ XFieldDesc is rich field description. Used to provide rich text descriptions for
 ### Usage Rules
 
 - **Parent Requirement**: Must be child of `<x-field>`: `<x-field-desc>` can only appear as a child element of `<x-field>` components
+- **Avoid Redundant Information**: Do not repeat information in `<x-field-desc>` that is already expressed by the parent `<x-field>` attributes. Specifically:
+  - **Required Status**: Do not mention "required" or "optional" in descriptions since `data-required` attribute already indicates this
+  - **Default Values**: Do not repeat default values in descriptions since `data-default` attribute already shows this
+  - **Deprecated Status**: Do not mention "deprecated" in descriptions since `data-deprecated` attribute already indicates this
+  - Focus descriptions on the field's purpose, format, constraints, example values, and usage guidance instead
 
 ### Good Examples
 
@@ -83,4 +88,33 @@ XFieldDesc is rich field description. Used to provide rich text descriptions for
   </x-field-group>
   ```
 
+- Example 7: Redundant required information in description (violates "Avoid Redundant Information" rule)
+  ```md
+  <x-field-group>
+    <x-field data-name="api_key" data-type="string" data-required="true">
+      <x-field-desc markdown>Your **API key** for authentication. **This field is required.**</x-field-desc>
+    </x-field>
+    <x-field data-name="timeout" data-type="number" data-required="false" data-default="5000">
+      <x-field-desc markdown>Request timeout in milliseconds. **Optional**, defaults to `5000`.</x-field-desc>
+    </x-field>
+    <x-field data-name="old_api" data-type="string" data-deprecated="true">
+      <x-field-desc markdown>Old API endpoint. **This field is deprecated.**</x-field-desc>
+    </x-field>
+  </x-field-group>
+  ```
+  **Correct approach:**
+  ```md
+  <x-field-group>
+    <x-field data-name="api_key" data-type="string" data-required="true">
+      <x-field-desc markdown>Your **API key** for authentication. Generate one from the `Settings > API Keys` section.</x-field-desc>
+    </x-field>
+    <x-field data-name="timeout" data-type="number" data-required="false" data-default="5000">
+      <x-field-desc markdown>Request timeout in milliseconds.</x-field-desc>
+    </x-field>
+    <x-field data-name="old_api" data-type="string" data-deprecated="true">
+      <x-field-desc markdown>Old API endpoint. Use the new endpoint instead.</x-field-desc>
+    </x-field>
+  </x-field-group>
+  ```
+
 </x-field-desc-usage-rules>

package/prompts/detail/custom/custom-components/x-field-group-usage-rules.md

@@ -15,7 +15,6 @@ XFieldGroup is `<x-field>` grouping container. Used to group multiple related `<
 
 - **Top-Level Only**: Used only at the top level for grouping related `<x-field>` elements. Cannot be nested inside other `<x-field>` or `<x-field-group>` elements
 - **Structured Data Only**: Use `<x-field-group>` for fields **other than simple types** (`string`, `number`, `boolean`, `symbol`), e.g., Properties, Context, Parameters, Return values. For simple-type fields, use plain Markdown text.
-- **Spacing Around**: Always insert a blank line before and after `<x-field-group>` when it’s adjacent to Markdown content.
 
 ### Good Examples
 
@@ -78,18 +77,4 @@ XFieldGroup is `<x-field>` grouping container. Used to group multiple related `<
   </x-field-group>
   ```
 
-- Example 6: Missing blank line before x-field-group (violates "Spacing Around" rule)
-  ```md
-  **Parameters**
-  <x-field-group>
-    <x-field data-name="initialState" data-type="any" data-required="false">
-      <x-field-desc markdown>The initial state value.</x-field-desc>
-    </x-field>
-  </x-field-group>
-
-  `useReducer` returns an array with two items:
-  <x-field-group>
-    <x-field data-name="dispatch" data-type="function" data-desc="A function that you can call with an action to update the state."></x-field>
-  </x-field-group>
-  ```
 </x-field-group-usage-rules>

package/prompts/detail/custom/custom-components/x-field-usage-rules.md

@@ -10,7 +10,7 @@ XField is structured data field, suitable for displaying API parameters, return
 - `data-default` (optional): Default value for the field
 - `data-required` (optional): Whether the field is required ("true" or "false")
 - `data-deprecated` (optional): Whether the field is deprecated ("true" or "false")
-- `data-desc` (optional): Simple description of the field (plain text only)
+- `data-desc` (optional): Simple description of the field. Do not use any Markdown syntax (see `<markdown_syntax_rules>` for the full list).
 
 ### Children
 

package/prompts/detail/generate/document-rules.md

@@ -1,6 +1,8 @@
 
 <document_rules>
 
+{% include "../../common/document/markdown-syntax-rules.md" %}
+
 Documentation Generation Rules:
 - **Opening Hook Requirement:** The document must begin with a compelling, relaxed, and concise introductory paragraph (The "Hook").
 - **Hook Content:** This paragraph must clearly state the specific outcome, knowledge, or skill the reader will gain upon completing the document (Preferably 50 words or less).
@@ -13,9 +15,6 @@ Documentation Generation Rules:
 - Since API names are already specified in document titles, avoid repeating them in subheadings—use sub-API names directly
 - Include links to related documents in the introduction using Markdown format to help users navigate to relevant content
 - Add links to further reading materials in the summary section using Markdown format
-- **Markdown Syntax Constraint**: Use only GitHub Flavored Markdown (GFM) syntax by default. Prohibited extensions include: custom blocks `:::`, footnotes `[^1]: notes`, math formulas `$$ LaTeX`, highlighted text `==code==`, and other non-GFM syntax unless explicitly defined in custom component rules
-- Use proper Markdown link syntax, for example: [Next Chapter Title](next_chapter_path)
-- **Ensure next_chapter_path references either external URLs or valid paths from the documentation structure**—use absolute paths from the documentation structure
 - When detailDataSource includes third-party links, incorporate them appropriately throughout the document
 - Structure each section with: title, introduction, code examples, response data samples, and explanatory notes. Place explanations directly after code examples without separate "Example Description" subheadings
 - Maintain content completeness and logical flow so users can follow the documentation seamlessly
@@ -23,10 +22,6 @@ Documentation Generation Rules:
 - All interface and method documentation must include **response data examples**
 - **Use `<x-field-group>` for all structured data**: Represent objects with nested `<x-field>` elements, and expand each structure to the **deepest relevant level**.
 - **Enhance field descriptions with example values**: For structured data defined using `<x-field-group>`, extract example values from type definitions, comments, or test cases to make documentation more practical and user-friendly.
-- **Use Markdown tables** for predefined values (e.g., status types, options) or term definitions to improve clarity and allow side-by-side comparison.
-- Validate output Markdown for completeness, ensuring tables are properly formatted
-- **Content Integrity**: Generate complete, syntactically correct code blocks (JSON, etc.). Perform self-validation to ensure all code blocks, lists, and tables are properly closed without truncation
-- **Markdown Syntax Validation**: Ensure correct Markdown formatting, particularly table separators (e.g., `|---|---|---|`) that match column counts
 - Use README files for reference only—extract the most current and comprehensive information directly from source code
 - Omit tag information from document headers as it's processed programmatically
 - Parse `jsx` syntax correctly when present in code samples

package/prompts/detail/generate/system-prompt.md

@@ -42,6 +42,8 @@ Documentation content generation rules:
 
 {% include "../custom/code-block-usage-rules.md" %}
 
+{% include "../custom/admonition-usage-rules.md" %}
+
 {% include "../../common/document/media-file-list-usage-rules.md" %}
 
 {% include "../../common/document/openapi-usage-rules.md" %}

package/prompts/detail/update/system-prompt.md

@@ -68,6 +68,8 @@ Documentation content optimization rules:
 
 {% include "../custom/code-block-usage-rules.md" %}
 
+{% include "../custom/admonition-usage-rules.md" %}
+
 {% include "../../common/document/media-file-list-usage-rules.md" %}
 
 {% include "../../common/document/openapi-usage-rules.md" %}

package/prompts/translate/admonition.md

@@ -0,0 +1,20 @@
+<admonition_rules>
+
+Admonition blocks use the following format:
+
+```
+:::severity
+
+text
+
+:::
+```
+
+Admonition Translation Rules:
+
+- **Translate** the text content only
+- **Do not translate** the severity keyword (success, info, warning, error)
+- **Preserve** the `:::` syntax and block structure
+
+</admonition_rules>
+

package/prompts/translate/translate-document.md

@@ -24,6 +24,8 @@ Translation Requirements:
 - Translate Descriptions Only in <x-field>: All `<x-field>` component attributes must maintain the original format. Only translate the description content within `data-desc` attribute or `<x-field-desc>` elements.
 
 {% include "./code-block.md" %}
+
+{% include "./admonition.md" %}
 </translation_rules>
 
 {% if feedback %}

package/utils/constants/index.mjs

@@ -1,5 +1,5 @@
 // Default file patterns for inclusion and exclusion
-export const DEFAULT_INCLUDE_PATTERNS = [
+export const DEFAULT_INCLUDE_PATTERNS = Object.freeze([
   // Python
   "*.py",
   "*.pyi",
@@ -100,9 +100,9 @@ export const DEFAULT_INCLUDE_PATTERNS = [
   "*.mkv",
   "*.webm",
   "*.m4v",
-];
+]);
 
-export const DEFAULT_EXCLUDE_PATTERNS = [
+export const DEFAULT_EXCLUDE_PATTERNS = Object.freeze([
   "**/doc-smith/**",
   "**/.aigne/**",
   "**/vendor/**",
@@ -130,7 +130,7 @@ export const DEFAULT_EXCLUDE_PATTERNS = [
   "**/bun.lockb",
   "**/bun.lock",
   "**/bun.lockb",
-];
+]);
 
 // Supported languages for documentation
 export const SUPPORTED_LANGUAGES = [

package/utils/d2-utils.mjs

@@ -206,7 +206,12 @@ export function wrapCode({ content }) {
   return `\`\`\`d2\n${content}\n\`\`\``;
 }
 
-export function replacePlaceholder({ content }) {
+/**
+ * Replaces D2 code block with DIAGRAM_PLACEHOLDER.
+ * @param {string} content - Document content containing D2 code block
+ * @returns {Array} - [contentWithPlaceholder, originalCodeBlock]
+ */
+export function replaceD2WithPlaceholder({ content }) {
   const [firstMatch] = Array.from(content.matchAll(codeBlockRegex));
   if (firstMatch) {
     const matchContent = firstMatch[0];
@@ -216,3 +221,37 @@ export function replacePlaceholder({ content }) {
 
   return [content, ""];
 }
+
+/**
+ * Replaces DIAGRAM_PLACEHOLDER with D2 code block, ensuring proper spacing.
+ * @param {string} content - Document content containing DIAGRAM_PLACEHOLDER
+ * @param {string} diagramSourceCode - D2 diagram source code (without markdown wrapper)
+ * @returns {string} - Content with placeholder replaced by code block
+ */
+export function replacePlaceholderWithD2({ content, diagramSourceCode }) {
+  if (!content || !diagramSourceCode) {
+    return content;
+  }
+
+  const placeholderIndex = content.indexOf(DIAGRAM_PLACEHOLDER);
+  if (placeholderIndex === -1) {
+    return content;
+  }
+
+  // Check if placeholder has newlines around it
+  const beforePlaceholder = content.substring(0, placeholderIndex);
+  const afterPlaceholder = content.substring(placeholderIndex + DIAGRAM_PLACEHOLDER.length);
+
+  const codeBlock = wrapCode({ content: diagramSourceCode });
+
+  // Add newlines if missing
+  let replacement = codeBlock;
+  if (beforePlaceholder && !beforePlaceholder.endsWith("\n")) {
+    replacement = `\n${replacement}`;
+  }
+  if (afterPlaceholder && !afterPlaceholder.startsWith("\n")) {
+    replacement = `${replacement}\n`;
+  }
+
+  return content.replace(DIAGRAM_PLACEHOLDER, replacement);
+}