@doccov/sdk 0.8.0 → 0.9.0

package/dist/index.js

@@ -3034,6 +3034,8 @@ function parseJSDocBlock(commentText) {
     params: [],
     throws: [],
     examples: [],
+    structuredExamples: [],
+    seeAlso: [],
     tags: [],
     rawParamNames: []
   };
@@ -3154,6 +3156,43 @@ function parseThrowsContent(content) {
     description: processInlineLinks(remaining)
   };
 }
+function parseExampleContent(content) {
+  const trimmed = content.trim();
+  if (!trimmed)
+    return null;
+  const lines = trimmed.split(`
+`);
+  let title;
+  let description;
+  let language;
+  let codeStartIndex = 0;
+  const firstLine = lines[0]?.trim() ?? "";
+  const looksLikeCode = /^(import|const|let|var|function|class|export|async|await|if|for|while|return|\/\/|\/\*|\{|\[)/.test(firstLine);
+  if (firstLine && !firstLine.startsWith("```") && !looksLikeCode) {
+    title = firstLine;
+    codeStartIndex = 1;
+  }
+  const codeBlockStart = lines.findIndex((l, i) => i >= codeStartIndex && l.trim().startsWith("```"));
+  if (codeBlockStart !== -1) {
+    const fenceMatch = lines[codeBlockStart].match(/```(\w+)?/);
+    language = fenceMatch?.[1];
+    if (codeBlockStart > codeStartIndex) {
+      const descLines = lines.slice(codeStartIndex, codeBlockStart).filter((l) => l.trim());
+      if (descLines.length > 0) {
+        description = descLines.join(`
+`).trim();
+      }
+    }
+    const codeBlockEnd = lines.findIndex((l, i) => i > codeBlockStart && l.trim() === "```");
+    const codeLines = codeBlockEnd === -1 ? lines.slice(codeBlockStart + 1) : lines.slice(codeBlockStart + 1, codeBlockEnd);
+    const code2 = codeLines.join(`
+`);
+    return { code: code2, title, description, language };
+  }
+  const code = lines.slice(codeStartIndex).join(`
+`).trim();
+  return { code, title, language: "ts" };
+}
 function findMatchingBrace(text, startIndex) {
   if (text[startIndex] !== "{")
     return -1;
@@ -3246,22 +3285,30 @@ function processTagContent(result, tag, content) {
       if (example) {
         result.examples.push(example);
       }
-      const langMatch = trimmedContent.match(/^```(\w+)/);
+      const structuredExample = parseExampleContent(trimmedContent);
+      if (structuredExample) {
+        result.structuredExamples.push(structuredExample);
+      }
       result.tags.push({
         name: "example",
         text: example,
-        language: langMatch?.[1]
+        language: structuredExample?.language
       });
       break;
     }
     case "see": {
       const linkTargets = extractAllLinkTargets(trimmedContent);
       for (const target of linkTargets) {
+        result.seeAlso.push(target);
         result.tags.push({ name: "link", text: target, reference: target });
         result.tags.push({ name: "see", text: target, reference: target });
       }
       if (linkTargets.length === 0) {
-        result.tags.push({ name: "see", text: trimmedContent, reference: trimmedContent });
+        const plainRef = trimmedContent.trim().split(/\s+/)[0];
+        if (plainRef) {
+          result.seeAlso.push(plainRef);
+        }
+        result.tags.push({ name: "see", text: trimmedContent, reference: plainRef || trimmedContent });
       }
       break;
     }
@@ -3389,6 +3436,8 @@ function parseJSDocText(commentText) {
       type: p.type
     })),
     examples: parsed.examples.length > 0 ? parsed.examples : undefined,
+    structuredExamples: parsed.structuredExamples.length > 0 ? parsed.structuredExamples : undefined,
+    seeAlso: parsed.seeAlso.length > 0 ? parsed.seeAlso : undefined,
     tags: parsed.tags.length > 0 ? parsed.tags : undefined,
     rawParamNames: parsed.rawParamNames
   };
@@ -3528,6 +3577,23 @@ function extractPresentationMetadata(doc) {
 }
 
 // src/analysis/serializers/classes.ts
+function extractClassRelations(heritage, parsedDoc) {
+  const relations = [];
+  if (heritage.extends) {
+    relations.push({ type: "extends", target: heritage.extends });
+  }
+  if (heritage.implements) {
+    for (const impl of heritage.implements) {
+      relations.push({ type: "implements", target: impl });
+    }
+  }
+  if (parsedDoc?.seeAlso) {
+    for (const ref of parsedDoc.seeAlso) {
+      relations.push({ type: "see-also", target: ref });
+    }
+  }
+  return relations;
+}
 function serializeClass(declaration, symbol, context) {
   const { checker, typeRegistry } = context;
   const typeRefs = typeRegistry.getTypeRefs();
@@ -3539,6 +3605,7 @@ function serializeClass(declaration, symbol, context) {
   const description = parsedDoc?.description ?? getJSDocComment(symbol, context.checker);
   const metadata = extractPresentationMetadata(parsedDoc);
   const decorators = extractDecorators(declaration);
+  const relations = extractClassRelations(heritage, parsedDoc);
   const exportEntry = {
     id: symbol.getName(),
     name: symbol.getName(),
@@ -3553,7 +3620,8 @@ function serializeClass(declaration, symbol, context) {
     ...heritage.implements && heritage.implements.length > 0 ? { implements: heritage.implements } : {},
     tags: parsedDoc?.tags,
     examples: parsedDoc?.examples,
-    decorators
+    decorators,
+    related: relations.length > 0 ? relations : undefined
   };
   const typeDefinition = {
     id: symbol.getName(),
@@ -3565,7 +3633,8 @@ function serializeClass(declaration, symbol, context) {
     members: members.length > 0 ? members : undefined,
     ...heritage.extends ? { extends: heritage.extends } : {},
     ...heritage.implements && heritage.implements.length > 0 ? { implements: heritage.implements } : {},
-    tags: parsedDoc?.tags
+    tags: parsedDoc?.tags,
+    related: relations.length > 0 ? relations : undefined
   };
   return {
     exportEntry,
@@ -3888,6 +3957,22 @@ function serializeCallSignatures(signatures, symbol, context, parsedDoc) {
     };
   });
 }
+function extractFunctionRelations(declaration, checker, parsedDoc) {
+  const relations = [];
+  if (declaration.type && ts2.isTypeReferenceNode(declaration.type)) {
+    const typeName = declaration.type.typeName.getText();
+    const builtIns = ["Promise", "Array", "Map", "Set", "Record", "Partial", "Required", "Pick", "Omit"];
+    if (!builtIns.includes(typeName)) {
+      relations.push({ type: "returns", target: typeName });
+    }
+  }
+  if (parsedDoc?.seeAlso) {
+    for (const ref of parsedDoc.seeAlso) {
+      relations.push({ type: "see-also", target: ref });
+    }
+  }
+  return relations;
+}
 function serializeFunctionExport(declaration, symbol, context) {
   const { checker } = context;
   const funcSymbol = checker.getSymbolAtLocation(declaration.name || declaration);
@@ -3896,6 +3981,7 @@ function serializeFunctionExport(declaration, symbol, context) {
   const metadata = extractPresentationMetadata(parsedDoc);
   const type = checker.getTypeAtLocation(declaration.name || declaration);
   const callSignatures = type.getCallSignatures();
+  const relations = extractFunctionRelations(declaration, checker, parsedDoc);
   return {
     id: symbol.getName(),
     name: symbol.getName(),
@@ -3906,7 +3992,8 @@ function serializeFunctionExport(declaration, symbol, context) {
     description,
     source: getSourceLocation(declaration),
     examples: parsedDoc?.examples,
-    tags: parsedDoc?.tags
+    tags: parsedDoc?.tags,
+    related: relations.length > 0 ? relations : undefined
   };
 }
 
@@ -3994,6 +4081,25 @@ function serializeInterfaceMembers(declaration, checker, typeRefs, referencedTyp
   }
   return members;
 }
+function extractInterfaceRelations(declaration, parsedDoc) {
+  const relations = [];
+  if (declaration.heritageClauses) {
+    for (const clause of declaration.heritageClauses) {
+      if (clause.token === ts2.SyntaxKind.ExtendsKeyword) {
+        for (const type of clause.types) {
+          const typeName = type.expression.getText();
+          relations.push({ type: "extends", target: typeName });
+        }
+      }
+    }
+  }
+  if (parsedDoc?.seeAlso) {
+    for (const ref of parsedDoc.seeAlso) {
+      relations.push({ type: "see-also", target: ref });
+    }
+  }
+  return relations;
+}
 function serializeInterface(declaration, symbol, context) {
   const { checker, typeRegistry } = context;
   const parsedDoc = parseJSDocComment(symbol, checker);
@@ -4003,6 +4109,7 @@ function serializeInterface(declaration, symbol, context) {
   const typeRefs = typeRegistry.getTypeRefs();
   const typeParameters = serializeTypeParameterDeclarations(declaration.typeParameters, checker, referencedTypes);
   const members = serializeInterfaceMembers(declaration, checker, typeRefs, referencedTypes);
+  const relations = extractInterfaceRelations(declaration, parsedDoc);
   const exportEntry = {
     id: symbol.getName(),
     name: symbol.getName(),
@@ -4014,7 +4121,8 @@ function serializeInterface(declaration, symbol, context) {
     members,
     typeParameters,
     tags: parsedDoc?.tags,
-    examples: parsedDoc?.examples
+    examples: parsedDoc?.examples,
+    related: relations.length > 0 ? relations : undefined
   };
   const schema = interfaceToSchema(declaration, checker, typeRefs, referencedTypes);
   const typeDefinition = {
@@ -4026,7 +4134,8 @@ function serializeInterface(declaration, symbol, context) {
     members,
     description,
     source: getSourceLocation(declaration),
-    tags: parsedDoc?.tags
+    tags: parsedDoc?.tags,
+    related: relations.length > 0 ? relations : undefined
   };
   return {
     exportEntry,
@@ -5206,7 +5315,9 @@ function generateAssertionFix(drift, exportEntry) {
   const oldValue = oldValueMatch?.[1];
   if (!oldValue)
     return null;
-  const updatedExample = oldExample.replace(new RegExp(`//\\s*=>\\s*${escapeRegex(oldValue)}`, "g"), `// => ${newValue}`);
+  const oldExampleCode = typeof oldExample === "string" ? oldExample : oldExample.code;
+  const updatedCode = oldExampleCode.replace(new RegExp(`//\\s*=>\\s*${escapeRegex(oldValue)}`, "g"), `// => ${newValue}`);
+  const updatedExample = typeof oldExample === "string" ? updatedCode : { ...oldExample, code: updatedCode };
   const updatedExamples = [...examples];
   updatedExamples[exampleIndex] = updatedExample;
   return {
@@ -5538,7 +5649,7 @@ function serializeJSDoc(patch, indent = "") {
     }
     lines.push(tagLine);
   }
-  if (patch.deprecated && patch.deprecated !== false) {
+  if (patch.deprecated && typeof patch.deprecated === "string") {
     lines.push(`@deprecated ${patch.deprecated}`);
   }
   if (patch.examples) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "DocCov SDK - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",
@@ -39,7 +39,7 @@
     "dist"
   ],
   "dependencies": {
-    "@openpkg-ts/spec": "^0.6.0",
+    "@openpkg-ts/spec": "^0.7.0",
     "@vercel/sandbox": "^1.0.3",
     "mdast": "^3.0.0",
     "remark-mdx": "^3.1.0",