@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 +269 -3
- package/dist/cli.mjs.map +1 -1
- package/dist/{index-Bh7jWkxS.d.mts → index-Bt6M-fvi.d.mts} +2 -2
- package/dist/index.d.mts +1 -1
- package/dist/presets.d.mts +1 -1
- package/package.json +11 -11
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,
|
|
12885
|
-
* report wherever `--lcov <path>` says, from the same measurement
|
|
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,
|