diff --git a/CHANGELOG.md b/CHANGELOG.md index 195c9a2..45428a5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ All notable changes to `ichava/icon-sets-flag` follow [Keep a Changelog](https:/ ## [Unreleased] +### Added + +- **The pack's kind is pinned against core's resolver.** `tests/Feature/SvgKindTest.php` gains cases for the D6 kind keys core now reads (ichava/core#162): `metadata.data.items` and `metadata.data.kinds.rules`, when present, hold valid kinds and globs and name files that exist; no category or the pack declares a `mixed` kind; and, with a core that has `Support\KindResolver`, a sample of items from every folder resolves `icon` from `package.kind`. `config.json` is unchanged: `package.kind` was already `icon`. `docs/configuration.md` describes the kind keys. + ### Changed - **Documentation links point at each repository's own `docs/`** (Sim, 2026-11-03: "all ichava repos have docs in their respective repos. thats by design"). Links to `opensource.simtabi.com/documentation/ichava/...` and the `opensource.simtabi.com/products/ichava/...` homepage, which answer 404 for every ichava page, now go to the matching `docs/*.md` on GitHub, or to the repository itself. Each target was checked to exist on that repository's `main`. The manifest's `homepage` and `support.docs` follow. diff --git a/docs/configuration.md b/docs/configuration.md index 6c441f2..3d6710d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -22,6 +22,31 @@ The set name and prefix are not here. Core reads both from `resources/assets/svg through `IconsConstants`, which is canonical for the pack's name, prefix, kind, variants and categories; the copies this file used to carry were read by nothing and are gone. +## Kinds in `config.json` + +`resources/assets/svg/config.json` declares what this pack's SVGs are, `icon` or `illustration`. Core decides +each item's kind from the first row that gives one. An item path is the file's path under `files/` without +`.svg` (`4x3/us`): + +| Row | Key | Notes | +|---|---|---| +| 1 | the host's `kinds.overrides` | the app developer's, in core's config; wins over the pack | +| 2 | `metadata.data.items..kind` | one item; the value is an object so it can grow | +| 3 | `metadata.data.kinds.rules[]` | `{ "match": "", "kind": "..." }`, ordered, **first match wins** | +| 4 | `metadata.data.categories..kind` | every item in that first-level folder | +| 5 | `package.kind` | the pack's default | +| 6 | | `icon` | + +Globs match the whole item path and are case-sensitive: `*` is any run of characters except `/`, `?` is one +character, and `**` is whole segments. A pack is "mixed" when its items resolve to both kinds; nothing declares +that, and there is no `"kind": "mixed"`. A value that names no kind is ignored by core and reported by +`ichava::ichava-core.info doctor`. See core's [kinds guide](https://github.com/ichava/core/blob/main/docs/kinds.md). + +This pack declares `package.kind: icon` and nothing else: flags are multicolour icons, not illustrations. No category, `items` or `kinds.rules` entry sets a kind, so every item resolves `icon` from row 5. + +`SvgKindTest` pins this against `config.json` and against core's resolver, so a typo here fails a test instead of +quietly filing SVGs as icons. + ## What is not here Cache, queue, database, logging, security and the `ICHAVA_*` environment surface are **core's**, and diff --git a/tests/Feature/SvgKindTest.php b/tests/Feature/SvgKindTest.php index 363daa2..24757cd 100644 --- a/tests/Feature/SvgKindTest.php +++ b/tests/Feature/SvgKindTest.php @@ -111,3 +111,119 @@ function flag_resolved_kinds(): array expect($registry->kindFor('ichava/icon-sets-flag', $slug)->value)->toBe($kind); } }); + +/** + * Up to $perCategory item paths from each first-level folder under files/, plus + * the files at its root: the paths core resolves a kind for (the path under + * `files/`, forward slashes, no `.svg`). + * + * @return list + */ +function flag_item_paths(int $perCategory = 5): array +{ + $root = dirname(__DIR__, 2) . '/resources/assets/svg/files'; + $paths = []; + + foreach (glob($root . '/*', GLOB_ONLYDIR) ?: [] as $directory) { + $taken = 0; + + foreach (new RecursiveIteratorIterator(new RecursiveDirectoryIterator($directory, FilesystemIterator::SKIP_DOTS)) as $file) { + if ($file->getExtension() !== 'svg' || flag_is_theme_twin($file->getBasename('.svg'))) { + continue; + } + + $paths[] = substr(str_replace('\\', '/', $file->getPathname()), strlen($root) + 1, -strlen('.svg')); + + if (++$taken >= $perCategory) { + break; + } + } + } + + foreach (glob($root . '/*.svg') ?: [] as $file) { + $paths[] = basename($file, '.svg'); + } + + sort($paths); + + return $paths; +} + +/** A theme twin is not an item: it inherits its light file's kind. */ +function flag_is_theme_twin(string $basename): bool +{ + return false; +} + +/** @return array{string, string} the kind and the D6 row source an item resolves to */ +function flag_expected(string $item): array +{ + return ['icon', 'pack']; +} + +it(description: 'declares item kinds and kind rules core can read', closure: function () { + $data = flag_kind_config()['metadata']['data']; + $files = dirname(__DIR__, 2) . '/resources/assets/svg/files'; + + // Absent is fine (a v0.1 manifest has neither). When present, `items` is a + // map keyed by item path and `kinds.rules` an ordered array: core drops an + // entry it cannot read and doctor reports it, so a typo would quietly fall + // through to the next row. + expect($data['items'] ?? [])->toBeArray(); + expect(array_is_list($data['kinds']['rules'] ?? []))->toBeTrue('kinds.rules must be an ordered array'); + + foreach ($data['items'] ?? [] as $path => $item) { + expect(is_array($item) && in_array($item['kind'] ?? null, flag_kinds(), true)) + ->toBeTrue("items.{$path}.kind names no kind"); + expect(is_file("{$files}/{$path}.svg"))->toBeTrue("items.{$path} names no file"); + } + + foreach ($data['kinds']['rules'] ?? [] as $index => $rule) { + $match = is_array($rule) ? ($rule['match'] ?? null) : null; + + expect(is_string($match) && $match !== '' && $match[0] !== '/' && strpbrk($match, '[]{}\\') === false) + ->toBeTrue("kinds.rules.{$index}.match is not a valid glob"); + expect(in_array($rule['kind'] ?? null, flag_kinds(), true)) + ->toBeTrue("kinds.rules.{$index}.kind names no kind"); + } +}); + +it(description: 'declares no kind mixed, since a mixed pack is derived from its items', closure: function () { + $config = flag_kind_config(); + $declared = [$config['package']['kind'] ?? null]; + + foreach ($config['metadata']['data']['categories'] ?? [] as $category) { + $declared[] = is_array($category) ? ($category['kind'] ?? null) : null; + } + + expect(in_array('mixed', $declared, true))->toBeFalse('there is no "mixed" kind'); +}); + +it(description: 'resolves each item to the kind and row the pack intends through core', closure: function () { + if (! class_exists(Simtabi\Laranail\Ichava\Support\KindResolver::class)) { + $this->markTestSkipped( + 'the ichava/core resolved here predates item kinds and rules (Support\KindResolver, ichava/core#162); ' + . 'the config.json cases above still run', + ); + } + + $resolver = $this->app->make(Simtabi\Laranail\Ichava\Support\KindResolver::class); + $items = flag_item_paths(); + + // A glob matching nothing would make the loop below vacuous. + expect(count($items))->toBeGreaterThanOrEqual(2, 'too few items were inspected'); + + $kinds = []; + + foreach ($items as $item) { + $resolution = $resolver->resolve('ichava/icon-sets-flag', $item); + [$kind, $source] = flag_expected($item); + + expect([$resolution->kind->value, $resolution->source->value]) + ->toBe([$kind, $source], "{$item} resolved to {$resolution->kind->value} from {$resolution->source->value}"); + + $kinds[$resolution->kind->value] = true; + } + + expect(array_keys($kinds))->toBe(['icon'], 'this pack is not mixed'); +});