Check Outdated Practices

Scan ETL step files for outdated coding patterns and offer to fix them.

Source of truth

The rules live in vscode_extensions/detect-outdated-practices/src/detector.mts, the same module the VS Code extension uses for its editor warnings. Run the detector; never re-implement it with grep. Not every rule is a per-line regex: the ds["table"] subscript-read rule tracks which variables hold a Dataset across the file, so grepping the OUTDATED_PATTERNS regexes silently misses it.

node vscode_extensions/detect-outdated-practices/src/cli.mts <file-or-dir> [...]          # file:line:column: problem
node vscode_extensions/detect-outdated-practices/src/cli.mts <file-or-dir> [...] --json   # adds each rule's full fix guidance

It takes files or directories (recursing into .py files), applies each rule's path scope against the repo-relative path, and needs only Node 22.18 or later — no build step, no npm install. If it can't run (older Node), say so and stop rather than falling back to grep.

Scope

By default, check the files involved in the current task (e.g., the steps being updated). If the user provides explicit paths or asks for a broader scan, use those instead.

Accept any of:

• A step path: etl/steps/data/garden/wb/2026-03-25/poverty_projections.py
• A namespace/version/short_name: wb/2026-03-25/poverty_projections
• A glob: etl/steps/data/garden/wb/2026-03-25/*.py
• all — pass etl/steps/data snapshots (a few seconds). That includes step files of retired versions still in the repo, so filter the report to active steps (dag/*.yml) unless the user wants everything.

Fix guidance

When applying fixes, keep these notes in mind:

• paths.regions.harmonize_names(tb): country_col, countries_file, and excluded_countries_file are all inferred by default — it assumes the column is "country", uses the step's .countries.json, and (when the file exists) the step's .excluded_countries.json. So a call that passes only those three defaults collapses to paths.regions.harmonize_names(tb); only pass an argument when you're overriding the default. The fallbacks come from the Regions instance PathFinder builds (self.countries_file / self.excluded_countries_file in etl/helpers.py, defaulted inside harmonize_names) — excluded_countries_file is wired only when the .excluded_countries.json is present, so dropping it is behavior-preserving exactly when the file exists. Preserve any non-default kwargs (warn_on_unused_countries, make_missing_countries_nan, etc.).
• ds["table"] → ds.read("table"): read() resets the index by default, so ds["table"].reset_index() becomes plain ds.read("table") — keeping the trailing .reset_index() adds a spurious index column. Where the step needs the index kept (typically a grapher step passing tables straight to create_dataset), use ds.read("table", reset_index=False). Keep any safe_types=False the step already relies on for large tables. After the swap, rebuild the step and confirm the output tables keep their index and shape.
• Linting: After fixing patterns, always run make check (or let the code-quality-fixer agent handle it). In particular, don't leave extra blank lines between imports — follow the project's import style (no blank lines within import groups, one blank line between standard library and third-party groups).

Workflow

1. Identify the files to scan based on the user's scope
2. Run node vscode_extensions/detect-outdated-practices/src/cli.mts <paths> --json on them
3. Report findings as a summary table, using each finding's message for the issue:

   | File | Issue | Line |
   |------|-------|------|
   | snapshots/wb/.../file.py | <message from extension> | 29 |

4. Ask the user: "Found N outdated patterns. Fix them?"
5. If yes, apply the modern replacements described in each finding's message and show a summary of changes. Re-run the detector on the edited files to confirm they come back clean.