specshield 3.2.0 → 3.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specshield",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "description": "CLI for OpenAPI breaking change detection and bi-directional contract verification — with can-i-deploy gating, GitHub PR checks, and a first-run setup wizard.",
   "main": "src/cli.js",
   "bin": {

package/src/commands/bdct.js

@@ -41,7 +41,7 @@ function withProjectDefaults(opts, command) {
   try {
     applyBdctDefaults(opts, command);
   } catch (err) {
-    if (err.code === 'MISSING_REQUIRED_OPTIONS') {
+    if (err.code === 'MISSING_REQUIRED_OPTIONS' || err.code === 'UNRESOLVED_PLACEHOLDER') {
       logger.error(err.message);
       process.exit(2);
     }

package/src/commands/compare.js

@@ -31,7 +31,12 @@ compare
   .option('--allow-breaking', 'Override fail-on-breaking behavior')
   .option('--config <path>', 'Path to .specshield.yml config file')
   .option('--ignore <change>', 'Ignore a specific change string (repeatable)', collect, [])
-  .option('--severity <level>', 'Minimum severity level: info | warning | error', 'error')
+  // Default severity is 'info' so additions and modifications are visible
+  // by default. Customers expect a diff summary to list ALL changes, with
+  // severity coloring/filtering as an opt-in narrowing. The previous default
+  // of 'error' silently hid every non-breaking change, which read as "0
+  // additions / 0 modifications" even when both existed.
+  .option('--severity <level>', 'Minimum severity level: info | warning | error', 'info')
   .option('--remote', 'Use the SpecShield hosted compare API')
   .option('--api-key <key>', 'API key for hosted mode (overrides env and stored config)')
   .option('--remote-url <url>', 'Override the hosted API base URL')

package/src/commands/init.js

@@ -25,6 +25,17 @@ const DEFAULT_SERVER = 'https://specshield.io';
 
 // ─── Helpers ───────────────────────────────────────────────────────────────
 
+const PLACEHOLDER = '<replace-me>';
+
+// Skippable text fields in the interactive wizard. Empty values for these
+// become PLACEHOLDER tokens in the generated config; non-skippable fields
+// (kind, contractFormat, environment which has a default) are not in this list.
+const PLACEHOLDER_FIELDS = [
+  'providerName', 'specPath',
+  'consumerName', 'consumerProvider', 'contractPath',
+  'org',
+];
+
 function abortIfCancelled(answers, keys) {
   // `prompts` returns undefined values when the user hits Ctrl-C.
   for (const k of keys) {
@@ -35,6 +46,42 @@ function abortIfCancelled(answers, keys) {
   }
 }
 
+/**
+ * Replace empty answers with the PLACEHOLDER token so the generated config
+ * makes the gap visible (vs writing an empty string the user might miss).
+ * Only operates on the fields listed in PLACEHOLDER_FIELDS — required
+ * non-text choices like `kind` are left untouched.
+ */
+function fillPlaceholders(answers) {
+  for (const f of PLACEHOLDER_FIELDS) {
+    if (answers[f] === '' || answers[f] === null || answers[f] === undefined) continue;
+    // Keep the value the user entered.
+  }
+  for (const f of PLACEHOLDER_FIELDS) {
+    if (answers[f] === '' || answers[f] === null) answers[f] = PLACEHOLDER;
+  }
+}
+
+/**
+ * Walk a built config object and return a list of `{ path, value }` for every
+ * leaf whose value equals PLACEHOLDER. The `path` is the dotted YAML path
+ * (e.g. `bdct.org`, `bdct.provider.spec`) — same form the user sees when
+ * editing the .specshield.yml file.
+ */
+function collectPlaceholders(cfg) {
+  const out = [];
+  const walk = (obj, prefix) => {
+    if (!obj || typeof obj !== 'object') return;
+    for (const [k, v] of Object.entries(obj)) {
+      const p = prefix ? `${prefix}.${k}` : k;
+      if (v === PLACEHOLDER) out.push({ path: p, value: v });
+      else if (v && typeof v === 'object') walk(v, p);
+    }
+  };
+  walk(cfg, '');
+  return out;
+}
+
 async function validateApiKey(server, key) {
   try {
     const res = await axios.post(`${server.replace(/\/$/, '')}/auth/validate-api-key`,
@@ -156,12 +203,21 @@ async function interactiveFlow(detected, opts) {
   const wantsProvider = k.kind === 'provider' || k.kind === 'both';
   const wantsConsumer = k.kind === 'consumer' || k.kind === 'both';
 
+  // Optional-by-default prompts. Pressing Enter on any text field is OK
+  // and produces a "<replace-me>" placeholder in the generated config —
+  // surfaced at the end of the wizard and refused by any bdct command
+  // that later tries to use it. Lets a user explore the wizard without
+  // having to know their org key or provider name up front.
+  const skipHint = chalk.gray('(press Enter to skip — fill in later)');
+
   if (wantsProvider) {
     const provQs = [
-      { type: 'text', name: 'providerName', message: 'Provider name', initial: detected.serviceName },
-      { type: 'text', name: 'specPath',     message: 'Path to provider OpenAPI spec',
-        initial: detected.spec || 'api/openapi.yaml',
-        validate: (v) => v ? true : 'Required',
+      { type: 'text', name: 'providerName',
+        message: `Provider name ${skipHint}`,
+        initial: detected.serviceName },
+      { type: 'text', name: 'specPath',
+        message: `Path to provider OpenAPI spec ${skipHint}`,
+        initial: detected.spec || 'openapi.yaml',
       },
     ];
     const r = await prompts(provQs);
@@ -171,15 +227,14 @@ async function interactiveFlow(detected, opts) {
 
   if (wantsConsumer) {
     const consQs = [
-      { type: 'text', name: 'consumerName',     message: 'Consumer name',
+      { type: 'text', name: 'consumerName',
+        message: `Consumer name ${skipHint}`,
         initial: detected.serviceName },
-      { type: 'text', name: 'consumerProvider', message: 'Provider this consumer talks to',
-        validate: (v) => v ? true : 'Required',
-      },
-      { type: 'text', name: 'contractPath',     message: 'Path to consumer contract',
-        initial: 'contracts/contract.yaml',
-        validate: (v) => v ? true : 'Required',
-      },
+      { type: 'text', name: 'consumerProvider',
+        message: `Provider this consumer talks to ${skipHint}` },
+      { type: 'text', name: 'contractPath',
+        message: `Path to consumer contract ${skipHint}`,
+        initial: 'contracts/contract.yaml' },
       { type: 'select', name: 'contractFormat', message: 'Contract format',
         choices: [
           { title: 'OpenAPI', value: 'OPENAPI' },
@@ -243,8 +298,8 @@ async function interactiveFlow(detected, opts) {
       });
       abortIfCancelled(r, ['org']);
       if (r.org === '__manual__') {
-        const m = await prompts({ type: 'text', name: 'org', message: 'Org key',
-          validate: (v) => v ? true : 'Required' });
+        const m = await prompts({ type: 'text', name: 'org',
+          message: `Org key ${skipHint}` });
         abortIfCancelled(m, ['org']);
         answers.org = m.org;
       } else {
@@ -252,8 +307,8 @@ async function interactiveFlow(detected, opts) {
       }
     } else {
       const r = await prompts({
-        type: 'text', name: 'org', message: 'Org key',
-        validate: (v) => v ? true : 'Required',
+        type: 'text', name: 'org',
+        message: `Org key ${skipHint}`,
       });
       abortIfCancelled(r, ['org']);
       answers.org = r.org;
@@ -326,6 +381,43 @@ function nonInteractiveFlow(detected, opts) {
   return answers;
 }
 
+// ─── Preview flow ──────────────────────────────────────────────────────────
+
+/**
+ * Used by `specshield init --print`. Behaves like `nonInteractiveFlow` but
+ * substitutes a "<replace-me>" placeholder for any required field the user
+ * didn't supply, instead of erroring out. The header comment printed
+ * alongside the YAML tells the user where to fill these in.
+ *
+ * Kind defaults to "provider" if a spec was detected (the most common
+ * case), else "skip" (local-compare-only).
+ */
+function previewFlow(detected, opts) {
+  const PLACEHOLDER = '<replace-me>';
+  const kind = opts.kind || (detected.spec ? 'provider' : 'skip');
+
+  const answers = {
+    kind,
+    server:      opts.server      || DEFAULT_SERVER,
+    org:         opts.org         || (kind === 'skip' ? null : PLACEHOLDER),
+    environment: opts.env         || detected.environment || 'staging',
+  };
+
+  if (kind === 'provider' || kind === 'both') {
+    answers.providerName = opts.provider || detected.serviceName || PLACEHOLDER;
+    answers.specPath     = opts.spec     || detected.spec        || PLACEHOLDER;
+  }
+  if (kind === 'consumer' || kind === 'both') {
+    answers.consumerName     = opts.consumer         || detected.serviceName || PLACEHOLDER;
+    answers.consumerProvider = opts.consumerProvider || PLACEHOLDER;
+    answers.contractPath     = opts.contract         || PLACEHOLDER;
+    answers.contractFormat   = opts.format           || 'OPENAPI';
+  }
+
+  answers.writeWorkflow = !!opts.writeWorkflow;
+  return answers;
+}
+
 // ─── Command ───────────────────────────────────────────────────────────────
 
 const initCommand = new Command('init')
@@ -349,12 +441,19 @@ const initCommand = new Command('init')
     const detected = detectAll(cwd);
 
     let answers;
-    if (opts.interactive === false) {
+    if (opts.print) {
+      // --print is documented as a dry-run that detects everything and writes
+      // a proposed YAML without prompting. Route it through the non-interactive
+      // flow (with relaxed validation — see previewFlow) so it truly never asks
+      // questions, even if the user didn't pass --no-interactive or all the
+      // required scripted-mode flags.
+      answers = previewFlow(detected, opts);
+    } else if (opts.interactive === false) {
       // In non-interactive mode, refuse to overwrite an existing config unless
       // --force is passed. Prevents a CI script from silently clobbering a
       // hand-edited .specshield.yml that has settings the wizard wouldn't
       // regenerate (custom branch, different provider name, etc.).
-      if (detected.existing && !opts.force && !opts.print) {
+      if (detected.existing && !opts.force) {
         logger.error(
           '.specshield.yml already exists. Pass --force to overwrite, or remove the file first.');
         process.exit(2);
@@ -365,11 +464,24 @@ const initCommand = new Command('init')
       if (answers === null) return;     // user said "don't overwrite"
     }
 
+    // Empty answers from the interactive flow → "<replace-me>" placeholders.
+    // The end-of-wizard summary lists every placeholder by path so users
+    // don't accidentally commit them.
+    fillPlaceholders(answers);
+
     const cfg  = buildConfig(answers, detected);
     const yaml = render(cfg);
 
     if (opts.print) {
-      process.stdout.write('\n' + yaml);
+      // Header comment makes it obvious this was a dry-run + flags any
+      // placeholders the user will need to fill in before committing.
+      process.stdout.write(
+        '\n# ─────────────────────────────────────────────────────────────\n' +
+        '#  specshield init --print — DRY RUN. No files were written.\n' +
+        '#  Review the YAML below; replace any "<replace-me>" placeholders\n' +
+        '#  before running `specshield init` (without --print) for real.\n' +
+        '# ─────────────────────────────────────────────────────────────\n\n' +
+        yaml);
       return;
     }
 
@@ -383,10 +495,29 @@ const initCommand = new Command('init')
         providerName:        answers.providerName,
         consumerName:        answers.consumerName,
         providerForConsumer: answers.consumerProvider,
+        org:                 answers.org,
+        specPath:            answers.specPath,
+        contractPath:        answers.contractPath,
+        environment:         answers.environment,
       }, cwd);
       ok(`Wrote ${chalk.white(path.relative(cwd, workflowPath))}`);
     }
 
+    // Placeholders summary — if the user pressed Enter on any prompt,
+    // surface what's still missing so they can fill it in before running
+    // any bdct command. Pre-flight checks in bdct.js will block commands
+    // that hit a literal "<replace-me>" value at runtime.
+    const placeholders = collectPlaceholders(cfg);
+    if (placeholders.length > 0) {
+      fmtSection('Placeholders to fill in');
+      placeholders.forEach(p =>
+        warn(`${chalk.yellow(p.path)} = ${chalk.gray('<replace-me>')}`));
+      warn(chalk.yellow(
+        `Edit ${path.relative(cwd, target) || '.specshield.yml'} ` +
+        `to replace ${placeholders.length} placeholder${placeholders.length === 1 ? '' : 's'} ` +
+        `before running bdct commands.`));
+    }
+
     fmtSection('Next steps');
     if (answers.kind !== 'skip') {
       info(`Try: ${chalk.white('specshield bdct list-providers')}`);
@@ -397,3 +528,6 @@ const initCommand = new Command('init')
   });
 
 module.exports = initCommand;
+
+// Exposed for unit tests — keep usage internal to the init module otherwise.
+module.exports.__test__ = { fillPlaceholders, collectPlaceholders, PLACEHOLDER };

package/src/core/classifyChanges.js

@@ -21,6 +21,11 @@ const BREAKING_TYPES = new Set([
   'REQUEST_TYPE_CHANGED',
   'RESPONSE_TYPE_CHANGED',
   'SCHEMA_REMOVED',
+  // Constraint tightening: previously-valid values become invalid → breaking.
+  'CONSTRAINT_TIGHTENED',
+  // Pattern changes are treated as breaking (semantic safety: we can't
+  // tell whether the new pattern accepts a superset of the old).
+  'CONSTRAINT_PATTERN_CHANGED',
 ]);
 
 const ADDITION_TYPES = new Set([
@@ -36,6 +41,8 @@ const ADDITION_TYPES = new Set([
 const MODIFICATION_TYPES = new Set([
   'FIELD_BECAME_OPTIONAL',
   'PARAMETER_BECAME_OPTIONAL',
+  // Constraint relaxation: previously-rejected values now valid → safe change.
+  'CONSTRAINT_RELAXED',
 ]);
 
 const WARNING_TYPES = new Set([
@@ -83,9 +90,120 @@ function classifyChanges(diffs) {
     }
   }
 
+  // Dedupe $ref-driven changes. When a schema property is added/removed/typed,
+  // the change appears once per endpoint that references the schema — which
+  // produces "6 breaking changes" reports when really one schema field was
+  // removed and it rippled through 4 endpoints. Group entries with the same
+  // (type, leafFieldName) and collapse them into one entry that names every
+  // affected endpoint. See `mergeDuplicateFieldChanges` for the rules.
+  result.breakingChanges = mergeDuplicateFieldChanges(result.breakingChanges);
+  result.additions       = mergeDuplicateFieldChanges(result.additions);
+  result.modifications   = mergeDuplicateFieldChanges(result.modifications);
+  result.warnings        = mergeDuplicateFieldChanges(result.warnings);
+
   return result;
 }
 
+// Types whose multi-counting is almost always caused by a $ref'd component
+// schema being inlined into many endpoint responses/requests. Safe to dedupe.
+const FIELD_DEDUPE_TYPES = new Set([
+  'RESPONSE_FIELD_REMOVED',
+  'RESPONSE_FIELD_ADDED',
+  'RESPONSE_FIELD_TYPE_CHANGED',
+  'REQUEST_FIELD_REMOVED',
+  'REQUEST_FIELD_ADDED',
+  'REQUEST_FIELD_TYPE_CHANGED',
+  'REQUEST_REQUIRED_FIELD_ADDED',
+  'FIELD_BECAME_REQUIRED',
+  'FIELD_BECAME_OPTIONAL',
+  'ENUM_VALUE_REMOVED',
+]);
+
+/**
+ * Returns the leaf field name from a dotted/bracketed field path so we can
+ * dedupe by component-property name rather than full positional path.
+ *
+ *   responses.200.data[items].legacy_id  →  legacy_id
+ *   responses.201.legacy_id              →  legacy_id
+ *   requestBody.email                    →  email
+ *
+ * Both rows above share leaf "legacy_id", so they're recognised as the same
+ * schema-level change.
+ */
+function leafFieldName(field) {
+  if (!field) return null;
+  const parts = field.split('.');
+  const last = parts[parts.length - 1];
+  // Strip trailing array marker like "data[items]" → "data"
+  return last.replace(/\[.*$/, '');
+}
+
+/**
+ * Collapses entries that have the same (type, leafFieldName) into one entry
+ * with an `affectedEndpoints` array of every `${METHOD} ${path}` it appeared
+ * under. The original first-seen entry is kept as the canonical record; its
+ * description is rewritten to lead with the field name and end with the
+ * affected-endpoint count.
+ *
+ * Non-field types (ENDPOINT_*, METHOD_*, SCHEMA_*, PARAMETER_*) pass through
+ * untouched — they're already at the right granularity.
+ */
+function mergeDuplicateFieldChanges(entries) {
+  const groups = new Map();
+  const passthrough = [];
+
+  for (const change of entries) {
+    if (!FIELD_DEDUPE_TYPES.has(change.type) || !change.field) {
+      passthrough.push(change);
+      continue;
+    }
+    const leaf = leafFieldName(change.field);
+    const key = `${change.type}::${leaf}`;
+    if (!groups.has(key)) {
+      groups.set(key, { canonical: { ...change }, endpoints: [] });
+    }
+    if (change.path && change.method) {
+      groups.get(key).endpoints.push(`${change.method.toUpperCase()} ${change.path}`);
+    }
+  }
+
+  const merged = [];
+  for (const { canonical, endpoints } of groups.values()) {
+    if (endpoints.length <= 1) {
+      // Single occurrence — keep the original detailed description.
+      merged.push(canonical);
+      continue;
+    }
+    const leaf = leafFieldName(canonical.field);
+    canonical.affectedEndpoints = endpoints;
+    canonical.description = describeMergedChange(canonical.type, leaf, endpoints);
+    // Strip path/method from the canonical entry since it now applies to many.
+    canonical.path = null;
+    canonical.method = null;
+    merged.push(canonical);
+  }
+
+  return [...merged, ...passthrough];
+}
+
+function describeMergedChange(type, leaf, endpoints) {
+  const n = endpoints.length;
+  const VERBS = {
+    RESPONSE_FIELD_REMOVED:        `Response field "${leaf}" was removed`,
+    RESPONSE_FIELD_ADDED:          `Response field "${leaf}" was added`,
+    RESPONSE_FIELD_TYPE_CHANGED:   `Response field "${leaf}" changed type`,
+    REQUEST_FIELD_REMOVED:         `Request field "${leaf}" was removed`,
+    REQUEST_FIELD_ADDED:           `Request field "${leaf}" was added`,
+    REQUEST_FIELD_TYPE_CHANGED:    `Request field "${leaf}" changed type`,
+    REQUEST_REQUIRED_FIELD_ADDED:  `Required request field "${leaf}" was added`,
+    FIELD_BECAME_REQUIRED:         `Field "${leaf}" became required`,
+    FIELD_BECAME_OPTIONAL:         `Field "${leaf}" became optional`,
+    ENUM_VALUE_REMOVED:            `Enum value removed from "${leaf}"`,
+  };
+  const head = VERBS[type] || `Change in "${leaf}"`;
+  return `${head} (affects ${n} endpoint${n === 1 ? '' : 's'}: ${endpoints.join(', ')})`;
+}
+
 /**
  * Filter a classified result to only include changes at or above minSeverity.
  * info < warning < error

package/src/core/configWriter.js

@@ -137,10 +137,32 @@ function writeProjectConfig(config, cwd = process.cwd()) {
 /**
  * Render a starter GitHub Actions workflow that uses
  * `specshield26/bdct-action@v1`. Optional output of the wizard.
+ *
+ * Every input forwarded to the action MUST be present in the rendered YAML
+ * — including org. A missing org renders `--org ""` on the CLI invocation
+ * and the action fails with a cryptic "expected value" error from commander.
+ *
+ * spec/contract paths come from detection (or the user's --spec / --contract
+ * flag). They are NOT hardcoded — a previous version assumed every project
+ * stored its spec at `api/openapi.yaml`, which broke every project that
+ * keeps the spec at the repo root.
  */
-function renderWorkflow({ kind, providerName, consumerName, providerForConsumer }) {
+function renderWorkflow({
+  kind,
+  providerName,
+  consumerName,
+  providerForConsumer,
+  org,
+  specPath,
+  contractPath,
+  environment,
+}) {
   const isProvider = kind === 'provider' || kind === 'both';
   const isConsumer = kind === 'consumer' || kind === 'both';
+  const env = environment || 'production';
+  const orgLine = org ? `          org: ${org}` : '          org: <replace-me>';
+  const spec    = specPath     || 'openapi.yaml';
+  const contract = contractPath || 'contracts/contract.yaml';
 
   const lines = [
     '# .github/workflows/specshield-bdct.yml',
@@ -163,10 +185,11 @@ function renderWorkflow({ kind, providerName, consumerName, providerForConsumer
       '      - uses: specshield26/bdct-action@v1',
       '        with:',
       '          command: publish-provider',
+      orgLine,
       `          provider: ${providerName}`,
       '          version: ${{ github.sha }}',
-      '          spec: api/openapi.yaml',
-      '          env: production',
+      `          spec: ${spec}`,
+      `          env: ${env}`,
       '          api-token: ${{ secrets.SPECSHIELD_API_KEY }}',
       '',
       '  gate:',
@@ -176,9 +199,10 @@ function renderWorkflow({ kind, providerName, consumerName, providerForConsumer
       '      - uses: specshield26/bdct-action@v1',
       '        with:',
       '          command: can-i-deploy',
+      orgLine,
       `          service: ${providerName}`,
       '          version: ${{ github.sha }}',
-      '          env: production',
+      `          env: ${env}`,
       '          api-token: ${{ secrets.SPECSHIELD_API_KEY }}',
       '',
     );
@@ -193,10 +217,11 @@ function renderWorkflow({ kind, providerName, consumerName, providerForConsumer
       '      - uses: specshield26/bdct-action@v1',
       '        with:',
       '          command: publish-consumer',
+      orgLine,
       `          consumer: ${consumerName}`,
       `          provider: ${providerForConsumer}`,
       '          version: ${{ github.sha }}',
-      '          contract: contracts/contract.yaml',
+      `          contract: ${contract}`,
       '          api-token: ${{ secrets.SPECSHIELD_API_KEY }}',
       '',
     );

package/src/core/diffEngine.js

@@ -124,6 +124,11 @@ function diffParameters(path, method, baseParams, targetParams, diffs) {
           description: `Parameter "${bp.name}" became ${tp.required ? 'required' : 'optional'} in ${method.toUpperCase()} ${path}`,
         });
       }
+
+      // Constraint changes on the parameter's schema (min/max, length,
+      // pattern, enum). Tightening = breaking; loosening = modification.
+      diffConstraints(
+        path, method, `parameters.${bp.name}`, bp.schema, tp.schema, diffs);
     }
   }
 
@@ -260,6 +265,9 @@ function diffSchemaNode(path, method, fieldPrefix, base, target, diffs, isReques
       // Enum changes on field
       diffEnums(path, method, fullField, bField.enum, tField.enum, diffs);
 
+      // Constraint changes on the field's schema (min/max, length, pattern).
+      diffConstraints(path, method, fullField, bField, tField, diffs);
+
       // Recurse into nested objects
       if (bField.properties || tField.properties) {
         diffSchemaNode(path, method, fullField, bField, tField, diffs, isRequest);
@@ -317,6 +325,97 @@ function diffSchemaNode(path, method, fieldPrefix, base, target, diffs, isReques
   }
 }
 
+// ─── Constraints (min/max, length, pattern) ─────────────────────────────────
+
+/**
+ * Detects changes to numeric/string constraint fields on a schema node.
+ * Classification is direction-aware:
+ *
+ *   maximum increased / minimum decreased / maxLength increased / etc.
+ *     → CONSTRAINT_RELAXED (modification — existing clients still valid)
+ *
+ *   maximum decreased / minimum increased / maxLength decreased / etc.
+ *     → CONSTRAINT_TIGHTENED (breaking — previously-valid values now rejected)
+ *
+ *   pattern added/changed/removed
+ *     → CONSTRAINT_PATTERN_CHANGED (breaking; semantic comparison is too hard
+ *        to do safely so we treat any change as potentially restrictive)
+ *
+ * `null` on either side means "not constrained" — adding a constraint is
+ * tightening, removing one is relaxing.
+ */
+function diffConstraints(path, method, fieldPrefix, base, target, diffs) {
+  if (!base || !target) return;
+
+  // Direction map: how to interpret a numeric change for each constraint.
+  // 'upper' constraints (maximum, maxLength, maxItems): higher = looser.
+  // 'lower' constraints (minimum, minLength, minItems): lower = looser.
+  const UPPER = ['maximum', 'maxLength', 'maxItems'];
+  const LOWER = ['minimum', 'minLength', 'minItems'];
+
+  for (const key of UPPER) {
+    pushNumericConstraint(path, method, fieldPrefix, key, base[key], target[key], 'upper', diffs);
+  }
+  for (const key of LOWER) {
+    pushNumericConstraint(path, method, fieldPrefix, key, base[key], target[key], 'lower', diffs);
+  }
+
+  // pattern: any change is treated as a tightening (breaking). Adding or
+  // removing a pattern also counts.
+  if ((base.pattern || null) !== (target.pattern || null)) {
+    diffs.push({
+      type: 'CONSTRAINT_PATTERN_CHANGED',
+      path, method, field: fieldPrefix,
+      oldValue: base.pattern || null,
+      newValue: target.pattern || null,
+      description: target.pattern
+        ? `Pattern constraint on "${fieldPrefix}" changed from ${base.pattern ? `/${base.pattern}/` : '(none)'} to /${target.pattern}/ in ${method.toUpperCase()} ${path}`
+        : `Pattern constraint on "${fieldPrefix}" was removed from ${method.toUpperCase()} ${path}`,
+    });
+  }
+}
+
+function pushNumericConstraint(path, method, field, key, oldVal, newVal, direction, diffs) {
+  // Treat null/undefined as "no constraint".
+  const had = oldVal !== null && oldVal !== undefined;
+  const has = newVal !== null && newVal !== undefined;
+
+  if (!had && !has) return;
+  if (had && has && oldVal === newVal) return;
+
+  // Adding a constraint where none existed → tightening (breaking).
+  if (!had && has) {
+    diffs.push({
+      type: 'CONSTRAINT_TIGHTENED',
+      path, method, field,
+      oldValue: null, newValue: String(newVal),
+      description: `${key} constraint added on "${field}" (now ${newVal}) — tightens "${method.toUpperCase()} ${path}"`,
+    });
+    return;
+  }
+  // Removing a constraint → relaxation (modification).
+  if (had && !has) {
+    diffs.push({
+      type: 'CONSTRAINT_RELAXED',
+      path, method, field,
+      oldValue: String(oldVal), newValue: null,
+      description: `${key} constraint removed from "${field}" — relaxes "${method.toUpperCase()} ${path}"`,
+    });
+    return;
+  }
+
+  // Both present, different value. Direction tells us whether higher = looser
+  // or higher = tighter for THIS constraint key.
+  const wentUp = newVal > oldVal;
+  const isRelaxation = (direction === 'upper' && wentUp) || (direction === 'lower' && !wentUp);
+  diffs.push({
+    type: isRelaxation ? 'CONSTRAINT_RELAXED' : 'CONSTRAINT_TIGHTENED',
+    path, method, field,
+    oldValue: String(oldVal), newValue: String(newVal),
+    description: `${key} on "${field}" changed from ${oldVal} to ${newVal} (${isRelaxation ? 'relaxed' : 'tightened'}) in ${method.toUpperCase()} ${path}`,
+  });
+}
+
 function diffEnums(path, method, fieldPrefix, baseEnum, targetEnum, diffs) {
   if (!baseEnum || !targetEnum) return;
   for (const val of baseEnum) {

package/src/core/normalizeSpec.js

@@ -119,6 +119,18 @@ function resolveSchema(schema, schemas, depth = 0) {
     required: Array.isArray(schema.required) ? schema.required : [],
     properties: {},
     items: null,
+    // Constraint fields — preserved so the diff engine can detect changes
+    // to ranges/patterns/lengths (e.g. `maximum: 100` → `maximum: 250`).
+    // `undefined` (not present) and `null` are treated as "no constraint"
+    // by the diff engine; the explicit values flow through unchanged.
+    minimum:    schema.minimum    !== undefined ? schema.minimum    : null,
+    maximum:    schema.maximum    !== undefined ? schema.maximum    : null,
+    minLength:  schema.minLength  !== undefined ? schema.minLength  : null,
+    maxLength:  schema.maxLength  !== undefined ? schema.maxLength  : null,
+    minItems:   schema.minItems   !== undefined ? schema.minItems   : null,
+    maxItems:   schema.maxItems   !== undefined ? schema.maxItems   : null,
+    pattern:    schema.pattern    || null,
+    multipleOf: schema.multipleOf !== undefined ? schema.multipleOf : null,
   };
 
   if (schema.properties) {

package/src/core/parseSpec.js

@@ -5,23 +5,49 @@ const path = require('path');
 
 /**
  * Parse raw spec content (YAML or JSON) into a JavaScript object.
- * Detects format from file extension or content.
+ * Detects format from file extension or content. Validates that the parsed
+ * object looks like an OpenAPI 3.x or Swagger 2.x spec — otherwise a file
+ * containing arbitrary YAML/JSON would silently succeed with "No changes
+ * detected" instead of erroring out.
  */
 function parseSpec(content, filePath) {
   const ext = filePath ? path.extname(filePath).toLowerCase() : '';
 
+  let parsed;
   try {
     if (ext === '.json') {
-      return parseJson(content);
+      parsed = parseJson(content);
     } else if (ext === '.yaml' || ext === '.yml') {
-      return parseYaml(content);
+      parsed = parseYaml(content);
     } else {
       // Auto-detect: try JSON first, then YAML
-      return autoDetect(content);
+      parsed = autoDetect(content);
     }
   } catch (err) {
     throw new Error(`Failed to parse spec "${filePath}": ${err.message}`);
   }
+
+  assertLooksLikeOpenApi(parsed, filePath);
+  return parsed;
+}
+
+/**
+ * Confirms the parsed object has a top-level `openapi: "3.x"` or `swagger: "..."`
+ * key — the minimum surface that defines an OpenAPI/Swagger document. Without
+ * this check, a stray YAML/JSON file would silently compare as identical to
+ * anything that doesn't share its incidental keys.
+ */
+function assertLooksLikeOpenApi(parsed, filePath) {
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error(`"${filePath}" is not a valid OpenAPI/Swagger spec (parsed value was not an object)`);
+  }
+  const isOpenApi3 = typeof parsed.openapi === 'string' && parsed.openapi.startsWith('3.');
+  const isSwagger2 = typeof parsed.swagger === 'string';
+  if (!isOpenApi3 && !isSwagger2) {
+    throw new Error(
+      `"${filePath}" is not a valid OpenAPI/Swagger spec ` +
+      '(missing top-level "openapi: 3.x" or "swagger: ..." key)');
+  }
 }
 
 function parseJson(content) {

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]);

package/src/core/projectDetect.js

@@ -101,11 +101,16 @@ function detectServiceName(cwd) {
     const m = cargo.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
     if (m) return { source: 'Cargo.toml', name: m[1] };
   }
-  // pom.xml — naive single-line artifactId match (good enough for detection)
+  // pom.xml — naive artifactId match. We strip <parent>...</parent> first
+  // because every Spring Boot project has <parent><artifactId>spring-boot-starter-parent
+  // </artifactId></parent> ABOVE the project's own <artifactId>, and a plain
+  // regex match would pick the parent's name. With the parent block removed,
+  // the first <artifactId> we find is the project's own.
   const pom = readText(path.join(cwd, 'pom.xml'));
   if (pom) {
-    const m = pom.match(/<artifactId>([^<]+)<\/artifactId>/);
-    if (m) return { source: 'pom.xml', name: m[1] };
+    const stripped = pom.replace(/<parent>[\s\S]*?<\/parent>/g, '');
+    const m = stripped.match(/<artifactId>([^<]+)<\/artifactId>/);
+    if (m) return { source: 'pom.xml', name: m[1].trim() };
   }
   // Fallback — directory name
   return { source: 'directory', name: path.basename(path.resolve(cwd)) };