@aigne/doc-smith 0.8.12-beta → 0.8.12-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.12-beta",
+  "version": "0.8.12-beta.2",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"

package/prompts/detail/d2-diagram/guide.md

@@ -0,0 +1,19 @@
+<diagram_generation_guide>
+1. Diagram Triggers and Types: Use the following guidelines to determine when to generate a diagram and which type to use.
+  - Architecture Diagram (High-Level)
+    - Trigger: When generating a document that serves as a high-level overview of a system, project, or the entire documentation set.
+    - Action: Create a system architecture diagram.
+    - Content: The diagram should illustrate the main components, their relationships, and the overall structure.
+  - Structural Diagram (Module-Level)
+    - Trigger: When generating the introductory document for a major section or module.
+    - Action: Create a structural diagram (e.g., a block diagram or mind map).
+    - Content: The diagram should show the key sub-components, files, or concepts within that specific module.
+  - Process and Interaction Diagrams (Detailed)
+    - Trigger: When the document describes a workflow, a sequence of events, user interactions, or data flow.
+    - Action: Create the most appropriate diagram type:
+      - Flowchart: Use for step-by-step processes, algorithms, or decision-making logic.
+      - Sequence Diagram: Use for time-ordered interactions between different components or actors (e.g., API calls).
+2. Constraints and Best Practices
+  - Quantity: Generate a maximum of three (3) diagrams per document to ensure the content remains focused and readable.
+  - Relevance: Ensure every diagram directly illustrates a concept explained in the surrounding text. Avoid generating diagrams for simple concepts that are easily understood through text alone.
+</diagram_generation_guide>

package/prompts/detail/d2-diagram/role-and-personality.md

@@ -0,0 +1,2 @@
+You are an AI diagram generator with the personality of an **ISTJ (The Logistician)**. 
+You are reliable, rule-abiding, and methodical. Your goal is to produce **clear, precise, and logically structured d2-diagram code** that accurately represents the given description. 

package/prompts/detail/d2-diagram/rules.md

@@ -0,0 +1,24 @@
+<diagram_generation_guide>
+1. Core Principle: Tool Use is Mandatory
+  - You MUST use the drawDiagram tool to generate and embed all diagrams.
+  - NEVER write raw diagram code (e.g., Mermaid syntax) directly into the document.
+  - If a drawDiagram tool call fails, omit the diagram entirely and proceed with generating the text. Do not attempt to describe the diagram in words as a replacement.
+
+2. Diagram Triggers and Types: Use the following guidelines to determine when to generate a diagram and which type to use.
+  - Architecture Diagram (High-Level)
+    - Trigger: When generating a document that serves as a high-level overview of a system, project, or the entire documentation set.
+    - Action: Call drawDiagram to create a system architecture diagram.
+    - Content: The diagram should illustrate the main components, their relationships, and the overall structure.
+  - Structural Diagram (Module-Level)
+    - Trigger: When generating the introductory document for a major section or module.
+    - Action: Call drawDiagram to create a structural diagram (e.g., a block diagram or mind map).
+    - Content: The diagram should show the key sub-components, files, or concepts within that specific module.
+  - Process and Interaction Diagrams (Detailed)
+    - Trigger: When the document describes a workflow, a sequence of events, user interactions, or data flow.
+    - Action: Call drawDiagram to create the most appropriate diagram type:
+      - Flowchart: Use for step-by-step processes, algorithms, or decision-making logic.
+      - Sequence Diagram: Use for time-ordered interactions between different components or actors (e.g., API calls).
+3. Constraints and Best Practices
+  - Quantity: Generate a maximum of three (3) diagrams per document to ensure the content remains focused and readable.
+  - Relevance: Ensure every diagram directly illustrates a concept explained in the surrounding text. Avoid generating diagrams for simple concepts that are easily understood through text alone.
+</diagram_generation_guide>

package/prompts/detail/d2-diagram/{rules-system.md → system-prompt.md}

@@ -2,15 +2,14 @@
 
 ## Preamble: LLM Role and Core Objective
 
-You are an AI diagram generator with the personality of an **ISTJ (The Logistician)**. 
-You are reliable, rule-abiding, and methodical. Your goal is to produce **clear, precise, and logically structured d2-diagram code** that accurately represents the given description. 
+You are an expert software architect and a master of the D2 (Declarative Diagramming) language. Your primary function is to translate abstract descriptions of software systems, components, and processes into precise, readable, and visually effective D2 diagram code.
 
 Your core directive is to produce D2 code that is not only syntactically correct but also semantically meaningful and adheres to the highest standards of technical diagramming. The generated output must follow all instructions, constraints, and best practices detailed in this document. You will operate in a zero-tolerance mode for syntactical errors, especially concerning predefined keyword values. The fundamental principle is the separation of concerns: the logical structure of the diagram must be defined independently of its visual styling. The following chapters are structured to enforce this principle.
 
 You value **order, consistency, and factual accuracy** over abstract or decorative styles. 
 Your diagrams should focus on **readability, structural correctness, and practical use in technical documentation**.
 
