@coldtea/pr-lens-schema 0.1.0

package/src/patch.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { Flow, GraphEdge, GraphNode, Lane, Stats } from "./graph.js";
+import { FullSha, Id, SchemaVersionField, Summary } from "./primitives.js";
+
+/**
+ * Update payloads are the element minus its id: a patch never renames the
+ * thing it addresses. Every field is optional and only the supplied fields
+ * are written, so two producers can patch different facets of one element
+ * without clobbering each other.
+ */
+export const LanePatch = Lane.omit({ id: true }).partial();
+export const NodePatch = GraphNode.omit({ id: true }).partial();
+export const EdgePatch = GraphEdge.omit({ id: true }).partial();
+export const FlowPatch = Flow.omit({ id: true }).partial();
+
+/**
+ * Operations that evolve a stored graph — in practice the baseline map, which
+ * is updated by each merged pull request rather than re-extracted wholesale.
+ *
+ * `remove_*` deletes the element from the map. That is a different statement
+ * from `delta: "removed"`, which says an element still exists in the map but
+ * is being deleted by the change under review.
+ */
+export const PatchOp = z
+  .discriminatedUnion("op", [
+    z.strictObject({ op: z.literal("add_lane"), lane: Lane }),
+    z.strictObject({ op: z.literal("update_lane"), id: Id, patch: LanePatch }),
+    z.strictObject({ op: z.literal("remove_lane"), id: Id }),
+
+    z.strictObject({ op: z.literal("add_node"), node: GraphNode }),
+    z.strictObject({ op: z.literal("update_node"), id: Id, patch: NodePatch }),
+    z.strictObject({ op: z.literal("remove_node"), id: Id }),
+
+    z.strictObject({ op: z.literal("add_edge"), edge: GraphEdge }),
+    z.strictObject({ op: z.literal("update_edge"), id: Id, patch: EdgePatch }),
+    z.strictObject({ op: z.literal("remove_edge"), id: Id }),
+
+    z.strictObject({ op: z.literal("add_flow"), flow: Flow }),
+    z.strictObject({ op: z.literal("update_flow"), id: Id, patch: FlowPatch }),
+    z.strictObject({ op: z.literal("remove_flow"), id: Id }),
+
+    z.strictObject({ op: z.literal("set_stats"), stats: Stats }),
+  ])
+  .describe("A single change to a stored graph document.");
+export type PatchOp = z.infer<typeof PatchOp>;
+
+export const PATCH_OPS = [
+  "add_lane",
+  "update_lane",
+  "remove_lane",
+  "add_node",
+  "update_node",
+  "remove_node",
+  "add_edge",
+  "update_edge",
+  "remove_edge",
+  "add_flow",
+  "update_flow",
+  "remove_flow",
+  "set_stats",
+] as const;
+
+/**
+ * A patch has to move the map: the same commit at both ends describes no
+ * transition, and such a patch could be applied over and over.
+ *
+ * The rule lives here as a predicate because a zod refinement does not
+ * survive into the inferred type — a caller holding a `PatchDoc` it built
+ * itself has to be held to the same rule as one that came from a parser.
+ */
+export const targetDescribesATransition = (target: {
+  fromSha: string;
+  toSha: string;
+}): boolean => target.fromSha !== target.toSha;
+
+/** An ordered batch of operations against one stored graph. */
+export const PatchDoc = z
+  .strictObject({
+    schemaVersion: SchemaVersionField,
+    kind: z.literal("patch"),
+    generatedAt: z.iso.datetime().optional(),
+    summary: Summary.optional().describe("Why the map is changing, in prose."),
+    target: z
+      .strictObject({
+        graphId: Id.describe("Id of the stored graph being patched."),
+        fromSha: FullSha.describe("Commit the stored graph reflects before the operations run."),
+        toSha: FullSha.describe("Commit it reflects once they have."),
+      })
+      .refine(targetDescribesATransition, {
+        message: "a patch has to move the map to a different commit",
+        path: ["toSha"],
+      })
+      .describe(
+        "Which stored graph these operations belong to, and which commits they carry it between. All three are required, and the commits must differ: they are what stops a patch landing on the wrong map, on a stale one, or twice.",
+      ),
+    ops: z.array(PatchOp).min(1).max(512).describe("Applied in array order."),
+  })
+  .describe("A PR Lens patch document.");
+export type PatchDoc = z.infer<typeof PatchDoc>;
+export type PatchDocInput = z.input<typeof PatchDoc>;

