@intentius/chant 0.80.0 → 0.82.0

package/dist/workspace/lineage-upgrade.d.ts

@@ -0,0 +1,152 @@
+/**
+ * `chant workspace upgrade <scope>`: bring one lineage scope to a newer
+ * version of its template (#2550, D9, ws-005, ws-032).
+ *
+ * The upgrade is a core command, never an Op the template ships, so the
+ * template cannot change the rules that judge its own upgrade. It works in the
+ * six steps of D9:
+ *
+ * 1. Fetch the target version of the template. For a git source that is one
+ *    `git fetch` of the target ref, plus the commit the scope was made from.
+ *    This is the command's only network step, catalogued in
+ *    `test/egress-catalogue.ts`. A local repository reaches nothing, and
+ *    neither does a directory source (#2647), which reads `--to <dir>`.
+ * 2. Rebuild the merge base offline: each recorded file's content at the base
+ *    commit, kept only when it has the hash the lock recorded. A file the
+ *    project never edited is its own merge base. Vendor sources keep no
+ *    history, so only unedited vendored files have a base.
+ * 3. Migrate in a separate git worktree, checked out at HEAD under
+ *    `.chant/upgrade/`. The chain is planned from the template's
+ *    `.chant/migrations/`, and a gap refuses the upgrade.
+ * 4. Merge per file (ws-005): an edited file takes the new version only when
+ *    every hunk merges cleanly. Otherwise it stays as it was, with one manual
+ *    step. The worktree never holds conflict markers.
+ * 5. Check the worktree: `chant build` and `chant lint` when the project is a
+ *    chant project, and the lineage checks of `chant workspace check`.
+ * 6. Bind the gate to the digest of the resulting patch: the pending fact and
+ *    the approval name it, so an approval covers exactly this patch.
+ *
+ * The project's own tree changes only once the gate is approved, when the
+ * patch is applied to it. A patch that changes governance files (Op files,
+ * `chant.config`, CI workflows, CODEOWNERS) needs human approvals, as many as
+ * the strictest gate in the Op files it changes asks for at HEAD. The
+ * upgraded Op files never decide their own gate.
+ */
+import type { ResolvedGateApproval } from "../op/gate-approval.js";
+import { LockError, type Lineage, type ManualStep } from "./lineage-lock.js";
+import { type UpdateResult } from "./lineage-update.js";
+/** The kind the patch digest is taken under, so it never collides with another kind of plan. */
+export declare const UPGRADE_PLAN_KIND = "workspace-upgrade";
+/** Where staging worktrees live, relative to the project root. */
+export declare const UPGRADE_DIR = ".chant/upgrade";
+export declare class UpgradeError extends LockError {
+    name: string;
+}
+export interface UpgradeCheck {
+    name: "build" | "lint" | "workspace check";
+    status: "passed" | "failed" | "skipped";
+    /** Why a check was skipped, or the tail of a failed command's output. */
+    detail?: string;
+}
+/** Runs `chant build` or `chant lint` in a directory. */
+export type ChantRunner = (command: "build" | "lint", cwd: string) => Promise<{
+    exitCode: number;
+    output: string;
+}>;
+/**
+ * The default runner: this same chant, in a child process. The child sees the
+ * worktree's sources and resolves packages the way the project does, since the
+ * worktree sits inside the project.
+ */
+export declare const spawnChant: ChantRunner;
+export interface UpgradeOptions {
+    /** The directory holding `.chant/workspace.lock.json`. */
+    root: string;
+    /** The scope to upgrade: `"."` or a vendor scope's directory. */
+    scope?: string;
+    /**
+     * The target ref (git) or label (vendor). Defaults to the ref the scope is
+     * pinned at. For a directory source, the directory holding the new version,
+     * as `<dir>[#<member>]`, resolved from the current directory; the member
+     * defaults to the recorded one.
+     */
+    to?: string;
+    /** Run migrations whose body is code. */
+    allowCode?: boolean;
+    /** Replaces the child-process build and lint. For tests. */
+    runChant?: ChantRunner;
+}
+export interface GovernanceChange {
+    /** Changed governance paths, relative to the repository root. */
+    paths: string[];
+    /** The approval the gate asks for, from the rules at HEAD. */
+    approval: ResolvedGateApproval;
+    /** Where the rules came from. */
+    rules: string;
+}
+export interface StagedUpgrade {
+    scope: string;
+    template: string;
+    kind: Lineage["kind"];
+    /** The pin before and after. */
+    from: string | null;
+    to: string | null;
+    commit?: {
+        from?: string;
+        to: string;
+    };
+    migrations: string[];
+    written: string[];
+    merged: string[];
+    removed: string[];
+    kept: string[];
+    skipped: UpdateResult["skipped"];
+    manualSteps: ManualStep[];
+    /** Paths the patch changes, relative to the repository root. */
+    changedPaths: string[];
+    patch: string;
+    /**
+     * The new lock. When git tracks it, its change is in `patch`. A template
+     * whose `.gitignore` covers `.chant/` leaves it untracked; the text is then
+     * applied beside the patch and covered by the digest on its own.
+     */
+    lock: {
+        path: string;
+        tracked: boolean;
+        text: string;
+    };
+    /** Whether the upgrade changes anything: the patch, or an untracked lock. */
+    changed: boolean;
+    /** `computePlanDigest(UPGRADE_PLAN_KIND, { scope, patch })`, plus `lock` when untracked: what the gate binds. */
+    digest: string;
+    governance: GovernanceChange | null;
+    checks: UpgradeCheck[];
+    checksOk: boolean;
+    /** The repository root and the commit the worktree was made from. */
+    repo: string;
+    head: string;
+    /** The staging worktree, and the project root inside it. */
+    worktree: string;
+    worktreeProject: string;
+    /** Remove the worktree. Safe to call twice. */
+    dispose(): void;
+}
+/** Whether a repository path is a governance file: one that decides gates, pipelines or review. */
+export declare function isGovernancePath(path: string): boolean;
+/**
+ * Stage an upgrade: steps 1 to 5 and the digest of step 6. Nothing in the
+ * project's tree changes. The caller decides the gate, then applies the patch
+ * with {@link applyStagedUpgrade} or commits it with {@link commitStagedUpgrade},
+ * and always calls `dispose()`.
+ */
+export declare function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgrade>;
+/** Apply the staged patch to the project's tree. Leaves it uncommitted. */
+export declare function applyStagedUpgrade(staged: StagedUpgrade): void;
+/**
+ * Commit the staged patch in the worktree and point `branch` at it. Returns
+ * the commit. The caller has already refused the default branch.
+ */
+export declare function commitStagedUpgrade(staged: StagedUpgrade, branch: string, message: string): string;
+/** One line per staged change, for the terminal and for a PR body. */
+export declare function describeStaged(staged: StagedUpgrade): string[];
+//# sourceMappingURL=lineage-upgrade.d.ts.map

