PDFCLOUD-6418: Upgrade repository quality scaffolding

.cit-quality/README.md

@@ -0,0 +1,59 @@
+# CIT quality tooling
+
+This directory contains vendored contributor tooling, separate from project
+source. It is maintained and tested in `cloud-innovation-team/cit-codex-skills`.
+Executing the local copy requires no GitHub authentication or source-repository
+access.
+
+## Provenance
+
+- Installed file: `.cit-quality/vendor/check_nfc_filenames.py`.
+- Upstream file:
+  `skills/cit-repository-quality-scaffolding/scripts/check_nfc_filenames.py`.
+- Source revision: `2dbf02d13b73799d2fcf1d3c7bab0a8371fd82ee`.
+- Source SHA-256:
+  `83d3bb79ebf3a5d6cb4f213f3af4421bd258693057514637ce87f3fc00a79056`.
+- Upstream suite:
+  `skills/cit-repository-quality-scaffolding/scripts/test_scaffolding.py`.
+
+The upstream behavioral suite tests rejection of non-NFC tracked filenames,
+acceptance after a byte-preserving rename, and normalization collisions. It also
+exercises the installed copy through the generated pre-commit hook. This
+provenance identifies the source; rendering alone does not establish a passing
+test run. Record the source revision and actual upstream validation in the PR.
+
+## Upstream validation
+
+On 2026-10-07, three focused upstream tests passed:
+
+- `test_vendored_checker_is_separate_from_project_source` (includes the
+  installed hook).
+- `test_normalization_collision_is_reported_without_renaming`.
+- `test_non_nfc_tracked_name_fails_hook_until_byte_preserving_rename`.
+
+Command:
+`uv run --script <skill>/scripts/test_scaffolding.py -v -n 2 -k "vendored_checker_is_separate or normalization_collision_is_reported or non_nfc_tracked_name_fails_hook_until_byte_preserving_rename" --durations=5`.
+
+Result: `3 passed` on Python 3.13.11; rerun during this refresh. This is focused
+validation, not a claim that the entire upstream suite or all checker failure
+paths were exercised.
+
+## Review and updates
+
+Review source provenance, updates, and the repository's hook integration.
+Implementation tests are maintained upstream; duplicate project tests are not
+required for an unchanged, upstream-tested copy. Local behavior changes require
+normal implementation review and appropriate regression coverage.
+
+Update the checker and this provenance note together from the scaffolding skill.
+Preserve the copied bytes; contribute fixes upstream instead of editing the
+vendored copy. Keep this directory out of project source, test discovery,
+coverage, and distribution inputs where those tools would otherwise traverse it.
+The `linguist-vendored` attribute classifies the code; it does not disable
+GitHub review requirements.
+
+Run the installed hook from the repository root:
+
+```shell
+uvx --from pre-commit==4.6.2 pre-commit run check-nfc-filenames --all-files
+```

.cit-quality/vendor/check_nfc_filenames.py

@@ -0,0 +1,87 @@
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Reject tracked Git paths that are not UTF-8 NFC, including collisions."""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+import unicodedata
+from pathlib import Path
+from typing import Any
+
+
+def tracked_filename_report(root: Path) -> dict[str, Any]:
+    """Inspect raw index paths, not filesystem names or quoted Git status text."""
+    process = subprocess.run(
+        ["git", "ls-files", "--cached", "-z"],
+        cwd=root,
+        check=False,
+        capture_output=True,
+    )
+    if process.returncode != 0:
+        return {
+            "checked": False,
+            "error": process.stderr.decode("utf-8", errors="replace").strip(),
+            "issues": [],
+            "collisions": [],
+        }
+
+    paths: list[str] = []
+    invalid_utf8: list[str] = []
+    for raw_path in process.stdout.split(b"\0"):
+        if not raw_path:
+            continue
+        try:
+            paths.append(raw_path.decode("utf-8"))
+        except UnicodeDecodeError:
+            invalid_utf8.append(raw_path.decode("utf-8", errors="backslashreplace"))
+
+    by_nfc: dict[str, list[str]] = {}
+    for path in set(paths):
+        by_nfc.setdefault(unicodedata.normalize("NFC", path), []).append(path)
+    collisions = [
+        {"nfc_path": normalized, "paths": sorted(originals)}
+        for normalized, originals in sorted(by_nfc.items())
+        if len(originals) > 1
+    ]
+    issues = [
+        {
+            "path": path,
+            "nfc_path": normalized,
+            "collides_with": sorted(other for other in originals if other != path),
+        }
+        for normalized, originals in sorted(by_nfc.items())
+        for path in sorted(originals)
+        if path != normalized
+    ]
+    return {
+        "checked": True,
+        "issues": issues,
+        "collisions": collisions,
+        "invalid_utf8": sorted(invalid_utf8),
+    }
+
+
+def main() -> int:
+    """Print actionable failures for a local pre-commit hook."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--repo", type=Path, default=Path.cwd())
+    args = parser.parse_args()
+    report = tracked_filename_report(args.repo)
+    if not report["checked"]:
+        print(f"Cannot inspect tracked filenames: {report['error']}", file=sys.stderr)
+        return 2
+    for issue in report["issues"]:
+        print(f"Non-NFC tracked path: {issue['path']!r} -> {issue['nfc_path']!r}")
+        if issue["collides_with"]:
+            print(f"  Normalization collision with: {issue['collides_with']!r}")
+    for path in report["invalid_utf8"]:
+        print(f"Tracked path is not UTF-8: {path!r}")
+    return 1 if report["issues"] or report["invalid_utf8"] else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.editorconfig

