fix(target): explain the JavaScript directory analysis route (#733)

This commit is contained in:
N0zoM1z0
2026-10-06 19:53:08 +08:00
committed by GitHub
parent 9dd6cef90a
commit 8d44b3edd3
15 changed files with 181 additions and 16 deletions
+9 -1
View File
@@ -217,7 +217,15 @@ const resolveAppBundle = async (
const metadata = await stat(path);
if (!metadata.isDirectory()) return ok(path);
if (extname(path).toLowerCase() !== ".app")
return err(new BinaryTargetError(path, "target is not an app or file"));
return err(
new BinaryTargetError(
path,
"this opening route requires a file or macOS app bundle",
{
constraint: "directory_requires_file",
},
),
);
const plistPath = join(path, "Contents", "Info.plist");
let name: string;
try {
+22
View File
@@ -500,3 +500,25 @@ describe("doctor Linux and Hopper discovery", () => {
);
});
});
describe("doctor target admission diagnostics", () => {
it("preserves route-specific target diagnostics from the host", async () => {
const targetCheck = {
name: "target",
ok: false,
classification: "unsupported_target" as const,
detail: "/fixture/javascript-app",
remediation: "Use analyze_javascript_application with input_path.",
};
const result = await runDoctor(
targetCheck.detail,
host({
inspectTarget: () => Promise.resolve(targetCheck),
validTarget: () => {
throw new Error("the detailed target check should be used");
},
}),
);
expect(result.checks).toContainEqual(targetCheck);
});
});
+31
View File
@@ -3,6 +3,7 @@ import { access, readFile, readdir } from "node:fs/promises";
import { homedir } from "node:os";
import { delimiter, join } from "node:path";
import { analysisErrorRemediationAction } from "../domain/analysisErrorPresentation.js";
import { parseBinaryTarget } from "./BinaryTargetResolver.js";
import { execFileOutput } from "../process/ExecFileOutput.js";
import type { JsonValue } from "../domain/jsonValue.js";
@@ -40,6 +41,7 @@ export interface DoctorCheck {
| "healthy"
| "missing_dependency"
| "unsupported_host"
| "unsupported_target"
| "missing_analysis_engine"
| "config_drift";
readonly detail?: string;
@@ -79,6 +81,8 @@ export interface DoctorHost {
macosVersion(): Promise<string | undefined>;
linuxDistribution(): Promise<LinuxDistribution | undefined>;
validTarget(path: string): Promise<boolean>;
/** Route-specific target admission details, when supplied by the host. */
inspectTarget?(path: string): Promise<DoctorCheck>;
executable(path: string): Promise<boolean>;
supportedLinuxHopper(path: string): Promise<boolean>;
linuxDemoRuntimeCheck(): Promise<DoctorCheck>;
@@ -333,6 +337,33 @@ export const systemDoctorHost = (
async validTarget(path) {
return (await parseBinaryTarget(path, process.cwd(), architecture)).ok;
},
async inspectTarget(path) {
const result = await parseBinaryTarget(path, process.cwd(), architecture);
if (result.ok)
return {
name: "target",
ok: true,
classification: "healthy",
detail: path,
};
const error = result.error;
return {
name: "target",
ok: false,
classification:
error.constraint === "directory_requires_file"
? "unsupported_target"
: "config_drift",
detail: path,
details: {
reason: error.reason,
...(error.constraint === undefined
? {}
: { constraint: error.constraint }),
},
remediation: analysisErrorRemediationAction(error),
};
},
executable: (path) =>
executableAvailable(
path,
+6 -4
View File
@@ -217,10 +217,12 @@ const optionalTargetCheck = async (
): Promise<DoctorCheck | undefined> =>
target === undefined
? undefined
: check("target", await host.validTarget(target), target, {
remediation: "Supply a readable local app or program path.",
classification: "config_drift",
});
: host.inspectTarget !== undefined
? host.inspectTarget(target)
: check("target", await host.validTarget(target), target, {
remediation: "Supply a readable local app or program path.",
classification: "config_drift",
});
const check = (
name: string,
+1 -1
View File
@@ -118,7 +118,7 @@ export const PROMPT_CONTRACTS = [
{
tools: ["open_binary", "analyze_javascript_application"],
instruction:
"For a JavaScript/Electron artifact, reconstruct its application graph without execution when useful; open target_path only when the required target is not active.",
"For a JavaScript/Electron application directory, call analyze_javascript_application with input_path=target_path directly; no open_binary call is needed. For a file or macOS app bundle, open target_path only when the required target is not active.",
},
{
tools: ["list_documents", "set_current_document"],
+8 -1
View File
@@ -36,6 +36,11 @@ export const analysisErrorRemediationAction = (
: `Use the active REA session ${error.ownerRunId} or close it before opening this target again.`;
if (error instanceof HopperRemoteError)
return "Review the Hopper diagnostic details; correct the request or retry if the failure was transient.";
if (
error instanceof BinaryTargetError &&
error.constraint === "directory_requires_file"
)
return "For a JavaScript/Electron application directory, call analyze_javascript_application with input_path or run `rea analyze <directory>`. For binary analysis, select its executable file.";
if (error instanceof AnalysisInputError)
return "Correct the listed arguments and retry.";
if (error instanceof UnknownRegistryError && error.reason === "not-found")
@@ -129,7 +134,9 @@ export const analysisErrorUserMessage = (error: AnalysisError): string => {
return "REA configuration is invalid. Run `rea doctor` and fix the reported setting.";
if (error instanceof NoBinaryOpenError) return error.message;
if (error instanceof BinaryTargetError)
return "REA could not open that app or binary. Check that the path exists, is readable, and points to a supported file.";
return error.constraint === "directory_requires_file"
? "open_binary accepts files and macOS app bundles. This target is a directory; JavaScript/Electron application directories can be analyzed directly with analyze_javascript_application or `rea analyze <directory>`."
: `${error.message}. Check that the path exists, is readable, and points to a supported file.`;
if (error._tag === "ProcessCaptureError")
return (
error.userMessage ??
+8 -1
View File
@@ -334,7 +334,14 @@ const lifecycleErrorDetails = (
error.userCategory === "cancelled"
)
return { operation: "process_capture", cleanup: "complete" };
if (error instanceof BinaryTargetError) return { path: error.path };
if (error instanceof BinaryTargetError)
return {
path: error.path,
reason: error.reason,
...(error.constraint === undefined
? {}
: { constraint: error.constraint }),
};
return undefined;
};
+9 -2
View File
@@ -15,14 +15,21 @@ export class NoBinaryOpenError extends AnalysisError {
}
}
/** Additional constraints identified while admitting a filesystem target. */
export interface BinaryTargetErrorOptions extends ErrorOptions {
readonly constraint?: "directory_requires_file";
}
/** A supplied target path could not be safely opened as a supported app or binary. */
export class BinaryTargetError extends AnalysisError {
readonly _tag = "BinaryTargetError";
readonly constraint: BinaryTargetErrorOptions["constraint"];
constructor(
readonly path: string,
reason: string,
options?: ErrorOptions,
readonly reason: string,
options?: BinaryTargetErrorOptions,
) {
super(`Cannot open artifact: ${reason}`, options);
this.constraint = options?.constraint;
}
}