@intentius/chant 0.79.0 → 0.81.0

package/src/workspace/compose-graph.ts

@@ -0,0 +1,228 @@
+/**
+ * The composed workspace IR that `chant workspace graph` prints (#2537, #2524
+ * D8, ws-009, ws-018, ws-022).
+ *
+ * Each member is read through its own `chant graph --format ir`, under its
+ * own toolchain. This module takes those documents and composes them:
+ *
+ * - Every node id becomes `<member>/<id>`. Member names can't hold `/`, and
+ *   `::` keeps its meaning for stacks inside a member (`app/web::Bucket`).
+ *   Edge ends, `$ref` values in attributes, `compositeInstance`,
+ *   `runtimeOwner` and export and import nodes are rewritten the same way.
+ * - `groups.byMember` maps each member to its node ids. `byLexicon` and
+ *   `byComposite` keep their keys (a lexicon or composite type is the same
+ *   thing in every member) and merge the ids. `byStack`, `byContainer` and
+ *   `byWave` name things inside one member, so their keys are prefixed too.
+ * - `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.
+ *
+ * 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
+ * newer than {@link GRAPH_IR_VERSION} can't be read safely, so that member is
+ * listed with a reason code and left out, like any other member that can't be
+ * read (#2524 D15).
+ *
+ * `chant graph` itself is untouched: this is the only place members compose.
+ */
+
+import type { Declaration } from "./declaration";
+import type { KindRegistry } from "./kinds";
+import { graphLinks, type LinkTableRow } from "./links";
+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";
+
+/** The version of the composed document `chant workspace graph` writes. */
+export const WORKSPACE_GRAPH_VERSION = 1;
+
+/**
+ * Why a member is missing from the composed graph, or from any per-member
+ * run. Closed, like the `ls` reason codes: a new code is a contract change.
+ */
+export const MEMBER_RUN_REASON_CODES = [
+  /** The member's kind is one the workspace commands don't run, such as `other`. */
+  "kind-not-run",
+  /** The member's directory does not exist. */
+  "dir-missing",
+  /** No installed kind has the member's kind name. */
+  "unknown-kind",
+  /** The directory is not what its kind reads. */
+  "kind-probe-failed",
+  /** The member's command exited with a failure. */
+  "command-failed",
+  /** The member's command printed something that isn't the document asked for. */
+  "output-unreadable",
+  /** The member's IR has a version this chant can't read. */
+  "ir-version-unsupported",
+] as const satisfies readonly ReasonCode[];
+export type MemberRunReasonCode = (typeof MEMBER_RUN_REASON_CODES)[number];
+
+export interface MemberReason {
+  code: MemberRunReasonCode;
+  message: string;
+}
+
+export interface ComposedMember {
+  name: string;
+  dir: string;
+  kind: string;
+  status: "composed" | "skipped" | "failed";
+  reason: MemberReason | null;
+  /** The chant version that read the member, when its toolchain said. */
+  chant: string | null;
+  /** The IR version the member printed; `null` when it printed none and was upgraded as version 1. */
+  irVersion: number | null;
+  /** Whole-read facts the member's IR carried (`meta`, `pipeline`), kept apart from the composed sections. */
+  meta?: Record<string, unknown>;
+  pipeline?: unknown;
+}
+
+export type ComposedNode = IRNode & { member: string };
+export type ComposedEdge = IREdge & { member: string };
+
+export interface WorkspaceGraph {
+  version: number;
+  workspace: { name: string; root: string };
+  members: ComposedMember[];
+  nodes: ComposedNode[];
+  edges: ComposedEdge[];
+  groups: IRGroups & { byMember: Record<string, string[]> };
+  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[];
+}
+
+/** Read one member's `chant graph --format ir` output, upgrading an unversioned (v1) IR in place. */
+export function readMemberIr(text: string): { ir: GraphIR; irVersion: number | null } | { reason: MemberReason } {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return { reason: { code: "output-unreadable", message: "chant graph --format ir printed something that is not JSON" } };
+  }
+  if (raw === null || typeof raw !== "object" || !Array.isArray((raw as GraphIR).nodes) || !Array.isArray((raw as GraphIR).edges)) {
+    return { reason: { code: "output-unreadable", message: "chant graph --format ir printed JSON with no nodes and edges" } };
+  }
+  const ir = raw as GraphIR;
+  const printed = ir.version;
+  if (printed === undefined) {
+    ir.version = 1;
+  } else if (typeof printed !== "number" || printed > GRAPH_IR_VERSION) {
+    return {
+      reason: {
+        code: "ir-version-unsupported",
+        message: `the member's chant printed IR version ${String(printed)}, and this chant reads up to version ${GRAPH_IR_VERSION}`,
+      },
+    };
+  }
+  ir.groups ??= {};
+  return { ir, irVersion: printed === undefined ? null : printed };
+}
+
+export interface ComposeInput {
+  member: ComposedMember;
+  /** Present for a member whose IR was read. */
+  ir?: GraphIR;
+}
+
+const prefix = (member: string, id: string): string => `${member}/${id}`;
+
+function prefixRefs(value: unknown, member: string): unknown {
+  if (Array.isArray(value)) return value.map((v) => prefixRefs(v, member));
+  if (value === null || typeof value !== "object") return value;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value)) {
+    out[k] = k === "$ref" && typeof v === "string" ? prefix(member, v) : prefixRefs(v, member);
+  }
+  return out;
+}
+
+function mergeInto(target: Record<string, string[]>, key: string, ids: string[]): void {
+  (target[key] ??= []).push(...ids);
+}
+
+function sorted(rec: Record<string, string[]>): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const k of Object.keys(rec).sort()) out[k] = [...rec[k]].sort();
+  return out;
+}
+
+/**
+ * Compose the members' IRs into the workspace document. Members keep the
+ * order they are given in. With `links`, the `links` section is filled from
+ * the declaration; `kinds` lets a member that isn't composed but whose kind
+ * lists its outputs (`other`, kinds from a package) be a link target.
+ */
+export function composeWorkspaceGraph(
+  workspace: { name: string; root: string },
+  inputs: ComposeInput[],
+  links?: { declaration: Declaration; kinds?: KindRegistry },
+): WorkspaceGraph {
+  const nodes: ComposedNode[] = [];
+  const edges: ComposedEdge[] = [];
+  const exports: WorkspaceGraph["exports"] = [];
+  const imports: WorkspaceGraph["imports"] = [];
+  const byMember: Record<string, string[]> = {};
+  const shared: Record<"byLexicon" | "byComposite", Record<string, string[]>> = { byLexicon: {}, byComposite: {} };
+  const scoped: Record<"byStack" | "byContainer" | "byWave", Record<string, string[]>> = { byStack: {}, byContainer: {}, byWave: {} };
+  const derivedAttrs: Record<string, Set<string>> = {};
+
+  for (const { member, ir } of inputs) {
+    if (!ir) continue;
+    const m = member.name;
+    const ids: string[] = [];
+    for (const node of ir.nodes) {
+      const composed: ComposedNode = { ...node, id: prefix(m, node.id), member: m, attrs: prefixRefs(node.attrs ?? {}, m) as Record<string, unknown> };
+      if (node.compositeInstance) composed.compositeInstance = prefix(m, node.compositeInstance);
+      if (node.runtimeOwner) composed.runtimeOwner = prefix(m, node.runtimeOwner);
+      nodes.push(composed);
+      ids.push(composed.id);
+    }
+    byMember[m] = ids.sort();
+    for (const edge of ir.edges) edges.push({ ...edge, from: prefix(m, edge.from), to: prefix(m, edge.to), member: m });
+    for (const key of ["byLexicon", "byComposite"] as const) {
+      for (const [k, v] of Object.entries(ir.groups[key] ?? {})) mergeInto(shared[key], k, v.map((id) => prefix(m, id)));
+    }
+    for (const key of ["byStack", "byContainer", "byWave"] as const) {
+      for (const [k, v] of Object.entries(ir.groups[key] ?? {})) mergeInto(scoped[key], prefix(m, k), v.map((id) => prefix(m, id)));
+    }
+    for (const e of ir.exports ?? []) exports.push({ ...e, ...(e.node ? { node: prefix(m, e.node) } : {}), member: m });
+    for (const i of ir.imports ?? []) imports.push({ ...i, node: prefix(m, i.node), member: m });
+    for (const [kind, attrs] of Object.entries(ir.derivedAttrs ?? {})) for (const a of attrs) (derivedAttrs[kind] ??= new Set()).add(a);
+    if (ir.meta) member.meta = ir.meta;
+    if (ir.pipeline) member.pipeline = ir.pipeline;
+  }
+
+  nodes.sort((a, b) => a.id.localeCompare(b.id));
+  const edgeKey = (e: ComposedEdge) => `${e.from}\u0000${e.to}\u0000${e.viaAttr ?? ""}`;
+  edges.sort((a, b) => edgeKey(a).localeCompare(edgeKey(b)));
+
+  const groups: WorkspaceGraph["groups"] = { byMember };
+  for (const key of ["byLexicon", "byComposite"] as const) if (Object.keys(shared[key]).length) groups[key] = sorted(shared[key]);
+  for (const key of ["byStack", "byContainer", "byWave"] as const) if (Object.keys(scoped[key]).length) groups[key] = sorted(scoped[key]);
+
+  const doc: WorkspaceGraph = {
+    version: WORKSPACE_GRAPH_VERSION,
+    workspace,
+    members: inputs.map((i) => i.member),
+    nodes,
+    edges,
+    groups,
+    exports,
+    imports,
+    links: links
+      ? graphLinks(links.declaration, { composed: inputs.filter((i) => i.ir).map((i) => i.member.name), exports, imports }, links.kinds)
+      : [],
+    records: [],
+  };
+  if (Object.keys(derivedAttrs).length) {
+    doc.derivedAttrs = Object.fromEntries(Object.keys(derivedAttrs).sort().map((k) => [k, [...derivedAttrs[k]].sort()]));
+  }
+  return doc;
+}

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

