• Home
  • Features
  • Pricing
  • Docs
  • Announcements
  • Sign In

dg / dresscode / 41101973300

19 Oct 2026 01:51PM UTC coverage: 97.759% (+0.5%) from 97.234%
41101973300

push

github

dg
released version 1.3.1

23162 of 23693 relevant lines covered (97.76%)

0.98 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

92.62
/src/Config/UpgradingFile.php
1
<?php declare(strict_types=1);
2

3
/**
4
 * This file is part of the DressCode, a coding style and upgrade tool for PHP (https://dresscode.run)
5
 * Copyright (c) 2026 David Grudl (https://davidgrudl.com)
6
 */
7

8
namespace DressCode\Config;
9

10
use DressCode\{ConfigurationException, Profile};
11
use DressCode\Domains\Map;
12
use DressCode\Upgrading\{FunctionPattern, MemberMapGrammar, MemberPattern};
13
use Nette\Neon\{Exception as NeonException, Neon};
14
use function array_key_exists, is_array, is_string;
15

16

17
/**
18
 * An upgrading file as it is written: the package whose versions its sections are of, what the namespaces of the
19
 * package declare, and the maps every section brings with the requirements of the rules of the plugin of the package it
20
 * turns on, which `selectFor()` lays out for the versions of the package the code must work with.
21
 * @internal
22
 */
