From 9627c43efa447dabd35c7cda521960c48ae10464 Mon Sep 17 00:00:00 2001
From: Rati Rukhadze <rrukhadze@crocobet.com>
Date: Tue, 11 Aug 2026 14:12:36 +0400
Subject: [PATCH] feat: add difflock:report, warn about secret-shaped defaults,
 and show progress on a tty

---
 src/Console/Commands/CheckCommand.php         |   9 +-
 .../Concerns/InteractsWithDifflock.php        |  33 ++
 src/Console/Commands/DiffCommand.php          |  38 +++
 src/Console/Commands/LintCommand.php          |   5 +-
 src/Console/Commands/ReportCommand.php        | 145 +++++++++
 src/Console/Formatters/HtmlReport.php         | 301 ++++++++++++++++++
 src/DifflockServiceProvider.php               |   2 +
 src/Support/SecretHeuristics.php              | 176 ++++++++++
 tests/Feature/ReportAndSecretsTest.php        | 178 +++++++++++
 9 files changed, 885 insertions(+), 2 deletions(-)
 create mode 100644 src/Console/Commands/ReportCommand.php
 create mode 100644 src/Console/Formatters/HtmlReport.php
 create mode 100644 src/Support/SecretHeuristics.php
 create mode 100644 tests/Feature/ReportAndSecretsTest.php

diff --git a/src/Console/Commands/CheckCommand.php b/src/Console/Commands/CheckCommand.php
index 93cad8b..0d194d5 100644
--- a/src/Console/Commands/CheckCommand.php
+++ b/src/Console/Commands/CheckCommand.php
@@ -5,6 +5,7 @@
 namespace Difflock\Console\Commands;
 
 use Difflock\Checkup;
+use Difflock\CheckupResult;
 use Difflock\Console\Commands\Concerns\InteractsWithDifflock;
 use Difflock\Console\Formatters\JsonReport;
 use Difflock\Console\Renderers\Banner;
