@aigne/doc-smith 0.9.8-alpha.3 → 0.9.8-alpha.4

package/agents/create/user-remove-document/review-documents-with-invalid-links.mjs

@@ -1,115 +0,0 @@
-import {
-  buildAllowedLinksFromStructure,
-  generateFileName,
-  pathToFlatName,
-} from "../../../utils/docs-finder-utils.mjs";
-
-/**
- * Generate feedback message for fixing invalid links in a document
- */
-function generateInvalidLinksFeedback(invalidLinks, documentPath, documentStructure) {
-  const invalidLinksList = invalidLinks.map((link) => `- ${link}`).join("\n");
-
-  // Build allowed links from document structure for replacement suggestions
-  const allowedLinks = buildAllowedLinksFromStructure(documentStructure);
-  const allowedLinksArray = Array.from(allowedLinks)
-    .filter((link) => link !== documentPath) // Exclude current document path
-    .sort();
-
-  const allowedLinksList =
-    allowedLinksArray.length > 0
-      ? allowedLinksArray.map((link) => `- ${link}`).join("\n")
-      : "(No available links)";
-
-  return `This document contains invalid links that need to be fixed. Please handle them according to the following instructions:
-
-**Invalid Links Found:**
-${invalidLinksList}
-
-**Available Valid Links:**
-${allowedLinksList}
-
-**Instructions for fixing invalid links:**
-
-1. For each invalid link found in the document:
-   - Using the document context and the list of available valid links, try to find a suitable replacement link from the available valid links.
-   - When choosing a replacement, exclude the current document path (${documentPath}); linking to the current document is not logical.
-   - **Do not consider the original invalid link or its related text**; they are outdated and should be replaced.
-
-2. If a suitable replacement link is found:
-   - Update **all related fields** associated with the invalid link (e.g., link URL, link text, surrounding context) according to the matched link from the available valid links.
-   - Ensure that after updating the link, the surrounding content remains consistent and natural. If there is a mismatch, update the corresponding content to keep everything aligned.
-
-3. If no suitable replacement link can be found:
-   - Remove the invalid link completely, including the link text and any associated content that only makes sense with that link.
-   - **Do not affect other unrelated content** in the document; only remove content that is directly tied to the invalid link.
-
-4. Ensure the document remains coherent and readable after the changes.`;
-}
-
-export default async function reviewDocumentsWithInvalidLinks(input = {}, options = {}) {
-  const { documentsWithInvalidLinks = [], documentStructure = [], locale = "en" } = input;
-
-  // If no documents with invalid links, return empty array
-  if (!Array.isArray(documentsWithInvalidLinks) || documentsWithInvalidLinks.length === 0) {
-    return {
-      documentsWithInvalidLinks: [],
-      documentsToUpdate: [],
-    };
-  }
-
-  // Create choices for user selection, default all checked
-  const choices = documentsWithInvalidLinks.map((doc) => {
-    const flatName = pathToFlatName(doc.path);
-    const filename = generateFileName(flatName, locale);
-
-    return {
-      name: `${doc.title} (${filename})`,
-      value: doc.path,
-      checked: true, // Default all selected
-      description: `Invalid Links(${doc.invalidLinks?.length || 0}): ${doc.invalidLinks?.join(", ")}`,
-    };
-  });
-
-  // Let user select documents (default all selected)
-  const selectedPaths = await options.prompts.checkbox({
-    message:
-      "Select documents with invalid links to fix (all selected by default, press Enter to confirm, or unselect all to skip):",
-    choices,
-  });
-
-  // Filter documents based on user selection
-  const selectedPathsSet = new Set(selectedPaths);
-  const filteredDocs = documentsWithInvalidLinks.filter((doc) => selectedPathsSet.has(doc.path));
-
-  if (filteredDocs.length === 0) {
-    return {
-      documentsWithInvalidLinks: [],
-      documentsToUpdate: [],
-    };
-  }
-
-  // Prepare documents: add necessary fields for update (without content)
-  const preparedDocs = [];
-
-  for (const doc of filteredDocs) {
-    if (!doc.path) continue;
-
-    // Find corresponding document in documentStructure to get additional fields
-    const structureDoc = documentStructure.find((item) => item.path === doc.path);
-
-    // Generate feedback message for fixing invalid links
-    const feedback = generateInvalidLinksFeedback(doc.invalidLinks, doc.path, documentStructure);
-
-    preparedDocs.push({
-      ...structureDoc,
-      feedback,
-      invalidLinks: doc.invalidLinks,
-    });
-  }
-
-  return {
-    documentsWithInvalidLinks: preparedDocs, // for print summary
-    documentsToUpdate: JSON.parse(JSON.stringify(preparedDocs)), // for batch update
-  };
-}

