@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/core/vocabulary/steps.js

@@ -0,0 +1,266 @@
+/**
+ * What counts as a Gherkin step in a scenario body, and what counts as that
+ * step's ARGUMENT — the one rule `loam gherkin` emits by and `loam validate`
+ * grades by.
+ *
+ * It lives in a leaf of its own because both of those readers need it and they
+ * sit on opposite sides of an import: `spec.ts` parses the markdown a scenario
+ * is written in, `gherkin/emit.ts` renders that scenario into a `.feature` file and
+ * parses requirements back out of `spec.ts` to do it. With the detector inside
+ * `gherkin/emit.ts`, asking "does this scenario have any steps?" from the parser made
+ * the two modules import each other, and a module-evaluation cycle is decided by
+ * whichever entry point happens to be loaded first.
+ *
+ * Nothing here reads a file or knows what a requirement is: it is text in, shape
+ * out, so both sides can depend on it and neither has to depend on the other.
+ * `fenceTracker` comes from `core/kernel/`, the one package below everything, for
+ * the same reason — `core/document/` already depends on this file, so borrowing
+ * the fence rule from `core/document/parse.ts` would close a package cycle.
+ */
+import { fenceTracker } from "../kernel/fences.js";
+const STEP_KEYWORD_RE = /^(given|when|then|and|but)$/i;
+/**
+ * Is this scenario body line a step? A step is a LIST BULLET (`-`, `*`, `+`)
+ * whose text opens with Given/When/Then/And/But — case-insensitive, so the
+ * OpenSpec `- **WHEN** ...` convention counts — where the keyword may be
+ * wrapped in `**bold**` and may carry a trailing colon. The keyword must stand
+ * alone before the step text (`- Givenx` is prose). Everything that is not a
+ * step stays scenario description: prose is never dropped, only steps are
+ * promoted.
+ */
+export function stepFromLine(line) {
+    const bullet = /^\s*[-*+]\s+(.*)$/.exec(line);
+    if (!bullet)
+        return null;
+    const rest = bullet[1];
+    const bold = /^\*\*([^*]+?)\*\*\s*(.*)$/.exec(rest);
+    let lead;
+    let tail;
+    if (bold) {
+        lead = bold[1].trim();
+        tail = bold[2];
+    }
+    else {
+        const sp = /^(\S+)\s*(.*)$/.exec(rest);
+        if (!sp)
+            return null;
+        lead = sp[1];
+        tail = sp[2];
+    }
+    const kw = STEP_KEYWORD_RE.exec(lead.replace(/:$/, ""));
+    if (!kw)
+        return null;
+    const word = kw[1].toLowerCase();
+    return { keyword: word[0].toUpperCase() + word.slice(1), text: tail.trim() };
+}
+/**
+ * `| a | b |` -> `["a", "b"]`; null when the line is not a pipe row at all.
+ *
+ * The split honours markdown's `\|` escape, and that is not a nicety: a cell
+ * holding a literal pipe — a regex alternation, a Kafka key template, a shell
+ * snippet — otherwise splits into two, the row's width stops matching the
+ * header's, and the WHOLE table is reported unreadable. The failure lands on the
+ * one row that needed the escape and reads as if the author miscounted columns.
+ * `\\` unescapes too, so a cell can end in a backslash without eating the
+ * delimiter after it.
+ */
+function cellsOf(line) {
+    const t = line.trim();
+    if (!/^\|.*\|$/.test(t))
+        return null;
+    const cells = [];
+    let cur = "";
+    for (let i = 1; i < t.length - 1; i += 1) {
+        const c = t[i];
+        if (c === "\\" && (t[i + 1] === "|" || t[i + 1] === "\\")) {
+            cur += t[i + 1];
+            i += 1;
+            continue;
+        }
+        if (c === "|") {
+            cells.push(cur.trim());
+            cur = "";
+            continue;
+        }
+        cur += c;
+    }
+    cells.push(cur.trim());
+    return cells;
+}
+/** `|---|:--:|` — the row markdown puts under a table header. */
+function isSeparator(cells) {
+    return cells.length > 0 && cells.every((c) => /^:?-+:?$/.test(c));
+}
+/**
+ * The scenario body split into fenced blocks, markdown tables and plain lines,
+ * in source order.
+ *
+ * Fences are recognised FIRST and win outright, which is what stops a pipe row
+ * inside a JSON payload from being hoisted out of it. That ordering is not a
+ * nicety: before it existed, a scenario carrying a fenced payload that happened
+ * to contain a table emitted the payload as trimmed prose and the payload's own
+ * table as the scenario's `Examples`, turning one data pass into an outline
+ * parameterized by the contents of its own request body — and `loam validate`
+ * graded it green, because steps existed and no table was malformed.
+ */
+function blocksOf(lines) {
+    const out = [];
+    const fenced = fenceTracker();
+    let open = null;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const inFence = fenced(line);
+        const marker = /^(\s*)(```|~~~)(.*)$/.exec(line);
+        if (inFence && marker && open === null) {
+            const info = marker[3].trim();
+            open = { indent: marker[1].length, lines: [], ...(info.length > 0 ? { contentType: info } : {}) };
+            continue;
+        }
+        if (open !== null) {
+            // The tracker still reports the CLOSING marker as fenced content, so the
+            // marker line is what ends the block rather than the first unfenced line
+            // after it — reading it the other way swallows the line following the
+            // fence into the payload.
+            if (marker) {
+                out.push({ kind: "fence", ...open });
+                open = null;
+                continue;
+            }
+            open.lines.push(line);
+            continue;
+        }
+        const table = tableAt(lines, i);
+        if (table !== null) {
+            out.push({ kind: "table", indent: table.indent, rows: table.rows, lines: lines.slice(i, table.end + 1) });
+            i = table.end;
+            continue;
+        }
+        out.push({ kind: "line", text: line });
+    }
+    // An unterminated fence is the author's typo, not a reason to lose the text:
+    // its lines go back as plain lines and land in the description.
+    if (open !== null)
+        for (const l of open.lines)
+            out.push({ kind: "line", text: l });
+    return out;
+}
+/**
+ * The markdown table starting at `lines[i]`, or null when none does.
+ * `rows` is null when a table was clearly intended and its shape cannot be read.
+ */
+function tableAt(lines, i) {
+    const header = cellsOf(lines[i] ?? "");
+    // An unnamed column cannot be referenced by a `<placeholder>`, so a header
+    // with an empty cell is not a header — it is prose that contains pipes.
+    if (header === null || header.length === 0 || header.some((c) => c.length === 0))
+        return null;
+    const sep = cellsOf(lines[i + 1] ?? "");
+    if (sep === null || !isSeparator(sep))
+        return null;
+    const indent = /^\s*/.exec(lines[i])[0].length;
+    if (sep.length !== header.length)
+        return { indent, end: i + 1, rows: null };
+    const rows = [];
+    let end = i + 1;
+    for (let j = i + 2; j < lines.length; j += 1) {
+        const row = cellsOf(lines[j]);
+        if (row === null)
+            break;
+        end = j;
+        if (row.length !== header.length)
+            return { indent, end, rows: null };
+        rows.push(row);
+    }
+    // A header and a separator with nothing under them is a table that carries
+    // zero cases — worse than no table, because it reads as coverage.
+    if (rows.length === 0)
+        return { indent, end, rows: null };
+    return { indent, end, rows: [header, ...rows] };
+}
+/**
+ * A scenario body split for rendering: bullet lines that read as steps become
+ * steps, a fenced block or an INDENTED table under a step becomes that step's
+ * argument, a table at the body's own left margin becomes the `Examples` of a
+ * `Scenario Outline`, and every other non-blank line is kept (edge-trimmed) as
+ * the scenario's description. Description renders BEFORE the steps whatever the
+ * source order — Gherkin's grammar ends a description at the first step keyword
+ * — so prose survives verbatim but interleaving does not.
+ *
+ * INDENTATION IS THE WHOLE DISAMBIGUATION, and it is one rule an author can
+ * hold in their head: a table written under a step, indented the way markdown
+ * already asks you to indent anything belonging to a list item, is that step's
+ * data table; a table at the margin is the scenario's case matrix. Before this
+ * rule existed there was only the second reading, so `Then the ledger holds:`
+ * followed by its expected rows silently became a two-case outline and the step
+ * reached the runner with no argument at all.
+ *
+ * The table matters more than it looks in both roles. A permission matrix, a
+ * validation matrix, a status-code table — the shape most of a service's
+ * decision layer actually has — is one parameterized test in the code it came
+ * from and one outline here. And an expected-state table is how a component
+ * test says what a row, a topic or an outbox must hold after one data pass;
+ * without it that assertion is prose, and prose asserts nothing.
+ *
+ * ONLY THE FIRST top-level table is `Examples`. Gherkin permits several
+ * `Examples` blocks per outline, and supporting them would make "which table is
+ * the outline's" a question with no answer in markdown; a second one keeps its
+ * prose exactly as it reads today.
+ */
+export function scenarioGherkin(lines) {
+    const description = [];
+    const steps = [];
+    let examples = null;
+    let malformedExamples = false;
+    let strandedBlocks = false;
+    const keep = (raw) => {
+        for (const l of raw)
+            if (l.trim().length > 0)
+                description.push(l.trim());
+    };
+    for (const block of blocksOf(lines)) {
+        if (block.kind === "line") {
+            if (block.text.trim().length === 0)
+                continue;
+            const step = stepFromLine(block.text);
+            if (step)
+                steps.push({ text: step.text.length > 0 ? `${step.keyword} ${step.text}` : step.keyword });
+            else
+                description.push(block.text.trim());
+            continue;
+        }
+        const last = steps[steps.length - 1];
+        if (block.kind === "fence") {
+            if (last === undefined) {
+                strandedBlocks = true;
+                keep(block.lines);
+                continue;
+            }
+            last.docstring = {
+                ...(block.contentType === undefined ? {} : { contentType: block.contentType }),
+                lines: block.lines.map((l) => l.slice(0, block.indent).trim().length === 0 ? l.slice(block.indent) : l.trimStart()),
+            };
+            continue;
+        }
+        // A table at the margin answers to the scenario; an indented one answers to
+        // the step above it. Either can be unreadable, and an unreadable one keeps
+        // its prose rather than being guessed at.
+        if (block.indent === 0 && examples === null && !malformedExamples) {
+            if (block.rows === null) {
+                malformedExamples = true;
+                keep(block.lines);
+            }
+            else
+                examples = { header: block.rows[0], rows: block.rows.slice(1) };
+            continue;
+        }
+        if (block.indent > 0 && block.rows !== null && last !== undefined) {
+            last.table = block.rows;
+            continue;
+        }
+        if (block.indent > 0)
+            strandedBlocks = true;
+        keep(block.lines);
+    }
+    return { description, steps, examples, malformedExamples, strandedBlocks };
+}
+//# sourceMappingURL=steps.js.map

package/dist/core/vocabulary/steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../../src/core/vocabulary/steps.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What counts as a Gherkin step in a scenario body, and what counts as that\n * step's ARGUMENT — the one rule `loam gherkin` emits by and `loam validate`\n * grades by.\n *\n * It lives in a leaf of its own because both of those readers need it and they\n * sit on opposite sides of an import: `spec.ts` parses the markdown a scenario\n * is written in, `gherkin/emit.ts` renders that scenario into a `.feature` file and\n * parses requirements back out of `spec.ts` to do it. With the detector inside\n * `gherkin/emit.ts`, asking \"does this scenario have any steps?\" from the parser made\n * the two modules import each other, and a module-evaluation cycle is decided by\n * whichever entry point happens to be loaded first.\n *\n * Nothing here reads a file or knows what a requirement is: it is text in, shape\n * out, so both sides can depend on it and neither has to depend on the other.\n * `fenceTracker` comes from `core/kernel/`, the one package below everything, for\n * the same reason — `core/document/` already depends on this file, so borrowing\n * the fence rule from `core/document/parse.ts` would close a package cycle.\n */\n\nimport { fenceTracker } from \"../kernel/fences.js\";\n\nconst STEP_KEYWORD_RE = /^(given|when|then|and|but)$/i;\n\nexport interface Step {\n  /** Canonical Gherkin keyword: Given / When / Then / And / But. */\n  keyword: string;\n  /** The rest of the line, trimmed. May be empty. */\n  text: string;\n}\n\n/**\n * Is this scenario body line a step? A step is a LIST BULLET (`-`, `*`, `+`)\n * whose text opens with Given/When/Then/And/But — case-insensitive, so the\n * OpenSpec `- **WHEN** ...` convention counts — where the keyword may be\n * wrapped in `**bold**` and may carry a trailing colon. The keyword must stand\n * alone before the step text (`- Givenx` is prose). Everything that is not a\n * step stays scenario description: prose is never dropped, only steps are\n * promoted.\n */\nexport function stepFromLine(line: string): Step | null {\n  const bullet = /^\\s*[-*+]\\s+(.*)$/.exec(line);\n  if (!bullet) return null;\n  const rest = bullet[1]!;\n  const bold = /^\\*\\*([^*]+?)\\*\\*\\s*(.*)$/.exec(rest);\n  let lead: string;\n  let tail: string;\n  if (bold) {\n    lead = bold[1]!.trim();\n    tail = bold[2]!;\n  } else {\n    const sp = /^(\\S+)\\s*(.*)$/.exec(rest);\n    if (!sp) return null;\n    lead = sp[1]!;\n    tail = sp[2]!;\n  }\n  const kw = STEP_KEYWORD_RE.exec(lead.replace(/:$/, \"\"));\n  if (!kw) return null;\n  const word = kw[1]!.toLowerCase();\n  return { keyword: word[0]!.toUpperCase() + word.slice(1), text: tail.trim() };\n}\n\n/** A Gherkin `Examples` table: the column names, then one row of values per case. */\nexport interface Examples {\n  header: string[];\n  rows: string[][];\n}\n\n/**\n * A fenced block written under a step — Gherkin's docstring argument, and the\n * only way to put a request body, an expected JSON document or any other\n * multi-line literal into a scenario.\n *\n * `lines` are NOT trimmed beyond removing the fence's own indentation, and that\n * asymmetry with every other line in this module is the whole point: a payload\n * whose leading whitespace has been eaten is a payload no step definition can\n * compare against, and the loss is invisible because the file still parses.\n */\nexport interface DocString {\n  /** The fence's info string (` ```json ` -> \"json\"), absent when it carried none. */\n  contentType?: string;\n  lines: string[];\n}\n\n/** One step as it will be emitted, with the argument written under it, if any. */\nexport interface EmittedStep {\n  /** The rendered step line: keyword then text — `Given a payment of 100.00`. */\n  text: string;\n  docstring?: DocString;\n  /**\n   * An INDENTED markdown table written under this step, as Gherkin's data-table\n   * argument: every row including the header, with the markdown separator row\n   * dropped. Markdown needs the separator to render at all, Gherkin has no such\n   * row, and the source stays legible in a pull request either way.\n   */\n  table?: string[][];\n}\n\nexport interface ScenarioGherkin {\n  description: string[];\n  steps: EmittedStep[];\n  /** The cases a `Scenario Outline` runs, or null for a plain `Scenario`. */\n  examples: Examples | null;\n  /**\n   * A top-level table was clearly intended as `Examples` and could not be read —\n   * a row whose width disagrees with the header, or a header with no rows under\n   * it.\n   *\n   * Reported rather than guessed at. The rule this whole module holds is that\n   * prose is never dropped, so a table loam cannot read stays in the scenario\n   * DESCRIPTION and the emission is still valid Gherkin — which is exactly why\n   * silence would be wrong: the author wrote twenty cases, cucumber runs one\n   * scenario, and both the file and the report look healthy.\n   */\n  malformedExamples: boolean;\n  /**\n   * A fenced block or an indented table was written where it cannot become a\n   * step argument — before the scenario's first step, or (for a table) in a\n   * shape this module cannot read. It stays in the description, so nothing is\n   * lost from the DOCUMENT, and everything is lost from the TEST: the payload\n   * reaches no step definition and the runner sees a step with no argument.\n   *\n   * A separate flag from `malformedExamples` because the fixes are different —\n   * one is \"move it under a step\", the other is \"give the table equal columns\" —\n   * and a machine must not have to guess which was meant.\n   */\n  strandedBlocks: boolean;\n}\n\n/**\n * `| a | b |` -> `[\"a\", \"b\"]`; null when the line is not a pipe row at all.\n *\n * The split honours markdown's `\\|` escape, and that is not a nicety: a cell\n * holding a literal pipe — a regex alternation, a Kafka key template, a shell\n * snippet — otherwise splits into two, the row's width stops matching the\n * header's, and the WHOLE table is reported unreadable. The failure lands on the\n * one row that needed the escape and reads as if the author miscounted columns.\n * `\\\\` unescapes too, so a cell can end in a backslash without eating the\n * delimiter after it.\n */\nfunction cellsOf(line: string): string[] | null {\n  const t = line.trim();\n  if (!/^\\|.*\\|$/.test(t)) return null;\n  const cells: string[] = [];\n  let cur = \"\";\n  for (let i = 1; i < t.length - 1; i += 1) {\n    const c = t[i]!;\n    if (c === \"\\\\\" && (t[i + 1] === \"|\" || t[i + 1] === \"\\\\\")) {\n      cur += t[i + 1]!;\n      i += 1;\n      continue;\n    }\n    if (c === \"|\") {\n      cells.push(cur.trim());\n      cur = \"\";\n      continue;\n    }\n    cur += c;\n  }\n  cells.push(cur.trim());\n  return cells;\n}\n\n/** `|---|:--:|` — the row markdown puts under a table header. */\nfunction isSeparator(cells: string[]): boolean {\n  return cells.length > 0 && cells.every((c) => /^:?-+:?$/.test(c));\n}\n\n/** One run of source lines, already classified by {@link blocksOf}. */\ntype Block =\n  | { kind: \"line\"; text: string }\n  | { kind: \"fence\"; indent: number; contentType?: string; lines: string[] }\n  | { kind: \"table\"; indent: number; rows: string[][] | null; lines: string[] };\n\n/**\n * The scenario body split into fenced blocks, markdown tables and plain lines,\n * in source order.\n *\n * Fences are recognised FIRST and win outright, which is what stops a pipe row\n * inside a JSON payload from being hoisted out of it. That ordering is not a\n * nicety: before it existed, a scenario carrying a fenced payload that happened\n * to contain a table emitted the payload as trimmed prose and the payload's own\n * table as the scenario's `Examples`, turning one data pass into an outline\n * parameterized by the contents of its own request body — and `loam validate`\n * graded it green, because steps existed and no table was malformed.\n */\nfunction blocksOf(lines: string[]): Block[] {\n  const out: Block[] = [];\n  const fenced = fenceTracker();\n  let open: { indent: number; contentType?: string; lines: string[] } | null = null;\n  for (let i = 0; i < lines.length; i += 1) {\n    const line = lines[i]!;\n    const inFence = fenced(line);\n    const marker = /^(\\s*)(```|~~~)(.*)$/.exec(line);\n    if (inFence && marker && open === null) {\n      const info = marker[3]!.trim();\n      open = { indent: marker[1]!.length, lines: [], ...(info.length > 0 ? { contentType: info } : {}) };\n      continue;\n    }\n    if (open !== null) {\n      // The tracker still reports the CLOSING marker as fenced content, so the\n      // marker line is what ends the block rather than the first unfenced line\n      // after it — reading it the other way swallows the line following the\n      // fence into the payload.\n      if (marker) {\n        out.push({ kind: \"fence\", ...open });\n        open = null;\n        continue;\n      }\n      open.lines.push(line);\n      continue;\n    }\n    const table = tableAt(lines, i);\n    if (table !== null) {\n      out.push({ kind: \"table\", indent: table.indent, rows: table.rows, lines: lines.slice(i, table.end + 1) });\n      i = table.end;\n      continue;\n    }\n    out.push({ kind: \"line\", text: line });\n  }\n  // An unterminated fence is the author's typo, not a reason to lose the text:\n  // its lines go back as plain lines and land in the description.\n  if (open !== null) for (const l of open.lines) out.push({ kind: \"line\", text: l });\n  return out;\n}\n\n/**\n * The markdown table starting at `lines[i]`, or null when none does.\n * `rows` is null when a table was clearly intended and its shape cannot be read.\n */\nfunction tableAt(lines: string[], i: number): { indent: number; end: number; rows: string[][] | null } | null {\n  const header = cellsOf(lines[i] ?? \"\");\n  // An unnamed column cannot be referenced by a `<placeholder>`, so a header\n  // with an empty cell is not a header — it is prose that contains pipes.\n  if (header === null || header.length === 0 || header.some((c) => c.length === 0)) return null;\n  const sep = cellsOf(lines[i + 1] ?? \"\");\n  if (sep === null || !isSeparator(sep)) return null;\n  const indent = /^\\s*/.exec(lines[i]!)![0]!.length;\n  if (sep.length !== header.length) return { indent, end: i + 1, rows: null };\n  const rows: string[][] = [];\n  let end = i + 1;\n  for (let j = i + 2; j < lines.length; j += 1) {\n    const row = cellsOf(lines[j]!);\n    if (row === null) break;\n    end = j;\n    if (row.length !== header.length) return { indent, end, rows: null };\n    rows.push(row);\n  }\n  // A header and a separator with nothing under them is a table that carries\n  // zero cases — worse than no table, because it reads as coverage.\n  if (rows.length === 0) return { indent, end, rows: null };\n  return { indent, end, rows: [header, ...rows] };\n}\n\n/**\n * A scenario body split for rendering: bullet lines that read as steps become\n * steps, a fenced block or an INDENTED table under a step becomes that step's\n * argument, a table at the body's own left margin becomes the `Examples` of a\n * `Scenario Outline`, and every other non-blank line is kept (edge-trimmed) as\n * the scenario's description. Description renders BEFORE the steps whatever the\n * source order — Gherkin's grammar ends a description at the first step keyword\n * — so prose survives verbatim but interleaving does not.\n *\n * INDENTATION IS THE WHOLE DISAMBIGUATION, and it is one rule an author can\n * hold in their head: a table written under a step, indented the way markdown\n * already asks you to indent anything belonging to a list item, is that step's\n * data table; a table at the margin is the scenario's case matrix. Before this\n * rule existed there was only the second reading, so `Then the ledger holds:`\n * followed by its expected rows silently became a two-case outline and the step\n * reached the runner with no argument at all.\n *\n * The table matters more than it looks in both roles. A permission matrix, a\n * validation matrix, a status-code table — the shape most of a service's\n * decision layer actually has — is one parameterized test in the code it came\n * from and one outline here. And an expected-state table is how a component\n * test says what a row, a topic or an outbox must hold after one data pass;\n * without it that assertion is prose, and prose asserts nothing.\n *\n * ONLY THE FIRST top-level table is `Examples`. Gherkin permits several\n * `Examples` blocks per outline, and supporting them would make \"which table is\n * the outline's\" a question with no answer in markdown; a second one keeps its\n * prose exactly as it reads today.\n */\nexport function scenarioGherkin(lines: string[]): ScenarioGherkin {\n  const description: string[] = [];\n  const steps: EmittedStep[] = [];\n  let examples: Examples | null = null;\n  let malformedExamples = false;\n  let strandedBlocks = false;\n  const keep = (raw: string[]): void => {\n    for (const l of raw) if (l.trim().length > 0) description.push(l.trim());\n  };\n  for (const block of blocksOf(lines)) {\n    if (block.kind === \"line\") {\n      if (block.text.trim().length === 0) continue;\n      const step = stepFromLine(block.text);\n      if (step) steps.push({ text: step.text.length > 0 ? `${step.keyword} ${step.text}` : step.keyword });\n      else description.push(block.text.trim());\n      continue;\n    }\n    const last = steps[steps.length - 1];\n    if (block.kind === \"fence\") {\n      if (last === undefined) {\n        strandedBlocks = true;\n        keep(block.lines);\n        continue;\n      }\n      last.docstring = {\n        ...(block.contentType === undefined ? {} : { contentType: block.contentType }),\n        lines: block.lines.map((l) => l.slice(0, block.indent).trim().length === 0 ? l.slice(block.indent) : l.trimStart()),\n      };\n      continue;\n    }\n    // A table at the margin answers to the scenario; an indented one answers to\n    // the step above it. Either can be unreadable, and an unreadable one keeps\n    // its prose rather than being guessed at.\n    if (block.indent === 0 && examples === null && !malformedExamples) {\n      if (block.rows === null) {\n        malformedExamples = true;\n        keep(block.lines);\n      } else examples = { header: block.rows[0]!, rows: block.rows.slice(1) };\n      continue;\n    }\n    if (block.indent > 0 && block.rows !== null && last !== undefined) {\n      last.table = block.rows;\n      continue;\n    }\n    if (block.indent > 0) strandedBlocks = true;\n    keep(block.lines);\n  }\n  return { description, steps, examples, malformedExamples, strandedBlocks };\n}\n"]}

