anz-legislation 1.2.1

package/dist/providers/plugin-loader.js

@@ -0,0 +1,219 @@
+/**
+ * Plugin Loader
+ *
+ * Dynamically loads and registers jurisdiction plugins.
+ * Supports both official and community plugins.
+ */
+import { ProviderRegistry } from '../providers/legislation-provider.js';
+import { CompatibilityMatrix } from '../utils/compatibility-matrix.js';
+export class PluginLoader {
+    registry;
+    compatibilityMatrix;
+    loadedPlugins = new Map();
+    coreVersion;
+    constructor(coreVersion, registry) {
+        this.coreVersion = coreVersion;
+        this.registry = registry ?? new ProviderRegistry();
+        this.compatibilityMatrix = new CompatibilityMatrix(coreVersion);
+    }
+    /**
+     * Load a plugin from path
+     */
+    async loadPlugin(pluginPath) {
+        try {
+            // Import plugin module
+            const module = await import(pluginPath);
+            // Get manifest
+            const manifest = module.default?.manifest ?? module.manifest;
+            if (!manifest) {
+                throw new Error('Plugin manifest not found');
+            }
+            // Verify plugin integrity (trust official plugins, warn on community)
+            if (manifest.pluginType === 'community') {
+                console.warn(`⚠️  Loading community plugin: ${manifest.name}. Ensure you trust the source.`);
+            }
+            // Check compatibility
+            this.compatibilityMatrix.register({
+                name: manifest.name,
+                version: manifest.version,
+                requires: {
+                    core: manifest.peerDependencies['nz-legislation-tool'] ?? '*',
+                },
+            });
+            if (!this.compatibilityMatrix.check(manifest.name, manifest.version)) {
+                throw new Error(`Plugin ${manifest.name}@${manifest.version} is not compatible with core v${this.coreVersion}`);
+            }
+            // Get provider class and instantiate
+            const ProviderClass = module[manifest.provider] ?? module.default;
+            if (!ProviderClass) {
+                throw new Error(`Provider class "${manifest.provider}" not found in plugin`);
+            }
+            const provider = new ProviderClass();
+            // Verify provider implements interface
+            if (!this.isValidProvider(provider)) {
+                throw new Error('Plugin does not implement LegislationProvider interface');
+            }
+            // Register provider
+            this.registry.register(provider);
+            // Store loaded plugin
+            const loadedPlugin = {
+                manifest,
+                provider,
+                loaded: true,
+            };
+            this.loadedPlugins.set(manifest.name, loadedPlugin);
+            console.log(`✅ Plugin loaded: ${manifest.name}@${manifest.version}`);
+            return loadedPlugin;
+        }
+        catch (error) {
+            const loadedPlugin = {
+                manifest: {
+                    name: pluginPath,
+                    version: 'unknown',
+                    main: '',
+                    provider: '',
+                    peerDependencies: {},
+                    pluginType: 'community',
+                    pluginStatus: 'alpha',
+                },
+                provider: null,
+                loaded: false,
+                error: error instanceof Error ? error : new Error(String(error)),
+            };
+            this.loadedPlugins.set(pluginPath, loadedPlugin);
+            console.error(`❌ Failed to load plugin: ${pluginPath}`);
+            console.error(`   Error: ${error instanceof Error ? error.message : String(error)}`);
+            return loadedPlugin;
+        }
+    }
+    /**
+     * Load multiple plugins in parallel
+     */
+    async loadPlugins(pluginPaths) {
+        const results = await Promise.allSettled(pluginPaths.map(path => this.loadPlugin(path)));
+        return results
+            .filter((r) => r.status === 'fulfilled')
+            .map(r => r.value);
+    }
+    /**
+     * Auto-discover plugins from directory
+     */
+    async discoverPlugins(directory) {
+        const plugins = [];
+        try {
+            const fs = await import('fs');
+            const path = await import('path');
+            if (!fs.existsSync(directory)) {
+                console.debug(`Plugin directory not found: ${directory}`);
+                return plugins;
+            }
+            const files = fs.readdirSync(directory);
+            for (const file of files) {
+                if (file.startsWith('@')) {
+                    // Scoped package directory
+                    const scopeDir = path.join(directory, file);
+                    const scopedPlugins = await this.discoverPlugins(scopeDir);
+                    plugins.push(...scopedPlugins.map(p => path.join(file, p)));
+                }
+                else if (file.startsWith('nz-legislation-') || file.startsWith('legislation-')) {
+                    // Plugin directory
+                    plugins.push(file);
+                }
+            }
+            console.log(`🔍 Discovered ${plugins.length} potential plugins in ${directory}`);
+        }
+        catch (error) {
+            console.error('Error discovering plugins:', error);
+        }
+        return plugins;
+    }
+    /**
+     * Get loaded plugin
+     */
+    getPlugin(name) {
+        return this.loadedPlugins.get(name);
+    }
+    /**
+     * Get all loaded plugins
+     */
+    getLoadedPlugins() {
+        return Array.from(this.loadedPlugins.values());
+    }
+    /**
+     * Get registry
+     */
+    getRegistry() {
+        return this.registry;
+    }
+    /**
+     * Get compatibility matrix
+     */
+    getCompatibilityMatrix() {
+        return this.compatibilityMatrix;
+    }
+    /**
+     * Unload plugin
+     */
+    unloadPlugin(name) {
+        const plugin = this.loadedPlugins.get(name);
+        if (plugin) {
+            // Note: In Node.js, we can't truly unload modules, but we can remove from registry
+            this.loadedPlugins.delete(name);
+            console.log(`Plugin unloaded: ${name}`);
+        }
+    }
+    /**
+     * Get plugin status report
+     */
+    getStatusReport() {
+        const plugins = this.getLoadedPlugins().map(p => ({
+            name: p.manifest.name,
+            version: p.manifest.version,
+            loaded: p.loaded,
+            error: p.error?.message,
+        }));
+        return {
+            coreVersion: this.coreVersion,
+            totalPlugins: plugins.length,
+            loaded: plugins.filter(p => p.loaded).length,
+            failed: plugins.filter(p => !p.loaded).length,
+            plugins,
+        };
+    }
+    /**
+     * Validate provider implements interface
+     */
+    isValidProvider(obj) {
+        return (typeof obj.getJurisdiction === 'function' &&
+            typeof obj.getDisplayName === 'function' &&
+            typeof obj.search === 'function' &&
+            typeof obj.getWork === 'function' &&
+            typeof obj.healthCheck === 'function');
+    }
+}
+/**
+ * Create global plugin loader instance
+ */
+let globalPluginLoader = null;
+export function getGlobalPluginLoader(coreVersion) {
+    if (!globalPluginLoader) {
+        globalPluginLoader = new PluginLoader(coreVersion);
+    }
+    return globalPluginLoader;
+}
+/**
+ * CLI helper for plugin status
+ */
+export function formatPluginStatus(report) {
+    const lines = [
+        `Plugin Status (Core v${report.coreVersion})`,
+        `Total: ${report.totalPlugins} | Loaded: ${report.loaded} | Failed: ${report.failed}`,
+        '',
+    ];
+    for (const plugin of report.plugins) {
+        const icon = plugin.loaded ? '✅' : '❌';
+        const error = plugin.error ? ` - ${plugin.error}` : '';
+        lines.push(`  ${icon} ${plugin.name}@${plugin.version}${error}`);
+    }
+    return lines.join('\n');
+}

