@doccov/sdk 0.7.0 → 0.9.0

package/dist/index.js

@@ -2063,6 +2063,35 @@ import * as fs2 from "node:fs";
 import * as path3 from "node:path";
 import { SCHEMA_URL, SCHEMA_VERSION } from "@openpkg-ts/spec";
 
+// src/analysis/decorator-utils.ts
+function extractDecorators(node) {
+  if (!ts2.canHaveDecorators(node)) {
+    return;
+  }
+  const decorators = ts2.getDecorators(node);
+  if (!decorators || decorators.length === 0) {
+    return;
+  }
+  return decorators.map((decorator) => {
+    const expression = decorator.expression;
+    if (ts2.isIdentifier(expression)) {
+      return { name: expression.text };
+    }
+    if (ts2.isCallExpression(expression)) {
+      const name = ts2.isIdentifier(expression.expression) ? expression.expression.text : expression.expression.getText();
+      const argumentsText = expression.arguments.map((arg) => arg.getText());
+      return { name, argumentsText };
+    }
+    if (ts2.isPropertyAccessExpression(expression)) {
+      return { name: expression.getText() };
+    }
+    return { name: expression.getText() };
+  });
+}
+function extractParameterDecorators(param) {
+  return extractDecorators(param);
+}
+
 // src/utils/parameter-utils.ts
 var BUILTIN_TYPE_SCHEMAS = {
   Date: { type: "string", format: "date-time" },
@@ -2991,6 +3020,10 @@ function structureParameter(param, paramDecl, paramType, typeChecker, typeRefs,
   if (paramDecl.dotDotDotToken) {
     out.rest = true;
   }
+  const decorators = extractParameterDecorators(paramDecl);
+  if (decorators) {
+    out.decorators = decorators;
+  }
   return out;
 }
 
@@ -2999,7 +3032,10 @@ function parseJSDocBlock(commentText) {
   const result = {
     description: "",
     params: [],
+    throws: [],
     examples: [],
+    structuredExamples: [],
+    seeAlso: [],
     tags: [],
     rawParamNames: []
   };
@@ -3104,6 +3140,59 @@ function parseReturnContent(content) {
     description: processInlineLinks(remaining)
   };
 }
+function parseThrowsContent(content) {
+  const trimmed = content.trim();
+  let remaining = trimmed;
+  let type;
+  if (remaining.startsWith("{")) {
+    const typeEnd = findMatchingBrace(remaining, 0);
+    if (typeEnd > 0) {
+      type = remaining.slice(1, typeEnd).trim();
+      remaining = remaining.slice(typeEnd + 1).trim();
+    }
+  }
+  return {
+    type,
+    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;
@@ -3179,27 +3268,47 @@ function processTagContent(result, tag, content) {
       });
       break;
     }
+    case "throws":
+    case "throw":
+    case "exception": {
+      const parsed = parseThrowsContent(trimmedContent);
+      result.throws.push(parsed);
+      result.tags.push({
+        name: "throws",
+        text: trimmedContent,
+        typeAnnotation: parsed.type
+      });
+      break;
+    }
     case "example": {
       const example = processInlineLinks(trimmedContent);
       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;
     }
@@ -3327,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
   };
@@ -3334,6 +3445,9 @@ function parseJSDocText(commentText) {
     result.returns = parsed.returns.description;
     result.returnsType = parsed.returns.type;
   }
+  if (parsed.throws.length > 0) {
+    result.throws = parsed.throws;
+  }
   return result;
 }
 function extractDestructuredParams(parsedDoc, paramName) {
@@ -3463,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();
@@ -3473,6 +3604,8 @@ function serializeClass(declaration, symbol, context) {
   const parsedDoc = parseJSDocComment(symbol, context.checker);
   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(),
@@ -3486,7 +3619,9 @@ function serializeClass(declaration, symbol, context) {
     ...heritage.extends ? { extends: heritage.extends } : {},
     ...heritage.implements && heritage.implements.length > 0 ? { implements: heritage.implements } : {},
     tags: parsedDoc?.tags,
-    examples: parsedDoc?.examples
+    examples: parsedDoc?.examples,
+    decorators,
+    related: relations.length > 0 ? relations : undefined
   };
   const typeDefinition = {
     id: symbol.getName(),
@@ -3498,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,
@@ -3579,7 +3715,8 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
         schema,
         description: memberDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined),
         flags: Object.keys(flags).length > 0 ? flags : undefined,
-        tags: memberDoc?.tags
+        tags: memberDoc?.tags,
+        decorators: extractDecorators(member)
       });
       continue;
     }
