Add initial tools utilities (#3)

Author: justinfagnani

.github/workflows/tests.yml

@@ -0,0 +1,26 @@
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    env:
+      WIREIT_FAILURES: continue
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - uses: google/wireit@setup-github-actions-caching/v1
+
+      - name: NPM install
+        run: npm ci
+
+      - name: Test
+        run: npm test

.gitignore

@@ -2,5 +2,5 @@ node_modules/
 .wireit/
 .eslintcache
 
-packages/**/lib/
-packages/**/tsconfig.tsbuildinfo
+packages/*/lib/
+packages/*/tsconfig.tsbuildinfo

package-lock.json

@@ -4,6 +4,7 @@
   ],
   "scripts": {
     "build": "wireit",
+    "test": "wireit",
     "format": "prettier \"./packages/*/src/**/*.ts\" --write",
     "check": "wireit"
   },
@@ -24,6 +25,11 @@
         "./packages/validator:build"
       ]
     },
+    "test": {
+      "dependencies": [
+        "./packages/tools:test"
+      ]
+    },
     "check": {
       "dependencies": [
         "check:lint",

package.json

@@ -1,5 +1,7 @@
 /lib/
-/test/
+/test/*
+!/test/test-data/
+
 /index.js
 /index.js.map
 /index.d.ts

packages/tools/.gitignore

@@ -8,7 +8,8 @@
   "type": "module",
   "main": "index.js",
   "scripts": {
-    "build": "wireit"
+    "build": "wireit",
+    "test": "wireit"
   },
   "wireit": {
     "build": {
@@ -25,9 +26,27 @@
         "index.d.ts.map",
         "lib/",
         "test/",
+        "!test/test-data/*",
         "tsconfig.tsbuildinfo"
       ],
       "clean": "if-file-deleted"
+    },
+    "test": {
+      "command": "NODE_OPTIONS='--enable-source-maps' uvu test \"_test\\.js$\"",
+      "dependencies": [
+        "build"
+      ],
+      "files": [
+        "test/test-data/*"
+      ],
+      "output": []
     }
+  },
+  "dependencies": {
+    "custom-elements-manifest": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^18.16.3",
+    "uvu": "^0.5.6"
   }
 }

packages/tools/package.json

@@ -1 +1,10 @@
-export {};
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+export * from './lib/get-custom-elements.js';
+export * from './lib/resolve-reference.js';
+export * from './lib/get-module.js';
+export * from './lib/predicates.js';

packages/tools/src/index.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+import type {
+  CustomElementDeclaration,
+  CustomElementExport,
+  Module,
+  Package,
+  Reference,
+} from 'custom-elements-manifest/schema.js';
+import {isCustomElementDeclaration} from './predicates.js';
+import {resolveReference} from './resolve-reference.js';
+
+export type CustomElementInfo = {
+  package: Package;
+  module: Module;
+  export: CustomElementExport;
+  declaration: CustomElementDeclaration;
+  declarationReference: Reference;
+};
+
+/**
+ * Gets all the custom element exports of a package
+ *
+ * @param pkg The package to search
+ * @param packageName The name of the package
+ * @param packageVersion The version of the package
+ */
+export const getCustomElements = (
+  pkg: Package,
+  packageName: string,
+  packageVersion: string
+): Array<CustomElementInfo> => {
+  const customElements: Array<CustomElementInfo> = [];
+  for (const mod of pkg.modules) {
+    if (mod.exports) {
+      for (const e of mod.exports) {
+        if (e.kind === 'custom-element-definition') {
+          // TODO (justinfagnani): for large manifests we want to index ahead
+          // of time to avoid polynomial lookups
+          const decl = resolveReference(
+            pkg,
+            mod,
+            e.declaration,
+            packageName,
+            packageVersion
+          );
+          if (decl !== undefined && isCustomElementDeclaration(decl)) {
+            customElements.push({
+              package: pkg,
+              module: mod,
+              export: e,
+              declaration: decl,
+              declarationReference: e.declaration,
+            });
+          } else {
+            // This is some kind of manifest error, should we warn?
+            // Or assume it was handled in a validation pass?
+          }
+        }
+      }
+    }
+  }
+  return customElements;
+};

packages/tools/src/lib/get-custom-elements.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+import type {Package} from 'custom-elements-manifest/schema.js';
+
+/**
+ * Gets a module by path from a package.
+ */
+export const getModule = (pkg: Package, path: string) => {
+  path = normalizeModulePath(path);
+  for (const mod of pkg.modules) {
+    const modulePath = normalizeModulePath(mod.path);
+    if (modulePath === path) {
+      return mod;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Normalizes a module path by removing leading slashes.
+ */
+export const normalizeModulePath = (path: string) =>
+  path.startsWith('/') ? path.substring(1) : path;

packages/tools/src/lib/get-module.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+import type {
+  Declaration,
+  ClassDeclaration,
+  CustomElementDeclaration,
+  FunctionDeclaration,
+  CustomElement,
+  CustomElementMixinDeclaration,
+} from 'custom-elements-manifest/schema.js';
+
+export const isClassDeclaration = (d: Declaration): d is ClassDeclaration =>
+  d.kind === 'class';
+
+export const isFunctionDeclaration = (
+  d: Declaration
+): d is FunctionDeclaration => d.kind === 'function';
+
+export const isMixinDeclaration = (d: Declaration): d is FunctionDeclaration =>
+  d.kind === 'mixin';
+
+export const isVariableDeclaration = (
+  d: Declaration
+): d is FunctionDeclaration => d.kind === 'variable';
+
+export const isCustomElement = (
+  d: Declaration
+): d is CustomElementDeclaration | CustomElementMixinDeclaration =>
+  (d as CustomElement).customElement === true;
+
+export const isCustomElementDeclaration = (
+  d: Declaration
+): d is CustomElementDeclaration => isClassDeclaration(d) && isCustomElement(d);
+
+export const isCustomElementMixinDeclaration = (
+  d: Declaration
+): d is CustomElementMixinDeclaration =>
+  isMixinDeclaration(d) && isCustomElement(d);