@theholocron/cli 5.0.0-alpha.283 → 5.0.0-alpha.285
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 +79 -98
- package/dist/cli.mjs.map +1 -1
- package/package.json +10 -10
package/dist/cli.mjs
CHANGED
|
@@ -29,6 +29,7 @@ import { findRootSync, isWorkspaceRoot, walkFilesSync } from "@theholocron/fs-ut
|
|
|
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";
|
|
31
31
|
import { stringifyJson } from "@theholocron/json-utils";
|
|
32
|
+
import { ADR_DIR, SPEC_DIRS, checkSpecs, evaluateDocsPresence, isAddedDocComment, isFeat, packageOf, parseSkipDocs } from "@theholocron/astromech/repo-validation";
|
|
32
33
|
import { lintCommitMsgFile } from "@theholocron/astromech/lint";
|
|
33
34
|
import { createGitHubClient } from "@theholocron/github-client";
|
|
34
35
|
// src/env/env.ts
|
|
@@ -12707,102 +12708,6 @@ function countSymbols(children, fallbackFile) {
|
|
|
12707
12708
|
for (const child of children ?? []) walk(child);
|
|
12708
12709
|
return out;
|
|
12709
12710
|
}
|
|
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
12711
|
// src/commands/probe/docs-presence/docs-presence-probe.ts
|
|
12807
12712
|
/** The public packages a PR added, by folder name: an added `<package>/src/index.ts` whose `package.json` is not private. */
|
|
12808
12713
|
function newPublicPackages(addedFiles, io) {
|
|
@@ -12860,7 +12765,8 @@ function docsPresenceProbe(io) {
|
|
|
12860
12765
|
label: "new packages without docs",
|
|
12861
12766
|
detail: `${newPackages.join(", ")}: add a docs page under docs/ in this PR, or a scoped follow-up right after`
|
|
12862
12767
|
});
|
|
12863
|
-
|
|
12768
|
+
const subjects = [io.env["PR_TITLE"] ?? "", ...io.subjects(base)].filter(Boolean);
|
|
12769
|
+
if (!isFeat(subjects)) {
|
|
12864
12770
|
ctx.say({
|
|
12865
12771
|
status: "ok",
|
|
12866
12772
|
label: "feature docs",
|
|
@@ -14025,6 +13931,80 @@ async function runProbe(input) {
|
|
|
14025
13931
|
rows
|
|
14026
13932
|
};
|
|
14027
13933
|
}
|
|
13934
|
+
// src/commands/probe/specs/real-specs-io.ts
|
|
13935
|
+
/** The `specs check` probe's inputs from the real filesystem under `repoRoot`. */
|
|
13936
|
+
function realSpecsIo(repoRoot) {
|
|
13937
|
+
/* v8 ignore start -- reads the real filesystem; the probe is tested with an injected io */
|
|
13938
|
+
return {
|
|
13939
|
+
list: (dir) => {
|
|
13940
|
+
try {
|
|
13941
|
+
return readdirSync(join(repoRoot, dir));
|
|
13942
|
+
} catch {
|
|
13943
|
+
return [];
|
|
13944
|
+
}
|
|
13945
|
+
},
|
|
13946
|
+
read: (path) => {
|
|
13947
|
+
try {
|
|
13948
|
+
return readFileSync(join(repoRoot, path), "utf8");
|
|
13949
|
+
} catch {
|
|
13950
|
+
return;
|
|
13951
|
+
}
|
|
13952
|
+
},
|
|
13953
|
+
repoPath: (arg) => relative(repoRoot, resolve(arg)).split("\\").join("/")
|
|
13954
|
+
};
|
|
13955
|
+
/* v8 ignore stop */
|
|
13956
|
+
}
|
|
13957
|
+
// src/commands/probe/specs/specs-probe.ts
|
|
13958
|
+
/** The group of probes that check the repo's written decisions and designs. */
|
|
13959
|
+
const SPECS_PROVIDER = "specs";
|
|
13960
|
+
/** The files to read: the ones named, or every file in the ADR and spec folders. A named file that is gone is dropped. */
|
|
13961
|
+
function filesToRead(args, io) {
|
|
13962
|
+
return (args.length > 0 ? args.map((arg) => io.repoPath(arg)) : [ADR_DIR, ...SPEC_DIRS].flatMap((dir) => io.list(dir).sort().map((name) => `${dir}/${name}`))).flatMap((path) => {
|
|
13963
|
+
const text = io.read(path);
|
|
13964
|
+
return text === void 0 ? [] : [{
|
|
13965
|
+
path,
|
|
13966
|
+
text
|
|
13967
|
+
}];
|
|
13968
|
+
});
|
|
13969
|
+
}
|
|
13970
|
+
/**
|
|
13971
|
+
* `specs check [files...]`: validates the frontmatter of the ADRs (`docs/wiki/decisions/*.md`, other than the template and
|
|
13972
|
+
* the README) and specs (`.notes/*.spec.md` and `docs/wiki/specifications/*.spec.md`). Without files it reads every ADR
|
|
13973
|
+
* and spec; with files it checks the ones among them that are an ADR or a spec, and ignores the rest. An error fails
|
|
13974
|
+
* the run (a bad or missing `id`, `title`, `status` or `date`, an unknown status, no frontmatter); a warning is
|
|
13975
|
+
* reported and never fails it (an accepted ADR with no discussion link, a spec with no issue). This is the `adrs` job of
|
|
13976
|
+
* `platform.repoValidation`; the rules are `checkSpecs` in `@theholocron/astromech/repo-validation`, which Sentinel runs on
|
|
13977
|
+
* a pull request's files too.
|
|
13978
|
+
*/
|
|
13979
|
+
function specsCheckProbe(io) {
|
|
13980
|
+
return {
|
|
13981
|
+
summary: "Fail for each ADR or spec with bad frontmatter; warn on a missing discussion link or issue (CI runs this).",
|
|
13982
|
+
writes: false,
|
|
13983
|
+
async run(ctx) {
|
|
13984
|
+
ctx.say({
|
|
13985
|
+
status: "heading",
|
|
13986
|
+
label: "ADRs and specs"
|
|
13987
|
+
});
|
|
13988
|
+
const { fileCount, findings } = checkSpecs(filesToRead(ctx.args ?? [], io));
|
|
13989
|
+
for (const f of findings) ctx.say({
|
|
13990
|
+
status: f.severity === "error" ? "fail" : "info",
|
|
13991
|
+
label: `${f.file}:${f.line}`,
|
|
13992
|
+
detail: `${f.reason} [${f.rule}]`
|
|
13993
|
+
});
|
|
13994
|
+
const errors = findings.filter((f) => f.severity === "error").length;
|
|
13995
|
+
const counts = `${fileCount} file(s) checked, ${errors} error(s), ${findings.length - errors} warning(s)`;
|
|
13996
|
+
ctx.say({
|
|
13997
|
+
status: errors === 0 ? "ok" : "info",
|
|
13998
|
+
label: "frontmatter",
|
|
13999
|
+
detail: counts
|
|
14000
|
+
});
|
|
14001
|
+
}
|
|
14002
|
+
};
|
|
14003
|
+
}
|
|
14004
|
+
/** The `specs` probes: the ADR and spec frontmatter check, over `io`. */
|
|
14005
|
+
function specsProbes(io) {
|
|
14006
|
+
return { check: specsCheckProbe(io) };
|
|
14007
|
+
}
|
|
14028
14008
|
// src/commands/probe/probe.ts
|
|
14029
14009
|
/**
|
|
14030
14010
|
* `holocron probe [<provider> [<probe>]]`. With nothing, lists what can be probed; with a provider, lists its probes;
|
|
@@ -14046,6 +14026,7 @@ async function runProbeCommand(input) {
|
|
|
14046
14026
|
groups.set(DEPS_PROVIDER, depsProbes(input.context.repoRoot, print));
|
|
14047
14027
|
groups.set(GENERATED_PROVIDER, generatedProbes(input.loaded, input.context.repoRoot));
|
|
14048
14028
|
groups.set("ci", ciProbes(input.context.org));
|
|
14029
|
+
groups.set(SPECS_PROVIDER, specsProbes(realSpecsIo(input.context.repoRoot)));
|
|
14049
14030
|
if (!input.provider) {
|
|
14050
14031
|
if (input.pick) await input.pick(groups);
|
|
14051
14032
|
else for (const line of listProbes(groups)) print(line);
|
|
@@ -14570,7 +14551,7 @@ cp .agents/skills/adr/assets/template.md docs/wiki/decisions/000N-short-title.md
|
|
|
14570
14551
|
\`\`\`
|
|
14571
14552
|
|
|
14572
14553
|
\`madr\` has no CLI — creation is manual. Frontmatter is validated in CI
|
|
14573
|
-
via \`
|
|
14554
|
+
via \`holocron probe specs check\` (the \`adrs\` job of \`platform.repoValidation\`).
|
|
14574
14555
|
|
|
14575
14556
|
## Status values
|
|
14576
14557
|
|