fix(windows): preserve opaque ANSI shortcut path identity (#11923)

Co-authored-by: ShuaixinHuang <197200901+ShuaixinHuang@users.noreply.github.com>
This commit is contained in:
ShuaixinHuangandShuaixinHuang authored and GitHub committed 2026-11-18 14:56:47 -05:00
1 parent 18c6b4490c
commit e39a53d5cd
4 files changed
+300 -31

No files matched your search

+12
View File
@@ -68,6 +68,18 @@ bytes is therefore not compared with a Unicode icon location, or the reverse,
because the code page is unobserved. This workflow does not emit verdicts
about intent.
Two ANSI paths can also remain incomparable. Multibyte trail bytes can look
like ASCII letters or backslashes, so the Latin1 projection cannot safely
undergo Unicode case folding or path normalization. Exact stored byte spellings
can establish equality; a byte-identical prefix followed by ASCII filename
tails can still establish equality or difference. Other opaque ANSI comparisons
remain unknown. LinkInfo joins involving non-ASCII ANSI parts retain an unknown
full-path identity; a known suffix extension can still be reported. Non-ASCII
ANSI extension text stays unknown rather than becoming a guessed Unicode
extension. Raw fields and artifact identity are preserved. The code page in a
ConsoleFE block describes the console and does not establish the original
system ANSI encoding for these paths.
A missing optional section is observed absence of that structure. It is not
proof the shortcut never carried that data in another container.
@@ -960,3 +960,164 @@ it("charges the string budget before decoding a LinkInfo string", async () => {
),
).rejects.toBeInstanceOf(WindowsShortcutResourceFailure);
});
it.each(
(["link-info", "environment"] as const).flatMap((origin) =>
[
{
label: "DBCS trail case",
target: "C:\\Tools\\\x83A.exe",
icon: "C:\\Tools\\\x83a.exe",
targetUnicode: "C:\\Tools\\ア.exe",
iconUnicode: "C:\\Tools\\ヂ.exe",
unicodeDiffers: true,
},
{
label: "fullwidth case",
target: "C:\\Tools\\\x82\x60.exe",
icon: "C:\\Tools\\\x82\x81.exe",
targetUnicode: "C:\\Tools\\A.exe",
iconUnicode: "C:\\Tools\\a.exe",
unicodeDiffers: false,
},
{
label: "DBCS trail separator",
target: "C:\\Tools\\\x83\\..\\app.exe",
icon: "C:\\Tools\\app.exe",
targetUnicode: "C:\\Tools\\ソ..\\app.exe",
iconUnicode: "C:\\Tools\\app.exe",
unicodeDiffers: true,
},
].map((test) => ({ origin, ...test })),
),
)(
"keeps $origin $label unknown without a system code page",
async ({
origin,
target,
icon,
targetUnicode,
iconUnicode,
unicodeDiffers,
}) => {
const options = (path: string, iconLocation: string, unicode: boolean) => ({
unicode,
flags:
LINK_FLAG.HasIconLocation |
(unicode ? LINK_FLAG.IsUnicode : 0) |
(origin === "link-info"
? LINK_FLAG.HasLinkInfo
: LINK_FLAG.HasExpString),
idList: null,
relativePath: "",
linkInfo:
origin === "link-info" ? { localBasePath: path, unicode } : null,
extraData:
origin === "environment"
? [
{
kind: "environment" as const,
ansi: path,
unicode: unicode ? path : "",
},
]
: [],
iconLocation,
});
const opaque = await parse(
windowsShortcutBytes(options(target, icon, false)),
);
expect(iconDifference(opaque)).toBeNull();
expect(opaque.string_data.icon_location?.value).toBe(icon);
expect(opaque.observations).toContainEqual({
kind: "target_extension",
evidence_kind: "derived",
extension: ".exe",
});
// Equal byte spellings remain equal without choosing any code page.
expect(
iconDifference(
await parse(windowsShortcutBytes(options(target, target, false))),
),
).toBe(false);
// The same names supplied as UTF-16 have known, comparable characters.
expect(
iconDifference(
await parse(
windowsShortcutBytes(options(targetUnicode, iconUnicode, true)),
),
),
).toBe(unicodeDiffers);
},
);
it("does not reinterpret an ANSI trail backslash while joining LinkInfo parts", async () => {
const base = "C:\\Tools\\\x83\\";
const report = await parse(
windowsShortcutBytes({
unicode: false,
idList: null,
relativePath: "",
linkInfo: { localBasePath: base, commonPathSuffix: "app.exe" },
extraData: [],
iconLocation: base + "app.exe",
}),
);
expect(report.link_info?.local_base_path).toBe(base);
expect(report.link_info?.common_path_suffix).toBe("app.exe");
expect(iconDifference(report)).toBeNull();
expect(report.observations).toContainEqual({
kind: "target_extension",
evidence_kind: "derived",
extension: ".exe",
});
for (const [knownTarget, expected] of [
["C:\\Known\\other.exe", null],
["C:\\Known\\icon.exe", false],
] as const) {
const mixed = await parse(
windowsShortcutBytes({
unicode: false,
idList: null,
relativePath: "",
linkInfo: { localBasePath: base, commonPathSuffix: "app.exe" },
extraData: [{ kind: "environment", unicode: knownTarget }],
iconLocation: "C:\\Known\\icon.exe",
}),
);
expect(iconDifference(mixed)).toBe(expected);
}
});
it("leaves non-ASCII ANSI extensions uninterpreted", async () => {
const path = "C:\\Tools\\report.\x83A";
const report = await parse(
windowsShortcutBytes({
unicode: false,
idList: null,
relativePath: "",
linkInfo: { localBasePath: path },
extraData: [],
iconLocation: path,
}),
);
expect(report.observations).toContainEqual({
kind: "target_extension",
evidence_kind: "derived",
extension: null,
});
expect(report.link_info?.local_base_path).toBe(path);
expect(iconDifference(report)).toBe(false);
const known = await parse(
windowsShortcutBytes({
linkInfo: { localBasePath: "C:\\Tools\\report.ア" },
extraData: [],
iconLocation: "C:\\Tools\\report.ア",
}),
);
expect(known.observations).toContainEqual({
kind: "target_extension",
evidence_kind: "derived",
extension: ".ア",
});
});
+73 -30
View File
@@ -245,14 +245,15 @@ const driveType = (
name: DRIVE_TYPES[raw] ?? null,
});
const extensionOf = (path: string | null | undefined): string | null => {
if (path === undefined || path === null || path.length === 0) return null;
const extensionOf = (path: string, ansi: boolean): string | null => {
if (path.length === 0) return null;
const normalized = path.replaceAll("/", "\\");
const slash = normalized.lastIndexOf("\\");
const name = slash === -1 ? normalized : normalized.slice(slash + 1);
const dot = name.lastIndexOf(".");
if (dot <= 0 || dot === name.length - 1) return null;
return name.slice(dot).toLowerCase();
const extension = name.slice(dot);
return ansi && !isAscii(extension) ? null : extension.toLowerCase();
};
const foldPath = (path: string): string =>
@@ -297,31 +298,67 @@ const hasUnexpandedVariable = (path: string): boolean =>
/%[^%\\/]+%/u.test(path);
/**
* A recorded path and where its non-ASCII text came from. Every ANSI code page
* agrees with ASCII, so only non-ASCII characters depend on the encoding. A
* non-ASCII ANSI byte is a character from the unobserved system code page,
* which its Latin1 projection does not name.
* A recorded path and where its text came from. All-ASCII strings agree across
* ANSI code pages, but an ASCII-valued trail byte in a multibyte string need not
* name an ASCII character. A Latin1 projection preserves bytes, not decoded
* character boundaries or case relationships.
*/
type RecordedPath = {
readonly path: string;
/** Null when independently encoded parts cannot establish a joined path. */
readonly path: string | null;
/** Holds non-ASCII text projected from ANSI bytes. */
readonly ansi: boolean;
/** Holds non-ASCII UTF-16 text. */
readonly unicode: boolean;
/** A suffix may establish this even when its parent's identity is unknown. */
readonly extension: string | null;
};
const isAscii = (text: string): boolean =>
[...text].every((char) => char <= "\u007f");
const recorded = (path: string, ansi: boolean): RecordedPath => {
const recorded = (path: string, ansi: boolean) => {
const nonAscii = !isAscii(path);
return { path, ansi: ansi && nonAscii, unicode: !ansi && nonAscii };
return {
path,
ansi: ansi && nonAscii,
unicode: !ansi && nonAscii,
extension: extensionOf(path, ansi),
};
};
/** Two paths compare as text only when their non-ASCII parts share one encoding. */
const comparableText = (left: RecordedPath, right: RecordedPath): boolean =>
!((left.ansi || right.ansi) && (left.unicode || right.unicode));
/** Opaque ANSI bytes are not Unicode characters or path separators. */
const pathsDiffer = (
left: RecordedPath,
right: RecordedPath,
): boolean | null => {
if (left.path === null || right.path === null || !comparableText(left, right))
return null;
if (!left.ansi && !right.ansi)
return normalizePath(left.path) !== normalizePath(right.path);
if (left.path === right.path) return false;
// The identical prefix can end in a separator or a DBCS trail byte: either
// way, only the following ASCII tails are compared. The prefix stays opaque.
const asciiTail = (path: string) => {
const at = Math.max(path.lastIndexOf("\\"), path.lastIndexOf("/")) + 1;
const name = path.slice(at);
return name !== "" && name !== "." && name !== ".." && isAscii(name)
? { prefix: path.slice(0, at), name }
: null;
};
const leftFile = asciiTail(left.path);
const rightFile = asciiTail(right.path);
return leftFile !== null &&
rightFile !== null &&
leftFile.prefix === rightFile.prefix
? leftFile.name.toLowerCase() !== rightFile.name.toLowerCase()
: null;
};
const iconDiffersFromTarget = (
icon: WindowsShortcut["string_data"]["icon_location"],
targets: readonly RecordedPath[],
@@ -330,18 +367,16 @@ const iconDiffersFromTarget = (
const text = icon.value;
if (!isFullPath(text) || hasUnexpandedVariable(text)) return null;
const iconPath = recorded(text, icon.encoding === "ansi");
const location = normalizePath(text);
const fullTargets = targets.filter((target) => isFullPath(target.path));
const fixedTargets = fullTargets.filter(
(target) =>
!hasUnexpandedVariable(target.path) && comparableText(target, iconPath),
const fullTargets = targets.filter(
(target) => target.path === null || isFullPath(target.path),
);
if (fixedTargets.some((target) => normalizePath(target.path) === location))
return false;
// A variable-bearing target, or one whose ANSI bytes the icon text cannot be
// compared with, could name the icon's file, so no difference is claimed.
if (fullTargets.length > fixedTargets.length) return null;
return fixedTargets.length === 0 ? null : true;
const differences = fullTargets.map((target) =>
target.path !== null && hasUnexpandedVariable(target.path)
? null
: pathsDiffer(target, iconPath),
);
if (differences.includes(false)) return false;
return differences.length === 0 || differences.includes(null) ? null : true;
};
/** LinkInfo local and network base paths, each joined with CommonPathSuffix. */
@@ -355,14 +390,22 @@ const linkInfoTargets = (
: recorded(suffixText, info.common_path_suffix_unicode === null);
// Each part keeps its own encoding, so an ASCII ANSI part never hides a
// comparable Unicode part.
const withSuffix = (base: RecordedPath): RecordedPath =>
suffix === null
? base
: {
path: `${base.path.replace(/\\$/u, "")}\\${suffix.path.replace(/^\\/u, "")}`,
ansi: base.ansi || suffix.ansi,
unicode: base.unicode || suffix.unicode,
};
const withSuffix = (base: ReturnType<typeof recorded>): RecordedPath => {
if (suffix === null) return base;
if (base.ansi || suffix.ansi)
return {
path: null,
ansi: base.ansi || suffix.ansi,
unicode: base.unicode || suffix.unicode,
extension: suffix.extension,
};
return {
path: `${base.path.replace(/\\$/u, "")}\\${suffix.path.replace(/^\\/u, "")}`,
ansi: base.ansi || suffix.ansi,
unicode: base.unicode || suffix.unicode,
extension: suffix.extension,
};
};
const values: RecordedPath[] = [];
const local = info.local_base_path_unicode ?? info.local_base_path;
if (local !== null && (suffix !== null || local.length > 0))
@@ -441,7 +484,7 @@ const observationsOf = (
{
kind: "target_extension",
evidence_kind: "derived",
extension: extensionOf(targets[0]?.path ?? null),
extension: targets[0]?.extension ?? null,
},
{
kind: "show_command_minimized",
+54 -1
View File
@@ -1,4 +1,5 @@
import { writeFile } from "node:fs/promises";
import { readFile, writeFile } from "node:fs/promises";
import { createHash } from "node:crypto";
import { join } from "node:path";
import { expect } from "vitest";
import { BINARY_DIAGNOSTICS_TOOL_CONTRACTS } from "../../src/contracts/native/binaryDiagnosticsToolContracts.js";
@@ -22,6 +23,58 @@ const shortcutContract = (() => {
return contract;
})();
cliTest.for([
{ target: "C:\\Tools\\\x83A.exe", icon: "C:\\Tools\\\x83a.exe" },
{ target: "C:\\Tools\\\x82\x60.exe", icon: "C:\\Tools\\\x82\x81.exe" },
])(
"preserves opaque ANSI path facts through compiled CLI and stdio MCP: $target",
async ({ target, icon }, { cli }) => {
const root = await createTestTempDirectory("rea-shortcut-ansi-cli-");
const path = join(root, "shortcut.lnk");
const bytes = windowsShortcutBytes({
unicode: false,
idList: null,
relativePath: "",
linkInfo: { localBasePath: target },
extraData: [],
iconLocation: icon,
});
await writeFile(path, bytes);
const result = await cli.run({
arguments: ["inspect-windows-shortcut", path, "--json"],
});
expect(result.exitCode, result.stderr).toBe(0);
const call = await cli.sharedMcpCall!();
const response = await call("inspect_windows_shortcut", { path });
expect(response.isError, JSON.stringify(response)).not.toBe(true);
for (const value of [result.json, response.structuredContent]) {
const evidence = shortcutContract.outputSchema.parse(value);
const report = evidence.normalized_result;
expect(report.artifact.sha256).toBe(
createHash("sha256").update(bytes).digest("hex"),
);
expect(report.link_info?.local_base_path).toBe(target);
expect(report.string_data.icon_location?.value).toBe(icon);
expect(report.coverage.status).toBe("complete");
expect(report.observations).toEqual(
expect.arrayContaining([
{
kind: "icon_location_differs_from_target",
evidence_kind: "derived",
value: null,
},
{
kind: "target_extension",
evidence_kind: "derived",
extension: ".exe",
},
]),
);
}
expect((await readFile(path)).equals(bytes)).toBe(true);
},
);
cliTest(
"preserves pre-epoch shortcut timestamps through CLI and stdio MCP",
async ({ cli }) => {