@@ -74,7 +75,13 @@ public function handle(Checkup $checkup, Repository $config, CheckupRenderer $re
         $connection = $this->option('connection');
 
         try {
-            $result = $checkup->run($threshold, is_string($connection) && $connection !== '' ? $connection : null);
+            $result = $this->whileWorking(
+                'Reading the schema and analysing migrations',
+                fn (): CheckupResult => $checkup->run(
+                    $threshold,
+                    is_string($connection) && $connection !== '' ? $connection : null,
+                ),
+            );
         } catch (Throwable $exception) {
             $this->components->error('Difflock could not complete the check: '.$exception->getMessage());
 
diff --git a/src/Console/Commands/Concerns/InteractsWithDifflock.php b/src/Console/Commands/Concerns/InteractsWithDifflock.php
index f9e4f7d..4dd4dff 100644
--- a/src/Console/Commands/Concerns/InteractsWithDifflock.php
+++ b/src/Console/Commands/Concerns/InteractsWithDifflock.php
@@ -88,6 +88,39 @@ protected function writeJson(array $document): void
         $this->output->writeln(JsonReport::encode($document), OutputInterface::OUTPUT_RAW);
     }
 
+    /**
+     * Run something slow, saying so while it runs.
+     *
+     * Reading a large schema is a few hundred queries and several seconds of silence,
+     * which is long enough for somebody to wonder whether the command has hung. The
+     * notice is written and then erased, so it exists only while the work does.
+     *
+     * Only on a decorated terminal: a CI log has no cursor to move, a JSON document
+     * must not gain a line, and a test buffer should assert on the report rather than
+     * on the reassurance.
+     *
+     * @template TResult
+     *
+     * @param  callable(): TResult  $work
+     * @return TResult
+     */
+    protected function whileWorking(string $message, callable $work): mixed
+    {
+        if (! $this->output->isDecorated() || $this->wantsJson()) {
+            return $work();
+        }
+
+        $this->output->write('  <fg=gray>'.$message.'…</>');
+
+        try {
+            return $work();
+        } finally {
+            // Back to the start of the line, blank it, and back again — so whatever
+            // prints next starts on a clean line rather than after the notice.
+            $this->output->write("\r".str_repeat(' ', mb_strlen($message) + 4)."\r");
+        }
+    }
+
     /**
      * @return list<string>
      */
diff --git a/src/Console/Commands/DiffCommand.php b/src/Console/Commands/DiffCommand.php
index 4655ee8..9fd7ef8 100644
--- a/src/Console/Commands/DiffCommand.php
+++ b/src/Console/Commands/DiffCommand.php
@@ -15,6 +15,8 @@
 use Difflock\Exceptions\InvalidSnapshot;
 use Difflock\Exceptions\MissingBaseline;
 use Difflock\Schema\Baseline;
+use Difflock\Schema\DatabaseSchema;
+use Difflock\Support\SecretHeuristics;
 use Illuminate\Console\Command;
 use Illuminate\Contracts\Config\Repository;
 use Throwable;
@@ -145,6 +147,8 @@ private function save(SchemaInspector $inspector, Baseline $baseline, ?string $c
         $this->output->writeln('  <fg=green>✓</> Baseline recorded: '.$tables.' table'
             .($tables === 1 ? '' : 's').'.');
 
+        $this->warnAboutSecrets($schema);
+
         foreach (Text::wrap('Written to '.$baseline->path().'. Commit it, and future runs of '
             .'difflock:diff will report anything that no longer matches.', '    ') as $line) {
             $this->output->writeln('<fg=gray>'.$line.'</>');
@@ -155,6 +159,40 @@ private function save(SchemaInspector $inspector, Baseline $baseline, ?string $c
         return self::SUCCESS;
     }
 
+    /**
+     * Say so before a column default that looks like a credential goes into git.
+     *
+     * Printed after the file is written rather than before, and it does not refuse:
+     * these are shapes, not certainties, and a tool that blocked on a heuristic
+     * would be wrong often enough to be turned off. Deleting the file and setting
+     * `snapshot.defaults` is a ten-second fix — noticing a year later is not.
+     */
+    private function warnAboutSecrets(DatabaseSchema $schema): void
+    {
+        $suspects = SecretHeuristics::suspects($schema);
+
+        if ($suspects === []) {
+            return;
+        }
+
+        $this->output->writeln('');
+        $this->output->writeln('  <fg=yellow>⚠</> '.count($suspects).' column default'
+            .(count($suspects) === 1 ? '' : 's').' in this file look like they may hold a credential:');
+
+        foreach (SecretHeuristics::describe($suspects) as $described) {
+            $this->output->writeln('    <fg=yellow>·</> '.$described);
+        }
+
+        foreach (Text::wrap(
+            'Difflock recognises shapes, not secrets, so check before you commit. To keep defaults out '
+                .'of the baseline entirely, set `snapshot.defaults` to false in config/difflock.php and '
+                .'record it again.',
+            '    ',
+        ) as $line) {
+            $this->output->writeln('<fg=gray>'.$line.'</>');
+        }
+    }
+
     private function connection(string $option): ?string
     {
         $value = $this->option($option);
diff --git a/src/Console/Commands/LintCommand.php b/src/Console/Commands/LintCommand.php
index 1f61116..d25d5f6 100644
--- a/src/Console/Commands/LintCommand.php
+++ b/src/Console/Commands/LintCommand.php
@@ -100,7 +100,10 @@ public function handle(MigrationAnalyzer $analyzer, Repository $config, ReportRe
         $scope = $this->option('all') === true ? MigrationScope::All : MigrationScope::Pending;
         $paths = $this->paths();
 
-        $report = $analyzer->analyze($scope, $paths);
+        $report = $this->whileWorking(
+            'Analysing migrations',
+            fn (): MigrationReport => $analyzer->analyze($scope, $paths),
+        );
 
         // Nothing pending is the ordinary state of a machine that is up to date, and
         // printing nothing there is how a useful tool gets mistaken for a broken one.
diff --git a/src/Console/Commands/ReportCommand.php b/src/Console/Commands/ReportCommand.php
new file mode 100644
index 0000000..7f01102
--- /dev/null
+++ b/src/Console/Commands/ReportCommand.php
@@ -0,0 +1,145 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Difflock\Console\Commands;
+
+use Difflock\Checkup;
+use Difflock\CheckupResult;
+use Difflock\Console\Commands\Concerns\InteractsWithDifflock;
+use Difflock\Console\Formatters\HtmlReport;
+use Difflock\Console\Formatters\JsonReport;
+use Difflock\Console\Renderers\Banner;
+use Difflock\Console\Renderers\Text;
+use Difflock\Risk\RiskLevel;
+use Illuminate\Console\Command;
+use Illuminate\Contracts\Config\Repository;
+use Illuminate\Filesystem\Filesystem;
+use Throwable;
+
+/**
+ * Writes the whole run — drift and findings — to a file somebody can open.
+ *
+ * The console output is for the person who ran the command. This is for everybody
+ * else: attach it to a pull request, keep it as a CI artifact, send it to whoever
+ * has to approve the deploy. The HTML is entirely self-contained, because an
+ * artifact opened from a `file://` URL has no network to fetch anything with.
+ *
+ * It never changes the verdict — the exit code is the one `difflock:check` would
+ * have given, so a report and a gate can never disagree.
+ */
+final class ReportCommand extends Command
+{
+    use InteractsWithDifflock;
+
+    protected $signature = 'difflock:report
+        {--output= : Where to write the report, default storage/difflock/report.html}
+        {--fail-on= : The lowest risk level that should fail the command}
+        {--connection= : The connection to inspect, overriding the configured one}
+        {--format=html : html for a file somebody opens, json for a machine}';
+
+    protected $description = 'Write the schema drift and migration analysis to a shareable file';
+
+    protected function configure(): void
+    {
+        parent::configure();
+
+        $this->setHelp(<<<'HELP'
+        Runs exactly what <info>difflock:check</info> runs and writes it to a file instead of
+        the terminal, exiting with the same codes.
+
+            php artisan difflock:report
+            php artisan difflock:report --output=build/difflock.html
+
+        The HTML has no external stylesheet, font or script, so it renders correctly
+        as a CI artifact opened straight from disk. Everything in it — table names,
+        column names, rule messages — is escaped, because all of it comes from a
+        database or from migration source rather than from this package.
+
+        <info>--format=json</info> writes the same document as difflock:check, for anything
+        that would rather parse than read.
+        HELP);
+    }
+
+    public function handle(Checkup $checkup, Repository $config, Filesystem $files, HtmlReport $html): int
+    {
+        if (! $this->enabled($config)) {
+            return self::INVALID;
+        }
+
+        $threshold = $this->threshold($config);
+
+        if (! $threshold instanceof RiskLevel) {
+            return $this->unknownThreshold();
+        }
+
+        $connection = $this->option('connection');
+
+        try {
+            $result = $this->whileWorking(
+                'Building the report',
+                fn (): CheckupResult => $checkup->run(
+                    $threshold,
+                    is_string($connection) && $connection !== '' ? $connection : null,
+                ),
+            );
+        } catch (Throwable $exception) {
+            $this->components->error('Difflock could not complete the report: '.$exception->getMessage());
+
+            return self::INVALID;
+        }
+
+        $json = $this->option('format') === 'json';
+        $path = $this->path($json);
+
+        $files->ensureDirectoryExists(dirname($path));
+        $files->put($path, $json
+            ? JsonReport::encode(JsonReport::check($result->drift, $result->report, $threshold, $result->failed()))."\n"
+            : $html->render($result, $this->generatedAt(), $this->application($config)));
+
+        Banner::render($this->output, 'Difflock  ·  Report');
+
+        $this->output->writeln('  <fg=green>✓</> Written to '.$path);
+
+        foreach (Text::wrap(
+            $result->failed()
+                ? 'The run failed — the report says why, and this command exits with the same code '
+                    .'difflock:check would have.'
+                : 'Nothing at or above the threshold.',
+            '    ',
+        ) as $line) {
+            $this->output->writeln('<fg=gray>'.$line.'</>');
+        }
+
+        $this->output->writeln('');
+
+        return $result->failed() ? self::FAILURE : self::SUCCESS;
+    }
+
+    private function path(bool $json): string
+    {
+        $output = $this->option('output');
+
+        if (is_string($output) && $output !== '') {
+            return $this->absolute($output);
+        }
+
+        return $this->laravel->storagePath('difflock/report.'.($json ? 'json' : 'html'));
+    }
+
+    /**
+     * A fixed-format timestamp rather than a localised one, so two reports of the
+     * same run diff cleanly.
+     */
+    private function generatedAt(): string
+    {
+        return gmdate('Y-m-d H:i').' UTC';
+    }
+
+    private function application(Repository $config): ?string
+    {
+        $name = $config->get('app.name');
+
+        return is_string($name) && $name !== '' ? $name : null;
+    }
+}
diff --git a/src/Console/Formatters/HtmlReport.php b/src/Console/Formatters/HtmlReport.php
new file mode 100644
index 0000000..e0ce459
--- /dev/null
+++ b/src/Console/Formatters/HtmlReport.php
@@ -0,0 +1,301 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Difflock\Console\Formatters;
+
+use Difflock\CheckupResult;
+use Difflock\Diff\ChangeType;
+use Difflock\Diff\SchemaDiff;
+use Difflock\Diff\TableDiff;
+use Difflock\Migration\MigrationFinding;
+use Difflock\Risk\RiskLevel;
+
+/**
+ * The whole of a Difflock run as one self-contained HTML file.
+ *
+ * Built for the place these reports actually get read: a CI artifact somebody opens
+ * from a pull request. That constrains it more than it might seem.
+ *
+ * **Nothing is fetched.** No stylesheet, no font, no script — a build artifact
+ * opened from a `file://` URL has no network, and a report that renders as unstyled
+ * text in the one context it exists for is a report nobody opens twice.
+ *
+ * **Everything is escaped.** Table names, column names and rule messages all come
+ * from a database and from migration source, neither of which this package controls.
+ * A column called `<script>` must render as a column called `<script>`.
+ *
+ * **It reads in both themes**, because half of the people opening it will be in a
+ * dark one and the other half will not.
+ */
+final class HtmlReport
+{
+    public function render(CheckupResult $result, string $generatedAt, ?string $application = null): string
+    {
+        $summary = $result->report->summary();
+        $failed = $result->failed();
+
+        $title = 'Difflock report'.($application === null ? '' : ' — '.$application);
+
+        return implode("\n", [
+            '<!doctype html>',
+            '<html lang="en"><head><meta charset="utf-8">',
+            '<meta name="viewport" content="width=device-width, initial-scale=1">',
+            '<title>'.$this->escape($title).'</title>',
+            '<style>'.$this->styles().'</style>',
+            '</head><body><main>',
+            '<header class="head">',
+            '<h1>Difflock</h1>',
+            '<p class="verdict '.($failed ? 'fail' : 'pass').'">'.($failed ? 'FAIL' : 'PASS').'</p>',
+            '<p class="meta">'.$this->escape($generatedAt)
+                .($application === null ? '' : ' · '.$this->escape($application)).'</p>',
+            '</header>',
+            $this->tally($summary->counts, $summary->total, count($result->report->accepted)),
+            $this->schema($result),
+            $this->findings($result->report->findings),
+            $this->warnings($result->report->warnings(), $result->report->databaseAvailable),
+            '<footer>Difflock analyses migration source statically and reads the live schema. '
+                .'It reports what it could not determine rather than guessing.</footer>',
+            '</main></body></html>',
+        ]);
+    }
+
+    /**
+     * @param  array<string, int>  $counts
+     */
+    private function tally(array $counts, int $total, int $accepted): string
+    {
+        $cells = '';
+
+        foreach (RiskLevel::ascending() as $level) {
+            $count = $counts[$level->value] ?? 0;
+
+            $cells .= '<div class="stat '.$level->value.($count > 0 ? ' on' : '').'">'
+                .'<span class="n">'.$count.'</span>'
+                .'<span class="l">'.$this->escape(ucfirst($level->value)).'</span></div>';
+        }
+
+        $note = $accepted > 0
+            ? '<p class="meta">'.$accepted.' previously accepted finding'.($accepted === 1 ? '' : 's')
+                .' not shown.</p>'
+            : '';
+
+        return '<section><h2>Risk</h2><div class="stats">'.$cells.'</div>'
+            .'<p class="meta">'.$total.' finding'.($total === 1 ? '' : 's').'.</p>'.$note.'</section>';
+    }
+
+    private function schema(CheckupResult $result): string
+    {
+        if ($result->baselineError !== null) {
+            return '<section><h2>Schema</h2><p class="bad">The recorded baseline could not be read: '
+                .$this->escape($result->baselineError).'</p></section>';
+        }
+
+        if (! $result->baselineRecorded) {
+            return '<section><h2>Schema</h2><p class="muted">No baseline recorded, so drift was not '
+                .'checked. Record one with <code>php artisan difflock:diff --save</code>.</p></section>';
+        }
+
+        if (! $result->drifted() || ! $result->drift instanceof SchemaDiff) {
+            return '<section><h2>Schema</h2><p class="good">No drift detected.</p></section>';
+        }
+
+        $body = '';
+
+        foreach ($result->drift->tables as $table) {
+            $body .= $this->table($table);
+        }
+
+        return '<section><h2>Schema drift</h2><p class="meta">'.$result->drift->count()
+            .' difference'.($result->drift->count() === 1 ? '' : 's').' from the baseline.</p>'
+            .$body.'</section>';
+    }
+
+    private function table(TableDiff $table): string
+    {
+        $rows = '';
+
+        foreach ($table->columns as $column) {
+            $rows .= $this->change($column->type, $column->name,
+                $column->to?->render() ?? $column->from?->render() ?? '');
+        }
+
+        foreach ($table->indexes as $index) {
+            $rows .= $this->change($index->type, $index->name,
+                $index->to?->render() ?? $index->from?->render() ?? '');
+        }
+
+        foreach ($table->foreignKeys as $key) {
+            $rows .= $this->change($key->type, $key->name,
+                $key->to?->render() ?? $key->from?->render() ?? '');
+        }
+
+        if ($table->type !== ChangeType::Changed) {
+            $rows = $this->change($table->type, 'table '.$table->type->value, '');
+        }
+
+        return '<div class="tbl"><h3>'.$this->escape($table->name).'</h3>'.$rows.'</div>';
+    }
+
+    private function change(ChangeType $type, string $name, string $detail): string
+    {
+        return '<div class="chg '.$type->value.'"><span class="mk">'.$this->escape($type->marker()).'</span>'
+            .'<span class="nm">'.$this->escape($name).'</span>'
+            .($detail === '' ? '' : '<span class="dt">'.$this->escape($detail).'</span>').'</div>';
+    }
+
+    /**
+     * Findings grouped exactly as the console groups them — by rule, risk and the
+     * prose they carry — so the two renderings never tell different stories.
+     *
+     * @param  list<MigrationFinding>  $findings
+     */
+    private function findings(array $findings): string
+    {
+        if ($findings === []) {
+            return '<section><h2>Migrations</h2><p class="good">Nothing to report.</p></section>';
+        }
+
+        $groups = [];
+
+        foreach ($findings as $finding) {
+            $groups[$finding->risk->value."\0".$finding->rule."\0".$finding->explanation][] = $finding;
+        }
+
+        $body = '';
+
+        foreach ($groups as $group) {
+            $first = $group[0];
+            $count = count($group);
+
+            $occurrences = '';
+
+            foreach ($group as $finding) {
+                $occurrences .= '<li><span class="msg">'.$this->escape($finding->message).'</span>'
+                    .'<span class="where">'.$this->escape($finding->migration)
+                    .($finding->line === null ? '' : ':'.$finding->line).'</span>'
+                    .$this->flags($finding).'</li>';
+            }
+
+            $body .= '<article class="grp '.$first->risk->value.'">'
+                .'<h3><span class="pill '.$first->risk->value.'">'.$this->escape($first->risk->label()).'</span> '
+                .$this->escape($first->rule)
+                .($count === 1 ? '' : ' <span class="muted">'.$count.' findings</span>').'</h3>'
+                .'<p>'.$this->escape($first->explanation).'</p>'
+                .($first->suggestion === null ? '' : '<p class="fix">'.$this->escape($first->suggestion).'</p>')
+                .'<ul>'.$occurrences.'</ul></article>';
+        }
+
+        return '<section><h2>Migrations</h2>'.$body.'</section>';
+    }
+
+    private function flags(MigrationFinding $finding): string
+    {
+        $flags = '';
+
+        if ($finding->destructive) {
+            $flags .= '<span class="flag bad">destructive</span>';
+        }
+
+        if (! $finding->reversible) {
+            $flags .= '<span class="flag bad">not reversible</span>';
+        }
+
+        if ($finding->conditional) {
+            $flags .= '<span class="flag">conditional</span>';
+        }
+
+        return $flags;
+    }
+
+    /**
+     * @param  list<string>  $warnings
+     */
+    private function warnings(array $warnings, bool $available): string
+    {
+        if ($warnings === [] && $available) {
+            return '';
+        }
+
+        $items = $available
+            ? ''
+            : '<li>The database could not be reached, so no finding took table size or the live schema '
+                .'into account.</li>';
+
+        foreach ($warnings as $warning) {
+            $items .= '<li>'.$this->escape($warning).'</li>';
+        }
+
+        return '<section><h2>Not fully analysed</h2><ul class="warn">'.$items.'</ul></section>';
+    }
+
+    private function escape(string $value): string
+    {
+        return htmlspecialchars($value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
+    }
+
+    private function styles(): string
+    {
+        return <<<'CSS'
+        :root{--bg:#fff;--fg:#16181d;--mut:#666e7a;--line:#e4e7ec;--card:#f8f9fb;
+        --safe:#2f855a;--low:#2b6cb0;--medium:#b7791f;--high:#c05621;--critical:#c53030}
+        @media(prefers-color-scheme:dark){:root{--bg:#14161a;--fg:#e6e8ec;--mut:#9aa3ae;
+        --line:#2a2e36;--card:#1b1e24;--safe:#68d391;--low:#63b3ed;--medium:#f6ad55;
+        --high:#fc8181;--critical:#feb2b2}}
+        *{box-sizing:border-box}
+        body{margin:0;background:var(--bg);color:var(--fg);
+        font:15px/1.6 ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif}
+        main{max-width:60rem;margin:0 auto;padding:2.5rem 1.25rem 4rem}
+        h1{font-size:1.6rem;margin:0}
+        h2{font-size:1rem;text-transform:uppercase;letter-spacing:.08em;color:var(--mut);
+        margin:2.5rem 0 .75rem;padding-bottom:.4rem;border-bottom:1px solid var(--line)}
+        h3{font-size:1rem;margin:0 0 .5rem}
+        .head{display:flex;align-items:baseline;gap:.75rem;flex-wrap:wrap}
+        .verdict{font-weight:700;letter-spacing:.06em;margin:0}
+        .verdict.pass{color:var(--safe)}.verdict.fail{color:var(--critical)}
+        .meta,.muted{color:var(--mut);font-size:.875rem;margin:.25rem 0}
+        .good{color:var(--safe)}.bad{color:var(--critical)}
+        .stats{display:flex;flex-wrap:wrap;gap:.5rem}
+        .stat{flex:1 1 6rem;background:var(--card);border:1px solid var(--line);
+        border-radius:.5rem;padding:.75rem;text-align:center;opacity:.55}
+        .stat.on{opacity:1}
+        .stat .n{display:block;font-size:1.5rem;font-weight:700}
+        .stat .l{display:block;font-size:.75rem;color:var(--mut);text-transform:uppercase;
+        letter-spacing:.06em}
+        .stat.safe .n{color:var(--safe)}.stat.low .n{color:var(--low)}
+        .stat.medium .n{color:var(--medium)}.stat.high .n{color:var(--high)}
+        .stat.critical .n{color:var(--critical)}
+        .grp{background:var(--card);border:1px solid var(--line);border-left-width:3px;
+        border-radius:.5rem;padding:1rem;margin:0 0 .75rem}
+        .grp.safe{border-left-color:var(--safe)}.grp.low{border-left-color:var(--low)}
+        .grp.medium{border-left-color:var(--medium)}.grp.high{border-left-color:var(--high)}
+        .grp.critical{border-left-color:var(--critical)}
+        .grp p{margin:.4rem 0}
+        .fix{color:var(--mut)}.fix::before{content:"→ "}
+        .pill{font-size:.7rem;font-weight:700;letter-spacing:.06em;padding:.1rem .45rem;
+        border-radius:.25rem;border:1px solid currentColor}
+        .pill.safe{color:var(--safe)}.pill.low{color:var(--low)}
+        .pill.medium{color:var(--medium)}.pill.high{color:var(--high)}
+        .pill.critical{color:var(--critical)}
+        .grp ul{list-style:none;margin:.75rem 0 0;padding:0;font-size:.875rem}
+        .grp li{padding:.3rem 0;border-top:1px solid var(--line);display:flex;
+        gap:.5rem;flex-wrap:wrap;align-items:baseline}
+        .msg{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
+        .where{color:var(--mut);font-size:.8rem}
+        .flag{font-size:.7rem;color:var(--mut);border:1px solid var(--line);
+        border-radius:.25rem;padding:0 .3rem}
+        .flag.bad{color:var(--critical)}
+        .tbl{margin:0 0 1rem}
+        .chg{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.85rem;
+        display:flex;gap:.5rem;padding:.15rem 0}
+        .chg .mk{width:1ch;font-weight:700}
+        .chg.added .mk{color:var(--safe)}.chg.removed .mk{color:var(--critical)}
+        .chg.changed .mk{color:var(--medium)}
+        .dt{color:var(--mut)}
+        .warn{color:var(--medium);font-size:.875rem}
+        code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.85em}
+        footer{margin-top:3rem;padding-top:1rem;border-top:1px solid var(--line);
+        color:var(--mut);font-size:.8rem}
+        CSS;
+    }
+}
diff --git a/src/DifflockServiceProvider.php b/src/DifflockServiceProvider.php
index 4da2220..f0469a3 100644
--- a/src/DifflockServiceProvider.php
+++ b/src/DifflockServiceProvider.php
@@ -10,6 +10,7 @@
 use Difflock\Console\Commands\DoctorCommand;
 use Difflock\Console\Commands\LintCommand;
 use Difflock\Console\Commands\MigrateCommand;
+use Difflock\Console\Commands\ReportCommand;
 use Difflock\Contracts\MigrationAnalyzer;
 use Difflock\Contracts\MigrationRule;
 use Difflock\Contracts\SchemaDiffer;
@@ -173,6 +174,7 @@ public function boot(): void
             DoctorCommand::class,
             LintCommand::class,
             MigrateCommand::class,
+            ReportCommand::class,
         ]);
 
         $this->publishes([
diff --git a/src/Support/SecretHeuristics.php b/src/Support/SecretHeuristics.php
new file mode 100644
index 0000000..7481c8e
--- /dev/null
+++ b/src/Support/SecretHeuristics.php
@@ -0,0 +1,176 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Difflock\Support;
+
+use Difflock\Schema\Column;
+use Difflock\Schema\DatabaseSchema;
+
+/**
+ * Column defaults that look like they might be credentials.
+ *
+ * The baseline is the one file Difflock asks you to commit, and a column default is
+ * the one place in a schema where an arbitrary string ends up. Most of them are
+ * `'draft'` or `0`. Occasionally one is a connection string with a password in it,
+ * or an API key somebody set as a default "temporarily" in 2023 — and committing
+ * that puts it in git history permanently, where deleting it later does not remove
+ * it.
+ *
+ * ## Heuristics, and their limits
+ *
+ * This recognises *shapes*, not secrets. It cannot know whether a long hex string is
+ * a key or a checksum, and it will never catch a credential that looks like an
+ * ordinary word. It is a prompt before a one-way action, not a scanner, and it is
+ * deliberately tuned to stay quiet: a false positive on every `difflock:diff --save`
+ * would train people to ignore the one that mattered.
+ *
+ * Function-call defaults are skipped entirely. `nextval(...)`, `gen_random_uuid()`
+ * and `CURRENT_TIMESTAMP` are the overwhelming majority of exotic-looking defaults
+ * and none of them can carry a secret.
+ */
+final class SecretHeuristics
+{
+    /**
+     * Prefixes that identify a credential on sight, published by the services that
+     * issue them precisely so they can be recognised.
+     *
+     * @var array<string, string>
+     */
+    private const array PREFIXES = [
+        '-----BEGIN' => 'a PEM-encoded private key',
+        'sk_live_' => 'a live Stripe secret key',
+        'sk_test_' => 'a Stripe test secret key',
+        'rk_live_' => 'a live Stripe restricted key',
+        'ghp_' => 'a GitHub personal access token',
+        'gho_' => 'a GitHub OAuth token',
+        'github_pat_' => 'a GitHub personal access token',
+        'glpat-' => 'a GitLab personal access token',
+        'xoxb-' => 'a Slack bot token',
+        'xoxp-' => 'a Slack user token',
+        'AKIA' => 'an AWS access key id',
+        'ASIA' => 'an AWS temporary access key id',
+        'AIza' => 'a Google API key',
+        'SG.' => 'a SendGrid API key',
+    ];
+
+    /**
+     * Every column default in the schema that looks like it should not be published.
+     *
+     * @return list<array{table: string, column: string, reason: string}>
+     */
+    public static function suspects(DatabaseSchema $schema): array
+    {
+        $suspects = [];
+
+        foreach ($schema->tables as $table) {
+            foreach ($table->columns as $column) {
+                $reason = self::reason($column);
+
+                if ($reason !== null) {
+                    $suspects[] = ['table' => $table->name, 'column' => $column->name, 'reason' => $reason];
+                }
+            }
+        }
+
+        return $suspects;
+    }
+
+    /** Why this column's default looks like a credential, or null if it does not. */
+    public static function reason(Column $column): ?string
+    {
+        $value = self::normalise($column->default);
+
+        if ($value === null) {
+            return null;
+        }
+
+        foreach (self::PREFIXES as $prefix => $describes) {
+            if (str_starts_with($value, $prefix)) {
+                return $describes;
+            }
+        }
+
+        if (self::hasCredentialsInUrl($value)) {
+            return 'a URL with a username and password in it';
+        }
+
+        if (preg_match('/\b(password|passwd|secret|api[_-]?key|access[_-]?token)\s*=\s*\S/i', $value) === 1) {
+            return 'a connection string or query carrying a credential';
+        }
+
+        if (self::looksRandom($value)) {
+            return 'a long random-looking string';
+        }
+
+        return null;
+    }
+
+    /**
+     * The default as the value itself: quotes removed, and any driver type cast
+     * dropped from the end.
+     *
+     * PostgreSQL reports `'draft'::character varying`, MySQL reports `draft`. Both
+     * reduce to `draft`, and a default that is a function call reduces to nothing —
+     * `now()` cannot hold a secret and neither can `nextval('users_id_seq')`.
+     */
+    private static function normalise(?string $default): ?string
+    {
+        if ($default === null) {
+            return null;
+        }
+
+        $value = trim($default);
+
+        // Drop a trailing PostgreSQL cast before anything else, so the quotes it sits
+        // outside of can still be stripped.
+        $value = (string) preg_replace('/::[a-z0-9_ ]+$/i', '', $value);
+        $value = trim($value);
+
+        if (strlen($value) >= 2 && ($value[0] === "'" || $value[0] === '"') && $value[-1] === $value[0]) {
+            $value = substr($value, 1, -1);
+        }
+
+        // A function call, not a literal.
+        if (str_contains($value, '(')) {
+            return null;
+        }
+
+        return $value === '' ? null : $value;
+    }
+
+    private static function hasCredentialsInUrl(string $value): bool
+    {
+        return preg_match('#^[a-z][a-z0-9+.-]*://[^/\s:@]+:[^/\s@]+@#i', $value) === 1;
+    }
+
+    /**
+     * Whether the value looks like it was generated rather than typed.
+     *
+     * Long, unbroken, and drawn from an alphabet a person would not choose for a
+     * default. The length floor is what keeps `draft`, `pending` and `en_GB` out,
+     * and the "no spaces" requirement keeps sentences out.
+     */
+    private static function looksRandom(string $value): bool
+    {
+        if (strlen($value) < 32 || str_contains($value, ' ')) {
+            return false;
+        }
+
+        // Hex or base64/base64url, entirely — the shape of a generated key.
+        return preg_match('/^[a-f0-9]{32,}$/i', $value) === 1
+            || preg_match('/^[A-Za-z0-9+\/_-]{32,}={0,2}$/', $value) === 1;
+    }
+
+    /**
+     * @param  list<array{table: string, column: string, reason: string}>  $suspects
+     * @return list<string>
+     */
+    public static function describe(array $suspects): array
+    {
+        return array_map(
+            static fn (array $suspect): string => $suspect['table'].'.'.$suspect['column'].' — '.$suspect['reason'],
+            $suspects,
+        );
+    }
+}
diff --git a/tests/Feature/ReportAndSecretsTest.php b/tests/Feature/ReportAndSecretsTest.php
new file mode 100644
index 0000000..c4a1b9b
--- /dev/null
+++ b/tests/Feature/ReportAndSecretsTest.php
@@ -0,0 +1,178 @@
+<?php
+
+declare(strict_types=1);
+
+use Difflock\Schema\Column;
+use Difflock\Schema\DatabaseSchema;
+use Difflock\Schema\Table;
+use Difflock\Support\SecretHeuristics;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+beforeEach(function (): void {
+    Schema::create('users', function (Blueprint $table): void {
+        $table->id();
+        $table->string('legacy_token')->nullable();
+    });
+
+    Schema::create('orders', function (Blueprint $table): void {
+        $table->id();
+        $table->unsignedBigInteger('customer_id');
+    });
+
+    config()->set('difflock.migrations.paths', [fixtures()]);
+});
+
+afterEach(function (): void {
+    $report = storage_path('difflock');
+
+    if (is_dir($report)) {
+        foreach (glob($report.'/*') ?: [] as $file) {
+            unlink($file);
+        }
+
+        rmdir($report);
+    }
+});
+
+describe('difflock:report', function (): void {
+    it('writes a self-contained html file and keeps the check exit code', function (): void {
+        [$exit, $output] = runCommand('difflock:report');
+
+        $path = storage_path('difflock/report.html');
+
+        expect($exit)->toBe(1)
+            ->and($output)->toContain('Written to')
+            ->and(file_exists($path))->toBeTrue();
+
+        $html = file_get_contents($path);
+
+        expect($html)->toStartWith('<!doctype html>')
+            ->toContain('DROP COLUMN users.legacy_token')
+            ->toContain('drop-column')
+            ->toContain('FAIL');
+
+        // Nothing may be fetched: a CI artifact opened from disk has no network.
+        expect($html)->not->toContain('<script')
+            ->and($html)->not->toContain('http://')
+            ->and($html)->not->toContain('https://');
+    });
+
+    it('escapes everything, because none of it is Difflock\'s text', function (): void {
+        Schema::create('x<script>', fn (Blueprint $table) => $table->id());
+
+        runCommand('difflock:diff', ['--save' => true]);
+        Schema::drop('x<script>');
+
+        runCommand('difflock:report');
+
+        $html = file_get_contents(storage_path('difflock/report.html'));
+
+        expect($html)->toContain('x&lt;script&gt;')
+            ->and($html)->not->toContain('<script>');
+    });
+
+    it('writes wherever it is told', function (): void {
+        [$exit] = runCommand('difflock:report', ['--output' => 'storage/difflock/custom.html']);
+
+        expect($exit)->toBe(1)
+            ->and(file_exists(base_path('storage/difflock/custom.html')))->toBeTrue();
+    });
+
+    it('writes the same json document difflock:check emits', function (): void {
+        runCommand('difflock:report', ['--format' => 'json']);
+
+        $document = json_decode(file_get_contents(storage_path('difflock/report.json')), true, flags: JSON_THROW_ON_ERROR);
+
+        expect($document)->toHaveKeys(['difflock', 'status', 'risk', 'threshold', 'schema', 'migrations'])
+            ->and($document['status'])->toBe('failed');
+    });
+
+    it('passes and says so when nothing crosses the threshold', function (): void {
+        config()->set('difflock.migrations.paths', [fixtures('safe')]);
+        runCommand('difflock:diff', ['--save' => true]);
+
+        [$exit] = runCommand('difflock:report');
+
+        expect($exit)->toBe(0)
+            ->and(file_get_contents(storage_path('difflock/report.html')))->toContain('PASS');
+    });
+
+    it('refuses to run when Difflock is disabled', function (): void {
+        config()->set('difflock.enabled', false);
+
+        expect(runCommand('difflock:report')[0])->toBe(2);
+    });
+});
+
+describe('secret heuristics', function (): void {
+    it('recognises credentials by shape', function (string $default, string $reason): void {
+        $column = new Column('api_key', 'varchar', 'varchar(255)', true, $default);
+
+        expect(SecretHeuristics::reason($column))->toContain($reason);
+    })->with([
+        ["'sk_live_51H8xQ2eZvKYlo2C'", 'Stripe'],
+        ["'ghp_16C7e42F292c6912E7710c838347Ae178B4a'", 'GitHub'],
+        ["'AKIAIOSFODNN7EXAMPLE'", 'AWS'],
+        ["'-----BEGIN RSA PRIVATE KEY-----'", 'private key'],
+        ["'postgres://admin:hunter2@db.internal:5432/app'", 'username and password'],
+        ["'d41d8cd98f00b204e9800998ecf8427ed41d8cd9'", 'random-looking'],
+        ["'host=db password=hunter2'", 'credential'],
+    ]);
+
+    /**
+     * The heuristics are only useful if they stay quiet. A warning on every ordinary
+     * default trains people to ignore the one that matters.
+     */
+    it('stays quiet about ordinary defaults', function (string $default): void {
+        expect(SecretHeuristics::reason(new Column('c', 'varchar', 'varchar(255)', true, $default)))
+            ->toBeNull();
+    })->with([
+        "'draft'",
+        "'pending'::character varying",
+        '0',
+        'CURRENT_TIMESTAMP',
+        "nextval('users_id_seq'::regclass)",
+        'gen_random_uuid()',
+        "'en_GB'",
+        "'a short sentence that is long enough to pass a length check but has spaces'",
+    ]);
+
+    it('says nothing when a column has no default at all', function (): void {
+        expect(SecretHeuristics::reason(new Column('c', 'varchar', 'varchar(255)', true)))->toBeNull();
+    });
+
+    it('finds suspects across a whole schema', function (): void {
+        $schema = new DatabaseSchema([
+            new Table('a', [new Column('token', 'varchar', 'varchar(255)', true, "'ghp_16C7e42F292c6912E7710c838347Ae178B4a'")]),
+            new Table('b', [new Column('status', 'varchar', 'varchar(255)', true, "'draft'")]),
+        ]);
+
+        $suspects = SecretHeuristics::suspects($schema);
+
+        expect($suspects)->toHaveCount(1)
+            ->and($suspects[0]['table'])->toBe('a')
+            ->and($suspects[0]['column'])->toBe('token')
+            ->and(SecretHeuristics::describe($suspects)[0])->toContain('a.token');
+    });
+
+    it('warns when recording a baseline that would publish one', function (): void {
+        Schema::create('integrations', function (Blueprint $table): void {
+            $table->id();
+            $table->string('api_key')->default('ghp_16C7e42F292c6912E7710c838347Ae178B4a');
+        });
+
+        [$exit, $output] = runCommand('difflock:diff', ['--save' => true]);
+
+        expect($exit)->toBe(0)
+            ->and($output)->toContain('may hold a credential')
+            ->toContain('integrations.api_key')
+            ->toContain('snapshot.defaults');
+    });
+
+    it('says nothing when recording an ordinary schema', function (): void {
+        [, $output] = runCommand('difflock:diff', ['--save' => true]);
+
+        expect($output)->not->toContain('may hold a credential');
+    });
+});