Migration

/**
 * BPA Findings Helper
 *
 * Two independent execution paths — the helper picks one based on what the
 * caller configured, never mixes them, and applies the same batching to both:
 *
 *   1. MCP configured (mcpFetcher + projectId)
 *        → first call: fetch all findings from MCP, cache to
 *          `<collectionsDir>/mcp/<projectId>/<pattern>.json`.
 *        → subsequent calls: read that cache.
 *        → every call applies `paginate(...)` and returns one batch.
 *
 *   2. MCP not configured, CSV path provided (or cached CSV collection exists)
 *        → first call: parse CSV, write the unified-collection JSON to
 *          `<collectionsDir>/unified-collection.json`.
 *        → subsequent calls: read that cache.
 *        → every call applies `paginate(...)` and returns one batch.
 *
 * The two cache locations are disjoint so the paths never shadow each other.
 * Batch size defaults to `DEFAULT_BATCH_SIZE` (5); pass `limit: null` to
 * disable batching.
 */

const path = require('path');
const fs = require('fs');
const {
  hasUnifiedCollection,
  fetchUnifiedBpaFindings,
  getAvailablePatterns,
  getUnifiedCollectionSummary,
  paginate,
  DEFAULT_BATCH_SIZE
} = require('./unified-collection-reader.js');
const { validateBpaFile, parseBpaFile, createUnifiedCollection } = require('./bpa-local-parser.js');

const DEFAULT_COLLECTIONS_DIR = './unified-collections';

/** Path to the MCP cache file for (projectId, pattern). */
function mcpCachePath(collectionsDir, projectId, pattern) {
  return path.join(collectionsDir, 'mcp', projectId, `${pattern}.json`);
}

/** Read a cached MCP fetch from disk; returns `null` if absent or invalid. */
function readMcpCache(collectionsDir, projectId, pattern) {
  const file = mcpCachePath(collectionsDir, projectId, pattern);
  if (!fs.existsSync(file)) return null;
  try {
    return JSON.parse(fs.readFileSync(file, 'utf8'));
  } catch {
    return null;
  }
}

/** Persist an MCP fetch to disk as the read model for subsequent paging. */
function writeMcpCache(collectionsDir, projectId, pattern, environment, targets, mcpMessage) {
  const file = mcpCachePath(collectionsDir, projectId, pattern);
  fs.mkdirSync(path.dirname(file), { recursive: true });
  fs.writeFileSync(file, JSON.stringify({
    source: 'mcp',
    projectId,
    pattern,
    environment,
    fetchedAt: new Date().toISOString(),
    targets,
    ...(mcpMessage ? { mcpMessage } : {})
  }, null, 2));
}

/**
 * Get BPA findings, batched. See module header for the two-path contract.
 *
 * Returns `{ success, source, message, targets, paging, … }` where
 * `paging = { total, returned, offset, limit, nextOffset, hasMore }`.
 */
async function getBpaFindings(pattern = 'all', options = {}) {
  const {
    bpaFilePath,
    collectionsDir = DEFAULT_COLLECTIONS_DIR,
    projectId,
    environment = 'prod',
    mcpFetcher,
    offset = 0,
    limit = DEFAULT_BATCH_SIZE
  } = options;

  // ── Path A: MCP (one fetch per (projectId, pattern), cached, then paged) ──
  if (mcpFetcher && projectId) {
    return getFromMcp({
      pattern, projectId, environment, mcpFetcher, collectionsDir, offset, limit
    });
  }

  // ── Path B: CSV / cached CSV collection ──
  if (bpaFilePath || hasUnifiedCollection(collectionsDir)) {
    return getFromCsvOrCache({
      pattern, bpaFilePath, collectionsDir, offset, limit
    });
  }

  // ── Nothing configured ──
  return {
    success: false,
    source: 'no-source',
    error: 'No BPA findings source available',
    message: 'No BPA data found. Configure MCP (mcpFetcher + projectId) or provide a BPA CSV file path.',
    troubleshooting: [
      'Configure MCP access with mcpFetcher and projectId',
      'Or provide the path to your BPA CSV report',
      'Or point to specific Java files for manual migration'
    ]
  };
}

/**
 * MCP path: first call fetches & caches; subsequent calls read cache.
 * Every call returns exactly one batch.
 */
async function getFromMcp({ pattern, projectId, environment, mcpFetcher, collectionsDir, offset, limit }) {
  let cache = readMcpCache(collectionsDir, projectId, pattern);

  if (!cache) {
    try {
      const mcp = await mcpFetcher({ projectId, pattern, environment });
      if (!mcp || mcp.success === false) {
        return {
          ...(mcp || {}),
          success: false,
          source: 'mcp-server',
          message: `MCP fetch did not succeed (project: ${projectId}).`
        };
      }
      const targets = Array.isArray(mcp.targets) ? mcp.targets : [];
      writeMcpCache(collectionsDir, projectId, pattern, environment, targets, mcp.message);
      cache = readMcpCache(collectionsDir, projectId, pattern);
    } catch (error) {
      return {
        success: false,
        source: 'mcp-error',
        error: `MCP server error: ${error.message}`,
        message: `Could not fetch from MCP server: ${error.message}`,
        troubleshooting: [
          'Check MCP server connectivity',
          'Verify project ID and credentials',
          'Provide a BPA CSV file path as an alternative'
        ]
      };
    }
  }

  const { targets, paging } = paginate(cache.targets, { offset, limit });
  const defaultMessage = `Using MCP cache for project ${projectId} (fetched ${formatTimestamp(cache.fetchedAt)}).`;
  return {
    success: true,
    source: 'mcp-server',
    projectId,
    environment,
    message: (cache.targets.length === 0 && cache.mcpMessage) ? cache.mcpMessage : defaultMessage,
    targets,
    paging
  };
}

/**
 * CSV / cached-collection path: first call parses CSV and writes the unified
 * collection; subsequent calls read it. Every call returns exactly one batch.
 */
function getFromCsvOrCache({ pattern, bpaFilePath, collectionsDir, offset, limit }) {
  // Create the cache on first invocation if it doesn't exist yet.
  if (!hasUnifiedCollection(collectionsDir)) {
    if (!bpaFilePath) {
      return {
        success: false,
        source: 'bpa-file',
        error: 'No BPA CSV path provided and no cached collection exists',
        message: `No cached collection at ${collectionsDir}; provide bpaFilePath to create one.`
      };
    }
    try {
      validateBpaFile(bpaFilePath);
      createUnifiedCollection(parseBpaFile(bpaFilePath), collectionsDir);
    } catch (error) {
      return {
        success: false,
        source: 'bpa-file-error',
        error: `Failed to process BPA file: ${error.message}`,
        message: `Could not process BPA file at ${bpaFilePath}: ${error.message}`,
        troubleshooting: [
          'Verify the file exists and is a valid BPA CSV',
          'Expected CSV headers: code, type, subtype, importance, identifier, message, context'
        ]
      };
    }
  }

  const patterns = getAvailablePatterns(collectionsDir);
  const hasPattern = pattern === 'all' ? patterns.length > 0 : patterns.includes(pattern);
  if (!hasPattern) {
    return {
      success: false,
      source: 'bpa-file',
      error: `Pattern '${pattern}' not found in BPA report`,
      message: `Pattern '${pattern}' not found. Available patterns: ${patterns.join(', ')}`,
      availablePatterns: patterns
    };
  }

  const summary = getUnifiedCollectionSummary(collectionsDir);
  const result = fetchUnifiedBpaFindings(pattern, collectionsDir, { offset, limit });
  result.source = 'bpa-file';
  result.message = `Using CSV collection (${summary?.totalFindings ?? result.paging.total} findings, ${formatTimestamp(summary?.timestamp)}).`;
  return result;
}

/**
 * Check what BPA sources are currently available.
 */
