@zgeoff/chex 0.0.0 → 0.0.2

package/src/dependency-gates/parse-root-manifest.ts

@@ -0,0 +1,68 @@
+import { isRecord } from './is-record.ts';
+
+export interface RootManifest {
+  readonly overrides: Readonly<Record<string, string>>;
+  readonly catalog: Readonly<Record<string, string>>;
+  readonly catalogs: Readonly<Record<string, Readonly<Record<string, string>>>>;
+  readonly auditScript: string;
+}
+
+export function parseRootManifest(text: string): RootManifest {
+  const manifest: unknown = JSON.parse(text);
+
+  if (!isRecord(manifest)) {
+    throw new TypeError('package.json holds no object');
+  }
+
+  const workspaces = manifest['workspaces'];
+  const catalog = isRecord(workspaces) ? workspaces['catalog'] : undefined;
+  const catalogs = isRecord(workspaces) ? workspaces['catalogs'] : undefined;
+  const scripts = manifest['scripts'];
+  const audit = isRecord(scripts) ? scripts['audit'] : undefined;
+
+  return {
+    overrides: parseVersions(manifest['overrides'], 'overrides'),
+    catalog: parseVersions(catalog, 'workspaces.catalog'),
+    catalogs: parseNamedCatalogs(catalogs),
+    auditScript: typeof audit === 'string' ? audit : '',
+  };
+}
+
+function parseVersions(value: unknown, field: string): Record<string, string> {
+  if (value === undefined) {
+    return {};
+  }
+
+  if (!isRecord(value)) {
+    throw new TypeError(`package.json sets ${field} to a value that is not an object`);
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).map(([name, version]) => {
+      if (typeof version !== 'string') {
+        throw new TypeError(
+          `package.json sets the ${field} entry for ${name} to a value that is not a version`,
+        );
+      }
+
+      return [name, version];
+    }),
+  );
+}
+
+function parseNamedCatalogs(value: unknown): Record<string, Record<string, string>> {
+  if (value === undefined) {
+    return {};
+  }
+
+  if (!isRecord(value)) {
+    throw new TypeError('package.json sets workspaces.catalogs to a value that is not an object');
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).map(([catalogName, versions]) => [
+      catalogName,
+      parseVersions(versions, `workspaces.catalogs.${catalogName}`),
+    ]),
+  );
+}

package/src/dependency-gates/read-dependency-gate-findings.ts

@@ -0,0 +1,91 @@
+import type { RunProgram } from '../run-program.ts';
+import { collectStaleAgeGateExcludes } from './collect-stale-age-gate-excludes.ts';
+import { collectUnneededAuditIgnores } from './collect-unneeded-audit-ignores.ts';
+import { collectUnneededOverrides } from './collect-unneeded-overrides.ts';
+import { parseAuditAdvisories } from './parse-audit-advisories.ts';
+import { parseAuditIgnoreIDs } from './parse-audit-ignore-ids.ts';
+import { parseFixablePackages } from './parse-fixable-packages.ts';
+import { parseLockfileDependents } from './parse-lockfile-dependents.ts';
+import type { RootManifest } from './parse-root-manifest.ts';
+import { parseRootManifest } from './parse-root-manifest.ts';
+import type { DependencyGateFinding } from './types.ts';
+
+export interface DependencyGateSources {
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+
+  // An ISO date, such as 2026-03-08.
+  readonly today: string;
+
+  readonly runProgram: RunProgram;
+
+  // The path is relative to the repo root.
+  readonly readRepoFile: (path: string) => string | null;
+}
+
+// The audit runs only for a repo that ignores an advisory, so a repo with no ignore needs no
+// network.
+export function readDependencyGateFindings(
+  sources: Readonly<DependencyGateSources>,
+): DependencyGateFinding[] {
+  const manifestText = sources.readRepoFile('package.json');
+
+  if (manifestText === null) {
+    throw new Error('the repo has no package.json');
+  }
+
+  const manifest = parseRootManifest(manifestText);
+  const ignoreIDs = parseAuditIgnoreIDs(manifest.auditScript);
+
+  return [
+    ...collectStaleAgeGateExcludes(sources.readRepoFile('bunfig.toml') ?? '', sources.today),
+    ...readOverrideFindings(sources, manifest),
+    ...(ignoreIDs.length === 0 ? [] : readIgnoreFindings(sources, ignoreIDs)),
+  ];
+}
+
+function readOverrideFindings(
+  sources: Readonly<DependencyGateSources>,
+  manifest: RootManifest,
+): DependencyGateFinding[] {
+  if (Object.keys(manifest.overrides).length === 0) {
+    return [];
+  }
+
+  const lockfile = sources.readRepoFile('bun.lock');
+
+  if (lockfile === null) {
+    throw new Error('package.json sets overrides, and the repo has no bun.lock');
+  }
+
+  return collectUnneededOverrides({
+    overrides: manifest.overrides,
+    catalog: manifest.catalog,
+    catalogs: manifest.catalogs,
+    dependents: parseLockfileDependents(lockfile),
+  });
+}
+
+function readIgnoreFindings(
+  sources: Readonly<DependencyGateSources>,
+  ignoreIDs: readonly string[],
+): DependencyGateFinding[] {
+  return collectUnneededAuditIgnores({
+    ignoreIDs,
+    advisories: parseAuditAdvisories(runBun(sources, ['audit', '--json'])),
+    fixablePackages: parseFixablePackages(runBun(sources, ['audit', 'fix', '--dry-run', '--json'])),
+  });
+}
+
+// `bun audit` exits 1 while any advisory remains, ignored ones included, so only empty output fails.
+function runBun(sources: Readonly<DependencyGateSources>, args: readonly string[]): string {
+  const result = sources.runProgram(['bun', ...args], { cwd: sources.cwd, env: sources.env });
+
+  if (result.stdout.trim() === '') {
+    throw new Error(
+      `bun ${args.join(' ')} printed nothing and exited ${result.exitCode}: ${result.stderr.trim()}`,
+    );
+  }
+
+  return result.stdout;
+}

