no-mistakes 0.33.1 → 0.35.0

package/README.md

@@ -119,6 +119,25 @@ CLI and Node analyses share a per-user machine-wide lock. CLI flags
 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
+importing file, including referenced projects. This keeps conflicting package
+aliases isolated while shared code can still select all importing tests. Pass
+`tsconfig` explicitly to force one config for a whole invocation when debugging
+or preserving a legacy single-config workflow.
+
+Graph queries also support `relationships: ["workflow"]` for canonical local
+GitHub Actions traversal: workflow file -> virtual job -> virtual step,
+`needs`, local reusable workflows/actions, supported literal `run:` targets and
+package scripts, and same-run artifact handoffs. Virtual IDs are
+`workflow.yml#job:<job>` and `workflow.yml#job:<job>/step:<zero-based-index>`.
+Use the precise `workflow-job`, `workflow-step`, `workflow-needs`,
+`workflow-uses`, `workflow-run`, or `workflow-artifact` filters to select a
+semantic while retaining its required structural bridge edges. The legacy `ci`
+relationship stays separate: it covers only workflow-file-to-Rust-binary Cargo
+invocations. Remote actions/workflows, `workflow_run`, dynamic shell commands,
+and paths outside the tracked graph are intentionally excluded.
+
 External `no-mistakes-*` executables on `PATH` can be invoked as subcommands.
 For example, after installing `no-mistakes-scripts`:
 

package/flow-types.d.ts

