@theholocron/cli 5.0.0-alpha.277 → 5.0.0-alpha.279
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 +30 -17
- package/dist/cli.mjs +277 -19
- package/dist/cli.mjs.map +1 -1
- package/dist/{compose-8k8KP396.mjs → compose-DxOjvMVt.mjs} +9 -0
- package/dist/{index-dMk1XHFO.d.mts → index-B59MneN-.d.mts} +18 -2
- package/dist/{index-D_HJGtOY.d.mts → index-aQ7iGTl7.d.mts} +315 -2
- package/dist/index.d.mts +8 -3
- package/dist/index.mjs +1 -1
- package/dist/plugin/capabilities.d.mts +1 -1
- package/dist/plugin/capabilities.mjs +23 -0
- package/dist/presets.d.mts +1 -1
- package/dist/presets.mjs +1 -1
- package/package.json +14 -14
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
|
|
545
|
-
|
|
|
546
|
-
| `holocron notifications setup`
|
|
547
|
-
| `holocron notifications channel add <name>`
|
|
548
|
-
| `holocron notifications create-server --name <n> --owner <id>`
|
|
549
|
-
| `holocron notifications link`
|
|
550
|
-
| `holocron notifications sync-roles`
|
|
551
|
-
| `holocron doctor notifications [--built-only] [--deliver]`
|
|
552
|
-
| `holocron doctor variables`
|
|
553
|
-
| `holocron doctor environments`
|
|
554
|
-
| `holocron doctor repo`
|
|
555
|
-
| `holocron doctor dns`
|
|
556
|
-
| `holocron doctor monitoring`
|
|
557
|
-
| `holocron doctor secrets`
|
|
558
|
-
| `holocron doctor tokens`
|
|
559
|
-
| `holocron doctor --all`
|
|
560
|
-
| `holocron probe [<provider> [<probe>]] [--dry-run] [--yes]`
|
|
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
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import { createRequire } from "node:module";
|
|
3
|
-
import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
|
|
3
|
+
import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
|
|
4
4
|
import { LOG_LEVELS, NoopAnalyticsSink, NoopErrorSink, redactObject } from "@theholocron/observability/core";
|
|
5
5
|
import yargs from "yargs";
|
|
6
6
|
import { hideBin } from "yargs/helpers";
|
|
@@ -2218,24 +2218,43 @@ function tokenContext(rawTokens) {
|
|
|
2218
2218
|
// src/commands/auth/auth-check.args.ts
|
|
2219
2219
|
const authCheckArgs = (yy) => yy.positional("provider", { type: "string" });
|
|
2220
2220
|
// src/plugin/capabilities/capabilities.ts
|
|
2221
|
+
/** How many providers each capability resolves to: one (`"single"`) or several active at once (`"many"`). */
|
|
2221
2222
|
const CARDINALITY = {
|
|
2223
|
+
/** `source` has exactly one provider. */
|
|
2222
2224
|
source: "single",
|
|
2225
|
+
/** `ci` has exactly one provider. */
|
|
2223
2226
|
ci: "single",
|
|
2227
|
+
/** `secrets` has exactly one provider. */
|
|
2224
2228
|
secrets: "single",
|
|
2229
|
+
/** `environments` has exactly one provider. */
|
|
2225
2230
|
environments: "single",
|
|
2231
|
+
/** `issues` has exactly one provider. */
|
|
2226
2232
|
issues: "single",
|
|
2233
|
+
/** `deployment` has exactly one provider. */
|
|
2227
2234
|
deployment: "single",
|
|
2235
|
+
/** `storage` has exactly one provider. */
|
|
2228
2236
|
storage: "single",
|
|
2237
|
+
/** `auth` has exactly one provider. */
|
|
2229
2238
|
auth: "single",
|
|
2239
|
+
/** `vault` has exactly one provider. */
|
|
2230
2240
|
vault: "single",
|
|
2241
|
+
/** `dns` has exactly one provider. */
|
|
2231
2242
|
dns: "single",
|
|
2243
|
+
/** `tooling` can have several providers active at once. */
|
|
2232
2244
|
tooling: "many",
|
|
2245
|
+
/** `notifications` can have several providers active at once. */
|
|
2233
2246
|
notifications: "many",
|
|
2247
|
+
/** `analytics` can have several providers active at once. */
|
|
2234
2248
|
analytics: "many",
|
|
2249
|
+
/** `errors` has exactly one provider. */
|
|
2235
2250
|
errors: "single",
|
|
2251
|
+
/** `logs` has exactly one provider. */
|
|
2236
2252
|
logs: "single",
|
|
2253
|
+
/** `monitoring` has exactly one provider. */
|
|
2237
2254
|
monitoring: "single",
|
|
2255
|
+
/** `wiki` has exactly one provider. */
|
|
2238
2256
|
wiki: "single",
|
|
2257
|
+
/** `workers` has exactly one provider. */
|
|
2239
2258
|
workers: "single"
|
|
2240
2259
|
};
|
|
2241
2260
|
/**
|
|
@@ -2250,6 +2269,7 @@ const REQUIRED_CAPABILITIES = [];
|
|
|
2250
2269
|
*/
|
|
2251
2270
|
var ElevationRequiredError = class extends Error {
|
|
2252
2271
|
elevation;
|
|
2272
|
+
/** Lets a caller tell this error from any other by name, across package copies. */
|
|
2253
2273
|
name = "ElevationRequiredError";
|
|
2254
2274
|
constructor(message, elevation, options) {
|
|
2255
2275
|
super(message, options);
|
|
@@ -2333,6 +2353,12 @@ function resolveEntry(key, raw) {
|
|
|
2333
2353
|
})
|
|
2334
2354
|
};
|
|
2335
2355
|
}
|
|
2356
|
+
/** The values `repoValidation.docsCoverage` accepts. */
|
|
2357
|
+
const DOCS_COVERAGE_MODES = [
|
|
2358
|
+
"off",
|
|
2359
|
+
"warn",
|
|
2360
|
+
"required"
|
|
2361
|
+
];
|
|
2336
2362
|
function resolveConfig(raw) {
|
|
2337
2363
|
if (!raw.name) throw new ConfigError("`name` is required");
|
|
2338
2364
|
if (!raw.providers || typeof raw.providers !== "object") throw new ConfigError("`providers` block is required");
|
|
@@ -2347,6 +2373,8 @@ function resolveConfig(raw) {
|
|
|
2347
2373
|
if (!raw.docs.build) throw new ConfigError("`docs.build` is required when `docs` is set");
|
|
2348
2374
|
docs = raw.docs;
|
|
2349
2375
|
}
|
|
2376
|
+
const docsCoverage = raw.repoValidation?.docsCoverage;
|
|
2377
|
+
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
2378
|
const homepage = raw.homepage ?? (docs?.domain ? `https://${docs.domain}/` : void 0);
|
|
2351
2379
|
return {
|
|
2352
2380
|
name: raw.name,
|
|
@@ -2355,6 +2383,7 @@ function resolveConfig(raw) {
|
|
|
2355
2383
|
org: raw.org,
|
|
2356
2384
|
domain: raw.domain,
|
|
2357
2385
|
repo: raw.repo,
|
|
2386
|
+
repoValidation: raw.repoValidation,
|
|
2358
2387
|
tasks: raw.tasks,
|
|
2359
2388
|
syncScripts: raw.syncScripts,
|
|
2360
2389
|
holocronScript: raw.holocronScript,
|
|
@@ -3789,12 +3818,12 @@ async function runDeploy(input) {
|
|
|
3789
3818
|
};
|
|
3790
3819
|
}
|
|
3791
3820
|
}
|
|
3792
|
-
const SKIP_DIRS$
|
|
3821
|
+
const SKIP_DIRS$3 = [
|
|
3793
3822
|
".git",
|
|
3794
3823
|
"node_modules",
|
|
3795
3824
|
".turbo"
|
|
3796
3825
|
];
|
|
3797
|
-
const defaultWalkFiles$2 = (dir) => walkFilesSync(dir, { skip: SKIP_DIRS$
|
|
3826
|
+
const defaultWalkFiles$2 = (dir) => walkFilesSync(dir, { skip: SKIP_DIRS$3 });
|
|
3798
3827
|
/** `holocron deploy --files <dir>` — the non-git counterpart to `runDeploy`. */
|
|
3799
3828
|
async function runDeployFromFiles(input) {
|
|
3800
3829
|
const print = input.print ?? ((line) => console.log(line));
|
|
@@ -9981,13 +10010,13 @@ function generateHolocronConfig(opts) {
|
|
|
9981
10010
|
lines.push(``);
|
|
9982
10011
|
return lines.join("\n");
|
|
9983
10012
|
}
|
|
9984
|
-
const SKIP_DIRS$
|
|
10013
|
+
const SKIP_DIRS$2 = [
|
|
9985
10014
|
".git",
|
|
9986
10015
|
"node_modules",
|
|
9987
10016
|
"dist",
|
|
9988
10017
|
".turbo"
|
|
9989
10018
|
];
|
|
9990
|
-
const defaultWalkFiles$1 = (dir) => walkFilesSync(dir, { skip: SKIP_DIRS$
|
|
10019
|
+
const defaultWalkFiles$1 = (dir) => walkFilesSync(dir, { skip: SKIP_DIRS$2 });
|
|
9991
10020
|
function isBinary(content) {
|
|
9992
10021
|
for (let i = 0; i < Math.min(content.length, 8e3); i++) if (content.charCodeAt(i) === 0) return true;
|
|
9993
10022
|
return false;
|
|
@@ -12051,6 +12080,9 @@ const probeArgs = (y) => y.positional("provider", {
|
|
|
12051
12080
|
type: "string",
|
|
12052
12081
|
array: true,
|
|
12053
12082
|
describe: "Arguments for the probe (`probe deps who <name>`)"
|
|
12083
|
+
}).option("lcov", {
|
|
12084
|
+
type: "string",
|
|
12085
|
+
describe: "Also write the coverage a `docs` probe measures to this lcov file (relative to the repo root)"
|
|
12054
12086
|
}).option("yes", {
|
|
12055
12087
|
type: "boolean",
|
|
12056
12088
|
default: false,
|
|
@@ -12489,13 +12521,13 @@ function planDeps(root) {
|
|
|
12489
12521
|
};
|
|
12490
12522
|
}
|
|
12491
12523
|
// src/commands/probe/deps/report-deps.ts
|
|
12492
|
-
const kindOf = (section) => section === "peerDependencies" ? "peer" : section === "devDependencies" ? "dev" : "prod";
|
|
12524
|
+
const kindOf$1 = (section) => section === "peerDependencies" ? "peer" : section === "devDependencies" ? "dev" : "prod";
|
|
12493
12525
|
/** Every package that uses a dependency, with how. */
|
|
12494
12526
|
function usersOf(row) {
|
|
12495
12527
|
const byPkg = /* @__PURE__ */ new Map();
|
|
12496
12528
|
for (const e of row.edges) {
|
|
12497
12529
|
const kinds = byPkg.get(e.pkg) ?? /* @__PURE__ */ new Set();
|
|
12498
|
-
kinds.add(kindOf(e.section));
|
|
12530
|
+
kinds.add(kindOf$1(e.section));
|
|
12499
12531
|
byPkg.set(e.pkg, kinds);
|
|
12500
12532
|
}
|
|
12501
12533
|
return [...byPkg.entries()].map(([pkg, kinds]) => ({
|
|
@@ -12516,7 +12548,7 @@ function detail(p, filter) {
|
|
|
12516
12548
|
for (const e of r.edges) {
|
|
12517
12549
|
const entry = byGroup.get(e.group) ?? /* @__PURE__ */ new Map();
|
|
12518
12550
|
const kinds = entry.get(e.pkg) ?? /* @__PURE__ */ new Set();
|
|
12519
|
-
kinds.add(kindOf(e.section));
|
|
12551
|
+
kinds.add(kindOf$1(e.section));
|
|
12520
12552
|
entry.set(e.pkg, kinds);
|
|
12521
12553
|
byGroup.set(e.group, entry);
|
|
12522
12554
|
}
|
|
@@ -12792,10 +12824,30 @@ function realDiff(repoRoot) {
|
|
|
12792
12824
|
};
|
|
12793
12825
|
/* v8 ignore stop */
|
|
12794
12826
|
}
|
|
12827
|
+
/** Writes the report `--lcov <path>` asks for, and says so; a dry run only says what it would write. */
|
|
12828
|
+
function writeLcov(ctx, repoRoot, packages) {
|
|
12829
|
+
if (!ctx.lcov) return;
|
|
12830
|
+
if (ctx.dryRun) {
|
|
12831
|
+
ctx.say({
|
|
12832
|
+
status: "info",
|
|
12833
|
+
label: "lcov",
|
|
12834
|
+
detail: `would write ${ctx.lcov}`
|
|
12835
|
+
});
|
|
12836
|
+
return;
|
|
12837
|
+
}
|
|
12838
|
+
const file = resolve(repoRoot, ctx.lcov);
|
|
12839
|
+
mkdirSync(dirname(file), { recursive: true });
|
|
12840
|
+
writeFileSync(file, toLcov(packages));
|
|
12841
|
+
ctx.say({
|
|
12842
|
+
status: "info",
|
|
12843
|
+
label: "lcov",
|
|
12844
|
+
detail: `wrote ${ctx.lcov}`
|
|
12845
|
+
});
|
|
12846
|
+
}
|
|
12795
12847
|
function percent(documented, total) {
|
|
12796
12848
|
return `${total === 0 ? 100 : Math.round(100 * documented / total)}%`;
|
|
12797
12849
|
}
|
|
12798
|
-
function summarise$
|
|
12850
|
+
function summarise$2(ctx, packages) {
|
|
12799
12851
|
let total = 0;
|
|
12800
12852
|
let documented = 0;
|
|
12801
12853
|
ctx.say({
|
|
@@ -12822,9 +12874,13 @@ function summarise$1(ctx, packages) {
|
|
|
12822
12874
|
* `docs coverage`: how much of each public package's exported API has a doc comment (functions, classes, interfaces,
|
|
12823
12875
|
* types, constants and their public members), measured with the repo's TypeDoc. `docs lcov` writes the same
|
|
12824
12876
|
* 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.
|
|
12877
|
+
* changes without a doc comment, which is the check CI runs. `docs coverage` and `docs patch` also write that
|
|
12878
|
+
* report wherever `--lcov <path>` says, from the same measurement, so CI gates and uploads with one command.
|
|
12879
|
+
*
|
|
12880
|
+
* `mode` is the repo's `repoValidation.docsCoverage`, and only `docs patch` follows it: `off` skips it (nothing is
|
|
12881
|
+
* measured or written), `warn` reports an undocumented export without failing, `required` fails for it.
|
|
12826
12882
|
*/
|
|
12827
|
-
function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = realDiff(repoRoot)) {
|
|
12883
|
+
function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = realDiff(repoRoot), mode = "required") {
|
|
12828
12884
|
const measure = () => measureDocsCoverage({
|
|
12829
12885
|
repoRoot,
|
|
12830
12886
|
typedoc
|
|
@@ -12834,27 +12890,40 @@ function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = rea
|
|
|
12834
12890
|
summary: "Show how much of each package's exported API has a doc comment.",
|
|
12835
12891
|
writes: false,
|
|
12836
12892
|
async run(ctx) {
|
|
12837
|
-
|
|
12893
|
+
const packages = measure();
|
|
12894
|
+
writeLcov(ctx, repoRoot, packages);
|
|
12895
|
+
summarise$2(ctx, packages);
|
|
12838
12896
|
}
|
|
12839
12897
|
},
|
|
12840
12898
|
patch: {
|
|
12841
12899
|
summary: "Fail for each export a PR adds or changes that has no doc comment (against BASE_SHA).",
|
|
12842
12900
|
writes: false,
|
|
12843
12901
|
async run(ctx) {
|
|
12902
|
+
if (mode === "off") {
|
|
12903
|
+
ctx.say({
|
|
12904
|
+
status: "info",
|
|
12905
|
+
label: "docs patch",
|
|
12906
|
+
detail: "off in this repo's config (repoValidation.docsCoverage)"
|
|
12907
|
+
});
|
|
12908
|
+
return;
|
|
12909
|
+
}
|
|
12844
12910
|
const added = addedLines(diff());
|
|
12845
12911
|
const touched = (dir) => [...added.keys()].some((file) => file.startsWith(`${dir}/`));
|
|
12846
|
-
const
|
|
12912
|
+
const packages = measureDocsCoverage({
|
|
12847
12913
|
repoRoot,
|
|
12848
12914
|
typedoc,
|
|
12849
|
-
only: touched
|
|
12850
|
-
})
|
|
12915
|
+
...ctx.lcov ? {} : { only: touched }
|
|
12916
|
+
});
|
|
12917
|
+
writeLcov(ctx, repoRoot, packages);
|
|
12918
|
+
const missing = packages.flatMap(({ symbols }) => symbols).filter((s) => added.get(s.file)?.has(s.line));
|
|
12851
12919
|
const undocumented = missing.filter((s) => !s.documented);
|
|
12852
12920
|
ctx.say({
|
|
12853
12921
|
status: "heading",
|
|
12854
12922
|
label: "Exports this PR adds or changes"
|
|
12855
12923
|
});
|
|
12924
|
+
const level = mode === "warn" ? "info" : "fail";
|
|
12856
12925
|
for (const { file, line, kind, name } of undocumented) ctx.say({
|
|
12857
|
-
status:
|
|
12926
|
+
status: level,
|
|
12858
12927
|
label: `${file}:${line}`,
|
|
12859
12928
|
detail: `${kind} ${name} has no doc comment`
|
|
12860
12929
|
});
|
|
@@ -12863,6 +12932,11 @@ function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = rea
|
|
|
12863
12932
|
label: `${missing.length} checked`,
|
|
12864
12933
|
detail: "every one has a doc comment"
|
|
12865
12934
|
});
|
|
12935
|
+
else if (mode === "warn") ctx.say({
|
|
12936
|
+
status: "info",
|
|
12937
|
+
label: `${undocumented.length} without a doc comment`,
|
|
12938
|
+
detail: "warn: not failing (repoValidation.docsCoverage)"
|
|
12939
|
+
});
|
|
12866
12940
|
}
|
|
12867
12941
|
},
|
|
12868
12942
|
lcov: {
|
|
@@ -12875,7 +12949,7 @@ function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = rea
|
|
|
12875
12949
|
mkdirSync(dirname(file), { recursive: true });
|
|
12876
12950
|
writeFileSync(file, toLcov(packages));
|
|
12877
12951
|
});
|
|
12878
|
-
summarise$
|
|
12952
|
+
summarise$2(ctx, packages);
|
|
12879
12953
|
}
|
|
12880
12954
|
}
|
|
12881
12955
|
};
|
|
@@ -13001,7 +13075,7 @@ async function generateConfigFiles(input) {
|
|
|
13001
13075
|
const content = createAstromech({
|
|
13002
13076
|
cwd: input.repoRoot,
|
|
13003
13077
|
logger: input.logger ?? getLogger()
|
|
13004
|
-
}).codecovConfig(existing);
|
|
13078
|
+
}).codecovConfig(existing, { docsCoverage: config.repoValidation?.docsCoverage ?? "off" });
|
|
13005
13079
|
const packageCount = readWorkspacePackages(input.repoRoot).length;
|
|
13006
13080
|
entries.push(file("codecov.yml", content, packageCount > 0 ? `${packageCount} components` : "no components"));
|
|
13007
13081
|
} catch (error) {
|
|
@@ -13345,6 +13419,186 @@ function listProbes(groups) {
|
|
|
13345
13419
|
}
|
|
13346
13420
|
return lines;
|
|
13347
13421
|
}
|
|
13422
|
+
// src/commands/probe/references/clone-org.ts
|
|
13423
|
+
const SKIP_DIRS$1 = /* @__PURE__ */ new Set([".git", "node_modules"]);
|
|
13424
|
+
const MAX_FILE_BYTES = 5242880;
|
|
13425
|
+
/** Every text file under `dir`: not in `.git` or `node_modules`, under 5 MiB, and without a NUL in its first KiB. */
|
|
13426
|
+
function* textFiles(dir, root = dir) {
|
|
13427
|
+
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
|
13428
|
+
if (SKIP_DIRS$1.has(entry.name)) continue;
|
|
13429
|
+
const path = join(dir, entry.name);
|
|
13430
|
+
if (entry.isDirectory()) yield* textFiles(path, root);
|
|
13431
|
+
else if (entry.isFile() && statSync(path).size < MAX_FILE_BYTES) {
|
|
13432
|
+
const buffer = readFileSync(path);
|
|
13433
|
+
if (!buffer.subarray(0, 1024).includes(0)) yield {
|
|
13434
|
+
path: relative(root, path),
|
|
13435
|
+
text: buffer.toString("utf8")
|
|
13436
|
+
};
|
|
13437
|
+
}
|
|
13438
|
+
}
|
|
13439
|
+
}
|
|
13440
|
+
/**
|
|
13441
|
+
* Shallow-clones the default branch of each active (not archived) repository of `org` with `gh`, one at a time, and
|
|
13442
|
+
* removes every clone when the scan ends. Cloning, rather than GitHub code search, because search skips repositories
|
|
13443
|
+
* that are not indexed and gives no guarantee of completeness.
|
|
13444
|
+
*/
|
|
13445
|
+
function cloneOrg(org) {
|
|
13446
|
+
return JSON.parse(execFileSync("gh", [
|
|
13447
|
+
"repo",
|
|
13448
|
+
"list",
|
|
13449
|
+
org,
|
|
13450
|
+
"--limit",
|
|
13451
|
+
"200",
|
|
13452
|
+
"--json",
|
|
13453
|
+
"name,isArchived,isTemplate"
|
|
13454
|
+
], { encoding: "utf8" })).filter((repo) => !repo.isArchived).sort((a, b) => a.name.localeCompare(b.name)).map((repo) => ({
|
|
13455
|
+
name: repo.name,
|
|
13456
|
+
isTemplate: repo.isTemplate,
|
|
13457
|
+
files() {
|
|
13458
|
+
const scratch = mkdtempSync(join(tmpdir(), "refs-"));
|
|
13459
|
+
const dest = join(scratch, repo.name);
|
|
13460
|
+
execFileSync("gh", [
|
|
13461
|
+
"repo",
|
|
13462
|
+
"clone",
|
|
13463
|
+
`${org}/${repo.name}`,
|
|
13464
|
+
dest,
|
|
13465
|
+
"--",
|
|
13466
|
+
"--depth",
|
|
13467
|
+
"1",
|
|
13468
|
+
"--quiet"
|
|
13469
|
+
], { stdio: "pipe" });
|
|
13470
|
+
try {
|
|
13471
|
+
return [...textFiles(dest)];
|
|
13472
|
+
} finally {
|
|
13473
|
+
rmSync(scratch, {
|
|
13474
|
+
recursive: true,
|
|
13475
|
+
force: true
|
|
13476
|
+
});
|
|
13477
|
+
}
|
|
13478
|
+
}
|
|
13479
|
+
}));
|
|
13480
|
+
/* v8 ignore stop */
|
|
13481
|
+
}
|
|
13482
|
+
// src/commands/probe/references/find-references.ts
|
|
13483
|
+
/** The repository that hosts the files; its own references are the starters and shims, not callers. */
|
|
13484
|
+
const HOST_REPO = ".github";
|
|
13485
|
+
/** What a reference points at, from the text after the needle. */
|
|
13486
|
+
function kindOf(line, needle) {
|
|
13487
|
+
const rest = line.slice(line.indexOf(needle) + needle.length);
|
|
13488
|
+
if (rest.startsWith("workflows/")) return "workflow";
|
|
13489
|
+
if (rest.startsWith("actions/")) return "action";
|
|
13490
|
+
return "other";
|
|
13491
|
+
}
|
|
13492
|
+
/** Every line of every file of `repo` that contains `needle`. */
|
|
13493
|
+
function findReferences(repo, needle) {
|
|
13494
|
+
const found = [];
|
|
13495
|
+
for (const file of repo.files()) file.text.split("\n").forEach((line, index) => {
|
|
13496
|
+
if (!line.includes(needle)) return;
|
|
13497
|
+
found.push({
|
|
13498
|
+
repo: repo.name,
|
|
13499
|
+
file: file.path,
|
|
13500
|
+
line: index + 1,
|
|
13501
|
+
kind: kindOf(line, needle),
|
|
13502
|
+
text: line.trim()
|
|
13503
|
+
});
|
|
13504
|
+
});
|
|
13505
|
+
return found;
|
|
13506
|
+
}
|
|
13507
|
+
// src/commands/probe/references/references-probes.ts
|
|
13508
|
+
function scan(repos, needle) {
|
|
13509
|
+
return {
|
|
13510
|
+
repos,
|
|
13511
|
+
found: repos.flatMap((repo) => findReferences(repo, needle))
|
|
13512
|
+
};
|
|
13513
|
+
}
|
|
13514
|
+
function summarise$1(ctx, repos, found, needle, max) {
|
|
13515
|
+
ctx.say({
|
|
13516
|
+
status: "heading",
|
|
13517
|
+
label: `References to ${needle}`
|
|
13518
|
+
});
|
|
13519
|
+
for (const repo of repos) {
|
|
13520
|
+
const own = found.filter((ref) => ref.repo === repo.name);
|
|
13521
|
+
const files = new Set(own.map((ref) => ref.file)).size;
|
|
13522
|
+
const count = (kind) => own.filter((ref) => ref.kind === kind).length;
|
|
13523
|
+
ctx.say({
|
|
13524
|
+
status: "info",
|
|
13525
|
+
label: repo.name === ".github" ? `${repo.name} (host)` : repo.name,
|
|
13526
|
+
detail: `${files} files: ${count("workflow")} workflow, ${count("action")} action, ${count("other")} other`
|
|
13527
|
+
});
|
|
13528
|
+
}
|
|
13529
|
+
const outside = found.filter((ref) => ref.repo !== HOST_REPO).length;
|
|
13530
|
+
const detail = `${found.length - outside} more inside ${HOST_REPO}`;
|
|
13531
|
+
if (max !== void 0 && outside > max) ctx.say({
|
|
13532
|
+
status: "fail",
|
|
13533
|
+
label: `${outside} outside ${HOST_REPO}`,
|
|
13534
|
+
detail: `more than the ${max} allowed; ${detail}`
|
|
13535
|
+
});
|
|
13536
|
+
else ctx.say({
|
|
13537
|
+
status: "ok",
|
|
13538
|
+
label: `${outside} outside ${HOST_REPO}`,
|
|
13539
|
+
detail
|
|
13540
|
+
});
|
|
13541
|
+
}
|
|
13542
|
+
/**
|
|
13543
|
+
* `ci refs` counts the references to the reusable workflows and composite actions hosted in `<org>/.github` across
|
|
13544
|
+
* every active repository of the org. It is the exit test for removing the forwarding shims there: they can go when
|
|
13545
|
+
* the count outside `.github` is zero. `ci refs <max>` fails above `<max>`. `ci ref-list` prints each reference with
|
|
13546
|
+
* its file and line.
|
|
13547
|
+
*/
|
|
13548
|
+
function ciProbes(org, clone = cloneOrg) {
|
|
13549
|
+
const needle = (name) => `${name}/.github/.github/`;
|
|
13550
|
+
const read = (ctx) => {
|
|
13551
|
+
if (!org) {
|
|
13552
|
+
ctx.say({
|
|
13553
|
+
status: "fail",
|
|
13554
|
+
label: "no org",
|
|
13555
|
+
detail: "the config has no org to scan"
|
|
13556
|
+
});
|
|
13557
|
+
return null;
|
|
13558
|
+
}
|
|
13559
|
+
return {
|
|
13560
|
+
org,
|
|
13561
|
+
...scan(clone(org), needle(org))
|
|
13562
|
+
};
|
|
13563
|
+
};
|
|
13564
|
+
return {
|
|
13565
|
+
refs: {
|
|
13566
|
+
summary: "Count references to the reusable workflows and actions hosted in the org's .github repo (arg: max).",
|
|
13567
|
+
writes: false,
|
|
13568
|
+
async run(ctx) {
|
|
13569
|
+
const result = read(ctx);
|
|
13570
|
+
if (!result) return;
|
|
13571
|
+
const max = ctx.args?.[0] === void 0 ? void 0 : Number(ctx.args[0]);
|
|
13572
|
+
if (max !== void 0 && !Number.isInteger(max)) {
|
|
13573
|
+
ctx.say({
|
|
13574
|
+
status: "fail",
|
|
13575
|
+
label: `\`${ctx.args[0]}\` is not a number`,
|
|
13576
|
+
detail: "usage: ci refs [max]"
|
|
13577
|
+
});
|
|
13578
|
+
return;
|
|
13579
|
+
}
|
|
13580
|
+
summarise$1(ctx, result.repos, result.found, needle(result.org), max);
|
|
13581
|
+
}
|
|
13582
|
+
},
|
|
13583
|
+
"ref-list": {
|
|
13584
|
+
summary: "List every reference to the org's .github workflows and actions, with file and line.",
|
|
13585
|
+
writes: false,
|
|
13586
|
+
async run(ctx) {
|
|
13587
|
+
const result = read(ctx);
|
|
13588
|
+
if (!result) return;
|
|
13589
|
+
for (const ref of result.found) ctx.say({
|
|
13590
|
+
status: "info",
|
|
13591
|
+
label: `${ref.repo}:${ref.file}:${ref.line}`,
|
|
13592
|
+
detail: `${ref.kind}: ${ref.text}`
|
|
13593
|
+
});
|
|
13594
|
+
ctx.say({
|
|
13595
|
+
status: "ok",
|
|
13596
|
+
label: `${result.found.length} references`
|
|
13597
|
+
});
|
|
13598
|
+
}
|
|
13599
|
+
}
|
|
13600
|
+
};
|
|
13601
|
+
}
|
|
13348
13602
|
// src/ui/command-failure/command-failure.ts
|
|
13349
13603
|
/**
|
|
13350
13604
|
* Error class names whose `.message` is a complete, actionable sentence. Any other error is printed too, so a command
|
|
@@ -13452,6 +13706,7 @@ async function runProbe(input) {
|
|
|
13452
13706
|
const ctx = {
|
|
13453
13707
|
dryRun: input.dryRun,
|
|
13454
13708
|
args: input.args ?? [],
|
|
13709
|
+
...input.lcov ? { lcov: input.lcov } : {},
|
|
13455
13710
|
say: emit,
|
|
13456
13711
|
secret: (value) => {
|
|
13457
13712
|
if (value) secrets.add(value);
|
|
@@ -13514,9 +13769,10 @@ async function runProbeCommand(input) {
|
|
|
13514
13769
|
});
|
|
13515
13770
|
groups.set(CORE_PROVIDER, coreProbes(loader, /* @__PURE__ */ new Map([[COMLINK_PROVIDER, comlink]])));
|
|
13516
13771
|
groups.set(COMLINK_PROVIDER, comlink);
|
|
13517
|
-
groups.set(DOCS_PROVIDER, docsCoverageProbes(input.context.repoRoot, input.typedoc));
|
|
13772
|
+
groups.set(DOCS_PROVIDER, docsCoverageProbes(input.context.repoRoot, input.typedoc, void 0, input.loaded.resolved.repoValidation?.docsCoverage ?? "off"));
|
|
13518
13773
|
groups.set(DEPS_PROVIDER, depsProbes(input.context.repoRoot, print));
|
|
13519
13774
|
groups.set(GENERATED_PROVIDER, generatedProbes(input.loaded, input.context.repoRoot));
|
|
13775
|
+
groups.set("ci", ciProbes(input.context.org));
|
|
13520
13776
|
if (!input.provider) {
|
|
13521
13777
|
if (input.pick) await input.pick(groups);
|
|
13522
13778
|
else for (const line of listProbes(groups)) print(line);
|
|
@@ -13542,6 +13798,7 @@ async function runProbeCommand(input) {
|
|
|
13542
13798
|
provider: input.provider,
|
|
13543
13799
|
probeName: input.probe,
|
|
13544
13800
|
args: input.args ?? [],
|
|
13801
|
+
...input.lcov ? { lcov: input.lcov } : {},
|
|
13545
13802
|
probe,
|
|
13546
13803
|
dryRun: input.dryRun ?? false,
|
|
13547
13804
|
yes: input.yes ?? false,
|
|
@@ -13573,6 +13830,7 @@ const probeCommand = {
|
|
|
13573
13830
|
...argv.provider ? { provider: argv.provider } : {},
|
|
13574
13831
|
...argv.probe ? { probe: argv.probe } : {},
|
|
13575
13832
|
...argv.args?.length ? { args: argv.args.map(String) } : {},
|
|
13833
|
+
...argv.lcov ? { lcov: argv.lcov } : {},
|
|
13576
13834
|
dryRun: argv.dryRun,
|
|
13577
13835
|
yes: argv.yes,
|
|
13578
13836
|
...process.stdin.isTTY ? { pick: (groups) => launchMenu(buildProbeMenuEntries(groups), argv, "probe — choose a provider:", "Run `holocron probe` to list the probes.", ["probe"]) } : {}
|