pruneguard 0.2.1 → 0.3.1

package/dist/index.d.mts

@@ -1,4 +1,13 @@
 //#region src-js/runtime.d.ts
+type ResolutionSource = "env" | "platform-package" | "dev" | "path";
+type ResolutionInfo = {
+  binaryPath: string;
+  source: ResolutionSource;
+  platformPackage?: string;
+  schemaPath?: string;
+  version?: string;
+  platform?: string;
+};
 type CommandResult = {
   args: string[];
   cwd?: string;
@@ -14,12 +23,14 @@ declare class PruneguardExecutionError extends Error {
   stderr?: string;
   binaryPath?: string;
   args?: string[];
+  resolutionSource?: ResolutionSource;
   constructor(code: PruneguardExecutionError["code"], message: string, details?: {
     exitCode?: number;
     stdout?: string;
     stderr?: string;
     binaryPath?: string;
     args?: string[];
+    resolutionSource?: ResolutionSource;
   });
 }
 //#endregion
@@ -113,6 +124,8 @@ type AnalysisReport = {
     }>;
     suggestion?: string;
     ruleName?: string;
+    primaryActionKind?: string;
+    actionKinds?: string[];
   }>;
   entrypoints: Array<{
     path: string;
@@ -164,6 +177,12 @@ type AnalysisReport = {
     cacheEntriesRead: number;
     cacheEntriesWritten: number;
     affectedScopeIncomplete: boolean;
+    executionMode?: "oneshot" | "daemon";
+    indexWarm?: boolean;
+    indexAgeMs?: number;
+    reusedGraphNodes?: number;
+    reusedGraphEdges?: number;
+    watcherLagMs?: number;
   };
 };
 type MigrationOutput = {
@@ -197,8 +216,156 @@ type ExplainReport = {
   focusFiltered: boolean;
 };
 type PruneguardConfig = Record<string, unknown>;
+type ReviewOptions = {
+  cwd?: string;
+  config?: string;
+  profile?: Profile;
+  baseRef?: string;
+  noCache?: boolean;
+  noBaseline?: boolean;
+};
+type ReviewReport = {
+  baseRef?: string;
+  changedFiles: string[];
+  newFindings: AnalysisReport["findings"];
+  blockingFindings: AnalysisReport["findings"];
+  advisoryFindings: AnalysisReport["findings"];
+  trust: {
+    fullScope: boolean;
+    baselineApplied: boolean;
+    unresolvedPressure: number;
+    confidenceCounts: {
+      high: number;
+      medium: number;
+      low: number;
+    };
+  };
+  recommendations: string[];
+  proposedActions?: Array<{
+    id: string;
+    kind: string;
+    targets: string[];
+    why: string;
+    preconditions: string[];
+    steps: Array<{
+      description: string;
+      file?: string;
+      action?: string;
+    }>;
+    verification: string[];
+    risk: "low" | "medium" | "high";
+    confidence: "high" | "medium" | "low";
+  }>;
+  executionMode?: "oneshot" | "daemon";
+  latencyMs?: number;
+};
+type SafeDeleteOptions = {
+  cwd?: string;
+  config?: string;
+  profile?: Profile;
+  targets: string[];
+  noCache?: boolean;
+};
+type SafeDeleteReport = {
+  targets: string[];
+  safe: Array<{
+    target: string;
+    confidence?: "high" | "medium" | "low";
+    reasons: string[];
+  }>;
+  needsReview: Array<{
+    target: string;
+    confidence?: "high" | "medium" | "low";
+    reasons: string[];
+  }>;
+  blocked: Array<{
+    target: string;
+    confidence?: "high" | "medium" | "low";
+    reasons: string[];
+  }>;
+  deletionOrder: string[];
+  evidence: Array<{
+    kind: string;
+    file?: string;
+    line?: number;
+    description: string;
+  }>;
+};
+type FixPlanOptions = {
+  cwd?: string;
+  config?: string;
+  profile?: Profile;
+  targets: string[];
+  noCache?: boolean;
+};
+type SuggestRulesOptions = {
+  cwd?: string;
+  config?: string;
+  profile?: Profile;
+  noCache?: boolean;
+};
+type SuggestRulesReport = {
+  suggestedRules: Array<{
+    kind: string;
+    name: string;
+    description: string;
+    configFragment: Record<string, unknown>;
+    confidence: "high" | "medium" | "low";
+    evidence?: string[];
+  }>;
+  tags?: Array<{
+    name: string;
+    glob: string;
+    rationale: string;
+  }>;
+  ownershipHints?: Array<{
+    pathGlob: string;
+    suggestedOwner: string;
+    crossTeamEdges: number;
+    rationale: string;
+  }>;
+  hotspots?: Array<{
+    file: string;
+    crossPackageImports: number;
+    crossOwnerImports: number;
+    incomingEdges: number;
+    outgoingEdges: number;
+    suggestion: string;
+  }>;
+  rationale?: string[];
+};
+type FixPlanReport = {
+  query: string[];
+  matchedFindings: AnalysisReport["findings"];
+  actions: Array<{
+    id: string;
+    kind: string;
+    targets: string[];
+    why: string;
+    preconditions: string[];
+    steps: Array<{
+      description: string;
+      file?: string;
+      action?: string;
+    }>;
+    verification: string[];
+    risk: "low" | "medium" | "high";
+    confidence: "high" | "medium" | "low";
+  }>;
+  blockedBy: string[];
+  verificationSteps: string[];
+  riskLevel: "low" | "medium" | "high";
+  confidence: "high" | "medium" | "low";
+};
+type DaemonStatusReport = {
+  running: boolean;
+  pid?: number;
+  port?: number;
+  version?: string;
+  startedAt?: string;
+  projectRoot?: string;
+};
 declare function scan(options?: ScanOptions): Promise<AnalysisReport>;
-/** @experimental */
 declare function scanDot(options?: ScanOptions): Promise<string>;
 declare function impact(options: ImpactOptions): Promise<ImpactReport>;
 declare function explain(options: ExplainOptions): Promise<ExplainReport>;
@@ -208,21 +375,27 @@ declare function loadConfig(options?: {
 }): Promise<PruneguardConfig>;
 declare function schemaPath(): string;
 declare function binaryPath(): string;
+declare function resolutionInfo(): ResolutionInfo;
 declare function run(args: string[], options?: {
   cwd?: string;
 }): Promise<CommandResult>;
 declare function debugResolve(options: DebugResolveOptions): Promise<string>;
 declare function debugEntrypoints(options?: DebugEntrypointsOptions): Promise<string[]>;
-/** @experimental */
+declare function review(options?: ReviewOptions): Promise<ReviewReport>;
+declare function safeDelete(options: SafeDeleteOptions): Promise<SafeDeleteReport>;
+declare function fixPlan(options: FixPlanOptions): Promise<FixPlanReport>;
+declare function suggestRules(options?: SuggestRulesOptions): Promise<SuggestRulesReport>;
 declare function migrateKnip(options?: {
   cwd?: string;
   file?: string;
 }): Promise<MigrationOutput>;
-/** @experimental */
 declare function migrateDepcruise(options?: {
   cwd?: string;
   file?: string;
   node?: boolean;
 }): Promise<MigrationOutput>;
+declare function daemonStatus(options?: {
+  cwd?: string;
+}): Promise<DaemonStatusReport>;
 //#endregion
-export { AnalysisReport, type CommandResult, DebugEntrypointsOptions, DebugResolveOptions, ExplainOptions, ExplainReport, ImpactOptions, ImpactReport, MigrationOutput, Profile, PruneguardConfig, PruneguardExecutionError, ScanOptions, binaryPath, debugEntrypoints, debugResolve, explain, impact, loadConfig, migrateDepcruise, migrateKnip, run, scan, scanDot, schemaPath };
+export { AnalysisReport, type CommandResult, DaemonStatusReport, DebugEntrypointsOptions, DebugResolveOptions, ExplainOptions, ExplainReport, FixPlanOptions, FixPlanReport, ImpactOptions, ImpactReport, MigrationOutput, Profile, PruneguardConfig, PruneguardExecutionError, type ResolutionInfo, type ResolutionSource, ReviewOptions, ReviewReport, SafeDeleteOptions, SafeDeleteReport, ScanOptions, SuggestRulesOptions, SuggestRulesReport, binaryPath, daemonStatus, debugEntrypoints, debugResolve, explain, fixPlan, impact, loadConfig, migrateDepcruise, migrateKnip, resolutionInfo, review, run, safeDelete, scan, scanDot, schemaPath, suggestRules };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { n as binaryPath$1, r as run$1, t as PruneguardExecutionError } from "./runtime-BxlGT_W-.mjs";
+import { i as run$1, n as binaryPath$1, r as resolutionInfo$1, t as PruneguardExecutionError } from "./runtime-BSHQsTbN.mjs";
 import { fileURLToPath } from "node:url";
 //#region src-js/index.ts
 function parseJson(result) {
@@ -44,7 +44,6 @@ async function scan(options = {}) {
 	if (result.exitCode !== 0 && result.exitCode !== 1) requireSuccess(result);
 	return parseJson(result);
 }
-/** @experimental */
 async function scanDot(options = {}) {
 	const args = [
 		"--format",
@@ -93,6 +92,9 @@ function schemaPath() {
 function binaryPath() {
 	return binaryPath$1();
 }
+function resolutionInfo() {
+	return resolutionInfo$1();
+}
 function run(args, options) {
 	return run$1(args, options);
 }
@@ -113,7 +115,49 @@ async function debugEntrypoints(options = {}) {
 	requireSuccess(result);
 	return result.stdout.trimEnd().split("\n").filter(Boolean);
 }
-/** @experimental */
+async function review(options = {}) {
+	const args = [
+		"--format",
+		"json",
+		"--severity",
+		"info"
+	];
+	pushGlobalFlags(args, options);
+	if (options.baseRef) args.push("--changed-since", options.baseRef);
+	if (options.noCache) args.push("--no-cache");
+	if (options.noBaseline) args.push("--no-baseline");
+	args.push("review");
+	const result = await run$1(args, { cwd: options.cwd });
+	if (result.exitCode !== 0 && result.exitCode !== 1) requireSuccess(result);
+	return parseJson(result);
+}
+async function safeDelete(options) {
+	const args = ["--format", "json"];
+	pushGlobalFlags(args, options);
+	if (options.noCache) args.push("--no-cache");
+	args.push("safe-delete", ...options.targets);
+	const result = await run$1(args, { cwd: options.cwd });
+	if (result.exitCode !== 0 && result.exitCode !== 1) requireSuccess(result);
+	return parseJson(result);
+}
+async function fixPlan(options) {
+	const args = ["--format", "json"];
+	pushGlobalFlags(args, options);
+	if (options.noCache) args.push("--no-cache");
+	args.push("fix-plan", ...options.targets);
+	const result = await run$1(args, { cwd: options.cwd });
+	requireSuccess(result);
+	return parseJson(result);
+}
+async function suggestRules(options = {}) {
+	const args = ["--format", "json"];
+	pushGlobalFlags(args, options);
+	if (options.noCache) args.push("--no-cache");
+	args.push("suggest-rules");
+	const result = await run$1(args, { cwd: options.cwd });
+	requireSuccess(result);
+	return parseJson(result);
+}
 async function migrateKnip(options = {}) {
 	const args = [
 		"--format",
@@ -126,7 +170,6 @@ async function migrateKnip(options = {}) {
 	requireSuccess(result);
 	return parseJson(result);
 }
-/** @experimental */
 async function migrateDepcruise(options = {}) {
 	const args = [
 		"--format",
@@ -140,5 +183,21 @@ async function migrateDepcruise(options = {}) {
 	requireSuccess(result);
 	return parseJson(result);
 }
+async function daemonStatus(options) {
+	const result = await run$1(["daemon", "status"], { cwd: options?.cwd });
+	if (result.exitCode === 1 && result.stdout.includes("no running daemon")) return { running: false };
+	if (result.exitCode !== 0) return { running: false };
+	const lines = result.stdout.trim().split("\n");
+	const report = { running: true };
+	for (const line of lines) {
+		const [key, ...rest] = line.split(": ");
+		const value = rest.join(": ").trim();
+		if (key === "pid") report.pid = parseInt(value, 10);
+		else if (key === "port") report.port = parseInt(value, 10);
+		else if (key === "version") report.version = value;
+		else if (key === "started_at") report.startedAt = value;
+	}
+	return report;
+}
 //#endregion
-export { PruneguardExecutionError, binaryPath, debugEntrypoints, debugResolve, explain, impact, loadConfig, migrateDepcruise, migrateKnip, run, scan, scanDot, schemaPath };
+export { PruneguardExecutionError, binaryPath, daemonStatus, debugEntrypoints, debugResolve, explain, fixPlan, impact, loadConfig, migrateDepcruise, migrateKnip, resolutionInfo, review, run, safeDelete, scan, scanDot, schemaPath, suggestRules };

package/dist/{runtime-BxlGT_W-.mjs → runtime-BSHQsTbN.mjs}

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { execFileSync, spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { accessSync, constants, existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 //#region src-js/runtime.ts
 const require = createRequire(import.meta.url);
@@ -13,6 +13,7 @@ var PruneguardExecutionError = class extends Error {
 	stderr;
 	binaryPath;
 	args;
+	resolutionSource;
 	constructor(code, message, details) {
 		super(message);
 		this.name = "PruneguardExecutionError";
@@ -22,6 +23,7 @@ var PruneguardExecutionError = class extends Error {
 		this.stderr = details?.stderr;
 		this.binaryPath = details?.binaryPath;
 		this.args = details?.args;
+		this.resolutionSource = details?.resolutionSource;
 	}
 };
 const PLATFORM_PACKAGES = {
@@ -40,7 +42,10 @@ function findPlatformBinary() {
 	if (!candidates) return void 0;
 	for (const pkg of candidates) try {
 		const binPath = join(dirname(require.resolve(`${pkg}/package.json`)), "bin", exeName());
-		if (existsSync(binPath)) return binPath;
+		if (existsSync(binPath)) return {
+			path: binPath,
+			packageName: pkg
+		};
 	} catch {
 		continue;
 	}
@@ -63,38 +68,94 @@ function findPathBinary() {
 	} catch {}
 }
 let cachedBinaryPath;
+let cachedResolutionSource;
+let cachedPlatformPackage;
+function validateExecutable(binPath, source) {
+	if (!existsSync(binPath)) throw new PruneguardExecutionError("PRUNEGUARD_BINARY_NOT_FOUND", `[${source}] Binary does not exist: ${binPath}. Run "pruneguard debug runtime" for diagnostics.`, {
+		binaryPath: binPath,
+		resolutionSource: source
+	});
+	if (process.platform !== "win32") try {
+		accessSync(binPath, constants.X_OK);
+	} catch {
+		throw new PruneguardExecutionError("PRUNEGUARD_BINARY_NOT_FOUND", `[${source}] Binary exists but is not executable: ${binPath}. Try: chmod +x "${binPath}"`, {
+			binaryPath: binPath,
+			resolutionSource: source
+		});
+	}
+}
 function binaryPath(options) {
 	if (cachedBinaryPath) return cachedBinaryPath;
 	const envPath = process.env.PRUNEGUARD_BINARY;
 	if (envPath) {
-		if (!existsSync(envPath)) throw new PruneguardExecutionError("PRUNEGUARD_BINARY_NOT_FOUND", `PRUNEGUARD_BINARY points to ${envPath} but the file does not exist`, { binaryPath: envPath });
+		validateExecutable(envPath, "env");
 		cachedBinaryPath = envPath;
+		cachedResolutionSource = "env";
 		return envPath;
 	}
 	const platformBin = findPlatformBinary();
 	if (platformBin) {
-		cachedBinaryPath = platformBin;
-		return platformBin;
+		validateExecutable(platformBin.path, "platform-package");
+		cachedBinaryPath = platformBin.path;
+		cachedResolutionSource = "platform-package";
+		cachedPlatformPackage = platformBin.packageName;
+		return platformBin.path;
 	}
 	const devBin = findDevBinary();
 	if (devBin) {
+		validateExecutable(devBin, "dev");
 		cachedBinaryPath = devBin;
+		cachedResolutionSource = "dev";
 		return devBin;
 	}
 	if (options?.allowPathFallback) {
 		const pathBin = findPathBinary();
 		if (pathBin) {
+			validateExecutable(pathBin, "path");
 			cachedBinaryPath = pathBin;
+			cachedResolutionSource = "path";
 			return pathBin;
 		}
 	}
-	throw new PruneguardExecutionError("PRUNEGUARD_BINARY_NOT_FOUND", "Could not find the pruneguard binary. Install a platform-specific package or set PRUNEGUARD_BINARY.");
+	const expectedPkgs = PLATFORM_PACKAGES[`${process.platform}-${process.arch === "arm64" ? "arm64" : "x64"}`];
+	const tried = [
+		"env(PRUNEGUARD_BINARY)",
+		"platform-package",
+		"dev(cargo build)"
+	];
+	if (options?.allowPathFallback) tried.push("PATH");
+	const pkgHint = expectedPkgs?.length ? `\n  Expected platform package: ${expectedPkgs.join(" or ")}` : "";
+	throw new PruneguardExecutionError("PRUNEGUARD_BINARY_NOT_FOUND", `Could not find the pruneguard binary for ${`${process.platform}-${process.arch}`}.\n  Tried: ${tried.join(", ")}${pkgHint}\n  Fix: npm install pruneguard (or set PRUNEGUARD_BINARY)\n  Debug: npx pruneguard debug runtime`);
+}
+function resolutionInfo() {
+	return {
+		binaryPath: binaryPath(),
+		source: cachedResolutionSource,
+		...cachedPlatformPackage ? { platformPackage: cachedPlatformPackage } : {},
+		schemaPath: join(dirname(fileURLToPath(import.meta.url)), "..", "configuration_schema.json"),
+		platform: `${process.platform}-${process.arch}`
+	};
+}
+/**
+* Returns `true` if the current process is running in a CI environment.
+*
+* Checks the common `CI` env var used by GitHub Actions, GitLab CI,
+* CircleCI, Travis CI, Jenkins, and most other CI providers.
+*/
+function isCI() {
+	const ci = process.env.CI;
+	return ci !== void 0 && ci !== "" && ci !== "0" && ci.toLowerCase() !== "false";
 }
 function run(args, options) {
 	const binary = binaryPath();
 	const start = performance.now();
+	const finalArgs = args.some((arg) => arg === "--daemon" || arg.startsWith("--daemon=")) ? args : [
+		"--daemon",
+		options?.daemon ?? (isCI() ? "off" : "auto"),
+		...args
+	];
 	return new Promise((resolve, reject) => {
-		const child = spawn(binary, args, {
+		const child = spawn(binary, finalArgs, {
 			cwd: options?.cwd,
 			stdio: [
 				"ignore",
@@ -113,7 +174,8 @@ function run(args, options) {
 		child.on("error", (err) => {
 			reject(new PruneguardExecutionError("PRUNEGUARD_EXECUTION_FAILED", `Failed to spawn pruneguard: ${err.message}`, {
 				binaryPath: binary,
-				args
+				args,
+				resolutionSource: cachedResolutionSource
 			}));
 		});
 		child.on("close", (exitCode) => {
@@ -129,4 +191,4 @@ function run(args, options) {
 	});
 }
 //#endregion
-export { binaryPath as n, run as r, PruneguardExecutionError as t };
+export { run as i, binaryPath as n, resolutionInfo as r, PruneguardExecutionError as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pruneguard",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Repo truth engine for JS/TS monorepos",
   "keywords": [
     "javascript",
@@ -27,6 +27,8 @@
   "files": [
     "configuration_schema.json",
     "report_schema.json",
+    "review_report_schema.json",
+    "safe_delete_report_schema.json",
     "dist",
     "README.md",
     "bin/pruneguard"
@@ -41,14 +43,14 @@
     }
   },
   "optionalDependencies": {
-    "@pruneguard/cli-darwin-arm64": "0.2.1",
-    "@pruneguard/cli-darwin-x64": "0.2.1",
-    "@pruneguard/cli-linux-arm64-gnu": "0.2.1",
-    "@pruneguard/cli-linux-arm64-musl": "0.2.1",
-    "@pruneguard/cli-linux-x64-gnu": "0.2.1",
-    "@pruneguard/cli-linux-x64-musl": "0.2.1",
-    "@pruneguard/cli-win32-arm64-msvc": "0.2.1",
-    "@pruneguard/cli-win32-x64-msvc": "0.2.1"
+    "@pruneguard/cli-darwin-arm64": "0.3.1",
+    "@pruneguard/cli-darwin-x64": "0.3.1",
+    "@pruneguard/cli-linux-arm64-gnu": "0.3.1",
+    "@pruneguard/cli-linux-arm64-musl": "0.3.1",
+    "@pruneguard/cli-linux-x64-gnu": "0.3.1",
+    "@pruneguard/cli-linux-x64-musl": "0.3.1",
+    "@pruneguard/cli-win32-arm64-msvc": "0.3.1",
+    "@pruneguard/cli-win32-x64-msvc": "0.3.1"
   },
   "engines": {
     "node": ">=18.0.0"