@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/lint/scripts/lintScripts.js

@@ -0,0 +1,298 @@
+'use strict';
+
+/**
+ * SCRIPTS-STANDARD §1-§3, as a module of the package that ships the uniform.
+ *
+ * WHY IT LIVES HERE. Confirmation `biz-service-manifest` 003 §19 makes
+ * `scripts/**` of every bearer a duty of the uniform, checked by "lint-scripts,
+ * shipped in the validator package". Until d.218 the rules were a file of the
+ * `api` checkout, and a file of one checkout cannot decide a rule about eight
+ * repositories: a biz service has no `api/` directory in its own CI and none at
+ * all inside its image, so the row would have been NOT RUN exactly where it is
+ * meant to answer. The rules moved; `api/scripts/ci/lint-scripts.mjs` calls
+ * this module and holds no rule of its own, so there is one implementation
+ * (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * WHAT DID NOT CHANGE. Every id, every message and every vocabulary is the one
+ * `api/tests/scripts/scripts-lint.bats` already asserts. The header probe stays
+ * anchored to the header SHAPE in the first lines of a file rather than to a
+ * token appearing anywhere: the unanchored probe missed the header linter
+ * itself.
+ *
+ * WHAT DID. An `@see api/…` target used to be resolved by stripping the `api/`
+ * prefix and looking under the run's own root — correct exactly once, when the
+ * run IS the api checkout. A biz script citing `api/docs/standards/…` would
+ * then have been measured against `<service>/docs/standards/…` and reported as
+ * a dead pointer it is not. So the api checkout is a PARAMETER: given, such a
+ * target is resolved against it; absent, the target is returned as UNRESOLVED
+ * and raises nothing, because a run that could not look must not report a pass
+ * (`.claude/rules/automation-gates.md` §5). Measured 2026-09-10 over the eight
+ * biz repositories: 47 `@see` lines under their scripts directories, of which 4
+ * open with the `api/` prefix.
+ *
+ * Two scopes, two rules. S001-S008 read the HEADER of every script under
+ * `scripts/`. S009 reads the COMMENTS of every test under `tests/scripts/` and
+ * nothing else in them: a `<path>.<ext>:<line>` citation in prose has no
+ * mechanism keeping it true (`doc-code-binding.md` §1), while the same shape on
+ * a CODE line is a fixture assertion whose target the test creates itself and
+ * which therefore cannot rot.
+ *
+ * @see api/docs/standards/SCRIPTS-STANDARD.md
+ * @see api/docs/governance/confirmations/biz-service-manifest.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** The five header fields, in the order SCRIPTS-STANDARD §1 writes them. */
+const ORDER = Object.freeze(['Owns', 'Usage', 'Shell', 'Exit', 'Status']);
+
+/** SCRIPTS-STANDARD §2: both vocabularies are closed, and a foreign value is a finding. */
+const STATUS_VOCAB = new Set(['current', 'draft', 'archived']);
+const SHELL_VOCAB = new Set(['bash>=4', 'bash>=3.2', 'sh', 'node>=18', 'node>=24']);
+
+/** The directory whose scripts carry the header. */
+const SCRIPT_SCOPE = 'scripts';
+
+/** The directory whose COMMENTS S009 reads, and nothing else in it. */
+const CITATION_SCOPE = 'tests/scripts';
+
+/**
+ * The directories whose files are libraries rather than entry points.
+ *
+ * This is the half of S007 the DIRECTORY decides, and the only half: a library
+ * is not invoked, so instead of a command line its `Usage:` carries the word by
+ * which it is brought into another file. WHICH word that is, is decided by the
+ * language (`usageWordFor`), never by the directory — d.249, on the BIZ-ingest
+ * finding of 2026-09-11: the rule used to read `scripts/lib/` as "shell" and
+ * `scripts/ci/lib/` as "Node", so a Node library under the first could not go
+ * green without writing something false about itself — ingest 1 file, meta 7,
+ * both red on this one rule and on nothing else (measured 2026-09-11, before
+ * and after). Making a file pass by writing a word that is not true of it is
+ * exactly what `architecture-principles.md` §10 forbids, so the rule moved
+ * rather than the files.
+ */
+const LIBRARY_SCOPES = Object.freeze(['scripts/lib/', 'scripts/ci/lib/']);
+
+/**
+ * Shell is sourced; everything else this lint reads is a Node module, and a
+ * Node module is required. The test is the extension, because that is what
+ * decides how the file can be brought in at all — `.` on a `.js` is not a thing
+ * a shell can do, and `require` on a `.sh` is not a thing Node can do.
+ *
+ * Written as "shell, or else Node" rather than as a list of Node extensions on
+ * purpose: the extensions this lint reads are `SCRIPT_EXTENSIONS`, and a second
+ * list here would be a copy of it that drifts (`change-discipline.md` § One rail
+ * per concern). A `.cjs` is outside the scan today; the day it enters, it needs
+ * no edit here.
+ *
+ * @param {string} relative path inside the repository
+ * @returns {'sourced'|'required'}
+ */
+const usageWordFor = (relative) => (relative.endsWith('.sh') ? 'sourced' : 'required');
+
+/** What the message calls the file, from the same test. */
+const languageOf = (relative) => (relative.endsWith('.sh') ? 'shell' : 'Node');
+
+/** What a script may be written in. */
+const SCRIPT_EXTENSIONS = /\.(sh|mjs|js)$/;
+
+/** What a test under the citation scope may be written in. */
+const CITATION_EXTENSIONS = /\.(bats|bash|sh)$/;
+
+/**
+ * A line number written into a comment. The extension list carries every module
+ * extension this platform writes, `.env` included: a generated env template
+ * renumbers every citation of it without one edit to the cited file, which is
+ * the shape a line citation can least survive.
+ */
+const LINE_CITATION = /[A-Za-z0-9_/.-]+\.(?:js|mjs|cjs|ts|mts|sh|bash|bats|yml|json|md|env):\d+/;
+
+/** A comment line of a shell-family test. */
+const COMMENT_LINE = /^\s*#/;
+
+/** The prefix a citation of the api checkout opens with, as every document writes it. */
+const API_PREFIX = 'api/';
+
+/**
+ * Every file under `dir` whose name matches, depth first, as `/`-separated
+ * paths relative to `root`.
+ *
+ * @param {string} dir absolute directory
+ * @param {string} root the root paths are reported against
+ * @param {RegExp} matches which file names belong to the scope
+ * @returns {string[]} sorted
+ */
+function walk(dir, root, matches) {
+  if (!fs.existsSync(dir)) return [];
+  const found = [];
+  const descend = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) descend(full);
+      else if (matches.test(entry.name)) found.push(path.relative(root, full).split(path.sep).join('/'));
+    }
+  };
+  descend(dir);
+  return found.sort();
+}
+
+/**
+ * Where an `@see` target lies, or null when this run cannot say.
+ *
+ * @param {{target: string, root: string, apiRoot: string|null}} params
+ * @returns {string|null} the absolute path to test, or null when unresolvable here
+ */
+function resolveSeeTarget({ target, root, apiRoot }) {
+  if (!target.startsWith(API_PREFIX)) return path.join(root, target);
+  if (apiRoot === null) return null;
+  return path.join(apiRoot, target.slice(API_PREFIX.length));
+}
+
+/**
+ * The header findings of one script.
+ *
+ * @param {{relative: string, lines: string[], root: string, apiRoot: string|null}} params
+ * @param {(id: string, line: number, message: string) => void} report
+ * @param {(target: string) => void} unresolved
+ */
+function lintHeader({ relative, lines, root, apiRoot }, report, unresolved) {
+  const marker = relative.endsWith('.sh') ? '#' : '//';
+  let i = lines[0] !== undefined && lines[0].startsWith('#!') ? 1 : 0;
+
+  // S001: five fields, exact order, contiguous from the top · S003: the comment
+  // marker matches the file type. (There is no S002 — the ids are the standard's,
+  // and it never defined one.)
+  const fields = {};
+  for (const name of ORDER) {
+    const line = lines[i] === undefined ? '' : lines[i];
+    const parsed = line.match(/^(#|\/\/) ([A-Za-z]+): (.*)$/);
+    if (parsed === null || parsed[2] !== name) {
+      report('S001', i + 1,
+        `Header field "${marker} ${name}: " expected here, found "${line.slice(0, 60)}". `
+        + `The five fields (${ORDER.join(', ')}) sit in this order immediately after the shebang `
+        + '(SCRIPTS-STANDARD §1). Fix: write the missing/misplaced field.');
+      return;
+    }
+    if (parsed[1] !== marker) {
+      report('S003', i + 1, `Comment marker "${parsed[1]}" does not match the file type - `
+        + `${relative.endsWith('.sh') ? 'shell scripts use "# "' : 'Node scripts use "// "'} (SCRIPTS-STANDARD §1).`);
+      return;
+    }
+    fields[name] = { value: parsed[3].trim(), line: i + 1 };
+    i += 1;
+  }
+
+  // S004 / S008: the two closed vocabularies. A parseable-but-foreign value is a
+  // lie with a green checkmark.
+  if (!STATUS_VOCAB.has(fields.Status.value)) {
+    report('S004', fields.Status.line,
+      `Status "${fields.Status.value}" is not in the closed vocabulary current|draft|archived `
+      + '(SCRIPTS-STANDARD §2). A parseable-but-foreign value is a lie with a green checkmark. '
+      + 'Fix: use one of the three words; extra prose goes below the blank comment line.');
+  }
+  if (!SHELL_VOCAB.has(fields.Shell.value)) {
+    report('S008', fields.Shell.line,
+      `Shell "${fields.Shell.value}" is not in the closed vocabulary `
+      + 'bash>=4|bash>=3.2|sh|node>=18|node>=24 (SCRIPTS-STANDARD §2).');
+  }
+
+  // S005: blank comment line after Status
+  if ((lines[i] === undefined ? '' : lines[i]).trim() !== marker) {
+    report('S005', i + 1,
+      `A blank comment line ("${marker}") must follow Status before any free text or @see (SCRIPTS-STANDARD §1).`);
+    return;
+  }
+  i += 1;
+
+  // S006: every @see immediately following points at a file that is there. The
+  // target is the first whitespace-delimited token after "@see" — section
+  // fragments (§…), em-dash annotations and parenthetical notes follow it.
+  while ((lines[i] === undefined ? '' : lines[i]).startsWith(`${marker} @see `)) {
+    const target = lines[i].slice(marker.length + 6).trim().split(/\s+/)[0];
+    const resolved = resolveSeeTarget({ target, root, apiRoot });
+    if (resolved === null) unresolved(target);
+    else if (!fs.existsSync(resolved)) {
+      report('S006', i + 1, `@see target "${target}" does not exist in the repo. Fix the path, or remove `
+        + 'the line; a dead pointer teaches the reader a wrong home (SCRIPTS-STANDARD §3).');
+    }
+    i += 1;
+  }
+
+  // S007: a library declares the usage word of ITS LANGUAGE.
+  if (LIBRARY_SCOPES.some((scope) => relative.startsWith(scope))) {
+    const expected = usageWordFor(relative);
+    if (fields.Usage.value !== expected) {
+      report('S007', fields.Usage.line, `A ${languageOf(relative)} library declares Usage: ${expected}, `
+        + `found "${fields.Usage.value}" (SCRIPTS-STANDARD §2).`);
+    }
+  }
+}
+
+/**
+ * The rules over one repository.
+ *
+ * A repository with no `scripts/` is an EMPTY scope, not an error: the caller
+ * that needs "there must be scripts here" is the api CLI, which says so itself,
+ * and the manifest row asks the question of eight repositories of which one may
+ * legitimately carry none. The returned `scanned` is what makes the difference
+ * visible — an empty scope and a clean scope do not look alike.
+ *
+ * @param {{root: string, apiRoot?: string|null}} params
+ *   `root` — the repository to read; `apiRoot` — the api checkout an `api/…`
+ *   citation is resolved against, or null when this run has none.
+ * @returns {{findings: Array<{id: string, file: string, line: number, message: string}>,
+ *            scanned: string[], citationScanned: string[], unresolved: string[]}}
+ */
+function lintScripts({ root, apiRoot = null }) {
+  if (typeof root !== 'string' || root.length === 0) {
+    throw new Error('[LintScripts] Repository root is required - lintScripts({ root }) got '
+      + `${JSON.stringify(root)}. Fix: pass the directory whose scripts/ is to be read.`);
+  }
+
+  const scanned = walk(path.join(root, SCRIPT_SCOPE), root, SCRIPT_EXTENSIONS);
+  const citationScanned = walk(path.join(root, ...CITATION_SCOPE.split('/')), root, CITATION_EXTENSIONS);
+
+  const findings = [];
+  const unresolved = [];
+
+  for (const relative of scanned) {
+    const lines = fs.readFileSync(path.join(root, ...relative.split('/')), 'utf8').split('\n');
+    lintHeader(
+      { relative, lines, root, apiRoot },
+      (id, line, message) => findings.push({ id, file: relative, line, message }),
+      (target) => unresolved.push(target)
+    );
+  }
+
+  // S009: a comment under tests/scripts/ cites a symbol or a literal string, and
+  // a covered defect cites the commit hash — never a line number.
+  for (const relative of citationScanned) {
+    const lines = fs.readFileSync(path.join(root, ...relative.split('/')), 'utf8').split('\n');
+    for (let n = 0; n < lines.length; n += 1) {
+      if (!COMMENT_LINE.test(lines[n])) continue;
+      const hit = lines[n].match(LINE_CITATION);
+      if (hit === null) continue;
+      findings.push({
+        id: 'S009',
+        file: relative,
+        line: n + 1,
+        message: `Comment cites a line number - "${hit[0]}". A line number has no mechanism keeping it true: `
+          + 'the file moves and the number stays (doc-code-binding.md §1). Fix: cite a symbol or a literal '
+          + 'string; a covered defect cites the commit hash that introduced or repaired it '
+          + "(git log -S'<string>' --format=%h -- <file>) - DOC-STANDARD rule 11."
+      });
+    }
+  }
+
+  return { findings, scanned, citationScanned, unresolved };
+}
+
+module.exports = {
+  lintScripts,
+  SCRIPT_SCOPE,
+  CITATION_SCOPE,
+  ORDER,
+  STATUS_VOCAB,
+  SHELL_VOCAB
+};

package/src/manifest/checks/composeRunnerBlock.js

@@ -0,0 +1,222 @@
+'use strict';
+
+/**
+ * The one-shot test runner as a DELIMITED BLOCK — the single definition the
+ * conformance check and the generator both read.
+ *
+ * Why a block rather than a whole file: a compose file cannot be byte-equal
+ * across repositories, because the service it declares IS the repository. But
+ * the runner beside that service is a platform decision end to end (owner
+ * decision `api/docs/governance/confirmations/biz-test-container.md` 001) — its
+ * profile, its user, its own memory budget, its entrypoint, and the paragraph
+ * explaining why the budget is separate. Measured over the eight biz
+ * repositories on 2026-09-09, seven declare a runner that is semantically the
+ * same and differs only in three places, all of them named below.
+ *
+ * ## What "normalized" means, and why it is not a loosening
+ *
+ * Two of the runner's declarations are NOT the block's to fix, because another
+ * rule already fixes them: `serviceFiles.js` § `composeRunner` requires the
+ * runner's `build`, `env_file` and `networks` to equal **the service it tests**.
+ * A service that reaches a second network reaches it in both nodes or its suite
+ * cannot see what the service sees. So those three are compared against the
+ * service (there), and removed before the block is compared against the template
+ * (here) — one concern, one rail (`.claude/rules/change-discipline.md` § One rail
+ * per concern). Everything else in the block is compared byte for byte.
+ *
+ * The service's own identity is the other normalization: the runner's key is
+ * `<container>_tests`, and the container name is the one thing that is per
+ * repository by construction. It is substituted back to the template's
+ * placeholders before the comparison, so the block is read as the template
+ * wrote it.
+ *
+ * ## The same definition renders
+ *
+ * `renderRunnerBlock` performs exactly the inverse: the template's block with
+ * this repository's identity in it and this repository's three shared
+ * declarations grafted in. That is what makes `npx oa-sync-template
+ * docker-compose.yml` produce a block the check then finds clean — a generator
+ * whose output its own check rejects is the defect this module exists to avoid.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md §2, §3.2
+ * @see api/docs/governance/confirmations/biz-test-container.md
+ */
+
+/** The declarations a runner shares with the service, or it is not testing the same thing. */
+const SHARED_DECLARATIONS = Object.freeze(['build', 'env_file', 'networks']);
+
+/** How deep the keys of one compose service sit, in the two-space indentation every compose file here uses. */
+const MEMBER_INDENT = 4;
+
+/** How deep a compose service's own name sits. */
+const SERVICE_INDENT = 2;
+
+/** The template's placeholders this module substitutes in both directions. */
+const CONTAINER_PLACEHOLDER = '__CONTAINER_NAME__';
+const SERVICE_PLACEHOLDER = '__SERVICE_NAME__';
+
+const indentOf = (line) => line.length - line.replace(/^ +/, '').length;
+
+/**
+ * The lines of `key:` and everything nested under it, within one node's lines.
+ *
+ * @param {string[]} lines the node's lines, its own name line included
+ * @param {string} key the declaration
+ * @param {number} indent the indentation the node's keys sit at
+ * @returns {{start: number, end: number}|null} null when the node does not declare it
+ */
+function declarationSpan(lines, key, indent = MEMBER_INDENT) {
+  const start = lines.findIndex((line) => indentOf(line) === indent && line.trim().startsWith(`${key}:`));
+  if (start === -1) return null;
+
+  let end = start + 1;
+  while (end < lines.length && lines[end].trim() !== '' && indentOf(lines[end]) > indent) end += 1;
+  return { start, end };
+}
+
+/**
+ * Where one compose service's lines begin and end, its name line first.
+ *
+ * The span starts at the KEY and not at whatever comment sits above it: those
+ * lines are the repository's own prose — in `api_biz/converter` they are the
+ * memory measurement taken inside that container — and a run that replaces the
+ * declaration has no business deleting them.
+ *
+ * @param {string} text the compose file
+ * @param {string} name the compose service name
+ * @returns {{start: number, end: number}|null} null when the file declares no such service
+ */
+function serviceSpan(text, name) {
+  const lines = text.split('\n');
+  const start = lines.findIndex((line) => indentOf(line) === SERVICE_INDENT && line.trim() === `${name}:`);
+  if (start === -1) return null;
+
+  let end = start + 1;
+  while (end < lines.length && (lines[end].trim() === '' || indentOf(lines[end]) > SERVICE_INDENT)) end += 1;
+  while (end > start + 1 && lines[end - 1].trim() === '') end -= 1;
+  return { start, end };
+}
+
+/**
+ * The lines of one compose service, its name line first.
+ *
+ * Read from the raw text rather than from the parsed node, because the graft
+ * writes the service's declaration back into a file VERBATIM — a re-serialized
+ * copy would rewrite formatting nobody asked to change
+ * (`.claude/rules/automation-gates.md` §1 requirement 3).
+ *
+ * @param {string} text the compose file
+ * @param {string} name the compose service name
+ * @returns {string[]} [] when the file declares no such service
+ */
+function serviceLines(text, name) {
+  const span = serviceSpan(text, name);
+  return span === null ? [] : text.split('\n').slice(span.start, span.end);
+}
+
+/**
+ * A compose file with ONE service's declaration replaced, and every other line
+ * of it left exactly as it was.
+ *
+ * The case it exists for was measured on 2026-09-10: seven of the eight biz
+ * repositories carry a runner that predates the block markers (d.220), so a run
+ * that only knew how to INSERT gave those files a second
+ * `<container>_tests:` key — a duplicate mapping key, which compose either
+ * refuses or resolves by taking the last one. Replacing it in place keeps one
+ * key, at the position the repository already chose for it.
+ *
+ * @param {{text: string, name: string, replacement: string[]}} args
+ * @returns {string}
+ */
+function replaceServiceNode({ text, name, replacement }) {
+  const span = serviceSpan(text, name);
+  if (span === null) {
+    throw new Error(`[ComposeRunnerBlock] No compose service "${name}" to replace - the file declares no `
+      + `line reading "  ${name}:". Fix: name a service the file declares.`);
+  }
+  const lines = text.split('\n');
+  return [...lines.slice(0, span.start), ...replacement, ...lines.slice(span.end)].join('\n');
+}
+
+/**
+ * The block without the declarations another rule owns.
+ *
+ * @param {string[]} lines
+ * @param {ReadonlyArray<string>} keys
+ * @returns {string[]}
+ */
+function stripDeclarations(lines, keys) {
+  let remaining = lines.slice();
+  for (const key of keys) {
+    const span = declarationSpan(remaining, key);
+    if (span === null) continue;
+    remaining = [...remaining.slice(0, span.start), ...remaining.slice(span.end)];
+  }
+  return remaining;
+}
+
+/**
+ * A repository's runner block as the template wrote it: its identity replaced by
+ * the placeholders, and the three shared declarations removed.
+ *
+ * The container name is substituted BEFORE the service name on purpose: the
+ * container name normally contains the service name (`api_service_converter`
+ * carries `converter`), so the wider match has to go first or it is destroyed by
+ * the narrower one.
+ *
+ * @param {{lines: string[], containerName: string, serviceName: string}} args
+ * @returns {string[]}
+ */
+function normalizeRunnerBlock({ lines, containerName, serviceName }) {
+  return stripDeclarations(lines, SHARED_DECLARATIONS).map((line) => line
+    .split(containerName).join(CONTAINER_PLACEHOLDER)
+    .split(serviceName).join(SERVICE_PLACEHOLDER));
+}
+
+/**
+ * The template's runner block for one repository: its identity substituted in,
+ * and its `build`, `env_file` and `networks` taken from the service this runner
+ * tests.
+ *
+ * A declaration the service does not make is REMOVED from the rendered block
+ * rather than left at the template's value: "the same as the service" is the
+ * rule, and a runner that reaches a network its service does not is exactly what
+ * the check would then report (`.claude/rules/architecture-principles.md` §3 —
+ * no fallback to a default nobody chose).
+ *
+ * @param {{reference: string[], composeText: string, containerName: string, serviceName: string}} args
+ * @returns {string[]} the block's lines, markers included
+ */
+function renderRunnerBlock({ reference, composeText, containerName, serviceName }) {
+  let rendered = reference.map((line) => line
+    .split(CONTAINER_PLACEHOLDER).join(containerName)
+    .split(SERVICE_PLACEHOLDER).join(serviceName));
+
+  const service = serviceLines(composeText, containerName);
+
+  for (const key of SHARED_DECLARATIONS) {
+    const mine = declarationSpan(rendered, key);
+    if (mine === null) continue;
+
+    const own = declarationSpan(service, key);
+    const replacement = own === null ? [] : service.slice(own.start, own.end);
+    rendered = [...rendered.slice(0, mine.start), ...replacement, ...rendered.slice(mine.end)];
+  }
+
+  return rendered;
+}
+
+module.exports = {
+  SHARED_DECLARATIONS,
+  CONTAINER_PLACEHOLDER,
+  SERVICE_PLACEHOLDER,
+  MEMBER_INDENT,
+  SERVICE_INDENT,
+  declarationSpan,
+  serviceSpan,
+  serviceLines,
+  replaceServiceNode,
+  stripDeclarations,
+  normalizeRunnerBlock,
+  renderRunnerBlock
+};

package/src/manifest/checks/composeShape.js

@@ -0,0 +1,165 @@
+'use strict';
+
+/**
+ * The two facts a compose file answers for this uniform — which services it
+ * declares, and what each of them says about itself — read straight from the
+ * text.
+ *
+ * There is no YAML parser here on purpose. `@onlineapps/conn-orch-validator`
+ * declares two dependencies, both `@onlineapps`, and a package sees only what it
+ * declares (`architecture-principles.md` § Shared Packages, gate G6): pulling a
+ * parser in to read four keys would change what every biz service installs.
+ * `utils/deployContract.js` reads the same files by line for the same reason,
+ * so this is that rail, not a second one.
+ *
+ * The subset it accepts is the one every compose file in this workspace is
+ * written in: two-space indentation, `key: value`, `key:` with a nested block,
+ * and `- item` sequences. A tab makes it fail loudly rather than mis-read a
+ * limit (`automation-gates.md` §1 requirement 4).
+ */
+
+/** How deep one level of nesting is, in spaces, in every compose file here. */
+const INDENT = 2;
+
+const indentOf = (line) => line.length - line.replace(/^ +/, '').length;
+const isBlank = (line) => line.trim() === '' || line.trim().startsWith('#');
+
+/**
+ * @typedef {object} ComposeNode
+ * @property {Map<string,string>} scalars `key: value` pairs at this level
+ * @property {Map<string,ComposeNode>} blocks nested mappings
+ * @property {Map<string,string[]>} sequences `- item` lists, items verbatim
+ * @property {string[]} keys every key at this level, in file order
+ */
+
+/** @returns {ComposeNode} */
+const emptyNode = () => ({ scalars: new Map(), blocks: new Map(), sequences: new Map(), keys: [] });
+
+/**
+ * Parse the lines at one indentation level into a node.
+ *
+ * @param {string[]} lines the whole file, split
+ * @param {number} start index of the first line of this level
+ * @param {number} indent the indentation this level sits at
+ * @returns {{ node: ComposeNode, next: number }}
+ */
+function parseLevel(lines, start, indent) {
+  const node = emptyNode();
+  let i = start;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    if (isBlank(line)) { i += 1; continue; }
+    if (indentOf(line) < indent) break;
+
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith('- ') || trimmed === '-') { i += 1; continue; }
+
+    const colon = trimmed.indexOf(':');
+    if (colon === -1) { i += 1; continue; }
+
+    const key = trimmed.slice(0, colon).trim();
+    const value = trimmed.slice(colon + 1).trim();
+    node.keys.push(key);
+
+    if (value !== '') {
+      node.scalars.set(key, value);
+      i += 1;
+      continue;
+    }
+
+    // A key with nothing after the colon opens either a nested mapping or a
+    // sequence; which one is decided by the first non-blank line under it.
+    let j = i + 1;
+    while (j < lines.length && isBlank(lines[j])) j += 1;
+
+    if (j >= lines.length || indentOf(lines[j]) <= indent) {
+      node.scalars.set(key, '');
+      i = j;
+      continue;
+    }
+
+    if (lines[j].trim().startsWith('-')) {
+      const items = [];
+      while (j < lines.length && (isBlank(lines[j]) || indentOf(lines[j]) > indent)) {
+        if (!isBlank(lines[j])) items.push(lines[j].trim().replace(/^-\s*/, ''));
+        j += 1;
+      }
+      node.sequences.set(key, items);
+      i = j;
+      continue;
+    }
+
+    const nested = parseLevel(lines, j, indentOf(lines[j]));
+    node.blocks.set(key, nested.node);
+    i = nested.next;
+  }
+
+  return { node, next: i };
+}
+
+/**
+ * The services a compose file declares, by name.
+ *
+ * @param {string} text the file's content
+ * @returns {Map<string, ComposeNode>} empty when the file declares no `services:`
+ */
+function readComposeServices(text) {
+  if (/^\t/m.test(text)) {
+    throw new Error('[ComposeShape] Compose file is indented with tabs - this reader accepts the two-space '
+      + 'indentation every compose file in this workspace uses. Fix: re-indent the file with spaces.');
+  }
+
+  const lines = text.split('\n');
+  const top = parseLevel(lines, 0, 0).node;
+  const services = top.blocks.get('services');
+  return services ? services.blocks : new Map();
+}
+
+/**
+ * Follow a dotted path of nested keys and return the scalar at its end.
+ *
+ * @param {ComposeNode} node where to start
+ * @param {string} dotted e.g. `deploy.resources.limits.memory`
+ * @returns {string|null} the value, or null when any step is absent
+ */
+function scalarAt(node, dotted) {
+  const parts = dotted.split('.');
+  const last = parts.pop();
+  let current = node;
+  for (const part of parts) {
+    current = current && current.blocks.get(part);
+    if (!current) return null;
+  }
+  const value = current.scalars.get(last);
+  return value === undefined ? null : value.replace(/^["']|["']$/g, '');
+}
+
+/**
+ * Is this key declared at all — as a scalar, a block or a sequence?
+ *
+ * @param {ComposeNode} node the service block
+ * @param {string} key the key
+ * @returns {boolean}
+ */
+const declares = (node, key) => node.keys.includes(key);
+
+/**
+ * One declaration as comparable text, whatever shape it takes. Two services
+ * that say the same thing compare equal even when one writes a sequence and the
+ * other a scalar.
+ *
+ * @param {ComposeNode} node the service block
+ * @param {string} key the key
+ * @returns {string} '' when the key is absent
+ */
+function declarationOf(node, key) {
+  if (node.sequences.has(key)) return node.sequences.get(key).join('\n');
+  if (node.scalars.has(key)) return node.scalars.get(key);
+  const block = node.blocks.get(key);
+  if (!block) return '';
+  return block.keys.map((child) => `${child}=${block.scalars.get(child) ?? declarationOf(block, child)}`).join('\n');
+}
+
+module.exports = { readComposeServices, scalarAt, declares, declarationOf, INDENT };