[steps] Add local action discovery utilities

Author: sswrk

packages/steps/src/BuildConfig.ts

@@ -8,6 +8,7 @@ import { BuildRuntimePlatform } from './BuildRuntimePlatform';
 import { BuildStepEnv } from './BuildStepEnv';
 import { BuildStepInputValueType, BuildStepInputValueTypeName } from './BuildStepInput';
 import { BuildConfigError, BuildWorkflowError } from './errors';
+import { isActionReference } from './utils/localActions';
 import { BUILD_STEP_OR_BUILD_GLOBAL_CONTEXT_REFERENCE_REGEX } from './utils/template';
 
 export type BuildFunctions = Record<string, BuildFunctionConfig>;
@@ -438,6 +439,16 @@ export function validateAllFunctionsExist(
     }
   }
   const calledFunctionsOrFunctionGroup = Array.from(calledFunctionsOrFunctionGroupsSet);
+  const actionReferences = calledFunctionsOrFunctionGroup.filter(isActionReference);
+  if (actionReferences.length > 0) {
+    throw new BuildConfigError(
+      `Local actions (${actionReferences
+        .map(ref => `"${ref}"`)
+        .join(
+          ', '
+        )}) are not supported in ".eas/build/*.yml" custom builds. Local actions can only be used in EAS workflows (".eas/workflows/*.yml").`
+    );
+  }
   const externalFunctionIdsSet = new Set(externalFunctionIds);
   const externalFunctionGroupsIdsSet = new Set(externalFunctionGroupsIds);
   const nonExistentFunctionsOrFunctionGroups = calledFunctionsOrFunctionGroup.filter(

packages/steps/src/__tests__/BuildConfig-test.ts

@@ -1042,6 +1042,40 @@ describe(validateAllFunctionsExist, () => {
       validateAllFunctionsExist(buildConfig, { externalFunctionIds: [] });
     }).toThrowError(/Calling non-existent functions: "eas\/build"/);
   });
