@atomic-ehr/fhir-canonical-manager 0.0.8 → 0.0.9

package/src/manager/canonical.ts

@@ -0,0 +1,338 @@
+/**
+ * Main CanonicalManager implementation
+ */
+
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import type {
+  Config,
+  CanonicalManager,
+  PackageId,
+  IndexEntry,
+  Resource,
+  Reference,
+  SourceContext,
+  SearchParameter,
+} from '../types';
+import { DEFAULT_REGISTRY } from '../constants';
+import { ensureDir } from '../fs';
+import { installPackages } from '../package';
+import {
+  createCache,
+  saveCacheToDisk,
+  loadCacheFromDisk,
+  computePackageLockHash,
+  type ExtendedCache,
+} from '../cache';
+import { scanDirectory } from '../scanner';
+import { resolveWithContext } from '../resolver';
+import { filterBySmartSearch } from '../search';
+
+export const createCanonicalManager = (config: Config): CanonicalManager => {
+  const { packages, workingDir } = config;
+  // Ensure registry URL ends with /
+  const registry = config.registry
+    ? config.registry.endsWith("/")
+      ? config.registry
+      : `${config.registry}/`
+    : DEFAULT_REGISTRY;
+  const nodeModulesPath = path.join(workingDir, "node_modules");
+  const cacheDir = path.join(workingDir, ".fcm", "cache");
+
+  let cache = createCache();
+  let initialized = false;
+  const searchParamsCache = new Map<string, SearchParameter[]>();
+
+  const ensureInitialized = (): void => {
+    if (!initialized) {
+      throw new Error("CanonicalManager not initialized. Call init() first.");
+    }
+  };
+
+  const init = async (): Promise<void> => {
+    if (initialized) return;
+
+    // Ensure directories exist
+    await ensureDir(workingDir);
+    await ensureDir(cacheDir);
+
+    // Get current package-lock.json hash
+    const currentPackageLockHash = await computePackageLockHash(workingDir);
+
+    // Try to load cache from disk
+    const cachedData = await loadCacheFromDisk(cacheDir);
+
+    // Check if cache is valid (exists and package-lock.json hasn't changed)
+    const cacheValid =
+      cachedData &&
+      cachedData.packageLockHash === currentPackageLockHash &&
+      currentPackageLockHash !== null;
+
+    if (cacheValid) {
+      // Restore cache from disk
+      cache.entries = cachedData.entries;
+      cache.packages = cachedData.packages;
+      Object.entries(cachedData.references).forEach(([id, metadata]) => {
+        cache.referenceManager.set(id, metadata);
+      });
+    } else {
+      // Cache is invalid or doesn't exist - rebuild it
+      if (cachedData && cachedData.packageLockHash !== currentPackageLockHash) {
+        console.log("Package dependencies have changed, rebuilding index...");
+      }
+
+      // Install packages if needed
+      await installPackages(packages, workingDir, registry);
+
+      // Clear cache before scanning
+      cache = createCache();
+
+      // Scan installed packages
+      await scanDirectory(nodeModulesPath, cache);
+
+      // Save cache to disk with current package-lock hash
+      await saveCacheToDisk(cache, cacheDir, workingDir);
+    }
+
+    initialized = true;
+  };
+
+  const destroy = async (): Promise<void> => {
+    cache.entries = {};
+    cache.packages = {};
+    cache.referenceManager.clear();
+    searchParamsCache.clear();
+    initialized = false;
+  };
+
+  const getPackages = async (): Promise<PackageId[]> => {
+    ensureInitialized();
+    return Object.values(cache.packages).map((p) => p.id);
+  };
+
+  const resolveEntry = async (
+    canonicalUrl: string,
+    options?: {
+      package?: string;
+      version?: string;
+      sourceContext?: SourceContext;
+    },
+  ): Promise<IndexEntry> => {
+    ensureInitialized();
+
+    if (options?.sourceContext) {
+      const contextResolved = await resolveWithContext(
+        canonicalUrl,
+        options.sourceContext,
+        cache,
+        resolveEntry,
+      );
+      if (contextResolved) {
+        return contextResolved;
+      }
+    }
+
+    const entries = cache.entries[canonicalUrl] || [];
+
+    if (entries.length === 0) {
+      throw new Error(`Cannot resolve canonical URL: ${canonicalUrl}`);
+    }
+
+    let filtered = [...entries];
+
+    if (options?.package) {
+      filtered = filtered.filter((e) => e.package?.name === options.package);
+    }
+
+    if (options?.version) {
+      filtered = filtered.filter((e) => e.version === options.version);
+    }
+
+    if (filtered.length === 0) {
+      throw new Error(
+        `No matching resource found for ${canonicalUrl} with given options`,
+      );
+    }
+
+    return filtered[0]!;
+  };
+
+  const resolve = async (
+    canonicalUrl: string,
+    options?: {
+      package?: string;
+      version?: string;
+      sourceContext?: SourceContext;
+    },
+  ): Promise<Resource> => {
+    const entry = await resolveEntry(canonicalUrl, options);
+    return read(entry);
+  };
+
+  const read = async (reference: Reference): Promise<Resource> => {
+    ensureInitialized();
+
+    const metadata = cache.referenceManager.get(reference.id);
+    if (!metadata) {
+      throw new Error(`Invalid reference ID: ${reference.id}`);
+    }
+
+    try {
+      const content = await fs.readFile(metadata.filePath, "utf-8");
+      const resource = JSON.parse(content);
+
+      return {
+        ...resource,
+        id: reference.id,
+        resourceType: reference.resourceType,
+      };
+    } catch (err) {
+      throw new Error(`Failed to read resource: ${err}`);
+    }
+  };
+
+  const searchEntries = async (params: {
+    kind?: string;
+    url?: string;
+    type?: string;
+    version?: string;
+    package?: PackageId;
+  }): Promise<IndexEntry[]> => {
+    ensureInitialized();
+
+    let results: IndexEntry[] = [];
+
+    if (params.url) {
+      results = cache.entries[params.url] || [];
+    } else {
+      for (const entries of Object.values(cache.entries)) {
+        results.push(...entries);
+      }
+    }
+
+    if (params.kind !== undefined) {
+      results = results.filter((e) => e.kind === params.kind);
+    }
+
+    if (params.type !== undefined) {
+      results = results.filter((e) => e.type === params.type);
+    }
+
+    if (params.version !== undefined) {
+      results = results.filter((e) => e.version === params.version);
+    }
+
+    if (params.package) {
+      const pkg = params.package;
+      results = results.filter(
+        (e) =>
+          e.package?.name === pkg.name && e.package?.version === pkg.version,
+      );
+    }
+
+    return results;
+  };
+
+  const search = async (params: {
+    kind?: string;
+    url?: string;
+    type?: string;
+    version?: string;
+    package?: PackageId;
+  }): Promise<Resource[]> => {
+    const entries = await searchEntries(params);
+    const resources = await Promise.all(entries.map((entry) => read(entry)));
+    return resources;
+  };
+
+  const smartSearch = async (
+    searchTerms: string[],
+    filters?: {
+      resourceType?: string;
+      type?: string;
+      kind?: string;
+      package?: PackageId;
+    },
+  ): Promise<IndexEntry[]> => {
+    ensureInitialized();
+
+    // Start with base search using filters
+    let results = await searchEntries({
+      kind: filters?.kind,
+      package: filters?.package,
+    });
+
+    // Apply resourceType filter
+    if (filters?.resourceType) {
+      results = results.filter(
+        (entry) => entry.resourceType === filters.resourceType,
+      );
+    }
+
+    // Apply type filter
+    if (filters?.type) {
+      results = results.filter((entry) => entry.type === filters.type);
+    }
+
+    // Apply smart search filtering
+    return filterBySmartSearch(results, searchTerms);
+  };
+
+  const getSearchParametersForResource = async (
+    resourceType: string
+  ): Promise<SearchParameter[]> => {
+    ensureInitialized();
+    
+    // Check cache first
+    if (searchParamsCache.has(resourceType)) {
+      return searchParamsCache.get(resourceType)!;
+    }
+    
+    // Query all SearchParameter resources
+    // Note: We search by resourceType, not type, because for SearchParameter resources,
+    // 'type' refers to the search parameter type (token, string, etc.)
+    const allEntries = await searchEntries({});
+    const searchParamEntries = allEntries.filter(
+      entry => entry.resourceType === 'SearchParameter'
+    );
+    
+    const results: SearchParameter[] = [];
+    
+    for (const entry of searchParamEntries) {
+      const resource = await read(entry);
+      
+      // Check if this parameter applies to the requested resource
+      const bases = resource.base || [];
+      if (Array.isArray(bases) && bases.includes(resourceType)) {
+        // Return the full original resource - it already contains all fields
+        // Cast through unknown to satisfy TypeScript
+        results.push(resource as unknown as SearchParameter);
+      }
+    }
+    
+    // Sort by code for consistent output
+    results.sort((a, b) => {
+      const codeA = a.code || '';
+      const codeB = b.code || '';
+      return codeA.localeCompare(codeB);
+    });
+    
+    // Cache the results
+    searchParamsCache.set(resourceType, results);
+    
+    return results;
+  };
+
+  return {
+    init,
+    destroy,
+    packages: getPackages,
+    resolveEntry,
+    resolve,
+    read,
+    searchEntries,
+    search,
+    smartSearch,
+    getSearchParametersForResource,
+  };
+};

