@elalfner/relevo 0.0.0-stage → 0.3.1

package/scripts/lib/can-edit-issue.mjs

@@ -0,0 +1,34 @@
+// Decides whether the description of an issue may be rewritten.
+// Implements "Only an issue Relevo has not committed to a build may be edited" of openspec/specs/issue/spec.md.
+import { LABELS, resolveLabelNames } from './labels.mjs';
+
+// Why each lifecycle label closes the issue to editing. `needs-spec` is the only one that leaves it open.
+const REASON = {
+  ready: 'go starts it by itself, so the new text would be built without anyone rereading it',
+  queued: 'go starts it by itself when there is capacity',
+  blocked: 'go starts it by itself when its dependency merges',
+  building: 'the agent is building from the current text; wait for it to finish or fail',
+  built: 'a branch already exists and the text would no longer match what was built',
+  'in-review': 'it is being reviewed against the current text',
+  'pr-open': 'a pull request already exists for the current text',
+  'qa-failed': 'a branch already exists and the text would no longer match what was built',
+  'changes-requested': 'a branch already exists and the text would no longer match what was built',
+  'needs-reviewer': 'it is built and waiting for a reviewer',
+};
+export const EDITABLE_LABELS = ['needs-spec'];
+
+/**
+ * @param {{state?: string, labels?: Array<string|{name: string}>}} issue  `gh issue view --json state,labels`
+ * @param {Record<string,string>} [overrides]  the `labels` setting of relevo.yml
+ * @returns {{editable: true} | {editable: false, label?: string, reason: string}}
+ */
+export function canEditIssue(issue, overrides = {}) {
+  if (String(issue.state ?? '').toUpperCase() !== 'OPEN') return { editable: false, reason: 'the issue is closed' };
+  const names = resolveLabelNames(overrides);
+  const have = new Set((issue.labels ?? []).map((l) => (typeof l === 'string' ? l : l.name)));
+  for (const { key } of LABELS) {
+    if (EDITABLE_LABELS.includes(key) || !have.has(names[key])) continue;
+    return { editable: false, label: names[key], reason: REASON[key] };
+  }
+  return { editable: true };
+}

package/scripts/lib/checklist.mjs

