action-pinner 0.1.0

package/dist/src/types.d.ts

@@ -0,0 +1,170 @@
+export type ScanMode = "scan" | "fix" | "enforce" | "pr";
+export interface PRConfig {
+    create: boolean;
+    branchPrefix: string;
+    title: string;
+    labels: string[];
+    reviewers: string[];
+    assignees: string[];
+    bodyTemplate?: string;
+}
+export interface EnforcementConfig {
+    enabled: boolean;
+    failOnUnpinned: boolean;
+    allowActions: string[];
+    exceptions: EnforcementException[];
+}
+export interface EnforcementException {
+    action: string;
+    ref?: string;
+    workflow?: string;
+    reason?: string;
+    justification?: string;
+    expiresAt?: string;
+}
+export interface DependabotConfig {
+    addVersionComments: boolean;
+    commentFormat: string;
+    generateConfigSnippet: boolean;
+}
+export interface OrgConfig {
+    name?: string;
+    type?: "org" | "user";
+    includePrivate: boolean;
+    includeArchived: boolean;
+}
+export interface PinActionsConfig {
+    mode: ScanMode;
+    include: string[];
+    exclude: string[];
+    repos: string[];
+    includeRepos: string[];
+    excludeActions: string[];
+    excludeRepos: string[];
+    org: OrgConfig;
+    pr: PRConfig;
+    enforcement: EnforcementConfig;
+    dependabot: DependabotConfig;
+    githubApiUrl?: string;
+    useNetrc?: boolean;
+}
+export type ActionRefKind = "pinned-sha" | "tag-or-branch" | "local" | "docker" | "invalid";
+export interface ActionReference {
+    filePath: string;
+    line: number;
+    column?: number;
+    raw: string;
+    action: string;
+    ref?: string;
+    kind: ActionRefKind;
+}
+export interface ResolutionResult {
+    original: string;
+    sha: string;
+    comment: string;
+    sourceRepo: string;
+    resolutionMethod: string;
+    resolvedAt: string;
+}
+export interface PinEvidence {
+    filePath: string;
+    line: number;
+    originalRef: string;
+    resolvedSha: string;
+    sourceRepo: string;
+    resolutionMethod: string;
+    resolvedAt: string;
+}
+export interface FilePatch {
+    filePath: string;
+    originalContent: string;
+    updatedContent: string;
+    referencesUpdated: ActionReference[];
+    evidence: PinEvidence[];
+}
+export interface ScanResult {
+    summary: ScanSummary;
+    references: ActionReference[];
+    unpinned: ActionReference[];
+}
+export interface ScanSummary {
+    filesScanned: number;
+    referencesFound: number;
+    unpinnedFound: number;
+}
+export type EnforcementFindingOutcome = "allowed" | "violation";
+export type EnforcementFindingReason = "allowlist" | "exception" | "unpinned" | "expired-exception" | "invalid-exception";
+export type EnforcementExceptionIssueReason = "expired" | "invalid-action" | "invalid-ref" | "invalid-workflow" | "invalid-expiry";
+export interface EnforcementFinding extends ActionReference {
+    outcome: EnforcementFindingOutcome;
+    reason: EnforcementFindingReason;
+    message: string;
+    exception?: EnforcementException;
+    matchedPattern?: string;
+}
+export interface EnforcementExceptionIssue {
+    index: number;
+    reason: EnforcementExceptionIssueReason;
+    message: string;
+    exception: EnforcementException;
+}
+export interface EnforcementSummary extends ScanSummary {
+    allowedCount: number;
+    violationCount: number;
+    invalidExceptionCount: number;
+}
+export interface EnforcementResult {
+    summary: EnforcementSummary;
+    references: ActionReference[];
+    allowed: EnforcementFinding[];
+    violations: EnforcementFinding[];
+    invalidExceptions: EnforcementExceptionIssue[];
+    compliant: boolean;
+}
+export interface MultiRepoEnforcementEntry {
+    repository: string;
+    defaultBranch: string;
+    scan: ScanResult;
+    enforcement: EnforcementResult;
+}
+export interface MultiRepoEnforcementResult {
+    repositories: MultiRepoEnforcementEntry[];
+    summary: {
+        repositoriesScanned: number;
+        repositoriesWithViolations: number;
+        filesScanned: number;
+        referencesFound: number;
+        unpinnedFound: number;
+        allowedCount: number;
+        violationCount: number;
+        invalidExceptionCount: number;
+    };
+    invalidExceptions: EnforcementExceptionIssue[];
+    compliant: boolean;
+}
+export interface ResolutionErrorDetails {
+    ref: string;
+    reason: string;
+    suggestions?: string[];
+    retryDetails?: {
+        attempts: number;
+        maxAttempts: number;
+        lastError?: string;
+    };
+}
+export declare class AmbiguousRefError extends Error {
+    readonly details: ResolutionErrorDetails & {
+        matchingShas: Array<{
+            sha: string;
+            source: string;
+        }>;
+    };
+    constructor(ref: string, matchingShas: Array<{
+        sha: string;
+        source: string;
+    }>);
+}
+export declare class UnresolvedRefError extends Error {
+    readonly details: ResolutionErrorDetails;
+    constructor(ref: string, attempts: number, maxAttempts: number, lastError?: string);
+}

