@contractspec/lib.contracts 1.45.2 → 1.45.3

package/dist/onboarding-base.d.ts

@@ -1,136 +1,136 @@
 import { OperationSpec } from "./operations/operation.js";
 import "./index.js";
-import * as _contractspec_lib_schema0 from "@contractspec/lib.schema";
+import * as _contractspec_lib_schema118 from "@contractspec/lib.schema";
 import { SchemaModel } from "@contractspec/lib.schema";
 
 //#region src/onboarding-base.d.ts
 /** Save/update onboarding draft (auto-save during flow) */
 declare const SaveOnboardingDraftInput: SchemaModel<{
   data: {
-    type: _contractspec_lib_schema0.FieldType<unknown, unknown>;
+    type: _contractspec_lib_schema118.FieldType<unknown, unknown>;
     isOptional: false;
   };
 }>;
 declare const SaveOnboardingDraftOutput: SchemaModel<{
   id: {
-    type: _contractspec_lib_schema0.FieldType<string, string>;
+    type: _contractspec_lib_schema118.FieldType<string, string>;
     isOptional: false;
   };
   organizationId: {
-    type: _contractspec_lib_schema0.FieldType<string, string>;
+    type: _contractspec_lib_schema118.FieldType<string, string>;
     isOptional: false;
   };
 }>;
 declare const SaveOnboardingDraftBaseSpec: OperationSpec<SchemaModel<{
   data: {
-    type: _contractspec_lib_schema0.FieldType<unknown, unknown>;
+    type: _contractspec_lib_schema118.FieldType<unknown, unknown>;
     isOptional: false;
   };
 }>, SchemaModel<{
   id: {
-    type: _contractspec_lib_schema0.FieldType<string, string>;
+    type: _contractspec_lib_schema118.FieldType<string, string>;
     isOptional: false;
   };
   organizationId: {
-    type: _contractspec_lib_schema0.FieldType<string, string>;
+    type: _contractspec_lib_schema118.FieldType<string, string>;
     isOptional: false;
   };
 }>, undefined>;
 /** Get current onboarding draft (on mount/restore) */
 declare const GetOnboardingDraftOutput: SchemaModel<{
   id: {
-    type: _contractspec_lib_schema0.FieldType<string, string>;
+    type: _contractspec_lib_schema118.FieldType<string, string>;
     isOptional: true;
   };
   organizationId: {
-    type: _contractspec_lib_schema0.FieldType<string, string>;
+    type: _contractspec_lib_schema118.FieldType<string, string>;
     isOptional: true;
   };
   data: {
-    type: _contractspec_lib_schema0.FieldType<unknown, unknown>;
+    type: _contractspec_lib_schema118.FieldType<unknown, unknown>;
     isOptional: true;
   };
   createdAt: {
-    type: _contractspec_lib_schema0.FieldType<Date, string>;
+    type: _contractspec_lib_schema118.FieldType<Date, string>;
     isOptional: true;
   };
   updatedAt: {
-    type: _contractspec_lib_schema0.FieldType<Date, string>;
+    type: _contractspec_lib_schema118.FieldType<Date, string>;
     isOptional: true;
   };
 }>;
