feat(metadata|docs|site): reuse metadata from a base icon with $extends: (#4360)

* feat(metadata): reuse metadata from a base icon with `$extends:`

Icon metadata can reference a base icon with an inline `$extends:<icon-name>`
marker in `tags`, `categories` or `contributors`. The marker is replaced in
place with the base icon's resolved values at build time.

- Resolve markers in `readAllMetadata` and `getIconMetaData`, failing on
  unknown icons, self references and circular chains
- Accept markers in `icon.schema.json`
- `pnpm checkIcons` fails on duplicate markers and on literals a marker
  already provides, and runs in CI
- Docs read the resolved metadata index instead of the raw icon JSON
- Use `$extends:alarm-clock` in `alarm-clock-minus`

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(metadata): reuse metadata from a base icon with `$extends:`

Icon metadata can reference a base icon with an inline `$extends:<icon-name>`
marker in `tags`, `categories` or `contributors`. The marker is replaced in
place with the base icon's resolved values at build time.

- Resolve markers in `readAllMetadata` and `getIconMetaData`, failing on
  unknown icons, self references and circular chains
- Accept markers in `icon.schema.json`
- `pnpm checkIcons` fails on duplicate markers and on literals a marker
  already provides, and runs in CI
- Docs read the resolved metadata index instead of the raw icon JSON
- Use `$extends:alarm-clock` in `alarm-clock-minus`

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Fix comments

* Format code

* Update tools/build-helpers/src/resolveMetadataExtends.ts

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Fix resolving icon metadata

* feat(metadata): reuse metadata from a base icon with `$extends:`

Icon metadata can reference a base icon with an inline `$extends:<icon-name>`
marker in `tags`, `categories` or `contributors`. The marker is replaced in
place with the base icon's resolved values at build time.

- Resolve markers in `readAllMetadata` and `getIconMetaData`, failing on
  unknown icons, self references and circular chains
- Accept markers in `icon.schema.json`
- `pnpm checkIcons` fails on duplicate markers and on literals a marker
  already provides, and runs in CI
- Docs read the resolved metadata index instead of the raw icon JSON
- Use `$extends:alarm-clock` in `alarm-clock-minus`

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Fix comments

* Format code

* Update tools/build-helpers/src/resolveMetadataExtends.ts

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Fix resolving icon metadata

* Fix comments

* Format code

* Update tools/build-helpers/src/resolveMetadataExtends.ts

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
This commit is contained in:
Eric Fennis
2026-10-29 17:29:58 +01:00
committed by GitHub
co-authored by Claude Opus 5.5 github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
parent e2c3360976
commit 7bf67d3b1c
14 changed files with 417 additions and 131 deletions
+71 -1
View File
@@ -3,12 +3,22 @@ import {
readSvgDirectory,
getCurrentDirPath,
readAllMetadata,
readMetadata,
} from '../tools/build-helpers/helpers.ts';
import { type IconMetadata } from '../tools/build-icons/types.ts';
const currentDir = getCurrentDirPath(import.meta.url);
const ICONS_DIR = path.resolve(currentDir, '../icons');
const icons = await readAllMetadata(ICONS_DIR) as Record<string, IconMetadata>;
let icons: Record<string, IconMetadata>;
try {
icons = await readAllMetadata(ICONS_DIR) as Record<string, IconMetadata>;
} catch (error) {
console.error(`Failed to read icon metadata: ${error instanceof Error ? error.message : String(error)}`);
console.error('This may be due to invalid extends references or circular dependencies.');
process.exit(1);
}
const CATEGORIES_DIR = path.resolve(currentDir, '../categories');
const categories = await readAllMetadata(CATEGORIES_DIR) as Record<string, {
icon: string;
@@ -43,6 +53,66 @@ Object.keys(icons).forEach((iconName) => {
});
});
const EXTENDS_PREFIX = '$extends:';
const MARKED_FIELDS = ['tags', 'categories', 'contributors'] as const;
type MarkedField = (typeof MARKED_FIELDS)[number];
const FIELD_LABELS: Record<MarkedField, string> = {
tags: 'tag',
categories: 'category',
contributors: 'contributor',
};
const isMarker = (entry: string) => entry.startsWith(EXTENDS_PREFIX);
// `readAllMetadata` expands the markers, so the duplicate checks below read the
// JSON as it is written on disk to see which entries are literals.
const iconJsonFiles = await readSvgDirectory(ICONS_DIR, '.json');
const rawIcons = Object.fromEntries(
await Promise.all(
iconJsonFiles.map(async (file) => [
path.basename(file, '.json'),
(await readMetadata(file, ICONS_DIR)) as Partial<Record<MarkedField, string[]>>,
]),
),
) as Record<string, Partial<Record<MarkedField, string[]>>>;
/** The values a single marker contributes to `field`. */
const resolveMarker = (marker: string, field: MarkedField): string[] => {
const parentName = marker.slice(EXTENDS_PREFIX.length);
return (icons[parentName]?.[field] as string[] | undefined) ?? [];
};
Object.entries(rawIcons).forEach(([iconName, rawMetadata]) => {
MARKED_FIELDS.forEach((field) => {
const entries = rawMetadata[field] ?? [];
const literals = new Set(entries.filter((entry) => !isMarker(entry)));
const seenMarkers = new Set<string>();
entries.filter(isMarker).forEach((marker) => {
if (seenMarkers.has(marker)) {
console.error(
`Icon '${iconName}': '${marker}' is listed twice in '${field}' — remove the duplicate marker.`,
);
error = true;
return;
}
seenMarkers.add(marker);
resolveMarker(marker, field)
.filter((value) => literals.has(value))
.forEach((value) => {
console.error(
`Icon '${iconName}': ${FIELD_LABELS[field]} '${value}' is already provided by ${marker} — remove the literal.`,
);
error = true;
});
});
});
});
Object.keys(categories).forEach((categoryName) => {
const category = categories[categoryName];
if (!category?.icon) {