function checkAvailableSources(options = {}) {
  const {
    bpaFilePath,
    collectionsDir = DEFAULT_COLLECTIONS_DIR,
    mcpFetcher,
    projectId
  } = options;

  const sources = {
    unifiedCollection: {
      available: hasUnifiedCollection(collectionsDir),
      patterns: [],
      path: collectionsDir,
      summary: null
    },
    bpaFile: {
      available: false,
      path: bpaFilePath || null
    },
    mcpServer: {
      available: !!(mcpFetcher && projectId),
      projectId: projectId || null,
      cached: !!(projectId && readMcpCache(collectionsDir, projectId, 'all'))
    }
  };

  if (sources.unifiedCollection.available) {
    sources.unifiedCollection.patterns = getAvailablePatterns(collectionsDir);
    sources.unifiedCollection.summary = getUnifiedCollectionSummary(collectionsDir);
  }

  if (bpaFilePath) {
    try {
      validateBpaFile(bpaFilePath);
      sources.bpaFile.available = true;
    } catch (e) {
      sources.bpaFile.available = false;
      sources.bpaFile.error = e.message;
    }
  }

  return sources;
}

/**
 * Format an ISO timestamp into a human-readable relative string.
 */
function formatTimestamp(isoTimestamp) {
  if (!isoTimestamp) return 'unknown date';
  try {
    const date = new Date(isoTimestamp);
    const now = new Date();
    const diffMs = now - date;
    const diffMins = Math.floor(diffMs / 60000);

    if (diffMins < 1) return 'just now';
    if (diffMins < 60) return `${diffMins} minute${diffMins > 1 ? 's' : ''} ago`;
    const diffHours = Math.floor(diffMins / 60);
    if (diffHours < 24) return `${diffHours} hour${diffHours > 1 ? 's' : ''} ago`;
    const diffDays = Math.floor(diffHours / 24);
    return `${diffDays} day${diffDays > 1 ? 's' : ''} ago`;
  } catch {
    return isoTimestamp;
  }
}

/**
 * CLI interface for testing
 *
 * Usage: node bpa-findings-helper.js <pattern> [collectionsDir] [bpaFilePath] [offset] [limit]
 *   offset defaults to 0
 *   limit  defaults to 5 (use 'all' to disable batching)
 */
async function main() {
  const args = process.argv.slice(2);
  const pattern = args[0] || 'all';
  const collectionsDir = args[1] || DEFAULT_COLLECTIONS_DIR;
  const bpaFilePath = args[2];
  const offset = args[3] !== undefined ? Number(args[3]) : 0;
  const limit = args[4] === 'all' ? null
    : args[4] !== undefined ? Number(args[4])
    : DEFAULT_BATCH_SIZE;

  console.log('BPA Findings Helper');
  console.log('==================');
  console.log(`Pattern: ${pattern}`);
  console.log(`Collections Dir: ${collectionsDir}`);
  if (bpaFilePath) console.log(`BPA File: ${bpaFilePath}`);
  console.log(`Offset: ${offset}`);
  console.log(`Limit:  ${limit === null ? 'all' : limit}`);
  console.log('');

  const sources = checkAvailableSources({ collectionsDir, bpaFilePath });

  console.log('Available Sources:');
  console.log(`  Unified Collection: ${sources.unifiedCollection.available ? '✅' : '❌'}`);
  if (sources.unifiedCollection.available) {
    console.log(`    Patterns: ${sources.unifiedCollection.patterns.join(', ')}`);
    console.log(`    Created: ${sources.unifiedCollection.summary?.timestamp || 'unknown'}`);
  }
  console.log(`  BPA File: ${sources.bpaFile.available ? '✅' : '❌'} ${sources.bpaFile.path || '(not provided)'}`);
  console.log(`  MCP Server: ${sources.mcpServer.available ? '✅' : '❌'}`);
  console.log('');

  const result = await getBpaFindings(pattern, { collectionsDir, bpaFilePath, offset, limit });

  console.log(`Source: ${result.source}`);
  console.log(`Message: ${result.message}`);
  console.log('');

  if (result.success) {
    const p = result.paging;
    console.log(p
      ? `✅ Batch ${p.returned}/${p.total} (offset ${p.offset}, next ${p.nextOffset ?? 'none'}, hasMore=${p.hasMore})`
      : `✅ Loaded ${result.targets.length} findings`);
    if (result.summary) {
      Object.entries(result.summary).forEach(([key, value]) => {
        console.log(`   ${key}: ${value}`);
      });
    }
  } else {
    console.error(`❌ ${result.error}`);
    if (result.troubleshooting?.length > 0) {
      console.error('');
      console.error('Troubleshooting:');
      result.troubleshooting.forEach(tip => console.error(`  - ${tip}`));
    }
  }
}

if (require.main === module) {
  main();
}

module.exports = {
  getBpaFindings,
  checkAvailableSources
};

/**
 * Unit tests for BPA findings helper (node --test).
 */
'use strict';

const test = require('node:test');
const assert = require('node:assert/strict');
const fs = require('fs');
const os = require('os');
const path = require('path');
const { getBpaFindings, checkAvailableSources } = require('./bpa-findings-helper.js');
const { paginate, DEFAULT_BATCH_SIZE } = require('./unified-collection-reader.js');

function tempDir() {
  return fs.mkdtempSync(path.join(os.tmpdir(), 'bpa-helper-test-'));
}

const MANY_CSV = path.join(__dirname, 'fixtures', 'many-scheduler-bpa.csv');
const MANY_CSV_TOTAL = 12; // classes in many-scheduler-bpa.csv

test('getBpaFindings with no CSV, collection, or MCP returns no-source', async () => {
  const dir = tempDir();
  const result = await getBpaFindings('scheduler', { collectionsDir: dir });
  assert.equal(result.success, false);
  assert.equal(result.source, 'no-source');
});

test('getBpaFindings uses mcpFetcher when projectId is set', async () => {
  const dir = tempDir();
  const mcpFetcher = async () => ({
    success: true,
    targets: [
      {
        pattern: 'scheduler',
        className: 'com.example.Job',
        identifier: 'org.apache.sling.commons.scheduler',
        issue: 'test'
      }
    ]
  });
  const result = await getBpaFindings('scheduler', {
    collectionsDir: dir,
    projectId: 'proj-1',
    mcpFetcher
  });
  assert.equal(result.success, true);
  assert.equal(result.source, 'mcp-server');
  assert.equal(result.targets.length, 1);
  assert.equal(result.targets[0].className, 'com.example.Job');
});

test('getBpaFindings ingests BPA CSV into empty collections dir', async () => {
  const dir = tempDir();
  const csvPath = path.join(__dirname, 'fixtures', 'minimal-scheduler-bpa.csv');
  const result = await getBpaFindings('scheduler', {
    collectionsDir: dir,
    bpaFilePath: csvPath
  });
  assert.equal(result.success, true);
  assert.equal(result.source, 'bpa-file');
  assert.ok(Array.isArray(result.targets));
  assert.ok(result.targets.length >= 1);
  assert.ok(
    result.targets.some(
      (t) => t.pattern === 'scheduler' && t.className.includes('SampleJob')
    )
  );
});

test('checkAvailableSources reflects MCP only when fetcher and projectId present', () => {
  const dir = tempDir();
  const noMcp = checkAvailableSources({ collectionsDir: dir });
  assert.equal(noMcp.mcpServer.available, false);

  const withMcp = checkAvailableSources({
    collectionsDir: dir,
    mcpFetcher: async () => ({}),
    projectId: 'p'
  });
  assert.equal(withMcp.mcpServer.available, true);
});

// ─────────────────────────────────────────────────────────────
// Batching: pure paginate()
// ─────────────────────────────────────────────────────────────

test('paginate() returns a batch of DEFAULT_BATCH_SIZE by default', () => {
  assert.equal(DEFAULT_BATCH_SIZE, 5);
  const items = Array.from({ length: 12 }, (_, i) => ({ i }));
  const { targets, paging } = paginate(items);
  assert.equal(targets.length, 5);
  assert.deepEqual(paging, {
    total: 12, returned: 5, offset: 0, limit: 5, nextOffset: 5, hasMore: true
  });
});

test('paginate() advances via nextOffset contiguously', () => {
  const items = Array.from({ length: 12 }, (_, i) => ({ i }));
  const seen = [];
  let offset = 0;
  for (let safety = 0; safety < 10; safety++) {
    const { targets, paging } = paginate(items, { offset, limit: 5 });
    for (const it of targets) seen.push(it.i);
    if (!paging.hasMore) break;
    offset = paging.nextOffset;
  }
  assert.deepEqual(seen, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]);
});