package/src/primitives.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import { SCHEMA_VERSION, SUPPORTED_VERSION_PATTERN } from "./version.js";
+
+/**
+ * Identifiers are authored by an extraction model, so they are constrained to
+ * a shape that survives being embedded in an SVG id, a URL fragment and a
+ * GitHub comment anchor without escaping.
+ */
+export const Id = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(
+    /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/,
+    "must start alphanumeric and contain only letters, digits and . _ : / -",
+  )
+  .describe("Stable identifier, unique within its collection in a document.");
+export type Id = z.infer<typeof Id>;
+
+/**
+ * The loose shape is checked here and the supported range is checked by the
+ * parser, which can say which version it implements. The exported JSON
+ * Schemas carry the range instead, since they have no parser behind them.
+ */
+export const SchemaVersionField = z
+  .string()
+  .regex(/^\d+\.\d+\.\d+$/, "must be a semver string, e.g. 0.1.0")
+  .meta({ pattern: SUPPORTED_VERSION_PATTERN })
+  .describe(`Contract version the document targets. Current: ${SCHEMA_VERSION}.`);
+
+/** Non-empty single-line label rendered on a card, lane header or edge. */
+export const Label = z.string().min(1).max(120).describe("Short display label.");
+
+/** Prose shown in drill-down bodies; kept short enough to stay scannable. */
+export const Summary = z
+  .string()
+  .min(1)
+  .max(2000)
+  .describe("One or two sentences of plain prose. No markdown headings.");
+
+export const Sha = z
+  .string()
+  .regex(/^[0-9a-f]{7,40}$/, "must be a lowercase hex git object name")
+  .describe("Git commit sha, abbreviated or full.");
+
+/**
+ * Abbreviations are fine for something a human reads, but not for deciding
+ * whether two records mean the same commit: two abbreviations of different
+ * lengths compare unequal, and a short one can collide as a repository grows.
+ * Anything a machine compares uses the full name.
+ */
+export const FullSha = z
+  .string()
+  .regex(/^[0-9a-f]{40}$/, "must be a full 40-character lowercase hex git object name")
+  .describe("Git commit sha, in full.");
+
+/**
+ * The two lenses PR Lens ships. The enum is additive: a future contract
+ * version may introduce further lenses, and consumers must treat an unknown
+ * lens as "skip this view" rather than as a hard failure.
+ */
+export const Lens = z.enum(["architecture", "data-flow"]).describe("Rendering lens.");
+export type Lens = z.infer<typeof Lens>;
+
+export const LENSES = Lens.options;
+
+/** The two renders that make a `<picture>` pair. */
+export const Theme = z.enum(["light", "dark"]).describe("Which colour scheme a render targets.");
+export type Theme = z.infer<typeof Theme>;
+
+export const THEMES = Theme.options;
+
+/**
+ * A render is one asset per view per theme, so these two caps are one rule
+ * rather than two numbers that happen to sit near each other: a document with
+ * more views than a manifest can carry at every theme is one whose full
+ * render could never be described, however well formed it looks.
+ *
+ * Deriving the view cap from the asset budget keeps the relationship in one
+ * place — raise the budget, or add a theme, and the other end moves with it
+ * instead of every surface rediscovering the arithmetic.
+ *
+ * The cap is deliberately the worst case, every theme rendered, rather than
+ * what some particular render would emit. A renderer asked for one theme
+ * could describe twice as many views, but then whether a document is
+ * renderable would depend on how it was asked to be rendered, and the promise
+ * this package exists to make — if it parses, it renders — would need a
+ * second rule at a second boundary to stay true.
+ */
+export const MAX_RENDER_ASSETS = 256;
+
+export const MAX_VIEWS = MAX_RENDER_ASSETS / THEMES.length;
+
+/**
+ * How an element relates to the base branch. `unchanged` elements are the
+ * context a reader needs to judge blast radius, so they are first-class
+ * rather than omitted.
+ */
+export const Delta = z
+  .enum(["added", "modified", "removed", "unchanged"])
+  .describe("Change state relative to the base commit.");
+export type Delta = z.infer<typeof Delta>;
+
+export const DELTAS = Delta.options;
+
+/**
+ * One rule both representations share: no absolute path in any spelling a
+ * platform recognises, and no `..` segment. A path that breaks it cannot
+ * produce a diff permalink, whatever else it might mean.
+ */
+const REPOSITORY_PATH = /^(?!\/)(?![A-Za-z]:)(?!.*\\)(?!.*(?:^|\/)\.\.(?:\/|$)).+$/;
+
+/**
+ * A pointer into the head tree, used to build diff permalinks. Line numbers
+ * are 1-based and refer to the head revision except on `removed` elements,
+ * where they refer to the base revision.
+ */
+export const FileRef = z
+  .strictObject({
+    path: z
+      .string()
+      .min(1)
+      .max(1024)
+      .regex(
+        REPOSITORY_PATH,
+        "must be a repository-relative POSIX path, without a drive letter, a backslash or a '..' segment",
+      )
+      .describe("Repository-relative path, POSIX separators."),
+    startLine: z.int().min(1).optional().describe("1-based first line."),
+    endLine: z.int().min(1).optional().describe("1-based last line, inclusive."),
+    revision: z
+      .enum(["head", "base"])
+      .optional()
+      .describe("Which side of the diff the lines refer to. Defaults to head."),
+  })
+  .meta({ dependentRequired: { endLine: ["startLine"] } })
+  .refine((f) => f.endLine === undefined || f.startLine !== undefined, {
+    message: "endLine requires startLine",
+    path: ["endLine"],
+  })
+  .refine((f) => f.endLine === undefined || f.startLine === undefined || f.endLine >= f.startLine, {
+    message: "endLine must be greater than or equal to startLine",
+    path: ["endLine"],
+  })
+  .describe("A file (and optional line range) backing an element.");
+export type FileRef = z.infer<typeof FileRef>;

