feat(migration): add schema safety planning

[kunaldhongade]

Summary

• add AST-backed PostgreSQL/Prisma migration operation evidence using pgsql-ast-parser
• classify destructive changes, unsafe non-null additions, backfills, index lock risk, rollback availability, and ambiguous targets
• emit a five-state old/new application and schema compatibility matrix through codedecay migration
• add a read-only Prisma migrate diff adapter plan contract with approval, target, timeout, cleanup, and secret-name boundaries

Safety

The CLI command is plan-only. It reads repo-local SQL files but does not read database secrets, connect to a database, execute commands, or apply migrations. Unspecified, remote-unapproved, and production-like targets remain blocked.

Validation

• pnpm run lint
• pnpm typecheck
• pnpm test (781 passed)
• pnpm build
• pnpm --filter @submuxhq/codedecay pack --dry-run
• built CLI child-repository migration UAT
• path containment, malformed SQL, rollback validation, production target, additive nullable, and non-null/no-default tests

Remaining Issue Scope

This is the static planning and adapter-contract foundation. Disposable database execution through packages/execution, representative existing-data fixtures, real old/new app runs, rollback execution, cleanup evidence, and final requirement/topology attachment remain follow-up work, so this PR does not close the full issue.

Refs #686

[github-actions]

CodeDecay PR Check

Lead catch: Database area changed — packages/cli/src/commands/migration.ts:1

packages/cli/src/commands/migration.ts touches a database area and should be reviewed for regression impact.

Risk: High · Merge 100/100 · Decay 31/100 · Security 0/100

Full CodeDecay report

CodeDecay Report

Overall risk: High

Score	Value
Merge risk	100/100
Decay risk	31/100
Security risk	0/100

Findings	Count
High	15
Medium	4
Low	13

Changed Files

• packages/cli/src/commands/migration.ts added (+18/-0)
• packages/cli/src/commands/registry.ts modified (+5/-0)
• packages/cli/src/docs/command-docs/analysis.ts modified (+16/-0)
• packages/cli/src/docs/command-docs/order.ts modified (+1/-1)
• packages/cli/src/parsers/args.ts modified (+1/-0)
• packages/cli/src/parsers/migration.ts added (+38/-0)
• packages/cli/src/types/index.ts modified (+1/-0)
• packages/cli/src/types/migration.ts added (+11/-0)
• packages/cli/test/built-cli-migration.test.ts added (+24/-0)
• packages/cli/test/migration.test.ts added (+41/-0)
• packages/knowledge/package.json modified (+1/-0)
• packages/knowledge/src/index.ts modified (+12/-0)
• packages/knowledge/src/migration/analyze.ts added (+148/-0)
• packages/knowledge/src/migration/render.ts added (+21/-0)
• packages/knowledge/src/migration/types.ts added (+57/-0)
• packages/knowledge/test/migration-safety.test.ts added (+69/-0)
• packages/tool-adapters/package.json modified (+2/-1)
• packages/tool-adapters/src/index.ts modified (+1/-0)
• packages/tool-adapters/src/migration/index.ts added (+2/-0)
• packages/tool-adapters/src/migration/plan.ts added (+36/-0)
• ...and 3 more file(s)

Likely Impacted Areas

• High Database and schema (database): packages/cli/src/commands/migration.ts, packages/cli/src/parsers/migration.ts, packages/cli/src/types/migration.ts, packages/knowledge/src/migration/analyze.ts, packages/knowledge/src/migration/render.ts, packages/knowledge/src/migration/types.ts, packages/tool-adapters/src/migration/index.ts, packages/tool-adapters/src/migration/plan.ts, packages/tool-adapters/src/migration/types.ts
• Medium Build and runtime configuration (config): packages/knowledge/package.json, packages/tool-adapters/package.json
• Low Dependency lockfile (config): pnpm-lock.yaml
• Low Documentation (docs): packages/cli/src/docs/command-docs/analysis.ts, packages/cli/src/docs/command-docs/order.ts
• Low Source code (source): packages/cli/src/commands/registry.ts, packages/cli/src/parsers/args.ts, packages/cli/src/types/index.ts, packages/knowledge/src/index.ts, packages/tool-adapters/src/index.ts
• Low Tests (test): packages/cli/test/built-cli-migration.test.ts, packages/cli/test/migration.test.ts, packages/knowledge/test/migration-safety.test.ts, packages/tool-adapters/test/migration.test.ts