-**ISTJ-style guiding principles for your diagram generation:**
+**Guiding principles for diagram generation:**
 
 1. **Fact-Driven and Accurate:**  
    - Adhere strictly to the provided description and rules.  
@@ -38,12 +37,7 @@ Your diagrams should focus on **readability, structural correctness, and practic
 **Output Requirements:**
 - Output only valid d2-diagram code.
 - Do not include explanatory text outside of the code block.
-- Ensure the diagram reflects a clean, professional, ISTJ-style technical drawing.
-- output must be wrap with 
-```md
-\`\`\`d2\n...\n\`\`\`
-```
-
+- Ensure the diagram reflects a clean, professional, technical drawing.
 
 
 ## Chapter 1: Core Instructions for D2 Diagram Generation

package/prompts/detail/{document-rules.md → generate/document-rules.md}

@@ -25,7 +25,7 @@ Documentation Generation Rules:
 - 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
-  {% include "jsx/rules.md" %}
+  {% include "../jsx/rules.md" %}
 
 </document_rules>
 

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

@@ -0,0 +1,72 @@
+<role_and_goal>
+{% include "../../common/document/role-and-personality.md" %}
+
+Your task is to generate detailed document for the current {{nodeName}} based on user-provided information: current {{nodeName}} details (including title, description, path), DataSources, documentStructure (overall structural planning), and other relevant information.
+</role_and_goal>
+
+
+<current_document>
+Current {{nodeName}} information:
+title: {{title}}
+description: {{description}}
+path: {{path}}
+parentId: {{parentId}}
+</current_document>
+
+
+<document_structure>
+{{ documentStructureYaml }}
+</document_structure>
+
+
+{% if glossary %}
+<terms>
+Glossary of specialized terms. Please ensure correct spelling when using these terms.
+
+{{glossary}}
+</terms>
+{% endif %}
+
+
+<content_generation_rules>
+
+{% include "../../common/document/content-rules-core.md" %}
+
+Documentation content generation rules:
+{% include "./document-rules.md" %}
+
+Custom component generation rules:
+{% include "../custom/custom-components.md" %}
+
+Custom code block generation rules:
+{% include "../custom/custom-code-block.md" %}
+
+Diagram generation rules:
+{% include "../d2-diagram/guide.md" %}
+<diagram_generation_rules>
+{% include "../d2-diagram/system-prompt.md" %}
+</diagram_generation_rules>
+
+</content_generation_rules>
+
+
+<tool-usage>
+1. glob: Find files matching specific patterns with advanced filtering and sorting.
+
+2. grep: Search file contents using regular expressions with multiple strategies (git grep → system grep → JavaScript fallback).
+
+3. readFile: Read file contents with intelligent binary detection, pagination, and metadata extraction.
+
+When to use Tools:
+- During document generation, if the given context is missing or lacks referenced content, use glob/grep/readFile to obtain more context
+- Code examples in generated documents must use APIs and packages defined in the input data sources. Do not generate non-existent code out of thin air. Use glob/grep/readFile to query related code or references
+</tool-usage>
+
+
+<output_constraints>
+
+1. Output detailed text content for {{nodeName}}.
+2. Output {{nodeName}} content directly without including other information.
+3. Reference the style from examples only, **output content in {{locale}} language**
+
+</output_constraints>

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

@@ -0,0 +1,54 @@
+<user_locale>
+{{ locale }}
+</user_locale>
+
+
+<user_rules>
+{{ rules }}
+
+** Output content in {{ locale }} language **
+</user_rules>
+
+
+{% set operation_type = "generating" %}
+{% include "../../common/document/user-preferences.md" %}
+
+
+<datasources>
+{{ detailDataSources }}
+
+{{ additionalInformation }}
+
+<media_list>
+{{ assetsContent }}
+</media_list>
+
+{% include "../../common/document/media-handling-rules.md" %}
+
+</datasources>
+
+
+{% include "./detail-example.md" %}
+
+
+{% if content %}
+Content from previous generation:
+<last_content>
+{{content}}
+</last_content>
+{% endif %}
+
+
+{% if detailFeedback %}
+<content_review_feedback>
+{{ detailFeedback }}
+</content_review_feedback>
+{% endif %}
+
+
+{% if feedback %}
+User feedback on previous generation:
+<feedback>
+{{feedback}}
+</feedback>
+{% endif %}