test('paginate() handles offset past end without error', () => {
  const { targets, paging } = paginate([{ i: 0 }, { i: 1 }], { offset: 5 });
  assert.equal(targets.length, 0);
  assert.equal(paging.hasMore, false);
  assert.equal(paging.nextOffset, null);
});

test('paginate() with limit=null returns everything', () => {
  const items = Array.from({ length: 12 }, (_, i) => ({ i }));
  const { targets, paging } = paginate(items, { limit: null });
  assert.equal(targets.length, 12);
  assert.equal(paging.hasMore, false);
  assert.equal(paging.limit, null);
});

// ─────────────────────────────────────────────────────────────
// Batching: local BPA CSV path end-to-end
// ─────────────────────────────────────────────────────────────

test('getBpaFindings (CSV path) returns a batch of 5 by default', async () => {
  const dir = tempDir();
  const r = await getBpaFindings('scheduler', {
    collectionsDir: dir,
    bpaFilePath: MANY_CSV
  });
  assert.equal(r.success, true);
  assert.equal(r.source, 'bpa-file');
  assert.equal(r.targets.length, 5);
  assert.ok(r.paging);
  assert.equal(r.paging.total, MANY_CSV_TOTAL);
  assert.equal(r.paging.returned, 5);
  assert.equal(r.paging.offset, 0);
  assert.equal(r.paging.limit, 5);
  assert.equal(r.paging.nextOffset, 5);
  assert.equal(r.paging.hasMore, true);
});

test('CSV path advances by nextOffset with stable contiguous order', async () => {
  const dir = tempDir();

  // First call parses CSV → writes cache → returns first batch.
  const first = await getBpaFindings('scheduler', {
    collectionsDir: dir,
    bpaFilePath: MANY_CSV
  });
  assert.equal(first.source, 'bpa-file');
  assert.equal(first.targets.length, 5);

  // Subsequent calls read the cache — same source, no re-parse.
  const second = await getBpaFindings('scheduler', {
    collectionsDir: dir,
    offset: first.paging.nextOffset
  });
  assert.equal(second.source, 'bpa-file');
  assert.equal(second.targets.length, 5);
  assert.equal(second.paging.offset, 5);
  assert.equal(second.paging.nextOffset, 10);
  assert.equal(second.paging.hasMore, true);

  const third = await getBpaFindings('scheduler', {
    collectionsDir: dir,
    offset: second.paging.nextOffset
  });
  assert.equal(third.source, 'bpa-file');
  assert.equal(third.targets.length, 2);
  assert.equal(third.paging.total, MANY_CSV_TOTAL);
  assert.equal(third.paging.offset, 10);
  assert.equal(third.paging.nextOffset, null);
  assert.equal(third.paging.hasMore, false);

  // No overlap, no gap.
  const allClassNames = [
    ...first.targets,
    ...second.targets,
    ...third.targets
  ].map((t) => t.className);
  assert.equal(new Set(allClassNames).size, allClassNames.length, 'batches must not overlap');
  assert.equal(allClassNames.length, MANY_CSV_TOTAL);
});

test('getBpaFindings (collection path) re-issuing the same offset returns the same batch', async () => {
  const dir = tempDir();
  await getBpaFindings('scheduler', { collectionsDir: dir, bpaFilePath: MANY_CSV });

  const a = await getBpaFindings('scheduler', { collectionsDir: dir, offset: 5 });
  const b = await getBpaFindings('scheduler', { collectionsDir: dir, offset: 5 });
  assert.deepEqual(
    a.targets.map((t) => t.className),
    b.targets.map((t) => t.className),
    'stable ordering: same offset, same batch'
  );
});

test('getBpaFindings (collection path) with limit=null returns every finding', async () => {
  const dir = tempDir();
  await getBpaFindings('scheduler', { collectionsDir: dir, bpaFilePath: MANY_CSV });
  const r = await getBpaFindings('scheduler', { collectionsDir: dir, limit: null });
  assert.equal(r.targets.length, MANY_CSV_TOTAL);
  assert.equal(r.paging.hasMore, false);
  assert.equal(r.paging.limit, null);
});

// ─────────────────────────────────────────────────────────────
// Batching: MCP path (one-shot fetch, cached to disk, paged client-side)
// ─────────────────────────────────────────────────────────────

/** MCP fetcher that returns `total` findings and counts how many times it was called. */
function mkCountingMcpFetcher(total) {
  const fetcher = async (args) => {
    fetcher.calls.push(args);
    return {
      success: true,
      targets: Array.from({ length: total }, (_, i) => ({
        pattern: 'scheduler',
        className: `com.example.Job${String(i).padStart(3, '0')}`,
        identifier: 'org.apache.sling.commons.scheduler',
        issue: 'mcp-test'
      }))
    };
  };
  fetcher.calls = [];
  return fetcher;
}

test('MCP path: first call fetches + caches + returns a batch of 5', async () => {
  const dir = tempDir();
  const mcpFetcher = mkCountingMcpFetcher(12);
  const r = await getBpaFindings('scheduler', {
    collectionsDir: dir,
    projectId: 'proj-A',
    mcpFetcher
  });
  assert.equal(r.success, true);
  assert.equal(r.source, 'mcp-server');
  assert.equal(r.targets.length, 5);
  assert.equal(r.paging.total, 12);
  assert.equal(r.paging.offset, 0);
  assert.equal(r.paging.nextOffset, 5);
  assert.equal(r.paging.hasMore, true);

  // Cache file written in the expected location.
  const cacheFile = path.join(dir, 'mcp', 'proj-A', 'scheduler.json');
  assert.ok(fs.existsSync(cacheFile), 'MCP cache file should exist after first call');
});

test('MCP path: subsequent batches read the cache — mcpFetcher is called once', async () => {
  const dir = tempDir();
  const mcpFetcher = mkCountingMcpFetcher(12);

  // Drive three batches: 5 + 5 + 2.
  const seen = [];
  let offset = 0;
  for (let safety = 0; safety < 10; safety++) {
    const r = await getBpaFindings('scheduler', {
      collectionsDir: dir,
      projectId: 'proj-A',
      mcpFetcher,
      offset
    });
    for (const t of r.targets) seen.push(t.className);
    if (!r.paging.hasMore) break;
    offset = r.paging.nextOffset;
  }

  assert.equal(seen.length, 12);
  assert.equal(new Set(seen).size, 12, 'no duplicates across batches');
  assert.equal(mcpFetcher.calls.length, 1, 'mcpFetcher must be called only once');
});

test('MCP path: mcpFetcher receives projectId/pattern/environment only (no limit/offset)', async () => {
  const dir = tempDir();
  const mcpFetcher = mkCountingMcpFetcher(3);
  await getBpaFindings('scheduler', {
    collectionsDir: dir,
    projectId: 'proj-A',
    environment: 'stage',
    mcpFetcher,
    offset: 10      // user-supplied offset must NOT be forwarded
  });
  assert.equal(mcpFetcher.calls.length, 1);
  const args = mcpFetcher.calls[0];
  assert.equal(args.projectId, 'proj-A');
  assert.equal(args.pattern, 'scheduler');
  assert.equal(args.environment, 'stage');
  assert.equal(args.limit, undefined, 'limit must not be sent to MCP');
  assert.equal(args.offset, undefined, 'offset must not be sent to MCP');
});

test('MCP path is preferred over a pre-existing CSV-derived cache', async () => {
  const dir = tempDir();

  // Seed a CSV-derived cache — simulates a previous CSV session.
  await getBpaFindings('scheduler', { collectionsDir: dir, bpaFilePath: MANY_CSV });

  // Now call with MCP configured; the CSV cache must NOT shadow MCP.
  const mcpFetcher = mkCountingMcpFetcher(3);
  const r = await getBpaFindings('scheduler', {
    collectionsDir: dir,
    projectId: 'proj-A',
    mcpFetcher
  });

  assert.equal(r.source, 'mcp-server');
  assert.equal(r.paging.total, 3, 'must read MCP count, not CSV count');
  assert.equal(mcpFetcher.calls.length, 1);
});

