@zgeoff/chex 0.0.1 → 0.0.3

package/src/docs/check-readmes.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# Fails on each README.md that is not one of the five kinds in docs-writing's
+# references/readmes.md, and prints what to do with it. Its last line counts the READMEs and those of
+# no kind.
+# Usage (from the repo root): check-readmes.sh
+# The five kinds:
+# 1. the root README.md;
+# 2. a README in a folder that holds a package.json, go.mod or Cargo.toml;
+# 3. docs/README.md;
+# 4. a design README: docs/design/<work>/README.md, or the README of a folder inside a design folder
+#    whose own README is a design README, outside any spikes/ folder;
+# 5. a spike README, whose first H1 starts "Spike: ", or, outside docs/design/, the README of a
+#    folder whose direct subfolders hold a spike README. A design README lists its own spikes.
+# A README git marks linguist-vendored belongs to someone else and is skipped.
+set -uo pipefail
+
+if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
+  echo "check-readmes: run it inside a git work tree, because it lists the files with git" >&2
+  exit 2
+fi
+
+if [ "$#" -gt 0 ]; then
+  echo "usage: check-readmes.sh" >&2
+  exit 2
+fi
+
+# Lists tracked and untracked READMEs, so a new README is checked before it is staged. A file deleted
+# from the working tree stays in the index until the deletion is staged, so it is dropped here.
+if ! listing=$(git -c core.quotePath=false ls-files --cached --others --exclude-standard -- \
+  ':(glob)**/README.md' ':(exclude,attr:linguist-vendored)' ':(exclude,attr:linguist-vendored=true)'); then
+  echo "check-readmes: git ls-files failed, so no README was checked" >&2
+  exit 2
+fi
+
+readmes=()
+while IFS= read -r file; do
+  [ -f "$file" ] && readmes+=("$file")
+done < <(sort -u <<< "$listing")
+
+declare -A listed=()
+for readme in "${readmes[@]}"; do
+  listed[$readme]=1
+done
+
+# Holds when the first H1 outside a code block starts "Spike: ".
+is_spike() {
+  awk '
+    match($0, /^[ \t]*(```+|~~~+)/) {
+      marker = substr($0, RSTART, RLENGTH)
+      sub(/^[ \t]*/, "", marker)
+      rest = substr($0, RSTART + RLENGTH)
+      # A fence closes only with the opening character, at least as long, and nothing after it.
+      if (open == "") open = marker
+      else if (substr(marker, 1, 1) == substr(open, 1, 1) && length(marker) >= length(open) && rest ~ /^[ \t]*$/) open = ""
+      next
+    }
+    open == "" && /^# / { found = ($0 ~ /^# Spike: /); exit }
+    END { exit !found }
+  ' "$1"
+}
+
+# Holds when a README in one of the folder's direct subfolders is a spike README.
+indexes_spikes() {
+  local dir=$1 readme
+  for readme in "${readmes[@]}"; do
+    if [[ $readme == "$dir"/*/README.md && $readme != "$dir"/*/*/README.md ]] && is_spike "$readme"; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+is_design() {
+  local readme=$1 parent
+  [[ $readme == docs/design/*/README.md && /$readme/ != */spikes/* ]] || return 1
+  [[ $readme != docs/design/*/*/README.md ]] && return 0
+  parent=$(dirname "$(dirname "$readme")")/README.md
+  [ -n "${listed[$parent]:-}" ] && is_design "$parent"
+}
+
+is_known() {
+  local readme=$1 dir
+  dir=$(dirname "$readme")
+
+  [ "$readme" = README.md ] && return 0
+  [ -f "$dir/package.json" ] || [ -f "$dir/go.mod" ] || [ -f "$dir/Cargo.toml" ] && return 0
+  [ "$readme" = docs/README.md ] && return 0
+  is_design "$readme" && return 0
+  is_spike "$readme" && return 0
+  [[ $dir != docs/design/* ]] && indexes_spikes "$dir"
+}
+
+unknown=0
+for readme in "${readmes[@]}"; do
+  if ! is_known "$readme"; then
+    unknown=$((unknown + 1))
+    echo "$readme: not one of the five kinds of README; move its content into docs/, or into a code comment beside the code it explains"
+  fi
+done
+
+echo "check-readmes: ${#readmes[@]} READMEs, $unknown not one of the five kinds"
+[ "$unknown" -eq 0 ]

package/src/docs/check-skill.sh

@@ -0,0 +1,413 @@
+#!/usr/bin/env bash
+# Checks the structure of each skill; exits non-zero when a skill breaks a rule that fails the run.
+# Usage (from the repo root): check-skill.sh [<skill-dir>...]
+# With no argument it checks every directory holding a SKILL.md under .agents/skills/ and
+# .claude/skills/, where a consumer repo installs skills, under skills/, where zgeoff/skills keeps
+# them, and under sync/skills/, where zgeoff/tools keeps the shared skill bases. A skill whose
+# SKILL.md git marks linguist-vendored is skipped, so a repo marks its third-party skills in
+# .gitattributes.
+# Fails on: a missing name or description, a name that differs from the folder or breaks the name
+# format, a description over 1,024 characters, a plain description that holds a colon YAML reads as a
+# key, a link with a line anchor outside code, and a SKILL.md body over 1,700 words, or over 5,000
+# for a rule set (metadata.kind: rule-set in the frontmatter).
+# Warns on: a SKILL.md body over 1,500 words, or over 4,000 for a rule set, a SKILL.md over 500
+# lines, a reference that SKILL.md does not list under ## References, a reference over 100 lines
+# with two or more headings and no contents list near its top, a reference that links to another
+# reference, and a code-formatted span outside a table that names an existing repo file.
+set -uo pipefail
+
+if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
+  echo "check-skill: run it inside a git work tree, because it lists the files with git" >&2
+  exit 2
+fi
+
+# Lists tracked and untracked files, so a new skill is checked before it is staged.
+# A caller runs it in a command substitution and exits on its failure, because git's failure
+# otherwise reaches the check as an empty list.
+list_files() {
+  local listing
+  if ! listing=$(git -c core.quotePath=false ls-files --cached --others --exclude-standard -- "$@"); then
+    echo "check-skill: git ls-files failed, so no skill was checked" >&2
+    exit 2
+  fi
+  sort -u <<< "$listing"
+}
+
+is_vendored() {
+  local value
+  value=$(git check-attr linguist-vendored -- "$1/SKILL.md" | sed 's/^.*: //')
+  [ "$value" = set ] || [ "$value" = true ]
+}
+
+dirs=()
+
+if [ "$#" -gt 0 ]; then
+  for dir in "$@"; do
+    dir=${dir%/}
+    if [ ! -f "$dir/SKILL.md" ]; then
+      echo "check-skill: $dir has no SKILL.md" >&2
+      exit 2
+    fi
+    dirs+=("$dir")
+  done
+else
+  skill_files=$(list_files ':(glob).agents/skills/**/SKILL.md' ':(glob).claude/skills/**/SKILL.md' \
+    ':(glob)skills/**/SKILL.md' ':(glob)sync/skills/**/SKILL.md') || exit 2
+  while IFS= read -r file; do
+    [ -n "$file" ] && [ -f "$file" ] && dirs+=("$(dirname "$file")")
+  done <<< "$skill_files"
+fi
+
+checked=()
+
+for dir in "${dirs[@]}"; do
+  is_vendored "$dir" || checked+=("$dir")
+done
+
+if [ "${#checked[@]}" -eq 0 ]; then
+  echo 'check-skill: no skills to check'
+  exit 0
+fi
+
+perl -COE -e '
+use strict;
+use warnings;
+
+my ($errors, $warnings) = (0, 0);
+
+for my $dir (@ARGV) {
+  $dir =~ s{^\./}{};
+  check_skill($dir);
+}
+
+printf "check-skill: %d skills, %d errors, %d warnings\n", scalar @ARGV, $errors, $warnings;
+exit($errors ? 1 : 0);
+
+sub fail {
+  my ($where, $message) = @_;
+  print "$where: $message\n";
+  $errors++;
+}
+
+sub warn_about {
+  my ($where, $message) = @_;
+  print "$where: $message (warning)\n";
+  $warnings++;
+}
+
+sub to_bytes {
+  my ($text) = @_;
+  utf8::encode($text);
+  return $text;
+}
+
+sub read_lines {
+  my ($path) = @_;
+  local $/ = "\n";
+  open my $fh, "<:encoding(UTF-8)", to_bytes($path) or die "check-skill: cannot read $path: $!\n";
+  my @lines = <$fh>;
+  close $fh;
+  chomp @lines;
+  return @lines;
+}
+
+sub check_skill {
+  my ($dir) = @_;
+  my $skill = "$dir/SKILL.md";
+  my @lines = read_lines($skill);
+
+  warn_about($skill, scalar(@lines) . " lines, over 500; check that each section is one most tasks need")
+    if @lines > 500;
+  check_words($skill, @lines);
+  check_frontmatter($dir, $skill, @lines);
+
+  open my $list, "-|", "git", "-c", "core.quotePath=false", "ls-files", "--cached", "--others",
+    "--exclude-standard", "--", $dir, ":(exclude,attr:linguist-vendored)",
+    ":(exclude,attr:linguist-vendored=true)" or die "check-skill: cannot list $dir: $!\n";
+  my %files;
+  while (my $file = <$list>) {
+    chomp $file;
+    utf8::decode($file);
+    $files{$file} = 1 if $file =~ /\.md\z/ && -f to_bytes($file);
+  }
+  close $list;
+
+  for my $file (sort keys %files) {
+    check_markdown($dir, $file, $file eq $skill);
+  }
+
+  my %listed = map { $_ => 1 } list_references($skill, @lines);
+  for my $file (sort grep { m{^\Q$dir\E/references/[^/]+\.md\z} } keys %files) {
+    warn_about($file, "SKILL.md does not list it under ## References; add a line naming the task that needs it")
+      unless $listed{$file};
+  }
+}
+
+# Counts the words of the body after the frontmatter, code blocks included: past the warning limit
+# an agent starts to skim, and past the error limit the skill fails the run. A rule set, such as a
+# code style, holds the rules an agent needs on every task of its kind, so it gets higher limits.
+sub check_words {
+  my ($skill, @lines) = @_;
+  my ($warn, $limit) = (1500, 1700);
+  my ($start, $in_metadata, $indent) = (0, 0, undef);
+  if (@lines && $lines[0] eq "---") {
+    for my $i (1 .. $#lines) {
+      my $line = $lines[$i];
+      if ($line eq "---") { $start = $i + 1; last }
+      if ($line =~ /^metadata:(?:\s+#.*)?\s*$/) { ($in_metadata, $indent) = (1, undef); next }
+      if ($line =~ /^metadata:\s*\{(.*)\}\s*(?:#.*)?$/) {
+        for my $entry (split_flow_entries($1)) {
+          ($warn, $limit) = (4000, 5000) if $entry =~ /^\s*kind:\s*(.*?)\s*$/ && unquote($1) eq "rule-set";
+        }
+        $in_metadata = 0;
+        next;
+      }
+      # A comment-only line, at any indent, is neither a key nor the end of the mapping.
+      next if $line =~ /^\s*#/;
+      $in_metadata = 0 if $line =~ /^\S/;
+      next unless $in_metadata && $line =~ /^(\s+)(\S.*?)\s*$/;
+      # Only a key of metadata itself counts, never a deeper line, such as the text of a block value.
+      $indent //= length $1;
+      next unless length($1) == $indent && $2 =~ /^kind:\s*(.*)$/;
+      ($warn, $limit) = (4000, 5000) if unquote($1) eq "rule-set";
+    }
+  }
+  my $words = 0;
+  for my $line (@lines[$start .. $#lines]) {
+    $words += () = $line =~ /\S+/g;
+  }
+  if ($words > $limit) {
+    fail($skill, "body is $words words, over the limit of $limit; cut it, or move what only some tasks need into a reference");
+  } elsif ($words > $warn) {
+    warn_about($skill, "body is $words words, over $warn; cut it, or move what only some tasks need into a reference");
+  }
+}
+
+# Splits the inside of a YAML flow mapping at each comma that sits outside a quoted value and a
+# nested flow collection, so a comma inside a value never starts an entry.
+sub split_flow_entries {
+  my ($text) = @_;
+  my (@entries, $quote);
+  my ($entry, $depth) = ("", 0);
+  for (my $i = 0; $i < length $text; $i++) {
+    my $char = substr($text, $i, 1);
+    if (defined $quote) {
+      if ($quote eq "\"" && $char eq "\\") { $entry .= substr($text, $i, 2); $i++; next }
+      undef $quote if $char eq $quote;
+    } elsif ($char eq "\"" || $char eq "\x27") {
+      $quote = $char;
+    } elsif ($char eq "{" || $char eq "[") {
+      $depth++;
+    } elsif ($char eq "}" || $char eq "]") {
+      $depth--;
+    } elsif ($char eq "," && $depth == 0) {
+      push @entries, $entry;
+      $entry = "";
+      next;
+    }
+    $entry .= $char;
+  }
+  return (@entries, $entry);
+}
+
+# Returns the files that the links under the ## References heading of SKILL.md point at.
+sub list_references {
+  my ($skill, @lines) = @_;
+  my ($in_section, @found) = (0);
+  for my $line (@lines) {
+    if ($line =~ /^##\s+(.*?)\s*$/) {
+      $in_section = $1 eq "References";
+      next;
+    }
+    next unless $in_section;
+    while ($line =~ /\]\(\s*([^()\s#]+)/g) {
+      my $resolved = resolve_path($skill, $1);
+      push @found, $resolved if defined $resolved;
+    }
+  }
+  return @found;
+}
+
+# Reads the frontmatter block: a name, and a description that may fold over indented lines.
+sub check_frontmatter {
+  my ($dir, $skill, @lines) = @_;
+  my ($name, $description, $in_description, $closed, $raw_description, $folded, $style, $colon);
+
+  if (@lines && $lines[0] eq "---") {
+    for my $line (@lines[1 .. $#lines]) {
+      if ($line eq "---") { $closed = 1; last }
+      if ($line =~ /^name:\s*(.*?)\s*$/) {
+        $name = unquote($1);
+        $in_description = 0;
+      } elsif ($line =~ /^description:\s*(.*?)\s*$/) {
+        $raw_description = $1;
+        $style = pick_scalar_style($raw_description);
+        $description = ($style // "") eq "block" ? "" : unquote($raw_description);
+        $colon = 1 if ($style // "") eq "plain" && has_key_colon($description);
+        $in_description = 1;
+      } elsif ($in_description && $line =~ /^\s+(\S.*?)\s*$/) {
+        $description .= ($description eq "" ? "" : " ") . $1;
+        $style //= $1 =~ /\A["\x27]/ ? "quoted" : "plain";
+        $colon = 1 if $style eq "plain" && has_key_colon($1);
+        $folded = 1;
+      } elsif ($line =~ /^[A-Za-z_-]+:/) {
+        $in_description = 0;
+      }
+    }
+  }
+
+  # A plain null (null, Null, NULL or ~) on one line has no text, as YAML reads it.
+  $description = "" if !$folded && defined $raw_description
+    && $raw_description =~ /\A(?:null|Null|NULL|~)(?:\s+#.*)?\z/;
+
+  unless ($closed) {
+    fail($skill, "has no frontmatter block");
+    return;
+  }
+
+  if (!defined $name || $name eq "") {
+    fail($skill, "has no name");
+  } else {
+    my $folder = $dir =~ s{.*/}{}r;
+    fail($skill, "name $name does not match the folder $folder") if $name ne $folder;
+    fail($skill, "name $name is not lowercase letters, digits and hyphens of at most 64 characters")
+      if $name !~ /\A[a-z0-9-]{1,64}\z/;
+  }
+
+  if (!defined $description || $description eq "") {
+    fail($skill, "has no description");
+  } elsif (length $description > 1024) {
+    fail($skill, "description is " . length($description) . " characters, over the limit of 1024");
+  }
+
+  fail($skill, "description holds a colon and a space, which YAML reads as a key in a plain scalar; reword it, or quote it or write it as a block scalar (>-)")
+    if $colon;
+}
+
+# Returns block, quoted or plain for the text after a key, or undef when the text is empty or only a
+# comment, since the scalar then starts on the next line. A block header may hold an indentation
+# digit and a chomping sign in either order, then a comment.
+sub pick_scalar_style {
+  my ($text) = @_;
+  return undef if $text eq "" || $text =~ /\A#/;
+  return "block" if $text =~ /\A[|>](?:[1-9][+-]?|[+-][1-9]?)?(?:\s+#.*)?\z/;
+  return "quoted" if $text =~ /\A["\x27]/;
+  return "plain";
+}
+
+# A colon followed by a space or the line end starts a mapping inside a plain YAML scalar, so a
+# loader rejects the frontmatter. A space and a hash end the scalar and start a comment.
+sub has_key_colon {
+  my ($text) = @_;
+  return ($text =~ s/\s+#.*\z//r) =~ /:(?:\s|\z)/;
+}
+
+# Returns the value of a scalar: the text inside its quotes, or plain text without a trailing comment.
+sub unquote {
+  my ($text) = @_;
+  return $2 if $text =~ /\A(["\x27])(.*?)\1\s*(?:#.*)?\z/;
+  return "" if $text =~ /\A#/;
+  $text =~ s/\s+#.*\z//;
+  return $text;
+}
+
+sub check_markdown {
+  my ($dir, $file, $is_skill) = @_;
+  my @lines = read_lines($file);
+  my $open = "";
+  my $line_number = 0;
+  my $contents_links = 0;
+  my $headings = 0;
+  my $reference = !$is_skill;
+  my $in_comment = 0;
+
+  for my $line (@lines) {
+    $line_number++;
+    if ($line =~ /^\s*(`{3,}|~{3,})(.*)$/) {
+      my ($marker, $rest) = ($1, $2);
+      if ($open eq "") { $open = $marker }
+      elsif (substr($marker, 0, 1) eq substr($open, 0, 1) && length($marker) >= length($open)
+        && $rest =~ /^\s*$/) { $open = "" }
+      next;
+    }
+    next if $open ne "";
+    $headings++ if $line =~ /^#{2,6}\s/;
+
+    # An HTML comment never renders, so its text holds no link and no path.
+    # A comment marker inside inline code renders as text, so the spans hide their markers first.
+    my $visible = $line =~ s{(`+)(.+?)\1}{my $span = $&; $span =~ s/<!--/<\x{1}!--/g; $span =~ s/-->/--\x{1}>/g; $span}ger;
+    if ($in_comment) {
+      next unless $visible =~ s/\A.*?-->//;
+      $in_comment = 0;
+    }
+    $visible =~ s/<!--.*?-->//g;
+    $in_comment = 1 if $visible =~ s/<!--.*\z//;
+    $visible =~ s/\x{1}//g;
+
+    my $text = $visible;
+    my @spans;
+    $text =~ s/(`+)(.+?)\1/push @spans, $2; ""/ge;
+
+    if ($line_number <= 30) {
+      $contents_links++ while $text =~ /\]\(#[^)\s]+\)/g;
+    }
+
+    my @targets;
+    push @targets, $1 while $text =~ /\]\(\s*(<[^>]*>|(?:[^()\s]|\([^()\s]*\))+)/g;
+    push @targets, $1 if $text =~ /^\s{0,3}\[(?!\^)[^\]]+\]:\s*(<[^>]*>|\S+)/;
+    push @targets, $2 while $text =~ /\b(?:href|src)\s*=\s*(["\x27])(.*?)\1/g;
+
+    for my $target (@targets) {
+      $target =~ s/^<(.*)>$/$1/;
+      fail("$file:$line_number", "link $target has a line anchor; name the target in the link text instead")
+        if $target =~ /#L[0-9]+/;
+      check_reference_link($dir, $file, $line_number, $target) if $reference;
+    }
+
+    # A span inside link text is already a link, so only the spans left after links drop are read.
+    # A table row holds commands the agent types, such as the commands table of a skill, so it is skipped.
+    next if $visible =~ /^\s*\|/;
+    my $outside_links = $visible =~ s/!?\[[^\]]*\]\([^)]*\)//gr;
+    my @bare;
+    $outside_links =~ s/(`+)(.+?)\1/push @bare, $2; ""/ge;
+
+    for my $span (@bare) {
+      $span =~ s/^\s+|\s+$//g;
+      next if $span !~ m{\A[\w.@/-]+\z} || $span !~ m{/};
+      warn_about("$file:$line_number", "`$span` names a file in the repo; link it instead")
+        if -f to_bytes($span);
+    }
+  }
+
+  if ($reference && @lines > 100 && $headings >= 2 && $contents_links < 2) {
+    warn_about($file, scalar(@lines) . " lines with no contents list near the top; open with links to its headings");
+  }
+}
+
+sub check_reference_link {
+  my ($dir, $file, $line_number, $target) = @_;
+  return if $target eq "" || $target =~ m{^(?:[a-z][a-z0-9+.-]*:|//|#)}i;
+  my ($path) = split /[#?]/, $target, 2;
+  my $resolved = resolve_path($file, $path);
+  return unless defined $resolved && $resolved ne $file;
+  return unless $resolved =~ m{^\Q$dir\E/references/.*\.md\z};
+  warn_about("$file:$line_number", "links to another reference ($resolved); link it from SKILL.md instead");
+}
+
+sub resolve_path {
+  my ($file, $path) = @_;
+  return undef if $path eq "";
+  my @parts = $path =~ m{^/} ? () : split m{/}, $file;
+  pop @parts unless $path =~ m{^/};
+  for my $part (split m{/}, $path) {
+    next if $part eq "" || $part eq ".";
+    if ($part eq "..") {
+      return undef unless @parts;
+      pop @parts;
+    } else {
+      push @parts, $part;
+    }
+  }
+  return @parts ? join("/", @parts) : undef;
+}
+' -- "${checked[@]}"

package/src/docs/check-vision.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Checks the repo's vision doc, docs/vision.md, against the docs-writing skill's contract. Fails when
+# the doc is missing or runs past one page.
+# Usage (from the repo root): check-vision.sh
+set -uo pipefail
+
+[ "$#" -eq 0 ] || {
+  echo "usage: check-vision.sh" >&2
+  exit 2
+}
+
+vision=docs/vision.md
+limit=60
+
+# A tracked or untracked doc counts, so a new one passes before it is staged, and an ignored one
+# does not.
+if ! listed=$(git -c core.quotePath=false ls-files --cached --others --exclude-standard -- "$vision"); then
+  echo "check-vision: git ls-files failed, so the vision doc was not checked" >&2
+  exit 2
+fi
+
+if [ -z "$listed" ] || [ ! -f "$vision" ]; then
+  echo "$vision: missing; write the vision doc the docs-writing skill's docs-tree reference describes (error)"
+  exit 1
+fi
+
+lines=$(awk 'END { print NR }' "$vision")
+
+if [ "$lines" -gt "$limit" ]; then
+  echo "$vision: $lines lines, over the vision doc limit of $limit (error: cut points to fit one page)"
+  exit 1
+fi
+
+echo "$vision: $lines lines (vision doc; limit $limit)"

package/src/find-install-cache-path.ts

@@ -0,0 +1,16 @@
+// A path segment, so `node_modules_backup` and `.bun/install/cache-old` are other folders.
+const installCachePattern = /(?:^|\/)(?:node_modules|\.bun\/install\/cache)(?:\/|$)/u;
+
+// actions/cache reads one path per line, and a line that starts with `!` leaves that path out. A
+// line that holds an expression is left alone, because GitHub resolves it only when the job runs.
+export function findInstallCachePath(paths: unknown): string | undefined {
+  return typeof paths === 'string'
+    ? paths
+        .split('\n')
+        .map((path) => path.trim())
+        .find(
+          (path) =>
+            !path.startsWith('!') && !path.includes('${{') && installCachePattern.test(path),
+        )
+    : undefined;
+}

package/src/format-commit-lines.ts

@@ -0,0 +1,3 @@
+export function formatCommitLines(commits: readonly string[]): string {
+  return commits.map((commit) => `${commit}\n`).join('');
+}

package/src/make-check-runner.ts

@@ -0,0 +1,40 @@
+import { join } from 'node:path';
+import type { CheckName } from './check-names.ts';
+
+export type CheckRunner = (args: readonly string[]) => Promise<number> | number;
+
+type DocsCheckName = 'prose' | 'length' | 'links' | 'readmes' | 'vision' | 'skill';
+
+export type RepoCheckName = Exclude<CheckName, DocsCheckName>;
+
+export interface CheckRunnerDeps {
+  // The folder that holds the docs checks' shell scripts.
+  readonly docsFolder: string;
+
+  // Runs a command with this process's output streams, and returns its exit code.
+  readonly runScript: (argv: readonly string[]) => Promise<number>;
+
+  readonly repoChecks: Readonly<Record<RepoCheckName, CheckRunner>>;
+}
+
+export function makeCheckRunner(
+  deps: CheckRunnerDeps,
+): (name: CheckName, args: readonly string[]) => Promise<number> {
+  const makeDocsCheckRunner =
+    (script: string): CheckRunner =>
+    (args) =>
+      deps.runScript(['bash', join(deps.docsFolder, script), ...args]);
+
+  // Typed over every check name, so a new check fails the type check until it has a runner.
+  const runners: Readonly<Record<CheckName, CheckRunner>> = {
+    prose: makeDocsCheckRunner('check-prose.sh'),
+    length: makeDocsCheckRunner('check-length.sh'),
+    links: makeDocsCheckRunner('check-links.sh'),
+    readmes: makeDocsCheckRunner('check-readmes.sh'),
+    vision: makeDocsCheckRunner('check-vision.sh'),
+    skill: makeDocsCheckRunner('check-skill.sh'),
+    ...deps.repoChecks,
+  };
+
+  return (name, args) => Promise.resolve(runners[name](args));
+}