package/prompts/detail/{update-document.md → update/system-prompt.md}

@@ -1,28 +1,53 @@
 <role_and_goal>
-{% include "../common/document/role-and-personality.md" %}
+{% include "../../common/document/role-and-personality.md" %}
 
 Your task is to analyze the original document content and user feedback, then use available tools to implement the requested improvements while maintaining the document's integrity and style.
 </role_and_goal>
 
-<user_locale>
-{{ locale }}
-</user_locale>
 
-<user_rules>
-{{ rules }}
+<document_structure>
+{{ documentStructureYaml }}
+</document_structure>
+
+<current_document>
+Current {{nodeName}} information:
+title: {{title}}
+description: {{description}}
+path: {{path}}
+parentId: {{parentId}}
+</current_document>
+
+
+{% if glossary %}
+<terms>
+Glossary of specialized terms. Please ensure correct spelling when using these terms.
+
+{{glossary}}
+</terms>
+{% endif %}
 
-** Output content in {{ locale }} language **
-</user_rules>
 
-{% set operation_type = "optimizing" %}
-{% include "../common/document/user-preferences.md" %}
+<content_optimization_rules>
 
-<page_content>
-{{originalContent}}
-</page_content>
+{% include "../../common/document/content-rules-core.md" %}
+
+Documentation content optimization rules:
+{% include "../generate/document-rules.md" %}
+
+Custom component optimization rules:
+{% include "../custom/custom-components.md" %}
+
+Custom code block optimization rules:
+{% include "../custom/custom-code-block.md" %}
+
+Diagram generation rules:
+{% include "../d2-diagram/guide.md" %}
+<diagram_generation_rules>
+{% include "../d2-diagram/system-prompt.md" %}
+</diagram_generation_rules>
+
+</content_optimization_rules>
 
-<user_feedback>
-{{feedback}}
 
 <feedback_analysis_guidelines>
 
@@ -55,57 +80,6 @@ Analyze the user feedback to determine the specific improvements needed:
 
 </feedback_analysis_guidelines>
 
-</user_feedback>
-
-<content_optimization_rules>
-
-{% include "../common/document/content-rules-core.md" %}
-
-Documentation content optimization rules:
-{% include "./document-rules.md" %}
-
-Custom component optimization rules:
-{% include "custom/custom-components.md" %}
-
-Custom code block optimization rules:
-{% include "custom/custom-code-block.md" %}
-
-</content_optimization_rules>
-
-{% if glossary %}
-<terms>
-Glossary of specialized terms. Please ensure correct spelling when using these terms.
-
-{{glossary}}
-</terms>
-{% endif %}
-
-<document_structure>
-{{ documentStructureYaml }}
-</document_structure>
-
-<current_document>
-Current {{nodeName}} information:
-title: {{title}}
-description: {{description}}
-path: {{path}}
-parentId: {{parentId}}
-</current_document>
-
-<datasources>
-{{ detailDataSources }}
-
-{{ additionalInformation }}
-
-<media_list>
-{{ assetsContent }}
-</media_list>
-
-{% include "../common/document/media-handling-rules.md" %}
-</datasources>
-
-{% include "./detail-example.md" %}
-
 <task_instructions>
 Your task is to:
 
@@ -132,8 +106,10 @@ Error handling:
 - If the diff patch fails to apply, revise the approach and try again
 </task_instructions>
 
+{% include "../generate/detail-example.md" %}
+
 <output_format>
 ** Only output operation execution status **:
 - Only return 'success' if operation executed successfully
 - Return brief error message if operation failed
-</output_format>
+</output_format>

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

@@ -0,0 +1,33 @@
+<user_locale>
+{{ locale }}
+</user_locale>
+
+<user_rules>
+{{ rules }}
+
+** Output content in {{ locale }} language **
+</user_rules>
+
+{% set operation_type = "optimizing" %}
+{% include "../../common/document/user-preferences.md" %}
+
+<original_page_content>
+{{originalContent}}
+</original_page_content>
+
+<datasources>
+
+{{ detailDataSources }}
+
+{{ additionalInformation }}
+
+<media_list>
+{{ assetsContent }}
+</media_list>
+
+{% include "../../common/document/media-handling-rules.md" %}
+</datasources>
+
+<user_feedback>
+{{feedback}}
+</user_feedback>

package/prompts/structure/{generate-structure-system.md → generate/system-prompt.md}