test('MCP cache files are keyed by (projectId, pattern) — different keys do not collide', async () => {
  const dir = tempDir();
  const fA = mkCountingMcpFetcher(3);
  const fB = mkCountingMcpFetcher(7);

  const ra = await getBpaFindings('scheduler', {
    collectionsDir: dir, projectId: 'proj-A', mcpFetcher: fA
  });
  const rb = await getBpaFindings('scheduler', {
    collectionsDir: dir, projectId: 'proj-B', mcpFetcher: fB
  });

  assert.equal(ra.paging.total, 3);
  assert.equal(rb.paging.total, 7);

  // Both caches present.
  assert.ok(fs.existsSync(path.join(dir, 'mcp', 'proj-A', 'scheduler.json')));
  assert.ok(fs.existsSync(path.join(dir, 'mcp', 'proj-B', 'scheduler.json')));
});

test('MCP path: success:true with empty targets propagates message and caches', async () => {
  const dir = tempDir();
  const mcpFetcher = async () => ({
    success: true,
    targets: [],
    summary: { schedulerCount: 0 },
    message: "No 'scheduler' findings in the latest BPA report for project proj-X."
  });
  const r = await getBpaFindings('scheduler', {
    collectionsDir: dir,
    projectId: 'proj-X',
    mcpFetcher
  });
  assert.equal(r.success, true);
  assert.equal(r.source, 'mcp-server');
  assert.equal(r.targets.length, 0);
  assert.equal(r.paging.total, 0);
  assert.equal(r.paging.hasMore, false);
  assert.ok(r.message.includes("No 'scheduler' findings"), 'message should reflect empty pattern result');

  const cacheFile = path.join(dir, 'mcp', 'proj-X', 'scheduler.json');
  assert.ok(fs.existsSync(cacheFile), 'cache file should be written even for empty results');

  // Second call should read cache and not invoke fetcher again.
  let fetcherCalled = false;
  const deadFetcher = async () => { fetcherCalled = true; return { success: true, targets: [] }; };
  const r2 = await getBpaFindings('scheduler', {
    collectionsDir: dir,
    projectId: 'proj-X',
    mcpFetcher: deadFetcher
  });
  assert.equal(fetcherCalled, false, 'fetcher must not be called when cache exists');
  assert.equal(r2.success, true);
  assert.ok(r2.message.includes("No 'scheduler' findings"), 'cached message should persist');
});

test('MCP path: second session reuses the cache across processes (no fetch)', async () => {
  const dir = tempDir();
  const fA = mkCountingMcpFetcher(8);

  // First session — populates the cache.
  await getBpaFindings('scheduler', {
    collectionsDir: dir, projectId: 'proj-A', mcpFetcher: fA
  });
  assert.equal(fA.calls.length, 1);

  // Second session with a "dead" fetcher that should never be called.
  const fDead = async () => {
    throw new Error('mcp fetcher must not be called when cache exists');
  };
  const r = await getBpaFindings('scheduler', {
    collectionsDir: dir, projectId: 'proj-A', mcpFetcher: fDead, offset: 5
  });
  assert.equal(r.success, true);
  assert.equal(r.source, 'mcp-server');
  assert.equal(r.paging.offset, 5);
});

#!/usr/bin/env node

/**
 * BPA Local Parser Script
 * 
 * Reads BPA CSV files from the local filesystem and creates a unified code transformer collection
 * that matches the cloud-adoption-service format.
 * 
 * Usage:
 *   node bpa-local-parser.js <bpa-csv-file-path> [output-directory]
 * 
 * Example:
 *   node bpa-local-parser.js ./cleaned_file6.csv ./unified-collections
 */

const fs = require('fs');
const path = require('path');

// Pattern to subtype mapping (matching cam-bpa-fetcher.ts)
const PATTERN_TO_SUBTYPE = {
  scheduler: "sling.commons.scheduler",
  assetApi: "unsupported.asset.api",
};

// CSV subtype to pattern mapping (based on actual CSV structure)
const CSV_SUBTYPE_TO_PATTERN = {
  "unsupported.asset.api": "assetApi",
  "javax.jcr.observation.EventListener": "eventListener", 
  "org.apache.sling.api.resource.observation.ResourceChangeListener": "resourceChangeListener",
  "org.osgi.service.event.EventHandler": "eventHandler"
};

// Known scheduler identifier
const SCHEDULER_IDENTIFIER = "org.apache.sling.commons.scheduler";

/**
 * Parse command line arguments
 */
function parseArgs() {
  const args = process.argv.slice(2);
  
  if (args.length < 1) {
    console.error('Usage: node bpa-local-parser.js <bpa-csv-file-path> [output-directory]');
    console.error('');
    console.error('Examples:');
    console.error('  node bpa-local-parser.js ./cleaned_file6.csv');
    console.error('  node bpa-local-parser.js ./cleaned_file6.csv ./unified-collections');
    process.exit(1);
  }
  
  return {
    bpaFilePath: args[0],
    outputDir: args[1] || './unified-collections'
  };
}

/**
 * Validate BPA file exists and is readable
 */
function validateBpaFile(filePath) {
  if (!fs.existsSync(filePath)) {
    throw new Error(`BPA file not found: ${filePath}`);
  }
  
  const stats = fs.statSync(filePath);
  if (!stats.isFile()) {
    throw new Error(`Path is not a file: ${filePath}`);
  }
  
  // Check if it's readable
  try {
    fs.accessSync(filePath, fs.constants.R_OK);
  } catch (error) {
    throw new Error(`BPA file is not readable: ${filePath}`);
  }
}

/**
 * Parse CSV line respecting quoted fields
 */
function parseCSVLine(line) {
  const result = [];
  let current = '';
  let inQuotes = false;
  let i = 0;
  
  while (i < line.length) {
    const char = line[i];
    
    if (char === '"') {
      if (inQuotes && line[i + 1] === '"') {
        // Escaped quote
        current += '"';
        i += 2;
      } else {
        // Toggle quote state
        inQuotes = !inQuotes;
        i++;
      }
    } else if (char === ',' && !inQuotes) {
      // Field separator
      result.push(current);
      current = '';
      i++;
    } else {
      current += char;
      i++;
    }
  }
  
  // Add the last field
  result.push(current);
  return result;
}

/**
 * Parse BPA CSV file
 */
function parseBpaFile(filePath) {
  try {
    const content = fs.readFileSync(filePath, 'utf8');
    const lines = content.split('\n').filter(line => line.trim());
    
    if (lines.length === 0) {
      throw new Error('Empty BPA file');
    }
    
    // Parse header
    const headers = parseCSVLine(lines[0]);
    console.log(`CSV Headers: ${headers.join(', ')}`);
    
    // Validate expected headers
    const expectedHeaders = ['code', 'type', 'subtype', 'importance', 'identifier', 'message', 'context'];
    const hasRequiredHeaders = expectedHeaders.every(header => headers.includes(header));
    
    if (!hasRequiredHeaders) {
      console.warn('CSV headers do not match expected format, proceeding with available headers');
    }
    
    // Parse data rows
    const findings = [];
    for (let i = 1; i < lines.length; i++) {
      const values = parseCSVLine(lines[i]);
      if (values.length >= headers.length) {
        const finding = {};
        headers.forEach((header, index) => {
          finding[header] = values[index] || '';
        });
        findings.push(finding);
      }
    }
    
    console.log(`Parsed ${findings.length} findings from CSV`);
    return { findings, headers };
  } catch (error) {
    throw new Error(`Error parsing BPA CSV file: ${error.message}`);
  }
}

/**
 * Extract findings from BPA CSV data
 */
function extractFindings(bpaData) {
  const findings = bpaData.findings || [];
  
  if (findings.length === 0) {
    console.warn('No findings found in BPA CSV data');
    return [];
  }
  
  console.log(`Found ${findings.length} findings in BPA CSV report`);
  return findings;
}

/**
 * Process scheduler findings from CSV
 */
function processSchedulerFindings(findings) {
  const schedulerFindings = findings.filter(finding => 
    finding.subtype === 'sling.commons.scheduler'
  );
  
  const identifiers = {};
  const classNames = [];
  
  schedulerFindings.forEach(finding => {
    // Extract class name from identifier
    const className = extractClassNameFromCsvFinding(finding);
    if (className && !classNames.includes(className)) {
      classNames.push(className);
    }
  });
  
  if (classNames.length > 0) {
    identifiers[SCHEDULER_IDENTIFIER] = classNames;
  }
  
  return {
    subtype: PATTERN_TO_SUBTYPE.scheduler,
    identifiers: identifiers
  };
}

