@doccov/sdk 0.7.0 → 0.8.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,6 +3032,7 @@ function parseJSDocBlock(commentText) {
   const result = {
     description: "",
     params: [],
+    throws: [],
     examples: [],
     tags: [],
     rawParamNames: []
@@ -3104,6 +3138,22 @@ 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 findMatchingBrace(text, startIndex) {
   if (text[startIndex] !== "{")
     return -1;
@@ -3179,6 +3229,18 @@ 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) {
@@ -3334,6 +3396,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) {
@@ -3473,6 +3538,7 @@ 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 exportEntry = {
     id: symbol.getName(),
     name: symbol.getName(),
@@ -3486,7 +3552,8 @@ 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
   };
   const typeDefinition = {
     id: symbol.getName(),
@@ -3579,7 +3646,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 +3669,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 +3690,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 +3724,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 +3733,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 +3750,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 +3869,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,7 +3883,8 @@ 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
     };
   });
 }
@@ -4095,6 +4176,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 +4188,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 +4282,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 +4330,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 +4342,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 +4364,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/sdk",
-  "version": "0.7.0",
+  "version": "0.8.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.6.0",
     "@vercel/sandbox": "^1.0.3",
     "mdast": "^3.0.0",
     "remark-mdx": "^3.1.0",