@intentius/chant 0.81.0 → 0.83.0

package/src/workspace/checks.ts

@@ -26,6 +26,7 @@
  * | WSP081 to WSP083 | recorded pipelines |
  * | WSP091 to WSP097 | member links (#2539) |
  * | WSP101 to WSP106 | generated files |
+ * | WSP111 to WSP114 | records read with `--kind` (#2549) |
  */
 
 import { realpathSync } from "node:fs";
@@ -42,6 +43,7 @@ import type { LinkTableRow } from "./links";
 import { gatherGeneratedFacts, GENERATED_CHECKS, type GeneratedFileFacts } from "./checks/generated";
 import { gatherLedgerFacts, LEDGER_CHECKS, type MemberLedgerFacts } from "./checks/ledgers";
 import { gatherPipelineFacts, PIPELINE_CHECKS, type MemberPipelineFacts } from "./checks/pipelines";
+import { RECORD_CHECKS, type RecordFacts } from "./checks/records";
 
 /**
  * What the checks beyond the declaration read, gathered from the checkout
@@ -55,6 +57,8 @@ export interface WorkspaceFacts {
   pipelines?: readonly MemberPipelineFacts[];
   /** Each declared or implicit generated file, with what its generator produced. */
   generated?: readonly GeneratedFileFacts[];
+  /** The records of the kind named with `--kind`, with their pins checked (#2549). */
+  records?: RecordFacts;
 }
 
 /** What every declaration check reads. */
@@ -77,6 +81,8 @@ export interface WorkspaceCheckContext {
 export interface WorkspaceDiagnostic extends PostSynthDiagnostic {
   /** A JSON Pointer into the declaration. */
   pointer: string;
+  /** An absolute path, for a finding about a file other than the declaration, such as a record (#2549). It is reported at its first line. */
+  file?: string;
 }
 
 export interface WorkspaceCheck {
@@ -295,6 +301,8 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
   ...LINK_CHECKS,
   // Generated files (#2541).
   ...GENERATED_CHECKS,
+  // Records read with --kind (#2549).
+  ...RECORD_CHECKS,
 ];
 
 const BY_ID = new Map(WORKSPACE_CHECKS.map((c) => [c.id, c]));
@@ -370,6 +378,8 @@ export interface DeclarationCheckOptions {
    * gathered: they describe the working tree, not the revision.
    */
   tree?: WorkspaceTree;
+  /** The records read with `--kind`, in the same tree (#2549). Given with or without `tree`. */
+  records?: RecordFacts;
 }
 
 /**
@@ -433,7 +443,8 @@ export async function runDeclarationChecks(
     return { file: display(location.file), diagnostics: [diagnostic], suppressed: [], links: [], ok: false };
   }
   const { registry, problems } = loadKindRegistry(declaration.pins, root);
-  const facts = options.gather === false || options.tree ? {} : await gatherWorkspaceFacts(root, declaration, options);
+  const gathered = options.gather === false || options.tree ? {} : await gatherWorkspaceFacts(root, declaration, options);
+  const facts: WorkspaceFacts = options.records ? { ...gathered, records: options.records } : gathered;
   const ctx: WorkspaceCheckContext = { declaration, tree, groups, kinds: registry, kindProblems: problems, facts };
   const findings = runWorkspaceChecks(ctx);
   const { active, suppressed } = applyCheckSettings(declaration, findings);
@@ -442,8 +453,7 @@ export async function runDeclarationChecks(
   const locate = (pointer: string): TextLocation => (parsed.ok ? parsed.locate(pointer) : { line: 1, column: 1 });
   const file = display(declaration.file);
   const toFinding = (d: WorkspaceDiagnostic): WorkspaceFinding => ({
-    file,
-    ...locate(d.pointer),
+    ...(d.file !== undefined ? { file: display(relative(root, d.file).split(sep).join("/")), line: 1, column: 1 } : { file, ...locate(d.pointer) }),
     ruleId: d.checkId,
     severity: d.severity,
     message: d.message,

package/src/workspace/compose-graph.test.ts

@@ -7,6 +7,7 @@ import { describe, expect, test } from "vitest";
 import { GRAPH_IR_VERSION, type GraphIR } from "../graph-ir";
 import { parseDeclaration } from "./declaration";
 import { composeWorkspaceGraph, readMemberIr, WORKSPACE_GRAPH_VERSION, type ComposedMember } from "./compose-graph";
+import type { LinkTableRow } from "./links";
 
 const member = (name: string, dir: string): ComposedMember => ({
   name,
@@ -136,7 +137,7 @@ describe("the links section (#2539)", () => {
     ];
     const doc = composeWorkspaceGraph({ name: "acme", root: "/w" }, inputs, { declaration });
     expect(
-      doc.links.map((r) => (r.status === "ambiguous" ? "" : `${r.origin} ${r.label} ${r.from ?? r.consumer} -> ${r.to}`)),
+      (doc.links as LinkTableRow[]).map((r) => (r.status === "ambiguous" ? "" : `${r.origin} ${r.label} ${r.from ?? r.consumer} -> ${r.to}`)),
     ).toEqual([
       "declared exact app -> web/Bucket",
       "inferred:joinKey folded jobs/BUCKET_ARN -> web/Bucket",

package/src/workspace/compose-graph.ts

@@ -16,8 +16,9 @@
  * - `links` holds the member links (#2524 D6, #2539): the declared links and
  *   the joins inferred from members' `imports` and `exports` with the core
  *   `joinKey()`, labelled `exact` or `folded` (`./links.ts`). A declared link
- *   suppresses the inferred edge it covers. `records` is the section record
- *   kinds fill (#2524 D4), empty so far.
+ *   suppresses the inferred edge it covers. `records` holds the records
+ *   read through a record kind (`--kind`, #2549), and their `asset` and
+ *   `constrains` links follow the member links in `links`.
  *
  * A member's IR with no `version` field comes from a chant older than #2529.
  * It is version 1, and it is upgraded in place by stamping that version. An IR
@@ -31,6 +32,7 @@
 import type { Declaration } from "./declaration";
 import type { KindRegistry } from "./kinds";
 import { graphLinks, type LinkTableRow } from "./links";
+import type { RecordLinkRow } from "./record-assets";
 import type { ReasonCode } from "./reason-codes";
 import { GRAPH_IR_VERSION, type GraphIR, type IRExport, type IRGroups, type IRImport, type IREdge, type IRNode } from "../graph-ir";
 
@@ -92,10 +94,25 @@ export interface WorkspaceGraph {
   exports: (IRExport & { member: string })[];
   imports: (IRImport & { member: string })[];
   derivedAttrs?: Record<string, string[]>;
-  /** Member links (#2524 D6, #2539), declared and inferred. Empty when no declaration is given. */
-  links: LinkTableRow[];
-  /** Record sections (#2524 D4). Empty until record kinds join the graph. */
-  records: unknown[];
+  /**
+   * Member links (#2524 D6, #2539), declared and inferred, then the links of
+   * the records read with `--kind` (#2549). Empty when no declaration is given.
+   */
+  links: (LinkTableRow | RecordLinkRow)[];
+  /** The records read with `--kind` (#2524 D4, #2549). Empty without it. */
+  records: GraphRecord[];
+}
+
+/** A record in the composed graph: enough to name it from a link row. */
+export interface GraphRecord {
+  /** The record kind's name, such as `decision`. */
+  kind: string;
+  id: string | null;
+  /** From the repository root. */
+  path: string;
+  state: string | null;
+  valid: boolean;
+  supersededBy: string | null;
 }
 
 /** Read one member's `chant graph --format ir` output, upgrading an unversioned (v1) IR in place. */

package/src/workspace/graph-cli.ts

@@ -1,8 +1,9 @@
 /**
- * `chant workspace graph [dir] [--at <rev>] [--member <name>] [-o <file>]
- * [--env <env>] [--dry-run]` (#2537, #2536): every `chant` member's IR, read
- * through the member's own toolchain and composed into one document
- * (`compose-graph.ts`).
+ * `chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>]
+ * [-o <file>] [--env <env>] [--dry-run]` (#2537, #2536): every `chant`
+ * member's IR, read through the member's own toolchain and composed into one
+ * document (`compose-graph.ts`). With `--kind`, the records of that kind and
+ * their asset and constrains links join it (#2549, `record-assets.ts`).
  *
  * The document is part of the read contract, described by `graph.schema.json`
  * beside this file. It is printed for a failure too, with the error's reason
@@ -28,6 +29,8 @@ import { composeWorkspaceGraph, readMemberIr, type ComposeInput, type WorkspaceG
 import { readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, type ErrorLocation, type WorkspaceErrorCode } from "./declaration";
 import { describePlan, emitDocument, executePlan, memberStatus, planJson, planMembers, type MemberPlan, type Toolchain, type UnitResult } from "./member-commands";
 import { loadKindRegistry } from "./kinds";
+import { recordLinkRows } from "./record-assets";
+import { RecordReadError } from "./records";
 import { workingTree } from "./tree";
 import { handToRootChant, locateWorkspace, type LocatedWorkspace } from "./which-chant";
 
@@ -40,7 +43,7 @@ export const GRAPH_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/worksp
 /** Why the graph couldn't be read at all: the declaration's codes, `--at`'s included. */
 export const GRAPH_ERROR_CODES = WORKSPACE_ERROR_CODES;
 
-const USAGE = "chant workspace graph [dir] [--at <rev>] [--member <name>] [-o <file>] [--env <env>] [--dry-run]";
+const USAGE = "chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--dry-run]";
 
 interface Head {
   $schema: string;
@@ -64,6 +67,12 @@ export interface GraphQuery {
   reader?: Toolchain;
   /** Called with each member's stderr, so the command can pass it on. */
   onStderr?: (text: string) => void;
+  /**
+   * A record kind file, absolute or relative to `cwd` (#2549). Its records
+   * fill `records`, and their asset pins and `constrains` entries become
+   * rows of `links`.
+   */
+  kind?: string;
 }
 
 export interface GraphResult {
@@ -171,7 +180,23 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
     // Links (#2539) resolve against the declaration that was read, the revision's for --at, and the kinds installed now.
     const kinds = loadKindRegistry(declaration.pins, located.rootOnDisk).registry;
     const graph = composeWorkspaceGraph({ name: declaration.name, root: located.root }, inputs, { declaration, kinds });
-    return { doc: { ...head, at: located.at, ...graph }, failed };
+    let recordsFailed = false;
+    if (query.kind !== undefined) {
+      // Artifact relationships come from records (#2549): a record's pins and
+      // what it constrains, read at the same revision as the declaration.
+      const { readRecordsFor } = await import("./records-cli");
+      try {
+        const read = await readRecordsFor({ kind: query.kind, cwd: query.cwd, at: query.at });
+        const name = read.loaded.kind.name;
+        graph.records = read.result.records.map((r) => ({ kind: name, id: r.id, path: r.path, state: r.state, valid: r.valid, supersededBy: r.supersededBy }));
+        graph.links.push(...recordLinkRows(name, read.result.records, read.loaded.kind.constrains?.field, located.tree, declaration.members));
+      } catch (err) {
+        if (!(err instanceof RecordReadError)) throw err;
+        recordsFailed = true;
+        query.onStderr?.(`${formatError({ message: `--kind ${query.kind}: ${err.code}: ${err.message}`, hint: USAGE })}\n`);
+      }
+    }
+    return { doc: { ...head, at: located.at, ...graph }, failed: failed || recordsFailed };
   } catch (err) {
     if (!(err instanceof WorkspaceReadError)) throw err;
     return { doc: { ...head, error: { code: err.code, message: err.message, location: err.location ?? null } }, failed: true };
@@ -209,6 +234,7 @@ export async function runWorkspaceGraph(ctx: CommandContext): Promise<number> {
     at: args.at,
     members: args.members,
     args,
+    ...(args.kind !== undefined ? { kind: resolve(args.kind) } : {}),
     onStderr: (text) => process.stderr.write(text),
   });
   emitDocument(doc, args.output);

package/src/workspace/graph-contract.test.ts

@@ -18,6 +18,7 @@ import { cleanScratch, commitAll, contract, declaration, declaration as declarat
 import type { GraphIR } from "../graph-ir";
 import { composeWorkspaceGraph, MEMBER_RUN_REASON_CODES } from "./compose-graph";
 import { parseDeclaration, WORKSPACE_ERROR_CODES } from "./declaration";
+import type { LinkTableRow } from "./links";
 import { GRAPH_CONTRACT_VERSION, GRAPH_ERROR_CODES, GRAPH_OUTPUT_SCHEMA_ID, workspaceGraph, type GraphDocument } from "./graph-cli";
 import schema from "./graph.schema.json";
 
@@ -101,7 +102,7 @@ describe("the links section (#2539)", () => {
     );
     const doc = { $schema: GRAPH_OUTPUT_SCHEMA_ID, contract: 1, chant: "0.81.0", at: null, ...graph };
     expectValid(doc);
-    expect(doc.links.map((r) => `${r.consumer} ${r.origin} ${r.status}`)).toEqual(["app declared resolved", "app declared missing", "jobs inferred:joinKey ambiguous"]);
+    expect((doc.links as LinkTableRow[]).map((r) => `${r.consumer} ${r.origin} ${r.status}`)).toEqual(["app declared resolved", "app declared missing", "jobs inferred:joinKey ambiguous"]);
   });
 });
 

