@davidvornholt/standards 0.10.0 → 0.10.2

package/src/dependabot-compose-input.ts

@@ -0,0 +1,136 @@
+import {
+  inspectIgnore,
+  inspectRegistryReferences,
+  overlapsUpdateTarget,
+  type UpdateBlock,
+  type UpdateTarget,
+  updateTarget,
+  updateTargetDescription,
+} from './dependabot-update';
+import { isRecord } from './github-settings-parse';
+import { parseYaml } from './yaml-parse';
+
+export type ParsedDependabot = {
+  readonly document: Record<string, unknown>;
+  readonly updates: ReadonlyArray<UpdateBlock>;
+  readonly registries: Record<string, unknown>;
+};
+
+export type ParsedLocal = {
+  readonly updates: ReadonlyArray<UpdateBlock>;
+  readonly registries: Record<string, unknown>;
+};
+
+export type ValidatedUpdate = {
+  readonly block: UpdateBlock;
+  readonly target: UpdateTarget;
+  readonly label: string;
+};
+
+const inspectRegistries = (
+  registries: unknown,
+  label: string,
+  problems: Array<string>,
+): Record<string, unknown> => {
+  if (registries === undefined) {
+    return {};
+  }
+  if (!isRecord(registries)) {
+    problems.push(`${label} registries must be a mapping`);
+    return {};
+  }
+  for (const [name, registry] of Object.entries(registries)) {
+    if (!isRecord(registry)) {
+      problems.push(`${label} registries.${name} must be a mapping`);
+    }
+  }
+  return registries;
+};
+
+export const parseDependabot = (
+  raw: string,
+  label: string,
+  problems: Array<string>,
+): ParsedDependabot | null => {
+  const { value, problem } = parseYaml(raw, label);
+  if (problem !== null) {
+    problems.push(problem);
+    return null;
+  }
+  if (!(isRecord(value) && Array.isArray(value.updates))) {
+    problems.push(`${label} must define an updates list`);
+    return null;
+  }
+  if (!value.updates.every(isRecord)) {
+    problems.push(`${label} updates entries must be mappings`);
+    return null;
+  }
+  return {
+    document: value,
+    updates: value.updates,
+    registries: inspectRegistries(value.registries, label, problems),
+  };
+};
+
+export const parseLocal = (
+  raw: string,
+  label: string,
+  problems: Array<string>,
+): ParsedLocal | null => {
+  const { value, problem } = parseYaml(raw, label);
+  if (problem !== null) {
+    problems.push(problem);
+    return null;
+  }
+  if (value === null || value === undefined) {
+    return { updates: [], registries: {} };
+  }
+  if (!isRecord(value)) {
+    problems.push(`${label} must contain a YAML mapping`);
+    return null;
+  }
+  const unknownKeys = Object.keys(value).filter(
+    (key) => key !== 'updates' && key !== 'registries',
+  );
+  if (unknownKeys.length > 0) {
+    problems.push(
+      `${label} may only define "updates" and "registries"; remove: ${unknownKeys.join(', ')}`,
+    );
+  }
+  const updates = value.updates ?? [];
+  if (!(Array.isArray(updates) && updates.every(isRecord))) {
+    problems.push(`${label} updates must be a list of mappings`);
+    return null;
+  }
+  return {
+    updates,
+    registries: inspectRegistries(value.registries, label, problems),
+  };
+};
+
+export const validateUpdates = (
+  updates: ReadonlyArray<UpdateBlock>,
+  label: string,
+  problems: Array<string>,
+): ReadonlyArray<ValidatedUpdate> => {
+  const validated: Array<ValidatedUpdate> = [];
+  for (const [index, block] of updates.entries()) {
+    const blockLabel = `${label} updates[${index}]`;
+    problems.push(...inspectIgnore(block.ignore, blockLabel));
+    problems.push(...inspectRegistryReferences(block.registries, blockLabel));
+    const target = updateTarget(block, blockLabel, problems);
+    if (target !== null) {
+      validated.push({ block, target, label: blockLabel });
+    }
+  }
+  for (const [index, candidate] of validated.entries()) {
+    for (const earlier of validated.slice(0, index)) {
+      if (overlapsUpdateTarget(candidate.target, earlier.target)) {
+        problems.push(
+          `${candidate.label} overlaps ${earlier.label}: ${updateTargetDescription(candidate.target)}`,
+        );
+      }
+    }
+  }
+  return validated;
+};

package/src/dependabot-compose.ts