Normalized Impact Graph

Graph artifact: .codedecay/local/impact-graph.json (4265 node(s), 8673 edge(s))

• Confidence: Direct: 8673, inferred: 0, heuristic: 0
• codedecay-js-babel-symbols via @babel/parser (available, adapter 1.0.0)
  • Limitation: Call expressions are not connected to target symbols in this adapter version.
  • Limitation: Only JavaScript and TypeScript files parsed by @babel/parser are represented.
  • Limitation: Static import resolution does not resolve runtime dependency injection or dynamic imports.
• codedecay-python-lezer via @lezer/python (available, adapter 1.0.0)
  • Limitation: Dynamic imports, dependency injection, decorators without literal routes, and framework route registries are not resolved.
  • Limitation: Python impact evidence uses the @lezer/python grammar and conservative module-to-file resolution.
  • Limitation: Static test imports do not prove execution or assertion quality.
• Graph limitation: A static test import does not prove the symbol executed or that assertions cover its behavior.

Symbol Impact Evidence

Graph artifact: .codedecay/local/symbol-impact-graph.json (916 file(s), 5402 edge(s))

• packages/cli/src/commands/migration.ts#runMigrationCommand -> packages/cli/src/commands/registry.ts
• packages/cli/src/commands/registry.ts#createCommandHandlers -> packages/cli/src/index.ts
• packages/cli/src/docs/command-docs/analysis.ts#ANALYSIS_COMMAND_DOCS -> packages/cli/src/docs/commands.ts
• packages/cli/src/docs/command-docs/order.ts#COMMAND_ORDER -> packages/cli/src/commands/help.ts, packages/cli/src/docs/commands.ts
• packages/cli/src/parsers/args.ts#parseMigrationArgs -> packages/cli/src/commands/migration.ts
• packages/cli/src/parsers/migration.ts#parseMigrationArgs -> packages/cli/src/commands/migration.ts, packages/cli/src/parsers/args.ts
• packages/cli/src/types/migration.ts#MigrationOptions -> packages/cli/src/commands/migration.ts, packages/cli/src/parsers/migration.ts, packages/cli/src/types.ts, packages/cli/src/types/index.ts
• packages/knowledge/src/index.ts#analyzeMigrationSafety -> packages/cli/src/commands/migration.ts, packages/knowledge/test/migration-safety.test.ts
  • Likely tests: packages/knowledge/test/migration-safety.test.ts
• packages/knowledge/src/index.ts#MigrationTargetKind -> packages/cli/src/types/migration.ts, packages/tool-adapters/src/migration/types.ts
• packages/knowledge/src/index.ts#renderMigrationSafetyMarkdown -> packages/cli/src/commands/migration.ts
• packages/knowledge/src/migration/analyze.ts#analyzeMigrationSafety -> packages/cli/src/commands/migration.ts, packages/knowledge/src/index.ts, packages/knowledge/test/migration-safety.test.ts
  • Likely tests: packages/knowledge/test/migration-safety.test.ts
• packages/knowledge/src/migration/analyze.ts#AnalyzeMigrationSafetyOptions -> packages/knowledge/src/index.ts
• ...and 14 more symbol impact(s)

Language And Parser Coverage

• Source files classified: 20
• Fully supported parser files: 20
• Limited files: 0
• Unsupported files: 0

Merge Risk Breakdown

• Score: 100/100
• Raw score before dampeners: 100/100
• Adjusted score before severity cap: 100/100
• Highest contributing severity: High

Top contributors:

• +30 Database area changed (direct): packages/cli/src/commands/migration.ts touches a database area and should be reviewed for regression impact.
• +30 Database area changed (direct): packages/cli/src/parsers/migration.ts touches a database area and should be reviewed for regression impact.
• +30 Database area changed (direct): packages/cli/src/types/migration.ts touches a database area and should be reviewed for regression impact.
• +30 Database area changed (direct): packages/knowledge/src/migration/analyze.ts touches a database area and should be reviewed for regression impact.
• +30 Database area changed (direct): packages/knowledge/src/migration/render.ts touches a database area and should be reviewed for regression impact.

Notes:

• Untrusted memory context is visible but contributes 0 score until trusted evidence corroborates it.

Decay Risk Breakdown

• Score: 31/100
• Raw score before dampeners: 42/100
• Adjusted score before severity cap: 31/100
• Highest contributing severity: High
• Evidence mode: heuristic-only