package/dist/providers/queensland-provider.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Queensland Legislation Provider
+ *
+ * Provides access to Queensland legislation via the official API at
+ * https://api.legislation.qld.gov.au/
+ */
+import { BaseLegislationProvider } from './legislation-provider.js';
+import type { SearchParams, SearchResults, Work, VersionSummary, CitationStyle } from './legislation-provider.js';
+export declare class QueenslandProvider extends BaseLegislationProvider {
+    private baseUrl;
+    private apiKey?;
+    constructor(apiKey?: string);
+    /**
+     * Search Queensland legislation
+     */
+    protected searchImpl(params: SearchParams): Promise<SearchResults>;
+    /**
+     * Get work by ID
+     */
+    protected getWorkImpl(workId: string): Promise<Work>;
+    /**
+     * Get versions of a work
+     */
+    protected getVersionsImpl(_workId: string): Promise<VersionSummary[]>;
+    /**
+     * Get specific version
+     */
+    protected getVersionImpl(_versionId: string): Promise<Work>;
+    /**
+     * Health check
+     */
+    healthCheck(): Promise<void>;
+    /**
+     * Custom citation generation for Queensland
+     */
+    getCitation(work: Work, style: CitationStyle): string;
+    /**
+     * Ensure API key is present for authenticated requests
+     */
+    private ensureAuthenticated;
+}
+export default QueenslandProvider;

package/dist/providers/queensland-provider.js