@@ -0,0 +1,68 @@
+// Builds the review checklist from the scenarios of a change specification.
+// One checklist line per `#### Scenario:` found under `<change>/specs/**/spec.md`.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SCENARIO_RE = /^####\s+Scenario:\s*(.+?)\s*$/;
+const STEP_RE = /^\s*[-*]\s+\*\*(AND WHEN|WHEN|THEN|AND THEN|AND)\*\*\s*(.*?)\s*$/;
+
+/** Parse scenarios out of the text of one spec file. */
+export function scenariosFromSpec(text, source = '') {
+  const scenarios = [];
+  let current = null;
+  String(text).split('\n').forEach((line) => {
+    const heading = line.match(/^#{1,6}\s/);
+    const scenario = line.match(SCENARIO_RE);
+    if (scenario) {
+      current = { title: scenario[1], when: [], then: [], source };
+      scenarios.push(current);
+      return;
+    }
+    if (heading) {
+      current = null;
+      return;
+    }
+    const step = current && line.match(STEP_RE);
+    if (!step) return;
+    const [, kind, rest] = step;
+    if (kind.endsWith('WHEN') || (kind === 'AND' && current.then.length === 0)) current.when.push(rest);
+    else current.then.push(rest);
+  });
+  return scenarios;
+}
+
+function specFiles(dir) {
+  const out = [];
+  (function walk(d) {
+    readdirSync(d).sort().forEach((name) => {
+      const path = join(d, name);
+      if (statSync(path).isDirectory()) walk(path);
+      else if (name === 'spec.md') out.push(path);
+    });
+  }(dir));
+  return out;
+}
+
+/** All scenarios of a change directory, in file order. Returns [{ id, title, when, then, source }]. */
+export function checklistFromChange(changeDir) {
+  const specsDir = join(changeDir, 'specs');
+  const items = [];
+  specFiles(specsDir).forEach((file) => {
+    scenariosFromSpec(readFileSync(file, 'utf8'), file.slice(changeDir.length).replace(/^\/+/, '')).forEach((s) => items.push(s));
+  });
+  return items.map((s, i) => ({ id: i + 1, ...s }));
+}
+
+/** Markdown checklist, optionally with the items already confirmed ticked. */
+export function checklistMarkdown(items, statuses = {}, autos = {}) {
+  return items
+    .map((s) => {
+      const mark = statuses[s.id] === 'ok' ? 'x' : ' ';
+      const detail = [s.when.join(' and '), s.then.join(' and ')].filter(Boolean);
+      const text = detail.length === 2 ? `when ${detail[0]}, then ${detail[1]}` : detail.join('');
+      const auto = autos[s.id] ? ` _(verified automatically: ${autos[s.id]})_` : '';
+      return `- [${mark}] ${s.id}. **${s.title}**: ${text}${auto}`;
+    })
+    .join('\n');
+}

package/scripts/lib/cli.mjs

@@ -0,0 +1,82 @@
+// The commands behind `relevo`. They only drive `claude plugin`, so Claude Code stays the one place that installs
+// and updates a plugin; nothing here writes a file. `run` and `has` are injected so a test can use a fake `claude`.
+
+export const MARKETPLACE = 'elalfner/relevo';
+export const MARKETPLACE_NAME = 'relevo';
+export const PLUGIN_ID = 'relevo@relevo';
+export const SCOPES = ['user', 'project', 'local'];
+
+export const USAGE = [
+  'usage: relevo <command> [--scope user|project|local]',
+  '',
+  '  install   add the marketplace and install the plugin (default scope: user)',
+  '  update    update the marketplace and the plugin',
+  '  doctor    check this repository (the same as /relevo:doctor)',
+  '  version   print the version of this package',
+  '',
+  'user: every project of this machine. project: this repository, shared through .claude/settings.json. local: this repository, only you.'
+].join('\n');
+
+/** Parses the arguments; { error } when they are not valid. */
+export function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  if (!command || command === '--help' || command === '-h' || command === 'help') return { command: 'help' };
+  if (!['install', 'update', 'doctor', 'version'].includes(command)) return { error: `unknown command "${command}"` };
+  let scope = 'user';
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === '--scope') { scope = rest[i + 1]; i += 1; } else if (arg.startsWith('--scope=')) scope = arg.slice(8);
+    else return { error: `unknown option "${arg}"` };
+  }
+  if (!SCOPES.includes(scope)) return { error: `the scope must be one of ${SCOPES.join(', ')}` };
+  return { command, scope };
+}
+
+/** The `claude` invocations of a command, in order. */
+export function steps(command, scope) {
+  if (command === 'install') {
+    return [
+      { label: 'add the marketplace (only .claude-plugin/ is downloaded)', args: ['plugin', 'marketplace', 'add', MARKETPLACE, '--scope', scope, '--sparse', '.claude-plugin'] },
+      { label: 'install the plugin', args: ['plugin', 'install', PLUGIN_ID, '--scope', scope] }
+    ];
+  }
+  if (command === 'update') {
+    return [
+      { label: 'update the marketplace', args: ['plugin', 'marketplace', 'update', MARKETPLACE_NAME] },
+      { label: 'update the plugin', args: ['plugin', 'update', PLUGIN_ID, '--scope', scope] }
+    ];
+  }
+  return [];
+}
+
+/**
+ * Runs a command. Returns { code, lines }: the lines to print and the exit code. Stops at the first failing step
+ * and says which one, so the person knows what was already done.
+ */
+export function execute({ command, scope }, { run, has, version, doctorScript }) {
+  const lines = [];
+  if (command === 'version') return { code: 0, lines: [version] };
+  if (command === 'doctor') {
+    const r = run(process.execPath, [doctorScript]);
+    return { code: r.code, lines: [r.output.trimEnd()] };
+  }
+  if (!has('claude')) {
+    return { code: 1, lines: ['Claude Code is required and "claude" was not found on the path.', 'Install it (https://code.claude.com/docs) and run this command again; nothing was changed.'] };
+  }
+  const list = steps(command, scope);
+  for (let i = 0; i < list.length; i += 1) {
+    const step = list[i];
+    lines.push(`[${i + 1}/${list.length}] ${step.label}`);
+    const r = run('claude', step.args);
+    if (r.output.trim()) lines.push(r.output.trimEnd());
+    if (r.code !== 0) {
+      lines.push(`The step "${step.label}" failed${i > 0 ? `; the steps before it were done (${list.slice(0, i).map((s) => s.label).join(', ')})` : ''}. Fix the cause and run the command again: it is safe to repeat.`);
+      return { code: r.code || 1, lines };
+    }
+  }
+  const where = { user: 'for this machine', project: 'for this repository (declared in .claude/settings.json, so commit it to share it)', local: 'for this repository, only for you' }[scope];
+  lines.push(command === 'install'
+    ? `Relevo is installed ${where}. Restart Claude Code and run /relevo:doctor.`
+    : 'Relevo is up to date. Restart Claude Code to apply it.');
+  return { code: 0, lines };
+}

