@aigne/doc-smith 0.8.11-beta.5 → 0.8.11-beta.7

package/tests/agents/utils/format-document-structure.test.mjs

@@ -104,7 +104,7 @@ describe("format-document-structure", () => {
   });
 
   // BASIC FUNCTIONALITY TESTS
-  test("should format empty document structure", async () => {
+  test("should format empty documentation structure", async () => {
     const result = await formatDocumentStructure({
       documentStructure: [],
     });
@@ -121,7 +121,7 @@ describe("format-document-structure", () => {
     });
   });
 
-  test("should format single item document structure", async () => {
+  test("should format single item documentation structure", async () => {
     const documentStructure = [
       {
         title: "Getting Started",
@@ -152,7 +152,7 @@ describe("format-document-structure", () => {
     expect(result.documentStructureYaml).toBe(expectedYaml);
   });
 
-  test("should format multiple items document structure", async () => {
+  test("should format multiple items documentation structure", async () => {
     const documentStructure = [
       {
         title: "API Reference",
@@ -321,7 +321,7 @@ describe("format-document-structure", () => {
     expect(result.documentStructure).toEqual(documentStructure);
   });
 
-  test("should return both yaml string and original document structure", async () => {
+  test("should return both yaml string and original documentation structure", async () => {
     const documentStructure = [
       {
         title: "Return Test",
@@ -339,7 +339,7 @@ describe("format-document-structure", () => {
     expect(result.documentStructure).toBe(documentStructure); // Should be the same reference
   });
 
-  test("should preserve original document structure unchanged", async () => {
+  test("should preserve original documentation structure unchanged", async () => {
     const originalDocumentStructure = [
       {
         title: "Original",

package/tests/agents/utils/load-sources.test.mjs

@@ -1030,8 +1030,8 @@ describe("load-sources", () => {
     });
   });
 
-  describe("Document path and document structure handling", () => {
-    test("should load existing document structure", async () => {
+  describe("Document path and documentation structure handling", () => {
+    test("should load existing documentation structure", async () => {
       const documentStructure = {
         sections: ["Introduction", "API", "Examples"],
         lastUpdated: new Date().toISOString(),
@@ -1050,7 +1050,7 @@ describe("load-sources", () => {
       expect(result.originalDocumentStructure).toEqual(documentStructure);
     });
 
-    test("should handle malformed document structure JSON", async () => {
+    test("should handle malformed documentation structure JSON", async () => {
       await writeFile(path.join(tempDir, "structure-plan.json"), "{ invalid json content");
 
       const result = await loadSources({
@@ -1064,7 +1064,7 @@ describe("load-sources", () => {
       expect(result.originalDocumentStructure).toBeUndefined();
     });
 
-    test("should handle non-ENOENT errors when reading document structure JSON", async () => {
+    test("should handle non-ENOENT errors when reading documentation structure JSON", async () => {
       // Import fs promises module to spy on
       const fsPromises = await import("node:fs/promises");
 

package/tests/agents/utils/save-docs.test.mjs

@@ -52,7 +52,7 @@ describe("save-docs", () => {
     expect(initialFiles).toContain("getting-started.md");
     expect(initialFiles).toContain("old-file.md");
 
-    // Test document structure
+    // Test documentation structure
     const documentStructure = [
       {
         path: "/overview",

package/tests/utils/conflict-detector.test.mjs

@@ -309,7 +309,7 @@ describe("conflict-detector", () => {
 
       // Should include conflict resolution rules in final rules
       expect(result.rules).toContain("=== Conflict Resolution Guidelines ===");
-      expect(result.rules).toContain("Create layered document structure");
+      expect(result.rules).toContain("Create layered documentation structure");
       expect(result.rules).toContain("Create separate user paths");
 
       // Should also include regular configuration content with enhanced format

package/tests/utils/docs-finder-utils.test.mjs

@@ -125,7 +125,7 @@ describe("docs-finder-utils", () => {
       expect(result).toBeUndefined();
     });
 
-    test("should handle empty document structure", () => {
+    test("should handle empty documentation structure", () => {
       const result = findItemByFlatName([], "any-name");
       expect(result).toBeUndefined();
     });
@@ -243,7 +243,7 @@ describe("docs-finder-utils", () => {
       expect(result).toEqual(["guide.zh.md", "overview.zh.md"]);
     });
 
-    test("should sort files by document structure order", async () => {
+    test("should sort files by documentation structure order", async () => {
       readdirSpy.mockResolvedValue(["guide.md", "overview.md", "advanced.md"]);
 
       const documentStructure = [{ path: "/overview" }, { path: "/guide" }, { path: "/advanced" }];
@@ -253,7 +253,7 @@ describe("docs-finder-utils", () => {
       expect(result).toEqual(["overview.md", "guide.md", "advanced.md"]);
     });
 
-    test("should handle files not in document structure", async () => {
+    test("should handle files not in documentation structure", async () => {
       readdirSpy.mockResolvedValue(["guide.md", "extra.md", "overview.md"]);
 
       const documentStructure = [{ path: "/overview" }, { path: "/guide" }];
@@ -480,7 +480,7 @@ describe("docs-finder-utils", () => {
       ]);
     });
 
-    test("should warn for files not in document structure", async () => {
+    test("should warn for files not in documentation structure", async () => {
       readFileSpy.mockResolvedValue("content");
 
       const selectedFiles = ["unknown.md"];
@@ -488,7 +488,7 @@ describe("docs-finder-utils", () => {
 
       expect(result).toEqual([]);
       expect(consoleWarnSpy).toHaveBeenCalledWith(
-        "⚠️  No document structure item found for file: unknown.md",
+        "⚠️  No documentation structure item found for file: unknown.md",
       );
     });
 
@@ -508,7 +508,7 @@ describe("docs-finder-utils", () => {
         },
       ]);
       expect(consoleWarnSpy).toHaveBeenCalledWith(
-        "⚠️  No document structure item found for file: unknown.md",
+        "⚠️  No documentation structure item found for file: unknown.md",
       );
     });
 
@@ -623,14 +623,14 @@ describe("docs-finder-utils", () => {
       await expect(getMainLanguageFiles("/denied", "en")).rejects.toThrow("Permission denied");
     });
 
-    test("processSelectedFiles should handle empty document structure", async () => {
+    test("processSelectedFiles should handle empty documentation structure", async () => {
       readFileSpy.mockResolvedValue("content");
 
       const result = await processSelectedFiles(["test.md"], [], "/docs");
 
       expect(result).toEqual([]);
       expect(consoleWarnSpy).toHaveBeenCalledWith(
-        "⚠️  No document structure item found for file: test.md",
+        "⚠️  No documentation structure item found for file: test.md",
       );
     });
   });

package/types/document-schema.mjs

@@ -3,22 +3,20 @@ import { zodToJsonSchema } from "zod-to-json-schema";
 
 // Update document content schemas
 export const updateDocumentContentInputSchema = z.object({
-  originalContent: z.string().min(1, "Original content is required"),
   diffPatch: z.string().min(1, "Diff patch is required"),
 });
 
 export const updateDocumentContentOutputSchema = z.object({
   success: z.boolean(),
   updatedContent: z.string().optional(),
-  error: z.string().optional(),
-  message: z.string(),
+  error: z.object({ message: z.string() }).optional(),
+  message: z.string().optional(),
 });
 
 // JSON Schema conversions for update document content
 export const getUpdateDocumentContentInputJsonSchema = () => {
   const schema = zodToJsonSchema(updateDocumentContentInputSchema);
   if (schema.properties) {
-    schema.properties.originalContent.description = "Original markdown content to be updated";
     schema.properties.diffPatch.description = "Diff patch string to apply to the original content";
   }
   return schema;
@@ -30,8 +28,9 @@ export const getUpdateDocumentContentOutputJsonSchema = () => {
     schema.properties.success.description = "Whether the update was successful";
     schema.properties.updatedContent.description =
       "Updated markdown content (only present if success is true)";
-    schema.properties.error.description = "Error message (only present if success is false)";
-    schema.properties.message.description = "Status message";
+    schema.properties.error.description =
+      "Error object containing error message (only present if success is false)";
+    schema.properties.message.description = "Success message (only present if success is true)";
   }
   return schema;
 };

package/types/document-structure-schema.mjs

@@ -10,12 +10,11 @@ export const documentItemSchema = z.object({
   sourceIds: z.array(z.string()).min(1, "At least one source ID is required"),
 });
 
-// Document structure schema - represents the entire document structure array
+// Documentation structure schema - represents the entire documentation structure array
 export const documentStructureSchema = z.array(documentItemSchema);
 
 // Add document schemas
 export const addDocumentInputSchema = z.object({
-  documentStructure: documentStructureSchema,
   title: z.string().min(1, "Title is required"),
   description: z.string().min(1, "Description is required"),
   path: z.string().startsWith("/", 'Path must start with "/"'),
@@ -25,37 +24,40 @@ export const addDocumentInputSchema = z.object({
 
 export const addDocumentOutputSchema = z.object({
   documentStructure: documentStructureSchema,
+  message: z.string().optional(),
   addedDocument: documentItemSchema.optional(),
+  error: z.object({ message: z.string() }).optional(),
 });
 
 // Delete document schemas
 export const deleteDocumentInputSchema = z.object({
-  documentStructure: documentStructureSchema,
   path: z.string().min(1, "Path is required"),
 });
 
 export const deleteDocumentOutputSchema = z.object({
   documentStructure: documentStructureSchema,
+  message: z.string().optional(),
   deletedDocument: documentItemSchema.optional(),
+  error: z.object({ message: z.string() }).optional(),
 });
 
 // Move document schemas
 export const moveDocumentInputSchema = z.object({
-  documentStructure: documentStructureSchema,
   path: z.string().min(1, "Path is required"),
   newParentId: z.string().nullable().optional(),
 });
 
 export const moveDocumentOutputSchema = z.object({
   documentStructure: documentStructureSchema,
+  message: z.string().optional(),
   originalDocument: documentItemSchema.optional(),
   updatedDocument: documentItemSchema.optional(),
+  error: z.object({ message: z.string() }).optional(),
 });
 
 // Update document schemas
 export const updateDocumentInputSchema = z
   .object({
-    documentStructure: documentStructureSchema,
     path: z.string().min(1, "Path is required"),
     title: z.string().min(1).optional(),
     description: z.string().min(1).optional(),
@@ -71,8 +73,10 @@ export const updateDocumentInputSchema = z
 
 export const updateDocumentOutputSchema = z.object({
   documentStructure: documentStructureSchema,
+  message: z.string().optional(),
   originalDocument: documentItemSchema.optional(),
   updatedDocument: documentItemSchema.optional(),
+  error: z.object({ message: z.string() }).optional(),
 });
 
 // JSON Schema conversion functions using zodToJsonSchema
@@ -80,7 +84,6 @@ export const getAddDocumentInputJsonSchema = () => {
   const schema = zodToJsonSchema(addDocumentInputSchema);
   // Add custom descriptions
   if (schema.properties) {
-    schema.properties.documentStructure.description = "Current document structure array";
     schema.properties.title.description = "Title of the new document";
     schema.properties.description.description = "Description of the new document";
     schema.properties.path.description = "URL path for the new document (must start with '/')";
@@ -96,8 +99,11 @@ export const getAddDocumentOutputJsonSchema = () => {
   const schema = zodToJsonSchema(addDocumentOutputSchema);
   if (schema.properties) {
     schema.properties.documentStructure.description =
-      "Updated document structure array with the new document added";
+      "Updated documentation structure array with the new document added";
+    schema.properties.message.description = "Success message describing the operation result";
     schema.properties.addedDocument.description = "The newly added document object";
+    schema.properties.error.description =
+      "Error object containing error message if operation failed";
   }
   return schema;
 };
@@ -105,7 +111,6 @@ export const getAddDocumentOutputJsonSchema = () => {
 export const getDeleteDocumentInputJsonSchema = () => {
   const schema = zodToJsonSchema(deleteDocumentInputSchema);
   if (schema.properties) {
-    schema.properties.documentStructure.description = "Current document structure array";
     schema.properties.path.description = "URL path of the document to delete";
   }
   return schema;
@@ -115,8 +120,11 @@ export const getDeleteDocumentOutputJsonSchema = () => {
   const schema = zodToJsonSchema(deleteDocumentOutputSchema);
   if (schema.properties) {
     schema.properties.documentStructure.description =
-      "Updated document structure array with the document removed";
+      "Updated documentation structure array with the document removed";
+    schema.properties.message.description = "Success message describing the operation result";
     schema.properties.deletedDocument.description = "The deleted document object";
+    schema.properties.error.description =
+      "Error object containing error message if operation failed";
   }
   return schema;
 };
@@ -124,7 +132,6 @@ export const getDeleteDocumentOutputJsonSchema = () => {
 export const getMoveDocumentInputJsonSchema = () => {
   const schema = zodToJsonSchema(moveDocumentInputSchema);
   if (schema.properties) {
-    schema.properties.documentStructure.description = "Current document structure array";
     schema.properties.path.description = "URL path of the document to move";
     schema.properties.newParentId.description =
       "Path of the new parent document (leave empty for top-level)";
@@ -136,9 +143,12 @@ export const getMoveDocumentOutputJsonSchema = () => {
   const schema = zodToJsonSchema(moveDocumentOutputSchema);
   if (schema.properties) {
     schema.properties.documentStructure.description =
-      "Updated document structure array with the document moved";
+      "Updated documentation structure array with the document moved";
+    schema.properties.message.description = "Success message describing the operation result";
     schema.properties.originalDocument.description = "The original document object before moving";
     schema.properties.updatedDocument.description = "The updated document object after moving";
+    schema.properties.error.description =
+      "Error object containing error message if operation failed";
   }
   return schema;
 };
@@ -146,7 +156,6 @@ export const getMoveDocumentOutputJsonSchema = () => {
 export const getUpdateDocumentInputJsonSchema = () => {
   const schema = zodToJsonSchema(updateDocumentInputSchema);
   if (schema.properties) {
-    schema.properties.documentStructure.description = "Current document structure array";
     schema.properties.path.description = "URL path of the document to update";
     schema.properties.title.description = "New title for the document (optional)";
     schema.properties.description.description = "New description for the document (optional)";
@@ -166,10 +175,13 @@ export const getUpdateDocumentOutputJsonSchema = () => {
   const schema = zodToJsonSchema(updateDocumentOutputSchema);
   if (schema.properties) {
     schema.properties.documentStructure.description =
-      "Updated document structure array with the document modified";
+      "Updated documentation structure array with the document modified";
+    schema.properties.message.description = "Success message describing the operation result";
     schema.properties.originalDocument.description = "The original document object before update";
     schema.properties.updatedDocument.description =
       "The updated document object after modification";
+    schema.properties.error.description =
+      "Error object containing error message if operation failed";
   }
   return schema;
 };

package/utils/conflict-detector.mjs

@@ -76,7 +76,7 @@ export function getFilteredOptions(targetQuestion, currentSelections, allOptions
 }
 
 /**
- * Detect conflicts in user configuration selections that can be resolved through document structure
+ * Detect conflicts in user configuration selections that can be resolved through documentation structure
  * @param {Object} config - User configuration
  * @returns {Array} Array of detected conflicts with resolution strategies
  */

package/utils/constants/index.mjs

@@ -350,7 +350,7 @@ export const SUPPORTED_FILE_EXTENSIONS = [".txt", ".md", ".json", ".yaml", ".yml
 export const CONFLICT_RULES = {
   // Internal conflicts within the same question (multi-select conflicts)
   internalConflicts: {
-    // Note: Most conflicts can be resolved through intelligent document structure
+    // Note: Most conflicts can be resolved through intelligent documentation structure
     // Only keeping conflicts that represent fundamental incompatibilities
   },
 
@@ -424,7 +424,7 @@ export const CONFLICT_RULES = {
 
 // 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 document structure
+  // Document purpose conflicts that can be resolved through documentation structure
   documentPurpose: [
     {
       conflictItems: ["getStarted", "findAnswers"],
@@ -451,7 +451,7 @@ export const CONFLICT_RESOLUTION_RULES = {
     },
   ],
 
-  // Target audience conflicts that can be resolved through document structure
+  // Target audience conflicts that can be resolved through documentation structure
   targetAudienceTypes: [
     {
       conflictItems: ["endUsers", "developers"],
@@ -475,7 +475,7 @@ export const CONFLICT_RESOLUTION_RULES = {
 // Resolution strategy descriptions
 export const RESOLUTION_STRATEGIES = {
   layered_structure: (items) =>
-    `Detected "${items.join('" and "')}" purpose conflict. Resolution strategy: Create layered document structure
+    `Detected "${items.join('" and "')}" purpose conflict. Resolution strategy: Create layered documentation 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`,

package/utils/docs-finder-utils.mjs

@@ -24,8 +24,8 @@ function generateFileName(flatName, locale) {
 }
 
 /**
- * Find a single item by path in document structure result and read its content
- * @param {Array} documentExecutionStructure - Array of document structure items
+ * Find a single item by path in documentation structure result and read its content
+ * @param {Array} documentExecutionStructure - Array of documentation structure items
  * @param {string} docPath - Document path to find (supports .md filenames)
  * @param {string} boardId - Board ID for fallback matching
  * @param {string} docsDir - Docs directory path for reading content
@@ -116,7 +116,7 @@ export async function readFileContent(docsDir, fileName) {
  * Get main language markdown files from docs directory
  * @param {string} docsDir - Docs directory path
  * @param {string} locale - Main language locale (e.g., 'en', 'zh', 'fr')
- * @param {Array} documentExecutionStructure - Array of document structure items to determine file order
+ * @param {Array} documentExecutionStructure - Array of documentation structure items to determine file order
  * @returns {Promise<string[]>} Array of main language .md files ordered by documentExecutionStructure
  */
 export async function getMainLanguageFiles(docsDir, locale, documentExecutionStructure = null) {
@@ -153,7 +153,7 @@ export async function getMainLanguageFiles(docsDir, locale, documentExecutionStr
 
   // If documentExecutionStructure is provided, sort files according to the order in documentExecutionStructure
   if (documentExecutionStructure && Array.isArray(documentExecutionStructure)) {
-    // Create a map from flat file name to document structure order
+    // Create a map from flat file name to documentation structure order
     const orderMap = new Map();
     documentExecutionStructure.forEach((item, index) => {
       const itemFlattenedPath = item.path.replace(/^\//, "").replace(/\//g, "-");
@@ -166,16 +166,16 @@ export async function getMainLanguageFiles(docsDir, locale, documentExecutionStr
       const orderA = orderMap.get(a);
       const orderB = orderMap.get(b);
 
-      // If both files are in the document structure, sort by order
+      // If both files are in the documentation structure, sort by order
       if (orderA !== undefined && orderB !== undefined) {
         return orderA - orderB;
       }
 
-      // If only one file is in the document structure, it comes first
+      // If only one file is in the documentation structure, it comes first
       if (orderA !== undefined) return -1;
       if (orderB !== undefined) return 1;
 
-      // If neither file is in the document structure, maintain alphabetical order
+      // If neither file is in the documentation structure, maintain alphabetical order
       return a.localeCompare(b);
     });
   }
@@ -200,8 +200,8 @@ export function fileNameToFlatPath(fileName) {
 }
 
 /**
- * Find document structure item by flattened file name
- * @param {Array} documentExecutionStructure - Array of document structure items
+ * Find documentation structure item by flattened file name
+ * @param {Array} documentExecutionStructure - Array of documentation structure items
  * @param {string} flatName - Flattened file name
  * @returns {Object|null} Found item or null
  */
@@ -215,7 +215,7 @@ export function findItemByFlatName(documentExecutionStructure, flatName) {
 /**
  * Process selected files and convert to found items with content
  * @param {string[]} selectedFiles - Array of selected file names
- * @param {Array} documentExecutionStructure - Array of document structure items
+ * @param {Array} documentExecutionStructure - Array of documentation structure items
  * @param {string} docsDir - Docs directory path
  * @returns {Promise<Object[]>} Array of found items with content
  */
@@ -244,7 +244,7 @@ export async function processSelectedFiles(selectedFiles, documentExecutionStruc
 
       foundItems.push(result);
     } else {
-      console.warn(`⚠️  No document structure item found for file: ${selectedFile}`);
+      console.warn(`⚠️  No documentation structure item found for file: ${selectedFile}`);
     }
   }
 

package/utils/markdown-checker.mjs

@@ -87,7 +87,7 @@ function checkDeadLinks(markdown, source, allowedLinks, errorMessages) {
     // Check if this link is in the allowed links set
     if (!allowedLinks.has(path)) {
       errorMessages.push(
-        `Found a dead link in ${source}: [${match[1]}](${trimLink}), ensure the link exists in the document structure path`,
+        `Found a dead link in ${source}: [${match[1]}](${trimLink}), ensure the link exists in the documentation structure path`,
       );
     }
   }