fix: pull writes canonical model files and detects changes reliably by angeloashmore · Pull Request #243 · prismicio/cli

angeloashmore · 2026-07-29T23:07:53Z

Resolves:

Description

Model comparison now sorts JSON keys at every depth before it compares. Field and tab order stays the same. This corrects three faults:

1. `pull` rewrote files that had no changes

Setup: Your model files came from an earlier prismic pull. The API returns nested keys (inside a field's config, for example) in a different order.
Before: The comparison sorted only the top-level keys. Pull saw a change and rewrote the files. git diff showed only key-order movement.
After: Pull prints "Already up to date." and does not touch the files.

2. `pull` did not rewrite files with a non-canonical key order

Setup: Slice Machine wrote your model files. Its key order is different from the format that the CLI writes.
Before: The comparison sorted the keys on both sides. Pull saw no difference and kept the old order. A later content change then mixed key-order noise into its diff.
After: Pull rewrites these files one time, in the canonical format. The next pull prints "Already up to date."

3. `sync --watch` reported changes that did not exist

Setup: A poll returns the same models with a different key order.
Before: The loop generated types and printed "Changes detected in " with an empty list.
After: Sync hashes the canonical models. It generates types and reports changes only on the initial sync or when a model changed.

push and status continue to ignore key order. They push nothing and report nothing when only the key order is different.

Checklist

A comprehensive Linear ticket, providing sufficient context and details to facilitate the review of the PR, is linked to the PR.
If my changes require tests, I added them.
If my changes affect backward compatibility, it has been discussed.
If my changes require an update to the CONTRIBUTING.md guide, I updated it.

Preview

How to QA ¹

Open a project with committed model files that Slice Machine wrote.
Run prismic pull. The command rewrites the files.
Run prismic pull again. The command prints "Already up to date." and leaves no dirty files.
Run prismic sync --watch. The command does not report changes when the remote models do not change.

🤖 Generated with Claude Code

Note

Medium Risk
Changes core model equality used by pull, sync, push, and status; incorrect canonicalization could hide real diffs or overwrite valid local models.

Overview
Pull and sync now treat Prismic models as equal when only JSON key order differs, while still rewriting local files to a stable canonical shape on pull.

Canonicalization in models.ts is deepened: sortKeys recurses through nested objects and arrays; Group nested fields and Slices zone choices (including legacy Slice entries) get explicit handling so field/tab order is preserved but metadata keys are sorted consistently.

pull fixes diffArrays equality to compare JSON.stringify(canonicalize(remote)) against the local model (already canonical on disk), avoiding false updates and missed rewrites.

sync hashes canonicalized remote state, uses the same canonical equality for slice/custom-type diffs, runs generateTypes only on the initial sync or when something actually changed, and logs change messages only when local files were updated—not on every poll when only the hash drifted without file ops.

^{Reviewed by Cursor Bugbot for commit d72140d. Bugbot is set up for automated code reviews on this repo. Configure here.}

Please use these labels when submitting a review:
❓ #ask: Ask a question.
💡 #idea: Suggest an idea.
⚠️ #issue: Strongly suggest a change.
🎉 #nice: Share a compliment. ↩

Model canonicalization sorted keys only one level deep, so structurally identical models with reordered keys inside nested config objects (e.g. an Image field's constraint) compared as different, causing pull to rewrite unchanged files. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…lize

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Sync compared raw remote JSON against canonical local files, so any remote change re-synced every model whose key order differed. Sync now uses pull's comparison: the remote model's canonical form against the local file as parsed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Pull now has a test that pulled files keep field order, a second pull changes nothing, and non-canonical files (types and slices) are rewritten in canonical form. The status reorder test also covers a slice and checks that push writes nothing. The scramble helper moves to test/it.ts and handles slice field maps. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…lize # Conflicts: # src/commands/sync.ts

Deep key sorting also sorted a Slices field's choices, which is the slice order shown in the editor, and the field maps inside legacy slices. Rebuild both from the unsorted input, like group fields. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Fixtures already hold their keys in a non-canonical order, so writing them to disk gives the same coverage as the scramble helper without restating which maps are position-significant. Cover a slice zone and a legacy slice too. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The pulled file only proved that field order survives. Assert the sorted key order of the model, a field, a thumbnail, a slice, and a variation, and add a second tab and thumbnail so tab and array order are covered. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Write the unsorted fixture locally before the pull so one run covers both the rewrite and the canonical output. Compare the pulled models to the fixture for content, then assert key order at each kind of object, including the slice zone and a legacy slice. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Write the unsorted fixture locally instead of pulling first, so status and push run against a non-canonical file in two CLI runs. Move the Choices type next to the function that uses it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The watch loop hashed the raw remote JSON. A change in key order flipped the hash without a real model change. The loop then ran generateTypes() and logged "Changes detected in" with no suffix. Hash the canonicalized models instead. Run generateTypes() and log changes only on the initial sync or when there are operations. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

cursor

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit d72140d. Configure here.}

lihbr

LGTM but I think there's an issue to check with select fields, see bellow :)

lihbr · 2026-08-14T05:46:29Z

 }

 function sortKeys<T>(object: T): T {
+	if (Array.isArray(object)) return object.map(sortKeys) as T;


⚠️ #issue: I believe this could tamper with the order of a select field's options: https://github.com/prismicio/prismic-client/blob/master/src/types/model/select.ts#L19, which might be unwanted.

angeloashmore and others added 6 commits July 29, 2026 23:07

fix: support TypeScript <5.9 in group field canonicalization

dcc6f9b

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/main' into aa/deep-sort-canonica…

cb73fde

…lize

refactor: consolidate canonicalization comments

fa32d3c

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

refactor: remove type cast in group field canonicalization

3f75a9b

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat: rewrite non-canonical model files on pull

e87830f

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

angeloashmore mentioned this pull request Jul 30, 2026

feat: rewrite non-canonical model files on pull #244

Merged

4 tasks

angeloashmore changed the title ~~fix: canonicalize nested model config objects~~ fix: pull writes canonical model files and detects changes reliably Jul 30, 2026

angeloashmore and others added 9 commits July 30, 2026 02:53

test: simplify canonical pull test

b3ace0c

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/main' into aa/deep-sort-canonica…

fc7fad0

…lize # Conflicts: # src/commands/sync.ts

angeloashmore marked this pull request as ready for review August 7, 2026 00:06

cursor Bot reviewed Aug 7, 2026

View reviewed changes

Comment thread src/commands/sync.ts

cursor Bot reviewed Aug 13, 2026

View reviewed changes

Comment thread src/commands/sync.ts

lihbr approved these changes Aug 14, 2026

View reviewed changes

Navigation Menu

Uh oh!

fix: pull writes canonical model files and detects changes reliably - #243

fix: pull writes canonical model files and detects changes reliably#243
angeloashmore wants to merge 16 commits into
mainfrom
aa/deep-sort-canonicalize

angeloashmore commented Jul 29, 2026 •

edited

Loading

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

lihbr left a comment

Uh oh!

lihbr Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

angeloashmore commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

1. pull rewrote files that had no changes

2. pull did not rewrite files with a non-canonical key order

3. sync --watch reported changes that did not exist

Checklist

Preview

How to QA 1

Footnotes

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lihbr left a comment

Choose a reason for hiding this comment

Uh oh!

lihbr Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

angeloashmore commented Jul 29, 2026 •

edited

Loading

1. `pull` rewrote files that had no changes

2. `pull` did not rewrite files with a non-canonical key order

3. `sync --watch` reported changes that did not exist

How to QA ¹