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

package/types/document-structure-schema.mjs

@@ -0,0 +1,244 @@
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+// Document item schema - represents a single document in the structure
+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(),
+  sourceIds: z.array(z.string()).min(1, "At least one source ID is required"),
+});
+
+// Document structure schema - represents the entire document 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 "/"'),
+  parentId: z.string().nullable().optional(),
+  sourceIds: z.array(z.string()).min(1, "At least one source ID is required"),
+});
+
+export const addDocumentOutputSchema = z.object({
+  documentStructure: documentStructureSchema,
+  addedDocument: documentItemSchema.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,
+  deletedDocument: documentItemSchema.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,
+  originalDocument: documentItemSchema.optional(),
+  updatedDocument: documentItemSchema.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(),
+    sourceIds: z.array(z.string()).min(1).optional(),
+  })
+  .refine(
+    (data) =>
+      data.title !== undefined || data.description !== undefined || data.sourceIds !== undefined,
+    {
+      message: "At least one field (title, description, or sourceIds) must be provided for update",
+    },
+  );
+
+export const updateDocumentOutputSchema = z.object({
+  documentStructure: documentStructureSchema,
+  originalDocument: documentItemSchema.optional(),
+  updatedDocument: documentItemSchema.optional(),
+});
+
+// JSON Schema conversion functions using zodToJsonSchema
+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 '/')";
+    schema.properties.parentId.description =
+      "Parent document path (leave empty for top-level documents)";
+    schema.properties.sourceIds.description =
+      "Source references from associated data sources (required)";
+  }
+  return schema;
+};
+
+export const getAddDocumentOutputJsonSchema = () => {
+  const schema = zodToJsonSchema(addDocumentOutputSchema);
+  if (schema.properties) {
+    schema.properties.documentStructure.description =
+      "Updated document structure array with the new document added";
+    schema.properties.addedDocument.description = "The newly added document object";
+  }
+  return schema;
+};
+
+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;
+};
+
+export const getDeleteDocumentOutputJsonSchema = () => {
+  const schema = zodToJsonSchema(deleteDocumentOutputSchema);
+  if (schema.properties) {
+    schema.properties.documentStructure.description =
+      "Updated document structure array with the document removed";
+    schema.properties.deletedDocument.description = "The deleted document object";
+  }
+  return schema;
+};
+
+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)";
+  }
+  return schema;
+};
+
+export const getMoveDocumentOutputJsonSchema = () => {
+  const schema = zodToJsonSchema(moveDocumentOutputSchema);
+  if (schema.properties) {
+    schema.properties.documentStructure.description =
+      "Updated document structure array with the document moved";
+    schema.properties.originalDocument.description = "The original document object before moving";
+    schema.properties.updatedDocument.description = "The updated document object after moving";
+  }
+  return schema;
+};
+
+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)";
+    schema.properties.sourceIds.description =
+      "New source references for the document (optional, cannot be empty if provided)";
+  }
+  // Add anyOf constraint for at least one update field
+  schema.anyOf = [
+    { required: ["title"] },
+    { required: ["description"] },
+    { required: ["sourceIds"] },
+  ];
+  return schema;
+};
+
+export const getUpdateDocumentOutputJsonSchema = () => {
+  const schema = zodToJsonSchema(updateDocumentOutputSchema);
+  if (schema.properties) {
+    schema.properties.documentStructure.description =
+      "Updated document structure array with the document modified";
+    schema.properties.originalDocument.description = "The original document object before update";
+    schema.properties.updatedDocument.description =
+      "The updated document object after modification";
+  }
+  return schema;
+};
+
+// Validation helper functions
+export const validateAddDocumentInput = (input) => {
+  try {
+    return {
+      success: true,
+      data: addDocumentInputSchema.parse(input),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error:
+        error.errors?.map((err) => `${err.path.join(".")}: ${err.message}`).join(", ") ||
+        error.message,
+    };
+  }
+};
+
+export const validateDeleteDocumentInput = (input) => {
+  try {
+    return {
+      success: true,
+      data: deleteDocumentInputSchema.parse(input),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error:
+        error.errors?.map((err) => `${err.path.join(".")}: ${err.message}`).join(", ") ||
+        error.message,
+    };
+  }
+};
+
+export const validateMoveDocumentInput = (input) => {
+  try {
+    return {
+      success: true,
+      data: moveDocumentInputSchema.parse(input),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error:
+        error.errors?.map((err) => `${err.path.join(".")}: ${err.message}`).join(", ") ||
+        error.message,
+    };
+  }
+};
+
+export const validateUpdateDocumentInput = (input) => {
+  try {
+    return {
+      success: true,
+      data: updateDocumentInputSchema.parse(input),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error:
+        error.errors?.map((err) => `${err.path.join(".")}: ${err.message}`).join(", ") ||
+        error.message,
+    };
+  }
+};
+
+// Type inference helpers for better IDE support
+export const createDocumentItem = (data) => documentItemSchema.parse(data);
+export const createDocumentStructure = (data) => documentStructureSchema.parse(data);

