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

package/agents/clear/clear-document-structure.mjs

@@ -0,0 +1,106 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { pathExists, toDisplayPath } from "../../utils/file-utils.mjs";
+
+export default async function clearDocumentStructure(input = {}, _options = {}) {
+  const { docsDir, workDir } = input;
+  const cwd = workDir || process.cwd();
+
+  // Fixed path where structure-plan.json is saved
+  const outputDir = join(cwd, ".aigne", "doc-smith", "output");
+  const structurePlanPath = join(outputDir, "structure-plan.json");
+
+  const results = [];
+  let hasError = false;
+
+  // Clear structure-plan.json
+  try {
+    const structureExists = await pathExists(structurePlanPath);
+    await rm(structurePlanPath, { force: true });
+
+    const structureDisplayPath = toDisplayPath(structurePlanPath);
+    const structureMessage = structureExists
+      ? `Cleared document structure plan (${structureDisplayPath})`
+      : `Document structure plan already empty (${structureDisplayPath})`;
+
+    results.push({
+      type: "structure",
+      cleared: structureExists,
+      message: structureMessage,
+    });
+  } catch (error) {
+    hasError = true;
+    results.push({
+      type: "structure",
+      error: true,
+      message: `Failed to clear document structure plan: ${error.message}`,
+    });
+  }
+
+  // Clear documents directory if provided
+  if (docsDir) {
+    try {
+      const docsExists = await pathExists(docsDir);
+      await rm(docsDir, { recursive: true, force: true });
+
+      const docsDisplayPath = toDisplayPath(docsDir);
+      const docsMessage = docsExists
+        ? `Cleared documents directory (${docsDisplayPath})`
+        : `Documents directory already empty (${docsDisplayPath})`;
+
+      results.push({
+        type: "documents",
+        cleared: docsExists,
+        message: docsMessage,
+      });
+    } catch (error) {
+      hasError = true;
+      results.push({
+        type: "documents",
+        error: true,
+        message: `Failed to clear documents directory: ${error.message}`,
+      });
+    }
+  }
+
+  // Prepare summary message
+  const clearedItems = results.filter((r) => r.cleared).length;
+  const errorItems = results.filter((r) => r.error).length;
+
+  let header;
+  if (errorItems > 0) {
+    header = "Document structure cleanup finished with some issues.";
+  } else if (clearedItems > 0) {
+    header = "Document structure cleared successfully!";
+  } else {
+    header = "Document structure already empty.";
+  }
+
+  const detailLines = results.map((item) => `- ${item.message}`).join("\n");
+  const message = [header, "", detailLines].filter(Boolean).join("\n");
+
+  return {
+    message,
+    results,
+    hasError,
+    clearedCount: clearedItems,
+  };
+}
+
+clearDocumentStructure.input_schema = {
+  type: "object",
+  properties: {
+    docsDir: {
+      type: "string",
+      description: "The documents directory to clear (optional)",
+    },
+    workDir: {
+      type: "string",
+      description: "The working directory (defaults to current directory)",
+    },
+  },
+};
+
+clearDocumentStructure.taskTitle = "Clear document structure and all generated documents";
+clearDocumentStructure.description =
+  "Clear the document structure plan (structure-plan.json) and optionally the documents directory";

package/agents/clear/clear-generated-docs.mjs

@@ -0,0 +1,51 @@
+import { rm } from "node:fs/promises";
+import { pathExists, resolveToAbsolute, toDisplayPath } from "../../utils/file-utils.mjs";
+
+export default async function clearGeneratedDocs(input = {}, _options = {}) {
+  const { docsDir } = input;
+
+  if (!docsDir) {
+    return {
+      message: "No generated documents directory specified",
+    };
+  }
+
+  const generatedDocsPath = resolveToAbsolute(docsDir);
+
+  const displayPath = toDisplayPath(generatedDocsPath);
+
+  try {
+    const existed = await pathExists(generatedDocsPath);
+    await rm(generatedDocsPath, { recursive: true, force: true });
+
+    const message = existed
+      ? `Cleared generated documents (${displayPath})`
+      : `Generated documents already empty (${displayPath})`;
+
+    return {
+      message,
+      cleared: existed,
+      path: displayPath,
+    };
+  } catch (error) {
+    return {
+      message: `Failed to clear generated documents: ${error.message}`,
+      error: true,
+      path: displayPath,
+    };
+  }
+}
+
+clearGeneratedDocs.input_schema = {
+  type: "object",
+  properties: {
+    docsDir: {
+      type: "string",
+      description: "The generated documents directory to clear",
+    },
+  },
+  required: ["docsDir"],
+};
+
+clearGeneratedDocs.taskTitle = "Clear all generated documents";
+clearGeneratedDocs.description = "Clear the generated documents directory";