@@ -3601,7 +3738,8 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
         signatures,
         description: methodDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined),
         flags: getMethodFlags(member),
-        tags: methodDoc?.tags
+        tags: methodDoc?.tags,
+        decorators: extractDecorators(member)
       });
       continue;
     }
@@ -3621,7 +3759,8 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
         visibility: getMemberVisibility(member.modifiers),
         signatures,
         description: ctorDoc?.description ?? (ctorSymbol ? getJSDocComment(ctorSymbol, checker) : undefined),
-        tags: ctorDoc?.tags
+        tags: ctorDoc?.tags,
+        decorators: extractDecorators(member)
       });
       continue;
     }
@@ -3654,7 +3793,8 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
         schema,
         description: memberDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined),
         flags: Object.keys(flags).length > 0 ? flags : undefined,
-        tags: memberDoc?.tags
+        tags: memberDoc?.tags,
+        decorators: extractDecorators(primaryMember)
       });
     }
   }
@@ -3662,6 +3802,10 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
 }
 function serializeSignature(signature, checker, typeRefs, referencedTypes, doc, symbol) {
   const typeParameters = serializeTypeParameterDeclarations(signature.declaration?.typeParameters, checker, referencedTypes);
+  const throws = doc?.throws?.map((t) => ({
+    type: t.type,
+    description: t.description
+  }));
   return {
     parameters: signature.getParameters().map((param) => {
       const paramDecl = param.valueDeclaration;
@@ -3675,7 +3819,8 @@ function serializeSignature(signature, checker, typeRefs, referencedTypes, doc,
       description: doc?.returns || ""
     },
     description: doc?.description || (symbol ? getJSDocComment(symbol, checker) : undefined),
-    typeParameters
+    typeParameters,
+    throws: throws && throws.length > 0 ? throws : undefined
   };
 }
 function getMemberVisibility(modifiers) {
@@ -3793,6 +3938,10 @@ function serializeCallSignatures(signatures, symbol, context, parsedDoc) {
         ...isAsserts ? { asserts: true } : {}
       };
     }
+    const throws = functionDoc?.throws?.map((t) => ({
+      type: t.type,
+      description: t.description
+    }));
     return {
       parameters,
       returns: {
@@ -3803,10 +3952,27 @@ function serializeCallSignatures(signatures, symbol, context, parsedDoc) {
       },
       description: functionDoc?.description || undefined,
       typeParameters,
-      overloadIndex: signatures.length > 1 ? index : undefined
+      overloadIndex: signatures.length > 1 ? index : undefined,
+      throws: throws && throws.length > 0 ? throws : undefined
     };
   });
 }
+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);
@@ -3815,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(),
@@ -3825,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
   };
 }
 
