Migrating from t-esc to t-out in OWL 3.0:
A Senior Architect's Field Guide for Odoo 19

<!-- Dangerous: developer chose t-raw for "formatting" -->
<span t-raw="record.user_description"/>

<!-- The user_description field contains user-supplied input -->
<!-- Result: XSS vulnerability -->

<!-- Safe: t-out auto-escapes strings -->
<span t-out="record.user_description"/>

<!-- If you genuinely need raw HTML (e.g., a sanitized rich-text field): -->
// In your JS component:
import { markup } from "@odoo/owl";
get safeDescription() {
    return markup(this.record.user_description);
}

#!/usr/bin/env python3
"""
migrate_tesc_to_tout.py
Replaces t-esc with t-out across all XML/QWeb templates in an Odoo module tree.
Generates a CSV audit log for code review.

Usage:
    python migrate_tesc_to_tout.py /path/to/custom_addons [--dry-run]
"""
import argparse
import csv
import os
import re
import sys
from datetime import datetime
from pathlib import Path

# Matches t-esc="..." (handles single and double quotes)
T_ESC_PATTERN = re.compile(
    r'\bt-esc\s*=\s*(["\'])(.*?)\1',
    re.DOTALL,
)

# Also catch any lingering t-raw (deprecated since Odoo 16)
T_RAW_PATTERN = re.compile(
    r'\bt-raw\s*=\s*(["\'])(.*?)\1',
    re.DOTALL,
)

EXTENSIONS = {'.xml', '.qweb'}


def find_template_files(root: Path):
    """Yield all XML/QWeb files under the given root."""
    for dirpath, _, filenames in os.walk(root):
        for fname in filenames:
            fpath = Path(dirpath) / fname
            if fpath.suffix.lower() in EXTENSIONS:
                yield fpath


def migrate_file(fpath: Path, dry_run: bool = False):
    """Replace t-esc and t-raw in a single file. Returns list of changes."""
    content = fpath.read_text(encoding='utf-8')
    changes = []

    def replace_tesc(match):
        quote = match.group(1)
        expr = match.group(2)
        changes.append({
            'file': str(fpath),
            'old': match.group(0),
            'new': f't-out={quote}{expr}{quote}',
            'type': 't-esc → t-out',
            'line': content[:match.start()].count('\n') + 1,
        })
        return f't-out={quote}{expr}{quote}'

    def replace_traw(match):
        quote = match.group(1)
        expr = match.group(2)
        changes.append({
            'file': str(fpath),
            'old': match.group(0),
            'new': f't-out={quote}{expr}{quote}',
            'type': 't-raw → t-out (⚠ REVIEW: needs markup())',
            'line': content[:match.start()].count('\n') + 1,
        })
        return f't-out={quote}{expr}{quote}'

    new_content = T_ESC_PATTERN.sub(replace_tesc, content)
    new_content = T_RAW_PATTERN.sub(replace_traw, new_content)

    if changes and not dry_run:
        fpath.write_text(new_content, encoding='utf-8')

    return changes


def main():
    parser = argparse.ArgumentParser(
        description='Migrate t-esc/t-raw → t-out for Odoo 19 / OWL 3.0'
    )
    parser.add_argument('root', help='Root directory of custom addons')
    parser.add_argument(
        '--dry-run',
        action='store_true',
        help='Preview changes without writing files',
    )
    args = parser.parse_args()

    root = Path(args.root).resolve()
    if not root.is_dir():
        print(f"Error: {root} is not a directory", file=sys.stderr)
        sys.exit(1)

    all_changes = []
    file_count = 0

    for fpath in find_template_files(root):
        changes = migrate_file(fpath, dry_run=args.dry_run)
        if changes:
            file_count += 1
            all_changes.extend(changes)

    # Generate CSV audit log
    timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
    log_file = root / f'tesc_migration_log_{timestamp}.csv'
    with open(log_file, 'w', newline='', encoding='utf-8') as f:
        writer = csv.DictWriter(
            f, fieldnames=['file', 'line', 'type', 'old', 'new']
        )
        writer.writeheader()
        writer.writerows(all_changes)

    mode = "DRY RUN" if args.dry_run else "APPLIED"
    print(f"\n[{mode}] Migration complete.")
    print(f"  Files affected : {file_count}")
    print(f"  Total changes  : {len(all_changes)}")
    t_raw_hits = sum(
        1 for c in all_changes if 't-raw' in c['type']
    )
    if t_raw_hits:
        print(
            f"  ⚠ t-raw → t-out : {t_raw_hits} "
            f"(MANUAL REVIEW: add markup() in JS)"
        )
    print(f"  Audit log      : {log_file}")


if __name__ == '__main__':
    main()

# Bash: find remaining t-esc in JS template literals and XML
grep -rn --include="*.js" --include="*.xml" \
  't-esc=' ./custom_addons/ | grep -v node_modules