@@ -3,11 +3,14 @@ root = true
 
 [*]
 charset = utf-8
+end_of_line = lf
+trim_trailing_whitespace = true
 insert_final_newline = true
 indent_style = space
 indent_size = 2
 
 [*.md]
+trim_trailing_whitespace = false
 indent_size = 2
 max_line_length = 80
 

.editorconfig-checker.json

@@ -1,5 +1,5 @@
 {
-  "Version": "v3.4.0",
+  "Version": "v3.11.1",
   "Verbose": false,
   "Debug": false,
   "IgnoreDefaults": false,

.gitattributes

@@ -1,7 +1,7 @@
+# BEGIN source: https://github.com/gitattributes/gitattributes/blob/2c20a14833a5ab196c7fc3effcc72ef4e895f4d4/Common.gitattributes
 # Common settings that generally should always be used with your language specific settings
 
 # Auto detect text files and perform LF normalization
-# https://www.davidlaing.com/2012/09/19/customise-your-gitattributes-to-become-a-git-ninja/
 *          text=auto
 
 #
@@ -10,26 +10,28 @@
 
 # Documents
 *.bibtex   text diff=bibtex
-*.doc	        diff=astextplain
-*.DOC	        diff=astextplain
-*.docx          diff=astextplain
-*.DOCX          diff=astextplain
-*.dot           diff=astextplain
-*.DOT           diff=astextplain
-*.pdf           diff=astextplain
-*.PDF           diff=astextplain
-*.rtf           diff=astextplain
-*.RTF	        diff=astextplain
-*.md       text
+*.doc      diff=astextplain
+*.DOC      diff=astextplain
+*.docx     diff=astextplain
+*.DOCX     diff=astextplain
+*.dot      diff=astextplain
+*.DOT      diff=astextplain
+*.pdf      diff=astextplain
+*.PDF      diff=astextplain
+*.rtf      diff=astextplain
+*.RTF      diff=astextplain
+*.md       text diff=markdown
+*.mdx      text diff=markdown
 *.tex      text diff=tex
 *.adoc     text
 *.textile  text
 *.mustache text
-*.csv      text
+*.csv      text eol=crlf
 *.tab      text
 *.tsv      text
 *.txt      text
 *.sql      text
+*.epub     diff=astextplain
 
 # Graphics
 *.png      binary
@@ -39,7 +41,7 @@
 *.tif      binary
 *.tiff     binary
 *.ico      binary
-# SVG treated as an asset (binary) by default.
+# SVG treated as text by default.
 *.svg      text
 # If you want to treat it as binary,
 # use the following line instead.
@@ -49,7 +51,9 @@
 # Scripts
 *.bash     text eol=lf
 *.fish     text eol=lf
+*.ksh      text eol=lf
 *.sh       text eol=lf
+*.zsh      text eol=lf
 # These are explicitly windows files and should use crlf
 *.bat      text eol=crlf
 *.cmd      text eol=crlf
@@ -64,10 +68,24 @@
 
 # Archives
 *.7z       binary
+*.bz       binary
+*.bz2      binary
+*.bzip2    binary
 *.gz       binary
+*.lz       binary
+*.lzma     binary
+*.rar      binary
 *.tar      binary
+*.taz      binary
+*.tbz      binary
+*.tbz2     binary
 *.tgz      binary
+*.tlz      binary
+*.txz      binary
+*.xz       binary
+*.Z        binary
 *.zip      binary
+*.zst      binary
 
 # Text files where line endings should be preserved
 *.patch    -text
@@ -78,6 +96,9 @@
 
 .gitattributes export-ignore
 .gitignore     export-ignore
+.gitkeep       export-ignore
+# END source: https://github.com/gitattributes/gitattributes/blob/2c20a14833a5ab196c7fc3effcc72ef4e895f4d4/Common.gitattributes
+
 # Basic .gitattributes for a python repo.
 
 # Source files
@@ -106,3 +127,13 @@
 # with the python modules ``pickle``, ``dbm.*``,
 # ``shelve``, ``marshal``, ``anydbm``, & ``bsddb``
 # (among others).
+
+# Service inputs must survive checkout byte-for-byte, including LF-only CSVs.
+/tests/resources/** -text !eol
+/examples/resources/** -text !eol
+# Resource helpers are maintained Python, not immutable test data.
+/tests/resources/**/*.py text eol=lf
+/tests/resources/**/*.pyi text eol=lf
+
+# CIT quality tooling is vendored, not project source.
+/.cit-quality/vendor/** linguist-vendored