@doccov/sdk 0.21.0 → 0.22.1

package/dist/index.d.ts

@@ -125,6 +125,8 @@ interface DetectedSchema {
 interface SchemaDetectionResult {
 	schemas: Map<string, DetectedSchema>;
 	errors: string[];
+	/** Warning when runtime was requested but compiled JS not found */
+	noCompiledJsWarning?: boolean;
 }
 declare function detectRuntimeSchemas(context: SchemaDetectionContext): Promise<SchemaDetectionResult>;
 declare function clearSchemaCache(): void;
@@ -329,9 +331,28 @@ type DriftResult = {
 	exports: Map<string, SpecDocDrift[]>;
 };
 /**
+* Information about an for context-aware suggestions.
+*/
+interface ExportInfo {
+	name: string;
+	kind: string;
+	isCallable: boolean;
+}
+/**
+* Registry of exports and types for cross-reference validation.
+*/
+interface ExportRegistry {
+	/** Map of names to their info (for context-aware suggestions) */
+	exports: Map<string, ExportInfo>;
+	/** Set of type names (interfaces, type aliases, etc.) */
+	types: Set<string>;
+	/** Combined set of all names (for backward compatibility) */
+	all: Set<string>;
+}
+/**
 * Build a registry of all export/type names for cross-reference validation.
 */
-declare function buildExportRegistry(spec: OpenPkgSpec): Set<string>;
+declare function buildExportRegistry(spec: OpenPkgSpec): ExportRegistry;
 /**
 * Compute drift for all exports in a spec.
 *
@@ -342,10 +363,10 @@ declare function computeDrift(spec: OpenPkgSpec): DriftResult;
 * Compute drift for a single export.
 *
 * @param entry - The to analyze
-* @param exportRegistry - Registry of known names for link validation
+* @param registry - Registry of known exports and types for validation
 * @returns Array of drift issues detected
 */
-declare function computeExportDrift(entry: SpecExport, exportRegistry?: Set<string>): SpecDocDrift[];
+declare function computeExportDrift(entry: SpecExport, registry?: ExportRegistry): SpecDocDrift[];
 /**
 * Detect runtime errors in @example blocks.
 * Results are provided externally after running examples via runExamples().

package/dist/index.js

@@ -204,7 +204,8 @@ async function detectRuntimeSchemas(context) {
   if (!compiledPath) {
     return {
       schemas: new Map,
-      errors: []
+      errors: [],
+      noCompiledJsWarning: true
     };
   }
   const extraction = await extractStandardSchemasFromProject(entryFile, baseDir);
@@ -646,7 +647,7 @@ function generateReturnTypeFix(drift, exportEntry, existingPatch) {
   const actualReturn = signature?.returns;
   if (!actualReturn)
     return null;
-  const correctType = actualReturn.tsType ?? stringifySchema(actualReturn.schema);
+  const correctType = stringifySchema(actualReturn.schema);
   const updatedReturn = {
     ...existingPatch?.returns,
     type: correctType
@@ -1394,27 +1395,42 @@ var LIBRARY_INTERNAL_PATTERNS = [
 
 // src/analysis/docs-coverage.ts
 function buildExportRegistry(spec) {
-  const registry = new Set;
+  const exports = new Map;
+  const types = new Set;
+  const all = new Set;
   for (const entry of spec.exports ?? []) {
-    registry.add(entry.name);
-    registry.add(entry.id);
+    const info = {
+      name: entry.name,
+      kind: entry.kind ?? "unknown",
+      isCallable: ["function", "class"].includes(entry.kind ?? "")
+    };
+    exports.set(entry.name, info);
+    if (entry.id)
+      exports.set(entry.id, info);
+    all.add(entry.name);
+    if (entry.id)
+      all.add(entry.id);
   }
   for (const type of spec.types ?? []) {
-    registry.add(type.name);
-    registry.add(type.id);
+    types.add(type.name);
+    if (type.id)
+      types.add(type.id);
+    all.add(type.name);
+    if (type.id)
+      all.add(type.id);
   }
-  return registry;
+  return { exports, types, all };
 }
 function computeDrift(spec) {
-  const exportRegistry = buildExportRegistry(spec);
+  const registry = buildExportRegistry(spec);
   const exports = new Map;
   for (const entry of spec.exports ?? []) {
-    const drift = computeExportDrift(entry, exportRegistry);
+    const drift = computeExportDrift(entry, registry);
     exports.set(entry.id ?? entry.name, drift);
   }
   return { exports };
 }
-function computeExportDrift(entry, exportRegistry) {
+function computeExportDrift(entry, registry) {
   return [
     ...detectParamDrift(entry),
     ...detectOptionalityDrift(entry),
@@ -1423,8 +1439,8 @@ function computeExportDrift(entry, exportRegistry) {
     ...detectGenericConstraintDrift(entry),
     ...detectDeprecatedDrift(entry),
     ...detectVisibilityDrift(entry),
-    ...detectExampleDrift(entry, exportRegistry),
-    ...detectBrokenLinks(entry, exportRegistry),
+    ...detectExampleDrift(entry, registry),
+    ...detectBrokenLinks(entry, registry),
     ...detectExampleSyntaxErrors(entry),
     ...detectAsyncMismatch(entry),
     ...detectPropertyTypeDrift(entry)
@@ -1471,24 +1487,39 @@ function detectParamDrift(entry) {
           if (properties.has(firstProperty)) {
             continue;
           }
-          const suggestion2 = findClosestMatch(firstProperty, Array.from(properties));
+          const propsArray = Array.from(properties);
+          const suggestion2 = findClosestMatch(firstProperty, propsArray);
+          let suggestionText2;
+          if (suggestion2) {
+            suggestionText2 = `Did you mean "${prefix}.${suggestion2.value}"?`;
+          } else if (propsArray.length > 0 && propsArray.length <= 8) {
+            const propsList = propsArray.slice(0, 5).map((p) => `${prefix}.${p}`);
+            suggestionText2 = propsArray.length > 5 ? `Available: ${propsList.join(", ")}... (${propsArray.length} total)` : `Available: ${propsList.join(", ")}`;
+          }
           drifts.push({
             type: "param-mismatch",
             target: documentedName,
             issue: `JSDoc documents property "${propertyPath}" on parameter "${prefix}" which does not exist.`,
-            suggestion: suggestion2?.distance !== undefined && suggestion2.distance <= 3 ? `${prefix}.${suggestion2.value}` : undefined
+            suggestion: suggestionText2
           });
           continue;
         }
         continue;
       }
     }
-    const suggestion = findClosestMatch(documentedName, Array.from(actualParamNames));
+    const paramsArray = Array.from(actualParamNames);
+    const suggestion = findClosestMatch(documentedName, paramsArray);
+    let suggestionText;
+    if (suggestion) {
+      suggestionText = `Did you mean "${suggestion.value}"?`;
+    } else if (paramsArray.length > 0 && paramsArray.length <= 6) {
+      suggestionText = `Available parameters: ${paramsArray.join(", ")}`;
+    }
     drifts.push({
       type: "param-mismatch",
       target: documentedName,
       issue: `JSDoc documents parameter "${documentedName}" which is not present in the signature.`,
-      suggestion: suggestion?.distance !== undefined && suggestion.distance <= 3 ? suggestion.value : undefined
+      suggestion: suggestionText
     });
   }
   return drifts;
@@ -1596,7 +1627,7 @@ function detectReturnTypeDrift(entry) {
   if (!signatureReturn) {
     return [];
   }
-  const declaredRaw = signatureReturn.tsType ?? extractTypeFromSchema(signatureReturn.schema);
+  const declaredRaw = extractTypeFromSchema(signatureReturn.schema);
   const declaredType = normalizeType(declaredRaw) ?? undefined;
   if (!declaredType) {
     return [];
@@ -1959,26 +1990,53 @@ function buildGenericConstraintSuggestion(templateName, actualConstraint) {
   }
   return `Remove the constraint from @template ${templateName} to match the declaration.`;
 }
+function splitCamelCase(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(/[\s_-]+/).filter(Boolean);
+}
 function findClosestMatch(source, candidates) {
   if (candidates.length === 0) {
     return;
   }
-  const normalizedSource = source.toLowerCase();
-  const substringCandidate = candidates.find((candidate) => {
-    const normalizedCandidate = candidate.toLowerCase();
-    return normalizedCandidate.includes(normalizedSource) || normalizedSource.includes(normalizedCandidate);
-  });
-  if (substringCandidate && substringCandidate !== source) {
-    return { value: substringCandidate, distance: 0 };
-  }
-  let best;
+  const sourceWords = splitCamelCase(source);
+  let bestMatch;
+  let bestScore = 0;
   for (const candidate of candidates) {
-    const distance = levenshtein(source, candidate);
-    if (!best || distance < best.distance) {
-      best = { value: candidate, distance };
+    if (candidate === source)
+      continue;
+    const candidateWords = splitCamelCase(candidate);
+    let matchingWords = 0;
+    let suffixMatch = false;
+    if (sourceWords.length > 0 && candidateWords.length > 0) {
+      const sourceSuffix = sourceWords[sourceWords.length - 1];
+      const candidateSuffix = candidateWords[candidateWords.length - 1];
+      if (sourceSuffix === candidateSuffix) {
+        suffixMatch = true;
+        matchingWords += 1.5;
+      }
+    }
+    const suffixWord = suffixMatch ? sourceWords[sourceWords.length - 1] : null;
+    for (const word of sourceWords) {
+      if (word !== suffixWord && candidateWords.includes(word)) {
+        matchingWords++;
+      }
+    }
+    if (matchingWords < 2)
+      continue;
+    const wordScore = matchingWords / Math.max(sourceWords.length, candidateWords.length);
+    const editDistance = levenshtein(source.toLowerCase(), candidate.toLowerCase());
+    const maxLen = Math.max(source.length, candidate.length);
+    const levScore = 1 - editDistance / maxLen;
+    const totalScore = suffixMatch ? wordScore * 1.5 + levScore : wordScore + levScore * 0.5;
+    if (totalScore > bestScore && totalScore >= 0.5) {
+      bestScore = totalScore;
+      bestMatch = candidate;
     }
   }
-  return best;
+  if (!bestMatch) {
+    return;
+  }
+  const distance = Math.round((1 - bestScore) * 10);
+  return { value: bestMatch, distance };
 }
 function levenshtein(a, b) {
   if (a === b) {
@@ -2008,8 +2066,22 @@ function levenshtein(a, b) {
   }
   return matrix[b.length][a.length];
 }
-function detectExampleDrift(entry, exportRegistry) {
-  if (!exportRegistry || !entry.examples?.length)
+function getIdentifierContext(node) {
+  const parent = node.parent;
+  if (!parent)
+    return "value";
+  if (ts2.isCallExpression(parent) && parent.expression === node)
+    return "call";
+  if (ts2.isNewExpression(parent) && parent.expression === node)
+    return "call";
+  if (ts2.isTypeReferenceNode(parent))
+    return "type";
+  if (ts2.isExpressionWithTypeArguments(parent))
+    return "type";
+  return "value";
+}
+function detectExampleDrift(entry, registry) {
+  if (!registry || !entry.examples?.length)
     return [];
   const drifts = [];
   for (const example of entry.examples) {
@@ -2023,7 +2095,11 @@ function detectExampleDrift(entry, exportRegistry) {
         if (isLocalDeclaration(node)) {
           localDeclarations.add(text);
         } else if (isIdentifierReference(node) && !isBuiltInIdentifier(text)) {
-          referencedIdentifiers.add(text);
+          const context = getIdentifierContext(node);
+          const existing = referencedIdentifiers.get(text);
+          if (!existing || context === "call") {
+            referencedIdentifiers.set(text, context);
+          }
         }
       }
       ts2.forEachChild(node, visit);
@@ -2035,16 +2111,27 @@ function detectExampleDrift(entry, exportRegistry) {
       continue;
     const sourceFile = ts2.createSourceFile("example.ts", codeContent, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TS);
     const localDeclarations = new Set;
-    const referencedIdentifiers = new Set;
+    const referencedIdentifiers = new Map;
     visit(sourceFile);
     for (const local of localDeclarations) {
       referencedIdentifiers.delete(local);
     }
-    for (const identifier of referencedIdentifiers) {
-      if (!exportRegistry.has(identifier)) {
-        const suggestion = findClosestMatch(identifier, Array.from(exportRegistry));
+    for (const [identifier, context] of referencedIdentifiers) {
+      if (!registry.all.has(identifier)) {
+        let candidates;
+        if (context === "call") {
+          candidates = Array.from(registry.exports.values()).filter((e) => e.isCallable).map((e) => e.name);
+        } else if (context === "type") {
+          candidates = [
+            ...Array.from(registry.types),
+            ...Array.from(registry.exports.values()).filter((e) => ["class", "interface", "type", "enum"].includes(e.kind)).map((e) => e.name)
+          ];
+        } else {
+          candidates = Array.from(registry.exports.keys());
+        }
+        const suggestion = findClosestMatch(identifier, candidates);
         const isPascal = /^[A-Z]/.test(identifier);
-        const hasCloseMatch = suggestion && suggestion.distance <= 3;
+        const hasCloseMatch = suggestion && suggestion.distance <= 5;
         if (hasCloseMatch || isPascal) {
           drifts.push({
             type: "example-drift",
@@ -2086,8 +2173,8 @@ function isIdentifierReference(node) {
     return false;
   return true;
 }
-function detectBrokenLinks(entry, exportRegistry) {
-  if (!exportRegistry) {
+function detectBrokenLinks(entry, registry) {
+  if (!registry) {
     return [];
   }
   const drifts = [];
@@ -2114,13 +2201,13 @@ function detectBrokenLinks(entry, exportRegistry) {
       if (target.includes("/") || target.includes("@")) {
         continue;
       }
-      if (!exportRegistry.has(rootName) && !exportRegistry.has(target)) {
-        const suggestion = findClosestMatch(rootName, Array.from(exportRegistry));
+      if (!registry.all.has(rootName) && !registry.all.has(target)) {
+        const suggestion = findClosestMatch(rootName, Array.from(registry.all));
         drifts.push({
           type: "broken-link",
           target,
           issue: `{${type} ${target}} references a symbol that does not exist.`,
-          suggestion: suggestion && suggestion.distance <= 3 ? `Did you mean "${suggestion.value}"?` : undefined
+          suggestion: suggestion ? `Did you mean "${suggestion.value}"?` : undefined
         });
       }
     }
@@ -2198,7 +2285,7 @@ function detectAsyncMismatch(entry) {
   }
   const drifts = [];
   const returnsPromise = signatures.some((sig) => {
-    const returnType = sig.returns?.tsType ?? extractTypeFromSchema(sig.returns?.schema) ?? "";
+    const returnType = extractTypeFromSchema(sig.returns?.schema) ?? "";
     return returnType.startsWith("Promise<") || returnType === "Promise";
   });
   const returnsTag = entry.tags?.find((tag) => tag.name === "returns" || tag.name === "return");
@@ -5161,11 +5248,11 @@ function formatTypeReference(type, typeChecker, typeRefs, referencedTypes, visit
     if (type.getFlags() & ts.TypeFlags.Object) {
       const objectType = type;
       if (objectType.objectFlags & ts.ObjectFlags.Mapped) {
-        return { type: "object", tsType: typeString };
+        return { type: "object" };
       }
     }
     if (type.flags & ts.TypeFlags.Conditional) {
-      return { type: "object", tsType: typeString };
+      return { type: "object" };
     }
     if (type.isUnion()) {
       const unionType = type;
@@ -6419,7 +6506,6 @@ function serializeCallSignatures(signatures, symbol, context, parsedDoc) {
       };
     });
     const returnType = signature.getReturnType();
-    const returnTypeText = returnType ? checker.typeToString(returnType) : undefined;
     if (returnType) {
       collectReferencedTypes(returnType, checker, referencedTypes);
     }
@@ -6445,7 +6531,6 @@ function serializeCallSignatures(signatures, symbol, context, parsedDoc) {
       returns: {
         schema: returnType ? formatTypeReference(returnType, checker, typeRefs, referencedTypes) : { type: "void" },
         description: functionDoc?.returns || "",
-        tsType: returnTypeText,
         ...typePredicateInfo ? { typePredicate: typePredicateInfo } : {}
       },
       description: functionDoc?.description || undefined,
@@ -8490,13 +8575,6 @@ function extractTypeName(schema) {
   if (typeof s.type === "string") {
     return s.type;
   }
-  if (typeof s.tsType === "string") {
-    const tsType = s.tsType;
-    if (tsType.length > 30) {
-      return `${tsType.slice(0, 27)}...`;
-    }
-    return tsType;
-  }
   return;
 }
 function hasSignatureChanged(oldMember, newMember) {
@@ -8540,8 +8618,8 @@ function findSimilarMember(removedName, newMembers, addedMembers) {
   for (const name of candidates) {
     if (name === removedName)
       continue;
-    const removedWords = splitCamelCase(removedName);
-    const newWords = splitCamelCase(name);
+    const removedWords = splitCamelCase2(removedName);
+    const newWords = splitCamelCase2(name);
     let matchingWords = 0;
     let suffixMatch = false;
     if (removedWords.length > 0 && newWords.length > 0) {
@@ -8588,7 +8666,7 @@ function levenshteinDistance(a, b) {
   }
   return matrix[b.length][a.length];
 }
-function splitCamelCase(str) {
+function splitCamelCase2(str) {
   return str.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().split(" ");
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/sdk",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "DocCov SDK - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",
@@ -39,7 +39,7 @@
     "dist"
   ],
   "dependencies": {
-    "@openpkg-ts/spec": "^0.10.0",
+    "@openpkg-ts/spec": "^0.11.0",
     "@vercel/sandbox": "^1.0.3",
     "mdast": "^3.0.0",
     "minimatch": "^10.1.1",