feat(diff): add --normalized-diff option to DiffCommand

- Introduced a new command line option `--normalized-diff` in `DiffCommandSettings` to control the normalization of diff output.
- Updated `RunDiff` method in `ISyncCommandService` and its implementation to accept a new parameter for normalized diff.
- Modified the `SyncCommandService` to handle normalized diff logic in the diff generation process.
- Enhanced the `BuildUnifiedDiff` method to support normalized diff rendering.
- Updated tests to verify the behavior of the new normalized diff feature.

Author: zacateras

CHANGELOG.md

@@ -22,6 +22,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - Treat equivalent extended-property blocks as compatible during comparison when the normalized `sp_addextendedproperty` statements differ only by ordering, argument spacing, or named-vs-positional argument forms within the same contiguous block.
 - Treat leading SSMS-generated banner comments on programmable objects as compatible during comparison.
 - Treat redundant empty or otherwise no-op `GO` batches as compatible during comparison.
+- Keep `diff` output readable by rendering compatible `Table` and `UserDefinedType` changes from readable script text instead of opaque comparison-normalized text.
+- Keep readable `diff` output for `Table` and table-valued `UserDefinedType` bodies at per-entry granularity instead of collapsing the entire body into one changed line.
+- Align readable `Table` and table-valued `UserDefinedType` diffs by individual body entries so a single changed column or inline constraint does not mark the entire body as changed.
 - Treat legacy explicit `NULL` tokens on CLR table-valued function return columns as compatible during comparison and preserve them during compatibility reconciliation when the rest of the definition matches.
 - Trailing semicolon differences on `INSERT` statement lines in data scripts are now suppressed during comparison normalization; scripts emitted with and without statement terminators compare as compatible (#47).
 - Legacy `TableData` scripts now compare as compatible when they differ from canonical output only by `SET IDENTITY_INSERT` semicolons or top-level `N'...'` string literal prefixes, including inside multi-line `INSERT ... VALUES (...)` statements.
@@ -42,6 +45,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - Next-steps suggestions are printed after `sqlct init` to guide users toward `pull`, `status`, and `diff` (#36).
 - Add `--object <selector>` to `sqlct pull` for exact-match filtering using the same selector forms as `diff --object` (#35).
 - Add `--filter <pattern>` to `sqlct pull` for regex-based filtering; multiple patterns may be provided and matching is case-insensitive (#35).
+- Add `--normalized-diff` to `sqlct diff` to render comparison-normalized diff text for debugging while preserving readable diff output by default.
 - Add `--filter <pattern>` to `sqlct diff` for regex-based filtering; without `--object` filters the output to matching objects, with `--object` additionally constrains the single-object result (#35).
 - SQL Authentication support: set `database.auth` to `"sql"` and supply `database.user` (and optionally `database.password`) in `sqlct.config.json` to connect using SQL Server Authentication (#30).
 - Support active object type `Assembly`, with deterministic scripting to `Assemblies/*.sql` for user-defined SQL Server assemblies.

README.md

@@ -23,7 +23,7 @@ validate configuration, and generate reproducible scripts for Git and CI/CD.
 - `sqlct data untrack [<pattern>] [--object <pattern>] [--filter <regex>] [--project-dir <path>]`
 - `sqlct data list [--project-dir <path>]`
 - `sqlct status [--project-dir <path>] [--target <db|folder>]`
-- `sqlct diff [--project-dir <path>] [--target <db|folder>] [--object <selector>] [--filter <pattern>...] [--context <N>]`
+- `sqlct diff [--project-dir <path>] [--target <db|folder>] [--object <selector>] [--filter <pattern>...] [--context <N>] [--normalized-diff]`
 - `sqlct pull [--project-dir <path>] [--object <selector>] [--filter <pattern>...]`
 
 Current runtime scope for `status`, `diff`, and `pull` covers:

specs/01-cli.md

@@ -224,7 +224,7 @@ Behavior:
 ### diff
 Show textual diffs.
 `
-sqlct diff [--project-dir <path>] [--target <db|folder>] [--object <selector>] [--filter <pattern>...] [--context <N>]
+sqlct diff [--project-dir <path>] [--target <db|folder>] [--object <selector>] [--filter <pattern>...] [--context <N>] [--normalized-diff]
 `
 Behavior:
 - Compare object script from DB vs folder.
@@ -234,6 +234,8 @@ Behavior:
 - Changed objects use DB-vs-folder unified diff.
 - Added/deleted objects use empty-side vs script-side unified diff.
 - Normalization includes line-ending/trailing-newline stability plus explicitly listed compatibility rules for deterministic comparison.
+- Displayed diff hunks SHOULD preserve readable script text where possible and MUST NOT fall back to opaque comparison-normalized formatting when a readable compatibility-preserving representation is available.
+- For `Table` and table-valued `UserDefinedType` scripts, readable diff rendering SHOULD preserve structural body boundaries so column and inline-constraint changes remain pinpointed within the body instead of collapsing the entire statement into one changed line.
 - Empty lines are ignored during comparison, and whitespace-only lines are normalized to empty lines first so blank separators differing only by spaces or tabs compare as compatible.
 - Redundant empty or no-op `GO` batches compare as compatible.
 - Trailing semicolons on `INSERT` statement lines are stripped during normalization; scripts emitted with and without statement terminators compare as compatible.
@@ -249,6 +251,7 @@ Behavior:
 - Leading SSMS-generated object banner comments on programmable objects (`StoredProcedure`, `View`, `Function`, `Trigger`) compare as compatible.
 - Diff output uses a chunked format: only changed lines and their surrounding context are shown, not the entire file.
 - `--context <N>` controls the number of unchanged context lines shown before and after each changed segment (default: 3). Negative values are treated as 0.
+- `--normalized-diff` switches diff rendering to the exact comparison-normalized text used for compatibility evaluation. It is intended for debugging and is off by default.
 - When two change segments are close enough that their context regions overlap, they are merged into a single hunk.
 - Each hunk is prefixed with a `@@ -l,s +l,s @@` header indicating the source and target line ranges.
 - When `data.trackedTables` is configured, `diff` also supports data-script diffs for tracked tables.

specs/04-scripting.md

@@ -812,6 +812,8 @@ When compatibility reference files are available, `sqlct` MAY apply reconciliati
 - Script generation MUST emit canonical scripting output per this document and MUST NOT include diff/status-specific normalization.
 - `status` and `diff` normalization behaviors are external contracts defined in `specs/01-cli.md` and `specs/05-output-formats.md`.
 - Scripting and comparison normalization responsibilities MUST remain decoupled.
+- Diff rendering MAY use comparison-normalized keys to identify compatible changes, but emitted diff text SHOULD remain human-readable and SHOULD prefer readable compatibility-preserving representations over opaque comparison-normalized forms.
+- For `Table` and table-valued `UserDefinedType` statements, readable diff rendering SHOULD retain structural body boundaries so body entries can diff at per-entry granularity when the compatibility-preserving representation exposes them.
 - Empty lines MUST be ignored during comparison, and whitespace-only lines MUST be normalized to empty lines first so that blank separators differing only by spaces or tabs compare as compatible.
 - Comparison normalization MAY ignore redundant empty or otherwise no-op `GO` batches, including batches that contain only standalone semicolon lines.
 - Trailing semicolons on `INSERT` statement lines MUST be stripped by comparison normalization so that scripts emitted with and without statement terminators compare as compatible.

src/SqlChangeTracker/Commands/DiffCommand.cs

@@ -16,7 +16,7 @@ public override int Execute(CommandContext context, DiffCommandSettings settings
         var output = new OutputFormatter(settings.Json);
         var showProgress = !settings.Json && !settings.NoProgress;
         var result = ProgressRunner.Run("Running diff...", showProgress,
-            progress => SyncService.RunDiff(settings.ProjectDir, settings.Target, settings.ObjectSelector, settings.FilterPatterns, settings.ContextLines ?? 3, progress));
+            progress => SyncService.RunDiff(settings.ProjectDir, settings.Target, settings.ObjectSelector, settings.FilterPatterns, settings.ContextLines ?? 3, settings.ShowNormalizedDiff, progress));
         if (!result.Success)
         {
             output.WriteError(new ErrorResult("diff", result.Error!));

src/SqlChangeTracker/Commands/GlobalSettings.cs

@@ -44,6 +44,9 @@ internal sealed class DiffCommandSettings : StatusCommandSettings
 
     [CommandOption("--context <N>")]
     public int? ContextLines { get; set; }
+
+    [CommandOption("--normalized-diff")]
+    public bool ShowNormalizedDiff { get; set; }
 }
 
 internal sealed class PullCommandSettings : ProjectCommandSettings

src/SqlChangeTracker/PACKAGE_README.md

@@ -23,7 +23,7 @@ sqlct data track [<pattern>] [--object <pattern>] [--filter <regex>] [--project-
 sqlct data untrack [<pattern>] [--object <pattern>] [--filter <regex>] [--project-dir <path>]
 sqlct data list [--project-dir <path>]
 sqlct status [--project-dir <path>] [--target <db|folder>] [--no-progress]
-sqlct diff [--project-dir <path>] [--target <db|folder>] [--object <selector>] [--filter <pattern>...] [--context <N>] [--no-progress]
+sqlct diff [--project-dir <path>] [--target <db|folder>] [--object <selector>] [--filter <pattern>...] [--context <N>] [--normalized-diff] [--no-progress]
 sqlct pull [--project-dir <path>] [--object <selector>] [--filter <pattern>...] [--no-progress]
 ```