@davidvornholt/standards 0.10.0 → 0.10.2

package/src/cli.ts

@@ -4,10 +4,11 @@
 // davidvornholt/standards template into a consumer repo and detects local
 // tampering with them. See the standards repository README for the design.
 //
-// This script is intentionally zero-dependency (Bun + Node built-ins only) and
-// does NOT use Effect: `bunx` must be able to execute the published package
-// before a consumer has dependencies. That is the documented exception to the
-// repo's Effect standard for standalone bootstrap tooling.
+// This bootstrap executable keeps its runtime surface minimal and does not use
+// Effect: `bunx` must be able to execute the published package before a
+// consumer has dependencies. Its strict YAML parser is a declared runtime
+// dependency. This is the documented exception to the repo's Effect standard
+// for standalone bootstrap tooling.
 
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
@@ -32,21 +33,28 @@ import {
   sep,
 } from 'node:path';
 import process from 'node:process';
+import {
+  composeDependabot,
+  DEPENDABOT_BASE_FILE,
+  DEPENDABOT_FILE,
+  DEPENDABOT_LOCAL_FILE,
+} from './dependabot-compose';
+import { inspectDependabot } from './dependabot-inspect';
 import { CANONICAL_SETTINGS_FILE, LOCAL_SETTINGS_FILE } from './github-api';
 import { runGithubApply, runGithubCheck } from './github-commands';
 import { loadGithubSettings } from './github-settings';
+import { isNonEmptyString, isRecord } from './github-settings-parse';
 import { collectStructureProblems } from './structure-check';
 import type { StructureProfile } from './structure-profile';
 import { hasSafeCommand } from './structure-script';
 
-const { YAML: BunYaml } = await import('bun');
-
 const DEFAULT_UPSTREAM = 'github:davidvornholt/standards';
 
 // Characters of a sha256 hex digest shown in drift reports; enough to identify.
 const HASH_PREVIEW_LENGTH = 12;
 
 const GITHUB_PREFIX = 'github:';
+const SKIP_GITHUB_CHECK_ENV = 'STANDARDS_SKIP_GITHUB_CHECK';
 
 // Never mirrored, even under a managed directory path: build output, VCS
 // metadata, and installed dependencies would otherwise pollute the lock when