@@ -0,0 +1,105 @@
+/**
+ * Queensland Legislation Provider
+ *
+ * Provides access to Queensland legislation via the official API at
+ * https://api.legislation.qld.gov.au/
+ */
+import { logger } from '../utils/logger.js';
+import { BaseLegislationProvider } from './legislation-provider.js';
+import { normalizeWorkType, parseWorkIdMetadata } from './output-adapters.js';
+export class QueenslandProvider extends BaseLegislationProvider {
+    baseUrl = 'https://api.legislation.qld.gov.au/v1';
+    apiKey;
+    constructor(apiKey) {
+        super('au-qld', 'Queensland', { requests: 30, per: 60 }, // 30 requests per minute
+        { max: 500, ttl: 24 * 60 * 60 * 1000 } // 500 entries, 24 hour TTL
+        );
+        this.apiKey = apiKey;
+    }
+    /**
+     * Search Queensland legislation
+     */
+    searchImpl(params) {
+        this.ensureAuthenticated();
+        // Implementation for the official QLD API search is currently in development.
+        logger.debug('Searching Queensland legislation', { params });
+        return Promise.reject(new Error('Queensland search is currently in development. Please use direct ID retrieval with "nzlegislation get <id> --jurisdiction au-qld".'));
+    }
+    /**
+     * Get work by ID
+     */
+    getWorkImpl(workId) {
+        this.ensureAuthenticated();
+        // Implementation for retrieving a specific work from QLD API
+        // e.g., GET /v1/content('{id}')
+        const metadata = parseWorkIdMetadata(workId);
+        return Promise.resolve({
+            ...metadata,
+            work_id: workId,
+            title: `${normalizeWorkType(metadata.type)} ${metadata.year} (Qld)`,
+            type: normalizeWorkType(metadata.type),
+            jurisdiction: 'au-qld',
+            status: 'in-force',
+            date: `${metadata.year || 1900}-01-01`,
+            url: `https://www.legislation.qld.gov.au/view/html/inforce/current/${workId.replace(/\//g, '-')}`,
+            versionCount: 1,
+            versions: [],
+            citations: {
+                australian: `${normalizeWorkType(metadata.type)} ${metadata.year} (Qld)`,
+            },
+        });
+    }
+    /**
+     * Get versions of a work
+     */
+    getVersionsImpl(_workId) {
+        this.ensureAuthenticated();
+        return Promise.resolve([]);
+    }
+    /**
+     * Get specific version
+     */
+    getVersionImpl(_versionId) {
+        this.ensureAuthenticated();
+        return Promise.reject(new Error('Not implemented - scraper pending'));
+    }
+    /**
+     * Health check
+     */
+    async healthCheck() {
+        // Check if Queensland legislation API is accessible
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 5000);
+        try {
+            const response = await fetch(`${this.baseUrl}/health`, {
+                signal: controller.signal,
+                method: 'HEAD',
+            });
+            if (!response.ok && response.status !== 401) {
+                // 401 is fine for health check if we lack key
+                throw new Error(`Health check failed with status ${response.status}`);
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Custom citation generation for Queensland
+     */
+    getCitation(work, style) {
+        if (style === 'australian') {
+            return `${work.title} (Qld)`;
+        }
+        return super.getCitation(work, style);
+    }
+    /**
+     * Ensure API key is present for authenticated requests
+     */
+    ensureAuthenticated() {
+        if (!this.apiKey) {
+            throw new Error('Queensland API key is required. Please set QUEENSLAND_API_KEY.');
+        }
+    }
+}
+export default QueenslandProvider;

package/dist/utils/api-optimization.d.ts

@@ -0,0 +1,92 @@
+/**
+ * API Call Optimization Utilities
+ *
+ * Provides connection pooling, retry strategies, request deduplication,
+ * and payload optimization for improved API performance.
+ */
+import { EventEmitter } from 'events';
+type SearchParamValue = string | number | boolean | null | undefined;
+type SearchParams = Record<string, SearchParamValue>;
+interface RequestOptions {
+    searchParams?: SearchParams;
+}
+interface DeduplicationStats {
+    pendingRequests: number;
+    recentRequests: number;
+}
+/**
+ * Connection pool configuration
+ */
+export interface ConnectionPoolConfig {
+    maxSockets?: number;
+    maxFreeSockets?: number;
+    timeout?: number;
+    keepAlive?: boolean;
+}
+/**
+ * Retry configuration
+ */
+export interface RetryConfig {
+    maxRetries?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    retryableStatusCodes?: number[];
+    retryableMethods?: string[];
+}
+/**
+ * Request deduplication configuration
+ */
+export interface DeduplicationConfig {
+    enabled?: boolean;
+    windowMs?: number;
+}
+/**
+ * Optimized API client options
+ */
+export interface OptimizedClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    pool?: ConnectionPoolConfig;
+    retry?: RetryConfig;
+    deduplication?: DeduplicationConfig;
+}
+/**
+ * Request metrics
+ */
+export interface RequestMetrics {
+    totalRequests: number;
+    successfulRequests: number;
+    failedRequests: number;
+    retriedRequests: number;
+    deduplicatedRequests: number;
+    averageResponseTime: number;
+    p95ResponseTime: number;
+    p99ResponseTime: number;
+}
+export declare class OptimizedApiClient extends EventEmitter {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly pool;
+    private readonly retryManager;
+    private readonly deduplicationManager;
+    private metrics;
+    private responseTimes;
+    constructor(options: OptimizedClientOptions);
+    get<T>(endpoint: string, options?: RequestOptions): Promise<T>;
+    private createClient;
+    private executeWithRetry;
+    private trackResponseTime;
+    getMetrics(): RequestMetrics;
+    resetMetrics(): void;
+    getDeduplicationStats(): DeduplicationStats;
+    close(): void;
+}
+export declare class PayloadOptimizer {
+    static compressPayload(data: unknown, fields?: string[]): unknown;
+    private static pickFields;
+    static minify(data: unknown): string;
+    static estimateSize(data: unknown): number;
+    private static isJsonObject;
+}
+export declare function createOptimizedClient(options: OptimizedClientOptions): OptimizedApiClient;
+export {};