@aigne/doc-smith 0.8.10 → 0.8.11-beta.1

package/utils/linter/index.mjs

@@ -0,0 +1,50 @@
+import { LINTER_API_URL } from "../constants/linter.mjs";
+
+export async function lintCode({ code, linter = "biome-lint", suffix = ".js" }) {
+  if (!code) {
+    throw new Error("Code parameter is required");
+  }
+  const timeout = 30 * 1000;
+  let filename = `code${suffix}`;
+  if (suffix === ".dockerfile") {
+    filename = "Dockerfile";
+  }
+  const testData = {
+    filename,
+    content: code,
+    options: {
+      validate_all: true,
+      fix: false,
+      log_level: "INFO",
+      timeout,
+    },
+  };
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    const response = await fetch(`${LINTER_API_URL}/${linter}/json`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(testData),
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+
+    const data = await response.json();
+    if (!data) {
+      throw new Error("Invalid response data");
+    }
+
+    return data;
+  } catch (error) {
+    throw new Error(`Linting failed: ${error.message}`);
+  }
+}

package/utils/markdown/index.mjs

@@ -0,0 +1,26 @@
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+import { visit } from "unist-util-visit";
+import { VFile } from "vfile";
+
+export function traverseMarkdownAst({ ast, test, visitor }) {
+  if (!ast || !test || !visitor) {
+    throw new Error("Required parameters missing: ast, test, and visitor must be provided");
+  }
+  visit(ast, test, visitor);
+}
+
+export function getMarkdownAst({ markdown }) {
+  if (!markdown || typeof markdown !== "string") {
+    throw new Error("Invalid markdown input: must be a non-empty string");
+  }
+  const file = new VFile({ value: markdown });
+  const processor = unified().use(remarkParse).use(remarkGfm);
+  try {
+    const ast = processor.parse(file);
+    return ast;
+  } catch (error) {
+    throw new Error(`Failed to parse markdown: ${error.message}`);
+  }
+}

package/utils/markdown-checker.mjs

@@ -7,7 +7,7 @@ import remarkParse from "remark-parse";
 import { unified } from "unified";
 import { visit } from "unist-util-visit";
 import { VFile } from "vfile";
-import { KROKI_CONCURRENCY } from "./constants.mjs";
+import { KROKI_CONCURRENCY } from "./constants/index.mjs";
 import { checkContent, isValidCode } from "./d2-utils.mjs";
 import { validateMermaidSyntax } from "./mermaid-validator.mjs";
 

package/utils/utils.mjs

