@davidvornholt/standards 0.17.3 → 0.19.0

package/src/github-ruleset-visibility.ts

@@ -0,0 +1,100 @@
+// Turns unverifiable ruleset fields into gate failures. This module owns both
+// the wording of an invisible field and the test for which field it is, so the
+// two cannot drift apart: an earlier version formatted the message in one
+// module and recovered the signal by parsing the suffix in another, where a
+// reformat would have silently stopped the bypass-actor fallback from firing.
+
+import {
+  ADMIN_VISIBILITY_ADVICE,
+  unverifiableProblem,
+} from './github-command-shared';
+import {
+  BYPASS_ACTORS_KEY,
+  type UnverifiableRulesetField,
+} from './github-ruleset-diff';
+
+const SCOPE = 'ruleset field(s)';
+
+export const isHiddenBypassActors = (
+  field: UnverifiableRulesetField,
+): boolean => field.key === BYPASS_ACTORS_KEY;
+
+const fieldLabel = (field: UnverifiableRulesetField): string =>
+  `ruleset "${field.name}": ${field.key}`;
+
+// What the GraphQL bypass-actor fallback established, so the advice can tell a
+// failed request from a permission gap. `countedNames` holds the live rulesets
+// GraphQL did answer a count for.
+export type BypassCountOutcome = {
+  readonly countedNames: ReadonlySet<string>;
+  readonly failure: string | null;
+};
+
+// Rulesets can be unverifiable for reasons other than a hidden bypass list, in
+// which case the fallback is never called.
+export const GRAPHQL_NOT_CONSULTED: BypassCountOutcome = {
+  countedNames: new Set(),
+  failure: null,
+};
+
+// The generic "read access to repository administration" remedy is
+// unactionable for brokered CI here: REST withholds this field from a GitHub
+// App installation token at every permission level, so widening the App only
+// broadens the blast radius while the gate stays red.
+const INSTALLATION_DEAD_END =
+  "A GitHub App installation token cannot read bypass_actors over REST at any permission level, so widening the App's permissions will not help";
+
+const COUNT_MATCHED_ADVICE = `GitHub reports the declared number of bypass actors but withholds their identities, so the repository is probably fine and only a local run with admin auth can confirm it. ${INSTALLATION_DEAD_END}`;
+
+const NOTHING_ANSWERED_ADVICE = `Neither REST nor the GraphQL bypass-actor count answered for the ruleset(s) listed, so nothing at all is known about who may bypass them; verify locally with admin auth. ${INSTALLATION_DEAD_END}`;
+
+// The two no-failure remedies differ per ruleset, so the fields are partitioned
+// rather than reported under whichever advice one of them happened to match: a
+// ruleset GraphQL never answered for must never be described as probably fine
+// because a sibling ruleset was counted.
+const hiddenBypassActorsProblems = (
+  fields: ReadonlyArray<UnverifiableRulesetField>,
+  outcome: BypassCountOutcome,
+): ReadonlyArray<string> => {
+  if (outcome.failure !== null) {
+    return unverifiableProblem(
+      SCOPE,
+      fields.map(fieldLabel),
+      `The GraphQL bypass-actor count did not answer (${outcome.failure}), so this is a failed request rather than a permission gap: re-run the check, and if it keeps failing verify locally with admin auth`,
+    );
+  }
+  const counted = fields.filter((field) =>
+    outcome.countedNames.has(field.name),
+  );
+  const unanswered = fields.filter(
+    (field) => !outcome.countedNames.has(field.name),
+  );
+  return [
+    ...unverifiableProblem(
+      SCOPE,
+      counted.map(fieldLabel),
+      COUNT_MATCHED_ADVICE,
+    ),
+    ...unverifiableProblem(
+      SCOPE,
+      unanswered.map(fieldLabel),
+      NOTHING_ANSWERED_ADVICE,
+    ),
+  ];
+};
+
+export const rulesetVisibilityProblems = (
+  unverifiable: ReadonlyArray<UnverifiableRulesetField>,
+  outcome: BypassCountOutcome,
+): ReadonlyArray<string> => {
+  const hidden = unverifiable.filter(isHiddenBypassActors);
+  const others = unverifiable.filter((field) => !isHiddenBypassActors(field));
+  return [
+    ...unverifiableProblem(
+      SCOPE,
+      others.map(fieldLabel),
+      ADMIN_VISIBILITY_ADVICE,
+    ),
+    ...hiddenBypassActorsProblems(hidden, outcome),
+  ];
+};