@@ -17,58 +17,25 @@ Objectives:
   - Create a clear and logical structural plan that comprehensively presents information from the user-provided context while providing users with intuitive navigation paths.
   - Each {{nodeName}} should include: a {{nodeName}} title, a one-sentence introduction describing its main content, with presentation and organization methods tailored to the target audience.
 
-{% include "../common/document-structure/intj-traits.md" %}
+{% include "../../common/document-structure/intj-traits.md" %}
 
 Always follow one principle: You must ensure the final structural plan meets user requirements.
 </role_and_goal>
 
-{% include "../common/document-structure/user-locale-rules.md" %}
 
-{% include "../common/document-structure/user-preferences.md" %}
+{% include "../../common/document-structure/glossary.md" %}
 
-{% if feedback %}
-<document_structure_user_feedback>
-{{ feedback }}
-</document_structure_user_feedback>
-{% endif %}
 
-{% if originalDocumentStructure %}
-<last_document_structure>
-{{originalDocumentStructure}}
-</last_document_structure>
-
-<last_document_structure_rule>
-If a previous structural plan (last_document_structure) is provided, follow these rules:
-  1.  **Feedback Implementation**: The new structural plan **must** correctly implement all changes requested in user feedback.
-  2.  **Unrelated Node Stability**: Nodes not mentioned in user feedback **must not have their path or sourcesIds attributes modified**. `path` and `sourcesIds` are critical identifiers linking existing content, and their stability is paramount.
-    Ideally, other attributes (such as `title`, `description`) should also remain stable, unless these changes are directly caused by a requested modification or result from DataSource updates.
-</last_document_structure_rule>
-{% endif %}
 
-{% if documentStructure %}
-<review_document_structure>
-{{ documentStructure }}
-</review_document_structure>
-{% endif %}
+{% include "../../common/document-structure/document-structure-rules.md" %}
 
-{% if structureReviewFeedback %}
-<document_structure_review_feedback>
-{{ structureReviewFeedback }}
-</document_structure_review_feedback>
-{% endif %}
 
-{% include "../common/document-structure/document-structure-rules.md" %}
+{% include "../../common/document-structure/conflict-resolution-guidance.md" %}
 
-{% include "../common/document-structure/conflict-resolution-guidance.md" %}
-
-{% include "../common/document-structure/glossary.md" %}
-
-<datasources>
-{{ datasources }}
-</datasources>
 
 {% ifAsync docsType == 'general' %}
-  {% include "./structure-example.md" %}
+  {% include "../structure-example.md" %}
 {% endif %}
 
-{% include "../common/document-structure/output-constraints.md" %}
+
+{% include "../../common/document-structure/output-constraints.md" %}

package/prompts/structure/{generate-structure-user.md → generate/user-prompt.md}

@@ -1,19 +1,20 @@
 
-{% include "../common/document-structure/user-locale-rules.md" %}
+{% include "../../common/document-structure/user-locale-rules.md" %}
 
-{% include "../common/document-structure/user-preferences.md" %}
+{% include "../../common/document-structure/user-preferences.md" %}
+
+
+<datasources>
+{{ datasources }}
+</datasources>
 
-{% if feedback %}
-<document_structure_user_feedback>
-{{ feedback }}
-</document_structure_user_feedback>
-{% endif %}
 
 {% if originalDocumentStructure %}
 <last_document_structure>
 {{originalDocumentStructure}}
 </last_document_structure>
 
+
 <last_document_structure_rule>
 If a previous structural plan (last_document_structure) is provided, follow these rules:
   1.  **Feedback Implementation**: The new structural plan **must** correctly implement all changes requested in user feedback.
@@ -22,20 +23,23 @@ If a previous structural plan (last_document_structure) is provided, follow thes
 </last_document_structure_rule>
 {% endif %}
 
+
 {% if documentStructure %}
 <review_document_structure>
 {{ documentStructure }}
 </review_document_structure>
 {% endif %}
 
+
+{% if feedback %}
+<document_structure_user_feedback>
+{{ feedback }}
+</document_structure_user_feedback>
+{% endif %}
+
+
 {% if structureReviewFeedback %}
 <document_structure_review_feedback>
 {{ structureReviewFeedback }}
 </document_structure_review_feedback>
 {% endif %}
-
-{% include "../common/document-structure/glossary.md" %}
-
-<datasources>
-{{ datasources }}
-</datasources>

package/prompts/structure/{update-document-structure.md → update/system-prompt.md}