/**
 * Process asset API findings from CSV
 */
function processAssetApiFindings(findings) {
  const assetApiFindings = findings.filter(finding => 
    finding.subtype === 'unsupported.asset.api'
  );
  
  const identifiers = {};
  
  assetApiFindings.forEach(finding => {
    // Extract class name from identifier (full path)
    const className = finding.identifier && isValidClassName(finding.identifier) ? finding.identifier.trim() : null;
    
    // Extract API method from message
    const apiMethod = extractAssetApiMethodFromMessage(finding.message);
    
    if (className && apiMethod) {
      if (!identifiers[apiMethod]) {
        identifiers[apiMethod] = [];
      }
      
      if (!identifiers[apiMethod].includes(className)) {
        identifiers[apiMethod].push(className);
      }
    }
  });
  
  return {
    subtype: PATTERN_TO_SUBTYPE.assetApi,
    identifiers: identifiers
  };
}

/**
 * Returns true if the value is a valid class name (excludes numeric-only values like "1", "4", "10").
 */
function isValidClassName(value) {
  if (!value || typeof value !== 'string') return false;
  const trimmed = value.trim();
  if (!trimmed) return false;
  // Exclude pure numbers (counts, line numbers, etc.)
  if (/^\d+$/.test(trimmed)) return false;
  return true;
}

/**
 * Extract full class identifier from CSV finding (returns complete path, not trimmed).
 */
function extractClassNameFromCsvFinding(finding) {
  // Prefer identifier field - return full path as-is
  if (finding.identifier && isValidClassName(finding.identifier)) {
    return finding.identifier.trim();
  }
  
  // Try to extract from message if identifier is not useful
  if (finding.message) {
    const classMatch = finding.message.match(/class\s+([a-zA-Z0-9_.]+)/);
    if (classMatch) {
      const className = classMatch[1];
      if (isValidClassName(className)) return className;
    }
  }
  
  return finding.identifier && isValidClassName(finding.identifier) ? finding.identifier.trim() : null;
}

/**
 * Extract Asset API method from message
 */
function extractAssetApiMethodFromMessage(message) {
  if (!message) return null;
  
  // Look for specific API methods mentioned in the message
  const apiMethods = [
    'com.day.cq.dam.api.AssetManager.createAsset',
    'com.day.cq.dam.api.AssetManager.removeAssetForBinary',
    'com.day.cq.dam.api.AssetManager.createAssetForBinary'
  ];
  
  for (const method of apiMethods) {
    if (message.includes(method)) {
      return method;
    }
  }
  
  // Generic fallback
  if (message.includes('AssetManager')) {
    return 'com.day.cq.dam.api.AssetManager';
  }
  
  return null;
}

/**
 * Process event listener findings from CSV
 */
function processEventListenerFindings(findings) {
  const eventListenerFindings = findings.filter(finding => 
    finding.subtype === 'javax.jcr.observation.EventListener'
  );
  
  const identifiers = {};
  const classNames = [];
  
  eventListenerFindings.forEach(finding => {
    const className = extractClassNameFromCsvFinding(finding);
    if (className && !classNames.includes(className)) {
      classNames.push(className);
    }
  });
  
  if (classNames.length > 0) {
    identifiers['javax.jcr.observation.EventListener'] = classNames;
  }
  
  return {
    subtype: 'javax.jcr.observation.EventListener',
    identifiers: identifiers
  };
}

/**
 * Process resource change listener findings from CSV
 */
function processResourceChangeListenerFindings(findings) {
  const resourceChangeListenerFindings = findings.filter(finding => 
    finding.subtype === 'org.apache.sling.api.resource.observation.ResourceChangeListener'
  );
  
  const identifiers = {};
  const classNames = [];
  
  resourceChangeListenerFindings.forEach(finding => {
    const className = extractClassNameFromCsvFinding(finding);
    if (className && !classNames.includes(className)) {
      classNames.push(className);
    }
  });
  
  if (classNames.length > 0) {
    identifiers['org.apache.sling.api.resource.observation.ResourceChangeListener'] = classNames;
  }
  
  return {
    subtype: 'org.apache.sling.api.resource.observation.ResourceChangeListener',
    identifiers: identifiers
  };
}

/**
 * Process event handler findings from CSV
 */
function processEventHandlerFindings(findings) {
  const eventHandlerFindings = findings.filter(finding => 
    finding.subtype === 'org.osgi.service.event.EventHandler'
  );
  
  const identifiers = {};
  const classNames = [];
  
  eventHandlerFindings.forEach(finding => {
    const className = extractClassNameFromCsvFinding(finding);
    if (className && !classNames.includes(className)) {
      classNames.push(className);
    }
  });
  
  if (classNames.length > 0) {
    identifiers['org.osgi.service.event.EventHandler'] = classNames;
  }
  
  return {
    subtype: 'org.osgi.service.event.EventHandler',
    identifiers: identifiers
  };
}

/**
 * Convert subtype to MongoDB-safe field name (matching cloud-adoption-service)
 */
function toMongoSafeFieldName(fieldName) {
  return fieldName ? fieldName.replace(/\./g, '_') : null;
}

/**
 * Convert identifier to MongoDB-safe field name (matching cloud-adoption-service)
 */
function toMongoSafeIdentifier(identifier) {
  return identifier ? identifier.replace(/\./g, '_') : null;
}

/**
 * Create unified collection structure (matching cloud-adoption-service format)
 */
function createUnifiedCollection(bpaData, outputDir) {
  const findings = extractFindings(bpaData);
  
  if (findings.length === 0) {
    console.warn('No findings to process');
    return;
  }
  
  // Ensure output directory exists
  if (!fs.existsSync(outputDir)) {
    fs.mkdirSync(outputDir, { recursive: true });
  }
  
  // Initialize unified subtypes structure
  const subtypes = {};
  let totalFindings = 0;
  
  // Process scheduler findings
  const schedulerCollection = processSchedulerFindings(findings);
  if (Object.keys(schedulerCollection.identifiers).length > 0) {
    const mongoSafeSubtype = toMongoSafeFieldName(schedulerCollection.subtype);
    subtypes[mongoSafeSubtype] = {};
    
    Object.entries(schedulerCollection.identifiers).forEach(([identifier, classNames]) => {
      const mongoSafeIdentifier = toMongoSafeIdentifier(identifier);
      subtypes[mongoSafeSubtype][mongoSafeIdentifier] = classNames;
      totalFindings += classNames.length;
    });
    
    console.log(`Found ${Object.values(schedulerCollection.identifiers).flat().length} scheduler classes`);
  }
  
  // Process asset API findings
  const assetApiCollection = processAssetApiFindings(findings);
  if (Object.keys(assetApiCollection.identifiers).length > 0) {
    const mongoSafeSubtype = toMongoSafeFieldName(assetApiCollection.subtype);
    subtypes[mongoSafeSubtype] = {};
    
    Object.entries(assetApiCollection.identifiers).forEach(([identifier, classNames]) => {
      const mongoSafeIdentifier = toMongoSafeIdentifier(identifier);
      subtypes[mongoSafeSubtype][mongoSafeIdentifier] = classNames;
      totalFindings += classNames.length;
    });
    
    console.log(`Found ${Object.values(assetApiCollection.identifiers).flat().length} asset API classes`);
  }
  
  // Process event listener findings
  const eventListenerCollection = processEventListenerFindings(findings);
  if (Object.keys(eventListenerCollection.identifiers).length > 0) {
    const mongoSafeSubtype = toMongoSafeFieldName(eventListenerCollection.subtype);
    subtypes[mongoSafeSubtype] = {};
    
    Object.entries(eventListenerCollection.identifiers).forEach(([identifier, classNames]) => {
      const mongoSafeIdentifier = toMongoSafeIdentifier(identifier);
      subtypes[mongoSafeSubtype][mongoSafeIdentifier] = classNames;
      totalFindings += classNames.length;
    });
    
    console.log(`Found ${Object.values(eventListenerCollection.identifiers).flat().length} event listener classes`);
  }
  
  // Process resource change listener findings
  const resourceChangeListenerCollection = processResourceChangeListenerFindings(findings);
  if (Object.keys(resourceChangeListenerCollection.identifiers).length > 0) {
    const mongoSafeSubtype = toMongoSafeFieldName(resourceChangeListenerCollection.subtype);
    subtypes[mongoSafeSubtype] = {};
    
    Object.entries(resourceChangeListenerCollection.identifiers).forEach(([identifier, classNames]) => {
      const mongoSafeIdentifier = toMongoSafeIdentifier(identifier);
      subtypes[mongoSafeSubtype][mongoSafeIdentifier] = classNames;
      totalFindings += classNames.length;
    });
    
    console.log(`Found ${Object.values(resourceChangeListenerCollection.identifiers).flat().length} resource change listener classes`);
  }
  
  // Process event handler findings
  const eventHandlerCollection = processEventHandlerFindings(findings);
  if (Object.keys(eventHandlerCollection.identifiers).length > 0) {
    const mongoSafeSubtype = toMongoSafeFieldName(eventHandlerCollection.subtype);
    subtypes[mongoSafeSubtype] = {};
    
    Object.entries(eventHandlerCollection.identifiers).forEach(([identifier, classNames]) => {
      const mongoSafeIdentifier = toMongoSafeIdentifier(identifier);
      subtypes[mongoSafeSubtype][mongoSafeIdentifier] = classNames;
      totalFindings += classNames.length;
    });
    
    console.log(`Found ${Object.values(eventHandlerCollection.identifiers).flat().length} event handler classes`);
  }
  
  // Create unified collection structure with metadata
  const subtypeKeys = Object.keys(subtypes);
  const unifiedCollection = {
    subtypes: subtypes,
    meta: {
      timestamp: new Date().toISOString(),
      source: 'local-bpa-parser',
      totalFindings: totalFindings,
      subtypeCount: subtypeKeys.length
    }
  };

  // Write unified collection file
  const unifiedPath = path.join(outputDir, 'unified-collection.json');
  fs.writeFileSync(unifiedPath, JSON.stringify(unifiedCollection, null, 2));
  console.log(`Created unified collection file: ${unifiedPath}`);

  return {
    subtypes: subtypeKeys,
    totalFindings,
    unifiedCollection
  };
}


