Function parseFileToken

src/utils/fileSyntax.ts:129–215

(raw: string)

 * Returns `null` for an empty folder (the token is left literal by the caller).
 */
export function parseFileToken(raw: string): ParsedFileToken | null {
	if (!raw) return null;

	const allParts = splitPipeParts(raw);
	const folderPath = (allParts.shift() ?? "").trim();
	if (!folderPath) return null;

	// Peel bare flags first.
	let remaining = allParts;
	const optionalResult = extractBareFlagPart(remaining, "optional");
	remaining = optionalResult.remaining;
	const optional = optionalResult.found;

	const customResult = extractBareFlagPart(remaining, "custom");
	remaining = customResult.remaining;
	const allowCustomInput = customResult.found;

	const multiResult = extractBareFlagPart(remaining, "multi");
	remaining = multiResult.remaining;
	const bareMultiSelect = multiResult.found;

	let mode: FileMode = "name";
	const afterMode: string[] = [];
	for (const part of remaining) {
		const trimmed = part.trim().toLowerCase();
		if (MODE_FLAGS.has(trimmed as FileMode)) {
			mode = trimmed as FileMode; // last one wins
			continue;
		}
		afterMode.push(part);
	}

	// Peel key:value options that are FILE-specific (label/name); everything else
	// (tag/exclude-*) is parsed by FieldSuggestionParser below.
	let label: string | undefined;
	let aliasName: string | undefined;
	for (const part of afterMode) {
		const parsed = parsePipeKeyValue(part);
		if (!parsed) continue;
		if (parsed.key === "label" && parsed.value) label = parsed.value;
		else if (parsed.key === "name" && parsed.value) aliasName = parsed.value;
	}

	// Delegate filter parsing to the shared FIELD parser (it skips unknown keys
	// like label/name and bare flags), then force the scope folder. The first
	// segment is the folder, so any `|folder:` sub-option the parser picks up is
	// intentionally discarded below (the positional folder always wins).
	const fieldParsed = FieldSuggestionParser.parse(raw);
	const multiSelect = bareMultiSelect || (fieldParsed.multiSelect ?? false);
	const filter: FieldFilter = {
		folder: folderPath,
		tags: fieldParsed.filters.tags,
		excludeFolders: fieldParsed.filters.excludeFolders,
		excludeTags: fieldParsed.filters.excludeTags,
		excludeFiles: fieldParsed.filters.excludeFiles,
	};

	// Sharing (`|name:`) is scoped to the picker's SCOPE (folder + filters): a pick