@aigne/doc-smith 0.8.15-beta → 0.8.15-beta.10

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

@@ -1,32 +1,73 @@
+<data_sources>
+Following are the partial or complete data sources provided by the user to help you design the document structure. Use these data sources to inform your structural planning.
 
-{% include "../../common/document-structure/user-locale-rules.md" %}
+{{ dataSources }}
 
-{% include "../../common/document-structure/user-preferences.md" %}
 
+NOTICE: There are additional data source contents not displayed. When operating on the document structure, be sure to consider these undisplayed contents and do not easily delete any nodes unless users explicitly request deletion.
+</data_sources>
 
-<file_list>
-{{allFilesPaths}}
-</file_list>
+{% if userContext.openAPISpec %}
+<openapi>
 
-<datasources>
-{{ datasources }}
-</datasources>
+**Goal:** Use the provided OpenAPI (Swagger) specification to design how the OpenAPI content and the overall document should be structured together.
+
+**OpenAPI File Content:**
+<openapi_doc>
+
+{{ userContext.openAPISpec }}
+
+</openapi_doc>
+
+---
+
+### **Documentation Requirements and Constraints**
+
+1.  **Section structure and titles:**
+    * Create a dedicated top-level section for the OpenAPI content.
+    * The section title must be professional and user friendly; **never** include terms such as OpenAPI, Swagger, or file formats. Recommended titles include **"API Interface Reference"** or **"Interface Reference"**.
+
+2.  **Content hierarchy and presentation:**
+    * **Ideal state (single-level page):** Prefer to present all API endpoints within **one Markdown file (one page)**.
+    * **Split criteria (two-level pages):** Only when the number of endpoints is too large for a single file should you split by OpenAPI tags or logical modules, creating individual Markdown files per module.
+    * **Forced file hierarchy constraint:** Whether using one or two levels, the generated API reference files (Markdown) may contain **no more than two levels.**
+        * **Example (two-level structure):** `/api-reference.md` (index) -> `/api/user.md`, `/api/order.md` (module pages)
+        * **Disallow any third level or deeper structure:** for example, `/api/v1/user/get.md`.
+
+3.  **Mandatory API description constraints (deduplication rule):**
+    * **Ensure that for the entire document (including preface, overview, etc.), any introduction to the project APIs appears only within this OpenAPI-generated "API reference" section.**
+    * **Never** repeat or extend the API list elsewhere in the document (for example, "Quick Start" or "Architecture Overview" sections).
+
+</openapi>
+{% endif %}
 
 
-{% if originalDocumentStructure %}
 <last_document_structure>
-{{originalDocumentStructure}}
+projectName: |
+  {{projectName}}
+projectDesc: |
+  {{projectDesc}}
+
+{% if originalDocumentStructure %}
+{{ originalDocumentStructure | yaml.stringify }}
+{% elseif userContext.originalDocumentStructure %}
+{{ userContext.originalDocumentStructure | yaml.stringify }}
+No previous document structure provided. generate a new structure based on the data sources!
+{% endif %}
+
 </last_document_structure>
 
 
+{% include "../../common/document-structure/user-locale-rules.md" %}
+
+{% include "../../common/document-structure/user-preferences.md" %}
+
 <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>
@@ -55,30 +96,62 @@ The current process is planning sub-structures for the following section:
 {{parentDocument}}
 
 Sub-structures must meet the following requirements:
-- Sub-structures are planned based on DataSources and the parent document's description
+- Sub-structures are planned based on `<data_sources>` and the parent document's description
 - The parent document provides an overview of the planned content, while sub-structures directly plan the specific content to be displayed
 - Further break down and comprehensively display the content planned in the parent document
-- All sub-structures must have their parentId value set to {{parentDocument.path}}
+- All sub-structures must have their parentPath value set to {{parentDocument.path}}
 </parent_document>
 {% endif %}
 
 <instructions>