/**
 * Main function
 */
function main() {
  try {
    const { bpaFilePath, outputDir } = parseArgs();
    
    console.log('BPA Local Parser');
    console.log('================');
    console.log(`BPA File: ${bpaFilePath}`);
    console.log(`Output Directory: ${outputDir}`);
    console.log('Format: Unified (cloud-adoption-service compatible)');
    console.log('');
    
    // Validate input file
    validateBpaFile(bpaFilePath);
    
    // Parse BPA file
    console.log('Parsing BPA CSV file...');
    const bpaData = parseBpaFile(bpaFilePath);
    
    // Create unified collection
    console.log('Creating unified collection...');
    const summary = createUnifiedCollection(bpaData, outputDir);
    
    console.log('');
    console.log('✅ Successfully created unified code transformer collection');
    console.log(`📁 Output directory: ${outputDir}`);
    console.log(`📊 Total subtypes: ${summary?.subtypes?.length || 0}`);
    console.log(`🎯 Total findings: ${summary?.totalFindings || 0}`);
    
    if (summary?.subtypes?.length > 0) {
      console.log('');
      console.log('Available subtypes:');
      summary.subtypes.forEach(subtype => {
        const subtypeData = summary.unifiedCollection?.subtypes?.[subtype];
        const count = subtypeData ? Object.values(subtypeData).flat().length : 0;
        console.log(`  - ${subtype}: ${count} classes`);
      });
    }
    
  } catch (error) {
    console.error('❌ Error:', error.message);
    process.exit(1);
  }
}

// Run the script if called directly
if (require.main === module) {
  main();
}

module.exports = {
  validateBpaFile,
  parseBpaFile,
  createUnifiedCollection,
  extractFindings
};

code,type,subtype,importance,identifier,message,context
BPA-001,issue,sling.commons.scheduler,high,com.example.jobs.Alpha,Uses Apache Sling scheduler in Alpha,
BPA-002,issue,sling.commons.scheduler,high,com.example.jobs.Bravo,Uses Apache Sling scheduler in Bravo,
BPA-003,issue,sling.commons.scheduler,high,com.example.jobs.Charlie,Uses Apache Sling scheduler in Charlie,
BPA-004,issue,sling.commons.scheduler,high,com.example.jobs.Delta,Uses Apache Sling scheduler in Delta,
BPA-005,issue,sling.commons.scheduler,high,com.example.jobs.Echo,Uses Apache Sling scheduler in Echo,
BPA-006,issue,sling.commons.scheduler,high,com.example.jobs.Foxtrot,Uses Apache Sling scheduler in Foxtrot,
BPA-007,issue,sling.commons.scheduler,high,com.example.jobs.Golf,Uses Apache Sling scheduler in Golf,
BPA-008,issue,sling.commons.scheduler,high,com.example.jobs.Hotel,Uses Apache Sling scheduler in Hotel,
BPA-009,issue,sling.commons.scheduler,high,com.example.jobs.India,Uses Apache Sling scheduler in India,
BPA-010,issue,sling.commons.scheduler,high,com.example.jobs.Juliet,Uses Apache Sling scheduler in Juliet,
BPA-011,issue,sling.commons.scheduler,high,com.example.jobs.Kilo,Uses Apache Sling scheduler in Kilo,
BPA-012,issue,sling.commons.scheduler,high,com.example.jobs.Lima,Uses Apache Sling scheduler in Lima,

code,type,subtype,importance,identifier,message,context
BPA-001,issue,sling.commons.scheduler,high,com.example.myapp.jobs.SampleJob,Uses Apache Sling scheduler in SampleJob,

{
  "name": "migration-scripts",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "migration-scripts",
      "version": "1.0.0",
      "engines": {
        "node": ">=14.0.0"
      }
    }
  }
}

{
  "name": "migration-scripts",
  "version": "1.0.0",
  "description": "BPA findings helper and parser for AEM migration skill",
  "scripts": {
    "parse-bpa": "node bpa-local-parser.js",
    "read-unified": "node unified-collection-reader.js",
    "check-sources": "node bpa-findings-helper.js",
    "test": "node --test bpa-findings-helper.test.js"
  },
  "engines": {
    "node": ">=14.0.0"
  }
}

/**
 * Unified Collection Reader
 * 
 * Reads unified code transformer collections (cloud-adoption-service format)
 * and returns data in the same format as the CAM BPA fetcher MCP tool.
 */

const fs = require('fs');
const path = require('path');

// Default batch size for paged access to findings. Keep this in sync with
// the documented batch size in migration/SKILL.md and cam-mcp.md.
const DEFAULT_BATCH_SIZE = 5;

// Pattern to subtype mapping (matching cam-bpa-fetcher.ts)
const PATTERN_TO_SUBTYPE = {
  scheduler: "sling.commons.scheduler",
  assetApi: "unsupported.asset.api",
  eventListener: "javax.jcr.observation.EventListener",
  resourceChangeListener: "org.apache.sling.api.resource.observation.ResourceChangeListener", 
  eventHandler: "org.osgi.service.event.EventHandler"
};

// MongoDB-safe to pattern mapping
const MONGO_SAFE_TO_PATTERN = {
  "sling_commons_scheduler": "scheduler",
  "unsupported_asset_api": "assetApi",
  "javax_jcr_observation_EventListener": "eventListener",
  "org_apache_sling_api_resource_observation_ResourceChangeListener": "resourceChangeListener",
  "org_osgi_service_event_EventHandler": "eventHandler"
};

// Known scheduler identifier
const SCHEDULER_IDENTIFIER = "org.apache.sling.commons.scheduler";

/**
 * BPA Target type (matching cam-bpa-fetcher.ts)
 */
class BpaTarget {
  constructor(pattern, className, identifier, issue, severity = "high") {
    this.pattern = pattern;
    this.className = className;
    this.identifier = identifier;
    this.issue = issue;
    this.severity = severity;
  }
}

/**
 * BPA Result type (matching cam-bpa-fetcher.ts)
 */
