chant workspace versions

Synopsis

chant workspace versions [<dir>] [--template <id>] [--available [--tags <glob>]] [--json]

Description

chant workspace versions compares a family of workspaces: the workspaces made from one template. It finds every .chant/workspace.lock.json under <dir>, the current directory by default, up to eight levels down. It skips node_modules, dist and hidden directories. Pointing it at a directory of checkouts compares them all. The design is D9 of #2524, requirement T9.

For each workspace it reports:

• each lineage scope’s template and ref, with its commit;
• whether adopt-lineage recorded the lineage, the scope’s provenance (adopted once the trust policy at base admits the adopted range, unattested otherwise) and its applied migrations;
• the chant and lexicon packages its package.json declares (@intentius/chant and @intentius/chant-lexicon-*), with the version installed where node would resolve it from the workspace.

Scopes are then grouped by template id. Each family names its newest version. A member on an older version is reported as behind, not as drift, since that word already has its own meanings in chant. When members of one family have a chant or lexicon package installed at different versions, the report names them too.

$ chant workspace versions ~/checkouts
billing
  .  github.com/acme/starter@v2.0.0 (4624a0b6ca83)  unattested, 1 migration(s)
  plugins: @intentius/chant 0.80.0, @intentius/chant-lexicon-aws 0.80.0
search
  .  github.com/acme/starter@v1.4.0 (9e1d04c2b7aa)  adopted
  plugins: @intentius/chant 0.79.0, @intentius/chant-lexicon-aws 0.79.0
family github.com/acme/starter: 2 scope(s), newest 2.0.0; behind: search (v1.4.0)
  @intentius/chant differs: 0.80.0 in billing; 0.79.0 in search
  @intentius/chant-lexicon-aws differs: 0.80.0 in billing; 0.79.0 in search

Without --available, the command reads files only. It fetches nothing and runs no project code, so it works offline and on checkouts whose dependencies are not installed. A package that is not installed shows as not installed with its declared range. A lock that cannot be read is listed with the reason, and the rest of the report still prints.

It needs no chant.workspace.json, and it reads the locks it finds without changing them. Nested workspaces are listed as separate workspaces.

The template’s own versions

With --available, each family whose template is a git source also lists the template’s version tags. Each member then says how many of them are newer than the version its lock sits at. Those are the refs chant workspace upgrade --to takes. --tags narrows them with a glob, as for adopt-lineage. Listing the tags is one git ls-remote --tags per family, catalogued in Network Egress. A family whose template is not a git source, or whose tags cannot be listed, says why.

$ chant workspace versions ~/checkouts --available
...
family github.com/acme/starter: 2 scope(s), newest 2.0.0; behind: search (v1.4.0)
  available: 5 version tag(s), newest v2.1.0
  billing at v2.0.0: 1 newer
  search at v1.4.0: 3 newer

Options

Option	Effect
--template <id>	Report only the family of this template id, as the lock writes it, such as github.com/acme/starter.
--available	Also list each git template’s version tags, and how many are newer than each member’s version.
--tags <glob>	With --available, list only tags matching the glob.
--json	Print { root, workspaces, families, pluginSpread }. Each workspace has path, scopes (scope, kind, template, ref, version, commit, migrations, adoption, provenance, source) and plugins (name, declared, installed), plus error when its lock is unreadable. Each family has template, newest and members (path, scope, ref, version, behind, and with --available newer), and with --available an available object (tags, newest, and error when the tags could not be listed).

Exit codes

Code	Meaning
0	The report was printed, including an empty one
1	<dir> is not a directory