@vivswan/github-settings-as-code 2.0.1-main.1072.gfded5f5 → 2.0.1-main.1074.gc449c5c

package/lib/pkg/cli.js

@@ -285,32 +285,98 @@ function inputsForMode(mode) {
 	};
 	return INPUT_NAMES.filter((name) => !hidden.includes(name) && reads(name));
 }
+/** A mode's subcommand: its flags are the inputs the mode reads. */
+function modeSubcommand(mode) {
+	return {
+		flags: new Set(inputsForMode(mode)),
+		mode
+	};
+}
 /**
-* The init subcommand's flags: the snapshot inputs of one repository, with
-* settings-file as the destination in place of snapshot-file. Filtered from
-* the declarations so the help keeps their order.
+* The init subcommand: the snapshot inputs of one repository, with
+* settings-file as the destination in place of snapshot-file. No mode runs
+* it, so the clauses restricted to modes leave its help.
 */
-const INIT_FLAGS = /* @__PURE__ */ new Set([
-	"repository",
-	"settings-file",
-	"on-missing-permission",
-	"sections",
-	"api-version"
-]);
-const INIT_INPUTS = INPUT_NAMES.filter((name) => INIT_FLAGS.has(name));
+const INIT_SUBCOMMAND = {
+	flags: /* @__PURE__ */ new Set([
+		"repository",
+		"settings-file",
+		"on-missing-permission",
+		"sections",
+		"api-version"
+	]),
+	mode: null
+};
+/** init's flags in declaration order, the order the help keeps. */
+const INIT_INPUTS = INPUT_NAMES.filter((name) => INIT_SUBCOMMAND.flags.has(name));
 /**
 * init's one reworded flag: the declaration describes the file apply and check
 * READ, and init WRITES it; every other init flag keeps its declared text.
 */
 const INIT_SETTINGS_FILE_DESCRIPTION = "Where the settings document is written: the file apply and check read. One path; an existing file is kept unless --force is passed.";
+/** `text` as the declaration spells it; a reworded declaration fails here rather than leave the help stale. */
+function declared(input, text) {
+	if (!INPUT_DECLS[input].description.includes(text)) throw new Error(`BUG: the ${input} input's description no longer says "${text}"; reword the CLI's clause with it`);
+	return text;
+}
+const MULTI_REPO_FLAGS = ["repos", "repos-dir"];
+const CLAUSES = [
+	{
+		input: "repository",
+		text: declared("repository", " Single-repo mode only; cannot be combined with repos or repos-dir."),
+		flags: MULTI_REPO_FLAGS
+	},
+	{
+		input: "settings-file",
+		text: declared("settings-file", " Single-repo and merge modes only; multi-repo targets read repos-dir files or each repository's own .github/settings.yml, so overriding it alongside repos or repos-dir fails the run."),
+		flags: MULTI_REPO_FLAGS
+	},
+	{
+		input: "snapshot-dir",
+		text: declared("snapshot-dir", "; defaults-file does not apply"),
+		flags: ["defaults-file"]
+	},
+	{
+		input: "sections",
+		text: declared("sections", " apply, check, and snapshot only: mode: merge writes every section its layers declare, so the allowlist belongs on the step that runs the merged document and fails the merge when set."),
+		modes: [
+			"apply",
+			"check",
+			"snapshot"
+		]
+	},
+	{
+		input: "private-report",
+		text: declared("private-report", " Under artifact, those reports are concatenated, age-encrypted to report-public-key, and uploaded as one workflow artifact (settings-as-code-private-report) for readers who hold the key but no GitHub access to the targets; the artifact channel needs the Actions artifact service, so on GitHub Enterprise Server it warns and uploads nothing."),
+		flags: ["report-public-key"]
+	},
+	{
+		input: "private-report",
+		text: declared("private-report", "issue, issue-on-failure, or artifact."),
+		replacement: "issue, or issue-on-failure.",
+		flags: ["report-public-key"]
+	}
+];
+function meets(subcommand, clause) {
+	const flags = (clause.flags ?? []).every((flag) => subcommand.flags.has(flag));
+	const mode = clause.modes === void 0 || subcommand.mode !== null && clause.modes.includes(subcommand.mode);
+	return flags && mode;
+}
 /** The sentence the action's `repository` description spends on a default a terminal never has. */