class BpaResult {
  constructor(success = false) {
    this.success = success;
    this.environment = 'local';
    this.projectId = 'unified-collection';
    this.targets = [];
    this.summary = {};
    this.message = null;
    this.error = null;
    this.errorDetails = null;
    this.troubleshooting = [];
    this.suggestion = [];
  }
}

/**
 * Convert MongoDB-safe field name back to original format
 */
function fromMongoSafeFieldName(mongoSafeFieldName) {
  return mongoSafeFieldName ? mongoSafeFieldName.replace(/_/g, '.') : null;
}

/**
 * Slice a flat array of findings and return `{ targets, paging }`.
 *
 * Caller must produce `items` in a stable, deterministic order so that
 * incrementing `offset` across calls yields contiguous, non-overlapping batches.
 * `limit: null` disables batching (returns everything).
 */
function paginate(items, { offset = 0, limit = DEFAULT_BATCH_SIZE } = {}) {
  const list = Array.isArray(items) ? items : [];
  const total = list.length;
  const start = Math.max(0, Math.floor(Number(offset)) || 0);
  const unbounded = limit === null;
  const size = unbounded ? total : Math.max(1, Math.floor(Number(limit)) || DEFAULT_BATCH_SIZE);
  const targets = list.slice(start, unbounded ? total : start + size);
  const reached = start + targets.length;
  const nextOffset = reached < total ? reached : null;
  return {
    targets,
    paging: {
      total,
      returned: targets.length,
      offset: start,
      limit: unbounded ? null : size,
      nextOffset,
      hasMore: nextOffset !== null
    }
  };
}

/**
 * Check if unified collection exists
 */
function hasUnifiedCollection(collectionsDir = './unified-collections') {
  const unifiedPath = path.join(collectionsDir, 'unified-collection.json');
  try {
    return fs.existsSync(unifiedPath) && fs.statSync(unifiedPath).isFile();
  } catch (error) {
    return false;
  }
}

/**
 * Get available patterns in unified collection
 */
function getAvailablePatterns(collectionsDir = './unified-collections') {
  if (!hasUnifiedCollection(collectionsDir)) {
    return [];
  }
  
  try {
    const unifiedCollection = readUnifiedCollection(collectionsDir);
    if (!unifiedCollection || !unifiedCollection.subtypes) {
      return [];
    }
    
    const patterns = Object.keys(unifiedCollection.subtypes)
      .map(mongoSafeSubtype => MONGO_SAFE_TO_PATTERN[mongoSafeSubtype])
      .filter(pattern => pattern);
    
    return patterns;
  } catch (error) {
    console.error('Error reading unified collection:', error.message);
    return [];
  }
}

/**
 * Read unified collection file
 */
function readUnifiedCollection(collectionsDir = './unified-collections') {
  const unifiedPath = path.join(collectionsDir, 'unified-collection.json');
  
  if (!fs.existsSync(unifiedPath)) {
    return null;
  }
  
  try {
    const content = fs.readFileSync(unifiedPath, 'utf8');
    return JSON.parse(content);
  } catch (error) {
    console.error('Error reading unified collection:', error.message);
    return null;
  }
}

/**
 * Process scheduler data from unified collection
 */
function processSchedulerFromUnified(subtypeData, targets) {
  let count = 0;
  
  // Sort identifiers alphabetically so the iteration order is deterministic
  // across runs, independent of how the unified-collection JSON was written.
  const identifierKeys = Object.keys(subtypeData || {}).sort();
  for (const mongoSafeIdentifier of identifierKeys) {
    const classNames = subtypeData[mongoSafeIdentifier] || [];
    const identifier = fromMongoSafeFieldName(mongoSafeIdentifier);
    
    for (const className of classNames) {
      count++;
      targets.push(new BpaTarget(
        "scheduler",
        className,
        identifier,
        "Uses imperative Scheduler API instead of declarative @SlingScheduled annotation",
        "high"
      ));
    }
  }
  
  return count;
}

/**
 * Process asset API data from unified collection
 */
function processAssetApiFromUnified(subtypeData, targets) {
  let count = 0;
  
  // Sort identifiers alphabetically so the iteration order is deterministic
  // across runs, independent of how the unified-collection JSON was written.
  const identifierKeys = Object.keys(subtypeData || {}).sort();
  for (const mongoSafeIdentifier of identifierKeys) {
    const classNames = subtypeData[mongoSafeIdentifier] || [];
    const identifier = fromMongoSafeFieldName(mongoSafeIdentifier);
    
    for (const className of classNames) {
      count++;
      targets.push(new BpaTarget(
        "assetApi",
        className,
        identifier,
        `Uses unsupported Asset API: ${identifier}`,
        "critical"
      ));
    }
  }
  
  return count;
}

/**
 * Process event listener data from unified collection
 */
function processEventListenerFromUnified(subtypeData, targets) {
  let count = 0;
  
  // Sort identifiers alphabetically so the iteration order is deterministic
  // across runs, independent of how the unified-collection JSON was written.
  const identifierKeys = Object.keys(subtypeData || {}).sort();
  for (const mongoSafeIdentifier of identifierKeys) {
    const classNames = subtypeData[mongoSafeIdentifier] || [];
    const identifier = fromMongoSafeFieldName(mongoSafeIdentifier);
    
    for (const className of classNames) {
      count++;
      targets.push(new BpaTarget(
        "eventListener",
        className,
        identifier,
        `Uses JCR Event Listener: ${identifier}`,
        "high"
      ));
    }
  }
  
  return count;
}

/**
 * Process resource change listener data from unified collection
 */
function processResourceChangeListenerFromUnified(subtypeData, targets) {
  let count = 0;
  
  // Sort identifiers alphabetically so the iteration order is deterministic
  // across runs, independent of how the unified-collection JSON was written.
  const identifierKeys = Object.keys(subtypeData || {}).sort();
  for (const mongoSafeIdentifier of identifierKeys) {
    const classNames = subtypeData[mongoSafeIdentifier] || [];
    const identifier = fromMongoSafeFieldName(mongoSafeIdentifier);
    
    for (const className of classNames) {
      count++;
      targets.push(new BpaTarget(
        "resourceChangeListener",
        className,
        identifier,
        `Uses Resource Change Listener: ${identifier}`,
        "high"
      ));
    }
  }
  
  return count;
}

/**
 * Process event handler data from unified collection
 */
function processEventHandlerFromUnified(subtypeData, targets) {
  let count = 0;
  
  // Sort identifiers alphabetically so the iteration order is deterministic
  // across runs, independent of how the unified-collection JSON was written.
  const identifierKeys = Object.keys(subtypeData || {}).sort();
  for (const mongoSafeIdentifier of identifierKeys) {
    const classNames = subtypeData[mongoSafeIdentifier] || [];
    const identifier = fromMongoSafeFieldName(mongoSafeIdentifier);
    
    for (const className of classNames) {
      count++;
      targets.push(new BpaTarget(
        "eventHandler",
        className,
        identifier,
        `Uses OSGi Event Handler: ${identifier}`,
        "high"
      ));
    }
  }
  
  return count;
}

/**
 * Fetch findings from unified collection (mimics cam-bpa-fetcher behavior).
 *
 * The full ordered list for the requested `pattern` is assembled, then
 * sliced into a batch via {@link paginate}. The returned object contains
 * `targets` (the batch) and `paging` (batch metadata for resuming).
 *
 * Ordering contract: for a given unified-collection.json file and a given
 * `pattern`, successive calls with incrementing `offset` return contiguous,
 * non-overlapping batches covering the full list.
 *
 * @param {string} pattern
 * @param {string} collectionsDir
 * @param {{offset?: number, limit?: number|null|'all'}} [paging]
 */
