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>

docs/scripts/writeIconDetails.mts

@@ -1,10 +1,11 @@
 import fs from 'fs';
 import path from 'path';
-import { readSvgDirectory, toCamelCase } from '@lucide/helpers';
+import { getIconMetaData } from '@lucide/build-icons';
+import { toCamelCase } from '@lucide/helpers';
 
 const currentDir = process.cwd();
 const ICONS_DIR = path.resolve(currentDir, '../icons');
-const icons = await readSvgDirectory(ICONS_DIR, '.json');
+const iconMetaData = await getIconMetaData(ICONS_DIR);
 
 const iconDetailsDirectory = path.resolve(currentDir, '.vitepress/data', 'iconDetails');
 
@@ -18,18 +19,27 @@ if (!fs.existsSync(iconDetailsDirectory)) {
 
 const indexFile = path.resolve(iconDetailsDirectory, `index.ts`);
 
-const writeIconFiles = icons.map(async (iconFileName) => {
-  const iconName = path.basename(iconFileName, '.json');
+const writeIconFiles = Object.entries(iconMetaData).map(async ([iconName, metaData]) => {
   const location = path.resolve(iconDetailsDirectory, `${iconName}.ts`);
+  const {
+    tags,
+    categories,
+    contributors,
+    aliases,
+    deprecated,
+    deprecationReason,
+    toBeRemovedInVersion,
+  } = metaData;
 
   const contents = `\
 import iconNode from '../iconNodes/${iconName}.node.json' with { type: 'json' };
-import metaData from '../../../../icons/${iconName}.json' with { type: 'json' };
 import releaseData from '../releaseMetadata/${iconName}.json' with { type: 'json' };
 import popularity from '../iconPopularity/${iconName}.json' with { type: 'json' };
 import { IconMetaData, IconNode } from '~/.vitepress/theme/types';
 
-const { tags, categories, contributors, aliases, deprecated, deprecationReason, toBeRemovedInVersion }: IconMetaData = metaData;
+const metaData: IconMetaData = ${JSON.stringify({ tags, categories, contributors, aliases, deprecated, deprecationReason, toBeRemovedInVersion })};
+
+const { tags, categories, contributors, aliases, deprecated, deprecationReason, toBeRemovedInVersion } = metaData;
 
 const iconDetails = {
   name: '${iconName}',

docs/scripts/writeIconMetaIndex.mts

@@ -1,10 +1,9 @@
 import fs from 'fs';
 import path from 'path';
-import { readSvgDirectory, toCamelCase } from '@lucide/helpers';
+import { readAllMetadata } from '@lucide/helpers';
 
 const currentDir = process.cwd();
 const ICONS_DIR = path.resolve(currentDir, '../icons');
-const iconJsonFiles = await readSvgDirectory(ICONS_DIR, '.json');
 
 const location = path.resolve(currentDir, '.vitepress/data', 'iconMetaData.ts');
 
@@ -12,29 +11,15 @@ if (fs.existsSync(location)) {
   fs.unlinkSync(location);
 }
 
-const iconMetaIndexFileImports = [];
-const iconMetaIndexFileExports = [];
-
-iconJsonFiles.forEach((iconJsonFile) => {
-  const iconName = path.basename(iconJsonFile, '.json');
-
-  iconMetaIndexFileImports.push(
-    `import ${toCamelCase(iconName)}Metadata from '../../../icons/${iconName}.json';`,
-  );
-  iconMetaIndexFileExports.push(`  '${iconName}': ${toCamelCase(iconName)}Metadata,`);
-});
+// The docs read this index raw and never re-resolve, so resolve the
+// `$extends:<icon-name>` markers here and bake the inherited
+// tags/categories/contributors into the generated file.
+const iconMetaData = await readAllMetadata(ICONS_DIR);
 
 try {
   await fs.promises.writeFile(
     location,
-    `\
-${iconMetaIndexFileImports.join('\n')}
-
-
-  export default {
-${iconMetaIndexFileExports.join('\n')}
-  }
-    `,
+    `export default ${JSON.stringify(iconMetaData, null, 2)};\n`,
     'utf-8',
   );