package/agents/clear/index.yaml

@@ -0,0 +1,23 @@
+type: team
+name: clear
+alias:
+  - clear
+description: Clear various types of data including document structure, generated documents, configuration, and authorization tokens
+skills:
+  - url: ../init/index.mjs
+    default_input:
+      skipIfExists: true
+  - ./choose-contents.mjs
+input_schema:
+  type: object
+  properties:
+    targets:
+      type: array
+      description: Items to clear without confirmation
+      items:
+        type: string
+        enum:
+          - documentStructure
+          - generatedDocs
+          - documentConfig
+          - authTokens

package/agents/evaluate/code-snippet.mjs

@@ -0,0 +1,93 @@
+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) => {
+      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],
+        };
+      });
+    },
+    { concurrency: 5 },
+  );
+  checkListResult.push(...checkList.flat());
+
+  return {
+    codeEvaluation: {
+      baseline: 100,
+      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

@@ -0,0 +1,70 @@
+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: openai/gpt-5
+# model: anthropic/claude-opus-4-0
+task_render_mode: collapse
+task_title: Evaluate the structure of the documentation
+input_schema:
+  type: object
+  properties:
+    documentStructureYaml:
+      type: string
+      description: Document structure planning
+    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:
+        baseline:
+          type: integer
+          description: Baseline score of selected purposes
+        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:
+        - baseline
+        - details
+  required:
+    - structureEvaluation

package/agents/evaluate/document.yaml

@@ -0,0 +1,79 @@
+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: openai/gpt-5
+# model: anthropic/claude-opus-4-0
+task_render_mode: collapse
+task_title: Evaluate document for '{{ title }}'
+input_schema:
+  type: object
+  properties:
+    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
+  required:
+    - content
+    - description
+    - purposes
+    - audiences
+    - readerKnowledgeLevel
+output_schema:
+  type: object
+  properties:
+    documentEvaluation:
+      type: object
+      properties:
+        baseline:
+          type: integer
+          description: Fixed baseline score (80)
+        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, navigability]
+                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:
+        - baseline
+        - details
+  required:
+    - documentEvaluation
+includeInputInOutput: true

package/agents/evaluate/generate-report.mjs

@@ -0,0 +1,78 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pick } from "@aigne/core/utils/type-utils.js";
+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,
+}) {
+  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);
+
+  return {
+    message,
+  };
+}
+
+generateEvaluationReport.taskTitle = "Generate evaluation report";

package/agents/evaluate/index.yaml

@@ -0,0 +1,39 @@
+type: team
+name: evaluate
+description: Evaluate document quality
+skills:
+  - url: ../init/index.mjs
+    default_input:
+      skipIfExists: true
+  - ../utils/load-sources.mjs
+  - ../utils/format-document-structure.mjs
+  - type: transform
+    name: transformData
+    task_render_mode: hide
+    jsonata: |
+      $merge([
+        $,
+        {
+          "documentStructure": originalDocumentStructure,
+          "datasources": "",
+          "datasourcesList": ""
+        }
+      ])
+  - ./document-structure.yaml
+  - type: team
+    name: batchEvaluateDocument
+    skills:
+      - ../utils/load-document-all-content.mjs
+      - ./document.yaml
+      - ./code-snippet.mjs
+      - type: transform
+        task_render_mode: hide
+        jsonata: |
+          $merge([
+            $
+          ])
+    iterate_on: originalDocumentStructure
+    concurrency: 5
+    mode: sequential
+  - ./generate-report.mjs
+mode: sequential

