pre-commit-bigfix 2.2.0__tar.gz → 2.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. {pre_commit_bigfix-2.2.0/pre_commit_bigfix.egg-info → pre_commit_bigfix-2.4.0}/PKG-INFO +92 -14
  2. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/README.md +90 -12
  3. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/__init__.py +1 -1
  4. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/bes_relevance_lint.py +214 -43
  5. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/bes_siterepo_validate_layout.py +379 -33
  6. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/run_all.py +2 -1
  7. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0/pre_commit_bigfix.egg-info}/PKG-INFO +92 -14
  8. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix.egg-info/requires.txt +1 -1
  9. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/setup.cfg +1 -1
  10. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_bes_relevance_lint.py +246 -14
  11. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_bes_siterepo_validate_layout.py +446 -0
  12. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_hook_declarations.py +10 -0
  13. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_schema_guard.py +94 -0
  14. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/LICENSE +0 -0
  15. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/MANIFEST.in +0 -0
  16. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/bes_actionscript_lint_schclass.py +0 -0
  17. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/bes_actionscript_validate_prefetch.py +0 -0
  18. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/bes_actionscript_validate_script.py +0 -0
  19. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/bes_common.py +0 -0
  20. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/bes_content_score_risk.py +0 -0
  21. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/bes_conventions_check.py +0 -0
  22. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/bes_relevance_convert_group.py +0 -0
  23. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/bes_schema_validate.py +0 -0
  24. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/schclass.py +0 -0
  25. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/schclass_data/ExpandedActionScript.schclass +0 -0
  26. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/schclass_data/bigfix_overrides.schclass +0 -0
  27. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix/schclass_tokenizer.py +0 -0
  28. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix.egg-info/SOURCES.txt +0 -0
  29. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix.egg-info/dependency_links.txt +0 -0
  30. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix.egg-info/entry_points.txt +0 -0
  31. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pre_commit_bigfix.egg-info/top_level.txt +0 -0
  32. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/pyproject.toml +0 -0
  33. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/setup.py +0 -0
  34. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_bes_actionscript_lint_schclass.py +0 -0
  35. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_bes_actionscript_validate_prefetch.py +0 -0
  36. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_bes_actionscript_validate_script.py +0 -0
  37. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_bes_common.py +0 -0
  38. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_bes_content_score_risk.py +0 -0
  39. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_bes_conventions_check.py +0 -0
  40. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_bes_relevance_convert_group.py +0 -0
  41. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_bes_schema_validate.py +0 -0
  42. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_package_metadata.py +0 -0
  43. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_release_workflow.py +0 -0
  44. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_run_all.py +0 -0
  45. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_schclass.py +0 -0
  46. {pre_commit_bigfix-2.2.0 → pre_commit_bigfix-2.4.0}/tests/test_schclass_tokenizer.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pre-commit-bigfix
3
- Version: 2.2.0
3
+ Version: 2.4.0
4
4
  Summary: pre-commit hooks for BigFix content
5
5
  Home-page: https://github.com/jgstew/pre-commit-bigfix
6
6
  Author: JGStew
@@ -25,7 +25,7 @@ License-File: LICENSE
25
25
  Requires-Dist: bigfix_prefetch>=1.1.5
26
26
  Requires-Dist: lxml
27
27
  Requires-Dist: validate_bes_xml<3,>=2.4.1
28
- Requires-Dist: bigfix-relevance-analyzer<2,>=1.23.1; python_version >= "3.11"
28
+ Requires-Dist: bigfix-relevance-analyzer<2,>=1.26.0; python_version >= "3.11"
29
29
  Provides-Extra: test
30
30
  Requires-Dist: pytest; extra == "test"
31
31
  Dynamic: license-file
@@ -624,6 +624,7 @@ of the file.
624
624
  | `E612` | an ActionScript `{` with anything after it on its line and no `}` to close it there, which fails the action |
625
625
  | `E613` | a `<?Relevance` with no closing `?>`, so its relevance was not linted |
626
626
  | `E614` | a BES file that is not well-formed XML, so nothing in it was linted (**off by default**; `--enable E614`) |
