Skip to content
ModernizeSpec

@modernizespec/core

@modernizespec/core is the foundation package. It contains TypeScript types, JSON Schema definitions, and validation utilities with zero external dependencies. Tool builders who only need types can import core without pulling in the full SDK.

Installation

Section titled “Installation”
Terminal window
npm install @modernizespec/core

What It Provides

Section titled “What It Provides”
ExportDescription
TypeScript typesTyped interfaces for every ModernizeSpec file
JSON Schema constantsSchema objects importable in code
Validation functionsValidate JSON against schemas
Version constantCurrent spec version string

TypeScript Types

Section titled “TypeScript Types”
import type {
  Manifest,
  DomainsFile,
  ComplexityFile,
  ExtractionPlan,
  ParityTests,
  MigrationState,
  BoundedContext,
  ContextMapEntry,
  ComplexityTier,
  Hotspot,
  Phase,
  SequencingConstraint,
  ParitySuite,
  ContextProgress,
  Blocker,
  Velocity,
} from "@modernizespec/core";

Key Type Definitions

Section titled “Key Type Definitions”
interface Manifest {
  modernizespec: string;
  project: string;
  legacy: {
    framework: string;
    language: string;
    loc: number;
    entities: number;
    endpoints: number;
    age_years?: number;
  };
  target: {
    language: string;
    architecture: "hexagonal" | "clean" | "modular-monolith" | "microservices";
    pattern: "strangler-fig" | "big-bang" | "parallel-run";
  };
  files: Record<string, string>;
}


interface BoundedContext {
  name: string;
  type: "core" | "supporting" | "generic";
  entities: string[];
  aggregateRoot: string;
  loc: number;
  endpoints: number;
  coupling: {
    internal: number;
    external: number;
  };
  dependencies: string[];
  godClasses?: Array<{
    file: string;
    loc: number;
    functions: number;
  }>;
}


interface ContextMapEntry {
  upstream: string;
  downstream: string;
  type: "conformist" | "acl" | "partnership" | "shared-kernel";
}


interface ContextProgress {
  name: string;
  status: "not-started" | "in-progress" | "complete" | "blocked";
  progress: number;
  entitiesMigrated: number;
  entitiesTotal: number;
  parityTests: {
    passing: number;
    failing: number;
    total: number;
  };
  assignedTeam?: string | null;
  notes?: string;
}

Validation

Section titled “Validation”
import { validate, validateManifest, validateDomains } from "@modernizespec/core";


// Validate any spec file by type
const errors = validate("manifest", jsonData);


// Or use type-specific validators
const manifestErrors = validateManifest(jsonData);
const domainsErrors = validateDomains(jsonData);


// Errors are typed
interface ValidationError {
  file: string;
  path: string;
  message: string;
  severity: "error" | "warning";
}

JSON Schema Access

Section titled “JSON Schema Access”
import {
  manifestSchema,
  domainsSchema,
  complexitySchema,
  extractionPlanSchema,
  parityTestsSchema,
  migrationStateSchema,
} from "@modernizespec/core/schemas";

These are plain JavaScript objects (JSON Schema draft-07) that can be used with any JSON Schema validator (ajv, zod-to-json-schema, etc.).

Version

Section titled “Version”
import { SPEC_VERSION } from "@modernizespec/core";
// "0.1.0"

Design Principles

Section titled “Design Principles”
  • Zero dependencies — only TypeScript types and JSON Schema definitions
  • Tree-shakeable — import only what you need
  • Runtime-agnostic — works in Node.js, Bun, Deno, and browsers
  • Strict types — discriminated unions, branded types where appropriate

Next Steps

Section titled “Next Steps”