package/dist/src/types.js

@@ -0,0 +1,41 @@
+export class AmbiguousRefError extends Error {
+    details;
+    constructor(ref, matchingShas) {
+        const details = {
+            ref,
+            reason: "Ambiguous ref resolved to multiple SHAs",
+            matchingShas,
+            suggestions: [
+                "Use pinning logic to explicitly specify the target SHA",
+                "Use explicit flags to disambiguate the reference"
+            ]
+        };
+        super(`Ambiguous ref: ${ref} resolved to ${matchingShas.length} SHAs`);
+        this.name = "AmbiguousRefError";
+        this.details = details;
+    }
+}
+export class UnresolvedRefError extends Error {
+    details;
+    constructor(ref, attempts, maxAttempts, lastError) {
+        const details = {
+            ref,
+            reason: "Could not resolve ref after retries",
+            suggestions: [
+                "Verify the ref exists in the repository",
+                "For private repositories, use a least-privilege token with Contents: Read (or classic repo scope only if fine-grained tokens are not available)",
+                "Add Pull requests: Write only when you are using PR creation features",
+                "Use --continue-on-error to skip this reference"
+            ],
+            retryDetails: {
+                attempts,
+                maxAttempts,
+                lastError
+            }
+        };
+        super(`Failed to resolve ${ref} after ${attempts} attempts: ${lastError}`);
+        this.name = "UnresolvedRefError";
+        this.details = details;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAgMA,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1B,OAAO,CAErB;IAEF,YACE,GAAW,EACX,YAAoD;QAEpD,MAAM,OAAO,GAAG;YACd,GAAG;YACH,MAAM,EAAE,yCAAyC;YACjD,YAAY;YACZ,WAAW,EAAE;gBACX,wDAAwD;gBACxD,kDAAkD;aACnD;SACF,CAAC;QACF,KAAK,CAAC,kBAAkB,GAAG,gBAAgB,YAAY,CAAC,MAAM,OAAO,CAAC,CAAC;QACvE,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3B,OAAO,CAAyB;IAEhD,YAAY,GAAW,EAAE,QAAgB,EAAE,WAAmB,EAAE,SAAkB;QAChF,MAAM,OAAO,GAAG;YACd,GAAG;YACH,MAAM,EAAE,qCAAqC;YAC7C,WAAW,EAAE;gBACX,yCAAyC;gBACzC,iJAAiJ;gBACjJ,uEAAuE;gBACvE,gDAAgD;aACjD;YACD,YAAY,EAAE;gBACZ,QAAQ;gBACR,WAAW;gBACX,SAAS;aACV;SACF,CAAC;QACF,KAAK,CAAC,qBAAqB,GAAG,UAAU,QAAQ,cAAc,SAAS,EAAE,CAAC,CAAC;QAC3E,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}

package/dist/src/version.d.ts

@@ -0,0 +1 @@
+export declare function getToolVersion(): Promise<string>;

package/dist/src/version.js

@@ -0,0 +1,22 @@
+import { readFile } from "node:fs/promises";
+let versionPromise;
+export function getToolVersion() {
+    versionPromise ??= readPackageVersion();
+    return versionPromise;
+}
+async function readPackageVersion() {
+    for (const relativePath of ["../package.json", "../../package.json"]) {
+        try {
+            const packageJson = await readFile(new URL(relativePath, import.meta.url), "utf8");
+            const parsed = JSON.parse(packageJson);
+            if (typeof parsed.version === "string" && parsed.version.length > 0) {
+                return parsed.version;
+            }
+        }
+        catch {
+            // Try the next known package.json location.
+        }
+    }
+    throw new Error("Unable to determine tool version from package.json.");
+}
+//# sourceMappingURL=version.js.map

package/dist/src/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,IAAI,cAA2C,CAAC;AAEhD,MAAM,UAAU,cAAc;IAC5B,cAAc,KAAK,kBAAkB,EAAE,CAAC;IACxC,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,KAAK,UAAU,kBAAkB;IAC/B,KAAK,MAAM,YAAY,IAAI,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,EAAE,CAAC;QACrE,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,MAAM,QAAQ,CAAC,IAAI,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;YACnF,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAA0B,CAAC;YAChE,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpE,OAAO,MAAM,CAAC,OAAO,CAAC;YACxB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;QAC9C,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;AACzE,CAAC"}

package/dist/src/workflow-paths.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_WORKFLOW_PATTERNS: string[];
+export declare function resolveWorkflowPatterns(inputs?: string[]): string[];
+export declare function normalizeWorkflowPattern(pattern: string): string;
+export declare function toDisplayPath(filePath: string, cwd?: string): string;

package/dist/src/workflow-paths.js

@@ -0,0 +1,29 @@
+import { relative, sep } from "node:path";
+export const DEFAULT_WORKFLOW_PATTERNS = [
+    ".github/workflows/**/*.yml",
+    ".github/workflows/**/*.yaml"
+];
+const GLOB_PATTERN = /[*?[{]/;
+export function resolveWorkflowPatterns(inputs = []) {
+    if (inputs.length === 0) {
+        return DEFAULT_WORKFLOW_PATTERNS.map(normalizeWorkflowPattern);
+    }
+    return inputs.flatMap((input) => {
+        const normalized = normalizeWorkflowPattern(input);
+        if (GLOB_PATTERN.test(normalized) || isWorkflowFile(normalized)) {
+            return [normalized];
+        }
+        const base = normalized.replace(/\/+$/, "");
+        return [`${base}/**/*.yml`, `${base}/**/*.yaml`];
+    });
+}
+export function normalizeWorkflowPattern(pattern) {
+    return pattern.replace(/\\/g, "/");
+}
+function isWorkflowFile(path) {
+    return path.endsWith(".yml") || path.endsWith(".yaml");
+}
+export function toDisplayPath(filePath, cwd = process.cwd()) {
+    return relative(cwd, filePath).split(sep).join("/");
+}
+//# sourceMappingURL=workflow-paths.js.map

package/dist/src/workflow-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-paths.js","sourceRoot":"","sources":["../../src/workflow-paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,4BAA4B;IAC5B,6BAA6B;CAC9B,CAAC;AAEF,MAAM,YAAY,GAAG,QAAQ,CAAC;AAE9B,MAAM,UAAU,uBAAuB,CAAC,SAAmB,EAAE;IAC3D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,yBAAyB,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;QACnD,IAAI,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,cAAc,CAAC,UAAU,CAAC,EAAE,CAAC;YAChE,OAAO,CAAC,UAAU,CAAC,CAAC;QACtB,CAAC;QAED,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC5C,OAAO,CAAC,GAAG,IAAI,WAAW,EAAE,GAAG,IAAI,YAAY,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,OAAe;IACtD,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE;IACjE,OAAO,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtD,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "action-pinner",
+  "version": "0.1.0",
+  "description": "Modern, maintained utility for pinning GitHub Actions to commit SHAs.",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist/src/",
+    "dist/index.*",
+    "README.md",
+    "LICENSE",
+    "action.yml"
+  ],
+  "bin": {
+    "action-pinner": "dist/src/index.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rimraf dist",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "lint": "tsc --noEmit -p tsconfig.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "github-actions",
+    "security",
+    "supply-chain",
+    "dependabot",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jongalloway/action-pinner.git"
+  },
+  "homepage": "https://github.com/jongalloway/action-pinner#readme",
+  "bugs": {
+    "url": "https://github.com/jongalloway/action-pinner/issues"
+  },
+  "dependencies": {
+    "@octokit/rest": "^22.0.0",
+    "commander": "^14.0.0",
+    "fast-glob": "^3.3.3",
+    "simple-git": "^3.28.0",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.1",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}