Compatibility matrix

This document describes the current Cogita package lanes, upgrade boundaries, and validation requirements. The version table is generated by scripts/check-compatibility-matrix.mjs from each package's package.json. If a package version changes, update the document before the release gate can pass.

Package Current version Compatibility lane Role
@cogita/shared 0.13.0 Core platform Shared types, capabilities, and version contracts
@cogita/core 0.15.0 Core platform Configuration, plugin registration, and build lifecycle
@cogita/cli 0.3.1 Core platform Site initialization, development, and build entry points
@cogita/ui 0.1.2 Theme ecosystem Shared theme UI components
@cogita/plugin-blog-list 0.3.5 Blog theme plugin Lists, filters, pagination, and archives
@cogita/plugin-categories 0.2.7 Blog theme plugin Category aggregation and pages
@cogita/plugin-code-copy 0.2.6 Blog theme plugin Runtime code-copy enhancement
@cogita/plugin-collections 1.0.7 Blog theme plugin Collection aggregation and pages
@cogita/plugin-comments 0.2.7 Blog theme plugin Comment configuration and post routes
@cogita/plugin-content-check 0.2.5 Blog theme plugin Content quality diagnostics
@cogita/plugin-content-relations 0.2.1 Knowledge plugin Local links, related content, and backlinks
@cogita/plugin-content-source-json 0.2.0 Knowledge plugin JSON export content-source adapter
@cogita/plugin-content-source-git 0.2.0 Knowledge plugin Independent Git Markdown content-source adapter
@cogita/plugin-images 1.0.7 Blog theme plugin Public image and cover handling
@cogita/plugin-posts-frontmatter 0.1.6 Blog theme plugin Post index and post pages
@cogita/plugin-reading-progress 0.3.7 Blog theme plugin Reading time and progress
@cogita/plugin-rss 1.0.7 Blog theme plugin RSS, Atom, and JSON Feed
@cogita/plugin-search 0.2.7 Blog theme plugin Local search index and pages
@cogita/plugin-seo 1.3.7 Blog theme plugin Page SEO metadata and audits
@cogita/plugin-sitemap 1.3.7 Blog theme plugin Sitemap generation
@cogita/plugin-tags 1.0.7 Blog theme plugin Tag aggregation and pages
@cogita/theme-lucid 0.12.1 Blog theme Default blog theme and full plugin integration
@cogita/theme-editorial 0.3.1 Blog theme Editorial-style blog theme
@cogita/theme-docs 0.3.1 Docs theme Technical handbook and documentation sites
@cogita/theme-knowledge 0.3.1 Knowledge theme Unified content, search, tags, and backlinks

Compatibility lanes

Core platform

@cogita/shared, @cogita/core, and @cogita/cli belong to one Core release lane. They may have different package versions, but changes to build context, ContentIndex, capability identifiers, or virtual modules must be validated in one Changesets release batch. Use CLI and Core packages from the same batch instead of combining unverified versions.

Blog themes and plugins

@cogita/theme-lucid and @cogita/theme-editorial combine multiple blog plugins and belong to the blog theme lane. A theme's package.json is the source of truth for its plugin list. When upgrading a plugin, run at least the minimal blog consumer and the real cogita-blog consumer.

Docs theme

@cogita/theme-docs is an independent docs-theme lane and does not depend on the blog plugin set. Validate it with an independent docs consumer, covering the home page, document routes, theme preview, and static output.

Knowledge theme and plugins

@cogita/theme-knowledge combines the unified content index, search, tags, and content relations, and belongs to the knowledge lane. Validate it with an independent knowledge consumer, covering posts, contentDir documents, root deployment, and subpath deployment.

Host runtime

Packages that use Rspress directly currently use @rspress/core ^1.45.1 as the compatibility baseline. Themes expose @rspress/runtime ^1.0.0 as a peer range and support React 18 or React 19. When upgrading Rspress or React, establish a new compatibility lane first, then update the script baseline and rerun every consumer gate.

Version and contract rules

  • A 0.x minor release may contain public API or build-contract changes; do not treat it like a patch-only upgrade.
  • Package versions describe release scope. ContentIndex, buildContext, and virtual-module shapes are described by their contractVersion or version header. Consumers should check the contract before reading new fields.
  • A theme or plugin that lacks a capability should report a stable diagnostic code and degrade safely instead of silently reading unknown fields.
  • The matrix records only combinations that have been verified. Do not mark a combination as supported because it is merely expected to work.

Upgrade workflow

  1. After changing a package version or public contract, run pnpm run check:compatibility -- --write to update the version table.
  2. Run pnpm run build:packages and pnpm run test.
  3. Run pnpm run check:release to validate package boundaries, the minimal blog, the independent blog, and the independent docs site.
  4. If a contract version changes, add migration notes and verify how old configuration degrades in a real consumer.

The compatibility check is part of pnpm run check:release. CI rejects a package-version change that does not update this document.