Add PHPCS diagnostic proxy and update docs

Author: AJenbo

docs/ARCHITECTURE.md

@@ -1012,9 +1012,15 @@ Output uses PHPStan's table format (with progress bar and coloured output) so th
 
 ## Diagnostic Worker Architecture
 
-Diagnostics run in a background `tokio::spawn` task so they never block completion, hover, or signature help. The worker is created during `initialized` via `clone_for_diagnostic_worker`, which builds a shallow clone of the `Backend`. All `Arc`-wrapped fields (maps, caches, the notify/pending slot) are shared by `Arc::clone`, so the worker sees every mutation the main `Backend` makes.
+Diagnostics run in three independent background `tokio::spawn` tasks so they never block completion, hover, or signature help:
 
-Non-`Arc` fields are snapshotted at spawn time: `php_version`, `vendor_uri_prefixes`, `vendor_dir_paths`, and `config`. These fields are only written during `initialized` (before the worker is spawned) and never change afterwards. If a future feature adds hot-reloading of `.phpantom.toml` or runtime PHP version changes, the worker would need to be notified or re-cloned. This invariant ("init-time fields are write-once") should be verified before adding any post-init mutation to these fields.
+1. **Native diagnostic worker** — collects fast (syntax errors, unused imports, deprecated usage) and slow (unknown classes/members/functions, argument count, implementation errors) diagnostics. Debounces at 500 ms.
+2. **PHPStan worker** — runs PHPStan in editor mode (`--tmp-file` / `--instead-of`). Debounces at 2 000 ms.
+3. **PHPCS worker** — runs PHP_CodeSniffer via `phpcs --report=json` with stdin piping. Debounces at 2 000 ms.
+
+Each worker is created during `initialized` via `clone_for_diagnostic_worker`, which builds a shallow clone of the `Backend`. All `Arc`-wrapped fields (maps, caches, the notify/pending slots) are shared by `Arc::clone`, so every worker sees all mutations the main `Backend` makes. The PHPStan and PHPCS workers each have their own notify handle, pending-URI slot, and diagnostic cache so they run independently of each other and of the native diagnostic worker.
+
+Non-`Arc` fields are snapshotted at spawn time: `php_version`, `vendor_uri_prefixes`, `vendor_dir_paths`, and `config`. These fields are only written during `initialized` (before the workers are spawned) and never change afterwards. If a future feature adds hot-reloading of `.phpantom.toml` or runtime PHP version changes, the workers would need to be notified or re-cloned. This invariant ("init-time fields are write-once") should be verified before adding any post-init mutation to these fields.
 
 ## Name Resolution
 

docs/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **PHPCS diagnostic proxy.** PHP_CodeSniffer violations are surfaced as LSP diagnostics. When `squizlabs/php_codesniffer` is in `require-dev`, PHPCS is auto-detected via Composer's bin-dir; otherwise it falls back to `$PATH`. Each violation uses the sniff name as the diagnostic code (e.g. `PSR12.Files.FileHeader.MissingPHPVersion`), maps PHPCS error/warning levels to LSP severity, and marks fixable violations in diagnostic data. Runs in a dedicated background worker with the same debounce and single-pending-URI design as the PHPStan proxy. Configurable under `[phpcs]` in `.phpantom.toml` with `command`, `standard`, and `timeout` options.
 - **Linked editing ranges.** Place the cursor on a variable and all occurrences within its definition region (from one assignment to the next) enter linked editing mode. Typing a new name updates every occurrence simultaneously without affecting reassigned uses of the same variable name. Ranges exclude the leading `$` sigil so that typing before a variable (e.g. wrapping it in a function call) does not propagate to other occurrences.
 - **Invalid class-like kind diagnostics.** Flags class-like names used in positions where their kind is guaranteed to fail at runtime: `new` on abstract classes, interfaces, traits, or enums; `extends` on a final class, interface, or trait; `implements` with a non-interface; trait `use` with a non-trait; `instanceof` with a trait (always false); `catch` with a non-Throwable type or trait; and traits in native type-hint positions. Severity follows PHP semantics: unconditional fatal errors are Error, runtime-conditional failures are Warning.
 - **Nested array shape inference from multi-level key assignments.** Assignments like `$b['a']['b'] = 'x'` now produce a nested array shape type (`array{a: array{b: string}}`), enabling array key completion and hover for arrays built incrementally with nested keys. Previously only single-level key assignments were tracked.

docs/todo.md

