actions-warden 0.1.0

package/src/commands/upgrade.js

@@ -0,0 +1,281 @@
+/**
+ * Upgrade command - bump pinned (or tagged) actions to the newest version
+ * permitted by the chosen policy.
+ *
+ * For SHA-pinned refs, the human-readable version is read from the inline
+ * comment (e.g. `# v3.1.0`). If absent, the action is reported as `unknown`
+ * and skipped.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import semver from 'semver';
+import { parseWorkflowSource, collectUses } from '../lib/parser.js';
+import { discoverWorkflows, resolveWorkflowArg } from '../lib/paths.js';
+import { listTags, pickLatestTag, resolveRefToSha, resolveToken, getCommitDate } from '../lib/resolver.js';
+import { writeFileGuarded } from '../lib/writer.js';
+import { parseIgnoreDirectives, isIgnored } from '../lib/ignore.js';
+import { rewriteUses } from './pin.js';
+import { format } from '../lib/formatter.js';
+
+const SHA_RE = /^[0-9a-f]{40}$/i;
+const INLINE_COMMENT_RE = /uses\s*:[^\n#]*#\s*([^\s]+)/;
+
+/**
+ * @typedef {object} UpgradeChange
+ * @property {string} id
+ * @property {string} file
+ * @property {string} action
+ * @property {string} fromRef
+ * @property {string|null} fromVersion
+ * @property {string} toTag
+ * @property {string} toSha
+ * @property {'major'|'minor'|'patch'|'unknown'} level
+ * @property {number} line
+ */
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.cwd]
+ * @param {string[]} [opts.workflows]
+ * @param {boolean} [opts.dryRun]
+ * @param {string} [opts.token]
+ * @param {'major'|'minor'|'patch'} [opts.mode]
+ * @param {string} [opts.fix]
+ * @param {number} [opts.minAgeDays]   - skip tags newer than this many days
+ * @returns {Promise<{changes: UpgradeChange[], errors: object[], skipped: object[], status: 'OK'|'FAIL'}>}
+ */
+export async function upgrade({
+  cwd = process.cwd(),
+  workflows,
+  dryRun = true,
+  token,
+  mode = 'minor',
+  fix,
+  minAgeDays = 7,
+} = {}) {
+  const files = await resolveTargets(workflows, cwd);
+  const tok = resolveToken(token);
+  /** @type {UpgradeChange[]} */
+  const changes = [];
+  const errors = [];
+  /** @type {object[]} */
+  const skipped = [];
+  const cooldownMs = Math.max(minAgeDays, 0) * 86_400_000;
+
+  for (const file of files) {
+    let source;
+    try {
+      source = await readFile(file, 'utf8');
+    } catch (err) {
+      errors.push({ file, error: String(err.message ?? err) });
+      continue;
+    }
+    const lines = source.split('\n');
+    let doc;
+    try {
+      doc = parseWorkflowSource(source, file);
+    } catch (err) {
+      errors.push({ file, error: String(err.message ?? err) });
+      continue;
+    }
+
+    const ignore = parseIgnoreDirectives(source);
+    const planned = [];
+    for (const { ref } of collectUses(doc)) {
+      if (ref.kind !== 'external' && ref.kind !== 'reusable-workflow') continue;
+      if (isIgnored(ignore, ref.line, 'unpinned-action')) continue;
+      const usesLine = lines[ref.line - 1] ?? '';
+      const inlineVersion = readInlineVersion(usesLine);
+      const currentVersion = ref.ref && SHA_RE.test(ref.ref) ? inlineVersion : ref.ref;
+      if (!currentVersion) continue;
+
+      let tags;
+      try {
+        tags = await listTags({ owner: ref.owner, repo: ref.repo, token: tok, cwd });
+      } catch (err) {
+        errors.push({ file, action: ref.raw, error: String(err.message ?? err) });
+        continue;
+      }
+      const latest = await pickAgedTag({
+        tags,
+        currentRef: currentVersion,
+        mode,
+        cooldownMs,
+        owner: ref.owner,
+        repo: ref.repo,
+        token: tok,
+        cwd,
+        skipped,
+        file,
+        ref,
+      });
+      if (!latest) continue;
+      if (latest.name === currentVersion) continue;
+      const level = bumpLevel(currentVersion, latest.name);
+      let resolved;
+      try {
+        resolved = await resolveRefToSha({
+          owner: ref.owner,
+          repo: ref.repo,
+          ref: latest.name,
+          token: tok,
+          cwd,
+        });
+      } catch (err) {
+        errors.push({ file, action: ref.raw, error: String(err.message ?? err) });
+        continue;
+      }
+      planned.push({ ref, latest, sha: resolved.sha, level, currentVersion });
+    }
+
+    let newSource = source;
+    for (const { ref, latest, sha, level, currentVersion } of planned) {
+      const change = {
+        id: changeId(file, ref.raw, latest.name),
+        file,
+        action: `${ref.owner}/${ref.repo}`,
+        fromRef: ref.ref,
+        fromVersion: currentVersion,
+        toTag: latest.name,
+        toSha: sha,
+        level,
+        line: ref.line,
+      };
+      if (fix && fix !== change.id) continue;
+      newSource = rewriteUses(newSource, ref, sha);
+      newSource = fixInlineComment(newSource, ref, latest.name, sha);
+      changes.push(change);
+    }
+    if (newSource !== source) {
+      await writeFileGuarded({ path: file, content: newSource, dryRun, cwd });
+    }
+  }
+  return { changes, errors, skipped, status: errors.length === 0 ? 'OK' : 'FAIL' };
+}
+
+/**
+ * Walk candidate tags newest-first and return the first whose commit is older
+ * than the cooldown threshold. Skipped candidates are recorded.
+ */
+async function pickAgedTag({ tags, currentRef, mode, cooldownMs, owner, repo, token, cwd, skipped, file, ref }) {
+  if (cooldownMs <= 0) {
+    return pickLatestTag({ tags, currentRef, mode });
+  }
+  const remaining = [...tags];
+  const cutoff = Date.now() - cooldownMs;
+  for (;;) {
+    const candidate = pickLatestTag({ tags: remaining, currentRef, mode });
+    if (!candidate) return null;
+    let dateMs;
+    try {
+      dateMs = await getCommitDate({ owner, repo, sha: candidate.sha, token, cwd });
+    } catch {
+      return candidate;
+    }
+    if (dateMs <= cutoff) return candidate;
+    skipped.push({
+      file,
+      action: `${ref.owner}/${ref.repo}`,
+      tag: candidate.name,
+      reason: 'cooldown',
+      ageDays: Math.round((Date.now() - dateMs) / 86_400_000),
+    });
+    const idx = remaining.findIndex(t => t.name === candidate.name);
+    if (idx === -1) return null;
+    remaining.splice(idx, 1);
+  }
+}
+
+function readInlineVersion(line) {
+  const m = INLINE_COMMENT_RE.exec(line);
+  return m ? m[1] : null;
+}
+
+function bumpLevel(from, to) {
+  const a = semver.coerce(from);
+  const b = semver.coerce(to);
+  if (!a || !b) return 'unknown';
+  if (a.major !== b.major) return 'major';
+  if (a.minor !== b.minor) return 'minor';
+  return 'patch';
+}
+
+function fixInlineComment(source, ref, newTag, sha) {
+  const left = ref.subpath ? `${ref.owner}/${ref.repo}/${ref.subpath}` : `${ref.owner}/${ref.repo}`;
+  const escLeft = escRe(left);
+  const escSha = escRe(sha);
+  const re = new RegExp(
+    `(uses\\s*:\\s*['"]?)${escLeft}@${escSha}(['"]?)\\s*#\\s*[^\\n]+`,
+    'g',
+  );
+  return source.replace(re, (_, prefix, closingQuote) => `${prefix}${left}@${sha}${closingQuote} # ${newTag}`);
+}
+
+function escRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function changeId(file, raw, target) {
+  return createHash('sha1').update(`up:${file}:${raw}->${target}`).digest('hex').slice(0, 10);
+}
+
+async function resolveTargets(workflows, cwd) {
+  if (!workflows || workflows.length === 0) return discoverWorkflows({ cwd });
+  const out = new Set();
+  for (const w of workflows) {
+    for (const f of await resolveWorkflowArg(w, cwd)) out.add(f);
+  }
+  return [...out].sort();
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof upgrade>>} result
+ * @param {{format: 'toon'|'json'|'text', dryRun: boolean, mode: string, cwd?: string}} opts
+ */
+export function renderUpgrade(result, opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  if (opts.format === 'json') {
+    return format('json', [], {
+      status: result.status,
+      json: {
+        dryRun: opts.dryRun,
+        mode: opts.mode,
+        changes: result.changes.map(c => ({ ...c, file: rel(c.file, cwd) })),
+        skipped: (result.skipped ?? []).map(s => ({ ...s, file: rel(s.file ?? '', cwd) })),
+        errors: result.errors,
+        status: result.status,
+      },
+    });
+  }
+  const records = [];
+  for (const c of result.changes) {
+    records.push({
+      label: 'UPGRADE',
+      fields: {
+        id: c.id,
+        file: rel(c.file, cwd),
+        line: c.line,
+        action: c.action,
+        from: c.fromVersion ?? c.fromRef,
+        to: c.toTag,
+        sha: c.toSha,
+        level: c.level,
+        applied: !opts.dryRun,
+      },
+    });
+  }
+  for (const s of result.skipped ?? []) {
+    records.push({ label: 'SKIP', fields: { file: rel(s.file ?? '', cwd), action: s.action, tag: s.tag, reason: s.reason, age_days: s.ageDays } });
+  }
+  for (const e of result.errors) {
+    records.push({ label: 'ERROR', fields: { file: rel(e.file ?? '', cwd), action: e.action ?? '', msg: e.error } });
+  }
+  records.push({ label: 'SUMMARY', fields: { changes: result.changes.length, skipped: (result.skipped ?? []).length, errors: result.errors.length, mode: opts.mode, dry_run: opts.dryRun } });
+  return format(opts.format, records, { status: result.status });
+}
+
+function rel(p, cwd) {
+  if (p && p.startsWith(cwd)) return p.slice(cwd.length + 1);
+  return p;
+}