package/agents/create/user-review-document-structure.mjs

@@ -1,140 +0,0 @@
-import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
-import { recordUpdate } from "../../utils/history-utils.mjs";
-import { printDocumentStructure } from "../../utils/docs-finder-utils.mjs";
-import equal from "fast-deep-equal";
-
-export default async function userReviewDocumentStructure({ documentStructure, ...rest }, options) {
-  // Check if documentation structure exists
-  if (!documentStructure || !Array.isArray(documentStructure) || documentStructure.length === 0) {
-    console.log("No documentation structure was generated to review.");
-    return { documentStructure };
-  }
-
-  // Print current documentation structure in a user-friendly format
-  if (!rest.isChat) {
-    printDocumentStructure(documentStructure);
-
-    // Ask user if they want to review the documentation structure
-    const needReview = await options.prompts.select({
-      message: "Would you like to refine the documentation structure?",
-      choices: [
-        {
-          name: "No, looks good",
-          value: "no",
-        },
-        {
-          name: "Yes, optimize the structure (e.g. rename 'Getting Started' to 'Quick Start', move 'API Reference' before 'Configuration')",
-          value: "yes",
-        },
-      ],
-    });
-
-    if (needReview === "no") {
-      return { documentStructure };
-    }
-  }
-
-  let currentStructure = documentStructure;
-
-  const MAX_ITERATIONS = 100;
-  let iterationCount = 0;
-
-  // share current structure with updateDocumentStructure agent
-  options.context.userContext.currentStructure = currentStructure;
-  while (iterationCount < MAX_ITERATIONS) {
-    iterationCount++;
-
-    // Ask for feedback
-    const feedback = rest.isChat
-      ? rest.feedback
-      : await options.prompts.input({
-          message:
-            "How would you like to improve the structure?\n" +
-            "Examples:\n" +
-            "  • Add a new document 'Troubleshooting'\n" +
-            "  • Remove the 'Legacy Features' document\n" +
-            "  • Move 'Installation' to the top of the structure\n\n" +
-            "  Press Enter to finish reviewing:",
-        });
-
-    // If no feedback, break the loop
-    if (!feedback?.trim()) {
-      break;
-    }
-
-    // Get the refineDocumentStructure agent
-    const refineAgent = options.context.agents["generateStructureExp"];
-    if (!refineAgent) {
-      console.log(
-        "Unable to process your feedback - the documentation structure update feature is unavailable.",
-      );
-      console.log("Please try again later or contact support if this continues.");
-      break;
-    }
-
-    // Get user preferences
-    const structureRules = getActiveRulesForScope("structure", []);
-    const globalRules = getActiveRulesForScope("global", []);
-    const allApplicableRules = [...structureRules, ...globalRules];
-    const ruleTexts = allApplicableRules.map((rule) => rule.rule);
-    const userPreferences = ruleTexts.length > 0 ? ruleTexts.join("\n\n") : "";
-
-    try {
-      // Call refineDocumentStructure agent with feedback
-      const { message, ...result } = await options.context.invoke(refineAgent, {
-        ...rest,
-        // dataSourceChunk: rest.dataSources[0].dataSourceChunk,
-        userFeedback: feedback.trim(),
-        // documentStructure: currentStructure,
-        // userPreferences,
-      });
-
-      // currentStructure = options.context.userContext.currentStructure;
-      currentStructure = result.documentStructure;
-
-      if (rest.isChat && equal(currentStructure, documentStructure)) {
-        throw new Error(
-          `The suggested structure changes did not modify the existing documentation structure. ${message}`,
-        );
-      }
-
-      // Check if feedback should be saved as user preference
-      const feedbackRefinerAgent = options.context.agents["checkFeedbackRefiner"];
-      if (feedbackRefinerAgent) {
-        try {
-          await options.context.invoke(feedbackRefinerAgent, {
-            documentStructureFeedback: feedback.trim(),
-            stage: "structure",
-          });
-        } catch (refinerError) {
-          console.warn("Could not save feedback as a user preference:", refinerError.message);
-          console.warn("Your feedback was applied but not saved as a preference.");
-        }
-      }
-
-      // Record update in history
-      recordUpdate({
-        operation: "structure_update",
-        feedback: feedback.trim(),
-      });
-
-      // Print current documentation structure in a user-friendly format
-      printDocumentStructure(currentStructure);
-
-      if (rest.isChat) {
-        break;
-      }
-    } catch (error) {
-      console.error("Error processing your feedback:");
-      console.error(`Type: ${error.name}`);
-      console.error(`Message: ${error.message}`);
-      console.error(`Stack: ${error.stack}`);
-      console.log("\nPlease try rephrasing your feedback or continue with the current structure.");
-      break;
-    }
-  }
-
-  return { documentStructure: currentStructure };
-}
-
-userReviewDocumentStructure.taskTitle = "User review and modify documentation structure";