+  test('rejects local action references with a dedicated error', () => {
+    const buildConfig: BuildConfig = {
+      build: {
+        steps: ['./.eas/actions/my-action'],
+      },
+    };
+
+    expect(() => {
+      validateAllFunctionsExist(buildConfig, { externalFunctionIds: [] });
+    }).toThrowError(
+      /Local actions \("\.\/\.eas\/actions\/my-action"\) are not supported in "\.eas\/build\/\*\.yml" custom builds\. Local actions can only be used in EAS workflows \("\.eas\/workflows\/\*\.yml"\)\./
+    );
+  });
+  test('rejects object-form local action references with a dedicated error', () => {
+    const buildConfig: BuildConfig = {
+      build: {
+        steps: [
+          {
+            './.eas/actions/my-action': {
+              inputs: {
+                foo: 'bar',
+              },
+            },
+          },
+        ],
+      },
+    };
+
+    expect(() => {
+      validateAllFunctionsExist(buildConfig, { externalFunctionIds: [] });
+    }).toThrow(
+      /Local actions \("\.\/\.eas\/actions\/my-action"\) are not supported in "\.eas\/build\/\*\.yml" custom builds\. Local actions can only be used in EAS workflows \("\.eas\/workflows\/\*\.yml"\)\./
+    );
+  });
   test('non-existent namespaced functions with skipNamespacedFunctionsOrFunctionGroupsCheck = false', () => {
     const buildConfig: BuildConfig = {
       build: {

packages/steps/src/index.ts

@@ -16,4 +16,5 @@ export * from './interpolation';
 export * from './utils/shell/spawn';
 export * from './utils/jsepEval';
 export * from './utils/hashFiles';
+export * from './utils/localActions';
 export { StepMetric, StepMetricResult } from './StepMetrics';

packages/steps/src/utils/__tests__/localActions-test.ts

@@ -0,0 +1,166 @@
+import { ActionConfigZ } from '@expo/eas-build-job';
+import path from 'path';
+
+import {
+  buildActionCatalogFromStepsAsync,
+  isActionReference,
+  isLocalActionPathWithinProject,
+  parseActionReference,
+  resolveLocalActionPath,
+} from '../localActions';
+
+describe(parseActionReference, () => {
+  it('parses local action references', () => {
+    expect(parseActionReference('./.eas/actions/setup')).toBe('./.eas/actions/setup');
+  });
+
+  it('normalizes local action references', () => {
+    expect(parseActionReference('  ./.eas/actions/setup/  ')).toBe('./.eas/actions/setup');
+  });
+
+  it('returns null for built-in function ids', () => {
+    expect(parseActionReference('eas/build')).toBeNull();
+  });
+
+  it('returns null for degenerate refs with no path segment', () => {
+    expect(parseActionReference('./')).toBeNull();
+    expect(parseActionReference('  ./  ')).toBeNull();
+  });
+});
+
+describe(isActionReference, () => {
+  it('returns true for local action references', () => {
+    expect(isActionReference('./.eas/actions/setup')).toBe(true);
+  });
+
+  it('returns false for built-in function ids', () => {
+    expect(isActionReference('eas/build')).toBe(false);
+  });
+
+  it('returns false for degenerate refs with no path segment', () => {
+    expect(isActionReference('./')).toBe(false);
+  });
+});
+
+describe(buildActionCatalogFromStepsAsync, () => {
+  it('loads referenced actions transitively', async () => {
+    const catalog = await buildActionCatalogFromStepsAsync({
+      rootSteps: [{ uses: './.eas/actions/outer', id: 'outer' }],
+      loadAction: async ref => {
+        if (ref === './.eas/actions/outer') {
+          return ActionConfigZ.parse({
+            runs: { steps: [{ uses: './.eas/actions/inner' }] },
+          });
+        }
+        if (ref === './.eas/actions/inner') {
+          return ActionConfigZ.parse({
+            runs: { steps: [{ run: 'echo inner' }] },
+          });
+        }
+        throw new Error(`missing ${ref}`);
+      },
+    });
+
+    expect(Object.keys(catalog).sort()).toEqual(['./.eas/actions/inner', './.eas/actions/outer']);
+  });
+
+  it('detects cycles while loading', async () => {
+    await expect(
+      buildActionCatalogFromStepsAsync({
+        rootSteps: [{ uses: './.eas/actions/a', id: 'a' }],
+        loadAction: async ref => {
+          if (ref === './.eas/actions/a') {
+            return ActionConfigZ.parse({
+              runs: { steps: [{ uses: './.eas/actions/b' }] },
+            });
+          }
+          if (ref === './.eas/actions/b') {
+            return ActionConfigZ.parse({
+              runs: { steps: [{ uses: './.eas/actions/a' }] },
+            });
+          }
+          throw new Error(`missing ${ref}`);
+        },
+      })
+    ).rejects.toThrow(/cycle/i);
+  });
+
+  it('rejects action chains deeper than the maximum nesting depth at catalog build time', async () => {
+    const chainLength = 12;
+    const refs = Array.from({ length: chainLength }, (_, index) => `./.eas/actions/a${index}`);
+
+    await expect(
+      buildActionCatalogFromStepsAsync({
+        rootSteps: [{ uses: refs[0], id: 'root' }],
+        loadAction: async ref => {
+          const index = refs.indexOf(ref);
+          if (index === -1) {
+            throw new Error(`missing ${ref}`);
+          }
+          if (index === chainLength - 1) {
+            return ActionConfigZ.parse({ runs: { steps: [{ run: 'echo leaf' }] } });
+          }
+          return ActionConfigZ.parse({
+            runs: { steps: [{ uses: refs[index + 1] }] },
+          });
+        },
+      })
+    ).rejects.toThrow(/Maximum action nesting depth \(10\) exceeded/);
+  });
+
+  it('collects normalized action references from steps', async () => {
+    const loadedRefs: string[] = [];
+    await buildActionCatalogFromStepsAsync({
+      rootSteps: [{ uses: './.eas/actions/setup/' }, { uses: 'eas/build' }, { run: 'echo hi' }],
+      loadAction: async ref => {
+        loadedRefs.push(ref);
+        return ActionConfigZ.parse({ runs: { steps: [{ run: 'echo setup' }] } });
+      },
+    });
+    expect(loadedRefs).toEqual(['./.eas/actions/setup']);
+  });
+});
+
+describe(resolveLocalActionPath, () => {
+  const projectRoot = path.resolve('/tmp/project');
+
+  it('resolves a reference under the conventional .eas/actions directory', () => {
+    expect(resolveLocalActionPath(projectRoot, './.eas/actions/setup')).toBe(
+      path.join(projectRoot, '.eas', 'actions', 'setup')
+    );
+  });
+
+  it('resolves an arbitrary GitHub Actions style path within the project', () => {
+    expect(resolveLocalActionPath(projectRoot, './internal-actions/deploy')).toBe(
+      path.join(projectRoot, 'internal-actions', 'deploy')
+    );
+  });
+});
+
+describe(isLocalActionPathWithinProject, () => {
+  const projectRoot = path.resolve('/tmp/project');
+
+  it('returns true for paths within the project', () => {
+    expect(
+      isLocalActionPathWithinProject(
+        projectRoot,
+        resolveLocalActionPath(projectRoot, './.eas/actions/setup')
+      )
+    ).toBe(true);
+  });
+
+  it('returns false when the reference escapes the project root via ..', () => {
+    expect(
+      isLocalActionPathWithinProject(
+        projectRoot,
+        resolveLocalActionPath(projectRoot, './../secrets')
+      )
+    ).toBe(false);
+  });
+
+  it('returns false when the reference resolves to the project root itself', () => {
+    expect(
+      isLocalActionPathWithinProject(projectRoot, resolveLocalActionPath(projectRoot, './'))
+    ).toBe(false);
+  });
+});

packages/steps/src/utils/localActions.ts

@@ -0,0 +1,117 @@
+/**
+ * Utilities for discovering local composite actions referenced via `uses:` in EAS
+ * workflows (`.eas/workflows/*.yml`) or inline job step definitions.
+ *
+ * Local actions are referenced by their path relative to the EAS project root, e.g.
+ * `uses: ./.eas/actions/<name>`, which resolves the action config at
+ * `<project-root>/.eas/actions/<name>/action.{yml,yaml}`. Any `./`-prefixed path is
+ * supported (GitHub Actions style), so actions can be organized freely, e.g.
+ * `uses: ./internal-actions/deploy`. The recommended convention is to keep them under
+ * `.eas/actions/<name>`. They are not supported in `.eas/build/*.yml` custom build
+ * config files.
+ */
+import { ActionCatalog, ActionConfig } from '@expo/eas-build-job';
+import path from 'path';
+
+export const MAX_ACTION_NESTING_DEPTH = 10;
+
+type ActionLoader = (ref: string) => Promise<ActionConfig>;
+
+type BuildActionCatalogFromStepsOptions = {
+  rootSteps: readonly unknown[];
+  loadAction: ActionLoader;
+};
+
+/** Recognizes `./…` local action references in a `uses` value, distinct from built-in functions like `eas/build`. */
+export function parseActionReference(uses: string): string | null {
+  const trimmed = uses.trim();
+  if (!trimmed.startsWith('./')) {
+    return null;
+  }
+  let ref = trimmed;
+  while (ref.length > 1 && ref.endsWith('/')) {
+    ref = ref.slice(0, -1);
+  }
+  if (!ref.slice(2)) {
+    return null;
+  }
+  return ref;
+}
+
+/** @see parseActionReference */
+export function isActionReference(uses: string): boolean {
+  return parseActionReference(uses) !== null;
+}
+
+/**
+ * Resolves every local action a workflow depends on, including actions referenced by other actions.
+ */
+export async function buildActionCatalogFromStepsAsync({
+  rootSteps,
+  loadAction,
+}: BuildActionCatalogFromStepsOptions): Promise<ActionCatalog> {
+  const catalog: ActionCatalog = {};
+  const loaded = new Set<string>();
+
+  const loadRecursiveAsync = async (ref: string, ancestry: string[]): Promise<void> => {
+    // Must run before `loaded.has(ref)` — a cyclic ref is already in `loaded` when the cycle closes.
+    if (ancestry.includes(ref)) {
+      const cyclePath = [...ancestry, ref].join(' -> ');
+      throw new Error(
+        `Detected a cycle while expanding actions: ${cyclePath}. An action cannot reference itself, directly or indirectly.`
+      );
+    }
+    if (ancestry.length > MAX_ACTION_NESTING_DEPTH) {
+      throw new Error(
+        `Maximum action nesting depth (${MAX_ACTION_NESTING_DEPTH}) exceeded while loading action "${ref}".`
+      );
+    }
+    if (loaded.has(ref)) {
+      return;
+    }
+
+    const config = await loadAction(ref);
+    catalog[ref] = config;
+    loaded.add(ref);
+
+    for (const nestedRef of collectActionReferencesFromSteps(config.runs.steps)) {
+      await loadRecursiveAsync(nestedRef, [...ancestry, ref]);
+    }
+  };
+
+  for (const ref of collectActionReferencesFromSteps(rootSteps)) {
+    await loadRecursiveAsync(ref, []);
+  }
+
+  return catalog;
+}
+
+/** Locates an action's on-disk directory from its workflow reference. */
+export function resolveLocalActionPath(projectRoot: string, ref: string): string {
+  return path.resolve(projectRoot, ref);
+}
+
+/** Guards against local action paths that escape the project root via `..` traversal. */
+export function isLocalActionPathWithinProject(projectRoot: string, actionPath: string): boolean {
+  const relative = path.relative(projectRoot, actionPath);
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+
+function collectActionReferencesFromSteps(
+  steps: readonly unknown[],
+  into: Set<string> = new Set()
+): Set<string> {
+  for (const step of steps) {
+    if (!step || typeof step !== 'object') {
+      continue;
+    }
+    const uses = (step as { uses?: unknown }).uses;
+    if (typeof uses === 'string') {
+      const parsed = parseActionReference(uses);
+      if (parsed) {
+        into.add(parsed);
+      }
+    }
+  }
+  return into;
+}