package/src/github-settings-parse.ts

@@ -1,8 +1,7 @@
-// Shape parsing for a single declarative GitHub settings file: the canonical
-// `.github/settings.json` or the repo-owned `.github/settings.local.json`
-// extension. Seam merging lives in github-settings.ts, drift comparison in
-// github-diff.ts, and the API interaction in github-api.ts. Like cli.ts, this
-// module is zero-dependency so `bunx` can execute the published package.
+// Parse one GitHub settings file: canonical `.github/settings.json` or the
+// repo-owned `.github/settings.local.json` extension. Seam merging, drift
+// comparison, and API interaction live in dedicated modules. This module stays
+// zero-dependency so `bunx` can execute the published package.
 
 import { labelIdentity } from './github-label-identity';
 
@@ -139,13 +138,15 @@ const parseDeclarationList = (
   options: ListField,
   problems: Array<string>,
 ): ReadonlyArray<unknown> | null => {
-  const list = raw ?? [];
-  if (!Array.isArray(list)) {
+  if (raw === undefined) {
+    return [];
+  }
+  if (!Array.isArray(raw)) {
     problems.push(`${options.label} "${options.field}" must be an array`);
     return null;
   }
-  problems.push(...options.listProblems(list, options.label));
-  return list;
+  problems.push(...options.listProblems(raw, options.label));
+  return raw;
 };
 
 export const parseSettings = (
@@ -162,7 +163,7 @@ export const parseSettings = (
       problems.push(`${label} has unknown key "${key}"`);
     }
   }
-  const repository = raw.repository ?? {};
+  const repository = 'repository' in raw ? raw.repository : {};
   if (!isRecord(repository)) {
     problems.push(`${label} "repository" must be an object`);
   }
@@ -179,6 +180,7 @@ export const parseSettings = (
   // Only the opt-out value is accepted: enforcement is the default, and an
   // explicit "enforced" would be a second way to spell the same state.
   if (
+    allowedKeys.has('rulesetEnforcement') &&
     raw.rulesetEnforcement !== undefined &&
     raw.rulesetEnforcement !== ENFORCEMENT_OPT_OUT
   ) {

package/src/github-settings.ts

@@ -1,7 +1,8 @@
 // Load and merge canonical GitHub settings with the repo-owned extension.
 // Parsing lives in github-settings-parse.ts, merge policy in
-// github-settings-merge.ts, drift in github-diff.ts, and API work in
-// github-api.ts; this stays dependency-free.
+// github-settings-merge.ts, drift in github-diff.ts and
+// github-ruleset-diff.ts, and API work in github-api.ts; this stays
+// dependency-free.
 
 import { mergeSettings } from './github-settings-merge';
 import {

package/src/managed-files.ts

@@ -1,4 +1,12 @@
-import { readdir, readFile, stat } from 'node:fs/promises';
+import {
+  lstat,
+  readdir,
+  readFile,
+  readlink,
+  rm,
+  symlink,
+  writeFile,
+} from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 
 // Never mirrored, even under a managed directory path: build output, VCS
@@ -16,34 +24,76 @@ const directiveToken = Buffer.from(['biome', 'ignore'].join('-'));
 
 const toPosix = (path: string): string => path.split(sep).join('/');
 
+// A managed path is a file or a symlink. A symlink's identity is its target,
+// never the content it resolves to: mirroring must reproduce the link itself,
+// and following it would copy the whole target tree into every consumer.
+export type ManagedEntry =
+  | { readonly kind: 'file'; readonly absolutePath: string }
+  | {
+      readonly kind: 'symlink';
+      readonly absolutePath: string;
+      readonly target: string;
+    }
+  // Only ever observed when inspecting a destination a consumer replaced; the
+  // upstream walk descends into directories instead of recording them.
+  | { readonly kind: 'directory'; readonly absolutePath: string };
+
+// Built rather than written as an escape so this source file stays plain ASCII
+// and greppable. File digests remain plain content hashes, so existing consumer
+// locks keep validating; the markers only need to be unreachable content for a
+// canonical file, and no text file begins with a NUL byte.
+const nul = String.fromCharCode(0);
+const SYMLINK_DIGEST_PREFIX = `${nul}standards-symlink${nul}`;
+const DIRECTORY_DIGEST = `${nul}standards-directory${nul}`;
+
+export const inspectManagedPath = async (
+  path: string,
+): Promise<ManagedEntry | null> => {
+  const info = await lstat(path).catch(() => null);
+  if (info === null) {
+    return null;
+  }
+  if (info.isSymbolicLink()) {
+    return {
+      kind: 'symlink',
+      absolutePath: path,
+      target: toPosix(await readlink(path)),
+    };
+  }
+  if (info.isDirectory()) {
+    return { kind: 'directory', absolutePath: path };
+  }
+  return { kind: 'file', absolutePath: path };
+};
+
 const walkManagedFiles = async (
   path: string,
   repositoryRoot: string,
-  files: Map<string, string>,
+  files: Map<string, ManagedEntry>,
 ): Promise<void> => {
-  const info = await stat(path).catch(() => null);
-  if (info === null) {
+  const entry = await inspectManagedPath(path);
+  if (entry === null) {
     return;
   }
-  if (info.isDirectory()) {
+  if (entry.kind === 'directory') {
     const entries = await readdir(path);
     await Promise.all(
       entries
-        .filter((entry) => !IGNORED_DIRECTORIES.has(entry))
-        .map((entry) =>
-          walkManagedFiles(join(path, entry), repositoryRoot, files),
+        .filter((name) => !IGNORED_DIRECTORIES.has(name))
+        .map((name) =>
+          walkManagedFiles(join(path, name), repositoryRoot, files),
         ),
     );
     return;
   }
-  files.set(toPosix(relative(repositoryRoot, path)), path);
+  files.set(toPosix(relative(repositoryRoot, path)), entry);
 };
 
 export const listManagedFiles = async (
   repositoryRoot: string,
   paths: ReadonlyArray<string>,
-): Promise<ReadonlyMap<string, string>> => {
-  const files = new Map<string, string>();
+): Promise<ReadonlyMap<string, ManagedEntry>> => {
+  const files = new Map<string, ManagedEntry>();
   await Promise.all(
     paths.map((path) =>
       walkManagedFiles(join(repositoryRoot, path), repositoryRoot, files),
@@ -52,12 +102,64 @@ export const listManagedFiles = async (
   return files;
 };
 
+// What the lock hashes for an entry: file content, or the marker-prefixed link
+// target. Retargeting a link therefore reads as drift the same way an edited
+// file does.
+export const managedEntryDigestInput = (
+  entry: ManagedEntry,
+): Promise<Buffer> => {
+  if (entry.kind === 'symlink') {
+    return Promise.resolve(
+      Buffer.from(`${SYMLINK_DIGEST_PREFIX}${entry.target}`),
+    );
+  }
+  if (entry.kind === 'directory') {
+    return Promise.resolve(Buffer.from(DIRECTORY_DIGEST));
+  }
+  return readFile(entry.absolutePath);
+};
+
+// Plant one managed entry, replacing a file or a link that occupies the
+// destination. Never recursive: a directory at the destination is unbounded
+// consumer content, so removing it is the caller's decision to make explicitly
+// once it has proven the path was engine-owned.
+export const writeManagedEntry = async (
+  dest: string,
+  entry: ManagedEntry,
+): Promise<void> => {
+  if (entry.kind === 'directory') {
+    throw new Error(`cannot mirror a directory as a managed path: ${dest}`);
+  }
+  const existing = await inspectManagedPath(dest);
+  if (existing?.kind === 'directory') {
+    throw new Error(
+      `refusing to replace the directory ${dest} with a managed ${entry.kind}; move or delete it first`,
+    );
+  }
+  // `symlink` refuses an existing path, and writing a file through a stale link
+  // would clobber that link's target instead of replacing the managed path.
+  if (
+    existing !== null &&
+    (entry.kind === 'symlink' || existing.kind === 'symlink')
+  ) {
+    await rm(dest, { force: true });
+  }
+  if (entry.kind === 'symlink') {
+    await symlink(entry.target, dest);
+    return;
+  }
+  await writeFile(dest, await readFile(entry.absolutePath));
+};
+
 export const findManagedFilesContainingBiomeDirectiveToken = async (
-  files: ReadonlyMap<string, string>,
+  files: ReadonlyMap<string, ManagedEntry>,
 ): Promise<ReadonlyArray<string>> => {
   const matches = await Promise.all(
-    [...files].map(async ([path, absolutePath]) =>
-      (await readFile(absolutePath)).includes(directiveToken) ? path : null,
+    [...files].map(async ([path, entry]) =>
+      entry.kind === 'file' &&
+      (await readFile(entry.absolutePath)).includes(directiveToken)
+        ? path
+        : null,
     ),
   );
   return matches.filter((path): path is string => path !== null).sort();

package/src/managed-path-ownership.ts

@@ -0,0 +1,85 @@
+// Ownership questions about a destination path, asked before init/sync writes
+// to it or deletes it. Both answers come from the lock: it is the only record of
+// what this engine put in a consumer, so anything absent from it is consumer
+// work that a mirror must never destroy.
+
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { inspectManagedPath, type ManagedEntry } from './managed-files';
+
+const collectPaths = async (
+  root: string,
+  rel: string,
+  found: Array<string>,
+): Promise<void> => {
+  const entry = await inspectManagedPath(join(root, rel));
+  if (entry === null) {
+    return;
+  }
+  if (entry.kind === 'directory') {
+    const names = await readdir(join(root, rel));
+    await Promise.all(
+      names.map((name) => collectPaths(root, `${rel}/${name}`, found)),
+    );
+    return;
+  }
+  found.push(rel);
+};
+
+// Paths inside `rel` that the lock never recorded, so a caller can tell an
+// engine-owned tree from consumer work. An older CLI that followed a canonical
+// link materialized its whole target tree and locked every path in it; a
+// consumer's own file under the same directory is absent from the lock. Nothing
+// here follows a symlink: every entry is judged where it sits.
+export const unlockedPathsUnder = async (
+  root: string,
+  rel: string,
+  locked: ReadonlySet<string>,
+): Promise<ReadonlyArray<string>> => {
+  const found: Array<string> = [];
+  await collectPaths(root, rel, found);
+  return found.filter((path) => !locked.has(path)).sort();
+};
+
+// An ancestor that is not a directory, so nothing can sit below it under the
+// name the lock recorded. The kind is part of the answer: below a symlink the
+// name still resolves, to somebody else's content, while below a file it
+// resolves to nothing at all.
+export type InterposedAncestor = {
+  readonly rel: string;
+  readonly kind: 'file' | 'symlink';
+};
+
+// The shallowest ancestor of `rel` inside `root` that is not a directory, or
+// null when the whole parent chain is directories.
+//
+// `planned` is the payload this run mirrors, and it wins over the disk: every
+// path in it has the kind upstream gives it once the mirror has finished, and
+// the caller runs after the mirror. A dry run, which writes nothing, therefore
+// reaches the same answer the matching real run does.
+//
+// A path whose parent chain crosses a link does not name what the caller thinks
+// it names: reading or removing it reaches into the link's target tree, which
+// is somebody else's content.
+export const interposedAncestor = async (
+  root: string,
+  rel: string,
+  planned: ReadonlyMap<string, ManagedEntry>,
+): Promise<InterposedAncestor | null> => {
+  const segments = rel.split('/').slice(0, -1);
+  const prefixes = segments.map((_, depth) =>
+    segments.slice(0, depth + 1).join('/'),
+  );
+  const entries = await Promise.all(
+    prefixes.map(
+      (prefix) => planned.get(prefix) ?? inspectManagedPath(join(root, prefix)),
+    ),
+  );
+  for (const [index, prefix] of prefixes.entries()) {
+    const entry = entries[index] ?? null;
+    if (entry !== null && entry.kind !== 'directory') {
+      return { rel: prefix, kind: entry.kind };
+    }
+  }
+  return null;
+};