no-mistakes 0.33.0 → 0.34.0

package/README.md

@@ -77,6 +77,8 @@ const {
   });
   const projectCheck = await check({
     root: process.cwd(),
+    // Path to tsconfig.json for alias resolution; searched upward if omitted.
+    // In monorepos, pass the workspace-scoped tsconfig (e.g. "web/tsconfig.json").
     tsconfig: "tsconfig.json",
   });
   const localFlow = await flow({
@@ -117,6 +119,13 @@ 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.
+
 External `no-mistakes-*` executables on `PATH` can be invoked as subcommands.
 For example, after installing `no-mistakes-scripts`:
 

package/analyze-project-types.d.ts

@@ -55,8 +55,11 @@ export type AnalyzeProjectReportRequest =
   | ({ type: "check"; id?: string } & BatchedCheckOptions);
 
 export interface AnalyzeProjectOptions {
+  /** Project root. Defaults to the current working directory. */
   root?: string;
+  /** Path to tsconfig.json for alias resolution. Searched upward if omitted. */
   tsconfig?: string;
+  /** Path to the no-mistakes config file (e.g. .no-mistakes.yml). Auto-discovered in root if omitted. */
   config?: string;
   filters?: string[];
   reports: AnalyzeProjectReportRequest[];

package/ci-types.d.ts

@@ -3,22 +3,29 @@
 // snake_case to match the serde-serialized output.
 
 export interface CiImpactOptions {
+  /** 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;
   /** Changed file paths (relative to root or absolute). */
   files: string[];
 }
 
 export interface CiEnvOptions {
+  /** 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;
   /** Environment variable name (case-sensitive). */
   var: string;
 }
 
 export interface ImpactedChecksOptions {
+  /** 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;
+  /** Path to tsconfig.json for alias resolution. Searched upward if omitted. */
   tsconfig?: string;
   base?: string;
   head?: string;

package/flow-types.d.ts

@@ -2,8 +2,11 @@ import type { Relationship } from "./traversal-types";
 
 export interface FlowOptions {
   target: string;
+  /** Project root. Defaults to the current working directory. */
   root?: string;
+  /** Path to tsconfig.json for alias resolution. Searched upward if omitted. */
   tsconfig?: string;
+  /** Path to the no-mistakes config file (e.g. .no-mistakes.yml). Auto-discovered in root if omitted. */
   config?: string;
   direction?: "deps" | "dependents" | "both";
   depth?: number;
@@ -35,7 +38,9 @@ export interface FlowReport {
 }
 
 export interface FetchesOptions {
+  /** 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;
   targets?: string[];
 }

package/import-usage-types.d.ts

@@ -16,6 +16,7 @@ export interface ImportUsageFile {
 
 export interface ImportUsagesOptions {
   files?: string[];
+  /** Project root. Defaults to the current working directory. */
   root?: string;
   scanRoots?: string[];
   filters?: string[];

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/named-query-types.d.ts

@@ -1,7 +1,9 @@
 // Named query modes (issue #419): data-pw, effects, rsc-callers, registry-extension.
 
 export interface DataPwOptions {
+  /** 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;
   /** The selector-attribute value to find (e.g. `search-bar`). */
   value: string;
@@ -29,8 +31,11 @@ export interface DataPwReport {
 }
 
 export interface EffectsOptions {
+  /** Project root. Defaults to the current working directory. */
   root?: string;
+  /** Path to tsconfig.json for alias resolution. Searched upward if omitted. */
   tsconfig?: string;
+  /** Path to the no-mistakes config file (e.g. .no-mistakes.yml). Auto-discovered in root if omitted. */
   config?: string;
   /** Effect kind to resolve (a key under `effects:` in config). */
   kind: string;
@@ -59,8 +64,11 @@ export interface EffectsReport {
 }
 
 export interface RscCallersOptions {
+  /** Project root. Defaults to the current working directory. */
   root?: string;
+  /** Path to tsconfig.json for alias resolution. Searched upward if omitted. */
   tsconfig?: string;
+  /** Path to the no-mistakes config file (e.g. .no-mistakes.yml). Auto-discovered in root if omitted. */
   config?: string;
   /** Component file to find RSC callers of. */
   component: string;
@@ -81,6 +89,7 @@ export interface RscCallersReport {
 }
 
 export interface RegistryExtensionOptions {
+  /** Project root. Defaults to the current working directory. */
   root?: string;
   /** Registry file to summarize the entry pattern of. */
   registryFile: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "no-mistakes",
-  "version": "0.33.0",
+  "version": "0.34.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/report-types.d.ts

@@ -1,5 +1,7 @@
 export interface PlaywrightOptions {
+  /** 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;
   playwrightConfig?: string[];
   project?: string;
@@ -40,7 +42,9 @@ export interface GraphEdge {
 }
 
 export interface InfraOptions {
+  /** 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;
   /** `infraResourceRefs` address (`<type>.<name>`). */
   address?: string;
@@ -79,7 +83,9 @@ export interface TestForRow {
 }
 
 export interface SwiftOptions {
+  /** 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;
   /** The Swift source file to query (relative to root). */
   file?: string;

package/scripts/install/retry.js

@@ -1,8 +1,14 @@
 "use strict";
 
-const DEFAULT_MAX_ATTEMPTS = 4;
-const DEFAULT_RETRY_BASE_MS = 500;
-const RETRY_MAX_DELAY_MS = 4_000;
+// A GitHub Releases asset download or its separate .sha256 checksum fetch can
+// hit a short-lived CDN 5xx, timeout, or connection reset. These defaults give
+// each network operation a bounded multi-attempt window (~15s avg / ~31s worst
+// case total sleep) to ride that out, rather than exhausting a tiny budget in a
+// few seconds. Override via NO_MISTAKES_DOWNLOAD_MAX_ATTEMPTS /
+// NO_MISTAKES_DOWNLOAD_RETRY_BASE_MS.
+const DEFAULT_MAX_ATTEMPTS = 6;
+const DEFAULT_RETRY_BASE_MS = 1_000;
+const RETRY_MAX_DELAY_MS = 30_000;
 const RETRYABLE_NETWORK_CODES = new Set([
   "ECONNRESET",
   "ECONNREFUSED",

package/test-types.d.ts

@@ -2,8 +2,11 @@ import type { SymbolEntrypoint } from "./traversal-types";
 
 export interface TestsPlanOptions {
   framework?: "vitest" | "playwright" | "dotnet" | "swift";
+  /** 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;
+  /** Path to tsconfig.json for alias resolution. Searched upward if omitted. */
   tsconfig?: string;
   base?: string;
   head?: string;
@@ -24,8 +27,11 @@ export interface TestsPlanOptions {
 }
 
 export interface TestsImpactOptions {
+  /** 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;
+  /** Path to tsconfig.json for alias resolution. Searched upward if omitted. */
   tsconfig?: string;
   /** Entrypoints to trace impact from: strings may use file#export, or pass { file, symbol }. */
   entrypoints: Array<string | SymbolEntrypoint>;
@@ -35,7 +41,9 @@ export interface TestsImpactOptions {
 
 export interface TestsTargetsOptions {
   framework: "vitest" | "playwright" | "dotnet" | "swift";
+  /** 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;
   files: string[];
 }
@@ -67,8 +75,32 @@ 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;
+
+export interface ResourceImpactEdgeDetail {
+  type: "resource";
+  consumer_file: string;
+  call_sites: ResourceCallSite[];
+}
+
+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[];
@@ -80,6 +112,7 @@ export interface TestPlanWarning {
   type: string;
   message: string;
   file: string;
+  line?: number;
 }
 
 export interface TestsTargetsReport {
@@ -100,8 +133,11 @@ export interface TestTargetWarning {
 }
 
 export interface TestsWhyOptions {
+  /** 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;
+  /** Path to tsconfig.json for alias resolution. Searched upward if omitted. */
   tsconfig?: string;
   test: string;
   changed?: string;
@@ -111,6 +147,7 @@ export interface TestsWhyOptions {
 export interface WhyStep {
   node: string;
   via?: string | null;
+  detail?: ImpactEdgeDetail | null;
 }
 
 export interface TestsPlanDocumentOptions {
@@ -120,10 +157,11 @@ 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 {
+  /** Project root. Defaults to the current working directory. */
   root?: string;
   base: string;
   head?: string;

package/traversal-types.d.ts

@@ -19,11 +19,14 @@ export type Relationship =
   | "dotnet"
   | "swift"
   | "terraform"
+  | "resource"
   | "all";
 
 export interface TraverseOptions {
   files: Array<string | SymbolEntrypoint>;
+  /** Project root. Defaults to the current working directory. */
   root?: string;
+  /** Path to tsconfig.json for alias resolution. Searched upward if omitted. */
   tsconfig?: string;
   depth?: number;
   filters?: string[];
@@ -49,9 +52,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 =
@@ -68,8 +87,11 @@ export type ExportKind =
 
 export interface SymbolsOptions {
   files: string[];
+  /** Project root. Defaults to the current working directory. */
   root?: string;
+  /** Path to tsconfig.json for alias resolution. Searched upward if omitted. */
   tsconfig?: string;
+  /** Path to the no-mistakes config file (e.g. .no-mistakes.yml). Auto-discovered in root if omitted. */
   config?: string;
   mode?: "list" | "signature-impact";
   symbol?: string;
@@ -155,8 +177,11 @@ export interface SignatureImpactResult {
 }
 
 export interface ProjectOptions {
+  /** Project root. Defaults to the current working directory. */
   root?: string;
+  /** Path to tsconfig.json for alias resolution. Searched upward if omitted. */
   tsconfig?: string;
+  /** Path to the no-mistakes config file (e.g. .no-mistakes.yml). Auto-discovered in root if omitted. */
   config?: string;
   filters?: string[];
   targets?: string[];

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[];
+}