package/src/workspace/graph.schema.json

@@ -218,14 +218,17 @@
         },
         "links": {
           "type": "array",
-          "description": "Member links (#2524 D6, #2539): the ones declared on a consumer and the ones inferred from join keys, resolved against the composed graph. A reader draws a row from its `from` node to its `to` node when both are set.",
+          "description": "Member links (#2524 D6, #2539): the ones declared on a consumer and the ones inferred from join keys, resolved against the composed graph. A reader draws a row from its `from` node to its `to` node when both are set. With --kind, the links of the records read follow (#2549): an `asset` row for each file a record pins by hash, and a `constrains` row for each member or path it governs. These rows have `record` and `target` instead of `consumer` and `producer`.",
           "items": {
             "$ref": "#/$defs/link"
           }
         },
         "records": {
           "type": "array",
-          "description": "Record sections (#2524 D4). Empty until record kinds join the graph."
+          "description": "The records read with --kind (#2524 D4, #2549), sorted by path; empty without it. A record link in `links` names its record by id.",
+          "items": {
+            "$ref": "#/$defs/record"
+          }
         }
       }
     },
@@ -655,8 +658,134 @@
               }
             }
           }
+        },
+        {
+          "type": "object",
+          "description": "A record link (#2549): from a current record to a file it pins (kind asset) or to a member or path it constrains (kind constrains). Superseded records have none. A reader finds the artifacts behind a file by taking the decisions whose constrains cover it and then their asset rows.",
+          "required": [
+            "kind",
+            "origin",
+            "resolves",
+            "recordKind",
+            "record",
+            "recordPath",
+            "target",
+            "member",
+            "status",
+            "reason"
+          ],
+          "properties": {
+            "kind": {
+              "enum": [
+                "asset",
+                "constrains"
+              ]
+            },
+            "origin": {
+              "const": "declared"
+            },
+            "resolves": {
+              "const": "source"
+            },
+            "recordKind": {
+              "type": "string",
+              "description": "The record's kind, such as decision."
+            },
+            "record": {
+              "type": "string",
+              "description": "The record's id."
+            },
+            "recordPath": {
+              "type": "string",
+              "description": "The record file, from the repository root."
+            },
+            "target": {
+              "type": "string",
+              "description": "For asset, the pinned path from the workspace root. For constrains, the entry as written: member:<name> or path:<path>."
+            },
+            "member": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "The member the target names or sits in; null when no member does."
+            },
+            "status": {
+              "enum": [
+                "pinned",
+                "drifted",
+                "missing",
+                "stale",
+                "resolved"
+              ],
+              "description": "For asset: pinned, drifted, missing or stale, as records reports the pin. For constrains: resolved, or missing when the member is not declared or the path does not exist."
+            },
+            "reason": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "Why the row is not pinned or resolved, or null."
+            },
+            "sha256": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "For asset: the pinned hash."
+            },
+            "actual": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "For asset: the hash of the file in the tree read, or null when it is missing."
+            }
+          }
         }
       ]