Top contributors:

• +18 Broad unrelated change set (heuristic): This PR changes 20 files across 1 top-level areas and 4 risk categories.
• +10 High complexity in changed function (heuristic): parseMigrationArgs has estimated cyclomatic complexity 12.
• +8 Change size (structural): Changed lines amplify review cost across 23 file(s).
• +6 File spread (structural): Change breadth spans 23 file(s).

Dampeners:

• -11 Heuristic-only dampener: Decay stays conservative until direct evidence exists.

Notes:

• Heuristic-only decay is capped at 54/100 until direct evidence exists.

Security Risk Breakdown

• Score: 0/100
• Raw score before dampeners: 0/100
• Adjusted score before severity cap: 0/100

Security Matcher Coverage

• Changed source files scanned: 16
• Security candidates found: 0
• Skipped files: 0

Test Evidence

• Mode: heuristic-only
• Sources: none
• Changed source coverage:
• packages/cli/src/commands/migration.ts: not measured (no measurable changed lines)
• packages/cli/src/commands/registry.ts: not measured (no measurable changed lines)
• packages/cli/src/docs/command-docs/analysis.ts: not measured (no measurable changed lines)
• packages/cli/src/docs/command-docs/order.ts: not measured (no measurable changed lines)
• packages/cli/src/parsers/args.ts: not measured (no measurable changed lines)
• packages/cli/src/parsers/migration.ts: not measured (no measurable changed lines)
• packages/cli/src/types/index.ts: not measured (no measurable changed lines)
• packages/cli/src/types/migration.ts: not measured (no measurable changed lines)
• Notes:
• No runtime coverage artifact was found. Test audit remains heuristic-only.

Changed Path Test Proof

Status	Count
Runtime-proven	0
Static-only	10
Weakened by mocks	0
Unproven	18

• Static-only packages/cli/src/commands/migration.ts#runMigrationCommand (static-reference, deterministic)
  • Evidence: Referenced by packages/cli/test/built-cli-migration.test.ts, packages/cli/test/migration.test.ts, packages/knowledge/test/migration-safety.test.ts, packages/tool-adapters/test/migration.test.ts, but no runtime coverage artifact proves changed lines executed.
  • Static references: packages/cli/test/built-cli-migration.test.ts, packages/cli/test/migration.test.ts, packages/knowledge/test/migration-safety.test.ts, packages/tool-adapters/test/migration.test.ts
  • Repair task: Strengthen packages/cli/test/built-cli-migration.test.ts so it executes packages/cli/src/commands/migration.ts#runMigrationCommand with assertions; static import alone is not proof.
• Static-only packages/cli/src/commands/registry.ts#createCommandHandlers (static-reference, deterministic)
  • Evidence: Referenced by packages/cli/test/built-cli-migration.test.ts, but no runtime coverage artifact proves changed lines executed.
  • Static references: packages/cli/test/built-cli-migration.test.ts
  • Repair task: Strengthen packages/cli/test/built-cli-migration.test.ts so it executes packages/cli/src/commands/registry.ts#createCommandHandlers with assertions; static import alone is not proof.
• Static-only packages/cli/src/docs/command-docs/analysis.ts#ANALYSIS_COMMAND_DOCS (static-reference, deterministic)
  • Evidence: Referenced by packages/knowledge/test/migration-safety.test.ts, but no runtime coverage artifact proves changed lines executed.
  • Static references: packages/knowledge/test/migration-safety.test.ts
  • Repair task: Strengthen packages/knowledge/test/migration-safety.test.ts so it executes packages/cli/src/docs/command-docs/analysis.ts#ANALYSIS_COMMAND_DOCS with assertions; static import alone is not proof.
• Unproven packages/cli/src/docs/command-docs/order.ts#COMMAND_ORDER (missing-proof, heuristic)
  • Evidence: No runtime coverage or static test reference was found for this changed path.
  • Repair task: Add an integration test that reaches packages/cli/src/docs/command-docs/order.ts#COMMAND_ORDER without mocking the changed boundary.
• Static-only packages/cli/src/parsers/args.ts#parseMigrationArgs (static-reference, deterministic)
  • Evidence: Referenced by packages/cli/test/migration.test.ts, but no runtime coverage artifact proves changed lines executed.
  • Static references: packages/cli/test/migration.test.ts
  • Repair task: Strengthen packages/cli/test/migration.test.ts so it executes packages/cli/src/parsers/args.ts#parseMigrationArgs with assertions; static import alone is not proof.