@@ -17,7 +17,7 @@ import {
   SUPPORTED_FILE_EXTENSIONS,
   SUPPORTED_LANGUAGES,
   TARGET_AUDIENCES,
-} from "./constants.mjs";
+} from "./constants/index.mjs";
 
 /**
  * Normalize path to absolute path for consistent comparison
@@ -934,7 +934,10 @@ export function processConfigFields(config) {
       .filter(Boolean);
 
     if (purposeRules.length > 0) {
-      allRulesContent.push(purposeRules.join("\n\n"));
+      const purposes = purposeRules.join("\n\n");
+      allRulesContent.push(purposes);
+
+      processed.purposes = purposes;
     }
   }
 
@@ -951,7 +954,10 @@ export function processConfigFields(config) {
       .filter(Boolean);
 
     if (audienceRules.length > 0) {
-      allRulesContent.push(audienceRules.join("\n\n"));
+      const audiences = audienceRules.join("\n\n");
+      allRulesContent.push(audiences);
+
+      processed.audiences = audiences;
     }
 
     // Get names for targetAudience field
@@ -976,20 +982,26 @@ export function processConfigFields(config) {
   // Process reader knowledge level (single value)
   let knowledgeContent = "";
   if (config.readerKnowledgeLevel) {
-    knowledgeContent = READER_KNOWLEDGE_LEVELS[config.readerKnowledgeLevel]?.content;
-    if (knowledgeContent) {
+    const knowledgeLevel = READER_KNOWLEDGE_LEVELS[config.readerKnowledgeLevel];
+    if (knowledgeLevel) {
+      knowledgeContent = knowledgeLevel.content;
       processed.readerKnowledgeContent = knowledgeContent;
       allRulesContent.push(`Reader Knowledge Level:\n${knowledgeContent}`);
+
+      processed.readerKnowledgeLevel = `Reader Knowledge Level - ${knowledgeLevel.name} : ${knowledgeLevel.description} \n${knowledgeContent}`;
     }
   }
 
   // Process documentation depth (single value)
   let depthContent = "";
   if (config.documentationDepth) {
-    depthContent = DOCUMENTATION_DEPTH[config.documentationDepth]?.content;
-    if (depthContent) {
+    const depthLevel = DOCUMENTATION_DEPTH[config.documentationDepth];
+    if (depthLevel) {
+      depthContent = depthLevel.content;
       processed.documentationDepthContent = depthContent;
       allRulesContent.push(`Documentation Depth:\n${depthContent}`);
+
+      processed.coverageDepth = `Documentation Depth - ${depthLevel.name} : ${depthLevel.description} \n${depthContent}`;
     }
   }
 

package/prompts/structure/generate-structure.md

@@ -1,161 +0,0 @@
-<role_and_goal>
-You are an experienced document structure architect with expertise in information organization and logical structuring. Your specialty lies in deeply understanding various forms of data sources (including but not limited to source code, API definitions, database schemas, configuration information, business logic descriptions, user stories, etc.) and extracting core information and key relationships from them.
-
-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.
-
-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 document 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.
-
-
-Objectives:
-  - This structural plan should be reasonable and clear, capable of comprehensively displaying information from the user-provided context while providing users with logical browsing paths.
-  - Each {{nodeName}} should include: {{nodeName}} title, a one-sentence introduction to the main information this {{nodeName}} displays, with information presentation and organization methods matching the target audience.
-
-Always follow one principle: You must ensure the final structural plan meets user requirements.
-</role_and_goal>
-
-<user_locale>
-{{ locale }}
-</user_locale>
-
-
-<user_rules>
-{{ rules }}
-
-** Output content in {{ locale }} language **
-</user_rules>
-
-{% if userPreferences %}
-<user_preferences>
-{{userPreferences}}
-
-User preference guidelines:
-- User preferences are derived from feedback provided in previous user interactions. When generating structural planning, consider user preferences to avoid repeating issues mentioned in user feedback
-- User preferences carry less weight than current user feedback
-</user_preferences>
-{% endif %}
-
-{% 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 %}
-
-{% if structureReviewFeedback %}
-<document_structure_review_feedback>
-{{ structureReviewFeedback }}
-</document_structure_review_feedback>
-{% endif %}
-
-<document_structure_rules>
-The target audience for this document is: {{targetAudience}}
-
-DataSources usage rules:
-1. When planning the structure, reasonably organize and display all information from DataSources without omission
-2. Users may provide limited DataSources. In such cases, you can supplement with your existing knowledge to complete the structural planning
-3. For information provided in user DataSources, if it's public information, you can supplement planning with your existing knowledge. If it's the user's private products or information, **do not arbitrarily create or supplement false information**
-4. If DataSources don't match the target audience, you need to reframe the DataSources to match the target audience
-
-Structural planning rules:
-
-1. {{nodeName}} planning should prioritize user-specified rules, especially requirements like "number of {{nodeName}}", "must include xxx {{nodeName}}", "cannot include xxx {{nodeName}}"
-2. Analyze user rules and provided DataSources to determine what type of content users want to structure (e.g., websites, documentation, books, etc.) and design appropriate structures for different content types
-3. {{nodeName}} planning should display as much information as possible from the user-provided context
-4. Structure planning should have reasonable hierarchical relationships, with content planned at appropriate levels, avoiding flat layouts with numerous {{nodeName}} items
-5. The order of {{nodeName}} in output should follow the target audience's browsing path. It doesn't need to follow the exact order in DataSources—progress from simple to advanced, from understanding to exploration, with reasonable pathways
-6. Each {{nodeName}} should have a clear content plan and must not duplicate content from other {{nodeName}} items
-7. Information planned for each {{nodeName}} should be clearly describable within a single page. If there's too much information to display or the concepts are too broad, consider splitting into sub-{{nodeName}} items
-8. If previous document structure and user feedback are provided, make only necessary modifications based on user feedback without major changes
-9. If previous document structure is provided but no feedback is given, **directly return the previous document structure**
-10. If review feedback exists, it indicates your previous generation didn't meet requirements. Optimize your output based on the review feedback
-
-{{nodeName}} planning rules:
-
-1. Each {{nodeName}} should include this information:
-
-- Title
-- Description of the important information this {{nodeName}} plans to display, with descriptions tailored to the target audience
-
-2. Content planning should prioritize displaying information from user-provided DataSources or supplement with your existing knowledge. Do not arbitrarily fabricate information.
-
-{% ifAsync docsType == 'general' %}
-  {% include "./document-rules.md" %}
-
-{% endif %}
-
-{% ifAsync docsType == 'getting-started' %}
-  {% include "./structure-getting-started.md" %}
-{% endif %}
-
-Other requirements:
-
-1. Must satisfy user specified rules
-2. Return information using the user's language {{locale}}
-</document_structure_rules>
-
-<conflict_resolution_guidance>
-When users select potentially conflicting options, conflict resolution guidance will be provided in user_rules. Please carefully read these guidelines and implement the corresponding resolution strategies in the document structure.
-
-Core principles for conflict resolution:
-1. **Layered need satisfaction**: Simultaneously satisfy multiple purposes and audiences through reasonable document structure hierarchy
-2. **Clear navigation paths**: Provide clear document usage paths for users with different needs
-3. **Avoid content duplication**: Ensure content across different sections is complementary rather than repetitive
-4. **Progressive disclosure**: From high-level overview to specific details, meeting needs at different depth levels
-
-Common conflict resolution patterns:
-- **Purpose conflicts**: Create hierarchical structures
-- **Audience conflicts**: Design role-oriented sections or paths
-- **Depth conflicts**: Adopt progressive structures that allow users to choose appropriate depth levels
-
-When generating document structure, prioritize conflict resolution strategies to ensure the final structure can harmoniously satisfy all user needs.
-</conflict_resolution_guidance>
-
-{% if glossary %}
-<terms>
-Glossary of specialized terms. Please ensure correct spelling when using these terms.
-
-{{glossary}}
-</terms>
-{% endif %}
-
-<datasources>
-{{ datasources }}
-</datasources>
-
-{% ifAsync docsType == 'general' %}
-  {% include "./structure-example.md" %}
-{% endif %}
-
-<output_constraints>
-
-1. Associated sourceIds should be as comprehensive as possible. You can include as many related datasources as possible.
-  - If datasources contain source code, **include as much related and adjacent source code as possible** to ensure quality of subsequent detail generation.
-  - First identify the most relevant source code files, then analyze the source code referenced within them. Referenced file paths, referenced files, and files in referenced paths all need to be included in sourceIds
-  - For referenced files, analyze another layer of source code files referenced within them and add to sourceIds to ensure complete context for detail generation
-2. Ensure sourceIds are never empty. Do not plan {{nodeName}} items without related data sources
-
-</output_constraints>