@openpkg-ts/spec 0.1.0 → 0.2.2

package/dist/index.js

@@ -1,22 +1,256 @@
 // src/constants.ts
-var SCHEMA_VERSION = "0.1.0";
-var SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.1.0/openpkg.schema.json";
+var SCHEMA_VERSION = "0.2.0";
+var SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.2.0/openpkg.schema.json";
 var JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
+// src/deref.ts
+function dereference(spec) {
+  const clone = JSON.parse(JSON.stringify(spec));
+  const typeLookup = buildTypeLookup(clone.types);
+  const visit = (value, seen) => {
+    if (Array.isArray(value)) {
+      return value.map((item) => visit(item, new Set(seen)));
+    }
+    if (value && typeof value === "object") {
+      const record = value;
+      const ref = readTypeRef(record);
+      if (ref) {
+        return resolveTypeRef(ref, typeLookup, seen);
+      }
+      const next = {};
+      for (const [key, nested] of Object.entries(record)) {
+        next[key] = visit(nested, seen);
+      }
+      return next;
+    }
+    return value;
+  };
+  clone.exports = clone.exports.map((item) => visit(item, new Set));
+  if (clone.types) {
+    clone.types = clone.types.map((item) => visit(item, new Set));
+  }
+  return clone;
+}
+function buildTypeLookup(types) {
+  const map = new Map;
+  if (!Array.isArray(types)) {
+    return map;
+  }
+  for (const type of types) {
+    if (type && typeof type.id === "string") {
+      map.set(type.id, type);
+    }
+  }
+  return map;
+}
+function readTypeRef(value) {
+  const ref = value.$ref;
+  if (typeof ref !== "string") {
+    return null;
+  }
+  const prefix = "#/types/";
+  if (!ref.startsWith(prefix)) {
+    return null;
+  }
+  return ref.slice(prefix.length);
+}
+function resolveTypeRef(id, lookup, seen) {
+  if (seen.has(id)) {
+    return { $ref: `#/types/${id}` };
+  }
+  const target = lookup.get(id);
+  if (!target) {
+    return { $ref: `#/types/${id}` };
+  }
+  seen.add(id);
+  if (target.schema) {
+    return JSON.parse(JSON.stringify(target.schema));
+  }
+  return JSON.parse(JSON.stringify(target));
+}
+// src/diff.ts
+function diffSpec(oldSpec, newSpec) {
+  const result = {
+    breaking: [],
+    nonBreaking: [],
+    docsOnly: [],
+    coverageDelta: 0,
+    oldCoverage: 0,
+    newCoverage: 0,
+    newUndocumented: [],
+    improvedExports: [],
+    regressedExports: [],
+    driftIntroduced: 0,
+    driftResolved: 0
+  };
+  diffCollections(result, oldSpec.exports, newSpec.exports);
+  diffCollections(result, oldSpec.types ?? [], newSpec.types ?? []);
+  result.oldCoverage = oldSpec.docs?.coverageScore ?? 0;
+  result.newCoverage = newSpec.docs?.coverageScore ?? 0;
+  result.coverageDelta = Math.round((result.newCoverage - result.oldCoverage) * 10) / 10;
+  const oldExportMap = toExportMap(oldSpec.exports);
+  const newExportMap = toExportMap(newSpec.exports);
+  for (const [id, newExport] of newExportMap.entries()) {
+    const oldExport = oldExportMap.get(id);
+    const newScore = newExport.docs?.coverageScore ?? 0;
+    const newDriftCount = newExport.docs?.drift?.length ?? 0;
+    if (!oldExport) {
+      if (newScore < 100 || (newExport.docs?.missing?.length ?? 0) > 0) {
+        result.newUndocumented.push(id);
+      }
+      result.driftIntroduced += newDriftCount;
+      continue;
+    }
+    const oldScore = oldExport.docs?.coverageScore ?? 0;
+    const oldDriftCount = oldExport.docs?.drift?.length ?? 0;
+    if (newScore > oldScore) {
+      result.improvedExports.push(id);
+    } else if (newScore < oldScore) {
+      result.regressedExports.push(id);
+    }
+    if (newDriftCount > oldDriftCount) {
+      result.driftIntroduced += newDriftCount - oldDriftCount;
+    } else if (oldDriftCount > newDriftCount) {
+      result.driftResolved += oldDriftCount - newDriftCount;
+    }
+  }
+  return result;
+}
+function toExportMap(exports) {
+  const map = new Map;
+  for (const exp of exports) {
+    if (exp && typeof exp.id === "string") {
+      map.set(exp.id, exp);
+    }
+  }
+  return map;
+}
+function diffCollections(result, oldItems, newItems) {
+  const oldMap = toMap(oldItems);
+  const newMap = toMap(newItems);
+  for (const [id, oldItem] of oldMap.entries()) {
+    const newItem = newMap.get(id);
+    if (!newItem) {
+      result.breaking.push(id);
+      continue;
+    }
+    const docOnly = isDocOnlyChange(oldItem, newItem);
+    const identical = isDeepEqual(oldItem, newItem);
+    if (identical) {
+      continue;
+    }
+    if (docOnly) {
+      result.docsOnly.push(id);
+      continue;
+    }
+    result.breaking.push(id);
+  }
+  for (const id of newMap.keys()) {
+    if (!oldMap.has(id)) {
+      result.nonBreaking.push(id);
+    }
+  }
+}
+function toMap(items) {
+  const map = new Map;
+  for (const item of items) {
+    if (item && typeof item.id === "string") {
+      map.set(item.id, item);
+    }
+  }
+  return map;
+}
+var DOC_KEYS = new Set(["description", "examples", "tags", "source", "rawComments"]);
+function isDocOnlyChange(a, b) {
+  const structuralA = normalizeForComparison(removeDocFields(a));
+  const structuralB = normalizeForComparison(removeDocFields(b));
+  if (structuralA !== structuralB) {
+    return false;
+  }
+  const fullA = normalizeForComparison(a);
+  const fullB = normalizeForComparison(b);
+  return fullA !== fullB;
+}
+function isDeepEqual(a, b) {
+  return normalizeForComparison(a) === normalizeForComparison(b);
+}
+function removeDocFields(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => removeDocFields(item));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const entries = Object.entries(value).filter(([key]) => !DOC_KEYS.has(key));
+  const cleaned = {};
+  for (const [key, val] of entries) {
+    cleaned[key] = removeDocFields(val);
+  }
+  return cleaned;
+}
+function normalizeForComparison(value) {
+  return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortKeys(item));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+  const result = {};
+  for (const [key, val] of entries) {
+    result[key] = sortKeys(val);
+  }
+  return result;
+}
+// src/normalize.ts
+var DEFAULT_ECOSYSTEM = "js/ts";
+var arrayFieldsByExport = ["signatures", "members", "examples", "tags"];
+var arrayFieldsByType = ["members", "tags"];
+function normalize(spec) {
+  const normalized = JSON.parse(JSON.stringify(spec));
+  normalized.meta = {
+    ecosystem: normalized.meta?.ecosystem ?? DEFAULT_ECOSYSTEM,
+    ...normalized.meta
+  };
+  normalized.exports = Array.isArray(normalized.exports) ? [...normalized.exports] : [];
+  normalized.exports.sort((a, b) => (a.name || "").localeCompare(b.name || ""));
+  normalized.exports = normalized.exports.map((item) => normalizeExport(item));
+  const types = Array.isArray(normalized.types) ? [...normalized.types] : [];
+  types.sort((a, b) => (a.name || "").localeCompare(b.name || ""));
+  normalized.types = types.map((item) => normalizeType(item));
+  return normalized;
+}
+function normalizeExport(item) {
+  const clone = JSON.parse(JSON.stringify(item));
+  for (const field of arrayFieldsByExport) {
+    if (!Array.isArray(clone[field])) {
+      clone[field] = [];
+    }
+  }
+  return clone;
+}
+function normalizeType(item) {
+  const clone = JSON.parse(JSON.stringify(item));
+  for (const field of arrayFieldsByType) {
+    if (!Array.isArray(clone[field])) {
+      clone[field] = [];
+    }
+  }
+  return clone;
+}
 // src/validate.ts
 import Ajv from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
