@intentius/chant 0.124.12 → 0.124.14

package/dist/workspace/links.js

@@ -0,0 +1,330 @@
+/**
+ * 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`, or `live` for the rows of `check --live`, #2549) 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 { joinKey, joinLabel } from "../join-key.js";
+/**
+ * The link kinds chant knows. Closed: a link of any other kind fails closed.
+ * `output` reads a named output of the producer. `telemetry` (#2558, D22)
+ * sends the consumer's telemetry to a pipeline or exporter of the producer's
+ * collector.
+ */
+export const LINK_KINDS = ["output", "telemetry"];
+export const DEFAULT_LINK_KIND = "output";
+/** The kind a link has when it names a collector target (#2558). */
+export const TELEMETRY_LINK_KIND = "telemetry";
+/** The OTLP protocols a telemetry link may state, as `OTEL_EXPORTER_OTLP_PROTOCOL` names them. */
+export const TELEMETRY_PROTOCOLS = ["grpc", "http/protobuf", "http/json"];
+/**
+ * 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 function declaredMemberLinks(declaration) {
+    const names = new Set(declaration.members.map((m) => m.name));
+    const seen = new Set();
+    const out = [];
+    for (const m of declaration.members) {
+        for (const l of m.links) {
+            const key = `${m.name}\0${l.member}`;
+            if (l.member === m.name || !names.has(l.member) || seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ consumer: m.name, producer: l.member });
+        }
+    }
+    return out;
+}
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** Why a declared link's target is not a member it may name, or undefined. */
+export function linkTargetProblem(declaration, consumer, link) {
+    if (link.member === consumer.name)
+        return `member ${consumer.name} links to itself; a link joins two members`;
+    const entry = declaration.entries.find((e) => e.name === link.member);
+    if (!entry)
+        return `member ${consumer.name} links to ${link.member}, which is not a member of this workspace`;
+    if (entry.type === "group")
+        return `member ${consumer.name} links to ${link.member}, which is an example group; a group has no links`;
+    return undefined;
+}
+/** Output names that fold to the same key as `name`, for a "did you mean" hint. */
+function nearNames(name, outputs) {
+    const key = joinKey(name);
+    return [...new Set(outputs.filter((o) => o.name !== name && joinKey(o.name) === key).map((o) => o.name))].sort(cmp);
+}
+/**
+ * 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 function resolveLinks(declaration, handles, telemetry) {
+    const rows = [];
+    const declaredTargets = new Map();
+    for (const consumer of declaration.members) {
+        for (const link of consumer.links) {
+            const kind = link.kind ?? DEFAULT_LINK_KIND;
+            const row = {
+                consumer: consumer.name,
+                producer: link.member,
+                output: link.output,
+                kind,
+                origin: "declared",
+                label: "exact",
+                input: null,
+                resolves: "source",
+                status: "resolved",
+                reason: null,
+                pointer: link.pointer,
+                ...(link.protocol ? { protocol: link.protocol } : {}),
+            };
+            rows.push(row);
+            const targetProblem = linkTargetProblem(declaration, consumer, link);
+            if (targetProblem) {
+                row.status = "invalid";
+                row.reason = targetProblem;
+                continue;
+            }
+            (declaredTargets.get(consumer.name) ?? declaredTargets.set(consumer.name, new Set()).get(consumer.name)).add(`${link.member}\0${link.output}`);
+            if (!LINK_KINDS.includes(kind)) {
+                row.status = "invalid";
+                row.reason = `the link kind ${kind} is not one chant knows; known link kinds: ${LINK_KINDS.join(", ")}`;
+                continue;
+            }
+            if (kind === TELEMETRY_LINK_KIND) {
+                resolveTelemetryLink(row, telemetry);
+                continue;
+            }
+            if (link.protocol) {
+                row.status = "invalid";
+                row.reason = `protocol applies to telemetry links; this link has kind ${kind}`;
+                continue;
+            }
+            const producer = handles.get(link.member);
+            const found = producer?.outputs.find((o) => o.name === link.output);
+            if (found) {
+                if (found.node)
+                    row.to = found.node;
+                continue;
+            }
+            if (!producer) {
+                row.status = "unresolved";
+                row.reason = `the outputs of ${link.member} were not read`;
+            }
+            else if (producer.exposesNone) {
+                row.status = "missing";
+                row.reason = producer.why ?? `${link.member} exposes no outputs`;
+            }
+            else if (!producer.complete) {
+                row.status = "unresolved";
+                row.reason = `${link.output} was not found in ${link.member}, whose outputs could not all be read in source${producer.why ? ` (${producer.why})` : ""}`;
+            }
+            else {
+                const near = nearNames(link.output, producer.outputs);
+                const known = producer.outputs.map((o) => o.name);
+                row.status = "missing";
+                row.reason =
+                    `${link.member} has no output ${link.output}` +
+                        (near.length ? `; did you mean ${near.join(" or ")}? Links match exactly` : "") +
+                        (known.length ? `; its outputs: ${[...new Set(known)].sort(cmp).join(", ")}` : "; it exposes no outputs");
+            }
+        }
+    }
+    // Inferred joins: a consumer's parameter against every other member's outputs.
+    const inferred = [];
+    for (const consumer of declaration.members) {
+        const mine = handles.get(consumer.name);
+        if (!mine)
+            continue;
+        const declared = declaredTargets.get(consumer.name) ?? new Set();
+        for (const input of mine.inputs) {
+            const candidates = [];
+            for (const producer of declaration.members) {
+                if (producer.name === consumer.name)
+                    continue;
+                for (const o of handles.get(producer.name)?.outputs ?? []) {
+                    const label = joinLabel(input.name, o.name);
+                    if (!label)
+                        continue;
+                    if (candidates.some((c) => c.producer === producer.name && c.output === o.name))
+                        continue;
+                    candidates.push({ producer: producer.name, output: o.name, label, ...(o.node ? { to: o.node } : {}) });
+                }
+            }
+            if (candidates.length === 0)
+                continue;
+            // A declared link to one of the matches settles the parameter.
+            if (candidates.some((c) => declared.has(`${c.producer}\0${c.output}`)))
+                continue;
+            const base = { consumer: consumer.name, kind: DEFAULT_LINK_KIND, origin: "inferred:joinKey", resolves: "source" };
+            if (candidates.length === 1) {
+                const c = candidates[0];
+                inferred.push({
+                    ...base,
+                    status: "resolved",
+                    reason: null,
+                    producer: c.producer,
+                    output: c.output,
+                    label: c.label,
+                    input: input.name,
+                    ...(input.node ? { from: input.node } : {}),
+                    ...(c.to ? { to: c.to } : {}),
+                });
+            }
+            else {
+                candidates.sort((a, b) => cmp(a.producer, b.producer) || cmp(a.output, b.output));
+                const producers = new Set(candidates.map((c) => c.producer));
+                inferred.push({
+                    ...base,
+                    status: "ambiguous",
+                    reason: producers.size > 1
+                        ? `parameter ${input.name} of ${consumer.name} matches outputs of ${[...producers].join(" and ")}`
+                        : `parameter ${input.name} of ${consumer.name} matches ${candidates.map((c) => c.output).join(" and ")} of ${candidates[0].producer}`,
+                    input: input.name,
+                    ...(input.node ? { from: input.node } : {}),
+                    candidates,
+                });
+            }
+        }
+    }
+    inferred.sort((a, b) => cmp(a.consumer, b.consumer) || cmp(a.input ?? "", b.input ?? ""));
+    return [...rows, ...inferred];
+}
+/**
+ * Resolve a telemetry link against the producer's collector (#2558): the
+ * target exists (presence), and when the link states a protocol, the target
+ * speaks it. A pipeline speaks what its receivers speak; an exporter speaks
+ * what its definition says. A target whose protocols the collector's
+ * definitions don't state leaves the link unresolved rather than failed.
+ */
+function resolveTelemetryLink(row, telemetry) {
+    if (!telemetry) {
+        row.status = "unresolved";
+        row.reason = `the collector of ${row.producer} is read by chant workspace graph; chant workspace check reads source and runs no member`;
+        return;
+    }
+    const collector = telemetry.collectors.get(row.producer);
+    if (!collector) {
+        if (!telemetry.composed.has(row.producer)) {
+            row.status = "unresolved";
+            row.reason = `the collector of ${row.producer} was not read: ${row.producer} was not composed`;
+        }
+        else {
+            row.status = "missing";
+            row.reason = `${row.producer} declares no collector: its build reports no collector pipelines or components`;
+        }
+        return;
+    }
+    const pipeline = collector.pipelines.find((p) => p.id === row.output);
+    const exporter = pipeline ? undefined : collector.exporters.find((e) => e.id === row.output);
+    if (!pipeline && !exporter) {
+        row.status = "missing";
+        row.reason =
+            `${row.producer}'s collector has no pipeline or exporter ${row.output}` +
+                `; pipelines: ${collector.pipelines.map((p) => p.id).join(", ") || "none"}` +
+                `; exporters: ${collector.exporters.map((e) => e.id).join(", ") || "none"}`;
+        return;
+    }
+    row.target = pipeline ? "pipeline" : "exporter";
+    if (!row.protocol)
+        return;
+    const ids = pipeline ? pipeline.receivers : [exporter.id];
+    const speaks = [...new Set(collector.components.filter((c) => ids.includes(c.id)).flatMap((c) => c.protocols))];
+    const what = pipeline ? `the receivers of pipeline ${row.output}` : `exporter ${row.output}`;
+    if (speaks.length === 0) {
+        row.status = "unresolved";
+        row.reason = `${what} state no protocols, so ${row.protocol} could not be confirmed`;
+    }
+    else if (!speaks.includes(row.protocol)) {
+        row.status = "invalid";
+        row.reason = `${what} speak ${speaks.join(", ")}, and the link sends ${row.protocol}`;
+    }
+}
+// ── Where the handles come from ──────────────────────────────────────────────
+/**
+ * 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 function kindHandles(m, kind) {
+    const outputs = kind.outputs;
+    if (outputs.from === "none") {
+        return { member: m.name, outputs: [], inputs: [], complete: true, why: `${m.name} is kind ${m.kind}, which exposes no outputs as link targets`, exposesNone: true };
+    }
+    if (outputs.from === "declared") {
+        const names = [...new Set([...outputs.names, ...(m.outputs ?? [])])];
+        return { member: m.name, outputs: names.map((name) => ({ name })), inputs: [], complete: true, why: null, exposesNone: false };
+    }
+    return undefined;
+}
+/**
+ * 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 function irMemberHandles(graph) {
+    const out = new Map();
+    for (const member of graph.composed) {
+        out.set(member, {
+            member,
+            outputs: graph.exports.filter((e) => e.member === member).map((e) => ({ name: e.name, ...(e.node ? { node: e.node } : {}) })),
+            inputs: graph.imports.filter((i) => i.member === member).map((i) => ({ name: i.name, node: i.node })),
+            complete: true,
+            why: null,
+            exposesNone: false,
+        });
+    }
+    return out;
+}
+/**
+ * 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 function graphLinks(declaration, graph, kinds) {
+    const handles = irMemberHandles(graph);
+    for (const m of declaration.members) {
+        const kind = kinds?.get(m.kind);
+        if (handles.has(m.name) || !kind)
+            continue;
+        const listed = kindHandles(m, kind);
+        if (listed)
+            handles.set(m.name, listed);
+    }
+    const telemetry = {
+        collectors: new Map((graph.collectors ?? []).map((c) => [c.member, c])),
+        composed: new Set(graph.composed),
+    };
+    return resolveLinks(declaration, handles, telemetry).map((row) => {
+        if (row.status === "ambiguous" || row.origin !== "declared")
+            return row;
+        // The declaration's pointer means nothing to a graph reader.
+        const { pointer: _pointer, ...rest } = row;
+        return rest;
+    });
+}

package/dist/workspace/ls-generated.js

@@ -0,0 +1,95 @@
+/**
+ * The generated files a member owns, and the CI job names inside them, for
+ * `chant workspace ls --json` (#3050; read by INTENTIUS/github-warden#62).
+ *
+ * Two sources feed the list. The member's declared `generated` entries (#2541)
+ * are relative to the member's directory. The interim record
+ * `.chant/generated.json` that `chant build --components --generate` and
+ * `chant run --generate` write (#2542) holds repository-relative paths, which is
+ * how a forge CI file outside the member's directory is named. A path in both
+ * lists once, with the declared entry's command.
+ *
+ * The job names are what a forge shows as the check name, so a reader can
+ * require them: for GitHub, Forgejo and Gitea the job's `name`, else its id;
+ * for GitLab the job's key. chant parses the file and runs nothing.
+ */
+import yaml from "js-yaml";
+import { isForgePath } from "./checks/pipelines.js";
+import { GENERATED_RECORD_FILE } from "./member-pipeline.js";
+import { joinPath } from "./tree.js";
+/** Top-level GitLab keys that are not jobs. */
+const GITLAB_KEYWORDS = new Set(["stages", "variables", "default", "include", "workflow", "image", "services", "cache", "before_script", "after_script", "pages"]);
+/** The check names in a forge CI file, or null when the file is no workflow or can't be parsed. */
+export function jobNames(path, text) {
+    let doc;
+    try {
+        doc = yaml.load(text);
+    }
+    catch {
+        return null;
+    }
+    if (!doc || typeof doc !== "object" || Array.isArray(doc))
+        return null;
+    const top = doc;
+    if (path.startsWith(".gitlab/ci/") || path === ".gitlab-ci.yml") {
+        return Object.entries(top)
+            .filter(([k, v]) => !k.startsWith(".") && !GITLAB_KEYWORDS.has(k) && v && typeof v === "object" && !Array.isArray(v))
+            .map(([k]) => k);
+    }
+    const jobs = top["jobs"];
+    if (!jobs || typeof jobs !== "object" || Array.isArray(jobs))
+        return null;
+    return Object.entries(jobs).map(([id, job]) => {
+        const name = job && typeof job === "object" ? job["name"] : undefined;
+        return typeof name === "string" && name !== "" ? name : id;
+    });
+}
+/**
+ * The member's generated files. `prefix` is the workspace root relative to the
+ * repository root, `"."` when they are the same. Never throws for a record that
+ * is missing or malformed: that member lists what the declaration gives.
+ */
+export function memberGenerated(member, tree, prefix) {
+    const repoPath = (workspacePath) => joinPath(prefix, workspacePath);
+    const byPath = new Map();
+    const recordFile = joinPath(member.dir, GENERATED_RECORD_FILE);
+    if (tree.stat(recordFile) === "file") {
+        try {
+            const parsed = JSON.parse(tree.read(recordFile));
+            for (const f of Array.isArray(parsed.files) ? parsed.files : []) {
+                if (typeof f.path !== "string")
+                    continue;
+                byPath.set(f.path, {
+                    path: f.path,
+                    command: typeof f.command === "string" ? f.command : "",
+                    env: typeof f.env === "string" ? f.env : null,
+                    jobs: null,
+                });
+            }
+        }
+        catch {
+            // an unreadable record lists nothing from itself
+        }
+    }
+    for (const g of member.generated) {
+        if (g.handWritten)
+            continue;
+        const path = repoPath(joinPath(member.dir, g.path));
+        byPath.set(path, { path, command: g.generator, env: byPath.get(path)?.env ?? null, jobs: null });
+    }
+    const own = prefix === "." ? "" : `${prefix}/`;
+    for (const entry of byPath.values()) {
+        if (!isForgePath(entry.path) || !entry.path.startsWith(own))
+            continue;
+        const inTree = entry.path.slice(own.length);
+        if (tree.stat(inTree) !== "file")
+            continue;
+        try {
+            entry.jobs = jobNames(entry.path, tree.read(inTree));
+        }
+        catch {
+            entry.jobs = null;
+        }
+    }
+    return [...byPath.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}