package/src/utils.ts

@@ -0,0 +1,7 @@
+/**
+ * Ends a switch over a closed set. Adding a variant then fails to compile at
+ * every consumer instead of silently falling through at runtime.
+ */
+export const assertNever = (value: never, message = "Unhandled variant"): never => {
+  throw new Error(`${message}: ${JSON.stringify(value)}`);
+};

package/src/validate.ts

@@ -0,0 +1,132 @@
+import type { z } from "zod";
+import { Config } from "./config.js";
+import { formatIssues, PrLensSchemaError, type Parsed, type SchemaIssue } from "./errors.js";
+import { GraphDoc } from "./graph.js";
+import { graphIntegrityIssues } from "./integrity.js";
+import { RenderManifest } from "./manifest.js";
+import { PatchDoc } from "./patch.js";
+import { isSupportedVersion, SCHEMA_VERSION } from "./version.js";
+
+const formatPath = (path: readonly PropertyKey[]): string =>
+  path.reduce<string>((acc, segment) => {
+    if (typeof segment === "number") return `${acc}[${segment}]`;
+    return acc === "" ? String(segment) : `${acc}.${String(segment)}`;
+  }, "");
+
+const toIssues = (error: z.ZodError): SchemaIssue[] =>
+  error.issues.map((issue) => ({
+    code: "INVALID_DOCUMENT" as const,
+    path: formatPath(issue.path),
+    message: issue.message,
+  }));
+
+const versionIssues = (version: string, path: string): SchemaIssue[] =>
+  isSupportedVersion(version)
+    ? []
+    : [
+        {
+          code: "UNSUPPORTED_SCHEMA_VERSION",
+          path,
+          message: `document targets schema version ${version}; this package implements ${SCHEMA_VERSION}`,
+        },
+      ];
+
+const fail = (label: string, issues: SchemaIssue[]): PrLensSchemaError => {
+  const first = issues[0];
+  return new PrLensSchemaError(
+    first ? first.code : "INVALID_DOCUMENT",
+    `invalid ${label}:\n${formatIssues(issues)}`,
+    issues,
+  );
+};
+
+/**
+ * Validating a recursive structure recurses, so a document nested deeply
+ * enough exhausts the stack while zod is still walking it — before any check
+ * of ours can count anything. A `safeParse` that throws would be a worse
+ * failure than the document it was handed, so the stack running out is
+ * reported as what it is: a document too deep to read.
+ *
+ * Every `RangeError` is read that way, not only the ones provoked by depth.
+ * That is deliberate: failing closed keeps the promise that these functions
+ * return a verdict rather than throwing one, and nesting is the only way a
+ * document is known to provoke one. Narrowing this to rethrow would trade
+ * that promise for a diagnosis.
+ */
+const attemptParse = <Schema extends z.ZodType>(
+  schema: Schema,
+  input: unknown,
+): { read: true; value: z.infer<Schema> } | { read: false; issues: SchemaIssue[] } => {
+  try {
+    const result = schema.safeParse(input);
+    return result.success
+      ? { read: true, value: result.data }
+      : { read: false, issues: toIssues(result.error) };
+  } catch (error) {
+    if (!(error instanceof RangeError)) throw error;
+    return {
+      read: false,
+      issues: [
+        {
+          code: "INVALID_DOCUMENT",
+          path: "",
+          message: "document nests too deeply to read",
+        },
+      ],
+    };
+  }
+};
+
+const parseDocument = <Schema extends z.ZodType>(
+  schema: Schema,
+  label: string,
+  input: unknown,
+  extraIssues: (value: z.infer<Schema>) => SchemaIssue[],
+): Parsed<z.infer<Schema>> => {
+  const result = attemptParse(schema, input);
+  if (!result.read) return { ok: false, error: fail(label, result.issues) };
+
+  const issues = extraIssues(result.value);
+  if (issues.length > 0) return { ok: false, error: fail(label, issues) };
+
+  return { ok: true, value: result.value };
+};
+
+const unwrap = <T>(parsed: Parsed<T>): T => {
+  if (parsed.ok) return parsed.value;
+  throw parsed.error;
+};
+
+/**
+ * Structure, contract version and referential integrity in one pass. A
+ * document that survives this is safe to render without further checking.
+ */
+export const safeParseGraphDoc = (input: unknown): Parsed<GraphDoc> =>
+  parseDocument(GraphDoc, "graph document", input, (doc) => [
+    ...versionIssues(doc.schemaVersion, "schemaVersion"),
+    ...graphIntegrityIssues(doc),
+  ]);
+
+export const parseGraphDoc = (input: unknown): GraphDoc => unwrap(safeParseGraphDoc(input));
+
+export const safeParsePatchDoc = (input: unknown): Parsed<PatchDoc> =>
+  parseDocument(PatchDoc, "patch document", input, (doc) =>
+    versionIssues(doc.schemaVersion, "schemaVersion"),
+  );
+
+export const parsePatchDoc = (input: unknown): PatchDoc => unwrap(safeParsePatchDoc(input));
+
+export const safeParseConfig = (input: unknown): Parsed<Config> =>
+  parseDocument(Config, "config", input, (config) =>
+    versionIssues(config.schemaVersion, "schemaVersion"),
+  );
+
+export const parseConfig = (input: unknown): Config => unwrap(safeParseConfig(input));
+
+export const safeParseRenderManifest = (input: unknown): Parsed<RenderManifest> =>
+  parseDocument(RenderManifest, "render manifest", input, (manifest) =>
+    versionIssues(manifest.schemaVersion, "schemaVersion"),
+  );
+
+export const parseRenderManifest = (input: unknown): RenderManifest =>
+  unwrap(safeParseRenderManifest(input));

package/src/version.ts

@@ -0,0 +1,31 @@
+/**
+ * Version of the PR Lens document contract.
+ *
+ * Every document carries this string so a consumer can refuse, migrate, or
+ * degrade gracefully when it meets a document it was not built for. Bumped
+ * with semver semantics: patch/minor releases only ever add optional fields
+ * or widen an enum, a major release may remove or retype a field.
+ */
+export const SCHEMA_VERSION = "0.1.0" as const;
+
+export type SchemaVersion = typeof SCHEMA_VERSION;
+
+const [currentMajor = "0", currentMinor = "0"] = SCHEMA_VERSION.split(".");
+
+const readableMinors = Array.from({ length: Number(currentMinor) + 1 }, (_, minor) => minor);
+
+/**
+ * Which versions this package reads, as a pattern so the rule can be carried
+ * into the exported JSON Schemas rather than restated there.
+ *
+ * Below 1.0 a minor bump is allowed to break, so only the exact major.minor
+ * is accepted; from 1.0 on, the major must match and a newer minor is
+ * readable because minor releases only add optional fields.
+ */
+export const SUPPORTED_VERSION_PATTERN =
+  currentMajor === "0"
+    ? `^0\\.${currentMinor}\\.\\d+$`
+    : `^${currentMajor}\\.(${readableMinors.join("|")})\\.\\d+$`;
+
+export const isSupportedVersion = (version: string): boolean =>
+  new RegExp(SUPPORTED_VERSION_PATTERN).test(version);