627
+ | `E615` | an `--auto-fix` was not written because it would turn a BES.xsd-valid file invalid; fix by hand, or `--disable E615` to write it anyway |
627
628
  | `W600` | a name no inspector dump defines |
628
629
  | `W601` | a property written singular over an object that may be plural |
629
630
  | `W602` | a singular spelling mid-chain (under a `whose` filter, or where a plural is built from it), where the plural reads safer |
@@ -635,7 +636,7 @@ of the file.
635
636
 
636
637
  `W600` is a warning rather than an error because a repo running a newer client
637
638
  than the analyzer's dump snapshot legitimately uses names it has never heard
638
- of. `W601` is **disabled by default** in the hook declaration: across 1,108
639
+ of. `W601` is **disabled by default**: across 1,108
639
640
  `.bes` files of real content it fires 6,127 times, which drowns everything
640
641
  else. Switch it back on with `--enable W601`.
641
642
 
@@ -646,12 +647,35 @@ says the relevance that could be extracted is sound, not that the file parses.
646
647
  A file opts out of every check here with
647
648
  `<!-- pre-commit-skip: bes-relevance-lint -->` anywhere in it. There is no
648
649
  per-rule marker: `--disable` takes a code repo-wide, and a single file that
649
- legitimately needs relevance this complex is what `--max-score` is for. Files
650
- are never rewritten, but where the analyzer can work out a safe rewrite of a
651
- whole statement (today, the singular spellings behind `W602`) the fixed
652
- statement is printed once under its first finding as `suggested fix: ...`.
650
+ legitimately needs relevance this complex is what `--max-score` is for.
653
651
  E-codes fail the hook; pass `--strict` to also fail on warnings.
654
652
 
653
+ Where the analyzer can work out a safe rewrite of a statement (the singular
654
+ spellings behind `W602`, and the `unique value of` / singular-aggregate
655
+ rewrites behind `E611`), the fixed statement is printed once under its first
656
+ finding as `suggested fix: ...`. By default that is all: **unlike the sibling
657
+ hooks, this one never rewrites a file unless the repo opts in**, because a
658
+ relevance fix changes what a statement says, not just how it is formatted:
659
+
660
+ ```yaml
661
+ - id: bes-relevance-lint
662
+ args: [--auto-fix=yes]
663
+ ```
664
+
665
+ With `--auto-fix=yes`, each safe fix is written in place as the smallest
666
+ edit that makes it (`setting` gains an `s`; a wrap inserts
667
+ `unique value of `), so entities, CDATA and line endings around it are kept.
668
+ The analyzer refuses a fix it cannot prove safe - one that would add a finding
669
+ (a wrap that pushes a statement over `--max-score`, say), or one under a rule
670
+ you `--disable` - and refuses site by site, so a file can come back partly
671
+ fixed. Each written edit is reported as
672
+ `path:line: [W602] auto-fixed: setting -> settings (plural-preferred)`; a fix
673
+ that was not written keeps its `suggested fix:` line with
674
+ `(not auto-fixed: <reason>)`. A fix that would turn a BES.xsd-valid file
675
+ invalid is not written, and is reported as `E615`; files no schema applies to
676
+ (`.rel`, `.bsr`, ...) are written unchecked, as every sibling hook does. Any
677
+ auto-fix fails the hook so the change is reviewed and re-staged.
678
+
655
679
  This hook needs **Python 3.11 or newer** - the analyzer requires it, while the
656
680
  rest of this package still runs on 3.8. No specific interpreter is pinned, since
657
681
  `language_version` names an exact executable and pinning `python3.11` would
@@ -813,13 +837,14 @@ warning (`W808`), since RHEL is case-sensitive.
813
837
  | --- | --- |
814
838
  | `E800` | a `.bes` file in the `.bes` folder whose name does not start with a numeric ID and a space or hyphen; `42- Name.bes` and `42 Name.bes` both work |
815
839
  | `E801` | two or more `.bes` files in one site share an ID, compared as integers, so `0042` and `42` collide; each names the others |
