diff --git a/docs/guides/native/windows-shortcut.md b/docs/guides/native/windows-shortcut.md index feadfa18a1..0343b62576 100644 --- a/docs/guides/native/windows-shortcut.md +++ b/docs/guides/native/windows-shortcut.md @@ -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. diff --git a/src/native/windows/WindowsShortcutParser.test.ts b/src/native/windows/WindowsShortcutParser.test.ts index 971a1349b7..360ac0d72b 100644 --- a/src/native/windows/WindowsShortcutParser.test.ts +++ b/src/native/windows/WindowsShortcutParser.test.ts @@ -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: ".ア", + }); +}); diff --git a/src/native/windows/WindowsShortcutParser.ts b/src/native/windows/WindowsShortcutParser.ts index bb75971fb0..c8647f0e11 100644 --- a/src/native/windows/WindowsShortcutParser.ts +++ b/src/native/windows/WindowsShortcutParser.ts @@ -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): 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", diff --git a/tests/acceptance/windowsShortcutCli.test.ts b/tests/acceptance/windowsShortcutCli.test.ts index 710a330680..9f9eeea29e 100644 --- a/tests/acceptance/windowsShortcutCli.test.ts +++ b/tests/acceptance/windowsShortcutCli.test.ts @@ -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 }) => {