@doccov/sdk 0.5.7 → 0.5.8

package/dist/index.d.ts

@@ -764,4 +764,82 @@ declare function readPackageJson(fs: FileSystem, dir: string): Promise<PackageJs
 * ```
 */
 declare function analyzeProject2(fs: FileSystem, options?: AnalyzeProjectOptions): Promise<ProjectInfo>;
-export { serializeJSDoc, safeParseJson, runExamplesWithPackage, runExamples, runExample, readPackageJson, parseMarkdownFiles, parseMarkdownFile, parseJSDocToPatch, parseAssertions, mergeFixes, isFixableDrift, isExecutableLang, hasNonAssertionComments, hasDocsImpact, hasDocsForExport, getUndocumentedExports, getRunCommand, getPrimaryBuildScript, getInstallCommand, getDocumentedExports, getDocsImpactSummary, generateFixesForExport, generateFix, formatPackageList, findRemovedReferences, findPackageByName, findJSDocLocation, findExportReferences, findDeprecatedReferences, extractPackageSpec, extractImports, extractFunctionCalls, diffSpecWithDocs, detectPackageManager, detectMonorepo, detectExampleRuntimeErrors, detectExampleAssertionFailures, detectEntryPoint, detectBuildInfo, createSourceFile, categorizeDrifts, blockReferencesExport, applyPatchToJSDoc, applyEdits, analyzeProject2 as analyzeProject, analyzeFile, analyzeDocsImpact, analyze, WorkspacePackage, SpecDiffWithDocs, SandboxFileSystem, RunExamplesWithPackageResult, RunExamplesWithPackageOptions, RunExampleOptions, ProjectInfo, PackageManagerInfo, PackageManager, PackageJson, PackageExports, OpenPkgSpec, OpenPkgOptions, OpenPkg4 as OpenPkg, NodeFileSystem, MonorepoType, MonorepoInfo, MemberChange, MarkdownDocFile, MarkdownCodeBlock, JSDocTag, JSDocReturn, JSDocPatch, JSDocParam, JSDocEdit, FixType, FixSuggestion, FilterOptions, FileSystem, ExportReference, ExampleRunResult, EntryPointSource, EntryPointInfo, DocsImpactResult, DocsImpactReference, DocsImpact, DocsChangeType, DocCovOptions, DocCov, DiffWithDocsOptions, Diagnostic, BuildInfo, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOptions, AnalysisResult };
+import { SpecExport as SpecExport4 } from "@openpkg-ts/spec";
+import { SpecExport as SpecExport3 } from "@openpkg-ts/spec";
+type LintSeverity = "error" | "warn" | "off";
+interface LintViolation {
+	rule: string;
+	severity: "error" | "warn";
+	message: string;
+	line?: number;
+	fixable: boolean;
+}
+interface LintRule {
+	name: string;
+	defaultSeverity: LintSeverity;
+	check(exp: SpecExport3, rawJSDoc?: string): LintViolation[];
+	fix?(exp: SpecExport3, rawJSDoc?: string): JSDocPatch | null;
+}
+interface LintConfig {
+	rules: Record<string, LintSeverity>;
+}
+interface LintResult {
+	violations: LintViolation[];
+	errorCount: number;
+	warningCount: number;
+	fixableCount: number;
+}
+/** All available lint rules */
+declare const allRules: LintRule[];
+/** Default configuration with rule defaults */
+declare function getDefaultConfig(): LintConfig;
+/** Get a rule by name */
+declare function getRule(name: string): LintRule | undefined;
+/** Lint a single */
+declare function lintExport(exp: SpecExport4, rawJSDoc?: string, config?: LintConfig): LintViolation[];
+/** Lint multiple exports and aggregate results */
+declare function lintExports(exports: Array<{
+	export: SpecExport4;
+	rawJSDoc?: string;
+}>, config?: LintConfig): LintResult;
+/** Merge user config with defaults */
+declare function mergeConfig(userConfig: Partial<LintConfig>): LintConfig;
+declare const consistentParamStyle: LintRule;
+declare const noEmptyReturns: LintRule;
+declare const requireDescription: LintRule;
+declare const requireExample: LintRule;
+interface ExampleTypeError {
+	/** Index of the example in the examples array */
+	exampleIndex: number;
+	/** Line number within the example (1-based) */
+	line: number;
+	/** Column number (1-based) */
+	column: number;
+	/** Error message from TypeScript */
+	message: string;
+	/** TypeScript diagnostic code */
+	code: number;
+}
+interface TypecheckResult {
+	/** All type errors found across examples */
+	errors: ExampleTypeError[];
+	/** Number of examples that passed */
+	passed: number;
+	/** Number of examples that failed */
+	failed: number;
+}
+interface TypecheckOptions {
+	/** Path to tsconfig.json (auto-detected if not provided) */
+	tsconfig?: string;
+	/** Package name for imports (auto-detected from package.json if not provided) */
+	packageName?: string;
+}
+/**
+* Type-check a single example
+*/
+declare function typecheckExample(example: string, packagePath: string, options?: TypecheckOptions): ExampleTypeError[];
+/**
+* Type-check multiple examples
+*/
+declare function typecheckExamples(examples: string[], packagePath: string, options?: TypecheckOptions): TypecheckResult;
+export { typecheckExamples, typecheckExample, serializeJSDoc, safeParseJson, runExamplesWithPackage, runExamples, runExample, requireExample, requireDescription, readPackageJson, parseMarkdownFiles, parseMarkdownFile, parseJSDocToPatch, parseAssertions, noEmptyReturns, mergeFixes, mergeConfig, lintExports, lintExport, isFixableDrift, isExecutableLang, hasNonAssertionComments, hasDocsImpact, hasDocsForExport, getUndocumentedExports, getRunCommand, getRule, getPrimaryBuildScript, getInstallCommand, getDocumentedExports, getDocsImpactSummary, getDefaultConfig, generateFixesForExport, generateFix, formatPackageList, findRemovedReferences, findPackageByName, findJSDocLocation, findExportReferences, findDeprecatedReferences, extractPackageSpec, extractImports, extractFunctionCalls, diffSpecWithDocs, detectPackageManager, detectMonorepo, detectExampleRuntimeErrors, detectExampleAssertionFailures, detectEntryPoint, detectBuildInfo, createSourceFile, consistentParamStyle, categorizeDrifts, blockReferencesExport, applyPatchToJSDoc, applyEdits, analyzeProject2 as analyzeProject, analyzeFile, analyzeDocsImpact, analyze, allRules, WorkspacePackage, TypecheckResult, TypecheckOptions, SpecDiffWithDocs, SandboxFileSystem, RunExamplesWithPackageResult, RunExamplesWithPackageOptions, RunExampleOptions, ProjectInfo, PackageManagerInfo, PackageManager, PackageJson, PackageExports, OpenPkgSpec, OpenPkgOptions, OpenPkg4 as OpenPkg, NodeFileSystem, MonorepoType, MonorepoInfo, MemberChange, MarkdownDocFile, MarkdownCodeBlock, LintViolation, LintSeverity, LintRule, LintResult, LintConfig, JSDocTag, JSDocReturn, JSDocPatch, JSDocParam, JSDocEdit, FixType, FixSuggestion, FilterOptions, FileSystem, ExportReference, ExampleTypeError, ExampleRunResult, EntryPointSource, EntryPointInfo, DocsImpactResult, DocsImpactReference, DocsImpact, DocsChangeType, DocCovOptions, DocCov, DiffWithDocsOptions, Diagnostic, BuildInfo, ApplyEditsResult, AnalyzeProjectOptions, AnalyzeOptions, AnalysisResult };

package/dist/index.js

@@ -5938,18 +5938,323 @@ async function analyzeProject(fs7, options = {}) {
   ]);
   return { packageManager, monorepo, entryPoint, build };
 }
+// src/lint/rules/consistent-param-style.ts
+var consistentParamStyle = {
+  name: "consistent-param-style",
+  defaultSeverity: "off",
+  check(exp, rawJSDoc) {
+    if (!rawJSDoc)
+      return [];
+    const violations = [];
+    const paramRegex = /@param\s+(?:\{[^}]+\}\s+)?(\S+)\s+([^@\n]+)/g;
+    let match;
+    while ((match = paramRegex.exec(rawJSDoc)) !== null) {
+      const paramName = match[1];
+      const rest = match[2].trim();
+      if (rest && !rest.startsWith("-") && !rest.startsWith("–")) {
+        violations.push({
+          rule: "consistent-param-style",
+          severity: "warn",
+          message: `Parameter '${paramName}' should use dash separator: @param ${paramName} - description`,
+          fixable: true
+        });
+      }
+    }
+    return violations;
+  },
+  fix(_exp, rawJSDoc) {
+    if (!rawJSDoc)
+      return null;
+    const patch = parseJSDocToPatch(rawJSDoc);
+    if (!patch.params || patch.params.length === 0)
+      return null;
+    return patch;
+  }
+};
+// src/lint/rules/no-empty-returns.ts
+var noEmptyReturns = {
+  name: "no-empty-returns",
+  defaultSeverity: "warn",
+  check(exp, rawJSDoc) {
+    if (!rawJSDoc)
+      return [];
+    const returnsMatch = rawJSDoc.match(/@returns?\s*(?:\{[^}]*\})?\s*$/m);
+    if (returnsMatch) {
+      return [
+        {
+          rule: "no-empty-returns",
+          severity: "warn",
+          message: `Export '${exp.name}' has @returns without a description`,
+          fixable: false
+        }
+      ];
+    }
+    const returnsTypeOnly = rawJSDoc.match(/@returns?\s+\{[^}]+\}\s*$/m);
+    if (returnsTypeOnly) {
+      return [
+        {
+          rule: "no-empty-returns",
+          severity: "warn",
+          message: `Export '${exp.name}' has @returns without a description`,
+          fixable: false
+        }
+      ];
+    }
+    return [];
+  }
+};
+// src/lint/rules/require-description.ts
+var requireDescription = {
+  name: "require-description",
+  defaultSeverity: "warn",
+  check(exp) {
+    if (!exp.description || exp.description.trim() === "") {
+      return [
+        {
+          rule: "require-description",
+          severity: "warn",
+          message: `Export '${exp.name}' is missing a description`,
+          fixable: false
+        }
+      ];
+    }
+    return [];
+  }
+};
+// src/lint/rules/require-example.ts
+var requireExample = {
+  name: "require-example",
+  defaultSeverity: "off",
+  check(exp) {
+    if (exp.kind !== "function" && exp.kind !== "method") {
+      return [];
+    }
+    if (!exp.examples || exp.examples.length === 0) {
+      return [
+        {
+          rule: "require-example",
+          severity: "warn",
+          message: `Function '${exp.name}' is missing an @example`,
+          fixable: false
+        }
+      ];
+    }
+    return [];
+  }
+};
+// src/lint/engine.ts
+var allRules = [
+  requireDescription,
+  requireExample,
+  noEmptyReturns,
+  consistentParamStyle
+];
+function getDefaultConfig() {
+  const rules = {};
+  for (const rule of allRules) {
+    rules[rule.name] = rule.defaultSeverity;
+  }
+  return { rules };
+}
+function getRule(name) {
+  return allRules.find((r) => r.name === name);
+}
+function lintExport(exp, rawJSDoc, config = getDefaultConfig()) {
+  const violations = [];
+  for (const rule of allRules) {
+    const severity = config.rules[rule.name];
+    if (severity === "off")
+      continue;
+    const ruleViolations = rule.check(exp, rawJSDoc);
+    for (const v of ruleViolations) {
+      violations.push({
+        ...v,
+        severity: severity === "error" ? "error" : "warn"
+      });
+    }
+  }
+  return violations;
+}
+function lintExports(exports, config = getDefaultConfig()) {
+  const violations = [];
+  for (const { export: exp, rawJSDoc } of exports) {
+    violations.push(...lintExport(exp, rawJSDoc, config));
+  }
+  return {
+    violations,
+    errorCount: violations.filter((v) => v.severity === "error").length,
+    warningCount: violations.filter((v) => v.severity === "warn").length,
+    fixableCount: violations.filter((v) => v.fixable).length
+  };
+}
+function mergeConfig(userConfig) {
+  const defaults = getDefaultConfig();
+  return {
+    rules: {
+      ...defaults.rules,
+      ...userConfig.rules
+    }
+  };
+}
+// src/typecheck/example-typechecker.ts
+import * as fs7 from "node:fs";
+import * as path8 from "node:path";
+import ts3 from "typescript";
+function stripCodeBlockMarkers2(code) {
+  return code.replace(/^```(?:ts|typescript|js|javascript)?\n?/i, "").replace(/\n?```$/i, "").trim();
+}
+function getPackageName(packagePath) {
+  const pkgJsonPath = path8.join(packagePath, "package.json");
+  if (fs7.existsSync(pkgJsonPath)) {
+    try {
+      const pkgJson = JSON.parse(fs7.readFileSync(pkgJsonPath, "utf-8"));
+      return pkgJson.name;
+    } catch {
+      return;
+    }
+  }
+  return;
+}
+function findTsConfig(packagePath) {
+  let dir = packagePath;
+  while (dir !== path8.dirname(dir)) {
+    const tsConfigPath = path8.join(dir, "tsconfig.json");
+    if (fs7.existsSync(tsConfigPath)) {
+      return tsConfigPath;
+    }
+    dir = path8.dirname(dir);
+  }
+  return;
+}
+function createVirtualSource(example, packageName, exportNames) {
+  const cleanCode = stripCodeBlockMarkers2(example);
+  const lines = [];
+  if (packageName && exportNames && exportNames.length > 0) {
+    lines.push(`import { ${exportNames.join(", ")} } from '${packageName}';`);
+    lines.push("");
+  }
+  lines.push(cleanCode);
+  return lines.join(`
+`);
+}
+function getCompilerOptions(tsconfigPath) {
+  if (tsconfigPath && fs7.existsSync(tsconfigPath)) {
+    const configFile = ts3.readConfigFile(tsconfigPath, ts3.sys.readFile);
+    if (!configFile.error) {
+      const parsed = ts3.parseJsonConfigFileContent(configFile.config, ts3.sys, path8.dirname(tsconfigPath));
+      return {
+        ...parsed.options,
+        noEmit: true,
+        skipLibCheck: true
+      };
+    }
+  }
+  return {
+    target: ts3.ScriptTarget.ES2022,
+    module: ts3.ModuleKind.ESNext,
+    moduleResolution: ts3.ModuleResolutionKind.Bundler,
+    esModuleInterop: true,
+    strict: true,
+    noEmit: true,
+    skipLibCheck: true
+  };
+}
+function typecheckExample(example, packagePath, options = {}) {
+  const errors = [];
+  const cleanCode = stripCodeBlockMarkers2(example);
+  const packageName = options.packageName ?? getPackageName(packagePath);
+  const tsconfigPath = options.tsconfig ?? findTsConfig(packagePath);
+  const compilerOptions = getCompilerOptions(tsconfigPath);
+  const virtualSource = createVirtualSource(cleanCode, packageName);
+  const virtualFileName = path8.join(packagePath, "__doccov_example__.ts");
+  const hasImport = packageName !== undefined;
+  const lineOffset = hasImport ? 2 : 0;
+  const sourceFile = ts3.createSourceFile(virtualFileName, virtualSource, ts3.ScriptTarget.ES2022, true);
+  const defaultHost = ts3.createCompilerHost(compilerOptions);
+  const customHost = {
+    ...defaultHost,
+    getSourceFile: (fileName, languageVersion) => {
+      if (fileName === virtualFileName) {
+        return sourceFile;
+      }
+      return defaultHost.getSourceFile(fileName, languageVersion);
+    },
+    fileExists: (fileName) => {
+      if (fileName === virtualFileName)
+        return true;
+      return defaultHost.fileExists(fileName);
+    },
+    readFile: (fileName) => {
+      if (fileName === virtualFileName)
+        return virtualSource;
+      return defaultHost.readFile(fileName);
+    }
+  };
+  const program = ts3.createProgram([virtualFileName], compilerOptions, customHost);
+  const diagnostics = ts3.getPreEmitDiagnostics(program, sourceFile);
+  for (const diagnostic of diagnostics) {
+    if (diagnostic.file && diagnostic.start !== undefined) {
+      const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+      const exampleLine = line - lineOffset + 1;
+      if (exampleLine < 1)
+        continue;
+      errors.push({
+        exampleIndex: 0,
+        line: exampleLine,
+        column: character + 1,
+        message: ts3.flattenDiagnosticMessageText(diagnostic.messageText, `
+`),
+        code: diagnostic.code
+      });
+    }
+  }
+  return errors;
+}
+function typecheckExamples(examples, packagePath, options = {}) {
+  const allErrors = [];
+  let passed = 0;
+  let failed = 0;
+  for (let i = 0;i < examples.length; i++) {
+    const example = examples[i];
+    if (!example || typeof example !== "string" || !example.trim()) {
+      continue;
+    }
+    const errors = typecheckExample(example, packagePath, options);
+    for (const error of errors) {
+      allErrors.push({ ...error, exampleIndex: i });
+    }
+    if (errors.length > 0) {
+      failed++;
+    } else {
+      passed++;
+    }
+  }
+  return {
+    errors: allErrors,
+    passed,
+    failed
+  };
+}
 export {
+  typecheckExamples,
+  typecheckExample,
   serializeJSDoc,
   safeParseJson,
   runExamplesWithPackage,
   runExamples,
   runExample,
+  requireExample,
+  requireDescription,
   readPackageJson,
   parseMarkdownFiles,
   parseMarkdownFile,
   parseJSDocToPatch,
   parseAssertions,
+  noEmptyReturns,
   mergeFixes,
+  mergeConfig,
+  lintExports,
+  lintExport,
   isFixableDrift,
   isExecutableLang,
   hasNonAssertionComments,
@@ -5957,10 +6262,12 @@ export {
   hasDocsForExport,
   getUndocumentedExports,
   getRunCommand,
+  getRule,
   getPrimaryBuildScript,
   getInstallCommand2 as getInstallCommand,
   getDocumentedExports,
   getDocsImpactSummary,
+  getDefaultConfig,
   generateFixesForExport,
   generateFix,
   formatPackageList,
@@ -5980,6 +6287,7 @@ export {
   detectEntryPoint,
   detectBuildInfo,
   createSourceFile,
+  consistentParamStyle,
   categorizeDrifts,
   blockReferencesExport,
   applyPatchToJSDoc,
@@ -5988,6 +6296,7 @@ export {
   analyzeFile,
   analyzeDocsImpact,
   analyze,
+  allRules,
   SandboxFileSystem,
   OpenPkg,
   NodeFileSystem,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/sdk",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "DocCov SDK - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",