@theholocron/cli 5.0.0-alpha.280 → 5.0.0-alpha.282

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
@@ -12707,6 +12707,268 @@ function countSymbols(children, fallbackFile) {
12707
12707
  for (const child of children ?? []) walk(child);
12708
12708
  return out;
12709
12709
  }
12710
+ // src/commands/probe/docs-presence/page-names.ts
12711
+ /**
12712
+ * The names a package's docs page can have: its folder name, and that name without the `-client` or
12713
+ * `holocron-plugin-` part its page drops (`clients/axiom-client` is the page `clients/axiom.mdx`).
12714
+ */
12715
+ function pageNames(dir) {
12716
+ const name = dir.slice(dir.lastIndexOf("/") + 1);
12717
+ return [.../* @__PURE__ */ new Set([
12718
+ name,
12719
+ name.replace(/-client$/, ""),
12720
+ name.replace(/^holocron-plugin-/, "")
12721
+ ])];
12722
+ }
12723
+ // src/commands/probe/docs-presence/has-docs-signal.ts
12724
+ /**
12725
+ * Whether the PR touches a package's documentation: a doc comment added in its source, its `README.md`, or a docs
12726
+ * page named after it (see `pageNames`).
12727
+ */
12728
+ function hasDocsSignal(dir, changedFiles, addedCommentLines) {
12729
+ if (addedCommentLines.length > 0) return true;
12730
+ const names = pageNames(dir);
12731
+ return changedFiles.some((f) => {
12732
+ if (f === `${dir}/README.md`) return true;
12733
+ if (!f.startsWith("docs/") || !/\.mdx?$/.test(f)) return false;
12734
+ return names.includes(f.slice(f.lastIndexOf("/") + 1).replace(/\.mdx?$/, ""));
12735
+ });
12736
+ }
12737
+ // src/commands/probe/docs-presence/evaluate-docs-presence.ts
12738
+ /**
12739
+ * Sorts the packages a feature changed into those that need a warning (no docs signal, and no `[skip docs]` marker
12740
+ * with a reason that covers them) and those a marker excused. A marker with no reason excuses nothing.
12741
+ */
12742
+ function evaluateDocsPresence(input) {
12743
+ const { packages, changedFiles, addedCommentLines, skip } = input;
12744
+ const result = {
12745
+ warn: [],
12746
+ skipped: [],
12747
+ missingReason: false
12748
+ };
12749
+ for (const dir of packages) {
12750
+ if (hasDocsSignal(dir, changedFiles, addedCommentLines(dir))) continue;
12751
+ const covered = skip !== null && (skip.scope === null || skip.scope.some((s) => s === dir || pageNames(dir).includes(s)));
12752
+ if (covered && skip.reason) {
12753
+ result.skipped.push({
12754
+ dir,
12755
+ reason: skip.reason
12756
+ });
12757
+ continue;
12758
+ }
12759
+ if (covered) result.missingReason = true;
12760
+ result.warn.push(dir);
12761
+ }
12762
+ return result;
12763
+ }
12764
+ // src/commands/probe/docs-presence/is-added-doc-comment.ts
12765
+ /** Whether a line of a unified diff adds part of a doc comment: its `/**` opener, a ` * text` line or the closer. */
12766
+ function isAddedDocComment(line) {
12767
+ return /^\+\s*(\/\*\*|\*(\s|\/|$))/.test(line);
12768
+ }
12769
+ // src/commands/probe/docs-presence/is-feat.ts
12770
+ /** Whether any subject is a Conventional Commit `feat`: `feat:`, `feat(scope):` or `feat!:`, in any case. */
12771
+ function isFeat(subjects) {
12772
+ return subjects.some((s) => /^feat(\([^)]*\))?!?:/i.test(s.trim()));
12773
+ }
12774
+ // src/commands/probe/docs-presence/package-of.ts
12775
+ /**
12776
+ * The public package a changed file is source of: the nearest folder above it with a `package.json`, when the file is
12777
+ * under that package's `src/` or is its root `index`, and the package is not private. Tests, other package files and
12778
+ * files in no package give `undefined`.
12779
+ */
12780
+ function packageOf(file, readPackage) {
12781
+ if (file.includes("node_modules/") || /\.(test|spec)\.[cm]?[jt]sx?$/.test(file)) return void 0;
12782
+ const parts = file.split("/");
12783
+ for (let i = parts.length - 1; i > 0; i--) {
12784
+ const dir = parts.slice(0, i).join("/");
12785
+ const pkg = readPackage(dir);
12786
+ if (!pkg) continue;
12787
+ if (pkg.private) return void 0;
12788
+ const inside = parts.slice(i).join("/");
12789
+ return inside.startsWith("src/") || /^index\.[cm]?[jt]s$/.test(inside) ? dir : void 0;
12790
+ }
12791
+ }
12792
+ // src/commands/probe/docs-presence/parse-skip-docs.ts
12793
+ /**
12794
+ * Finds `[skip docs] reason`, or `[skip docs: pkg-a, pkg-b] reason`, on one line of a PR description or commit
12795
+ * body. Like semantic-release's `[skip ci]`, except that the reason after it is what makes it count. `null` when the
12796
+ * text has no marker.
12797
+ */
12798
+ function parseSkipDocs(text) {
12799
+ const match = /\[skip docs(?::\s*([^\]]*?))?\][ \t]*([^\n]*)/i.exec(text);
12800
+ if (!match) return null;
12801
+ return {
12802
+ scope: match[1] ? match[1].split(",").map((s) => s.trim()).filter(Boolean) : null,
12803
+ reason: match[2].trim()
12804
+ };
12805
+ }
12806
+ // src/commands/probe/docs-presence/docs-presence-probe.ts
12807
+ /** The public packages a PR added, by folder name: an added `<package>/src/index.ts` whose `package.json` is not private. */
12808
+ function newPublicPackages(addedFiles, io) {
12809
+ return addedFiles.flatMap((file) => {
12810
+ const dir = /^(.+)\/src\/index\.ts$/.exec(file)?.[1];
12811
+ if (!dir || dir.includes("node_modules")) return [];
12812
+ const pkg = io.readPackage(dir);
12813
+ return pkg && !pkg.private ? [dir.slice(dir.lastIndexOf("/") + 1)] : [];
12814
+ });
12815
+ }
12816
+ /**
12817
+ * `docs presence`: warns, and never fails, when a PR ships a feature without touching the docs. It warns for a new
12818
+ * public package with no docs change at all, and for a `feat` that changes a public package's source (`src/**` or a
12819
+ * root `index`) with no docs signal for that package: its README, a docs page named after it, or a doc comment added
12820
+ * in its source. `[skip docs] <reason>` in the PR description (`PR_BODY`) or a commit message excuses it, scoped with
12821
+ * `[skip docs: <package>]`; a marker with no reason excuses nothing. This is the `docsEnforcement` job of
12822
+ * `platform.repoValidation`. The base to diff against is `BASE_SHA` (default `HEAD~1`).
12823
+ */
12824
+ function docsPresenceProbe(io) {
12825
+ return {
12826
+ summary: "Warn when a new package, or a feat to one, ships without a docs change (never fails).",
12827
+ writes: false,
12828
+ async run(ctx) {
12829
+ const base = io.env["BASE_SHA"] || "HEAD~1";
12830
+ let addedFiles;
12831
+ let changedFiles;
12832
+ try {
12833
+ addedFiles = io.addedFiles(base);
12834
+ changedFiles = io.changedFiles(base);
12835
+ } catch {
12836
+ ctx.say({
12837
+ status: "info",
12838
+ label: "docs presence",
12839
+ detail: "could not determine the changed files; skipped"
12840
+ });
12841
+ return;
12842
+ }
12843
+ ctx.say({
12844
+ status: "heading",
12845
+ label: "Docs presence"
12846
+ });
12847
+ const newPackages = newPublicPackages(addedFiles, io);
12848
+ if (newPackages.length === 0) ctx.say({
12849
+ status: "ok",
12850
+ label: "new packages",
12851
+ detail: "no new public packages"
12852
+ });
12853
+ else if (changedFiles.some((f) => f.startsWith("docs/") || /\.mdx?$/.test(f))) ctx.say({
12854
+ status: "ok",
12855
+ label: "new packages",
12856
+ detail: `${newPackages.join(", ")}: a docs change is in the PR`
12857
+ });
12858
+ else ctx.say({
12859
+ status: "info",
12860
+ label: "new packages without docs",
12861
+ detail: `${newPackages.join(", ")}: add a docs page under docs/ in this PR, or a scoped follow-up right after`
12862
+ });
12863
+ if (!isFeat([io.env["PR_TITLE"] ?? "", ...io.subjects(base)].filter(Boolean))) {
12864
+ ctx.say({
12865
+ status: "ok",
12866
+ label: "feature docs",
12867
+ detail: "no feat in this PR; nothing to check"
12868
+ });
12869
+ return;
12870
+ }
12871
+ const packages = [...new Set(changedFiles.flatMap((f) => packageOf(f, io.readPackage) ?? []))];
12872
+ if (packages.length === 0) {
12873
+ ctx.say({
12874
+ status: "ok",
12875
+ label: "feature docs",
12876
+ detail: "a feat, but no public package source changed"
12877
+ });
12878
+ return;
12879
+ }
12880
+ const { warn, skipped, missingReason } = evaluateDocsPresence({
12881
+ packages,
12882
+ changedFiles,
12883
+ addedCommentLines: (dir) => io.diffOf(base, dir).split("\n").filter(isAddedDocComment),
12884
+ skip: parseSkipDocs(`${io.env["PR_BODY"] ?? ""}\n${io.messages(base)}`)
12885
+ });
12886
+ for (const { dir, reason } of skipped) ctx.say({
12887
+ status: "info",
12888
+ label: `skipped ${dir}`,
12889
+ detail: `[skip docs] ${reason}`
12890
+ });
12891
+ for (const dir of warn) ctx.say({
12892
+ status: "info",
12893
+ label: `warning: ${dir}`,
12894
+ detail: "this feat changes the package's source without a docs change: update its README, page or a doc comment, or add `[skip docs] <reason>` to the PR description"
12895
+ });
12896
+ if (missingReason) ctx.say({
12897
+ status: "info",
12898
+ label: "[skip docs]",
12899
+ detail: "found, but it has no reason after it, so it does not count"
12900
+ });
12901
+ if (warn.length === 0) ctx.say({
12902
+ status: "ok",
12903
+ label: "feature docs",
12904
+ detail: "every changed package has a docs signal or a [skip docs] reason"
12905
+ });
12906
+ }
12907
+ };
12908
+ }
12909
+ // src/commands/probe/docs-presence/real-docs-presence-io.ts
12910
+ /** The docs-presence probe's inputs from the real git, filesystem and environment of `repoRoot`. */
12911
+ function realDocsPresenceIo(repoRoot) {
12912
+ /* v8 ignore start -- runs the real git and reads real files; the probe is tested with an injected io */
12913
+ const git = (args) => execFileSync("git", args, {
12914
+ cwd: repoRoot,
12915
+ encoding: "utf8",
12916
+ maxBuffer: 67108864
12917
+ }).trim();
12918
+ const lines = (text) => text.split("\n").filter(Boolean);
12919
+ const quietly = (args) => {
12920
+ try {
12921
+ return git(args);
12922
+ } catch {
12923
+ return "";
12924
+ }
12925
+ };
12926
+ return {
12927
+ env: process.env,
12928
+ addedFiles: (base) => lines(git([
12929
+ "diff",
12930
+ "--name-only",
12931
+ "--diff-filter=A",
12932
+ base,
12933
+ "HEAD"
12934
+ ])),
12935
+ changedFiles: (base) => lines(git([
12936
+ "diff",
12937
+ "--name-only",
12938
+ base,
12939
+ "HEAD"
12940
+ ])),
12941
+ subjects: (base) => lines(quietly([
12942
+ "log",
12943
+ `${base}..HEAD`,
12944
+ "--format=%s"
12945
+ ])),
12946
+ messages: (base) => quietly([
12947
+ "log",
12948
+ `${base}..HEAD`,
12949
+ "--format=%B"
12950
+ ]),
12951
+ diffOf: (base, dir) => quietly([
12952
+ "diff",
12953
+ "-U0",
12954
+ base,
12955
+ "HEAD",
12956
+ "--",
12957
+ `${dir}/src`,
12958
+ `${dir}/index.ts`
12959
+ ]),
12960
+ readPackage: (dir) => {
12961
+ const path = join(repoRoot, dir, "package.json");
12962
+ if (!existsSync(path)) return void 0;
12963
+ try {
12964
+ return JSON.parse(readFileSync(path, "utf8"));
12965
+ } catch {
12966
+ return;
12967
+ }
12968
+ }
12969
+ };
12970
+ /* v8 ignore stop */
12971
+ }
12710
12972
  // src/commands/probe/docs-coverage/added-lines.ts