@@ -32,7 +32,6 @@ within the same impact tier.
 | F9  | [Namespace renaming](todo/lsp-features.md#f9-namespace-renaming)                                                             | Medium      | Medium |
 | A40 | [Convert to instance variable](todo/actions.md#a40-convert-to-instance-variable)                                             | Medium      | Medium |
 | D10 | [PHPMD diagnostic proxy](todo/diagnostics.md#d10-phpmd-diagnostic-proxy)                                                     | Low         | Medium |
-| D14 | [PHPCS diagnostic proxy](todo/diagnostics.md#d14-phpcs-diagnostic-proxy)                                                     | Low         | Medium |
 | D15 | [Type error diagnostics](todo/diagnostics.md#d15-type-error-diagnostics) (argument, return, property type mismatches)        | Medium-High | High   |
 |     | **Release 0.8.0**                                                                                                            |             |        |
 

docs/todo/diagnostics.md

@@ -294,38 +294,6 @@ resolution. This eliminates the secondary resolvers entirely.
 
 ---
 
-## D14. PHPCS diagnostic proxy
-
-**Impact: Low · Effort: Medium**
-
-Proxy PHP_CodeSniffer (PHPCS) diagnostics into the editor, following
-the same pattern as the existing PHPStan proxy. PHPCS reports coding
-standard violations (PSR-12, PSR-1, custom sniffs) and is widely used
-in PHP projects for enforcing style and detecting common mistakes.
-
-### Implementation
-
-1. Add a `[phpcs]` section to the config schema in `src/config.rs`
-   with `command` (default `"vendor/bin/phpcs"`), `timeout`,
-   `standard` (default: project's `phpcs.xml` or `phpcs.xml.dist`,
-   falling back to `PSR12`), and an `enabled` flag.
-2. Run PHPCS with `--report=json` on the current file and parse the
-   JSON output into LSP diagnostics. Each violation maps to a
-   diagnostic with the sniff name as the code (e.g.
-   `PSR12.Files.FileHeader.MissingPHPVersion`).
-3. Map PHPCS severity levels (`error` / `warning`) to LSP
-   `DiagnosticSeverity::Error` and `DiagnosticSeverity::Warning`.
-4. Mark fixable violations (PHPCS reports `fixable: true` per
-   violation) so that a companion code action can run `phpcbf` to
-   auto-fix them.
-5. Respect the same debounce and queueing logic used by the PHPStan
-   proxy to avoid overwhelming the tool on rapid edits.
-6. Support `phpcs:ignore` and `phpcs:disable` / `phpcs:enable`
-   suppression comments when diagnostic suppression intelligence
-   (D5) is implemented.
-
----
-
 ## D15. Type error diagnostics
 
 **Impact: Medium-High · Effort: High**

src/config.rs

@@ -29,6 +29,8 @@ pub struct Config {
     pub formatting: FormattingConfig,
     /// PHPStan proxy settings.
     pub phpstan: PhpStanConfig,
+    /// PHPCS (PHP_CodeSniffer) proxy settings.
+    pub phpcs: PhpcsConfig,
 }
 
 /// `[php]` section — PHP version override.
@@ -175,6 +177,47 @@ impl PhpStanConfig {
     }
 }
 
+/// `[phpcs]` section — PHP_CodeSniffer proxy settings.
+///
+/// When `command` is unset (`None`), PHPantom auto-detects via
+/// `vendor/bin/phpcs` then `$PATH`.  Set to `""` (empty string)
+/// to explicitly disable PHPCS integration.
+#[derive(Debug, Clone, Default, Deserialize)]
+#[serde(default)]
+pub struct PhpcsConfig {
+    /// Command (path or name) to run PHPCS.
+    ///
+    /// - `None` (default) — auto-detect `vendor/bin/phpcs`,
+    ///   then `phpcs` on `$PATH`.
+    /// - `""` — disable PHPCS.
+    /// - Any other value — use as the command (e.g.
+    ///   `"vendor/bin/phpcs"` or `"phpcs"`).
+    pub command: Option<String>,
+    /// Coding standard to enforce (e.g. `"PSR12"`).
+    ///
+    /// When unset, PHPCS uses its own default detection
+    /// (`phpcs.xml` / `phpcs.xml.dist` in the project root,
+    /// then its built-in default).
+    pub standard: Option<String>,
+    /// Maximum runtime in milliseconds before PHPCS is killed.
+    /// Defaults to 30 000 ms (30 seconds).
+    pub timeout: Option<u64>,
+}
+
+impl PhpcsConfig {
+    /// Return the configured timeout in milliseconds, falling back to
+    /// 30 000 ms when unset.
+    pub fn timeout_ms(&self) -> u64 {
+        self.timeout.unwrap_or(30_000)
+    }
+
+    /// Whether PHPCS is explicitly disabled (command set to empty
+    /// string).
+    pub fn is_disabled(&self) -> bool {
+        self.command.as_deref() == Some("")
+    }
+}
+
 /// `[indexing]` section — controls how PHPantom discovers classes across
 /// the workspace.
 #[derive(Debug, Clone, Default, Deserialize)]
@@ -435,6 +478,10 @@ mod tests {
         assert!(config.phpstan.memory_limit.is_none());
         assert!(config.phpstan.timeout.is_none());
         assert_eq!(config.phpstan.timeout_ms(), 60_000);
+        assert!(config.phpcs.command.is_none());
+        assert!(config.phpcs.standard.is_none());
+        assert!(config.phpcs.timeout.is_none());
+        assert_eq!(config.phpcs.timeout_ms(), 30_000);
     }
 
     #[test]
@@ -448,6 +495,7 @@ mod tests {
         assert!(config.formatting.php_cs_fixer.is_none());
         assert!(config.formatting.phpcbf.is_none());
         assert!(config.phpstan.command.is_none());
+        assert!(config.phpcs.command.is_none());
     }
 
     #[test]
@@ -463,6 +511,7 @@ mod tests {
         assert!(config.formatting.php_cs_fixer.is_none());
         assert!(config.formatting.phpcbf.is_none());
         assert!(config.phpstan.command.is_none());
+        assert!(config.phpcs.command.is_none());
     }
 
     #[test]
@@ -621,6 +670,11 @@ timeout = 5000
 command = "/usr/local/bin/phpstan"
 memory-limit = "2G"
 timeout = 30000
+
+[phpcs]
+command = "/usr/local/bin/phpcs"
+standard = "PSR12"
+timeout = 15000
 "#,
         )
         .unwrap();
@@ -641,6 +695,12 @@ timeout = 30000
         );
         assert_eq!(config.phpstan.memory_limit.as_deref(), Some("2G"));
         assert_eq!(config.phpstan.timeout_ms(), 30_000);
+        assert_eq!(
+            config.phpcs.command.as_deref(),
+            Some("/usr/local/bin/phpcs")
+        );
+        assert_eq!(config.phpcs.standard.as_deref(), Some("PSR12"));
+        assert_eq!(config.phpcs.timeout_ms(), 15_000);
     }
 
     #[test]
@@ -765,6 +825,53 @@ timeout = 30000
         assert!(!config.formatting.is_disabled());
     }
 