23
final readonly class UpgradingFile
24
{
25
        /** the maps of what the code must not have, by which what a version above the lowest one retires is reported */
26
        private const ForbiddenMaps = ['forbiddenClasses', 'forbiddenFunctions', 'forbiddenConstants', 'forbiddenMembers'];
27

28
        private const SectionPattern = '~^since (\d+(?:\.\d+)*)$~D';
29
        private const PackagePattern = '~^(?:php|[a-z0-9_.-]+/[a-z0-9_.-]+)$~D';
30
        private const VersionPattern = '~^\d+(?:\.\d+)*$~D';
31

32

33
        private function __construct(
34
                /** the package the sections are versions of, `php` for PHP itself */
35
                public string $package,
1 ✔
36
                /** @var array{functions: list<string>, constants: list<string>}  what the package declares in its namespaces, fully qualified */
37
                public array $namespaces,
1 ✔
38
                /** @var array<string, array<string, array<string, mixed>>>  version => map => its entries, the oldest first */
39
                private array $sections,
1 ✔
40
                /** @var array<string, array<string, string>>  version => a requirement of the plugin of the package => its value */
41
                private array $requirements = [],
1 ✔
42
        ) {
43
        }
1 ✔
44

45

46
        /**
47
         * Reads the file, a value as NEON gives it, an entity too, for the grammar of the map to read.
48
         * @throws ConfigurationException
49
         */
50
        public static function fromFile(string $file, string $label): self
51
        {
52
                if (!is_file($file)) {
1 ✔
53
                        throw new ConfigurationException("Upgrading file $label does not exist.");
×
54
                }
55

56
                try {
57
                        $data = Neon::decodeFile($file);
1 ✔
58
                } catch (NeonException $e) {
1 ✔
59
                        throw new ConfigurationException("Upgrading file $label is not valid NEON: {$e->getMessage()}", previous: $e);
1 ✔
60
                }
61

62
                $package = is_array($data) ? $data['package'] ?? null : null;
1 ✔
63
                if (!is_string($package) || !preg_match(self::PackagePattern, $package)) {
1 ✔
64
                        throw new ConfigurationException("Upgrading file $label: The key `package` must name the package the sections are versions of, as `vendor/name`, or `php`.");
1 ✔
65
                }
66

67
                $sections = $requirements = [];
1 ✔
68
                foreach ($data as $key => $section) {
1 ✔
69
                        if ($key === 'package' || $key === 'namespaces') {
1 ✔
70
                                continue;
1 ✔
71
                        } elseif (!is_string($key) || !preg_match(self::SectionPattern, $key, $m)) {
1 ✔
72
                                throw new ConfigurationException("Upgrading file $label: Unexpected key `$key`; the file holds `package`, `namespaces` and sections `since <version>`.");
1 ✔
73
                        } elseif (!is_array($section) || (array_is_list($section) && $section !== [])) {
1 ✔
74
                                throw new ConfigurationException("Upgrading file $label: The section `$key` must be a map of maps to their entries.");
1 ✔
75
                        }
76

77
                        foreach ($section as $map => $entries) {
1 ✔
78
                                if (is_string($map) && str_contains($map, '.') && is_string($entries)) {
1 ✔
79
                                        $requirements[$m[1]][$map] = $entries;
1 ✔
80
                                        continue;
1 ✔
81
                                } elseif (!is_string($map) || !is_array($entries)) {
1 ✔
82
                                        throw new ConfigurationException("Upgrading file $label: The map `$map` in `$key` must be a map of entries; a package turns on only a rule of its own plugin, by the path of its decision and a word.");
1 ✔
83
                                } elseif (in_array($map, self::ForbiddenMaps, true)) {
1 ✔
84
                                        try {
85
                                                $entries = Map::expandBareNames($entries, $map);
1 ✔
86
                                        } catch (ConfigurationException $e) {
×
87
                                                throw new ConfigurationException("Upgrading file $label, `$key`: {$e->getMessage()}", previous: $e);
×
88
                                        }
89
                                }
90

91
                                foreach ($entries as $entry => $value) {
1 ✔
92
                                        $from = is_array($value) ? $value['from'] ?? null : null;
1 ✔
93
                                        if ($from !== null && (!is_string($from) || !preg_match(self::VersionPattern, $from))) {
1 ✔
94
                                                throw new ConfigurationException("Upgrading file $label: `from` of the entry `$entry` of `$map` in `$key` must be a version, as `'8.0'`.");
1 ✔
95
                                        }
96
                                }
97

98
                                $sections[$m[1]][$map] = $entries;
1 ✔
99
                        }
100
                }
101

102
                uksort($sections, fn(string $a, string $b) => version_compare($a, $b));
1 ✔
103
                uksort($requirements, fn(string $a, string $b) => version_compare($a, $b));
1 ✔
104
                try {
105
                        $namespaces = new Profile(namespaces: is_array($data['namespaces'] ?? null) ? $data['namespaces'] : [])->namespaces;
1 ✔
106
                } catch (\InvalidArgumentException $e) {
×
107
                        throw new ConfigurationException("Upgrading file $label: {$e->getMessage()}", previous: $e);
×
108
                }
109

110
                return new self($package, $namespaces, $sections, $requirements);
1 ✔
111
        }
112

113

114
        /**
115
         * Every section as it is written, the oldest first: its maps, the entries without the version `from` says their fix
116
         * is right from, and the requirements it turns on.
117
         * @return array<string, array{array<string, array<string, mixed>>, array<string, string>}>  version => maps, requirements
118
         */
119
        public function getSections(): array
120
        {
121
                $versions = array_unique(array_map(strval(...), [...array_keys($this->sections), ...array_keys($this->requirements)]));
1 ✔
122
                usort($versions, fn(string $a, string $b) => version_compare($a, $b));
1 ✔
123
                $sections = [];
1 ✔
124
                foreach ($versions as $version) {
1 ✔
125
                        $sections[$version] = [
1 ✔
126
                                array_map(fn(array $entries) => array_map(self::removeFrom(...), $entries), $this->sections[$version] ?? []),
1 ✔
127
                                $this->requirements[$version] ?? [],
1 ✔
128
                        ];
129
                }
130

131
                return $sections;
1 ✔
132
        }
133

134

135
        /**
136
         * The data for code that must work with the versions of the constraint, null where any version does. An entry is
137
         * rewritten where the lowest version reaches its section, or the version `from` says its fix is right from, a later
138
         * section having the last word on it: every entry where any version does, none where there is no lower bound.
139
         * What a section above the lowest version retires, where a version the constraint allows reaches it, is reported
140
         * without a fix as the entry of a forbidden map (`retire()`), unless a section reached rewrites or forbids the same
141
         * thing already. A requirement is turned on where the lowest version reaches its section, and says nothing above it.
142
         */
143
        public function selectFor(?string $constraint, Layer $layer): UpgradingData
144
        {
145
                $lowest = $constraint === null ? null : Versions::findLowestVersion($constraint);
1 ✔
146
                $reaches = fn(string $version) => $constraint === null || ($lowest !== null && version_compare($lowest, $version, '>='));
1 ✔
147
                $maps = $retirements = $retired = $unreached = $reported = [];
1 ✔
148
                foreach ($this->sections as $since => $section) {
1 ✔
149
                        $since = (string) $since;
1 ✔
150
                        $left = [];
1 ✔
151
                        foreach ($section as $map => $entries) {
1 ✔
152
                                foreach ($entries as $key => $value) {
1 ✔
153
                                        $from = is_array($value) ? $value['from'] ?? null : null;
1 ✔
154
                                        if (!$reaches($since) && ($from === null || !$reaches($from))) {
1 ✔
155
                                                $left[$map][$key] = $value;
1 ✔
156
                                                continue;
1 ✔
157
                                        }
158

159
                                        $maps[$map][$key] = self::removeFrom($value);
1 ✔
160
                                        unset($retirements[$map][$key]);
1 ✔
161
                                        if (in_array($map, self::ForbiddenMaps, true) && $value !== MemberMapGrammar::Keep) {
1 ✔
162
                                                $retirements[$map][$key] = $since;
1 ✔
163
                                        }
164
                                }
165
                        }
166

167
                        if ($left === [] || $constraint === null) {
1 ✔
168
                                continue;
1 ✔
169
                        }
170

171
                        $unreached[] = $since;
1 ✔
172
                        if (!Versions::isSubset($constraint, "<$since")) {
1 ✔
173
                                $reported[] = $since;
1 ✔
174
                                foreach (self::retire($left) as [$map, $key, $sentence, $version]) {
1 ✔
175
                                        $retired[$map][$key] = [$sentence, $version ?? $since];
1 ✔
176
                                }
177
                        }
178
                }
179

180
                $written = [];
1 ✔
181
                foreach ($maps as $map => $entries) {
1 ✔
182
                        foreach (array_keys($entries) as $key) {
1 ✔
183
                                $target = self::findForbidden($map, (string) $key);
1 ✔
184
                                if ($target !== null) {
1 ✔
185
                                        $written[$target[0]][self::identify(...$target)] = true;
1 ✔
186
                                }
187
                        }
188
                }
189

190
                foreach ($retired as $map => $entries) {
1 ✔
191
                        foreach ($entries as $key => [$sentence, $version]) {
1 ✔
192
                                if (!isset($written[$map][self::identify($map, $key)])) {
1 ✔
193
                                        $maps[$map][$key] = $sentence;
1 ✔
194
                                        $retirements[$map][$key] = $version;
1 ✔
195
                                }
196
                        }
197
                }
198

199
                $requirements = [];
1 ✔
200
                foreach ($this->requirements as $since => $values) {
1 ✔
201
                        if ($reaches((string) $since)) {
1 ✔
202
                                $requirements = array_replace($requirements, $values);
1 ✔
203
                        }
204
                }
205

206
                return new UpgradingData($layer, $this->package, $this->namespaces, $maps, $retirements, $unreached, $reported, $requirements);
1 ✔
207
        }
208

209

210
        /**
211
         * What entries left above the lowest version say the code still meets on a version it may run on, as entries of the
212
         * forbidden maps (`findForbidden()`), since what they write instead is not there in the lowest one: what they forbid,
213
         * and what they replace, each with its sentence and the version it says, where that is not the one of its section.
214
         * @param  array<string, array<string, mixed>>  $section  map => its entries
215
         * @return list<array{string, string, ?string, ?string}>  forbidden map, key, sentence, version
216
         */
217
        private static function retire(array $section): array
218
        {
219
                $retired = [];
1 ✔
220
                foreach ($section as $map => $entries) {
1 ✔
221
                        foreach ($entries as $key => $value) {
1 ✔
222
                                [$write, $from] = is_array($value) ? [$value['write'] ?? null, $value['from'] ?? null] : [$value, null];
1 ✔
223
                                $target = self::findForbidden($map, (string) $key);
1 ✔
224
                                if ($target === null || $write === MemberMapGrammar::Keep) {
1 ✔
225
                                        continue;
1 ✔
226
                                }
227

228
                                [$forbidden, $name] = $target;
1 ✔
229
                                $retired[] = match (true) {
1 ✔
230
                                        $map === $forbidden => [$forbidden, $name, $write, null],
1 ✔
231
                                        $write === MemberMapGrammar::Removed => [$forbidden, $name, 'does nothing', $from],
1 ✔
232
                                        is_string($write) => [$forbidden, $name, 'replaced by `' . ltrim($write, '\\') . '`', null],
1 ✔
233
                                        default => [$forbidden, $name, 'replaced', null],
1 ✔
234
                                };
235
                        }
236
                }
237

238
                return $retired;
1 ✔
239
        }
240

241

242
        /**
243
         * The forbidden map an entry of the map is reported by where it cannot be rewritten, and its key there: a call of
244
         * a function as the function, a call of a member by the shape of its arguments as `forbiddenMembers` reads it; null
245
         * for a map that forbids nothing by itself, an annotation and the maps of plugins, and for a key that is no name.
246
         * @return ?array{string, string}
247
         */
248
        private static function findForbidden(string $map, string $key): ?array
249
        {
250
                try {
251
                        return match (true) {
252
                                in_array($map, self::ForbiddenMaps, true) => [$map, $key],
1 ✔
253
                                $map === 'replacedClasses' => ['forbiddenClasses', $key],
1 ✔
254
                                $map === 'replacedFunctions' => ['forbiddenFunctions', $key],
1 ✔
255
                                $map === 'replacedMembers' => ['forbiddenMembers', $key],
1 ✔
256
                                $map === 'replacedCalls' && MemberMapGrammar::isFunctionKey($key)
1 ✔
257
                                        => ['forbiddenFunctions', FunctionPattern::fromKey($key)->name],
1 ✔
258
                                $map === 'replacedCalls' => ['forbiddenMembers', $key],
1 ✔
259
                                default => null,
1 ✔
260
                        };
261
                } catch (\InvalidArgumentException) {
×
262
                        return null; // the grammar of the map says what is wrong with the key
×
263
                }
264
        }
265

266

267
        /**
268
         * What the key of a forbidden map names whatever way it is written, so that one rewritten and one forbidden meet: a
269
         * member by its class and name, a class, a function and a constant by its name.
270
         */
271
        private static function identify(string $forbidden, string $key): string
272
        {
273
                try {
274
                        $member = $forbidden === 'forbiddenMembers' ? MemberPattern::fromKey($key) : null;
1 ✔
275
                } catch (\InvalidArgumentException) {
×
276
                        $member = null;
×
277
                }
278

279
                return strtolower($member === null ? ltrim($key, '\\') : "$member->class::$member->name");
1 ✔
280
        }
281

282

283
        /** The entry as the map reads it, without the version it is right from; `{write: X}` is X. */
284
        private static function removeFrom(mixed $value): mixed
285
        {
286
                if (!is_array($value) || !array_key_exists('from', $value)) {
1 ✔
287
                        return $value;
1 ✔
288
                }
289

290
                unset($value['from']);
1 ✔
291
                return array_keys($value) === ['write'] ? $value['write'] : $value;
1 ✔
292
        }
293
}
STATUS · Troubleshooting · Open an Issue · Sales · Support · CAREERS · ENTERPRISE · START FREE TRIAL · SCHEDULE DEMO
ANNOUNCEMENTS · TWITTER · TOS & SLA · Supported CI Services · What's a CI service? · Automated Testing

© 2026 Coveralls, Inc