@appthreat/atom-parsetools 1.3.0 → 1.5.0

package/plugins/autoload.php

@@ -19,4 +19,4 @@ if (PHP_VERSION_ID < 50600) {
 
 require_once __DIR__ . '/composer/autoload_real.php';
 
-return ComposerAutoloaderInit4ada460927b79cef097dac97641f1695::getLoader();
+return ComposerAutoloaderInitb1096a2b08d571b985540b4492c44680::getLoader();

package/plugins/composer/autoload_classmap.php

@@ -46,6 +46,7 @@ return array(
     'PhpParser\\Lexer\\TokenEmulator\\AttributeEmulator' => $vendorDir . '/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/AttributeEmulator.php',
     'PhpParser\\Lexer\\TokenEmulator\\EnumTokenEmulator' => $vendorDir . '/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/EnumTokenEmulator.php',
     'PhpParser\\Lexer\\TokenEmulator\\ExplicitOctalEmulator' => $vendorDir . '/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/ExplicitOctalEmulator.php',
+    'PhpParser\\Lexer\\TokenEmulator\\FnTokenEmulator' => $vendorDir . '/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/FnTokenEmulator.php',
     'PhpParser\\Lexer\\TokenEmulator\\KeywordEmulator' => $vendorDir . '/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/KeywordEmulator.php',
     'PhpParser\\Lexer\\TokenEmulator\\MatchTokenEmulator' => $vendorDir . '/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/MatchTokenEmulator.php',
     'PhpParser\\Lexer\\TokenEmulator\\NullsafeTokenEmulator' => $vendorDir . '/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/NullsafeTokenEmulator.php',

package/plugins/composer/autoload_real.php

@@ -2,7 +2,7 @@
 
 // autoload_real.php @generated by Composer
 
-class ComposerAutoloaderInit4ada460927b79cef097dac97641f1695
+class ComposerAutoloaderInitb1096a2b08d571b985540b4492c44680
 {
     private static $loader;
 
@@ -22,12 +22,12 @@ class ComposerAutoloaderInit4ada460927b79cef097dac97641f1695
             return self::$loader;
         }
 
-        spl_autoload_register(array('ComposerAutoloaderInit4ada460927b79cef097dac97641f1695', 'loadClassLoader'), true, true);
+        spl_autoload_register(array('ComposerAutoloaderInitb1096a2b08d571b985540b4492c44680', 'loadClassLoader'), true, true);
         self::$loader = $loader = new \Composer\Autoload\ClassLoader(\dirname(__DIR__));
-        spl_autoload_unregister(array('ComposerAutoloaderInit4ada460927b79cef097dac97641f1695', 'loadClassLoader'));
+        spl_autoload_unregister(array('ComposerAutoloaderInitb1096a2b08d571b985540b4492c44680', 'loadClassLoader'));
 
         require __DIR__ . '/autoload_static.php';
-        call_user_func(\Composer\Autoload\ComposerStaticInit4ada460927b79cef097dac97641f1695::getInitializer($loader));
+        call_user_func(\Composer\Autoload\ComposerStaticInitb1096a2b08d571b985540b4492c44680::getInitializer($loader));
 
         $loader->register(true);
 

package/plugins/composer/autoload_static.php

@@ -4,7 +4,7 @@
 
 namespace Composer\Autoload;
 
-class ComposerStaticInit4ada460927b79cef097dac97641f1695
+class ComposerStaticInitb1096a2b08d571b985540b4492c44680
 {
     public static $prefixLengthsPsr4 = array (
         'P' =>
@@ -61,6 +61,7 @@ class ComposerStaticInit4ada460927b79cef097dac97641f1695
         'PhpParser\\Lexer\\TokenEmulator\\AttributeEmulator' => __DIR__ . '/..' . '/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/AttributeEmulator.php',
         'PhpParser\\Lexer\\TokenEmulator\\EnumTokenEmulator' => __DIR__ . '/..' . '/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/EnumTokenEmulator.php',
         'PhpParser\\Lexer\\TokenEmulator\\ExplicitOctalEmulator' => __DIR__ . '/..' . '/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/ExplicitOctalEmulator.php',
+        'PhpParser\\Lexer\\TokenEmulator\\FnTokenEmulator' => __DIR__ . '/..' . '/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/FnTokenEmulator.php',
         'PhpParser\\Lexer\\TokenEmulator\\KeywordEmulator' => __DIR__ . '/..' . '/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/KeywordEmulator.php',
         'PhpParser\\Lexer\\TokenEmulator\\MatchTokenEmulator' => __DIR__ . '/..' . '/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/MatchTokenEmulator.php',
         'PhpParser\\Lexer\\TokenEmulator\\NullsafeTokenEmulator' => __DIR__ . '/..' . '/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/NullsafeTokenEmulator.php',
@@ -295,9 +296,9 @@ class ComposerStaticInit4ada460927b79cef097dac97641f1695
     public static function getInitializer(ClassLoader $loader)
     {
         return \Closure::bind(function () use ($loader) {
-            $loader->prefixLengthsPsr4 = ComposerStaticInit4ada460927b79cef097dac97641f1695::$prefixLengthsPsr4;
-            $loader->prefixDirsPsr4 = ComposerStaticInit4ada460927b79cef097dac97641f1695::$prefixDirsPsr4;
-            $loader->classMap = ComposerStaticInit4ada460927b79cef097dac97641f1695::$classMap;
+            $loader->prefixLengthsPsr4 = ComposerStaticInitb1096a2b08d571b985540b4492c44680::$prefixLengthsPsr4;
+            $loader->prefixDirsPsr4 = ComposerStaticInitb1096a2b08d571b985540b4492c44680::$prefixDirsPsr4;
+            $loader->classMap = ComposerStaticInitb1096a2b08d571b985540b4492c44680::$classMap;
 
         }, null, ClassLoader::class);
     }

package/plugins/composer/installed.json

@@ -2,21 +2,20 @@
     "packages": [
         {
             "name": "nikic/php-parser",
-            "version": "v5.7.0",
-            "version_normalized": "5.7.0.0",
+            "version": "v5.8.0",
+            "version_normalized": "5.8.0.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/nikic/PHP-Parser.git",
-                "reference": "dca41cd15c2ac9d055ad70dbfd011130757d1f82"
+                "reference": "044a6a392ff8ad0d61f14370a5fbbd0a0107152f"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/dca41cd15c2ac9d055ad70dbfd011130757d1f82",
-                "reference": "dca41cd15c2ac9d055ad70dbfd011130757d1f82",
+                "url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/044a6a392ff8ad0d61f14370a5fbbd0a0107152f",
+                "reference": "044a6a392ff8ad0d61f14370a5fbbd0a0107152f",
                 "shasum": ""
             },
             "require": {
-                "ext-ctype": "*",
                 "ext-json": "*",
                 "ext-tokenizer": "*",
                 "php": ">=7.4"
@@ -25,7 +24,7 @@
                 "ircmaxell/php-yacc": "^0.0.7",
                 "phpunit/phpunit": "^9.0"
             },
-            "time": "2025-12-06T11:56:16+00:00",
+            "time": "2026-07-04T14:30:18+00:00",
             "bin": [
                 "bin/php-parse"
             ],
@@ -57,7 +56,7 @@
             ],
             "support": {
                 "issues": "https://github.com/nikic/PHP-Parser/issues",
-                "source": "https://github.com/nikic/PHP-Parser/tree/v5.7.0"
+                "source": "https://github.com/nikic/PHP-Parser/tree/v5.8.0"
             },
             "install-path": "../nikic/php-parser"
         }

package/plugins/composer/installed.php

@@ -1,9 +1,9 @@
 <?php return array(
     'root' => array(
         'name' => '__root__',
-        'pretty_version' => 'v1.3.0',
-        'version' => '1.3.0.0',
-        'reference' => '65d96106e47fe9607cec2ba1be69da7c9c4d574c',
+        'pretty_version' => 'v1.5.0',
+        'version' => '1.5.0.0',
+        'reference' => '21c39993dc05f74643f5047de71f4bb65f0ead4a',
         'type' => 'library',
         'install_path' => __DIR__ . '/../../',
         'aliases' => array(),
@@ -11,18 +11,18 @@
     ),
     'versions' => array(
         '__root__' => array(
-            'pretty_version' => 'v1.3.0',
-            'version' => '1.3.0.0',
-            'reference' => '65d96106e47fe9607cec2ba1be69da7c9c4d574c',
+            'pretty_version' => 'v1.5.0',
+            'version' => '1.5.0.0',
+            'reference' => '21c39993dc05f74643f5047de71f4bb65f0ead4a',
             'type' => 'library',
             'install_path' => __DIR__ . '/../../',
             'aliases' => array(),
             'dev_requirement' => false,
         ),
         'nikic/php-parser' => array(
-            'pretty_version' => 'v5.7.0',
-            'version' => '5.7.0.0',
-            'reference' => 'dca41cd15c2ac9d055ad70dbfd011130757d1f82',
+            'pretty_version' => 'v5.8.0',
+            'version' => '5.8.0.0',
+            'reference' => '044a6a392ff8ad0d61f14370a5fbbd0a0107152f',
             'type' => 'library',
             'install_path' => __DIR__ . '/../nikic/php-parser',
             'aliases' => array(),

package/plugins/composer.json

@@ -1,5 +1,5 @@
 {
     "require": {
-        "nikic/php-parser": "5.7.0"
+        "nikic/php-parser": "5.8.0"
     }
 }

package/plugins/composer.lock

@@ -4,24 +4,23 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "4ada460927b79cef097dac97641f1695",
+    "content-hash": "b1096a2b08d571b985540b4492c44680",
     "packages": [
         {
             "name": "nikic/php-parser",
-            "version": "v5.7.0",
+            "version": "v5.8.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/nikic/PHP-Parser.git",
-                "reference": "dca41cd15c2ac9d055ad70dbfd011130757d1f82"
+                "reference": "044a6a392ff8ad0d61f14370a5fbbd0a0107152f"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/dca41cd15c2ac9d055ad70dbfd011130757d1f82",
-                "reference": "dca41cd15c2ac9d055ad70dbfd011130757d1f82",
+                "url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/044a6a392ff8ad0d61f14370a5fbbd0a0107152f",
+                "reference": "044a6a392ff8ad0d61f14370a5fbbd0a0107152f",
                 "shasum": ""
             },
             "require": {
-                "ext-ctype": "*",
                 "ext-json": "*",
                 "ext-tokenizer": "*",
                 "php": ">=7.4"
@@ -60,9 +59,9 @@
             ],
             "support": {
                 "issues": "https://github.com/nikic/PHP-Parser/issues",
-                "source": "https://github.com/nikic/PHP-Parser/tree/v5.7.0"
+                "source": "https://github.com/nikic/PHP-Parser/tree/v5.8.0"
             },
-            "time": "2025-12-06T11:56:16+00:00"
+            "time": "2026-07-04T14:30:18+00:00"
         }
     ],
     "packages-dev": [],

package/plugins/nikic/php-parser/composer.json

@@ -15,8 +15,7 @@
     "require": {
         "php": ">=7.4",
         "ext-tokenizer": "*",
-        "ext-json": "*",
-        "ext-ctype": "*"
+        "ext-json": "*"
     },
     "require-dev": {
         "phpunit/phpunit": "^9.0",

package/plugins/nikic/php-parser/lib/PhpParser/ConstExprEvaluator.php

@@ -215,9 +215,7 @@ class ConstExprEvaluator {
             case '<':   return $this->evaluate($l) <   $this->evaluate($r);
             case '<=':  return $this->evaluate($l) <=  $this->evaluate($r);
             case '<=>': return $this->evaluate($l) <=> $this->evaluate($r);
-            case '|>':
-                $lval = $this->evaluate($l);
-                return $this->evaluate($r)($lval);
+            case '|>':  return ($this->fallbackEvaluator)($expr);
         }
 
         throw new \Exception('Should not happen');

package/plugins/nikic/php-parser/lib/PhpParser/Lexer/Emulative.php

@@ -9,6 +9,7 @@ use PhpParser\Lexer\TokenEmulator\AsymmetricVisibilityTokenEmulator;
 use PhpParser\Lexer\TokenEmulator\AttributeEmulator;
 use PhpParser\Lexer\TokenEmulator\EnumTokenEmulator;
 use PhpParser\Lexer\TokenEmulator\ExplicitOctalEmulator;
+use PhpParser\Lexer\TokenEmulator\FnTokenEmulator;
 use PhpParser\Lexer\TokenEmulator\MatchTokenEmulator;
 use PhpParser\Lexer\TokenEmulator\NullsafeTokenEmulator;
 use PhpParser\Lexer\TokenEmulator\PipeOperatorEmulator;
@@ -40,6 +41,7 @@ class Emulative extends Lexer {
         $this->hostPhpVersion = PhpVersion::getHostVersion();
 
         $emulators = [
+            new FnTokenEmulator(),
             new MatchTokenEmulator(),
             new NullsafeTokenEmulator(),
             new AttributeEmulator(),

package/plugins/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/FnTokenEmulator.php

@@ -0,0 +1,20 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Lexer\TokenEmulator;
+
+use PhpParser\PhpVersion;
+
+// Retained for reverse emulation support only.
+final class FnTokenEmulator extends KeywordEmulator {
+    public function getPhpVersion(): PhpVersion {
+        return PhpVersion::fromString('7.4');
+    }
+
+    public function getKeywordString(): string {
+        return 'fn';
+    }
+
+    public function getKeywordToken(): int {
+        return \T_FN;
+    }
+}

package/plugins/nikic/php-parser/lib/PhpParser/Lexer/TokenEmulator/KeywordEmulator.php

@@ -14,7 +14,7 @@ abstract class KeywordEmulator extends TokenEmulator {
 
     /** @param Token[] $tokens */
     protected function isKeywordContext(array $tokens, int $pos): bool {
-        $prevToken = $this->getPreviousNonSpaceToken($tokens, $pos);
+        $prevToken = $this->getPreviousNonIgnorableToken($tokens, $pos);
         if ($prevToken === null) {
             return false;
         }
@@ -35,13 +35,14 @@ abstract class KeywordEmulator extends TokenEmulator {
     }
 
     /** @param Token[] $tokens */
-    private function getPreviousNonSpaceToken(array $tokens, int $start): ?Token {
+    private function getPreviousNonIgnorableToken(array $tokens, int $start): ?Token {
         for ($i = $start - 1; $i >= 0; --$i) {
-            if ($tokens[$i]->id === T_WHITESPACE) {
+            $token = $tokens[$i];
+            if ($token->id === T_WHITESPACE || $token->id == T_COMMENT || $token->id === T_DOC_COMMENT) {
                 continue;
             }
 
-            return $tokens[$i];
+            return $token;
         }
 
         return null;

package/plugins/nikic/php-parser/lib/PhpParser/ParserAbstract.php

@@ -1078,6 +1078,13 @@ abstract class ParserAbstract implements Parser {
                 $node->default->getAttributes()
             ));
         }
+
+        if ($node->type instanceof Identifier && $node->type->name === 'void') {
+            $this->emitError(new Error(
+                'void cannot be used as a parameter type',
+                $node->type->getAttributes()
+            ));
+        }
     }
 
     protected function checkTryCatch(TryCatch $node): void {

package/plugins/nikic/php-parser/lib/PhpParser/PrettyPrinterAbstract.php

@@ -1006,9 +1006,25 @@ abstract class PrettyPrinterAbstract implements PrettyPrinter {
 
             list($findToken, $extraLeft, $extraRight) = $this->emptyListInsertionMap[$mapKey];
             if (null !== $findToken) {
-                $insertPos = $this->origTokens->findRight($pos, $findToken) + 1;
-                $result .= $this->origTokens->getTokenCode($pos, $insertPos, $indentAdjustment);
-                $pos = $insertPos;
+                // For anon classes skip to the class keyword.
+                $isAnonClassArgs = $mapKey === PrintableNewAnonClassNode::class . '->args';
+                if ($isAnonClassArgs) {
+                    $insertPos = $this->origTokens->findRight($pos, \T_CLASS) + 1;
+                    $result .= $this->origTokens->getTokenCode($pos, $insertPos, $indentAdjustment);
+                    $pos = $insertPos;
+                }
+
+                // If "new Foo" was used without arguments, we need to convert to "new Foo()".
+                if (($mapKey === Expr\New_::class . '->args' || $isAnonClassArgs) &&
+                    !$this->origTokens->haveTokenImmediatelyAfter($pos - 1, '(')
+                ) {
+                    $extraLeft = '(';
+                    $extraRight = ')';
+                } else {
+                    $insertPos = $this->origTokens->findRight($pos, $findToken) + 1;
+                    $result .= $this->origTokens->getTokenCode($pos, $insertPos, $indentAdjustment);
+                    $pos = $insertPos;
+                }
             }
 
             $first = true;
@@ -1293,7 +1309,7 @@ abstract class PrettyPrinterAbstract implements PrettyPrinter {
         $this->labelCharMap = [];
         for ($i = 0; $i < 256; $i++) {
             $chr = chr($i);
-            $this->labelCharMap[$chr] = $i >= 0x80 || ctype_alnum($chr);
+            $this->labelCharMap[$chr] = (bool) preg_match('/^[a-zA-Z0-9_\x80-\xff]$/', $chr);
         }
 
         if ($this->phpVersion->allowsDelInIdentifiers()) {

package/plugins/rubyastgen/Gemfile

@@ -2,10 +2,12 @@
 
 source "https://rubygems.org"
 
+# Only pure-Ruby gems are vendored: rbastgen puts these on the load path directly, so the bundle
+# works under every supported Ruby ABI. prism and racc are deliberately absent — both are default
+# gems in Ruby 3.4+ and 4.0+, and their C extensions are built per ABI, which is what locked the
+# published bundle to the single Ruby version it was built with.
 group :frontend do
-    gem "ruby_ast_gen", github: 'appthreat/ruby_ast_gen', ref: 'cc312ebf06b4b5b1a8ef4c3c9c71ca98eb9fcd01'
-    gem "parser", "~> 3.3.11.1"
-    gem "prism", "~> 1.9"
+    gem "ruby_ast_gen", github: 'appthreat/ruby_ast_gen', ref: '4ac84327b3af4a8003bb9ece2566df6471cdd851'
+    gem "parser", "~> 3.3.12.0"
     gem "ostruct", "~> 0.6.3"
-    gem "racc", "~> 1.8.1"
 end

package/plugins/rubyastgen/Gemfile.lock

@@ -1,19 +1,18 @@
 GIT
   remote: https://github.com/appthreat/ruby_ast_gen.git
-  revision: cc312ebf06b4b5b1a8ef4c3c9c71ca98eb9fcd01
-  ref: cc312ebf06b4b5b1a8ef4c3c9c71ca98eb9fcd01
+  revision: 4ac84327b3af4a8003bb9ece2566df6471cdd851
+  ref: 4ac84327b3af4a8003bb9ece2566df6471cdd851
   specs:
-    ruby_ast_gen (1.3.0)
+    ruby_ast_gen (2.0.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
     ostruct (0.6.3)
-    parser (3.3.11.1)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
-    prism (1.9.0)
     racc (1.8.1)
 
 PLATFORMS
@@ -22,9 +21,7 @@ PLATFORMS
 
 DEPENDENCIES
   ostruct (~> 0.6.3)
-  parser (~> 3.3.11.1)
-  prism (~> 1.9)
-  racc (~> 1.8.1)
+  parser (~> 3.3.12.0)
   ruby_ast_gen!
 
 BUNDLED WITH

package/plugins/rubyastgen/bundle/ruby/4.0.0/bundler/gems/ruby_ast_gen-4ac84327b3af/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "ostruct", "~> 0.6.3"
+gem "parser", "~> 3.3.12.0"
+gem "prism", "~> 1.9"
+gem "rake", "~> 13.4.2"
+gem "rspec", "~> 3.13.2"

package/plugins/rubyastgen/bundle/ruby/4.0.0/bundler/gems/ruby_ast_gen-4ac84327b3af/exe/ruby_ast_gen

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# require "bundler/setup"
+# We do the below instead of the above, as the above can be flaky
+libs = File.expand_path("../vendor/bundle/ruby/*/gems/**/lib", __dir__)
+$LOAD_PATH.unshift(*Dir.glob(libs))
+
+require_relative "../lib/ruby_ast_gen"
+
+# Argument parsing and the usage text both come from RubyAstGen::CLI::FLAGS.
+result = RubyAstGen::CLI.parse(ARGV)
+options = result.options
+
+# Configure logging before emitting anything, so -l/--log applies to the argument warnings too.
+RubyAstGen::Logger.level = :debug if options[:debug]
+RubyAstGen::Logger.level = options[:log_level] if options[:log_level]
+result.warnings.each { |warning| RubyAstGen::Logger.warn warning }
+
+# Informational modes run after the whole argv is read, so `--parser-info` reflects a
+# `--parser-target` passed in any order.
+case result.mode
+when :parser_info
+  puts RubyAstGen.parser_info_text(parser_target: options[:parser_target])
+  exit
+when :version
+  puts RubyAstGen::VERSION
+  exit
+when :help
+  puts RubyAstGen::CLI.help_text
+  exit
+end
+
+# Usage errors are the only fatal cases: everything a run encounters per file is reported and
+# skipped instead, because a non-zero exit costs the caller every file (see the comment in
+# RubyAstGen::CLI.parse). --fail-on-error is the sole opt-out, for CI callers who would rather
+# fail than analyse a partial corpus; chen never passes it.
+begin
+  summary = RubyAstGen.parse(options)
+  if options[:fail_on_error] && summary[:files_failed] > 0
+    RubyAstGen::Logger.error "#{summary[:files_failed]} file(s) failed to parse; details in " \
+      "#{File.join(options[:output].to_s, RubyAstGen::DIAGNOSTICS_FILENAME)}"
+    exit 1
+  end
+rescue ArgumentError => e
+  RubyAstGen::Logger.error e.message
+  exit 1
+rescue StandardError => e
+  # Anything unexpected (an unwritable output directory, for example) still exits with a single
+  # readable line: the caller only sees our stdout, and a raw backtrace tells it nothing about
+  # which input it was invoked with. The backtrace is available with -d.
+  RubyAstGen::Logger.error "#{e.class}: #{e.message}"
+  RubyAstGen::Logger.debug e.backtrace.join("\n")
+  exit 1
+end

package/plugins/rubyastgen/bundle/ruby/4.0.0/bundler/gems/ruby_ast_gen-4ac84327b3af/lib/ruby_ast_gen/cli.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module RubyAstGen
+  # Command-line surface, kept in the library rather than in `exe/ruby_ast_gen` so it can be
+  # tested without shelling out.
+  #
+  # FLAGS is the single source of truth: it drives argument parsing *and* renders `--help`, so
+  # the two cannot drift. They used to be maintained separately, and the README documented
+  # `-l/--log` for a release in which the argv loop rejected it with a non-zero exit.
+  module CLI
+
+    Flag = Struct.new(:short, :long, :kind, :key, :placeholder, :description, keyword_init: true) do
+      def names
+        [short, long].compact
+      end
+
+      # "-i, --input <path>" / "    --parser-info"
+      def usage
+        head = short ? "#{short}, #{long}" : "    #{long}"
+        placeholder ? "#{head} #{placeholder}" : head
+      end
+    end
+
+    # Worker count for directory runs. Exposed because the ceiling is memory, not CPU: a JRuby
+    # container or a repo of very large files may need fewer (plan 03 §7).
+    DEFAULT_THREADS = 10
+
+    FLAGS = [
+      Flag.new(short: "-i", long: "--input", kind: :value, key: :input, placeholder: "<path>",
+               description: "The input file or directory (required)"),
+      Flag.new(short: "-o", long: "--output", kind: :value, key: :output, placeholder: "<dir>",
+               description: "The output directory (default: '.ast')"),
+      Flag.new(short: "-e", long: "--exclude", kind: :value, key: :exclude, placeholder: "<regex>",
+               description: "The exclusion regex (default: '^(tests?|vendor|spec)')"),
+      Flag.new(short: "-l", long: "--log", kind: :value, key: :log_level, placeholder: "<level>",
+               description: "The logging level: debug, info, warn or error (default: info)"),
+      Flag.new(short: "-d", long: "--debug", kind: :boolean, key: :debug,
+               description: "Enable debug logging (same as --log debug)"),
+      Flag.new(long: "--parser-target", kind: :value, key: :parser_target, placeholder: "<x.y>",
+               description: "Parse with a specific Ruby grammar (e.g. 3.4, 4.0) instead\nof the newest available"),
+      Flag.new(long: "--max-depth", kind: :value, key: :max_depth, placeholder: "<n>",
+               description: "Maximum AST depth before truncation " \
+                            "(default: #{NodeHandling::MAX_NESTING_DEPTH})"),
+      Flag.new(long: "--threads", kind: :value, key: :threads, placeholder: "<n>",
+               description: "Worker threads for a directory run " \
+                            "(default: #{DEFAULT_THREADS})"),
+      Flag.new(long: "--fail-on-error", kind: :boolean, key: :fail_on_error,
+               description: "Exit non-zero when any input file failed to parse"),
+      Flag.new(long: "--parser-info", kind: :mode, key: :parser_info,
+               description: "Print parser/runtime capability information"),
+      Flag.new(long: "--version", kind: :mode, key: :version,
+               description: "Print the version"),
+      Flag.new(long: "--help", kind: :mode, key: :help,
+               description: "Print usage")
+    ].freeze
+
+    BY_NAME = FLAGS.flat_map { |flag| flag.names.map { |name| [name, flag] } }.to_h.freeze
+
+    DEFAULTS = {
+      input: nil,
+      output: ".ast",
+      exclude: "^(tests?|vendor|spec)",
+      debug: false,
+      log_level: nil,
+      parser_target: nil,
+      max_depth: nil,
+      threads: nil,
+      fail_on_error: false
+    }.freeze
+
+    # Warnings are collected rather than printed so the caller can configure the log level
+    # first: `-l error` would otherwise be unable to silence them, since they are produced
+    # before the level is known.
+    Result = Struct.new(:options, :mode, :warnings, keyword_init: true)
+
+    def self.parse(argv)
+      options = DEFAULTS.dup
+      mode = :parse
+      warnings = []
+
+      index = 0
+      while index < argv.size
+        arg = argv[index]
+        flag = BY_NAME[arg]
+
+        case flag&.kind
+        when :value
+          value = argv[index + 1]
+          # Only a *known flag* counts as a missing value. Testing for a leading "-" would
+          # reject legitimate values such as an exclusion regex of "-vendor".
+          if value.nil? || BY_NAME.key?(value)
+            warnings << "Option #{arg} expects a value; got #{value.inspect}. Ignoring it."
+          else
+            options[flag.key] = value
+            index += 1
+          end
+        when :boolean
+          options[flag.key] = true
+        when :mode
+          mode = flag.key
+        else
+          # chen maps any non-zero exit to a failed command -> DefaultAstGenRunnerResult() ->
+          # zero parsed files, i.e. an empty CPG (chen consumer plan 04 §10.1). An unrecognized flag must not
+          # cost the user their whole atom, so warn and continue.
+          warnings << "Unknown option: #{arg} (ignoring)"
+        end
+
+        index += 1
+      end
+
+      Result.new(options: options, mode: mode, warnings: warnings)
+    end
+
+    DESCRIPTION_COLUMN = 25
+
+    def self.help_text
+      lines = ["Usage:"]
+      FLAGS.each do |flag|
+        usage = flag.usage
+        head, *rest = flag.description.split("\n")
+        if usage.length < DESCRIPTION_COLUMN
+          lines << "  #{usage.ljust(DESCRIPTION_COLUMN)}#{head}"
+        else
+          # No room on the flag's own line; start the description underneath it.
+          lines << "  #{usage}"
+          lines << "  #{' ' * DESCRIPTION_COLUMN}#{head}"
+        end
+        rest.each { |line| lines << "  #{' ' * DESCRIPTION_COLUMN}#{line}" }
+      end
+      lines.join("\n")
+    end
+  end
+end