package/agents/create/utils/init-current-content.mjs

@@ -1,34 +0,0 @@
-import { readFileContent } from "../../../utils/docs-finder-utils.mjs";
-import { getFileName, userContextAt } from "../../../utils/utils.mjs";
-
-/**
- * Initialize currentContents in userContext for document update
- * Reads document content from file system and sets it in userContext
- * Uses getFileName utility to generate filename consistently
- */
-export default async function initCurrentContent(input, options) {
-  const { path, docsDir, locale = "en" } = input;
-
-  if (!path) {
-    return {};
-  }
-
-  // Generate filename using unified utility function
-  const fileName = getFileName(path, locale);
-
-  // Read document content
-  const content = docsDir ? await readFileContent(docsDir, fileName) : null;
-
-  if (!content) {
-    console.warn(`⚠️  Could not read content from ${fileName}`);
-    return {};
-  }
-
-  // Initialize currentContents[path] in userContext
-  const contentContext = userContextAt(options, `currentContents.${path}`);
-  contentContext.set(content);
-
-  return {};
-}
-
-initCurrentContent.task_render_mode = "hide";

package/agents/create/utils/merge-document-structures.mjs

@@ -1,30 +0,0 @@
-export default async function mergeDocumentStructures(input, options) {
-  if (input.projectName) {
-    options.context.userContext.projectName = input.projectName;
-  }
-  if (input.projectDesc) {
-    options.context.userContext.projectDesc = input.projectDesc;
-  }
-
-  input.projectName = options.context.userContext.projectName;
-  input.projectDesc = options.context.userContext.projectDesc;
-
-  options.context.userContext.originalDocumentStructure ??= [];
-
-  const originalStructures = [...options.context.userContext.originalDocumentStructure];
-
-  if (input.structures) {
-    for (const item of input.structures) {
-      const index = originalStructures.findIndex((s) => s.path === item.path);
-      if (index !== -1) {
-        originalStructures[index] = item;
-      } else {
-        originalStructures.push(item);
-      }
-    }
-  }
-
-  options.context.userContext.originalDocumentStructure = originalStructures;
-
-  return {};
-}

package/agents/evaluate/code-snippet.mjs