package/utils/auth-utils.mjs

@@ -7,6 +7,7 @@ import chalk from "chalk";
 import open from "open";
 import { joinURL } from "ufo";
 import { parse, stringify } from "yaml";
+
 import {
   ComponentNotFoundError,
   getComponentMountPoint,
@@ -16,7 +17,8 @@ import {
   BLOCKLET_ADD_COMPONENT_DOCS,
   DISCUSS_KIT_DID,
   DISCUSS_KIT_STORE_URL,
-} from "./constants.mjs";
+  DOC_OFFICIAL_ACCESS_TOKEN,
+} from "./constants/index.mjs";
 
 const WELLKNOWN_SERVICE_PATH_PREFIX = "/.well-known/service";
 
@@ -37,8 +39,9 @@ export async function getAccessToken(appUrl, ltToken = "") {
       if (existsSync(DOC_SMITH_ENV_FILE)) {
         const data = await readFile(DOC_SMITH_ENV_FILE, "utf8");
         if (data.includes("DOC_DISCUSS_KIT_ACCESS_TOKEN")) {
-          const envs = parse(data);
-          if (envs[hostname]?.DOC_DISCUSS_KIT_ACCESS_TOKEN) {
+          // Handle empty or invalid YAML files
+          const envs = data.trim() ? parse(data) : null;
+          if (envs?.[hostname]?.DOC_DISCUSS_KIT_ACCESS_TOKEN) {
             accessToken = envs[hostname].DOC_DISCUSS_KIT_ACCESS_TOKEN;
           }
         }
@@ -111,9 +114,12 @@ export async function getAccessToken(appUrl, ltToken = "") {
       mkdirSync(aigneDir, { recursive: true });
     }
 
-    const existingConfig = existsSync(DOC_SMITH_ENV_FILE)
-      ? parse(await readFile(DOC_SMITH_ENV_FILE, "utf8"))
-      : {};
+    let existingConfig = {};
+    if (existsSync(DOC_SMITH_ENV_FILE)) {
+      const fileContent = await readFile(DOC_SMITH_ENV_FILE, "utf8");
+      const parsedConfig = fileContent.trim() ? parse(fileContent) : null;
+      existingConfig = parsedConfig || {};
+    }
 
     await writeFile(
       DOC_SMITH_ENV_FILE,
@@ -134,3 +140,122 @@ export async function getAccessToken(appUrl, ltToken = "") {
 
   return accessToken;
 }
+
+/**
+ * Get official access token from environment, config file, or prompt user for authorization.
+ * @param {string} baseUrl - The official service URL
+ * @returns {Promise<string>} - The access token
+ */
+export async function getOfficialAccessToken(baseUrl) {
+  // Early parameter validation
+  if (!baseUrl) {
+    throw new Error("baseUrl parameter is required for getOfficialAccessToken.");
+  }
+
+  // Parse URL once and reuse
+  const urlObj = new URL(baseUrl);
+  const { hostname, origin } = urlObj;
+  const DOC_SMITH_ENV_FILE = join(homedir(), ".aigne", "doc-smith-connected.yaml");
+
+  // 1. Check environment variable
+  let accessToken = process.env[DOC_OFFICIAL_ACCESS_TOKEN];
+
+  // 2. Check config file if not in env
+  if (!accessToken) {
+    try {
+      if (existsSync(DOC_SMITH_ENV_FILE)) {
+        const data = await readFile(DOC_SMITH_ENV_FILE, "utf8");
+        // Handle empty or invalid YAML files
+        const envs = data.trim() ? parse(data) : null;
+        if (envs) {
+          accessToken = envs[hostname]?.[DOC_OFFICIAL_ACCESS_TOKEN];
+        }
+      }
+    } catch (_error) {
+      // ignore
+    }
+  }
+
+  // If token is found, return it
+  if (accessToken) {
+    return accessToken;
+  }
+
+  // Generate new access token
+  const connectUrl = joinURL(origin, WELLKNOWN_SERVICE_PATH_PREFIX);
+
+  try {
+    const result = await createConnect({
+      connectUrl,
+      connectAction: "gen-simple-access-key",
+      source: "AIGNE DocSmith connect to official service",
+      closeOnSuccess: true,
+      appName: "AIGNE DocSmith",
+      appLogo: "https://docsmith.aigne.io/image-bin/uploads/9645caf64b4232699982c4d940b03b90.svg",
+      openPage: (pageUrl) => {
+        console.log(
+          "🔗 Please open this URL in your browser to authorize access: ",
+          chalk.cyan(pageUrl),
+          "\n",
+        );
+        open(pageUrl);
+      },
+    });
+
+    accessToken = result.accessKeySecret;
+    process.env[DOC_OFFICIAL_ACCESS_TOKEN] = accessToken;
+
+    // Save the access token to config file
+    await saveTokenToConfigFile(
+      DOC_SMITH_ENV_FILE,
+      hostname,
+      DOC_OFFICIAL_ACCESS_TOKEN,
+      accessToken,
+    );
+  } catch (error) {
+    console.debug(error);
+    throw new Error(
+      "Failed to obtain official access token. Please check your network connection and try again later.",
+    );
+  }
+
+  return accessToken;
+}
+
+/**
+ * Helper function to save access token to config file
+ * @param {string} configFile - Path to config file
+ * @param {string} hostname - Hostname key
+ * @param {string} tokenKey - Token key name
+ * @param {string} tokenValue - Token value
+ */
+async function saveTokenToConfigFile(configFile, hostname, tokenKey, tokenValue) {
+  try {
+    const aigneDir = join(homedir(), ".aigne");
+    if (!existsSync(aigneDir)) {
+      mkdirSync(aigneDir, { recursive: true });
+    }
+
+    let existingConfig = {};
+    if (existsSync(configFile)) {
+      const fileContent = await readFile(configFile, "utf8");
+      // Handle empty or invalid YAML files
+      const parsedConfig = fileContent.trim() ? parse(fileContent) : null;
+      existingConfig = parsedConfig || {};
+    }
+
+    await writeFile(
+      configFile,
+      stringify({
+        ...existingConfig,
+        [hostname]: {
+          ...existingConfig[hostname],
+          [tokenKey]: tokenValue,
+        },
+      }),
+    );
+  } catch (error) {
+    console.warn(`Failed to save token to config file ${configFile}: ${error.message}`, error);
+    // Don't throw here, as the token is already obtained and set in env
+  }
+}

package/utils/conflict-detector.mjs

@@ -1,4 +1,8 @@
-import { CONFLICT_RESOLUTION_RULES, CONFLICT_RULES, RESOLUTION_STRATEGIES } from "./constants.mjs";
+import {
+  CONFLICT_RESOLUTION_RULES,
+  CONFLICT_RULES,
+  RESOLUTION_STRATEGIES,
+} from "./constants/index.mjs";
 
 /**
  * Get filtered options based on cross-question conflict rules

package/utils/{constants.mjs → constants/index.mjs}

@@ -332,6 +332,8 @@ export const DISCUSS_KIT_DID = "z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu";
 
 export const PAYMENT_KIT_DID = "z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk";
 
+export const DOC_OFFICIAL_ACCESS_TOKEN = "DOC_OFFICIAL_ACCESS_TOKEN";
+
 // Discuss Kit related URLs
 export const DISCUSS_KIT_STORE_URL =
   "https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu";
@@ -540,3 +542,110 @@ export const TMP_DIR = ".tmp";
 export const TMP_DOCS_DIR = "docs";
 
 export const TMP_ASSETS_DIR = "assets";
+
+// Default evaluation scoring weights
+export const DEFAULT_EVALUATION_WEIGHTS = {
+  evaluationConfig: {
+    accuracy: {
+      weight: 0.35,
+      description: "Technical correctness of the documentation.",
+      subDimensions: {
+        signatureConsistency: {
+          weight: 0.5,
+          description:
+            "Function signatures match the source code (e.g., OpenAPI spec, TypeScript types).",
+        },
+        linkValidity: {
+          weight: 0.25,
+          description: "No broken internal links or invalid cross-references.",
+        },
+        codeExampleIntegrity: {
+          weight: 0.25,
+          description:
+            "All code blocks are syntactically valid and labeled with the correct language.",
+        },
+      },
+    },
+    coverage: {
+      weight: 0.35,
+      description: "Completeness of documentation for all public components.",
+      subDimensions: {
+        apiCoverage: {
+          weight: 0.4,
+          description: "Percentage of exported functions/classes documented.",
+        },
+        paramReturnCoverage: {
+          weight: 0.3,
+          description: "Percentage of function parameters and return values described.",
+        },
+        changeTracking: {
+          weight: 0.3,
+          description:
+            "All new or modified code since the last commit is reflected in the documentation.",
+        },
+      },
+    },
+    readability: {
+      weight: 0.15,
+      description: "Ease of understanding for human readers.",
+      subDimensions: {
+        clarityScore: {
+          weight: 0.28,
+          description:
+            "Overall clarity including reading coherence, logical flow and translation quality.",
+        },
+        consistency: {
+          weight: 0.12,
+          description: "Terminology, style and formatting are unified and professional.",
+        },
+        contentQuality: {
+          weight: 0.24,
+          description:
+            "Accurate and complete content that adds value with sufficient detail and examples.",
+        },
+        purposeAlignment: {
+          weight: 0.14,
+          description:
+            "Content matches the intended purpose such as quick start, API reference or troubleshooting.",
+        },
+        audienceAlignment: {
+          weight: 0.12,
+          description:
+            "Language and examples match the target audience (e.g., developers, non-technical users).",
+        },
+        knowledgeLevelAlignment: {
+          weight: 0.1,
+          description: "Depth and difficulty fit the readers' knowledge level.",
+        },
+      },
+    },
+    structure: {
+      weight: 0.15,
+      description: "Organization and navigability of the documentation.",
+      subDimensions: {
+        navigability: {
+          weight: 0.2,
+          description: "Table of contents entries correctly link to headings.",
+        },
+        informationScent: {
+          weight: 0.2,
+          description:
+            "Key pages such as Quick Start can be reached within three clicks from the homepage.",
+        },
+        purposeCoverage: {
+          weight: 0.25,
+          description:
+            "Structure covers all selected documentation goals without forcing them into a single page.",
+        },
+        audienceCoverage: {
+          weight: 0.2,
+          description: "Structure covers the main intended audience groups.",
+        },
+        coverageDepthAlignment: {
+          weight: 0.15,
+          description: "Overall balance of conciseness, depth and breadth meets user expectations.",
+        },
+      },
+    },
+  },
+};

package/utils/constants/linter.mjs

@@ -0,0 +1,102 @@
+export const LINTER_API_URL = process.env.LINTER_API_URL || "https://linter.abtnet.io";
+
+export const LINTER_SUPPORTED_FILE = {
+  biome: [".js", ".jsx", ".ts", ".tsx", ".json"],
+  eslint: [".js", ".jsx", ".ts", ".tsx", ".vue"],
+  oxlint: [".js", ".jsx", ".ts", ".tsx"],
+  prettier: [".js", ".jsx", ".ts", ".tsx", ".json", ".css"],
+  pylint: [".py"],
+  flake8: [".py"],
+  black: [".py"],
+  isort: [".py"],
+  mypy: [".py"],
+  shellcheck: [".sh", ".bash", ".dash", ".ksh"],
+  "golangci-lint": [".go"],
+  rubocop: [".rb", ".rake", ".gemfile", "Gemfile"],
+  hadolint: ["Dockerfile", ".dockerfile"],
+  yamllint: [".yml", ".yaml"],
+  stylelint: [".css", ".scss", ".sass"],
+};
+export const SUFFIX_TO_CODE_LANGUAGE = {
+  ".js": ["js", "javascript", "node"],
+  ".jsx": ["jsx"],
+  ".ts": ["ts", "typescript"],
+  ".tsx": ["tsx"],
+  ".json": ["json"],
+  ".vue": ["vue"],
+  ".css": ["css"],
+  ".py": ["python", "python3"],
+  ".sh": ["shell", "sh", "shell-script", "bash", "zsh"],
+  ".go": ["go", "golang"],
+  ".rb": ["ruby", "jruby", "macruby", "rake", "rb", "rbx"],
+  ".dockerfile": ["dockerfile"],
+  ".yml": ["yaml", "yml"],
+  ".sass": ["sass"],
+  ".scss": ["scss"],
+};
+
+export const CODE_LANGUAGE_MAP_LINTER = {
+  js: "biome-lint",
+  javascript: "biome-lint",
+  node: "biome-lint",
+  jsx: "biome-lint",
+  ts: "biome-lint",
+  typescript: "biome-lint",
+  tsx: "biome-lint",
+  json: "biome-lint",
+  vue: "eslint",
+  css: "prettier",
+  python: "flake8",
+  python3: "flake8",
+  shell: "shellcheck",
+  sh: "shellcheck",
+  "shell-script": "shellcheck",
+  bash: "shellcheck",
+  zsh: "shellcheck",
+  go: "golangci-lint",
+  golang: "golangci-lint",
+  ruby: "rubocop",
+  jruby: "rubocop",
+  macruby: "rubocop",
+  rake: "rubocop",
+  rb: "rubocop",
+  rbx: "rubocop",
+  dockerfile: "hadolint",
+  yaml: "yamllint",
+  yml: "yamllint",
+  sass: "stylelint",
+  scss: "stylelint",
+};
+
+export const CODE_LANGUAGE_MAP_SUFFIX = {
+  js: ".js",
+  javascript: ".js",
+  node: ".js",
+  jsx: ".jsx",
+  ts: ".ts",
+  typescript: ".ts",
+  tsx: ".tsx",
+  json: ".json",
+  vue: ".vue",
+  css: ".css",
+  python: ".py",
+  python3: ".py",
+  shell: ".sh",
+  sh: ".sh",
+  "shell-script": ".sh",
+  bash: ".sh",
+  zsh: ".sh",
+  go: ".go",
+  golang: ".go",
+  ruby: ".rb",
+  jruby: ".rb",
+  macruby: ".rb",
+  rake: ".rb",
+  rb: ".rb",
+  rbx: ".rb",
+  dockerfile: ".dockerfile",
+  yaml: ".yml",
+  yml: ".yml",
+  sass: ".sass",
+  scss: ".scss",
+};

package/utils/d2-utils.mjs

@@ -1,7 +1,6 @@
 import path from "node:path";
 
 import { D2 } from "@terrastruct/d2";
-import Debug from "debug";
 import fs from "fs-extra";
 import { glob } from "glob";
 import pMap from "p-map";
@@ -13,12 +12,11 @@ import {
   FILE_CONCURRENCY,
   TMP_ASSETS_DIR,
   TMP_DIR,
-} from "./constants.mjs";
+} from "./constants/index.mjs";
+import { debug } from "./debug.mjs";
 import { iconMap } from "./icon-map.mjs";
 import { getContentHash } from "./utils.mjs";
 
-const debug = Debug("doc-smith");
-
 export async function getChart({ content, strict }) {
   const d2 = new D2();
   const iconUrlList = Object.keys(iconMap);

package/utils/debug.mjs

@@ -0,0 +1,3 @@
+import Debug from "debug";
+
+export const debug = Debug("doc-smith");