816
- | `E802` | a `.bes` file's server path is too long and the rename cannot fix it: even `<ID> X.bes` is too long (the folders are), it has no ID, or `E805` is disabled. Renaming a folder changes its `.fxf` or digest, so that is left to you |
840
+ | `E802` | a `.bes` file's server path is too long and the rename cannot fix it: even `<ID> X.bes` is too long (the folders are), it has no ID (and `E809` gives it none), or `E805` is disabled. Renaming a folder changes its `.fxf` or digest, so that is left to you |
817
841
  | `E803` | fix: zero padding in the ID (`0042- X.bes` -> `42- X.bes`); done even when the ID is a duplicate (`E801`), since the ID does not change |
818
842
  | `E804` | fix: non-ASCII characters in the name, folded to ASCII |
819
843
  | `E805` | fix: the server path is too long, or the name is over 255 bytes, so the file is renamed `<ID> <Title>.bes` |
820
- | `E806` | a rename was skipped: the new name is taken (ignoring case), the file has unstaged changes pre-commit set aside, the commit uses a temporary index (`git commit -a`, `git commit <paths>`), or the rename failed |
844
+ | `E806` | a rename was skipped: the new name is taken (ignoring case), the file has unstaged changes pre-commit set aside, the commit uses a temporary index (`git commit -a`, `git commit <paths>`), the rename failed, or `E809` could not choose an ID safely (shallow clone, unknown base branch) |
821
845
  | `E807` | another tracked file's server path is too long, inside the site roots or not (the server clones the whole repo). It is not renamed, since actions may refer to it by name |
822
846
  | `E808` | a file or folder name over 255 bytes in UTF-8 (Linux `NAME_MAX`) that the rename cannot fix; each folder once |
847
+ | `E809` | fix: a file with no ID (`E800`), or a duplicate (`E801`) that is not the one keeping the ID, gets a new ID no file in git history has used; see **New IDs** |
823
848
  | `W800` | a `.bes` file outside the `.bes` folder; the server does not gather it |
824
849
  | `W801` | a `.bes` file directly in the `.bes` folder, or deeper than `<BesFileDir>/<fxf>/<digest>/` (how the server handles either is undocumented) |
825
850
  | `W802` | a file in the `.bes` folder other than `.bes` or `digest.xml`; an `.xsd` too, since `bes-schema-validate` already has the schemas |
@@ -853,6 +878,8 @@ count in full. The options:
853
878
  | `--repo-name` | the last part of the `origin` remote URL without `.git`, or the repo folder's name |
854
879
  | `--branch` | `main` |
855
880
  | `--max-path` | `259` |
881
+ | `--base-ref` | `PRE_COMMIT_FROM_REF`, else `origin/$GITHUB_BASE_REF`, else `HEAD` (see **New IDs**) |
882
+ | `--min-id` | `1` (see **New IDs**) |
856
883
 
857
884
  **Renames.** By default each `.bes` file in the `.bes` folder is renamed at
858
885
  most once, combining the fixes it needs: zero padding stripped from the ID
@@ -863,7 +890,7 @@ cut to fit both limits (`E805`). The title comes from the file's `<Title>`,
863
890
  or from its current name if the title has no letter or digit; it is made
864
891
  ASCII and safe on Windows, cut short, and any trailing space, dot or hyphen
865
892
  is dropped. A name that already fits is left alone, even when it differs
866
- from the title. The ID never changes and no file moves between folders.
893
+ from the title. Only `E809` changes an ID, and no file moves between folders.
867
894
 
868
895
  Tracked files are renamed with `git mv`, so the renames are staged and the
869
896
  next commit carries them whole; a plain rename would leave an unstaged
@@ -883,10 +910,61 @@ renamed (`E806`) where the rename would be lost:
883
910
  Any rename makes the hook exit 1, so review the renames and commit again.
884
911
  `--check` is a dry run that reports what would be renamed.
885
912
 
