@modernizespec/sdk

@modernizespec/sdk is the full SDK for working with ModernizeSpec files programmatically. It wraps the core types and schemas with file I/O, codebase analysis, progress tracking, and parity comparison utilities.

Installation

npm install @modernizespec/sdk

Why an SDK

Capability	Without SDK	With SDK
Read spec files	Manual `JSON.parse` + path resolution	`ModernizeSpec.load(projectDir)`
Validate compliance	Write your own schema validation	`spec.validate()` with typed errors
Generate from codebase	Build your own AST analysis	`ModernizeSpec.analyze(projectDir)`
Track progress	Parse `migration-state.json` manually	`spec.state.advance("Accounts", 0.45)`
Compare legacy vs modern	Custom diff logic	`spec.parity.compare(legacy, modern)`

API Surface

Loading a Spec

import { ModernizeSpec } from "@modernizespec/sdk";

// Load existing spec from project
const spec = await ModernizeSpec.load("/path/to/project");

// Access typed data
const domains = spec.domains;        // Typed bounded contexts
const hotspots = spec.complexity;    // Extraction tiers, God-classes
const plan = spec.extractionPlan;    // Phased sequence with risk
const state = spec.migrationState;   // Current progress

Validation

// Validate all files against schemas
const errors = spec.validate();

if (errors.length > 0) {
  for (const error of errors) {
    console.error(`${error.file}: ${error.path} — ${error.message}`);
  }
}

Codebase Analysis

// Generate spec from codebase analysis
const generated = await ModernizeSpec.analyze("/path/to/legacy", {
  language: "python",
  framework: "frappe",
});

// Review the generated domains
console.log(generated.domains.contexts);

Progress Updates

// Update progress for a context
state.updateContext("Accounts", {
  progress: 0.45,
  entitiesMigrated: 12,
  parityTests: { passing: 68, failing: 4, total: 72 },
});

// Write back to disk
await spec.save();

Parity Comparison

// Compare legacy and modern behavior
const diff = spec.parity.compare(
  legacyOutput,
  modernOutput,
  { tolerance: 0.001 } // numeric precision tolerance
);

console.log(diff.matches);    // true if within tolerance
console.log(diff.deviations); // list of field-level differences

Key Classes

`ModernizeSpec`

The main entry point. Static methods for loading and analyzing. Instance methods for accessing, validating, and saving.

Method	Description
`ModernizeSpec.load(dir)`	Load spec from `.agents/modernization/`
`ModernizeSpec.analyze(dir, options)`	Generate spec from codebase analysis
`spec.validate()`	Validate all files against schemas
`spec.save()`	Write all modified files back to disk

`DomainsAccessor`

Access bounded context data.

Property/Method	Description
`spec.domains.contexts`	Array of all bounded contexts
`spec.domains.contextMap`	Array of context relationships
`spec.domains.getContextForFile(path)`	Find which context owns a file
`spec.domains.getContext(name)`	Get a specific context by name

`ComplexityAccessor`

Access extraction tier and hotspot data.

Property/Method	Description
`spec.complexity.tiers`	Array of extraction tiers
`spec.complexity.hotspots`	Array of complexity hotspots
`spec.complexity.getTier(module)`	Get tier for a module

`MigrationStateAccessor`

Read and update progress.

Property/Method	Description
`spec.migrationState.overallProgress`	Overall progress (0-1)
`spec.migrationState.contexts`	Per-context progress array
`spec.migrationState.blockers`	Active blockers
`spec.migrationState.velocity`	Velocity metrics
`spec.migrationState.updateContext(name, data)`	Update context progress
`spec.migrationState.addBlocker(blocker)`	Add a new blocker
`spec.migrationState.resolveBlocker(id)`	Mark blocker as resolved

Error Handling

The SDK uses typed errors:

import { SpecNotFoundError, ValidationError, AnalysisError } from "@modernizespec/sdk";

try {
  const spec = await ModernizeSpec.load("/path/to/project");
} catch (error) {
  if (error instanceof SpecNotFoundError) {
    console.error("No .agents/modernization/ directory found");
  }
}

Next Steps

@modernizespec/cli — CLI that wraps this SDK
@modernizespec/core — Types-only package
MCP Server Integration — Build MCP tools with the SDK