@@ -0,0 +1,109 @@
+/**
+ * Merging per-member lint and audit output (#2537, #2524 D16): one SARIF run
+ * per member, and a `member` field on every audit finding.
+ */
+
+import { pathToFileURL } from "node:url";
+import { describe, expect, test } from "vitest";
+import { mergeAudit, mergeSarif, type MemberOutput } from "./compose-reports";
+
+const sarif = (uris: string[]) =>
+  JSON.stringify({
+    version: "2.1.0",
+    runs: [
+      {
+        tool: { driver: { name: "chant", rules: [{ id: "COR001" }] } },
+        results: uris.map((uri) => ({
+          ruleId: "COR001",
+          ruleIndex: 0,
+          message: { text: "m" },
+          locations: [{ physicalLocation: { artifactLocation: { uri } } }],
+        })),
+      },
+    ],
+  });
+
+const out = (id: string, dir: string, stdout: string, exitCode = 0, stderr = ""): MemberOutput => ({
+  id,
+  member: id.split(":")[0],
+  dir,
+  exitCode,
+  stdout,
+  stderr,
+});
+
+describe("mergeSarif", () => {
+  const root = "/work/acme";
+  const log = mergeSarif(
+    [
+      out("platform", ".", sarif([pathToFileURL("/work/acme/src/a.ts").href])),
+      out("api", "services/api", sarif([pathToFileURL("/work/acme/services/api/src/b.ts").href, "src/c.ts"])),
+      out("examples:examples/demo", "examples/demo", "Error: boom", 1, "stack trace"),
+    ],
+    root,
+  ) as { runs: Array<Record<string, unknown>> };
+
+  test("writes one run per member, told apart by automationDetails.id", () => {
+    expect(log.runs).toHaveLength(3);
+    expect(log.runs.map((r) => (r.automationDetails as { id: string }).id)).toEqual(["platform/", "api/", "examples:examples/demo/"]);
+    expect(log.runs[1].properties).toEqual({ member: "api", dir: "services/api" });
+  });
+
+  test("makes artifact URIs relative to the workspace root", () => {
+    const uris = (i: number) =>
+      (log.runs[i].results as Array<{ locations: Array<{ physicalLocation: { artifactLocation: { uri: string } } }> }>).map(
+        (r) => r.locations[0].physicalLocation.artifactLocation.uri,
+      );
+    expect(uris(0)).toEqual(["src/a.ts"]);
+    expect(uris(1)).toEqual(["services/api/src/b.ts", "services/api/src/c.ts"]);
+  });
+
+  test("gives a member whose lint printed no SARIF a failed invocation and no results", () => {
+    const failed = log.runs[2] as { results: unknown[]; invocations: Array<{ executionSuccessful: boolean; exitCode: number }> };
+    expect(failed.results).toEqual([]);
+    expect(failed.invocations[0]).toMatchObject({ executionSuccessful: false, exitCode: 1 });
+  });
+
+  test("folds a member's extra runs into its one run", () => {
+    const two = JSON.parse(sarif(["x.ts"]));
+    two.runs.push(JSON.parse(sarif(["y.ts"])).runs[0]);
+    const merged = mergeSarif([out("m", "m", JSON.stringify(two))], root) as { runs: Array<{ results: Array<Record<string, unknown>> }> };
+    expect(merged.runs).toHaveLength(1);
+    expect(merged.runs[0].results).toHaveLength(2);
+    expect(merged.runs[0].results[1].ruleIndex).toBeUndefined();
+  });
+});
+
+describe("mergeAudit", () => {
+  const report = (files: string[]) =>
+    JSON.stringify({
+      schemaVersion: "1.0",
+      status: "ok",
+      summary: { total: files.length },
+      findings: files.map((file) => ({ checkId: "WK8202", severity: "error", message: "m", file })),
+    });
+
+  test("adds a member field to every finding and keeps the rest", () => {
+    const doc = mergeAudit([out("api", "services/api", report(["manifests/pod.yaml"]))], { name: "acme", root: "/w" });
+    expect(doc.schemaVersion).toBe("1.0");
+    expect(doc.findings).toEqual([{ checkId: "WK8202", severity: "error", message: "m", file: "manifests/pod.yaml", member: "api" }]);
+  });
+
+  test("leaves findings in another member's directory to that member", () => {
+    const root = { ...out("platform", ".", report(["ci.yml", "services/api/manifests/pod.yaml"])), exclude: ["services/api"] };
+    const doc = mergeAudit([root], { name: "acme", root: "/w" });
+    expect(doc.findings.map((f) => f.file)).toEqual(["ci.yml"]);
+    expect(doc.members[0].leftToMembers).toBe(1);
+  });
+
+  test("records a member with nothing to audit, and one whose audit failed", () => {
+    const doc = mergeAudit(
+      [out("empty", "e", "No auditable files found under ..\n"), out("broken", "b", "", 1, "Error: boom")],
+      { name: "acme", root: "/w" },
+    );
+    expect(doc.members.map((m) => [m.member, m.status, m.note ?? m.error])).toEqual([
+      ["empty", "ok", "No auditable files found under .."],
+      ["broken", "failed", "Error: boom"],
+    ]);
+  });
+});

