@coldtea/pr-lens-cli 0.1.0

package/src/comment.ts

@@ -0,0 +1,190 @@
+import { assertNever } from "@coldtea/pr-lens-schema";
+import type { GraphDoc, Lens, RenderAsset, RenderManifest, View } from "@coldtea/pr-lens-schema";
+import { PrLensCliError } from "./errors.js";
+
+/**
+ * How the comment is recognised on a second run, so a pull request keeps one
+ * PR Lens comment instead of collecting one per push. Nothing else may spell
+ * this string: a marker that drifts orphans every comment already posted.
+ */
+export const COMMENT_MARKER = "<!-- pr-lens -->";
+
+const PROJECT_URL = "https://github.com/coldteadotai/pr-lens";
+const COLDTEA_URL = "https://coldtea.ai";
+
+export type CommentOptions = {
+  graph: GraphDoc;
+  manifest: RenderManifest;
+  /** Prefix for assets the manifest records as local paths, e.g. a raw content URL. */
+  assetBaseUrl: string | undefined;
+  branding: boolean;
+};
+
+const escape = (value: string): string =>
+  value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+
+/**
+ * Model-authored prose, rendered as the words it is.
+ *
+ * Every string in the document was written by a model reading a diff, and a
+ * pull request can carry whatever text an author likes into that diff. So
+ * none of it may reach GitHub as markup: escaping the HTML is only half the
+ * job, because markdown would still turn `[Security update](http://…)` into a
+ * link that looks like ours. Each string therefore lands inside an HTML
+ * element — inside one, markdown is not parsed at all — on a single line, so
+ * a blank line cannot end the block and let the rest through.
+ *
+ * The zero-width space after an @ or a # is the last piece: those are matched
+ * after markdown, on the rendered text, and would otherwise notify a person
+ * or cross-link an issue on the say-so of a diff.
+ */
+const text = (value: string): string =>
+  escape(value.replace(/\s+/g, " ").trim()).replace(/([@#])(?=[\w-])/g, "$1&#8203;");
+
+const href = (asset: RenderAsset, assetBaseUrl: string | undefined): string => {
+  if (asset.url !== undefined) return asset.url;
+  if (asset.path === undefined || assetBaseUrl === undefined)
+    throw new PrLensCliError(
+      "USAGE",
+      `asset '${asset.id}' is a local file, so the comment has nowhere to point`,
+      "pass --asset-base-url with the location the rendered SVGs are published at",
+    );
+
+  return `${assetBaseUrl.replace(/\/+$/, "")}/${asset.path.replace(/^\/+/, "")}`;
+};
+
+type ThemePair = { light: RenderAsset | undefined; dark: RenderAsset | undefined };
+
+const pairsByLens = (assets: readonly RenderAsset[]): Map<Lens, ThemePair> => {
+  const pairs = new Map<Lens, ThemePair>();
+  for (const asset of assets) {
+    const pair = pairs.get(asset.lens) ?? { light: undefined, dark: undefined };
+    pairs.set(asset.lens, { ...pair, [asset.theme]: asset });
+  }
+  return pairs;
+};
+
+/**
+ * A `<picture>` is what makes one comment readable in both GitHub themes: the
+ * dark source is swapped in by the browser, with the light asset as the `img`
+ * every other reader — email, mobile, an old client — falls back to.
+ *
+ * The whole thing is a link to the image itself, because a comment column is
+ * about 830 pixels wide and a diagram of a system with several lanes is
+ * several times that. It arrives scaled to fit, which is right for scanning,
+ * and one click gives a reader the size the labels were drawn at.
+ */
+const picture = (pair: ThemePair, alt: string, assetBaseUrl: string | undefined): string => {
+  const fallback = pair.light ?? pair.dark;
+  if (fallback === undefined) return "";
+
+  const source = escape(href(fallback, assetBaseUrl));
+  const image = `<img alt="${text(alt)}" src="${source}" width="${fallback.width}">`;
+
+  const shown =
+    pair.dark === undefined || pair.light === undefined
+      ? image
+      : [
+          "<picture>",
+          `  <source media="(prefers-color-scheme: dark)" srcset="${escape(href(pair.dark, assetBaseUrl))}">`,
+          `  ${image}`,
+          "</picture>",
+        ].join("\n");
+
+  return `<a href="${source}">${shown}</a>`;
+};
+
+const lensLabel = (lens: Lens): string => {
+  switch (lens) {
+    case "architecture":
+      return "Architecture";
+    case "data-flow":
+      return "Data flow";
+    default:
+      return assertNever(lens, "Unhandled lens");
+  }
+};
+
+const statsLine = (graph: GraphDoc): string => {
+  const { stats } = graph;
+  if (stats === undefined) return "";
+
+  const chips = [
+    stats.filesChanged === undefined
+      ? undefined
+      : `${stats.filesChanged} ${stats.filesChanged === 1 ? "file" : "files"}`,
+    stats.additions === undefined ? undefined : `+${stats.additions}`,
+    stats.deletions === undefined ? undefined : `−${stats.deletions}`,
+    ...stats.chips.map((chip) => `${chip.label} ${chip.value}`),
+  ].filter((chip): chip is string => chip !== undefined);
+
+  return `<p>${chips.map((chip) => `<code>${text(chip)}</code>`).join(" · ")}</p>`;
+};
+
+const viewSection = (
+  view: View,
+  assets: Map<string, RenderAsset[]>,
+  assetBaseUrl: string | undefined,
+): string => {
+  const own = assets.get(view.id) ?? [];
+  const pair = pairsByLens(own).get(view.lens);
+
+  const body = [
+    view.summary === undefined ? "" : `<p>${text(view.summary)}</p>`,
+    pair === undefined ? "" : picture(pair, view.title, assetBaseUrl),
+    ...view.children.map((child) => viewSection(child, assets, assetBaseUrl)),
+  ].filter((part) => part !== "");
+
+  return [
+    `<details${view.defaultOpen ? " open" : ""}>`,
+    `<summary><b>${text(view.title)}</b></summary>`,
+    "",
+    ...body.flatMap((part) => [part, ""]),
+    "</details>",
+  ].join("\n");
+};
+
+/** Assets keyed by the view they belong to; the root render has no view. */
+const ROOT = "";
+
+const byView = (manifest: RenderManifest): Map<string, RenderAsset[]> => {
+  const grouped = new Map<string, RenderAsset[]>();
+  for (const asset of manifest.assets) {
+    const key = asset.view ?? ROOT;
+    grouped.set(key, [...(grouped.get(key) ?? []), asset]);
+  }
+  return grouped;
+};
+
+export const composeComment = (options: CommentOptions): string => {
+  const { graph, manifest, assetBaseUrl, branding } = options;
+  const assets = byView(manifest);
+  const roots = pairsByLens(assets.get(ROOT) ?? []);
+
+  const diagrams = graph.lenses.flatMap((lens) => {
+    const pair = roots.get(lens);
+    return pair === undefined ? [] : [picture(pair, `${graph.title} — ${lensLabel(lens)}`, assetBaseUrl)];
+  });
+
+  const footer = branding
+    ? `<sub>◈ Rendered by <a href="${PROJECT_URL}">PR Lens</a> · from the team behind <a href="${COLDTEA_URL}">Coldtea</a></sub>`
+    : "";
+
+  return [
+    COMMENT_MARKER,
+    `<h3>${text(graph.title)}</h3>`,
+    graph.summary === undefined ? "" : `<p>${text(graph.summary)}</p>`,
+    statsLine(graph),
+    ...diagrams,
+    ...graph.views.map((view) => viewSection(view, assets, assetBaseUrl)),
+    footer === "" ? "" : "---",
+    footer,
+  ]
+    .filter((block) => block !== "")
+    .join("\n\n")
+    .concat("\n");
+};

package/src/config-file.ts

@@ -0,0 +1,26 @@
+import type { Config } from "@coldtea/pr-lens-schema";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { readConfig } from "./document.js";
+
+/** Where a repository puts its corrections, in the order they are looked for. */
+export const CONFIG_PATHS = [".github/pr-lens.yml", ".github/pr-lens.yaml"] as const;
+
+export type LoadedConfig = { path: string; config: Config };
+
+export const loadConfig = async (path: string): Promise<LoadedConfig> => ({
+  path,
+  config: await readConfig(path),
+});
+
+export const discoverConfig = async (root: string): Promise<LoadedConfig | undefined> => {
+  for (const candidate of CONFIG_PATHS) {
+    const path = join(root, candidate);
+    const found = await access(path).then(
+      () => true,
+      () => false,
+    );
+    if (found) return loadConfig(path);
+  }
+  return undefined;
+};

package/src/corrections.ts

@@ -0,0 +1,86 @@
+import { applyCorrections, graphContentHash } from "@coldtea/pr-lens-renderer";
+import type { Config, GraphDoc, MapCorrections } from "@coldtea/pr-lens-schema";
+
+const NOTHING: MapCorrections = { rename: [], exclude: [], lane: [], group: [] };
+
+/**
+ * A label, lane id and group id that appear nowhere in this document.
+ *
+ * It is what makes the question answerable at all: a rename to the label a
+ * node already carries moves nothing, and so does a lane pin into the lane a
+ * node is already in. Asking with a value the document cannot already hold
+ * separates "no node matches this" from "every node it matches already agrees
+ * with it" — and the difference matters, because the second is a live
+ * correction holding the line against the next inference.
+ */
+const unusedEverywhere = (graph: GraphDoc): string => {
+  const taken = new Set([
+    ...graph.nodes.map((node) => node.label),
+    ...graph.nodes.flatMap((node) => (node.group === undefined ? [] : [node.group])),
+    ...graph.nodes.map((node) => node.lane),
+    ...graph.lanes.map((lane) => lane.id),
+  ]);
+
+  let candidate = "pr-lens-probe";
+  for (let suffix = 1; taken.has(candidate); suffix += 1) candidate = `pr-lens-probe-${suffix}`;
+  return candidate;
+};
+
+type Probe = { what: string; match: string; only: MapCorrections };
+
+/**
+ * Each correction on its own, aimed somewhere the document is not, so that
+ * matching it always shows. Excluding is the one that needs no probe: a node
+ * a rule matches is always removed.
+ */
+const probes = (map: MapCorrections, probe: string): Probe[] => [
+  ...map.rename.map((rule) => ({
+    what: "rename",
+    match: rule.match,
+    only: { ...NOTHING, rename: [{ match: rule.match, to: probe }] },
+  })),
+  ...map.exclude.map((selector) => ({
+    what: "exclude",
+    match: selector,
+    only: { ...NOTHING, exclude: [selector] },
+  })),
+  ...map.lane.map((rule) => ({
+    what: "lane",
+    match: rule.match,
+    only: { ...NOTHING, lane: [{ match: rule.match, lane: probe }] },
+  })),
+  ...map.group.map((rule) => ({
+    what: "group",
+    match: rule.match,
+    only: { ...NOTHING, group: [{ match: rule.match, group: probe }] },
+  })),
+];
+
+/**
+ * Which of a repository's corrections match no node in this document.
+ *
+ * A selector that matches nothing is a config that has drifted since it was
+ * written — the file it named was moved or deleted — and saying so is the
+ * difference between a correction that stopped working and one that never
+ * did. It is never a reason to delete a correction that does match: that one
+ * is what keeps holding as the code moves.
+ *
+ * Which nodes a selector matches is the renderer's answer to give, so it is
+ * asked rather than recomputed. A second opinion about what a selector means
+ * is how the two drift apart.
+ */
+export const unmatchedCorrections = (graph: GraphDoc, config: Config): string[] => {
+  const before = graphContentHash(graph);
+  const probe = unusedEverywhere(graph);
+
+  return probes(config.map, probe).flatMap(({ what, match, only }) => {
+    try {
+      if (graphContentHash(applyCorrections(graph, only)) !== before) return [];
+    } catch {
+      // A correction that emptied the document is a correction that matched.
+      return [];
+    }
+
+    return [`${what} '${match}' changed nothing — no node in this document matches it`];
+  });
+};

package/src/document.ts

@@ -0,0 +1,119 @@
+import {
+  assertNever,
+  formatIssues,
+  safeParseConfig,
+  safeParseGraphDoc,
+  safeParsePatchDoc,
+  safeParseRenderManifest,
+  type Config,
+  type GraphDoc,
+  type Parsed,
+  type PatchDoc,
+  type PrLensSchemaError,
+  type RenderManifest,
+} from "@coldtea/pr-lens-schema";
+import { extname } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { PrLensCliError } from "./errors.js";
+import { readTextFile } from "./io.js";
+
+export type DocumentKind = "graph" | "patch" | "render-manifest" | "config";
+
+export type ValidatedDocument =
+  | { kind: "graph"; document: GraphDoc }
+  | { kind: "patch"; document: PatchDoc }
+  | { kind: "render-manifest"; document: RenderManifest }
+  | { kind: "config"; document: Config };
+
+export const describeDocumentKind = (kind: DocumentKind): string => {
+  switch (kind) {
+    case "graph":
+      return "graph document";
+    case "patch":
+      return "patch document";
+    case "render-manifest":
+      return "render manifest";
+    case "config":
+      return "config";
+    default:
+      return assertNever(kind, "Unhandled document kind");
+  }
+};
+
+export const invalidDocument = (
+  path: string,
+  kind: DocumentKind,
+  error: PrLensSchemaError,
+): PrLensCliError =>
+  new PrLensCliError(
+    "INVALID_DOCUMENT",
+    `${path} is not a valid ${describeDocumentKind(kind)} [${error.code}]`,
+    formatIssues(error.issues),
+  );
+
+const take = <T>(path: string, kind: DocumentKind, parsed: Parsed<T>): T => {
+  if (!parsed.ok) throw invalidDocument(path, kind, parsed.error);
+  return parsed.value;
+};
+
+/**
+ * YAML is a superset of JSON, so one parser reads both and a hand-written
+ * config gets the same treatment whichever spelling a repository chose.
+ */
+const readDocumentSource = async (path: string): Promise<unknown> => {
+  const text = await readTextFile(path);
+  try {
+    return parseYaml(text);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const syntax = extname(path) === ".json" ? "JSON" : "YAML";
+    throw new PrLensCliError("UNREADABLE_FILE", `${path} is not valid ${syntax}`, detail);
+  }
+};
+
+export const readGraphDoc = async (path: string): Promise<GraphDoc> =>
+  take(path, "graph", safeParseGraphDoc(await readDocumentSource(path)));
+
+export const readRenderManifest = async (path: string): Promise<RenderManifest> =>
+  take(path, "render-manifest", safeParseRenderManifest(await readDocumentSource(path)));
+
+export const readConfig = async (path: string): Promise<Config> =>
+  take(path, "config", safeParseConfig(await readDocumentSource(path)));
+
+/**
+ * `kind` names the document. Only a config lacks one, because it is the only
+ * one of the four a person writes by hand, and a discriminant in a file a
+ * person maintains buys nothing.
+ */
+const documentKindOf = (path: string, value: unknown): DocumentKind => {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new PrLensCliError("UNKNOWN_DOCUMENT", `${path} does not hold a PR Lens document`);
+
+  const kind = "kind" in value ? value.kind : undefined;
+  if (kind === undefined) return "config";
+  if (kind === "graph" || kind === "patch" || kind === "render-manifest") return kind;
+
+  throw new PrLensCliError(
+    "UNKNOWN_DOCUMENT",
+    `${path} declares an unknown document kind ${JSON.stringify(kind)}`,
+    "expected 'graph', 'patch' or 'render-manifest' — or no 'kind' at all, for a config",
+  );
+};
+
+export const validateDocumentFile = async (path: string): Promise<ValidatedDocument> => {
+  const source = await readDocumentSource(path);
+  const kind = documentKindOf(path, source);
+
+  switch (kind) {
+    case "graph":
+      return { kind, document: take(path, kind, safeParseGraphDoc(source)) };
+    case "patch":
+      return { kind, document: take(path, kind, safeParsePatchDoc(source)) };
+    case "render-manifest":
+      return { kind, document: take(path, kind, safeParseRenderManifest(source)) };
+    case "config":
+      return { kind, document: take(path, kind, safeParseConfig(source)) };
+    default:
+      return assertNever(kind, "Unhandled document kind");
+  }
+};

package/src/errors.ts

@@ -0,0 +1,36 @@
+/**
+ * Every failure a run can end on, as a code a caller — a script, a workflow
+ * step, or a future command — can branch on. Messages are for humans and may
+ * be reworded; codes are the contract.
+ */
+export type CliErrorCode =
+  | "USAGE"
+  | "UNREADABLE_FILE"
+  | "UNKNOWN_DOCUMENT"
+  | "INVALID_DOCUMENT"
+  | "GIT_FAILED"
+  | "EMPTY_DIFF"
+  | "REPOSITORY_UNKNOWN"
+  | "MISSING_API_KEY"
+  | "PROVIDER_FAILED"
+  | "MODEL_OUTPUT_INVALID"
+  | "RENDER_FAILED";
+
+export class PrLensCliError extends Error {
+  readonly code: CliErrorCode;
+  /** Extra lines printed under the message: validation issues, a git stderr, a hint. */
+  readonly details: string | undefined;
+
+  constructor(code: CliErrorCode, message: string, details?: string) {
+    super(message);
+    this.name = "PrLensCliError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export const usageError = (message: string, details?: string): PrLensCliError =>
+  new PrLensCliError("USAGE", message, details);
+
+export const formatError = (error: PrLensCliError): string =>
+  [`✗ ${error.message} [${error.code}]`, error.details ?? ""].filter((line) => line !== "").join("\n");

package/src/extract.ts

@@ -0,0 +1,136 @@
+import {
+  SCHEMA_VERSION,
+  safeParseGraphDoc,
+  type GraphDoc,
+  type GraphDocInput,
+  type Lens,
+} from "@coldtea/pr-lens-schema";
+import { z } from "zod";
+import { PrLensCliError } from "./errors.js";
+import type { JsonCompletion, Turn } from "./providers/index.js";
+import { buildJsonRepairPrompt, buildRepairPrompt } from "./prompt.js";
+
+/** One repair round. A model that cannot fix a named path in one go does not fix it in three. */
+const MAX_ATTEMPTS = 2;
+
+const JsonObject = z.record(z.string(), z.unknown());
+
+/**
+ * The fields the repository already knows the answer to. They are written
+ * over whatever the model emitted rather than merged with it: a commit sha, a
+ * line count or the lens set that was asked for is a fact, and a fact the
+ * model is free to restate is a fact that eventually disagrees with itself.
+ */
+export type KnownFields = {
+  provenance: GraphDocInput["provenance"];
+  stats: { filesChanged: number; additions: number; deletions: number };
+  lenses: readonly Lens[];
+  generatedAt: string;
+};
+
+/**
+ * Stamping the lens set is what makes `--lens` a request rather than a
+ * suggestion: a document whose flows or views need a lens that was not asked
+ * for now fails validation, and the correction round removes them.
+ */
+export const applyKnownFields = (body: Record<string, unknown>, known: KnownFields): unknown => {
+  const authored = JsonObject.safeParse(body.stats);
+  return {
+    ...body,
+    schemaVersion: SCHEMA_VERSION,
+    kind: "graph",
+    generatedAt: known.generatedAt,
+    provenance: known.provenance,
+    lenses: [...known.lenses],
+    stats: { ...(authored.success ? authored.data : {}), ...known.stats },
+  };
+};
+
+const FENCE = /^```(?:json)?\s*\n([\s\S]*?)\n?```\s*$/;
+
+export type JsonObjectRead =
+  | { ok: true; value: Record<string, unknown> }
+  | { ok: false; reason: string };
+
+/**
+ * Providers asked for JSON still fence it now and then, and some prepend a
+ * line of prose. Both are recoverable, and a run that already spent the tokens
+ * should not fail on packaging.
+ *
+ * A failure is returned rather than thrown, because truncated or malformed
+ * JSON is a weak model's most common answer and deserves the same correction
+ * round a structurally wrong document gets.
+ */
+export const readJsonObject = (text: string): JsonObjectRead => {
+  const fenced = FENCE.exec(text.trim());
+  const candidate = fenced?.[1] ?? text;
+  const start = candidate.indexOf("{");
+  const end = candidate.lastIndexOf("}");
+
+  let reason = "the answer holds no JSON object";
+
+  const attempts = [candidate, start >= 0 && end > start ? candidate.slice(start, end + 1) : ""];
+  for (const attempt of attempts) {
+    if (attempt === "") continue;
+    try {
+      const parsed = JsonObject.safeParse(JSON.parse(attempt));
+      if (parsed.success) return { ok: true, value: parsed.data };
+      reason = "the answer is JSON, but not an object";
+    } catch (error) {
+      reason = error instanceof Error ? error.message : String(error);
+    }
+  }
+
+  return { ok: false, reason };
+};
+
+export type Complete = (request: JsonCompletion) => Promise<string>;
+
+export type Extraction = { document: GraphDoc; attempts: number };
+
+export const extractGraph = async (
+  options: {
+    system: string;
+    user: string;
+    maxOutputTokens: number;
+    known: KnownFields;
+    onAttempt?: (attempt: number) => void;
+  },
+  complete: Complete,
+): Promise<Extraction> => {
+  const turns: Turn[] = [{ role: "user", text: options.user }];
+
+  const giveUp = (message: string, details: string): PrLensCliError =>
+    new PrLensCliError("MODEL_OUTPUT_INVALID", message, details);
+
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    options.onAttempt?.(attempt);
+    const last = attempt === MAX_ATTEMPTS;
+
+    const text = await complete({
+      system: options.system,
+      turns,
+      maxOutputTokens: options.maxOutputTokens,
+    });
+
+    const read = readJsonObject(text);
+    if (!read.ok) {
+      if (last) throw giveUp("the model did not answer with a JSON object, twice", read.reason);
+      turns.push({ role: "model", text }, { role: "user", text: buildJsonRepairPrompt(read.reason) });
+      continue;
+    }
+
+    const parsed = safeParseGraphDoc(applyKnownFields(read.value, options.known));
+    if (parsed.ok) return { document: parsed.value, attempts: attempt };
+
+    if (last)
+      throw giveUp(
+        `the model produced a document that does not validate, twice [${parsed.error.code}]`,
+        parsed.error.message,
+      );
+
+    turns.push({ role: "model", text }, { role: "user", text: buildRepairPrompt(parsed.error) });
+  }
+
+  throw giveUp("extraction produced no document", "no attempt returned an answer");
+};