docblock-rewrite

Converts PHPDoc and JSDoc blocks into one-line plain-English // comments that a non-technical reader can understand. Two engines under shared rules: interactive skill mode (Read/Edit walk, 1-20 files) and a bundled bash + perl + claude --print runner (20+ files, unattended, CI-able) exposed as /docblock-rewrite. Walks .php, .js, .ts, .jsx, .tsx, .mjs, .cjs. Skip list covers vendor, node_modules, dist, build, coverage, __tests__, .git, .next, .nuxt, out, tmp, *.min.js, *.min.css. Honors @internal, @deprecated, @ignore opt-out tags. File-level detection via @file/@package/@module or post-block declare/namespace/use/import/export. Banned-word list: instantiate, invoke, callback, promise, iterate, async, boolean, array, object, parameter, argument, mutate, hash, payload, instance, factory, singleton, polyfill, regex. Output format: one line beginning with // and ending with a period, capitalized, present-tense verb for functions/methods, noun phrase for classes/files/properties/constants, max 100 chars total. Validation gates: one-line check, // prefix, length cap, banned-word regex. Bad outputs leave the original block intact for human review. Backups saved as .bak per file unless --no-backup. Dry-run mode emits unified diffs without writing. Concurrency configurable (default 3). Right-to-left byte-offset splice preserves alignment across multi-block files.