@@ -3913,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);
@@ -3922,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(),
@@ -3933,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 = {
@@ -3945,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,
@@ -4095,6 +4285,8 @@ function serializeNamespace(declaration, symbol, context) {
   const description = parsedDoc?.description ?? getJSDocComment(symbol, checker);
   const metadata = extractPresentationMetadata(parsedDoc);
   const members = extractNamespaceMembers(declaration, checker);
+  const isAugmentation = ts2.isStringLiteral(declaration.name);
+  const augmentedModule = isAugmentation ? declaration.name.text : undefined;
   return {
     id: symbol.getName(),
     name: symbol.getName(),
@@ -4105,7 +4297,9 @@ function serializeNamespace(declaration, symbol, context) {
     source: getSourceLocation(declaration),
     members: members.length > 0 ? members : undefined,
     tags: parsedDoc?.tags,
-    examples: parsedDoc?.examples
+    examples: parsedDoc?.examples,
+    isAugmentation: isAugmentation || undefined,
+    augmentedModule
   };
 }
 function extractNamespaceMembers(declaration, checker) {
@@ -4197,6 +4391,46 @@ function extractNamespaceMembers(declaration, checker) {
 }
 
 // src/analysis/serializers/type-aliases.ts
+function analyzeTypeAliasKind(typeNode) {
+  if (ts2.isConditionalTypeNode(typeNode)) {
+    return {
+      typeAliasKind: "conditional",
+      conditionalType: {
+        checkType: typeNode.checkType.getText(),
+        extendsType: typeNode.extendsType.getText(),
+        trueType: typeNode.trueType.getText(),
+        falseType: typeNode.falseType.getText()
+      }
+    };
+  }
+  if (ts2.isMappedTypeNode(typeNode)) {
+    const readonlyToken = typeNode.readonlyToken;
+    const questionToken = typeNode.questionToken;
+    return {
+      typeAliasKind: "mapped",
+      mappedType: {
+        typeParameter: typeNode.typeParameter.getText(),
+        nameType: typeNode.nameType?.getText(),
+        valueType: typeNode.type?.getText(),
+        readonly: readonlyToken ? readonlyToken.kind === ts2.SyntaxKind.MinusToken ? "-" : readonlyToken.kind === ts2.SyntaxKind.PlusToken ? "+" : true : undefined,
+        optional: questionToken ? questionToken.kind === ts2.SyntaxKind.MinusToken ? "-" : questionToken.kind === ts2.SyntaxKind.PlusToken ? "+" : true : undefined
+      }
+    };
+  }
+  if (ts2.isTemplateLiteralTypeNode(typeNode)) {
+    return { typeAliasKind: "template-literal" };
+  }
+  if (containsInferType(typeNode)) {
+    return { typeAliasKind: "infer" };
+  }
+  return { typeAliasKind: "alias" };
+}
+function containsInferType(node) {
+  if (ts2.isInferTypeNode(node)) {
+    return true;
+  }
+  return ts2.forEachChild(node, containsInferType) ?? false;
+}
 function serializeTypeAlias(declaration, symbol, context) {
   const { checker, typeRegistry } = context;
   const typeRefs = typeRegistry.getTypeRefs();
@@ -4205,6 +4439,7 @@ function serializeTypeAlias(declaration, symbol, context) {
   const description = parsedDoc?.description ?? getJSDocComment(symbol, checker);
   const metadata = extractPresentationMetadata(parsedDoc);
   const typeParameters = serializeTypeParameterDeclarations(declaration.typeParameters, checker, referencedTypes);
+  const typeAnalysis = analyzeTypeAliasKind(declaration.type);
   const exportEntry = {
     id: symbol.getName(),
     name: symbol.getName(),
@@ -4216,7 +4451,10 @@ function serializeTypeAlias(declaration, symbol, context) {
     source: getSourceLocation(declaration),
     typeParameters,
     tags: parsedDoc?.tags,
-    examples: parsedDoc?.examples
+    examples: parsedDoc?.examples,
+    typeAliasKind: typeAnalysis.typeAliasKind !== "alias" ? typeAnalysis.typeAliasKind : undefined,
+    conditionalType: typeAnalysis.conditionalType,
+    mappedType: typeAnalysis.mappedType
   };
   const aliasType = checker.getTypeAtLocation(declaration.type);
   const aliasName = symbol.getName();
@@ -4235,7 +4473,10 @@ function serializeTypeAlias(declaration, symbol, context) {
     kind: "type",
     description,
     source: getSourceLocation(declaration),
-    tags: parsedDoc?.tags
+    tags: parsedDoc?.tags,
+    typeAliasKind: typeAnalysis.typeAliasKind !== "alias" ? typeAnalysis.typeAliasKind : undefined,
+    conditionalType: typeAnalysis.conditionalType,
+    mappedType: typeAnalysis.mappedType
   };
   if (typeof aliasSchema === "string") {
     typeDefinition.type = aliasSchema;
@@ -5074,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 {
@@ -5406,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.7.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.5.0",
+    "@openpkg-ts/spec": "^0.7.0",
     "@vercel/sandbox": "^1.0.3",
     "mdast": "^3.0.0",
     "remark-mdx": "^3.1.0",