package/dist/core/workspace/discover.js

@@ -0,0 +1,239 @@
+/**
+ * Member discovery for `loam open` — pure computation, no printing.
+ *
+ * The hard problem this module solves is binding DIRECTION: each service
+ * repo's committed loam.json points AT the docs repo, and the docs repo knows
+ * nothing about who points at it. So membership is a join computed at run
+ * time — {candidate directory has a loam.json} ∧ {that config resolves its
+ * docsDir to this docs repo} — over a deliberately bounded search: a depth-1
+ * readdir of a handful of roots, never a disk walk. Same committed files plus
+ * same filesystem always produce the same member set, in the same order.
+ */
+import { realpathSync, statSync } from "node:fs";
+import { readFile, readdir } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { CONFIG_FILENAME, parseConfig } from "../envelope/config.js";
+import { inOrder } from "../kernel/concurrency.js";
+import { DocsRepoUnavailableError } from "../repo/state.js";
+/**
+ * One directory's identity for "is this the same checkout?" comparisons.
+ *
+ * Realpath first, because two spellings of one directory (a symlinked sibling,
+ * an 8.3 short name, a `..` route) must not become two workspace folders.
+ * Case-folded only on win32, because NTFS resolves names case-insensitively
+ * and `realpathSync` does not promise canonical case — without the fold,
+ * `C:\Repos` and `c:\repos` read as two checkouts of one service and convict
+ * an innocent tree of `binding-duplicate`. The fold is NOT applied elsewhere:
+ * on a case-sensitive filesystem two genuinely distinct directories may differ
+ * only by case, and folding there would silently merge them.
+ *
+ * `null` means the path names nothing on this machine — for a candidate's
+ * docsDir that is the answer "bound to a missing or foreign fleet", never an
+ * error.
+ */
+function identityOf(dir) {
+    try {
+        const real = realpathSync(dir);
+        return process.platform === "win32" ? real.toLowerCase() : real;
+    }
+    catch {
+        // Unresolvable is a fact about the filesystem, not a failure of the scan.
+        return null;
+    }
+}
+/** Read and validate one candidate directory's committed binding. */
+async function readBinding(dir) {
+    let raw;
+    try {
+        // The read stays inside the try that classifies it: a loam.json that is a
+        // directory, or one whose permissions refuse us, is "exists but cannot be
+        // believed", exactly as loadConfig treats the same failures.
+        raw = await readFile(join(dir, CONFIG_FILENAME), "utf8");
+    }
+    catch (err) {
+        const e = err;
+        // Not present reads as "not bound to anything" — most siblings of a docs
+        // repo are ordinary directories, and silence is the honest answer for them.
+        if (e.code === "ENOENT")
+            return { kind: "absent" };
+        return { kind: "unreadable", problem: err instanceof Error ? err.message : String(err) };
+    }
+    try {
+        // THE config validator — a second opinion here would let `loam open` count
+        // a checkout every other command refuses to load, or vice versa.
+        return { kind: "config", config: parseConfig(raw, dir) };
+    }
+    catch (err) {
+        return { kind: "unreadable", problem: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Depth-1 candidate directories under one scan root, sorted by name so the
+ * member set never depends on readdir order — or the reason the root could
+ * not be listed at all. The failure is DATA here, not a degrade: whether an
+ * unlistable root reads as empty (a default root a CI sandbox denies) or as a
+ * refusal (an explicit `--root` that owes an honest answer) is the caller's
+ * decision, and this function deciding it would hide the second case forever.
+ */
+async function candidateDirs(root) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch (err) {
+        return { kind: "unlistable", problem: err instanceof Error ? err.message : String(err) };
+    }
+    const dirs = [];
+    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+        const candidate = join(root, entry.name);
+        if (entry.isDirectory()) {
+            dirs.push(candidate);
+            continue;
+        }
+        if (!entry.isSymbolicLink())
+            continue;
+        try {
+            // A symlinked sibling is a real checkout on its other end — developers
+            // link worktrees beside a docs repo — so it is classified by its target.
+            if (statSync(candidate).isDirectory())
+                dirs.push(candidate);
+        }
+        catch {
+            // A dangling link names nothing; there is no checkout to consider.
+        }
+    }
+    return { kind: "listed", dirs };
+}
+/**
+ * Derive the workspace member set from the committed bindings.
+ *
+ * The docs repo and the current repo are always members — their bindings are
+ * the committed facts `loadConfig` already validated. A scanned sibling is a
+ * member iff its loam.json parses and resolves its docsDir to this docs repo.
+ * Ordering is deterministic: docs repo, current repo, then scan members
+ * sorted by folder name and path.
+ *
+ * Throws `DocsRepoUnavailableError` when the docs repo's own identity cannot
+ * be established — it passed the readiness gate moments ago, so an
+ * unresolvable realpath here means it vanished mid-run. Failing closed is the
+ * doctrine: comparing candidates against a guessed identity would silently
+ * drop every member and answer `no-members` about a fleet nobody scanned.
+ */
+export async function discoverMembers(req) {
+    const docsIdentity = identityOf(req.docsDir);
+    if (docsIdentity === null) {
+        throw new DocsRepoUnavailableError({ kind: "missing", path: req.docsDir }, `The configured docs repo does not exist: ${req.docsDir}. ` +
+            "Fix `docsDir` in loam.json, clone the docs repo there, " +
+            "or run `loam init --docs <dir> --create` to make a new one.");
+    }
+    const seen = new Set([docsIdentity]);
+    const docsMember = {
+        path: req.docsDir,
+        name: basename(req.docsDir),
+        service: null,
+        via: "docs-repo",
+    };
+    // Run from the docs repo itself, the current repo IS the docs repo: one
+    // member, and it answers as the docs repo — "docs-repo" is the stronger
+    // fact. The `?? spelling` fallback only feeds the dedupe key: an
+    // unresolvable configRoot still becomes a member, it just dedupes by its
+    // own spelling instead of a canonical one.
+    const currentIdentity = identityOf(req.configRoot) ?? req.configRoot;
+    const currentMember = seen.has(currentIdentity)
+        ? null
+        : {
+            path: req.configRoot,
+            name: req.service ?? basename(req.configRoot),
+            service: req.service ?? null,
+            via: "current-repo",
+        };
+    if (currentMember !== null)
+        seen.add(currentIdentity);
+    // Default roots: beside the docs repo and beside the current repo — the
+    // side-by-side layout SCHEMA.md's "../docs-repo" example already assumes.
+    // Usually one directory; identity-deduped so it is scanned once.
+    const scannedRoots = [];
+    const rootIds = new Set();
+    for (const root of req.roots ?? [dirname(req.docsDir), dirname(req.configRoot)]) {
+        const id = identityOf(root) ?? root;
+        if (rootIds.has(id))
+            continue;
+        rootIds.add(id);
+        scannedRoots.push(root);
+    }
+    const unreadableRoots = [];
+    const skipped = [];
+    const scanMembers = [];
+    // The ROOT loop is sequential on purpose: `seen` is a shared accumulator
+    // and "the earlier root wins" is the documented tie-break for a checkout
+    // reachable under two roots — scanning roots in parallel would make
+    // membership depend on I/O timing. The candidates WITHIN a root carry no
+    // such ordering, so their bindings are read through the shared pool;
+    // `inOrder` returns them in listing order, which keeps the verdicts below
+    // deterministic anyway.
+    for (const root of scannedRoots) {
+        const listing = await candidateDirs(root);
+        if (listing.kind === "unlistable") {
+            unreadableRoots.push({ root, problem: listing.problem });
+            continue;
+        }
+        const bindings = await inOrder(listing.dirs, async (dir) => ({
+            dir,
+            binding: await readBinding(dir),
+        }));
+        for (const { dir, binding } of bindings) {
+            // Identity first, before any verdict: a candidate that already IS a
+            // member (the docs repo itself, the current repo, a symlink twin from
+            // an earlier root) must not be re-reported — least of all as skipped,
+            // which would call one checkout both a member and unreadable.
+            const id = identityOf(dir) ?? dir;
+            if (seen.has(id))
+                continue;
+            if (binding.kind === "absent")
+                continue;
+            if (binding.kind === "unreadable") {
+                // Reported, never fatal — "a file loam cannot read is reported, never
+                // skipped" — but never a member either: an unreadable binding proves
+                // nothing about which fleet the checkout belongs to.
+                skipped.push({ path: join(dir, CONFIG_FILENAME), problem: binding.problem });
+                continue;
+            }
+            // The join itself: bound to THIS docs repo, or not a member. `null`
+            // (docsDir names nothing here) is a checkout of a missing or foreign
+            // fleet — silently out, exactly like one bound elsewhere.
+            if (identityOf(binding.config.docsDir) !== docsIdentity)
+                continue;
+            seen.add(id);
+            scanMembers.push({
+                path: dir,
+                name: binding.config.service ?? basename(dir),
+                service: binding.config.service ?? null,
+                via: "scan",
+                root,
+            });
+        }
+    }
+    scanMembers.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    // Two realpath-DISTINCT checkouts declaring one service id: loam cannot know
+    // which one speaks for the service, and a workspace is derived, not guessed.
+    // The current repo participates — a scanned twin of the repo you are
+    // standing in is the commonest way this happens (a second worktree).
+    const byService = new Map();
+    for (const member of [...(currentMember === null ? [] : [currentMember]), ...scanMembers]) {
+        if (member.service === null)
+            continue;
+        byService.set(member.service, [...(byService.get(member.service) ?? []), member.path]);
+    }
+    const duplicates = [...byService.entries()]
+        .filter(([, paths]) => paths.length > 1)
+        .map(([service, paths]) => ({ service, paths }))
+        .sort((a, b) => (a.service < b.service ? -1 : a.service > b.service ? 1 : 0));
+    return {
+        members: [docsMember, ...(currentMember === null ? [] : [currentMember]), ...scanMembers],
+        scannedRoots,
+        unreadableRoots,
+        skipped,
+        duplicates,
+    };
+}
+//# sourceMappingURL=discover.js.map

package/dist/core/workspace/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../../src/core/workspace/discover.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Member discovery for `loam open` — pure computation, no printing.\n *\n * The hard problem this module solves is binding DIRECTION: each service\n * repo's committed loam.json points AT the docs repo, and the docs repo knows\n * nothing about who points at it. So membership is a join computed at run\n * time — {candidate directory has a loam.json} ∧ {that config resolves its\n * docsDir to this docs repo} — over a deliberately bounded search: a depth-1\n * readdir of a handful of roots, never a disk walk. Same committed files plus\n * same filesystem always produce the same member set, in the same order.\n */\nimport { realpathSync, statSync } from \"node:fs\";\nimport { readFile, readdir } from \"node:fs/promises\";\nimport { basename, dirname, join } from \"node:path\";\nimport { CONFIG_FILENAME, parseConfig, type LoamConfig } from \"../envelope/config.js\";\nimport { inOrder } from \"../kernel/concurrency.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { ServiceId } from \"../kernel/ids/service.js\";\nimport { DocsRepoUnavailableError } from \"../repo/state.js\";\n\ninterface MemberFacts {\n  /** Absolute path of the member's repository root. */\n  path: string;\n  /** Folder display name: the member's service id when bound, else its basename. */\n  name: string;\n  service: ServiceId | null;\n}\n\n/**\n * One folder of the workspace being derived, with where it came from. A\n * variant, not an optional field: `root` exists exactly when the member was\n * found by the scan, and the union makes an always-member carrying a scan\n * root — or a scan member missing one — unrepresentable. One arm per `via`\n * value (not \"docs-repo\" | \"current-repo\" folded into one), because a\n * single-literal discriminant is what the checker's narrowing filters on.\n */\nexport type WorkspaceMember =\n  | (MemberFacts & { via: \"docs-repo\" })\n  | (MemberFacts & { via: \"current-repo\" })\n  | (MemberFacts & { via: \"scan\"; root: string });\n\n/** Everything the scan learned, as data — the command decides what refuses. */\nexport interface Discovery {\n  members: WorkspaceMember[];\n  /** The roots actually scanned, deduped, in scan order. */\n  scannedRoots: string[];\n  /**\n   * Roots whose depth-1 listing itself failed. Recorded, never swallowed:\n   * \"nothing is wrong\" and \"I could not look\" are opposite facts, and only\n   * the caller knows whether the root was a degradable default or an explicit\n   * `--root` that owes a refusal.\n   */\n  unreadableRoots: { root: string; problem: string }[];\n  /** Candidates whose loam.json exists but cannot be believed — reported, never members. */\n  skipped: { path: string; problem: string }[];\n  /** Service ids declared by two or more realpath-distinct member checkouts. */\n  duplicates: { service: string; paths: string[] }[];\n}\n\nexport interface DiscoverRequest {\n  /** Resolved docs repo root — the identity every candidate binding is compared against. */\n  docsDir: DocsDir;\n  /** Root of the repo whose loam.json governs this invocation (`config.root`). */\n  configRoot: string;\n  /** The service that repo declares, when it declares one. */\n  service?: ServiceId;\n  /** Explicit scan roots. When present they REPLACE the defaults — an explicit scan is exactly what was asked. */\n  roots?: string[];\n}\n\n/**\n * One directory's identity for \"is this the same checkout?\" comparisons.\n *\n * Realpath first, because two spellings of one directory (a symlinked sibling,\n * an 8.3 short name, a `..` route) must not become two workspace folders.\n * Case-folded only on win32, because NTFS resolves names case-insensitively\n * and `realpathSync` does not promise canonical case — without the fold,\n * `C:\\Repos` and `c:\\repos` read as two checkouts of one service and convict\n * an innocent tree of `binding-duplicate`. The fold is NOT applied elsewhere:\n * on a case-sensitive filesystem two genuinely distinct directories may differ\n * only by case, and folding there would silently merge them.\n *\n * `null` means the path names nothing on this machine — for a candidate's\n * docsDir that is the answer \"bound to a missing or foreign fleet\", never an\n * error.\n */\nfunction identityOf(dir: string): string | null {\n  try {\n    const real = realpathSync(dir);\n    return process.platform === \"win32\" ? real.toLowerCase() : real;\n  } catch {\n    // Unresolvable is a fact about the filesystem, not a failure of the scan.\n    return null;\n  }\n}\n\n/** A parsed candidate binding, or the reason it cannot be believed. */\ntype Candidate =\n  | { kind: \"config\"; config: LoamConfig }\n  | { kind: \"unreadable\"; problem: string }\n  | { kind: \"absent\" };\n\n/** Read and validate one candidate directory's committed binding. */\nasync function readBinding(dir: string): Promise<Candidate> {\n  let raw: string;\n  try {\n    // The read stays inside the try that classifies it: a loam.json that is a\n    // directory, or one whose permissions refuse us, is \"exists but cannot be\n    // believed\", exactly as loadConfig treats the same failures.\n    raw = await readFile(join(dir, CONFIG_FILENAME), \"utf8\");\n  } catch (err) {\n    const e = err as NodeJS.ErrnoException;\n    // Not present reads as \"not bound to anything\" — most siblings of a docs\n    // repo are ordinary directories, and silence is the honest answer for them.\n    if (e.code === \"ENOENT\") return { kind: \"absent\" };\n    return { kind: \"unreadable\", problem: err instanceof Error ? err.message : String(err) };\n  }\n  try {\n    // THE config validator — a second opinion here would let `loam open` count\n    // a checkout every other command refuses to load, or vice versa.\n    return { kind: \"config\", config: parseConfig(raw, dir) };\n  } catch (err) {\n    return { kind: \"unreadable\", problem: err instanceof Error ? err.message : String(err) };\n  }\n}\n\n/**\n * Depth-1 candidate directories under one scan root, sorted by name so the\n * member set never depends on readdir order — or the reason the root could\n * not be listed at all. The failure is DATA here, not a degrade: whether an\n * unlistable root reads as empty (a default root a CI sandbox denies) or as a\n * refusal (an explicit `--root` that owes an honest answer) is the caller's\n * decision, and this function deciding it would hide the second case forever.\n */\nasync function candidateDirs(\n  root: string,\n): Promise<{ kind: \"listed\"; dirs: string[] } | { kind: \"unlistable\"; problem: string }> {\n  let entries;\n  try {\n    entries = await readdir(root, { withFileTypes: true });\n  } catch (err) {\n    return { kind: \"unlistable\", problem: err instanceof Error ? err.message : String(err) };\n  }\n  const dirs: string[] = [];\n  for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {\n    const candidate = join(root, entry.name);\n    if (entry.isDirectory()) {\n      dirs.push(candidate);\n      continue;\n    }\n    if (!entry.isSymbolicLink()) continue;\n    try {\n      // A symlinked sibling is a real checkout on its other end — developers\n      // link worktrees beside a docs repo — so it is classified by its target.\n      if (statSync(candidate).isDirectory()) dirs.push(candidate);\n    } catch {\n      // A dangling link names nothing; there is no checkout to consider.\n    }\n  }\n  return { kind: \"listed\", dirs };\n}\n\n/**\n * Derive the workspace member set from the committed bindings.\n *\n * The docs repo and the current repo are always members — their bindings are\n * the committed facts `loadConfig` already validated. A scanned sibling is a\n * member iff its loam.json parses and resolves its docsDir to this docs repo.\n * Ordering is deterministic: docs repo, current repo, then scan members\n * sorted by folder name and path.\n *\n * Throws `DocsRepoUnavailableError` when the docs repo's own identity cannot\n * be established — it passed the readiness gate moments ago, so an\n * unresolvable realpath here means it vanished mid-run. Failing closed is the\n * doctrine: comparing candidates against a guessed identity would silently\n * drop every member and answer `no-members` about a fleet nobody scanned.\n */\nexport async function discoverMembers(req: DiscoverRequest): Promise<Discovery> {\n  const docsIdentity = identityOf(req.docsDir);\n  if (docsIdentity === null) {\n    throw new DocsRepoUnavailableError(\n      { kind: \"missing\", path: req.docsDir },\n      `The configured docs repo does not exist: ${req.docsDir}. ` +\n        \"Fix `docsDir` in loam.json, clone the docs repo there, \" +\n        \"or run `loam init --docs <dir> --create` to make a new one.\",\n    );\n  }\n  const seen = new Set<string>([docsIdentity]);\n  const docsMember: WorkspaceMember = {\n    path: req.docsDir,\n    name: basename(req.docsDir),\n    service: null,\n    via: \"docs-repo\",\n  };\n\n  // Run from the docs repo itself, the current repo IS the docs repo: one\n  // member, and it answers as the docs repo — \"docs-repo\" is the stronger\n  // fact. The `?? spelling` fallback only feeds the dedupe key: an\n  // unresolvable configRoot still becomes a member, it just dedupes by its\n  // own spelling instead of a canonical one.\n  const currentIdentity = identityOf(req.configRoot) ?? req.configRoot;\n  const currentMember: WorkspaceMember | null = seen.has(currentIdentity)\n    ? null\n    : {\n        path: req.configRoot,\n        name: req.service ?? basename(req.configRoot),\n        service: req.service ?? null,\n        via: \"current-repo\",\n      };\n  if (currentMember !== null) seen.add(currentIdentity);\n\n  // Default roots: beside the docs repo and beside the current repo — the\n  // side-by-side layout SCHEMA.md's \"../docs-repo\" example already assumes.\n  // Usually one directory; identity-deduped so it is scanned once.\n  const scannedRoots: string[] = [];\n  const rootIds = new Set<string>();\n  for (const root of req.roots ?? [dirname(req.docsDir), dirname(req.configRoot)]) {\n    const id = identityOf(root) ?? root;\n    if (rootIds.has(id)) continue;\n    rootIds.add(id);\n    scannedRoots.push(root);\n  }\n\n  const unreadableRoots: Discovery[\"unreadableRoots\"] = [];\n  const skipped: Discovery[\"skipped\"] = [];\n  const scanMembers: WorkspaceMember[] = [];\n  // The ROOT loop is sequential on purpose: `seen` is a shared accumulator\n  // and \"the earlier root wins\" is the documented tie-break for a checkout\n  // reachable under two roots — scanning roots in parallel would make\n  // membership depend on I/O timing. The candidates WITHIN a root carry no\n  // such ordering, so their bindings are read through the shared pool;\n  // `inOrder` returns them in listing order, which keeps the verdicts below\n  // deterministic anyway.\n  for (const root of scannedRoots) {\n    const listing = await candidateDirs(root);\n    if (listing.kind === \"unlistable\") {\n      unreadableRoots.push({ root, problem: listing.problem });\n      continue;\n    }\n    const bindings = await inOrder(listing.dirs, async (dir) => ({\n      dir,\n      binding: await readBinding(dir),\n    }));\n    for (const { dir, binding } of bindings) {\n      // Identity first, before any verdict: a candidate that already IS a\n      // member (the docs repo itself, the current repo, a symlink twin from\n      // an earlier root) must not be re-reported — least of all as skipped,\n      // which would call one checkout both a member and unreadable.\n      const id = identityOf(dir) ?? dir;\n      if (seen.has(id)) continue;\n      if (binding.kind === \"absent\") continue;\n      if (binding.kind === \"unreadable\") {\n        // Reported, never fatal — \"a file loam cannot read is reported, never\n        // skipped\" — but never a member either: an unreadable binding proves\n        // nothing about which fleet the checkout belongs to.\n        skipped.push({ path: join(dir, CONFIG_FILENAME), problem: binding.problem });\n        continue;\n      }\n      // The join itself: bound to THIS docs repo, or not a member. `null`\n      // (docsDir names nothing here) is a checkout of a missing or foreign\n      // fleet — silently out, exactly like one bound elsewhere.\n      if (identityOf(binding.config.docsDir) !== docsIdentity) continue;\n      seen.add(id);\n      scanMembers.push({\n        path: dir,\n        name: binding.config.service ?? basename(dir),\n        service: binding.config.service ?? null,\n        via: \"scan\",\n        root,\n      });\n    }\n  }\n  scanMembers.sort((a, b) =>\n    a.name < b.name ? -1 : a.name > b.name ? 1 : a.path < b.path ? -1 : a.path > b.path ? 1 : 0,\n  );\n\n  // Two realpath-DISTINCT checkouts declaring one service id: loam cannot know\n  // which one speaks for the service, and a workspace is derived, not guessed.\n  // The current repo participates — a scanned twin of the repo you are\n  // standing in is the commonest way this happens (a second worktree).\n  const byService = new Map<string, string[]>();\n  for (const member of [...(currentMember === null ? [] : [currentMember]), ...scanMembers]) {\n    if (member.service === null) continue;\n    byService.set(member.service, [...(byService.get(member.service) ?? []), member.path]);\n  }\n  const duplicates = [...byService.entries()]\n    .filter(([, paths]) => paths.length > 1)\n    .map(([service, paths]) => ({ service, paths }))\n    .sort((a, b) => (a.service < b.service ? -1 : a.service > b.service ? 1 : 0));\n\n  return {\n    members: [docsMember, ...(currentMember === null ? [] : [currentMember]), ...scanMembers],\n    scannedRoots,\n    unreadableRoots,\n    skipped,\n    duplicates,\n  };\n}\n"]}

