/diagnostic-dofile

name: diagnostic-dofile
description: |
  Use this skill when the user needs to inspect, audit, or diagnose the safety of a Stata do-file. Typical scenarios include: uncertainty about whether a .do file is safe; receiving a complete do-file from an unofficial source (not the Stata website, not a well-known academic institution or professor's official site); asking to check a batch of do-files; or requesting a read-only security/risk/portability diagnostic report. The skill does not modify the original file; it only emits a JSON report. Note that this is not a mandatory step for every do-file; run it only when a security review is warranted.
metadata:
  version: "0.1.0"

Diagnostic do-file

This skill inspects a Stata do-file without changing the original file and outputs a JSON diagnostic report. The underlying script reuses `stata_mcp.utils.parse_dofile` and `stata_mcp.guard.blacklist`, so it handles Stata command abbreviations, prefixes (`capture` / `quietly`), macro expansion, block comments, `#delimit ;`, and other common constructs.

When to use

Recommended situations:

• You receive a complete do-file from an unknown or unofficial source, especially one downloaded from outside the Stata website or well-known academic/professor sites.
• The code arrives as an email attachment, cloud-drive link, forum post, or chat message, and you want to verify that it contains no dangerous commands or data-overwrite risks.
• Before taking over or reproducing someone else's project, you want to audit the key do-files.
• You explicitly want a read-only diagnostic report covering security, portability, encoding, and other dimensions.

This skill is not required every time you write a do-file. For analysis code you wrote yourself, understand, and trust, you can run it directly without generating a diagnostic report each time.

How to run

uv run plugins/stata-toolbox/skills/diagnostic-dofile/diagnose_dofile.py path/to/file.do

Save the report to a file:

uv run plugins/stata-toolbox/skills/diagnostic-dofile/diagnose_dofile.py path/to/file.do -o report.json

Current checks

1. File metadata

• File path, size, and modification time.
• UTC timestamp when the report was generated.
• SHA-256 hash of the file.

2. Encoding and format

• UTF-8 or UTF-8 with BOM.
• Non-UTF-8 encodings such as GBK/GB2312.
• Line ending: LF, CRLF, or mixed.
• Empty file or comment-only file.

3. Dangerous commands

Based on `src/stata_mcp/guard/blacklist.py`:

• Shell / system commands: `!`, `!!`, `shell`, `xshell`, `winexec`, `unixcmd`.
• File deletion: `erase`, `rm`, `rmdir`.
• External code execution: `do`, `run`, `include`.
• Embedded runtimes: `python`, `mata`, `java`, `plugin`.
• Package-management commands: `ssc`, `net`, `github`, `adoupdate`, `update`.
• Working-directory changes: `cd`, `chdir`.

4. Data-overwrite risks

• `use xxx.dta` followed by `save xxx.dta, replace` pointing to the same file.
• Memory-clearing operations such as `clear all` / `drop _all`.

5. Output-file overwrite

• `graph export xxx, replace`.
• `export xxx, replace`.
• Commands with `replace` such as `outreg2`, `esttab`, `estout`, `putexcel`, `putdocx`, `putpdf`, `logout`, `texdoc`.
• `log using xxx.log, replace`.
• `saveold xxx, replace`.

6. External commands / user-written packages

• Recognizes common external commands such as `reghdfe`, `estout`, `outreg2`, `esttab`, `coefplot`, `ivreg2`, `rdrobust`.
• Reports them so the caller can run Stata `help <command>` to verify installation.

7. Paths and portability

• Absolute paths such as `/Users/...` or `C:\...`.
• `webuse` or network URLs for loading data.
• `cd` / `chdir` working-directory changes.

8. Macro and parsing risks

• Unresolved macro variables (global macros, local macro expressions, etc.).
• Unclosed block comments, quotes, or program blocks that may affect parsing reliability.

Report format

The report is a JSON object with the following structure:

{
  "schema_version": "0.1.0",
  "generated_at": "2026-09-22T12:34:56.789012Z",
  "file": {
    "path": "/project/analysis.do",
    "size_bytes": 1234,
    "sha256": "abc123...",
    "encoding": "utf-8",
    "has_bom": false,
    "line_ending": "lf"
  },
  "summary": {
    "total_lines": 100,
    "code_lines": 60,
    "comment_lines": 30,
    "blank_lines": 10,
    "error_count": 2,
    "warning_count": 5,
    "info_count": 3
  },
  "findings": [
    {
      "level": "error",
      "line": 12,
      "category": "dangerous_command",
      "message": "Detected dangerous command 'shell'"
    }
  ]
}

Notes

• The script only reads the original file and never modifies the do-file content.
• Findings are for reference only; the final execution decision is yours.
• For Stata-MCP, dangerous commands are automatically blocked by the security guard during `stata_do`. To disable the guard, configure `~/.statamcp/config.toml`, but this is not recommended.