@acme-skunkworks/agent-skills 1.0.0 → 1.1.0

package/skills/preflight/config.example.json

@@ -0,0 +1,6 @@
+{
+  "baseBranch": "main",
+  "workspaces": {
+    "web": { "filter": "@acme/web", "prefix": "apps/web/" }
+  }
+}

package/skills/preflight/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@acme-skunkworks/skill-preflight",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Agent skill: change-gated, branch-scoped lint preflight — lint only the categories a branch touched (ESLint / markdownlint / actionlint), classify violations as introduced vs pre-existing, and drive the fix/defer loop via an exit-code contract.",
+  "keywords": [
+    "agent-skill",
+    "claude-code",
+    "cursor",
+    "lint",
+    "eslint",
+    "markdownlint",
+    "actionlint",
+    "preflight"
+  ],
+  "homepage": "https://github.com/acme-skunkworks/agent-skills/tree/main/skills/preflight#readme",
+  "bugs": {
+    "url": "https://github.com/acme-skunkworks/agent-skills/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/acme-skunkworks/agent-skills.git",
+    "directory": "skills/preflight"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Rob Easthope",
+    "url": "https://github.com/RobEasthope"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/skills/preflight/scripts/classify-lint.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * Classify lint violations as introduced (branch) vs pre-existing.
+ */
+import {
+  getIntroducedLinesPerFile,
+  isIntroducedLine,
+} from "./lib/diff-lines.mjs";
+import { toRepoRelative } from "./lib/paths.mjs";
+
+/**
+ * @typedef {{ file: string; line: number; column?: number; ruleId?: string; message: string; source: 'eslint' | 'markdownlint' | 'actionlint' }} Violation
+ * @typedef {{ introduced: Violation[]; preExisting: Violation[] }} Classified
+ */
+
+/**
+ * @param {string} mergeBase
+ * @param {Violation[]} violations
+ * @returns {Classified}
+ */
+export function classifyViolations(mergeBase, violations) {
+  const introducedByFile = getIntroducedLinesPerFile(mergeBase);
+  /** @type {Violation[]} */
+  const introduced = [];
+  /** @type {Violation[]} */
+  const preExisting = [];
+
+  for (const v of violations) {
+    if (isIntroducedLine(introducedByFile, v.file, v.line)) {
+      introduced.push(v);
+    } else {
+      preExisting.push(v);
+    }
+  }
+
+  return { introduced, preExisting };
+}
+
+/**
+ * @param {string} eslintJson
+ * @returns {Violation[]}
+ */
+export function parseEslintJson(eslintJson) {
+  if (!eslintJson.trim()) {
+    return [];
+  }
+
+  let data;
+  try {
+    data = JSON.parse(eslintJson);
+  } catch {
+    return [];
+  }
+
+  if (!Array.isArray(data)) {
+    return [];
+  }
+
+  /** @type {Violation[]} */
+  const violations = [];
+  for (const result of data) {
+    const file = toRepoRelative(result.filePath ?? "");
+    for (const msg of result.messages ?? []) {
+      // Drop severity 0 (off) only. Severity 1 (warn) is kept and counts as a
+      // blocking violation when on an introduced line — preflight is
+      // deliberately strict about warnings the branch adds.
+      if (msg.severity === 0 || !msg.line) {
+        continue;
+      }
+
+      violations.push({
+        file,
+        line: msg.line,
+        column: msg.column,
+        ruleId: msg.ruleId,
+        message: msg.message,
+        source: "eslint",
+      });
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * markdownlint-cli2 JSON: array of { fileName, lineNumber, ruleNames, ruleDescription, ... }
+ * @param {string} mdJson
+ * @returns {Violation[]}
+ */
+export function parseMarkdownlintJson(mdJson) {
+  if (!mdJson.trim()) {
+    return [];
+  }
+
+  let data;
+  try {
+    data = JSON.parse(mdJson);
+  } catch {
+    return [];
+  }
+
+  const items = Array.isArray(data) ? data : (data?.issues ?? []);
+  if (!Array.isArray(items)) {
+    return [];
+  }
+
+  /** @type {Violation[]} */
+  const violations = [];
+  for (const item of items) {
+    const file = toRepoRelative(item.fileName ?? item.file ?? "");
+    const line = item.lineNumber ?? item.line;
+    if (!file || !line) {
+      continue;
+    }
+
+    violations.push({
+      file,
+      line,
+      ruleId: Array.isArray(item.ruleNames)
+        ? item.ruleNames.join("/")
+        : item.ruleName,
+      message:
+        item.ruleDescription ??
+        item.ruleInformation ??
+        "markdownlint violation",
+      source: "markdownlint",
+    });
+  }
+
+  return violations;
+}
+
+/**
+ * actionlint outputs text to stderr; map line-based errors when present.
+ *
+ * Lines that don't match `file:line:col: message` are attributed to the single
+ * workflow file when only one was passed, and otherwise silently dropped.
+ * preflight's process-level guard exits 1 whenever actionlint exits non-zero
+ * with no parseable violations, which catches the all-or-nothing failure case.
+ * If a run emits a mix of parseable and unparseable lines the parseable ones
+ * still surface and the unmatched lines remain dropped — in practice
+ * actionlint's text format is consistent enough that this case is vanishingly
+ * rare.
+ * @param {string} stderr
+ * @param {string[]} workflowFiles
+ * @returns {Violation[]}
+ */
+export function parseActionlintText(stderr, workflowFiles) {
+  /** @type {Violation[]} */
+  const violations = [];
+  const lines = stderr.split("\n").filter(Boolean);
+  for (const line of lines) {
+    const match = line.match(/^([^:]+):(\d+):(\d+): (.+)$/);
+    if (match) {
+      violations.push({
+        file: toRepoRelative(match[1]),
+        line: Number(match[2]),
+        column: Number(match[3]),
+        message: match[4],
+        source: "actionlint",
+      });
+      continue;
+    }
+
+    if (workflowFiles.length === 1) {
+      violations.push({
+        file: workflowFiles[0],
+        line: 1,
+        message: line,
+        source: "actionlint",
+      });
+    }
+  }
+
+  return violations;
+}

package/skills/preflight/scripts/lib/diff-lines.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * Map branch-introduced line numbers per file from git diff hunks.
+ */
+import { spawnSync } from "node:child_process";
+
+/**
+ * @param {string} mergeBase
+ * @returns {Map<string, Set<number>>}
+ */
+export function getIntroducedLinesPerFile(mergeBase) {
+  const result = spawnSync(
+    "git",
+    ["diff", `${mergeBase}...HEAD`, "-U0", "--no-color"],
+    // A large branch diff can exceed Node's 1 MiB default and be silently
+    // truncated (with `result.error` set but `status` possibly still 0).
+    // Truncation drops hunks → introduced lines misclassified as pre-existing
+    // → preflight falsely passes, so raise the limit and treat `error` as fatal.
+    { encoding: "utf8", maxBuffer: 10 * 1024 * 1024 },
+  );
+  if (result.error || result.status !== 0) {
+    const detail =
+      result.error?.message ||
+      result.stderr?.trim() ||
+      "unknown git diff error";
+    throw new Error(
+      `preflight: git diff for line classification failed: ${detail}`,
+    );
+  }
+
+  /** @type {Map<string, Set<number>>} */
+  const byFile = new Map();
+  let currentFile = null;
+
+  for (const line of result.stdout.split("\n")) {
+    if (line.startsWith("+++ b/")) {
+      const path = line.slice("+++ b/".length);
+      currentFile = path === "/dev/null" ? null : path;
+      continue;
+    }
+
+    if (!line.startsWith("@@") || !currentFile) {
+      continue;
+    }
+
+    const plus = line.match(/\+(\d+)(?:,(\d+))?/);
+    if (!plus) {
+      continue;
+    }
+
+    const start = Number(plus[1]);
+    const count = plus[2] === undefined ? 1 : Number(plus[2]);
+    if (count === 0) {
+      continue;
+    }
+
+    if (!byFile.has(currentFile)) {
+      byFile.set(currentFile, new Set());
+    }
+
+    const lines = byFile.get(currentFile);
+    for (let i = 0; i < count; i++) {
+      lines.add(start + i);
+    }
+  }
+
+  return byFile;
+}
+
+/**
+ * @param {Map<string, Set<number>>} introducedByFile
+ * @param {string} filePath
+ * @param {number} line
+ */
+export function isIntroducedLine(introducedByFile, filePath, line) {
+  const normalized = filePath.replace(/^\.\//, "");
+  const introduced = introducedByFile.get(normalized);
+  if (!introduced) {
+    return false;
+  }
+
+  return introduced.has(line);
+}

package/skills/preflight/scripts/lib/paths.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * Normalise tool output paths to repo-relative form (matches git diff keys).
+ */
+import { relative, resolve } from "node:path";
+
+const ROOT = process.cwd();
+
+/**
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function toRepoRelative(filePath) {
+  if (!filePath) {
+    return "";
+  }
+
+  const abs = filePath.startsWith("/") ? filePath : resolve(ROOT, filePath);
+  const rel = relative(ROOT, abs);
+
+  if (rel.startsWith("..")) {
+    return filePath.replace(/^\//, "").replace(/\\/g, "/");
+  }
+
+  return rel.replace(/\\/g, "/");
+}