@democratize-quality/qualitylens-core 0.1.0

package/dist/sources/routes.source.js

@@ -0,0 +1,288 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/sources/routes.source.ts
+var routes_source_exports = {};
+__export(routes_source_exports, {
+  RoutesSource: () => RoutesSource
+});
+module.exports = __toCommonJS(routes_source_exports);
+
+// src/utils/logger.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var Logger = class {
+  logPath = null;
+  fd = null;
+  /**
+   * Open (or create) qualitylens.log in the given directory.
+   * Appends to an existing log so multiple runs accumulate history.
+   * Call once at the start of each command.
+   */
+  configure(outputDir) {
+    try {
+      fs.mkdirSync(outputDir, { recursive: true });
+      this.logPath = path.join(outputDir, "qualitylens.log");
+      this.fd = fs.openSync(this.logPath, "a");
+      this.write("INFO", `--- qualitylens session started (pid ${process.pid}) ---`);
+    } catch {
+      this.logPath = null;
+      this.fd = null;
+    }
+  }
+  /** Path to the current log file, or null if not configured. */
+  get filePath() {
+    return this.logPath;
+  }
+  info(msg, detail) {
+    this.write("INFO", msg, detail);
+  }
+  warn(msg, detail) {
+    this.write("WARN", msg, detail);
+  }
+  /** Logs full detail (stack trace, raw error) to file only. */
+  error(msg, detail) {
+    this.write("ERROR", msg, detail);
+  }
+  debug(msg, detail) {
+    this.write("DEBUG", msg, detail);
+  }
+  close() {
+    if (this.fd !== null) {
+      try {
+        fs.closeSync(this.fd);
+      } catch {
+      }
+      this.fd = null;
+    }
+  }
+  write(level, msg, detail) {
+    if (this.fd === null) return;
+    const ts = (/* @__PURE__ */ new Date()).toISOString();
+    let line = `[${ts}] ${level.padEnd(5)} ${msg}`;
+    if (detail !== void 0) {
+      if (detail instanceof Error) {
+        line += `
+  ${detail.message}`;
+        if (detail.stack) {
+          line += "\n" + detail.stack.split("\n").map((l) => "  " + l).join("\n");
+        }
+      } else if (typeof detail === "string" && detail.trim()) {
+        line += "\n" + detail.split("\n").map((l) => "  " + l).join("\n");
+      } else if (typeof detail === "object") {
+        try {
+          line += "\n  " + JSON.stringify(detail, null, 2).replace(/\n/g, "\n  ");
+        } catch {
+        }
+      }
+    }
+    try {
+      fs.writeSync(this.fd, line + "\n");
+    } catch {
+    }
+  }
+};
+var logger = new Logger();
+
+// src/sources/routes.source.ts
+var fs2 = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
+var import_fast_glob = __toESM(require("fast-glob"));
+var RoutesSource = class {
+  constructor(config) {
+    this.config = config;
+  }
+  async collect() {
+    const type = this.config.type;
+    logger.info(`[routes] collecting routes`, { type, path: this.config.path });
+    try {
+      switch (type) {
+        case "nextjs":
+          return await this.collectNextJs();
+        case "openapi":
+          return await this.collectOpenApi();
+        case "express":
+          return await this.collectExpress();
+        case "manual":
+          return await this.collectManual();
+        default:
+          throw new Error(
+            `Unknown routes.type "${this.config.type}" in qualitylens.yaml.
+  Valid values: nextjs, openapi, express, manual`
+          );
+      }
+    } catch (err) {
+      logger.error(`[routes] collection failed (type=${type}, path=${this.config.path})`, err);
+      throw err;
+    }
+  }
+  /**
+   * Next.js pages/ or app/ directory scanner.
+   * 
+   * AI INSTRUCTIONS:
+   * 1. Glob all .tsx, .ts, .jsx, .js files under config.path
+   * 2. Convert file path to route:
+   *    pages/checkout/payment.tsx   → /checkout/payment
+   *    pages/index.tsx              → /
+   *    pages/auth/[id].tsx          → /auth/:id
+   *    app/checkout/page.tsx        → /checkout  (App Router pattern)
+   * 3. Skip: _app, _document, _error, api/ routes, layout.tsx, loading.tsx
+   * 4. Return AppRoute[]
+   */
+  async collectNextJs() {
+    const rootPath = path2.resolve(this.config.path);
+    if (!fs2.existsSync(rootPath)) {
+      throw new Error(
+        `Next.js routes directory not found: ${rootPath}
+  Check routes.path in qualitylens.yaml \u2014 it should point to your pages/ or app/ directory.`
+      );
+    }
+    const appRouterPages = await (0, import_fast_glob.default)("**/page.{tsx,ts,jsx,js}", {
+      cwd: rootPath,
+      absolute: false,
+      ignore: ["**/node_modules/**"]
+    });
+    if (appRouterPages.length > 0) {
+      return appRouterPages.map((filePath) => {
+        const dir = filePath.replace(/\/page\.[jt]sx?$/, "").replace(/^page\.[jt]sx?$/, "");
+        const segments = dir.split("/").filter((seg) => !(seg.startsWith("(") && seg.endsWith(")")));
+        const routeSegments = segments.map(
+          (seg) => seg.startsWith("[") && seg.endsWith("]") ? `:${seg.slice(1, -1)}` : seg
+        );
+        const normalised = ("/" + routeSegments.join("/")).replace(/\/+/g, "/").replace(/\/$/, "") || "/";
+        return { path: normalised };
+      });
+    }
+    const pageFiles = await (0, import_fast_glob.default)("**/*.{tsx,ts,jsx,js}", {
+      cwd: rootPath,
+      absolute: false,
+      ignore: ["**/node_modules/**", "**/_app.*", "**/_document.*", "**/_error.*", "**/api/**"]
+    });
+    return pageFiles.map((filePath) => {
+      const withoutExt = filePath.replace(/\.[jt]sx?$/, "");
+      const withoutIndex = withoutExt.replace(/(^|\/)index$/, "");
+      const segments = withoutIndex.split("/").map((seg) => seg.startsWith("[") && seg.endsWith("]") ? `:${seg.slice(1, -1)}` : seg);
+      return { path: ("/" + segments.join("/")).replace(/\/+/g, "/").replace(/\/$/, "") || "/" };
+    });
+  }
+  /**
+   * OpenAPI / Swagger spec parser.
+   * 
+   * AI INSTRUCTIONS:
+   * 1. Read the JSON or YAML file at config.path
+   * 2. Extract spec.paths object — keys are route paths
+   * 3. For each path, extract HTTP methods (get, post, put, delete, patch)
+   * 4. Return one AppRoute per path+method combination
+   * 5. Support both JSON (.json) and YAML (.yaml, .yml) specs
+   */
+  async collectOpenApi() {
+    const absPath = path2.resolve(this.config.path);
+    if (!fs2.existsSync(absPath)) {
+      throw new Error(
+        `OpenAPI spec not found: ${absPath}
+  If your spec is generated at build time, check the routes.generate command in qualitylens.yaml.
+  Run the generate command manually first to confirm it produces the file.`
+      );
+    }
+    let content;
+    try {
+      content = fs2.readFileSync(absPath, "utf-8");
+    } catch (err) {
+      throw new Error(`Could not read OpenAPI spec at ${absPath}: ${err.message}`);
+    }
+    const ext = path2.extname(this.config.path).toLowerCase();
+    let spec;
+    try {
+      spec = ext === ".json" ? JSON.parse(content) : (await import("js-yaml")).load(content);
+    } catch (err) {
+      throw new Error(
+        `Failed to parse OpenAPI spec at ${absPath} as ${ext === ".json" ? "JSON" : "YAML"}.
+  Parse error: ${err.message}
+  Check the file is valid by running: node -e "JSON.parse(require('fs').readFileSync('${absPath}','utf-8'))"`
+      );
+    }
+    const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"];
+    const routes = [];
+    for (const [routePath, pathItem] of Object.entries(spec.paths ?? {})) {
+      const normalisedPath = routePath.replace(/\{(\w+)\}/g, ":$1");
+      for (const method of HTTP_METHODS) {
+        if (pathItem[method]) {
+          routes.push({ path: normalisedPath, method: method.toUpperCase() });
+        }
+      }
+    }
+    return routes;
+  }
+  /**
+   * Express routes manifest (JSON file).
+   * Format: [{ path: '/checkout', method: 'GET' }, ...]
+   * Users generate this with express-list-routes or similar.
+   */
+  async collectExpress() {
+    return this.readJsonRouteManifest("express");
+  }
+  /**
+   * Manual route list in qualitylens.yaml.
+   * config.path points to a JSON file with [{ path: '/route' }]
+   */
+  async collectManual() {
+    return this.readJsonRouteManifest("manual");
+  }
+  /** Shared reader for express and manual JSON route manifests. */
+  readJsonRouteManifest(type) {
+    const absPath = path2.resolve(this.config.path);
+    if (!fs2.existsSync(absPath)) {
+      throw new Error(
+        `Routes manifest not found: ${absPath}
+  routes.type is "${type}" \u2014 qualitylens expects a JSON file at routes.path.
+  Format: [{ "path": "/api/users", "method": "GET" }, ...]`
+      );
+    }
+    let content;
+    try {
+      content = fs2.readFileSync(absPath, "utf-8");
+    } catch (err) {
+      throw new Error(`Could not read routes manifest at ${absPath}: ${err.message}`);
+    }
+    try {
+      return JSON.parse(content);
+    } catch (err) {
+      throw new Error(
+        `Failed to parse routes manifest at ${absPath} as JSON.
+  Parse error: ${err.message}
+  Expected format: [{ "path": "/api/users", "method": "GET" }, ...]`
+      );
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RoutesSource
+});
+//# sourceMappingURL=routes.source.js.map

package/dist/sources/routes.source.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sources/routes.source.ts","../../src/utils/logger.ts"],"sourcesContent":["/**\n * src/sources/routes.source.ts\n * \n * Discovers application routes from the project structure.\n * Supports: Next.js pages/, Next.js app/, OpenAPI spec, Express manifest.\n * \n * AI INSTRUCTIONS:\n * Implement each strategy as a private method.\n * collect() dispatches to the right strategy based on config.type.\n */\n\nimport { AppRoute, TestGapConfig } from '../core/types'\nimport { logger } from '../utils/logger'\nimport * as fs from 'fs'\nimport * as path from 'path'\nimport glob from 'fast-glob'\n\nexport class RoutesSource {\n  constructor(private config: TestGapConfig['routes']) {}\n\n  async collect(): Promise<AppRoute[]> {\n    const type = this.config.type\n    logger.info(`[routes] collecting routes`, { type, path: this.config.path })\n\n    try {\n      switch (type) {\n        case 'nextjs':   return await this.collectNextJs()\n        case 'openapi':  return await this.collectOpenApi()\n        case 'express':  return await this.collectExpress()\n        case 'manual':   return await this.collectManual()\n        default:\n          throw new Error(\n            `Unknown routes.type \"${(this.config as any).type}\" in qualitylens.yaml.\\n` +\n            `  Valid values: nextjs, openapi, express, manual`\n          )\n      }\n    } catch (err) {\n      logger.error(`[routes] collection failed (type=${type}, path=${this.config.path})`, err)\n      throw err\n    }\n  }\n\n  /**\n   * Next.js pages/ or app/ directory scanner.\n   * \n   * AI INSTRUCTIONS:\n   * 1. Glob all .tsx, .ts, .jsx, .js files under config.path\n   * 2. Convert file path to route:\n   *    pages/checkout/payment.tsx   → /checkout/payment\n   *    pages/index.tsx              → /\n   *    pages/auth/[id].tsx          → /auth/:id\n   *    app/checkout/page.tsx        → /checkout  (App Router pattern)\n   * 3. Skip: _app, _document, _error, api/ routes, layout.tsx, loading.tsx\n   * 4. Return AppRoute[]\n   */\n  private async collectNextJs(): Promise<AppRoute[]> {\n    const rootPath = path.resolve(this.config.path)\n\n    if (!fs.existsSync(rootPath)) {\n      throw new Error(\n        `Next.js routes directory not found: ${rootPath}\\n` +\n        `  Check routes.path in qualitylens.yaml — it should point to your pages/ or app/ directory.`\n      )\n    }\n\n    // Detect App Router vs Pages Router by looking for files named \"page.tsx/ts\".\n    // App Router  → files are named page.tsx inside route folders: app/cart/page.tsx\n    // Pages Router → files ARE the routes: pages/cart.tsx\n    const appRouterPages = await glob('**/page.{tsx,ts,jsx,js}', {\n      cwd: rootPath,\n      absolute: false,\n      ignore: ['**/node_modules/**'],\n    })\n\n    if (appRouterPages.length > 0) {\n      // ── App Router ──────────────────────────────────────────────────────────\n      return appRouterPages.map(filePath => {\n        // fast-glob always uses forward slashes — safe to split on '/' on all OSes.\n        // filePath examples:\n        //   page.tsx                  → /\n        //   cart/page.tsx             → /cart\n        //   orders/[id]/page.tsx      → /orders/:id\n        //   (auth)/login/page.tsx     → /login  (route groups in parens are stripped)\n\n        // Remove the trailing \"/page.tsx\" (or page.ts etc.)\n        const dir = filePath\n          .replace(/\\/page\\.[jt]sx?$/, '')\n          .replace(/^page\\.[jt]sx?$/, '')\n\n        // Strip route groups: (auth) → removed entirely\n        const segments = dir\n          .split('/')\n          .filter(seg => !(seg.startsWith('(') && seg.endsWith(')')))\n\n        // Convert [param] dynamic segments to :param\n        const routeSegments = segments.map(seg =>\n          seg.startsWith('[') && seg.endsWith(']') ? `:${seg.slice(1, -1)}` : seg\n        )\n\n        const normalised = ('/' + routeSegments.join('/')).replace(/\\/+/g, '/').replace(/\\/$/, '') || '/'\n        return { path: normalised }\n      })\n    }\n\n    // ── Pages Router ──────────────────────────────────────────────────────────\n    const pageFiles = await glob('**/*.{tsx,ts,jsx,js}', {\n      cwd: rootPath,\n      absolute: false,\n      ignore: ['**/node_modules/**', '**/_app.*', '**/_document.*', '**/_error.*', '**/api/**'],\n    })\n\n    return pageFiles.map(filePath => {\n      // pages/checkout/payment.tsx → /checkout/payment\n      // pages/index.tsx            → /\n      const withoutExt = filePath.replace(/\\.[jt]sx?$/, '')\n      const withoutIndex = withoutExt.replace(/(^|\\/)index$/, '')\n      const segments = withoutIndex\n        .split('/')\n        .map(seg => seg.startsWith('[') && seg.endsWith(']') ? `:${seg.slice(1, -1)}` : seg)\n\n      return { path: ('/' + segments.join('/')).replace(/\\/+/g, '/').replace(/\\/$/, '') || '/' }\n    })\n  }\n\n  /**\n   * OpenAPI / Swagger spec parser.\n   * \n   * AI INSTRUCTIONS:\n   * 1. Read the JSON or YAML file at config.path\n   * 2. Extract spec.paths object — keys are route paths\n   * 3. For each path, extract HTTP methods (get, post, put, delete, patch)\n   * 4. Return one AppRoute per path+method combination\n   * 5. Support both JSON (.json) and YAML (.yaml, .yml) specs\n   */\n  private async collectOpenApi(): Promise<AppRoute[]> {\n    const absPath = path.resolve(this.config.path)\n\n    if (!fs.existsSync(absPath)) {\n      throw new Error(\n        `OpenAPI spec not found: ${absPath}\\n` +\n        `  If your spec is generated at build time, check the routes.generate command in qualitylens.yaml.\\n` +\n        `  Run the generate command manually first to confirm it produces the file.`\n      )\n    }\n\n    let content: string\n    try {\n      content = fs.readFileSync(absPath, 'utf-8')\n    } catch (err) {\n      throw new Error(`Could not read OpenAPI spec at ${absPath}: ${(err as Error).message}`)\n    }\n\n    // Support both JSON and YAML OpenAPI specs — detect by file extension\n    const ext = path.extname(this.config.path).toLowerCase()\n    let spec: any\n    try {\n      spec = (ext === '.json')\n        ? JSON.parse(content)\n        : (await import('js-yaml')).load(content)\n    } catch (err) {\n      throw new Error(\n        `Failed to parse OpenAPI spec at ${absPath} as ${ext === '.json' ? 'JSON' : 'YAML'}.\\n` +\n        `  Parse error: ${(err as Error).message}\\n` +\n        `  Check the file is valid by running: node -e \"JSON.parse(require('fs').readFileSync('${absPath}','utf-8'))\"`\n      )\n    }\n\n    // The OpenAPI `paths` object is a map of route → { get: {}, post: {}, ... }\n    // e.g. { '/api/products': { get: {...}, post: {...} }, '/api/products/{id}': { get: {...} } }\n    const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options']\n    const routes: AppRoute[] = []\n\n    for (const [routePath, pathItem] of Object.entries(spec.paths ?? {})) {\n      // Convert OpenAPI {param} style to :param style (consistent with the rest of qualitylens)\n      const normalisedPath = routePath.replace(/\\{(\\w+)\\}/g, ':$1')\n\n      for (const method of HTTP_METHODS) {\n        if ((pathItem as any)[method]) {\n          routes.push({ path: normalisedPath, method: method.toUpperCase() })\n        }\n      }\n    }\n\n    return routes\n  }\n\n  /**\n   * Express routes manifest (JSON file).\n   * Format: [{ path: '/checkout', method: 'GET' }, ...]\n   * Users generate this with express-list-routes or similar.\n   */\n  private async collectExpress(): Promise<AppRoute[]> {\n    return this.readJsonRouteManifest('express')\n  }\n\n  /**\n   * Manual route list in qualitylens.yaml.\n   * config.path points to a JSON file with [{ path: '/route' }]\n   */\n  private async collectManual(): Promise<AppRoute[]> {\n    return this.readJsonRouteManifest('manual')\n  }\n\n  /** Shared reader for express and manual JSON route manifests. */\n  private readJsonRouteManifest(type: string): AppRoute[] {\n    const absPath = path.resolve(this.config.path)\n\n    if (!fs.existsSync(absPath)) {\n      throw new Error(\n        `Routes manifest not found: ${absPath}\\n` +\n        `  routes.type is \"${type}\" — qualitylens expects a JSON file at routes.path.\\n` +\n        `  Format: [{ \"path\": \"/api/users\", \"method\": \"GET\" }, ...]`\n      )\n    }\n\n    let content: string\n    try {\n      content = fs.readFileSync(absPath, 'utf-8')\n    } catch (err) {\n      throw new Error(`Could not read routes manifest at ${absPath}: ${(err as Error).message}`)\n    }\n\n    try {\n      return JSON.parse(content) as AppRoute[]\n    } catch (err) {\n      throw new Error(\n        `Failed to parse routes manifest at ${absPath} as JSON.\\n` +\n        `  Parse error: ${(err as Error).message}\\n` +\n        `  Expected format: [{ \"path\": \"/api/users\", \"method\": \"GET\" }, ...]`\n      )\n    }\n  }\n}\n","/**\n * src/utils/logger.ts\n *\n * Module-level singleton logger.\n * - Always writes to a log file (qualitylens.log) with timestamps and full detail.\n * - Console output is handled separately by each command — the logger only writes the file.\n *\n * Usage:\n *   import { logger } from './utils/logger'\n *   logger.configure('./reports')        // call once at startup\n *   logger.info('scan started', { config: opts.config })\n *   logger.error('route discovery failed', err)\n */\n\nimport * as fs from 'fs'\nimport * as path from 'path'\n\ntype LogLevel = 'INFO' | 'WARN' | 'ERROR' | 'DEBUG'\n\nclass Logger {\n  private logPath: string | null = null\n  private fd: number | null = null\n\n  /**\n   * Open (or create) qualitylens.log in the given directory.\n   * Appends to an existing log so multiple runs accumulate history.\n   * Call once at the start of each command.\n   */\n  configure(outputDir: string): void {\n    try {\n      fs.mkdirSync(outputDir, { recursive: true })\n      this.logPath = path.join(outputDir, 'qualitylens.log')\n      this.fd = fs.openSync(this.logPath, 'a')\n      this.write('INFO', `--- qualitylens session started (pid ${process.pid}) ---`)\n    } catch {\n      // If we can't open a log file, continue silently — logging is non-blocking\n      this.logPath = null\n      this.fd = null\n    }\n  }\n\n  /** Path to the current log file, or null if not configured. */\n  get filePath(): string | null {\n    return this.logPath\n  }\n\n  info(msg: string, detail?: unknown): void {\n    this.write('INFO', msg, detail)\n  }\n\n  warn(msg: string, detail?: unknown): void {\n    this.write('WARN', msg, detail)\n  }\n\n  /** Logs full detail (stack trace, raw error) to file only. */\n  error(msg: string, detail?: unknown): void {\n    this.write('ERROR', msg, detail)\n  }\n\n  debug(msg: string, detail?: unknown): void {\n    this.write('DEBUG', msg, detail)\n  }\n\n  close(): void {\n    if (this.fd !== null) {\n      try { fs.closeSync(this.fd) } catch { /* ignore */ }\n      this.fd = null\n    }\n  }\n\n  private write(level: LogLevel, msg: string, detail?: unknown): void {\n    if (this.fd === null) return\n\n    const ts = new Date().toISOString()\n    let line = `[${ts}] ${level.padEnd(5)} ${msg}`\n\n    if (detail !== undefined) {\n      if (detail instanceof Error) {\n        line += `\\n  ${detail.message}`\n        if (detail.stack) {\n          line += '\\n' + detail.stack.split('\\n').map(l => '  ' + l).join('\\n')\n        }\n      } else if (typeof detail === 'string' && detail.trim()) {\n        line += '\\n' + detail.split('\\n').map(l => '  ' + l).join('\\n')\n      } else if (typeof detail === 'object') {\n        try {\n          line += '\\n  ' + JSON.stringify(detail, null, 2).replace(/\\n/g, '\\n  ')\n        } catch { /* circular ref or similar — skip */ }\n      }\n    }\n\n    try {\n      fs.writeSync(this.fd, line + '\\n')\n    } catch { /* disk full or fd closed — ignore */ }\n  }\n}\n\nexport const logger = new Logger()\n"],"mappings":"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","names":["fs","path","glob"]}

package/dist/sources/routes.source.mjs

@@ -0,0 +1,251 @@
+// src/utils/logger.ts
+import * as fs from "fs";
+import * as path from "path";
+var Logger = class {
+  logPath = null;
+  fd = null;
+  /**
+   * Open (or create) qualitylens.log in the given directory.
+   * Appends to an existing log so multiple runs accumulate history.
+   * Call once at the start of each command.
+   */
+  configure(outputDir) {
+    try {
+      fs.mkdirSync(outputDir, { recursive: true });
+      this.logPath = path.join(outputDir, "qualitylens.log");
+      this.fd = fs.openSync(this.logPath, "a");
+      this.write("INFO", `--- qualitylens session started (pid ${process.pid}) ---`);
+    } catch {
+      this.logPath = null;
+      this.fd = null;
+    }
+  }
+  /** Path to the current log file, or null if not configured. */
+  get filePath() {
+    return this.logPath;
+  }
+  info(msg, detail) {
+    this.write("INFO", msg, detail);
+  }
+  warn(msg, detail) {
+    this.write("WARN", msg, detail);
+  }
+  /** Logs full detail (stack trace, raw error) to file only. */
+  error(msg, detail) {
+    this.write("ERROR", msg, detail);
+  }
+  debug(msg, detail) {
+    this.write("DEBUG", msg, detail);
+  }
+  close() {
+    if (this.fd !== null) {
+      try {
+        fs.closeSync(this.fd);
+      } catch {
+      }
+      this.fd = null;
+    }
+  }
+  write(level, msg, detail) {
+    if (this.fd === null) return;
+    const ts = (/* @__PURE__ */ new Date()).toISOString();
+    let line = `[${ts}] ${level.padEnd(5)} ${msg}`;
+    if (detail !== void 0) {
+      if (detail instanceof Error) {
+        line += `
+  ${detail.message}`;
+        if (detail.stack) {
+          line += "\n" + detail.stack.split("\n").map((l) => "  " + l).join("\n");
+        }
+      } else if (typeof detail === "string" && detail.trim()) {
+        line += "\n" + detail.split("\n").map((l) => "  " + l).join("\n");
+      } else if (typeof detail === "object") {
+        try {
+          line += "\n  " + JSON.stringify(detail, null, 2).replace(/\n/g, "\n  ");
+        } catch {
+        }
+      }
+    }
+    try {
+      fs.writeSync(this.fd, line + "\n");
+    } catch {
+    }
+  }
+};
+var logger = new Logger();
+
+// src/sources/routes.source.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import glob from "fast-glob";
+var RoutesSource = class {
+  constructor(config) {
+    this.config = config;
+  }
+  async collect() {
+    const type = this.config.type;
+    logger.info(`[routes] collecting routes`, { type, path: this.config.path });
+    try {
+      switch (type) {
+        case "nextjs":
+          return await this.collectNextJs();
+        case "openapi":
+          return await this.collectOpenApi();
+        case "express":
+          return await this.collectExpress();
+        case "manual":
+          return await this.collectManual();
+        default:
+          throw new Error(
+            `Unknown routes.type "${this.config.type}" in qualitylens.yaml.
+  Valid values: nextjs, openapi, express, manual`
+          );
+      }
+    } catch (err) {
+      logger.error(`[routes] collection failed (type=${type}, path=${this.config.path})`, err);
+      throw err;
+    }
+  }
+  /**
+   * Next.js pages/ or app/ directory scanner.
+   * 
+   * AI INSTRUCTIONS:
+   * 1. Glob all .tsx, .ts, .jsx, .js files under config.path
+   * 2. Convert file path to route:
+   *    pages/checkout/payment.tsx   → /checkout/payment
+   *    pages/index.tsx              → /
+   *    pages/auth/[id].tsx          → /auth/:id
+   *    app/checkout/page.tsx        → /checkout  (App Router pattern)
+   * 3. Skip: _app, _document, _error, api/ routes, layout.tsx, loading.tsx
+   * 4. Return AppRoute[]
+   */
+  async collectNextJs() {
+    const rootPath = path2.resolve(this.config.path);
+    if (!fs2.existsSync(rootPath)) {
+      throw new Error(
+        `Next.js routes directory not found: ${rootPath}
+  Check routes.path in qualitylens.yaml \u2014 it should point to your pages/ or app/ directory.`
+      );
+    }
+    const appRouterPages = await glob("**/page.{tsx,ts,jsx,js}", {
+      cwd: rootPath,
+      absolute: false,
+      ignore: ["**/node_modules/**"]
+    });
+    if (appRouterPages.length > 0) {
+      return appRouterPages.map((filePath) => {
+        const dir = filePath.replace(/\/page\.[jt]sx?$/, "").replace(/^page\.[jt]sx?$/, "");
+        const segments = dir.split("/").filter((seg) => !(seg.startsWith("(") && seg.endsWith(")")));
+        const routeSegments = segments.map(
+          (seg) => seg.startsWith("[") && seg.endsWith("]") ? `:${seg.slice(1, -1)}` : seg
+        );
+        const normalised = ("/" + routeSegments.join("/")).replace(/\/+/g, "/").replace(/\/$/, "") || "/";
+        return { path: normalised };
+      });
+    }
+    const pageFiles = await glob("**/*.{tsx,ts,jsx,js}", {
+      cwd: rootPath,
+      absolute: false,
+      ignore: ["**/node_modules/**", "**/_app.*", "**/_document.*", "**/_error.*", "**/api/**"]
+    });
+    return pageFiles.map((filePath) => {
+      const withoutExt = filePath.replace(/\.[jt]sx?$/, "");
+      const withoutIndex = withoutExt.replace(/(^|\/)index$/, "");
+      const segments = withoutIndex.split("/").map((seg) => seg.startsWith("[") && seg.endsWith("]") ? `:${seg.slice(1, -1)}` : seg);
+      return { path: ("/" + segments.join("/")).replace(/\/+/g, "/").replace(/\/$/, "") || "/" };
+    });
+  }
+  /**
+   * OpenAPI / Swagger spec parser.
+   * 
+   * AI INSTRUCTIONS:
+   * 1. Read the JSON or YAML file at config.path
+   * 2. Extract spec.paths object — keys are route paths
+   * 3. For each path, extract HTTP methods (get, post, put, delete, patch)
+   * 4. Return one AppRoute per path+method combination
+   * 5. Support both JSON (.json) and YAML (.yaml, .yml) specs
+   */
+  async collectOpenApi() {
+    const absPath = path2.resolve(this.config.path);
+    if (!fs2.existsSync(absPath)) {
+      throw new Error(
+        `OpenAPI spec not found: ${absPath}
+  If your spec is generated at build time, check the routes.generate command in qualitylens.yaml.
+  Run the generate command manually first to confirm it produces the file.`
+      );
+    }
+    let content;
+    try {
+      content = fs2.readFileSync(absPath, "utf-8");
+    } catch (err) {
+      throw new Error(`Could not read OpenAPI spec at ${absPath}: ${err.message}`);
+    }
+    const ext = path2.extname(this.config.path).toLowerCase();
+    let spec;
+    try {
+      spec = ext === ".json" ? JSON.parse(content) : (await import("js-yaml")).load(content);
+    } catch (err) {
+      throw new Error(
+        `Failed to parse OpenAPI spec at ${absPath} as ${ext === ".json" ? "JSON" : "YAML"}.
+  Parse error: ${err.message}
+  Check the file is valid by running: node -e "JSON.parse(require('fs').readFileSync('${absPath}','utf-8'))"`
+      );
+    }
+    const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"];
+    const routes = [];
+    for (const [routePath, pathItem] of Object.entries(spec.paths ?? {})) {
+      const normalisedPath = routePath.replace(/\{(\w+)\}/g, ":$1");
+      for (const method of HTTP_METHODS) {
+        if (pathItem[method]) {
+          routes.push({ path: normalisedPath, method: method.toUpperCase() });
+        }
+      }
+    }
+    return routes;
+  }
+  /**
+   * Express routes manifest (JSON file).
+   * Format: [{ path: '/checkout', method: 'GET' }, ...]
+   * Users generate this with express-list-routes or similar.
+   */
+  async collectExpress() {
+    return this.readJsonRouteManifest("express");
+  }
+  /**
+   * Manual route list in qualitylens.yaml.
+   * config.path points to a JSON file with [{ path: '/route' }]
+   */
+  async collectManual() {
+    return this.readJsonRouteManifest("manual");
+  }
+  /** Shared reader for express and manual JSON route manifests. */
+  readJsonRouteManifest(type) {
+    const absPath = path2.resolve(this.config.path);
+    if (!fs2.existsSync(absPath)) {
+      throw new Error(
+        `Routes manifest not found: ${absPath}
+  routes.type is "${type}" \u2014 qualitylens expects a JSON file at routes.path.
+  Format: [{ "path": "/api/users", "method": "GET" }, ...]`
+      );
+    }
+    let content;
+    try {
+      content = fs2.readFileSync(absPath, "utf-8");
+    } catch (err) {
+      throw new Error(`Could not read routes manifest at ${absPath}: ${err.message}`);
+    }
+    try {
+      return JSON.parse(content);
+    } catch (err) {
+      throw new Error(
+        `Failed to parse routes manifest at ${absPath} as JSON.
+  Parse error: ${err.message}
+  Expected format: [{ "path": "/api/users", "method": "GET" }, ...]`
+      );
+    }
+  }
+};
+export {
+  RoutesSource
+};
+//# sourceMappingURL=routes.source.mjs.map

package/dist/sources/routes.source.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/logger.ts","../../src/sources/routes.source.ts"],"sourcesContent":["/**\n * src/utils/logger.ts\n *\n * Module-level singleton logger.\n * - Always writes to a log file (qualitylens.log) with timestamps and full detail.\n * - Console output is handled separately by each command — the logger only writes the file.\n *\n * Usage:\n *   import { logger } from './utils/logger'\n *   logger.configure('./reports')        // call once at startup\n *   logger.info('scan started', { config: opts.config })\n *   logger.error('route discovery failed', err)\n */\n\nimport * as fs from 'fs'\nimport * as path from 'path'\n\ntype LogLevel = 'INFO' | 'WARN' | 'ERROR' | 'DEBUG'\n\nclass Logger {\n  private logPath: string | null = null\n  private fd: number | null = null\n\n  /**\n   * Open (or create) qualitylens.log in the given directory.\n   * Appends to an existing log so multiple runs accumulate history.\n   * Call once at the start of each command.\n   */\n  configure(outputDir: string): void {\n    try {\n      fs.mkdirSync(outputDir, { recursive: true })\n      this.logPath = path.join(outputDir, 'qualitylens.log')\n      this.fd = fs.openSync(this.logPath, 'a')\n      this.write('INFO', `--- qualitylens session started (pid ${process.pid}) ---`)\n    } catch {\n      // If we can't open a log file, continue silently — logging is non-blocking\n      this.logPath = null\n      this.fd = null\n    }\n  }\n\n  /** Path to the current log file, or null if not configured. */\n  get filePath(): string | null {\n    return this.logPath\n  }\n\n  info(msg: string, detail?: unknown): void {\n    this.write('INFO', msg, detail)\n  }\n\n  warn(msg: string, detail?: unknown): void {\n    this.write('WARN', msg, detail)\n  }\n\n  /** Logs full detail (stack trace, raw error) to file only. */\n  error(msg: string, detail?: unknown): void {\n    this.write('ERROR', msg, detail)\n  }\n\n  debug(msg: string, detail?: unknown): void {\n    this.write('DEBUG', msg, detail)\n  }\n\n  close(): void {\n    if (this.fd !== null) {\n      try { fs.closeSync(this.fd) } catch { /* ignore */ }\n      this.fd = null\n    }\n  }\n\n  private write(level: LogLevel, msg: string, detail?: unknown): void {\n    if (this.fd === null) return\n\n    const ts = new Date().toISOString()\n    let line = `[${ts}] ${level.padEnd(5)} ${msg}`\n\n    if (detail !== undefined) {\n      if (detail instanceof Error) {\n        line += `\\n  ${detail.message}`\n        if (detail.stack) {\n          line += '\\n' + detail.stack.split('\\n').map(l => '  ' + l).join('\\n')\n        }\n      } else if (typeof detail === 'string' && detail.trim()) {\n        line += '\\n' + detail.split('\\n').map(l => '  ' + l).join('\\n')\n      } else if (typeof detail === 'object') {\n        try {\n          line += '\\n  ' + JSON.stringify(detail, null, 2).replace(/\\n/g, '\\n  ')\n        } catch { /* circular ref or similar — skip */ }\n      }\n    }\n\n    try {\n      fs.writeSync(this.fd, line + '\\n')\n    } catch { /* disk full or fd closed — ignore */ }\n  }\n}\n\nexport const logger = new Logger()\n","/**\n * src/sources/routes.source.ts\n * \n * Discovers application routes from the project structure.\n * Supports: Next.js pages/, Next.js app/, OpenAPI spec, Express manifest.\n * \n * AI INSTRUCTIONS:\n * Implement each strategy as a private method.\n * collect() dispatches to the right strategy based on config.type.\n */\n\nimport { AppRoute, TestGapConfig } from '../core/types'\nimport { logger } from '../utils/logger'\nimport * as fs from 'fs'\nimport * as path from 'path'\nimport glob from 'fast-glob'\n\nexport class RoutesSource {\n  constructor(private config: TestGapConfig['routes']) {}\n\n  async collect(): Promise<AppRoute[]> {\n    const type = this.config.type\n    logger.info(`[routes] collecting routes`, { type, path: this.config.path })\n\n    try {\n      switch (type) {\n        case 'nextjs':   return await this.collectNextJs()\n        case 'openapi':  return await this.collectOpenApi()\n        case 'express':  return await this.collectExpress()\n        case 'manual':   return await this.collectManual()\n        default:\n          throw new Error(\n            `Unknown routes.type \"${(this.config as any).type}\" in qualitylens.yaml.\\n` +\n            `  Valid values: nextjs, openapi, express, manual`\n          )\n      }\n    } catch (err) {\n      logger.error(`[routes] collection failed (type=${type}, path=${this.config.path})`, err)\n      throw err\n    }\n  }\n\n  /**\n   * Next.js pages/ or app/ directory scanner.\n   * \n   * AI INSTRUCTIONS:\n   * 1. Glob all .tsx, .ts, .jsx, .js files under config.path\n   * 2. Convert file path to route:\n   *    pages/checkout/payment.tsx   → /checkout/payment\n   *    pages/index.tsx              → /\n   *    pages/auth/[id].tsx          → /auth/:id\n   *    app/checkout/page.tsx        → /checkout  (App Router pattern)\n   * 3. Skip: _app, _document, _error, api/ routes, layout.tsx, loading.tsx\n   * 4. Return AppRoute[]\n   */\n  private async collectNextJs(): Promise<AppRoute[]> {\n    const rootPath = path.resolve(this.config.path)\n\n    if (!fs.existsSync(rootPath)) {\n      throw new Error(\n        `Next.js routes directory not found: ${rootPath}\\n` +\n        `  Check routes.path in qualitylens.yaml — it should point to your pages/ or app/ directory.`\n      )\n    }\n\n    // Detect App Router vs Pages Router by looking for files named \"page.tsx/ts\".\n    // App Router  → files are named page.tsx inside route folders: app/cart/page.tsx\n    // Pages Router → files ARE the routes: pages/cart.tsx\n    const appRouterPages = await glob('**/page.{tsx,ts,jsx,js}', {\n      cwd: rootPath,\n      absolute: false,\n      ignore: ['**/node_modules/**'],\n    })\n\n    if (appRouterPages.length > 0) {\n      // ── App Router ──────────────────────────────────────────────────────────\n      return appRouterPages.map(filePath => {\n        // fast-glob always uses forward slashes — safe to split on '/' on all OSes.\n        // filePath examples:\n        //   page.tsx                  → /\n        //   cart/page.tsx             → /cart\n        //   orders/[id]/page.tsx      → /orders/:id\n        //   (auth)/login/page.tsx     → /login  (route groups in parens are stripped)\n\n        // Remove the trailing \"/page.tsx\" (or page.ts etc.)\n        const dir = filePath\n          .replace(/\\/page\\.[jt]sx?$/, '')\n          .replace(/^page\\.[jt]sx?$/, '')\n\n        // Strip route groups: (auth) → removed entirely\n        const segments = dir\n          .split('/')\n          .filter(seg => !(seg.startsWith('(') && seg.endsWith(')')))\n\n        // Convert [param] dynamic segments to :param\n        const routeSegments = segments.map(seg =>\n          seg.startsWith('[') && seg.endsWith(']') ? `:${seg.slice(1, -1)}` : seg\n        )\n\n        const normalised = ('/' + routeSegments.join('/')).replace(/\\/+/g, '/').replace(/\\/$/, '') || '/'\n        return { path: normalised }\n      })\n    }\n\n    // ── Pages Router ──────────────────────────────────────────────────────────\n    const pageFiles = await glob('**/*.{tsx,ts,jsx,js}', {\n      cwd: rootPath,\n      absolute: false,\n      ignore: ['**/node_modules/**', '**/_app.*', '**/_document.*', '**/_error.*', '**/api/**'],\n    })\n\n    return pageFiles.map(filePath => {\n      // pages/checkout/payment.tsx → /checkout/payment\n      // pages/index.tsx            → /\n      const withoutExt = filePath.replace(/\\.[jt]sx?$/, '')\n      const withoutIndex = withoutExt.replace(/(^|\\/)index$/, '')\n      const segments = withoutIndex\n        .split('/')\n        .map(seg => seg.startsWith('[') && seg.endsWith(']') ? `:${seg.slice(1, -1)}` : seg)\n\n      return { path: ('/' + segments.join('/')).replace(/\\/+/g, '/').replace(/\\/$/, '') || '/' }\n    })\n  }\n\n  /**\n   * OpenAPI / Swagger spec parser.\n   * \n   * AI INSTRUCTIONS:\n   * 1. Read the JSON or YAML file at config.path\n   * 2. Extract spec.paths object — keys are route paths\n   * 3. For each path, extract HTTP methods (get, post, put, delete, patch)\n   * 4. Return one AppRoute per path+method combination\n   * 5. Support both JSON (.json) and YAML (.yaml, .yml) specs\n   */\n  private async collectOpenApi(): Promise<AppRoute[]> {\n    const absPath = path.resolve(this.config.path)\n\n    if (!fs.existsSync(absPath)) {\n      throw new Error(\n        `OpenAPI spec not found: ${absPath}\\n` +\n        `  If your spec is generated at build time, check the routes.generate command in qualitylens.yaml.\\n` +\n        `  Run the generate command manually first to confirm it produces the file.`\n      )\n    }\n\n    let content: string\n    try {\n      content = fs.readFileSync(absPath, 'utf-8')\n    } catch (err) {\n      throw new Error(`Could not read OpenAPI spec at ${absPath}: ${(err as Error).message}`)\n    }\n\n    // Support both JSON and YAML OpenAPI specs — detect by file extension\n    const ext = path.extname(this.config.path).toLowerCase()\n    let spec: any\n    try {\n      spec = (ext === '.json')\n        ? JSON.parse(content)\n        : (await import('js-yaml')).load(content)\n    } catch (err) {\n      throw new Error(\n        `Failed to parse OpenAPI spec at ${absPath} as ${ext === '.json' ? 'JSON' : 'YAML'}.\\n` +\n        `  Parse error: ${(err as Error).message}\\n` +\n        `  Check the file is valid by running: node -e \"JSON.parse(require('fs').readFileSync('${absPath}','utf-8'))\"`\n      )\n    }\n\n    // The OpenAPI `paths` object is a map of route → { get: {}, post: {}, ... }\n    // e.g. { '/api/products': { get: {...}, post: {...} }, '/api/products/{id}': { get: {...} } }\n    const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options']\n    const routes: AppRoute[] = []\n\n    for (const [routePath, pathItem] of Object.entries(spec.paths ?? {})) {\n      // Convert OpenAPI {param} style to :param style (consistent with the rest of qualitylens)\n      const normalisedPath = routePath.replace(/\\{(\\w+)\\}/g, ':$1')\n\n      for (const method of HTTP_METHODS) {\n        if ((pathItem as any)[method]) {\n          routes.push({ path: normalisedPath, method: method.toUpperCase() })\n        }\n      }\n    }\n\n    return routes\n  }\n\n  /**\n   * Express routes manifest (JSON file).\n   * Format: [{ path: '/checkout', method: 'GET' }, ...]\n   * Users generate this with express-list-routes or similar.\n   */\n  private async collectExpress(): Promise<AppRoute[]> {\n    return this.readJsonRouteManifest('express')\n  }\n\n  /**\n   * Manual route list in qualitylens.yaml.\n   * config.path points to a JSON file with [{ path: '/route' }]\n   */\n  private async collectManual(): Promise<AppRoute[]> {\n    return this.readJsonRouteManifest('manual')\n  }\n\n  /** Shared reader for express and manual JSON route manifests. */\n  private readJsonRouteManifest(type: string): AppRoute[] {\n    const absPath = path.resolve(this.config.path)\n\n    if (!fs.existsSync(absPath)) {\n      throw new Error(\n        `Routes manifest not found: ${absPath}\\n` +\n        `  routes.type is \"${type}\" — qualitylens expects a JSON file at routes.path.\\n` +\n        `  Format: [{ \"path\": \"/api/users\", \"method\": \"GET\" }, ...]`\n      )\n    }\n\n    let content: string\n    try {\n      content = fs.readFileSync(absPath, 'utf-8')\n    } catch (err) {\n      throw new Error(`Could not read routes manifest at ${absPath}: ${(err as Error).message}`)\n    }\n\n    try {\n      return JSON.parse(content) as AppRoute[]\n    } catch (err) {\n      throw new Error(\n        `Failed to parse routes manifest at ${absPath} as JSON.\\n` +\n        `  Parse error: ${(err as Error).message}\\n` +\n        `  Expected format: [{ \"path\": \"/api/users\", \"method\": \"GET\" }, ...]`\n      )\n    }\n  }\n}\n"],"mappings":"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","names":["fs","path"]}

package/dist/sources/yaml.source.d.mts

@@ -0,0 +1,16 @@
+import { BaseSource } from './base.source.mjs';
+import { TestEntry } from '../core/types.mjs';
+
+/**
+ * src/sources/yaml.source.ts
+ * Reads manual coverage entries from qualitylens.yaml
+ */
+
+declare class YamlSource extends BaseSource {
+    private configPath;
+    readonly name = "yaml";
+    constructor(configPath: string);
+    collect(): Promise<TestEntry[]>;
+}
+
+export { YamlSource };

package/dist/sources/yaml.source.d.ts

@@ -0,0 +1,16 @@
+import { BaseSource } from './base.source.js';
+import { TestEntry } from '../core/types.js';
+
+/**
+ * src/sources/yaml.source.ts
+ * Reads manual coverage entries from qualitylens.yaml
+ */
+
+declare class YamlSource extends BaseSource {
+    private configPath;
+    readonly name = "yaml";
+    constructor(configPath: string);
+    collect(): Promise<TestEntry[]>;
+}
+
+export { YamlSource };