+    },
+    "record": {
+      "type": "object",
+      "required": [
+        "kind",
+        "id",
+        "path",
+        "state",
+        "valid",
+        "supersededBy"
+      ],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "description": "The record kind's name, such as decision."
+        },
+        "id": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "path": {
+          "type": "string",
+          "description": "The record file, from the repository root, with / separators."
+        },
+        "state": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "valid": {
+          "type": "boolean",
+          "description": "As chant workspace records reports it."
+        },
+        "supersededBy": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
     }
   }
 }

package/src/workspace/lineage-check.ts

@@ -1,5 +1,5 @@
 /**
- * `chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated]`:
+ * `chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>]`:
  * the lineage checks (#2550, D9), and the declaration checks (#2535, D16)
  * when a declaration sits between the current directory and the git root.
  *
@@ -10,7 +10,9 @@
  * check. The declaration checks report `WSP` findings through lint's
  * reporters (`./checks.ts`), and cover member ledgers (#2538), recorded
  * pipelines (#2542) and generated files (#2541) as well as the declaration
- * itself (#2641). `--generated` runs each declared generator too.
+ * itself (#2641). `--generated` runs each declared generator too. `--kind`
+ * reads a record kind's records and reports the files they pin by hash that
+ * have changed since (#2549).
  *
  * `chant workspace upgrade` runs the same checks in its staging worktree
  * before it reaches its gate.
@@ -23,6 +25,7 @@ import type { CommandContext } from "../cli/registry";
 import type { LintDiagnostic, LintRule } from "../lint/rule";
 import { findWorkspaceRoot } from "../project-root";
 import type { DeclarationCheckReport } from "./checks";
+import type { RecordFacts } from "./checks/records";
 import { LOCK_FILE, LockError, parseLock, readLock } from "./lineage-lock";
 import type { ReasonCode } from "./reason-codes";
 import type { WorkspaceTree } from "./tree";
@@ -81,7 +84,7 @@ export function findingKey(f: CheckFinding): string {
   return `${f.code}\0${f.scope ?? ""}\0${f.path ?? ""}`;
 }
 
-const USAGE = "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated]";
+const USAGE = "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>]";
 const FORMATS = ["stylish", "json", "sarif"] as const;
 
 /** A lock finding as a lint diagnostic, for `--format json` and `--format sarif`. */