• Static-only packages/cli/src/parsers/migration.ts#parseMigrationArgs (static-reference, deterministic)
  • Evidence: Referenced by packages/cli/test/built-cli-migration.test.ts, packages/cli/test/migration.test.ts, packages/knowledge/test/migration-safety.test.ts, packages/tool-adapters/test/migration.test.ts, but no runtime coverage artifact proves changed lines executed.
  • Static references: packages/cli/test/built-cli-migration.test.ts, packages/cli/test/migration.test.ts, packages/knowledge/test/migration-safety.test.ts, packages/tool-adapters/test/migration.test.ts
  • Repair task: Strengthen packages/cli/test/built-cli-migration.test.ts so it executes packages/cli/src/parsers/migration.ts#parseMigrationArgs with assertions; static import alone is not proof.
• Unproven packages/cli/src/types/index.ts (missing-proof, heuristic)
  • Evidence: No runtime coverage or static test reference was found for this changed path.
  • Repair task: Add an integration test that reaches packages/cli/src/types/index.ts without mocking the changed boundary.
• Static-only packages/cli/src/types/migration.ts#MigrationOptions (static-reference, deterministic)
  • Evidence: Referenced by packages/cli/test/built-cli-migration.test.ts, packages/cli/test/migration.test.ts, packages/knowledge/test/migration-safety.test.ts, packages/tool-adapters/test/migration.test.ts, but no runtime coverage artifact proves changed lines executed.
  • Static references: packages/cli/test/built-cli-migration.test.ts, packages/cli/test/migration.test.ts, packages/knowledge/test/migration-safety.test.ts, packages/tool-adapters/test/migration.test.ts
  • Repair task: Strengthen packages/cli/test/built-cli-migration.test.ts so it executes packages/cli/src/types/migration.ts#MigrationOptions with assertions; static import alone is not proof.
• ...and 20 more changed path proof entries

Untrusted Memory Context

• Project invariant may be impacted (packages/cli/src/commands/registry.ts:19): Untrusted memory context: invariant "No hidden cloud or model call" applies to this change. The OSS CLI must remain useful without telemetry, API keys, hosted services, required LLM calls, or CodeDecayCloud.
• Project invariant may be impacted (packages/cli/src/commands/registry.ts:19): Untrusted memory context: invariant "Commands are explicit" applies to this change. CodeDecay must not run project commands unless they are configured and safety.allowCommands is true.
• Project invariant may be impacted (packages/cli/src/commands/registry.ts:19): Untrusted memory context: invariant "Tool evidence is separate from AI suggestions" applies to this change. Reports must not present agent/model suggestions as verified evidence unless backed by deterministic checks or command output.
• Project invariant may be impacted (packages/knowledge/package.json:18): Untrusted memory context: invariant "Package remains installable from npm" applies to this change. The published package must include README, LICENSE, package.json, dist/index.js, and dist/index.d.ts without workspace-only dependency leaks.
• Past regression area changed (packages/knowledge/package.json:18): Untrusted memory context: past regression "Published npm package leaked workspace protocol" may be relevant. Published package installation failed when workspace protocol dependencies leaked into the npm package.
• Project invariant may be impacted (packages/cli/src/commands/registry.ts:19): Untrusted memory context: invariant "Output must be actionable" applies to this change. Redteam reports and agent bundles should say what behavior to verify, which test proof is weak or missing, and what task a coding agent should perform.
• Architecture note applies (packages/cli/src/commands/migration.ts:1): Untrusted architecture context: CLI is the published surface: The public npm package is @submuxhq/codedecay and the binary is codedecay. Internal workspace packages are implementation details.

High Risk Findings