-const ACTIONS_DEFAULT_SENTENCE = "Defaults to the current repository.";
-const CLI_REPOSITORY_SENTENCE = "Required unless repos or repos-dir is set (inside GitHub Actions, GITHUB_REPOSITORY supplies it).";
-if (!INPUT_DECLS.repository.description.includes(ACTIONS_DEFAULT_SENTENCE)) throw new Error(`BUG: the repository input's description no longer says "${ACTIONS_DEFAULT_SENTENCE}"; reword the CLI's replacement with it`);
-/** The flag's help text: the declaration's, reworded where it assumes the Actions runner. */
-function inputDescription(name) {
-	const description = INPUT_DECLS[name].description;
-	return name === "repository" ? description.replace(ACTIONS_DEFAULT_SENTENCE, CLI_REPOSITORY_SENTENCE) : description;
+const ACTIONS_DEFAULT_SENTENCE = declared("repository", "Defaults to the current repository.");
+/**
+* A flag's help text under `subcommand`: the declaration's, minus the clauses
+* about flags and modes the subcommand lacks, and reworded where it assumes
+* the Actions runner.
+*/
+function inputDescription(name, subcommand) {
+	let description = INPUT_DECLS[name].description;
+	for (const clause of CLAUSES) if (clause.input === name && !meets(subcommand, clause)) description = description.replace(clause.text, clause.replacement ?? "");
+	if (name === "repository") {
+		const unless = MULTI_REPO_FLAGS.every((flag) => subcommand.flags.has(flag)) ? " unless repos or repos-dir is set" : "";
+		description = description.replace(ACTIONS_DEFAULT_SENTENCE, `Required${unless} (inside GitHub Actions, GITHUB_REPOSITORY supplies it).`);
+	}
+	return description;
 }
 /** Whether the declaration is a list; read through InputDecl since only the list members carry the field. */
 function isList(name) {
@@ -328,16 +394,16 @@ function once(flag) {
 	};
 }
 /**
-* The commander option for one input: `--<name> <value>`, repeatable when the
-* declaration is a list; `description` replaces the declaration's where a
-* subcommand reads the input for another purpose.
+* The commander option for one input under `subcommand`: `--<name> <value>`,
+* repeatable when the declaration is a list; `description` replaces the
+* declaration's where the subcommand reads the input for another purpose.
 */
-function inputOption(name, description = inputDescription(name)) {
+function inputOption(name, subcommand, description = inputDescription(name, subcommand)) {
 	const parse = isList(name) ? accumulate : once(name);
 	return new Option(`--${name} <value>`, description).argParser(parse);
 }
 /** Commander's attribute for each flag (camelCase of the name), read from commander itself. */
-const ATTRIBUTE = Object.fromEntries(INPUT_NAMES.map((name) => [name, inputOption(name).attributeName()]));
+const ATTRIBUTE = Object.fromEntries(INPUT_NAMES.map((name) => [name, new Option(`--${name} <value>`).attributeName()]));
 /** A flag value as the runner would hand it over: trimmed, as @actions/core trims every input. */
 function inputValue(value) {
 	return typeof value === "string" ? value.trim() : "";
@@ -534,7 +600,8 @@ function buildProgram(options) {
 	};
 	for (const [name, mode] of Object.entries(MODE_COMMANDS)) {
 		const command = program.command(name).description(DESCRIPTION[name]);
-		for (const input of inputsForMode(mode)) command.addOption(inputOption(input));
+		const subcommand = modeSubcommand(mode);
+		for (const input of subcommand.flags) command.addOption(inputOption(input, subcommand));
 		command.action(async function() {
 			const values = this.optsWithGlobals();
 			const { io, flush } = openIo(values);
@@ -544,7 +611,7 @@ function buildProgram(options) {
 		});
 	}
 	const init = program.command("init").description(DESCRIPTION.init);
-	for (const input of INIT_INPUTS) init.addOption(input === "settings-file" ? inputOption(input, INIT_SETTINGS_FILE_DESCRIPTION) : inputOption(input));
+	for (const input of INIT_INPUTS) init.addOption(input === "settings-file" ? inputOption(input, INIT_SUBCOMMAND, INIT_SETTINGS_FILE_DESCRIPTION) : inputOption(input, INIT_SUBCOMMAND));
 	init.option("--force", "Replace the settings file when it already exists; without it, init refuses").action(async function() {
 		const values = this.optsWithGlobals();
 		const { io } = openIo(values);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vivswan/github-settings-as-code",
-  "version": "2.0.1-main.1072.gfded5f5",
+  "version": "2.0.1-main.1074.gc449c5c",
   "description": "GitHub Action applying declarative repository settings: rulesets, labels, branch protection, and more.",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",