@@ -142,7 +145,7 @@ export type CheckDocument =
  * to `cwd`. `runGenerators` is `--generated`; with `at` it does nothing,
  * since the member facts describe the working tree, not the revision.
  */
-export async function runChecks(cwd: string, at?: string, options: { runGenerators?: boolean } = {}): Promise<CheckDocument> {
+export async function runChecks(cwd: string, at?: string, options: { runGenerators?: boolean; kind?: string } = {}): Promise<CheckDocument> {
   // Loaded here, not at the top: `workspace upgrade` imports this module for checkLineage alone.
   const [{ findDeclarationDir, readDeclaration, readerVersion }, { gitTop, gitTree, resolveCommit, workingTree }] = await Promise.all([
     import("./declaration"),
@@ -184,9 +187,11 @@ export async function runChecks(cwd: string, at?: string, options: { runGenerato
   if (found) {
     const { runDeclarationChecks } = await import("./checks");
     const { dir, tree } = found;
+    const records = options.kind !== undefined ? await readRecordFacts(options.kind, cwd, commit) : undefined;
     declaration = await runDeclarationChecks(dir, (file) => relative(cwd, join(dir, file)).split(sep).join("/"), {
       runGenerators: options.runGenerators === true,
       ...(commit !== null ? { tree } : {}),
+      ...(records ? { records } : {}),
     });
     let name: string | null = null;
     try {
@@ -200,6 +205,18 @@ export async function runChecks(cwd: string, at?: string, options: { runGenerato
   return { ...head, at: commit, workspace, ...report, ok, ...(declaration ? { declaration } : {}) };
 }
 
+/** The records of the kind file `kind` for the record checks (#2549), at `commit` or in the working tree. */
+async function readRecordFacts(kind: string, cwd: string, commit: string | null): Promise<RecordFacts> {
+  const [{ readRecordsFor }, { RecordReadError }] = await Promise.all([import("./records-cli"), import("./records")]);
+  try {
+    const read = await readRecordsFor({ kind, cwd, ...(commit !== null ? { at: commit } : {}) });
+    return { kind, records: read.result.records.map((r) => ({ ...r, file: join(read.root, ...r.path.split("/")) })) };
+  } catch (err) {
+    if (!(err instanceof RecordReadError)) throw err;
+    return { kind, error: { code: err.code, message: err.message } };
+  }
+}
+
 export async function runWorkspaceCheck(ctx: CommandContext): Promise<number> {
   const root = process.cwd();
   if (ctx.args.extraPositional) {
@@ -218,7 +235,7 @@ export async function runWorkspaceCheck(ctx: CommandContext): Promise<number> {
     const handed = await handToRootChant(root, ctx.args.at);
     if (handed !== undefined) return handed;
   }
-  const doc = await runChecks(root, ctx.args.at, { runGenerators: ctx.args.generated === true });
+  const doc = await runChecks(root, ctx.args.at, { runGenerators: ctx.args.generated === true, ...(ctx.args.kind !== undefined ? { kind: ctx.args.kind } : {}) });
   if ("error" in doc) {
     if (ctx.args.json || format === "json") console.log(JSON.stringify(doc, null, 2));
     else console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));

package/src/workspace/lineage-cli.ts

@@ -11,7 +11,7 @@
 
 import { formatError, formatSuccess } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
-import { LOCK_FILE, LockError, readLock, resolveManualStep, scopeStatus, writeLock, type ManualStep } from "./lineage-lock";
+import { LOCK_FILE, LockError, readLock, resolveManualStep, scopeStatus, writeLock, type LineageSource, type ManualStep } from "./lineage-lock";
 
 const USAGE = "chant workspace lineage [--json] | chant workspace lineage resolve <path>";
 
@@ -20,6 +20,8 @@ export interface LineageScopeView {
   kind: "template" | "vendor";
   name?: string;
   template: string;
+  /** Where the files came from, as the lock records it: its `type` and the repository, directory, lexicon or URL. */
+  source: LineageSource;
   ref?: string;
   address: Record<string, unknown> | null;
   files: number;
@@ -28,6 +30,22 @@ export interface LineageScopeView {
   manualSteps: ManualStep[];
 }
 
+/** One line naming a scope's source kind and where it points (#2647). */
+export function describeSource(source: LineageSource): string {
+  switch (source.type) {
+    case "git":
+      return `git ${source.repo}${source.path ? `#${source.path}` : ""}`;
+    case "dir":
+      return `dir ${source.path}${source.member ? `#${source.member}` : ""}`;
+    case "lexicon":
+      return `lexicon ${source.lexicon}/${source.template}`;
+    case "local":
+      return `local ${source.path}`;
+    case "archive":
+      return `archive ${source.url}${source.subpath ? `#${source.subpath}` : ""}`;
+  }
+}
+
 /** The lock as `--json` prints it: one view per scope, with its state in the tree. */
 export function lineageView(root: string): { lock: string; scopes: LineageScopeView[] } | null {
   const lock = readLock(root);
@@ -39,6 +57,7 @@ export function lineageView(root: string): { lock: string; scopes: LineageScopeV
       kind: lineage.kind,
       ...(lineage.name !== undefined ? { name: lineage.name } : {}),
       template: lineage.template,
+      source: lineage.source,
       ...(lineage.ref !== undefined ? { ref: lineage.ref } : {}),
       address: lineage.address,
       files: Object.keys(lineage.files).length,
@@ -73,6 +92,7 @@ export async function runWorkspaceLineage(ctx: CommandContext): Promise<number>
       const pin = s.ref ? `@${s.ref}` : "";
       const at = typeof s.address?.commit === "string" ? ` (${s.address.commit.slice(0, 12)})` : "";
       lines.push(`${s.scope}  ${s.kind}${s.name ? ` ${s.name}` : ""}  ${s.template}${pin}${at}`);
+      lines.push(`  source: ${describeSource(s.source)}`);
       lines.push(`  ${s.files} file(s), ${s.edited.length} edited, ${s.missing.length} deleted`);
       for (const m of s.manualSteps) lines.push(`  manual step: ${s.scope === "." ? "" : `${s.scope}/`}${m.path} (${m.reason})`);
     }