package/src/manager/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Manager module exports
+ */
+
+export { createCanonicalManager } from './canonical';
+
+// For backward compatibility
+export { createCanonicalManager as CanonicalManager } from './canonical';

package/src/package/detector.ts

@@ -0,0 +1,24 @@
+/**
+ * Package manager detection
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+export async function detectPackageManager(): Promise<"bun" | "npm" | null> {
+  try {
+    // Check for bun first
+    await execAsync("bun --version");
+    return "bun";
+  } catch {
+    try {
+      // Fall back to npm
+      await execAsync("npm --version");
+      return "npm";
+    } catch {
+      return null;
+    }
+  }
+}

package/src/package/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Package management exports
+ */
+
+export { detectPackageManager } from './detector';
+export { installPackages } from './installer';

package/src/package/installer.ts

@@ -0,0 +1,77 @@
+/**
+ * Package installation functionality
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { ensureDir, fileExists } from '../fs';
+import { detectPackageManager } from './detector';
+
+const execAsync = promisify(exec);
+
+export const installPackages = async (
+  packages: string[],
+  workingDir: string,
+  registry?: string,
+): Promise<void> => {
+  await ensureDir(workingDir);
+
+  // Check if package.json exists
+  const packageJsonPath = path.join(workingDir, "package.json");
+  if (!(await fileExists(packageJsonPath))) {
+    // Create minimal package.json
+    const minimalPackageJson = {
+      name: "fhir-canonical-manager-workspace",
+      version: "1.0.0",
+      private: true,
+      dependencies: {},
+    };
+    await fs.writeFile(
+      packageJsonPath,
+      JSON.stringify(minimalPackageJson, null, 2),
+    );
+  }
+
+  // Detect available package manager
+  const packageManager = await detectPackageManager();
+  if (!packageManager) {
+    throw new Error("No package manager found. Please install npm or bun.");
+  }
+
+  // Install packages
+  for (const pkg of packages) {
+    try {
+      if (packageManager === "bun") {
+        // Use bun with auth bypass trick for FHIR registry
+        const env = {
+          ...process.env,
+          HOME: workingDir, // Prevent reading user's .npmrc
+          NPM_CONFIG_USERCONFIG: "/dev/null", // Extra safety
+        };
+
+        const cmd = registry
+          ? `cd ${workingDir} && bun add ${pkg} --registry ${registry}`
+          : `cd ${workingDir} && bun add ${pkg}`;
+
+        await execAsync(cmd, {
+          env,
+          maxBuffer: 10 * 1024 * 1024, // 10MB buffer
+        });
+      } else {
+        // Use npm (handles auth correctly)
+        const cmd = registry
+          ? `cd ${workingDir} && npm add ${pkg} --registry ${registry}`
+          : `cd ${workingDir} && npm add ${pkg}`;
+
+        await execAsync(cmd, {
+          maxBuffer: 10 * 1024 * 1024, // 10MB buffer
+        });
+      }
+    } catch (err) {
+      console.error(`Failed to install package ${pkg}:`, err);
+      throw err;
+    }
+  }
+};

package/src/reference/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Reference management exports
+ */
+
+export { generateReferenceId } from './store';
+export { createReferenceManager } from './manager';
+export type { ReferenceManager } from './manager';
+
+// For backward compatibility - function alias (will be deprecated)
+export { createReferenceManager as ReferenceManagerFactory } from './manager';

