@theholocron/cli 5.0.0-alpha.277 → 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/README.md CHANGED
@@ -298,6 +298,19 @@ branch so Sentinel validates against what's actually being developed, then
298
298
  change it back once that branch merges to `main` for a stable cut and stops
299
299
  being the active branch.
300
300
 
301
+ ### Doc-comment coverage
302
+
303
+ ```ts
304
+ export default defineConfig({
305
+ repoValidation: { docsCoverage: "required" }, // "off" (default) | "warn" | "required"
306
+ });
307
+ ```
308
+
309
+ Controls `holocron probe docs patch` (skipped, reports without failing, or fails for an export a PR adds or changes
310
+ without a doc comment) and whether `holocron repo setup` adds the `documentation` flag and its statuses to
311
+ `codecov.yml`, informational for `"warn"`. It never touches the required checks. See the
312
+ [config docs](https://docs.theholocron.dev/holocron/config/#doc-comment-coverage).
313
+
301
314
  ### Git hooks
302
315
 
303
316
  ```ts
@@ -541,23 +554,23 @@ A `notifications` provider can declare a whole server in `holocron.config.ts`
541
554
  pinned messages, onboarding, the bot application) and the CLI applies and checks it. The
542
555
  commands and the config are provider-neutral; Discord is the first provider.
543
556
 
544
- | Command | What it does |
545
- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
546
- | `holocron notifications setup` | Applies the layout; looks everything up by name first, so a re-run changes nothing that matches |
547
- | `holocron notifications channel add <name>` | Creates one channel (optionally with a webhook whose URL is stored as a secret) |
548
- | `holocron notifications create-server --name <n> --owner <id>` | Creates the server the layout describes, writes its id into the config, applies the layout, invites the owner, waits for them to join and hands the server over (`--resume` finishes an interrupted hand-over; `--force` allows a second server) |
549
- | `holocron notifications link` | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept) |
550
- | `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
551
- | `holocron doctor notifications [--built-only] [--deliver]` | Step by step: does the server match the layout, do the secrets exist, and does a person (not the bot) own it. A full run also leaves one `🧪 test:` post in the layout's `testChannel`; `--built-only` posts nothing; `--deliver` posts to every channel and removes each post. It also reads the Checkly feed (webhook, alert channel, subscriptions) and the Comlink relay (Worker, route, bindings, the tracker's integration and rule), posting nothing, so `--built-only` keeps those steps |
552
- | `holocron doctor variables` | Do the Actions variables `repo.variables` declares exist, with those values (and, for the organization's, that visibility)? One row for the repository and one for the organization, each only when declared. Read-only. An undeclared variable counts only with `prune`; a scope that cannot be read (no provider, no org token) is a skip, not a failure |
553
- | `holocron doctor environments` | Do the deployment environments exist? The ones `repo setup` creates (`staging`, `production`, when an `environments` provider is configured) plus every environment `repo.secrets.environments` names. One row. A missing one fails; an extra one is never a problem; no provider with some named is a skip |
554
- | `holocron doctor repo` | Do the repository settings `repo setup` writes match the config? One row per group the config declares: description and homepage, default branch and merge settings, topics, custom properties, team access, branch protection; labels and security settings are always checked. Read-only. Reads through optional `Source` methods (`getRepoInfo`, `getProperties`, `listLabels`, `listTeamAccess`, `getRulesetDetail`, `getSecurity`); a group that cannot be read is a skip, not a failure |
555
- | `holocron doctor dns` | Do the DNS records the config makes setup write exist, pointing where they should? The preview domain's apex and wildcard CNAMEs (Cloudflare), the docs host a wiki provider asks for, and the relay Worker's proxied placeholder; one row per zone. A missing record, another target or a missing proxy fails; an extra record never does. A record `ensureCustomDomain()` returns is not checked, because asking for it creates the domain |
556
- | `holocron doctor monitoring` | Do the checks the `monitoring` provider declares exist in its account, matched by name, with the URL, method and (when stated) frequency, locations, activated, should-fail, body and assertions the config sets? One row. A check in the account that is not declared is never a problem. A provider that cannot list its checks, failed to load or has no token is a skip |
557
- | `holocron doctor secrets` | Do the secrets the config says must exist (`repo.secrets`, plus the notification layout's webhook and role secrets and the Chromatic token) exist? One row for the repository, the organization and each environment, each only when something is expected there. Names only; an undeclared secret is never a problem. A scope that cannot be read is a skip |
558
- | `holocron doctor tokens` | For every token a configured plugin lists (every plugin that resolves one: GitHub's nine, Discord's three, Sentry's two, ...), looked up as the plugin does (its env var, the vendor's, then keyring) and verified with its `verifyToken`: set and accepted is ok (with how long is left, when the token expires), set and rejected fails, a token with 7 days or fewer left fails with `expires in N days: renew it`, not set is a skip. No token is printed. What a token may do is not checked, because GitHub does not return a fine-grained token's permissions |
559
- | `holocron doctor --all` | Runs every deep check (`doctor notifications`, `doctor variables`, ...) and prints one row each, then `N ok, N fail, N skipped` counted in checks. Exits 1 when any check failed. A check that cannot run (no provider, no token) is a skip with the reason. Read-only: notifications runs as `--built-only`, so it posts nothing |
560
- | `holocron probe [<provider> [<probe>]] [--dry-run] [--yes]` | Poke a live provider on purpose: list the probes, inspect something, or run a proof that cleans up after itself. Plugins offer the probes; nothing secret is printed; one that changes things asks first |
557
+ | Command | What it does |
558
+ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
559
+ | `holocron notifications setup` | Applies the layout; looks everything up by name first, so a re-run changes nothing that matches |
560
+ | `holocron notifications channel add <name>` | Creates one channel (optionally with a webhook whose URL is stored as a secret) |
561
+ | `holocron notifications create-server --name <n> --owner <id>` | Creates the server the layout describes, writes its id into the config, applies the layout, invites the owner, waits for them to join and hands the server over (`--resume` finishes an interrupted hand-over; `--force` allows a second server) |
562
+ | `holocron notifications link` | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept) |
563
+ | `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
564
+ | `holocron doctor notifications [--built-only] [--deliver]` | Step by step: does the server match the layout, do the secrets exist, and does a person (not the bot) own it. A full run also leaves one `🧪 test:` post in the layout's `testChannel`; `--built-only` posts nothing; `--deliver` posts to every channel and removes each post. It also reads the Checkly feed (webhook, alert channel, subscriptions) and the Comlink relay (Worker, route, bindings, the tracker's integration and rule), posting nothing, so `--built-only` keeps those steps |
565
+ | `holocron doctor variables` | Do the Actions variables `repo.variables` declares exist, with those values (and, for the organization's, that visibility)? One row for the repository and one for the organization, each only when declared. Read-only. An undeclared variable counts only with `prune`; a scope that cannot be read (no provider, no org token) is a skip, not a failure |
566
+ | `holocron doctor environments` | Do the deployment environments exist? The ones `repo setup` creates (`staging`, `production`, when an `environments` provider is configured) plus every environment `repo.secrets.environments` names. One row. A missing one fails; an extra one is never a problem; no provider with some named is a skip |
567
+ | `holocron doctor repo` | Do the repository settings `repo setup` writes match the config? One row per group the config declares: description and homepage, default branch and merge settings, topics, custom properties, team access, branch protection; labels and security settings are always checked. Read-only. Reads through optional `Source` methods (`getRepoInfo`, `getProperties`, `listLabels`, `listTeamAccess`, `getRulesetDetail`, `getSecurity`); a group that cannot be read is a skip, not a failure |
568
+ | `holocron doctor dns` | Do the DNS records the config makes setup write exist, pointing where they should? The preview domain's apex and wildcard CNAMEs (Cloudflare), the docs host a wiki provider asks for, and the relay Worker's proxied placeholder; one row per zone. A missing record, another target or a missing proxy fails; an extra record never does. A record `ensureCustomDomain()` returns is not checked, because asking for it creates the domain |
569
+ | `holocron doctor monitoring` | Do the checks the `monitoring` provider declares exist in its account, matched by name, with the URL, method and (when stated) frequency, locations, activated, should-fail, body and assertions the config sets? One row. A check in the account that is not declared is never a problem. A provider that cannot list its checks, failed to load or has no token is a skip |
570
+ | `holocron doctor secrets` | Do the secrets the config says must exist (`repo.secrets`, plus the notification layout's webhook and role secrets and the Chromatic token) exist? One row for the repository, the organization and each environment, each only when something is expected there. Names only; an undeclared secret is never a problem. A scope that cannot be read is a skip |
571
+ | `holocron doctor tokens` | For every token a configured plugin lists (every plugin that resolves one: GitHub's nine, Discord's three, Sentry's two, ...), looked up as the plugin does (its env var, the vendor's, then keyring) and verified with its `verifyToken`: set and accepted is ok (with how long is left, when the token expires), set and rejected fails, a token with 7 days or fewer left fails with `expires in N days: renew it`, not set is a skip. No token is printed. What a token may do is not checked, because GitHub does not return a fine-grained token's permissions |
572
+ | `holocron doctor --all` | Runs every deep check (`doctor notifications`, `doctor variables`, ...) and prints one row each, then `N ok, N fail, N skipped` counted in checks. Exits 1 when any check failed. A check that cannot run (no provider, no token) is a skip with the reason. Read-only: notifications runs as `--built-only`, so it posts nothing |
573
+ | `holocron probe [<provider> [<probe>]] [--dry-run] [--yes] [--lcov <path>]` | Poke a live provider on purpose: list the probes, inspect something, or run a proof that cleans up after itself. Plugins offer the probes; nothing secret is printed; one that changes things asks first |
561
574
 
562
575
  Channels fed by another service are declared with `feeds` on the channel: `{ name: "uptime", webhook: true, feeds: { monitoring: true } }` (the object form `{ name?, webhook?, avatar? }` overrides the alert channel's name, default `Message to #<channel>`, the dedicated webhook's name, default the provider's, and gives that webhook a picture, a file path or `https://` URL, or `{ url, image }` (the URL is tried first, the file in the repo is the fallback), else the provider's own icon (`Monitoring.icon`, a URL and an embedded `data:` image; Checkly provides one), else the layout's `webhookAvatar`, else the layout's `webhookAvatar`). `setup` gives the channel a dedicated webhook and hands its URL straight to the `monitoring` provider through `Monitoring.ensureAlertChannel({ name, format: "discord", url? })`, which finds an alert channel of that name or creates one and subscribes every check; the URL is never stored as a secret. It needs a `monitoring` provider that implements `ensureAlertChannel` (Checkly does). Two feeds may not share an alert channel name, and a feed's webhook may not share the channel's own webhook name (compared without regard to case).
563
576
 
package/dist/cli.mjs CHANGED
@@ -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,
@@ -12051,6 +12060,9 @@ const probeArgs = (y) => y.positional("provider", {
12051
12060
  type: "string",
12052
12061
  array: true,
12053
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)"
12054
12066
  }).option("yes", {
12055
12067
  type: "boolean",
12056
12068
  default: false,
@@ -12792,6 +12804,26 @@ function realDiff(repoRoot) {
12792
12804
  };
12793
12805
  /* v8 ignore stop */
12794
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
+ }
12795
12827
  function percent(documented, total) {
12796
12828
  return `${total === 0 ? 100 : Math.round(100 * documented / total)}%`;
12797
12829
  }
@@ -12822,9 +12854,13 @@ function summarise$1(ctx, packages) {
12822
12854
  * `docs coverage`: how much of each public package's exported API has a doc comment (functions, classes, interfaces,
12823
12855
  * types, constants and their public members), measured with the repo's TypeDoc. `docs lcov` writes the same
12824
12856
  * numbers as `coverage/docs.lcov`, for a coverage service to read. `docs patch` fails for each export a PR adds or
12825
- * 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.
12826
12862
  */
12827
- function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = realDiff(repoRoot)) {
12863
+ function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = realDiff(repoRoot), mode = "required") {
12828
12864
  const measure = () => measureDocsCoverage({
12829
12865
  repoRoot,
12830
12866
  typedoc
@@ -12834,27 +12870,40 @@ function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = rea
12834
12870
  summary: "Show how much of each package's exported API has a doc comment.",
12835
12871
  writes: false,
12836
12872
  async run(ctx) {
12837
- summarise$1(ctx, measure());
12873
+ const packages = measure();
12874
+ writeLcov(ctx, repoRoot, packages);
12875
+ summarise$1(ctx, packages);
12838
12876
  }
12839
12877
  },
12840
12878
  patch: {
12841
12879
  summary: "Fail for each export a PR adds or changes that has no doc comment (against BASE_SHA).",
12842
12880
  writes: false,
12843
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
+ }
12844
12890
  const added = addedLines(diff());
12845
12891
  const touched = (dir) => [...added.keys()].some((file) => file.startsWith(`${dir}/`));
12846
- const missing = measureDocsCoverage({
12892
+ const packages = measureDocsCoverage({
12847
12893
  repoRoot,
12848
12894
  typedoc,
12849
- only: touched
12850
- }).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));
12851
12899
  const undocumented = missing.filter((s) => !s.documented);
12852
12900
  ctx.say({
12853
12901
  status: "heading",
12854
12902
  label: "Exports this PR adds or changes"
12855
12903
  });
12904
+ const level = mode === "warn" ? "info" : "fail";
12856
12905
  for (const { file, line, kind, name } of undocumented) ctx.say({
12857
- status: "fail",
12906
+ status: level,
12858
12907
  label: `${file}:${line}`,
12859
12908
  detail: `${kind} ${name} has no doc comment`
12860
12909
  });
@@ -12863,6 +12912,11 @@ function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = rea
12863
12912
  label: `${missing.length} checked`,
12864
12913
  detail: "every one has a doc comment"
12865
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
+ });
12866
12920
  }