@@ -79,6 +87,7 @@ type Source = {
 
 type Command =
   | 'check'
+  | 'dependabot'
   | 'doctor'
   | 'github'
   | 'help'
@@ -93,6 +102,7 @@ type CliOptions = {
   readonly from: string | undefined;
   readonly ref: string | undefined;
   readonly apply: boolean;
+  readonly write: boolean;
   readonly profile: StructureProfile;
 };
 
@@ -403,6 +413,12 @@ const runInit = async (
 ): Promise<void> => {
   const seeds = await seedTargets(src.dir, manifest.seedDir);
   assertDisjoint(manifest.paths, [...seeds.keys()]);
+  const prospectiveDependabot = await prepareProspectiveDependabot(
+    manifest,
+    src.dir,
+    consumer,
+    seeds.get(DEPENDABOT_LOCAL_FILE) ?? null,
+  );
   await Promise.all(
     [...seeds].map(async ([rel, abs]) => {
       const dest = join(consumer, rel);
@@ -423,6 +439,7 @@ const runInit = async (
     dryRun: false,
   });
   reportMirror(result, false);
+  await applyProspectiveDependabot(consumer, prospectiveDependabot, false);
   await writeLock(consumer, {
     upstream: manifest.upstream,
     sha: src.sha,
@@ -441,6 +458,12 @@ const runSync = async (
 ): Promise<void> => {
   const seeds = await seedTargets(src.dir, manifest.seedDir);
   assertDisjoint(manifest.paths, [...seeds.keys()]);
+  const prospectiveDependabot = await prepareProspectiveDependabot(
+    manifest,
+    src.dir,
+    consumer,
+    null,
+  );
   const lock = await readLock(consumer);
   const result = await mirror({
     manifest,
@@ -450,6 +473,7 @@ const runSync = async (
     dryRun,
   });
   reportMirror(result, dryRun);
+  await applyProspectiveDependabot(consumer, prospectiveDependabot, dryRun);
   if (dryRun) {
     return;
   }
@@ -510,177 +534,159 @@ const runCheck = async (consumer: string): Promise<boolean> => {
 const readTextIfPresent = async (path: string): Promise<string | null> =>
   existsSync(path) ? readFile(path, 'utf8') : null;
 
-const DEPENDABOT_BASELINE_ECOSYSTEMS = ['bun', 'github-actions'] as const;
-const DEPENDABOT_SCHEDULE_INTERVALS = new Set([
-  'daily',
-  'weekly',
-  'monthly',
-  'quarterly',
-  'semiannually',
-  'yearly',
-  'cron',
-]);
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
-
-const isNonEmptyString = (value: unknown): value is string =>
-  typeof value === 'string' && value.length > 0;
-
-type DependabotUpdateInspection = {
-  readonly problems: ReadonlyArray<string>;
-  readonly rootEcosystem: string | null;
+type DependabotSources = {
+  readonly base: string | null;
+  readonly local: string | null;
+  readonly current: string | null;
 };
 
-const inspectDependabotSchedule = (
-  schedule: unknown,
-  label: string,
-): ReadonlyArray<string> => {
-  if (!(isRecord(schedule) && isNonEmptyString(schedule.interval))) {
-    return [`${label} must define schedule.interval`];
-  }
-  if (!DEPENDABOT_SCHEDULE_INTERVALS.has(schedule.interval)) {
-    return [`${label} has an unsupported schedule.interval`];
-  }
-  if (schedule.interval === 'cron' && !isNonEmptyString(schedule.cronjob)) {
-    return [`${label} must define schedule.cronjob for a cron interval`];
-  }
-  return [];
-};
-
-type DependabotGroupInspection = {
+const readDependabotSources = async (
+  consumer: string,
+): Promise<DependabotSources> => ({
+  base: await readTextIfPresent(join(consumer, DEPENDABOT_BASE_FILE)),
+  local: await readTextIfPresent(join(consumer, DEPENDABOT_LOCAL_FILE)),
+  current: await readTextIfPresent(join(consumer, DEPENDABOT_FILE)),
+});
+
+// Compose the generated Dependabot config from its on-disk sources, folding
+// Dependabot semantic validation into the same problem list.
+const composedDependabot = (
+  sources: DependabotSources,
+): {
+  readonly composed: string | null;
   readonly problems: ReadonlyArray<string>;
-  readonly scheduledGroups: ReadonlySet<string>;
-};
-
-const inspectDependabotGroups = (
-  groups: unknown,
-): DependabotGroupInspection => {
-  if (groups === undefined) {
-    return { problems: [], scheduledGroups: new Set() };
-  }
-  if (!isRecord(groups)) {
+} => {
+  if (sources.base === null) {
     return {
+      composed: null,
       problems: [
-        '.github/dependabot.yml multi-ecosystem-groups must be a mapping',
+        `${DEPENDABOT_BASE_FILE} must exist; run \`bun standards sync\` to mirror it in`,
       ],
-      scheduledGroups: new Set(),
     };
   }
-
-  const problems: Array<string> = [];
-  const scheduledGroups = new Set<string>();
-  for (const [name, group] of Object.entries(groups)) {
-    const label = `.github/dependabot.yml multi-ecosystem-groups.${name}`;
-    const groupProblems = isRecord(group)
-      ? inspectDependabotSchedule(group.schedule, label)
-      : [`${label} must be a mapping`];
-    problems.push(...groupProblems);
-    if (groupProblems.length === 0) {
-      scheduledGroups.add(name);
-    }
+  const result = composeDependabot(sources.base, sources.local);
+  if (result.composed === null) {
+    return result;
   }
-  return { problems, scheduledGroups };
+  const problems = inspectDependabot(result.composed);
+  return problems.length > 0 ? { composed: null, problems } : result;
 };
 
-const inspectDependabotUpdate = (
-  update: unknown,
-  index: number,
-  scheduledGroups: ReadonlySet<string>,
-): DependabotUpdateInspection => {
-  const label = `.github/dependabot.yml updates[${index}]`;
-  if (!isRecord(update)) {
-    return { problems: [`${label} must be a mapping`], rootEcosystem: null };
-  }
-
-  const {
-    directory,
-    directories,
-    schedule,
-    'multi-ecosystem-group': multiEcosystemGroup,
-    'package-ecosystem': ecosystem,
-  } = update;
-  const problems: Array<string> = [];
-  if (!isNonEmptyString(ecosystem)) {
-    problems.push(`${label} must define package-ecosystem`);
+const dependabotProblems = async (
+  consumer: string,
+): Promise<ReadonlyArray<string>> => {
+  const sources = await readDependabotSources(consumer);
+  const { composed, problems } = composedDependabot(sources);
+  if (composed === null) {
+    return problems;
   }
-
-  const hasDirectory = isNonEmptyString(directory);
-  const hasDirectories =
-    Array.isArray(directories) &&
-    directories.length > 0 &&
-    directories.every(isNonEmptyString);
-  if (hasDirectory === hasDirectories) {
-    problems.push(
-      `${label} must define exactly one of directory or directories`,
-    );
+  if (sources.current !== composed) {
+    return [
+      `${DEPENDABOT_FILE} does not match its composed sources; regenerate it with \`bun standards dependabot --write\``,
+    ];
   }
+  return [];
+};
 
-  if (schedule === undefined && isNonEmptyString(multiEcosystemGroup)) {
-    if (!scheduledGroups.has(multiEcosystemGroup)) {
-      problems.push(
-        `${label} must reference a scheduled multi-ecosystem group`,
-      );
-    }
-  } else {
-    problems.push(...inspectDependabotSchedule(schedule, label));
-  }
+const writeComposedDependabot = async (
+  consumer: string,
+  composed: string,
+): Promise<void> => {
+  const dest = join(consumer, DEPENDABOT_FILE);
+  await mkdir(dirname(dest), { recursive: true });
+  await writeFile(dest, composed);
+};
 
-  const targetsRoot =
-    directory === '/' ||
-    (Array.isArray(directories) && directories.includes('/'));
-  return {
-    problems,
-    rootEcosystem:
-      isNonEmptyString(ecosystem) && targetsRoot ? ecosystem : null,
-  };
+const composeProblemsError = (problems: ReadonlyArray<string>): Error =>
+  new Error(
+    [
+      `cannot compose ${DEPENDABOT_FILE}:`,
+      ...problems.map((problem) => `  - ${problem}`),
+    ].join('\n'),
+  );
+
+type ProspectiveDependabot = {
+  readonly composed: string;
+  readonly current: string | null;
 };
 
-const inspectDependabot = (raw: string): ReadonlyArray<string> => {
-  const problems: Array<string> = [];
-  let config: unknown;
-  try {
-    config = BunYaml.parse(raw);
-  } catch {
-    return ['.github/dependabot.yml must contain valid YAML'];
+// Validate the incoming canonical base against the effective local overlay
+// before init/sync mutates any consumer-owned, canonical, generated, or lock
+// file. For init, an existing overlay wins; otherwise the overlay seed is what
+// the command is about to install.
+const prepareProspectiveDependabot = async (
+  manifest: Manifest,
+  srcDir: string,
+  consumer: string,
+  localSeed: string | null,
+): Promise<ProspectiveDependabot> => {
+  const incoming = await listManaged(srcDir, manifest.paths);
+  const basePath = incoming.get(DEPENDABOT_BASE_FILE);
+  if (basePath === undefined) {
+    throw new Error(
+      `source content must manage ${DEPENDABOT_BASE_FILE}; @davidvornholt/standards 0.10.1 requires a 0.10.1-compatible content ref`,
+    );
+  }
+  const existingLocal = await readTextIfPresent(
+    join(consumer, DEPENDABOT_LOCAL_FILE),
+  );
+  const local =
+    existingLocal ??
+    (localSeed === null ? null : await readFile(localSeed, 'utf8'));
+  const current = await readTextIfPresent(join(consumer, DEPENDABOT_FILE));
+  const sources = {
+    base: await readFile(basePath, 'utf8'),
+    local,
+    current,
+  };
+  const { composed, problems } = composedDependabot(sources);
+  if (composed === null) {
+    throw composeProblemsError(problems);
   }
+  return { composed, current };
+};
 
-  if (!isRecord(config)) {
-    return ['.github/dependabot.yml must contain a YAML mapping'];
+const applyProspectiveDependabot = async (
+  consumer: string,
+  prospective: ProspectiveDependabot,
+  dryRun: boolean,
+): Promise<void> => {
+  if (prospective.current === prospective.composed) {
+    return;
   }
-  if (config.version !== 2) {
-    problems.push('.github/dependabot.yml must use version: 2');
+  if (dryRun) {
+    console.log(`  would generate ${DEPENDABOT_FILE}`);
+    return;
   }
+  await writeComposedDependabot(consumer, prospective.composed);
+  console.log(`  generated ${DEPENDABOT_FILE}`);
+};
 
-  const { updates, 'multi-ecosystem-groups': multiEcosystemGroups } = config;
-  if (!Array.isArray(updates)) {
-    problems.push('.github/dependabot.yml must define an updates list');
-    return problems;
+const runDependabotCheck = async (consumer: string): Promise<boolean> => {
+  const problems = await dependabotProblems(consumer);
+  if (problems.length > 0) {
+    console.error(`standards dependabot: ${problems.length} problem(s):`);
+    console.error(problems.map((problem) => `  - ${problem}`).join('\n'));
+    return false;
   }
+  console.log(
+    `standards dependabot: ${DEPENDABOT_FILE} matches its composed sources`,
+  );
+  return true;
+};
 
-  const groupInspection = inspectDependabotGroups(multiEcosystemGroups);
-  problems.push(...groupInspection.problems);
-  const rootEcosystems = new Set<string>();
-  for (const [index, update] of updates.entries()) {
-    const inspection = inspectDependabotUpdate(
-      update,
-      index,
-      groupInspection.scheduledGroups,
-    );
-    problems.push(...inspection.problems);
-    if (inspection.rootEcosystem !== null) {
-      rootEcosystems.add(inspection.rootEcosystem);
-    }
+const runDependabotWrite = async (consumer: string): Promise<void> => {
+  const sources = await readDependabotSources(consumer);
+  const { composed, problems } = composedDependabot(sources);
+  if (composed === null) {
+    throw composeProblemsError(problems);
   }
-
-  for (const ecosystem of DEPENDABOT_BASELINE_ECOSYSTEMS) {
-    if (!rootEcosystems.has(ecosystem)) {
-      problems.push(
-        `.github/dependabot.yml must include a root-directory ${ecosystem} ecosystem`,
-      );
-    }
+  if (sources.current === composed) {
+    console.log(`standards dependabot: ${DEPENDABOT_FILE} is up to date`);
+    return;
   }
-  return problems;
+  await writeComposedDependabot(consumer, composed);
+  console.log(`standards dependabot: generated ${DEPENDABOT_FILE}`);
 };
 
 const inspectPackageJson = (packageRaw: string): ReadonlyArray<string> => {
@@ -726,14 +732,7 @@ const runDoctor = async (consumer: string): Promise<boolean> => {
     problems.push('AGENTS.local.md must exist for project-specific guidance');
   }
 
-  const dependabot = await readTextIfPresent(
-    join(consumer, '.github/dependabot.yml'),
-  );
-  if (dependabot === null) {
-    problems.push('.github/dependabot.yml must exist');
-  } else {
-    problems.push(...inspectDependabot(dependabot));
-  }
+  problems.push(...(await dependabotProblems(consumer)));
 
   const packagePath = join(consumer, 'package.json');
   const packageRaw = await readTextIfPresent(packagePath);
@@ -773,13 +772,14 @@ const runDoctor = async (consumer: string): Promise<boolean> => {
 const USAGE = `Usage: standards <command> [options]
 
 Commands:
-  init       Bootstrap a consumer repo: seed repo-owned files, mirror canonical files, write the lock
-  sync       Mirror canonical files from upstream and rewrite the lock
-  check      Verify canonical files, extension seams, monorepo structure, and GitHub settings
-  doctor     Validate extension seams only
-  structure  Validate monorepo structure rules only
-  github     Compare (--check) or converge (--apply) live GitHub settings
-  help       Show this help
+  init        Bootstrap a consumer repo: seed repo-owned files, mirror canonical files, write the lock
+  sync        Mirror canonical files from upstream, regenerate the composed Dependabot config, and rewrite the lock
+  check       Verify canonical files, extension seams, monorepo structure, and GitHub settings
+  doctor      Validate extension seams only
+  structure   Validate monorepo structure rules only
+  dependabot  Verify (--check) or regenerate (--write) the composed .github/dependabot.yml
+  github      Compare (--check) or converge (--apply) live GitHub settings
+  help        Show this help
 
 Options:
   --dir <path>   Consumer directory to operate on (default: current directory)
@@ -787,12 +787,14 @@ Options:
   --from <src>   Upstream override for init/sync (GitHub repo or local path)
   --ref <ref>    Upstream tag, branch, or full commit sha for init/sync (remote Git/GitHub sources only; default: main)
   --dry-run      Preview a sync without writing anything
-  --check        With github: compare live settings to the declaration (default)
-  --apply        With github: converge the live repository (needs admin auth)`;
+  --check        With github/dependabot: compare against the declared sources (default)
+  --apply        With github: converge the live repository (needs admin auth)
+  --write        With dependabot: regenerate the composed .github/dependabot.yml`;
 
 const commandFromArg = (arg: string): Command => {
   if (
     arg === 'check' ||
+    arg === 'dependabot' ||
     arg === 'doctor' ||
     arg === 'github' ||
     arg === 'help' ||
@@ -832,6 +834,44 @@ const nextOptionValue = (
   return value;
 };
 
+type ParsedFlags = {
+  readonly command: Command | undefined;
+  readonly checkFlag: boolean;
+  readonly apply: boolean;
+  readonly write: boolean;
+  readonly ref: string | undefined;
+  readonly profile: StructureProfile | undefined;
+};
+
+// Every option is only meaningful with specific commands; reject the rest so a
+// typo fails loudly instead of silently doing the default thing.
+const assertOptionUsage = (flags: ParsedFlags): void => {
+  const { command, checkFlag, apply, write, ref, profile } = flags;
+  if (checkFlag && command !== 'github' && command !== 'dependabot') {
+    throw new Error(
+      '--check is only valid with the github and dependabot commands',
+    );
+  }
+  if (apply && command !== 'github') {
+    throw new Error('--apply is only valid with the github command');
+  }
+  if (apply && checkFlag) {
+    throw new Error('github accepts exactly one of --check or --apply');
+  }
+  if (write && command !== 'dependabot') {
+    throw new Error('--write is only valid with the dependabot command');
+  }
+  if (write && checkFlag) {
+    throw new Error('dependabot accepts exactly one of --check or --write');
+  }
+  if (ref !== undefined && command !== 'init' && command !== 'sync') {
+    throw new Error('--ref is only valid with the init and sync commands');
+  }
+  if (profile !== undefined && command !== 'structure') {
+    throw new Error('--profile is only valid with the structure command');
+  }
+};
+
 const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
   let command: Command | undefined;
   let consumer = process.cwd();
@@ -840,6 +880,7 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
   let ref: string | undefined;
   let checkFlag = false;
   let apply = false;
+  let write = false;
   let profile: StructureProfile | undefined;
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -851,6 +892,9 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
       case '--check':
         checkFlag = true;
         break;
+      case '--write':
+        write = true;
+        break;
       case '--dir':
         consumer = nextOptionValue(argv, index);
         index += 1;
@@ -879,21 +923,7 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
     }
   }
 
-  if (checkFlag && command !== 'github') {
-    throw new Error('--check is only valid with the github command');
-  }
-  if (apply && command !== 'github') {
-    throw new Error('--apply is only valid with the github command');
-  }
-  if (apply && checkFlag) {
-    throw new Error('github accepts exactly one of --check or --apply');
-  }
-  if (ref !== undefined && command !== 'init' && command !== 'sync') {
-    throw new Error('--ref is only valid with the init and sync commands');
-  }
-  if (profile !== undefined && command !== 'structure') {
-    throw new Error('--profile is only valid with the structure command');
-  }
+  assertOptionUsage({ command, checkFlag, apply, write, ref, profile });
 
   return {
     command,
@@ -902,6 +932,7 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
     from,
     ref,
     apply,
+    write,
     profile: profile ?? 'consumer',
   };
 };
@@ -934,13 +965,27 @@ const runCheckCommand = async (consumer: string): Promise<boolean> => {
   // closed: once .github/settings.json exists, an unreachable API or an
   // unreadable origin is a failure, not a skip.
   const githubIsConverged = existsSync(join(consumer, CANONICAL_SETTINGS_FILE))
-    ? await runGithubCheck(consumer)
+    ? await runGithubCheckGate(consumer)
     : true;
   return (
     driftIsClean && integrationIsValid && structureIsValid && githubIsConverged
   );
 };
 
+// The canonical workflow sets this only for its unprivileged quality job,
+// where a separate isolated job runs the same live check with the admin-read
+// token. Absent that exact workflow seam, local and explicit checks remain
+// fail-closed.
+const runGithubCheckGate = (consumer: string): Promise<boolean> => {
+  if (process.env[SKIP_GITHUB_CHECK_ENV] === 'true') {
+    console.log(
+      `standards github: live settings check skipped because ${SKIP_GITHUB_CHECK_ENV}=true; the canonical workflow's isolated github-settings job must own this check`,
+    );
+    return Promise.resolve(true);
+  }
+  return runGithubCheck(consumer);
+};
+
 // Consumer-owned sync policy, checked in next to the canonical (read-only)
 // standards-sync workflow it configures — versioned and reviewable, unlike
 // repository Actions variables. All fields are optional; a missing file means
@@ -1069,7 +1114,7 @@ const runSyncCommand = async (
 
 // Commands whose success is reported through the exit code.
 const runGateCommand = (
-  command: 'check' | 'doctor' | 'github' | 'structure',
+  command: 'check' | 'dependabot' | 'doctor' | 'github' | 'structure',
   consumer: string,
   apply: boolean,
   profile: StructureProfile,
@@ -1077,19 +1122,21 @@ const runGateCommand = (
   if (command === 'check') {
     return runCheckCommand(consumer);
   }
+  if (command === 'dependabot') {
+    return runDependabotCheck(consumer);
+  }
   if (command === 'doctor') {
     return runDoctor(consumer);
   }
   if (command === 'structure') {
     return runStructure(consumer, profile);
   }
-  return apply ? runGithubApply(consumer) : runGithubCheck(consumer);
+  return apply ? runGithubApply(consumer) : runGithubCheckGate(consumer);
 };
 
 const main = async (): Promise<void> => {
-  const { command, consumer, dryRun, from, ref, apply, profile } = parseArgs(
-    process.argv.slice(2),
-  );
+  const { command, consumer, dryRun, from, ref, apply, write, profile } =
+    parseArgs(process.argv.slice(2));
 
   if (command === undefined) {
     console.error('standards: a command is required\n');
@@ -1113,6 +1160,11 @@ const main = async (): Promise<void> => {
     return;
   }
 
+  if (command === 'dependabot' && write) {
+    await runDependabotWrite(consumer);
+    return;
+  }
+
   if (!(await runGateCommand(command, consumer, apply, profile))) {
     process.exitCode = 1;
   }