@volter/twin-github 0.1.2 → 2.0.1

package/dist/src/semantics/push-reactions.js

@@ -0,0 +1,513 @@
+// What GitHub does when a branch moves, which no API call asks for:
+// - a workflow file committed under .github/workflows on the default branch is a workflow, named by its `name:`
+//   (docs.github.com/actions/writing-workflows/about-workflows), and a push of a branch or a tag runs every workflow of
+//   the pushed commit whose `on:` includes push and whose branch and tag filters take the ref
+//   (docs.github.com/actions/writing-workflows/choosing-when-your-workflow-runs);
+// - secret scanning reads every pushed file and raises an alert for each token it recognises, with where it was found
+//   (docs.github.com/code-security/secret-scanning/introduction/about-secret-scanning);
+// - Dependabot, once its alerts are on, reads the default branch's package.json manifests and raises an alert for a dependency an advisory
+//   names, and closes it as fixed once the manifest no longer asks for a vulnerable version
+//   (docs.github.com/code-security/dependabot/dependabot-alerts/about-dependabot-alerts);
+// - a run a runner finishes keeps what its workflow's steps uploaded: an artifact per actions/upload-artifact step
+//   (by its `name`) and a cache per actions/cache step (by its `key`) (docs.github.com/actions/using-workflows/
+//   storing-workflow-data-as-artifacts, docs.github.com/actions/using-workflows/caching-dependencies-to-speed-up-workflows);
+// - a direct push to a branch whose rulesets require pull requests is evaluated against them (directPushRules).
+//
+// Where the documentation stops and the twin decides: a workflow's `on:` and its steps are read by pattern, not by a
+// YAML parser, so a trigger or step written in an unusual form is not seen; the recognised tokens are GitHub's
+// personal access tokens (classic and fine-grained), AWS access key ids and Stripe live secret keys; the advisory table
+// is three real advisories (lodash, minimist, axios); an artifact's size is its name's length in KiB, a cache's its
+// key's.
+import { createHash } from 'node:crypto';
+import { actionsId, diffFilesInPlane, readGitTagFromPlane, planeAncestors, toGithubIssue, GITHUB_WORLD_USER, planeEntryAt, readGitBlobFromPlane, readGitTreeFromPlane, readGitCommitFromPlane, recordRuleSuite, rulesetsFor, } from "../github-twin.js";
+import { gh, put } from "./shared.js";
+const ZERO = '0'.repeat(40);
+const WORKFLOW_PATH = /^\.github\/workflows\/[^/]+\.ya?ml$/;
+/** Secret patterns GitHub's secret scanning recognises, with its type names. */
+const SECRETS = [
+    { type: 'github_personal_access_token', display: 'GitHub Personal Access Token', pattern: /\bghp_[A-Za-z0-9]{36}\b/g },
+    { type: 'github_personal_access_token', display: 'GitHub Personal Access Token', pattern: /\bgithub_pat_[A-Za-z0-9_]{82}\b/g },
+    { type: 'aws_access_key_id', display: 'Amazon AWS Access Key ID', pattern: /\bAKIA[0-9A-Z]{16}\b/g },
+    { type: 'stripe_api_key', display: 'Stripe API Key', pattern: /\bsk_live_[0-9A-Za-z]{24,}\b/g },
+];
+/** Advisories Dependabot knows: the package, the first fixed version, the advisory. */
+const ADVISORIES = [
+    { name: 'lodash', fixed: '4.17.21', ghsa: 'GHSA-35jh-r3h4-6jhm', severity: 'high', summary: 'Command Injection in lodash' },
+    { name: 'minimist', fixed: '1.2.6', ghsa: 'GHSA-xvch-5gv4-984h', severity: 'critical', summary: 'Prototype Pollution in minimist' },
+    { name: 'axios', fixed: '1.6.0', ghsa: 'GHSA-wf5p-g6vw-rhxx', severity: 'medium', summary: 'Axios Cross-Site Request Forgery Vulnerability' },
+];
+const versionParts = (v) => v.replace(/^[^0-9]*/, '').split(/[.+-]/).slice(0, 3).map((x) => Number.parseInt(x, 10) || 0);
+const below = (a, b) => {
+    const x = versionParts(a);
+    const y = versionParts(b);
+    for (let i = 0; i < 3; i++)
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) < (y[i] ?? 0);
+    return false;
+};
+const text = (b64) => Buffer.from(b64, 'base64').toString('utf8');
+/** A file's text at a commit, or undefined. */
+async function fileAt(repo, commit, path, root) {
+    const hit = await planeEntryAt(repo, commit, path, root);
+    if (!hit || hit.kind !== 'file')
+        return undefined;
+    const blob = await readGitBlobFromPlane(repo, hit.entry.sha, root);
+    return blob ? { text: text(blob.content_b64), sha: hit.entry.sha } : undefined;
+}
+/** Every file path in a commit's tree. */
+async function allPaths(repo, commit, root) {
+    const c = await readGitCommitFromPlane(repo, commit, root);
+    if (!c)
+        return [];
+    const out = [];
+    const walk = async (tree, prefix) => {
+        for (const e of (await readGitTreeFromPlane(repo, tree, root)) ?? []) {
+            const p = prefix ? `${prefix}/${e.path}` : e.path;
+            if (e.type === 'tree')
+                await walk(e.sha, p);
+            else if (e.type === 'blob')
+                out.push(p);
+        }
+    };
+    await walk(c.tree_sha, '');
+    return out;
+}
+/** The files a push added or changed, and those it removed. */
+async function changed(repo, before, after, root) {
+    if (before === ZERO)
+        return { touched: await allPaths(repo, after, root), removed: [] };
+    const diff = (await diffFilesInPlane(repo, before, after, root)) ?? [];
+    return { touched: diff.filter((f) => f.status !== 'removed').map((f) => f.filename), removed: diff.filter((f) => f.status === 'removed').map((f) => f.filename) };
+}
+const workflowName = (source, path) => /^name:\s*["']?([^"'\n]+?)["']?\s*$/m.exec(source)?.[1] ?? path;
+/** Whether a workflow's `on:` includes `event` (`on: push`, `on: [push, …]`, or a `push` key under `on:`). */
+function listensTo(source, event) {
+    const on = /^on:(.*)$/m.exec(source);
+    if (!on)
+        return false;
+    const word = new RegExp(`(?<![\\w-])${event}(?![\\w-])`);
+    if (word.test(on[1]))
+        return true;
+    for (const line of source.slice((on.index ?? 0) + on[0].length).split('\n').slice(1)) {
+        if (line.trim() && !/^[ \t]/.test(line))
+            break;
+        if (new RegExp(`^[ \\t]+-?\\s*${event}\\s*:?\\s*$`).test(line) || new RegExp(`^[ \\t]+${event}\\s*:`).test(line))
+            return true;
+    }
+    return false;
+}
+/** The list a workflow's `on: push:` gives under `key` (`branches`, `tags`, `branches-ignore`, `tags-ignore`), inline
+ *  (`[a, b]`) or as `- a` lines, or undefined when it gives none. */
+function pushFilter(source, key) {
+    const lines = source.split('\n');
+    const on = lines.findIndex((l) => /^on:\s*$/.test(l));
+    if (on === -1)
+        return undefined;
+    const push = lines.findIndex((l, i) => i > on && /^[ \t]+push:\s*$/.test(l));
+    if (push === -1)
+        return undefined;
+    const depth = (l) => /^[ \t]*/.exec(l)[0].length;
+    for (let i = push + 1; i < lines.length && (!lines[i].trim() || depth(lines[i]) > depth(lines[push])); i++) {
+        const m = new RegExp(`^([ \\t]+)${key}:\\s*(.*)$`).exec(lines[i]);
+        if (!m)
+            continue;
+        const unquote = (v) => v.trim().replace(/^["']|["']$/g, '');
+        if (m[2].trim().startsWith('['))
+            return m[2].trim().slice(1, -1).split(',').map(unquote).filter(Boolean);
+        const out = [];
+        for (let j = i + 1; j < lines.length && /^[ \t]+-\s*/.test(lines[j]) && depth(lines[j]) > m[1].length; j++)
+            out.push(unquote(lines[j].replace(/^[ \t]+-\s*/, '')));
+        return out;
+    }
+    return undefined;
+}
+/** A ref name against a workflow filter's glob: `*` is any run of characters but `/`, `**` any run at all
+ *  (docs.github.com/actions/writing-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet). */
+const globMatch = (pattern, name) => new RegExp(`^${pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, '\u0000').replace(/\*/g, '[^/]*').replace(/\u0000/g, '.*').replace(/\?/g, '.?')}$`).test(name);
+/** Whether a push of `ref` runs a workflow: its `on:` includes push, and its branch and tag filters let the ref
+ *  through. Defining only branch filters runs it for no tag, only tag filters for no branch, neither for both
+ *  (docs.github.com/actions/writing-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore). */
+function onPushOf(source, ref) {
+    if (!listensTo(source, 'push'))
+        return false;
+    const [branches, branchesIgnore, tags, tagsIgnore] = ['branches', 'branches-ignore', 'tags', 'tags-ignore'].map((k) => pushFilter(source, k));
+    const isTag = ref.startsWith('refs/tags/');
+    const name = ref.replace(/^refs\/(heads|tags)\//, '');
+    const [only, ignore, otherOnly, otherIgnore] = isTag ? [tags, tagsIgnore, branches, branchesIgnore] : [branches, branchesIgnore, tags, tagsIgnore];
+    if (!only && !ignore)
+        return !otherOnly && !otherIgnore;
+    if (only)
+        return only.some((p) => globMatch(p, name));
+    return !ignore.some((p) => globMatch(p, name));
+}
+/** A workflow's jobs, in file order: each job's id (its key under `jobs:`) and the name GitHub shows for it, its `name:`
+ *  or else its id (docs.github.com/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idname). */
+export function jobsOf(source) {
+    const at = /^jobs:\s*$/m.exec(source);
+    if (!at)
+        return [];
+    const out = [];
+    let indent;
+    let child; // the indentation of a job's own keys
+    for (const line of source.slice((at.index ?? 0) + at[0].length).split('\n').slice(1)) {
+        if (line.trim() && !/^[ \t]/.test(line))
+            break;
+        if (!line.trim())
+            continue;
+        const depth = /^[ \t]*/.exec(line)[0].length;
+        const key = /^[ \t]+([A-Za-z_][\w-]*):\s*$/.exec(line);
+        if (key && (indent === undefined || depth === indent)) {
+            indent = depth;
+            child = undefined;
+            out.push({ id: key[1], name: key[1] });
+            continue;
+        }
+        child ??= depth;
+        const name = /^[ \t]+name:\s*["']?([^"'\n]+?)["']?\s*$/.exec(line);
+        if (name && depth === child && out.length)
+            out.at(-1).name = name[1];
+    }
+    return out;
+}
+/** The permissions a workflow grants its GITHUB_TOKEN: its `permissions:` blocks (`contents: write`, or `read-all` /
+ *  `write-all`), over the default a repository created today has, read access to contents and packages
+ *  (docs.github.com/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). */
+export function tokenPermissions(source) {
+    const out = { contents: 'read', metadata: 'read', packages: 'read' };
+    const lines = source.split('\n');
+    for (const [i, line] of lines.entries()) {
+        const m = /^([ \t]*)permissions:\s*(\S*)\s*$/.exec(line);
+        if (!m)
+            continue;
+        if (m[2] === 'write-all' || m[2] === 'read-all')
+            for (const k of ['actions', 'checks', 'contents', 'deployments', 'issues', 'packages', 'pages', 'pull-requests', 'statuses'])
+                out[k] = m[2].slice(0, -4);
+        for (let j = i + 1; j < lines.length; j++) {
+            const kv = /^([ \t]+)([a-z-]+):\s*(read|write|none)\s*$/.exec(lines[j]);
+            if (!kv || kv[1].length <= m[1].length)
+                break;
+            out[kv[2]] = kv[3];
+        }
+    }
+    return out;
+}
+/** The runner labels a workflow's job asks for (`runs-on: ubuntu-latest`, or a list of them), read from its file. */
+function runsOn(st, repo, wf) {
+    const defaultBranch = st.repos.find((r) => r.full_name === repo)?.default_branch ?? 'main';
+    const file = st.contents.find((c) => c.repository === repo && c.path === wf.path && (c.branch ?? defaultBranch) === defaultBranch);
+    const source = file ? Buffer.from(file.content_b64 ?? '', 'base64').toString('utf8') : '';
+    const value = /^\s+runs-on:\s*(.+?)\s*$/m.exec(source)?.[1];
+    if (!value)
+        return [];
+    return value.startsWith('[') ? value.slice(1, -1).split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean) : [value.replace(/^["']|["']$/g, '')];
+}
+/** A queued run of a workflow, with a job per job of its file at the run's commit (one named for the workflow when
+ *  the file cannot be read): what a dispatch, a push or a pull request starts. A run from a fork that needs a
+ *  maintainer's approval first is created waiting, `action_required`, with no jobs until it is approved
+ *  (approveRun). */
+export async function queueRun(ctx, st, repo, wf, branch, headSha, event, actor, opts = {}) {
+    let runNumber = 0;
+    for (const r of st.workflowRuns)
+        if (r.repository === repo && r.workflow_id === wf.id)
+            runNumber = Math.max(runNumber, r.run_number);
+    runNumber += 1;
+    const runId = actionsId(`${repo}:run:${wf.id}:${runNumber}`);
+    const at = ctx.occurredAt;
+    const waiting = opts.awaitingApproval === true;
+    await put(ctx, { operation: `workflow_run.${event === 'push' ? 'push' : event === 'pull_request' ? 'pull_request' : 'dispatch'}`, subjectType: 'workflow_run', subjectId: `run:${runId}`, fields: { repository: repo, workflow_id: wf.id, name: wf.name, run_number: runNumber, event, status: waiting ? 'completed' : 'queued', conclusion: waiting ? 'action_required' : null, head_sha: headSha, head_branch: branch, created_at: at, updated_at: at, ...(actor ? { actor_login: actor } : {}), ...(opts.headRepo && opts.headRepo !== repo ? { head_repository: opts.headRepo } : {}) } });
+    if (!waiting)
+        await queueJobs(ctx, st, repo, wf, runId, runNumber, branch, headSha);
+    return runId;
+}
+/** The check run an Actions job reports on its commit: named for the job, under the GitHub Actions app's check suite,
+ *  with the job's status and conclusion, and the job's id (a job's check_run_url names it)
+ *  (docs.github.com/rest/guides/using-the-rest-api-to-interact-with-checks: GitHub Actions reports each job as a check
+ *  run; docs.github.com/rest/actions/workflow-jobs). */
+export function actionsCheckRun(job, status, conclusion, at) {
+    return {
+        operation: status === 'queued' ? 'check_run.create' : 'check_run.update', subjectType: 'check_run', subjectId: `check:${job.id}`,
+        fields: { repository: job.repository, head_sha: job.head_sha, name: job.name, status, conclusion, app_slug: 'github-actions', details_url: `https://github.com/${job.repository}/actions/runs/${job.run_id}/job/${job.id}`, ...(status === 'queued' ? { started_at: at, completed_at: null } : { completed_at: at }) },
+    };
+}
+/** A run's jobs, queued: one per job of the workflow file at the run's commit. The first keeps the id a run's single
+ *  job has always had. */
+export async function queueJobs(ctx, st, repo, wf, runId, runNumber, branch, headSha) {
+    const file = await fileAt(repo, headSha, wf.path, ctx.root);
+    const jobs = file ? jobsOf(file.text) : [];
+    const named = jobs.length ? jobs : [{ id: '', name: wf.name }];
+    for (const [i, job] of named.entries()) {
+        const jobId = actionsId(i === 0 ? `${repo}:job:${wf.id}:${runNumber}` : `${repo}:job:${wf.id}:${runNumber}:${job.id}`);
+        await put(ctx, { operation: 'workflow_job.create', subjectType: 'workflow_job', subjectId: `job:${jobId}`, fields: { run_id: runId, repository: repo, name: job.name, status: 'queued', conclusion: null, head_sha: headSha, steps: [{ name: 'set up job', status: 'queued', number: 1 }], labels: runsOn(st, repo, wf), workflow_name: wf.name, head_branch: branch, created_at: ctx.occurredAt } });
+        await put(ctx, actionsCheckRun({ id: jobId, repository: repo, head_sha: headSha, name: job.name, run_id: runId }, 'queued', null, ctx.occurredAt));
+    }
+}
+/** The issue numbers texts link with GitHub's closing keywords, `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`,
+ *  `resolve`, `resolves` or `resolved` before `#n` (docs.github.com/issues/tracking-your-work-with-issues/using-issues/
+ *  linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword). */
+export function closingIssueNumbers(texts) {
+    const out = [];
+    for (const text of texts)
+        for (const m of text.matchAll(/\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?):?\s+#(\d+)\b/gi))
+            if (!out.includes(Number(m[1])))
+                out.push(Number(m[1]));
+    return out;
+}
+/** Whether a pull request's author needs a maintainer to approve its workflow runs: by default a first-time
+ *  contributor from a fork, "users who have never had a commit or pull request merged into the repository"
+ *  (docs.github.com/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/
+ *  managing-github-actions-settings-for-a-repository#controlling-changes-from-forks-to-workflows-in-public-repositories).
+ *  Where the documentation stops and the twin decides: someone with write access to the repository (its owner, an
+ *  owner of its organization, a collaborator with write or more) is not a first-time contributor. */
+export function needsApproval(st, repo, author) {
+    if (!author || canWrite(st, repo, author))
+        return false;
+    return !st.prs.some((p) => p.repository === repo && p.is_pull_request && p.merged && p.user_login === author);
+}
+/** Whether `login` has write access to `repo`: its owner, an owner of its organization, or a collaborator with write
+ *  or more. */
+export function canWrite(st, repo, login) {
+    const owner = repo.split('/')[0];
+    if (login.toLowerCase() === owner.toLowerCase())
+        return true;
+    if (st.orgMembers.some((m) => m.org === owner && m.login === login && m.role === 'admin' && m.state === 'active'))
+        return true;
+    return st.collaborators.some((c) => c.repository === repo && c.login === login && ['push', 'write', 'maintain', 'admin'].includes(c.permission));
+}
+/** A pull request opened, reopened or pushed to runs the base repository's workflows whose `on:` includes
+ *  pull_request, as its head commit has them (docs.github.com/actions/writing-workflows/choosing-when-your-workflow-
+ *  runs/events-that-trigger-workflows#pull_request: by default on opened, synchronize and reopened). A first-time
+ *  contributor's run from a fork waits for approval (needsApproval). */
+export async function reactToPullRequest(ctx, repo, number, action) {
+    if (!['opened', 'synchronize', 'reopened'].includes(action))
+        return;
+    const { root, state, caller } = gh(ctx);
+    const pr = state().prs.find((p) => p.repository === repo && p.number === number && p.is_pull_request);
+    if (!pr?.head_sha || (pr.state ?? 'open') !== 'open')
+        return;
+    const fromFork = pr.head_repo !== undefined && pr.head_repo !== repo;
+    const waiting = fromFork && needsApproval(state(), repo, pr.user_login);
+    for (const wf of state().workflows.filter((w) => w.repository === repo && w.state === 'active')) {
+        const file = await fileAt(repo, pr.head_sha, wf.path, root);
+        if (file && listensTo(file.text, 'pull_request'))
+            await queueRun(ctx, state(), repo, wf, pr.head_ref ?? '', pr.head_sha, 'pull_request', caller ?? pr.user_login ?? undefined, { awaitingApproval: waiting, ...(pr.head_repo ? { headRepo: pr.head_repo } : {}) });
+    }
+}
+/** A direct push to a branch whose rulesets require pull requests fails those rules, and the push is refused when
+ *  one is active (docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/
+ *  available-rules-for-rulesets#require-a-pull-request-before-merging). In evaluate mode the push lands and its rule
+ *  suite records what would have failed (docs.github.com/.../managing-rulesets/managing-rulesets-for-a-repository#viewing-insights-for-rulesets). */
+export function directPushRules(st, repo, branch) {
+    const evaluations = [];
+    let refused;
+    for (const enforcement of ['active', 'evaluate']) {
+        for (const failed of rulesetsFor(st, repo, branch, enforcement).map((set) => pullRequestRuleFails(set, enforcement)))
+            if (failed) {
+                evaluations.push(failed);
+                if (enforcement === 'active')
+                    refused = failed.details;
+            }
+    }
+    return { refused, evaluations };
+}
+/** A push that landed past rules only evaluated is on the record as the rule suite it would have failed. */
+async function recordEvaluatedPush(ctx, repo, ref, before, after, evaluations) {
+    const { root, caller } = gh(ctx);
+    await recordRuleSuite(repo, { repository: repo, ref, actor_login: caller ?? GITHUB_WORLD_USER, before_sha: before, after_sha: after, pushed_at: ctx.occurredAt, result: 'fail', rules: evaluations }, ctx.occurredAt, root, (w) => put(ctx, w));
+}
+/** A token secret scanning recognises in a pushed file: an alert, with where it was found, unless one already holds it. */
+async function secretFound(ctx, repo, path, file, s, m, after) {
+    const { state } = gh(ctx);
+    const at = ctx.occurredAt;
+    const digest = createHash('sha256').update(m[0]).digest('hex');
+    const alerts = state().secretScanningAlerts.filter((a) => a.repository === repo);
+    if (alerts.some((a) => a._secret === digest))
+        return;
+    const number = Math.max(0, ...alerts.map((a) => a.number)) + 1;
+    const line = file.text.slice(0, m.index ?? 0).split('\n').length;
+    const column = (m.index ?? 0) - file.text.slice(0, m.index ?? 0).lastIndexOf('\n');
+    await put(ctx, {
+        operation: 'secret_scanning_alert.create', subjectType: 'secret_scanning_alert', subjectId: `secretscan:${repo}#${number}`,
+        fields: { number, repository: repo, state: 'open', secret_type: s.type, secret_type_display_name: s.display, created_at: at, updated_at: at, _secret: digest,
+            locations: [{ path, start_line: line, end_line: line, start_column: column, end_column: column + m[0].length, blob_sha: file.sha, commit_sha: after }] },
+    });
+}
+/** A ruleset's pull_request rule, which a direct push fails. */
+function pullRequestRuleFails(set, enforcement) {
+    if (!set.rules.some((r) => r.type === 'pull_request'))
+        return undefined;
+    return { ruleset_id: set.id, ruleset_name: set.name, rule_type: 'pull_request', enforcement, result: 'fail', details: 'Changes must be made through a pull request.' };
+}
+/** GitHub's reactions to a branch of `repo` moving from `before` to `after`. */
+export async function reactToPush(ctx, repo, ref, before, after) {
+    const { root, state, caller } = gh(ctx);
+    // a pushed tag runs the workflows whose push filters take it, as the tagged commit has them (an annotated tag is
+    // peeled to its commit); the run's branch is the tag's name
+    if (ref.startsWith('refs/tags/')) {
+        if (after === ZERO)
+            return;
+        const commit = (await readGitTagFromPlane(repo, after, root))?.object_sha ?? after;
+        for (const wf of state().workflows.filter((w) => w.repository === repo && w.state === 'active')) {
+            const file = await fileAt(repo, commit, wf.path, root);
+            if (file && onPushOf(file.text, ref))
+                await queueRun(ctx, state(), repo, wf, ref.slice('refs/tags/'.length), commit, 'push', caller);
+        }
+        return;
+    }
+    if (!ref.startsWith('refs/heads/'))
+        return;
+    const branch = ref.slice('refs/heads/'.length);
+    // A branch's files, as the Contents API keeps a receipt for each: a move writes the files it touched and drops
+    // those it removed, however it was made (an API commit, the Git Data API, a git push), and a deleted branch
+    // drops them all. The repository's language, size and licence, its code search and a workflow's runners read the
+    // default branch's.
+    const receipt = (path) => `content:${repo}#${branch}:${path}`;
+    const drop = (path) => put(ctx, { operation: 'content_file.delete', subjectType: 'content_file', subjectId: receipt(path), fields: { deleted: true, repository: repo, path, branch } });
+    if (after === ZERO) {
+        for (const c of state().contents.filter((x) => x.repository === repo && x.branch === branch))
+            await drop(c.path);
+        return;
+    }
+    const defaultBranch = state().repos.find((r) => r.full_name === repo)?.default_branch ?? 'main';
+    // a push that landed past rules only evaluated is on the record as the rule suite it would have failed
+    const rules = directPushRules(state(), repo, branch);
+    if (rules.evaluations.length)
+        await recordEvaluatedPush(ctx, repo, ref, before, after, rules.evaluations);
+    const { touched, removed } = await changed(repo, before, after, root);
+    for (const path of touched) {
+        const hit = await planeEntryAt(repo, after, path, root);
+        const blob = hit?.kind === 'file' ? await readGitBlobFromPlane(repo, hit.entry.sha, root) : null;
+        if (hit?.kind === 'file' && blob)
+            await put(ctx, { operation: 'content_file.update', subjectType: 'content_file', subjectId: receipt(path), fields: { repository: repo, path, branch, sha: hit.entry.sha, content_b64: blob.content_b64, size: blob.size, deleted: false } });
+    }
+    for (const path of removed)
+        await drop(path);
+    const at = ctx.occurredAt;
+    // secret scanning reads every pushed file, on any branch
+    for (const path of touched) {
+        const file = await fileAt(repo, after, path, root);
+        if (!file)
+            continue;
+        for (const s of SECRETS) {
+            for (const m of file.text.matchAll(s.pattern))
+                await secretFound(ctx, repo, path, file, s, m, after);
+        }
+    }
+    // workflows live on the default branch
+    for (const path of branch === defaultBranch ? [...touched, ...removed].filter((p) => WORKFLOW_PATH.test(p)) : []) {
+        // a workflow keeps its id when its repository is transferred and renamed
+        const existing = state().workflows.find((w) => w.repository === repo && w.path === path);
+        const id = existing?.id ?? actionsId(`${repo}:workflow:${path}`);
+        const file = removed.includes(path) ? undefined : await fileAt(repo, after, path, root);
+        await put(ctx, {
+            operation: file ? 'workflow.register' : 'workflow.delete', subjectType: 'workflow', subjectId: `workflow:${id}`,
+            fields: { repository: repo, name: file ? workflowName(file.text, path) : (existing?.name ?? path), path, state: file ? 'active' : 'deleted', created_at: existing?.created_at ?? at, updated_at: at },
+        });
+    }
+    // a push to any branch runs every workflow of the pushed commit that listens for pushes to it
+    for (const wf of state().workflows.filter((w) => w.repository === repo && w.state === 'active')) {
+        const file = await fileAt(repo, after, wf.path, root);
+        if (file && onPushOf(file.text, ref))
+            await queueRun(ctx, state(), repo, wf, branch, after, 'push', caller);
+    }
+    if (branch !== defaultBranch)
+        return;
+    // a commit pushed to the default branch closes the issues its message links with a closing keyword
+    // (docs.github.com/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue)
+    if (before !== ZERO) {
+        const held = await planeAncestors(repo, before, root);
+        const messages = [];
+        for (const sha of (await planeAncestors(repo, after, root)).keys())
+            if (!held.has(sha))
+                messages.push((await readGitCommitFromPlane(repo, sha, root))?.message ?? '');
+        for (const n of closingIssueNumbers(messages)) {
+            const issue = state().issues.find((i) => i.repository === repo && i.number === n);
+            // the close is the issue's move by the push (manifest.ts): a git push is another wire's (`external`)
+            const by = ctx.call.operation.id;
+            if (!issue || (issue.state ?? 'open') !== 'open' || ctx.legal('issue', 'state', by, issue.state ?? 'open', 'closed', issue.id, by === 'git-receive-pack' ? 'external' : 'api'))
+                continue;
+            await put(ctx, { operation: 'issue.update', subjectType: 'issue', subjectId: issue.id, fields: { number: n, repository: repo, state: 'closed', state_reason: 'completed', updated_at: at } });
+            const now = state();
+            const closed = now.issues.find((i) => i.id === issue.id);
+            const { announce } = await import("./shared.js");
+            await announce(ctx, [{ event: 'issues', action: 'closed', repository: repo, number: n, ...(closed ? { issue: toGithubIssue(closed, now.milestones, undefined, now.comments) } : {}) }]);
+        }
+    }
+    // Dependabot, when its alerts are on, reads the manifests the push changed
+    if (dependabotOn(ctx, repo))
+        await dependabotReads(ctx, repo, after, [...touched, ...removed].filter((p) => p === 'package.json' || p.endsWith('/package.json')), removed);
+}
+/** Whether Dependabot alerts are on for a repository: off until someone with admin access turns them on
+ *  (docs.github.com/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts,
+ *  docs.github.com/rest/repos/repos#enable-vulnerability-alerts). */
+export function dependabotOn(ctx, repo) {
+    return ctx.tree().some((r) => r.type === 'vulnerability_alerts' && r.repository === repo && r.enabled === true && r.deleted !== true);
+}
+/** Dependabot reads package.json manifests at a commit of the default branch: an alert opens for a dependency an
+ *  advisory names at a vulnerable version, and an open one is fixed once the manifest no longer asks for one
+ *  (docs.github.com/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). */
+export async function dependabotReads(ctx, repo, commit, manifests, removed = []) {
+    const { root, state } = gh(ctx);
+    const at = ctx.occurredAt;
+    for (const manifestPath of manifests) {
+        const file = removed.includes(manifestPath) ? undefined : await fileAt(repo, commit, manifestPath, root);
+        let deps = {};
+        try {
+            const pkg = file ? JSON.parse(file.text) : {};
+            deps = { ...(pkg.devDependencies ?? {}), ...(pkg.dependencies ?? {}) };
+        }
+        catch {
+            deps = {};
+        }
+        for (const adv of ADVISORIES) {
+            const alerts = state().dependabotAlerts.filter((a) => a.repository === repo);
+            const current = alerts.find((a) => a.package_name === adv.name && a.manifest_path === manifestPath && a.state !== 'fixed');
+            const wanted = deps[adv.name];
+            const vulnerable = wanted !== undefined && below(wanted, adv.fixed);
+            if (vulnerable && !current) {
+                const number = Math.max(0, ...alerts.map((a) => a.number)) + 1;
+                await put(ctx, { operation: 'dependabot_alert.create', subjectType: 'dependabot_alert', subjectId: `dependabot:${repo}#${number}`,
+                    fields: { number, repository: repo, state: 'open', package_name: adv.name, ecosystem: 'npm', ghsa_id: adv.ghsa, severity: adv.severity, summary: adv.summary, manifest_path: manifestPath, created_at: at, updated_at: at } });
+            }
+            else if (!vulnerable && current && current.state === 'open') {
+                await put(ctx, { operation: 'dependabot_alert.update', subjectType: 'dependabot_alert', subjectId: `dependabot:${repo}#${current.number}`, fields: { ...current, state: 'fixed', updated_at: at } });
+            }
+        }
+    }
+}
+/** Every package.json at a commit, for Dependabot's first read when its alerts are turned on. */
+export async function manifestsAt(repo, commit, root) {
+    return (await allPaths(repo, commit, root)).filter((p) => p === 'package.json' || p.endsWith('/package.json'));
+}
+/** An actions/cache step's cache, saved under its key when the job ends. */
+async function saveCache(repo, run, step, write, nextId, at) {
+    const key = /\bkey:\s*["']?([^"'\n]+?)["']?\s*$/m.exec(step)?.[1];
+    if (!key)
+        return;
+    const id = nextId('cache');
+    await write({ operation: 'actions_cache.create', subjectType: 'actions_cache', subjectId: `cache:${id}`, fields: { repository: repo, key, ref: `refs/heads/${run.head_branch ?? 'main'}`, size_in_bytes: key.length * 1024, created_at: at, last_accessed_at: at } });
+}
+/** What a run's workflow steps uploaded, read from the workflow file at the run's commit: its artifacts, uploaded while
+ *  it runs, and its caches, saved when its job ends. */
+export async function runOutputs(repo, run, st, root, write, nextId, at, what = { artifacts: true, caches: true }) {
+    const wf = st.workflows.find((w) => w.id === run.workflow_id);
+    if (!wf)
+        return;
+    const file = await fileAt(repo, run.head_sha, wf.path, root);
+    if (!file)
+        return;
+    // each `uses:` step and the `with:` block under it
+    const steps = file.text.split(/\n(?=\s*-\s)/);
+    for (const step of steps) {
+        const uses = /uses:\s*([^\s@]+)@/.exec(step)?.[1];
+        // an artifact is uploaded by its step, while the run is under way; upload-pages-artifact's is named github-pages
+        // unless its step names it (github.com/actions/upload-pages-artifact)
+        if (what.artifacts && (uses === 'actions/upload-artifact' || uses === 'actions/upload-pages-artifact')) {
+            const named = step.includes('with:') ? /\bname:\s*["']?([^"'\n]+?)["']?\s*$/m.exec(step.slice(step.indexOf('with:')))?.[1] : undefined;
+            const name = named ?? (uses === 'actions/upload-pages-artifact' ? 'github-pages' : 'artifact');
+            const id = nextId('artifact');
+            await write({ operation: 'actions_artifact.create', subjectType: 'actions_artifact', subjectId: `artifact:${id}`, fields: { repository: repo, name, size_in_bytes: name.length * 1024, run_id: run.id, expired: false, created_at: at } });
+        }
+        if (what.caches && uses === 'actions/cache')
+            await saveCache(repo, run, step, write, nextId, at);
+    }
+}

package/dist/src/semantics/releases.d.ts

@@ -0,0 +1,19 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+/** GitHub's generated release notes for `tag` (docs.github.com/repositories/releasing-projects-on-github/automatically-
+ *  generated-release-notes, docs.github.com/rest/releases/releases#generate-release-notes-content-for-a-release): the
+ *  pull requests merged since the previous release, each with its author, the contributors whose first merged pull
+ *  request is among them, and the full changelog's link. The previous release is the latest published one other than
+ *  this tag's, unless `previous` names a tag. Where the documentation stops and the twin decides: a repository's
+ *  release.yml categories are not read. */
+export declare function generatedNotes(ctx: SemanticsContext, tag: string, target: string | undefined, previous: string | undefined): Promise<{
+    name: string;
+    body: string;
+}>;
+/** A release asset's upload as it arrived: its raw bytes and their media type, which the server hands the upload
+ *  operation (github-server.ts) since GitHub reads this body as the file, not as JSON. */
+export declare const assetUploads: AsyncLocalStorage<{
+    bytes: Uint8Array;
+    type: string | null;
+}>;
+export declare function releasesSemantics(): Record<string, Semantics>;