12867
12921
  },
12868
12922
  lcov: {
@@ -13001,7 +13055,7 @@ async function generateConfigFiles(input) {
13001
13055
  const content = createAstromech({
13002
13056
  cwd: input.repoRoot,
13003
13057
  logger: input.logger ?? getLogger()
13004
- }).codecovConfig(existing);
13058
+ }).codecovConfig(existing, { docsCoverage: config.repoValidation?.docsCoverage ?? "off" });
13005
13059
  const packageCount = readWorkspacePackages(input.repoRoot).length;
13006
13060
  entries.push(file("codecov.yml", content, packageCount > 0 ? `${packageCount} components` : "no components"));
13007
13061
  } catch (error) {
@@ -13452,6 +13506,7 @@ async function runProbe(input) {
13452
13506
  const ctx = {
13453
13507
  dryRun: input.dryRun,
13454
13508
  args: input.args ?? [],
13509
+ ...input.lcov ? { lcov: input.lcov } : {},
13455
13510
  say: emit,
13456
13511
  secret: (value) => {
13457
13512
  if (value) secrets.add(value);
@@ -13514,7 +13569,7 @@ async function runProbeCommand(input) {
13514
13569
  });
13515
13570
  groups.set(CORE_PROVIDER, coreProbes(loader, /* @__PURE__ */ new Map([[COMLINK_PROVIDER, comlink]])));
13516
13571
  groups.set(COMLINK_PROVIDER, comlink);
13517
- 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"));
13518
13573
  groups.set(DEPS_PROVIDER, depsProbes(input.context.repoRoot, print));
13519
13574
  groups.set(GENERATED_PROVIDER, generatedProbes(input.loaded, input.context.repoRoot));
13520
13575
  if (!input.provider) {
@@ -13542,6 +13597,7 @@ async function runProbeCommand(input) {
13542
13597
  provider: input.provider,
13543
13598
  probeName: input.probe,
13544
13599
  args: input.args ?? [],
13600
+ ...input.lcov ? { lcov: input.lcov } : {},
13545
13601
  probe,
13546
13602
  dryRun: input.dryRun ?? false,
13547
13603
  yes: input.yes ?? false,
@@ -13573,6 +13629,7 @@ const probeCommand = {
13573
13629
  ...argv.provider ? { provider: argv.provider } : {},
13574
13630
  ...argv.probe ? { probe: argv.probe } : {},
13575
13631
  ...argv.args?.length ? { args: argv.args.map(String) } : {},
13632
+ ...argv.lcov ? { lcov: argv.lcov } : {},
13576
13633
  dryRun: argv.dryRun,
13577
13634
  yes: argv.yes,
13578
13635
  ...process.stdin.isTTY ? { pick: (groups) => launchMenu(buildProbeMenuEntries(groups), argv, "probe — choose a provider:", "Run `holocron probe` to list the probes.", ["probe"]) } : {}