specshield 3.0.0 → 3.1.2

package/src/core/configWriter.js

@@ -0,0 +1,221 @@
+'use strict';
+
+/**
+ * Render `.specshield.yml` from a structured config object.
+ *
+ * Hand-rolled YAML so we can interleave comments. The shape is small and
+ * stable; using `js-yaml.dump` would give us a clean file but no comments —
+ * comments are 80% of the value of the file for users reading it later.
+ *
+ * Schema (all keys optional except where noted):
+ *
+ *   {
+ *     schemaVersion: 1,
+ *     failOnBreaking: true,
+ *     severity: 'error',
+ *     bdct: {
+ *       org: 'acme-pay',                  // required
+ *       server: 'https://specshield.io',
+ *       environment: 'staging',
+ *       provider: { name, spec, branch },
+ *       consumer: { name, provider, contract, format }
+ *     },
+ *     github: { specPath, failOnBreaking, commentOnPr }
+ *   }
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const HEADER = [
+  '# .specshield.yml — generated by `specshield init`',
+  '#',
+  '# Picked up automatically by every `specshield` invocation in this directory.',
+  '# CLI flags always override values in this file.',
+  '# Safe to commit. Never put your API key here — keep it in ~/.specshield/config.json',
+  '# or set SPECSHIELD_API_KEY in CI.',
+  '',
+];
+
+function quoteIfNeeded(v) {
+  if (v === null || v === undefined) return null;
+  const s = String(v);
+  if (/^[\w./@:-]+$/.test(s)) return s;        // safe bare scalar
+  return JSON.stringify(s);                    // double-quoted, JSON is YAML-safe
+}
+
+function emit(lines, indent, key, value) {
+  if (value === null || value === undefined || value === '') return;
+  lines.push(`${' '.repeat(indent)}${key}: ${quoteIfNeeded(value)}`);
+}
+
+function emitBoolean(lines, indent, key, value) {
+  if (value === null || value === undefined) return;
+  lines.push(`${' '.repeat(indent)}${key}: ${value ? 'true' : 'false'}`);
+}
+
+function emitComment(lines, indent, text) {
+  lines.push(`${' '.repeat(indent)}# ${text}`);
+}
+
+function blank(lines) {
+  if (lines[lines.length - 1] !== '') lines.push('');
+}
+
+/**
+ * Build the YAML string. Returns the final document including a trailing newline.
+ */
+function render(config = {}) {
+  const lines = [...HEADER];
+
+  emit(lines, 0, 'schemaVersion', config.schemaVersion ?? 1);
+  blank(lines);
+
+  // ── Local compare defaults ────────────────────────────────────────────
+  emitComment(lines, 0, 'Local compare defaults — used by `specshield compare`.');
+  emitBoolean(lines, 0, 'failOnBreaking', config.failOnBreaking ?? true);
+  emit       (lines, 0, 'severity',       config.severity       ?? 'error');
+  blank(lines);
+
+  // ── BDCT section ──────────────────────────────────────────────────────
+  if (config.bdct && Object.keys(config.bdct).length > 0) {
+    emitComment(lines, 0, 'BDCT defaults — used by every `specshield bdct ...` command.');
+    lines.push('bdct:');
+    emit(lines, 2, 'org',         config.bdct.org);
+    if (config.bdct.server && config.bdct.server !== 'https://specshield.io') {
+      emit(lines, 2, 'server',    config.bdct.server);
+    }
+    emit(lines, 2, 'environment', config.bdct.environment);
+
+    if (config.bdct.provider) {
+      blank(lines);
+      emitComment(lines, 2, 'This project publishes a provider spec.');
+      lines.push('  provider:');
+      emit(lines, 4, 'name',   config.bdct.provider.name);
+      emit(lines, 4, 'spec',   config.bdct.provider.spec);
+      emit(lines, 4, 'branch', config.bdct.provider.branch);
+    }
+
+    if (config.bdct.consumer) {
+      blank(lines);
+      emitComment(lines, 2, 'This project publishes a consumer contract.');
+      lines.push('  consumer:');
+      emit(lines, 4, 'name',     config.bdct.consumer.name);
+      emit(lines, 4, 'provider', config.bdct.consumer.provider);
+      emit(lines, 4, 'contract', config.bdct.consumer.contract);
+      emit(lines, 4, 'format',   config.bdct.consumer.format ?? 'OPENAPI');
+    }
+    blank(lines);
+  }
+
+  // ── GitHub App defaults ───────────────────────────────────────────────
+  if (config.github && Object.keys(config.github).length > 0) {
+    emitComment(lines, 0, 'GitHub App + bdct-action defaults.');
+    lines.push('github:');
+    emit       (lines, 2, 'specPath',       config.github.specPath);
+    emitBoolean(lines, 2, 'failOnBreaking', config.github.failOnBreaking);
+    emitBoolean(lines, 2, 'commentOnPr',    config.github.commentOnPr);
+    blank(lines);
+  }
+
+  // Trim trailing blank lines, ensure exactly one trailing newline.
+  while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Write the rendered YAML to `<cwd>/.specshield.yml`. Creates parent dirs
+ * if needed (it shouldn't, but defensive). Returns the absolute path written.
+ */
+function writeProjectConfig(config, cwd = process.cwd()) {
+  const target = path.join(cwd, '.specshield.yml');
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, render(config), 'utf8');
+  return target;
+}
+
+/**
+ * Render a starter GitHub Actions workflow that uses
+ * `specshield26/bdct-action@v1`. Optional output of the wizard.
+ */
+function renderWorkflow({ kind, providerName, consumerName, providerForConsumer }) {
+  const isProvider = kind === 'provider' || kind === 'both';
+  const isConsumer = kind === 'consumer' || kind === 'both';
+
+  const lines = [
+    '# .github/workflows/specshield-bdct.yml',
+    '# Generated by `specshield init`. Edit freely.',
+    'name: SpecShield BDCT',
+    '',
+    'on:',
+    '  push:',
+    '    branches: [main]',
+    '',
+    'jobs:',
+  ];
+
+  if (isProvider) {
+    lines.push(
+      '  publish-provider:',
+      '    runs-on: ubuntu-latest',
+      '    steps:',
+      '      - uses: actions/checkout@v4',
+      '      - uses: specshield26/bdct-action@v1',
+      '        with:',
+      '          command: publish-provider',
+      `          provider: ${providerName}`,
+      '          version: ${{ github.sha }}',
+      '          spec: api/openapi.yaml',
+      '          env: production',
+      '          api-token: ${{ secrets.SPECSHIELD_API_KEY }}',
+      '',
+      '  gate:',
+      '    needs: publish-provider',
+      '    runs-on: ubuntu-latest',
+      '    steps:',
+      '      - uses: specshield26/bdct-action@v1',
+      '        with:',
+      '          command: can-i-deploy',
+      `          service: ${providerName}`,
+      '          version: ${{ github.sha }}',
+      '          env: production',
+      '          api-token: ${{ secrets.SPECSHIELD_API_KEY }}',
+      '',
+    );
+  }
+
+  if (isConsumer) {
+    lines.push(
+      '  publish-consumer:',
+      '    runs-on: ubuntu-latest',
+      '    steps:',
+      '      - uses: actions/checkout@v4',
+      '      - uses: specshield26/bdct-action@v1',
+      '        with:',
+      '          command: publish-consumer',
+      `          consumer: ${consumerName}`,
+      `          provider: ${providerForConsumer}`,
+      '          version: ${{ github.sha }}',
+      '          contract: contracts/contract.yaml',
+      '          api-token: ${{ secrets.SPECSHIELD_API_KEY }}',
+      '',
+    );
+  }
+
+  return lines.join('\n');
+}
+
+function writeWorkflow(spec, cwd = process.cwd()) {
+  const dir    = path.join(cwd, '.github', 'workflows');
+  const target = path.join(dir, 'specshield-bdct.yml');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(target, renderWorkflow(spec), 'utf8');
+  return target;
+}
+
+module.exports = {
+  render,
+  writeProjectConfig,
+  renderWorkflow,
+  writeWorkflow,
+};

package/src/core/projectConfig.js

@@ -0,0 +1,189 @@
+'use strict';
+
+/**
+ * Load `.specshield.yml` from the working directory (or any ancestor) and
+ * apply its defaults to a parsed CLI options object.
+ *
+ * Precedence at call time:
+ *   CLI flag  >  env var  >  .specshield.yml  >  hard-coded default
+ *
+ * Each `bdct` subcommand calls `applyBdctDefaults(opts, command)` after
+ * parsing args. Required-field validation happens here too — that way the
+ * CLI flags can stop being `requiredOption(...)` and fall through gracefully
+ * to the project config when the user is running from a configured repo.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const logger = require('../utils/logger');
+
+/**
+ * Walk upward from `start` looking for `.specshield.yml` or `.specshield.yaml`.
+ * Returns the absolute path of the first hit, or null.
+ */
+function findProjectConfigFile(start = process.cwd()) {
+  let dir = path.resolve(start);
+  // Bound walk to a sensible depth — never escape the user's home directory.
+  for (let i = 0; i < 20; i++) {
+    for (const name of ['.specshield.yml', '.specshield.yaml']) {
+      const candidate = path.join(dir, name);
+      if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+        return candidate;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+let cached = null;
+let cachedFor = null;
+
+/**
+ * Returns the parsed config object (or an empty `{}` if no file is found).
+ * Cached per-process for the same starting directory; tests can pass
+ * `{ noCache: true }` or call `clearCache()` to refetch.
+ */
+function loadProjectConfig(start = process.cwd(), { noCache = false } = {}) {
+  if (!noCache && cached !== null && cachedFor === start) return cached;
+
+  const file = findProjectConfigFile(start);
+  if (!file) {
+    cached = {}; cachedFor = start;
+    return cached;
+  }
+
+  let parsed = {};
+  try {
+    const raw = fs.readFileSync(file, 'utf8');
+    parsed = yaml.load(raw) || {};
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+      logger.warn(`Ignoring ${file}: top-level must be a YAML mapping.`);
+      parsed = {};
+    }
+  } catch (err) {
+    logger.warn(`Failed to read ${file}: ${err.message}. Continuing without project config.`);
+    parsed = {};
+  }
+
+  cached = { ...parsed, _file: file };
+  cachedFor = start;
+  return cached;
+}
+
+function clearCache() { cached = null; cachedFor = null; }
+
+/**
+ * Required-field declaration per BDCT subcommand. Same source-of-truth the
+ * old `requiredOption(...)` checks used; centralised here so missing fields
+ * produce a single, friendly error.
+ */
+const REQUIRED_FIELDS = {
+  'publish-provider': ['org', 'provider', 'version', 'spec'],
+  'publish-consumer': ['org', 'consumer', 'provider', 'version', 'contract'],
+  'verify':           ['org', 'consumer', 'consumerVersion', 'provider', 'providerVersion'],
+  'can-i-deploy':     ['org', 'service', 'version'],
+  'matrix':           ['org'],
+  'list':             ['org'],
+  'list-providers':   ['org'],
+  'list-consumers':   ['org'],
+};
+
+/**
+ * Map a CLI option name to a path inside `.specshield.yml > bdct`.
+ * Returns null when there is no defaulting rule for that option.
+ */
+function bdctDefaultFor(bdct, name, command) {
+  if (!bdct) return undefined;
+  switch (name) {
+    case 'org':         return bdct.org;
+    case 'server':      return bdct.server;
+    case 'env':         return bdct.environment;
+
+    case 'provider': {
+      // For consumer-side operations the provider lives under `bdct.consumer.provider`.
+      if (command === 'publish-consumer' || command === 'verify') {
+        return bdct.consumer && bdct.consumer.provider;
+      }
+      // For everything else it's the project's own provider name.
+      return bdct.provider && bdct.provider.name;
+    }
+    case 'consumer':    return bdct.consumer && bdct.consumer.name;
+    case 'service': {
+      // can-i-deploy service is whichever role the project owns.
+      return (bdct.provider && bdct.provider.name)
+          || (bdct.consumer && bdct.consumer.name);
+    }
+    case 'spec':        return bdct.provider && bdct.provider.spec;
+    case 'contract':    return bdct.consumer && bdct.consumer.contract;
+    case 'format':      return bdct.consumer && bdct.consumer.format;
+    case 'branch':      return bdct.provider && bdct.provider.branch;
+    default:            return undefined;
+  }
+}
+
+/**
+ * Mutates `opts` in place: for every CLI option that is currently undefined
+ * (or empty string), look up a default in the loaded project config.
+ *
+ * Then verify every required field for the given `command` is present.
+ * Throws an Error listing all missing fields if not.
+ */
+function applyBdctDefaults(opts, command, { cwd = process.cwd() } = {}) {
+  const cfg = loadProjectConfig(cwd);
+  const bdct = cfg.bdct;
+
+  const FIELDS = [
+    'org', 'server', 'env',
+    'provider', 'consumer', 'service',
+    'version', 'consumerVersion', 'providerVersion',
+    'spec', 'contract', 'format', 'branch',
+  ];
+
+  // Paths in the config file are interpreted relative to the config file's
+  // directory (not the CWD where the command was invoked). This lets a user
+  // run `specshield bdct publish-provider` from any subdirectory.
+  const configDir = cfg._file ? path.dirname(cfg._file) : cwd;
+  const resolvePath = (v) =>
+    !v || path.isAbsolute(v) ? v : path.resolve(configDir, v);
+
+  for (const f of FIELDS) {
+    if (opts[f] !== undefined && opts[f] !== '') continue;
+    const def = bdctDefaultFor(bdct, f, command);
+    if (def === undefined || def === null || def === '') continue;
+    opts[f] = (f === 'spec' || f === 'contract') ? resolvePath(def) : def;
+  }
+
+  // Required-field check.
+  const required = REQUIRED_FIELDS[command] || [];
+  const missing  = required.filter(k => !opts[k]);
+  if (missing.length > 0) {
+    const flagFor = (k) => '--' + k.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+    const msg = [
+      `Missing required ${missing.length === 1 ? 'option' : 'options'} for \`bdct ${command}\`: `
+        + missing.map(flagFor).join(', '),
+    ];
+    if (cfg._file) {
+      msg.push(`Set them as CLI flags or add them under \`bdct\` in ${cfg._file}.`);
+    } else {
+      msg.push('Pass them as CLI flags, or run `specshield init` to write a `.specshield.yml`.');
+    }
+    const err = new Error(msg.join('\n'));
+    err.code = 'MISSING_REQUIRED_OPTIONS';
+    err.missing = missing;
+    throw err;
+  }
+
+  return opts;
+}
+
+module.exports = {
+  findProjectConfigFile,
+  loadProjectConfig,
+  clearCache,
+  applyBdctDefaults,
+  REQUIRED_FIELDS,
+};

package/src/core/projectDetect.js

@@ -0,0 +1,180 @@
+'use strict';
+
+/**
+ * Detect project context for `specshield init`.
+ *
+ * Pure I/O: reads files inside `cwd`, returns a plain object.
+ * No prompting, no network. Each detector is independent and never throws —
+ * unknown values come back as `null` so callers can decide whether to
+ * prompt or fail.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const cp   = require('child_process');
+
+// Glob order matters — first hit wins for the auto-detected default,
+// later hits become "alternates" the wizard can offer in a multi-select.
+const SPEC_CANDIDATES = [
+  'api/openapi.yaml',  'api/openapi.yml',  'api/openapi.json',
+  'openapi.yaml',      'openapi.yml',      'openapi.json',
+  'spec/openapi.yaml', 'spec/openapi.yml', 'spec/openapi.json',
+  'docs/openapi.yaml', 'docs/openapi.yml', 'docs/openapi.json',
+  'swagger.yaml',      'swagger.yml',      'swagger.json',
+];
+
+function fileExists(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+function readText(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return null; }
+}
+
+function safeLoadYaml(p) {
+  try { return yaml.load(fs.readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+/**
+ * Returns true if the parsed object looks like an OpenAPI 3.x or Swagger 2.x spec.
+ * Cheap structural check — does not validate the full schema.
+ */
+function looksLikeOpenApi(parsed) {
+  if (!parsed || typeof parsed !== 'object') return false;
+  if (typeof parsed.openapi === 'string' && parsed.openapi.startsWith('3.')) return true;
+  if (typeof parsed.swagger === 'string') return true;
+  return false;
+}
+
+/**
+ * Find every plausible OpenAPI spec under `cwd` from the candidate list.
+ * Returns absolute paths in canonical order; the first entry is the
+ * "best" guess (existing-file order in `SPEC_CANDIDATES`).
+ */
+function findSpecCandidates(cwd) {
+  const matches = [];
+  for (const rel of SPEC_CANDIDATES) {
+    const abs = path.join(cwd, rel);
+    if (fileExists(abs)) {
+      const parsed = safeLoadYaml(abs);
+      matches.push({ rel, abs, valid: looksLikeOpenApi(parsed) });
+    }
+  }
+  return matches;
+}
+
+/**
+ * Best-guess service / provider name in priority order:
+ *   package.json name (with @scope stripped)
+ *   pyproject.toml [project] name
+ *   go.mod module last segment
+ *   Cargo.toml [package] name
+ *   pom.xml <artifactId>
+ *   directory name
+ */
+function detectServiceName(cwd) {
+  // package.json
+  const pkg = readJson(path.join(cwd, 'package.json'));
+  if (pkg && typeof pkg.name === 'string') {
+    return { source: 'package.json', name: pkg.name.replace(/^@[^/]+\//, '') };
+  }
+  // pyproject.toml — read just enough to find the name without a TOML parser
+  const pyproject = readText(path.join(cwd, 'pyproject.toml'));
+  if (pyproject) {
+    const m = pyproject.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
+    if (m) return { source: 'pyproject.toml', name: m[1] };
+  }
+  // go.mod
+  const goMod = readText(path.join(cwd, 'go.mod'));
+  if (goMod) {
+    const m = goMod.match(/^module\s+(\S+)/m);
+    if (m) return { source: 'go.mod', name: m[1].split('/').pop() };
+  }
+  // Cargo.toml
+  const cargo = readText(path.join(cwd, 'Cargo.toml'));
+  if (cargo) {
+    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)
+  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] };
+  }
+  // Fallback — directory name
+  return { source: 'directory', name: path.basename(path.resolve(cwd)) };
+}
+
+/**
+ * Read git remote + current branch. Returns `{ remote, owner, repo, branch }`
+ * with all fields null if the directory is not a git working tree.
+ */
+function detectGit(cwd) {
+  const out = (cmd) => {
+    try {
+      return cp.execSync(cmd, { cwd, stdio: ['ignore', 'pipe', 'ignore'] })
+               .toString().trim();
+    } catch { return null; }
+  };
+
+  const remote = out('git config --get remote.origin.url');
+  const branch = out('git symbolic-ref --short HEAD') || null;
+
+  let owner = null, repo = null;
+  if (remote) {
+    // Match git@host:owner/repo.git OR https://host/owner/repo(.git)?
+    const m = remote.match(/[:/]([^/:]+)\/([^/]+?)(?:\.git)?$/);
+    if (m) { owner = m[1]; repo = m[2]; }
+  }
+  return { remote, owner, repo, branch };
+}
+
+/**
+ * Suggest a default environment based on the current branch.
+ * `main` / `master` → "production", anything else → "staging".
+ */
+function suggestEnvironment(branch) {
+  if (!branch) return 'staging';
+  if (branch === 'main' || branch === 'master') return 'production';
+  return 'staging';
+}
+
+/**
+ * Top-level: run every detector and return one combined snapshot.
+ */
+function detectAll(cwd = process.cwd()) {
+  const specs    = findSpecCandidates(cwd);
+  const service  = detectServiceName(cwd);
+  const git      = detectGit(cwd);
+  const env      = suggestEnvironment(git.branch);
+  const existing = fileExists(path.join(cwd, '.specshield.yml'))
+                || fileExists(path.join(cwd, '.specshield.yaml'));
+
+  return {
+    cwd,
+    specs,
+    spec:        specs.find(s => s.valid)?.rel || specs[0]?.rel || null,
+    service,
+    serviceName: service.name,
+    git,
+    branch:      git.branch,
+    environment: env,
+    existing,
+  };
+}
+
+module.exports = {
+  SPEC_CANDIDATES,
+  looksLikeOpenApi,
+  findSpecCandidates,
+  detectServiceName,
+  detectGit,
+  suggestEnvironment,
+  detectAll,
+};