package/agents/generate/document-structure-tools/add-document.mjs

@@ -0,0 +1,56 @@
+import {
+  getAddDocumentInputJsonSchema,
+  getAddDocumentOutputJsonSchema,
+  validateAddDocumentInput,
+} from "../../../types/document-structure-schema.mjs";
+
+export default async function addDocument(input) {
+  // Validate input using Zod schema
+  const validation = validateAddDocumentInput(input);
+  if (!validation.success) {
+    console.log(`⚠️  Cannot add document: ${validation.error}`);
+    return { documentStructure: input.documentStructure };
+  }
+
+  const { documentStructure, title, description, path, parentId, sourceIds } = validation.data;
+
+  // Validate parent exists if parentId is provided
+  if (parentId && parentId !== "null") {
+    const parentExists = documentStructure.some((item) => item.path === parentId);
+    if (!parentExists) {
+      console.log(`⚠️  Cannot add document: Parent document '${parentId}' not found.`);
+      return { documentStructure };
+    }
+  }
+
+  // Check if document with same path already exists
+  const existingDocument = documentStructure.find((item) => item.path === path);
+  if (existingDocument) {
+    console.log(
+      `⚠️  Cannot add document: A document with path '${path}' already exists. Choose a different path.`,
+    );
+    return { documentStructure };
+  }
+
+  // Create new document object
+  const newDocument = {
+    title,
+    description,
+    path,
+    parentId: parentId || null,
+    sourceIds: [...sourceIds], // Create a copy of the array
+  };
+
+  // Add the new document to the document structure
+  const updatedStructure = [...documentStructure, newDocument];
+
+  return {
+    documentStructure: updatedStructure,
+    addedDocument: newDocument,
+  };
+}
+
+addDocument.taskTitle = "Add new document";
+addDocument.description = "Add a new document to the document structure";
+addDocument.inputSchema = getAddDocumentInputJsonSchema();
+addDocument.outputSchema = getAddDocumentOutputJsonSchema();

package/agents/generate/document-structure-tools/delete-document.mjs

@@ -0,0 +1,49 @@
+import {
+  getDeleteDocumentInputJsonSchema,
+  getDeleteDocumentOutputJsonSchema,
+  validateDeleteDocumentInput,
+} from "../../../types/document-structure-schema.mjs";
+
+export default async function deleteDocument(input) {
+  // Validate input using Zod schema
+  const validation = validateDeleteDocumentInput(input);
+  if (!validation.success) {
+    console.log(`⚠️  Cannot delete document: ${validation.error}`);
+    return { documentStructure: input.documentStructure };
+  }
+
+  const { documentStructure, path } = validation.data;
+
+  // Find the document to delete
+  const documentIndex = documentStructure.findIndex((item) => item.path === path);
+  if (documentIndex === -1) {
+    console.log(
+      `⚠️  Cannot delete document: Document '${path}' does not exist. Please choose an existing document to delete.`,
+    );
+    return { documentStructure };
+  }
+
+  const documentToDelete = documentStructure[documentIndex];
+
+  // Check if any other documents have this document as parent
+  const childDocuments = documentStructure.filter((item) => item.parentId === path);
+  if (childDocuments.length > 0) {
+    console.log(
+      `⚠️  Cannot delete document: Document '${path}' has ${childDocuments.length} child document(s): ${childDocuments.map((p) => p.path).join(", ")}. Please first move or delete these child documents.`,
+    );
+    return { documentStructure };
+  }
+
+  // Remove the document from the document structure
+  const updatedStructure = documentStructure.filter((_, index) => index !== documentIndex);
+
+  return {
+    documentStructure: updatedStructure,
+    deletedDocument: documentToDelete,
+  };
+}
+
+deleteDocument.taskTitle = "Delete document";
+deleteDocument.description = "Delete a document from the document structure";
+deleteDocument.inputSchema = getDeleteDocumentInputJsonSchema();
+deleteDocument.outputSchema = getDeleteDocumentOutputJsonSchema();