function fetchUnifiedBpaFindings(pattern = "all", collectionsDir = './unified-collections', paging = {}) {
  const result = new BpaResult();
  
  // Check if unified collection exists
  if (!hasUnifiedCollection(collectionsDir)) {
    result.error = `Unified collection not found: ${collectionsDir}/unified-collection.json`;
    result.troubleshooting = [
      "Run bpa-local-parser.js with --unified flag to create unified collection",
      "Ensure the collections directory path is correct",
      "Check that BPA file has been processed successfully"
    ];
    result.suggestion = [
      "Use: node bpa-local-parser.js <bpa-file-path> [output-directory] --unified",
      "Verify BPA file contains valid findings data"
    ];
    return result;
  }
  
  // Read unified collection
  const unifiedCollection = readUnifiedCollection(collectionsDir);
  if (!unifiedCollection || !unifiedCollection.subtypes) {
    result.error = "Invalid unified collection format";
    result.troubleshooting = [
      "Check that unified-collection.json contains valid JSON",
      "Verify the file has 'subtypes' property",
      "Re-run bpa-local-parser.js if file is corrupted"
    ];
    return result;
  }
  
  // Determine patterns to fetch
  const availablePatterns = getAvailablePatterns(collectionsDir);
  
  if (availablePatterns.length === 0) {
    result.error = "No valid pattern collections found in unified collection";
    result.troubleshooting = [
      "Check that unified collection contains supported subtypes",
      "Verify pattern files contain valid data",
      "Re-run bpa-local-parser.js if data is missing"
    ];
    return result;
  }
  
  // Sort patterns alphabetically so "all" returns findings in a deterministic
  // order independent of how availablePatterns was produced.
  const patternsToFetch = pattern === "all"
    ? [...availablePatterns].sort()
    : availablePatterns.filter(p => p === pattern);
  
  if (patternsToFetch.length === 0) {
    result.error = `Pattern '${pattern}' not found in unified collection. Available: ${availablePatterns.join(', ')}`;
    result.suggestion = [
      `Use one of: ${availablePatterns.join(', ')}, all`,
      "Check that the requested pattern was included in the BPA report"
    ];
    return result;
  }
  
  console.log(`[Unified Collection Reader] Reading patterns: ${patternsToFetch.join(', ')}`);
  
  // Process each pattern
  for (const pat of patternsToFetch) {
    const mongoSafeSubtype = Object.keys(MONGO_SAFE_TO_PATTERN).find(key => 
      MONGO_SAFE_TO_PATTERN[key] === pat
    );
    
    if (!mongoSafeSubtype) {
      console.warn(`[Unified Collection Reader] Unknown pattern: ${pat}, skipping`);
      continue;
    }
    
    const subtypeData = unifiedCollection.subtypes[mongoSafeSubtype];
    if (!subtypeData) {
      console.warn(`[Unified Collection Reader] No data for pattern: ${pat}, skipping`);
      continue;
    }
    
    // Process data based on pattern type
    let count = 0;
    if (pat === "scheduler") {
      count = processSchedulerFromUnified(subtypeData, result.targets);
      result.summary.schedulerCount = count;
    } else if (pat === "assetApi") {
      count = processAssetApiFromUnified(subtypeData, result.targets);
      result.summary.assetApiCount = count;
    } else if (pat === "eventListener") {
      count = processEventListenerFromUnified(subtypeData, result.targets);
      result.summary.eventListenerCount = count;
    } else if (pat === "resourceChangeListener") {
      count = processResourceChangeListenerFromUnified(subtypeData, result.targets);
      result.summary.resourceChangeListenerCount = count;
    } else if (pat === "eventHandler") {
      count = processEventHandlerFromUnified(subtypeData, result.targets);
      result.summary.eventHandlerCount = count;
    }
    
    console.log(`[Unified Collection Reader] Processed ${count} findings for pattern: ${pat}`);
  }
  
  if (result.targets.length === 0) {
    result.error = "No findings found in unified collection";
    result.suggestion = [
      "Verify that BPA file contained relevant findings",
      "Check that bpa-local-parser.js processed the file correctly",
      "Inspect unified collection file for expected data structure"
    ];
    return result;
  }

  const { targets, paging: p } = paginate(result.targets, paging);
  result.targets = targets;
  result.paging = p;
  result.success = true;
  console.log(
    `[Unified Collection Reader] Batch ${p.returned}/${p.total} ` +
    `(offset ${p.offset}, hasMore=${p.hasMore})`
  );
  return result;
}

/**
 * Get summary of unified collection (derived from unified-collection.json).
 * Returns { timestamp, subtypes, totalFindings } for display purposes.
 */
function getUnifiedCollectionSummary(collectionsDir = './unified-collections') {
  const unifiedCollection = readUnifiedCollection(collectionsDir);
  if (!unifiedCollection || !unifiedCollection.subtypes) {
    return null;
  }

  const subtypes = Object.keys(unifiedCollection.subtypes);
  let totalFindings = 0;
  for (const subtypeKey of subtypes) {
    const subtypeData = unifiedCollection.subtypes[subtypeKey] || {};
    for (const classNames of Object.values(subtypeData)) {
      totalFindings += (classNames || []).length;
    }
  }

  return {
    timestamp: unifiedCollection.meta?.timestamp || null,
    subtypes,
    totalFindings: unifiedCollection.meta?.totalFindings ?? totalFindings
  };
}

/**
 * CLI interface for testing
 *
 * Usage: node unified-collection-reader.js <pattern> [collectionsDir] [offset] [limit]
 *   offset defaults to 0
 *   limit  defaults to 5 (use 'all' to disable batching)
 */
function main() {
  const args = process.argv.slice(2);
  const pattern = args[0] || 'all';
  const collectionsDir = args[1] || './unified-collections';
  const offset = args[2] !== undefined ? Number(args[2]) : 0;
  const limit = args[3] !== undefined
    ? (args[3] === 'all' ? null : Number(args[3]))
    : DEFAULT_BATCH_SIZE;

  console.log('Unified Collection Reader');
  console.log('========================');
  console.log(`Pattern: ${pattern}`);
  console.log(`Collections Directory: ${collectionsDir}`);
  console.log(`Offset: ${offset}`);
  console.log(`Limit:  ${limit === null ? 'all' : limit}`);
  console.log('');
  
  // Check if unified collection exists
  if (!hasUnifiedCollection(collectionsDir)) {
    console.error(`❌ Unified collection not found: ${collectionsDir}/unified-collection.json`);
    console.error('');
    console.error('To create unified collection:');
    console.error('  node bpa-local-parser.js <bpa-file-path> [output-directory] --unified');
    process.exit(1);
  }
  
  // Show available patterns
  const availablePatterns = getAvailablePatterns(collectionsDir);
  console.log(`Available patterns: ${availablePatterns.join(', ')}`);
  
  // Show summary
  const summary = getUnifiedCollectionSummary(collectionsDir);
  if (summary) {
    console.log(`Total subtypes: ${summary.subtypes?.length || 0}`);
    console.log(`Total findings: ${summary.totalFindings || 0}`);
    console.log(`Created: ${summary.timestamp || '(unknown)'}`);
  }
  
  console.log('');
  
  // Fetch findings
  const result = fetchUnifiedBpaFindings(pattern, collectionsDir, { offset, limit });

  if (result.success) {
    const p = result.paging;
    console.log(`✅ Batch ${p.returned}/${p.total} (offset ${p.offset}, next ${p.nextOffset ?? 'none'}, hasMore=${p.hasMore})`);
    console.log('');
    
    // Group by pattern
    const byPattern = result.targets.reduce((acc, target) => {
      if (!acc[target.pattern]) acc[target.pattern] = [];
      acc[target.pattern].push(target);
      return acc;
    }, {});
    
    Object.entries(byPattern).forEach(([pat, targets]) => {
      console.log(`${pat.toUpperCase()}:`);
      targets.forEach(target => {
        console.log(`  - ${target.className} (${target.severity}): ${target.issue}`);
      });
      console.log('');
    });
  } else {
    console.error('❌ Error:', result.error);
    if (result.troubleshooting?.length > 0) {
      console.error('');
      console.error('Troubleshooting:');
      result.troubleshooting.forEach(tip => console.error(`  - ${tip}`));
    }
    if (result.suggestion?.length > 0) {
      console.error('');
      console.error('Suggestions:');
      result.suggestion.forEach(tip => console.error(`  - ${tip}`));
    }
    process.exit(1);
  }
}

// Run CLI if called directly
if (require.main === module) {
  main();
}

module.exports = {
  hasUnifiedCollection,
  getAvailablePatterns,
  fetchUnifiedBpaFindings,
  getUnifiedCollectionSummary,
  readUnifiedCollection,
  paginate,
  DEFAULT_BATCH_SIZE,
  BpaTarget,
  BpaResult
};