Python POC for GitHub-based API Reviews

.github/shared/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@azure-tools/specs-shared",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./array": "./src/array.js",
+    "./breaking-change": "./src/breaking-change.js",
+    "./changed-files": "./src/changed-files.js",
+    "./console": "./src/console.js",
+    "./eslint-base-config": "./eslint.base.config.js",
+    "./exec": "./src/exec.js",
+    "./git": "./src/git.js",
+    "./github": "./src/github.js",
+    "./logger": "./src/logger.js",
+    "./math": "./src/math.js",
+    "./path": "./src/path.js",
+    "./readme": "./src/readme.js",
+    "./sdk-types": "./src/sdk-types.js",
+    "./set": "./src/set.js",
+    "./simple-git": "./src/simple-git.js",
+    "./sleep": "./src/sleep.js",
+    "./sort": "./src/sort.js",
+    "./spec-model-error": "./src/spec-model-error.js",
+    "./spec-model": "./src/spec-model.js",
+    "./swagger": "./src/swagger.js",
+    "./tag": "./src/tag.js",
+    "./time": "./src/time.js",
+    "./test/examples": "./test/examples.js"
+  },
+  "bin": {
+    "spec-model": "./cmd/spec-model.js"
+  },
+  "_comments": {
+    "dependencies": "Runtime dependencies must be kept to an absolute minimum for performance, ideally with no transitive dependencies",
+    "dependencies2": "All runtime and dev dependencies in this file, must be a subset of ../package.json"
+  },
+  "dependencies": {
+    "@apidevtools/json-schema-ref-parser": "^15.1.3",
+    "debug": "^4.4.3",
+    "js-yaml": "^4.1.0",
+    "marked": "^18.0.0",
+    "simple-git": "^3.36.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.0",
+    "@tsconfig/node20": "^20.1.4",
+    "@types/debug": "^4.1.12",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.0.0",
+    "@types/semver": "^7.7.1",
+    "@vitest/coverage-v8": "^4.1.0",
+    "cross-env": "^10.1.0",
+    "eslint": "^10.0.0",
+    "globals": "^17.0.0",
+    "prettier": "3.8.3",
+    "prettier-plugin-organize-imports": "^4.2.0",
+    "semver": "^7.7.1",
+    "tinybench": "^6.0.0",
+    "typescript": "~6.0.2",
+    "typescript-eslint": "^8.58.0",
+    "vitest": "^4.1.0"
+  },
+  "scripts": {
+    "check": "npm run test:ci && npm run lint && npm run format:check",
+    "lint": "npm run lint:eslint && npm run lint:tsc",
+    "lint:eslint": "cross-env DEBUG=eslint:eslint,eslint:linter eslint",
+    "lint:tsc": "tsc --build --verbose",
+    "format": "prettier . --ignore-path ../.prettierignore --write",
+    "format:check": "prettier . --ignore-path ../.prettierignore --check",
+    "format:check:ci": "prettier . --ignore-path ../.prettierignore --check --log-level debug",
+    "perf": "node perf/perf.js",
+    "test": "vitest",
+    "test:ci": "vitest run --coverage --reporter=verbose"
+  }
+}

.github/shared/src/cache.js

@@ -0,0 +1,61 @@
+/**
+ * Caches values in memory with a single key of any type.
+ *
+ * @template K, V
+ */
+export class KeyedCache {
+  /** @type {Map<K, V>} */
+  #map = new Map();
+
+  /**
+   * Returns cached value, initializing if necessary
+   *
+   * @param {K} key
+   * @param {() => V} factory
+   * @returns {V} cached value
+   *
+   * @example
+   * const result = cache.getOrCreate(42, async () => await doWork(42));
+   */
+  getOrCreate(key, factory) {
+    let value = this.#map.get(key);
+
+    if (value === undefined) {
+      value = factory();
+      this.#map.set(key, value);
+    }
+
+    return value;
+  }
+}
+
+/**
+ * Caches values in memory with an ordered pair of keys of any types.
+ *
+ * @template K1, K2, V
+ */
+export class KeyedPairCache {
+  // Two-layer nested cache
+  /** @type {KeyedCache<K1, KeyedCache<K2, V>>} */
+  #cache1 = new KeyedCache();
+
+  /**
+   * Returns cached value, initializing if necessary.
+   * Keys are ordered, so (key1, key2) != (key2, key1).
+   *
+   * @param {K1} key1
+   * @param {K2} key2
+   * @param {() => V} factory
+   * @returns {V} cached value
+   *
+   * @example
+  * const result = cache.getOrCreate(42, 7, async () => await doWork(42, 7));
+   */
+  getOrCreate(key1, key2, factory) {
+    // key1 => cache for the next layer
+    const cache2 = this.#cache1.getOrCreate(key1, () => new KeyedCache());
+
+    // key2 => final value
+    return cache2.getOrCreate(key2, factory);
+  }
+}