no-mistakes 0.47.0 → 0.48.1

package/README.md

@@ -43,8 +43,6 @@ const {
     root: process.cwd(),
     files: ["src/main.mts"],
     relationships: ["import"],
-    timeout: 30,
-    lockTimeout: 30,
   });
   const tests = await dependents({
     root: process.cwd(),
@@ -72,7 +70,7 @@ const {
     changedFiles: ["src/utils.mts"],
   });
   // Complete changed-file inventory, including paths that selected no tests.
-  console.log(plan.changed_files);
+  console.log(plan.changedFiles);
   const targetCommands = await testsTargets({
     root: process.cwd(),
     framework: "vitest",
@@ -121,10 +119,11 @@ const {
 
 CLI and Node analyses share a per-user machine-wide lock. CLI flags
 `--timeout`, `--lock-timeout`, and `--fail-on-lock` have Node equivalents
-`timeout`, `lockTimeout`, and `failOnLock`. Both timeouts default to 30 seconds;
-`0` disables either CLI timeout, while `0` or `null` disables it in Node.
-Waiting does not alter successful output, and Node lock/timeout failures reject
-the returned Promise.
+`timeout`, `lockTimeout`, and `failOnLock`. CLI timeouts default to 30 seconds;
+Node/N-API omits both deadlines unless you set them. `0` disables either CLI
+timeout, while `0` or `null` disables it in Node. While waiting, stderr reports
+the holder pid and elapsed seconds. Waiting does not alter successful output,
+and Node lock/timeout failures reject the returned Promise.
 
 Dependency graph, query, and test-planning resolution is per workspace by
 default: when `tsconfig` is omitted, each import uses the config that owns its

package/flow-types.d.ts

@@ -15,7 +15,14 @@ export interface FlowOptions {
 
 export interface FlowNode {
   id: string;
-  kind: "file" | "symbol" | "module" | "queue-job" | "workflow-job" | "workflow-step";
+  kind:
+    | "file"
+    | "symbol"
+    | "module"
+    | "queue-job"
+    | "workflow-job"
+    | "workflow-step"
+    | "trpc-procedure";
   depth: number;
   file?: string;
   symbol?: string;
@@ -27,6 +34,10 @@ export interface FlowNode {
   job?: string;
   /** Zero-based step index for a virtual GitHub Actions workflow step node. */
   step?: number;
+  /** Router file for a virtual tRPC procedure node. */
+  routerFile?: string;
+  /** Dotted procedure path for a virtual tRPC procedure node (`user.get`). */
+  procedure?: string;
 }
 
 export interface FlowEdge {

package/index.d.ts

@@ -24,6 +24,7 @@ import type {
   ResolveCheckFilesOptions,
   ResolveCheckResult,
   ResolveCheckBatchResult,
+  ResolvedConfig,
   GraphEdge,
   PlaywrightOptions,
   PlaywrightRelatedOptions,
@@ -98,6 +99,9 @@ export function resolveCheck(
 export function fetches(options?: WithInvocationOptions<FetchesOptions>): Promise<FetchReport>;
 export function flow(options: WithInvocationOptions<FlowOptions>): Promise<FlowReport>;
 export function check(options?: WithInvocationOptions<CheckOptions>): Promise<CheckReport>;
+export function resolveConfig(
+  options?: WithInvocationOptions<ProjectOptions>,
+): Promise<ResolvedConfig>;
 export function validateMermaidMarkdown(
   options: WithInvocationOptions<MermaidValidationOptions>,
 ): Promise<MermaidValidationResult>;

package/index.js

@@ -5,9 +5,12 @@
 const native = require(process.env.NO_MISTAKES_TEST_NAPI_ADDON_PATH || "./bin/no-mistakes.node");
 const planning = require("./planning");
 const { createWorkflowTopologyIndex } = require("./workflow-topology-index");
+const fs = require("node:fs");
+const path = require("node:path");
 
 async function callJson(fn, options) {
-  return JSON.parse(await fn(JSON.stringify(options || {})));
+  const input = Buffer.from(JSON.stringify(options || {}));
+  return JSON.parse(await fn(input));
 }
 
 function createJsonApis(descriptors) {
@@ -23,6 +26,7 @@ const jsonApis = createJsonApis({
   analyzeProject: "analyzeProjectJson",
   callSites: "callSitesJson",
   check: "checkJson",
+  resolveConfig: "resolveConfigJson",
   ciEnv: "ciEnvJson",
   ciImpact: "ciImpactJson",
   ciTopology: "ciTopologyJson",
@@ -57,18 +61,90 @@ const jsonApis = createJsonApis({
   symbols: "symbolsJson",
 });
 
+const PLAN_INPUT_REPORTS = new Set(["testsComment", "testsGraph", "testsGraphMermaid"]);
+const CAMELIZE_REPORTS = new Set(["testsPlan", "testsImpact", "testsTargets", "testsGraph"]);
+
+async function analyzeProject(options = {}) {
+  const request = { ...options };
+  const generatedDirs = [];
+  try {
+    if (Array.isArray(request.reports)) {
+      request.reports = await Promise.all(
+        request.reports.map(async (report) => {
+          if (report.type === "testsWhy") {
+            const prepared = await planning.prepareWhyPlan(report);
+            if (prepared.generatedDir) generatedDirs.push(prepared.generatedDir);
+            return prepared.request;
+          }
+          return PLAN_INPUT_REPORTS.has(report.type)
+            ? await planning.decamelizePlanOptions(report)
+            : report;
+        }),
+      );
+    }
+    const result = await jsonApis.analyzeProject(request);
+    for (const report of result.reports || []) {
+      if (report.type === "testsWhy") {
+        report.result = planning.camelizeWhy(report.result);
+      } else if (CAMELIZE_REPORTS.has(report.type)) {
+        report.result = planning.camelizeValue(report.result);
+      }
+    }
+    return result;
+  } finally {
+    await Promise.all(generatedDirs.map((dir) => planning.removeGeneratedDir(dir)));
+  }
+}
+
+const topologyMemo = new Map();
+
+async function ciTopology(options) {
+  const root = path.resolve((options && options.root) || process.cwd());
+  const configPath = path.resolve(root, (options && options.config) || ".no-mistakes.yml");
+  let mtime = 0;
+  try {
+    mtime = fs.statSync(configPath).mtimeMs;
+  } catch {
+    mtime = 0;
+  }
+  const workflows = JSON.stringify(
+    []
+      .concat((options && options.workflows) || [])
+      .map(String)
+      .sort(),
+  );
+  const identity = `${root}\0${configPath}\0`;
+  const key = `${identity}${mtime}\0${workflows}`;
+  const stale = [];
+  for (const memoKey of topologyMemo.keys()) {
+    if (!memoKey.startsWith(identity)) continue;
+    const memoMtime = memoKey.slice(identity.length).split("\0")[0];
+    if (memoMtime !== String(mtime)) stale.push(memoKey);
+  }
+  for (const memoKey of stale) topologyMemo.delete(memoKey);
+  const cached = topologyMemo.get(key);
+  if (cached) return cached.then((value) => structuredClone(value));
+  const pending = jsonApis.ciTopology({ ...options, root }).catch((error) => {
+    topologyMemo.delete(key);
+    throw error;
+  });
+  topologyMemo.set(key, pending);
+  return pending.then((value) => structuredClone(value));
+}
+
 async function version() {
   return native.version();
 }
 
 module.exports.createWorkflowTopologyIndex = createWorkflowTopologyIndex;
 module.exports.version = version;
-module.exports.analyzeProject = jsonApis.analyzeProject;
+module.exports.analyzeProject = analyzeProject;
 module.exports.callSites = jsonApis.callSites;
 module.exports.check = jsonApis.check;
+module.exports.resolveConfig = jsonApis.resolveConfig;
 module.exports.ciEnv = jsonApis.ciEnv;
 module.exports.ciImpact = jsonApis.ciImpact;
-module.exports.ciTopology = jsonApis.ciTopology;
+module.exports.ciTopology = ciTopology;
 module.exports.dataPw = jsonApis.dataPw;
 module.exports.deadExports = jsonApis.deadExports;
 module.exports.dependencies = jsonApis.dependencies;

package/index.mjs

@@ -0,0 +1,64 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const cjs = require("./index.js");
+
+export const {
+  analyzeProject,
+  callSites,
+  check,
+  ciEnv,
+  ciImpact,
+  ciTopology,
+  createWorkflowTopologyIndex,
+  dataPw,
+  deadExports,
+  dependencies,
+  dependents,
+  effects,
+  exportsOf,
+  fetches,
+  flow,
+  impactedChecks,
+  importUsages,
+  importers,
+  infraOutputs,
+  infraResourceRefs,
+  infraTestFor,
+  lockfileDiff,
+  playwrightCheck,
+  playwrightEdges,
+  playwrightRelated,
+  playwrightTests,
+  queueCheck,
+  queueEdges,
+  queueRelated,
+  queues,
+  reactAnalyze,
+  reactCheck,
+  reactUsages,
+  registryExtension,
+  related,
+  resolveCheck,
+  resolveConfig,
+  rscCallers,
+  serverContracts,
+  serverRouteEdges,
+  serverRouteList,
+  serverRouteRelated,
+  serverRoutes,
+  swiftImporters,
+  swiftTestTargets,
+  symbols,
+  testsComment,
+  testsGraph,
+  testsGraphMermaid,
+  testsImpact,
+  testsPlan,
+  testsTargets,
+  testsWhy,
+  validateMermaidMarkdown,
+  version,
+} = cjs;
+
+export default cjs;

package/invocation-types.d.ts

@@ -1,8 +1,8 @@
 /** Controls shared by every analysis invocation. Durations are in seconds. */
 export interface InvocationOptions {
-  /** Command execution timeout. Defaults to 30; 0 or null disables it. */
+  /** Command execution timeout in whole non-negative seconds. Omit, `0`, or `null` disables it. CLI default remains 30. */
   timeout?: number | null;
-  /** Maximum time to wait for the machine-wide lock. Defaults to 30; 0 or null waits indefinitely. */
+  /** Maximum time to wait for the machine-wide lock, in whole non-negative seconds. Omit, `0`, or `null` waits indefinitely. CLI default remains 30. */
   lockTimeout?: number | null;
   /** Fail immediately instead of waiting when another invocation holds the lock. */
   failOnLock?: boolean;
@@ -11,6 +11,8 @@ export interface InvocationOptions {
    * `0` uses the CPU count, matching CLI `--jobs 0`.
    */
   jobs?: number | null;
+  /** `ci` sets unbounded command and lock timeouts. CLI `--profile ci` does the same. */
+  profile?: "ci";
 }
 
 export type WithInvocationOptions<T> = T & InvocationOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "no-mistakes",
-  "version": "0.47.0",
+  "version": "0.48.1",
   "description": "Static codebase analysis tools for TS/JS dependencies, dependents, and symbols",
   "license": "MIT",
   "repository": {
@@ -15,8 +15,10 @@
     "bin/",
     "*.d.ts",
     "index.js",
+    "index.mjs",
     "planning.js",
     "workflow-topology-index.js",
+    "workflow-topology-index-helpers.js",
     "scripts/install.js",
     "scripts/install/",
     "README.md",
@@ -24,6 +26,15 @@
   ],
   "main": "index.js",
   "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.js"
+    },
+    "./planning.js": "./planning.js",
+    "./workflow-topology-index.js": "./workflow-topology-index.js"
+  },
   "publishConfig": {
     "access": "public"
   },

package/planning.js

@@ -1,9 +1,13 @@
 "use strict";
 
+const fs = require("node:fs/promises");
+const os = require("node:os");
+const path = require("node:path");
 const native = require(process.env.NO_MISTAKES_TEST_NAPI_ADDON_PATH || "./bin/no-mistakes.node");
 
 async function callJson(fn, options) {
-  return JSON.parse(await fn(JSON.stringify(options || {})));
+  const input = Buffer.from(JSON.stringify(options || {}));
+  return JSON.parse(await fn(input));
 }
 
 function createJsonApis(descriptors) {
@@ -15,12 +19,110 @@ function createJsonApis(descriptors) {
   );
 }
 
+function camelizeKey(key) {
+  return key.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+function decamelizeKey(key) {
+  return key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+
+function mapKeys(value, mapKey) {
+  if (Array.isArray(value)) return value.map((item) => mapKeys(item, mapKey));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, nested]) => [mapKey(key), mapKeys(nested, mapKey)]),
+    );
+  }
+  return value;
+}
+
+function camelizeValue(value) {
+  return mapKeys(value, camelizeKey);
+}
+
+function decamelizeValue(value) {
+  return mapKeys(value, decamelizeKey);
+}
+
+function loadPlanJson(planJson) {
+  let parsed = planJson;
+  if (typeof parsed === "string") {
+    try {
+      parsed = JSON.parse(parsed);
+    } catch {
+      return planJson;
+    }
+  }
+  if (parsed && typeof parsed === "object") {
+    return decamelizeValue(parsed);
+  }
+  return planJson;
+}
+
+async function readPlanFile(planPath) {
+  try {
+    return JSON.parse(await fs.readFile(planPath, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+async function decamelizePlanOptions(options = {}) {
+  const next = { ...options };
+  if (next.planJson != null) {
+    next.planJson = loadPlanJson(next.planJson);
+  } else if (typeof next.plan === "string") {
+    const document = await readPlanFile(next.plan);
+    if (document !== undefined) {
+      next.planJson = loadPlanJson(document);
+      delete next.plan;
+    }
+  }
+  return next;
+}
+
+async function prepareWhyPlan(options = {}) {
+  const next = { ...options };
+  let document = next.planJson;
+  if (document == null && typeof next.plan === "string") {
+    document = await readPlanFile(next.plan);
+    if (document === undefined) return { request: next };
+  }
+  if (document == null) return { request: next };
+  const generatedDir = await fs.mkdtemp(path.join(os.tmpdir(), "no-mistakes-why-"));
+  await fs.writeFile(path.join(generatedDir, "plan.json"), JSON.stringify(loadPlanJson(document)));
+  next.plan = path.join(generatedDir, "plan.json");
+  delete next.planJson;
+  return { request: next, generatedDir };
+}
+
+async function materializeWhyPlan(options = {}) {
+  return (await prepareWhyPlan(options)).request;
+}
+
+async function removeGeneratedDir(generatedDir) {
+  if (!generatedDir) return;
+  await fs.rm(generatedDir, { recursive: true, force: true }).catch(() => {});
+}
+
+function camelizeWhy(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return camelizeValue(value);
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([key, nested]) => [key, camelizeValue(nested)]),
+  );
+}
+
 async function testsComment(options) {
-  return native.testsCommentMarkdown(JSON.stringify(options || {}));
+  const input = Buffer.from(JSON.stringify(await decamelizePlanOptions(options)));
+  return String(await native.testsCommentMarkdown(input));
 }
 
 async function testsGraphMermaid(options) {
-  return native.testsGraphMermaid(JSON.stringify(options || {}));
+  const input = Buffer.from(JSON.stringify(await decamelizePlanOptions(options)));
+  return String(await native.testsGraphMermaid(input));
 }
 
 const jsonApis = createJsonApis({
@@ -41,8 +143,44 @@ const jsonApis = createJsonApis({
   testsWhy: "testsWhyJson",
 });
 
+async function testsPlan(options) {
+  return camelizeValue(await jsonApis.testsPlan(options));
+}
+
+async function testsImpact(options) {
+  return camelizeValue(await jsonApis.testsImpact(options));
+}
+
+async function testsTargets(options) {
+  return camelizeValue(await jsonApis.testsTargets(options));
+}
+
+async function testsWhy(options) {
+  const { request, generatedDir } = await prepareWhyPlan(options);
+  try {
+    return camelizeWhy(await jsonApis.testsWhy(request));
+  } finally {
+    await removeGeneratedDir(generatedDir);
+  }
+}
+
+async function testsGraph(options) {
+  return camelizeValue(await jsonApis.testsGraph(await decamelizePlanOptions(options)));
+}
+
 module.exports = {
+  camelizeValue,
+  camelizeWhy,
+  decamelizePlanOptions,
+  materializeWhyPlan,
+  prepareWhyPlan,
+  removeGeneratedDir,
   testsComment,
   testsGraphMermaid,
   ...jsonApis,
+  testsGraph,
+  testsImpact,
+  testsPlan,
+  testsTargets,
+  testsWhy,
 };

package/resolve-config-types.d.ts

@@ -0,0 +1,50 @@
+import type { TestPlanFramework } from "./test-types";
+
+export interface ResolvedConfig {
+  configPath?: string | null;
+  frontendApps: ResolvedFrontendApp[];
+  playwright: ResolvedPlaywright;
+  vitestFullSuiteTriggers: ResolvedTrigger[];
+  fullSuiteTriggers: ResolvedFrameworkTriggers[];
+}
+
+export interface ResolvedFrontendApp {
+  project?: string | null;
+  root: string;
+  routeRoot: string;
+  selectorRoots: string[];
+}
+
+export interface ResolvedPlaywright {
+  coverageRoutes: boolean;
+  coverageSelectors: boolean;
+  frontendRoot?: string | null;
+  selectorRoots: string[];
+  apps: ResolvedPlaywrightApp[];
+}
+
+export interface ResolvedPlaywrightApp {
+  playwrightProject: string;
+  project?: string | null;
+  frontendRoot?: string | null;
+  selectorRoots: string[];
+  rewrites: ResolvedRewrite[];
+  ignoreRoutes: string[];
+}
+
+export interface ResolvedRewrite {
+  source: string;
+  destination: string;
+}
+
+export interface ResolvedTrigger {
+  name: string;
+  paths: string[];
+  targets: string[];
+  source: "triggers" | "projects";
+}
+
+export interface ResolvedFrameworkTriggers {
+  framework: TestPlanFramework;
+  triggers: ResolvedTrigger[];
+}

package/test-types.d.ts

@@ -10,7 +10,12 @@ export type TestPlanFramework =
   | "go"
   | "cargo"
   | "rails"
-  | "php";
+  | "php"
+  | "java"
+  | "kotlin"
+  | "elixir"
+  | "dart"
+  | "jest";
 
 interface TestsPlanOptionsBase {
   framework?: TestPlanFramework;
@@ -36,6 +41,10 @@ interface TestsPlanOptionsBase {
   limitPercent?: number;
   limitFiles?: number;
   globalConfigFallback?: boolean;
+  /** Include the markdown PR comment as `comment` on the returned plan. */
+  includeComment?: boolean;
+  /** Keep only selected tests whose relative path matches one of these globs. */
+  includeGlob?: string[];
 }
 
 /**
@@ -85,16 +94,29 @@ export interface TestsTargetsOptions {
 
 export interface TestPlan {
   /** Complete deterministic changed-file inventory, relative to the request root. */
-  changed_files: string[];
-  selected_tests: SelectedTest[];
+  changedFiles: string[];
+  selectedTests: SelectedTest[];
   groups?: TestPlanGroup[];
   warnings: TestPlanWarning[];
-  fallback_triggered: boolean;
-  fallback_reason?: string | null;
+  fallbackTriggered: boolean;
+  fallbackReason?: string | null;
+  executionTargets?: GroupedExecutionTarget[];
+  comment?: string | null;
+}
+
+export interface GroupedExecutionTarget {
+  runner: TestPlanFramework;
+  config?: string | null;
+  project?: string | null;
+  /** Path-prefix display name, such as a Swift package root. */
+  name?: string;
+  baseCommand: string[];
+  runnerArgs: string[];
+  testFiles: string[];
 }
 
 export interface SelectedTest {
-  test_file: string;
+  testFile: string;
   confidence: "low" | "medium" | "high";
   reasons: ImpactReason[];
   targets?: TestExecutionTarget[];
@@ -106,24 +128,26 @@ export interface TestExecutionTarget {
   /** True when config is a Vitest workspace/project-array source rendered with --workspace. */
   workspace?: boolean;
   project?: string | null;
-  base_command: string[];
-  runner_args: string[];
+  /** Path-prefix display name, such as a Swift package root. */
+  name?: string;
+  baseCommand: string[];
+  runnerArgs: string[];
 }
 
 export interface ImpactReason {
-  changed_file: string;
+  changedFile: string;
   path: string[];
   via: string[];
   /** When present, aligns index-for-index with `via`. */
-  via_details?: Array<ImpactEdgeDetail | null>;
+  viaDetails?: Array<ImpactEdgeDetail | null>;
 }
 
 export type ImpactEdgeDetail = ResourceImpactEdgeDetail | VitestSetupImpactEdgeDetail;
 
 export interface ResourceImpactEdgeDetail {
   type: "resource";
-  consumer_file: string;
-  call_sites: ResourceCallSite[];
+  consumerFile: string;
+  callSites: ResourceCallSite[];
 }
 
 export interface VitestSetupImpactEdgeDetail {
@@ -132,7 +156,7 @@ export interface VitestSetupImpactEdgeDetail {
 }
 
 export interface ResourceCallSite {
-  call_kind: ResourceCallKind;
+  callKind: ResourceCallKind;
   line: number;
 }
 
@@ -186,6 +210,7 @@ export interface TestsWhyOptions {
   test: string;
   changed?: string;
   plan?: string;
+  planJson?: SavedTestPlan | string;
 }
 
 export interface WhyStep {
@@ -194,10 +219,8 @@ export interface WhyStep {
   detail?: ImpactEdgeDetail | null;
 }
 
-/** A current or pre-`changed_files` plan accepted by saved-plan document APIs. */
-export type SavedTestPlan = Omit<TestPlan, "changed_files"> & {
-  changed_files?: string[];
-};
+/** A current or pre-`changedFiles` plan accepted by saved-plan document APIs. */
+export type SavedTestPlan = TestPlan;
 
 export interface TestsPlanDocumentOptions {
   plan?: string;

package/traversal-types.d.ts

@@ -31,7 +31,12 @@ export type Relationship =
   | "rust"
   | "ruby"
   | "php"
+  | "java"
+  | "kotlin"
+  | "elixir"
+  | "dart"
   | "resource"
+  | "trpc"
   | "all";
 
 export interface TraverseOptions {
@@ -59,6 +64,10 @@ export interface DependencyFile {
   job?: string;
   /** Zero-based step index for a virtual GitHub Actions workflow step node. */
   step?: number;
+  /** Router file for a virtual tRPC procedure node. */
+  routerFile?: string;
+  /** Dotted procedure path for a virtual tRPC procedure node (`user.get`). */
+  procedure?: string;
   module?: string;
   depth: number;
   via?: string[];

package/types.d.ts

@@ -11,3 +11,4 @@ export * from "./workflow-topology-types";
 export * from "./query-types";
 export * from "./named-query-types";
 export * from "./mermaid-types";
+export * from "./resolve-config-types";

package/workflow-topology-index-helpers.js

@@ -0,0 +1,28 @@
+"use strict";
+
+function stepMatches(selector, step) {
+  return (
+    (selector.id === undefined || selector.id === step.id) &&
+    (selector.uses === undefined || selector.uses === step.uses) &&
+    (selector.name === undefined || selector.name === step.name)
+  );
+}
+
+function directCallerJobIdsForUses(jobsById, uses) {
+  const ids = [];
+  for (const job of jobsById.values()) {
+    if (job.steps.some((step) => step.uses === uses)) ids.push(job.id);
+  }
+  return Object.freeze(ids.sort());
+}
+
+function stepOrderIndexes(job, selectors) {
+  return Object.freeze(
+    selectors.map((selector) => {
+      const step = job.steps.find((candidate) => stepMatches(selector, candidate));
+      return step == null ? -1 : step.index;
+    }),
+  );
+}
+
+module.exports = { directCallerJobIdsForUses, stepOrderIndexes };

package/workflow-topology-index-types.d.ts

@@ -24,6 +24,13 @@ export interface WorkflowTopologyIndex {
   directDownstreamJobIds(jobId: string): readonly string[];
   transitiveDownstreamJobIds(jobId: string): readonly string[];
   directCallerJobIds(workflowPath: string): readonly string[];
+  /** Job ids whose steps `uses:` this action or workflow path. */
+  directCallerJobIdsForUses(uses: string): readonly string[];
+  /** Step indexes for `selectors` in `jobId`, or `-1` when a selector is missing. */
+  stepOrderIndexes(
+    jobId: string,
+    selectors: ReadonlyArray<{ id?: string; uses?: string; name?: string }>,
+  ): readonly number[];
   directCallerWorkflowPaths(workflowPath: string): readonly string[];
   transitiveCallerWorkflowPaths(workflowPath: string): readonly string[];
   directCalleeWorkflowPaths(workflowPath: string): readonly string[];

package/workflow-topology-index.js

@@ -1,5 +1,10 @@
 "use strict";
 
+const {
+  directCallerJobIdsForUses,
+  stepOrderIndexes,
+} = require("./workflow-topology-index-helpers");
+
 // A pure-JS query index rebuilt from the `ciTopology()` JSON, ported from
 // the original engine's `topology-index.mts` + `frozen-topology.mts`. This
 // stays JS-only by design: it returns closures over frozen `Map`s, which
@@ -214,6 +219,11 @@ function createWorkflowTopologyIndex(topology) {
     transitiveWorkflowRunSubscriberPaths: workflowQuery(workflowRunSubscribers, true),
     artifactProducersForConsumerJob: artifactEdgeQuery(artifactProducers),
     artifactConsumersForProducerJob: artifactEdgeQuery(artifactConsumers),
+    directCallerJobIdsForUses: (uses) => directCallerJobIdsForUses(jobsById, uses),
+    stepOrderIndexes: (jobId, selectors) => {
+      assertKnown(jobsById, jobId, "workflow job");
+      return stepOrderIndexes(jobsById.get(jobId), selectors);
+    },
   });
 }