package/dist/core/workspace/render.js

@@ -0,0 +1,52 @@
+/**
+ * Deterministic `.code-workspace` rendering — pure computation, no printing.
+ *
+ * The output is a derived file: same members plus same target path must
+ * produce the same bytes on every machine, which is why every path is spelled
+ * with forward slashes (VS Code and Cursor accept them on Windows too, and
+ * they are the one spelling that diffs identically across checkouts) and why
+ * the JSON shape follows saveConfig's convention — 2-space indent, trailing
+ * newline.
+ */
+import { dirname, isAbsolute, relative } from "node:path";
+/**
+ * The `path` a folder entry gets, from the already-computed relative and the
+ * member's absolute path.
+ *
+ * Split out of `renderWorkspace` because the fallback decision is win32-only
+ * on a win32 host — `relative()` answers a cross-drive pair with the ABSOLUTE
+ * target, since no `..` chain crosses drives — and a POSIX test host can
+ * therefore never steer the platform `relative()` into producing one. Taking
+ * `rel` as data lets the suite exercise the branch with win32-shaped input.
+ *
+ * The drive-letter test backs up `isAbsolute` because that check is also
+ * platform-bound: on POSIX, `D:\other\svc` reads as a relative name. A POSIX
+ * directory literally named `D:` would match too and get the absolute
+ * spelling instead of the relative one — a stranger workspace file, but a
+ * correct one, and the pathological name is not worth a platform fork here.
+ */
+export function workspacePathSpelling(rel, absolute) {
+    const spelling = rel === "" ? "." : isAbsolute(rel) || /^[A-Za-z]:[\\/]/.test(rel) ? absolute : rel;
+    return spelling.split(/[\\/]/).join("/");
+}
+/**
+ * Render the workspace document for `members`, targeted at `outPath`.
+ *
+ * Folder paths are relative to the file's own directory, so the committed
+ * side-by-side layout opens on every machine that checks it out; a member on
+ * another drive keeps its absolute path, because no relative spelling exists.
+ * The folders are returned still attached to their members so the command can
+ * echo the exact written spelling into its `--json` payload without joining
+ * two arrays by position.
+ */
+export function renderWorkspace(members, outPath) {
+    const outDir = dirname(outPath);
+    const folders = members.map((member) => ({
+        member,
+        name: member.name,
+        path: workspacePathSpelling(relative(outDir, member.path), member.path),
+    }));
+    const text = JSON.stringify({ folders: folders.map(({ name, path }) => ({ name, path })) }, null, 2) + "\n";
+    return { text, folders };
+}
+//# sourceMappingURL=render.js.map