@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 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
- if (!isFeat([io.env["PR_TITLE"] ?? "", ...io.subjects(base)].filter(Boolean))) {
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 \`scripts/validate-adrs.mjs\` (runs as part of the Lint workflow).
14554
+ via \`holocron probe specs check\` (the \`adrs\` job of \`platform.repoValidation\`).
14574
14555
 
14575
14556
  ## Status values
14576
14557