@contractual/differs.json-schema 0.1.0-dev.0

package/dist/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../src/compare.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,oBAAoB,EAG1B,MAAM,YAAY,CAAC;AAKpB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,OAAO,EACrB,YAAY,EAAE,OAAO,EACrB,OAAO,CAAC,EAAE,cAAc,GACvB,aAAa,CAuDf;AA0KD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,OAAO,EACrB,YAAY,EAAE,OAAO,GACpB,oBAAoB,CAetB"}

package/dist/compare.js

@@ -0,0 +1,232 @@
+/**
+ * Strands-compatible JSON Schema comparison API
+ *
+ * Provides schema comparison with output format matching the Strands API
+ * (https://strands.octue.com/api/compare-schemas)
+ */
+import { resolveRefs } from './ref-resolver.js';
+import { walk } from './walker.js';
+import { classify, classifyPropertyAdded } from './classifiers.js';
+/**
+ * Compare two JSON Schema objects and return Strands-compatible result
+ *
+ * @param sourceSchema - The source (old/baseline) schema object
+ * @param targetSchema - The target (new/current) schema object
+ * @param options - Optional comparison options
+ * @returns CompareResult in Strands API format
+ *
+ * @example
+ * ```typescript
+ * const source = { type: 'object', properties: { name: { type: 'string' } } };
+ * const target = { type: 'object', properties: { name: { type: 'number' } } };
+ *
+ * const result = compareSchemas(source, target, { currentVersion: '1.0.0' });
+ * console.log(result.version);    // 'major'
+ * console.log(result.newVersion); // { major: 2, minor: 0, patch: 0, version: '2.0.0' }
+ * ```
+ */
+export function compareSchemas(sourceSchema, targetSchema, options) {
+    // Resolve $refs in both schemas
+    const resolvedSourceResult = resolveRefs(sourceSchema);
+    const resolvedTargetResult = resolveRefs(targetSchema);
+    const resolvedSource = resolvedSourceResult.schema;
+    const resolvedTarget = resolvedTargetResult.schema;
+    // Walk both schemas and detect raw changes
+    const rawChanges = walk(resolvedSource, resolvedTarget, '');
+    // Classify changes and generate traces
+    const traces = [];
+    let hasBreaking = false;
+    let hasNonBreaking = false;
+    let hasPatch = false;
+    let hasUnknown = false;
+    for (const raw of rawChanges) {
+        const severity = classifyChange(raw, resolvedTarget);
+        // Track highest severity
+        switch (severity) {
+            case 'breaking':
+                hasBreaking = true;
+                break;
+            case 'non-breaking':
+                hasNonBreaking = true;
+                break;
+            case 'patch':
+                hasPatch = true;
+                break;
+            case 'unknown':
+                hasUnknown = true;
+                break;
+        }
+        // Generate trace
+        const trace = rawChangeToTrace(raw, severity);
+        traces.push(trace);
+    }
+    // Determine version bump
+    const version = determineVersion(hasBreaking, hasNonBreaking, hasPatch, hasUnknown, traces);
+    // Compute new version if current version provided
+    const newVersion = options?.currentVersion
+        ? computeNewVersion(options.currentVersion, version)
+        : null;
+    return {
+        version,
+        traces,
+        newVersion,
+    };
+}
+/**
+ * Classify a change, with context-aware classification for property-added
+ */
+function classifyChange(change, newSchema) {
+    if (change.type === 'property-added') {
+        return classifyPropertyAdded(change, newSchema);
+    }
+    return classify(change);
+}
+/**
+ * Convert a RawChange to a Strands trace
+ */
+function rawChangeToTrace(change, severity) {
+    const compatibility = severityToCompatibility(severity);
+    // Determine left/right paths based on change type
+    const isAddition = change.type.includes('added') ||
+        change.type === 'type-widened' ||
+        change.type === 'constraint-loosened';
+    const isRemoval = change.type.includes('removed') ||
+        change.type === 'type-narrowed' ||
+        change.type === 'constraint-tightened';
+    let left = change.path;
+    let right = change.path;
+    // For additions, left is null (didn't exist in source)
+    if (isAddition && change.oldValue === undefined) {
+        left = null;
+    }
+    // For removals, right is null (doesn't exist in target)
+    if (isRemoval && change.newValue === undefined) {
+        right = null;
+    }
+    return {
+        compatibility,
+        left,
+        right,
+    };
+}
+/**
+ * Map ChangeSeverity to Strands compatibility
+ */
+function severityToCompatibility(severity) {
+    switch (severity) {
+        case 'breaking':
+            return 'incompatible';
+        case 'non-breaking':
+        case 'patch':
+            return 'compatible';
+        case 'unknown':
+        default:
+            return 'unknown';
+    }
+}
+/**
+ * Determine the version bump level based on detected changes
+ */
+function determineVersion(hasBreaking, hasNonBreaking, hasPatch, hasUnknown, traces) {
+    // No changes = equal
+    if (traces.length === 0) {
+        return 'equal';
+    }
+    // If there are unknown changes, we can't determine version
+    if (hasUnknown && !hasBreaking && !hasNonBreaking) {
+        return null;
+    }
+    // Priority: breaking > non-breaking > patch
+    if (hasBreaking) {
+        return 'major';
+    }
+    if (hasNonBreaking) {
+        return 'minor';
+    }
+    if (hasPatch) {
+        return 'patch';
+    }
+    // Only unknown changes
+    return null;
+}
+/**
+ * Compute the new semantic version based on current version and bump level
+ */
+function computeNewVersion(currentVersion, bumpLevel) {
+    if (bumpLevel === null || bumpLevel === 'equal') {
+        // Parse current version and return as-is for equal
+        const parsed = parseVersion(currentVersion);
+        if (!parsed)
+            return null;
+        return bumpLevel === 'equal' ? parsed : null;
+    }
+    const parsed = parseVersion(currentVersion);
+    if (!parsed) {
+        return null;
+    }
+    let { major, minor, patch } = parsed;
+    switch (bumpLevel) {
+        case 'major':
+            major += 1;
+            minor = 0;
+            patch = 0;
+            break;
+        case 'minor':
+            minor += 1;
+            patch = 0;
+            break;
+        case 'patch':
+            patch += 1;
+            break;
+    }
+    return {
+        major,
+        minor,
+        patch,
+        version: `${major}.${minor}.${patch}`,
+    };
+}
+/**
+ * Parse a semver string into components
+ */
+function parseVersion(version) {
+    // Remove 'v' prefix if present
+    const cleaned = version.startsWith('v') ? version.slice(1) : version;
+    // Match semver pattern (with optional prerelease/build)
+    const match = cleaned.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match) {
+        return null;
+    }
+    const major = parseInt(match[1], 10);
+    const minor = parseInt(match[2], 10);
+    const patch = parseInt(match[3], 10);
+    return {
+        major,
+        minor,
+        patch,
+        version: `${major}.${minor}.${patch}`,
+    };
+}
+/**
+ * Compare two JSON Schema objects and return a simple compatibility result
+ *
+ * Convenience function for quick compatibility checks.
+ *
+ * @param sourceSchema - The source (old/baseline) schema object
+ * @param targetSchema - The target (new/current) schema object
+ * @returns 'compatible' | 'incompatible' | 'unknown'
+ */
+export function checkCompatibility(sourceSchema, targetSchema) {
+    const result = compareSchemas(sourceSchema, targetSchema);
+    // If any trace is incompatible, overall is incompatible
+    if (result.traces.some((t) => t.compatibility === 'incompatible')) {
+        return 'incompatible';
+    }
+    // If any trace is unknown, overall is unknown
+    if (result.traces.some((t) => t.compatibility === 'unknown')) {
+        return 'unknown';
+    }
+    // All compatible
+    return 'compatible';
+}
+//# sourceMappingURL=compare.js.map