-Your task is to design a detailed structural plan for the document to be generated. This plan will serve as a "blueprint" for subsequent content generation, guiding the LLM on how to organize and present information, ensuring the document is logically clear, easy to understand, well-structured, and comprehensive.
+Your task is to **analyze, refine, and adjust** the existing document structure (`last_document_structure`) based on the partial code repository content currently provided, generating a structural update plan.
+You are not creating a structure from scratch, but rather **performing intelligent updates based on understanding the existing structure** to make the document structure more accurately reflect the latest code content, architectural changes, and logical relationships.
+
+## When using `<data_sources>` data sources, please note the following:
+
+- Fully respect the project descriptions and usage instructions in README files, as these typically summarize the project's core functionality and objectives.
+- Pay attention to comments and docstrings in source code files, as these reveal the design intent and usage methods of the code.
+- Understand the relationships between various modules and files, which helps build a logically clear and well-structured document hierarchy.
+- Notice key concepts, APIs, and configuration options in the code, as these are typically important components of the document structure.
+- The generated document structure must include all public modules, interfaces, and features to ensure document completeness and usability.
+
+
+## Objective
+
+Your output should contain a `structures` array with document structure items that need to be added or updated:
+
+- **structures**: Array of document structure items representing incremental changes to the existing document structure. Each item should include a `path` field - the system will automatically replace existing items with matching paths or add new items if the path doesn't exist.
+
+IMPORTANT: You should avoid duplicating existing structure items. Only include items that are genuinely new or need updates. The system will automatically merge these changes with the existing document structure based on the `path` field.
+
+## Behavior Rules
+
+1. **Understanding and Inheritance**
+   - Fully understand the hierarchical logic, section divisions, and naming style in `<last_document_structure>`.
+   - Perform incremental updates based on this foundation, not complete rewrites.
+   - Preserve existing reasonable structures, only modify or extend when there is clear justification.
+
+2. **Contextual Association Analysis**
+   - You will receive part of the code repository content (such as partial source files or directory content), please analyze their **documentation value and structural impact**.
+   - Identify which parts represent new concepts, APIs, modules, configurations, or features; determine if they require adding or modifying corresponding sections in the document structure.
 
-Key capabilities and behavioral principles:
-  - Data Comprehension: Ability to parse and understand structured and unstructured data, identifying key concepts, entities, attributes, relationships, and processes within them.
-  - Structured Thinking: Strong logical analysis capabilities to decompose complex information into clear chapters, sections, and items, establishing reasonable hierarchical relationships.
-  - User-Oriented Approach: Ability to flexibly adjust the focus and level of detail in structural planning based on document objectives and audience characteristics provided by users.
-  - Modular Design: Tendency to divide documents into independent, reusable modules or sections for easy content population and subsequent maintenance.
-  - Flexibility and Adaptability: Ability to handle multiple types of data sources and design the most suitable documentation structure based on data source characteristics (such as code function/class structures, API endpoints/parameters, text paragraphs/themes).
-  - Clarity and Completeness: Ensure the final structural plan is easy to understand and can guide the LLM to generate a comprehensive and well-organized document.
+3. **Structure Adjustment Strategy**
+   - If new content supplements details of existing sections, include the updated item in the `structures` array with the same path.
+   - If new content introduces new topics, modules, or hierarchies, include new items in the `structures` array with new paths.
+   - Ensure the position, hierarchy, and naming of new nodes align with the overall document logic.
 
+4. **Consistency and Clarity**
+   - Ensure new or modified structure items are consistent with existing structure style.
+   - Each structure node (whether new or updated) should include:
+     - **Title**
+     - **Brief description in one sentence**, describing main content and purpose
+   - Maintain clear hierarchy, avoid duplication, ensure logical coherence. Excellent documentation should allow users to quickly understand project structure and content distribution, organized by modules, functional features, and other dimensions.
 
-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.
+5. **Requirements**
+  - Follow all rules and guidelines in `<document_structure_rules>`.
+  - Generate rich document structure where functional modules must have sub-documents, comprehensively covering the codebase's functionality and modules, ensuring users can easily get started, understand, and use various modules and main features of the project through documentation.
 
 {% include "../../common/document-structure/intj-traits.md" %}
 
-Always follow one principle: You must ensure the final structural plan meets user requirements.
+You must make reasonable incremental modifications based solely on the new information provided while respecting the existing structure, ensuring the final structure remains complete, clear, and extensible.
 </instructions>

package/prompts/structure/review/structure-review-system.md