package/src/reference/manager.ts

@@ -0,0 +1,51 @@
+/**
+ * Reference manager factory
+ */
+
+import type { Reference, ReferenceMetadata, ReferenceStore } from '../types';
+import { generateReferenceId } from './store';
+
+export interface ReferenceManager extends ReferenceStore {
+  generateId: typeof generateReferenceId;
+  getIdsByUrl: (url: string) => string[];
+  createReference: (id: string, metadata: ReferenceMetadata) => Reference;
+  getAllReferences: () => Record<string, ReferenceMetadata>;
+}
+
+export const createReferenceManager = (): ReferenceManager => {
+  const references: Record<string, ReferenceMetadata> = {};
+  const urlToIds: Record<string, string[]> = {};
+
+  const set = (id: string, metadata: ReferenceMetadata): void => {
+    references[id] = metadata;
+    if (metadata.url) {
+      if (!urlToIds[metadata.url]) {
+        urlToIds[metadata.url] = [];
+      }
+      const ids = urlToIds[metadata.url];
+      if (ids && !ids.includes(id)) {
+        ids.push(id);
+      }
+    }
+  };
+
+  const clear = (): void => {
+    Object.keys(references).forEach((key) => delete references[key]);
+    Object.keys(urlToIds).forEach((key) => delete urlToIds[key]);
+  };
+
+  return {
+    generateId: generateReferenceId,
+    get: (id: string) => references[id],
+    set,
+    has: (id: string) => id in references,
+    clear,
+    size: () => Object.keys(references).length,
+    getIdsByUrl: (url: string) => urlToIds[url] || [],
+    createReference: (id: string, metadata: ReferenceMetadata): Reference => ({
+      id,
+      resourceType: metadata.resourceType,
+    }),
+    getAllReferences: () => references,
+  };
+};