-declare const GetOnboardingDraftBaseSpec: OperationSpec<_contractspec_lib_schema0.AnySchemaModel, SchemaModel<{
+declare const GetOnboardingDraftBaseSpec: OperationSpec<_contractspec_lib_schema118.AnySchemaModel, SchemaModel<{
   id: {
-    type: _contractspec_lib_schema0.FieldType<string, string>;
+    type: _contractspec_lib_schema118.FieldType<string, string>;
     isOptional: true;
   };
   organizationId: {
-    type: _contractspec_lib_schema0.FieldType<string, string>;
+    type: _contractspec_lib_schema118.FieldType<string, string>;
     isOptional: true;
   };
   data: {
-    type: _contractspec_lib_schema0.FieldType<unknown, unknown>;
+    type: _contractspec_lib_schema118.FieldType<unknown, unknown>;
     isOptional: true;
   };
   createdAt: {
-    type: _contractspec_lib_schema0.FieldType<Date, string>;
+    type: _contractspec_lib_schema118.FieldType<Date, string>;
     isOptional: true;
   };
   updatedAt: {
-    type: _contractspec_lib_schema0.FieldType<Date, string>;
+    type: _contractspec_lib_schema118.FieldType<Date, string>;
     isOptional: true;
   };
 }>, undefined>;
 /** Delete onboarding draft (cleanup after completion or cancel) */
 declare const DeleteOnboardingDraftOutput: SchemaModel<{
   ok: {
-    type: _contractspec_lib_schema0.FieldType<boolean, boolean>;
+    type: _contractspec_lib_schema118.FieldType<boolean, boolean>;
     isOptional: false;
   };
 }>;
-declare const DeleteOnboardingDraftBaseSpec: OperationSpec<_contractspec_lib_schema0.AnySchemaModel, SchemaModel<{
+declare const DeleteOnboardingDraftBaseSpec: OperationSpec<_contractspec_lib_schema118.AnySchemaModel, SchemaModel<{
   ok: {
-    type: _contractspec_lib_schema0.FieldType<boolean, boolean>;
+    type: _contractspec_lib_schema118.FieldType<boolean, boolean>;
     isOptional: false;
   };
 }>, undefined>;
 /** Complete onboarding (final submit, creates entities) */
 declare const CompleteOnboardingBaseInput: SchemaModel<{
   data: {
-    type: _contractspec_lib_schema0.FieldType<unknown, unknown>;
+    type: _contractspec_lib_schema118.FieldType<unknown, unknown>;
     isOptional: false;
   };
 }>;
 declare const CompleteOnboardingBaseOutput: SchemaModel<{
   success: {
-    type: _contractspec_lib_schema0.FieldType<boolean, boolean>;
+    type: _contractspec_lib_schema118.FieldType<boolean, boolean>;
     isOptional: false;
   };
   userId: {
-    type: _contractspec_lib_schema0.FieldType<string, string>;
+    type: _contractspec_lib_schema118.FieldType<string, string>;
     isOptional: true;
   };
   organizationId: {
-    type: _contractspec_lib_schema0.FieldType<string, string>;
+    type: _contractspec_lib_schema118.FieldType<string, string>;
     isOptional: true;
   };
 }>;
 declare const CompleteOnboardingBaseSpec: OperationSpec<SchemaModel<{
   data: {
-    type: _contractspec_lib_schema0.FieldType<unknown, unknown>;
+    type: _contractspec_lib_schema118.FieldType<unknown, unknown>;
     isOptional: false;
   };
 }>, SchemaModel<{
   success: {
-    type: _contractspec_lib_schema0.FieldType<boolean, boolean>;
+    type: _contractspec_lib_schema118.FieldType<boolean, boolean>;
     isOptional: false;
   };
   userId: {
-    type: _contractspec_lib_schema0.FieldType<string, string>;
+    type: _contractspec_lib_schema118.FieldType<string, string>;
     isOptional: true;
   };
   organizationId: {
-    type: _contractspec_lib_schema0.FieldType<string, string>;
+    type: _contractspec_lib_schema118.FieldType<string, string>;
     isOptional: true;
   };
 }>, undefined>;

package/dist/versioning/index.d.ts

@@ -0,0 +1,3 @@
+import { ChangeEntry, ChangeType, ChangelogDocBlock, ChangelogEntry, ChangelogJsonExport, ChangelogResult, SemanticVersion, VersionAnalysis, VersionAnalysisResult, VersionBumpType, isChangeType, isChangelogDocBlock, isVersionBumpType } from "./types.js";
+import { bumpVersion, compareVersions, determineBumpType, formatVersion, getBumpTypePriority, getMaxBumpType, isValidVersion, isVersionEqual, isVersionGreater, isVersionLess, parseVersion, parseVersionStrict, validateVersion } from "./utils.js";
+export { ChangeEntry, ChangeType, ChangelogDocBlock, ChangelogEntry, ChangelogJsonExport, ChangelogResult, SemanticVersion, VersionAnalysis, VersionAnalysisResult, VersionBumpType, bumpVersion, compareVersions, determineBumpType, formatVersion, getBumpTypePriority, getMaxBumpType, isChangeType, isChangelogDocBlock, isValidVersion, isVersionBumpType, isVersionEqual, isVersionGreater, isVersionLess, parseVersion, parseVersionStrict, validateVersion };

package/dist/versioning/index.js

@@ -0,0 +1,4 @@
+import { isChangeType, isChangelogDocBlock, isVersionBumpType } from "./types.js";
+import { bumpVersion, compareVersions, determineBumpType, formatVersion, getBumpTypePriority, getMaxBumpType, isValidVersion, isVersionEqual, isVersionGreater, isVersionLess, parseVersion, parseVersionStrict, validateVersion } from "./utils.js";
+
+export { bumpVersion, compareVersions, determineBumpType, formatVersion, getBumpTypePriority, getMaxBumpType, isChangeType, isChangelogDocBlock, isValidVersion, isVersionBumpType, isVersionEqual, isVersionGreater, isVersionLess, parseVersion, parseVersionStrict, validateVersion };

package/dist/versioning/types.d.ts

@@ -0,0 +1,127 @@
+import { DocBlock } from "../docs/types.js";
+
+//#region src/versioning/types.d.ts
+
+/** Version bump type based on semantic versioning */
+type VersionBumpType = 'patch' | 'minor' | 'major';
+/** Semantic version components */
+interface SemanticVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease?: string;
+  build?: string;
+}
+/** Type of change for changelog entries */
+type ChangeType = 'added' | 'changed' | 'fixed' | 'removed' | 'deprecated' | 'breaking' | 'security';
+/** Individual change entry */
+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 */
+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 */
+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 */
+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 */
+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 */
+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 */
+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 */
+declare function isChangelogDocBlock(doc: DocBlock): doc is ChangelogDocBlock;
+/** Check if a string is a valid VersionBumpType */
+declare function isVersionBumpType(value: unknown): value is VersionBumpType;
+/** Check if a string is a valid ChangeType */
+declare function isChangeType(value: unknown): value is ChangeType;
+//#endregion
+export { ChangeEntry, ChangeType, ChangelogDocBlock, ChangelogEntry, ChangelogJsonExport, ChangelogResult, SemanticVersion, VersionAnalysis, VersionAnalysisResult, VersionBumpType, isChangeType, isChangelogDocBlock, isVersionBumpType };

package/dist/versioning/types.js

@@ -0,0 +1,24 @@
+//#region src/versioning/types.ts
+/** Check if a DocBlock is a ChangelogDocBlock */
+function isChangelogDocBlock(doc) {
+	return doc.kind === "changelog" && "specKey" in doc && "entries" in doc;
+}
+/** Check if a string is a valid VersionBumpType */
+function isVersionBumpType(value) {
+	return value === "patch" || value === "minor" || value === "major";
+}
+/** Check if a string is a valid ChangeType */
+function isChangeType(value) {
+	return typeof value === "string" && [
+		"added",
+		"changed",
+		"fixed",
+		"removed",
+		"deprecated",
+		"breaking",
+		"security"
+	].includes(value);
+}
+
+//#endregion
+export { isChangeType, isChangelogDocBlock, isVersionBumpType };

package/dist/versioning/utils.d.ts

@@ -0,0 +1,95 @@
+import { SemanticVersion, VersionBumpType } from "./types.js";
+
+//#region src/versioning/utils.d.ts
+
+/**
+ * Parse a semantic version string into components.
+ *
+ * @param version - Version string (e.g., "1.2.3", "1.0.0-alpha.1")
+ * @returns Parsed SemanticVersion or null if invalid
+ *
+ * @example
+ * parseVersion("1.2.3") // { major: 1, minor: 2, patch: 3 }
+ * parseVersion("2.0.0-beta.1") // { major: 2, minor: 0, patch: 0, prerelease: "beta.1" }
+ */
+declare function parseVersion(version: string): SemanticVersion | null;
+/**
+ * Strictly parse a version, throwing on invalid input.
+ *
+ * @throws Error if version is not valid semver
+ */
+declare function parseVersionStrict(version: string): SemanticVersion;
+/**
+ * Format a SemanticVersion back to string.
+ *
+ * @example
+ * formatVersion({ major: 1, minor: 2, patch: 3 }) // "1.2.3"
+ * formatVersion({ major: 2, minor: 0, patch: 0, prerelease: "beta.1" }) // "2.0.0-beta.1"
+ */
+declare function formatVersion(version: SemanticVersion): string;
+/**
+ * Compare two version strings.
+ *
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ *
+ * @example
+ * compareVersions("1.0.0", "2.0.0") // -1
+ * compareVersions("1.2.3", "1.2.3") // 0
+ * compareVersions("2.0.0", "1.9.9") // 1
+ */
+declare function compareVersions(a: string, b: string): -1 | 0 | 1;
+/**
+ * Check if version a is greater than version b.
+ */
+declare function isVersionGreater(a: string, b: string): boolean;
+/**
+ * Check if version a is less than version b.
+ */
+declare function isVersionLess(a: string, b: string): boolean;
+/**
+ * Check if two versions are equal.
+ */
+declare function isVersionEqual(a: string, b: string): boolean;
+/**
+ * Bump a version by the specified type.
+ *
+ * @param current - Current version string
+ * @param bumpType - Type of bump: 'patch', 'minor', or 'major'
+ * @returns New version string
+ *
+ * @example
+ * bumpVersion("1.2.3", "patch") // "1.2.4"
+ * bumpVersion("1.2.3", "minor") // "1.3.0"
+ * bumpVersion("1.2.3", "major") // "2.0.0"
+ */
+declare function bumpVersion(current: string, bumpType: VersionBumpType): string;
+/**
+ * Determine the appropriate version bump type based on change impact.
+ *
+ * - Breaking changes → major
+ * - Non-breaking additions/changes → minor
+ * - Fixes only → patch
+ *
+ * @param hasBreaking - Whether breaking changes were detected
+ * @param hasNonBreaking - Whether non-breaking changes (additions, changes) were detected
+ * @returns Appropriate bump type
+ */
+declare function determineBumpType(hasBreaking: boolean, hasNonBreaking: boolean): VersionBumpType;
+/**
+ * Get sort priority for bump types (higher = more significant).
+ */
+declare function getBumpTypePriority(bumpType: VersionBumpType): number;
+/**
+ * Get the most significant bump type from a list.
+ */
+declare function getMaxBumpType(bumpTypes: VersionBumpType[]): VersionBumpType | null;
+/**
+ * Check if a string is a valid semantic version.
+ */
+declare function isValidVersion(version: string): boolean;
+/**
+ * Validate a version string, returning validation errors.
+ */
+declare function validateVersion(version: string): string[];
+//#endregion
+export { bumpVersion, compareVersions, determineBumpType, formatVersion, getBumpTypePriority, getMaxBumpType, isValidVersion, isVersionEqual, isVersionGreater, isVersionLess, parseVersion, parseVersionStrict, validateVersion };

package/dist/versioning/utils.js

@@ -0,0 +1,180 @@
+//#region src/versioning/utils.ts
+/** Regex for parsing semantic versions */
+const SEMVER_REGEX = /^(\d+)\.(\d+)\.(\d+)(?:-([a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*))?(?:\+([a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*))?$/;
+/**
+* Parse a semantic version string into components.
+*
+* @param version - Version string (e.g., "1.2.3", "1.0.0-alpha.1")
+* @returns Parsed SemanticVersion or null if invalid
+*
+* @example
+* parseVersion("1.2.3") // { major: 1, minor: 2, patch: 3 }
+* parseVersion("2.0.0-beta.1") // { major: 2, minor: 0, patch: 0, prerelease: "beta.1" }
+*/
+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 }
+	};
+}
+/**
+* Strictly parse a version, throwing on invalid input.
+*
+* @throws Error if version is not valid semver
+*/
+function parseVersionStrict(version) {
+	const parsed = parseVersion(version);
+	if (!parsed) throw new Error(`Invalid semantic version: "${version}"`);
+	return parsed;
+}
+/**
+* Format a SemanticVersion back to string.
+*
+* @example
+* formatVersion({ major: 1, minor: 2, patch: 3 }) // "1.2.3"
+* formatVersion({ major: 2, minor: 0, patch: 0, prerelease: "beta.1" }) // "2.0.0-beta.1"
+*/
+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;
+}
+/**
+* Compare two version strings.
+*
+* @returns -1 if a < b, 0 if a === b, 1 if a > b
+*
+* @example
+* compareVersions("1.0.0", "2.0.0") // -1
+* compareVersions("1.2.3", "1.2.3") // 0
+* compareVersions("2.0.0", "1.9.9") // 1
+*/
+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;
+}
+/**
+* Check if version a is greater than version b.
+*/
+function isVersionGreater(a, b) {
+	return compareVersions(a, b) === 1;
+}
+/**
+* Check if version a is less than version b.
+*/
+function isVersionLess(a, b) {
+	return compareVersions(a, b) === -1;
+}
+/**
+* Check if two versions are equal.
+*/
+function isVersionEqual(a, b) {
+	return compareVersions(a, b) === 0;
+}
+/**
+* Bump a version by the specified type.
+*
+* @param current - Current version string
+* @param bumpType - Type of bump: 'patch', 'minor', or 'major'
+* @returns New version string
+*
+* @example
+* bumpVersion("1.2.3", "patch") // "1.2.4"
+* bumpVersion("1.2.3", "minor") // "1.3.0"
+* bumpVersion("1.2.3", "major") // "2.0.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
+		});
+	}
+}
+/**
+* Determine the appropriate version bump type based on change impact.
+*
+* - Breaking changes → major
+* - Non-breaking additions/changes → minor
+* - Fixes only → patch
+*
+* @param hasBreaking - Whether breaking changes were detected
+* @param hasNonBreaking - Whether non-breaking changes (additions, changes) were detected
+* @returns Appropriate bump type
+*/
+function determineBumpType(hasBreaking, hasNonBreaking) {
+	if (hasBreaking) return "major";
+	if (hasNonBreaking) return "minor";
+	return "patch";
+}
+/**
+* Get sort priority for bump types (higher = more significant).
+*/
+function getBumpTypePriority(bumpType) {
+	switch (bumpType) {
+		case "major": return 3;
+		case "minor": return 2;
+		case "patch": return 1;
+	}
+}
+/**
+* Get the most significant bump type from a list.
+*/
+function getMaxBumpType(bumpTypes) {
+	if (bumpTypes.length === 0) return null;
+	return bumpTypes.reduce((max, current) => getBumpTypePriority(current) > getBumpTypePriority(max) ? current : max);
+}
+/**
+* Check if a string is a valid semantic version.
+*/
+function isValidVersion(version) {
+	return parseVersion(version) !== null;
+}
+/**
+* Validate a version string, returning validation errors.
+*/
+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;
+}
+
+//#endregion
+export { bumpVersion, compareVersions, determineBumpType, formatVersion, getBumpTypePriority, getMaxBumpType, isValidVersion, isVersionEqual, isVersionGreater, isVersionLess, parseVersion, parseVersionStrict, validateVersion };