specshield 3.2.1 → 3.2.3

package/src/core/har/parseHar.js

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * Read + normalise a HAR (HTTP Archive 1.2) file into the minimal record
+ * shape the OpenAPI emitter consumes.
+ *
+ *   readHarFile(path)                 → parsed HAR object (validates shape)
+ *   normaliseEntries(har, opts)       → HarRecord[]
+ *
+ * HarRecord = {
+ *   method:               'GET' | 'POST' | …,
+ *   url:                  URL object,
+ *   path:                 '/users/123',
+ *   query:                { limit: '10', … },
+ *   requestBody:          parsed JSON | undefined,
+ *   responseStatus:       200,
+ *   responseBody:         parsed JSON | undefined,
+ *   requestContentType:   'application/json' | null,
+ *   responseContentType:  'application/json' | null,
+ * }
+ */
+
+const fs = require('fs');
+const { URL } = require('url');
+
+function isJsonMimeType(m) {
+  if (!m) return false;
+  return /\bjson\b/i.test(m);
+}
+
+function safeJsonParse(text) {
+  if (typeof text !== 'string' || text.trim().length === 0) return undefined;
+  try { return JSON.parse(text); } catch { return undefined; }
+}
+
+function readHarFile(filepath) {
+  const raw = fs.readFileSync(filepath, 'utf8');
+  let doc;
+  try { doc = JSON.parse(raw); }
+  catch (e) { throw new Error(`Not valid HAR JSON: ${filepath} (${e.message})`); }
+  if (!doc || typeof doc !== 'object' || !doc.log || !Array.isArray(doc.log.entries)) {
+    throw new Error(`Not a HAR file (missing log.entries): ${filepath}`);
+  }
+  return doc;
+}
+
+/**
+ * @param har          parsed HAR object
+ * @param opts.baseUrl filter: keep only entries whose URL host (and optional
+ *                     prefix path, e.g. /v1) matches. Bare host accepted.
+ * @param opts.methods filter: keep only these HTTP methods (case-insensitive)
+ * @param opts.onlyJson default true — drop entries whose bodies are non-JSON
+ */
+function normaliseEntries(har, opts = {}) {
+  const out = [];
+  const entries = har.log.entries;
+  const baseUrl = opts.baseUrl ? normaliseBase(opts.baseUrl) : null;
+  const methods = Array.isArray(opts.methods) && opts.methods.length > 0
+    ? new Set(opts.methods.map(m => m.toUpperCase()))
+    : null;
+  const onlyJson = opts.onlyJson !== false;
+
+  for (const e of entries) {
+    if (!e || !e.request) continue;
+    let url;
+    try { url = new URL(e.request.url); } catch { continue; }
+
+    const method = String(e.request.method || 'GET').toUpperCase();
+    if (methods && !methods.has(method)) continue;
+    if (baseUrl && !urlMatchesBase(url, baseUrl)) continue;
+
+    const reqMime = headerValue(e.request.headers, 'content-type');
+    const resMime = e.response && e.response.content && e.response.content.mimeType;
+
+    const requestBody  = safeJsonParse(e.request.postData && e.request.postData.text);
+    const responseBody = safeJsonParse(e.response && e.response.content && e.response.content.text);
+
+    // Drop entries whose declared body is non-JSON (or undecodable). We can't
+    // infer a JSON Schema from binary/multipart/HTML, and silently emitting
+    // a wrong schema would be worse than dropping the sample.
+    if (onlyJson) {
+      const hasReqText = e.request.postData && typeof e.request.postData.text === 'string'
+                        && e.request.postData.text.length > 0;
+      if (hasReqText && requestBody === undefined && !isJsonMimeType(reqMime)) continue;
+
+      const hasResText = e.response && e.response.content
+                        && typeof e.response.content.text === 'string'
+                        && e.response.content.text.length > 0;
+      if (hasResText && responseBody === undefined && !isJsonMimeType(resMime)) continue;
+    }
+
+    const query = {};
+    url.searchParams.forEach((v, k) => { query[k] = v; });
+
+    out.push({
+      method,
+      url,
+      path: url.pathname,
+      query,
+      requestBody,
+      responseStatus: e.response ? e.response.status : 0,
+      responseBody,
+      requestContentType: reqMime || null,
+      responseContentType: resMime || null,
+    });
+  }
+  return out;
+}
+
+function headerValue(headers, name) {
+  if (!Array.isArray(headers)) return null;
+  const wanted = name.toLowerCase();
+  for (const h of headers) {
+    if (h && typeof h.name === 'string' && h.name.toLowerCase() === wanted) return h.value;
+  }
+  return null;
+}
+
+function normaliseBase(base) {
+  if (!base) return null;
+  if (!/^https?:\/\//i.test(base)) base = `https://${base}`;
+  try { return new URL(base); } catch { return null; }
+}
+
+function urlMatchesBase(url, baseUrl) {
+  if (!baseUrl) return true;
+  if (url.host !== baseUrl.host) return false;
+  if (url.protocol !== baseUrl.protocol) return false;
+  const basePath = baseUrl.pathname.replace(/\/$/, '');
+  if (basePath && basePath !== '/' &&
+      !url.pathname.startsWith(basePath + '/') &&
+      url.pathname !== basePath) return false;
+  return true;
+}
+
+module.exports = { readHarFile, normaliseEntries, isJsonMimeType };

package/src/core/har/pathTemplate.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * Path-template inference for HAR → OpenAPI capture (Fix 2 of the BDCT
+ * fidelity roadmap).
+ *
+ * Goal: turn concrete request paths recorded in real traffic into OpenAPI
+ * path templates, e.g.
+ *   /users/123/orders/550e8400-e29b-41d4-a716-446655440000
+ *     → /users/{userId}/orders/{orderId}
+ *
+ * Heuristic (intentionally conservative — false positives cost more than
+ * false negatives because over-templating destroys meaningful endpoint
+ * shape):
+ *
+ *   A segment is "dynamic" iff it matches one of:
+ *     - all digits                       e.g. "123", "42"
+ *     - UUID                             e.g. "550e8400-…"
+ *     - hex-only ≥ 8 chars               e.g. "9a3f7c1b"  (mongo-style ids)
+ *     - has a digit AND a hyphen/underscore   e.g. "PAY-2026-001"
+ *
+ *   Pure-alpha segments ("orders", "summary", "profile") stay literal.
+ *
+ * Param naming: if the preceding segment is alpha (a resource name), the
+ * synthesised param is "<singular>Id" (rough singularise: strip trailing
+ * `s`), so /users/123 → /users/{userId}. Otherwise it's plain "id".
+ *
+ * Custom dynamic patterns can be supplied via `opts.dynamicPatterns` —
+ * an array of RegExp matched against each segment.
+ */
+
+const UUID_RE   = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const HEX_RE    = /^[0-9a-f]{8,}$/i;
+const DIGITS_RE = /^\d+$/;
+
+function isDynamicSegment(seg, opts = {}) {
+  if (!seg) return false;
+  if (DIGITS_RE.test(seg)) return true;
+  if (UUID_RE.test(seg))   return true;
+  if (HEX_RE.test(seg))    return true;
+  if (/[-_]/.test(seg) && /\d/.test(seg)) return true;
+  if (Array.isArray(opts.dynamicPatterns)) {
+    for (const re of opts.dynamicPatterns) if (re.test(seg)) return true;
+  }
+  return false;
+}
+
+function paramNameFromContext(prevSegment) {
+  if (!prevSegment || !/^[a-z][a-z0-9_-]*$/i.test(prevSegment)) return 'id';
+  // Rough singularisation: users → user, orders → order, but "address" → "addres"
+  // is wrong. Only apply when the result still has >1 char AND the original
+  // ends in a plural-looking 's' (not 'ss' which is usually mass-noun).
+  const m = /^(.+?)s$/.exec(prevSegment);
+  const base = (m && !/ss$/.test(prevSegment)) ? m[1] : prevSegment;
+  if (!base || base.length < 2) return 'id';
+  return `${base}Id`;
+}
+
+/**
+ * Convert a concrete path (no query string) into a templated path.
+ * Returns { templated, paramNames }.
+ */
+function templatePath(concretePath, opts = {}) {
+  if (typeof concretePath !== 'string' || concretePath.length === 0) {
+    return { templated: '/', paramNames: [] };
+  }
+  // Strip query if caller accidentally passed it.
+  const q = concretePath.indexOf('?');
+  const clean = q >= 0 ? concretePath.slice(0, q) : concretePath;
+
+  const segments = clean.split('/');
+  const paramNames = [];
+  // De-duplicate within one path so /users/1/users/2 → /users/{userId}/users/{userId2}
+  const used = new Map();
+
+  for (let i = 0; i < segments.length; i++) {
+    const s = segments[i];
+    if (!s) continue;
+    if (isDynamicSegment(s, opts)) {
+      let name = paramNameFromContext(segments[i - 1]);
+      const seen = used.get(name) || 0;
+      if (seen > 0) name = `${name}${seen + 1}`;
+      used.set(name.replace(/\d+$/, '') || name, seen + 1);
+      segments[i] = `{${name}}`;
+      paramNames.push(name);
+    }
+  }
+  const joined = segments.join('/');
+  return { templated: joined || '/', paramNames };
+}
+
+module.exports = { templatePath, isDynamicSegment, paramNameFromContext };

package/src/core/har/schemaInfer.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * JSON Schema inference from sample bodies — for HAR-ingest capture (Fix 2).
+ *
+ *   inferSchema(value)              → JSON Schema describing one sample
+ *   mergeSchemas(a, b)              → schema that admits both inputs
+ *
+ * The merger is the interesting bit: across multiple recorded responses
+ * for the same endpoint, fields seen in EVERY sample stay `required`;
+ * fields seen in only SOME become optional; type conflicts widen
+ * conservatively (integer + number → number; otherwise → string).
+ *
+ * Common string formats (uuid, date-time, email) are detected so the
+ * emitted OpenAPI subset is richer than just "type: string".
+ */
+
+const UUID_RE      = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DATE_TIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+const EMAIL_RE     = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+
+function inferSchema(value) {
+  if (value === null || value === undefined) return { type: 'null' };
+  if (typeof value === 'boolean') return { type: 'boolean' };
+  if (typeof value === 'string') {
+    if (UUID_RE.test(value))      return { type: 'string', format: 'uuid' };
+    if (DATE_TIME_RE.test(value)) return { type: 'string', format: 'date-time' };
+    if (EMAIL_RE.test(value))     return { type: 'string', format: 'email' };
+    return { type: 'string' };
+  }
+  if (typeof value === 'number') {
+    return Number.isInteger(value) ? { type: 'integer' } : { type: 'number' };
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return { type: 'array', items: {} };
+    let items = inferSchema(value[0]);
+    for (let i = 1; i < value.length; i++) {
+      items = mergeSchemas(items, inferSchema(value[i]));
+    }
+    return { type: 'array', items };
+  }
+  if (typeof value === 'object') {
+    const properties = {};
+    const required = [];
+    for (const [k, v] of Object.entries(value)) {
+      properties[k] = inferSchema(v);
+      // null values still register the key, but the field is not "required"
+      // (it was present-but-null; another sample might omit it entirely).
+      if (v !== null && v !== undefined) required.push(k);
+    }
+    const out = { type: 'object', properties };
+    if (required.length > 0) out.required = required;
+    return out;
+  }
+  return {};
+}
+
+function mergeSchemas(a, b) {
+  if (!a || Object.keys(a).length === 0) return b || {};
+  if (!b || Object.keys(b).length === 0) return a;
+  if (a.type === 'null') return b;
+  if (b.type === 'null') return a;
+
+  if (a.type === b.type) {
+    if (a.type === 'object') {
+      const out = { type: 'object', properties: {} };
+      const allKeys = new Set([
+        ...Object.keys(a.properties || {}),
+        ...Object.keys(b.properties || {}),
+      ]);
+      for (const k of allKeys) {
+        const aProp = a.properties && a.properties[k];
+        const bProp = b.properties && b.properties[k];
+        out.properties[k] = aProp && bProp ? mergeSchemas(aProp, bProp) : (aProp || bProp);
+      }
+      // Required = INTERSECTION (a field is only "always present" if both samples had it).
+      const aReq = new Set(a.required || []);
+      const bReq = new Set(b.required || []);
+      const intersect = [...aReq].filter(k => bReq.has(k));
+      if (intersect.length > 0) out.required = intersect;
+      return out;
+    }
+    if (a.type === 'array') {
+      return { type: 'array', items: mergeSchemas(a.items || {}, b.items || {}) };
+    }
+    // Same primitive type. Keep `format` only if both samples agreed.
+    const out = { type: a.type };
+    if (a.format && a.format === b.format) out.format = a.format;
+    return out;
+  }
+
+  // Type mismatch — widen numerically; otherwise fall back to string.
+  if ((a.type === 'integer' && b.type === 'number') ||
+      (a.type === 'number'  && b.type === 'integer')) {
+    return { type: 'number' };
+  }
+  return { type: 'string' };
+}
+
+module.exports = { inferSchema, mergeSchemas };

package/src/core/projectConfig.js

@@ -157,6 +157,25 @@ function applyBdctDefaults(opts, command, { cwd = process.cwd() } = {}) {
     opts[f] = (f === 'spec' || f === 'contract') ? resolvePath(def) : def;
   }
 
+  // Placeholder check — `<replace-me>` is the marker `specshield init` writes
+  // for fields the user skipped during the wizard. Letting it flow through
+  // would send the literal string to the backend, producing confusing 4xx
+  // errors. Refuse with a message that points at the file and field.
+  const placeholders = FIELDS
+    .filter(f => opts[f] === '<replace-me>')
+    .map(f => '--' + f.replace(/[A-Z]/g, m => '-' + m.toLowerCase()));
+  if (placeholders.length > 0) {
+    const where = cfg._file ? cfg._file : '(no config file found)';
+    const err = new Error(
+      `The following value${placeholders.length === 1 ? ' is' : 's are'} still set to ` +
+      `the "<replace-me>" placeholder written by \`specshield init\`: ` +
+      placeholders.join(', ') + '\n' +
+      `Edit ${where} (or pass real values as CLI flags) before re-running.`);
+    err.code = 'UNRESOLVED_PLACEHOLDER';
+    err.placeholders = placeholders;
+    throw err;
+  }
+
   // Required-field check.
   const required = REQUIRED_FIELDS[command] || [];
   const missing  = required.filter(k => !opts[k]);