@@ -0,0 +1,188 @@
+// Composes the generated .github/dependabot.yml from the canonical base and
+// the optional repo-owned additive overlay.
+
+import {
+  parseDependabot,
+  parseLocal,
+  type ValidatedUpdate,
+  validateUpdates,
+} from './dependabot-compose-input';
+import {
+  overlapsUpdateTarget,
+  sameUpdateTarget,
+  type UpdateBlock,
+  updateTargetDescription,
+} from './dependabot-update';
+import { emitYamlDocument } from './yaml-emit';
+
+export const DEPENDABOT_FILE = '.github/dependabot.yml';
+export const DEPENDABOT_BASE_FILE = '.github/dependabot.base.yml';
+export const DEPENDABOT_LOCAL_FILE = '.github/dependabot.local.yml';
+
+const GENERATED_HEADER = `# GENERATED FILE - do not edit. \`bun standards sync\` (or
+# \`bun standards dependabot --write\`) composes ${DEPENDABOT_BASE_FILE}
+# (canonical) with ${DEPENDABOT_LOCAL_FILE} (repo-owned) into this file.
+`;
+
+const MERGE_KEYS = new Set([
+  'package-ecosystem',
+  'directory',
+  'directories',
+  'target-branch',
+  'ignore',
+  'registries',
+]);
+
+const mergeMatchingBlock = (
+  target: UpdateBlock,
+  local: ValidatedUpdate,
+  problems: Array<string>,
+): void => {
+  const extraKeys = Object.keys(local.block).filter(
+    (key) => !MERGE_KEYS.has(key),
+  );
+  if (extraKeys.length > 0) {
+    problems.push(
+      `${local.label} matches a canonical block and may only add ignore or registries entries; remove: ${extraKeys.join(', ')}`,
+    );
+    return;
+  }
+  const hasIgnore =
+    Array.isArray(local.block.ignore) && local.block.ignore.length > 0;
+  const hasRegistries =
+    local.block.registries === '*' ||
+    (Array.isArray(local.block.registries) &&
+      local.block.registries.length > 0);
+  if (!(hasIgnore || hasRegistries)) {
+    problems.push(
+      `${local.label} matches a canonical block and must add a non-empty ignore or registries list`,
+    );
+    return;
+  }
+  if (hasIgnore) {
+    target.ignore = [
+      ...((target.ignore as ReadonlyArray<unknown> | undefined) ?? []),
+      ...(local.block.ignore as ReadonlyArray<unknown>),
+    ];
+  }
+  if (hasRegistries) {
+    if (target.registries === '*' || local.block.registries === '*') {
+      target.registries = '*';
+    } else {
+      target.registries = [
+        ...new Set([
+          ...((target.registries as ReadonlyArray<string> | undefined) ?? []),
+          ...(local.block.registries as ReadonlyArray<string>),
+        ]),
+      ];
+    }
+  }
+};
+
+const mergeUpdates = (
+  baseUpdates: ReadonlyArray<ValidatedUpdate>,
+  localUpdates: ReadonlyArray<ValidatedUpdate>,
+  problems: Array<string>,
+): Array<UpdateBlock> => {
+  const updates = baseUpdates.map(({ block }) => ({ ...block }));
+  for (const localUpdate of localUpdates) {
+    const matchingIndex = baseUpdates.findIndex(({ target }) =>
+      sameUpdateTarget(target, localUpdate.target),
+    );
+    const overlapping = baseUpdates.find(({ target }) =>
+      overlapsUpdateTarget(target, localUpdate.target),
+    );
+    if (matchingIndex >= 0) {
+      const target = updates[matchingIndex];
+      if (target !== undefined) {
+        mergeMatchingBlock(target, localUpdate, problems);
+      }
+    } else if (overlapping === undefined) {
+      updates.push({ ...localUpdate.block });
+    } else {
+      problems.push(
+        `${localUpdate.label} overlaps ${overlapping.label}: ${updateTargetDescription(localUpdate.target)}`,
+      );
+    }
+  }
+  return updates;
+};
+
+const inspectRegistryReferencesExist = (
+  updates: ReadonlyArray<UpdateBlock>,
+  registryNames: ReadonlySet<string>,
+  problems: Array<string>,
+): void => {
+  for (const [index, update] of updates.entries()) {
+    if (Array.isArray(update.registries)) {
+      const missing = update.registries.filter(
+        (name) => name !== '*' && !registryNames.has(String(name)),
+      );
+      if (missing.length > 0) {
+        problems.push(
+          `${DEPENDABOT_FILE} updates[${index}].registries references undefined registries: ${missing.join(', ')}`,
+        );
+      }
+    }
+  }
+};
+
+export type DependabotCompose = {
+  readonly composed: string | null;
+  readonly problems: ReadonlyArray<string>;
+};
+
+export const composeDependabot = (
+  baseRaw: string,
+  localRaw: string | null,
+): DependabotCompose => {
+  const problems: Array<string> = [];
+  const base = parseDependabot(baseRaw, DEPENDABOT_BASE_FILE, problems);
+  const local =
+    localRaw === null
+      ? { updates: [], registries: {} }
+      : parseLocal(localRaw, DEPENDABOT_LOCAL_FILE, problems);
+  if (base === null || local === null) {
+    return { composed: null, problems };
+  }
+  const baseUpdates = validateUpdates(
+    base.updates,
+    DEPENDABOT_BASE_FILE,
+    problems,
+  );
+  const localUpdates = validateUpdates(
+    local.updates,
+    DEPENDABOT_LOCAL_FILE,
+    problems,
+  );
+  const registryCollisions = Object.keys(local.registries).filter((name) =>
+    Object.hasOwn(base.registries, name),
+  );
+  if (registryCollisions.length > 0) {
+    problems.push(
+      `${DEPENDABOT_LOCAL_FILE} registries collide with canonical registries: ${registryCollisions.join(', ')}`,
+    );
+  }
+  if (problems.length > 0) {
+    return { composed: null, problems };
+  }
+  const updates = mergeUpdates(baseUpdates, localUpdates, problems);
+  const registries = { ...base.registries, ...local.registries };
+  inspectRegistryReferencesExist(
+    updates,
+    new Set(Object.keys(registries)),
+    problems,
+  );
+  if (problems.length > 0) {
+    return { composed: null, problems };
+  }
+  const document = {
+    ...base.document,
+    ...(Object.keys(registries).length > 0 ? { registries } : {}),
+    updates,
+  };
+  return {
+    composed: `${GENERATED_HEADER}${emitYamlDocument(document)}`,
+    problems: [],
+  };
+};