package/src/dependency-gates/run-dependency-gates-check.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runProgram } from '../run-program.ts';
+import type { DependencyGateSources } from './read-dependency-gate-findings.ts';
+import { readDependencyGateFindings } from './read-dependency-gate-findings.ts';
+
+export interface DependencyGatesCheck extends DependencyGateSources {
+  readonly writeOutput: (text: string) => void;
+  readonly writeError: (text: string) => void;
+}
+
+export function runDependencyGatesCheck(check: Readonly<DependencyGatesCheck>): number {
+  try {
+    const findings = readDependencyGateFindings(check);
+
+    for (const finding of findings) {
+      check.writeOutput(`${finding.path}: ${finding.entry}: ${finding.problem}\n`);
+    }
+
+    return findings.length === 0 ? 0 : 1;
+  } catch (error) {
+    check.writeError(
+      `dependency-gates: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+
+    return 2;
+  }
+}
+
+export function runDependencyGatesCommand(): number {
+  const cwd = process.cwd();
+
+  return runDependencyGatesCheck({
+    cwd,
+    env: process.env,
+    today: new Date().toISOString().slice(0, 10),
+    runProgram,
+    readRepoFile: (path) => {
+      const fullPath = join(cwd, path);
+
+      return existsSync(fullPath) ? readFileSync(fullPath, 'utf8') : null;
+    },
+    writeOutput: (text) => {
+      process.stdout.write(text);
+    },
+    writeError: (text) => {
+      process.stderr.write(text);
+    },
+  });
+}
+
+if (import.meta.main) {
+  process.exitCode = runDependencyGatesCommand();
+}

package/src/dependency-gates/types.ts

@@ -0,0 +1,19 @@
+export interface DependencyGateFinding {
+  // The repo file that holds the entry, relative to the repo root.
+  readonly path: string;
+
+  readonly entry: string;
+  readonly problem: string;
+}
+
+export interface LockfileDependent {
+  readonly dependent: string;
+  readonly name: string;
+  readonly range: string;
+}
+
+// An ignore names an advisory by its GHSA ID or by bun's numeric ID, so an advisory carries both.
+export interface AuditAdvisory {
+  readonly advisoryIDs: readonly string[];
+  readonly packageName: string;
+}

package/src/docs/check-length.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# Checks each README against its line limit and each docs/ file against its cap. A README over its
+# limit fails the run; a README over its target and a docs/ file over its cap print a warning and
+# never fail it. Its last line counts the READMEs and those over their limit.
+# Usage (from the repo root): check-length.sh
+# A README's limit comes from its path alone: the root README and each packages/*/README.md take the
+# front page and package limits, and every other README takes the folder limit. A spike README under
+# docs/design/**/spikes/ is a folder README, not a doc. --package <readme> is deprecated: the script
+# accepts it, prints a notice, and ignores it.
+set -uo pipefail
+
+if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
+  echo "check-length: run it inside a git work tree, because it lists the files with git" >&2
+  exit 2
+fi
+
+usage() {
+  echo "usage: check-length.sh" >&2
+  exit 2
+}
+
+while [ "$#" -gt 0 ]; do
+  case $1 in
+    --package)
+      [ "$#" -ge 2 ] || usage
+      echo "check-length: --package is deprecated and ignored; a README's limit comes from its path" >&2
+      shift 2
+      ;;
+    *) usage ;;
+  esac
+done
+
+# Lists tracked and untracked files, so a new doc 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.
+# 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 file
+  if ! listing=$(git -c core.quotePath=false ls-files --cached --others --exclude-standard -- "$@"); then
+    echo "check-length: git ls-files failed, so no file was checked" >&2
+    exit 2
+  fi
+  while IFS= read -r file; do
+    [ -n "$file" ] && [ -f "$file" ] && printf '%s\n' "$file"
+  done < <(sort -u <<< "$listing")
+  return 0
+}
+
+count_lines() {
+  awk 'END { print NR }' "$1"
+}
+
+# Prints the README's target, limit and kind.
+pick_readme_kind() {
+  local readme=$1
+
+  if [ "$readme" = README.md ]; then
+    echo '80 100 front page'
+  elif [[ $readme == packages/*/README.md && $readme != packages/*/*/README.md ]]; then
+    echo '80 100 package'
+  else
+    echo '60 70 folder'
+  fi
+}
+
+fail=0
+readmes=0
+over_limit=0
+spike_readmes='docs/design/**/spikes/*/README.md'
+spike_files='docs/design/**/spikes/**'
+
+# docs/README.md is the docs index, so the docs cap governs it, not a README limit. A spike README
+# under docs/design/ is a README.
+readme_list=$(
+  list_files ':(glob)**/README.md' ':(exclude,glob)docs/**' ':(exclude,glob).claude/**' \
+    ':(exclude,glob).agents/**'
+
+  # git ls-files warns on a pathspec whose folder is missing.
+  if [ -d docs/design ]; then
+    list_files ":(glob)$spike_readmes"
+  fi
+) || exit 2
+
+while IFS= read -r readme; do
+  [ -n "$readme" ] || continue
+  readmes=$((readmes + 1))
+  read -r target limit name <<< "$(pick_readme_kind "$readme")"
+  lines=$(count_lines "$readme")
+
+  if [ "$lines" -gt "$limit" ]; then
+    fail=1
+    over_limit=$((over_limit + 1))
+    echo "$readme: $lines lines, over the $name README limit of $limit (target $target; error)"
+  elif [ "$lines" -gt "$target" ]; then
+    echo "$readme: $lines lines, over the $name README target of $target (limit $limit; warning)"
+  else
+    echo "$readme: $lines lines ($name README; target $target, limit $limit)"
+  fi
+done < <(sort <<< "$readme_list")
+
+# A spike's README takes a README limit, and its other files have no cap.
+docs=$(list_files ':(glob)docs/**/*.md' ":(exclude,glob)$spike_files") || exit 2
+
+while IFS= read -r doc; do
+  [ -n "$doc" ] || continue
+  cap=250
+  case /$doc in */runbooks/*) cap=300 ;; esac
+  lines=$(count_lines "$doc")
+
+  if [ "$lines" -gt "$cap" ]; then
+    echo "$doc: $lines lines, over the docs cap of $cap (warning: cut points, then split at a concept boundary)"
+  fi
+done <<< "$docs"
+
+echo
+echo "check-length: $readmes READMEs, $over_limit over the line limit"
+exit "$fail"

package/src/docs/check-links.sh

@@ -0,0 +1,245 @@
+#!/usr/bin/env bash
+# Checks every relative link and anchor in Markdown files; exits non-zero on a broken one.
+# Usage (from the repo root): check-links.sh [<path>...]
+# With no path, it reads every README.md outside .claude/ and .agents/, every spike's results.md,
+# every Markdown file under docs/, and every skill's Markdown 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 link with a
+# scheme (https:, mailto:) is never followed. An anchor is checked only on a Markdown target, against
+# GitHub's heading anchors and the page's explicit id and name attributes.
+set -uo pipefail
+
+if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
+  echo "check-links: run it inside a git work tree, because it lists the files with git" >&2
+  exit 2
+fi
+
+if [ "$#" -eq 0 ]; then
+  set -- ':(glob)**/README.md' ':(glob)**/results.md' ':(glob)docs/**/*.md' \
+    ':(glob).agents/skills/**/*.md' ':(glob).claude/skills/**/*.md' ':(glob)skills/**/*.md' \
+    ':(glob)sync/skills/**/*.md' \
+    ':(exclude,glob).claude/**/README.md' ':(exclude,glob).agents/**/README.md'
+fi
+
+# The repo's project-docs-writing skill links to placeholder targets as examples, and so do the
+# docs-writing and skill-writing bases that zgeoff/tools keeps under sync/skills/ and delivers to
+# .claude/skills/. A file git marks linguist-vendored belongs to someone else.
+set -- "$@" ':(exclude).agents/skills/project-docs-writing' \
+  ':(exclude).claude/skills/project-docs-writing' ':(exclude).claude/skills/docs-writing' \
+  ':(exclude).claude/skills/skill-writing' ':(exclude)sync/skills/docs-writing' \
+  ':(exclude)sync/skills/skill-writing' ':(exclude,attr:linguist-vendored)' \
+  ':(exclude,attr:linguist-vendored=true)'
+
+# The pipeline below drops git's exit status until perl has printed its summary, so a git that
+# cannot list the files fails here first.
+if ! git ls-files --cached --others --exclude-standard -- "$@" > /dev/null; then
+  echo "check-links: git ls-files failed, so no link was checked" >&2
+  exit 2
+fi
+
+# Reads untracked files too, so a new doc is checked before it is staged.
+git ls-files -z --cached --others --exclude-standard -- "$@" | perl -0 -COE -e '
+use strict;
+use warnings;
+
+my (%seen, @files);
+while (my $file = <STDIN>) {
+  chomp $file;
+  utf8::decode($file);
+  next if $file !~ /\.md\z/ || $seen{$file}++ || !-f to_bytes($file);
+  push @files, $file;
+}
+
+my (%anchor_cache, $broken);
+
+for my $file (sort @files) {
+  my $line_number = 0;
+  my $open = "";
+  my $in_comment = 0;
+  for my $line (read_lines($file)) {
+    $line_number++;
+    if ($open eq "") {
+      ($line, $in_comment) = strip_comments($line, $in_comment);
+    }
+    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 "";
+    for my $target (collect_targets($line)) {
+      my $problem = check_target($file, $target);
+      next unless defined $problem;
+      print STDERR "$file:$line_number: ($target) $problem\n";
+      $broken++;
+    }
+  }
+}
+
+if ($broken) {
+  exit 1;
+}
+printf "check-links: %d files, every relative link resolves\n", scalar @files;
+
+# File names stay decoded text until they reach the filesystem.
+sub to_bytes {
+  my ($text) = @_;
+  utf8::encode($text);
+  return $text;
+}
+
+# GitHub never renders an HTML comment, so a link inside one is dropped. Returns the line without
+# its comments and whether a comment is still open at its end.
+sub strip_comments {
+  my ($line, $in_comment) = @_;
+  my $kept = "";
+  while (length $line) {
+    if ($in_comment) {
+      my $end = index $line, "-->";
+      return ($kept, 1) if $end < 0;
+      $line = substr $line, $end + 3;
+      $in_comment = 0;
+    } else {
+      my $start = index $line, "<!--";
+      return ($kept . $line, 0) if $start < 0;
+      $kept .= substr $line, 0, $start;
+      $line = substr $line, $start + 4;
+      $in_comment = 1;
+    }
+  }
+  return ($kept, $in_comment);
+}
+
+sub read_lines {
+  my ($path) = @_;
+  local $/ = "\n";
+  open my $fh, "<:encoding(UTF-8)", to_bytes($path) or die "check-links: cannot read $path: $!\n";
+  my @lines = <$fh>;
+  close $fh;
+  chomp @lines;
+  return @lines;
+}
+
+# Inline links and images, reference definitions, and HTML href and src attributes. Code spans
+# are dropped first, since a link inside one is literal text. A target may hold one level of
+# balanced parentheses, and a footnote definition is no link.
+sub collect_targets {
+  my ($line) = @_;
+  $line =~ s/(`+).*?\1//g;
+  my @targets;
+  push @targets, $1 while $line =~ /\]\(\s*(<[^>]*>|(?:[^()\s]|\([^()\s]*\))+)/g;
+  push @targets, $1 if $line =~ /^\s{0,3}\[(?!\^)[^\]]+\]:\s*(<[^>]*>|\S+)/;
+  push @targets, $1 while $line =~ /\b(?:href|src)\s*=\s*"([^"]*)"/g;
+  return map { s/^<(.*)>$/$1/r } @targets;
+}
+
+sub check_target {
+  my ($file, $target) = @_;
+  return undef if $target eq "" || $target =~ m{^(?:[a-z][a-z0-9+.-]*:|//)}i;
+  my ($path, $anchor) = split /#/, $target, 2;
+  $path =~ s/\?.*//;
+  $path = decode_percent($path);
+  my $resolved = $path eq "" ? $file : resolve_path($file, $path);
+  return "points outside the repository" unless defined $resolved;
+  return "$resolved does not exist" unless -e to_bytes($resolved);
+  return undef if !defined $anchor || $anchor eq "" || -d to_bytes($resolved) || $resolved !~ /\.md\z/;
+  $anchor = decode_percent($anchor);
+  my $anchors = $anchor_cache{$resolved} //= collect_anchors($resolved);
+  return $anchors->{$anchor} ? undef : "$resolved has no heading #$anchor";
+}
+
+sub decode_percent {
+  my ($text) = @_;
+  utf8::encode($text);
+  $text =~ s/%([0-9A-Fa-f]{2})/chr hex $1/ge;
+  utf8::decode($text);
+  return $text;
+}
+
+# A leading slash resolves from the repository root, as GitHub resolves it.
+sub resolve_path {
+  my ($file, $path) = @_;
+  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) : ".";
+}
+
+# GitHub anchors: ATX and setext headings outside code blocks, slugged and numbered on repeat,
+# plus explicit id and name attributes.
+sub collect_anchors {
+  my ($path) = @_;
+  my (%anchors, %count);
+  my $open = "";
+  my $previous = "";
+  my @lines = read_lines($path);
+  my $start = 0;
+  if (@lines && $lines[0] eq "---") {
+    for my $i (1 .. $#lines) {
+      if ($lines[$i] eq "---") { $start = $i + 1; last }
+    }
+  }
+  for my $line (@lines[$start .. $#lines]) {
+    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 = "" }
+      $previous = "";
+      next;
+    }
+    next if $open ne "";
+    my $title;
+    if ($line =~ /^ {0,3}#{1,6}(?:\s+(.*?))?\s*$/) {
+      $title = ($1 // "") =~ s/\s+#+\s*$//r;
+    } elsif ($line =~ /^ {0,3}(?:=+|-+)\s*$/ && $previous =~ /\S/
+      && $previous !~ /^\s*(?:[-*+]\s|\d+[.)]\s|>|#|\|)/) {
+      $title = $previous =~ s/^\s+|\s+$//gr;
+    }
+    if (defined $title) {
+      my $slug = build_slug($title);
+      my $n = $count{$slug}++;
+      $anchors{$n ? "$slug-$n" : $slug} = 1;
+    }
+    $anchors{$1} = 1 while $line =~ /\b(?:id|name)\s*=\s*"([^"]+)"/g;
+    $previous = $line;
+  }
+  return \%anchors;
+}
+
+# GitHub slugs the rendered heading text. Outside code spans, link syntax, HTML tags and emphasis
+# markers drop and entities decode; a code span keeps its text. Then the text is lowercased,
+# every character but a letter, mark, digit, "_", "-" or space dropped, and each space a "-".
+sub build_slug {
+  my ($title) = @_;
+  my @parts = split /(`+[^`]*`+)/, $title;
+  for my $part (@parts) {
+    if ($part =~ /^`+([^`]*)`+$/) {
+      $part = $1;
+      next;
+    }
+    $part =~ s/!?\[([^\]]*)\]\([^)]*\)/$1/g;
+    $part =~ s/<[^>]+>//g;
+    $part =~ s/(?<![\p{L}\p{N}])[_*]+|[_*]+(?![\p{L}\p{N}])//g;
+    $part =~ s/&#(\d+);/chr $1/ge;
+    $part =~ s/&#x([0-9a-f]+);/chr hex $1/gie;
+    my %entities = (amp => "&", lt => "<", gt => ">", quot => q("), nbsp => " ");
+    $part =~ s/&(amp|lt|gt|quot|nbsp);/$entities{$1}/g;
+  }
+  $title = lc join "", @parts;
+  $title =~ s/^\s+|\s+$//g;
+  $title =~ s/[^\p{L}\p{M}\p{N}_\- ]//g;
+  $title =~ s/ /-/g;
+  return $title;
+}
+'