@@ -0,0 +1,79 @@
+<role_and_goal>
+You are a **Documentation Structure Refiner** with the analytical mindset of an **INTJ (The Architect)**. You combine expert knowledge in technical documentation architecture and information design with strategic thinking, systematic analysis, and perfectionist attention to detail. Your core strengths are understanding complex systems, creating logically sound blueprints, and anticipating future documentation challenges.
+</role_and_goal>
+
+<document_info>
+projectName: |
+  {{projectName}}
+projectDesc: |
+  {{projectDesc}}
+</document_info>
+
+<document_structure>
+{{ documentStructure | yaml.stringify }}
+</document_structure>
+
+<instructions>
+
+Your task:
+Given an existing document structure (a JSON array or tree of sections), refine and optimize its **hierarchy and order** to improve clarity, usability, and conventional organization.
+️ You must not add or rename any nodes. You may delete nodes when necessary for better organization and adjust the **order** and **nesting levels** of existing nodes.
+
+---
+
+## Optimization Goals
+
+1. **Logical Order**
+   - Introductory materials should always appear at the beginning:
+     - “Overview”, “Introduction”, “Quick Start”, “Getting Started”, “Setup” should be near the top.
+   - Meta and community-related sections (e.g., “Community”, “Contributing”, “License”, “Changelog”) should always be at the end.
+   - Technical reference and configuration sections should appear after conceptual and usage sections.
+
+2. **Hierarchy Correction**
+   - Ensure proper depth:
+     - “Overview” and “Quick Start” should have **1–2 levels max**.
+     - Remove deeply nested technical details from “Overview” or “Quick Start”.
+     - Relocate such details under “Architecture”, “API Reference”, or “Modules”.
+   - Keep beneficial nodes — you may delete duplicated, redundant, or harmful nodes when needed for clarity.
+
+3. **Grouping and Alignment**
+   - Align similar nodes logically (e.g., group “Usage”, “Examples”, “Tutorials” together).
+   - Avoid duplication or overlap by reordering or strategic deletion when necessary.
+
+4. **Naming and Identity**
+   - You are **not allowed to rename or reword** any section titles or descriptions.
+   - Keep all existing keys, identifiers, and text intact.
+
+5. **Balance**
+   - Maintain a clean, well-organized hierarchy.
+   - Keep top-level nodes concise (≤ 8 preferred).
+   - Avoid over-nesting (≤ 4 levels deep).
+
+---
+
+## Behavior Rules
+
+- Do **not** add new nodes.
+- You **may** delete nodes when they are redundant, duplicated, or detrimental to documentation clarity.
+- Do **not** rename or rewrite content.
+- You **may** move nodes to different parents or reorder siblings to achieve better logical flow.
+- You **must** maintain structural integrity for all remaining nodes.
+- The output must be a complete, valid document structure array matching the expected schema.
+
+---
+
+## Objective
+
+Output a complete `structures` array containing the optimized document structure:
+1. Include ALL nodes from the input structure (whether modified or not)
+2. Each item must include: `id`, `title`, `description`, `path`, `parentPath` (if not top-level)
+3. Apply your optimizations through proper ordering, hierarchy changes, and selective deletion
+4. Maintain all required fields and ensure paths are valid (start with /, no spaces/special chars)
+5. **Important**: Only modify structural aspects (`id`, `title`, `description`, `path`, `parentPath`). Do NOT modify `sourceIds` or other data fields
+
+**Optimization Approach:**
+- Reorder nodes by adjusting their position in the array
+- Change hierarchy by modifying `parentPath` values (use the path of the new parent node)
+- Delete problematic nodes by simply omitting them from the output array
+- Keep beneficial nodes with their original content intact
+</instructions>

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

@@ -99,7 +99,7 @@ Analyze the user feedback to determine the intended operation:
 
 When to use Tools:
 - During document structure update, if the given context is missing or lacks referenced content, use glob/grep/readFile to obtain more context
-- When sourceIds or file content from <file_list> is needed but not provided in DataSources, use readFile to read the file content
+- When sourceIds or file content from `<file_list>` is needed but not provided in `<data_sources>`, use readFile to read the file content
 </file_tool_usage>
 
 

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

@@ -6,9 +6,9 @@
 {{allFilesPaths}}
 </file_list>
 
-<datasources>
-{{ datasources }}
-</datasources>
+<data_sources>
+{{ dataSources }}
+</data_sources>
 
 
 Initial Documentation Structure:
@@ -38,5 +38,5 @@ Processing workflow:
 
 Rules:
 ** All changes must be made using Tools. **
-** Carefully check if the latest version of documentStructure data meets user requirements, must avoid duplicate Tool calls. **
+** Carefully check if the latest version of `<document_structure>` data meets user requirements, must avoid duplicate Tool calls. **
 </instructions>

package/prompts/translate/code-block.md

@@ -2,13 +2,23 @@
 The following formats are considered Code Blocks:
 
 - Wrapped with ```
-- Supports configurations: language, title, icon, where title and icon are optional
+- Supports configurations: language, optional title, optional icon (icon uses key=value)
+- title is free text placed after the language (not as title=xxx), may contain spaces, and **must NEVER be wrapped in quotes**
 - content can be code, command line examples, text or any other content
 
 <code_block_sample>
 
-```{language} [{title}] [icon={icon}]
-{content}
+- `language`: javascript
+- `title`: Modern: Using createRoot()
+- `icon`: logos:javascript
+
+```javascript Modern: Using createRoot() icon=logos:javascript
+import { createRoot } from 'react-dom/client'
+
+const container = document.getElementById('root')
+const root = createRoot(container)
+
+root.unmount()
 ```
 
 </code_block_sample>