886
- Files with no ID are reported (`E800`), not given one. An opt-in
887
- `--assign-ids` is deferred: choosing IDs is a policy decision, best backed
888
- by a counter file as CommunityContent does, since taking the highest ID plus
889
- one could reuse a deleted item's ID.
913
+ **New IDs (`E809`).** A file with no ID, or a duplicate ID, gets a new one
914
+ in the same rename, which also applies `E804` and `E805`:
915
+
916
+ - No ID: `Name.bes` becomes `<ID> Name.bes`. The server never gathered it,
917
+ so nothing deployed refers to it.
918
+ - Duplicate ID: the one file on the base branch keeps the ID, and the others
919
+ get new ones (`42- X.bes` -> `1043- X.bes`). Renumbering only new content
920
+ keeps actions and baselines that refer to the old ID working. A file
921
+ renamed from one on the base branch counts as on it, as `git diff -M`
922
+ pairs them. When every file in the group is new, the first by path keeps
923
+ the ID. Nothing is renumbered, and `E806` says why, when two or more are
924
+ already on the base branch (which one keeps the ID is for a person to
925
+ decide), or when the ID is on the base branch but git sees no file here as
926
+ that file renamed (it may be one, changed too much to pair).
927
+ - The new ID is one more than the highest ID any `.bes` path has had in git
928
+ history (`git log --all --full-history -m`: every branch and tag, both
929
+ sides of every merge, every site in the repo) or has now, so it never
930
+ reuses the ID of a deleted or renamed file. It sees only the branches and
931
+ tags this clone has fetched: fetch first. Gaps are never filled. For a site whose older IDs predate the git
932
+ repo, set a floor with `--min-id`.
933
+ - The base branch is the first of `--base-ref`, `PRE_COMMIT_FROM_REF` (set by `pre-commit run --from-ref`)
934
+ and `origin/$GITHUB_BASE_REF` (set in a GitHub `pull_request` run) that is
935
+ a commit in the clone. Without any, it is `HEAD`: in a local commit, the
936
+ staged files are the new ones. Once both files of a duplicate are
937
+ committed on a feature branch, `HEAD` sees neither as new: run with
938
+ `--base-ref origin/main` (or the branch it merges into), as `E806` says.
939
+ - In a shallow clone, git history is incomplete, so no ID is assigned
940
+ (`E806`); likewise for duplicates when `--base-ref` is not a commit.
941
+ - `--disable E809` reports `E800` and `E801` only, as before. Disabling
942
+ `E800` or `E801` also stops `E809` for those files.
943
+
944
+ In GitHub Actions, check out the full history (the default is one commit),
945
+ and give pre-commit the PR's base so that it knows which files are new:
946
+
947
+ ```yaml
948
+ - uses: actions/checkout@v7
949
+ with:
950
+ fetch-depth: 0
951
+ - uses: pre-commit/action@v3.0.1
952
+ with:
953
+ extra_args: >-
954
+ --from-ref ${{ github.event.pull_request.base.sha }}
955
+ --to-ref ${{ github.event.pull_request.head.sha }}
956
+ ```
957
+
958
+ The hook renames the files on the runner and fails, and the log names each
959
+ new file name, for the author to apply (or run the hook locally with
960
+ `--base-ref` naming the PR's base branch). To commit
961
+ the fix back to a PR branch instead, check out `github.head_ref` with
962
+ `contents: write`, then commit and push any change. Fork PRs cannot be
963
+ pushed to, and a push with `GITHUB_TOKEN` starts no new workflow run. Two
964
+ open PRs can choose the same ID; the one merged second then has a duplicate
965
+ on the base branch and is renumbered when it runs again, so require branches
966
+ to be up to date before merging. A site that assigns IDs after merge from a
967
+ counter file, as CommunityContent does, should use `--disable E809`.
890
968
 
891
969
  Not checked here: more than one object in a `.bes` file, or Baselines
892
970
  (repository sites are thought to handle both); schemas, GroupRelevance and
@@ -592,6 +592,7 @@ of the file.
592
592
  | `E612` | an ActionScript `{` with anything after it on its line and no `}` to close it there, which fails the action |
593
593
  | `E613` | a `<?Relevance` with no closing `?>`, so its relevance was not linted |
594
594
  | `E614` | a BES file that is not well-formed XML, so nothing in it was linted (**off by default**; `--enable E614`) |
595
+ | `E615` | an `--auto-fix` was not written because it would turn a BES.xsd-valid file invalid; fix by hand, or `--disable E615` to write it anyway |
595
596
  | `W600` | a name no inspector dump defines |
596
597
  | `W601` | a property written singular over an object that may be plural |
597
598
  | `W602` | a singular spelling mid-chain (under a `whose` filter, or where a plural is built from it), where the plural reads safer |
@@ -603,7 +604,7 @@ of the file.
603
604
 
604
605
  `W600` is a warning rather than an error because a repo running a newer client
605
606
  than the analyzer's dump snapshot legitimately uses names it has never heard
606
- of. `W601` is **disabled by default** in the hook declaration: across 1,108
607
+ of. `W601` is **disabled by default**: across 1,108
607
608
  `.bes` files of real content it fires 6,127 times, which drowns everything
608
609
  else. Switch it back on with `--enable W601`.
609
610
 
@@ -614,12 +615,35 @@ says the relevance that could be extracted is sound, not that the file parses.
614
615
  A file opts out of every check here with
615
616
  `<!-- pre-commit-skip: bes-relevance-lint -->` anywhere in it. There is no
616
617
  per-rule marker: `--disable` takes a code repo-wide, and a single file that
617
- legitimately needs relevance this complex is what `--max-score` is for. Files
618
- are never rewritten, but where the analyzer can work out a safe rewrite of a
619
- whole statement (today, the singular spellings behind `W602`) the fixed
620
- statement is printed once under its first finding as `suggested fix: ...`.
618
+ legitimately needs relevance this complex is what `--max-score` is for.
621
619
  E-codes fail the hook; pass `--strict` to also fail on warnings.
622
620
 
621
+ Where the analyzer can work out a safe rewrite of a statement (the singular
622
+ spellings behind `W602`, and the `unique value of` / singular-aggregate
623
+ rewrites behind `E611`), the fixed statement is printed once under its first
624
+ finding as `suggested fix: ...`. By default that is all: **unlike the sibling
625
+ hooks, this one never rewrites a file unless the repo opts in**, because a
626
+ relevance fix changes what a statement says, not just how it is formatted:
627
+
628
+ ```yaml
629
+ - id: bes-relevance-lint
630
+ args: [--auto-fix=yes]
631
+ ```
632
+
633
+ With `--auto-fix=yes`, each safe fix is written in place as the smallest
634
+ edit that makes it (`setting` gains an `s`; a wrap inserts
635
+ `unique value of `), so entities, CDATA and line endings around it are kept.
636
+ The analyzer refuses a fix it cannot prove safe - one that would add a finding
637
+ (a wrap that pushes a statement over `--max-score`, say), or one under a rule
638
+ you `--disable` - and refuses site by site, so a file can come back partly
639
+ fixed. Each written edit is reported as
640
+ `path:line: [W602] auto-fixed: setting -> settings (plural-preferred)`; a fix
641
+ that was not written keeps its `suggested fix:` line with
642
+ `(not auto-fixed: <reason>)`. A fix that would turn a BES.xsd-valid file
643
+ invalid is not written, and is reported as `E615`; files no schema applies to
644
+ (`.rel`, `.bsr`, ...) are written unchecked, as every sibling hook does. Any
645
+ auto-fix fails the hook so the change is reviewed and re-staged.
646
+
623
647
  This hook needs **Python 3.11 or newer** - the analyzer requires it, while the
624
648
  rest of this package still runs on 3.8. No specific interpreter is pinned, since
625
649
  `language_version` names an exact executable and pinning `python3.11` would
@@ -781,13 +805,14 @@ warning (`W808`), since RHEL is case-sensitive.
781
805
  | --- | --- |
782
806
  | `E800` | a `.bes` file in the `.bes` folder whose name does not start with a numeric ID and a space or hyphen; `42- Name.bes` and `42 Name.bes` both work |
783
807
  | `E801` | two or more `.bes` files in one site share an ID, compared as integers, so `0042` and `42` collide; each names the others |
784
- | `E802` | a `.bes` file's server path is too long and the rename cannot fix it: even `<ID> X.bes` is too long (the folders are), it has no ID, or `E805` is disabled. Renaming a folder changes its `.fxf` or digest, so that is left to you |
808
+ | `E802` | a `.bes` file's server path is too long and the rename cannot fix it: even `<ID> X.bes` is too long (the folders are), it has no ID (and `E809` gives it none), or `E805` is disabled. Renaming a folder changes its `.fxf` or digest, so that is left to you |
785
809
  | `E803` | fix: zero padding in the ID (`0042- X.bes` -> `42- X.bes`); done even when the ID is a duplicate (`E801`), since the ID does not change |
786
810
  | `E804` | fix: non-ASCII characters in the name, folded to ASCII |
787
811
  | `E805` | fix: the server path is too long, or the name is over 255 bytes, so the file is renamed `<ID> <Title>.bes` |
788
- | `E806` | a rename was skipped: the new name is taken (ignoring case), the file has unstaged changes pre-commit set aside, the commit uses a temporary index (`git commit -a`, `git commit <paths>`), or the rename failed |
812
+ | `E806` | a rename was skipped: the new name is taken (ignoring case), the file has unstaged changes pre-commit set aside, the commit uses a temporary index (`git commit -a`, `git commit <paths>`), the rename failed, or `E809` could not choose an ID safely (shallow clone, unknown base branch) |
789
813
  | `E807` | another tracked file's server path is too long, inside the site roots or not (the server clones the whole repo). It is not renamed, since actions may refer to it by name |
790
814
  | `E808` | a file or folder name over 255 bytes in UTF-8 (Linux `NAME_MAX`) that the rename cannot fix; each folder once |
815
+ | `E809` | fix: a file with no ID (`E800`), or a duplicate (`E801`) that is not the one keeping the ID, gets a new ID no file in git history has used; see **New IDs** |
791
816
  | `W800` | a `.bes` file outside the `.bes` folder; the server does not gather it |
792
817
  | `W801` | a `.bes` file directly in the `.bes` folder, or deeper than `<BesFileDir>/<fxf>/<digest>/` (how the server handles either is undocumented) |
793
818
  | `W802` | a file in the `.bes` folder other than `.bes` or `digest.xml`; an `.xsd` too, since `bes-schema-validate` already has the schemas |
@@ -821,6 +846,8 @@ count in full. The options:
821
846
  | `--repo-name` | the last part of the `origin` remote URL without `.git`, or the repo folder's name |
822
847
  | `--branch` | `main` |
823
848
  | `--max-path` | `259` |
849
+ | `--base-ref` | `PRE_COMMIT_FROM_REF`, else `origin/$GITHUB_BASE_REF`, else `HEAD` (see **New IDs**) |
850
+ | `--min-id` | `1` (see **New IDs**) |
824
851
 
825
852
  **Renames.** By default each `.bes` file in the `.bes` folder is renamed at
826
853
  most once, combining the fixes it needs: zero padding stripped from the ID
@@ -831,7 +858,7 @@ cut to fit both limits (`E805`). The title comes from the file's `<Title>`,
831
858
  or from its current name if the title has no letter or digit; it is made
832
859
  ASCII and safe on Windows, cut short, and any trailing space, dot or hyphen
833
860
  is dropped. A name that already fits is left alone, even when it differs
834
- from the title. The ID never changes and no file moves between folders.
861
+ from the title. Only `E809` changes an ID, and no file moves between folders.
835
862
 
836
863
  Tracked files are renamed with `git mv`, so the renames are staged and the
837
864
  next commit carries them whole; a plain rename would leave an unstaged
@@ -851,10 +878,61 @@ renamed (`E806`) where the rename would be lost:
851
878
  Any rename makes the hook exit 1, so review the renames and commit again.
852
879
  `--check` is a dry run that reports what would be renamed.
853
880
 
854
- Files with no ID are reported (`E800`), not given one. An opt-in
855
- `--assign-ids` is deferred: choosing IDs is a policy decision, best backed
856
- by a counter file as CommunityContent does, since taking the highest ID plus
857
- one could reuse a deleted item's ID.
881
+ **New IDs (`E809`).** A file with no ID, or a duplicate ID, gets a new one
882
+ in the same rename, which also applies `E804` and `E805`:
883
+
884
+ - No ID: `Name.bes` becomes `<ID> Name.bes`. The server never gathered it,
885
+ so nothing deployed refers to it.
886
+ - Duplicate ID: the one file on the base branch keeps the ID, and the others
887
+ get new ones (`42- X.bes` -> `1043- X.bes`). Renumbering only new content
888
+ keeps actions and baselines that refer to the old ID working. A file
889
+ renamed from one on the base branch counts as on it, as `git diff -M`
890
+ pairs them. When every file in the group is new, the first by path keeps
891
+ the ID. Nothing is renumbered, and `E806` says why, when two or more are
892
+ already on the base branch (which one keeps the ID is for a person to
893
+ decide), or when the ID is on the base branch but git sees no file here as
894
+ that file renamed (it may be one, changed too much to pair).
895
+ - The new ID is one more than the highest ID any `.bes` path has had in git
896
+ history (`git log --all --full-history -m`: every branch and tag, both
897
+ sides of every merge, every site in the repo) or has now, so it never
898
+ reuses the ID of a deleted or renamed file. It sees only the branches and
899
+ tags this clone has fetched: fetch first. Gaps are never filled. For a site whose older IDs predate the git
900
+ repo, set a floor with `--min-id`.
901
+ - The base branch is the first of `--base-ref`, `PRE_COMMIT_FROM_REF` (set by `pre-commit run --from-ref`)
902
+ and `origin/$GITHUB_BASE_REF` (set in a GitHub `pull_request` run) that is
903
+ a commit in the clone. Without any, it is `HEAD`: in a local commit, the
904
+ staged files are the new ones. Once both files of a duplicate are
905
+ committed on a feature branch, `HEAD` sees neither as new: run with
906
+ `--base-ref origin/main` (or the branch it merges into), as `E806` says.
907
+ - In a shallow clone, git history is incomplete, so no ID is assigned
908
+ (`E806`); likewise for duplicates when `--base-ref` is not a commit.
909
+ - `--disable E809` reports `E800` and `E801` only, as before. Disabling
910
+ `E800` or `E801` also stops `E809` for those files.
911
+
912
+ In GitHub Actions, check out the full history (the default is one commit),
913
+ and give pre-commit the PR's base so that it knows which files are new:
914
+
915
+ ```yaml
916
+ - uses: actions/checkout@v7
917
+ with:
918
+ fetch-depth: 0
919
+ - uses: pre-commit/action@v3.0.1
920
+ with:
921
+ extra_args: >-
922
+ --from-ref ${{ github.event.pull_request.base.sha }}
923
+ --to-ref ${{ github.event.pull_request.head.sha }}
924
+ ```
925
+
926
+ The hook renames the files on the runner and fails, and the log names each
927
+ new file name, for the author to apply (or run the hook locally with
928
+ `--base-ref` naming the PR's base branch). To commit
929
+ the fix back to a PR branch instead, check out `github.head_ref` with
930
+ `contents: write`, then commit and push any change. Fork PRs cannot be
931
+ pushed to, and a push with `GITHUB_TOKEN` starts no new workflow run. Two
932
+ open PRs can choose the same ID; the one merged second then has a duplicate
933
+ on the base branch and is renumbered when it runs again, so require branches
934
+ to be up to date before merging. A site that assigns IDs after merge from a
935
+ counter file, as CommunityContent does, should use `--disable E809`.
858
936
 
859
937
  Not checked here: more than one object in a `.bes` file, or Baselines
860
938
  (repository sites are thought to handle both); schemas, GroupRelevance and
@@ -1,3 +1,3 @@
1
1
  """To support running this directly as a python module."""
2
2
 
3
- __version__ = "2.2.0"
3
+ __version__ = "2.4.0"