12711
12973
  /**
12712
12974
  * The lines a unified diff (`git diff -U0`) adds or changes, by file: from each hunk header
@@ -12881,13 +13143,16 @@ function summarise$2(ctx, packages) {
12881
13143
  * `docs coverage`: how much of each public package's exported API has a doc comment (functions, classes, interfaces,
12882
13144
  * types, constants and their public members), measured with the repo's TypeDoc. `docs lcov` writes the same
12883
13145
  * numbers as `coverage/docs.lcov`, for a coverage service to read. `docs patch` fails for each export a PR adds or
12884
- * changes without a doc comment, which is the check CI runs. `docs coverage` and `docs patch` also write that
12885
- * report wherever `--lcov <path>` says, from the same measurement, so CI gates and uploads with one command.
13146
+ * changes without a doc comment, for a person to run before pushing (in CI the Codecov status gates). `docs coverage`
13147
+ * and `docs patch` also write that report wherever `--lcov <path>` says, from the same measurement.
13148
+ *
13149
+ * `docs presence` is a different kind of check (does a feature come with docs?), kept in this group with the others: see
13150
+ * `docsPresenceProbe`. `presenceIo` is what it reads from git and the filesystem.
12886
13151
  *
12887
13152
  * `mode` is the repo's `repoValidation.docsCoverage`, and only `docs patch` follows it: `off` skips it (nothing is
12888
13153
  * measured or written), `warn` reports an undocumented export without failing, `required` fails for it.
12889
13154
  */
12890
- function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = realDiff(repoRoot), mode = "required") {
13155
+ function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = realDiff(repoRoot), mode = "required", presenceIo = realDocsPresenceIo(repoRoot)) {
12891
13156
  const measure = () => measureDocsCoverage({
12892
13157
  repoRoot,
12893
13158
  typedoc
@@ -12946,6 +13211,7 @@ function docsCoverageProbes(repoRoot, typedoc = runTypedoc(repoRoot), diff = rea
12946
13211
  });
12947
13212
  }
12948
13213
  },
13214
+ presence: docsPresenceProbe(presenceIo),
12949
13215
  lcov: {
12950
13216
  summary: "Write coverage/docs.lcov: the doc-comment coverage as an lcov report.",
12951
13217
  writes: true,