Method writeTagOccurrence

src/metaController.ts:633–653

* Rewrite one body-tag occurrence in place, by its parsed span. The span is * re-validated against current file content first, so an edit that raced a * change to the note refuses to write (with a Notice) rather than corrupt * unrelated text. `newValue` is the full replacement token c

(property: Partial<Property>, newValue: unknown, file: TFile)

     * unrelated text. `newValue` is the full replacement token computed by the UI.
     */
    private async writeTagOccurrence(property: Partial<Property>, newValue: unknown, file: TFile): Promise<void> {
        // The UI passes a full token (`#new`, `#a/leaf`, `#tag:value`); a bare
        // value from the API (`"done"`) is normalised to `#done`. Reject anything
        // that is not a single valid tag rather than splice invalid text into the
        // note (e.g. `#meeting notes`, which Obsidian would parse as `#meeting`).
        const newToken = normalizeTagToken(String(newValue));
        if (!isValidTagToken(newToken)) {
            throw new Error(`'${String(newValue)}' is not a valid tag name.`);
        }

        const content = await this.app.vault.read(file);
        const updated = spliceTag(content, property.position, property.key ?? "", newToken);

        if (updated === null) {
            throw new Error(
                `could not locate the tag '${property.key}' to edit - the note may have changed since it was opened. Reopen and try again.`,
            );
        }

        await this.app.vault.modify(file, updated);
    }

    private escapeSpecialCharacters(text: string): string{
        return text.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, '\\$&');