package/dist/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../src/compare.ts"],"names":[],"mappings":"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"}

package/dist/differ.d.ts

@@ -0,0 +1,57 @@
+/**
+ * JSON Schema Structural Differ
+ *
+ * Compares two JSON Schema files and detects structural changes,
+ * classifying them by severity for semver bump decisions.
+ */
+import type { DiffResult, RawChange } from './types.js';
+/**
+ * Format a human-readable message for a change
+ *
+ * @param change - The raw change to format
+ * @returns Human-readable message describing the change
+ */
+export declare function formatChangeMessage(change: RawChange): string;
+/**
+ * Diff two JSON Schema files and detect structural changes
+ *
+ * Reads both schema files, resolves $ref references, walks the schemas
+ * to detect differences, and classifies each change by severity.
+ *
+ * @param oldPath - Path to the old/base schema file
+ * @param newPath - Path to the new/changed schema file
+ * @returns DiffResult with classified changes and suggested bump
+ *
+ * @example
+ * ```typescript
+ * const result = await diffJsonSchema('v1/schema.json', 'v2/schema.json');
+ *
+ * console.log(`Suggested bump: ${result.suggestedBump}`);
+ * console.log(`Breaking changes: ${result.summary.breaking}`);
+ *
+ * for (const change of result.changes) {
+ *   console.log(`[${change.severity}] ${change.message}`);
+ * }
+ * ```
+ */
+export declare function diffJsonSchema(oldPath: string, newPath: string): Promise<DiffResult>;
+/**
+ * Diff two JSON Schema objects and detect structural changes
+ *
+ * Like diffJsonSchema but accepts schema objects directly instead of file paths.
+ *
+ * @param oldSchema - The old/base schema object
+ * @param newSchema - The new/changed schema object
+ * @returns DiffResult with classified changes and suggested bump
+ *
+ * @example
+ * ```typescript
+ * const oldSchema = { type: 'object', properties: { name: { type: 'string' } } };
+ * const newSchema = { type: 'object', properties: { name: { type: 'number' } } };
+ *
+ * const result = diffJsonSchemaObjects(oldSchema, newSchema);
+ * console.log(`Suggested bump: ${result.suggestedBump}`);
+ * ```
+ */
+export declare function diffJsonSchemaObjects(oldSchema: unknown, newSchema: unknown): DiffResult;
+//# sourceMappingURL=differ.d.ts.map

