fhirsmith 0.16.1 → 0.18.0

package/tx/ocl/cs-ocl.cjs

@@ -7,6 +7,8 @@ const { SearchFilterText } = require('../library/designations');
 const { PAGE_SIZE, CONCEPT_PAGE_SIZE, COLD_CACHE_FRESHNESS_MS, OCL_CODESYSTEM_MARKER_EXTENSION } = require('./shared/constants');
 const { createOclHttpClient } = require('./http/client');
 const { fetchAllPages, extractItemsAndNext } = require('./http/pagination');
+const { OclReferenceResolver, isOrgOwned } = require('./resolve/reference-resolver');
+const { PublicAccessChecker } = require('./resolve/public-access');
 const { CACHE_CS_DIR, CACHE_VS_DIR, getCacheFilePath } = require('./cache/cache-paths');
 const { ensureCacheDirectories, getColdCacheAgeMs, formatCacheAgeMinutes } = require('./cache/cache-utils');
 const { computeCodeSystemFingerprint } = require('./fingerprint/fingerprint');
@@ -43,6 +45,19 @@ class OCLCodeSystemProvider extends AbstractCodeSystemProvider {
     this.baseUrl = http.baseUrl;
     this.httpClient = http.client;
 
+    // Resolves each source's DEFAULT version (latest release, else HEAD) so both
+    // get registered. Disabled without a token, in which case discovery stays
+    // HEAD-only exactly as before.
+    this.publicAccess = new PublicAccessChecker({ httpClient: this.httpClient, logger: oclLog });
+    this.referenceResolver = new OclReferenceResolver({
+      httpClient: this.httpClient,
+      token: options.token || null,
+      logger: oclLog,
+      publicAccess: this.publicAccess
+    });
+    this._defaultVersionByCanonical = new Map();
+    this._headMetaByCanonical = new Map();
+
     this._codeSystemsByCanonical = new Map();
     this._idToCodeSystem = new Map();
     this.sourceMetaByUrl = new Map();
@@ -72,6 +87,7 @@ class OCLCodeSystemProvider extends AbstractCodeSystemProvider {
         oclLog.info(`Fetched ${sources.length} sources`);
 
         const snapshot = this.#buildSourceSnapshot(sources);
+        await this.#augmentSnapshotWithDefaultVersions(snapshot);
         this.#applySnapshot(snapshot);
 
         oclLog.info(`Loaded ${this._codeSystemsByCanonical.size} code systems`);
@@ -135,7 +151,94 @@ class OCLCodeSystemProvider extends AbstractCodeSystemProvider {
   }
 
   getSourceMetas() {
-    return Array.from(this.sourceMetaByUrl.values());
+    // Default metas first: registerProvider's unversioned key is first-wins, so
+    // the release (when one exists) becomes what a versionless request gets,
+    // matching OCL's own resolution. HEAD variants stay reachable via |HEAD.
+    return [
+      ...this.sourceMetaByUrl.values(),
+      ...this._headMetaByCanonical.values()
+    ];
+  }
+
+  /**
+   * Resolve each source's DEFAULT version via one chunked $resolveReference
+   * batch: OCL answers with the latest release, or HEAD when none is released.
+   * For sources whose default is a release, the snapshot entry becomes the
+   * release (CodeSystem resource, meta, versioned concepts URL) and the HEAD
+   * variant is kept as an extra meta, so BOTH versions get factories.
+   *
+   * Only canonicals that are new or whose listing checksum changed are
+   * re-resolved, so a steady-state refresh costs no extra requests. A no-op
+   * without a token: discovery stays HEAD-only exactly as before.
+   */
+  async #augmentSnapshotWithDefaultVersions(snapshot) {
+    if (!this.referenceResolver.isEnabled()) {
+      return;
+    }
+
+    const previousSnapshot = this._sourceStateByCanonical;
+    const toResolve = [];
+    for (const [canonicalUrl, entry] of snapshot.entries()) {
+      entry.baseChecksum = entry.checksum;
+      const previous = previousSnapshot.get(canonicalUrl);
+      const previousBase = previous?.baseChecksum ?? previous?.checksum ?? null;
+      if (!this._defaultVersionByCanonical.has(canonicalUrl) || previousBase !== entry.baseChecksum) {
+        toResolve.push(canonicalUrl);
+      }
+    }
+
+    if (toResolve.length > 0) {
+      const results = await this.referenceResolver.resolveReferences(toResolve, { bypassCache: true });
+      if (Array.isArray(results)) {
+        toResolve.forEach((canonicalUrl, i) => {
+          const r = results[i];
+          if (r?.resolved && r.result?.version) {
+            this._defaultVersionByCanonical.set(canonicalUrl, r.result.version);
+          } else {
+            this._defaultVersionByCanonical.delete(canonicalUrl);
+          }
+        });
+      } else {
+        // Resolver unavailable: keep whatever defaults we knew; new canonicals
+        // stay HEAD-only until a later cycle succeeds.
+        oclLog.warn('Default-version resolution unavailable; keeping previous defaults');
+      }
+    }
+
+    let releaseCount = 0;
+    for (const [canonicalUrl, entry] of snapshot.entries()) {
+      const defaultVersion = this._defaultVersionByCanonical.get(canonicalUrl);
+      const headVersion = entry.meta?.version || null;
+      if (!defaultVersion || defaultVersion === headVersion) {
+        continue;
+      }
+      const conceptsUrl = entry.meta?.conceptsUrl;
+      if (!conceptsUrl || !conceptsUrl.endsWith('concepts/')) {
+        continue;
+      }
+
+      const baseRepo = conceptsUrl.slice(0, -'concepts/'.length);
+      const releaseJson = structuredClone(entry.cs.jsonObj);
+      releaseJson.version = defaultVersion;
+      const releaseCs = new CodeSystem(releaseJson, 'R5', true);
+      const releaseMeta = {
+        ...entry.meta,
+        version: defaultVersion,
+        conceptsUrl: `${baseRepo}${encodeURIComponent(defaultVersion)}/concepts/`,
+        codeSystem: releaseCs
+      };
+
+      entry.headMeta = entry.meta;
+      entry.meta = releaseMeta;
+      entry.cs = releaseCs;
+      // A release being published or deleted must surface as "changed".
+      entry.checksum = `${entry.baseChecksum}|default=${defaultVersion}`;
+      releaseCount++;
+    }
+
+    if (releaseCount > 0) {
+      oclLog.info(`${releaseCount} code system(s) defaulting to a released version (HEAD kept as |HEAD)`);
+    }
   }
 
   #scheduleRefresh() {
@@ -147,14 +250,24 @@ class OCLCodeSystemProvider extends AbstractCodeSystemProvider {
       try {
         const sources = await this.#fetchSourcesForDiscovery();
         const nextSnapshot = this.#buildSourceSnapshot(sources);
+        await this.#augmentSnapshotWithDefaultVersions(nextSnapshot);
         const changes = this.#diffSnapshots(this._sourceStateByCanonical, nextSnapshot);
         this.#applySnapshot(nextSnapshot);
-        for (const cs of changes.added || []) {
+        // Create factories for versions that appeared: the default (release) meta
+        // first so it claims the unversioned keys, then the HEAD variant. Covers
+        // both newly discovered sources and a release published on a known one.
+        for (const cs of [...(changes.added || []), ...(changes.changed || [])]) {
           const entry = nextSnapshot.get(cs.url);
-          if (entry?.meta && !OCLSourceCodeSystemFactory.hasFactory(cs.url, cs.version || null)) {
-            const factory = OCLSourceCodeSystemFactory.createForDiscoveredSource(this.httpClient, entry.meta);
+          for (const meta of [entry?.meta, entry?.headMeta]) {
+            if (!meta) {
+              continue;
+            }
+            if (OCLSourceCodeSystemFactory.hasExactFactory(meta.canonicalUrl, meta.version || null)) {
+              continue;
+            }
+            const factory = OCLSourceCodeSystemFactory.createForDiscoveredSource(this.httpClient, meta);
             if (factory) {
-              oclLog.info(`Factory created for newly discovered source: ${cs.url}`);
+              oclLog.info(`Factory created for ${meta.canonicalUrl}|${meta.version || ''}`);
             }
           }
         }
@@ -189,10 +302,37 @@ class OCLCodeSystemProvider extends AbstractCodeSystemProvider {
   }
 
   async #fetchSourcesForDiscovery() {
+    // Prefer the global listing: one paginated crawl instead of one listing per
+    // org (N+1 requests). Org-only policy: user-owned sources are experimental by
+    // convention and not visible to the terminology service, so filter them out.
+    try {
+      const all = await this.#fetchAllPages('/sources/');
+      if (Array.isArray(all) && all.length > 0) {
+        const seen = new Set();
+        const orgOwned = [];
+        for (const source of all) {
+          if (!source || typeof source !== 'object' || !isOrgOwned(source)) {
+            continue;
+          }
+          const key = this.#sourceIdentity(source);
+          if (seen.has(key)) {
+            continue;
+          }
+          seen.add(key);
+          orgOwned.push(source);
+        }
+        if (orgOwned.length > 0) {
+          // Public-only: a private source the token can see must not be served.
+          return await this.publicAccess.filterPublic(orgOwned);
+        }
+      }
+    } catch (error) {
+      oclLog.warn(`Global /sources/ listing failed (${error.message}); falling back to per-org discovery`);
+    }
+
     const organizations = await this.#fetchOrganizationIds();
     if (organizations.length === 0) {
-      // Fallback for OCL instances that expose global listing but not org listing.
-      return await this.#fetchAllPages('/sources/');
+      return [];
     }
 
     const allSources = [];
@@ -202,7 +342,9 @@ class OCLCodeSystemProvider extends AbstractCodeSystemProvider {
       const endpoint = `/orgs/${encodeURIComponent(orgId)}/sources/`;
       const sources = await this.#fetchAllPages(endpoint);
       for (const source of sources) {
-        if (!source || typeof source !== 'object') {
+        // Org-only policy applies to the per-org fallback too, not just the global
+        // listing (an org listing can still surface non-org-owned entries).
+        if (!source || typeof source !== 'object' || !isOrgOwned(source)) {
           continue;
         }
         const key = this.#sourceIdentity(source);
@@ -214,7 +356,8 @@ class OCLCodeSystemProvider extends AbstractCodeSystemProvider {
       }
     }
 
-    return allSources;
+    // Public-only: a private source the token can see must not be served.
+    return await this.publicAccess.filterPublic(allSources);
   }
 
   async #fetchOrganizationIds() {
@@ -284,6 +427,7 @@ class OCLCodeSystemProvider extends AbstractCodeSystemProvider {
     this._codeSystemsByCanonical.clear();
     this._idToCodeSystem.clear();
     this.sourceMetaByUrl.clear();
+    this._headMetaByCanonical.clear();
     this._usedIds.clear();
 
     for (const [canonicalUrl, entry] of snapshot.entries()) {
@@ -308,6 +452,9 @@ class OCLCodeSystemProvider extends AbstractCodeSystemProvider {
       this._codeSystemsByCanonical.set(canonicalUrl, cs);
       this._idToCodeSystem.set(cs.id, cs);
       this.sourceMetaByUrl.set(canonicalUrl, meta);
+      if (entry.headMeta) {
+        this._headMetaByCanonical.set(canonicalUrl, entry.headMeta);
+      }
     }
 
     this._sourceStateByCanonical = snapshot;
@@ -1834,11 +1981,14 @@ class OCLSourceCodeSystemFactory extends CodeSystemFactoryProvider {
   }
 
   #resourceKey() {
-    const crypto = require('crypto');
+    // Plain `system|version`, matching how hasExactFactory/#findFactory build
+    // their lookup keys. This used to be a SHA-256 of the same string, which
+    // meant exact-version lookups could NEVER match a registered factory (plain
+    // string vs hash) — only the unversioned `system|` alias ever worked. The
+    // key is only used for in-memory maps, job keys and logs, so hashing bought
+    // nothing and broke version-aware matching.
     const normalizedSystem = OCLSourceCodeSystemFactory.#normalizeSystem(this.system());
-    const base = `${normalizedSystem}|${this.version() || ''}`;
-    const hash = crypto.createHash('sha256').update(base).digest('hex');
-    return hash;
+    return `${normalizedSystem}|${this.version() || ''}`;
   }
 
   currentChecksum() {

package/tx/ocl/resolve/public-access.js

@@ -0,0 +1,143 @@
+// Shared public-access gate for OCL repos.
+//
+// The configured OCL token can see every repo its account has access to, and both
+// discovery (listing crawls) and $resolveReference answer anonymous terminology
+// requests — so a PRIVATE repo the token can see must never be surfaced. OCL repo
+// objects carry `public_access` (`View` | `Edit` | `None`; `None` = private), but
+// the listing endpoints and $resolveReference results do NOT include it, so it is
+// read from a per-repo GET. Results are cached by repoUrl (bounded LRU) and shared
+// between the resolver gate and discovery; a GET error is NOT cached (so a transient
+// blip is retried next time rather than pinning a repo as private), and batch checks
+// run with a concurrency limit.
+//
+// Plain .js (not .cjs): jest's collectCoverageFrom globs **/*.js only.
+
+const DEFAULT_CACHE_LIMIT = 5000;
+const DEFAULT_CONCURRENCY = 8;
+
+/**
+ * Whether an OCL repo's public_access makes it publicly viewable. Fail-closed:
+ * anything that is not an explicit public value (incl. null/unknown) is NOT public.
+ */
+function isPublicAccess(value) {
+  const s = String(value == null ? '' : value).trim().toLowerCase();
+  return s === 'view' || s === 'edit';
+}
+
+// Client input ends up in log lines; strip control characters / newlines and cap
+// the length so a crafted reference cannot forge log entries or flood the log.
+function safeForLog(value) {
+  // Matching control characters is the whole point here (we are scrubbing them).
+  // eslint-disable-next-line no-control-regex
+  const s = String(value == null ? '' : value).replace(/[\u0000-\u001f\u007f]+/g, ' ');
+  return s.length > 200 ? `${s.slice(0, 200)}…` : s;
+}
+
+// Run fn over items with at most `limit` in flight; preserves input order.
+async function mapLimit(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const size = Math.max(1, Math.min(limit, items.length));
+  const workers = Array.from({ length: size }, async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await fn(items[index], index);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+class PublicAccessChecker {
+  #httpClient;
+  #logger;
+  #cache = new Map();
+  #cacheLimit;
+  #concurrency;
+
+  /**
+   * @param {object} options
+   * @param {object} options.httpClient - axios instance from createOclHttpClient
+   * @param {object} [options.logger]
+   * @param {number} [options.cacheLimit] - max repoUrls cached (bounded LRU)
+   * @param {number} [options.concurrency] - max concurrent repo GETs in a batch
+   */
+  constructor({ httpClient, logger = console, cacheLimit = DEFAULT_CACHE_LIMIT, concurrency = DEFAULT_CONCURRENCY } = {}) {
+    if (!httpClient) {
+      throw new Error('PublicAccessChecker requires an http client');
+    }
+    this.#httpClient = httpClient;
+    this.#logger = logger;
+    this.#cacheLimit = cacheLimit > 0 ? cacheLimit : DEFAULT_CACHE_LIMIT;
+    this.#concurrency = concurrency > 0 ? concurrency : DEFAULT_CONCURRENCY;
+  }
+
+  #touch(key) {
+    const value = this.#cache.get(key);
+    this.#cache.delete(key);
+    this.#cache.set(key, value);
+    return value;
+  }
+
+  #put(key, value) {
+    if (this.#cache.has(key)) {
+      this.#cache.delete(key);
+    }
+    this.#cache.set(key, value);
+    if (this.#cache.size > this.#cacheLimit) {
+      this.#cache.delete(this.#cache.keys().next().value);
+    }
+  }
+
+  /**
+   * Resolve a repo's public visibility.
+   * @param {string} repoUrl - relative OCL repo path
+   * @param {string|null} [inlineAccess] - public_access if already known (skips the GET)
+   * @returns {Promise<{public: boolean, determined: boolean}>} determined=false when
+   *   the check errored (not cached, so it is retried later).
+   */
+  async check(repoUrl, inlineAccess = null) {
+    if (inlineAccess != null) {
+      return { public: isPublicAccess(inlineAccess), determined: true };
+    }
+    if (!repoUrl || typeof repoUrl !== 'string') {
+      return { public: false, determined: true };
+    }
+    if (this.#cache.has(repoUrl)) {
+      return { public: this.#touch(repoUrl), determined: true };
+    }
+    try {
+      const response = await this.#httpClient.get(repoUrl);
+      const repo = response?.data && typeof response.data === 'object' ? response.data : null;
+      const pub = isPublicAccess(repo ? (repo.public_access ?? repo.publicAccess ?? null) : null);
+      this.#put(repoUrl, pub);
+      return { public: pub, determined: true };
+    } catch (error) {
+      this.#logger.warn(`public_access check failed for ${safeForLog(repoUrl)}: ${safeForLog(error.message)}`);
+      return { public: false, determined: false };
+    }
+  }
+
+  async isPublic(repoUrl, inlineAccess = null) {
+    return (await this.check(repoUrl, inlineAccess)).public;
+  }
+
+  /**
+   * Keep only the repo-like items that are publicly viewable, concurrency-limited.
+   * @param {Array} items
+   * @param {function} [urlOf] - item -> repoUrl
+   * @param {function} [accessOf] - item -> inline public_access (null if not present)
+   */
+  async filterPublic(items, urlOf = (x) => (x && x.url), accessOf = (x) => (x && (x.public_access ?? x.publicAccess ?? null))) {
+    const list = Array.isArray(items) ? items : [];
+    const verdicts = await mapLimit(list, this.#concurrency, (item) => this.isPublic(urlOf(item), accessOf(item)));
+    return list.filter((_, index) => verdicts[index]);
+  }
+}
+
+module.exports = {
+  PublicAccessChecker,
+  isPublicAccess,
+  safeForLog,
+  mapLimit
+};