@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/ls.js

@@ -0,0 +1,277 @@
+/**
+ * `chant workspace ls [dir] [--at <rev>] [--json]` (#2534): list a workspace's
+ * members and example groups from its declaration.
+ *
+ * A member that can't be read is still listed, with a reason code, and the
+ * command still exits 0 (#2524 D15, ws-020). Failing on it is the job of
+ * `chant workspace check`. Only a declaration that can't be read exits 1.
+ *
+ * The `--json` output is part of the read contract, versioned like
+ * `workspace records` and described by `ls.schema.json` beside this file.
+ *
+ * The record kinds the declaration names are listed too, the workspace's own
+ * and each member's, with each kind file's own name when it loads (#2680).
+ * Loading one imports it, so {@link listWorkspace} lists them unloaded and
+ * {@link listWorkspaceWithKinds}, which the command runs, loads them.
+ *
+ * The declared diagram artifacts are listed too, flattened across the
+ * workspace and its members into one `diagrams` array (#2764). Unlike record
+ * kinds, nothing about a diagram is loaded: everything printed comes
+ * straight from the declaration, and chant runs no renderer to list it.
+ */
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { formatError } from "../cli/format.js";
+import { declaredDiagrams, extensionsAt, readDeclaration, readerVersion, resolveGroups, WorkspaceReadError, } from "./declaration.js";
+import { memberGenerated } from "./ls-generated.js";
+import { loadKindRegistry, probeKind } from "./kinds.js";
+import { handToRootChant, locateWorkspace } from "./which-chant.js";
+import { declaredSessions } from "./write-scope.js";
+/** The version of the `ls` output this chant writes. */
+export const LS_CONTRACT_VERSION = 1;
+/** `$id` of the JSON Schema for the `--json` output, shipped beside this file. */
+export const LS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/ls/v1/ls.schema.json";
+const USAGE = "chant workspace ls [dir] [--at <rev>] [--json]";
+/**
+ * Why one member can't be read. Closed, like the error codes: a new code is a
+ * contract change.
+ */
+export const MEMBER_REASON_CODES = [
+    /** The member's directory does not exist. */
+    "dir-missing",
+    /** No built-in kind or pinned package supplies the member's kind. */
+    "unknown-kind",
+    /** The directory is not what its kind reads, such as a `chant` member with no chant config. */
+    "kind-probe-failed",
+];
+/** Why a group lists nothing. */
+export const GROUP_REASON_CODES = [
+    /** No directory the globs match holds a chant project. */
+    "no-matches",
+];
+/** A member's reason code, or null when its kind can read it. */
+export function memberReason(member, tree, kinds) {
+    if (tree.stat(member.dir === "." ? "" : member.dir) !== "dir") {
+        return { code: "dir-missing", message: `${member.dir} is not a directory${tree.label}` };
+    }
+    const kind = kinds.get(member.kind);
+    if (!kind) {
+        return { code: "unknown-kind", message: `no built-in kind or pinned package supplies kind ${member.kind}; known kinds: ${kinds.names().join(", ")}` };
+    }
+    if (!probeKind(kind, tree, member.dir === "." ? "" : member.dir)) {
+        return { code: "kind-probe-failed", message: `${member.dir} is not ${kind.description}` };
+    }
+    return null;
+}
+/**
+ * Find the workspace, read it and build the document `--json` prints, with
+ * the declared record kinds unloaded: `kind` null and no reason. Never throws
+ * a {@link WorkspaceReadError}.
+ */
+export function listWorkspace(query) {
+    return readListing(query).doc;
+}
+/** {@link listWorkspace}, with each declared record kind loaded for its name, or the reason it can't be (#2680). */
+export async function listWorkspaceWithKinds(query) {
+    const { doc, declaration, tree, rootOnDisk } = readListing(query);
+    if (!declaration || "error" in doc)
+        return doc;
+    const { loadDeclaredKinds } = await import("./declared-kinds.js");
+    const loaded = await loadDeclaredKinds(declaration, tree, rootOnDisk, { acceptance: true, ...(doc.at !== null ? { at: doc.at } : {}) });
+    const byPath = new Map(loaded.map((k) => [k.declared.path, k]));
+    const fill = (r) => {
+        const k = byPath.get(r.path);
+        const acceptance = k.acceptance ? k.acceptance.map((a) => ({ item: a.item, state: a.state, met: a.met, total: a.total })) : null;
+        return { ...r, name: r.name ?? k.kind, kind: k.kind, reason: k.reason, acceptance };
+    };
+    return {
+        ...doc,
+        workspace: { ...doc.workspace, records: doc.workspace.records.map(fill) },
+        members: doc.members.map((m) => ({ ...m, records: m.records.map(fill) })),
+    };
+}
+const unloaded = (records) => records.map((r) => ({ name: r.name, path: r.path, kind: null, reason: null, acceptance: null }));
+function readListing(query) {
+    const chant = readerVersion();
+    const head = { $schema: LS_OUTPUT_SCHEMA_ID, contract: LS_CONTRACT_VERSION, chant };
+    try {
+        const located = locateWorkspace(query.cwd, query.at);
+        const { tree, rootOnDisk, at } = located;
+        const declaration = readDeclaration(tree, "", { rootChant: true });
+        // Kinds come from the pinned packages installed in the working tree, also
+        // for --at: they are read as data, never run (#2535).
+        const kinds = query.kinds ?? loadKindRegistry(declaration.pins, rootOnDisk).registry;
+        const groups = resolveGroups(declaration, tree);
+        const repoPrefix = isAbsolute(located.root) ? "." : located.root;
+        // Sessions are read where the write paths read them, at base (#3615); a
+        // listing at a revision reads them there, so it describes one commit.
+        const sessions = at !== null ? { agents: declaration.agents, from: "at" } : (declaredSessions(query.cwd) ?? { agents: declaration.agents, from: "working-tree" });
+        const members = declaration.members.map((m) => {
+            const reason = memberReason(m, tree, kinds);
+            return {
+                name: m.name,
+                dir: m.dir,
+                kind: m.kind,
+                roles: m.roles,
+                upstream: m.upstream,
+                because: m.because,
+                readable: reason === null,
+                reason,
+                records: unloaded(m.records),
+                generated: memberGenerated(m, tree, repoPrefix),
+                agents: sessions.agents.filter((a) => a.members.includes(m.name)).map((a) => a.name),
+                // The member's x- keys, as declared (#3595).
+                ...extensionsAt(declaration, m.pointer),
+            };
+        });
+        const lsGroups = groups.map((g) => ({
+            name: g.group.name,
+            kind: "examples",
+            glob: g.group.globs,
+            matches: g.matches,
+            skipped: g.skipped,
+            reason: g.matches.length === 0
+                ? { code: "no-matches", message: `no directory ${g.group.globs.join(" or ")} matches${tree.label} holds a chant project` }
+                : null,
+        }));
+        const diagrams = declaredDiagrams(declaration).map((d) => ({
+            name: d.name,
+            title: d.title,
+            source: d.source,
+            render: d.render,
+            renderer: d.renderer,
+            member: d.member,
+        }));
+        const doc = {
+            ...head,
+            at,
+            workspace: {
+                name: declaration.name,
+                root: located.root,
+                file: declaration.file,
+                schema: declaration.schema,
+                minReader: declaration.minReader,
+                pins: declaration.pins,
+                records: unloaded(declaration.records),
+                agentsFrom: sessions.from,
+                ...extensionsAt(declaration, ""),
+            },
+            members,
+            groups: lsGroups,
+            diagrams,
+            ci: declaration.ci
+                ? {
+                    green: declaration.ci.green
+                        ? {
+                            branch: declaration.ci.green.branch,
+                            window: declaration.ci.green.window,
+                            phases: declaration.ci.green.phases.map((p) => ({ name: p.name, runs: p.runs, skipped: p.skipped })),
+                            require: declaration.ci.green.require,
+                        }
+                        : null,
+                }
+                : null,
+            summary: {
+                members: members.length,
+                unreadable: members.filter((m) => !m.readable).length,
+                groups: lsGroups.length,
+                matches: lsGroups.reduce((n, g) => n + g.matches.length, 0),
+            },
+        };
+        return { doc, declaration, tree, rootOnDisk };
+    }
+    catch (err) {
+        if (!(err instanceof WorkspaceReadError))
+            throw err;
+        return { doc: { ...head, error: { code: err.code, message: err.message, location: err.location ?? null } } };
+    }
+}
+export async function runWorkspaceLs(ctx) {
+    const { args } = ctx;
+    const cwd = resolve(args.extraPositional ?? ".");
+    if (!existsSync(cwd)) {
+        console.error(formatError({ message: `${cwd} does not exist`, hint: USAGE }));
+        return 1;
+    }
+    // The root's chant reads the declaration (ws-021).
+    const handed = await handToRootChant(cwd, args.at);
+    if (handed !== undefined)
+        return handed;
+    const doc = await listWorkspaceWithKinds({ cwd, at: args.at });
+    if (args.json) {
+        console.log(JSON.stringify(doc, null, 2));
+    }
+    else if ("error" in doc) {
+        const l = doc.error.location;
+        const where = l ? `${l.file}:${l.line}:${l.column}: ` : "";
+        console.error(formatError({ message: `${doc.error.code}: ${where}${doc.error.message}`, hint: USAGE }));
+    }
+    else {
+        console.log(formatLs(doc));
+    }
+    return "error" in doc ? 1 : 0;
+}
+function table(rows) {
+    const widths = rows[0].map((_, c) => Math.max(...rows.map((r) => r[c].length)));
+    return rows.map((r) => r.map((cell, c) => (c === r.length - 1 ? cell : cell.padEnd(widths[c]))).join("  ").trimEnd());
+}
+function formatLs(doc) {
+    const lines = [];
+    const w = doc.workspace;
+    lines.push(`${w.name}  (${w.root === "." ? w.file : `${w.root}/${w.file}`}${doc.at ? ` at ${doc.at.slice(0, 8)}` : ""})`);
+    if (doc.members.length > 0) {
+        lines.push("");
+        const rows = [["MEMBER", "KIND", "DIR", "ROLES"]];
+        for (const m of doc.members) {
+            rows.push([m.name, m.kind, m.dir, m.roles.map((r) => (r.path ? `${r.name}:${r.path}` : r.name)).join(",")]);
+        }
+        const rendered = table(rows);
+        lines.push(rendered[0]);
+        doc.members.forEach((m, i) => {
+            lines.push(rendered[i + 1]);
+            if (m.reason)
+                lines.push(`  ${m.reason.code}: ${m.reason.message}`);
+        });
+    }
+    const kinds = [...w.records.map((r) => ({ owner: "(workspace)", r })), ...doc.members.flatMap((m) => m.records.map((r) => ({ owner: m.name, r })))];
+    if (kinds.length > 0) {
+        lines.push("");
+        const rows = [["RECORDS", "KIND", "MEMBER", "FILE"]];
+        for (const { owner, r } of kinds)
+            rows.push([r.name ?? "-", r.kind ?? "-", owner, r.path]);
+        const rendered = table(rows);
+        lines.push(rendered[0]);
+        kinds.forEach(({ r }, i) => {
+            lines.push(rendered[i + 1]);
+            if (r.reason)
+                lines.push(`  ${r.reason.code}: ${r.reason.message}`);
+            for (const a of r.acceptance ?? [])
+                lines.push(`  ${a.item} ${a.state ?? "-"}: ${a.met}/${a.total} criteria met`);
+        });
+    }
+    if (doc.diagrams.length > 0) {
+        lines.push("");
+        const rows = [["DIAGRAM", "MEMBER", "SOURCE", "RENDER", "RENDERER"]];
+        for (const d of doc.diagrams)
+            rows.push([d.name, d.member ?? "(workspace)", d.source ?? "-", d.render ?? "-", `${d.renderer.tool} ${d.renderer.version}`]);
+        lines.push(...table(rows));
+    }
+    if (doc.groups.length > 0) {
+        lines.push("");
+        const rows = [["GROUP", "KIND", "GLOB", "PROJECTS"]];
+        for (const g of doc.groups)
+            rows.push([g.name, g.kind, g.glob.join(" "), String(g.matches.length)]);
+        const rendered = table(rows);
+        lines.push(rendered[0]);
+        doc.groups.forEach((g, i) => {
+            lines.push(rendered[i + 1]);
+            if (g.reason)
+                lines.push(`  ${g.reason.code}: ${g.reason.message}`);
+        });
+    }
+    const s = doc.summary;
+    lines.push("");
+    lines.push(`${s.members} member${s.members === 1 ? "" : "s"}, ${s.unreadable} unreadable; ` +
+        `${s.groups} example group${s.groups === 1 ? "" : "s"} with ${s.matches} project${s.matches === 1 ? "" : "s"}`);
+    return lines.join("\n");
+}

