From e2de1cd3265f4221d37b9a96f401f6b48cabfa95 Mon Sep 17 00:00:00 2001 From: Arthur van de Vondervoort Date: Fri, 28 Aug 2026 21:29:22 +0200 Subject: [PATCH 1/2] docs(FC0004): describe the AZ AL Dev Tools-compatible sort order Co-Authored-By: Claude Fable 5 --- .../docs/analyzers/FormattingCop/FC0004.md | 40 ++++++++++++------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/content/docs/analyzers/FormattingCop/FC0004.md b/content/docs/analyzers/FormattingCop/FC0004.md index d0e3a48..5a7a06d 100644 --- a/content/docs/analyzers/FormattingCop/FC0004.md +++ b/content/docs/analyzers/FormattingCop/FC0004.md @@ -1,5 +1,5 @@ +++ -title = 'Permission declarations should be ordered alphabetically' +title = 'Permission declarations should be sorted by object type and name' linkTitle = 'FC0004' [params] @@ -10,13 +10,25 @@ linkTitle = 'FC0004' ignoreObsolete = false +++ -Alphabetical ordering of `Permissions` property entries is not cosmetic. It directly reduces merge conflicts in source control. +A consistent order of `Permissions` property entries is not cosmetic. It directly reduces merge conflicts in source control. -When two developers (or agents) add a permission entry to the end of an unsorted list, that change touches the same line range and produces a conflict almost every time. In a sorted list, each entry lands at a deterministic position based on its name. Two additions to a sorted list are unlikely to collide unless they happen to be alphabetically adjacent. The result is fewer unexpected conflicts and less friction during code review and merging. +When two developers (or agents) add a permission entry to the end of an unsorted list, that change touches the same line range and produces a conflict almost every time. In a sorted list, each entry lands at a deterministic position. Two additions to a sorted list are unlikely to collide unless they happen to be adjacent. The result is fewer unexpected conflicts and less friction during code review and merging. This matters most for `permissionset` objects, which routinely contain dozens of entries. But it applies equally to the `Permissions` property on codeunits, reports, queries, and xmlports. -Entries are sorted first by object type keyword (`codeunit`, `page`, `report`, `table`, `tabledata`, etc.) and then by object name (case-insensitive). +### Sort order + +FC0004 enforces the order produced by the **Sort Permissions** command of the [AZ AL Dev Tools](https://marketplace.visualstudio.com/items?itemName=andrzejzwierzchowski.al-code-outline) extension, so code sorted by that command never triggers the rule: + +1. `table` and `tabledata` entries come first, **interleaved and sorted by object name**. When a `table` and a `tabledata` entry share a name, `table` comes first. +2. The remaining entries follow in this fixed type order: `codeunit`, `page`, `query`, `report`, `xmlport`, each type sorted by object name. +3. Object names compare naturally, case-insensitively and ignoring spaces: `Item 2` comes before `Item 10`, and `"Post. Appr. Setup"` comes before `"Post Inv. Setup"` (compared as `Post.Appr.Setup` vs `PostInv.Setup`). +4. Entries inside `#region` … `#endregion` blocks are sorted within their block; blocks keep their position, and entries that follow a block are moved above it (a block's own entries are listed before its nested blocks). +5. Lists that contain other preprocessor directives (`#if`, `#pragma`, …) or unbalanced `#region` directives are not checked. + +Like AZ AL Dev Tools, `system` permissions are treated as table-type entries and sorted by name inside the table group. + +> **Breaking change.** Earlier versions of FC0004 sorted alphabetically by type keyword (`codeunit`, `page`, `report`, `tabledata`, …) and compared names ordinally. Code that satisfied the old rule may now be reported; the code fix reorders it. ### Example @@ -28,14 +40,14 @@ permissionset 50100 "Sales Permissions" Assignable = true; Access = Public; - Permissions = tabledata "Sales Header" = R, - codeunit "Sales-Post" = X, + Permissions = codeunit "Sales-Post" = X, + tabledata "Sales Header" = R, page "Sales Order" = X, - tabledata Customer = R; // Permission declarations should be ordered alphabetically [FC0004] + tabledata Customer = R; // Permission declarations should be sorted by object type and name [FC0004] } {{< /highlight >}} -Sort the entries by type, then by name: +Table entries first, sorted by name, then the other types in their fixed order: {{< highlight al "hl_lines=6-9" >}} permissionset 50100 "Sales Permissions" @@ -43,17 +55,17 @@ permissionset 50100 "Sales Permissions" Assignable = true; Access = Public; - Permissions = codeunit "Sales-Post" = X, - page "Sales Order" = X, - tabledata Customer = R, - tabledata "Sales Header" = R; + Permissions = tabledata Customer = R, + tabledata "Sales Header" = R, + codeunit "Sales-Post" = X, + page "Sales Order" = X; } {{< /highlight >}} ### Code fix -The **ALCops: Sort permission declarations alphabetically** code fix reorders all entries in the `Permissions` property. When the original declaration is on a single line, the fix converts it to multi-line format for readability. +The **ALCops: Sort permission declarations** code fix reorders the entries in place. Indentation, comments and `#region` blocks keep their layout; only the entries move. When the original declaration is on a single line, the fix converts it to multi-line format for readability. ### See also -- [AC0031](../../applicationcop/ac0031/) and [AC0032](../../applicationcop/ac0032/) validate the correctness of permission entries. FC0004 validates their ordering. +- [AC0031](../../applicationcop/ac0031/) and [AC0032](../../applicationcop/ac0032/) validate the correctness of permission entries. FC0004 validates their ordering; the AC0031 code fix inserts new entries at the position FC0004 expects. From e2297a8485c634421cac8ee111f1e030c6f7e0e7 Mon Sep 17 00:00:00 2001 From: Arthur van de Vondervoort Date: Tue, 1 Sep 2026 15:24:15 +0200 Subject: [PATCH 2/2] docs(FC0004): lead with ALCops code fix, mention AZ AL Dev Tools as compatible Reframe the sort order section to describe FC0004's own behavior rather than defining it in terms of AZ AL Dev Tools. The compatibility note moves to a standalone paragraph after the breaking change callout. Co-Authored-By: Claude Opus 4.6 (1M context) --- content/docs/analyzers/FormattingCop/FC0004.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/docs/analyzers/FormattingCop/FC0004.md b/content/docs/analyzers/FormattingCop/FC0004.md index 5a7a06d..67b341f 100644 --- a/content/docs/analyzers/FormattingCop/FC0004.md +++ b/content/docs/analyzers/FormattingCop/FC0004.md @@ -18,7 +18,7 @@ This matters most for `permissionset` objects, which routinely contain dozens of ### Sort order -FC0004 enforces the order produced by the **Sort Permissions** command of the [AZ AL Dev Tools](https://marketplace.visualstudio.com/items?itemName=andrzejzwierzchowski.al-code-outline) extension, so code sorted by that command never triggers the rule: +FC0004 enforces the following order. The code fix reorders entries to match (see [Code fix](#code-fix)): 1. `table` and `tabledata` entries come first, **interleaved and sorted by object name**. When a `table` and a `tabledata` entry share a name, `table` comes first. 2. The remaining entries follow in this fixed type order: `codeunit`, `page`, `query`, `report`, `xmlport`, each type sorted by object name. @@ -26,10 +26,12 @@ FC0004 enforces the order produced by the **Sort Permissions** command of the [A 4. Entries inside `#region` … `#endregion` blocks are sorted within their block; blocks keep their position, and entries that follow a block are moved above it (a block's own entries are listed before its nested blocks). 5. Lists that contain other preprocessor directives (`#if`, `#pragma`, …) or unbalanced `#region` directives are not checked. -Like AZ AL Dev Tools, `system` permissions are treated as table-type entries and sorted by name inside the table group. +`system` permissions are treated as table-type entries and sorted by name inside the table group. > **Breaking change.** Earlier versions of FC0004 sorted alphabetically by type keyword (`codeunit`, `page`, `report`, `tabledata`, …) and compared names ordinally. Code that satisfied the old rule may now be reported; the code fix reorders it. +This sort order is compatible with the **Sort Permissions** command of the [AZ AL Dev Tools](https://marketplace.visualstudio.com/items?itemName=andrzejzwierzchowski.al-code-outline) extension. Code sorted by either tool satisfies the rule. + ### Example The following `permissionset` declares entries in arbitrary order: