@theholocron/cli 5.0.0-alpha.276 → 5.0.0-alpha.278

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.mjs CHANGED
@@ -24,7 +24,7 @@ import { errorMessage } from "@theholocron/misc-utils";
24
24
  import path, { basename, dirname, join, relative, resolve, sep } from "node:path";
25
25
  import { ConfigFileError, loadConfigFile } from "@theholocron/datapad";
26
26
  import { readGitRemote, updateGitignore } from "@theholocron/git-utils";
27
- import { discoverWorkspacePackages, readPackageJson, readPackageJsonSync, resolveWorkspaceGlobs } from "@theholocron/pkg-utils";
27
+ import { bumpCatalogPins, discoverWorkspacePackages, parseCatalogs, readPackageJson, readPackageJsonSync, resolveWorkspaceGlobs } from "@theholocron/pkg-utils";
28
28
  import { findRootSync, isWorkspaceRoot, walkFilesSync } from "@theholocron/fs-utils";
29
29
  import { access, copyFile, mkdir, open, readFile, readdir, realpath, rename, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
30
30
  import { createServer } from "node:http";
@@ -2333,6 +2333,12 @@ function resolveEntry(key, raw) {
2333
2333
  })
2334
2334
  };
2335
2335
  }
2336
+ /** The values `repoValidation.docsCoverage` accepts. */
2337
+ const DOCS_COVERAGE_MODES = [
2338
+ "off",
2339
+ "warn",
2340
+ "required"
2341
+ ];
2336
2342
  function resolveConfig(raw) {
2337
2343
  if (!raw.name) throw new ConfigError("`name` is required");
2338
2344
  if (!raw.providers || typeof raw.providers !== "object") throw new ConfigError("`providers` block is required");
@@ -2347,6 +2353,8 @@ function resolveConfig(raw) {
2347
2353
  if (!raw.docs.build) throw new ConfigError("`docs.build` is required when `docs` is set");
2348
2354
  docs = raw.docs;
2349
2355
  }
2356
+ const docsCoverage = raw.repoValidation?.docsCoverage;
2357
+ if (docsCoverage !== void 0 && !DOCS_COVERAGE_MODES.includes(docsCoverage)) throw new ConfigError(`\`repoValidation.docsCoverage\` must be one of ${DOCS_COVERAGE_MODES.map((m) => `"${m}"`).join(", ")}, got ${JSON.stringify(docsCoverage)}`);
2350
2358
  const homepage = raw.homepage ?? (docs?.domain ? `https://${docs.domain}/` : void 0);
2351
2359
  return {
2352
2360
  name: raw.name,
@@ -2355,6 +2363,7 @@ function resolveConfig(raw) {
2355
2363
  org: raw.org,
2356
2364
  domain: raw.domain,
2357
2365
  repo: raw.repo,
2366
+ repoValidation: raw.repoValidation,
2358
2367
  tasks: raw.tasks,
2359
2368
  syncScripts: raw.syncScripts,
2360
2369
  holocronScript: raw.holocronScript,
@@ -3966,6 +3975,17 @@ function summariseChecks(rows) {
3966
3975
  skip: rows.filter((r) => r.status === "skip").length
3967
3976
  };
3968
3977
  }
3978
+ // src/commands/missing-token/missing-token.ts
3979
+ /**
3980
+ * Why a provider call could not be tried for want of a token, or undefined when the error is something else. A plugin
3981
+ * resolves its token on first use and throws an `AuthError` naming where it looked; the GitHub plugin throws a
3982
+ * {@link MissingTokenError}. Both mean "no token", which a deep check reports as a skip, not a failure. The
3983
+ * `AuthError` is matched by name because the plugin and the CLI may each hold their own copy of the class.
3984
+ */
3985
+ function missingTokenReason(err) {
3986
+ if (err instanceof MissingTokenError) return err.message;
3987
+ if (err instanceof Error && err.name === "AuthError") return err.message;
3988
+ }
3969
3989
  // src/commands/notifications-channel-add/avatar.ts
3970
3990
  /**
3971
3991
  * Read a webhook avatar named in a layout: a file path (from the directory the CLI runs in) or an
@@ -4633,7 +4653,7 @@ async function runDoctorDns(input) {
4633
4653
  });
4634
4654
  else if (!loader.has("dns")) {
4635
4655
  const why = whyMissing(loader, "dns", "no `dns` provider to check them with");
4636
- for (const zone of zones) rows.push(row$4(zone, "skip", why));
4656
+ for (const zone of zones) rows.push(row$3(zone, "skip", why));
4637
4657
  } else {
4638
4658
  const dns = loader.get("dns");
4639
4659
  for (const zone of zones) rows.push(await checkZone(dns, zone, expected.filter((e) => e.zone === zone).map((e) => e.record)));
@@ -4653,7 +4673,7 @@ async function runDoctorDns(input) {
4653
4673
  ...status === "skip" ? { reason: [...new Set(rows.map((r) => r.detail))].join("; ") } : {}
4654
4674
  };
4655
4675
  }
4656
- function row$4(zone, status, detail, problems = []) {
4676
+ function row$3(zone, status, detail, problems = []) {
4657
4677
  return {
4658
4678
  id: `dns-${zone}`,
4659
4679
  title: `${zone} records exist`,
@@ -4671,9 +4691,10 @@ async function checkZone(dns, zone, wanted) {
4671
4691
  equal: (want, found) => sameContent(want.content, found.content) && (want.proxied !== true || found.proxied === true),
4672
4692
  show: (r) => `${r.content}${r.proxied ? " (proxied)" : ""}`
4673
4693
  });
4674
- return problems.length > 0 ? row$4(zone, "fail", `${problems.length} problem(s)`, problems) : row$4(zone, "ok", `${wanted.length} of ${wanted.length} exist`);
4694
+ return problems.length > 0 ? row$3(zone, "fail", `${problems.length} problem(s)`, problems) : row$3(zone, "ok", `${wanted.length} of ${wanted.length} exist`);
4675
4695
  } catch (err) {
4676
- return err instanceof MissingTokenError ? row$4(zone, "skip", err.message) : row$4(zone, "fail", errorMessage(err));
4696
+ const noToken = missingTokenReason(err);
4697
+ return noToken !== void 0 ? row$3(zone, "skip", noToken) : row$3(zone, "fail", errorMessage(err));
4677
4698
  }
4678
4699
  }
4679
4700
  // src/commands/doctor-dns/doctor-dns.command.ts
@@ -4748,7 +4769,8 @@ async function checkEnvironments(loader, named) {
4748
4769
  });
4749
4770
  return problems.length > 0 ? make("fail", `${problems.length} problem(s)`, problems) : make("ok", `${names.length} of ${names.length} exist`);
4750
4771
  } catch (err) {
4751
- return err instanceof MissingTokenError ? make("skip", err.message) : make("fail", errorMessage(err));
4772
+ const noToken = missingTokenReason(err);
4773
+ return noToken !== void 0 ? make("skip", noToken) : make("fail", errorMessage(err));
4752
4774
  }
4753
4775
  }
4754
4776
  // src/commands/doctor-environments/doctor-environments.command.ts
@@ -4852,7 +4874,8 @@ async function checkRow(loader) {
4852
4874
  problems: []
4853
4875
  };
4854
4876
  } catch (err) {
4855
- if (err instanceof MissingTokenError) return skip(err.message);
4877
+ const noToken = missingTokenReason(err);
4878
+ if (noToken !== void 0) return skip(noToken);
4856
4879
  return {
4857
4880
  id: ID,
4858
4881
  title: TITLE,
@@ -4940,16 +4963,26 @@ const doctorNotificationsArgs = (y) => y.option("scope", {
4940
4963
  default: false,
4941
4964
  describe: "Post a test message through every channel's webhook, read it back and remove it (works with --built-only)"
4942
4965
  });
4943
- // src/commands/missing-token/missing-token.ts
4944
- /**
4945
- * Why a provider call could not be tried for want of a token, or undefined when the error is something else. A plugin
4946
- * resolves its token on first use and throws an `AuthError` naming where it looked; the GitHub plugin throws a
4947
- * {@link MissingTokenError}. Both mean "no token", which a deep check reports as a skip, not a failure. The
4948
- * `AuthError` is matched by name because the plugin and the CLI may each hold their own copy of the class.
4949
- */
4950
- function missingTokenReason(err) {
4951
- if (err instanceof MissingTokenError) return err.message;
4952
- if (err instanceof Error && err.name === "AuthError") return err.message;
4966
+ // src/commands/notification-check-rows/notification-check-rows.ts
4967
+ /** A step that could not be tried: the reason is the detail, and it is not a failure. */
4968
+ function skipRow(id, title, reason) {
4969
+ return {
4970
+ id,
4971
+ title,
4972
+ status: "skip",
4973
+ detail: reason,
4974
+ problems: []
4975
+ };
4976
+ }
4977
+ /** A step that held when it has no problems, and failed with one line per problem when it has. */
4978
+ function resultRow(id, title, problems, ok) {
4979
+ return {
4980
+ id,
4981
+ title,
4982
+ status: problems.length === 0 ? "pass" : "fail",
4983
+ detail: problems.length === 0 ? ok : `${problems.length} problem(s)`,
4984
+ problems
4985
+ };
4953
4986
  }
4954
4987
  // src/commands/notifications-sync-roles/plan.ts
4955
4988
  /**
@@ -5576,32 +5609,18 @@ async function runNotificationsSetup(input$1) {
5576
5609
  return report;
5577
5610
  }
5578
5611
  // src/commands/monitoring-feed-checks/monitoring-feed-checks.ts
5579
- const WEBHOOK_ID = "monitoring-feed-webhook";
5580
- const WEBHOOK_TITLE = "monitoring feed webhook exists and has a picture";
5612
+ const WEBHOOK_ID$1 = "monitoring-feed-webhook";
5613
+ const WEBHOOK_TITLE$1 = "monitoring feed webhook exists and has a picture";
5581
5614
  const CHANNEL_ID = "monitoring-alert-channel";
5582
5615
  const CHANNEL_TITLE = "monitoring alert channel posts through the feed webhook";
5583
5616
  const SUBSCRIPTIONS_ID = "monitoring-subscriptions";
5584
5617
  const SUBSCRIPTIONS_TITLE = "monitoring alert channel is subscribed to every check";
5585
- const same$1 = (a, b) => a.toLowerCase() === b.toLowerCase();
5586
- const shown$1 = (s) => sanitizeDetail(s);
5587
- const skip = (id, title, reason) => ({
5588
- id,
5589
- title,
5590
- status: "skip",
5591
- detail: reason,
5592
- problems: []
5593
- });
5594
- const row$3 = (id, title, problems, ok) => ({
5595
- id,
5596
- title,
5597
- status: problems.length === 0 ? "pass" : "fail",
5598
- detail: problems.length === 0 ? ok : `${problems.length} problem(s)`,
5599
- problems
5600
- });
5618
+ const same$2 = (a, b) => a.toLowerCase() === b.toLowerCase();
5619
+ const shown$3 = (s) => sanitizeDetail(s);
5601
5620
  const skipAll = (reason) => [
5602
- skip(WEBHOOK_ID, WEBHOOK_TITLE, reason),
5603
- skip(CHANNEL_ID, CHANNEL_TITLE, reason),
5604
- skip(SUBSCRIPTIONS_ID, SUBSCRIPTIONS_TITLE, reason)
5621
+ skipRow(WEBHOOK_ID$1, WEBHOOK_TITLE$1, reason),
5622
+ skipRow(CHANNEL_ID, CHANNEL_TITLE, reason),
5623
+ skipRow(SUBSCRIPTIONS_ID, SUBSCRIPTIONS_TITLE, reason)
5605
5624
  ];
5606
5625
  /**
5607
5626
  * The steps of `doctor notifications` that check the monitoring provider's feed into Discord: the webhook it posts
@@ -5624,14 +5643,14 @@ async function monitoringFeedChecks(input) {
5624
5643
  let channelSkip;
5625
5644
  for (const { channel, feed } of fed) {
5626
5645
  const names = monitoringFeed(channel.name, feed, monitoring);
5627
- const where = found.channels.find((c) => same$1(c.name, channel.name));
5646
+ const where = found.channels.find((c) => same$2(c.name, channel.name));
5628
5647
  const hookId = where?.webhookIds?.[names.webhook.toLowerCase()];
5629
- const named = where?.webhooks.some((w) => same$1(w, names.webhook)) ?? false;
5630
- const label = `#${shown$1(channel.name)}`;
5648
+ const named = where?.webhooks.some((w) => same$2(w, names.webhook)) ?? false;
5649
+ const label = `#${shown$3(channel.name)}`;
5631
5650
  if (!where) webhookProblems.push(`${label}: no channel to hold the feed webhook`);
5632
- else if (where.webhooksError) webhookProblems.push(`${label}: could not list its webhooks (${shown$1(where.webhooksError)})`);
5633
- else if (!named) webhookProblems.push(`${label}: no webhook named ${shown$1(names.webhook)}`);
5634
- else if (feedAvatarOf(layout, feed, monitoring).length > 0 && !where.webhookAvatars?.some((w) => same$1(w, names.webhook))) webhookProblems.push(`${label}: webhook ${shown$1(names.webhook)} has no picture`);
5651
+ else if (where.webhooksError) webhookProblems.push(`${label}: could not list its webhooks (${shown$3(where.webhooksError)})`);
5652
+ else if (!named) webhookProblems.push(`${label}: no webhook named ${shown$3(names.webhook)}`);
5653
+ else if (feedAvatarOf(layout, feed, monitoring).length > 0 && !where.webhookAvatars?.some((w) => same$2(w, names.webhook))) webhookProblems.push(`${label}: webhook ${shown$3(names.webhook)} has no picture`);
5635
5654
  if (channelSkip !== void 0) continue;
5636
5655
  if (!monitoring.inspectAlertChannel) {
5637
5656
  channelSkip = `the \`${monitoring.providerName}\` provider cannot read its alert channels`;
@@ -5646,21 +5665,21 @@ async function monitoringFeedChecks(input) {
5646
5665
  channelSkip = noToken;
5647
5666
  continue;
5648
5667
  }
5649
- channelProblems.push(`${label}: ${shown$1(describeProviderError(err))}`);
5668
+ channelProblems.push(`${label}: ${shown$3(describeProviderError(err))}`);
5650
5669
  continue;
5651
5670
  }
5652
5671
  if (!state.exists) {
5653
- channelProblems.push(`${label}: missing alert channel ${shown$1(names.name)}`);
5672
+ channelProblems.push(`${label}: missing alert channel ${shown$3(names.name)}`);
5654
5673
  continue;
5655
5674
  }
5656
- if (!state.discord) channelProblems.push(`${label}: ${shown$1(names.name)} is not formatted for Discord`);
5657
- if (!state.webhookId) channelProblems.push(`${label}: ${shown$1(names.name)} does not post to a Discord webhook URL`);
5658
- else if (hookId !== void 0 && state.webhookId !== hookId) channelProblems.push(`${label}: ${shown$1(names.name)} posts through a different webhook than ${shown$1(names.webhook)}`);
5659
- for (const check of state.unsubscribed) subscriptionProblems.push(`${label}: ${shown$1(names.name)} is not subscribed to ${shown$1(check)}`);
5660
- for (const check of state.deactivated) subscriptionProblems.push(`${label}: ${shown$1(names.name)} has ${shown$1(check)} switched off`);
5675
+ if (!state.discord) channelProblems.push(`${label}: ${shown$3(names.name)} is not formatted for Discord`);
5676
+ if (!state.webhookId) channelProblems.push(`${label}: ${shown$3(names.name)} does not post to a Discord webhook URL`);
5677
+ else if (hookId !== void 0 && state.webhookId !== hookId) channelProblems.push(`${label}: ${shown$3(names.name)} posts through a different webhook than ${shown$3(names.webhook)}`);
5678
+ for (const check of state.unsubscribed) subscriptionProblems.push(`${label}: ${shown$3(names.name)} is not subscribed to ${shown$3(check)}`);
5679
+ for (const check of state.deactivated) subscriptionProblems.push(`${label}: ${shown$3(names.name)} has ${shown$3(check)} switched off`);
5661
5680
  }
5662
5681
  const n = fed.length;
5663
- return [row$3(WEBHOOK_ID, WEBHOOK_TITLE, webhookProblems, `${n} of ${n} as declared`), ...channelSkip === void 0 ? [row$3(CHANNEL_ID, CHANNEL_TITLE, channelProblems, `${n} of ${n} as declared`), row$3(SUBSCRIPTIONS_ID, SUBSCRIPTIONS_TITLE, subscriptionProblems, `${n} of ${n} subscribed`)] : [skip(CHANNEL_ID, CHANNEL_TITLE, channelSkip), skip(SUBSCRIPTIONS_ID, SUBSCRIPTIONS_TITLE, channelSkip)]];
5682
+ return [resultRow(WEBHOOK_ID$1, WEBHOOK_TITLE$1, webhookProblems, `${n} of ${n} as declared`), ...channelSkip === void 0 ? [resultRow(CHANNEL_ID, CHANNEL_TITLE, channelProblems, `${n} of ${n} as declared`), resultRow(SUBSCRIPTIONS_ID, SUBSCRIPTIONS_TITLE, subscriptionProblems, `${n} of ${n} subscribed`)] : [skipRow(CHANNEL_ID, CHANNEL_TITLE, channelSkip), skipRow(SUBSCRIPTIONS_ID, SUBSCRIPTIONS_TITLE, channelSkip)]];
5664
5683
  }
5665
5684
  const localRedirectUri = (port) => `http://localhost:${port}/callback`;
5666
5685
  /**
@@ -6166,6 +6185,143 @@ async function runNotificationsLink(input) {
6166
6185
  return refuse(describeProviderError(err), logReason(err));
6167
6186
  }
6168
6187
  }
6188
+ // src/commands/relay-checks/relay-checks.ts
6189
+ /** How long to wait for the Worker before calling it unreachable. */
6190
+ const RELAY_TIMEOUT_MS = 5e3;
6191
+ const ANSWERS_ID = "relay-answers";
6192
+ const ANSWERS_TITLE = "relay Worker answers an unsigned request with 401";
6193
+ const WORKER_ID = "relay-worker";
6194
+ const WORKER_TITLE = "relay Worker is deployed and routed";
6195
+ const BINDINGS_ID = "relay-bindings";
6196
+ const BINDINGS_TITLE = "relay Worker has its webhook and signing secret bound";
6197
+ const WEBHOOK_ID = "relay-feed-webhook";
6198
+ const WEBHOOK_TITLE = "error feed webhook exists and has a picture";
6199
+ const same$1 = (a, b) => a.toLowerCase() === b.toLowerCase();
6200
+ const shown$2 = (s) => sanitizeDetail(s);
6201
+ /** One unsigned `POST` to the Worker, and what the answer says about it. Reads nothing from the response. */
6202
+ async function answers(url, doFetch) {
6203
+ try {
6204
+ const response = await doFetch(url, {
6205
+ method: "POST",
6206
+ redirect: "manual",
6207
+ signal: AbortSignal.timeout(RELAY_TIMEOUT_MS)
6208
+ });
6209
+ if (response.status === 401) return [];
6210
+ if (response.status === 404) return [`${shown$2(url)} answered 404: the Worker is not deployed or has no route`];
6211
+ return [`${shown$2(url)} answered ${response.status}, expected 401 for an unsigned request`];
6212
+ } catch (err) {
6213
+ return [err instanceof Error && err.name === "TimeoutError" ? `${shown$2(url)} gave no answer within ${RELAY_TIMEOUT_MS / 1e3}s` : `${shown$2(url)} could not be reached: ${shown$2(errorMessage(err))}`];
6214
+ }
6215
+ }
6216
+ /**
6217
+ * The steps of `doctor notifications` that check the Comlink relay: the Worker answers an unsigned request with 401,
6218
+ * its script and route are deployed, its webhook and signing secret are bound (names only), and the feed webhook the
6219
+ * relay posts through exists. Read-only: the one request is unsigned, which the Worker rejects before reading it. No
6220
+ * rows when the layout declares no relay. The DNS record is `doctor dns`'s.
6221
+ */
6222
+ async function relayChecks(input) {
6223
+ const { layout } = input;
6224
+ const relay = layout.relay;
6225
+ if (!relay?.host || !wantsRelay(layout)) return [];
6226
+ if (!input.errors) return [
6227
+ skipRow(ANSWERS_ID, ANSWERS_TITLE, input.errorsMissingReason),
6228
+ skipRow(WORKER_ID, WORKER_TITLE, input.errorsMissingReason),
6229
+ skipRow(BINDINGS_ID, BINDINGS_TITLE, input.errorsMissingReason),
6230
+ skipRow(WEBHOOK_ID, WEBHOOK_TITLE, input.errorsMissingReason)
6231
+ ];
6232
+ const source = input.errors.providerName;
6233
+ const rows = [];
6234
+ rows.push(resultRow(ANSWERS_ID, ANSWERS_TITLE, await answers(`https://${relay.host}/${source}`, input.fetch ?? fetch), `https://${shown$2(relay.host)}/${shown$2(source)} answered 401`));
6235
+ const script = relay.script ?? "comlink";
6236
+ const route = `${relay.host}/*`;
6237
+ const skipWorker = (reason) => [skipRow(WORKER_ID, WORKER_TITLE, reason), skipRow(BINDINGS_ID, BINDINGS_TITLE, reason)];
6238
+ if (!input.workers) rows.push(...skipWorker(input.workersMissingReason));
6239
+ else if (!input.workers.inspectScript) rows.push(...skipWorker(`the \`${input.workers.providerName}\` provider cannot read its Workers`));
6240
+ else try {
6241
+ const state = await input.workers.inspectScript(script, relay.host);
6242
+ if (!state.exists) rows.push(resultRow(WORKER_ID, WORKER_TITLE, [`no Worker named ${shown$2(script)}`], ""), skipRow(BINDINGS_ID, BINDINGS_TITLE, `not checked: no Worker named ${shown$2(script)}`));
6243
+ else {
6244
+ const bound = new Set(state.bindingNames.map((n) => n.toUpperCase()));
6245
+ const wanted = [relayWebhookBinding(source), relaySecretBinding(source)];
6246
+ rows.push(resultRow(WORKER_ID, WORKER_TITLE, state.routes.some((r) => same$1(r, route)) ? [] : [`${shown$2(script)} has no route ${shown$2(route)}`], `${shown$2(script)} serves ${shown$2(route)}`), resultRow(BINDINGS_ID, BINDINGS_TITLE, wanted.filter((n) => !bound.has(n)).map((n) => `${n}: not bound`), `${wanted.length} of ${wanted.length} bound`));
6247
+ }
6248
+ } catch (err) {
6249
+ const reason = missingTokenReason(err);
6250
+ rows.push(...reason === void 0 ? [resultRow(WORKER_ID, WORKER_TITLE, [shown$2(describeProviderError(err))], ""), skipRow(BINDINGS_ID, BINDINGS_TITLE, "not checked: could not read the Worker")] : skipWorker(reason));
6251
+ }
6252
+ rows.push(webhookRow(input, source));
6253
+ return rows;
6254
+ }
6255
+ /** The error feed's webhook is on its channel, with a picture when the layout or the provider gives one. */
6256
+ function webhookRow(input, source) {
6257
+ if (!input.found) return skipRow(WEBHOOK_ID, WEBHOOK_TITLE, "not checked: could not read the server");
6258
+ const channel = input.layout.categories.flatMap((cat) => cat.channels ?? []).find((c) => c.feeds?.errors);
6259
+ const feed = channel.feeds.errors;
6260
+ const name = errorsFeedWebhook(feed, { providerName: source });
6261
+ const where = input.found.channels.find((c) => same$1(c.name, channel.name));
6262
+ const label = `#${shown$2(channel.name)}`;
6263
+ const problems = [];
6264
+ if (!where) problems.push(`${label}: no channel to hold the feed webhook`);
6265
+ else if (where.webhooksError) problems.push(`${label}: could not list its webhooks (${shown$2(where.webhooksError)})`);
6266
+ else if (!where.webhooks.some((w) => same$1(w, name))) problems.push(`${label}: no webhook named ${shown$2(name)}`);
6267
+ else if (feedAvatarOf(input.layout, feed).length > 0 && !where.webhookAvatars?.some((w) => same$1(w, name))) problems.push(`${label}: webhook ${shown$2(name)} has no picture`);
6268
+ return resultRow(WEBHOOK_ID, WEBHOOK_TITLE, problems, `${label}: ${shown$2(name)}`);
6269
+ }
6270
+ // src/commands/sentry-relay-checks/sentry-relay-checks.ts
6271
+ const INTEGRATION_ID = "relay-integration";
6272
+ const INTEGRATION_TITLE = "error tracker integration posts to the relay";
6273
+ const RULE_ID = "relay-rule";
6274
+ const RULE_TITLE = "error tracker alert rule is on and sends through the integration";
6275
+ const shown$1 = (s) => sanitizeDetail(s);
6276
+ const bare = (url) => url.replace(/\/+$/, "");
6277
+ /**
6278
+ * The steps of `doctor notifications` that check the error tracker's side of the relay: the integration exists, posts
6279
+ * to the relay Worker and is offered as an alert action, and the alert rule is on each project, enabled and sending
6280
+ * through the integration. Read-only, and the integration's signing secret is never read. No rows unless the layout
6281
+ * declares `relay.errors`, which is what `notifications setup` acts on.
6282
+ */
6283
+ async function sentryRelayChecks(input) {
6284
+ const { layout, errors } = input;
6285
+ const tracker = layout.relay?.errors;
6286
+ if (!tracker || !wantsRelay(layout)) return [];
6287
+ const skipBoth = (reason) => [skipRow(INTEGRATION_ID, INTEGRATION_TITLE, reason), skipRow(RULE_ID, RULE_TITLE, reason)];
6288
+ if (!errors) return skipBoth(input.errorsMissingReason);
6289
+ if (!errors.inspectRelay) return skipBoth(`the \`${errors.providerName}\` provider cannot read its relay`);
6290
+ const name = tracker.integration ?? "Comlink";
6291
+ const rule = tracker.rule ?? "Errors to Discord (Comlink)";
6292
+ let state;
6293
+ try {
6294
+ state = await errors.inspectRelay({
6295
+ name,
6296
+ projects: tracker.projects,
6297
+ rule: { name: rule }
6298
+ });
6299
+ } catch (err) {
6300
+ const noToken = missingTokenReason(err);
6301
+ if (noToken !== void 0) return skipBoth(noToken);
6302
+ return [resultRow(INTEGRATION_ID, INTEGRATION_TITLE, [shown$1(describeProviderError(err))], ""), skipRow(RULE_ID, RULE_TITLE, "not checked: could not read the integration")];
6303
+ }
6304
+ const expected = `https://${layout.relay.host}/${errors.providerName}`;
6305
+ const integrationProblems = [];
6306
+ if (!state.integration) integrationProblems.push(`no integration named ${shown$1(name)}`);
6307
+ else {
6308
+ const posts = state.integration.webhookUrl;
6309
+ if (bare(posts ?? "") !== expected) integrationProblems.push(`${shown$1(name)} posts to ${shown$1(posts ?? "nowhere")}, not ${shown$1(expected)}`);
6310
+ if (!state.integration.alertAction) integrationProblems.push(`${shown$1(name)} is not offered as an alert action`);
6311
+ }
6312
+ const ruleProblems = [];
6313
+ for (const project of tracker.projects) {
6314
+ const found = state.rules.find((r) => r.project === project);
6315
+ if (!found) {
6316
+ ruleProblems.push(`${shown$1(project)}: no rule named ${shown$1(rule)} on it`);
6317
+ continue;
6318
+ }
6319
+ if (!found.enabled) ruleProblems.push(`${shown$1(project)}: ${shown$1(rule)} is disabled`);
6320
+ if (!found.sends) ruleProblems.push(`${shown$1(project)}: ${shown$1(rule)} does not send through ${shown$1(name)}`);
6321
+ }
6322
+ const n = tracker.projects.length;
6323
+ return [resultRow(INTEGRATION_ID, INTEGRATION_TITLE, integrationProblems, `${shown$1(name)} posts to ${shown$1(expected)}`), resultRow(RULE_ID, RULE_TITLE, ruleProblems, n === 0 ? "none declared" : `${n} of ${n} projects`)];
6324
+ }
6169
6325
  // src/commands/doctor-notifications/doctor-notifications.ts
6170
6326
  /**
6171
6327
  * `holocron doctor notifications` -- compare the layout a provider
@@ -6649,6 +6805,20 @@ async function runDoctorNotifications(input) {
6649
6805
  missingReason: whyMissing(loader, "monitoring", "no `monitoring` provider is configured"),
6650
6806
  found
6651
6807
  }));
6808
+ checks.push(...await relayChecks({
6809
+ layout,
6810
+ errors: loader.has("errors") ? loader.get("errors") : void 0,
6811
+ errorsMissingReason: whyMissing(loader, "errors", "no `errors` provider is configured"),
6812
+ workers: loader.has("workers") ? loader.get("workers") : void 0,
6813
+ workersMissingReason: whyMissing(loader, "workers", "no `workers` provider is configured"),
6814
+ found,
6815
+ ...input.fetch ? { fetch: input.fetch } : {}
6816
+ }));
6817
+ checks.push(...await sentryRelayChecks({
6818
+ layout,
6819
+ errors: loader.has("errors") ? loader.get("errors") : void 0,
6820
+ errorsMissingReason: whyMissing(loader, "errors", "no `errors` provider is configured")
6821
+ }));
6652
6822
  const withHook = (layout.categories ?? []).flatMap((cat) => (cat.channels ?? []).filter((c) => c.webhook).map((channel) => ({
6653
6823
  cat,
6654
6824
  channel
@@ -7201,7 +7371,8 @@ async function runDoctorRepo(input) {
7201
7371
  try {
7202
7372
  rows.push(row$2(check, await check.run(source)));
7203
7373
  } catch (err) {
7204
- if (err instanceof MissingTokenError) rows.push(row$2(check, { skip: err.message }));
7374
+ const noToken = missingTokenReason(err);
7375
+ if (noToken !== void 0) rows.push(row$2(check, { skip: noToken }));
7205
7376
  else rows.push({
7206
7377
  id: check.id,
7207
7378
  title: check.title,
@@ -7349,7 +7520,7 @@ async function syncedSecrets(entries, vault) {
7349
7520
  names: Object.keys(await vault.readEnvironment(entry.environment))
7350
7521
  });
7351
7522
  } catch (err) {
7352
- skip(err instanceof MissingTokenError ? err.message : `could not read vault environment ${entry.environment}: ${describeProviderError(err)}`);
7523
+ skip(missingTokenReason(err) ?? `could not read vault environment ${entry.environment}: ${describeProviderError(err)}`);
7353
7524
  }
7354
7525
  }
7355
7526
  return {
@@ -7488,11 +7659,12 @@ async function checkScope(secrets, check) {
7488
7659
  problems: []
7489
7660
  };
7490
7661
  } catch (err) {
7491
- if (err instanceof MissingTokenError) return {
7662
+ const noToken = missingTokenReason(err);
7663
+ if (noToken !== void 0) return {
7492
7664
  id,
7493
7665
  title,
7494
7666
  status: "skip",
7495
- detail: err.message,
7667
+ detail: noToken,
7496
7668
  problems: []
7497
7669
  };
7498
7670
  return {
@@ -7713,7 +7885,8 @@ async function runDoctorVariables(input) {
7713
7885
  for (const check of checks) try {
7714
7886
  rows.push(row(check, await check.run(source)));
7715
7887
  } catch (err) {
7716
- if (err instanceof MissingTokenError) rows.push(row(check, { skip: err.message }));
7888
+ const noToken = missingTokenReason(err);
7889
+ if (noToken !== void 0) rows.push(row(check, { skip: noToken }));
7717
7890
  else rows.push({
7718
7891
  id: check.id,
7719
7892
  title: check.title,
@@ -7974,14 +8147,15 @@ async function outcomeOf(check, input) {
7974
8147
  });
7975
8148
  } catch (err) {
7976
8149
  if (err instanceof WorkspaceContextError) throw err;
7977
- if (err instanceof MissingTokenError) return {
8150
+ const noToken = missingTokenReason(err);
8151
+ if (noToken !== void 0) return {
7978
8152
  status: "skip",
7979
8153
  summary: {
7980
8154
  ok: 0,
7981
8155
  fail: 0,
7982
8156
  skip: 1
7983
8157
  },
7984
- reason: err.message
8158
+ reason: noToken
7985
8159
  };
7986
8160
  return {
7987
8161
  status: "fail",
@@ -11886,6 +12060,9 @@ const probeArgs = (y) => y.positional("provider", {
11886
12060
  type: "string",
11887
12061
  array: true,
11888
12062
  describe: "Arguments for the probe (`probe deps who <name>`)"
12063
+ }).option("lcov", {
12064
+ type: "string",
12065
+ describe: "Also write the coverage a `docs` probe measures to this lcov file (relative to the repo root)"
11889
12066
  }).option("yes", {
11890
12067
  type: "boolean",
11891
12068
  default: false,
@@ -12184,40 +12361,6 @@ function collectEdges(root, dirs) {
12184
12361
  inRepo
12185
12362
  };
12186
12363
  }
12187
- // src/commands/probe/deps/parse-catalogs.ts
12188
- /** Parse the `catalog:` and `catalogs:` blocks of `pnpm-workspace.yaml` (the generated, flat format). */
12189
- function parseCatalogs(text) {
12190
- const catalogs = { default: {} };
12191
- let current = null;
12192
- let inCatalogs = false;
12193
- for (const raw of text.split("\n")) {
12194
- if (raw.trim() === "" || raw.trimStart().startsWith("#")) continue;
12195
- if (/^catalog:\s*$/.test(raw)) {
12196
- current = "default";
12197
- inCatalogs = false;
12198
- continue;
12199
- }
12200
- if (/^catalogs:\s*$/.test(raw)) {
12201
- current = null;
12202
- inCatalogs = true;
12203
- continue;
12204
- }
12205
- if (/^\S/.test(raw)) {
12206
- current = null;
12207
- inCatalogs = false;
12208
- continue;
12209
- }
12210
- const named = inCatalogs ? raw.match(/^ {2}([A-Za-z0-9_-]+):\s*$/) : null;
12211
- if (named?.[1]) {
12212
- current = named[1];
12213
- catalogs[current] ??= {};
12214
- continue;
12215
- }
12216
- const entry = raw.match(/^\s+("[^"]+"|[^\s:][^:]*?):\s*(.+?)\s*$/);
12217
- if (entry?.[1] && entry[2] && current) (catalogs[current] ??= {})[entry[1].replace(/^"|"$/g, "")] = entry[2].replace(/^"|"$/g, "");
12218
- }
12219
- return catalogs;
12220
- }
12221
12364
  // src/commands/probe/deps/pick-range.ts
12222
12365
  /** `^1.2.3`, `~1.2.3`, `1.2.3`, `>=1.2.3` -> [1, 2, 3]; null for anything else. */
12223
12366
  function minVersion(range) {
@@ -12661,6 +12804,26 @@ function realDiff(repoRoot) {
12661
12804
  };
12662
12805
  /* v8 ignore stop */
12663
12806
  }
12807
+ /** Writes the report `--lcov <path>` asks for, and says so; a dry run only says what it would write. */
12808
+ function writeLcov(ctx, repoRoot, packages) {
12809
+ if (!ctx.lcov) return;
12810
+ if (ctx.dryRun) {
12811
+ ctx.say({
12812
+ status: "info",
12813
+ label: "lcov",
12814
+ detail: `would write ${ctx.lcov}`
12815
+ });
12816
+ return;
12817
+ }
12818
+ const file = resolve(repoRoot, ctx.lcov);
12819
+ mkdirSync(dirname(file), { recursive: true });
12820
+ writeFileSync(file, toLcov(packages));
12821
+ ctx.say({
12822
+ status: "info",
12823
+ label: "lcov",
12824
+ detail: `wrote ${ctx.lcov}`
12825
+ });
12826
+ }
12664
12827
  function percent(documented, total) {
12665
12828
  return `${total === 0 ? 100 : Math.round(100 * documented / total)}%`;
12666
12829
  }
@@ -12691,9 +12854,13 @@ function summarise$1(ctx, packages) {
12691
12854
  * `docs coverage`: how much of each public package's exported API has a doc comment (functions, classes, interfaces,
12692
12855
  * types, constants and their public members), measured with the repo's TypeDoc. `docs lcov` writes the same
12693
12856
  * numbers as `coverage/docs.lcov`, for a coverage service to read. `docs patch` fails for each export a PR adds or
12694
- * changes without a doc comment, which is the check CI runs.
12857
+ * changes without a doc comment, which is the check CI runs. `docs coverage` and `docs patch` also write that
12858
+ * report wherever `--lcov <path>` says, from the same measurement, so CI gates and uploads with one command.
12859
+ *
12860
+ * `mode` is the repo's `repoValidation.docsCoverage`, and only `docs patch` follows it: `off` skips it (nothing is
12861
+ * measured or written), `warn` reports an undocumented export without failing, `required` fails for it.
12695
12862
  */
12696
- function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = realDiff(repoRoot)) {
12863
+ function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = realDiff(repoRoot), mode = "required") {
12697
12864
  const measure = () => measureDocsCoverage({
12698
12865
  repoRoot,
12699
12866
  typedoc
@@ -12703,27 +12870,40 @@ function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = rea
12703
12870
  summary: "Show how much of each package's exported API has a doc comment.",
12704
12871
  writes: false,
12705
12872
  async run(ctx) {
12706
- summarise$1(ctx, measure());
12873
+ const packages = measure();
12874
+ writeLcov(ctx, repoRoot, packages);
12875
+ summarise$1(ctx, packages);
12707
12876
  }
12708
12877
  },
12709
12878
  patch: {
12710
12879
  summary: "Fail for each export a PR adds or changes that has no doc comment (against BASE_SHA).",
12711
12880
  writes: false,
12712
12881
  async run(ctx) {
12882
+ if (mode === "off") {
12883
+ ctx.say({
12884
+ status: "info",
12885
+ label: "docs patch",
12886
+ detail: "off in this repo's config (repoValidation.docsCoverage)"
12887
+ });
12888
+ return;
12889
+ }
12713
12890
  const added = addedLines(diff());
12714
12891
  const touched = (dir) => [...added.keys()].some((file) => file.startsWith(`${dir}/`));
12715
- const missing = measureDocsCoverage({
12892
+ const packages = measureDocsCoverage({
12716
12893
  repoRoot,
12717
12894
  typedoc,
12718
- only: touched
12719
- }).flatMap(({ symbols }) => symbols).filter((s) => added.get(s.file)?.has(s.line));
12895
+ ...ctx.lcov ? {} : { only: touched }
12896
+ });
12897
+ writeLcov(ctx, repoRoot, packages);
12898
+ const missing = packages.flatMap(({ symbols }) => symbols).filter((s) => added.get(s.file)?.has(s.line));
12720
12899
  const undocumented = missing.filter((s) => !s.documented);
12721
12900
  ctx.say({
12722
12901
  status: "heading",
12723
12902
  label: "Exports this PR adds or changes"
12724
12903
  });
12904
+ const level = mode === "warn" ? "info" : "fail";
12725
12905
  for (const { file, line, kind, name } of undocumented) ctx.say({
12726
- status: "fail",
12906
+ status: level,
12727
12907
  label: `${file}:${line}`,
12728
12908
  detail: `${kind} ${name} has no doc comment`
12729
12909
  });
@@ -12732,6 +12912,11 @@ function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = rea
12732
12912
  label: `${missing.length} checked`,
12733
12913
  detail: "every one has a doc comment"
12734
12914
  });
12915
+ else if (mode === "warn") ctx.say({
12916
+ status: "info",
12917
+ label: `${undocumented.length} without a doc comment`,
12918
+ detail: "warn: not failing (repoValidation.docsCoverage)"
12919
+ });
12735
12920
  }
12736
12921
  },
12737
12922
  lcov: {
@@ -12870,7 +13055,7 @@ async function generateConfigFiles(input) {
12870
13055
  const content = createAstromech({
12871
13056
  cwd: input.repoRoot,
12872
13057
  logger: input.logger ?? getLogger()
12873
- }).codecovConfig(existing);
13058
+ }).codecovConfig(existing, { docsCoverage: config.repoValidation?.docsCoverage ?? "off" });
12874
13059
  const packageCount = readWorkspacePackages(input.repoRoot).length;
12875
13060
  entries.push(file("codecov.yml", content, packageCount > 0 ? `${packageCount} components` : "no components"));
12876
13061
  } catch (error) {
@@ -13321,6 +13506,7 @@ async function runProbe(input) {
13321
13506
  const ctx = {
13322
13507
  dryRun: input.dryRun,
13323
13508
  args: input.args ?? [],
13509
+ ...input.lcov ? { lcov: input.lcov } : {},
13324
13510
  say: emit,
13325
13511
  secret: (value) => {
13326
13512
  if (value) secrets.add(value);
@@ -13383,7 +13569,7 @@ async function runProbeCommand(input) {
13383
13569
  });
13384
13570
  groups.set(CORE_PROVIDER, coreProbes(loader, /* @__PURE__ */ new Map([[COMLINK_PROVIDER, comlink]])));
13385
13571
  groups.set(COMLINK_PROVIDER, comlink);
13386
- groups.set(DOCS_PROVIDER, docsCoverageProbes(input.context.repoRoot, input.typedoc));
13572
+ groups.set(DOCS_PROVIDER, docsCoverageProbes(input.context.repoRoot, input.typedoc, void 0, input.loaded.resolved.repoValidation?.docsCoverage ?? "off"));
13387
13573
  groups.set(DEPS_PROVIDER, depsProbes(input.context.repoRoot, print));
13388
13574
  groups.set(GENERATED_PROVIDER, generatedProbes(input.loaded, input.context.repoRoot));
13389
13575
  if (!input.provider) {
@@ -13411,6 +13597,7 @@ async function runProbeCommand(input) {
13411
13597
  provider: input.provider,
13412
13598
  probeName: input.probe,
13413
13599
  args: input.args ?? [],
13600
+ ...input.lcov ? { lcov: input.lcov } : {},
13414
13601
  probe,
13415
13602
  dryRun: input.dryRun ?? false,
13416
13603
  yes: input.yes ?? false,
@@ -13442,6 +13629,7 @@ const probeCommand = {
13442
13629
  ...argv.provider ? { provider: argv.provider } : {},
13443
13630
  ...argv.probe ? { probe: argv.probe } : {},
13444
13631
  ...argv.args?.length ? { args: argv.args.map(String) } : {},
13632
+ ...argv.lcov ? { lcov: argv.lcov } : {},
13445
13633
  dryRun: argv.dryRun,
13446
13634
  yes: argv.yes,
13447
13635
  ...process.stdin.isTTY ? { pick: (groups) => launchMenu(buildProbeMenuEntries(groups), argv, "probe — choose a provider:", "Run `holocron probe` to list the probes.", ["probe"]) } : {}
@@ -16291,50 +16479,13 @@ const fetchLatestFromNpm = async (pkg) => {
16291
16479
  return null;
16292
16480
  }
16293
16481
  };
16294
- /** `a > b` for `x.y.z` release versions (prerelease tags are ignored). */
16295
- function gt(a, b) {
16296
- const pa = a.split(".").map((n) => parseInt(n, 10));
16297
- const pb = b.split(".").map((n) => parseInt(n, 10));
16298
- for (let i = 0; i < 3; i++) {
16299
- const x = pa[i] ?? 0;
16300
- const y = pb[i] ?? 0;
16301
- if (x !== y) return x > y;
16302
- }
16303
- return false;
16304
- }
16305
- const CATALOG_LINE = /^(\s*['"]?)(@theholocron\/[a-z0-9-]+)(['"]?\s*:\s*['"]?)([~^]?)(\d+\.\d+\.\d+[\w.-]*)(['"]?\s*)$/;
16482
+ const HOLOCRON_PACKAGE = /^@theholocron\/[a-z0-9-]+$/;
16306
16483
  /**
16307
16484
  * Rewrite every `@theholocron/*` pin in a `pnpm-workspace.yaml` to `latest`,
16308
16485
  * keeping the range prefix. `latest` is looked up once per package.
16309
16486
  */
16310
- async function bumpCatalogs(content, fetchLatest) {
16311
- const lines = content.split("\n");
16312
- const wanted = /* @__PURE__ */ new Set();
16313
- for (const line of lines) {
16314
- const m = CATALOG_LINE.exec(line);
16315
- if (m) wanted.add(m[2]);
16316
- }
16317
- const latest = /* @__PURE__ */ new Map();
16318
- await Promise.all([...wanted].map(async (pkg) => {
16319
- latest.set(pkg, await fetchLatest(pkg));
16320
- }));
16321
- const bumps = [];
16322
- return {
16323
- content: lines.map((line) => {
16324
- const m = CATALOG_LINE.exec(line);
16325
- if (!m) return line;
16326
- const [, pre, pkg, mid, prefix, current, post] = m;
16327
- const next = latest.get(pkg);
16328
- if (!next || next === current || !gt(next, current)) return line;
16329
- bumps.push({
16330
- pkg,
16331
- from: current,
16332
- to: next
16333
- });
16334
- return `${pre}${pkg}${mid}${prefix}${next}${post}`;
16335
- }).join("\n"),
16336
- bumps
16337
- };
16487
+ function bumpCatalogs(content, fetchLatest) {
16488
+ return bumpCatalogPins(content, fetchLatest, { include: (pkg) => HOLOCRON_PACKAGE.test(pkg) });
16338
16489
  }
16339
16490
  /** True if the file still uses the 7.x preset shape. */
16340
16491
  function isLegacyConfig(content) {