no-mistakes 0.32.1 → 0.33.1

package/README.md

@@ -42,6 +42,8 @@ const {
     root: process.cwd(),
     files: ["src/main.mts"],
     relationships: ["import"],
+    timeout: 30,
+    lockTimeout: 30,
   });
   const tests = await dependents({
     root: process.cwd(),
@@ -75,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({
@@ -108,6 +112,13 @@ 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.
+
 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.d.ts

@@ -66,72 +66,135 @@ import type {
   TestsWhyOptions,
   TraverseOptions,
   WhyStep,
+  WithInvocationOptions,
 } from "./types";
 
 export * from "./types";
 
-export function dependencies(options: TraverseOptions): Promise<DependencyResult>;
-export function dependents(options: TraverseOptions): Promise<DependencyResult>;
-export function related(options: TraverseOptions): Promise<DependencyResult>;
-export function analyzeProject(options: AnalyzeProjectOptions): Promise<AnalyzeProjectResult>;
-export function symbols(options: SymbolsSignatureImpactOptions): Promise<SignatureImpactResult>;
-export function symbols(options: SymbolsListOptions): Promise<SymbolsResult>;
-export function symbols(options: SymbolsOptions): Promise<SymbolsResult | SignatureImpactResult>;
-export function importUsages(options?: ImportUsagesOptions): Promise<ImportUsagesResult>;
-export function importers(options: ImportersOptions): Promise<ImportersResult>;
-export function exportsOf(options: ExportsOfOptions): Promise<ExportsOfResult>;
-export function deadExports(options: DeadExportsOptions): Promise<DeadExportsResult>;
-export function callSites(options: CallSitesOptions): Promise<CallSitesResult>;
-export function resolveCheck(options: ResolveCheckOptions): Promise<ResolveCheckResult>;
-export function fetches(options?: FetchesOptions): Promise<unknown>;
-export function flow(options: FlowOptions): Promise<FlowReport>;
-export function check(options?: ProjectOptions): Promise<CheckReport>;
-export function testsPlan(options: TestsPlanOptions): Promise<TestPlan>;
-export function testsImpact(options: TestsImpactOptions): Promise<TestPlan>;
-export function testsTargets(options: TestsTargetsOptions): Promise<TestsTargetsReport>;
-export function testsWhy(options: TestsWhyOptions): Promise<Record<string, WhyStep[]>>;
-export function testsComment(options: TestsPlanDocumentOptions): Promise<string>;
-export function testsGraph(options: TestsPlanDocumentOptions): Promise<TestGraph>;
-export function testsGraphMermaid(options: TestsPlanDocumentOptions): Promise<string>;
-export function playwrightCheck(options?: PlaywrightOptions): Promise<unknown>;
-export function playwrightEdges(options?: PlaywrightOptions): Promise<unknown>;
-export function playwrightRelated(options: PlaywrightRelatedOptions): Promise<unknown>;
-export function playwrightTests(options?: PlaywrightOptions): Promise<unknown>;
-export function queues(options?: ProjectOptions): Promise<QueueReport>;
-export function queueEdges(options?: ProjectOptions): Promise<GraphEdge[]>;
-export function queueRelated(options: ProjectOptions): Promise<GraphEdge[]>;
-export function queueCheck(options?: ProjectOptions): Promise<unknown[]>;
-export function serverRoutes(options?: ProjectOptions): Promise<ServerRoutesReport>;
-export function serverRouteList(options?: ProjectOptions): Promise<unknown[]>;
-export function serverRouteEdges(options?: ProjectOptions): Promise<GraphEdge[]>;
-export function serverRouteRelated(options: ProjectOptions): Promise<GraphEdge[]>;
-export function serverContracts(options?: ProjectOptions): Promise<ServerContractsReport>;
-export function reactAnalyze(options?: ProjectOptions): Promise<ReactComponentFacts[]>;
-export function reactCheck(options?: ProjectOptions): Promise<ReactViolation[]>;
+export function dependencies(
+  options: WithInvocationOptions<TraverseOptions>,
+): Promise<DependencyResult>;
+export function dependents(
+  options: WithInvocationOptions<TraverseOptions>,
+): Promise<DependencyResult>;
+export function related(options: WithInvocationOptions<TraverseOptions>): Promise<DependencyResult>;
+export function analyzeProject(
+  options: WithInvocationOptions<AnalyzeProjectOptions>,
+): Promise<AnalyzeProjectResult>;
+export function symbols(
+  options: WithInvocationOptions<SymbolsSignatureImpactOptions>,
+): Promise<SignatureImpactResult>;
+export function symbols(options: WithInvocationOptions<SymbolsListOptions>): Promise<SymbolsResult>;
+export function symbols(
+  options: WithInvocationOptions<SymbolsOptions>,
+): Promise<SymbolsResult | SignatureImpactResult>;
+export function importUsages(
+  options?: WithInvocationOptions<ImportUsagesOptions>,
+): Promise<ImportUsagesResult>;
+export function importers(
+  options: WithInvocationOptions<ImportersOptions>,
+): Promise<ImportersResult>;
+export function exportsOf(
+  options: WithInvocationOptions<ExportsOfOptions>,
+): Promise<ExportsOfResult>;
+export function deadExports(
+  options: WithInvocationOptions<DeadExportsOptions>,
+): Promise<DeadExportsResult>;
+export function callSites(
+  options: WithInvocationOptions<CallSitesOptions>,
+): Promise<CallSitesResult>;
+export function resolveCheck(
+  options: WithInvocationOptions<ResolveCheckOptions>,
+): Promise<ResolveCheckResult>;
+export function fetches(options?: WithInvocationOptions<FetchesOptions>): Promise<unknown>;
+export function flow(options: WithInvocationOptions<FlowOptions>): Promise<FlowReport>;
+export function check(options?: WithInvocationOptions<ProjectOptions>): Promise<CheckReport>;
+export function testsPlan(options: WithInvocationOptions<TestsPlanOptions>): Promise<TestPlan>;
+export function testsImpact(options: WithInvocationOptions<TestsImpactOptions>): Promise<TestPlan>;
+export function testsTargets(
+  options: WithInvocationOptions<TestsTargetsOptions>,
+): Promise<TestsTargetsReport>;
+export function testsWhy(
+  options: WithInvocationOptions<TestsWhyOptions>,
+): Promise<Record<string, WhyStep[]>>;
+export function testsComment(
+  options: WithInvocationOptions<TestsPlanDocumentOptions>,
+): Promise<string>;
+export function testsGraph(
+  options: WithInvocationOptions<TestsPlanDocumentOptions>,
+): Promise<TestGraph>;
+export function testsGraphMermaid(
+  options: WithInvocationOptions<TestsPlanDocumentOptions>,
+): Promise<string>;
+export function playwrightCheck(
+  options?: WithInvocationOptions<PlaywrightOptions>,
+): Promise<unknown>;
+export function playwrightEdges(
+  options?: WithInvocationOptions<PlaywrightOptions>,
+): Promise<unknown>;
+export function playwrightRelated(
+  options: WithInvocationOptions<PlaywrightRelatedOptions>,
+): Promise<unknown>;
+export function playwrightTests(
+  options?: WithInvocationOptions<PlaywrightOptions>,
+): Promise<unknown>;
+export function queues(options?: WithInvocationOptions<ProjectOptions>): Promise<QueueReport>;
+export function queueEdges(options?: WithInvocationOptions<ProjectOptions>): Promise<GraphEdge[]>;
+export function queueRelated(options: WithInvocationOptions<ProjectOptions>): Promise<GraphEdge[]>;
+export function queueCheck(options?: WithInvocationOptions<ProjectOptions>): Promise<unknown[]>;
+export function serverRoutes(
+  options?: WithInvocationOptions<ProjectOptions>,
+): Promise<ServerRoutesReport>;
+export function serverRouteList(
+  options?: WithInvocationOptions<ProjectOptions>,
+): Promise<unknown[]>;
+export function serverRouteEdges(
+  options?: WithInvocationOptions<ProjectOptions>,
+): Promise<GraphEdge[]>;
+export function serverRouteRelated(
+  options: WithInvocationOptions<ProjectOptions>,
+): Promise<GraphEdge[]>;
+export function serverContracts(
+  options?: WithInvocationOptions<ProjectOptions>,
+): Promise<ServerContractsReport>;
+export function reactAnalyze(
+  options?: WithInvocationOptions<ProjectOptions>,
+): Promise<ReactComponentFacts[]>;
+export function reactCheck(
+  options?: WithInvocationOptions<ProjectOptions>,
+): Promise<ReactViolation[]>;
 export function reactUsages(
-  options: ProjectOptions & { target: string },
+  options: WithInvocationOptions<ProjectOptions & { target: string }>,
 ): Promise<ReactUsagesReport>;
-export function lockfileDiff(options: LockfileDiffOptions): Promise<LockfileDiffEntry[]>;
-export function ciImpact(options: CiImpactOptions): Promise<CiImpactReport>;
-export function ciEnv(options: CiEnvOptions): Promise<CiEnvReport>;
-export function impactedChecks(options: ImpactedChecksOptions): Promise<ImpactedChecksReport>;
-export function dataPw(options: DataPwOptions): Promise<DataPwReport>;
-export function effects(options: EffectsOptions): Promise<EffectsReport>;
-export function rscCallers(options: RscCallersOptions): Promise<RscCallersReport>;
+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: RegistryExtensionOptions,
+  options: WithInvocationOptions<RegistryExtensionOptions>,
 ): Promise<RegistryExtensionReport>;
 export function infraResourceRefs(
-  options: InfraOptions & { address: string },
+  options: WithInvocationOptions<InfraOptions & { address: string }>,
 ): Promise<ResourceRefRow[]>;
 export function infraOutputs(
-  options: InfraOptions & { moduleDir: string },
+  options: WithInvocationOptions<InfraOptions & { moduleDir: string }>,
 ): Promise<ModuleOutputsResult>;
-export function infraTestFor(options: InfraOptions & { tfFile: string }): Promise<TestForRow[]>;
+export function infraTestFor(
+  options: WithInvocationOptions<InfraOptions & { tfFile: string }>,
+): Promise<TestForRow[]>;
 export function swiftImporters(
-  options: SwiftOptions & { file: string },
+  options: WithInvocationOptions<SwiftOptions & { file: string }>,
 ): Promise<SwiftImporterRow[]>;
 export function swiftTestTargets(
-  options: SwiftOptions & { file: string },
+  options: WithInvocationOptions<SwiftOptions & { file: string }>,
 ): Promise<SwiftTestTargetRow[]>;
 export function version(): Promise<string>;

package/invocation-types.d.ts

@@ -0,0 +1,11 @@
+/** Controls shared by every analysis invocation. Durations are in seconds. */
+export interface InvocationOptions {
+  /** Command execution timeout. Defaults to 30; 0 or null disables it. */
+  timeout?: number | null;
+  /** Maximum time to wait for the machine-wide lock. Defaults to 30; 0 or null waits indefinitely. */
+  lockTimeout?: number | null;
+  /** Fail immediately instead of waiting when another invocation holds the lock. */
+  failOnLock?: boolean;
+}
+
+export type WithInvocationOptions<T> = T & InvocationOptions;

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.32.1",
+  "version": "0.33.1",
   "description": "Static codebase analysis tools for TS/JS dependencies, dependents, and symbols",
   "license": "MIT",
   "repository": {

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[];
 }
@@ -100,8 +108,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;
@@ -124,6 +135,7 @@ export interface TestGraph {
 }
 
 export interface LockfileDiffOptions {
+  /** Project root. Defaults to the current working directory. */
   root?: string;
   base: string;
   head?: string;

package/traversal-types.d.ts

@@ -23,7 +23,9 @@ export type Relationship =
 
 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[];
@@ -68,8 +70,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 +160,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

@@ -1,3 +1,4 @@
+export * from "./invocation-types";
 export * from "./traversal-types";
 export * from "./analyze-project-types";
 export * from "./flow-types";