package/scripts/lib/commit-change.mjs

@@ -0,0 +1,57 @@
+// One safe way to commit: name the files, check protected paths, scan the diff, and only then commit.
+// Implements "Safe commits" of the go specification and "Protected paths" of the security specification.
+//
+// `git(args) -> stdout` is injected so the logic can be tested; the command-line wrapper runs the real git.
+
+import { checkScope } from './platform-scope.mjs';
+import { checkProtected, formatViolations } from './protected-paths.mjs';
+import { formatFindings, scanDiff } from './scan.mjs';
+import { explicitStageArgs } from './staging.mjs';
+
+/**
+ * Stage `paths`, check them and commit only them.
+ *   message    the commit message
+ *   paths      the files or folders to commit, named one by one (never "." or "-A")
+ *   allow      globs from the `Allow-paths:` line of the issue (dependency files only)
+ *   rulesFile  the project rules file (`qa.rules_from`), which is never changed
+ *   within     the folder of the platform of the issue: files outside it are refused (`.` or null: no limit)
+ *   change     the change id, whose specification folder may always be committed
+ * Returns { ok, commit, findings, violations }. When something is found nothing is committed and the named paths
+ * are unstaged again (files that were staged for other reasons stay staged).
+ */
+export function commitChange({ git, message, paths, allow = [], rulesFile = null, within = null, change = null }) {
+  if (!String(message ?? '').trim()) throw new Error('give a commit message');
+  const addArgs = explicitStageArgs(paths);
+
+  // A path that is protected is refused before anything is staged.
+  const named = checkProtected(paths, { allow, rulesFile });
+  if (named.violations.some((v) => v.tier === 'hard')) return { ok: false, commit: null, findings: [], violations: named.violations };
+
+  git(addArgs);
+  const unstage = () => git(['reset', '-q', '--', ...paths]);
+
+  // The folders named above may hold protected files: check what is really staged under them.
+  const staged = git(['diff', '--cached', '--name-only', '--', ...paths]).split('\n').filter(Boolean);
+  const violations = [
+    ...checkProtected(staged, { allow, rulesFile }).violations,
+    ...checkScope(staged, { within, change, allow }).violations,
+  ];
+  const findings = scanDiff(git(['diff', '--cached', '-U0', '--', ...paths]));
+  if (violations.length > 0 || findings.length > 0) {
+    unstage();
+    return { ok: false, commit: null, findings, violations };
+  }
+  if (staged.length === 0) throw new Error('nothing to commit: none of the named paths has changes');
+
+  // `--` with paths commits only those paths, so files staged for another reason are left alone.
+  git(['commit', '-q', '-m', message, '--', ...paths]);
+  return { ok: true, commit: git(['rev-parse', '--short', 'HEAD']).trim(), findings: [], violations: [] };
+}
+
+/** The lines to print when a commit was refused. Never contains a secret. */
+export function refusalText({ findings, violations }) {
+  const lines = [];
+  if (violations.length > 0) lines.push(formatViolations(violations));
+  if (findings.length > 0) lines.push(formatFindings(findings));
+  return lines.join('\n');
+}

package/scripts/lib/config.mjs

