feat(db): improve migration status reporting

[joshtrichards]

• Resolves: #

Summary

Improve the migrations:status command so that its output is accurate, easier to interpret, and more useful for diagnosing migration-state inconsistencies.

The command now presents a structured status report with an overall summary, clearer terminology, explicit version states, detailed unapplied migrations, and actionable warnings when migration history references versions missing from the installed code.

Changes

• Replace ambiguous status labels such as “New Migrations” with more precise terminology.
• Group output into configuration, version status, migration count, warning, and unapplied migration sections.
• Add an overall status indicating whether migrations are:
  • up to date
  • unapplied
  • in need of attention
• Distinguish valid boundary states from indeterminate states:
  • None when no previous or next migration exists
  • Unknown when the last executed migration is missing from the installed code
• List every unapplied migration by version, including its name and description when provided.
• Report the specific executed migration versions missing from the installed code.
• Add guidance to verify the installed app/server version rather than editing migration history manually.
• Dynamically align labels for more readable terminal output.
• Add focused tests covering version states, unapplied migration details, and output alignment.

Motivation

The previous output used ambiguous terms and could report that an installation was at the first or latest migration when the current recorded migration was simply unavailable in the installed code. In addition, unnamed migrations were omitted from the pending migration details.

Examples

Database migration status for "core"
====================================

Status: 2 unapplied migrations

Migration configuration
-----------------------
App:                  core
History Table:        oc_migrations
Migration Namespace:  OC\Core\Migrations
Migration Directory:  /var/www/nextcloud/core/Migrations

Version status
--------------
Previous Available:          32000Date20250501090000
Last Recorded as Executed:   33000Date20251210120000
Next Available:              34000Date20260318095645
Latest Available:            34000Date20260402143000

Migration counts
----------------
Recorded as Executed:          33
Missing from Installed Code:    0
Available in Installed Code:   35
Unapplied:                      2

Unapplied migrations
--------------------
34000Date20260318095645
  Name:         Migrate background job arguments
  Description:  Converts background job arguments to the new storage format.

34000Date20260402143000
  Name:         Not provided
  Description:  Not provided

www-data@7851fbf10178:~/html/core/Command/Db$ NC_debug=true  ../../../occ migrations:status activity
Database migration status for "activity"
========================================

Status: Up to date

Migration configuration
-----------------------
App:                  activity
History Table:        oc_migrations
Migration Namespace:  OCA\Activity\Migration
Migration Directory:  /var/www/html/apps/activity/lib/Migration

Version status
--------------
Previous Available:         2011Date20201207091915
Last Recorded as Executed:  8000Date20260603120000
Next Available:             None (at latest available migration)
Latest Available:           8000Date20260603120000

Migration counts
----------------
Recorded as Executed:         12
Missing from Installed Code:  0
Available in Installed Code:  12
Unapplied:                    0

Unapplied migrations
--------------------
None

www-data@7851fbf10178:~/html/core/Command/Db$ NC_debug=true  ../../../occ migrations:status --help  
Description:
  Show the database migration status for an app

Usage:
  migrations:status <app>

Arguments:
  app                   App ID to inspect, or "core" for server migrations

Options:
  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
      --no-warnings     Skip global warnings, show command output only
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  The migrations:status command shows the database migration status
  for core or an installed app.
  
  It reports:
    - migration versions recorded as executed
    - migration files available in the installed code
    - migrations that have not yet been applied
    - executed migrations that are missing from the installed code
  
  This command is read-only. It does not execute migrations or modify migration
  history.
  
  If executed migrations are missing from the installed code, verify that the
  installed app and server code match the intended version. Do not remove records
  from the migration history table manually.
  
  Example:
  
    php occ migrations:status core
www-data@7851fbf10178:~/html/core/Command/Db$ 

Testing

Added tests covering:

• no migrations recorded as executed
• the first available migration
• an intermediate migration
• the latest available migration
• a last executed migration missing from the installed code
• no available migration files
• duplicate and missing migration names and descriptions
• listing every unapplied migration by version
• dynamic terminal-output alignment

TODO

• ...

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)
• Labels added where applicable (ex: bug/enhancement, 3. to review, feature component)
• Milestone added for target branch/version (ex: 32.x for stable32)

AI (if applicable)

• The content of this PR was partly or fully generated using AI