@contractspec/lib.contracts-spec 2.0.0

package/dist/versioning/index.js

@@ -0,0 +1,274 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/versioning/refs.ts
+function isVersionedSpecRef(ref) {
+  return typeof ref === "object" && ref !== null && "key" in ref && typeof ref.key === "string" && ref.key.length > 0 && "version" in ref && typeof ref.version === "string" && ref.version.length > 0;
+}
+function isOptionalVersionedSpecRef(ref) {
+  if (typeof ref !== "object" || ref === null)
+    return false;
+  if (!("key" in ref))
+    return false;
+  if (typeof ref.key !== "string" || ref.key.length === 0) {
+    return false;
+  }
+  if ("version" in ref && ref.version != null) {
+    return typeof ref.version === "string";
+  }
+  return true;
+}
+function isSpecKeyRef(ref) {
+  return typeof ref === "object" && ref !== null && "key" in ref && typeof ref.key === "string" && ref.key.length > 0;
+}
+function createVersionedRef(key, version) {
+  if (!key || key.trim().length === 0) {
+    throw new Error("Spec key cannot be empty");
+  }
+  if (!version || version.trim().length === 0) {
+    throw new Error("Spec version cannot be empty");
+  }
+  return { key: key.trim(), version: version.trim() };
+}
+function createOptionalRef(key, version) {
+  if (!key || key.trim().length === 0) {
+    throw new Error("Spec key cannot be empty");
+  }
+  const ref = { key: key.trim() };
+  if (version != null && version.trim().length > 0) {
+    ref.version = version.trim();
+  }
+  return ref;
+}
+function createKeyRef(key) {
+  if (!key || key.trim().length === 0) {
+    throw new Error("Spec key cannot be empty");
+  }
+  return { key: key.trim() };
+}
+function formatVersionedRefKey(ref) {
+  return `${ref.key}.v${ref.version}`;
+}
+function parseVersionedRefKey(refKey) {
+  const match = refKey.match(/^(.+)\.v(\d+\.\d+\.\d+(?:-.+)?)$/);
+  if (!match)
+    return;
+  const key = match[1];
+  const version = match[2];
+  if (!key || !version)
+    return;
+  return { key, version };
+}
+
+// src/versioning/types.ts
+function isChangelogDocBlock(doc) {
+  return doc.kind === "changelog" && "specKey" in doc && "entries" in doc;
+}
+function isVersionBumpType(value) {
+  return value === "patch" || value === "minor" || value === "major";
+}
+function isChangeType(value) {
+  const validTypes = [
+    "added",
+    "changed",
+    "fixed",
+    "removed",
+    "deprecated",
+    "breaking",
+    "security"
+  ];
+  return typeof value === "string" && validTypes.includes(value);
+}
+
+// src/versioning/utils.ts
+var SEMVER_REGEX = /^(\d+)\.(\d+)\.(\d+)(?:-([a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*))?(?:\+([a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*))?$/;
+function parseVersion(version) {
+  const match = version.trim().match(SEMVER_REGEX);
+  if (!match) {
+    return null;
+  }
+  const majorStr = match[1];
+  const minorStr = match[2];
+  const patchStr = match[3];
+  const prerelease = match[4];
+  const build = match[5];
+  if (!majorStr || !minorStr || !patchStr) {
+    return null;
+  }
+  return {
+    major: parseInt(majorStr, 10),
+    minor: parseInt(minorStr, 10),
+    patch: parseInt(patchStr, 10),
+    ...prerelease && { prerelease },
+    ...build && { build }
+  };
+}
+function parseVersionStrict(version) {
+  const parsed = parseVersion(version);
+  if (!parsed) {
+    throw new Error(`Invalid semantic version: "${version}"`);
+  }
+  return parsed;
+}
+function formatVersion(version) {
+  let result = `${version.major}.${version.minor}.${version.patch}`;
+  if (version.prerelease) {
+    result += `-${version.prerelease}`;
+  }
+  if (version.build) {
+    result += `+${version.build}`;
+  }
+  return result;
+}
+function compareVersions(a, b) {
+  const versionA = parseVersionStrict(a);
+  const versionB = parseVersionStrict(b);
+  if (versionA.major !== versionB.major) {
+    return versionA.major > versionB.major ? 1 : -1;
+  }
+  if (versionA.minor !== versionB.minor) {
+    return versionA.minor > versionB.minor ? 1 : -1;
+  }
+  if (versionA.patch !== versionB.patch) {
+    return versionA.patch > versionB.patch ? 1 : -1;
+  }
+  if (versionA.prerelease && !versionB.prerelease) {
+    return -1;
+  }
+  if (!versionA.prerelease && versionB.prerelease) {
+    return 1;
+  }
+  if (versionA.prerelease && versionB.prerelease) {
+    return versionA.prerelease < versionB.prerelease ? -1 : versionA.prerelease > versionB.prerelease ? 1 : 0;
+  }
+  return 0;
+}
+function isVersionGreater(a, b) {
+  return compareVersions(a, b) === 1;
+}
+function isVersionLess(a, b) {
+  return compareVersions(a, b) === -1;
+}
+function isVersionEqual(a, b) {
+  return compareVersions(a, b) === 0;
+}
+function bumpVersion(current, bumpType) {
+  const version = parseVersionStrict(current);
+  switch (bumpType) {
+    case "major":
+      return formatVersion({
+        major: version.major + 1,
+        minor: 0,
+        patch: 0
+      });
+    case "minor":
+      return formatVersion({
+        major: version.major,
+        minor: version.minor + 1,
+        patch: 0
+      });
+    case "patch":
+      return formatVersion({
+        major: version.major,
+        minor: version.minor,
+        patch: version.patch + 1
+      });
+  }
+}
+function determineBumpType(hasBreaking, hasNonBreaking) {
+  if (hasBreaking) {
+    return "major";
+  }
+  if (hasNonBreaking) {
+    return "minor";
+  }
+  return "patch";
+}
+function getBumpTypePriority(bumpType) {
+  switch (bumpType) {
+    case "major":
+      return 3;
+    case "minor":
+      return 2;
+    case "patch":
+      return 1;
+  }
+}
+function getMaxBumpType(bumpTypes) {
+  if (bumpTypes.length === 0) {
+    return null;
+  }
+  return bumpTypes.reduce((max, current) => getBumpTypePriority(current) > getBumpTypePriority(max) ? current : max);
+}
+function isValidVersion(version) {
+  return parseVersion(version) !== null;
+}
+function validateVersion(version) {
+  const errors = [];
+  if (!version || typeof version !== "string") {
+    errors.push("Version must be a non-empty string");
+    return errors;
+  }
+  const trimmed = version.trim();
+  if (trimmed !== version) {
+    errors.push("Version should not have leading or trailing whitespace");
+  }
+  if (!parseVersion(trimmed)) {
+    errors.push(`Invalid semantic version format: "${version}". Expected format: MAJOR.MINOR.PATCH[-prerelease][+build]`);
+  }
+  return errors;
+}
+export {
+  validateVersion,
+  parseVersionedRefKey,
+  parseVersionStrict,
+  parseVersion,
+  isVersionedSpecRef,
+  isVersionLess,
+  isVersionGreater,
+  isVersionEqual,
+  isVersionBumpType,
+  isValidVersion,
+  isSpecKeyRef,
+  isOptionalVersionedSpecRef,
+  isChangelogDocBlock,
+  isChangeType,
+  getMaxBumpType,
+  getBumpTypePriority,
+  formatVersionedRefKey,
+  formatVersion,
+  determineBumpType,
+  createVersionedRef,
+  createOptionalRef,
+  createKeyRef,
+  compareVersions,
+  bumpVersion
+};

package/dist/versioning/refs.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Base reference types for ContractSpec versioning.
+ *
+ * Provides canonical reference types for linking between specs.
+ * Domain-specific refs (OpRef, EventRef, etc.) should alias these
+ * base types for consistency and maintainability.
+ *
+ * @module versioning/refs
+ */
+/**
+ * Base reference type for versioned specs.
+ * Used to reference any spec by its key and version.
+ *
+ * @example
+ * ```typescript
+ * const opRef: VersionedSpecRef = { key: 'auth.login', version: '1.0.0' };
+ * ```
+ */
+export interface VersionedSpecRef {
+    /** Unique key identifying the spec (e.g., "auth.login", "user.created"). */
+    key: string;
+    /** Semantic version of the spec (e.g., "1.0.0", "2.1.0"). */
+    version: string;
+}
+/**
+ * Base reference type for specs with optional version.
+ * When version is omitted, typically refers to the latest version.
+ *
+ * @example
+ * ```typescript
+ * // Reference to latest version
+ * const latestRef: OptionalVersionedSpecRef = { key: 'auth.login' };
+ *
+ * // Reference to specific version
+ * const specificRef: OptionalVersionedSpecRef = { key: 'auth.login', version: '1.0.0' };
+ * ```
+ */
+export interface OptionalVersionedSpecRef {
+    /** Unique key identifying the spec. */
+    key: string;
+    /** Optional semantic version. When omitted, refers to the latest version. */
+    version?: string;
+}
+/**
+ * Base reference type for unversioned spec keys.
+ * Used when only the key is needed without version information.
+ *
+ * @example
+ * ```typescript
+ * const featureRef: SpecKeyRef = { key: 'premium-features' };
+ * ```
+ */
+export interface SpecKeyRef {
+    /** Unique key identifying the spec. */
+    key: string;
+}
+/**
+ * Checks if a value is a valid VersionedSpecRef.
+ *
+ * @param ref - The value to check
+ * @returns True if the value has both key and version as strings
+ *
+ * @example
+ * ```typescript
+ * const ref = { key: 'auth.login', version: '1.0.0' };
+ * if (isVersionedSpecRef(ref)) {
+ *   console.log(`Spec: ${ref.key}@${ref.version}`);
+ * }
+ * ```
+ */
+export declare function isVersionedSpecRef(ref: unknown): ref is VersionedSpecRef;
+/**
+ * Checks if a value is a valid OptionalVersionedSpecRef.
+ *
+ * @param ref - The value to check
+ * @returns True if the value has a key string and optional version string
+ *
+ * @example
+ * ```typescript
+ * const ref = { key: 'auth.login' };
+ * if (isOptionalVersionedSpecRef(ref)) {
+ *   console.log(`Spec: ${ref.key}${ref.version ? `@${ref.version}` : ''}`);
+ * }
+ * ```
+ */
+export declare function isOptionalVersionedSpecRef(ref: unknown): ref is OptionalVersionedSpecRef;
+/**
+ * Checks if a value is a valid SpecKeyRef.
+ *
+ * @param ref - The value to check
+ * @returns True if the value has a key string
+ *
+ * @example
+ * ```typescript
+ * const ref = { key: 'premium-features' };
+ * if (isSpecKeyRef(ref)) {
+ *   console.log(`Feature: ${ref.key}`);
+ * }
+ * ```
+ */
+export declare function isSpecKeyRef(ref: unknown): ref is SpecKeyRef;
+/**
+ * Creates a versioned spec reference.
+ *
+ * @param key - The spec key (e.g., "auth.login")
+ * @param version - The semantic version (e.g., "1.0.0")
+ * @returns A VersionedSpecRef object
+ * @throws {Error} If key or version is empty
+ *
+ * @example
+ * ```typescript
+ * const ref = createVersionedRef('auth.login', '1.0.0');
+ * // { key: 'auth.login', version: '1.0.0' }
+ * ```
+ */
+export declare function createVersionedRef(key: string, version: string): VersionedSpecRef;
+/**
+ * Creates an optional versioned spec reference.
+ *
+ * @param key - The spec key (e.g., "auth.login")
+ * @param version - Optional semantic version
+ * @returns An OptionalVersionedSpecRef object
+ * @throws {Error} If key is empty
+ *
+ * @example
+ * ```typescript
+ * // Reference to latest version
+ * const latestRef = createOptionalRef('auth.login');
+ * // { key: 'auth.login' }
+ *
+ * // Reference to specific version
+ * const specificRef = createOptionalRef('auth.login', '1.0.0');
+ * // { key: 'auth.login', version: '1.0.0' }
+ * ```
+ */
+export declare function createOptionalRef(key: string, version?: string): OptionalVersionedSpecRef;
+/**
+ * Creates a spec key reference.
+ *
+ * @param key - The spec key (e.g., "premium-features")
+ * @returns A SpecKeyRef object
+ * @throws {Error} If key is empty
+ *
+ * @example
+ * ```typescript
+ * const ref = createKeyRef('premium-features');
+ * // { key: 'premium-features' }
+ * ```
+ */
+export declare function createKeyRef(key: string): SpecKeyRef;
+/**
+ * Formats a versioned ref as a string key.
+ *
+ * @param ref - The versioned spec reference
+ * @returns A string in the format "key.vversion"
+ *
+ * @example
+ * ```typescript
+ * const str = formatVersionedRefKey({ key: 'auth.login', version: '1.0.0' });
+ * // "auth.login.v1.0.0"
+ * ```
+ */
+export declare function formatVersionedRefKey(ref: VersionedSpecRef): string;
+/**
+ * Parses a versioned ref string back into a ref object.
+ *
+ * @param refKey - A string in the format "key.vversion"
+ * @returns A VersionedSpecRef or undefined if parsing fails
+ *
+ * @example
+ * ```typescript
+ * const ref = parseVersionedRefKey('auth.login.v1.0.0');
+ * // { key: 'auth.login', version: '1.0.0' }
+ * ```
+ */
+export declare function parseVersionedRefKey(refKey: string): VersionedSpecRef | undefined;

package/dist/versioning/refs.js

@@ -0,0 +1,99 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/versioning/refs.ts
+function isVersionedSpecRef(ref) {
+  return typeof ref === "object" && ref !== null && "key" in ref && typeof ref.key === "string" && ref.key.length > 0 && "version" in ref && typeof ref.version === "string" && ref.version.length > 0;
+}
+function isOptionalVersionedSpecRef(ref) {
+  if (typeof ref !== "object" || ref === null)
+    return false;
+  if (!("key" in ref))
+    return false;
+  if (typeof ref.key !== "string" || ref.key.length === 0) {
+    return false;
+  }
+  if ("version" in ref && ref.version != null) {
+    return typeof ref.version === "string";
+  }
+  return true;
+}
+function isSpecKeyRef(ref) {
+  return typeof ref === "object" && ref !== null && "key" in ref && typeof ref.key === "string" && ref.key.length > 0;
+}
+function createVersionedRef(key, version) {
+  if (!key || key.trim().length === 0) {
+    throw new Error("Spec key cannot be empty");
+  }
+  if (!version || version.trim().length === 0) {
+    throw new Error("Spec version cannot be empty");
+  }
+  return { key: key.trim(), version: version.trim() };
+}
+function createOptionalRef(key, version) {
+  if (!key || key.trim().length === 0) {
+    throw new Error("Spec key cannot be empty");
+  }
+  const ref = { key: key.trim() };
+  if (version != null && version.trim().length > 0) {
+    ref.version = version.trim();
+  }
+  return ref;
+}
+function createKeyRef(key) {
+  if (!key || key.trim().length === 0) {
+    throw new Error("Spec key cannot be empty");
+  }
+  return { key: key.trim() };
+}
+function formatVersionedRefKey(ref) {
+  return `${ref.key}.v${ref.version}`;
+}
+function parseVersionedRefKey(refKey) {
+  const match = refKey.match(/^(.+)\.v(\d+\.\d+\.\d+(?:-.+)?)$/);
+  if (!match)
+    return;
+  const key = match[1];
+  const version = match[2];
+  if (!key || !version)
+    return;
+  return { key, version };
+}
+export {
+  parseVersionedRefKey,
+  isVersionedSpecRef,
+  isSpecKeyRef,
+  isOptionalVersionedSpecRef,
+  formatVersionedRefKey,
+  createVersionedRef,
+  createOptionalRef,
+  createKeyRef
+};

package/dist/versioning/refs.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for versioning reference types and utilities.
+ */
+export {};

package/dist/versioning/types.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Versioning types for ContractSpec changelog and version management.
+ *
+ * Supports three-tier changelogs:
+ * - Per-spec: ChangelogDocBlock entries
+ * - Per-library: Package CHANGELOG.md files
+ * - Per-monorepo: Root CHANGELOG.md
+ */
+import type { DocBlock } from '../docs/types';
+/** Version bump type based on semantic versioning */
+export type VersionBumpType = 'patch' | 'minor' | 'major';
+/** Semantic version components */
+export interface SemanticVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease?: string;
+    build?: string;
+}
+/** Type of change for changelog entries */
+export type ChangeType = 'added' | 'changed' | 'fixed' | 'removed' | 'deprecated' | 'breaking' | 'security';
+/** Individual change entry */
+export interface ChangeEntry {
+    /** Type of change */
+    type: ChangeType;
+    /** Human-readable description of the change */
+    description: string;
+    /** Schema/code path changed (e.g., "io.input.email", "meta.stability") */
+    path?: string;
+    /** Related issue/ticket reference (e.g., "GH-123", "JIRA-456") */
+    issueRef?: string;
+    /** Git commit SHA for traceability */
+    commitSha?: string;
+    /** Author of the change */
+    author?: string;
+}
+/** Changelog entry for a specific version */
+export interface ChangelogEntry {
+    /** Version number (semver format) */
+    version: string;
+    /** Release date (ISO 8601 format) */
+    date: string;
+    /** Type of version bump that led to this version */
+    bumpType: VersionBumpType;
+    /** List of changes in this version */
+    changes: ChangeEntry[];
+    /** Breaking changes (subset for emphasis) */
+    breakingChanges?: ChangeEntry[];
+    /** Deprecation notices */
+    deprecations?: ChangeEntry[];
+    /** Contributors to this version */
+    contributors?: string[];
+    /** Release notes summary */
+    summary?: string;
+}
+/** DocBlock extension for per-spec changelogs */
+export interface ChangelogDocBlock extends DocBlock {
+    /** Changelog-specific kind */
+    kind: 'changelog';
+    /** Related spec key (e.g., "auth.beginSignup") */
+    specKey: string;
+    /** Current spec version */
+    specVersion: string;
+    /** Changelog entries for this spec */
+    entries: ChangelogEntry[];
+}
+/** Result of version analysis for a single spec */
+export interface VersionAnalysis {
+    /** Path to the spec file */
+    specPath: string;
+    /** Spec key (e.g., "auth.login") */
+    specKey: string;
+    /** Current version in the spec */
+    currentVersion: string;
+    /** Suggested new version based on changes */
+    suggestedVersion: string;
+    /** Suggested bump type */
+    bumpType: VersionBumpType;
+    /** Detected changes requiring version bump */
+    changes: ChangeEntry[];
+    /** Whether breaking changes were detected */
+    hasBreaking: boolean;
+}
+/** Aggregated version analysis result */
+export interface VersionAnalysisResult {
+    /** Individual spec analyses */
+    analyses: VersionAnalysis[];
+    /** Total specs analyzed */
+    totalSpecs: number;
+    /** Specs needing version bump */
+    specsNeedingBump: number;
+    /** Total breaking changes across all specs */
+    totalBreaking: number;
+    /** Git baseline used for comparison */
+    baseline?: string;
+}
+/** Result of changelog generation */
+export interface ChangelogResult {
+    /** Per-spec DocBlock entries */
+    specChangelogs: ChangelogDocBlock[];
+    /** Library-level markdown by package path */
+    libraryMarkdown: Map<string, string>;
+    /** Monorepo-level markdown */
+    monorepoMarkdown: string;
+    /** JSON format for programmatic use */
+    json: ChangelogJsonExport;
+}
+/** JSON export format for changelogs */
+export interface ChangelogJsonExport {
+    generatedAt: string;
+    baseline?: string;
+    specs: {
+        key: string;
+        version: string;
+        path: string;
+        entries: ChangelogEntry[];
+    }[];
+    libraries: {
+        name: string;
+        path: string;
+        version: string;
+        entries: ChangelogEntry[];
+    }[];
+}
+/** Check if a DocBlock is a ChangelogDocBlock */
+export declare function isChangelogDocBlock(doc: DocBlock): doc is ChangelogDocBlock;
+/** Check if a string is a valid VersionBumpType */
+export declare function isVersionBumpType(value: unknown): value is VersionBumpType;
+/** Check if a string is a valid ChangeType */
+export declare function isChangeType(value: unknown): value is ChangeType;