@@ -1,97 +0,0 @@
-import pMap from "p-map";
-import pRetry from "p-retry";
-import {
-  CODE_LANGUAGE_MAP_LINTER,
-  CODE_LANGUAGE_MAP_SUFFIX,
-} from "../../utils/constants/linter.mjs";
-import { debug } from "../../utils/debug.mjs";
-import { lintCode } from "../../utils/linter/index.mjs";
-import { getMarkdownAst, traverseMarkdownAst } from "../../utils/markdown/index.mjs";
-
-const severityMapLevel = {
-  error: "critical",
-  warning: "minor",
-};
-
-export default async function evaluateDocumentCode({ content }) {
-  const ast = getMarkdownAst({ markdown: content });
-  const checkPromiseList = [];
-  const checkListResult = [];
-  let totalCount = 0;
-  let ignoreCount = 0;
-  let errorCount = 0;
-
-  traverseMarkdownAst({
-    ast,
-    test: "code",
-    visitor(node) {
-      const linter = CODE_LANGUAGE_MAP_LINTER[node.lang];
-      if (linter) {
-        const suffix = CODE_LANGUAGE_MAP_SUFFIX[node.lang];
-        checkPromiseList.push({ linter, code: node.value, suffix });
-        totalCount += 1;
-      } else {
-        ignoreCount += 1;
-      }
-    },
-  });
-  const checkList = await pMap(
-    checkPromiseList,
-    async (item) => {
-      try {
-        const result = await pRetry(() => lintCode(item), {
-          onFailedAttempt: ({ error, attemptNumber, retriesLeft }) => {
-            debug(
-              `Attempt ${attemptNumber} failed: ${error.message}. There are ${retriesLeft} retries left.`,
-            );
-          },
-          retries: 3,
-        });
-        // lint occurs error, ignore
-        if (!result.success) {
-          debug("Lint failed", item, result);
-          return [];
-        }
-
-        if (!result.issues || result.issues.length === 0) {
-          debug("Lint result empty issues", item, result);
-          return [];
-        }
-
-        errorCount += 1;
-        return result.issues.map((x) => {
-          return {
-            ...x,
-            level: severityMapLevel[x.severity],
-          };
-        });
-      } catch (error) {
-        debug("Lint occurred error", error);
-        return [];
-      }
-    },
-    { concurrency: 5 },
-  );
-  checkListResult.push(...checkList.flat());
-
-  return {
-    codeEvaluation: {
-      details: checkListResult,
-      totalCount,
-      ignoreCount,
-      errorCount,
-    },
-  };
-}
-
-evaluateDocumentCode.description = "Traverse markdown code blocks and evaluate them.";
-
-evaluateDocumentCode.input_schema = {
-  type: "object",
-  properties: {
-    content: {
-      type: "string",
-      description: "Source markdown content to be evaluated.",
-    },
-  },
-};

package/agents/evaluate/document-structure.yaml

@@ -1,67 +0,0 @@
-name: evaluateDocumentStructure
-description: Evaluates the results generated by the document-structure agent to ensure they meet expectations, especially in scenarios with previous generation results and user feedback.
-instructions:
-  url: ../../prompts/evaluate/document-structure.md
-model:
-  model: gpt-5
-  temperature: 1
-task_render_mode: collapse
-task_title: Evaluate the structure of the documentation
-input_schema:
-  type: object
-  properties:
-    documentStructureYaml:
-      type: string
-      description: Documentation structure data
-    purposes:
-      type: string
-      description: User-selected document goals
-    audiences:
-      type: string
-      description: User-selected target audiences
-    coverageDepth:
-      type: string
-      description: User-selected content depth
-  required:
-    - documentStructureYaml
-    - purposes
-    - audiences
-    - coverageDepth
-output_schema:
-  type: object
-  properties:
-    structureEvaluation:
-      type: object
-      properties:
-        details:
-          type: array
-          items:
-            type: object
-            properties:
-              dimension:
-                type: string
-                enum: [purposeCoverage, audienceCoverage, depthCoverage]
-                description: Dimension associated with this observation
-              level:
-                type: string
-                enum: [excellent, good, meets, minor, critical]
-                description: Evaluation level applied to the observation
-              topic:
-                type: string
-                description: Short identifier for the purpose/audience/depth aspect being judged
-              description:
-                type: string
-                description: Why the level was assigned
-              line:
-                type: integer
-                description: Integer line number within the source document/module (use 0 if unknown)
-            required:
-              - dimension
-              - level
-              - topic
-              - description
-          description: List of detailed evaluations for each purpose dimension
-      required:
-        - details
-  required:
-    - structureEvaluation

package/agents/evaluate/document.yaml