@@ -4,7 +4,7 @@ You are a documentation structure update specialist with the strategic mindset o
 You analyze user feedback and intentions to modify existing documentation structures using specific operations.
 Your task is to understand user requirements and execute the appropriate structure modifications efficiently and accurately.
 
-{% include "../common/document-structure/intj-traits.md" %}
+{% include "../../common/document-structure/intj-traits.md" %}
 
 Processing workflow:
 
@@ -25,31 +25,20 @@ Objectives:
 
 </role_and_goal>
 
-{% include "../common/document-structure/user-locale-rules.md" %}
 
-{% include "../common/document-structure/user-preferences.md" %}
+{% include "../../common/document-structure/glossary.md" %}
 
-Initial Documentation Structure:
-<initial_document_structure>
-{{documentStructure}}
-</initial_document_structure>
 
-{% include "../common/document-structure/document-structure-rules.md" %}
+{% include "../../common/document-structure/document-structure-rules.md" %}
 
-{% include "../common/document-structure/conflict-resolution-guidance.md" %}
 
-{% include "../common/document-structure/glossary.md" %}
+{% include "../../common/document-structure/conflict-resolution-guidance.md" %}
 
-<datasources>
-{{ datasources }}
-</datasources>
 
 {% ifAsync docsType == 'general' %}
-  {% include "./structure-example.md" %}
+  {% include "../structure-example.md" %}
 {% endif %}
 
-<user_feedback>
-{{ feedback }}
 
 <feedback_analysis_guidelines>
 
@@ -77,12 +66,9 @@ Analyze the user feedback to determine the intended operation:
 
 </feedback_analysis_guidelines>
 
-</user_feedback>
 
 
-{% include "../common/document-structure/output-constraints.md" %}
-
-Operation execution rules:
+<operation_execution_rules>
 
 - Always analyze the user feedback first to understand the exact intent
 - Use only the appropriate tools based on the determined operation type
@@ -91,8 +77,7 @@ Operation execution rules:
 - Maintain data integrity by ensuring all constraints are met
 - Only use Tools to update data Use provided Tools to modify documentation structure, use the documentation structure returned by Tools as the latest version
 
-Tool usage guidelines:
-
+<tool_usage_guidelines>
 1. **addDocument**: Use when user wants to create new document
    - Ensure path starts with '/' and is unique
    - Validate parent exists if parentId is provided
@@ -109,14 +94,18 @@ Tool usage guidelines:
 4. **moveDocument**: Use when user wants to change document hierarchy
    - Validate new parent exists
    - Check for circular dependencies
-
-Error handling:
-
+</tool_usage_guidelines>
+<operation_error_handling>
 - If user intent is unclear, ask for clarification
 - If required information is missing, request the needed details
 - If operation would break constraints, explain the issue and suggest alternatives
-
+</operation_error_handling>
+<operation_output_constraints>
 ** Only output operation execution status **:
 - Only return 'success' if operation executed successfully
 - Return brief error message if operation failed
-</output_constraints>
+</operation_output_constraints>
+</operation_execution_rules>
+
+
+{% include "../../common/document-structure/output-constraints.md" %}

package/prompts/structure/update/user-prompt.md

@@ -0,0 +1,19 @@
+{% include "../../common/document-structure/user-locale-rules.md" %}
+
+{% include "../../common/document-structure/user-preferences.md" %}
+
+
+<datasources>
+{{ datasources }}
+</datasources>
+
+
+Initial Documentation Structure:
+<initial_document_structure>
+{{documentStructure}}
+</initial_document_structure>
+
+
+<user_feedback>
+{{ feedback }}
+</user_feedback>

package/tests/agents/generate/user-review-document-structure.test.mjs

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from "bun:
 import userReviewDocumentStructure from "../../../agents/generate/user-review-document-structure.mjs";
 
 import * as preferencesUtils from "../../../utils/preferences-utils.mjs";
+import * as historyUtils from "../../../utils/history-utils.mjs";
 
 describe("user-review-document-structure", () => {
   let mockOptions;
@@ -61,6 +62,7 @@ describe("user-review-document-structure", () => {
     );
 
     consoleSpy = spyOn(console, "log").mockImplementation(() => {});
+    spyOn(historyUtils, "recordUpdate").mockImplementation(() => {});
 
     // Clear prompts mock call history
     mockOptions.prompts.select.mockClear();

package/tests/agents/update/check-document.test.mjs

@@ -25,7 +25,7 @@ describe("check-document", () => {
     mockOptions = {
       context: {
         agents: {
-          generateAndTranslateDocument: { mockAgent: true },
+          handleDocumentUpdate: { mockAgent: true },
         },
         invoke: mock(async () => ({ mockResult: true })),
       },