@ryhrm-gz/xincodo-lib/skills/save-before-publish-checks/references/migration-issues-and-lint-severities.md

Utilities for working with Xincodo body documents.

# Migration Issues and Lint Severities

Use this reference when implementing pre-save or pre-publish checks.

## Migration Result

```ts
type BodyMigrationResult = BodyMigrationSuccess | BodyMigrationFailure;

type BodyMigrationSuccess = {
  success: true;
  output: Body;
  migrated: boolean;
  fromVersion: number;
  toVersion: 1;
};

type BodyMigrationFailure = {
  success: false;
  issue: BodyMigrationIssue;
};
```

## Migration Issue Codes

```ts
type BodyMigrationIssueCode = "invalid_body" | "unsupported_version";
```

`invalid_body` includes:

- non-object input
- missing version
- non-integer version
- current-version data that does not match the Body schema
- migrated data that still fails schema validation

`unsupported_version` includes:

- versions lower than the minimum supported Body version
- versions greater than the current `BODY_VERSION`
- missing migration steps between supported versions

## Throwing API

```ts
migrateBody(input: unknown): Body
```

`migrateBody` throws `BodyMigrationError` on failure. Prefer
`safeMigrateBody` for user-facing save or publish checks.

## Default Save/Publish Policy

Block:

- `safeMigrateBody(...).success === false`
- `lintBody(...).valid === false`
- any issue in `report.errors`

Surface but do not block by default:

- `report.warnings`
- `report.infos`

The consuming application may choose stricter rules, such as blocking publish
on `missing_image_alt`, but that is not the default library policy.

## Standard Pipeline

```ts
const migrated = safeMigrateBody(value);
if (!migrated.success) {
  return { ok: false as const, stage: "migration", issue: migrated.issue };
}

const report = lintBody(migrated.output);
if (!report.valid) {
  return { ok: false as const, stage: "lint", report };
}

return { ok: true as const, body: migrated.output, warnings: report.warnings };
```