refactor(icon-build-helpers): update metadata generation (#5372)

* chore: check-in work

* chore: check-in work

* refactor(icons): update metadata build helpers

* chore(icons): run remove-usage-fields migration

* chore(icons): uncomment builder code

* chore(icon-metadata): add special case for glyphs

* feat(metadata): add pictogram extension

* feat(icon-metadata): add support for extensions in ci-check

* refactor(pictograms): run migration for pictogram files

* feat(pictograms): add metadata support for pictograms

* chore(icon-metadata): fix eslint violations

* chore(icons): update metadata with new icon changes

* chore(icon-build-helpers): update comment with latest terminology

* chore(pictograms): update scaffold task to only use pictograms extension

* chore(icons): update metadata with new icon changes

Co-authored-by: TJ Egan <[email protected]>

packages/icon-build-helpers/package.json

@@ -29,7 +29,7 @@
     "joi": "^14.3.1",
     "js-yaml": "^3.12.1",
     "klaw-sync": "^6.0.0",
-    "memfs": "^2.14.0",
+    "memfs": "^3.0.4",
     "prettier": "^1.19.1",
     "prop-types": "^15.6.2",
     "react": "^16.6.0",

packages/icon-build-helpers/src/index.js

@@ -8,11 +8,9 @@
 'use strict';
 
 const builders = require('./builders');
-const buildMetadata = require('./build-metadata');
-const check = require('./check');
+const Metadata = require('./metadata');
 
 module.exports = {
   builders,
-  buildMetadata,
-  check,
+  Metadata,
 };

packages/icon-build-helpers/src/metadata/README.md

@@ -0,0 +1,37 @@
+# Metadata
+
+## About
+
+We store metadata for a collection of SVG assets to help with searching and
+using icons in the Carbon Design System. However, due to the large number of
+assets we maintain, we needed to build a system for organizing information about
+these icons and creating an output file to be consumed by tooling.
+
+As a result, the Metadata module provides support for building, scaffolding, and
+verifying metadata information about a collection of SVG assets. Under the hood,
+this module will build up a registry of all available assets and compare them
+against metadata files called "extensions". These files are typically written in
+YAML and are separated to make authoring of specific types of data easier.
+
+In general, we support the following extension types:
+
+- Icons: provides information for icons available from the source directory of
+  SVG assets
+- Categories: provides category and subcategory information for a collection of
+  icons
+- Module name: provides computed names used in code for an icon
+- Deprecations: provides a listing of icons that have been deprecated and
+  details how to update usage to the preferred format
+
+To support the above use-cases, Metadata makes use of the following concepts:
+
+- [Registry](./registry.js): build up a source of truth for all available SVG
+  assets in a source tree
+- [Extensions](./extensions/index.js): distinct sources of metadata captured for
+  icons. These modules provide support for verifying file structure, extending
+  the resulting output metadata, and logical checks to verify information
+  present (or not present) in these files
+- [Adapters](./adapters.js): provide support for authoring metadata in a variety
+  of formats, we currently author in YAML
+- [Storage](./storage.js): ability to read and write extension files for a given
+  adapter

packages/icon-build-helpers/src/metadata/__tests__/registry-test.js

@@ -0,0 +1,78 @@
+/**
+ * Copyright IBM Corp. 2020, 2020
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+describe('registry', () => {
+  let Registry;
+  let vol;
+
+  beforeEach(() => {
+    jest.mock('fs', () => {
+      const memfs = require('memfs');
+      vol = memfs.vol;
+      return memfs.fs;
+    });
+    Registry = require('../registry');
+  });
+
+  afterEach(() => {
+    vol.reset();
+  });
+
+  it('should register each asset from a directory', async () => {
+    const assets = ['a', 'b', 'c'];
+    const files = {};
+    for (const asset of assets) {
+      const filepath = `/svg/${asset}.svg`;
+      files[filepath] = 'mock';
+    }
+    vol.fromJSON(files);
+
+    const registry = await Registry.create('/svg');
+    for (const [id] of registry) {
+      expect(assets.indexOf(id)).not.toBe(-1);
+    }
+  });
+
+  it('should register each asset in nested directories', async () => {
+    const assets = ['foo/a', 'foo/bar/b', 'baz/c'];
+    const files = {};
+    for (const asset of assets) {
+      const filepath = `/svg/${asset}.svg`;
+      files[filepath] = 'mock';
+    }
+    vol.fromJSON(files);
+
+    const registry = await Registry.create('/svg');
+    for (const icon of registry.values()) {
+      const asset = icon.namespace.join('/') + '/' + icon.id;
+      expect(assets.indexOf(asset)).not.toBe(-1);
+    }
+  });
+
+  it('should register assets with the same name under the same icon', async () => {
+    const assets = ['16/a', '20/a', '32/a'];
+    const files = {};
+    for (const asset of assets) {
+      const filepath = `/svg/${asset}.svg`;
+      files[filepath] = 'mock';
+    }
+    vol.fromJSON(files);
+
+    const registry = await Registry.create('/svg');
+    expect(registry.size).toBe(1);
+
+    const icon = registry.get('a');
+    expect(icon.assets.length).toBe(assets.length);
+    expect(icon.assets[0].size).toBe(16);
+    expect(icon.assets[1].size).toBe(20);
+    expect(icon.assets[2].size).toBe(32);
+  });
+});