@@ -0,0 +1,296 @@
+// Schema, defaults and validation for relevo.yml.
+// Implements openspec/specs/configuration/spec.md.
+
+import { parse, YamlLiteError } from './yaml-lite.mjs';
+import { LABEL_KEYS } from './labels.mjs';
+import { SUPPORTED_LANGUAGES } from './messages.mjs';
+import { findCredentials } from './scan.mjs';
+import { normalizePlatforms } from './platforms.mjs';
+
+// One entry per supported setting. `required: true` means there is no default.
+export const SETTINGS = [
+  { path: 'branches.base', type: 'string', default: 'dev' },
+  { path: 'branches.release', type: 'string', default: 'main' },
+  { path: 'tracker', type: 'enum', allowed: ['github'], default: 'github' },
+  { path: 'git_provider', type: 'enum', allowed: ['github'], default: 'github' },
+  { path: 'team.members', type: 'string[]', default: [] },
+  { path: 'team.spec_writer', type: 'string', default: null },
+  { path: 'team.approvers', type: 'string[]', default: [] },
+  { path: 'review.mode', type: 'enum', allowed: ['none', 'peer', 'roles'], default: 'peer' },
+  { path: 'review.merger', type: 'enum', allowed: ['author', 'approver'], default: 'approver' },
+  { path: 'review.autopilot', type: 'enum', allowed: ['off', 'precheck', 'verify'], default: 'off' },
+  { path: 'review.allowed_origins', type: 'origin-list', default: [] },
+  { path: 'limits.built_unreviewed_per_person', type: 'int', min: 1, default: 2 },
+  { path: 'limits.concurrent_agents', type: 'int', min: 1, default: 3 },
+  { path: 'limits.review_sla_hours', type: 'int', min: 1, default: 8 },
+  { path: 'limits.run_max_turns', type: 'int', min: 1, default: 100 },
+  { path: 'limits.building_alert_hours', type: 'int', min: 1, default: 3 },
+  { path: 'limits.run_max_cost', type: 'number', exclusiveMin: 0, required: true },
+  { path: 'qa.retries', type: 'int', min: 0, default: 1 },
+  { path: 'qa.rules_from', type: 'path-list', default: [] },
+  { path: 'skills.allow_scripts', type: 'string[]', default: [] },
+  { path: 'links', type: 'repo-list', default: [] },
+  { path: 'evidence.policy', type: 'enum', allowed: ['attach_to_pr', 'local_only'], default: 'attach_to_pr' },
+  { path: 'digest.issue', type: 'int', min: 1, default: null },
+  { path: 'language', type: 'string', default: 'en' },
+  { path: 'design.images', type: 'bool', default: false },
+  { path: 'trust', type: 'enum', allowed: ['private-team', 'public'], default: 'private-team' },
+];
+
+const GROUPS = new Set(SETTINGS.filter((s) => s.path.includes('.')).map((s) => s.path.split('.')[0]));
+const TOP_SCALARS = new Set(SETTINGS.filter((s) => !s.path.includes('.')).map((s) => s.path));
+const KNOWN_TOP = new Set([...GROUPS, ...TOP_SCALARS, 'labels', 'platform', 'platforms']);
+const ORIGIN_RE = /^https?:\/\/[A-Za-z0-9.-]+(?::\d{1,5})?$/;
+const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const LANGUAGE_RE = /^[a-z]{2}(-[A-Z]{2})?$/;
+const GITHUB_LABEL_MAX = 50;
+
+function getPath(obj, path) {
+  return path.split('.').reduce((acc, key) => (acc && typeof acc === 'object' ? acc[key] : undefined), obj);
+}
+
+function setPath(obj, path, value) {
+  const keys = path.split('.');
+  let cursor = obj;
+  keys.slice(0, -1).forEach((key) => {
+    if (typeof cursor[key] !== 'object' || cursor[key] === null) cursor[key] = {};
+    cursor = cursor[key];
+  });
+  cursor[keys[keys.length - 1]] = value;
+}
+
+function describeAllowed(allowed) {
+  return allowed.map((v) => `"${v}"`).join(', ');
+}
+
+function checkType(setting, value, errors) {
+  const { path } = setting;
+  switch (setting.type) {
+    case 'string':
+      if (typeof value !== 'string' || value.trim() === '') {
+        errors.push({ path, message: `${path} must be a non-empty string (got ${JSON.stringify(value)})` });
+      }
+      break;
+    case 'string[]':
+      if (!Array.isArray(value) || value.some((v) => typeof v !== 'string' || v.trim() === '')) {
+        errors.push({ path, message: `${path} must be a list of non-empty strings (got ${JSON.stringify(value)})` });
+      }
+      break;
+    case 'path-list':
+      if (!Array.isArray(value) || value.length === 0 || value.some((v) => typeof v !== 'string' || v.trim() === '')) {
+        errors.push({ path, message: `${path} must be a file name or a list of file names (got ${JSON.stringify(value)})` });
+      }
+      break;
+    case 'repo-list': {
+      if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+        errors.push({ path, message: `${path} must be a list of repositories written owner/repo (got ${JSON.stringify(value)})` });
+        break;
+      }
+      value.filter((v) => !REPO_RE.test(v)).forEach((v) => errors.push({ path, message: `${path}: "${v}" is not a repository; the form is owner/repo` }));
+      value.filter((v, i) => value.indexOf(v) !== i).forEach((v) => errors.push({ path, message: `${path} lists "${v}" more than once` }));
+      break;
+    }
+    case 'origin-list': {
+      if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+        errors.push({ path, message: `${path} must be a list of web origins written like https://staging.example.com (got ${JSON.stringify(value)})` });
+        break;
+      }
+      value.filter((v) => !ORIGIN_RE.test(v)).forEach((v) => errors.push({ path, message: `${path}: "${v}" is not an origin; write the scheme, the host and optionally the port, with no path (https://staging.example.com)` }));
+      break;
+    }
+    case 'enum':
+      if (!setting.allowed.includes(value)) {
+        errors.push({
+          path,
+          message: `${path} has invalid value ${JSON.stringify(value)}; allowed values: ${describeAllowed(setting.allowed)}`,
+        });
+      }
+      break;
+    case 'bool':
+      if (typeof value !== 'boolean') errors.push({ path, message: `${path} must be true or false (got ${JSON.stringify(value)})` });
+      break;
+    case 'int':
+      if (!Number.isInteger(value) || value < setting.min) {
+        errors.push({ path, message: `${path} must be an integer >= ${setting.min} (got ${JSON.stringify(value)})` });
+      }
+      break;
+    case 'number':
+      if (typeof value !== 'number' || !(value > setting.exclusiveMin)) {
+        errors.push({ path, message: `${path} must be a number > ${setting.exclusiveMin} (got ${JSON.stringify(value)})` });
+      }
+      break;
+    default:
+      break;
+  }
+}
+
+function collectStrings(value, path, out) {
+  if (typeof value === 'string') out.push({ path, value });
+  else if (Array.isArray(value)) value.forEach((v, i) => collectStrings(v, `${path}[${i}]`, out));
+  else if (value && typeof value === 'object') {
+    Object.entries(value).forEach(([k, v]) => collectStrings(v, path ? `${path}.${k}` : k, out));
+  }
+}
+
+/**
+ * Validate a parsed configuration object.
+ * Returns { ok, errors, warnings, config } where config has defaults applied.
+ */
+export function validateConfig(raw, { knownTargets = null, knownChecks = null } = {}) {
+  const errors = [];
+  const warnings = [];
+  const user = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    errors.push({ path: '', message: 'relevo.yml must be a map of settings' });
+  }
+
+  // Unknown top-level keys and unknown keys inside groups (catches typos).
+  Object.keys(user).forEach((key) => {
+    if (!KNOWN_TOP.has(key)) errors.push({ path: key, message: `unknown setting "${key}"` });
+  });
+  GROUPS.forEach((group) => {
+    const value = user[group];
+    if (value === undefined || value === null) return;
+    if (typeof value !== 'object' || Array.isArray(value)) {
+      errors.push({ path: group, message: `${group} must be a map` });
+      return;
+    }
+    const known = new Set(SETTINGS.filter((s) => s.path.startsWith(`${group}.`)).map((s) => s.path.split('.')[1]));
+    Object.keys(value).forEach((k) => {
+      if (!known.has(k)) errors.push({ path: `${group}.${k}`, message: `unknown setting "${group}.${k}"` });
+    });
+  });
+
+  // Per-setting checks and defaults.
+  const config = {};
+  SETTINGS.forEach((setting) => {
+    const value = getPath(user, setting.path);
+    if (value === undefined || value === null) {
+      if (setting.required) {
+        errors.push({
+          path: setting.path,
+          message: `${setting.path} is required: unattended runs must always have a cost limit (amount in US dollars per run)`,
+        });
+        return;
+      }
+      setPath(config, setting.path, structuredClone(setting.default));
+      return;
+    }
+    // A single file name is the same as a list of one.
+    const given = setting.type === 'path-list' && typeof value === 'string' ? [value] : value;
+    checkType(setting, given, errors);
+    setPath(config, setting.path, given);
+  });
+
+  // Platforms: the registry, or the legacy shortcut turned into one entry.
+  const normalized = normalizePlatforms({ platform: user.platform, platforms: user.platforms }, { knownTargets });
+  errors.push(...normalized.errors);
+  config.platforms = normalized.platforms;
+  if (knownChecks) {
+    Object.entries(config.platforms).forEach(([name, entry]) => {
+      const valid = knownChecks(entry.stack);
+      if (!valid) return;
+      Object.keys(entry.checks ?? {}).filter((c) => !valid.includes(c)).forEach((c) => {
+        errors.push({ path: `platforms.${name}.checks.${c}`, message: `platforms.${name}.checks has unknown command "${c}"; the stack "${entry.stack}" defines: ${valid.join(', ')}` });
+      });
+    });
+  }
+
+  // Labels: renameable, unique, within GitHub's length limit.
+  const labels = user.labels;
+  config.labels = {};
+  if (labels !== undefined && labels !== null) {
+    if (typeof labels !== 'object' || Array.isArray(labels)) {
+      errors.push({ path: 'labels', message: 'labels must be a map of label key to label name' });
+    } else {
+      Object.entries(labels).forEach(([key, name]) => {
+        if (!LABEL_KEYS.includes(key)) {
+          errors.push({ path: `labels.${key}`, message: `unknown label key "${key}"; allowed keys: ${describeAllowed(LABEL_KEYS)}` });
+        } else if (typeof name !== 'string' || name.trim() === '' || name.length > GITHUB_LABEL_MAX) {
+          errors.push({ path: `labels.${key}`, message: `labels.${key} must be a non-empty string of at most ${GITHUB_LABEL_MAX} characters` });
+        } else {
+          config.labels[key] = name;
+        }
+      });
+      const names = Object.values(config.labels);
+      if (new Set(names).size !== names.length) {
+        errors.push({ path: 'labels', message: 'label names must be unique' });
+      }
+    }
+  }
+
+  // Language: any language tag; only some have message catalogs.
+  const lang = config.language;
+  if (typeof lang === 'string') {
+    if (!LANGUAGE_RE.test(lang)) {
+      errors.push({ path: 'language', message: `language must look like "en" or "pt-BR" (got ${JSON.stringify(lang)})` });
+    } else if (!SUPPORTED_LANGUAGES.includes(lang.split('-')[0])) {
+      warnings.push({
+        path: 'language',
+        message: `no message catalog for "${lang}"; messages fall back to "en" (available: ${SUPPORTED_LANGUAGES.join(', ')})`,
+      });
+    }
+  }
+
+  // Cross-setting rules.
+  if (config.review.mode === 'roles' && config.team.approvers.length === 0) {
+    errors.push({ path: 'team.approvers', message: 'team.approvers must list at least one person when review.mode is "roles"' });
+  }
+  if (config.trust === 'public' && config.review.mode === 'none') {
+    errors.push({ path: 'review.mode', message: 'trust "public" needs a human review of generated code: review.mode cannot be "none"' });
+  }
+  if (config.review.mode === 'peer' || config.review.mode === 'roles') {
+    const eligible = config.team.members.filter((m) => m !== config.team.spec_writer);
+    if (eligible.length < 2) {
+      warnings.push({
+        path: 'team.members',
+        message: 'review.mode needs a second person to review: team.members should list at least 2 people besides the spec writer',
+      });
+    }
+  }
+
+  // Credentials must never live in this file (checked on every value and key).
+  const strings = [];
+  collectStrings(user, '', strings);
+  strings.forEach(({ path, value }) => {
+    if (findCredentials(value, { strict: true }).length > 0) {
+      errors.push({
+        path,
+        message: `${path || 'value'} looks like a credential; move it to the repository secret store, never to relevo.yml`,
+      });
+    }
+  });
+  const flatKeys = [];
+  (function walk(obj, prefix) {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return;
+    Object.entries(obj).forEach(([k, v]) => {
+      flatKeys.push({ key: k, path: prefix ? `${prefix}.${k}` : k });
+      walk(v, prefix ? `${prefix}.${k}` : k);
+    });
+  }(user, ''));
+  flatKeys.forEach(({ key, path }) => {
+    if (/(api[_-]?key|secret|password|token)/i.test(key)) {
+      errors.push({
+        path,
+        message: `${path} looks like a credential setting; move it to the repository secret store, never to relevo.yml`,
+      });
+    }
+  });
+
+  return { ok: errors.length === 0, errors, warnings, config };
+}
+
+/** Parse relevo.yml text and validate it. Parse errors are returned as errors. */
+export function loadConfig(text, options = {}) {
+  let raw;
+  try {
+    raw = parse(text);
+  } catch (err) {
+    if (err instanceof YamlLiteError) {
+      return { ok: false, errors: [{ path: '', message: `relevo.yml is not valid: ${err.message}` }], warnings: [], config: null };
+    }
+    throw err;
+  }
+  return validateConfig(raw, options);
+}