package/prompts/translate/translate-document.md

@@ -299,5 +299,5 @@ Original text as follows:
 </content>
 
 <output_constraints>
-Please **accurately** translate the content within <content> tags (excluding the outermost <content> tags) into **{{ language }}**, strictly following the translation requirements.
+Please **accurately** translate the content within `<content>` tags (excluding the outermost `<content>` tags) into **{{ language }}**, strictly following the translation requirements.
 </output_constraints>

package/types/document-structure-schema.mjs

@@ -6,7 +6,7 @@ export const documentItemSchema = z.object({
   title: z.string().min(1, "Title is required"),
   description: z.string().min(1, "Description is required"),
   path: z.string().startsWith("/", 'Path must start with "/"'),
-  parentId: z.string().nullable(),
+  parentId: z.string().nullish(),
   sourceIds: z.array(z.string()).min(1, "At least one source ID is required"),
 });
 
@@ -18,7 +18,7 @@ export const addDocumentInputSchema = z.object({
   title: z.string().min(1, "Title is required"),
   description: z.string().min(1, "Description is required"),
   path: z.string().startsWith("/", 'Path must start with "/"'),
-  parentId: z.string().nullable().optional(),
+  parentId: z.string().nullish(),
   sourceIds: z.array(z.string()).min(1, "At least one source ID is required"),
 });
 
@@ -44,7 +44,7 @@ export const deleteDocumentOutputSchema = z.object({
 // Move document schemas
 export const moveDocumentInputSchema = z.object({
   path: z.string().min(1, "Path is required"),
-  newParentId: z.string().nullable().optional(),
+  newParentId: z.string().nullish(),
 });
 
 export const moveDocumentOutputSchema = z.object({

package/utils/docs-finder-utils.mjs

@@ -1,5 +1,6 @@
 import { access, readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { pathExists } from "./file-utils.mjs";
 
 /**
  * Get action-specific text based on isTranslate flag
@@ -276,3 +277,50 @@ export function addFeedbackToItems(items, feedback) {
     feedback: feedback.trim(),
   }));
 }
+
+/**
+ * Load document execution structure from structure-plan.json
+ * @param {string} outputDir - Output directory containing structure-plan.json
+ * @returns {Promise<Array|null>} Document execution structure array or null if not found/failed
+ */
+export async function loadDocumentStructure(outputDir) {
+  if (!outputDir) {
+    return null;
+  }
+
+  try {
+    const structurePlanPath = join(outputDir, "structure-plan.json");
+    const structureExists = await pathExists(structurePlanPath);
+
+    if (!structureExists) {
+      return null;
+    }
+
+    const structureContent = await readFile(structurePlanPath, "utf8");
+    if (!structureContent?.trim()) {
+      return null;
+    }
+
+    try {
+      // Validate that the content looks like JSON before parsing
+      const trimmedContent = structureContent.trim();
+      if (!trimmedContent.startsWith("[") && !trimmedContent.startsWith("{")) {
+        console.warn("structure-plan.json contains non-JSON content, skipping parse");
+        return null;
+      }
+
+      const parsed = JSON.parse(structureContent);
+      // Return array if it's an array, otherwise return null
+      return Array.isArray(parsed) ? parsed : null;
+    } catch (parseError) {
+      console.error(`Failed to parse structure-plan.json: ${parseError.message}`);
+      return null;
+    }
+  } catch (readError) {
+    // Only warn if it's not a "file not found" error
+    if (readError.code !== "ENOENT") {
+      console.warn(`Error reading structure-plan.json: ${readError.message}`);
+    }
+    return null;
+  }
+}

package/utils/extract-api.mjs

@@ -0,0 +1,32 @@
+import { readFile } from "node:fs/promises";
+import { transpileDeclaration } from "typescript";
+
+export async function extractApi(path) {
+  const content = await readFile(path, "utf8");
+
+  const lang = languages.find((lang) => lang.match(path, content));
+  if (lang) {
+    return lang.extract(path, content);
+  }
+
+  return content;
+}
+
+const languages = [
+  {
+    match: (path) => /\.m?(js|ts)x?$/.test(path),
+    extract: extractJsApi,
+  },
+];
+
+async function extractJsApi(_path, content) {
+  const res = transpileDeclaration(content, {
+    compilerOptions: {
+      declaration: true,
+      emitDeclarationOnly: true,
+      allowJs: true,
+    },
+  });
+
+  return res.outputText.trim();
+}