• Broad unrelated change set: This PR changes 20 files across 1 top-level areas and 4 risk categories.
• Database area changed (packages/cli/src/commands/migration.ts:1): packages/cli/src/commands/migration.ts touches a database area and should be reviewed for regression impact.
• Database area changed (packages/cli/src/parsers/migration.ts:1): packages/cli/src/parsers/migration.ts touches a database area and should be reviewed for regression impact.
• Database area changed (packages/cli/src/types/migration.ts:1): packages/cli/src/types/migration.ts touches a database area and should be reviewed for regression impact.
• Database area changed (packages/knowledge/src/migration/analyze.ts:1): packages/knowledge/src/migration/analyze.ts touches a database area and should be reviewed for regression impact.
• Database area changed (packages/knowledge/src/migration/render.ts:1): packages/knowledge/src/migration/render.ts touches a database area and should be reviewed for regression impact.
• Database area changed (packages/knowledge/src/migration/types.ts:1): packages/knowledge/src/migration/types.ts touches a database area and should be reviewed for regression impact.
• Database area changed (packages/tool-adapters/src/migration/index.ts:1): packages/tool-adapters/src/migration/index.ts touches a database area and should be reviewed for regression impact.
• Database area changed (packages/tool-adapters/src/migration/plan.ts:1): packages/tool-adapters/src/migration/plan.ts touches a database area and should be reviewed for regression impact.
• Database area changed (packages/tool-adapters/src/migration/types.ts:1): packages/tool-adapters/src/migration/types.ts touches a database area and should be reviewed for regression impact.

Medium Risk Findings

• High complexity in changed function (packages/cli/src/parsers/migration.ts:5): parseMigrationArgs has estimated cyclomatic complexity 12.
• Config area changed (packages/knowledge/package.json:18): packages/knowledge/package.json touches a config area and should be reviewed for regression impact.
• Config area changed (packages/tool-adapters/package.json:17): packages/tool-adapters/package.json touches a config area and should be reviewed for regression impact.

Low Risk Findings

• Config area changed (pnpm-lock.yaml:151): pnpm-lock.yaml touches a config area and should be reviewed for regression impact.
• Docs area changed (packages/cli/src/docs/command-docs/analysis.ts:4): packages/cli/src/docs/command-docs/analysis.ts touches a docs area and should be reviewed for regression impact.
• Docs area changed (packages/cli/src/docs/command-docs/order.ts:1): packages/cli/src/docs/command-docs/order.ts touches a docs area and should be reviewed for regression impact.
• Source area changed (packages/cli/src/commands/registry.ts:19): packages/cli/src/commands/registry.ts touches a source area and should be reviewed for regression impact.
• Source area changed (packages/cli/src/parsers/args.ts:15): packages/cli/src/parsers/args.ts touches a source area and should be reviewed for regression impact.
• Source area changed (packages/cli/src/types/index.ts:15): packages/cli/src/types/index.ts touches a source area and should be reviewed for regression impact.
• Source area changed (packages/knowledge/src/index.ts:47): packages/knowledge/src/index.ts touches a source area and should be reviewed for regression impact.
• Source area changed (packages/tool-adapters/src/index.ts:4): packages/tool-adapters/src/index.ts touches a source area and should be reviewed for regression impact.
• Test area changed (packages/cli/test/built-cli-migration.test.ts:1): packages/cli/test/built-cli-migration.test.ts touches a test area and should be reviewed for regression impact.
• Test area changed (packages/cli/test/migration.test.ts:1): packages/cli/test/migration.test.ts touches a test area and should be reviewed for regression impact.
• Test area changed (packages/knowledge/test/migration-safety.test.ts:1): packages/knowledge/test/migration-safety.test.ts touches a test area and should be reviewed for regression impact.
• Test area changed (packages/tool-adapters/test/migration.test.ts:1): packages/tool-adapters/test/migration.test.ts touches a test area and should be reviewed for regression impact.

Recommended Checks

• Add an integration test that reaches packages/cli/src/docs/command-docs/order.ts#COMMAND_ORDER without mocking the changed boundary.
• Add an integration test that reaches packages/cli/src/types/index.ts without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/index.ts#MigrationTargetKind without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/index.ts#renderMigrationSafetyMarkdown without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/migration/analyze.ts#AnalyzeMigrationSafetyOptions without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/migration/render.ts#renderMigrationSafetyMarkdown without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/migration/types.ts#MIGRATION_EVIDENCE_SCHEMA_VERSION without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/migration/types.ts#MigrationMatrixState without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/migration/types.ts#MigrationOperationEvidence without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/migration/types.ts#MigrationOperationKind without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/migration/types.ts#MigrationRisk without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/migration/types.ts#MigrationSafetyReport without mocking the changed boundary.

Notes

CodeDecay is deterministic and local-first. This report was generated without telemetry, API keys, LLMs, or model calls.

---

Found by CodeDecay - deterministic, local-first, no telemetry.