@elalfner/relevo 0.0.0-stage → 0.3.0

package/scripts/lib/issue-parse.mjs

@@ -0,0 +1,194 @@
+// Reads what the `go` gates need from an issue body.
+// The expected shape is documented in docs/issue-format.md.
+
+import { section } from './issue-sections.mjs';
+
+export const ATTACHMENT_HOSTS = ['github.com', 'user-images.githubusercontent.com', 'private-user-images.githubusercontent.com'];
+export const MAX_REFERENCES = 5;
+
+const FENCE_RE = /^\s*(```|~~~)/;
+const HEADING_RE = /^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/;
+const BULLET_RE = /^\s*(?:[-*+]|\d+[.)])\s+\S/;
+const WHEN_RE = /^\s*(?:[-*+]\s+)?(?:\*\*|__)?(?:WHEN|GIVEN)(?:\*\*|__)?(?:\s|:)/i;
+const THEN_RE = /^\s*(?:[-*+]\s+)?(?:\*\*|__)?THEN(?:\*\*|__)?(?:\s|:)/i;
+const EDGE_RE = /\b(edge[ -]?cases?|casos?\s+(?:borde|l[ií]mite|extremos?))\b/i;
+const DEPENDS_RE = /^\s*(?:[-*+]\s+)?Depend(?:s[- ]on|e(?:\s+de)?):\s*(.+)$/i;
+const ALLOW_RE = /^\s*(?:[-*+]\s+)?Allow-paths:\s*(.+)$/i;
+const PLATFORM_RE = /^\s*(?:[-*+]\s+)?Platform:\s*(.+)$/i;
+
+/** Remove fenced code blocks so examples inside them are not counted. */
+function withoutCode(body) {
+  const out = [];
+  let inFence = false;
+  String(body ?? '').split('\n').forEach((line) => {
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      return;
+    }
+    if (!inFence) out.push(line);
+  });
+  return out;
+}
+
+/**
+ * The "Design reference" section: a bullet per reference, `- <target>: <what must match>`, plus fenced example code.
+ * <target> is a backticked path of the repository, a backticked owner/repo:path of a linked repository, or a link.
+ * Returns { present, references: [{ kind, target, repo?, path?, allowed?, match }], code, problems }.
+ */
+export function parseDesign(body) {
+  const found = section(body, 'Design reference');
+  if (!found) return { present: false, references: [], code: 0, problems: [] };
+  let code = 0;
+  let inFence = false;
+  const references = [];
+  const problems = [];
+  found.text.split('\n').forEach((line) => {
+    if (FENCE_RE.test(line)) {
+      if (!inFence) code += 1;
+      inFence = !inFence;
+      return;
+    }
+    if (inFence || !/^\s*[-*+]\s+/.test(line)) return;
+    const bullet = line.replace(/^\s*[-*+]\s+/, '').trim();
+    const tick = bullet.match(/^`([^`]+)`\s*(?::\s*(.*))?$/);
+    const link = bullet.match(/^<?(https?:\/\/[^\s>]+?)>?\s*(?::\s+(.*))?$/);
+    const m = tick ?? link;
+    if (!m) {
+      problems.push(`"${bullet.slice(0, 60)}" is not a reference: write \`path\`: what must match`);
+      return;
+    }
+    const target = m[1].trim();
+    const match = (m[2] ?? '').trim();
+    const ref = { target, match };
+    if (/^https?:\/\//.test(target)) {
+      let host = '';
+      try {
+        host = new URL(target).hostname;
+      } catch { /* not a URL */ }
+      const ok = ATTACHMENT_HOSTS.includes(host) && (host !== 'github.com' || new URL(target).pathname.startsWith('/user-attachments/'));
+      Object.assign(ref, { kind: 'attachment', allowed: ok });
+    } else if (/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+:[^\s]+$/.test(target)) {
+      const [repo, ...rest] = target.split(':');
+      Object.assign(ref, { kind: 'repo-file', repo, path: rest.join(':') });
+    } else {
+      Object.assign(ref, { kind: 'path', path: target });
+    }
+    const path = ref.path;
+    if (path !== undefined && (path.startsWith('/') || /^[A-Za-z]:[\\/]/.test(path) || path.split(/[\\/]/).includes('..'))) {
+      problems.push(`"${target}" leaves the repository: use a path inside it`);
+      return;
+    }
+    if (match === '') problems.push(`"${target}" does not say what must match (structure, spacing, typography, colour, states)`);
+    references.push(ref);
+  });
+  return { present: true, references, code, problems };
+}
+
+/**
+ * Returns {
+ *   scenarios: number,          // complete WHEN/THEN pairs
+ *   edgeCases: number,          // bullets under an "Edge cases" heading
+ *   dependsOn: number[],        // issue numbers of this repository from "Depends-on: #N" lines
+ *   dependsOnExternal: { repo, number }[],   // issues of other repositories from "Depends-on: owner/repo#N"
+ *   dependsOnInvalid: string[], // tokens of a Depends-on line that look like a repository but are not owner/repo#N
+ *   allowPaths: string[],       // paths and globs from "Allow-paths:" lines (dependency files the change may touch)
+ *   platform: string[],         // every name written on a "Platform:" line, in order (the platform the issue is for)
+ *   openQuestions: string[],    // the lines written under an "Open questions" heading (the template's comment and "none" excluded)
+ *   needsClarification: boolean,// the literal text NEEDS CLARIFICATION outside code blocks
+ *   decisionIds: string[],      // D1, D2... from "### D<n>. title" headings under "Decisions"
+ *   constraintIds: string[],    // C1, C2... from "- C<n>: text" bullets under "Constraints"
+ *   idProblems: string[],       // repeated or malformed decision and constraint ids
+ *   missing: string[],          // what the spec gate reports as absent
+ * }
+ */
+export function parseIssueBody(body) {
+  const lines = withoutCode(body);
+
+  const whens = lines.filter((l) => WHEN_RE.test(l)).length;
+  const thens = lines.filter((l) => THEN_RE.test(l)).length;
+  const scenarios = Math.min(whens, thens);
+
+  let edgeCases = 0;
+  let inEdge = false;
+  lines.forEach((line) => {
+    const heading = line.match(HEADING_RE);
+    if (heading) {
+      inEdge = EDGE_RE.test(heading[2]);
+      return;
+    }
+    if (inEdge && BULLET_RE.test(line)) edgeCases += 1;
+  });
+
+  // `#12` is an issue of this repository; `owner/repo#12` is an issue of another one. A token that looks like a
+  // repository but is not followed by `#number` (for example "acme/api 12") is invalid.
+  const dependsOn = [];
+  const dependsOnExternal = [];
+  const dependsOnInvalid = [];
+  lines.forEach((line) => {
+    const m = line.match(DEPENDS_RE);
+    if (!m) return;
+    [...m[1].matchAll(/(?:([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+))?#(\d+)/g)].forEach((ref) => {
+      const num = Number.parseInt(ref[2], 10);
+      if (ref[1]) {
+        if (!dependsOnExternal.some((d) => d.repo === ref[1] && d.number === num)) dependsOnExternal.push({ repo: ref[1], number: num });
+      } else if (!dependsOn.includes(num)) dependsOn.push(num);
+    });
+    const withoutRefs = m[1].replace(/(?:[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)?#\d+/g, ' ');
+    [...withoutRefs.matchAll(/[A-Za-z0-9_.:-]*[A-Za-z0-9_.-]+\/[A-Za-z0-9_./:-]+/g)].forEach((bad) => {
+      if (!dependsOnInvalid.includes(bad[0])) dependsOnInvalid.push(bad[0]);
+    });
+  });
+
+  // Dependency files the change may touch; comma separated, with or without backticks around each path.
+  const allowPaths = [];
+  lines.forEach((line) => {
+    const m = line.match(ALLOW_RE);
+    if (!m) return;
+    m[1].split(',').map((p) => p.trim().replace(/^`+|`+$/g, '').trim()).filter(Boolean).forEach((p) => {
+      if (!allowPaths.includes(p)) allowPaths.push(p);
+    });
+  });
+
+  // The platform(s) named by the issue; resolving them against relevo.yml is platform-of.mjs's job.
+  const platform = [];
+  lines.forEach((line) => {
+    const m = line.match(PLATFORM_RE);
+    if (!m) return;
+    m[1].split(',').map((p) => p.trim().replace(/^`+|`+$/g, '').trim()).filter(Boolean).forEach((p) => platform.push(p));
+  });
+
+  const none = /^(?:none|nothing|n\/a|ninguna?|nada|-)\.?$/i;
+  const openQuestions = String(section(body, 'Open questions')?.text ?? '')
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l !== '' && !none.test(l.replace(/^[-*+]\s+/, '')));
+  const needsClarification = lines.some((l) => /NEEDS CLARIFICATION/.test(l));
+
+  const idProblems = [];
+  const decisionIds = [];
+  String(section(body, 'Decisions')?.text ?? '').split('\n').forEach((line) => {
+    const h = line.match(/^###\s+(.*?)\s*$/);
+    if (!h) return;
+    const ok = h[1].match(/^(D\d+)\.\s+\S/);
+    if (ok) {
+      if (decisionIds.includes(ok[1])) idProblems.push(`the decision id ${ok[1]} is repeated`);
+      else decisionIds.push(ok[1]);
+    } else if (/^D(?:\d|[.:\s])/.test(h[1])) idProblems.push(`"### ${h[1]}" is not a decision: write "### D1. <title>"`);
+  });
+  const constraintIds = [];
+  String(section(body, 'Constraints')?.text ?? '').split('\n').forEach((line) => {
+    const b = line.match(/^\s*[-*+]\s+(C\d+)(.?)/);
+    if (!b) return;
+    if (b[2] !== ':') idProblems.push(`"${line.trim()}" is not a constraint: write "- ${b[1]}: <limit>"`);
+    else if (constraintIds.includes(b[1])) idProblems.push(`the constraint id ${b[1]} is repeated`);
+    else constraintIds.push(b[1]);
+  });
+
+  const missing = [];
+  if (scenarios === 0) missing.push('scenarios written as WHEN/THEN pairs');
+  if (edgeCases === 0) missing.push('edge cases (a list under an "Edge cases" heading)');
+
+  const design = parseDesign(body);
+  return { design, scenarios, edgeCases, dependsOn, dependsOnExternal, dependsOnInvalid, allowPaths, platform, openQuestions, needsClarification, decisionIds, constraintIds, idProblems, missing };
+}

package/scripts/lib/issue-sections.mjs

@@ -0,0 +1,43 @@
+// Reads the sections of an issue body by heading, and copies them word for word.
+// Implements "Sections of the issue are copied word for word" of openspec/specs/go/spec.md.
+// The format is documented in docs/issue-format.md; headings are always in English.
+
+const FENCE_RE = /^\s*(```|~~~)/;
+const H2_RE = /^##\s+(.*?)\s*#*\s*$/;
+
+/** The sections of level 2, in order: [{ name, text }]. Text is the lines under the heading, trimmed of blank lines at both ends. */
+export function sections(body) {
+  const out = [];
+  let current = null;
+  let inFence = false;
+  String(body ?? '').split('\n').forEach((line) => {
+    if (FENCE_RE.test(line)) inFence = !inFence;
+    const h = !inFence && !/^###/.test(line) ? line.match(H2_RE) : null;
+    if (h) {
+      current = { name: h[1].trim(), lines: [] };
+      out.push(current);
+      return;
+    }
+    if (current) current.lines.push(line);
+  });
+  return out.map(({ name, lines }) => ({ name, text: lines.join('\n').replace(/^\s*\n/, '').replace(/\s+$/, '') }));
+}
+
+/** One section by name (case-insensitive), or null. */
+export function section(body, name) {
+  const wanted = String(name).trim().toLowerCase();
+  return sections(body).find((s) => s.name.toLowerCase() === wanted) ?? null;
+}
+
+/**
+ * The markdown that go appends to design.md: for each name that exists and has text, "## From the issue: <Name>" and the
+ * text unchanged, in the order of `names`.
+ */
+export function copyBlock(body, names) {
+  const blocks = [];
+  names.forEach((name) => {
+    const s = section(body, name);
+    if (s && s.text !== '') blocks.push(`## From the issue: ${s.name}\n\n${s.text}\n`);
+  });
+  return blocks.join('\n');
+}

package/scripts/lib/labels.mjs

@@ -0,0 +1,65 @@
+// Label set and state transitions.
+// Implements openspec/specs/issue-lifecycle/spec.md.
+
+// kind:
+//   state   - lifecycle label; exactly one of the exclusive labels at a time
+//   exit    - side exit that replaces the lifecycle label
+//   overlay - added next to the current state, never replaces it
+export const LABELS = [
+  { key: 'ready', name: 'relevo:ready', color: '0e8a16', kind: 'state', description: 'Spec is finished; the agent may start' },
+  { key: 'queued', name: 'relevo:queued', color: 'c5def5', kind: 'state', description: 'Waiting for capacity' },
+  { key: 'building', name: 'relevo:building', color: 'fbca04', kind: 'state', description: 'The agent is building it' },
+  { key: 'built', name: 'relevo:built', color: '1d76db', kind: 'state', description: 'Built and QA passed; waiting for the assignee' },
+  { key: 'in-review', name: 'relevo:in-review', color: '5319e7', kind: 'state', description: 'Being reviewed on a device' },
+  { key: 'pr-open', name: 'relevo:pr-open', color: '0075ca', kind: 'state', description: 'Pull request open; waiting for the peer' },
+  { key: 'needs-spec', name: 'relevo:needs-spec', color: 'd93f0b', kind: 'exit', description: 'Spec is incomplete or defective; back to the spec writer' },
+  { key: 'blocked', name: 'relevo:blocked', color: 'b60205', kind: 'exit', description: 'Waiting for a dependency to merge' },
+  { key: 'qa-failed', name: 'relevo:qa-failed', color: 'e11d21', kind: 'exit', description: 'QA still rejected after the retries; branch is pushed' },
+  { key: 'changes-requested', name: 'relevo:changes-requested', color: 'f9d0c4', kind: 'exit', description: 'The reviewer asked for changes' },
+  { key: 'needs-reviewer', name: 'relevo:needs-reviewer', color: 'fef2c0', kind: 'overlay', description: 'No reviewer available or the review is overdue' },
+];
+
+export const LABEL_KEYS = LABELS.map((l) => l.key);
+
+const EXCLUSIVE_KEYS = LABELS.filter((l) => l.kind !== 'overlay').map((l) => l.key);
+
+/** Map each label key to its effective name, applying the `labels` overrides of relevo.yml. */
+export function resolveLabelNames(overrides = {}) {
+  const names = {};
+  LABELS.forEach((l) => {
+    names[l.key] = overrides[l.key] ?? l.name;
+  });
+  return names;
+}
+
+/** Label definitions with effective names, for creating labels in a repository. */
+export function labelDefinitions(overrides = {}) {
+  const names = resolveLabelNames(overrides);
+  return LABELS.map((l) => ({ ...l, name: names[l.key] }));
+}
+
+/**
+ * Compute the label changes needed to move an issue to `toKey`.
+ * - state/exit labels are exclusive: moving to one removes any other exclusive label.
+ * - overlay labels are only added.
+ * Returns { add: [names], remove: [names] } using effective label names.
+ */
+export function transition(currentNames, toKey, overrides = {}) {
+  if (!LABEL_KEYS.includes(toKey)) throw new Error(`unknown label key "${toKey}"`);
+  const names = resolveLabelNames(overrides);
+  const current = new Set(currentNames);
+  const target = names[toKey];
+  if (!EXCLUSIVE_KEYS.includes(toKey)) {
+    return { add: current.has(target) ? [] : [target], remove: [] };
+  }
+  const remove = EXCLUSIVE_KEYS.filter((k) => k !== toKey)
+    .map((k) => names[k])
+    .filter((n) => current.has(n));
+  return { add: current.has(target) ? [] : [target], remove };
+}
+
+/** Labels to remove when the issue is finished (every Relevo label). */
+export function clearAll(currentNames, overrides = {}) {
+  const names = new Set(Object.values(resolveLabelNames(overrides)));
+  return { add: [], remove: currentNames.filter((n) => names.has(n)) };
+}

package/scripts/lib/language.mjs

@@ -0,0 +1,9 @@
+// The languages of the messages and reports, and the choice of one from a language tag.
+
+export const SUPPORTED_LANGUAGES = ['en', 'es'];
+
+/** Pick the catalog for a language tag such as "es" or "es-MX"; unknown languages use English. */
+export function pickLanguage(language) {
+  const base = String(language ?? 'en').split('-')[0];
+  return SUPPORTED_LANGUAGES.includes(base) ? base : 'en';
+}

package/scripts/lib/logaudit.mjs

@@ -0,0 +1,123 @@
+// Audits a device log for the error classes the review spec names:
+// layout overflows, lifecycle errors, unhandled exceptions, unhandled network or data
+// errors, and missing-activity errors.
+
+const ANSI_RE = /\u001b\[[0-9;]*m/g;
+const MAX_FINDINGS = 50;
+const MAX_EXCERPT = 200;
+
+const UNHANDLED_CONTEXT = /E\/flutter|Unhandled Exception|EXCEPTION CAUGHT|FATAL EXCEPTION|AndroidRuntime/;
+
+const RULES = [
+  { cls: 'layout', re: /RenderFlex overflowed|BoxConstraints forces an infinite|was given unbounded (height|width)|unbounded (height|width)/i },
+  { cls: 'lifecycle', re: /setState\(\) called (during build|after dispose)|called after dispose\(\)|deactivated widget's ancestor/i },
+  { cls: 'exception', re: /Unhandled Exception|EXCEPTION CAUGHT BY|FATAL EXCEPTION|NoSuchMethodError|\bTypeError\b|\bFlutterError\b|\bUncaught\b|\bReferenceError\b|\bSyntaxError\b|Unhandled (?:promise )?rejection/ },
+  // A network or data exception only counts when it was not handled: it shows up as an error in the log.
+  { cls: 'network-data', re: /\b(DioException|SocketException|HttpException|ClientException|PostgrestException|AuthException)\b/, needs: UNHANDLED_CONTEXT },
+  // A driven browser: a console.error call, a request that failed, an error response, or one the origin guard stopped. Written by web-review.mjs.
+  { cls: 'network-data', re: /\brequestfailed\b|\bresponse [45]\d\d\b|\bblocked request\b/ },
+  { cls: 'console-error', re: /\bconsole\.error\b/ },
+  { cls: 'missing-activity', re: /ActivityNotFoundException/ },
+];
+
+export const ERROR_CLASSES = [...new Set(RULES.map((r) => r.cls))];
+export const PASSED = 'REVIEW PASSED';
+export const PASSED_WITH_WAIVERS = 'REVIEW PASSED (with waivers)';
+export const REJECTED = 'REVIEW REJECTED';
+export const INCONCLUSIVE = 'REVIEW INCONCLUSIVE';
+
+/**
+ * Scan log text. Returns { verdict, findings: [{ class, line, excerpt }], counts }.
+ * verdict is "REVIEW PASSED", "REVIEW REJECTED", or "REVIEW INCONCLUSIVE" when there is no evidence to judge: the log is
+ * empty, or `scope` (from filterByApp) says the application's process was never found in it. An inconclusive audit
+ * carries a `reason` and is never a pass.
+ */
+export function auditLog(text, { scope = null } = {}) {
+  if (String(text ?? '').trim() === '') {
+    return { verdict: INCONCLUSIVE, reason: 'the device log is empty: the app was not started, the device was disconnected or the log could not be read', findings: [], counts: {} };
+  }
+  if (scope && scope.pids.length === 0) {
+    return { verdict: INCONCLUSIVE, reason: `no line of the log was written by ${scope.package}: restart the app and repeat the steps`, findings: [], counts: {} };
+  }
+  const findings = [];
+  const seen = new Set();
+  String(text).split('\n').forEach((raw, idx) => {
+    const line = raw.replace(ANSI_RE, '');
+    RULES.forEach((rule) => {
+      if (!rule.re.test(line)) return;
+      if (rule.needs && !rule.needs.test(line)) return;
+      const excerpt = line.trim().slice(0, MAX_EXCERPT);
+      const key = `${rule.cls}|${excerpt}`;
+      if (seen.has(key) || findings.length >= MAX_FINDINGS) return;
+      seen.add(key);
+      findings.push({ class: rule.cls, line: idx + 1, excerpt });
+    });
+  });
+  const counts = {};
+  findings.forEach((f) => {
+    counts[f.class] = (counts[f.class] ?? 0) + 1;
+  });
+  return { verdict: findings.length === 0 ? PASSED : REJECTED, findings, counts };
+}
+
+/** Markdown report of an audit. */
+export function auditReport(audit, { issue, scope } = {}) {
+  const lines = [`# Review report${issue ? ` for #${issue}` : ''}`, '', `**${audit.verdict}**`, ''];
+  if (audit.verdict === INCONCLUSIVE) {
+    lines.push(`This audit proves nothing: ${audit.reason}. It cannot be waived.`);
+    return `${lines.join('\n')}\n`;
+  }
+  if (scope?.pids?.length) {
+    lines.push(`Scope: only the processes of \`${scope.package}\` (pid ${scope.pids.join(', ')}); other apps' log lines were ignored.`, '');
+  } else {
+    lines.push('Scope: the whole device log.', '');
+  }
+  if (audit.findings.length === 0) {
+    lines.push('The device log contains none of the error classes: layout, lifecycle, exceptions, network or data errors, missing activity.');
+  } else {
+    lines.push(`${audit.findings.length} finding(s):`, '');
+    audit.findings.forEach((f, i) => lines.push(`${i + 1}. **${f.class}** (log line ${f.line}): \`${f.excerpt.replace(/`/g, "'")}\`${f.waived ? ` — WAIVED by the reviewer: ${f.reason}` : ''}`));
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// `logcat -v time` writes "E/tag( 1234): msg"; `-v threadtime` writes "10-14 12:00:00.123  1234  1234 E tag: msg".
+const PID_TIME = /^\S+\s+\S+\s+[VDIWEF]\/[^(]*\(\s*(\d+)\)/;
+const PID_THREADTIME = /^\S+\s+\S+\s+(\d+)\s+\d+\s+[VDIWEF]\s/;
+
+/** Process id of a logcat line, or null when the format has none. */
+export function linePid(line) {
+  const m = PID_THREADTIME.exec(line) ?? PID_TIME.exec(line);
+  return m ? Number(m[1]) : null;
+}
+
+/** Process ids the log itself says belong to an application package (process start and crash headers). */
+export function pidsForPackage(text, pkg) {
+  const p = escapeRe(pkg);
+  const re = [new RegExp(`Start proc (\\d+):${p}[/:]`), new RegExp(`Process: ${p}, PID: (\\d+)`)];
+  const pids = new Set();
+  String(text).split('\n').forEach((line) => {
+    re.forEach((r) => {
+      const m = r.exec(line);
+      if (m) pids.add(Number(m[1]));
+    });
+  });
+  return [...pids];
+}
+
+/**
+ * Keep only the log lines written by the processes of one application, so that other apps on the same
+ * device (and whatever they log) are neither audited nor quoted in the report.
+ * Returns { text, scope } where scope is { package, pids } when filtered, or { package, pids: [] } when the
+ * log never names the app's process, in which case the whole log is returned and the caller must say so.
+ */
+export function filterByApp(text, { package: pkg, pids = [] }) {
+  const all = new Set([...pids.map(Number), ...pidsForPackage(text, pkg)]);
+  if (all.size === 0) return { text: String(text), scope: { package: pkg, pids: [] } };
+  const kept = String(text).split('\n').filter((line) => {
+    const pid = linePid(line);
+    return pid !== null && all.has(pid);
+  });
+  return { text: kept.join('\n'), scope: { package: pkg, pids: [...all] } };
+}