package/src/index.js

@@ -0,0 +1,19 @@
+/**
+ * Public programmatic API.
+ *
+ * Each command can be invoked without spawning a subprocess:
+ *
+ *   import { audit, pin, upgrade, report } from 'actions-warden';
+ *   const result = await audit({ cwd: '/repo' });
+ */
+
+export { audit, renderAudit } from './commands/audit.js';
+export { pin, renderPin, rewriteUses } from './commands/pin.js';
+export { upgrade, renderUpgrade } from './commands/upgrade.js';
+export { report, renderReport } from './commands/report.js';
+export { listRules } from './rules/index.js';
+export { parseWorkflowFile, parseWorkflowSource, collectUses, parseActionRef } from './lib/parser.js';
+export { format, renderToon, renderJson, renderText, summarize, SEVERITY_ORDER } from './lib/formatter.js';
+export { discoverWorkflows } from './lib/paths.js';
+export { redact } from './lib/redact.js';
+export { parseIgnoreDirectives, isIgnored } from './lib/ignore.js';

package/src/lib/cache.js

@@ -0,0 +1,68 @@
+/**
+ * On-disk cache for GitHub API responses.
+ *
+ * Keyed by sha1 of the request URL. TTL stored in the cache entry. Files live
+ * in `.actions-warden-cache/` inside the working directory.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { createHash } from 'node:crypto';
+
+/**
+ * @typedef {object} CacheEntry
+ * @property {number} savedAt   - ms epoch
+ * @property {number} ttlMs
+ * @property {unknown} value
+ */
+
+/**
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function cacheDir(cwd = process.cwd()) {
+  return resolve(cwd, '.actions-warden-cache');
+}
+
+/**
+ * @param {string} key
+ * @returns {string}
+ */
+function digest(key) {
+  return createHash('sha1').update(key).digest('hex');
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.key
+ * @param {number} [opts.ttlMs]     - default 1h
+ * @param {string} [opts.cwd]
+ * @returns {Promise<unknown|undefined>}
+ */
+export async function readCache({ key, ttlMs = 3600 * 1000, cwd = process.cwd() }) {
+  const path = join(cacheDir(cwd), `${digest(key)}.json`);
+  try {
+    const raw = await readFile(path, 'utf8');
+    /** @type {CacheEntry} */
+    const entry = JSON.parse(raw);
+    if (Date.now() - entry.savedAt > Math.min(entry.ttlMs, ttlMs)) return undefined;
+    return entry.value;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.key
+ * @param {unknown} opts.value
+ * @param {number} [opts.ttlMs]
+ * @param {string} [opts.cwd]
+ */
+export async function writeCache({ key, value, ttlMs = 3600 * 1000, cwd = process.cwd() }) {
+  const dir = cacheDir(cwd);
+  await mkdir(dir, { recursive: true });
+  /** @type {CacheEntry} */
+  const entry = { savedAt: Date.now(), ttlMs, value };
+  await writeFile(join(dir, `${digest(key)}.json`), JSON.stringify(entry), 'utf8');
+}

package/src/lib/formatter.js

@@ -0,0 +1,136 @@
+/**
+ * Output formatter supporting TOON (Token-Oriented Object Notation), JSON, and
+ * plain text.
+ *
+ * TOON output rules:
+ *   - One record per line: `LABEL: key=value key=value`
+ *   - Values containing spaces or `=` are quoted: `msg="hello world"`
+ *   - Empty/null values are omitted
+ *   - Trailing `STATUS: OK` or `STATUS: FAIL` signal for machine consumers
+ */
+
+import { redact } from './redact.js';
+
+/**
+ * Severity ordering, lowest-to-highest.
+ */
+export const SEVERITY_ORDER = ['low', 'medium', 'high', 'critical'];
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function quoteIfNeeded(value) {
+  if (value === '') return '""';
+  if (/[\s="]/.test(value)) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+
+/**
+ * Serialize a record to a single TOON line.
+ *
+ * @param {string} label
+ * @param {Record<string, unknown>} fields
+ * @returns {string}
+ */
+export function toonLine(label, fields) {
+  const parts = [];
+  for (const [k, v] of Object.entries(fields)) {
+    if (v === null || v === undefined || v === '') continue;
+    const value = typeof v === 'string' ? v : String(v);
+    parts.push(`${k}=${quoteIfNeeded(redact(value))}`);
+  }
+  return parts.length === 0 ? `${label}:` : `${label}: ${parts.join(' ')}`;
+}
+
+/**
+ * Render a TOON document.
+ *
+ * @param {Array<{label: string, fields: Record<string, unknown>}>} records
+ * @param {{status?: 'OK'|'FAIL'}} [options]
+ * @returns {string}
+ */
+export function renderToon(records, options = {}) {
+  const lines = records.map(r => toonLine(r.label, r.fields));
+  if (options.status) lines.push(`STATUS: ${options.status}`);
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Render JSON with stable key ordering and 2-space indent.
+ *
+ * @param {unknown} payload
+ * @returns {string}
+ */
+export function renderJson(payload) {
+  return JSON.stringify(payload, null, 2) + '\n';
+}
+
+/**
+ * Render plain text (human-readable summary).
+ *
+ * @param {Array<{label: string, fields: Record<string, unknown>}>} records
+ * @param {{status?: 'OK'|'FAIL'}} [options]
+ * @returns {string}
+ */
+export function renderText(records, options = {}) {
+  const lines = records.map(r => {
+    const kv = Object.entries(r.fields)
+      .filter(([, v]) => v !== null && v !== undefined && v !== '')
+      .map(([k, v]) => `${k}=${redact(String(v))}`)
+      .join(' ');
+    return `[${r.label}] ${kv}`;
+  });
+  if (options.status) lines.push(`==> ${options.status}`);
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Format records into the requested output mode.
+ *
+ * @param {'toon'|'json'|'text'} format
+ * @param {Array<{label: string, fields: Record<string, unknown>}>} records
+ * @param {{status?: 'OK'|'FAIL', json?: unknown}} [options]
+ * @returns {string}
+ */
+export function format(format_, records, options = {}) {
+  switch (format_) {
+    case 'json':
+      return renderJson(options.json ?? recordsToJson(records, options));
+    case 'text':
+      return renderText(records, options);
+    case 'toon':
+    default:
+      return renderToon(records, options);
+  }
+}
+
+/**
+ * Convert records to a generic JSON payload when no custom JSON is supplied.
+ *
+ * @param {Array<{label: string, fields: Record<string, unknown>}>} records
+ * @param {{status?: string}} options
+ * @returns {object}
+ */
+function recordsToJson(records, options) {
+  return {
+    records: records.map(r => ({ label: r.label, ...r.fields })),
+    status: options.status ?? null,
+  };
+}
+
+/**
+ * Aggregate findings into a summary record.
+ *
+ * @param {Array<{severity: string}>} findings
+ * @returns {Record<string, number>}
+ */
+export function summarize(findings) {
+  const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const f of findings) {
+    if (counts[f.severity] !== undefined) counts[f.severity] += 1;
+  }
+  return counts;
+}

package/src/lib/ignore.js

@@ -0,0 +1,134 @@
+/**
+ * Inline ignore directives in workflow sources.
+ *
+ * Directives (accept either `actions-warden-` or `aw-` prefix):
+ *
+ *   # actions-warden-ignore-file                - silence the entire file
+ *   # actions-warden-ignore-start               - start a block (until -end)
+ *   # actions-warden-ignore-end                 - end the current block
+ *   # actions-warden-ignore-next-line           - silence the next non-comment line
+ *   # actions-warden-ignore                     - silence the same line (inline)
+ *
+ * Optional rule filter: append rule ids after a colon, e.g.
+ *   # actions-warden-ignore: unpinned-action,secrets-in-env
+ *
+ * Without a filter the directive silences every rule.
+ */
+
+const PREFIX = '(?:actions-warden|aw)';
+const TAIL = '(?::\\s*([\\w,\\s-]+))?\\s*$';
+const RE_FILE = new RegExp(`#\\s*${PREFIX}-ignore-file${TAIL}`);
+const RE_START = new RegExp(`#\\s*${PREFIX}-ignore-start${TAIL}`);
+const RE_END = new RegExp(`#\\s*${PREFIX}-ignore-end\\s*$`);
+const RE_NEXT = new RegExp(`#\\s*${PREFIX}-ignore-next-line${TAIL}`);
+const RE_INLINE = new RegExp(`#\\s*${PREFIX}-ignore(?!-)${TAIL}`);
+
+/**
+ * @typedef {object} IgnoreScope
+ * @property {boolean} wholeFile
+ * @property {Set<string>|null} fileRules           - null means "all rules"
+ * @property {Array<{start: number, end: number, rules: Set<string>|null}>} ranges
+ * @property {Map<number, Set<string>|null>} lines  - line -> ignored rule set (or null = all)
+ */
+
+/**
+ * @param {string|null|undefined} list   comma- or whitespace-separated rule ids
+ * @returns {Set<string>|null}            null = match every rule
+ */
+function parseRuleList(list) {
+  if (!list) return null;
+  const ids = list.split(/[\s,]+/).map(s => s.trim()).filter(Boolean);
+  if (ids.length === 0) return null;
+  return new Set(ids);
+}
+
+/**
+ * @param {string} source
+ * @returns {IgnoreScope}
+ */
+export function parseIgnoreDirectives(source) {
+  /** @type {IgnoreScope} */
+  const scope = {
+    wholeFile: false,
+    fileRules: null,
+    ranges: [],
+    lines: new Map(),
+  };
+  const lines = source.split('\n');
+  /** @type {{start: number, rules: Set<string>|null}|null} */
+  let openBlock = null;
+
+  lines.forEach((text, i) => {
+    const lineNo = i + 1;
+    const fileMatch = text.match(RE_FILE);
+    if (fileMatch) {
+      scope.wholeFile = true;
+      scope.fileRules = parseRuleList(fileMatch[1]);
+      return;
+    }
+    const startMatch = text.match(RE_START);
+    if (startMatch) {
+      openBlock = { start: lineNo, rules: parseRuleList(startMatch[1]) };
+      return;
+    }
+    if (RE_END.test(text)) {
+      if (openBlock) {
+        scope.ranges.push({ start: openBlock.start, end: lineNo, rules: openBlock.rules });
+        openBlock = null;
+      }
+      return;
+    }
+    const nextMatch = text.match(RE_NEXT);
+    if (nextMatch) {
+      for (let j = i + 1; j < lines.length; j += 1) {
+        const next = lines[j].trim();
+        if (next === '' || next.startsWith('#')) continue;
+        mergeLine(scope.lines, j + 1, parseRuleList(nextMatch[1]));
+        break;
+      }
+      return;
+    }
+    const inlineMatch = text.match(RE_INLINE);
+    if (inlineMatch) {
+      mergeLine(scope.lines, lineNo, parseRuleList(inlineMatch[1]));
+    }
+  });
+
+  if (openBlock) {
+    scope.ranges.push({ start: openBlock.start, end: lines.length, rules: openBlock.rules });
+  }
+  return scope;
+}
+
+function mergeLine(map, line, rules) {
+  const existing = map.get(line);
+  if (existing === undefined) {
+    map.set(line, rules);
+    return;
+  }
+  if (existing === null || rules === null) {
+    map.set(line, null);
+    return;
+  }
+  for (const r of rules) existing.add(r);
+}
+
+/**
+ * @param {IgnoreScope} scope
+ * @param {number} line
+ * @param {string} ruleId
+ * @returns {boolean}
+ */
+export function isIgnored(scope, line, ruleId) {
+  if (scope.wholeFile && matches(scope.fileRules, ruleId)) return true;
+  for (const range of scope.ranges) {
+    if (line >= range.start && line <= range.end && matches(range.rules, ruleId)) return true;
+  }
+  const lineRules = scope.lines.get(line);
+  if (lineRules !== undefined && matches(lineRules, ruleId)) return true;
+  return false;
+}
+
+function matches(rules, ruleId) {
+  return rules === null ? true : rules.has(ruleId);
+}