package/src/workspace/compose-reports.ts

@@ -0,0 +1,186 @@
+/**
+ * Merging per-member lint and audit output (#2537, #2524 D16, ws-025, ws-026).
+ *
+ * `chant workspace lint --format sarif` prints one SARIF log with one run per
+ * member, each run being what that member's own `chant lint --format sarif`
+ * printed. `chant workspace audit --format json` prints one document whose
+ * findings each carry a `member` field. Both keep what the member's chant
+ * said and only add where it came from.
+ */
+
+import { isAbsolute, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SARIF_SCHEMA = "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json";
+
+/** One member's output, as the merge sees it. */
+export interface MemberOutput {
+  /** The member's name, or `<group>:<dir>` for an example-group match. */
+  id: string;
+  /** The member or group name. */
+  member: string;
+  /** Relative to the workspace root, `"."` for the root member. */
+  dir: string;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  /**
+   * Directories (relative to the member) that belong to other members. Set
+   * for member `.`: its audit walks the whole root, and findings in these
+   * directories are reported by the members they belong to.
+   */
+  exclude?: string[];
+}
+
+type Json = Record<string, unknown>;
+
+/** A root-relative path for a URI a member's SARIF wrote. Other URIs pass through. */
+function rootRelativeUri(uri: string, memberDir: string, root: string): string {
+  let abs: string | undefined;
+  if (uri.startsWith("file://")) {
+    try {
+      abs = fileURLToPath(uri);
+    } catch {
+      return uri;
+    }
+  } else if (isAbsolute(uri)) {
+    abs = uri;
+  }
+  if (abs !== undefined) {
+    const rel = relative(root, abs).split("\\").join("/");
+    return rel.startsWith("..") || isAbsolute(rel) ? uri : rel;
+  }
+  if (/^[a-z][a-z0-9+.-]*:/i.test(uri)) return uri;
+  return memberDir === "." ? uri : `${memberDir}/${uri}`;
+}
+
+function rewriteUris(value: unknown, memberDir: string, root: string): unknown {
+  if (Array.isArray(value)) return value.map((v) => rewriteUris(v, memberDir, root));
+  if (value === null || typeof value !== "object") return value;
+  const out: Json = {};
+  for (const [k, v] of Object.entries(value)) {
+    out[k] = k === "artifactLocation" && v && typeof v === "object" && typeof (v as Json).uri === "string"
+      ? { ...(v as Json), uri: rootRelativeUri((v as Json).uri as string, memberDir, root) }
+      : rewriteUris(v, memberDir, root);
+  }
+  return out;
+}
+
+/** A run for a member whose lint printed no SARIF: no results, and the failure as a notification. */
+function failedRun(unit: MemberOutput, why: string): Json {
+  const tail = unit.stderr.trim().split("\n").slice(-20).join("\n");
+  return {
+    tool: { driver: { name: "chant", informationUri: "https://intentius.io/chant" } },
+    automationDetails: { id: `${unit.id}/` },
+    properties: { member: unit.member, dir: unit.dir },
+    invocations: [
+      {
+        executionSuccessful: false,
+        exitCode: unit.exitCode,
+        toolExecutionNotifications: [{ level: "error", message: { text: tail ? `${why}\n${tail}` : why } }],
+      },
+    ],
+    results: [],
+  };
+}
+
+/**
+ * One SARIF log with one run per member. A member's own log normally holds
+ * one run; if it holds more, their results are folded into the first so the
+ * member still has exactly one. Artifact URIs become relative to the
+ * workspace root, and each run's `automationDetails.id` is `<member>/`, the
+ * SARIF way to tell runs of one tool apart.
+ */
+export function mergeSarif(units: MemberOutput[], root: string): Json {
+  const runs: Json[] = [];
+  for (const unit of units) {
+    let log: Json;
+    try {
+      log = JSON.parse(unit.stdout) as Json;
+    } catch {
+      runs.push(failedRun(unit, `chant lint exited ${unit.exitCode} and printed no SARIF`));
+      continue;
+    }
+    const own = Array.isArray(log.runs) ? (log.runs as Json[]) : [];
+    if (own.length === 0) {
+      runs.push(failedRun(unit, "chant lint printed a SARIF log with no runs"));
+      continue;
+    }
+    const [first, ...rest] = own.map((r) => rewriteUris(r, unit.dir, root) as Json);
+    const results = [...((first.results as unknown[]) ?? [])];
+    for (const r of rest) {
+      for (const res of (r.results as Json[]) ?? []) {
+        // A rule index points into its own run's rules; folded in, it would point at the wrong one.
+        const { ruleIndex: _dropped, ...kept } = res;
+        results.push(kept);
+      }
+    }
+    runs.push({
+      ...first,
+      results,
+      automationDetails: { ...((first.automationDetails as Json) ?? {}), id: `${unit.id}/` },
+      properties: { ...((first.properties as Json) ?? {}), member: unit.member, dir: unit.dir },
+    });
+  }
+  return { $schema: SARIF_SCHEMA, version: "2.1.0", runs };
+}
+
+export interface MemberAuditStatus {
+  member: string;
+  dir: string;
+  exitCode: number;
+  status: "ok" | "no-lexicons" | "failed";
+  summary: Json | null;
+  error: string | null;
+  /** What the member's audit printed instead of a report when it had nothing to audit. */
+  note?: string;
+  /** Findings dropped from member `.` because they sit in another member's directory. */
+  leftToMembers?: number;
+}
+
+export interface WorkspaceAuditDocument {
+  /** The audit report schema version the members wrote, when they all agree. */
+  schemaVersion: string | null;
+  workspace: { name: string; root: string };
+  members: MemberAuditStatus[];
+  findings: Json[];
+}
+
+/**
+ * Merge each member's `chant audit --format json` report. Every finding keeps
+ * its fields, with `file` still relative to its member, and gains `member`.
+ */
+export function mergeAudit(units: MemberOutput[], workspace: { name: string; root: string }): WorkspaceAuditDocument {
+  const members: MemberAuditStatus[] = [];
+  const findings: Json[] = [];
+  const versions = new Set<string>();
+  for (const unit of units) {
+    let report: Json;
+    try {
+      report = JSON.parse(unit.stdout) as Json;
+    } catch {
+      if (unit.exitCode === 0) {
+        // `chant audit` says so in plain text when a directory holds nothing it audits.
+        members.push({ member: unit.id, dir: unit.dir, exitCode: 0, status: "ok", summary: null, error: null, note: unit.stdout.trim() });
+        continue;
+      }
+      const tail = unit.stderr.trim().split("\n").slice(-5).join("\n");
+      members.push({ member: unit.id, dir: unit.dir, exitCode: unit.exitCode, status: "failed", summary: null, error: tail || "chant audit printed no JSON report" });
+      continue;
+    }
+    if (typeof report.schemaVersion === "string") versions.add(report.schemaVersion);
+    const own = (report.findings as Json[]) ?? [];
+    const kept = own.filter((f) => !unit.exclude?.some((d) => typeof f.file === "string" && (f.file === d || f.file.startsWith(`${d}/`))));
+    members.push({
+      member: unit.id,
+      dir: unit.dir,
+      exitCode: unit.exitCode,
+      status: report.status === "no-lexicons" ? "no-lexicons" : "ok",
+      summary: (report.summary as Json) ?? null,
+      error: null,
+      ...(kept.length < own.length ? { leftToMembers: own.length - kept.length } : {}),
+    });
+    for (const f of kept) findings.push({ ...f, member: unit.id });
+  }
+  return { schemaVersion: versions.size === 1 ? [...versions][0] : null, workspace, members, findings };
+}