keytidy 0.1.0__tar.gz

keytidy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytidy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

keytidy-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: keytidy
+Version: 0.1.0
+Summary: Tidy JSON key order — and sort package.json the conventional way (canonical field order, sorted dependencies, untouched scripts). Zero dependencies.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/keytidy-py
+Project-URL: Repository, https://github.com/jjdoor/keytidy-py
+Project-URL: Issues, https://github.com/jjdoor/keytidy-py/issues
+Keywords: json,package.json,sort,format,formatter,tidy,keys,cli,pre-commit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# keytidy
+
+**Tidy JSON key order — and sort `package.json` the way it's actually meant to
+look.** Inconsistent key order is pure diff noise: one teammate's editor writes
+`name` first, another's tool writes it last, and every PR churns lines that
+didn't really change. keytidy gives every JSON file one deterministic order.
+**Zero dependencies** (pure standard library).
+
+```bash
+pip install keytidy
+
+keytidy                 # sort ./package.json in place
+keytidy --check         # CI gate: exit 1 if anything isn't sorted
+```
+
+## It's not just "sort all the keys"
+
+Sorting `package.json` alphabetically would be *wrong* — `name` belongs at the
+top, not wedged between `module` and `optionalDependencies`. So keytidy treats
+`package.json` specially:
+
+- **Top-level fields** follow the conventional order (`name`, `version`,
+  `description`, …, `scripts`, `dependencies`, `devDependencies`, …). Unknown
+  fields (your `tool.*`, custom keys) sort alphabetically after the known ones.
+- **Dependency blocks** (`dependencies`, `devDependencies`, `peerDependencies`,
+  …) are sorted A→Z — the part you actually want sorted.
+- **`scripts` is left in your order**, because script order is frequently
+  meaningful (`pretest` → `test` → `posttest`, ordered build steps). Opt in with
+  `--sort-scripts` if you disagree.
+
+Every other `.json` file just gets a clean recursive alphabetical sort, with
+**arrays left in their original order** (an array is data, not config).
+
+## Example
+
+```jsonc
+// before
+{ "version": "1.0.0", "scripts": { "test": "…", "build": "…" },
+  "name": "demo", "dependencies": { "zod": "…", "axios": "…" } }
+
+// after  →  keytidy
+{
+  "name": "demo",
+  "version": "1.0.0",
+  "scripts": { "test": "…", "build": "…" },        // order preserved
+  "dependencies": { "axios": "…", "zod": "…" }      // sorted A→Z
+}
+```
+
+## Usage
+
+```bash
+keytidy                    # sort ./package.json in place
+keytidy package.json tsconfig.json
+keytidy *.json             # your shell expands the glob
+keytidy --check            # don't write; exit 1 if any file isn't sorted
+keytidy --stdout pkg.json  # print the sorted result instead of writing
+keytidy --indent 4         # force 4-space indent (default: detected, else 2)
+keytidy --sort-scripts     # also sort the package.json scripts block
+keytidy --all-keys         # ignore the conventional order, sort A→Z
+```
+
+You can also run it as a module: `python -m keytidy`.
+
+Indentation is **detected from the file** and preserved, so keytidy doesn't
+fight your existing 2-space / 4-space / tab style. The trailing newline is kept
+as-is.
+
+### As a CI / pre-commit gate
+
+```yaml
+# .pre-commit-config.yaml
+- repo: local
+  hooks:
+    - id: keytidy
+      name: keytidy
+      entry: keytidy --check
+      language: system
+      files: package\.json$
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | sorted (write mode) or everything already sorted (`--check`) |
+| `1` | a file needs sorting (`--check` only) |
+| `2` | invalid JSON, or a file couldn't be read/written |
+
+## Notes
+
+- It rewrites by parsing and re-serializing, so it normalizes JSON formatting.
+  It does **not** support comments or trailing commas (JSONC / `tsconfig.json`
+  with comments will report invalid JSON rather than mangle them).
+- The sort itself is pure and deterministic, shared with the Node port — for
+  typical config files the two produce identical output.
+
+## Also available for Node
+
+Same behavior, same flags: [`npx keytidy`](https://www.npmjs.com/package/keytidy)
+(source: [keytidy](https://github.com/jjdoor/keytidy)).
+
+## License
+
+MIT

keytidy-0.1.0/README.md

@@ -0,0 +1,105 @@
+# keytidy
+
+**Tidy JSON key order — and sort `package.json` the way it's actually meant to
+look.** Inconsistent key order is pure diff noise: one teammate's editor writes
+`name` first, another's tool writes it last, and every PR churns lines that
+didn't really change. keytidy gives every JSON file one deterministic order.
+**Zero dependencies** (pure standard library).
+
+```bash
+pip install keytidy
+
+keytidy                 # sort ./package.json in place
+keytidy --check         # CI gate: exit 1 if anything isn't sorted
+```
+
+## It's not just "sort all the keys"
+
+Sorting `package.json` alphabetically would be *wrong* — `name` belongs at the
+top, not wedged between `module` and `optionalDependencies`. So keytidy treats
+`package.json` specially:
+
+- **Top-level fields** follow the conventional order (`name`, `version`,
+  `description`, …, `scripts`, `dependencies`, `devDependencies`, …). Unknown
+  fields (your `tool.*`, custom keys) sort alphabetically after the known ones.
+- **Dependency blocks** (`dependencies`, `devDependencies`, `peerDependencies`,
+  …) are sorted A→Z — the part you actually want sorted.
+- **`scripts` is left in your order**, because script order is frequently
+  meaningful (`pretest` → `test` → `posttest`, ordered build steps). Opt in with
+  `--sort-scripts` if you disagree.
+
+Every other `.json` file just gets a clean recursive alphabetical sort, with
+**arrays left in their original order** (an array is data, not config).
+
+## Example
+
+```jsonc
+// before
+{ "version": "1.0.0", "scripts": { "test": "…", "build": "…" },
+  "name": "demo", "dependencies": { "zod": "…", "axios": "…" } }
+
+// after  →  keytidy
+{
+  "name": "demo",
+  "version": "1.0.0",
+  "scripts": { "test": "…", "build": "…" },        // order preserved
+  "dependencies": { "axios": "…", "zod": "…" }      // sorted A→Z
+}
+```
+
+## Usage
+
+```bash
+keytidy                    # sort ./package.json in place
+keytidy package.json tsconfig.json
+keytidy *.json             # your shell expands the glob
+keytidy --check            # don't write; exit 1 if any file isn't sorted
+keytidy --stdout pkg.json  # print the sorted result instead of writing
+keytidy --indent 4         # force 4-space indent (default: detected, else 2)
+keytidy --sort-scripts     # also sort the package.json scripts block
+keytidy --all-keys         # ignore the conventional order, sort A→Z
+```
+
+You can also run it as a module: `python -m keytidy`.
+
+Indentation is **detected from the file** and preserved, so keytidy doesn't
+fight your existing 2-space / 4-space / tab style. The trailing newline is kept
+as-is.
+
+### As a CI / pre-commit gate
+
+```yaml
+# .pre-commit-config.yaml
+- repo: local
+  hooks:
+    - id: keytidy
+      name: keytidy
+      entry: keytidy --check
+      language: system
+      files: package\.json$
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | sorted (write mode) or everything already sorted (`--check`) |
+| `1` | a file needs sorting (`--check` only) |
+| `2` | invalid JSON, or a file couldn't be read/written |
+
+## Notes
+
+- It rewrites by parsing and re-serializing, so it normalizes JSON formatting.
+  It does **not** support comments or trailing commas (JSONC / `tsconfig.json`
+  with comments will report invalid JSON rather than mangle them).
+- The sort itself is pure and deterministic, shared with the Node port — for
+  typical config files the two produce identical output.
+
+## Also available for Node
+
+Same behavior, same flags: [`npx keytidy`](https://www.npmjs.com/package/keytidy)
+(source: [keytidy](https://github.com/jjdoor/keytidy)).
+
+## License
+
+MIT

keytidy-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "keytidy"
+version = "0.1.0"
+description = "Tidy JSON key order — and sort package.json the conventional way (canonical field order, sorted dependencies, untouched scripts). Zero dependencies."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "yyfjj" }]
+keywords = ["json", "package.json", "sort", "format", "formatter", "tidy", "keys", "cli", "pre-commit"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/jjdoor/keytidy-py"
+Repository = "https://github.com/jjdoor/keytidy-py"
+Issues = "https://github.com/jjdoor/keytidy-py/issues"
+
+[project.scripts]
+keytidy = "keytidy.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

keytidy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

keytidy-0.1.0/src/keytidy/__init__.py

@@ -0,0 +1,3 @@
+"""keytidy — tidy JSON key order, with smart package.json handling. Zero dependencies."""
+
+__version__ = "0.1.0"

keytidy-0.1.0/src/keytidy/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

keytidy-0.1.0/src/keytidy/cli.py

@@ -0,0 +1,164 @@
+"""keytidy command-line interface."""
+
+import json
+import os
+import sys
+
+from . import core
+
+VERSION = "0.1.0"
+
+# ---- tiny color helpers (no dep) ----
+_COLOR = sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+
+
+def _c(code, s):
+    return f"\x1b[{code}m{s}\x1b[0m" if _COLOR else s
+
+
+def red(s): return _c("31", s)
+def green(s): return _c("32", s)
+def yellow(s): return _c("33", s)
+def dim(s): return _c("2", s)
+def bold(s): return _c("1", s)
+
+
+HELP = f"""{bold('keytidy')} — tidy JSON key order (and package.json the way it's meant to look).
+
+{bold('Usage')}
+  keytidy [file...]      Sort & rewrite the files (defaults to ./package.json)
+  keytidy --check        Don't write; exit 1 if anything isn't sorted (CI)
+  keytidy --stdout       Print the sorted result instead of writing
+  keytidy *.json         Sort every JSON file (your shell expands the glob)
+
+{bold('Options')}
+  --indent <n|tab>   Override indentation (default: detected from the file, else 2)
+  --sort-scripts     Also sort package.json "scripts" (off — script order matters)
+  --all-keys         Sort package.json purely alphabetically (ignore the conventional order)
+  --version
+
+{bold('What it does')}
+  • generic JSON  — every object's keys sorted A->Z; arrays kept in order
+  • package.json  — conventional field order (name, version, …, dependencies),
+                    dependency blocks sorted A->Z, "scripts" left as you wrote it
+
+{bold('Exit')}  0 sorted/clean · 1 needs sorting (--check) · 2 bad JSON / IO error
+"""
+
+
+def die(msg):
+    sys.stderr.write(red(f"keytidy: {msg}\n"))
+    sys.exit(2)
+
+
+def parse_args(argv):
+    opts = {"files": [], "check": False, "stdout": False, "indent": None,
+            "sortScripts": False, "allKeys": False}
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a == "--check":
+            opts["check"] = True
+        elif a == "--stdout":
+            opts["stdout"] = True
+        elif a == "--sort-scripts":
+            opts["sortScripts"] = True
+        elif a == "--all-keys":
+            opts["allKeys"] = True
+        elif a == "--indent":
+            i += 1
+            if i >= len(argv):
+                die('--indent needs a value (a number or "tab")')
+            v = argv[i]
+            if v == "tab":
+                opts["indent"] = "\t"
+            elif v.isdigit():
+                opts["indent"] = int(v)
+            else:
+                die('--indent must be a number or "tab"')
+        elif a.startswith("-"):
+            die(f"unknown flag: {a} (try --help)")
+        else:
+            opts["files"].append(a)
+        i += 1
+    return opts
+
+
+def resolve_files(files):
+    if files:
+        return files
+    if os.path.exists("package.json"):
+        return ["package.json"]
+    die("no files given and no ./package.json found — pass a JSON file")
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if "-h" in argv or "--help" in argv:
+        sys.stdout.write(HELP)
+        return 0
+    if "-v" in argv or "--version" in argv:
+        sys.stdout.write(VERSION + "\n")
+        return 0
+
+    opts = parse_args(argv)
+    files = resolve_files(opts["files"])
+
+    errored = False
+    needs_sort = False
+
+    for file in files:
+        try:
+            with open(file, encoding="utf-8") as f:
+                text = f.read()
+        except FileNotFoundError:
+            sys.stderr.write(red(f"✗ {file} — no such file\n"))
+            errored = True
+            continue
+        except OSError as e:
+            sys.stderr.write(red(f"✗ {file} — {e}\n"))
+            errored = True
+            continue
+
+        try:
+            result = core.process(text, {
+                "packageJson": os.path.basename(file) == "package.json",
+                "indent": opts["indent"],
+                "sortScripts": opts["sortScripts"],
+                "allKeys": opts["allKeys"],
+            })
+        except (json.JSONDecodeError, ValueError) as e:
+            sys.stderr.write(red(f"✗ {file} — invalid JSON: {e}\n"))
+            errored = True
+            continue
+
+        if opts["stdout"]:
+            sys.stdout.write(result["output"])
+            continue
+        if opts["check"]:
+            if result["changed"]:
+                needs_sort = True
+                sys.stdout.write("{} {} {}\n".format(yellow("✗"), file, dim("— not sorted")))
+            else:
+                sys.stdout.write("{} {} {}\n".format(green("✓"), file, dim("— sorted")))
+            continue
+        # write mode
+        if result["changed"]:
+            try:
+                with open(file, "w", encoding="utf-8") as f:
+                    f.write(result["output"])
+            except OSError as e:
+                sys.stderr.write(red(f"✗ {file} — {e}\n"))
+                errored = True
+                continue
+            sys.stdout.write("{} {} {}\n".format(green("✓"), bold(file), dim("— sorted")))
+        else:
+            sys.stdout.write("{} {} {}\n".format(dim("•"), file, dim("— already sorted")))
+
+    if errored:
+        return 2
+    if opts["check"] and needs_sort:
+        if not opts["stdout"]:
+            sys.stdout.write("\n{} {} {}\n".format(dim("run"), bold("keytidy"), dim("to fix")))
+        return 1
+    return 0

keytidy-0.1.0/src/keytidy/core.py

@@ -0,0 +1,96 @@
+"""keytidy core — pure JSON key-ordering logic. No fs, no process, no clock.
+
+Two jobs:
+
+  1. Generic JSON — recursively sort every object's keys alphabetically. Arrays
+     keep their order (arrays are data, not config); primitives are untouched.
+     The point is to kill the diff noise from tools that emit keys in arbitrary
+     order.
+  2. package.json — sorting it alphabetically would be *wrong* (``name`` should
+     come before ``dependencies``). So package.json gets the conventional field
+     order at the top level, its dependency objects sorted alphabetically, and
+     its ``scripts`` block left in the author's order.
+
+Mirrors the Node port behavior. The fs/CLI plumbing lives in cli.py.
+"""
+
+import json
+import re
+
+# Conventional top-level order for package.json (npm's own ordering plus what
+# the ecosystem settled on). Keys not in this list are appended alphabetically.
+PACKAGE_FIELD_ORDER = [
+    "$schema", "name", "displayName", "version", "private", "description",
+    "keywords", "license", "licenses", "homepage", "repository", "bugs", "funding",
+    "author", "contributors", "maintainers", "type", "imports", "exports", "main",
+    "module", "browser", "unpkg", "jsdelivr", "types", "typings", "typesVersions",
+    "bin", "man", "files", "directories", "scripts", "config", "sideEffects",
+    "workspaces", "engines", "engineStrict", "os", "cpu", "packageManager",
+    "publishConfig", "dependencies", "devDependencies", "peerDependencies",
+    "peerDependenciesMeta", "optionalDependencies", "bundledDependencies",
+    "bundleDependencies", "overrides", "resolutions",
+]
+
+# Within package.json, these object values keep their original key order.
+PRESERVE_ORDER_FIELDS = {"scripts"}
+
+_INDENT_RE = re.compile(r'\n([ \t]+)["\]{}]')
+
+
+def detect_indent(text):
+    """Detect the indentation of an existing JSON document. Returns a space
+    count, the string "\\t", or 2."""
+    m = _INDENT_RE.search(text)
+    if not m:
+        return 2
+    return "\t" if m.group(1)[0] == "\t" else len(m.group(1))
+
+
+def order_package_keys(keys):
+    """Return package.json keys in conventional order: known fields first (in
+    canonical sequence), then unknown fields alphabetically."""
+    known = set(PACKAGE_FIELD_ORDER)
+    present = [k for k in PACKAGE_FIELD_ORDER if k in keys]
+    unknown = sorted(k for k in keys if k not in known)
+    return present + unknown
+
+
+def sort_value(value, opts, package_top):
+    """Recursively produce a key-sorted copy of ``value``."""
+    if isinstance(value, list):
+        return [sort_value(v, opts, False) for v in value]
+    if not isinstance(value, dict):
+        return value
+
+    keys = list(value.keys())
+    if package_top and not opts.get("allKeys"):
+        ordered = order_package_keys(keys)
+    else:
+        ordered = sorted(keys)
+
+    out = {}
+    for k in ordered:
+        preserve = package_top and not opts.get("sortScripts") and k in PRESERVE_ORDER_FIELDS
+        out[k] = value[k] if preserve else sort_value(value[k], opts, False)
+    return out
+
+
+def serialize(value, indent):
+    """Serialize matching the Node port: given indent, ``: `` / ``,`` separators,
+    UTF-8 (no \\uXXXX escaping)."""
+    return json.dumps(value, indent=indent, ensure_ascii=False, separators=(",", ": "))
+
+
+def process(text, opts=None):
+    """Sort one JSON document. Returns ``{"output": str, "changed": bool}``.
+    Raises ValueError (via json) on invalid JSON."""
+    opts = opts or {}
+    data = json.loads(text)
+    indent = opts["indent"] if opts.get("indent") is not None else detect_indent(text)
+    package_top = bool(opts.get("packageJson")) and isinstance(data, dict)
+    sorted_data = sort_value(data, {"sortScripts": bool(opts.get("sortScripts")),
+                                    "allKeys": bool(opts.get("allKeys"))}, package_top)
+    output = serialize(sorted_data, indent)
+    if text.endswith("\n"):
+        output += "\n"
+    return {"output": output, "changed": output != text}

keytidy-0.1.0/src/keytidy.egg-info/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: keytidy
+Version: 0.1.0
+Summary: Tidy JSON key order — and sort package.json the conventional way (canonical field order, sorted dependencies, untouched scripts). Zero dependencies.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/keytidy-py
+Project-URL: Repository, https://github.com/jjdoor/keytidy-py
+Project-URL: Issues, https://github.com/jjdoor/keytidy-py/issues
+Keywords: json,package.json,sort,format,formatter,tidy,keys,cli,pre-commit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# keytidy
+
+**Tidy JSON key order — and sort `package.json` the way it's actually meant to
+look.** Inconsistent key order is pure diff noise: one teammate's editor writes
+`name` first, another's tool writes it last, and every PR churns lines that
+didn't really change. keytidy gives every JSON file one deterministic order.
+**Zero dependencies** (pure standard library).
+
+```bash
+pip install keytidy
+
+keytidy                 # sort ./package.json in place
+keytidy --check         # CI gate: exit 1 if anything isn't sorted
+```
+
+## It's not just "sort all the keys"
+
+Sorting `package.json` alphabetically would be *wrong* — `name` belongs at the
+top, not wedged between `module` and `optionalDependencies`. So keytidy treats
+`package.json` specially:
+
+- **Top-level fields** follow the conventional order (`name`, `version`,
+  `description`, …, `scripts`, `dependencies`, `devDependencies`, …). Unknown
+  fields (your `tool.*`, custom keys) sort alphabetically after the known ones.
+- **Dependency blocks** (`dependencies`, `devDependencies`, `peerDependencies`,
+  …) are sorted A→Z — the part you actually want sorted.
+- **`scripts` is left in your order**, because script order is frequently
+  meaningful (`pretest` → `test` → `posttest`, ordered build steps). Opt in with
+  `--sort-scripts` if you disagree.
+
+Every other `.json` file just gets a clean recursive alphabetical sort, with
+**arrays left in their original order** (an array is data, not config).
+
+## Example
+
+```jsonc
+// before
+{ "version": "1.0.0", "scripts": { "test": "…", "build": "…" },
+  "name": "demo", "dependencies": { "zod": "…", "axios": "…" } }
+
+// after  →  keytidy
+{
+  "name": "demo",
+  "version": "1.0.0",
+  "scripts": { "test": "…", "build": "…" },        // order preserved
+  "dependencies": { "axios": "…", "zod": "…" }      // sorted A→Z
+}
+```
+
+## Usage
+
+```bash
+keytidy                    # sort ./package.json in place
+keytidy package.json tsconfig.json
+keytidy *.json             # your shell expands the glob
+keytidy --check            # don't write; exit 1 if any file isn't sorted
+keytidy --stdout pkg.json  # print the sorted result instead of writing
+keytidy --indent 4         # force 4-space indent (default: detected, else 2)
+keytidy --sort-scripts     # also sort the package.json scripts block
+keytidy --all-keys         # ignore the conventional order, sort A→Z
+```
+
+You can also run it as a module: `python -m keytidy`.
+
+Indentation is **detected from the file** and preserved, so keytidy doesn't
+fight your existing 2-space / 4-space / tab style. The trailing newline is kept
+as-is.
+
+### As a CI / pre-commit gate
+
+```yaml
+# .pre-commit-config.yaml
+- repo: local
+  hooks:
+    - id: keytidy
+      name: keytidy
+      entry: keytidy --check
+      language: system
+      files: package\.json$
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | sorted (write mode) or everything already sorted (`--check`) |
+| `1` | a file needs sorting (`--check` only) |
+| `2` | invalid JSON, or a file couldn't be read/written |
+
+## Notes
+
+- It rewrites by parsing and re-serializing, so it normalizes JSON formatting.
+  It does **not** support comments or trailing commas (JSONC / `tsconfig.json`
+  with comments will report invalid JSON rather than mangle them).
+- The sort itself is pure and deterministic, shared with the Node port — for
+  typical config files the two produce identical output.
+
+## Also available for Node
+
+Same behavior, same flags: [`npx keytidy`](https://www.npmjs.com/package/keytidy)
+(source: [keytidy](https://github.com/jjdoor/keytidy)).
+
+## License
+
+MIT

keytidy-0.1.0/src/keytidy.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/keytidy/__init__.py
+src/keytidy/__main__.py
+src/keytidy/cli.py
+src/keytidy/core.py
+src/keytidy.egg-info/PKG-INFO
+src/keytidy.egg-info/SOURCES.txt
+src/keytidy.egg-info/dependency_links.txt
+src/keytidy.egg-info/entry_points.txt
+src/keytidy.egg-info/top_level.txt
+tests/test_core.py

keytidy-0.1.0/src/keytidy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

keytidy-0.1.0/src/keytidy.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+keytidy = keytidy.cli:main

keytidy-0.1.0/src/keytidy.egg-info/top_level.txt

@@ -0,0 +1 @@
+keytidy

keytidy-0.1.0/tests/test_core.py

@@ -0,0 +1,103 @@
+import json
+
+import pytest
+
+from keytidy import core
+
+
+def keys_of(s):
+    return list(json.loads(s).keys())
+
+
+# ---- order_package_keys ----------------------------------------------------
+
+def test_order_package_keys():
+    assert core.order_package_keys(["dependencies", "name", "zzz", "version", "aaa"]) == \
+        ["name", "version", "dependencies", "aaa", "zzz"]
+
+
+# ---- detect_indent ---------------------------------------------------------
+
+def test_detect_indent():
+    assert core.detect_indent('{\n  "a": 1\n}') == 2
+    assert core.detect_indent('{\n    "a": 1\n}') == 4
+    assert core.detect_indent('{\n\t"a": 1\n}') == "\t"
+    assert core.detect_indent("{}") == 2
+
+
+# ---- generic JSON ----------------------------------------------------------
+
+def test_generic_sort_recursive():
+    src = json.dumps({"b": 1, "a": 2, "nested": {"z": 1, "y": 2}}, indent=2)
+    out = core.process(src, {"packageJson": False})["output"]
+    assert keys_of(out) == ["a", "b", "nested"]
+    assert list(json.loads(out)["nested"].keys()) == ["y", "z"]
+
+
+def test_arrays_keep_order_but_objects_inside_sort():
+    src = json.dumps({"list": [3, 1, 2], "rows": [{"b": 1, "a": 2}]})
+    parsed = json.loads(core.process(src, {})["output"])
+    assert parsed["list"] == [3, 1, 2]
+    assert list(parsed["rows"][0].keys()) == ["a", "b"]
+
+
+# ---- package.json ----------------------------------------------------------
+
+PKG = json.dumps({
+    "version": "1.0.0",
+    "scripts": {"test": "t", "build": "b"},
+    "name": "x",
+    "dependencies": {"b": "1", "a": "1"},
+    "description": "d",
+    "customField": 1,
+}, indent=2)
+
+
+def test_package_top_level_order():
+    out = core.process(PKG, {"packageJson": True})["output"]
+    assert keys_of(out) == ["name", "version", "description", "scripts", "dependencies", "customField"]
+
+
+def test_deps_sorted_scripts_preserved():
+    parsed = json.loads(core.process(PKG, {"packageJson": True})["output"])
+    assert list(parsed["dependencies"].keys()) == ["a", "b"]
+    assert list(parsed["scripts"].keys()) == ["test", "build"]
+
+
+def test_sort_scripts_flag():
+    parsed = json.loads(core.process(PKG, {"packageJson": True, "sortScripts": True})["output"])
+    assert list(parsed["scripts"].keys()) == ["build", "test"]
+
+
+def test_all_keys_flag():
+    out = core.process(PKG, {"packageJson": True, "allKeys": True})["output"]
+    assert keys_of(out) == ["customField", "dependencies", "description", "name", "scripts", "version"]
+
+
+def test_non_package_file_is_plain_alphabetical():
+    out = core.process(PKG, {"packageJson": False})["output"]
+    assert keys_of(out) == ["customField", "dependencies", "description", "name", "scripts", "version"]
+
+
+# ---- idempotency & formatting ---------------------------------------------
+
+def test_idempotent():
+    once = core.process(PKG, {"packageJson": True})["output"]
+    twice = core.process(once, {"packageJson": True})
+    assert twice["changed"] is False
+    assert twice["output"] == once
+
+
+def test_trailing_newline_preserved():
+    assert core.process('{"b":1,"a":2}\n', {})["output"].endswith("\n")
+    assert not core.process('{"b":1,"a":2}', {})["output"].endswith("\n")
+
+
+def test_indent_override():
+    out = core.process('{\n  "b": 1,\n  "a": 2\n}', {"indent": 4})["output"]
+    assert '\n    "a"' in out
+
+
+def test_invalid_json_raises():
+    with pytest.raises(ValueError):
+        core.process("{not json}", {})