package/src/reference/store.ts

@@ -0,0 +1,15 @@
+/**
+ * Reference store implementation
+ */
+
+import { createHash } from 'crypto';
+import type { ReferenceMetadata, ReferenceStore } from '../types';
+
+export const generateReferenceId = (metadata: {
+  packageName: string;
+  packageVersion: string;
+  filePath: string;
+}): string => {
+  const input = `${metadata.packageName}@${metadata.packageVersion}:${metadata.filePath}`;
+  return createHash("sha256").update(input).digest("base64url");
+};

package/src/resolver/context.ts

@@ -0,0 +1,25 @@
+/**
+ * Context-aware resolution functionality
+ */
+
+import type { SourceContext, IndexEntry } from '../types';
+import type { ExtendedCache } from '../cache/core';
+
+export const resolveWithContext = async (
+  url: string,
+  context: SourceContext,
+  cache: ExtendedCache,
+  resolveEntry: (url: string, options?: any) => Promise<IndexEntry>,
+): Promise<IndexEntry | null> => {
+  if (context.package) {
+    try {
+      return await resolveEntry(url, {
+        package: context.package.name,
+        version: context.package.version,
+      });
+    } catch {
+      // Fall through to global resolution
+    }
+  }
+  return null;
+};

package/src/resolver/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Resolver module exports
+ */
+
+export { resolveWithContext } from './context';

