@arjunkhera/atlas 0.3.7 → 0.3.9

package/tests/tests-yaml.mjs

@@ -0,0 +1,258 @@
+// atlas/tests.yaml: the reader, the check and the guard parts.
+//
+// The file is YAML with `spec: 1`. An unknown field is an error, so a typo
+// cannot hide. A field that holds what looks like a secret value is an error,
+// and the message names the field, never the value. Two personas that share
+// one secret must each say `same-identity`.
+//
+// The guard parts decide what a test may reach. A pull request may not change
+// them for itself: CI reads them from the main branch and compares.
+import { readFileSync } from 'node:fs';
+import { parseYaml, YamlError } from './yaml.mjs';
+
+export const SPEC = 1;
+
+// The parts of the file that only the owner may change. The `vars` part holds
+// the names of the variables, not their values.
+export const GUARD_PARTS = Object.freeze([
+  'guards',
+  'environments.*.allowed',
+  'environments.*.vars',
+  'personas.*.secret',
+  'secrets',
+  'judges',
+  'outside-text',
+]);
+
+const ENV_KEYS = ['same-as', 'start', 'ready', 'stop', 'url', 'vars', 'allowed', 'why'];
+const SCHEMA = {
+  top: ['spec', 'area', 'runner', 'environments', 'ways-in', 'stand-ins', 'personas', 'setups', 'data', 'fixtures', 'judges', 'guards', 'secrets', 'limits', 'budget', 'outside-text'],
+  runner: ['language', 'command'],
+  environment: ENV_KEYS,
+  ready: ['get', 'status', 'limit'],
+  wayIn: ['driver', 'base', 'command', 'module', 'env', 'cwd', 'why'],
+  standIn: ['start', 'why', 'ready'],
+  persona: ['role', 'secret', 'same-identity', 'sign-in', 'make', 'of', 'why'],
+  setup: ['with', 'steps', 'gives', 'why'],
+  data: ['rule', 'why'],
+  fixture: ['path', 'facts', 'bytes', 'text', 'why', 'made-up'],
+  judge: ['model', 'asks', 'runs', 'agree', 'cost-cap'],
+  guards: ['hosts', 'secrets'],
+  secret: ['why', 'local', 'ci'],
+  budget: ['cases', 'calls', 'minutes', 'money'],
+};
+// `guards` is optional: the smallest file of the design has none, and then a
+// test may reach this machine only.
+const REQUIRED = ['spec', 'runner', 'environments', 'ways-in'];
+const NAME = /^[A-Z][A-Z0-9_]*$/;
+
+// ---------------------------------------------------------------- secret test
+
+function entropy(text) {
+  const counts = new Map();
+  for (const c of text) counts.set(c, (counts.get(c) ?? 0) + 1);
+  let bits = 0;
+  for (const n of counts.values()) bits -= (n / text.length) * Math.log2(n / text.length);
+  return bits;
+}
+
+// The shapes of a leaked credential. The sources are built from parts, so this
+// file never holds the text of a key block.
+const PEM = new RegExp(`-----BEGIN [A-Z ]*${'PRIVATE'} KEY-----`);
+const SHAPES = [
+  PEM,
+  /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})\b/,
+  /\b(?:sk-[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16})\b/,
+  /\bxox[abprs]-[A-Za-z0-9-]{10,}/,
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/,
+  /\bBearer\s+[A-Za-z0-9._~+/=-]{20,}/i,
+  /\b[a-z][a-z0-9+.-]*:\/\/[^\s:@/]+:[^\s:@/]+@[^\s/]+/i,
+];
+
+// True when a text looks like a secret value. A placeholder such as
+// "{run.secret}" never does. A word such as "not-a-real-key" does not either:
+// it has no digit and little entropy.
+export function looksLikeSecret(text) {
+  if (typeof text !== 'string') return false;
+  if (/^\{[^{}]+\}$/.test(text.trim())) return false;
+  if (SHAPES.some((shape) => shape.test(text))) return true;
+  const word = text.trim();
+  if (word.length < 24 || /\s/.test(word)) return false;
+  if (/^https?:\/\//i.test(word) || /^[./~]/.test(word) || word.includes('{')) return false;
+  if (/^[0-9a-f]{32,}$/i.test(word)) return true;
+  if (!/\d/.test(word) || !/[A-Za-z]/.test(word)) return false;
+  return entropy(word) >= 3.6;
+}
+
+// ---------------------------------------------------------------- the reader
+
+export function parseTestsYaml(source) {
+  return parseYaml(source);
+}
+
+export function readTestsYaml(path) {
+  return parseYaml(readFileSync(path, 'utf8'));
+}
+
+// Merges a `same-as` environment over the one it names.
+export function resolveEnvironments(environments = {}) {
+  const resolved = {};
+  const walk = (name, seen = []) => {
+    const env = environments[name];
+    if (!env || typeof env !== 'object') return {};
+    if (!env['same-as']) return { ...env };
+    if (seen.includes(name)) return { ...env };
+    const { 'same-as': from, ...rest } = env;
+    return { ...walk(from, [...seen, name]), ...rest, 'same-as': from };
+  };
+  for (const name of Object.keys(environments)) resolved[name] = walk(name);
+  return resolved;
+}
+
+// ---------------------------------------------------------------- the check
+
+// Returns a list of { code, path, line, message }. `path` is the field as
+// dotted text. A finding never holds the value of a field.
+export function checkTestsYaml(parsed) {
+  const { value, lineOf } = parsed;
+  const findings = [];
+  const say = (code, path, message) => findings.push({ code, path: path.join('.'), line: lineOf(path) ?? lineOf(path.slice(0, -1)) ?? 1, message });
+  const isMap = (x) => x && typeof x === 'object' && !Array.isArray(x);
+
+  if (!isMap(value)) { findings.push({ code: 'tests-yaml', path: '', line: 1, message: 'the file holds no map' }); return findings; }
+  const known = (obj, allowed, path) => {
+    for (const key of Object.keys(obj)) {
+      if (!allowed.includes(key)) say('tests-yaml-unknown-field', [...path, key], `unknown field "${[...path, key].join('.')}"`);
+    }
+  };
+  const each = (obj, allowed, path, extra) => {
+    if (!isMap(obj)) return;
+    for (const [name, entry] of Object.entries(obj)) {
+      if (!isMap(entry)) { say('tests-yaml', [...path, name], `"${[...path, name].join('.')}" must be a map`); continue; }
+      known(entry, allowed, [...path, name]);
+      extra?.(entry, [...path, name], name);
+    }
+  };
+
+  known(value, SCHEMA.top, []);
+  for (const key of REQUIRED) if (!(key in value)) say('tests-yaml-missing-field', [key], `the field "${key}" is needed`);
+  if ('spec' in value && value.spec !== SPEC) say('tests-yaml-spec', ['spec'], `spec must be ${SPEC}; this check reads spec ${SPEC} only`);
+  if (isMap(value.runner)) {
+    known(value.runner, SCHEMA.runner, ['runner']);
+    for (const key of SCHEMA.runner) if (!(key in value.runner)) say('tests-yaml-missing-field', ['runner', key], `the field "runner.${key}" is needed`);
+  } else if ('runner' in value) say('tests-yaml', ['runner'], '"runner" must be a map');
+
+  each(value.environments, SCHEMA.environment, ['environments'], (env, path) => {
+    if (isMap(env.ready)) known(env.ready, SCHEMA.ready, [...path, 'ready']);
+    if (env.vars !== undefined && !isMap(env.vars)) say('tests-yaml', [...path, 'vars'], `"${path.join('.')}.vars" must be a map`);
+    if (env['same-as'] && !isMap(value.environments?.[env['same-as']])) say('unknown-name', [...path, 'same-as'], `"same-as" names an environment that does not exist`);
+  });
+  if (!isMap(value.environments) && 'environments' in value) say('tests-yaml', ['environments'], '"environments" must be a map');
+
+  each(value['ways-in'], SCHEMA.wayIn, ['ways-in'], (way, path) => {
+    if (!way.driver) say('tests-yaml-missing-field', [...path, 'driver'], `the field "${[...path, 'driver'].join('.')}" is needed`);
+  });
+  each(value['stand-ins'], SCHEMA.standIn, ['stand-ins'], (entry, path) => { if (isMap(entry.ready)) known(entry.ready, SCHEMA.ready, [...path, 'ready']); });
+  each(value.personas, SCHEMA.persona, ['personas']);
+  each(value.setups, SCHEMA.setup, ['setups']);
+  each(value.fixtures, SCHEMA.fixture, ['fixtures']);
+  each(value.judges, SCHEMA.judge, ['judges']);
+  each(value.secrets, SCHEMA.secret, ['secrets']);
+  if (isMap(value.data)) {
+    for (const [name, rule] of Object.entries(value.data)) if (isMap(rule)) known(rule, SCHEMA.data, ['data', name]);
+  }
+  if (isMap(value.guards)) {
+    known(value.guards, SCHEMA.guards, ['guards']);
+    if (!Array.isArray(value.guards.hosts) || !value.guards.hosts.length) say('tests-yaml-missing-field', ['guards', 'hosts'], 'the field "guards.hosts" is needed: the hosts that a test may reach');
+  } else if ('guards' in value) say('tests-yaml', ['guards'], '"guards" must be a map');
+  if (isMap(value.budget)) known(value.budget, SCHEMA.budget, ['budget']);
+  if ('outside-text' in value && typeof value['outside-text'] !== 'boolean') say('tests-yaml', ['outside-text'], '"outside-text" must be true or false');
+
+  // A secret appears by name only. Every text in the file is tested.
+  const walk = (node, path) => {
+    if (typeof node === 'string') {
+      if (looksLikeSecret(node)) say('tests-yaml-secret', path, `"${path.join('.')}" holds what looks like a secret value; this file carries names only`);
+    } else if (Array.isArray(node)) node.forEach((one, i) => walk(one, [...path, i]));
+    else if (isMap(node)) for (const [k, one] of Object.entries(node)) walk(one, [...path, k]);
+  };
+  walk(value, []);
+
+  // A persona names its secret; it never holds one.
+  const varNames = new Set();
+  for (const env of Object.values(value.environments ?? {})) for (const name of Object.keys(env?.vars ?? {})) varNames.add(name);
+  const secretNames = new Set(Object.keys(value.secrets ?? {}));
+  const bySecret = new Map();
+  if (isMap(value.personas)) {
+    for (const [name, persona] of Object.entries(value.personas)) {
+      if (!isMap(persona)) continue;
+      if (persona.secret !== undefined) {
+        if (typeof persona.secret !== 'string' || !NAME.test(persona.secret)) {
+          say('tests-yaml-secret', ['personas', name, 'secret'], `"personas.${name}.secret" must be the NAME of a variable, in capitals; it must not hold a value`);
+          continue;
+        }
+        if (!varNames.has(persona.secret) && !secretNames.has(persona.secret)) {
+          say('unknown-name', ['personas', name, 'secret'], `"personas.${name}.secret" names ${persona.secret}, which no environment sets in "vars" and "secrets" does not list`);
+        }
+        if (!bySecret.has(persona.secret)) bySecret.set(persona.secret, []);
+        bySecret.get(persona.secret).push(name);
+      }
+      if (persona['same-identity'] !== undefined && !isMap(value.personas[persona['same-identity']])) {
+        say('unknown-name', ['personas', name, 'same-identity'], `"personas.${name}.same-identity" names a persona that does not exist`);
+      }
+    }
+    for (const [secret, names] of bySecret) {
+      if (names.length < 2) continue;
+      for (const name of names) {
+        const partner = value.personas[name]['same-identity'];
+        if (!partner || !names.includes(partner) || partner === name) {
+          say('persona-shared-secret', ['personas', name], `persona "${name}" shares the secret ${secret} with ${names.filter((n) => n !== name).join(', ')} and does not say "same-identity" for one of them`);
+        }
+      }
+    }
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------- guard parts
+
+const sortKeys = (x) => {
+  if (Array.isArray(x)) return x.map(sortKeys);
+  if (x && typeof x === 'object') return Object.fromEntries(Object.keys(x).sort().map((k) => [k, sortKeys(x[k])]));
+  return x;
+};
+
+// The guard parts of a parsed file, flat: part path to value. An environment
+// is read after its `same-as` is applied. A `vars` part holds the names only.
+export function guardParts(value) {
+  const out = {};
+  const v = value ?? {};
+  if ('guards' in v) out.guards = sortKeys(v.guards);
+  const envs = resolveEnvironments(v.environments ?? {});
+  for (const [name, env] of Object.entries(envs)) {
+    if ('allowed' in env) out[`environments.${name}.allowed`] = env.allowed;
+    if (env.vars && typeof env.vars === 'object') out[`environments.${name}.vars`] = Object.keys(env.vars).sort();
+  }
+  for (const [name, persona] of Object.entries(v.personas ?? {})) {
+    if (persona && typeof persona === 'object' && 'secret' in persona) out[`personas.${name}.secret`] = persona.secret;
+  }
+  if ('secrets' in v) out.secrets = sortKeys(v.secrets);
+  if ('judges' in v) out.judges = sortKeys(v.judges);
+  if ('outside-text' in v) out['outside-text'] = v['outside-text'];
+  return out;
+}
+
+// Compares the guard parts of a file from the main branch with the same file
+// in the pull request. Both arguments are the parsed `value` or the text.
+// Returns one change for each part that differs: { part, base, head }.
+export function compareGuardParts(base, head) {
+  const read = (x) => (typeof x === 'string' ? parseYaml(x).value : x);
+  const a = guardParts(read(base));
+  const b = guardParts(read(head));
+  const changes = [];
+  for (const part of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()) {
+    if (JSON.stringify(a[part]) !== JSON.stringify(b[part])) changes.push({ part, base: a[part] ?? null, head: b[part] ?? null });
+  }
+  return changes;
+}
+
+export { YamlError };

package/tests/wait.mjs

@@ -0,0 +1,44 @@
+// The wait of a scenario: wait for a signal, never for a fixed time.
+//
+//   const last = await waitUntil(() => api.get('/status'), {
+//     until: (r) => r.body.state === 'done',
+//     fail:  (r) => r.body.state === 'error',
+//     limit: '2m',
+//   });
+//
+// It reads again and again. It returns the last value when `until` holds. It
+// throws WaitFailed at once when `fail` holds. It throws WaitTimeout, with
+// the last value, when the limit runs out. A wait with no limit is refused.
+import { setTimeout as sleep } from 'node:timers/promises';
+import { WaitFailed, WaitTimeout } from './errors.mjs';
+
+const UNITS = { ms: 1, millisecond: 1, milliseconds: 1, s: 1000, second: 1000, seconds: 1000, m: 60000, min: 60000, minute: 60000, minutes: 60000, h: 3600000, hour: 3600000, hours: 3600000 };
+
+// "30s", "2m", "2 minutes" or a number of milliseconds.
+export function parseLimit(limit) {
+  if (typeof limit === 'number' && Number.isFinite(limit) && limit > 0) return limit;
+  const match = /^(\d+(?:\.\d+)?)\s*([a-z]+)$/i.exec(String(limit ?? '').trim());
+  if (!match || !Object.hasOwn(UNITS, match[2].toLowerCase())) throw new Error(`a limit is a number of milliseconds, or like "30s" or "2m"; found "${limit}"`);
+  return Number(match[1]) * UNITS[match[2].toLowerCase()];
+}
+
+const show = (last) => JSON.stringify(last?.body ?? last)?.slice(0, 600);
+
+export async function waitUntil(read, options = {}) {
+  const { until, fail = () => false, absent = () => false, limit, every = '250ms', absentLimit = 10 } = options;
+  if (typeof read !== 'function') throw new Error('waitUntil needs a function that reads the state');
+  if (typeof until !== 'function') throw new Error('waitUntil needs an `until` state');
+  if (limit === undefined || limit === null) throw new Error('waitUntil needs a `limit`: a wait with no time limit is refused');
+  const deadline = Date.now() + parseLimit(limit);
+  let last;
+  let absentReads = 0;
+  for (;;) {
+    last = await read();
+    if (fail(last)) throw new WaitFailed(`the wait met its fail state: ${show(last)}`, last);
+    if (until(last)) return last;
+    absentReads = absent(last) ? absentReads + 1 : 0;
+    if (absentReads >= absentLimit) throw new WaitFailed(`the field that the wait reads was absent for ${absentReads} reads in a row`, last);
+    if (Date.now() >= deadline) throw new WaitTimeout(`the wait ran out after ${limit}; last state: ${show(last)}`, last);
+    await sleep(parseLimit(every));
+  }
+}

package/tests/yaml.mjs

@@ -0,0 +1,327 @@
+// A small YAML reader for tests.yaml and the front matter of a scenario.
+//
+// Atlas ships no dependency, so this reads the subset that these files use:
+// comments; nested maps by indentation; block lists of scalars and of maps;
+// flow lists and flow maps, nested to any depth, over several lines;
+// quoted and plain scalars; null, booleans and numbers; and the block scalars
+// | and >. Anything else raises a YamlError, so a file is never half read.
+//
+// `parseYaml(source)` returns `{ value, lineOf }`. `lineOf(path)` gives the
+// 1-based line where the key at that path (an array of keys and indexes)
+// starts, or null. An error names its line. It never carries the text of the
+// line, because a line can hold a secret value.
+
+export class YamlError extends Error {
+  constructor(message, line) {
+    super(line === undefined ? message : `${message} (line ${line})`);
+    this.name = 'YamlError';
+    this.line = line;
+  }
+}
+
+const pathKey = (path) => JSON.stringify(path);
+
+// Cuts a trailing comment: a # that starts the text or follows a space, and
+// sits outside quotes.
+function stripComment(text) {
+  let quote = null;
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text[i];
+    if (quote) {
+      if (c === '\\' && quote === '"') i += 1;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if ((c === '"' || c === "'") && (i === 0 || /[\s[{,:]/.test(text[i - 1]))) quote = c;
+    else if (c === '#' && (i === 0 || /\s/.test(text[i - 1]))) return text.slice(0, i).trimEnd();
+  }
+  return text.trimEnd();
+}
+
+// Counts open brackets outside quotes: positive when a flow value is still open.
+function depthOf(text) {
+  let depth = 0;
+  let quote = null;
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text[i];
+    if (quote) {
+      if (c === '\\' && quote === '"') i += 1;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") quote = c;
+    else if (c === '[' || c === '{') depth += 1;
+    else if (c === ']' || c === '}') depth -= 1;
+  }
+  return depth;
+}
+
+function plainScalar(text) {
+  if (text === '' || text === '~' || /^null$/i.test(text)) return null;
+  if (/^true$/i.test(text)) return true;
+  if (/^false$/i.test(text)) return false;
+  if (/^-?\d+$/.test(text)) return Number(text);
+  if (/^-?\d+\.\d+$/.test(text)) return Number(text);
+  return text;
+}
+
+function quoted(text, line) {
+  const q = text[0];
+  if (text.length < 2 || text[text.length - 1] !== q) throw new YamlError('a quoted value does not close', line);
+  const inner = text.slice(1, -1);
+  if (q === "'") return inner.replaceAll("''", "'");
+  return inner.replace(/\\(.)/g, (_, c) => ({ n: '\n', t: '\t', r: '\r' })[c] ?? c);
+}
+
+// Reads one value from inline text: a flow list, a flow map or a scalar.
+function inlineValue(text, line, lines, path) {
+  const t = text.trim();
+  if (t.startsWith('[') || t.startsWith('{')) {
+    const flow = new Flow(t, line, lines, path);
+    const value = flow.value(path);
+    flow.skip();
+    if (flow.i < t.length) throw new YamlError('text follows a flow value', line);
+    return value;
+  }
+  if (t.startsWith('"') || t.startsWith("'")) return quoted(t, line);
+  return plainScalar(t);
+}
+
+class Flow {
+  constructor(text, line, lines, path) {
+    this.t = text;
+    this.i = 0;
+    this.line = line;
+    this.lines = lines;
+    this.base = path;
+  }
+
+  skip() { while (this.i < this.t.length && /\s/.test(this.t[this.i])) this.i += 1; }
+
+  value(path) {
+    this.skip();
+    const c = this.t[this.i];
+    if (c === '[') return this.list(path);
+    if (c === '{') return this.map(path);
+    if (c === '"' || c === "'") return this.quotedString();
+    return plainScalar(this.plain(',]}').trim());
+  }
+
+  quotedString() {
+    const q = this.t[this.i];
+    const start = this.i;
+    this.i += 1;
+    while (this.i < this.t.length && this.t[this.i] !== q) {
+      if (q === '"' && this.t[this.i] === '\\') this.i += 1;
+      this.i += 1;
+    }
+    if (this.i >= this.t.length) throw new YamlError('a quoted value does not close', this.line);
+    this.i += 1;
+    return quoted(this.t.slice(start, this.i), this.line);
+  }
+
+  // A plain scalar ends at one of `stops`; a colon only ends it when a space or a stop follows.
+  plain(stops) {
+    const start = this.i;
+    while (this.i < this.t.length && !stops.includes(this.t[this.i])) this.i += 1;
+    return this.t.slice(start, this.i);
+  }
+
+  list(path) {
+    this.i += 1;
+    const out = [];
+    for (;;) {
+      this.skip();
+      if (this.i >= this.t.length) throw new YamlError('a flow list does not close', this.line);
+      if (this.t[this.i] === ']') { this.i += 1; return out; }
+      this.lines.set(pathKey([...path, out.length]), this.line);
+      out.push(this.value([...path, out.length]));
+      this.skip();
+      if (this.t[this.i] === ',') this.i += 1;
+      else if (this.t[this.i] !== ']') throw new YamlError('a flow list has text where a comma should be', this.line);
+    }
+  }
+
+  map(path) {
+    this.i += 1;
+    const out = {};
+    for (;;) {
+      this.skip();
+      if (this.i >= this.t.length) throw new YamlError('a flow map does not close', this.line);
+      if (this.t[this.i] === '}') { this.i += 1; return out; }
+      let key;
+      if (this.t[this.i] === '"' || this.t[this.i] === "'") key = this.quotedString();
+      else {
+        const start = this.i;
+        while (this.i < this.t.length) {
+          const c = this.t[this.i];
+          if (c === ':' && (this.i + 1 >= this.t.length || /[\s,}\]]/.test(this.t[this.i + 1]))) break;
+          if (c === ',' || c === '}') break;
+          this.i += 1;
+        }
+        key = this.t.slice(start, this.i).trim();
+      }
+      this.skip();
+      if (this.t[this.i] !== ':') throw new YamlError('a flow map entry has no colon', this.line);
+      this.i += 1;
+      this.lines.set(pathKey([...path, key]), this.line);
+      this.skip();
+      out[key] = (this.t[this.i] === ',' || this.t[this.i] === '}') ? null : this.value([...path, key]);
+      this.skip();
+      if (this.t[this.i] === ',') this.i += 1;
+      else if (this.t[this.i] !== '}') throw new YamlError('a flow map has text where a comma should be', this.line);
+    }
+  }
+}
+
+// Splits "key: rest" at the first colon that ends a key. Returns null when the text is no entry.
+function splitKey(text) {
+  let key;
+  let end;
+  if (text[0] === '"' || text[0] === "'") {
+    const q = text[0];
+    let i = 1;
+    while (i < text.length && text[i] !== q) i += (q === '"' && text[i] === '\\') ? 2 : 1;
+    if (i >= text.length) return null;
+    key = quoted(text.slice(0, i + 1));
+    end = i + 1;
+    while (text[end] === ' ') end += 1;
+    if (text[end] !== ':') return null;
+  } else {
+    let i = 0;
+    for (; i < text.length; i += 1) {
+      if (text[i] === ':' && (i + 1 === text.length || text[i + 1] === ' ')) break;
+    }
+    if (i >= text.length) return null;
+    key = text.slice(0, i).trim();
+    end = i;
+    if (!key || /^[[{]/.test(key)) return null;
+  }
+  return { key, rest: text.slice(end + 1).trim() };
+}
+
+export function parseYaml(source) {
+  const raw = String(source ?? '').replace(/\r\n?/g, '\n').split('\n');
+  const rows = raw.map((text, index) => ({ text, number: index + 1 }));
+  const lines = new Map();
+  let at = 0;
+
+  const indentOf = (row) => {
+    if (/^\t/.test(row.text)) throw new YamlError('a tab starts a line; YAML indents with spaces', row.number);
+    return row.text.length - row.text.trimStart().length;
+  };
+  const blank = (row) => !row.text.trim() || /^\s*#/.test(row.text);
+  const skipBlank = () => { while (at < rows.length && blank(rows[at])) at += 1; };
+  const peek = () => { skipBlank(); return at < rows.length ? rows[at] : null; };
+
+  // Document markers are allowed only before the first content.
+  skipBlank();
+  while (at < rows.length && /^(---|\.\.\.)\s*$/.test(rows[at].text)) { at += 1; skipBlank(); }
+
+  function blockScalar(header, parentIndent) {
+    const fold = header[0] === '>';
+    const parts = [];
+    let inner = null;
+    while (at < rows.length) {
+      const row = rows[at];
+      if (row.text.trim() === '') { parts.push(''); at += 1; continue; }
+      const indent = indentOf(row);
+      if (indent <= parentIndent) break;
+      if (inner === null) inner = indent;
+      parts.push(row.text.slice(Math.min(inner, indent)));
+      at += 1;
+    }
+    while (parts.length && parts[parts.length - 1] === '') parts.pop();
+    const text = fold ? parts.join(' ') : parts.join('\n');
+    return header.includes('-') ? text : `${text}\n`;
+  }
+
+  // The inline text of an entry, joined over lines while a flow value is open.
+  function inlineText(first, row) {
+    let text = stripComment(first);
+    let depth = depthOf(text);
+    while (depth > 0) {
+      if (at >= rows.length) throw new YamlError('a flow value does not close', row.number);
+      const next = rows[at];
+      at += 1;
+      if (next.text.trim() === '' || /^\s*#/.test(next.text)) continue;
+      text += ` ${stripComment(next.text.trim())}`;
+      depth = depthOf(text);
+    }
+    return text;
+  }
+
+  function valueAfterKey(rest, row, indent, path, allowSameIndentList) {
+    if (rest === '' || rest.startsWith('#')) {
+      const next = peek();
+      if (next && indentOf(next) > indent) return block(indentOf(next), path);
+      if (allowSameIndentList && next && indentOf(next) === indent && /^-( |$)/.test(next.text.trimStart())) return block(indent, path);
+      return null;
+    }
+    if (/^[|>][+-]?\s*(#.*)?$/.test(rest)) return blockScalar(rest, indent);
+    return inlineValue(inlineText(rest, row), row.number, lines, path);
+  }
+
+  function block(indent, path) {
+    const row = peek();
+    if (!row) return null;
+    return /^-( |$)/.test(row.text.trimStart()) ? list(indent, path) : map(indent, path);
+  }
+
+  function map(indent, path) {
+    const out = {};
+    for (;;) {
+      const row = peek();
+      if (!row || indentOf(row) !== indent) {
+        if (row && indentOf(row) > indent) throw new YamlError('the indentation is deeper than the map above it', row.number);
+        return out;
+      }
+      const body = row.text.trimStart();
+      if (/^-( |$)/.test(body)) return out;
+      if (/^(---|\.\.\.)\s*$/.test(body)) throw new YamlError('a second document starts here; this reader reads one document per file', row.number);
+      const entry = splitKey(body);
+      if (!entry) throw new YamlError('a line is not a key and a value', row.number);
+      if (Object.hasOwn(out, entry.key)) throw new YamlError(`the key "${entry.key}" is written twice`, row.number);
+      at += 1;
+      const here = [...path, entry.key];
+      lines.set(pathKey(here), row.number);
+      out[entry.key] = valueAfterKey(entry.rest, row, indent, here, true);
+    }
+  }
+
+  function list(indent, path) {
+    const out = [];
+    for (;;) {
+      const row = peek();
+      if (!row || indentOf(row) !== indent || !/^-( |$)/.test(row.text.trimStart())) return out;
+      const rest = row.text.trimStart().slice(1).trim();
+      const here = [...path, out.length];
+      lines.set(pathKey(here), row.number);
+      if (rest === '' || rest.startsWith('#')) {
+        at += 1;
+        const next = peek();
+        out.push(next && indentOf(next) > indent ? block(indentOf(next), here) : null);
+        continue;
+      }
+      const entry = (!rest.startsWith('[') && !rest.startsWith('{')) ? splitKey(rest) : null;
+      if (entry) {
+        // A map that starts on the dash line: read it at the column of its first key.
+        const column = indent + (row.text.trimStart().length - rest.length);
+        rows[at] = { text: `${' '.repeat(column)}${rest}`, number: row.number };
+        out.push(map(column, here));
+        continue;
+      }
+      at += 1;
+      out.push(inlineValue(inlineText(rest, row), row.number, lines, here));
+    }
+  }
+
+  const first = peek();
+  let value = null;
+  if (first) {
+    value = block(indentOf(first), []);
+    const extra = peek();
+    if (extra) throw new YamlError(/^(---|\.\.\.)\s*$/.test(extra.text) ? 'a second document starts here; this reader reads one document per file' : 'the indentation does not match the lines above', extra.number);
+  }
+  return { value, lineOf: (path) => lines.get(pathKey(path)) ?? null };
+}