package/dist/workspace/ls.schema.json

@@ -0,0 +1,333 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/ls/v1/ls.schema.json",
+  "title": "chant workspace ls output",
+  "description": "What `chant workspace ls --json` prints, version 1 of the read contract for listing a workspace (#2524 D15, #2534). Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
+  "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }],
+  "$defs": {
+    "ciGreen": {
+      "description": "Which commits chant ci tick tags green: the first-parent commits of branch within window whose required phases all passed.",
+      "type": "object",
+      "required": ["branch", "window", "phases", "require"],
+      "properties": {
+        "branch": { "type": "string" },
+        "window": { "type": "string", "description": "Such as 24h, the default." },
+        "phases": {
+          "description": "In file order.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "runs", "skipped"],
+            "properties": {
+              "name": { "type": "string" },
+              "runs": { "type": "array", "items": { "type": "string" }, "description": "Check-run name patterns, * standing for any run of characters." },
+              "skipped": { "enum": ["pass", "fail"], "description": "What a run that finished as skipped counts as." }
+            }
+          }
+        },
+        "require": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "result": {
+      "description": "The declaration was read. Exit code 0, even when some members can't be read.",
+      "type": "object",
+      "required": ["$schema", "contract", "chant", "at", "workspace", "members", "groups", "diagrams", "summary"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/ls/v1/ls.schema.json" },
+        "contract": { "const": 1 },
+        "chant": { "type": "string", "description": "The version of the chant that read the workspace." },
+        "at": {
+          "description": "The full commit id the workspace was read at (--at), or null for the working tree.",
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{40,64}$"
+        },
+        "error": false,
+        "workspace": {
+          "type": "object",
+          "patternProperties": { "^x-": { "description": "Added in contract 1 by #3595. An x- key the declaration holds at the top level, with its value as written." } },
+          "required": ["name", "root", "file", "schema", "minReader", "pins"],
+          "properties": {
+            "name": { "type": "string", "description": "The declared name. With the revision, it identifies the workspace." },
+            "root": {
+              "type": "string",
+              "description": "The workspace root relative to the git root, with / separators, \".\" for the git root itself. An absolute path outside a git repository."
+            },
+            "file": { "enum": ["chant.workspace.json", "chant.workspace.jsonc"] },
+            "schema": { "const": 1 },
+            "minReader": { "type": ["string", "null"] },
+            "pins": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["package", "version", "path", "integrity"],
+                "properties": {
+                  "package": { "type": ["string", "null"] },
+                  "version": { "type": ["string", "null"] },
+                  "path": { "type": ["string", "null"] },
+                  "integrity": { "type": ["string", "null"] }
+                }
+              }
+            },
+            "records": {
+              "description": "Added in contract 1 by #2680. The workspace's own record kinds, from the declaration's top-level records, in file order.",
+              "type": "array",
+              "items": { "$ref": "#/$defs/recordKind" }
+            },
+            "agentsFrom": {
+              "description": "Added in contract 1 by #3615. Where the members' agents were read: base, the declaration at the base revision (origin/HEAD, main or master), as chant workspace agent and the write paths read it; working-tree, when there is no base or no declaration at it; at, the declaration at the --at revision.",
+              "enum": ["base", "working-tree", "at"]
+            }
+          }
+        },
+        "members": {
+          "description": "Every member, in declaration order, readable or not.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/member" }
+        },
+        "groups": {
+          "description": "Every example group (ws-051), in declaration order. Their matches are not members.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/group" }
+        },
+        "diagrams": {
+          "description": "Added in contract 1 by #2764. Every declared diagram artifact, flattened across the workspace and its members: the workspace's own first, then each member's, in file order.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/diagram" }
+        },
+        "ci": {
+          "description": "Added in contract 1 by #3573 (ws-103), so absent from an older chant's output. The declaration's ci block with its defaults filled in, or null when it has none; green is null when the block declares no green.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["green"],
+              "properties": { "green": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/ciGreen" }] } }
+            }
+          ]
+        },
+        "summary": {
+          "type": "object",
+          "required": ["members", "unreadable", "groups", "matches"],
+          "properties": {
+            "members": { "type": "integer", "minimum": 0 },
+            "unreadable": { "type": "integer", "minimum": 0, "description": "Members with a reason." },
+            "groups": { "type": "integer", "minimum": 0 },
+            "matches": { "type": "integer", "minimum": 0, "description": "Projects across all groups." }
+          }
+        }
+      }
+    },
+    "member": {
+      "type": "object",
+      "patternProperties": { "^x-": { "description": "Added in contract 1 by #3595. An x- key the declaration holds on this object, with its value as written." } },
+      "required": ["name", "dir", "kind", "roles", "upstream", "because", "readable", "reason"],
+      "properties": {
+        "name": { "type": "string" },
+        "dir": { "type": "string", "description": "Relative to the workspace root, with / separators; \".\" is the root member." },
+        "kind": { "type": "string" },
+        "roles": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "path"],
+            "properties": {
+              "name": { "type": "string" },
+              "path": { "type": ["string", "null"], "description": "Relative to the member's directory, or null for the whole member." }
+            }
+          }
+        },
+        "upstream": { "type": ["string", "null"] },
+        "because": { "type": ["string", "null"] },
+        "readable": { "type": "boolean", "description": "True exactly when reason is null." },
+        "records": {
+          "description": "Added in contract 1 by #2680. The record kinds the member declares, in file order. A kind that can't be loaded does not make the member unreadable.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/recordKind" }
+        },
+        "generated": {
+          "description": "Added in contract 1 by #3050. The files the member generates, from its declared generated entries and from the record `chant build --components --generate` and `chant run --generate` write, sorted by path. A hand-written entry is not listed.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/generatedFile" }
+        },
+        "agents": {
+          "description": "Added in contract 1 by #3615. The names of the agent sessions the declaration binds to the member (agents[].member or agents[].members), in declaration order, read where workspace.agentsFrom says. Empty when none is. A session bound to several members is listed on each.",
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "reason": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["code", "message"],
+              "properties": {
+                "code": { "enum": ["dir-missing", "unknown-kind", "kind-probe-failed"] },
+                "message": { "type": "string" }
+              }
+            }
+          ]
+        }
+      },
+      "if": { "type": "object", "properties": { "readable": { "const": true } }, "required": ["readable"] },
+      "then": { "type": "object", "properties": { "reason": { "type": "null" } } },
+      "else": { "type": "object", "properties": { "reason": { "type": "object" } } }
+    },
+    "recordKind": {
+      "description": "A record kind the declaration names (#2680). chant workspace records and graph --intent read every one of them when --kind is not given.",
+      "type": "object",
+      "required": ["name", "path", "kind", "reason"],
+      "properties": {
+        "name": { "type": ["string", "null"], "description": "The name the declaration gives the kind, else the kind file's own recordKind.name, else null when the file can't be loaded." },
+        "path": { "type": "string", "description": "The kind file, relative to the workspace root, with / separators." },
+        "kind": { "type": ["string", "null"], "description": "The kind file's recordKind.name, or null when it can't be loaded." },
+        "reason": {
+          "description": "Why the kind file can't be loaded, or null. The file is looked for in the tree read, the revision under --at, and loaded from the working tree.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["code", "message"],
+              "properties": {
+                "code": { "enum": ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch"] },
+                "message": { "type": "string" }
+              }
+            }
+          ]
+        },
+        "acceptance": {
+          "description": "Added in contract 1 by #2772. For a work kind whose work block names acceptance criteria: each current work item that lists some, in path order, with how many of its criteria passing evidence meets, read in the tree read. Null for any other kind, and when the kind or its records can't be read.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["item", "state", "met", "total"],
+                "properties": {
+                  "item": { "type": "string", "description": "The work item's id." },
+                  "state": { "type": ["string", "null"], "description": "The item's state." },
+                  "met": { "type": "integer", "minimum": 0, "description": "Criteria met by evidence naming them, with result pass and the criterion's verification; a manual verdict counts only from someone other than the implementer." },
+                  "total": { "type": "integer", "minimum": 0, "description": "Criteria the item lists." }
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "generatedFile": {
+      "type": "object",
+      "required": ["path", "command", "env", "jobs"],
+      "properties": {
+        "path": { "type": "string", "description": "From the repository root, with / separators, which is how a forge reads a CI file. For a workspace below the git root, that includes the workspace root." },
+        "command": { "type": "string", "description": "The command that regenerates the file, run in the member's directory. Empty when a record names none." },
+        "env": { "type": ["string", "null"], "description": "The environment a component pipeline deploys, or null." },
+        "jobs": {
+          "description": "The check names a forge CI file declares: for GitHub, Forgejo and Gitea the job's name, else its id; for GitLab the job's key. Null for any other file, and for a CI file that is missing from the tree read or can't be parsed.",
+          "type": ["array", "null"],
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "diagram": {
+      "description": "A diagram artifact the declaration names (#2764), pinned to the renderer its render was made with. chant runs no renderer; everything here comes straight from the declaration.",
+      "type": "object",
+      "required": ["name", "title", "source", "render", "renderer", "member"],
+      "properties": {
+        "name": { "type": "string" },
+        "title": { "type": "string" },
+        "source": { "type": ["string", "null"], "description": "From the workspace root, with / separators. Null for an SVG with no source." },
+        "render": { "type": ["string", "null"], "description": "From the workspace root, with / separators. Null for a mermaid or excalidraw diagram with no committed render: a reader draws it from its source." },
+        "renderer": {
+          "type": "object",
+          "required": ["tool", "version", "args"],
+          "properties": {
+            "tool": { "enum": ["d2", "mermaid", "graphviz", "excalidraw"] },
+            "version": { "type": "string", "description": "The exact release the render was made with, such as 0.9.0. For mermaid or excalidraw, the release of the library a reader draws the source with." },
+            "args": { "type": "array", "items": { "type": "string" }, "description": "Passed before the input and output paths, in order." }
+          }
+        },
+        "member": { "type": ["string", "null"], "description": "The member that declares it, or null for the workspace's own." }
+      }
+    },
+    "group": {
+      "type": "object",
+      "required": ["name", "kind", "glob", "matches", "skipped", "reason"],
+      "properties": {
+        "name": { "type": "string" },
+        "kind": { "const": "examples" },
+        "glob": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+        "matches": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Directories the globs match that hold a chant project, relative to the workspace root, sorted. They are built and linted, and nothing else."
+        },
+        "skipped": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Directories the globs match that hold no chant project. They are left alone."
+        },
+        "reason": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["code", "message"],
+              "properties": {
+                "code": { "enum": ["no-matches"] },
+                "message": { "type": "string" }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "failure": {
+      "description": "The declaration could not be read, and nothing is listed. Exit code 1.",
+      "type": "object",
+      "required": ["$schema", "contract", "chant", "error"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/ls/v1/ls.schema.json" },
+        "contract": { "const": 1 },
+        "chant": { "type": "string" },
+        "error": {
+          "type": "object",
+          "required": ["code", "message", "location"],
+          "properties": {
+            "code": {
+              "enum": [
+                "declaration-missing",
+                "declaration-ambiguous",
+                "declaration-unparseable",
+                "declaration-invalid",
+                "placement-invalid",
+                "reader-too-old",
+                "root-chant-required",
+                "not-a-git-repository",
+                "revision-unknown"
+              ]
+            },
+            "message": { "type": "string" },
+            "location": {
+              "description": "Where in the declaration the problem is, or null when it is not in the file.",
+              "oneOf": [
+                { "type": "null" },
+                {
+                  "type": "object",
+                  "required": ["file", "line", "column"],
+                  "properties": {
+                    "file": { "type": "string" },
+                    "line": { "type": "integer", "minimum": 1 },
+                    "column": { "type": "integer", "minimum": 1 }
+                  }
+                }
+              ]
+            }
+          }
+        },
+        "members": false,
+        "workspace": false
+      }
+    }
+  }
+}