package/src/scanner/directory.ts

@@ -0,0 +1,42 @@
+/**
+ * Directory scanning functionality
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import type { ExtendedCache } from '../cache/core';
+import { isFhirPackage } from '../fs';
+import { scanPackage } from './package';
+
+export const scanDirectory = async (
+  dirPath: string,
+  cache: ExtendedCache,
+): Promise<void> => {
+  try {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const fullPath = path.join(dirPath, entry.name);
+
+      if (entry.name.startsWith("@")) {
+        const scopedEntries = await fs.readdir(fullPath, {
+          withFileTypes: true,
+        });
+        for (const scopedEntry of scopedEntries) {
+          if (!scopedEntry.isDirectory()) continue;
+
+          const scopedPath = path.join(fullPath, scopedEntry.name);
+          if (await isFhirPackage(scopedPath)) {
+            await scanPackage(scopedPath, cache);
+          }
+        }
+      } else if (await isFhirPackage(fullPath)) {
+        await scanPackage(fullPath, cache);
+      }
+    }
+  } catch {
+    // Silently ignore scan errors
+  }
+};

package/src/scanner/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Scanner module exports
+ */
+
+export { parseIndex, isValidFileEntry, isValidIndexFile } from './parser';
+export { processIndex } from './processor';
+export { scanPackage } from './package';
+export { scanDirectory } from './directory';

package/src/scanner/package.ts

@@ -0,0 +1,38 @@
+/**
+ * Package scanning functionality
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import type { PackageJson, PackageInfo } from '../types';
+import type { ExtendedCache } from '../cache/core';
+import { fileExists } from '../fs';
+import { processIndex } from './processor';
+
+export const scanPackage = async (
+  packagePath: string,
+  cache: ExtendedCache,
+): Promise<void> => {
+  try {
+    const packageJsonPath = path.join(packagePath, "package.json");
+    const packageJsonContent = await fs.readFile(packageJsonPath, "utf-8");
+    const packageJson: PackageJson = JSON.parse(packageJsonContent);
+
+    const packageInfo: PackageInfo = {
+      id: { name: packageJson.name, version: packageJson.version },
+      path: packagePath,
+      canonical: packageJson.canonical,
+      fhirVersions: packageJson.fhirVersions,
+    };
+    cache.packages[packageJson.name] = packageInfo;
+
+    await processIndex(packagePath, packageJson, cache);
+
+    const examplesPath = path.join(packagePath, "examples");
+    if (await fileExists(path.join(examplesPath, ".index.json"))) {
+      await processIndex(examplesPath, packageJson, cache);
+    }
+  } catch {
+    // Silently ignore package scan errors
+  }
+};

package/src/scanner/parser.ts

@@ -0,0 +1,42 @@
+/**
+ * Index file parsing and validation
+ */
+
+import type { IndexFile, IndexFileEntry } from '../types';
+
+export const isValidFileEntry = (entry: any): boolean => {
+  if (!entry || typeof entry !== "object") return false;
+  if (!entry.filename || typeof entry.filename !== "string") return false;
+  if (!entry.resourceType || typeof entry.resourceType !== "string")
+    return false;
+  if (!entry.id || typeof entry.id !== "string") return false;
+
+  const optionalStringFields = ["url", "version", "kind", "type"];
+  for (const field of optionalStringFields) {
+    if (entry[field] !== undefined && typeof entry[field] !== "string") {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+export const isValidIndexFile = (data: any): boolean => {
+  if (!data || typeof data !== "object") return false;
+  if (!data["index-version"] || typeof data["index-version"] !== "number")
+    return false;
+  if (!Array.isArray(data.files)) return false;
+  return data.files.every((file: any) => isValidFileEntry(file));
+};
+
+export const parseIndex = (content: string, filePath: string): IndexFile | null => {
+  try {
+    const data = JSON.parse(content);
+    if (!isValidIndexFile(data)) {
+      return null;
+    }
+    return data as IndexFile;
+  } catch {
+    return null;
+  }
+};