-// schemas/v0.1.0/openpkg.schema.json
+// schemas/v0.2.0/openpkg.schema.json
 var openpkg_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: "https://unpkg.com/@openpkg-ts/spec/schemas/v0.1.0/openpkg.schema.json",
+  $id: "https://unpkg.com/@openpkg-ts/spec/schemas/v0.2.0/openpkg.schema.json",
   title: "OpenPkg Specification",
   description: "Schema for OpenPkg specification files",
   type: "object",
-  required: [
-    "openpkg",
-    "meta",
-    "exports"
-  ],
+  required: ["openpkg", "meta", "exports"],
   properties: {
     $schema: {
       type: "string",
@@ -27,14 +261,12 @@ var openpkg_schema_default = {
       type: "string",
       description: "OpenPkg specification version",
       pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$",
-      const: "0.1.0"
+      const: "0.2.0"
     },
     meta: {
       type: "object",
       description: "Package metadata",
-      required: [
-        "name"
-      ],
+      required: ["name"],
       properties: {
         name: {
           type: "string",
@@ -58,14 +290,7 @@ var openpkg_schema_default = {
         },
         ecosystem: {
           type: "string",
-          description: "Package ecosystem",
-          enum: [
-            "js/ts",
-            "python",
-            "rust",
-            "go",
-            "java"
-          ]
+          description: "Package ecosystem"
         }
       }
     },
@@ -82,16 +307,81 @@ var openpkg_schema_default = {
       items: {
         $ref: "#/$defs/typeDef"
       }
+    },
+    docs: {
+      $ref: "#/$defs/docsMetadata",
+      description: "Aggregate documentation coverage metadata"
     }
   },
   $defs: {
+    docSignal: {
+      type: "string",
+      enum: ["description", "params", "returns", "examples"]
+    },
+    docDrift: {
+      type: "object",
+      required: ["type", "issue"],
+      properties: {
+        type: {
+          type: "string",
+          enum: [
+            "param-mismatch",
+            "param-type-mismatch",
+            "return-type-mismatch",
+            "generic-constraint-mismatch",
+            "optionality-mismatch",
+            "deprecated-mismatch",
+            "visibility-mismatch",
+            "example-drift",
+            "broken-link"
+          ]
+        },
+        target: {
+          type: "string",
+          description: "Relevant identifier (e.g., parameter name)"
+        },
+        issue: {
+          type: "string",
+          description: "Human-friendly drift explanation"
+        },
+        suggestion: {
+          type: "string",
+          description: "Optional remediation hint"
+        }
+      },
+      additionalProperties: false
+    },
+    docsMetadata: {
+      type: "object",
+      description: "Documentation coverage metadata",
+      additionalProperties: false,
+      properties: {
+        coverageScore: {
+          type: "number",
+          minimum: 0,
+          maximum: 100,
+          description: "Documentation coverage value from 0-100."
+        },
+        missing: {
+          type: "array",
+          description: "Doc components missing for this entity",
+          items: {
+            $ref: "#/$defs/docSignal"
+          },
+          uniqueItems: true
+        },
+        drift: {
+          type: "array",
+          description: "Detected documentation drift signals",
+          items: {
+            $ref: "#/$defs/docDrift"
+          }
+        }
+      }
+    },
     export: {
       type: "object",
-      required: [
-        "id",
-        "name",
-        "kind"
-      ],
+      required: ["id", "name", "kind"],
       properties: {
         id: {
           type: "string",
@@ -101,17 +391,26 @@ var openpkg_schema_default = {
           type: "string",
           description: "Export name"
         },
+        slug: {
+          type: "string",
+          description: "Stable slug for linking"
+        },
+        displayName: {
+          type: "string",
+          description: "UI-friendly label"
+        },
+        category: {
+          type: "string",
+          description: "Grouping hint for navigation"
+        },
+        importPath: {
+          type: "string",
+          description: "Recommended import path"
+        },
         kind: {
           type: "string",
           description: "Kind of export",
-          enum: [
-            "function",
-            "class",
-            "variable",
-            "interface",
-            "type",
-            "enum"
-          ]
+          enum: ["function", "class", "variable", "interface", "type", "enum"]
         },
         description: {
           type: "string",
@@ -131,25 +430,40 @@ var openpkg_schema_default = {
             $ref: "#/$defs/signature"
           }
         },
-        properties: {
+        type: {
+          description: "Type reference or inline schema for variables",
+          oneOf: [{ type: "string" }, { $ref: "#/$defs/schema" }]
+        },
+        members: {
+          type: "array",
+          description: "Class/interface/enum members",
+          items: { type: "object" }
+        },
+        tags: {
           type: "array",
-          description: "Class/interface properties",
+          description: "JSDoc/TSDoc tags",
           items: {
-            $ref: "#/$defs/property"
+            type: "object",
+            required: ["name", "text"],
+            properties: {
+              name: { type: "string" },
+              text: { type: "string" }
+            },
+            additionalProperties: false
           }
         },
         source: {
           $ref: "#/$defs/sourceLocation"
+        },
+        docs: {
+          $ref: "#/$defs/docsMetadata",
+          description: "Documentation coverage metadata for this export"
         }
       }
     },
     typeDef: {
       type: "object",
-      required: [
-        "id",
-        "name",
-        "kind"
-      ],
+      required: ["id", "name", "kind"],
       properties: {
         id: {
           type: "string",
@@ -159,15 +473,26 @@ var openpkg_schema_default = {
           type: "string",
           description: "Type name"
         },
+        slug: {
+          type: "string",
+          description: "Stable slug for linking"
+        },
+        displayName: {
+          type: "string",
+          description: "UI-friendly label"
+        },
+        category: {
+          type: "string",
+          description: "Grouping hint for navigation"
+        },
+        importPath: {
+          type: "string",
+          description: "Recommended import path"
+        },
         kind: {
           type: "string",
           description: "Kind of type definition",
-          enum: [
-            "interface",
-            "type",
-            "enum",
-            "class"
-          ]
+          enum: ["interface", "type", "enum", "class"]
         },
         description: {
           type: "string",
@@ -180,11 +505,22 @@ var openpkg_schema_default = {
           type: "string",
           description: "Type expression for type aliases"
         },
-        properties: {
+        members: {
           type: "array",
-          description: "Properties for interfaces/classes",
+          description: "Members for classes/interfaces/enums",
+          items: { type: "object" }
+        },
+        tags: {
+          type: "array",
+          description: "JSDoc/TSDoc tags",
           items: {
-            $ref: "#/$defs/property"
+            type: "object",
+            required: ["name", "text"],
+            properties: {
+              name: { type: "string" },
+              text: { type: "string" }
+            },
+            additionalProperties: false
           }
         },
         source: {
@@ -212,10 +548,7 @@ var openpkg_schema_default = {
     },
     parameter: {
       type: "object",
-      required: [
-        "name",
-        "required"
-      ],
+      required: ["name", "required"],
       properties: {
         name: {
           type: "string",
@@ -225,12 +558,12 @@ var openpkg_schema_default = {
           type: "boolean",
           description: "Whether the parameter is required"
         },
+        schema: {
+          $ref: "#/$defs/schema"
+        },
         description: {
           type: "string",
           description: "Parameter description"
-        },
-        schema: {
-          $ref: "#/$defs/schema"
         }
       }
     },
@@ -246,30 +579,6 @@ var openpkg_schema_default = {
         }
       }
     },
-    property: {
-      type: "object",
-      required: [
-        "name",
-        "required"
-      ],
-      properties: {
-        name: {
-          type: "string",
-          description: "Property name"
-        },
-        required: {
-          type: "boolean",
-          description: "Whether the property is required"
-        },
-        description: {
-          type: "string",
-          description: "Property description"
-        },
-        schema: {
-          $ref: "#/$defs/schema"
-        }
-      }
-    },
     schema: {
       anyOf: [
         {
@@ -284,17 +593,13 @@ var openpkg_schema_default = {
               pattern: "^#/types/[A-Za-z0-9_.-]+$"
             }
           },
-          required: [
-            "$ref"
-          ],
+          required: ["$ref"],
           additionalProperties: false
         },
         {
           type: "object",
           not: {
-            required: [
-              "$ref"
-            ]
+            required: ["$ref"]
           },
           additionalProperties: true
         }
@@ -302,10 +607,7 @@ var openpkg_schema_default = {
     },
     sourceLocation: {
       type: "object",
-      required: [
-        "file",
-        "line"
-      ],
+      required: ["file", "line"],
       properties: {
         file: {
           type: "string",
@@ -358,204 +660,9 @@ function getValidationErrors(spec) {
   const result = validateSpec(spec);
   return result.ok ? [] : result.errors;
 }
-// src/normalize.ts
-var DEFAULT_ECOSYSTEM = "js/ts";
-var arrayFieldsByExport = ["signatures", "members", "examples", "tags"];
-var arrayFieldsByType = ["members", "tags"];
-function normalize(spec) {
-  const normalized = JSON.parse(JSON.stringify(spec));
-  normalized.meta = {
-    ecosystem: normalized.meta?.ecosystem ?? DEFAULT_ECOSYSTEM,
-    ...normalized.meta
-  };
-  normalized.exports = Array.isArray(normalized.exports) ? [...normalized.exports] : [];
-  normalized.exports.sort((a, b) => (a.name || "").localeCompare(b.name || ""));
-  normalized.exports = normalized.exports.map((item) => normalizeExport(item));
-  const types = Array.isArray(normalized.types) ? [...normalized.types] : [];
-  types.sort((a, b) => (a.name || "").localeCompare(b.name || ""));
-  normalized.types = types.map((item) => normalizeType(item));
-  normalized.examples = normalized.examples ?? [];
-  normalized.extensions = normalized.extensions ?? {};
-  return normalized;
-}
-function normalizeExport(item) {
-  const clone = JSON.parse(JSON.stringify(item));
-  for (const field of arrayFieldsByExport) {
-    if (!Array.isArray(clone[field])) {
-      clone[field] = [];
-    }
-  }
-  return clone;
-}
-function normalizeType(item) {
-  const clone = JSON.parse(JSON.stringify(item));
-  for (const field of arrayFieldsByType) {
-    if (!Array.isArray(clone[field])) {
-      clone[field] = [];
-    }
-  }
-  return clone;
-}
-// src/deref.ts
-function dereference(spec) {
-  const clone = JSON.parse(JSON.stringify(spec));
-  const typeLookup = buildTypeLookup(clone.types);
-  const visit = (value, seen) => {
-    if (Array.isArray(value)) {
-      return value.map((item) => visit(item, new Set(seen)));
-    }
-    if (value && typeof value === "object") {
-      const record = value;
-      const ref = readTypeRef(record);
-      if (ref) {
-        return resolveTypeRef(ref, typeLookup, seen);
-      }
-      const next = {};
-      for (const [key, nested] of Object.entries(record)) {
-        next[key] = visit(nested, seen);
-      }
-      return next;
-    }
-    return value;
-  };
-  clone.exports = clone.exports.map((item) => visit(item, new Set));
-  if (clone.types) {
-    clone.types = clone.types.map((item) => visit(item, new Set));
-  }
-  return clone;
-}
-function buildTypeLookup(types) {
-  const map = new Map;
-  if (!Array.isArray(types)) {
-    return map;
-  }
-  for (const type of types) {
-    if (type && typeof type.id === "string") {
-      map.set(type.id, type);
-    }
-  }
-  return map;
-}
-function readTypeRef(value) {
-  const ref = value["$ref"];
-  if (typeof ref !== "string") {
-    return null;
-  }
-  const prefix = "#/types/";
-  if (!ref.startsWith(prefix)) {
-    return null;
-  }
-  return ref.slice(prefix.length);
-}
-function resolveTypeRef(id, lookup, seen) {
-  if (seen.has(id)) {
-    return { $ref: `#/types/${id}` };
-  }
-  const target = lookup.get(id);
-  if (!target) {
-    return { $ref: `#/types/${id}` };
-  }
-  seen.add(id);
-  if (target.schema) {
-    return JSON.parse(JSON.stringify(target.schema));
-  }
-  return JSON.parse(JSON.stringify(target));
-}
-// src/migrate/v0_1_0__to__0_2_0.ts
-function migrate_0_1_0__to__0_2_0(spec) {
-  return spec;
-}
-// src/diff.ts
-function diffSpec(a, b) {
-  const result = { breaking: [], nonBreaking: [], docsOnly: [] };
-  diffCollections(result, a.exports, b.exports);
-  diffCollections(result, a.types ?? [], b.types ?? []);
-  return result;
-}
-function diffCollections(result, oldItems, newItems) {
-  const oldMap = toMap(oldItems);
-  const newMap = toMap(newItems);
-  for (const [id, oldItem] of oldMap.entries()) {
-    const newItem = newMap.get(id);
-    if (!newItem) {
-      result.breaking.push(id);
-      continue;
-    }
-    const docOnly = isDocOnlyChange(oldItem, newItem);
-    const identical = isDeepEqual(oldItem, newItem);
-    if (identical) {
-      continue;
-    }
-    if (docOnly) {
-      result.docsOnly.push(id);
-      continue;
-    }
-    result.breaking.push(id);
-  }
-  for (const id of newMap.keys()) {
-    if (!oldMap.has(id)) {
-      result.nonBreaking.push(id);
-    }
-  }
-}
-function toMap(items) {
-  const map = new Map;
-  for (const item of items) {
-    if (item && typeof item.id === "string") {
-      map.set(item.id, item);
-    }
-  }
-  return map;
-}
-var DOC_KEYS = new Set(["description", "examples", "tags", "source", "rawComments"]);
-function isDocOnlyChange(a, b) {
-  const structuralA = normalizeForComparison(removeDocFields(a));
-  const structuralB = normalizeForComparison(removeDocFields(b));
-  if (structuralA !== structuralB) {
-    return false;
-  }
-  const fullA = normalizeForComparison(a);
-  const fullB = normalizeForComparison(b);
-  return fullA !== fullB;
-}
-function isDeepEqual(a, b) {
-  return normalizeForComparison(a) === normalizeForComparison(b);
-}
-function removeDocFields(value) {
-  if (Array.isArray(value)) {
-    return value.map((item) => removeDocFields(item));
-  }
-  if (!value || typeof value !== "object") {
-    return value;
-  }
-  const entries = Object.entries(value).filter(([key]) => !DOC_KEYS.has(key));
-  const cleaned = {};
-  for (const [key, val] of entries) {
-    cleaned[key] = removeDocFields(val);
-  }
-  return cleaned;
-}
-function normalizeForComparison(value) {
-  return JSON.stringify(sortKeys(value));
-}
-function sortKeys(value) {
-  if (Array.isArray(value)) {
-    return value.map((item) => sortKeys(item));
-  }
-  if (!value || typeof value !== "object") {
-    return value;
-  }
-  const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
-  const result = {};
-  for (const [key, val] of entries) {
-    result[key] = sortKeys(val);
-  }
-  return result;
-}
 export {
   validateSpec,
   normalize,
-  migrate_0_1_0__to__0_2_0 as migrate,
   getValidationErrors,
   diffSpec,
   dereference,