@doccov/spec 0.24.0

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+type DriftType = "param-mismatch" | "param-type-mismatch" | "return-type-mismatch" | "generic-constraint-mismatch" | "optionality-mismatch" | "deprecated-mismatch" | "visibility-mismatch" | "async-mismatch" | "property-type-drift" | "example-drift" | "example-syntax-error" | "example-runtime-error" | "example-assertion-failed" | "broken-link";
+type DriftCategory = "structural" | "semantic" | "example";
+declare const DRIFT_CATEGORIES: Record<DriftType, DriftCategory>;
+declare const DRIFT_CATEGORY_LABELS: Record<DriftCategory, string>;
+declare const DRIFT_CATEGORY_DESCRIPTIONS: Record<DriftCategory, string>;
+type DocCovDrift = {
+	type: DriftType;
+	target?: string;
+	issue: string;
+	suggestion?: string;
+	category: DriftCategory;
+	fixable: boolean;
+};
+type ExampleTypecheckError = {
+	exampleIndex: number;
+	line: number;
+	column: number;
+	message: string;
+};
+type ExampleRuntimeDrift = {
+	exampleIndex: number;
+	issue: string;
+	suggestion?: string;
+};
+type ExampleAnalysis = {
+	typecheckErrors?: ExampleTypecheckError[];
+	runtimeDrifts?: ExampleRuntimeDrift[];
+};
+type MissingDocRule = "description" | "params" | "returns" | "examples" | "throws";
+type DocCovSpecVersion = "1.0.0";
+type DocCovSpec = {
+	$schema?: string;
+	doccov: DocCovSpecVersion;
+	/** Reference to source openpkg spec */
+	source: {
+		file: string;
+		specVersion: string;
+		packageName: string;
+		packageVersion?: string;
+	};
+	generatedAt: string;
+	/** Aggregate coverage summary */
+	summary: DocCovSummary;
+	/** Per-analysis, keyed by openpkg ID */
+	exports: Record<string, ExportAnalysis>;
+};
+type DocCovSummary = {
+	/** Overall coverage score (0-100) */
+	score: number;
+	/** Total exports analyzed */
+	totalExports: number;
+	/** Exports with complete documentation */
+	documentedExports: number;
+	/** Missing documentation by rule */
+	missingByRule: Record<MissingDocRule, number>;
+	/** Drift summary */
+	drift: {
+		total: number;
+		fixable: number;
+		byCategory: Record<DriftCategory, number>;
+	};
+	/** Example validation summary (if run) */
+	examples?: {
+		total: number;
+		withExamples: number;
+		typecheckPassed?: number;
+		typecheckFailed?: number;
+		runtimePassed?: number;
+		runtimeFailed?: number;
+	};
+};
+type ExportAnalysis = {
+	/** Coverage score for this (0-100) */
+	coverageScore: number;
+	/** Missing documentation rules */
+	missing?: MissingDocRule[];
+	/** Drift issues */
+	drift?: DocCovDrift[];
+	/** Example validation results */
+	examples?: ExampleAnalysis;
+};
+declare const SCHEMA_VERSION = "1.0.0";
+declare const SCHEMA_URL = "https://unpkg.com/@doccov/spec/schemas/v1.0.0/doccov.schema.json";
+type DocCovSchemaVersion = "1.0.0" | "latest";
+declare const LATEST_VERSION: DocCovSchemaVersion;
+type DocCovSpecError = {
+	instancePath: string;
+	message: string;
+	keyword: string;
+};
+declare function validateDocCovSpec(spec: unknown, version?: DocCovSchemaVersion): {
+	ok: true;
+} | {
+	ok: false;
+	errors: DocCovSpecError[];
+};
+declare function assertDocCovSpec(spec: unknown, version?: DocCovSchemaVersion): asserts spec is DocCovSpec;
+declare function getDocCovValidationErrors(spec: unknown, version?: DocCovSchemaVersion): DocCovSpecError[];
+declare function getAvailableDocCovVersions(): string[];
+export { validateDocCovSpec, getDocCovValidationErrors, getAvailableDocCovVersions, assertDocCovSpec, SCHEMA_VERSION, SCHEMA_URL, MissingDocRule, LATEST_VERSION, ExportAnalysis, ExampleTypecheckError, ExampleRuntimeDrift, ExampleAnalysis, DriftType, DriftCategory, DocCovSummary, DocCovSpecVersion, DocCovSpecError, DocCovSpec, DocCovSchemaVersion, DocCovDrift, DRIFT_CATEGORY_LABELS, DRIFT_CATEGORY_DESCRIPTIONS, DRIFT_CATEGORIES };

package/dist/index.js