@@ -1,82 +0,0 @@
-name: evaluateDocument
-description: Evaluates the quality of generated document content, ensuring compliance with user-configured goals, audiences, and knowledge level requirements.
-instructions:
-  url: ../../prompts/evaluate/document.md
-model:
-  model: gpt-5
-  temperature: 1
-task_render_mode: collapse
-task_title: Evaluate document for '{{ title }}'
-input_schema:
-  type: object
-  properties:
-    path:
-      type: string
-      description: Document path to be evaluated
-    content:
-      type: string
-      description: Document content to be evaluated
-    translationsString:
-      type: string
-      description: Document translation content
-    description:
-      type: string
-      description: Document content planning description
-    purposes:
-      type: string
-      description: User-selected document goals
-    audiences:
-      type: string
-      description: User-selected target audiences
-    readerKnowledgeLevel:
-      type: string
-      description: User-selected reader knowledge level
-    allDocumentContentList:
-      type: array
-      description: All document content list for better evaluate
-  required:
-    - content
-    - description
-    - purposes
-    - audiences
-    - readerKnowledgeLevel
-output_schema:
-  type: object
-  properties:
-    documentEvaluation:
-      type: object
-      properties:
-        details:
-          type: array
-          description: Detailed observations contributing to the final score
-          items:
-            type: object
-            properties:
-              dimension:
-                type: string
-                enum: [readability, coherence, contentQuality, consistency, purposeAlignment, audienceAlignment, knowledgeLevelAlignment]
-                description: Dimension associated with this observation
-              level:
-                type: string
-                enum: [excellent, good, meets, minor, critical]
-                description: Evaluation level applied to the observation
-              topic:
-                type: string
-                description: Short identifier for the assessed passage or section
-              line:
-                type: integer
-                description: Source line number related to the observation (0 if unknown)
-              description:
-                type: string
-                description: Impact-focused explanation of the observation
-            required:
-              - dimension
-              - level
-              - topic
-              - line
-              - description
-      required:
-        - details
-  required:
-    - documentEvaluation
-includeInputInOutput: true

package/agents/evaluate/generate-report.mjs

@@ -1,85 +0,0 @@
-import { writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { pick } from "@aigne/core/utils/type-utils.js";
-import isInCi from "is-in-ci";
-import openTerminal from "open";
-
-import { DOC_SMITH_DIR } from "../../utils/constants/index.mjs";
-import {
-  copyHtmlReportTemplate,
-  createReportStructure,
-  ensureDirectoryExists,
-  generateReportSuccessMessage,
-  generateTimestampForFolder,
-} from "../../utils/evaluate/report-utils.mjs";
-import { toRelativePath } from "../../utils/utils.mjs";
-
-/**
- * Generate and save evaluation report by aggregating results from both structure and document evaluation agents
- * @param {Object} params - Parameters object containing all evaluation data
- * @param {Object} params.purposeCoverage - Purpose coverage evaluation from evaluate/document-structure agent
- * @param {Object} params.audienceCoverage - Audience coverage evaluation from evaluate/document-structure agent
- * @param {Object} params.coverageDepthAlignment - Coverage depth alignment evaluation from evaluate/document-structure agent
- * @param {Array} params.originalDocumentStructure - Array of document evaluation results from evaluate/document agent
- * @param {Object} [params.metadata] - Additional metadata for the report
- * @param {string} [params.basePath] - Base path for saving reports, defaults to current working directory
- * @returns {Promise<string>} Path to the saved report file
- */
-export default async function generateEvaluationReport({
-  structureEvaluation,
-  originalDocumentStructure,
-  metadata = {},
-  basePath = process.cwd(),
-  projectName,
-  projectDesc,
-  projectLogo,
-  documentPurpose,
-  targetAudienceTypes,
-  readerKnowledgeLevel,
-  documentationDepth,
-  targetAudience,
-  open = true,
-}) {
-  const timestamp = new Date().toISOString();
-  const timestampForFolder = generateTimestampForFolder();
-  const documentEvaluations = originalDocumentStructure.map((x) =>
-    pick(x, ["title", "description", "path", "parentId", "documentEvaluation", "codeEvaluation"]),
-  );
-
-  // Create report structure
-  const report = createReportStructure({
-    timestamp,
-    metadata,
-    structureEvaluation,
-    documentEvaluations,
-    projectName,
-    projectDesc,
-    projectLogo,
-    documentPurpose,
-    targetAudienceTypes,
-    readerKnowledgeLevel,
-    documentationDepth,
-    targetAudience,
-  });
-
-  const saveDir = join(basePath, DOC_SMITH_DIR, "evaluate", timestampForFolder);
-  const jsonReportPath = join(saveDir, "integrity-report.json");
-
-  await ensureDirectoryExists(saveDir);
-  await writeFile(jsonReportPath, JSON.stringify(report, null, 2), "utf8");
-
-  // Copy HTML report template
-  const htmlReportPath = await copyHtmlReportTemplate(saveDir, report);
-
-  // Generate success message
-  const message = generateReportSuccessMessage(toRelativePath(jsonReportPath), htmlReportPath);
-  if (open && !isInCi) {
-    openTerminal(htmlReportPath);
-  }
-
-  return {
-    message,
-  };
-}
-
-generateEvaluationReport.taskTitle = "Generate evaluation report";