package/src/dependabot-inspect.ts

@@ -0,0 +1,181 @@
+import { DEPENDABOT_FILE } from './dependabot-compose';
+import { updateTarget } from './dependabot-update';
+import { isNonEmptyString, isRecord } from './github-settings-parse';
+import { parseYaml } from './yaml-parse';
+
+const DEPENDABOT_BASELINE_ECOSYSTEMS = ['bun', 'github-actions'] as const;
+const DEPENDABOT_SCHEDULE_INTERVALS = new Set([
+  'daily',
+  'weekly',
+  'monthly',
+  'quarterly',
+  'semiannually',
+  'yearly',
+  'cron',
+]);
+
+type DependabotUpdateInspection = {
+  readonly problems: ReadonlyArray<string>;
+  readonly rootEcosystem: 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 = {
+  readonly problems: ReadonlyArray<string>;
+  readonly scheduledGroups: ReadonlySet<string>;
+};
+
+const inspectDependabotGroups = (
+  groups: unknown,
+): DependabotGroupInspection => {
+  if (groups === undefined) {
+    return { problems: [], scheduledGroups: new Set() };
+  }
+  if (!isRecord(groups)) {
+    return {
+      problems: [`${DEPENDABOT_FILE} multi-ecosystem-groups must be a mapping`],
+      scheduledGroups: new Set(),
+    };
+  }
+
+  const problems: Array<string> = [];
+  const scheduledGroups = new Set<string>();
+  for (const [name, group] of Object.entries(groups)) {
+    const label = `${DEPENDABOT_FILE} 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);
+    }
+  }
+  return { problems, scheduledGroups };
+};
+
+const inspectDependabotUpdateSchedule = (
+  grouped: {
+    readonly name: unknown;
+    readonly patterns: unknown;
+    readonly schedule: unknown;
+  },
+  label: string,
+  scheduledGroups: ReadonlySet<string>,
+): ReadonlyArray<string> => {
+  if (grouped.name === undefined) {
+    return inspectDependabotSchedule(grouped.schedule, label);
+  }
+  const problems: Array<string> = [];
+  if (!isNonEmptyString(grouped.name)) {
+    problems.push(`${label}.multi-ecosystem-group must be a non-empty string`);
+  } else if (!scheduledGroups.has(grouped.name)) {
+    problems.push(`${label} must reference a scheduled multi-ecosystem group`);
+  }
+  if (
+    !(
+      Array.isArray(grouped.patterns) &&
+      grouped.patterns.length > 0 &&
+      grouped.patterns.every(isNonEmptyString)
+    )
+  ) {
+    problems.push(
+      `${label} must define non-empty patterns when using a multi-ecosystem group`,
+    );
+  }
+  if (grouped.schedule !== undefined) {
+    problems.push(...inspectDependabotSchedule(grouped.schedule, label));
+  }
+  return problems;
+};
+
+const inspectDependabotUpdate = (
+  update: unknown,
+  index: number,
+  scheduledGroups: ReadonlySet<string>,
+): DependabotUpdateInspection => {
+  const label = `${DEPENDABOT_FILE} updates[${index}]`;
+  if (!isRecord(update)) {
+    return { problems: [`${label} must be a mapping`], rootEcosystem: null };
+  }
+
+  const {
+    schedule,
+    patterns,
+    'multi-ecosystem-group': multiEcosystemGroup,
+  } = update;
+  const problems: Array<string> = [];
+  const target = updateTarget(update, label, problems);
+
+  problems.push(
+    ...inspectDependabotUpdateSchedule(
+      { name: multiEcosystemGroup, patterns, schedule },
+      label,
+      scheduledGroups,
+    ),
+  );
+
+  return {
+    problems,
+    rootEcosystem: target?.directories.includes('/') ? target.ecosystem : null,
+  };
+};
+
+export const inspectDependabot = (raw: string): ReadonlyArray<string> => {
+  const problems: Array<string> = [];
+  const { value: config, problem } = parseYaml(raw, DEPENDABOT_FILE);
+  if (problem !== null) {
+    return [problem];
+  }
+
+  if (!isRecord(config)) {
+    return [`${DEPENDABOT_FILE} must contain a YAML mapping`];
+  }
+  if (config.version !== 2) {
+    problems.push(`${DEPENDABOT_FILE} must use version: 2`);
+  }
+
+  const { updates, 'multi-ecosystem-groups': multiEcosystemGroups } = config;
+  if (!Array.isArray(updates)) {
+    problems.push(`${DEPENDABOT_FILE} must define an updates list`);
+    return problems;
+  }
+
+  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);
+    }
+  }
+
+  for (const ecosystem of DEPENDABOT_BASELINE_ECOSYSTEMS) {
+    if (!rootEcosystems.has(ecosystem)) {
+      problems.push(
+        `${DEPENDABOT_FILE} must include a root-directory ${ecosystem} ecosystem`,
+      );
+    }
+  }
+  return problems;
+};

package/src/dependabot-update.ts

@@ -0,0 +1,156 @@
+import { isNonEmptyString, isRecord } from './github-settings-parse';
+
+export type UpdateBlock = Record<string, unknown>;
+
+export type UpdateTarget = {
+  readonly ecosystem: string;
+  readonly targetBranch: string | null;
+  readonly directories: ReadonlyArray<string>;
+};
+
+const listOfNonEmptyStrings = (
+  value: unknown,
+): value is ReadonlyArray<string> =>
+  Array.isArray(value) && value.length > 0 && value.every(isNonEmptyString);
+
+const inspectIgnoreEntry = (
+  entry: unknown,
+  label: string,
+): ReadonlyArray<string> => {
+  if (!isRecord(entry)) {
+    return [`${label} must be a mapping`];
+  }
+  const problems: Array<string> = [];
+  if (!isNonEmptyString(entry['dependency-name'])) {
+    problems.push(`${label} must define a non-empty dependency-name`);
+  }
+  for (const key of ['versions', 'update-types'] as const) {
+    const value = entry[key];
+    if (value !== undefined && !listOfNonEmptyStrings(value)) {
+      problems.push(`${label}.${key} must be a non-empty string list`);
+    }
+  }
+  return problems;
+};
+
+export const inspectIgnore = (
+  ignore: unknown,
+  label: string,
+): ReadonlyArray<string> => {
+  if (ignore === undefined) {
+    return [];
+  }
+  if (!Array.isArray(ignore)) {
+    return [`${label}.ignore must be a list`];
+  }
+  const problems: Array<string> = [];
+  for (const [index, entry] of ignore.entries()) {
+    problems.push(...inspectIgnoreEntry(entry, `${label}.ignore[${index}]`));
+  }
+  return problems;
+};
+
+export const inspectRegistryReferences = (
+  registries: unknown,
+  label: string,
+): ReadonlyArray<string> => {
+  if (registries === undefined) {
+    return [];
+  }
+  if (registries === '*') {
+    return [];
+  }
+  if (!listOfNonEmptyStrings(registries)) {
+    return [`${label}.registries must be "*" or a non-empty string list`];
+  }
+  return new Set(registries).size === registries.length
+    ? []
+    : [`${label}.registries must not contain duplicates`];
+};
+
+export const updateTarget = (
+  block: UpdateBlock,
+  label: string,
+  problems: Array<string>,
+): UpdateTarget | null => {
+  const ecosystem = block['package-ecosystem'];
+  if (!isNonEmptyString(ecosystem)) {
+    problems.push(`${label} must define package-ecosystem`);
+  }
+  const targetBranch = block['target-branch'];
+  if (targetBranch !== undefined && !isNonEmptyString(targetBranch)) {
+    problems.push(`${label}.target-branch must be a non-empty string`);
+  }
+
+  const { directory, directories } = block;
+  const hasDirectory = Object.hasOwn(block, 'directory');
+  const hasDirectories = Object.hasOwn(block, 'directories');
+  if (hasDirectory === hasDirectories) {
+    problems.push(
+      `${label} must define exactly one of directory or directories`,
+    );
+    return null;
+  }
+  if (hasDirectory && !isNonEmptyString(directory)) {
+    problems.push(`${label}.directory must be a non-empty string`);
+    return null;
+  }
+  if (hasDirectories && !listOfNonEmptyStrings(directories)) {
+    problems.push(`${label}.directories must be a non-empty string list`);
+    return null;
+  }
+  const rawDirectories: ReadonlyArray<string> = hasDirectory
+    ? [directory as string]
+    : (directories as ReadonlyArray<string>);
+  const normalized = [...new Set(rawDirectories)].sort();
+  if (
+    !hasDirectory &&
+    Array.isArray(directories) &&
+    normalized.length !== directories.length
+  ) {
+    problems.push(`${label}.directories must not contain duplicates`);
+  }
+  if (
+    !isNonEmptyString(ecosystem) ||
+    (targetBranch !== undefined && !isNonEmptyString(targetBranch))
+  ) {
+    return null;
+  }
+  return {
+    ecosystem,
+    targetBranch: targetBranch ?? null,
+    directories: normalized,
+  };
+};
+
+export const sameUpdateScope = (
+  left: UpdateTarget,
+  right: UpdateTarget,
+): boolean =>
+  left.ecosystem === right.ecosystem &&
+  left.targetBranch === right.targetBranch;
+
+export const sameUpdateTarget = (
+  left: UpdateTarget,
+  right: UpdateTarget,
+): boolean =>
+  sameUpdateScope(left, right) &&
+  left.directories.length === right.directories.length &&
+  left.directories.every(
+    (directory, index) => directory === right.directories[index],
+  );
+
+export const overlapsUpdateTarget = (
+  left: UpdateTarget,
+  right: UpdateTarget,
+): boolean =>
+  sameUpdateScope(left, right) &&
+  left.directories.some((directory) => right.directories.includes(directory));
+
+export const updateTargetDescription = (target: UpdateTarget): string => {
+  const branch =
+    target.targetBranch === null
+      ? 'the default target branch'
+      : `target branch "${target.targetBranch}"`;
+  return `"${target.ecosystem}" on ${branch} for ${target.directories.join(', ')}`;
+};

package/src/github-settings-parse.ts

@@ -25,6 +25,9 @@ export type ParsedGithubSettings = {
 export const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value);
 
+export const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === 'string' && value.length > 0;
+
 export const isNamedRuleset = (
   value: unknown,
 ): value is Readonly<Record<string, unknown>> & { readonly name: string } =>

package/src/structure-profile.ts

@@ -30,6 +30,7 @@ const SOURCE_ROOT_EXPECTATIONS: ReadonlyArray<RootScriptExpectation> = [
     name: 'check',
     commands: [
       `${SOURCE_CLI} structure --profile source`,
+      `${SOURCE_CLI} dependabot --check`,
       `${SOURCE_CLI} github --check`,
       'turbo run lint check-types test',
     ],
@@ -39,6 +40,7 @@ const SOURCE_ROOT_EXPECTATIONS: ReadonlyArray<RootScriptExpectation> = [
     name: 'check:fix',
     commands: [
       `${SOURCE_CLI} structure --profile source`,
+      `${SOURCE_CLI} dependabot --write`,
       `${SOURCE_CLI} github --check`,
       'turbo run lint:fix check-types test',
     ],