+    #[test]
+    fn parses_phpcs_command() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(CONFIG_FILE_NAME);
+        std::fs::write(&path, "[phpcs]\ncommand = \"vendor/bin/phpcs\"\n").unwrap();
+        let config = load_config(dir.path()).unwrap();
+        assert_eq!(config.phpcs.command.as_deref(), Some("vendor/bin/phpcs"));
+    }
+
+    #[test]
+    fn parses_phpcs_standard() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(CONFIG_FILE_NAME);
+        std::fs::write(&path, "[phpcs]\nstandard = \"PSR1\"\n").unwrap();
+        let config = load_config(dir.path()).unwrap();
+        assert_eq!(config.phpcs.standard.as_deref(), Some("PSR1"));
+    }
+
+    #[test]
+    fn parses_phpcs_timeout() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(CONFIG_FILE_NAME);
+        std::fs::write(&path, "[phpcs]\ntimeout = 20000\n").unwrap();
+        let config = load_config(dir.path()).unwrap();
+        assert_eq!(config.phpcs.timeout_ms(), 20_000);
+    }
+
+    #[test]
+    fn phpcs_empty_string_disables() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(CONFIG_FILE_NAME);
+        std::fs::write(&path, "[phpcs]\ncommand = \"\"\n").unwrap();
+        let config = load_config(dir.path()).unwrap();
+        assert_eq!(config.phpcs.command.as_deref(), Some(""));
+        assert!(config.phpcs.is_disabled());
+    }
+
+    #[test]
+    fn phpcs_defaults() {
+        let config = Config::default();
+        assert!(config.phpcs.command.is_none());
+        assert!(config.phpcs.standard.is_none());
+        assert!(config.phpcs.timeout.is_none());
+        assert_eq!(config.phpcs.timeout_ms(), 30_000);
+        assert!(!config.phpcs.is_disabled());
+    }
+
     #[test]
     fn merge_toml_overlay_wins() {
         let mut base: toml::Table = toml::from_str("[php]\nversion = \"8.2\"\n").unwrap();