package/dist/differ.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"differ.d.ts","sourceRoot":"","sources":["../src/differ.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAA0B,SAAS,EAAE,MAAM,YAAY,CAAC;AAKhF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CA4F7D;AA+ED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAgG1F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,GAAG,UAAU,CA6CxF"}

package/dist/differ.js

@@ -0,0 +1,304 @@
+/**
+ * JSON Schema Structural Differ
+ *
+ * Compares two JSON Schema files and detects structural changes,
+ * classifying them by severity for semver bump decisions.
+ */
+import { readFile } from 'node:fs/promises';
+import { resolveRefs } from './ref-resolver.js';
+import { walk } from './walker.js';
+import { classify, classifyPropertyAdded } from './classifiers.js';
+/**
+ * Format a human-readable message for a change
+ *
+ * @param change - The raw change to format
+ * @returns Human-readable message describing the change
+ */
+export function formatChangeMessage(change) {
+    const pathDisplay = change.path || '/';
+    switch (change.type) {
+        case 'property-added':
+            return `Property added at ${pathDisplay}`;
+        case 'property-removed':
+            return `Property removed at ${pathDisplay}`;
+        case 'required-added':
+            return `Field "${formatRequiredFieldName(change.newValue)}" made required at ${pathDisplay}`;
+        case 'required-removed':
+            return `Field "${formatRequiredFieldName(change.oldValue)}" made optional at ${pathDisplay}`;
+        case 'type-changed':
+            return `Type changed from ${formatValue(change.oldValue)} to ${formatValue(change.newValue)} at ${pathDisplay}`;
+        case 'type-narrowed':
+            return `Type narrowed from ${formatValue(change.oldValue)} to ${formatValue(change.newValue)} at ${pathDisplay}`;
+        case 'type-widened':
+            return `Type widened from ${formatValue(change.oldValue)} to ${formatValue(change.newValue)} at ${pathDisplay}`;
+        case 'enum-value-added':
+            return `Enum value ${formatValue(change.newValue)} added at ${pathDisplay}`;
+        case 'enum-value-removed':
+            return `Enum value ${formatValue(change.oldValue)} removed at ${pathDisplay}`;
+        case 'enum-added':
+            return `Enum constraint added at ${pathDisplay}`;
+        case 'enum-removed':
+            return `Enum constraint removed at ${pathDisplay}`;
+        case 'constraint-tightened':
+            return formatConstraintMessage(change, 'tightened', pathDisplay);
+        case 'constraint-loosened':
+            return formatConstraintMessage(change, 'loosened', pathDisplay);
+        case 'format-added':
+            return `Format "${change.newValue}" added at ${pathDisplay}`;
+        case 'format-removed':
+            return `Format "${change.oldValue}" removed at ${pathDisplay}`;
+        case 'format-changed':
+            return `Format changed from "${change.oldValue}" to "${change.newValue}" at ${pathDisplay}`;
+        case 'additional-properties-denied':
+            return `Additional properties denied at ${pathDisplay}`;
+        case 'additional-properties-allowed':
+            return `Additional properties allowed at ${pathDisplay}`;
+        case 'additional-properties-changed':
+            return `Additional properties schema changed at ${pathDisplay}`;
+        case 'items-changed':
+            return `Array items schema changed at ${pathDisplay}`;
+        case 'min-items-increased':
+            return `Minimum items increased from ${formatValue(change.oldValue)} to ${formatValue(change.newValue)} at ${pathDisplay}`;
+        case 'max-items-decreased':
+            return `Maximum items decreased from ${formatValue(change.oldValue)} to ${formatValue(change.newValue)} at ${pathDisplay}`;
+        case 'composition-changed':
+            return `Composition (allOf/anyOf/oneOf) changed at ${pathDisplay}`;
+        case 'ref-target-changed':
+            return `Reference target changed at ${pathDisplay}`;
+        case 'description-changed':
+            return `Description changed at ${pathDisplay}`;
+        case 'title-changed':
+            return `Title changed at ${pathDisplay}`;
+        case 'default-changed':
+            return `Default value changed at ${pathDisplay}`;
+        case 'examples-changed':
+            return `Examples changed at ${pathDisplay}`;
+        case 'unknown-change':
+        default:
+            return `Unknown change at ${pathDisplay}`;
+    }
+}
+/**
+ * Format a value for display in messages
+ */
+function formatValue(value) {
+    if (value === undefined) {
+        return 'undefined';
+    }
+    if (value === null) {
+        return 'null';
+    }
+    if (typeof value === 'string') {
+        return `"${value}"`;
+    }
+    if (Array.isArray(value)) {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'object') {
+        return JSON.stringify(value);
+    }
+    return String(value);
+}
+/**
+ * Format required field name from change value
+ */
+function formatRequiredFieldName(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    return String(value);
+}
+/**
+ * Format constraint change message
+ */
+function formatConstraintMessage(change, direction, pathDisplay) {
+    const constraintName = extractConstraintName(change.path);
+    const oldVal = change.oldValue !== undefined ? formatValue(change.oldValue) : 'none';
+    const newVal = change.newValue !== undefined ? formatValue(change.newValue) : 'none';
+    if (constraintName) {
+        return `Constraint "${constraintName}" ${direction} from ${oldVal} to ${newVal} at ${pathDisplay}`;
+    }
+    return `Constraint ${direction} from ${oldVal} to ${newVal} at ${pathDisplay}`;
+}
+/**
+ * Extract constraint name from path
+ */
+function extractConstraintName(path) {
+    const segments = path.split('/');
+    const lastSegment = segments[segments.length - 1];
+    if (lastSegment && lastSegment !== '') {
+        return lastSegment;
+    }
+    return null;
+}
+/**
+ * Classify a change, with context-aware classification for property-added
+ *
+ * @param change - The raw change to classify
+ * @param newSchema - The new schema for context (used for property-added)
+ * @returns The severity classification
+ */
+function classifyChange(change, newSchema) {
+    if (change.type === 'property-added') {
+        return classifyPropertyAdded(change, newSchema);
+    }
+    return classify(change);
+}
+/**
+ * Diff two JSON Schema files and detect structural changes
+ *
+ * Reads both schema files, resolves $ref references, walks the schemas
+ * to detect differences, and classifies each change by severity.
+ *
+ * @param oldPath - Path to the old/base schema file
+ * @param newPath - Path to the new/changed schema file
+ * @returns DiffResult with classified changes and suggested bump
+ *
+ * @example
+ * ```typescript
+ * const result = await diffJsonSchema('v1/schema.json', 'v2/schema.json');
+ *
+ * console.log(`Suggested bump: ${result.suggestedBump}`);
+ * console.log(`Breaking changes: ${result.summary.breaking}`);
+ *
+ * for (const change of result.changes) {
+ *   console.log(`[${change.severity}] ${change.message}`);
+ * }
+ * ```
+ */
+export async function diffJsonSchema(oldPath, newPath) {
+    // Read both schema files
+    let oldContent;
+    let newContent;
+    try {
+        oldContent = await readFile(oldPath, 'utf-8');
+    }
+    catch (error) {
+        throw new Error(`Failed to read old schema file "${oldPath}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        newContent = await readFile(newPath, 'utf-8');
+    }
+    catch (error) {
+        throw new Error(`Failed to read new schema file "${newPath}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Parse JSON
+    let oldSchema;
+    let newSchema;
+    try {
+        oldSchema = JSON.parse(oldContent);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse old schema as JSON "${oldPath}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        newSchema = JSON.parse(newContent);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse new schema as JSON "${newPath}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Resolve $refs in both schemas
+    const resolvedOldResult = resolveRefs(oldSchema);
+    const resolvedNewResult = resolveRefs(newSchema);
+    const resolvedOld = resolvedOldResult.schema;
+    const resolvedNew = resolvedNewResult.schema;
+    // Log warnings if any $refs couldn't be resolved
+    const allWarnings = [
+        ...resolvedOldResult.warnings.map((w) => `[old] ${w}`),
+        ...resolvedNewResult.warnings.map((w) => `[new] ${w}`),
+    ];
+    if (allWarnings.length > 0) {
+        // Warnings are informational; diff continues with best effort
+        // In production, you might want to expose these in the result
+    }
+    // Walk both schemas and detect raw changes
+    const rawChanges = walk(resolvedOld, resolvedNew, '');
+    // Classify changes and build final Change objects
+    const changes = rawChanges.map((raw) => ({
+        path: raw.path,
+        severity: classifyChange(raw, resolvedNew),
+        category: raw.type,
+        message: formatChangeMessage(raw),
+        oldValue: raw.oldValue,
+        newValue: raw.newValue,
+    }));
+    // Calculate summary counts
+    const summary = {
+        breaking: changes.filter((c) => c.severity === 'breaking').length,
+        nonBreaking: changes.filter((c) => c.severity === 'non-breaking').length,
+        patch: changes.filter((c) => c.severity === 'patch').length,
+        unknown: changes.filter((c) => c.severity === 'unknown').length,
+    };
+    // Determine suggested semver bump based on highest severity
+    const suggestedBump = summary.breaking > 0
+        ? 'major'
+        : summary.nonBreaking > 0
+            ? 'minor'
+            : summary.patch > 0
+                ? 'patch'
+                : 'none';
+    return {
+        contract: '',
+        changes,
+        summary,
+        suggestedBump,
+    };
+}
+/**
+ * Diff two JSON Schema objects and detect structural changes
+ *
+ * Like diffJsonSchema but accepts schema objects directly instead of file paths.
+ *
+ * @param oldSchema - The old/base schema object
+ * @param newSchema - The new/changed schema object
+ * @returns DiffResult with classified changes and suggested bump
+ *
+ * @example
+ * ```typescript
+ * const oldSchema = { type: 'object', properties: { name: { type: 'string' } } };
+ * const newSchema = { type: 'object', properties: { name: { type: 'number' } } };
+ *
+ * const result = diffJsonSchemaObjects(oldSchema, newSchema);
+ * console.log(`Suggested bump: ${result.suggestedBump}`);
+ * ```
+ */
+export function diffJsonSchemaObjects(oldSchema, newSchema) {
+    // Resolve $refs in both schemas
+    const resolvedOldResult = resolveRefs(oldSchema);
+    const resolvedNewResult = resolveRefs(newSchema);
+    const resolvedOld = resolvedOldResult.schema;
+    const resolvedNew = resolvedNewResult.schema;
+    // Walk both schemas and detect raw changes
+    const rawChanges = walk(resolvedOld, resolvedNew, '');
+    // Classify changes and build final Change objects
+    const changes = rawChanges.map((raw) => ({
+        path: raw.path,
+        severity: classifyChange(raw, resolvedNew),
+        category: raw.type,
+        message: formatChangeMessage(raw),
+        oldValue: raw.oldValue,
+        newValue: raw.newValue,
+    }));
+    // Calculate summary counts
+    const summary = {
+        breaking: changes.filter((c) => c.severity === 'breaking').length,
+        nonBreaking: changes.filter((c) => c.severity === 'non-breaking').length,
+        patch: changes.filter((c) => c.severity === 'patch').length,
+        unknown: changes.filter((c) => c.severity === 'unknown').length,
+    };
+    // Determine suggested semver bump based on highest severity
+    const suggestedBump = summary.breaking > 0
+        ? 'major'
+        : summary.nonBreaking > 0
+            ? 'minor'
+            : summary.patch > 0
+                ? 'patch'
+                : 'none';
+    return {
+        contract: '',
+        changes,
+        summary,
+        suggestedBump,
+    };
+}
+//# sourceMappingURL=differ.js.map

package/dist/differ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"differ.js","sourceRoot":"","sources":["../src/differ.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @contractual/differs.json-schema
+ *
+ * Detect and classify breaking changes between JSON Schema versions.
+ *
+ * This package provides tools to compare JSON Schema documents and determine
+ * the semantic versioning impact of changes. It identifies breaking changes
+ * (major), non-breaking additions (minor), and documentation changes (patch).
+ *
+ * @example
+ * ```typescript
+ * import { compareSchemas } from '@contractual/differs.json-schema';
+ *
+ * const result = compareSchemas(oldSchema, newSchema, { currentVersion: '1.0.0' });
+ * console.log(result.version);    // 'major' | 'minor' | 'patch' | 'equal' | null
+ * console.log(result.newVersion); // { major: 2, minor: 0, patch: 0, version: '2.0.0' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { diffJsonSchema, diffJsonSchemaObjects } from '@contractual/differs.json-schema';
+ *
+ * // Compare files
+ * const result = await diffJsonSchema('v1/schema.json', 'v2/schema.json');
+ * console.log(result.suggestedBump); // 'major' | 'minor' | 'patch' | 'none'
+ *
+ * // Compare schema objects directly
+ * const result2 = diffJsonSchemaObjects(oldSchema, newSchema);
+ * for (const change of result2.changes) {
+ *   console.log(`[${change.severity}] ${change.message}`);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { compareSchemas, checkCompatibility } from './compare.js';
+export { diffJsonSchema, diffJsonSchemaObjects, formatChangeMessage } from './differ.js';
+export { classify, classifyPropertyAdded, classifyAll, CLASSIFICATION_SETS, } from './classifiers.js';
+export { resolveRefs, hasUnresolvedRefs, extractRefs, validateRefs, type ResolveResult, } from './ref-resolver.js';
+export { walk } from './walker.js';
+export type { CompareResult, CompareOptions, StrandsTrace, StrandsCompatibility, StrandsVersion, SemanticVersion, JsonSchemaDraft, } from './types.js';
+export type { ResolvedSchema, JSONSchemaType, NormalizedType, ConstraintKey, ConstraintDirection, CompositionKeyword, MetadataKey, AnnotationKey, ContentKey, WalkerContext, } from './types.js';
+export { isSchemaObject, isSchemaArray, normalizeType, arraysEqual, deepEqual, escapeJsonPointer, joinPath, CONSTRAINT_KEYS, CONSTRAINT_DIRECTION, COMPOSITION_KEYWORDS, METADATA_KEYS, ANNOTATION_KEYS, CONTENT_KEYS, DEFAULT_MAX_DEPTH, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAMH,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAMlE,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAMzF,OAAO,EACL,QAAQ,EACR,qBAAqB,EACrB,WAAW,EACX,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAMnC,YAAY,EACV,aAAa,EACb,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AAMpB,YAAY,EACV,cAAc,EACd,cAAc,EACd,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AAMpB,OAAO,EACL,cAAc,EACd,aAAa,EACb,aAAa,EACb,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,iBAAiB,GAClB,MAAM,YAAY,CAAC"}