specshield 3.2.2 → 3.2.4

package/src/core/conformance/responseValidator.js

@@ -0,0 +1,114 @@
+'use strict';
+
+/**
+ * Validate an actual HTTP response body against the OAS response schema —
+ * the core of Fix 3 (spec-vs-production conformance).
+ *
+ * OpenAPI 3.0 schemas are a *modified subset* of JSON Schema. ajv validates
+ * standard JSON Schema, so we normalise OAS-isms first:
+ *
+ *   - `nullable: true`     → union with null (`type: [x, 'null']`)
+ *   - `example`, `examples`, `xml`, `discriminator`, `readOnly`, `writeOnly`,
+ *     `deprecated`, `externalDocs`              → stripped (annotations only)
+ *
+ * Anything else (allOf/oneOf/anyOf/not, formats, enums, required, additional-
+ * Properties) passes through to ajv unchanged.
+ *
+ * Format keywords (date-time, uuid, email, …) are handled by ajv-formats.
+ */
+
+const Ajv = require('ajv').default;
+const addFormats = require('ajv-formats');
+
+// One ajv per-validator-call would be slow; cache compiled validators by
+// schema reference. Lifetime is the process — for the CLI that's fine.
+const ajv = new Ajv({
+  strict: false,           // OAS allows non-standard keywords; don't fail compile
+  allErrors: true,         // collect every mismatch, not just the first
+  validateFormats: true,
+  coerceTypes: false,      // a body field that's "1" when spec says integer = mismatch
+});
+addFormats(ajv);
+
+const compiledCache = new WeakMap();
+
+function compile(schema) {
+  if (compiledCache.has(schema)) return compiledCache.get(schema);
+  const normalised = oasToJsonSchema(schema);
+  const fn = ajv.compile(normalised);
+  compiledCache.set(schema, fn);
+  return fn;
+}
+
+/** Recursively rewrite OAS-3.0 quirks into plain JSON Schema. */
+function oasToJsonSchema(node) {
+  if (node === null || typeof node !== 'object') return node;
+  if (Array.isArray(node)) return node.map(oasToJsonSchema);
+
+  // Drop OAS-only annotations that confuse ajv (or are no-ops for validation).
+  const STRIP = new Set([
+    'example', 'examples', 'xml', 'discriminator',
+    'readOnly', 'writeOnly', 'deprecated', 'externalDocs',
+  ]);
+
+  const out = {};
+  for (const [k, v] of Object.entries(node)) {
+    if (STRIP.has(k)) continue;
+    if (k === 'nullable') continue;            // handled below
+    out[k] = oasToJsonSchema(v);
+  }
+
+  // `nullable: true` → widen type to also permit null. JSON Schema 2020-12 +
+  // ajv accept `type: [...]` arrays.
+  if (node.nullable === true && out.type) {
+    if (Array.isArray(out.type)) {
+      if (!out.type.includes('null')) out.type = [...out.type, 'null'];
+    } else {
+      out.type = [out.type, 'null'];
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Validate one body against one schema.
+ * Returns { ok: true } on pass; otherwise { ok: false, errors: [...] } where
+ * each error is { path, message, expected?, got? } — caller-friendly format.
+ */
+function validateBody(body, schema) {
+  if (!schema) return { ok: true, errors: [] };
+  let validate;
+  try { validate = compile(schema); }
+  catch (e) {
+    return { ok: false, errors: [{
+      path: '', message: `spec schema is invalid: ${e.message}`,
+    }]};
+  }
+  const ok = validate(body);
+  if (ok) return { ok: true, errors: [] };
+  return {
+    ok: false,
+    errors: (validate.errors || []).map(e => ({
+      path: e.instancePath || '(root)',
+      keyword: e.keyword,                       // 'enum' | 'required' | 'type' | 'format' | …
+      message: e.message || 'validation failed',
+      expected: e.params,                       // ajv's params, e.g. { allowedValues, missingProperty, format, type }
+      got: peek(body, e.instancePath),
+    })),
+  };
+}
+
+/** Best-effort: extract the value at a JSON-Pointer-style path for the error. */
+function peek(body, jsonPointer) {
+  if (!jsonPointer || jsonPointer === '') return body;
+  const parts = jsonPointer.split('/').slice(1).map(p => p.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let cur = body;
+  for (const p of parts) {
+    if (cur === null || cur === undefined) return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+module.exports = { validateBody, oasToJsonSchema };

package/src/core/conformance/runner.js

@@ -0,0 +1,133 @@
+'use strict';
+
+/**
+ * Execute a set of conformance probes against the running provider.
+ * Pure function-ish: takes probes + an `http(method, url, opts)` adapter
+ * (so tests can inject without spinning a real HTTP client) and returns
+ * a structured result list.
+ *
+ *   ProbeResult = {
+ *     routePath:  '/users/{userId}',
+ *     method:     'GET',
+ *     resolvedPath: '/users/u-7',          // or null if skipped
+ *     status:     'PASS' | 'FAIL' | 'SKIPPED' | 'ERROR',
+ *     httpStatus: 200,                      // if reached
+ *     reason:     human-readable summary,
+ *     mismatches: [{path, message, expected, got}, …],  // only on FAIL
+ *     skipReason: 'unresolved path params: paymentId',  // only on SKIPPED
+ *     error:      'ECONNREFUSED …',                     // only on ERROR
+ *   }
+ *
+ *   RunSummary = { total, pass, fail, skipped, error }
+ */
+
+const { resolveProbePath, collectSpecExamples } = require('./pathResolver');
+const { pickResponseSchema } = require('./probeBuilder');
+const { validateBody }       = require('./responseValidator');
+
+/**
+ * @param spec        dereferenced OAS (used to gather param examples)
+ * @param probes      output of buildProbes(spec)
+ * @param opts.baseUrl       e.g. 'https://staging.payments.acme.com'
+ * @param opts.pathParams    { paymentId: 'pay-123', ... } CLI overrides
+ * @param opts.headers       request headers to send (e.g. auth)
+ * @param opts.http          async (method, url, {headers, timeoutMs}) → {status, body}
+ * @param opts.timeoutMs     default 8000
+ */
+async function runProbes(spec, probes, opts) {
+  const examples = collectSpecExamples(spec);
+  const results = [];
+  const http = opts.http;
+  const baseUrl = String(opts.baseUrl || '').replace(/\/$/, '');
+
+  for (const probe of probes) {
+    const { resolved, missing } = resolveProbePath(
+      probe.routePath, probe.method, examples, opts.pathParams,
+    );
+
+    if (missing.length > 0) {
+      results.push({
+        routePath: probe.routePath, method: probe.method,
+        resolvedPath: null, status: 'SKIPPED',
+        reason: `unresolved path params (no --path-params or spec example)`,
+        skipReason: missing.join(', '),
+      });
+      continue;
+    }
+
+    const url = baseUrl + resolved;
+    let httpStatus, body, err;
+    try {
+      const r = await http(probe.method, url, {
+        headers: opts.headers || {},
+        timeoutMs: opts.timeoutMs || 8000,
+      });
+      httpStatus = r.status;
+      body = r.body;
+    } catch (e) {
+      err = e.message || String(e);
+    }
+
+    if (err) {
+      results.push({
+        routePath: probe.routePath, method: probe.method,
+        resolvedPath: resolved, status: 'ERROR',
+        reason: 'HTTP call failed', error: err,
+      });
+      continue;
+    }
+
+    const schema = pickResponseSchema(probe, httpStatus);
+    if (schema === undefined) {
+      results.push({
+        routePath: probe.routePath, method: probe.method,
+        resolvedPath: resolved, status: 'FAIL', httpStatus,
+        reason: `actual status ${httpStatus} is not documented in the spec`,
+        mismatches: [],
+      });
+      continue;
+    }
+    if (schema === null) {
+      // Status documented but no JSON schema — accept any response body.
+      results.push({
+        routePath: probe.routePath, method: probe.method,
+        resolvedPath: resolved, status: 'PASS', httpStatus,
+        reason: 'status documented (no JSON schema to validate against)',
+        mismatches: [],
+      });
+      continue;
+    }
+
+    const { ok, errors } = validateBody(body, schema);
+    if (ok) {
+      results.push({
+        routePath: probe.routePath, method: probe.method,
+        resolvedPath: resolved, status: 'PASS', httpStatus,
+        reason: 'response matches spec schema',
+        mismatches: [],
+      });
+    } else {
+      results.push({
+        routePath: probe.routePath, method: probe.method,
+        resolvedPath: resolved, status: 'FAIL', httpStatus,
+        reason: `response body does not match spec (${errors.length} mismatch${errors.length === 1 ? '' : 'es'})`,
+        mismatches: errors,
+      });
+    }
+  }
+
+  return { results, summary: summarise(results) };
+}
+
+function summarise(results) {
+  const s = { total: results.length, pass: 0, fail: 0, skipped: 0, error: 0 };
+  for (const r of results) {
+    if (r.status === 'PASS') s.pass++;
+    else if (r.status === 'FAIL') s.fail++;
+    else if (r.status === 'SKIPPED') s.skipped++;
+    else if (r.status === 'ERROR') s.error++;
+  }
+  return s;
+}
+
+module.exports = { runProbes, summarise };

package/src/core/har/emitOpenapi.js

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * Group normalised HAR records by (method, templated-path) and emit an
+ * OpenAPI 3.0 document. Per-status response schemas are merged across all
+ * samples for that group so the emitted contract describes what the
+ * consumer ACTUALLY read across the captured run — not just one example.
+ */
+
+const { templatePath } = require('./pathTemplate');
+const { inferSchema, mergeSchemas } = require('./schemaInfer');
+
+/**
+ * @param records normalised HAR records (output of normaliseEntries())
+ * @param opts    { title, version, baseUrl, dynamicPatterns }
+ * @returns       OpenAPI 3.0 document (plain JS object)
+ */
+function harToOpenapi(records, opts = {}) {
+  const groups = new Map();   // key: "METHOD /templated/path"
+
+  for (const r of records) {
+    const { templated, paramNames } = templatePath(r.path, {
+      dynamicPatterns: opts.dynamicPatterns,
+    });
+    const key = `${r.method} ${templated}`;
+    let g = groups.get(key);
+    if (!g) {
+      g = {
+        method: r.method.toLowerCase(),
+        path: templated,
+        paramNames,
+        requestSchema: undefined,
+        responses: new Map(),    // status → merged schema (or null = saw status, no JSON body)
+      };
+      groups.set(key, g);
+    }
+
+    if (r.requestBody !== undefined) {
+      const sample = inferSchema(r.requestBody);
+      g.requestSchema = g.requestSchema ? mergeSchemas(g.requestSchema, sample) : sample;
+    }
+
+    if (r.responseStatus) {
+      const status = String(r.responseStatus);
+      const schema = r.responseBody !== undefined ? inferSchema(r.responseBody) : null;
+      if (schema) {
+        const existing = g.responses.get(status);
+        g.responses.set(status, existing ? mergeSchemas(existing, schema) : schema);
+      } else if (!g.responses.has(status)) {
+        g.responses.set(status, null);
+      }
+    }
+  }
+
+  // Build the OpenAPI doc.
+  const paths = {};
+  for (const g of groups.values()) {
+    const pItem = paths[g.path] || (paths[g.path] = {});
+    const op = {};
+
+    if (g.paramNames.length > 0) {
+      op.parameters = g.paramNames.map(name => ({
+        name, in: 'path', required: true, schema: { type: 'string' },
+      }));
+    }
+
+    if (g.requestSchema) {
+      op.requestBody = {
+        required: true,
+        content: { 'application/json': { schema: g.requestSchema } },
+      };
+    }
+
+    const responses = {};
+    if (g.responses.size === 0) {
+      responses['200'] = { description: 'OK' };
+    } else {
+      // Sort numerically for stable output.
+      const statuses = [...g.responses.keys()].sort((a, b) => Number(a) - Number(b));
+      for (const status of statuses) {
+        const schema = g.responses.get(status);
+        const r = { description: defaultDescriptionFor(status) };
+        if (schema) r.content = { 'application/json': { schema } };
+        responses[status] = r;
+      }
+    }
+    op.responses = responses;
+
+    pItem[g.method] = op;
+  }
+
+  const doc = {
+    openapi: '3.0.0',
+    info: {
+      title: opts.title || 'Captured consumer contract',
+      version: opts.version || '0.1.0',
+      description:
+        'Generated by `specshield bdct capture` from recorded HAR traffic. ' +
+        'Reflects only the endpoints/fields the consumer actually called/read.',
+    },
+    paths: sortObject(paths),   // stable, alphabetical output
+  };
+  if (opts.baseUrl) doc.servers = [{ url: String(opts.baseUrl) }];
+  // Re-order top-level so `servers` appears between `info` and `paths` (idiomatic).
+  if (opts.baseUrl) {
+    return { openapi: doc.openapi, info: doc.info, servers: doc.servers, paths: doc.paths };
+  }
+  return doc;
+}
+
+function defaultDescriptionFor(status) {
+  const n = Number(status);
+  if (n >= 200 && n < 300) return 'Successful response';
+  if (n >= 300 && n < 400) return 'Redirection';
+  if (n >= 400 && n < 500) return 'Client error';
+  if (n >= 500)            return 'Server error';
+  return 'Response';
+}
+
+function sortObject(o) {
+  if (!o || typeof o !== 'object') return o;
+  return Object.keys(o).sort().reduce((acc, k) => { acc[k] = o[k]; return acc; }, {});
+}
+
+module.exports = { harToOpenapi };

package/src/core/har/index.js

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * One-call orchestrator for `specshield bdct capture from-har`. Read a HAR
+ * file → produce an OpenAPI 3.0 document (text + parsed) + a small summary
+ * the CLI can print.
+ *
+ * This is Phase 1 of Fix 2 (the BDCT fidelity-roadmap "capture" feature):
+ * HAR ingest specifically — language-agnostic, no TLS-proxy gymnastics.
+ * Later phases can layer on live capture (Node `--require` interceptor,
+ * full mitm proxy) without changing the downstream pipeline.
+ */
+
+const yaml = require('js-yaml');
+const { readHarFile, normaliseEntries } = require('./parseHar');
+const { harToOpenapi } = require('./emitOpenapi');
+
+/**
+ * @param filepath  path to a HAR file
+ * @param opts      { baseUrl, methods, onlyJson, title, version, format,
+ *                    dynamicPatterns }
+ * @returns         { text, doc, summary }
+ *
+ *   text     — the OpenAPI document serialised (default: YAML)
+ *   doc      — the same document as a JS object
+ *   summary  — { harEntries, recordsKept, endpoints, operations }
+ */
+function captureFromHarFile(filepath, opts = {}) {
+  const har = readHarFile(filepath);
+  const records = normaliseEntries(har, {
+    baseUrl: opts.baseUrl,
+    methods: opts.methods,
+    onlyJson: opts.onlyJson,
+  });
+  const doc = harToOpenapi(records, {
+    title: opts.title,
+    version: opts.version,
+    baseUrl: opts.baseUrl,
+    dynamicPatterns: opts.dynamicPatterns,
+  });
+
+  const fmt = String(opts.format || 'yaml').toLowerCase();
+  const text = fmt === 'json'
+    ? JSON.stringify(doc, null, 2) + '\n'
+    : yaml.dump(doc, { noRefs: true, sortKeys: false, lineWidth: 120 });
+
+  return {
+    text,
+    doc,
+    summary: {
+      harEntries: har.log.entries.length,
+      recordsKept: records.length,
+      endpoints: Object.keys(doc.paths || {}).length,
+      operations: countOperations(doc),
+    },
+  };
+}
+
+function countOperations(doc) {
+  let n = 0;
+  const methods = ['get','post','put','patch','delete','head','options','trace'];
+  for (const item of Object.values(doc.paths || {})) {
+    for (const k of Object.keys(item)) if (methods.includes(k)) n++;
+  }
+  return n;
+}
+
+module.exports = { captureFromHarFile };

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 };