package/dist/workspace/lineage-upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage-upgrade.d.ts","sourceRoot":"","sources":["../../src/workspace/lineage-upgrade.ts"],"names":[],"mappings":"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"}

package/dist/workspace/lineage-vendor.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `chant vendor` over the lineage lock (#2540, ws-038).
+ *
+ * A vendored target is one lineage scope of kind `vendor`: copied, with no
+ * parameters. `pull` updates it file by file through {@link applyUpstream}, so
+ * local edits survive and a file both sides changed becomes a manual step.
+ * `check` reports edits and fails on open manual steps.
+ *
+ * `vendor.json` is still read. A project whose lock has no vendor scopes and
+ * which never ran `chant vendor migrate` keeps today's `vendor.json` behaviour
+ * byte for byte (#2525 rule 2): this module loads only when a lock exists or
+ * `migrate` runs.
+ */
+import { type Lineage, type LineageLock, type ManualStep } from "./lineage-lock.js";
+/** Vendor scopes in the lock, by scope key. */
+export declare function vendorScopes(lock: LineageLock): Array<[string, Lineage]>;
+export interface LockedPull {
+    name: string;
+    target: string;
+    digest: string;
+    fileCount: number;
+    written: number;
+    kept: number;
+    removed: number;
+    manualSteps: ManualStep[];
+}
+/** Pull the lock's vendor scopes (or just `only`). Writes the lock. */
+export declare function pullLockedScopes(root: string, only?: string): Promise<LockedPull[]>;
+export declare function formatLockedPull(p: LockedPull): string;
+export type LockedCheckStatus = "ok" | "customised" | "manual" | "unpinned" | "missing";
+export interface LockedCheck {
+    name: string;
+    status: LockedCheckStatus;
+    customised: string[];
+    manualSteps: ManualStep[];
+}
+/** Check each vendor scope in the lock against the tree. */
+export declare function checkLockedScopes(root: string): LockedCheck[];
+export declare function formatLockedCheck(c: LockedCheck): string;
+/** Whether a check result fails the check the way drift does for `vendor.json`. */
+export declare function lockedCheckFails(c: LockedCheck): boolean;
+export interface MigrateResult {
+    migrated: Array<{
+        name: string;
+        target: string;
+        files: number;
+        pinned: boolean;
+    }>;
+    lockCreated: boolean;
+}
+/**
+ * Move every `vendor.json` entry into the lock as a vendor scope, then delete
+ * `vendor.json`. An entry's checksum becomes the scope's digest.
+ *
+ * Per-file merge bases come from the target when it still matches the
+ * checksum. When it has been edited, they come from the source instead, which
+ * must still hash to the checksum; otherwise the pinned content is gone and the
+ * entry is refused. Nothing is written unless every entry migrates.
+ */
+export declare function migrateVendorManifest(root: string): Promise<MigrateResult>;
+/** Whether `vendor.json` sits next to the lock. */
+export declare function manifestPresent(root: string): boolean;
+//# sourceMappingURL=lineage-vendor.d.ts.map

package/dist/workspace/lineage-vendor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage-vendor.d.ts","sourceRoot":"","sources":["../../src/workspace/lineage-vendor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH,OAAO,EAA6G,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAS5L,+CAA+C;AAC/C,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAExE;AAUD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED,uEAAuE;AACvE,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAoBzF;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAKtD;AAID,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,YAAY,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAExF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,CAAC;IAC1B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED,4DAA4D;AAC5D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAoB7D;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAgBxD;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAExD;AAID,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAClF,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAiDhF;AAED,mDAAmD;AACnD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/workspace/lineage-version.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Template versions and version ranges, for migration chains (#2550, D9).
+ *
+ * A template's version is read from the ref it was pinned at: `v1.4.0`,
+ * `1.4`, or a prefixed release tag such as `chant-v0.80.0`. Missing minor and
+ * patch numbers read as 0. A ref that is not a version (a branch, a commit)
+ * has none, and a chain of migrations cannot be planned from it.
+ *
+ * Ranges use the familiar npm subset: comparators (`>=1.0.0 <2.0.0`), `^`,
+ * `~`, `x` wildcards, a bare version for an exact match, `*` for any, and
+ * `||` between alternatives. Pre-release tags compare below their release,
+ * and a range matches a pre-release only through an exact comparator.
+ */
+export interface Version {
+    major: number;
+    minor: number;
+    patch: number;
+    /** The pre-release label after `-`, or empty for a release. */
+    pre: string;
+}
+/** The version a ref names, or null when it names none. */
+export declare function parseVersion(ref: string | undefined | null): Version | null;
+export declare function formatVersion(v: Version): string;
+export declare function compareVersions(a: Version, b: Version): number;
+export declare class VersionRangeError extends Error {
+    name: string;
+}
+/** Check a range's syntax, throwing {@link VersionRangeError} when it cannot be read. */
+export declare function validateRange(range: string): void;
+/** Whether `version` falls in `range`. */
+export declare function satisfies(version: Version, range: string): boolean;
+//# sourceMappingURL=lineage-version.d.ts.map

package/dist/workspace/lineage-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage-version.d.ts","sourceRoot":"","sources":["../../src/workspace/lineage-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;CACb;AAID,2DAA2D;AAC3D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,CAK3E;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAEhD;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,MAAM,CAQ9D;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IACjC,IAAI,SAAuB;CACrC;AAkED,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED,0CAA0C;AAC1C,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAMlE"}

package/dist/workspace/links.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Member links (#2524 D6, #2539; ws-008).
+ *
+ * A member link is stated once, on the consumer, as `{member, output}`, and it
+ * is matched exactly against the outputs the producer exposes. Which outputs
+ * a member exposes is up to its kind ({@link KindOutputs}): a `chant` member's
+ * are read from its source, a nested workspace exposes none, and `other` and
+ * kinds from a package expose what the kind and the entry list.
+ *
+ * A join nobody wrote down is inferred: a `chant` consumer's parameter is
+ * matched to other members' outputs with the core {@link joinKey}, and the
+ * join is labelled `exact` or `folded`. A parameter that matches two or more
+ * outputs is an ambiguity row, not an edge. A declared link from the same
+ * consumer to one of the matched outputs settles it: the inferred rows for
+ * that parameter give way to the declared one, which is how an inferred edge
+ * is promoted.
+ *
+ * Every row says how it was found (`declared` or `inferred:joinKey`), where it
+ * resolved (`source`; `check --live` comes later) and its status. A link that
+ * can't be resolved is kept, with the reason.
+ *
+ * {@link resolveLinks} takes the members' handles as plain data, so the same
+ * rules serve `chant workspace check`, which reads the handles from source
+ * (`sourceMemberHandles` in `./member-handles.ts`, which loads the TypeScript
+ * parser), and `chant workspace graph`, which reads
+ * them from each member's graph IR ({@link irMemberHandles}).
+ */
+import { type JoinLabel } from "../join-key.js";
+import type { Declaration, LinkDeclaration, Member } from "./declaration.js";
+import type { KindRegistry, MemberKind } from "./kinds.js";
+/** The link kinds chant knows. Closed: a link of any other kind fails closed. */
+export declare const LINK_KINDS: readonly ["output"];
+export declare const DEFAULT_LINK_KIND = "output";
+/** How a row was found: written down, or inferred by the named rule. */
+export type LinkOrigin = "declared" | "inferred:joinKey";
+/** One output or parameter of a member, as a join sees it. */
+export interface JoinHandle {
+    name: string;
+    /** The node that holds it, when the reader knows one (a graph IR id). */
+    node?: string;
+}
+/** What a member offers links, and what it reads. */
+export interface MemberHandles {
+    member: string;
+    outputs: JoinHandle[];
+    /** Parameters a join may feed. Only `chant` members have them. */
+    inputs: JoinHandle[];
+    /**
+     * Whether `outputs` is every output the member exposes. When it isn't, a
+     * link to a name not in the list is unresolved, not missing.
+     */
+    complete: boolean;
+    /** Why the list is incomplete, or why the member exposes none. */
+    why: string | null;
+    /** True when the member's kind exposes no outputs at all. */
+    exposesNone: boolean;
+}
+interface RowBase {
+    consumer: string;
+    kind: string;
+    origin: LinkOrigin;
+    resolves: "source";
+    /** Why the row is not `resolved`, or null. */
+    reason: string | null;
+}
+/** A declared link, or an inferred join with one producer. */
+export interface LinkRow extends RowBase {
+    status: "resolved" | "missing" | "unresolved" | "invalid";
+    producer: string;
+    output: string;
+    /** `exact` for every declared link; `exact` or `folded` for an inferred one. */
+    label: JoinLabel;
+    /** The consumer's parameter an inferred join feeds; null for a declared link. */
+    input: string | null;
+    /** The consumer's parameter node and the producer's output node, when known. */
+    from?: string;
+    to?: string;
+    /** The declared link's JSON Pointer in the declaration. */
+    pointer?: string;
+}
+/** A parameter that joins outputs of two or more producers (or two outputs of one). */
+export interface AmbiguousRow extends RowBase {
+    status: "ambiguous";
+    input: string;
+    from?: string;
+    candidates: {
+        producer: string;
+        output: string;
+        label: JoinLabel;
+        to?: string;
+    }[];
+}
+export type LinkTableRow = LinkRow | AmbiguousRow;
+/** A link between two members, in the shape the pipeline checks read (#2542). */
+export interface MemberLinkPair {
+    consumer: string;
+    producer: string;
+}
+/**
+ * The member pairs the declaration links, consumer first, once each, in
+ * declaration order. Only links to a declared member other than the consumer
+ * count.
+ */
+export declare function declaredMemberLinks(declaration: Declaration): MemberLinkPair[];
+/** Why a declared link's target is not a member it may name, or undefined. */
+export declare function linkTargetProblem(declaration: Declaration, consumer: Member, link: LinkDeclaration): string | undefined;
+/**
+ * Resolve every declared link and infer the joins nobody wrote down.
+ * `handles` holds one entry per member whose handles were read; a member
+ * missing from it is unresolved. Declared rows come first, in declaration
+ * order; inferred and ambiguous rows follow, sorted by consumer and parameter.
+ */
+export declare function resolveLinks(declaration: Declaration, handles: ReadonlyMap<string, MemberHandles>): LinkTableRow[];
+/**
+ * The handles of a member whose kind lists its outputs, or exposes none.
+ * Undefined for a kind whose outputs are read from the member (`chant`).
+ */
+export declare function kindHandles(m: Member, kind: MemberKind): MemberHandles | undefined;
+/** The part of a composed workspace graph (#2537) the links read. */
+export interface ComposedHandles {
+    /** Members whose IR was composed. */
+    composed: readonly string[];
+    exports: readonly {
+        member: string;
+        name: string;
+        node?: string;
+    }[];
+    imports: readonly {
+        member: string;
+        name: string;
+        node: string;
+    }[];
+}
+/**
+ * Every composed member's handles, from the `exports` and `imports` of the
+ * composed workspace graph, for its `links` section. Node ids are the
+ * composed ones (`<member>/<id>`). A member's IR lists all its outputs, so
+ * its list is complete.
+ */
+export declare function irMemberHandles(graph: ComposedHandles): Map<string, MemberHandles>;
+/**
+ * The `links` section of the composed workspace graph (#2537, #2524 D8):
+ * the declared links and inferred joins, with composed node ids on the ends
+ * that have one. Declared links suppress the inferred edges they cover.
+ * With `kinds`, a member that isn't composed but whose kind lists its outputs
+ * (`other`, kinds from a package) is a link target too.
+ */
+export declare function graphLinks(declaration: Declaration, graph: ComposedHandles, kinds?: KindRegistry): LinkTableRow[];
+export {};
+//# sourceMappingURL=links.d.ts.map

package/dist/workspace/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../src/workspace/links.ts"],"names":[],"mappings":"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"}

package/dist/workspace/ls.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `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.
+ */
+import type { CommandContext } from "../cli/registry.js";
+import { type Declaration, type ErrorLocation, type Member, type WorkspaceErrorCode } from "./declaration.js";
+import { type KindRegistry } from "./kinds.js";
+import type { WorkspaceTree } from "./tree.js";
+/** The version of the `ls` output this chant writes. */
+export declare const LS_CONTRACT_VERSION = 1;
+/** `$id` of the JSON Schema for the `--json` output, shipped beside this file. */
+export declare const LS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/ls/v1/ls.schema.json";
+/**
+ * Why one member can't be read. Closed, like the error codes: a new code is a
+ * contract change.
+ */
+export declare const MEMBER_REASON_CODES: readonly ["dir-missing", "unknown-kind", "kind-probe-failed"];
+export type MemberReasonCode = (typeof MEMBER_REASON_CODES)[number];
+/** Why a group lists nothing. */
+export declare const GROUP_REASON_CODES: readonly ["no-matches"];
+export type GroupReasonCode = (typeof GROUP_REASON_CODES)[number];
+export interface LsMember {
+    name: string;
+    dir: string;
+    kind: string;
+    roles: {
+        name: string;
+        path: string | null;
+    }[];
+    upstream: string | null;
+    because: string | null;
+    readable: boolean;
+    reason: {
+        code: MemberReasonCode;
+        message: string;
+    } | null;
+}
+export interface LsGroup {
+    name: string;
+    kind: "examples";
+    glob: string[];
+    matches: string[];
+    skipped: string[];
+    reason: {
+        code: GroupReasonCode;
+        message: string;
+    } | null;
+}
+export type LsDocument = {
+    $schema: string;
+    contract: number;
+    chant: string;
+    at: string | null;
+    workspace: {
+        name: string;
+        /** The workspace root relative to the git root, `"."` for the git root itself. Absolute outside git. */
+        root: string;
+        file: string;
+        schema: number;
+        minReader: string | null;
+        pins: Declaration["pins"];
+    };
+    members: LsMember[];
+    groups: LsGroup[];
+    summary: {
+        members: number;
+        unreadable: number;
+        groups: number;
+        matches: number;
+    };
+} | {
+    $schema: string;
+    contract: number;
+    chant: string;
+    error: {
+        code: WorkspaceErrorCode;
+        message: string;
+        location: ErrorLocation | null;
+    };
+};
+export interface LsQuery {
+    /** Where the walk up to the declaration starts. */
+    cwd: string;
+    at?: string;
+    kinds?: KindRegistry;
+}
+/** A member's reason code, or null when its kind can read it. */
+export declare function memberReason(member: Member, tree: WorkspaceTree, kinds: KindRegistry): LsMember["reason"];
+/** Find the workspace, read it and build the document `--json` prints. Never throws a {@link WorkspaceReadError}. */
+export declare function listWorkspace(query: LsQuery): LsDocument;
+export declare function runWorkspaceLs(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=ls.d.ts.map

package/dist/workspace/ls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ls.d.ts","sourceRoot":"","sources":["../../src/workspace/ls.ts"],"names":[],"mappings":"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"}