add a README

README.md

@@ -0,0 +1,86 @@
+# Changelord, registrar of deeds extraordinaire
+
+Changelord is a changelog manager scratching my particular itches.
+It's cli-based, and keep its data in a YAML file adhering
+to a well-defined schema.
+
+The first iteration of `changelord` was written [in Perl][original]. You can
+read its [introductory article][blog] on my blog.
+
+## Installation
+
+    pnpm install changelord
+
+## CLI commands
+
+### Global options
+
+#### `--help`
+
+Outputs the list of commands and options.
+
+#### `--version`
+
+Outputs the `changelord` version.
+
+#### `--source`
+
+Specifies which source yaml file to use. Defaults to the `CHANGELOG.yml` file
+in the current directory.
+
+### `changelord init`
+
+Initializes the changelog source file. The YAML file is made of three
+sections.
+
+- `project` -- contains information and configuration about the project itself.
+- `releases` -- the entries for the changelog proper.
+- `change_types` -- defines all types of changes this project supports.
+
+### `changelord add`
+
+Adds an entry to the `NEXT` release.
+
+    $ changelord add --type=maint added a changelog to the project.
+
+#### Options
+
+- `--type` -- type of change.
+- `--ticket` -- associated ticket.
+
+### `changelord print`
+
+Renders the changelog as markdown.
+
+#### Options
+
+- `--no-next` -- don't show the `NEXT` section.
+
+### `changelord cut`
+
+Cuts the next release. That is, resolves the `NEXT` version number based on the
+latest version and the changes in the `NEXT` section, and sets its date as
+today. Modifies the source file with the result.
+
+#### Options
+
+- `--dry` -- Resolves the next version but only outputs the resulting section
+  without changing the source file.
+
+### `changelord schema`
+
+Outputs the JSON schema defining the structure of the source file.
+
+### `changelord upcoming`
+
+Outputs the changes listed in the `NEXT` release.
+
+### `changelord latest-version`
+
+Outputs the latest non-NEXT release.
+
+    $ changelord latest-version
+    3.2.0
+
+[blog]: https://techblog.babyl.ca/entry/changelord/
+[original]: https://metacpan.org/dist/App-Changelord/view/bin/changelord

src/changelord.js

@@ -13,6 +13,7 @@ import schema from "./command/schema.js";
 import add from "./command/add.js";
 import cut from "./command/cut.js";
 import upcoming from "./command/upcoming.js";
+import latest from "./command/latest-version.js";
 
 consola.raw = (...args) => console.log(...args);
 
@@ -22,13 +23,13 @@ yargs(hideBin(process.argv))
     })
     .default("source", join(process.cwd(), "CHANGELOG.yml"))
     .describe("source", "changelog source")
-  .command(print)
     .command(init)
     .command(add)
-  .command(schema)
-  .command(cut)
     .command(print)
+    .command(cut)
+    .command(schema)
     .command(upcoming)
+    .command(latest)
     .strictCommands()
     .help()
     .parse();

src/command/add.js

@@ -26,7 +26,9 @@ export default {
     builder: (yargs) => {
         yargs
             .string("ticket")
+            .describe("ticket", "ticket associated with the change")
             .string("type")
+            .describe("type", "type of change")
             .middleware((argv) => {
                 argv.add_to_next = async (entry) => {
                     const changelog = yaml.parse(await fs.readFile(argv.source, "utf-8"));

src/command/latest-version.js

@@ -0,0 +1,27 @@
+import yaml from "yaml";
+import fs from "fs-extra";
+
+const handler = async (config) => {
+  const changelog = yaml.parse(await fs.readFile(config.source, "utf-8"));
+
+  const latest_version = changelog.releases.find(
+    ({ version }) => version !== "NEXT"
+  );
+
+  if (config.json) {
+    config.consola.raw(latest_version);
+  } else {
+    config.consola.raw(latest_version.version);
+  }
+};
+
+export default {
+  command: "latest-version",
+  desc: "output the latest version present in the changelog",
+  builder: (yargs) => {
+    yargs
+      .boolean("json")
+      .describe("json", "output latest version entry as json");
+  },
+  handler,
+};