Add semver sort subcommand for sorting semantic versions (#133)

* Initial plan

* Initial planning for sort subcommand feature

Co-authored-by: justinmchase <[email protected]>

* Implement sort subcommand with comprehensive tests

Co-authored-by: justinmchase <[email protected]>

* Add README documentation for sort command

Co-authored-by: justinmchase <[email protected]>

* Address PR feedback: handle empty versions gracefully

Co-authored-by: justinmchase <[email protected]>

* Update test to capture build metadata behavior and update semver to 1.0.6

Co-authored-by: justinmchase <[email protected]>

* Add sort command to action.yml and docker-action tests, update copilot instructions

Co-authored-by: justinmchase <[email protected]>

* Remove special case logic for prerelease in none increment

Co-authored-by: justinmchase <[email protected]>

* Revert unintended test changes to version files

Co-authored-by: justinmchase <[email protected]>

* Update value input description to include sort command

Co-authored-by: justinmchase <[email protected]>

* Add tests for build metadata in None increment

Co-authored-by: justinmchase <[email protected]>

* Split version strings by whitespace to handle space-separated versions

Co-authored-by: justinmchase <[email protected]>

* Remove --desc option, keep only --asc since descending is default

Co-authored-by: justinmchase <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: justinmchase <[email protected]>
Co-authored-by: Justin Chase <[email protected]>

Author: Copilot

.github/copilot-instructions.md

@@ -200,3 +200,33 @@ The GitHub Actions workflow requires:
 
 **NEVER CANCEL operations - they complete very quickly. Set timeouts of 60+
 seconds minimum for safety.**
+
+## Adding New Subcommands
+
+When adding a new subcommand to the CLI, you MUST also update the following
+files:
+
+1. **action.yml**: Add the new subcommand to the `inputs.command.options` list
+   - This makes the command available in the GitHub Action
+   - Keep the list alphabetically sorted for consistency
+
+2. **.github/workflows/checks.yml**: Add an integration test step in the
+   `docker-action` job
+   - Add a step that tests the new subcommand using the action
+   - Follow the naming pattern: `- name: <Command Name>`
+   - Provide appropriate test values via the `with:` section
+   - This ensures the command works correctly in the Docker action context
+
+3. **README.md**: Update the usage documentation
+   - Add the new command to the commands list
+   - Provide usage examples
+   - Document any command-specific options or flags
+
+4. **src/commands/mod.ts**: Export the new command
+5. **main.ts**: Register the new command with yargs
+
+**Example**: When adding the `sort` subcommand:
+
+- Added `- sort` to action.yml command options
+- Added a "Sort" test step in docker-action job with test values
+- Updated README with sort command documentation and examples

.github/workflows/checks.yml

@@ -141,6 +141,11 @@ jobs:
           command: lte
           value: 1.2.3
           compare-to: 1.2.3
+      - name: Sort
+        uses: ./
+        with:
+          command: sort
+          value: 2.0.0 1.0.0 3.0.0
 
   docker:
     runs-on: ubuntu-latest

README.md

@@ -47,16 +47,17 @@ deno task install
 semver <command>
 
 Commands:
-  semver get            Get the version
-  semver set <value>    Set the version
-  semver inc            Increment the version
-  semver parse [value]  Parse the version and print
-  semver cmp <v1> <v2>  Compare v1 to v2 and return -1/0/1
-  semver gt <v1> <v2>   Return 0 if v1 is greater than v2, else 1
-  semver gte <v1> <v2>  Return 0 if v1 is greater than or equal to v2, else 1
-  semver lt <v1> <v2>   Return 0 if v1 is less than v2, else 1
-  semver lte <v1> <v2>  Return 0 if v1 is less than or equal to v2, else 1
-  semver eq <v1> <v2>   Return 0 if v1 is equal to v2, else 1
+  semver get                Get the version
+  semver set <value>        Set the version
+  semver inc                Increment the version
+  semver parse [value]      Parse the version and print
+  semver cmp <v1> <v2>      Compare v1 to v2 and return -1/0/1
+  semver gt <v1> <v2>       Return 0 if v1 is greater than v2, else 1
+  semver gte <v1> <v2>      Return 0 if v1 is greater than or equal to v2, else 1
+  semver lt <v1> <v2>       Return 0 if v1 is less than v2, else 1
+  semver lte <v1> <v2>      Return 0 if v1 is less than or equal to v2, else 1
+  semver eq <v1> <v2>       Return 0 if v1 is equal to v2, else 1
+  semver sort [versions..]  Sort semantic versions
 
 Options:
   --help     Show help                                                 [boolean]
@@ -74,6 +75,10 @@ command will create the `VERSION` file if it doesn't already exist.
 The `parse` command accepts a version string as input and parses and prints that
 version as output if it is valid.
 
+The `sort` command accepts one or more version strings and outputs them in
+sorted order (descending by default, one version per line). Use the `-a` flag
+for ascending order, or read versions from stdin using `--`.
+
 #### examples
 
 ```sh
@@ -97,6 +102,28 @@ semver get # 1.2.3
 semver parse 1.0.0 # {"major":1,"minor":1,"patch":0,"prerelease":[],"build":[]}
 ```
 
+```sh
+# sort versions in descending order (default)
+semver sort 2.0.0 1.0.0 3.0.0
+# 3.0.0
+# 2.0.0
+# 1.0.0
+```
+
+```sh
+# sort versions in ascending order
+semver sort -a 2.0.0 1.0.0 3.0.0
+# 1.0.0
+# 2.0.0
+# 3.0.0
+```
+
+```sh
+# sort versions from stdin
+cat versions.txt | semver sort --
+# (sorted output)
+```
+
 ### Incrementing
 
 When calling the command `inc` the `VERSION` file will be updated based on the

action.yml

@@ -20,6 +20,7 @@ inputs:
       - gte
       - lt
       - lte
+      - sort
   sub-command:
     type: choice
     description: "The kind of increment (major|minor|patch|none) for (get|inc) commands"
@@ -39,7 +40,7 @@ inputs:
     required: false
   value:
     type: string
-    description: The Version (for set, parse, eq, cmp, gt, gte, lt, lte commands)
+    description: The Version (for set, parse, eq, cmp, gt, gte, lt, lte commands) or space-separated versions (for sort command)
     required: false
   compare-to:
     type: string

deno.json

@@ -5,7 +5,7 @@
     "@std/fmt": "jsr:@std/fmt@^1.0.8",
     "json5": "npm:json5@^2.2.3",
     "jsonc-parser": "npm:jsonc-parser@^3.2.1",
-    "semver": "jsr:@std/semver@^1.0.3",
+    "semver": "jsr:@std/semver@^1.0.6",
     "path": "jsr:@std/path@^1.0.6",
     "assert": "jsr:@std/assert@^1.0.6",
     "testing/bdd": "jsr:@std/testing@^1.0.3/bdd",

deno.lock

@@ -12,6 +12,7 @@ import {
   lte,
   parse,
   set,
+  sort,
 } from "./src/commands/mod.ts";
 import { getContext } from "./src/context.ts";
 import { ApplicationError } from "./src/errors/application.error.ts";
@@ -34,6 +35,7 @@ try {
     .command(lt)
     .command(lte)
     .command(eq)
+    .command(sort)
     .strictOptions()
     .strictCommands()
     .demandCommand(1)

main.ts

@@ -8,3 +8,4 @@ export * from "./gte.ts";
 export * from "./lt.ts";
 export * from "./lte.ts";
 export * from "./eq.ts";
+export * from "./sort.ts";