CHANGELOG.md

Changelog

All notable changes to the OSIRIS JSON Toolbox packages will be documented in this file.

The format follows Keep a Changelog. Package versioning follows Semantic Versioning.

Note

This changelog tracks the toolbox packages (@osirisjson/core, @osirisjson/cli, @osirisjson/sdk). For changes to the architectural guidelines and documentation, see docs/guidelines/v1.0/CHANGELOG.md. For changes to the OSIRIS specification, core schema and core architectural guidelines, see the OSIRIS repository.

---

[Unreleased]

Added - 2026-02-28

@osirisjson/cli

• Table summary output (src/format-text.ts): structured table on stderr showing Status/File/Errors/Warnings/Info per file with footer summary (e.g. 3 files | 1 passed | 1 failed | 1 error)
• --verbose flag (src/args.ts): when set, detailed diagnostics (code snippets, line:col) are emitted to stdout alongside the table; default mode shows table only
• Unit tests for renderTable() and verbose/non-verbose formatText() behavior; integration tests for --verbose

Added - 2026-02-27

@osirisjson/cli

• CLI validation command (osiris validate): CI-friendly validation interface wrapping @osirisjson/core's validate() function
• Argument parsing (src/args.ts): hand-rolled zero-dependency parser supporting --profile, --format, --color, --schema, --help, --version
• Input resolution (src/input.ts): file reading, non-recursive directory expansion (.json only), stdin buffering, path normalization
• Runner orchestration (src/runner.ts): per-file read -> parse -> validate pipeline with exit code resolution (0=success, 1=validation error, 2=operational error)
• Human-readable formatter (src/format-text.ts): colored diagnostic output with 1-based line:col, 3-line code snippets, summary to stderr
• Machine-readable formatter (src/format-json.ts): JSON envelope (single input) / NDJSON (multi-input) with 0-based LSP ranges
• ANSI color helpers (src/color.ts): red/yellow/cyan/bold/dim with TTY-aware auto-detection and --color flag override
• Unit tests: 42 tests across args, input, runner, format-json, format-text, color modules
• Integration tests: 14 end-to-end tests via child process covering help, version, valid/invalid files, JSON/text output, stdin, multi-file, directory expansion

Added - 2026-02-26

@osirisjson/core

• OSIRIS document types (src/types/osiris.ts): full TypeScript type model for OSIRIS v1.0 - OsirisDocument, OsirisResource, OsirisConnection, OsirisGroup, OsirisProvider, OsirisMetadata, OsirisTopology with index signatures for forward-compatibility
• diagnostic model (src/diagnostic/types.ts): Diagnostic, ValidationOptions, ValidationProfile, plugin API (RuleDefinition, RuleContext), LSP-style Position/DiagnosticRange, DocumentIndexes for O(1) lookups
• JSON Pointer utilities (src/diagnostic/pointer.ts): RFC 6901 pointer(), pointerAppend(), parsePointer(), resolvePointer()
• code registry (src/diagnostic/registry.ts): array-format codes loader with lookupCode() and getRegistry()
• validation engine pipeline:
  • src/engine/loader.ts - schema loader with Ajv 2020-12 cache and offline-first version routing
  • src/engine/stage1.ts - Stage 1 structural validation with classifyAjvError() emitting 15+ specific V-* codes
  • src/engine/stage2.ts - Stage 2 semantic validation (duplicate IDs, dangling refs, group cycles, V-TYPE-007 osiris. type prefix rules)
  • src/engine/stage3.ts - Stage 3 domain best-practice rules with plugin support
  • src/engine/pipeline.ts - pipeline orchestrator with profile-based stage gating and diagnostic capping
• public API surface (src/index.ts): validate() entry point, type re-exports, JSON Pointer helpers, code registry lookup, engine internals for CLI/editor consumers
• unit tests: pointer utilities, schema loader version routing, code registry, Stage 1 code attribution (V-META-001, V-META-002, V-TPGY-002, V-RES-004, V-RES-007, V-CONN-006, V-GRP-006), Stage 2 V-TYPE-007 custom type prefix validation
• integration test scaffold for specification fixture validation

Changed - 2026-02-22

• Stage 1 code precision - replaced codeFromPath() with classifyAjvError() in stage1.ts. Ajv errors are now classified using instancePath + keyword + params together, emitting 15+ specific V-* codes (e.g. V-RES-004 for empty resource type, V-META-002 for bad timestamp format) instead of coarse parent-level fallbacks (e.g. everything under /topology/resources was V-RES-001).

Changed - 2026-02-21

• src/registry/v1.0/codes.json updated with OSIRIS-1.0.0 specification validation rules
• scripts/generate-assets.mjs updated to handle array-format registry, added per-asset validation hook, deterministic sort by code
• scripts/check-deps-direction.mjs updated ROOT path calculation to use dirname
• src/diagnostic/registry.ts updated to expose specRef, tags, deprecated, replacedBy from CodeEntry
• src/engine/stage1.ts updated V-DOC-002/003 assignments to match spec registry (V-DOC-002 = missing required fields, V-DOC-003 = invalid version format)

Added - 2026-02-21

• Community and governance files: CHANGELOG.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, MAINTAINERS.md
• Monorepo root configuration: pnpm workspaces (pnpm-workspace.yaml), turborepo pipeline (turbo.json), shared tsconfig.base.json
• Build scripts: scripts/generate-assets.mjs JSON -> TS asset generation, scripts/check-deps-direction.mjs (forbidden dependency guard)
• @osirisjson/core package scaffold: package.json, tsconfig.json, tsup.config.ts
• @osirisjson/cli workspace stub
• @osirisjson/sdk workspace stub
• Bundled assets for @osirisjson/core:
  • src/schema/v1.0/osiris.schema.json - bundled OSIRIS JSON Schema v1.0
  • src/registry/v1.0/codes.json - V-* diagnostic code registry v1.0
  • tests/fixtures/v1.0/ - 13 OSIRIS v1.0 specification example documents (IT and OT)

---

[0.1.0] - not yet released

Will be tagged when:

• All source files are implemented
• Integration test suite passes clean against all 13 specification fixtures
• Package is published to NPM as @osirisjson/core@0.1.0