Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
25 changes: 25 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.<item path>.kind` | one item; the value is an object so it can grow |
| 3 | `metadata.data.kinds.rules[]` | `{ "match": "<glob>", "kind": "..." }`, ordered, **first match wins** |
| 4 | `metadata.data.categories.<slug>.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
Expand Down
116 changes: 116 additions & 0 deletions tests/Feature/SvgKindTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -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<string>
*/
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');
});
Loading