@@ -0,0 +1,259 @@
+// src/types.ts
+var DRIFT_CATEGORIES = {
+  "param-mismatch": "structural",
+  "param-type-mismatch": "structural",
+  "return-type-mismatch": "structural",
+  "optionality-mismatch": "structural",
+  "generic-constraint-mismatch": "structural",
+  "property-type-drift": "structural",
+  "async-mismatch": "structural",
+  "deprecated-mismatch": "semantic",
+  "visibility-mismatch": "semantic",
+  "broken-link": "semantic",
+  "example-drift": "example",
+  "example-syntax-error": "example",
+  "example-runtime-error": "example",
+  "example-assertion-failed": "example"
+};
+var DRIFT_CATEGORY_LABELS = {
+  structural: "Signature mismatches",
+  semantic: "Metadata issues",
+  example: "Example problems"
+};
+var DRIFT_CATEGORY_DESCRIPTIONS = {
+  structural: "JSDoc types or parameters don't match the actual code signature",
+  semantic: "Deprecation, visibility, or reference issues",
+  example: "@example code has errors or doesn't work correctly"
+};
+// src/constants.ts
+var SCHEMA_VERSION = "1.0.0";
+var SCHEMA_URL = "https://unpkg.com/@doccov/spec/schemas/v1.0.0/doccov.schema.json";
+// src/validate.ts
+import Ajv from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+// schemas/v1.0.0/doccov.schema.json
+var doccov_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://unpkg.com/@doccov/spec/schemas/v1.0.0/doccov.schema.json",
+  title: "DocCov Specification",
+  description: "Documentation coverage analysis specification",
+  type: "object",
+  required: ["doccov", "source", "generatedAt", "summary", "exports"],
+  properties: {
+    $schema: { type: "string" },
+    doccov: { const: "1.0.0" },
+    source: { $ref: "#/$defs/source" },
+    generatedAt: { type: "string", format: "date-time" },
+    summary: { $ref: "#/$defs/summary" },
+    exports: {
+      type: "object",
+      additionalProperties: { $ref: "#/$defs/exportAnalysis" }
+    }
+  },
+  $defs: {
+    source: {
+      type: "object",
+      required: ["file", "specVersion", "packageName"],
+      properties: {
+        file: { type: "string" },
+        specVersion: { type: "string" },
+        packageName: { type: "string" },
+        packageVersion: { type: "string" }
+      }
+    },
+    driftType: {
+      type: "string",
+      enum: [
+        "param-mismatch",
+        "param-type-mismatch",
+        "return-type-mismatch",
+        "generic-constraint-mismatch",
+        "optionality-mismatch",
+        "deprecated-mismatch",
+        "visibility-mismatch",
+        "async-mismatch",
+        "property-type-drift",
+        "example-drift",
+        "example-syntax-error",
+        "example-runtime-error",
+        "example-assertion-failed",
+        "broken-link"
+      ]
+    },
+    driftCategory: {
+      type: "string",
+      enum: ["structural", "semantic", "example"]
+    },
+    missingDocRule: {
+      type: "string",
+      enum: ["description", "params", "returns", "examples", "throws"]
+    },
+    drift: {
+      type: "object",
+      required: ["type", "issue", "category", "fixable"],
+      properties: {
+        type: { $ref: "#/$defs/driftType" },
+        target: { type: "string" },
+        issue: { type: "string" },
+        suggestion: { type: "string" },
+        category: { $ref: "#/$defs/driftCategory" },
+        fixable: { type: "boolean" }
+      }
+    },
+    summary: {
+      type: "object",
+      required: ["score", "totalExports", "documentedExports", "missingByRule", "drift"],
+      properties: {
+        score: { type: "number", minimum: 0, maximum: 100 },
+        totalExports: { type: "integer", minimum: 0 },
+        documentedExports: { type: "integer", minimum: 0 },
+        missingByRule: {
+          type: "object",
+          additionalProperties: { type: "integer", minimum: 0 }
+        },
+        drift: {
+          type: "object",
+          required: ["total", "fixable", "byCategory"],
+          properties: {
+            total: { type: "integer", minimum: 0 },
+            fixable: { type: "integer", minimum: 0 },
+            byCategory: {
+              type: "object",
+              additionalProperties: { type: "integer", minimum: 0 }
+            }
+          }
+        },
+        examples: {
+          type: "object",
+          properties: {
+            total: { type: "integer", minimum: 0 },
+            withExamples: { type: "integer", minimum: 0 },
+            typecheckPassed: { type: "integer", minimum: 0 },
+            typecheckFailed: { type: "integer", minimum: 0 },
+            runtimePassed: { type: "integer", minimum: 0 },
+            runtimeFailed: { type: "integer", minimum: 0 }
+          }
+        }
+      }
+    },
+    exampleTypecheckError: {
+      type: "object",
+      required: ["exampleIndex", "line", "column", "message"],
+      properties: {
+        exampleIndex: { type: "integer", minimum: 0 },
+        line: { type: "integer", minimum: 0 },
+        column: { type: "integer", minimum: 0 },
+        message: { type: "string" }
+      }
+    },
+    exampleRuntimeDrift: {
+      type: "object",
+      required: ["exampleIndex", "issue"],
+      properties: {
+        exampleIndex: { type: "integer", minimum: 0 },
+        issue: { type: "string" },
+        suggestion: { type: "string" }
+      }
+    },
+    exampleAnalysis: {
+      type: "object",
+      properties: {
+        typecheckErrors: {
+          type: "array",
+          items: { $ref: "#/$defs/exampleTypecheckError" }
+        },
+        runtimeDrifts: {
+          type: "array",
+          items: { $ref: "#/$defs/exampleRuntimeDrift" }
+        }
+      }
+    },
+    exportAnalysis: {
+      type: "object",
+      required: ["coverageScore"],
+      properties: {
+        coverageScore: { type: "number", minimum: 0, maximum: 100 },
+        missing: {
+          type: "array",
+          items: { $ref: "#/$defs/missingDocRule" }
+        },
+        drift: {
+          type: "array",
+          items: { $ref: "#/$defs/drift" }
+        },
+        examples: { $ref: "#/$defs/exampleAnalysis" }
+      }
+    }
+  }
+};
+
+// src/validate.ts
+var LATEST_VERSION = "1.0.0";
+var schemas = {
+  "1.0.0": doccov_schema_default
+};
+var ajv = new Ajv({
+  strict: false,
+  allErrors: true,
+  allowUnionTypes: true
+});
+addFormats(ajv);
+var validatorCache = new Map;
+function getValidator(version = "latest") {
+  const resolvedVersion = version === "latest" ? LATEST_VERSION : version;
+  let validator = validatorCache.get(resolvedVersion);
+  if (validator) {
+    return validator;
+  }
+  const schema = schemas[resolvedVersion];
+  if (!schema) {
+    throw new Error(`Unknown schema version: ${resolvedVersion}. Available: ${Object.keys(schemas).join(", ")}`);
+  }
+  validator = ajv.compile(schema);
+  validatorCache.set(resolvedVersion, validator);
+  return validator;
+}
+function validateDocCovSpec(spec, version = "latest") {
+  const validate = getValidator(version);
+  const ok = validate(spec);
+  if (ok) {
+    return { ok: true };
+  }
+  const errors = (validate.errors ?? []).map((error) => ({
+    instancePath: error.instancePath ?? "",
+    message: error.message ?? "invalid",
+    keyword: error.keyword ?? "unknown"
+  }));
+  return {
+    ok: false,
+    errors
+  };
+}
+function assertDocCovSpec(spec, version = "latest") {
+  const result = validateDocCovSpec(spec, version);
+  if (!result.ok) {
+    const details = result.errors.map((error) => `- ${error.instancePath || "/"} ${error.message}`).join(`
+`);
+    throw new Error(`Invalid DocCovSpec:
+${details}`);
+  }
+}
+function getDocCovValidationErrors(spec, version = "latest") {
+  const result = validateDocCovSpec(spec, version);
+  return result.ok ? [] : result.errors;
+}
+function getAvailableDocCovVersions() {
+  return Object.keys(schemas);
+}
+export {
+  validateDocCovSpec,
+  getDocCovValidationErrors,
+  getAvailableDocCovVersions,
+  assertDocCovSpec,
+  SCHEMA_VERSION,
+  SCHEMA_URL,
+  LATEST_VERSION,
+  DRIFT_CATEGORY_LABELS,
+  DRIFT_CATEGORY_DESCRIPTIONS,
+  DRIFT_CATEGORIES
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@doccov/spec",
+  "version": "0.24.0",
+  "description": "DocCov specification schema, types, and validation",
+  "keywords": [
+    "doccov",
+    "documentation",
+    "coverage",
+    "json-schema",
+    "validation",
+    "typescript"
+  ],
+  "homepage": "https://github.com/doccov/doccov#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doccov/doccov.git",
+    "directory": "packages/doccov-spec"
+  },
+  "license": "MIT",
+  "author": "Ryan Waits",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "schemas"
+  ],
+  "scripts": {
+    "build": "bunup",
+    "dev": "bunup --watch",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "format": "biome format --write src/"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^20.0.0",
+    "bunup": "latest",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schemas/v1.0.0/doccov.schema.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/@doccov/spec/schemas/v1.0.0/doccov.schema.json",
+  "title": "DocCov Specification",
+  "description": "Documentation coverage analysis specification",
+  "type": "object",
+  "required": ["doccov", "source", "generatedAt", "summary", "exports"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "doccov": { "const": "1.0.0" },
+    "source": { "$ref": "#/$defs/source" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "summary": { "$ref": "#/$defs/summary" },
+    "exports": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/exportAnalysis" }
+    }
+  },
+  "$defs": {
+    "source": {
+      "type": "object",
+      "required": ["file", "specVersion", "packageName"],
+      "properties": {
+        "file": { "type": "string" },
+        "specVersion": { "type": "string" },
+        "packageName": { "type": "string" },
+        "packageVersion": { "type": "string" }
+      }
+    },
+    "driftType": {
+      "type": "string",
+      "enum": [
+        "param-mismatch",
+        "param-type-mismatch",
+        "return-type-mismatch",
+        "generic-constraint-mismatch",
+        "optionality-mismatch",
+        "deprecated-mismatch",
+        "visibility-mismatch",
+        "async-mismatch",
+        "property-type-drift",
+        "example-drift",
+        "example-syntax-error",
+        "example-runtime-error",
+        "example-assertion-failed",
+        "broken-link"
+      ]
+    },
+    "driftCategory": {
+      "type": "string",
+      "enum": ["structural", "semantic", "example"]
+    },
+    "missingDocRule": {
+      "type": "string",
+      "enum": ["description", "params", "returns", "examples", "throws"]
+    },
+    "drift": {
+      "type": "object",
+      "required": ["type", "issue", "category", "fixable"],
+      "properties": {
+        "type": { "$ref": "#/$defs/driftType" },
+        "target": { "type": "string" },
+        "issue": { "type": "string" },
+        "suggestion": { "type": "string" },
+        "category": { "$ref": "#/$defs/driftCategory" },
+        "fixable": { "type": "boolean" }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["score", "totalExports", "documentedExports", "missingByRule", "drift"],
+      "properties": {
+        "score": { "type": "number", "minimum": 0, "maximum": 100 },
+        "totalExports": { "type": "integer", "minimum": 0 },
+        "documentedExports": { "type": "integer", "minimum": 0 },
+        "missingByRule": {
+          "type": "object",
+          "additionalProperties": { "type": "integer", "minimum": 0 }
+        },
+        "drift": {
+          "type": "object",
+          "required": ["total", "fixable", "byCategory"],
+          "properties": {
+            "total": { "type": "integer", "minimum": 0 },
+            "fixable": { "type": "integer", "minimum": 0 },
+            "byCategory": {
+              "type": "object",
+              "additionalProperties": { "type": "integer", "minimum": 0 }
+            }
+          }
+        },
+        "examples": {
+          "type": "object",
+          "properties": {
+            "total": { "type": "integer", "minimum": 0 },
+            "withExamples": { "type": "integer", "minimum": 0 },
+            "typecheckPassed": { "type": "integer", "minimum": 0 },
+            "typecheckFailed": { "type": "integer", "minimum": 0 },
+            "runtimePassed": { "type": "integer", "minimum": 0 },
+            "runtimeFailed": { "type": "integer", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "exampleTypecheckError": {
+      "type": "object",
+      "required": ["exampleIndex", "line", "column", "message"],
+      "properties": {
+        "exampleIndex": { "type": "integer", "minimum": 0 },
+        "line": { "type": "integer", "minimum": 0 },
+        "column": { "type": "integer", "minimum": 0 },
+        "message": { "type": "string" }
+      }
+    },
+    "exampleRuntimeDrift": {
+      "type": "object",
+      "required": ["exampleIndex", "issue"],
+      "properties": {
+        "exampleIndex": { "type": "integer", "minimum": 0 },
+        "issue": { "type": "string" },
+        "suggestion": { "type": "string" }
+      }
+    },
+    "exampleAnalysis": {
+      "type": "object",
+      "properties": {
+        "typecheckErrors": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/exampleTypecheckError" }
+        },
+        "runtimeDrifts": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/exampleRuntimeDrift" }
+        }
+      }
+    },
+    "exportAnalysis": {
+      "type": "object",
+      "required": ["coverageScore"],
+      "properties": {
+        "coverageScore": { "type": "number", "minimum": 0, "maximum": 100 },
+        "missing": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/missingDocRule" }
+        },
+        "drift": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/drift" }
+        },
+        "examples": { "$ref": "#/$defs/exampleAnalysis" }
+      }
+    }
+  }
+}