@@ -15,13 +15,18 @@ export interface FlowOptions {
 
 export interface FlowNode {
   id: string;
-  kind: "file" | "symbol" | "module" | "queue-job";
+  kind: "file" | "symbol" | "module" | "queue-job" | "workflow-job" | "workflow-step";
   depth: number;
   file?: string;
   symbol?: string;
   module?: string;
   queueFile?: string;
+  /** Workflow file for a virtual GitHub Actions job or step node. */
+  workflowFile?: string;
+  /** GitHub Actions job identifier for a virtual workflow job or step node. */
   job?: string;
+  /** Zero-based step index for a virtual GitHub Actions workflow step node. */
+  step?: number;
 }
 
 export interface FlowEdge {

package/index-ci-infra.d.ts

@@ -0,0 +1,70 @@
+// CI, impacted-checks, data-flow, infra, and Swift API declarations, split
+// out of `index.d.ts` to stay under the 200-line file limit.
+
+import type {
+  CiEnvOptions,
+  CiEnvReport,
+  CiImpactOptions,
+  CiImpactReport,
+  CiTopologyOptions,
+  DataPwOptions,
+  DataPwReport,
+  EffectsOptions,
+  EffectsReport,
+  ImpactedChecksOptions,
+  ImpactedChecksReport,
+  InfraOptions,
+  LockfileDiffEntry,
+  LockfileDiffOptions,
+  ModuleOutputsResult,
+  RegistryExtensionOptions,
+  RegistryExtensionReport,
+  ResourceRefRow,
+  RscCallersOptions,
+  RscCallersReport,
+  SwiftImporterRow,
+  SwiftOptions,
+  SwiftTestTargetRow,
+  TestForRow,
+  WithInvocationOptions,
+  WorkflowTopology,
+  WorkflowTopologyIndex,
+} from "./types";
+
+export function lockfileDiff(
+  options: WithInvocationOptions<LockfileDiffOptions>,
+): Promise<LockfileDiffEntry[]>;
+export function ciImpact(options: WithInvocationOptions<CiImpactOptions>): Promise<CiImpactReport>;
+export function ciEnv(options: WithInvocationOptions<CiEnvOptions>): Promise<CiEnvReport>;
+export function ciTopology(
+  options?: WithInvocationOptions<CiTopologyOptions>,
+): Promise<WorkflowTopology>;
+/** Builds a query index over a `ciTopology()` result. Pure JS — never crosses the N-API boundary. */
+export function createWorkflowTopologyIndex(topology: WorkflowTopology): WorkflowTopologyIndex;
+export function impactedChecks(
+  options: WithInvocationOptions<ImpactedChecksOptions>,
+): Promise<ImpactedChecksReport>;
+export function dataPw(options: WithInvocationOptions<DataPwOptions>): Promise<DataPwReport>;
+export function effects(options: WithInvocationOptions<EffectsOptions>): Promise<EffectsReport>;
+export function rscCallers(
+  options: WithInvocationOptions<RscCallersOptions>,
+): Promise<RscCallersReport>;
+export function registryExtension(
+  options: WithInvocationOptions<RegistryExtensionOptions>,
+): Promise<RegistryExtensionReport>;
+export function infraResourceRefs(
+  options: WithInvocationOptions<InfraOptions & { address: string }>,
+): Promise<ResourceRefRow[]>;
+export function infraOutputs(
+  options: WithInvocationOptions<InfraOptions & { moduleDir: string }>,
+): Promise<ModuleOutputsResult>;
+export function infraTestFor(
+  options: WithInvocationOptions<InfraOptions & { tfFile: string }>,
+): Promise<TestForRow[]>;
+export function swiftImporters(
+  options: WithInvocationOptions<SwiftOptions & { file: string }>,
+): Promise<SwiftImporterRow[]>;
+export function swiftTestTargets(
+  options: WithInvocationOptions<SwiftOptions & { file: string }>,
+): Promise<SwiftTestTargetRow[]>;
+export function version(): Promise<string>;

package/index.d.ts

@@ -2,30 +2,16 @@ import type {
   CheckReport,
   AnalyzeProjectOptions,
   AnalyzeProjectResult,
-  CiEnvOptions,
-  CiEnvReport,
-  CiImpactOptions,
-  CiImpactReport,
   CallSitesOptions,
   CallSitesResult,
-  DataPwOptions,
-  DataPwReport,
   DeadExportsOptions,
   DeadExportsResult,
-  EffectsOptions,
-  EffectsReport,
-  RscCallersOptions,
-  RscCallersReport,
-  RegistryExtensionOptions,
-  RegistryExtensionReport,
   DependencyResult,
   ExportsOfOptions,
   ExportsOfResult,
   FetchesOptions,
   FlowOptions,
   FlowReport,
-  ImpactedChecksOptions,
-  ImpactedChecksReport,
   ImportUsagesOptions,
   ImportUsagesResult,
   ImportersOptions,
@@ -33,10 +19,6 @@ import type {
   ResolveCheckOptions,
   ResolveCheckResult,
   GraphEdge,
-  InfraOptions,
-  LockfileDiffEntry,
-  LockfileDiffOptions,
-  ModuleOutputsResult,
   PlaywrightOptions,
   PlaywrightRelatedOptions,
   ProjectOptions,
@@ -44,14 +26,9 @@ import type {
   ReactComponentFacts,
   ReactUsagesReport,
   ReactViolation,
-  ResourceRefRow,
   ServerRoutesReport,
   ServerContractsReport,
   SignatureImpactResult,
-  SwiftImporterRow,
-  SwiftOptions,
-  SwiftTestTargetRow,
-  TestForRow,
   SymbolsListOptions,
   SymbolsOptions,
   SymbolsResult,
@@ -70,6 +47,7 @@ import type {
 } from "./types";
 
 export * from "./types";
+export * from "./index-ci-infra";
 
 export function dependencies(
   options: WithInvocationOptions<TraverseOptions>,
@@ -166,35 +144,3 @@ export function reactCheck(
 export function reactUsages(
   options: WithInvocationOptions<ProjectOptions & { target: string }>,
 ): Promise<ReactUsagesReport>;
-export function lockfileDiff(
-  options: WithInvocationOptions<LockfileDiffOptions>,
-): Promise<LockfileDiffEntry[]>;
-export function ciImpact(options: WithInvocationOptions<CiImpactOptions>): Promise<CiImpactReport>;
-export function ciEnv(options: WithInvocationOptions<CiEnvOptions>): Promise<CiEnvReport>;
-export function impactedChecks(
-  options: WithInvocationOptions<ImpactedChecksOptions>,
-): Promise<ImpactedChecksReport>;
-export function dataPw(options: WithInvocationOptions<DataPwOptions>): Promise<DataPwReport>;
-export function effects(options: WithInvocationOptions<EffectsOptions>): Promise<EffectsReport>;
-export function rscCallers(
-  options: WithInvocationOptions<RscCallersOptions>,
-): Promise<RscCallersReport>;
-export function registryExtension(
-  options: WithInvocationOptions<RegistryExtensionOptions>,
-): Promise<RegistryExtensionReport>;
-export function infraResourceRefs(
-  options: WithInvocationOptions<InfraOptions & { address: string }>,
-): Promise<ResourceRefRow[]>;
-export function infraOutputs(
-  options: WithInvocationOptions<InfraOptions & { moduleDir: string }>,
-): Promise<ModuleOutputsResult>;
-export function infraTestFor(
-  options: WithInvocationOptions<InfraOptions & { tfFile: string }>,
-): Promise<TestForRow[]>;
-export function swiftImporters(
-  options: WithInvocationOptions<SwiftOptions & { file: string }>,
-): Promise<SwiftImporterRow[]>;
-export function swiftTestTargets(
-  options: WithInvocationOptions<SwiftOptions & { file: string }>,
-): Promise<SwiftTestTargetRow[]>;
-export function version(): Promise<string>;

package/index.js

@@ -2,6 +2,7 @@
 
 const native = require("./bin/no-mistakes.node");
 const planning = require("./planning");
+const { createWorkflowTopologyIndex } = require("./workflow-topology-index");
 
 async function callJson(fn, options) {
   return JSON.parse(await fn(JSON.stringify(options || {})));
@@ -115,6 +116,10 @@ async function ciEnv(options) {
   return callJson(native.ciEnvJson, options);
 }
 
+async function ciTopology(options) {
+  return callJson(native.ciTopologyJson, options);
+}
+
 async function impactedChecks(options) {
   return callJson(native.impactedChecksJson, options);
 }
@@ -149,6 +154,8 @@ module.exports = {
   check,
   ciEnv,
   ciImpact,
+  ciTopology,
+  createWorkflowTopologyIndex,
   dataPw,
   deadExports,
   dependencies,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "no-mistakes",
-  "version": "0.33.1",
+  "version": "0.35.0",
   "description": "Static codebase analysis tools for TS/JS dependencies, dependents, and symbols",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,7 @@
     "*.d.ts",
     "index.js",
     "planning.js",
+    "workflow-topology-index.js",
     "scripts/install.js",
     "scripts/install/",
     "README.md",

package/test-types.d.ts

@@ -66,6 +66,8 @@ export interface SelectedTest {
 export interface TestExecutionTarget {
   runner: "vitest" | "playwright" | "dotnet" | "swift";
   config?: string | null;
+  /** True when config is a Vitest workspace/project-array source rendered with --workspace. */
+  workspace?: boolean;
   project?: string | null;
   base_command: string[];
   runner_args: string[];
@@ -75,8 +77,37 @@ export interface ImpactReason {
   changed_file: string;
   path: string[];
   via: string[];
+  /** When present, aligns index-for-index with `via`. */
+  via_details?: Array<ImpactEdgeDetail | null>;
 }
 
+export type ImpactEdgeDetail = ResourceImpactEdgeDetail | VitestSetupImpactEdgeDetail;
+
+export interface ResourceImpactEdgeDetail {
+  type: "resource";
+  consumer_file: string;
+  call_sites: ResourceCallSite[];
+}
+
+export interface VitestSetupImpactEdgeDetail {
+  type: "vitest-setup";
+  field: "setupFiles" | "globalSetup";
+}
+
+export interface ResourceCallSite {
+  call_kind: ResourceCallKind;
+  line: number;
+}
+
+/** Static runtime filesystem API that created a resource dependency edge. */
+export type ResourceCallKind =
+  | "read-file"
+  | "read-file-sync"
+  | "read-directory"
+  | "read-directory-sync"
+  | "glob"
+  | "glob-sync";
+
 export interface TestPlanGroup {
   type: string;
   selected: string[];
@@ -88,6 +119,7 @@ export interface TestPlanWarning {
   type: string;
   message: string;
   file: string;
+  line?: number;
 }
 
 export interface TestsTargetsReport {
@@ -122,6 +154,7 @@ export interface TestsWhyOptions {
 export interface WhyStep {
   node: string;
   via?: string | null;
+  detail?: ImpactEdgeDetail | null;
 }
 
 export interface TestsPlanDocumentOptions {
@@ -131,7 +164,7 @@ export interface TestsPlanDocumentOptions {
 
 export interface TestGraph {
   nodes: Array<{ name: string; type: "changed" | "test" | "intermediate" }>;
-  edges: Array<{ from: string; to: string; via: string }>;
+  edges: Array<{ from: string; to: string; via: string; detail?: ImpactEdgeDetail }>;
 }
 
 export interface LockfileDiffOptions {

package/traversal-types.d.ts

@@ -12,6 +12,13 @@ export type Relationship =
   | "queue"
   | "md"
   | "ci"
+  | "workflow"
+  | "workflow-job"
+  | "workflow-step"
+  | "workflow-needs"
+  | "workflow-uses"
+  | "workflow-run"
+  | "workflow-artifact"
   | "http"
   | "process"
   | "asset"
@@ -19,6 +26,7 @@ export type Relationship =
   | "dotnet"
   | "swift"
   | "terraform"
+  | "resource"
   | "all";
 
 export interface TraverseOptions {
@@ -40,7 +48,12 @@ export interface DependencyFile {
   file?: string;
   symbol?: string;
   queueFile?: string;
+  /** Workflow file for a virtual GitHub Actions job or step node. */
+  workflowFile?: string;
+  /** GitHub Actions job identifier for a virtual workflow job or step node. */
   job?: string;
+  /** Zero-based step index for a virtual GitHub Actions workflow step node. */
+  step?: number;
   module?: string;
   depth: number;
   via?: string[];
@@ -51,9 +64,25 @@ export interface SymbolEntrypoint {
   symbol?: string;
 }
 
+export interface TsConfigDiagnostic {
+  kind: "ambiguous-ownership" | "invalid-config" | "invalid-extends" | "invalid-reference";
+  config: string | null;
+  file: string | null;
+  detail: string;
+  candidates: string[];
+}
+
+export interface TsConfigProvenance {
+  importer: string;
+  config: string | null;
+  forced: boolean;
+}
+
 export interface DependencyResult {
   roots: string[];
   files: DependencyFile[];
+  diagnostics: TsConfigDiagnostic[];
+  tsconfig_provenance: TsConfigProvenance[];
 }
 
 export type ExportKind =

package/types.d.ts

@@ -7,5 +7,6 @@ export * from "./test-types";
 export * from "./report-types";
 export * from "./server-contract-types";
 export * from "./ci-types";
+export * from "./workflow-topology-types";
 export * from "./query-types";
 export * from "./named-query-types";

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

@@ -0,0 +1,56 @@
+// Artifact-dataflow types for `ciTopology()`, split out of
+// `workflow-topology-types.d.ts` to stay under the 200-line file limit.
+// Mirrors the schema-v1 JSON contract exactly (field names, casing) — see
+// `docs/node-api.md` for the stability guarantees.
+
+export type ArtifactValue =
+  | { kind: "static"; raw: string; value: string; instanceCount?: number }
+  | { kind: "finite"; raw: string; values: string[]; instanceCounts: Record<string, number> }
+  | { kind: "dynamic"; raw: string }
+  | { kind: "path-derived"; reason: "archive-disabled" };
+
+export type ArtifactActionFlag =
+  | { kind: "static"; raw?: string; effective: boolean }
+  | { kind: "dynamic"; raw: string };
+
+export interface ArtifactUploadDeclaration {
+  kind: "upload";
+  name: ArtifactValue;
+  archive: ArtifactActionFlag;
+  overwrite: ArtifactActionFlag;
+}
+
+export type ArtifactDownloadSelector =
+  | { kind: "name"; name: ArtifactValue }
+  | { kind: "pattern"; pattern: ArtifactValue }
+  | { kind: "all" }
+  | { kind: "artifact-ids"; artifactIds: ArtifactValue }
+  | {
+      kind: "unresolved";
+      reason: "name-with-artifact-ids";
+      name: ArtifactValue;
+      artifactIds: ArtifactValue;
+    };
+
+export type ArtifactDownloadSource =
+  | { kind: "current-run"; repository?: ArtifactValue; runId?: ArtifactValue }
+  | { kind: "external"; repository?: ArtifactValue; runId?: ArtifactValue }
+  | { kind: "dynamic"; repository?: ArtifactValue; runId?: ArtifactValue };
+
+export interface ArtifactDownloadDeclaration {
+  kind: "download";
+  selector: ArtifactDownloadSelector;
+  source: ArtifactDownloadSource;
+}
+
+export type ArtifactDeclaration = ArtifactUploadDeclaration | ArtifactDownloadDeclaration;
+
+export interface ArtifactEdge {
+  kind: "artifact";
+  from: string;
+  to: string;
+  name: string;
+  producerStep: number;
+  consumerStep: number;
+  match: "exact" | "pattern" | "all" | "possible";
+}

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

@@ -0,0 +1,39 @@
+// The JS-only `createWorkflowTopologyIndex()` query index type, split out
+// of `workflow-topology-types.d.ts` to stay under the 200-line file limit.
+
+import type { ArtifactEdge } from "./workflow-topology-artifact-types";
+import type {
+  WorkflowJobNode,
+  WorkflowNode,
+  WorkflowRunEdge,
+  WorkflowTopology,
+} from "./workflow-topology-types";
+
+/**
+ * A frozen, sorted query index over a {@link WorkflowTopology}, built
+ * entirely in JS from `ciTopology()`'s output via
+ * {@link createWorkflowTopologyIndex}. Every array-returning method throws
+ * `Error("unknown workflow job: <id>")` / `Error("unknown workflow: <path>")`
+ * for an id not present in the topology.
+ */
+export interface WorkflowTopologyIndex {
+  readonly workflowsByPath: ReadonlyMap<string, Readonly<WorkflowNode>>;
+  readonly jobsById: ReadonlyMap<string, Readonly<WorkflowJobNode>>;
+  directUpstreamJobIds(jobId: string): readonly string[];
+  transitiveUpstreamJobIds(jobId: string): readonly string[];
+  directDownstreamJobIds(jobId: string): readonly string[];
+  transitiveDownstreamJobIds(jobId: string): readonly string[];
+  directCallerJobIds(workflowPath: string): readonly string[];
+  directCallerWorkflowPaths(workflowPath: string): readonly string[];
+  transitiveCallerWorkflowPaths(workflowPath: string): readonly string[];
+  directCalleeWorkflowPaths(workflowPath: string): readonly string[];
+  transitiveCalleeWorkflowPaths(workflowPath: string): readonly string[];
+  incomingWorkflowRunEdges(workflowPath: string): readonly Readonly<WorkflowRunEdge>[];
+  outgoingWorkflowRunEdges(workflowPath: string): readonly Readonly<WorkflowRunEdge>[];
+  directWorkflowRunSourcePaths(workflowPath: string): readonly string[];
+  transitiveWorkflowRunSourcePaths(workflowPath: string): readonly string[];
+  directWorkflowRunSubscriberPaths(workflowPath: string): readonly string[];
+  transitiveWorkflowRunSubscriberPaths(workflowPath: string): readonly string[];
+  artifactProducersForConsumerJob(jobId: string): readonly Readonly<ArtifactEdge>[];
+  artifactConsumersForProducerJob(jobId: string): readonly Readonly<ArtifactEdge>[];
+}

package/workflow-topology-index.js

@@ -0,0 +1,220 @@
+"use strict";
+
+// 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
+// doesn't cross the N-API boundary cleanly, and the native side already
+// does the expensive parse/diagnose/resolve work — this index is just
+// deterministic, sorted traversal over data it's handed.
+
+function deepFrozenClone(value) {
+  return freezeRecursively(structuredClone(value));
+}
+
+function freezeRecursively(value) {
+  if (value === null || typeof value !== "object") return value;
+  for (const nested of Object.values(value)) freezeRecursively(nested);
+  return Object.freeze(value);
+}
+
+// `Object.freeze(new Map())` does NOT stop `.set()`/`.delete()` from
+// working (freeze only covers own enumerable properties, not a Map's
+// internal slots) — this wrapper is what actually makes `workflowsByPath`
+// / `jobsById` read-only.
+class FrozenReadonlyMap {
+  #source;
+
+  constructor(source) {
+    this.#source = source;
+    Object.freeze(this);
+  }
+
+  get size() {
+    return this.#source.size;
+  }
+
+  entries() {
+    return this.#source.entries();
+  }
+
+  forEach(callback, thisArg) {
+    for (const [key, value] of this.#source) callback.call(thisArg, value, key, this);
+  }
+
+  get(key) {
+    return this.#source.get(key);
+  }
+
+  has(key) {
+    return this.#source.has(key);
+  }
+
+  keys() {
+    return this.#source.keys();
+  }
+
+  values() {
+    return this.#source.values();
+  }
+
+  [Symbol.iterator]() {
+    return this.entries();
+  }
+
+  get [Symbol.toStringTag]() {
+    return "Map";
+  }
+}
+
+function adjacencyMap(ids) {
+  return new Map([...ids].map((id) => [id, new Set()]));
+}
+
+function artifactEdgeMap(ids) {
+  return new Map([...ids].map((id) => [id, []]));
+}
+
+function assertKnown(values, id, label) {
+  if (!values.has(id)) throw new Error(`unknown ${label}: ${id}`);
+}
+
+function query(adjacency, source, transitive) {
+  const direct = adjacency.get(source);
+  if (!transitive) return Object.freeze([...direct].sort());
+  const visited = new Set();
+  const pending = [...direct];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (current === source || visited.has(current)) continue;
+    visited.add(current);
+    for (const neighbor of adjacency.get(current)) {
+      if (neighbor !== source && !visited.has(neighbor)) pending.push(neighbor);
+    }
+  }
+  return Object.freeze([...visited].sort());
+}
+
+function workflowPathFromId(id) {
+  const index = id.indexOf("#");
+  return index === -1 ? id : id.slice(0, index);
+}
+
+function artifactEdgeKey(edge) {
+  return [edge.name, edge.from, edge.to, edge.producerStep, edge.consumerStep, edge.match].join(
+    "\0",
+  );
+}
+
+function workflowRunEdgeKey(edge) {
+  const metadata = {
+    types: edge.types,
+    branches: edge.branches,
+    branchesIgnore: edge.branchesIgnore,
+  };
+  return [edge.from, edge.to, JSON.stringify(metadata)].join("\0");
+}
+
+/**
+ * Builds a frozen, sorted query index over a `WorkflowTopology` (the
+ * parsed object returned by `ciTopology()`, or `JSON.parse`d from
+ * `no-mistakes ci topology --format json`).
+ */
+function createWorkflowTopologyIndex(topology) {
+  const workflowsByPath = new Map(
+    topology.workflows.map((workflow) => [workflow.path, deepFrozenClone(workflow)]),
+  );
+  const jobsById = new Map(topology.jobs.map((job) => [job.id, deepFrozenClone(job)]));
+  const upstreamJobs = adjacencyMap(jobsById.keys());
+  const downstreamJobs = adjacencyMap(jobsById.keys());
+  const callerJobs = adjacencyMap(workflowsByPath.keys());
+  const callers = adjacencyMap(workflowsByPath.keys());
+  const callees = adjacencyMap(workflowsByPath.keys());
+  const workflowRunSources = adjacencyMap(workflowsByPath.keys());
+  const workflowRunSubscribers = adjacencyMap(workflowsByPath.keys());
+  const artifactProducers = artifactEdgeMap(jobsById.keys());
+  const artifactConsumers = artifactEdgeMap(jobsById.keys());
+  const incomingWorkflowRunEdges = new Map([...workflowsByPath.keys()].map((path) => [path, []]));
+  const outgoingWorkflowRunEdges = new Map([...workflowsByPath.keys()].map((path) => [path, []]));
+
+  for (const edge of topology.edges) {
+    if (edge.kind === "needs") {
+      if (!jobsById.has(edge.from) || !jobsById.has(edge.to)) continue;
+      upstreamJobs.get(edge.to).add(edge.from);
+      downstreamJobs.get(edge.from).add(edge.to);
+      continue;
+    }
+    if (edge.kind === "workflow-run") {
+      if (!workflowsByPath.has(edge.from) || !workflowsByPath.has(edge.to)) continue;
+      const edgeSnapshot = deepFrozenClone(edge);
+      workflowRunSources.get(edge.to).add(edge.from);
+      workflowRunSubscribers.get(edge.from).add(edge.to);
+      incomingWorkflowRunEdges.get(edge.to).push(edgeSnapshot);
+      outgoingWorkflowRunEdges.get(edge.from).push(edgeSnapshot);
+      continue;
+    }
+    if (edge.kind === "artifact") {
+      if (!jobsById.has(edge.from) || !jobsById.has(edge.to)) continue;
+      const edgeSnapshot = deepFrozenClone(edge);
+      artifactProducers.get(edge.to).push(edgeSnapshot);
+      artifactConsumers.get(edge.from).push(edgeSnapshot);
+      continue;
+    }
+    // edge.kind === "calls"
+    if (!edge.local || !edge.to || !jobsById.has(edge.from) || !workflowsByPath.has(edge.to))
+      continue;
+    const callerPath = workflowPathFromId(edge.from);
+    if (!workflowsByPath.has(callerPath)) continue;
+    callerJobs.get(edge.to).add(edge.from);
+    callers.get(edge.to).add(callerPath);
+    callees.get(callerPath).add(edge.to);
+  }
+
+  const jobQuery = (adjacency, transitive) => (jobId) => {
+    assertKnown(jobsById, jobId, "workflow job");
+    return query(adjacency, jobId, transitive);
+  };
+  const workflowQuery = (adjacency, transitive) => (workflowPath) => {
+    assertKnown(workflowsByPath, workflowPath, "workflow");
+    return query(adjacency, workflowPath, transitive);
+  };
+  const workflowRunEdgeQuery = (edgesByPath) => (workflowPath) => {
+    assertKnown(workflowsByPath, workflowPath, "workflow");
+    return Object.freeze(
+      [...edgesByPath.get(workflowPath)].sort((left, right) =>
+        workflowRunEdgeKey(left).localeCompare(workflowRunEdgeKey(right)),
+      ),
+    );
+  };
+  const artifactEdgeQuery = (edgesByJob) => (jobId) => {
+    assertKnown(jobsById, jobId, "workflow job");
+    return Object.freeze(
+      [...edgesByJob.get(jobId)].sort((left, right) =>
+        artifactEdgeKey(left).localeCompare(artifactEdgeKey(right)),
+      ),
+    );
+  };
+
+  return Object.freeze({
+    workflowsByPath: new FrozenReadonlyMap(workflowsByPath),
+    jobsById: new FrozenReadonlyMap(jobsById),
+    directUpstreamJobIds: jobQuery(upstreamJobs, false),
+    transitiveUpstreamJobIds: jobQuery(upstreamJobs, true),
+    directDownstreamJobIds: jobQuery(downstreamJobs, false),
+    transitiveDownstreamJobIds: jobQuery(downstreamJobs, true),
+    directCallerJobIds: workflowQuery(callerJobs, false),
+    directCallerWorkflowPaths: workflowQuery(callers, false),
+    transitiveCallerWorkflowPaths: workflowQuery(callers, true),
+    directCalleeWorkflowPaths: workflowQuery(callees, false),
+    transitiveCalleeWorkflowPaths: workflowQuery(callees, true),
+    incomingWorkflowRunEdges: workflowRunEdgeQuery(incomingWorkflowRunEdges),
+    outgoingWorkflowRunEdges: workflowRunEdgeQuery(outgoingWorkflowRunEdges),
+    directWorkflowRunSourcePaths: workflowQuery(workflowRunSources, false),
+    transitiveWorkflowRunSourcePaths: workflowQuery(workflowRunSources, true),
+    directWorkflowRunSubscriberPaths: workflowQuery(workflowRunSubscribers, false),
+    transitiveWorkflowRunSubscriberPaths: workflowQuery(workflowRunSubscribers, true),
+    artifactProducersForConsumerJob: artifactEdgeQuery(artifactProducers),
+    artifactConsumersForProducerJob: artifactEdgeQuery(artifactConsumers),
+  });
+}
+
+module.exports = { createWorkflowTopologyIndex };

package/workflow-topology-types.d.ts

@@ -0,0 +1,179 @@
+// Types for `ciTopology()` / `no-mistakes ci topology` and the JS-only
+// `createWorkflowTopologyIndex()` query index built from its output.
+//
+// This mirrors the schema-v1 JSON contract exactly (field names, casing) —
+// see `docs/node-api.md` for the stability guarantees (field order and
+// array/diagnostic sort order are part of the contract).
+
+import type { ArtifactDeclaration, ArtifactEdge } from "./workflow-topology-artifact-types";
+
+export * from "./workflow-topology-artifact-types";
+export * from "./workflow-topology-index-types";
+
+export interface CiTopologyOptions {
+  /** Project root. Defaults to the current working directory. */
+  root?: string;
+  /** Path to the no-mistakes config file (e.g. .no-mistakes.yml). Auto-discovered in root if omitted. */
+  config?: string;
+  /**
+   * Restrict output to these workflow(s) (basename or a path inside
+   * `.github/workflows`) plus their transitive local reusable-workflow
+   * callees. Omit or pass `[]` for every workflow.
+   */
+  workflows?: string[];
+}
+
+export type JsonScalar = boolean | number | string;
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type ConcurrencyValue = boolean | string;
+
+export interface WorkflowConcurrency {
+  raw: { group: string; cancelInProgress?: ConcurrencyValue; queue?: string };
+  effective: { group: string; cancelInProgress: ConcurrencyValue; queue: string };
+}
+
+export interface WorkflowTrigger {
+  event: string;
+  config?: JsonValue;
+}
+
+export interface WorkflowCallInput {
+  type?: "boolean" | "number" | "string";
+  required: boolean;
+  default?: JsonScalar;
+  description?: string;
+}
+
+export interface WorkflowCallSecret {
+  required: boolean;
+  description?: string;
+}
+
+export interface WorkflowCallOutput {
+  value?: string;
+  description?: string;
+}
+
+export interface WorkflowCallContract {
+  inputs: Record<string, WorkflowCallInput>;
+  secrets: Record<string, WorkflowCallSecret>;
+  outputs: Record<string, WorkflowCallOutput>;
+}
+
+export type WorkflowNode = {
+  id: string;
+  path: string;
+  name: string;
+  triggers: WorkflowTrigger[];
+  jobIds: string[];
+  concurrency?: WorkflowConcurrency;
+} & (
+  | { callable: true; workflowCall: WorkflowCallContract }
+  | { callable: false; workflowCall?: undefined }
+);
+
+export interface WorkflowStep {
+  index: number;
+  kind: "action" | "run" | "other";
+  id?: string;
+  name?: string;
+  condition?: string;
+  uses?: string;
+  /** Present when this step is an `actions/{upload,download}-artifact` action. */
+  artifact?: ArtifactDeclaration;
+}
+
+export interface WorkflowJobNode {
+  id: string;
+  workflowId: string;
+  key: string;
+  kind: "job" | "matrix-template";
+  name?: string;
+  condition?: string;
+  matrix?: JsonValue;
+  concurrency?: WorkflowConcurrency;
+  steps: WorkflowStep[];
+}
+
+export interface NeedsEdge {
+  kind: "needs";
+  from: string;
+  to: string;
+}
+
+export interface WorkflowCallEdge {
+  kind: "calls";
+  from: string;
+  target: string;
+  local: boolean;
+  bindings: {
+    inputs: Record<string, JsonScalar>;
+    secrets: { mode: "inherit" } | { mode: "explicit"; values: Record<string, JsonScalar> };
+  };
+  /** Present only for local (`./`) calls. */
+  to?: string;
+}
+
+export interface WorkflowRunEdge {
+  kind: "workflow-run";
+  from: string;
+  to: string;
+  types?: string[];
+  branches?: string[];
+  branchesIgnore?: string[];
+}
+
+export type WorkflowTopologyEdge = NeedsEdge | WorkflowCallEdge | WorkflowRunEdge | ArtifactEdge;
+
+export type WorkflowTopologyDiagnosticCode =
+  | "malformed-workflow"
+  | "missing-needs-dependency"
+  | "job-dependency-cycle"
+  | "duplicate-step-id"
+  | "unknown-step-reference"
+  | "non-prior-step-reference"
+  | "duplicate-workflow-name"
+  | "missing-local-workflow"
+  | "non-callable-workflow"
+  | "workflow-call-cycle"
+  | "missing-workflow-run-source"
+  | "ambiguous-workflow-run-source"
+  | "workflow-run-cycle"
+  | "workflow-run-chain-limit"
+  | "unknown-workflow-filter"
+  | "invalid-workflow-filter"
+  | "missing-workflow-call-input"
+  | "unknown-workflow-call-input"
+  | "workflow-call-input-type-mismatch"
+  | "missing-workflow-call-secret"
+  | "unknown-workflow-call-secret"
+  | "unknown-workflow-call-output"
+  | "missing-artifact-producer"
+  | "ambiguous-artifact-producer"
+  | "artifact-resolution-limit";
+
+export interface WorkflowTopologyDiagnostic {
+  severity: "error";
+  code: WorkflowTopologyDiagnosticCode;
+  message: string;
+  workflowPath: string;
+  jobId?: string;
+  stepIndex?: number;
+  callJobId?: string;
+  calleeWorkflowPath?: string;
+}
+
+export interface WorkflowTopology {
+  schemaVersion: 1;
+  workflows: WorkflowNode[];
+  jobs: WorkflowJobNode[];
+  edges: WorkflowTopologyEdge[];
+  diagnostics: WorkflowTopologyDiagnostic[];
+}