actions-warden 0.3.0 → 0.4.0

package/src/commands/org-scan.js

@@ -3,8 +3,7 @@
  * fetch workflow YAML from each default branch, and aggregate audit findings.
  */
 
-import { realpath } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import picomatch from 'picomatch';
 import { auditSources } from './audit.js';
 import { loadBaseline } from '../lib/baseline.js';
@@ -27,6 +26,7 @@ import {
 } from '../lib/org-checkpoint.js';
 import { resolveToken } from '../lib/resolver.js';
 import { listRules, RULES } from '../rules/index.js';
+import { sameFilePath } from '../lib/path-equality.js';
 
 const VISIBILITIES = new Set(['all', 'public', 'private', 'internal']);
 const ORGANIZATION_RE = /^[A-Za-z0-9_.-]+$/;
@@ -126,7 +126,7 @@ export async function scanOrganization({
   });
   const loadedCheckpoint = resume
     ? await loadOrganizationCheckpoint({ path: checkpointPath, cwd, identity: checkpointIdentity })
-    : { results: new Map() };
+    : { results: new Map(), migrationRequired: false };
   if (resume) {
     await emitProgress(onProgress, {
       type: 'checkpoint-loaded',
@@ -177,9 +177,9 @@ export async function scanOrganization({
     identity: checkpointIdentity,
     results: checkpointResults,
   });
-  if (checkpointPath && !resume) {
+  if (checkpointPath && (!resume || loadedCheckpoint.migrationRequired)) {
     await persistCheckpoint();
-    await emitProgress(onProgress, { type: 'checkpoint-created' });
+    if (!resume) await emitProgress(onProgress, { type: 'checkpoint-created' });
   }
 
   let completed = 0;
@@ -495,18 +495,13 @@ function createCheckpointWriter({ path, cwd, identity, results }) {
 
 async function assertCheckpointDoesNotReplaceControlFile(path, cwd, controlFiles) {
   const requested = resolve(cwd, path);
-  const checkpoint = comparablePath(join(await realpath(dirname(requested)), basename(requested)));
   for (const controlFile of controlFiles) {
-    if (controlFile && comparablePath(resolve(controlFile)) === checkpoint) {
+    if (controlFile && await sameFilePath(requested, resolve(controlFile))) {
       throw new Error('checkpoint path cannot replace the active config or baseline');
     }
   }
 }
 
-function comparablePath(path) {
-  return process.platform === 'win32' ? path.toLowerCase() : path;
-}
-
 async function emitRetryProgress(onProgress, retry, repository) {
   await emitProgress(onProgress, {
     type: 'request-retry',

package/src/lib/agent-mode.js

@@ -6,13 +6,15 @@
  * derived from the same identity used to validate resumable checkpoints.
  */
 
-import { createHash } from 'node:crypto';
 import { lstat } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { loadBaseline } from './baseline.js';
 import { loadConfig } from './config.js';
 import { format } from './formatter.js';
-import { createOrganizationCheckpointIdentity } from './org-checkpoint.js';
+import {
+  createOrganizationCheckpointArtifactKey,
+  createOrganizationCheckpointIdentity,
+} from './org-checkpoint.js';
 import { RULES } from '../rules/index.js';
 
 export const AGENT_MODE_ENVIRONMENT_VARIABLE = 'ACTIONS_WARDEN_MODE';
@@ -99,10 +101,7 @@ export async function createOrganizationAgentArtifacts({
     config,
     baselineData,
   });
-  const key = createHash('sha256')
-    .update(JSON.stringify(identity))
-    .digest('hex')
-    .slice(0, 32);
+  const key = createOrganizationCheckpointArtifactKey(identity);
   const groupedKey = key.match(/.{8}/g).join('.');
   const checkpointPath = `.actions-warden-agent.${groupedKey}.checkpoint.json`;
   const reportExtension = REPORT_EXTENSIONS[reportFormat];

package/src/lib/org-checkpoint.js

@@ -18,7 +18,14 @@ import { listRules } from '../rules/index.js';
 import { VERSION } from '../version.js';
 
 const CHECKPOINT_KIND = 'actions-warden-org-scan';
-const CHECKPOINT_SCHEMA_VERSION = '1.0';
+const CHECKPOINT_SCHEMA_VERSION = '1.1';
+const LEGACY_CHECKPOINT_SCHEMA_VERSION = '1.0';
+const FIRST_ANALYSIS_GENERATION_TOOL_VERSION = '0.3.0';
+const TOOL_VERSION_RE = /^\d+\.\d+\.\d+$/;
+// Increment this whenever organization discovery, parsing, finding identity,
+// rule evaluation, or persisted result semantics can change. Package releases
+// that leave those behaviors compatible must keep the generation unchanged.
+export const ORGANIZATION_ANALYSIS_GENERATION = 1;
 export const MAX_ORGANIZATION_CHECKPOINT_BYTES = 256 * 1024 * 1024;
 const NAME_RE = /^[A-Za-z0-9_.-]+$/;
 const SHA_RE = /^[0-9a-f]{40}$/i;
@@ -41,7 +48,7 @@ export function createOrganizationCheckpointIdentity({
   baselineData,
 }) {
   return {
-    toolVersion: VERSION,
+    analysisGeneration: ORGANIZATION_ANALYSIS_GENERATION,
     rulesHash: RULES_HASH,
     organization: organization.toLowerCase(),
     scope: {
@@ -66,6 +73,42 @@ export function createOrganizationCheckpointIdentity({
   };
 }
 
+/**
+ * Create the stable key used by automatic agent artifacts.
+ *
+ * Generation 1 deliberately retains the exact identity serialization used by
+ * v0.3.0 so existing automatic checkpoints remain discoverable after an
+ * upgrade. Later generations use the version-independent compatibility
+ * identity directly.
+ */
+export function createOrganizationCheckpointArtifactKey(identity) {
+  const compatibleIdentity = identity.analysisGeneration === 1
+    ? {
+        toolVersion: FIRST_ANALYSIS_GENERATION_TOOL_VERSION,
+        rulesHash: identity.rulesHash,
+        organization: identity.organization,
+        scope: {
+          repositories: identity.scope.repositories,
+          visibility: identity.scope.visibility,
+          includeArchived: identity.scope.includeArchived,
+          includeDisabled: identity.scope.includeDisabled,
+          includeForks: identity.scope.includeForks,
+          maxRepositories: identity.scope.maxRepositories,
+          severity: identity.scope.severity,
+          explain: identity.scope.explain,
+        },
+        configHash: identity.configHash,
+        baselineHash: identity.baselineHash,
+      }
+    : identity;
+  return createHash('sha256')
+    .update(identity.analysisGeneration === 1
+      ? JSON.stringify(compatibleIdentity)
+      : stableStringify(compatibleIdentity))
+    .digest('hex')
+    .slice(0, 32);
+}
+
 export async function loadOrganizationCheckpoint({ path, cwd, identity }) {
   const resolvedPath = await resolveRepositoryFile(path, cwd);
   const metadata = await stat(resolvedPath);
@@ -83,13 +126,21 @@ export async function loadOrganizationCheckpoint({ path, cwd, identity }) {
     if (error instanceof SyntaxError) throw new Error('organization checkpoint is not valid JSON');
     throw error;
   }
-  if (!isRecord(checkpoint) || checkpoint.schemaVersion !== CHECKPOINT_SCHEMA_VERSION) {
-    throw new Error(`organization checkpoint schemaVersion must be "${CHECKPOINT_SCHEMA_VERSION}"`);
+  if (
+    !isRecord(checkpoint)
+    || ![CHECKPOINT_SCHEMA_VERSION, LEGACY_CHECKPOINT_SCHEMA_VERSION]
+      .includes(checkpoint.schemaVersion)
+  ) {
+    throw new Error(
+      `organization checkpoint schemaVersion must be "${CHECKPOINT_SCHEMA_VERSION}"`
+      + ` or "${LEGACY_CHECKPOINT_SCHEMA_VERSION}"`,
+    );
   }
   if (checkpoint.kind !== CHECKPOINT_KIND) {
     throw new Error('file is not an actions-warden organization checkpoint');
   }
-  validateIdentity(checkpoint.identity, identity);
+  const storedIdentity = normalizeCheckpointIdentity(checkpoint);
+  validateIdentity(storedIdentity, identity);
   if (!Array.isArray(checkpoint.repositories)) {
     throw new Error('organization checkpoint repositories must be an array');
   }
@@ -101,7 +152,12 @@ export async function loadOrganizationCheckpoint({ path, cwd, identity }) {
     if (results.has(key)) throw new Error(`duplicate checkpoint repository: ${result.repository}`);
     results.set(key, result);
   }
-  return { path: resolvedPath, results };
+  return {
+    path: resolvedPath,
+    results,
+    migrationRequired: checkpoint.schemaVersion !== CHECKPOINT_SCHEMA_VERSION
+      || checkpoint.toolVersion !== VERSION,
+  };
 }
 
 export async function validateOrganizationCheckpointPath({ path, cwd }) {
@@ -120,6 +176,7 @@ export async function writeOrganizationCheckpoint({
   const content = `${JSON.stringify(redactDeep({
     schemaVersion: CHECKPOINT_SCHEMA_VERSION,
     kind: CHECKPOINT_KIND,
+    toolVersion: VERSION,
     identity,
     repositories,
   }), null, 2)}\n`;
@@ -188,7 +245,7 @@ function serializeCheckpointResult(result, cwd) {
 function validateIdentity(actual, expected) {
   if (!isRecord(actual)) throw new Error('organization checkpoint identity is invalid');
   for (const field of [
-    'toolVersion',
+    'analysisGeneration',
     'rulesHash',
     'organization',
     'scope',
@@ -201,6 +258,32 @@ function validateIdentity(actual, expected) {
   }
 }
 
+function normalizeCheckpointIdentity(checkpoint) {
+  if (!isRecord(checkpoint.identity)) {
+    throw new Error('organization checkpoint identity is invalid');
+  }
+  if (checkpoint.schemaVersion === CHECKPOINT_SCHEMA_VERSION) {
+    if (typeof checkpoint.toolVersion !== 'string' || !TOOL_VERSION_RE.test(checkpoint.toolVersion)) {
+      throw new Error('organization checkpoint toolVersion is invalid');
+    }
+    return checkpoint.identity;
+  }
+  if (checkpoint.identity.toolVersion !== FIRST_ANALYSIS_GENERATION_TOOL_VERSION) {
+    throw new Error(
+      `organization checkpoint toolVersion ${String(checkpoint.identity.toolVersion)}`
+      + ' has no compatible analysis generation',
+    );
+  }
+  return {
+    analysisGeneration: 1,
+    rulesHash: checkpoint.identity.rulesHash,
+    organization: checkpoint.identity.organization,
+    scope: checkpoint.identity.scope,
+    configHash: checkpoint.identity.configHash,
+    baselineHash: checkpoint.identity.baselineHash,
+  };
+}
+
 function validateCheckpointResult(value, identity) {
   if (!isRecord(value)) throw new Error('organization checkpoint repository result is invalid');
   const repository = validateFullName(value.repository);

package/src/lib/path-equality.js

@@ -0,0 +1,30 @@
+import { realpath } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+
+/**
+ * Compare two existing or prospective file paths after resolving their real
+ * parents. Existing entries are fully resolved so a control-file symlink is
+ * compared with its target rather than only with the symlink name.
+ */
+export async function sameFilePath(left, right) {
+  const [leftPath, rightPath] = await Promise.all([
+    canonicalPath(left),
+    canonicalPath(right),
+  ]);
+  return comparablePath(leftPath) === comparablePath(rightPath);
+}
+
+async function canonicalPath(path) {
+  try {
+    return await realpath(path);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return join(await realpath(dirname(path)), basename(path));
+  }
+}
+
+function comparablePath(path) {
+  return process.platform === 'win32' || process.platform === 'darwin'
+    ? path.toLowerCase()
+    : path;
+}

package/src/lib/writer.js

@@ -44,6 +44,9 @@ export async function writeFileGuarded({ path, content, dryRun = true, cwd = pro
     if (entry.isSymbolicLink()) {
       throw new Error(`refusing to write through a symlink: ${path}`);
     }
+    if (!entry.isFile()) {
+      throw new Error(`refusing to replace a non-file path: ${path}`);
+    }
     existingMode = entry.mode & 0o777;
   } catch (error) {
     if (error.code !== 'ENOENT') throw error;

package/src/version.js

@@ -1,3 +1,3 @@
 // Runtime version embedded in the GitHub Action bundle. The version-sync check
 // keeps this value aligned with package.json, the lockfile, and plugin metadata.
-export const VERSION = '0.3.0';
+export const VERSION = '0.4.0';