@mmerterden/multi-agent-pipeline 20.12.0 → 20.13.0

package/pipeline/schemas/analysis-spec.schema.json

@@ -57,6 +57,28 @@
       "default": "global",
       "description": "Analysis profile chosen at Phase 0 Step 1b (Locked 31). 'global' renders analysis-template.md (23-section development handoff); 'corporate' renders analysis-template-corporate.md (IG/UC/FG requirements document). Both read the same evidence; only the projection differs."
     },
+    "edgeCandidates": {
+      "type": "array",
+      "description": "Failure paths proposed from the evidence (refusals, error codes, timeouts, empty or expired states), shown at the Pass B preview. Only accepted ones enter the document; a candidate needs a source.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["target", "candidate", "source"],
+        "properties": {
+          "target": {
+            "type": "string",
+            "description": "Use case or rule group the candidate belongs to, e.g. UC-001 or BR-login."
+          },
+          "candidate": { "type": "string", "minLength": 1 },
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Where the evidence states it: a spec path, a page, a file:line."
+          },
+          "accepted": { "type": "boolean" }
+        }
+      }
+    },
     "options": {
       "type": "object",
       "additionalProperties": false,

package/pipeline/schemas/prefs.schema.json

@@ -948,7 +948,7 @@
                 },
                 "titleFormat": {
                   "type": "string",
-                  "description": "Page-title pattern, e.g. \"{prefix}{module}_{flow}_{suffix}\". Placeholders are resolved at emit time."
+                  "description": "Page-title pattern, e.g. \"{status}{prefix}{module}_{flow}_{suffix}\". Placeholders are resolved at emit time; {status} is the draft marker while the document is not final, and empty once it is. Without {status} the marker is prepended."
                 },
                 "titlePrefix": {
                   "type": "string",
@@ -2107,6 +2107,27 @@
               "type": "string",
               "default": "ma-analysis",
               "description": "Prefix of the identity label a created issue carries. The label is how a second run, on a second machine or by a second analyst, finds the tree it already made instead of opening a duplicate."
+            },
+            "epicLinkMode": {
+              "type": "string",
+              "enum": ["auto", "parent", "epicLinkField", "none"],
+              "default": "auto",
+              "description": "How a story joins an existing epic. auto: parent on Cloud, the epic-link field (found by its schema type) on Server and Data Center, nothing when neither exists."
+            },
+            "epicLinkFieldId": {
+              "type": ["string", "null"],
+              "default": null,
+              "description": "The epic-link custom field id, for epicLinkField mode or to skip discovery. Null means discover."
+            },
+            "cloneByChannel": {
+              "type": "boolean",
+              "default": false,
+              "description": "Create one linked story per channel in channelComponents, each carrying that channel's component."
+            },
+            "cloneLinkType": {
+              "type": "string",
+              "default": "Relates",
+              "description": "The link type between a story and its channel clones, by this site's name."
             }
           }
         },

package/pipeline/scripts/analysis-story-body.mjs

@@ -0,0 +1,210 @@
+/**
+ * analysis-story-body.mjs  -  the description of a story planned from an
+ * analysis document.
+ *
+ * Everything in the body comes from the document: the user story, the
+ * acceptance criteria of the story's own requirement ids, the redesign rows that
+ * touch its section, and the links to the analysis page, the design and the API
+ * spec. A missing piece stays missing and is reported as a warning; nothing is
+ * invented. Document text is escaped before it is placed in wiki markup, so it
+ * cannot become a macro, a mention, an image or a link.
+ *
+ * @module pipeline/scripts/analysis-story-body
+ */
+
+import { escapeJiraWiki, wikiLink } from "./jira-wiki-escape.mjs";
+import { redesignSections } from "../lib/analysis-sections.mjs";
+
+const MAX_CRITERIA = 8;
+const MAX_DESIGN_LINKS = 5;
+
+// A criterion that describes a refusal, an error or an alternative path. One is
+// expected per story, so the tester has something that must NOT happen.
+const NEGATIVE =
+  /(?<![\p{L}])(not|never|cannot|error|errors|fails?|failed|invalid|reject\w*|denied|timeout|hata\w*|geçersiz|reddedil\w*|başarısız|olmaz|yapılamaz|bulunamaz\w*)(?![\p{L}])/iu;
+
+const FIGMA_URL = /https:\/\/(?:www\.)?figma\.com\/[^\s)|\]]+/g;
+const API_URL = /https?:\/\/[^\s)|\]]*(?:swagger|openapi|api-docs)[^\s)|\]]*/gi;
+
+function cells(row) {
+  return row
+    .trim()
+    .replace(/^\||\|$/g, "")
+    .split("|")
+    .map((c) => c.trim());
+}
+
+const unbold = (s) => s.replace(/\*\*/g, "").trim();
+
+function headingIndex(lines, pred) {
+  return lines.findIndex((l) => /^#{2,4}\s/.test(l) && pred(l));
+}
+
+/** Lines under the first heading `pred` accepts, up to the next heading at its level or shallower. */
+function bodyUnder(lines, pred) {
+  const start = headingIndex(lines, pred);
+  if (start < 0) return [];
+  const depth = lines[start].match(/^#+/)[0].length;
+  const out = [];
+  for (const l of lines.slice(start + 1)) {
+    const m = l.match(/^(#+)\s/);
+    if (m && m[1].length <= depth) break;
+    out.push(l);
+  }
+  return out;
+}
+
+const sectionPred = (number) => (l) =>
+  new RegExp(`^#{2,4}\\s+${number.replace(/\./g, "\\.")}\\b`).test(l);
+
+/** Value cell of a two-column `| **Field** | value |` row whose field is one of `names`. */
+function fieldValue(lines, names) {
+  for (const l of lines) {
+    if (!l.trim().startsWith("|")) continue;
+    const c = cells(l);
+    if (c.length >= 2 && names.some((n) => unbold(c[0]).toLowerCase() === n.toLowerCase())) {
+      return c[1] || null;
+    }
+  }
+  return null;
+}
+
+function rowFor(lines, id) {
+  return lines.find((l) => {
+    if (!l.trim().startsWith("|")) return false;
+    return (cells(l)[0] || "").toUpperCase() === id.toUpperCase();
+  });
+}
+
+const isEmpty = (v) => !v || /^\p{Pd}$/u.test(v.trim());
+
+function userStoryOf(story, lines, corporate) {
+  if (corporate) {
+    const uc = story.group || "";
+    const ucLines = uc ? bodyUnder(lines, (l) => l.includes(uc)) : [];
+    const desc = fieldValue(ucLines, ["Kısa Açıklama", "Short Description"]);
+    if (isEmpty(desc)) return null;
+    const actor = fieldValue(ucLines, ["Aktör", "Actor"]);
+    return isEmpty(actor) ? desc : `${actor}: ${desc}`;
+  }
+  const isStory = (l) => /^\s*(As an?\s|Bir\s.+\solarak\b)/i.test(l);
+  const own = story.sectionNumber ? bodyUnder(lines, sectionPred(story.sectionNumber)) : [];
+  const line = own.find(isStory);
+  if (line) return line.trim();
+  // Rules often sit in their own sub-section, apart from the story they serve.
+  // The user-story section answers only when it holds exactly one story; with
+  // several, which one this story belongs to is not guessed.
+  const all = bodyUnder(lines, sectionPred("4")).filter(isStory);
+  return all.length === 1 ? all[0].trim() : null;
+}
+
+function acceptanceOf(story, lines, corporate) {
+  const out = [];
+  for (const id of story.sourceIds || []) {
+    const row = rowFor(lines, id);
+    if (!row) continue;
+    const c = cells(row);
+    const value = corporate ? c[1] : !isEmpty(c[3]) ? c[3] : c[1];
+    if (!isEmpty(value)) out.push(value);
+  }
+  if (corporate && story.group) {
+    const ucLines = bodyUnder(lines, (l) => l.includes(story.group));
+    for (const names of [
+      ["Alternatif Akış", "Alternative Flow"],
+      ["İstisna Akışı", "Exception Flow"],
+    ]) {
+      const v = fieldValue(ucLines, names);
+      if (!isEmpty(v)) out.push(v);
+    }
+  }
+  return [...new Set(out)].slice(0, MAX_CRITERIA);
+}
+
+function currentVsTargetOf(story, lines, profile, redesign) {
+  if (!redesign || !story.sectionNumber) return [];
+  const rd = redesignSections(lines, profile);
+  if (!rd.dl.body) return [];
+  const rows = rd.dl.body.filter((l) => /^\s*\|\s*CB-/i.test(l));
+  return rows
+    .map(cells)
+    .filter((c) => (c[2] || "").startsWith(story.sectionNumber))
+    .map((c) => ({ id: c[0], status: c[1], where: c[2] }));
+}
+
+function linksOf(story, lines, ctx) {
+  const links = [];
+  if (ctx.pageUrl) links.push({ kind: "analysis", label: "Analysis", url: ctx.pageUrl });
+  const scope = [
+    ...(story.sectionNumber ? bodyUnder(lines, sectionPred(story.sectionNumber)) : []),
+    ...(story.group ? bodyUnder(lines, (l) => l.includes(story.group)) : []),
+  ].join("\n");
+  const design = [...new Set(scope.match(FIGMA_URL) || [])].slice(0, MAX_DESIGN_LINKS);
+  design.forEach((url, i) =>
+    links.push({ kind: "design", label: design.length > 1 ? `Design ${i + 1}` : "Design", url }),
+  );
+  const refs = bodyUnder(lines, (l) => /Referans|References/i.test(l)).join("\n");
+  const api = [...new Set(refs.match(API_URL) || [])];
+  api.forEach((url, i) =>
+    links.push({ kind: "api", label: api.length > 1 ? `API spec ${i + 1}` : "API spec", url }),
+  );
+  return links;
+}
+
+function render({ userStory, acceptance, currentVsTarget, links }, sourceIds) {
+  const out = [];
+  if (userStory) out.push("h3. User story", escapeJiraWiki(userStory), "");
+  if (acceptance.length) {
+    out.push("h3. Acceptance criteria", ...acceptance.map((a) => `# ${escapeJiraWiki(a)}`), "");
+  }
+  if (currentVsTarget.length) {
+    out.push("h3. Current vs target", "||Id||Status||Where||");
+    for (const r of currentVsTarget) {
+      out.push(`|${escapeJiraWiki(r.id)}|${escapeJiraWiki(r.status)}|${escapeJiraWiki(r.where)}|`);
+    }
+    out.push("");
+  }
+  if (links.length) {
+    out.push("h3. Links", ...links.map((l) => `* ${wikiLink(l.label, l.url)}`), "");
+  }
+  out.push(
+    `Sources: ${escapeJiraWiki(sourceIds.length ? sourceIds.join(", ") : "derived from the section heading")}`,
+  );
+  return out.join("\n");
+}
+
+/**
+ * @param {{title: string, group?: string, sectionNumber?: string, sourceIds: string[]}} story
+ * @param {{text: string, profile?: string, pageUrl?: string|null, redesign?: boolean}} ctx
+ */
+export function buildStoryBody(story, ctx) {
+  const lines = ctx.text.split("\n");
+  const profile = (ctx.profile || "global").toLowerCase();
+  const corporate = profile === "corporate";
+  const userStory = userStoryOf(story, lines, corporate);
+  const acceptance = acceptanceOf(story, lines, corporate);
+  const currentVsTarget = currentVsTargetOf(story, lines, profile, ctx.redesign === true);
+  const links = linksOf(story, lines, ctx);
+
+  const warnings = [];
+  if (!userStory) warnings.push("no user story found in the document");
+  if (acceptance.length < 2)
+    warnings.push(`fewer than 2 acceptance criteria (${acceptance.length})`);
+  if (!acceptance.some((a) => NEGATIVE.test(a))) warnings.push("no negative acceptance criterion");
+
+  const body = { userStory, acceptance, currentVsTarget, links };
+  return { ...body, warnings, wiki: render(body, story.sourceIds || []) };
+}
+
+/**
+ * The short description of a role sub-task: its role, its story and its sources.
+ *
+ * @param {string} role
+ * @param {{title: string, sourceIds: string[]}} story
+ */
+export function buildSubtaskBody(role, story) {
+  return [
+    `Role: ${escapeJiraWiki(role)}`,
+    `Story: ${escapeJiraWiki(story.title)}`,
+    `Sources: ${escapeJiraWiki((story.sourceIds || []).join(", ") || "derived from the section heading")}`,
+  ].join("\n");
+}

package/pipeline/scripts/analysis-story-tree.mjs

@@ -49,12 +49,13 @@
  * field in the JSON, and the exit code is what it was.
  *
  * Usage:
- *   analysis-story-tree.mjs <analysis.md> [--json] [--prefs FILE]
+ *   analysis-story-tree.mjs <analysis.md> [--json] [--brief] [--prefs FILE] [--page-url URL]
  *
  * Exit: 0 planned, 2 nothing to plan, 3 usage, 4 the document is not issue-ready.
  */
 
 import { readFileSync, existsSync } from "node:fs";
+import { buildStoryBody, buildSubtaskBody } from "./analysis-story-body.mjs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -72,12 +73,16 @@ import {
 
 const argv = process.argv.slice(2);
 const JSON_OUT = argv.includes("--json");
+const BRIEF = argv.includes("--brief");
 const prefsFlag = argv.indexOf("--prefs");
 const PREFS_PATH =
   prefsFlag !== -1
     ? argv[prefsFlag + 1]
     : join(homedir(), ".claude", "multi-agent-preferences.json");
-const file = argv.find((a) => !a.startsWith("--") && a !== PREFS_PATH);
+const pageUrlFlag = argv.indexOf("--page-url");
+const PAGE_URL = pageUrlFlag !== -1 ? argv[pageUrlFlag + 1] : null;
+const valueIdx = new Set([prefsFlag, pageUrlFlag].filter((i) => i !== -1).map((i) => i + 1));
+const file = argv.find((a, i) => !a.startsWith("--") && !valueIdx.has(i));
 
 function die(msg, code) {
   process.stderr.write(`${msg}\n`);
@@ -153,6 +158,10 @@ export function identityLabel(prefix, docId, sourceIds) {
  *   issueTree.channelComponents  channel -> this site's component name
  *   issueTree.channelTeams       channel -> this site's team name
  *   issueTree.labelPrefix        prefix of the identity label
+ *   issueTree.epicLinkMode       how a story joins an existing epic
+ *   issueTree.epicLinkFieldId    the epic-link field, when not discovered
+ *   issueTree.cloneByChannel     one linked story per channel in channelComponents
+ *   issueTree.cloneLinkType      the link type between a story and its clones
  */
 const ISSUE_TREE_SETTINGS = [
   "issueTree.enabled",
@@ -164,6 +173,10 @@ const ISSUE_TREE_SETTINGS = [
   "issueTree.channelComponents",
   "issueTree.channelTeams",
   "issueTree.labelPrefix",
+  "issueTree.epicLinkMode",
+  "issueTree.epicLinkFieldId",
+  "issueTree.cloneByChannel",
+  "issueTree.cloneLinkType",
 ];
 
 function readPrefs() {
@@ -234,7 +247,7 @@ export function coverageOf(defined, nodes, corporate = false) {
   };
 }
 
-export function plan(text, prefs) {
+export function plan(text, prefs, { pageUrl = null } = {}) {
   const fm = frontMatter(text);
   const profile = (fm.profile || "global").toLowerCase();
   const corporate = profile === "corporate";
@@ -256,12 +269,9 @@ export function plan(text, prefs) {
   // atoms. A story with no section is still a story - the atoms are the claim,
   // the heading is only the label.
   //
-  // A lite document may carry no ids at all, and its user-story sub-sections are
-  // still real work. Deriving from those keeps such a run useful AND makes
-  // `unverifiable` a state that actually occurs: without this fallback the
-  // no-atom document produced no stories, exited "nothing to plan", and the
-  // unverifiable branch below was unreachable - a case the code claimed to
-  // handle and never could.
+  // A document may carry no ids at all, and its user-story sub-sections are
+  // still real work. Deriving from those keeps such a run useful and gives it
+  // an honest `unverifiable` coverage verdict instead of "nothing to plan".
   //
   // Corporate atoms are attributed ROW-WISE, never section-wise. The template
   // states the mapping in a column - the functional-requirement table carries a
@@ -326,6 +336,7 @@ export function plan(text, prefs) {
       kind: "story",
       title: best && best.n > 0 ? `${best.s.number} ${best.s.title}` : g,
       group: g,
+      sectionNumber: best && best.n > 0 ? best.s.number : null,
       sourceIds: ids,
       label: identityLabel(prefix, docId, [g, ...ids]),
       subtasks: (prefs.subtaskRoles || []).map((role) => ({
@@ -346,6 +357,7 @@ export function plan(text, prefs) {
         kind: "story",
         title: `${sec.number} ${sec.title}`,
         group: sec.number,
+        sectionNumber: sec.number,
         sourceIds: [],
         derivedFrom: "section",
         label: identityLabel(prefix, docId, [sec.number]),
@@ -360,6 +372,34 @@ export function plan(text, prefs) {
     }
   }
 
+  const bodyCtx = {
+    text,
+    profile,
+    pageUrl: pageUrl || fm.confluence_url || null,
+    redesign: String(fm.redesign || "").toLowerCase() === "true",
+  };
+  for (const story of stories) {
+    const b = buildStoryBody(story, bodyCtx);
+    story.description = b.wiki;
+    story.body = {
+      userStory: b.userStory,
+      acceptance: b.acceptance,
+      currentVsTarget: b.currentVsTarget,
+      links: b.links,
+    };
+    story.bodyWarnings = b.warnings;
+    for (const t of story.subtasks) t.description = buildSubtaskBody(t.role, story);
+    const channels = prefs.cloneByChannel ? Object.entries(prefs.channelComponents || {}) : [];
+    story.clones = channels.map(([channel, component]) => ({
+      kind: "clone",
+      channel,
+      title: `${story.title} [${channel}]`,
+      components: [component],
+      label: identityLabel(prefix, docId, [story.group, ...story.sourceIds, `ch:${channel}`]),
+      description: story.description,
+    }));
+  }
+
   const coverage = coverageOf(defined, stories, corporate);
 
   return {
@@ -379,9 +419,16 @@ export function plan(text, prefs) {
       labelPrefix: prefix,
       channelComponents: prefs.channelComponents ?? {},
       channelTeams: prefs.channelTeams ?? {},
+      epicLinkMode: prefs.epicLinkMode ?? "auto",
+      epicLinkFieldId: prefs.epicLinkFieldId ?? null,
+      cloneByChannel: prefs.cloneByChannel === true,
+      cloneLinkType: prefs.cloneLinkType ?? "Relates",
     },
     nodes: stories,
-    writeCount: stories.reduce((n, s) => n + 1 + s.subtasks.length, 0),
+    writeCount: stories.reduce(
+      (n, s) => n + 1 + s.subtasks.length + 2 * (s.clones?.length || 0),
+      0,
+    ),
   };
 }
 
@@ -407,7 +454,11 @@ function consistencyOf(text, nodes) {
 }
 
 async function main() {
-  if (!file) return die("usage: analysis-story-tree.mjs <analysis.md> [--json] [--prefs FILE]", 3);
+  if (!file)
+    return die(
+      "usage: analysis-story-tree.mjs <analysis.md> [--json] [--brief] [--prefs FILE] [--page-url URL]",
+      3,
+    );
   if (!existsSync(file)) return die(`analysis-story-tree: no such file: ${file}`, 3);
   const text = readFileSync(file, "utf8");
 
@@ -438,7 +489,7 @@ async function main() {
     return;
   }
 
-  const result = plan(text, prefs);
+  const result = plan(text, prefs, { pageUrl: PAGE_URL });
   if (result.nodes.length === 0) {
     process.stderr.write("analysis-story-tree: no stories could be derived from this document\n");
     process.exitCode = 2;
@@ -500,9 +551,19 @@ async function main() {
       `      sources: ${s.sourceIds.length ? s.sourceIds.join(", ") : "(none - derived from the section heading)"}\n`,
     );
     process.stdout.write(`      label:   ${s.label}\n`);
+    for (const w of s.bodyWarnings || []) process.stdout.write(`      body warning: ${w}\n`);
+    if (!BRIEF && s.description) {
+      process.stdout.write("      description:\n");
+      for (const line of s.description.split("\n")) process.stdout.write(`        ${line}\n`);
+    }
     for (const t of s.subtasks) {
       process.stdout.write(`      subtask  ${t.role}  [${t.label}]\n`);
     }
+    for (const c of s.clones || []) {
+      process.stdout.write(
+        `      clone    ${c.channel}  component ${c.components.join(", ")}  [${c.label}]\n`,
+      );
+    }
   }
   // Every field's provenance, so a wrong setting is visible here rather than in
   // Jira after the writes have happened.

package/pipeline/scripts/analysis-tickets-writeback.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * analysis-tickets-writeback.mjs  -  list the tickets a story tree produced in
+ * the analysis document it came from.
+ *
+ * Reads the plan (titles, sources, channels) and the writer's ledger (the key
+ * each label was created as, or found as), and writes a `## Tickets` table
+ * between `<!-- tickets:start -->` and `<!-- tickets:end -->`. A second run
+ * replaces the block, so the table never doubles. The block sits after the last
+ * numbered section and carries no number, so canonical numbering is untouched.
+ * A node with no key in the ledger is left out: the table lists what exists.
+ *
+ * Local only. Publishing the updated document is a separate, approved step.
+ *
+ * Usage:
+ *   analysis-tickets-writeback.mjs --doc FILE --ledger FILE --plan FILE
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+const START = "<!-- tickets:start -->";
+const END = "<!-- tickets:end -->";
+
+/** Latest key per label, from `created` and `exists` events. */
+export function keysFromLedger(text) {
+  const keys = new Map();
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let e;
+    try {
+      e = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if ((e.event === "created" || e.event === "exists") && e.label && e.key) {
+      keys.set(e.label, e.key);
+    }
+  }
+  return keys;
+}
+
+const cell = (v) => String(v).replace(/\|/g, "\\|").replace(/\n/g, " ");
+
+/** The marked block for this plan and these keys. */
+export function ticketsBlock(plan, keys) {
+  const rows = [];
+  for (const n of plan.nodes || []) {
+    const sources = (n.sourceIds || []).join(", ") || "-";
+    if (keys.has(n.label)) rows.push([n.title, keys.get(n.label), sources, "-"]);
+    for (const c of n.clones || []) {
+      if (keys.has(c.label)) rows.push([c.title, keys.get(c.label), sources, c.channel]);
+    }
+  }
+  const heading =
+    plan.coverage?.verdict === "unverifiable" ? "## Tickets (coverage unverified)" : "## Tickets";
+  return [
+    START,
+    heading,
+    "",
+    "| Story | Key | Sources | Channel |",
+    "|---|---|---|---|",
+    ...rows.map((r) => `| ${r.map(cell).join(" | ")} |`),
+    END,
+  ].join("\n");
+}
+
+/** The document with its tickets block replaced, or appended when absent. */
+export function withTickets(doc, block) {
+  const s = doc.indexOf(START);
+  const e = doc.indexOf(END);
+  if (s >= 0 && e > s) return doc.slice(0, s) + block + doc.slice(e + END.length);
+  return `${doc.replace(/\s*$/, "")}\n\n${block}\n`;
+}
+
+function arg(argv, flag) {
+  const i = argv.indexOf(flag);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const doc = arg(argv, "--doc");
+  const ledger = arg(argv, "--ledger");
+  const planFile = arg(argv, "--plan");
+  if (!doc || !ledger || !planFile) {
+    process.stderr.write(
+      "usage: analysis-tickets-writeback.mjs --doc FILE --ledger FILE --plan FILE\n",
+    );
+    process.exitCode = 64;
+    return;
+  }
+  const plan = JSON.parse(readFileSync(planFile, "utf8"));
+  const keys = keysFromLedger(readFileSync(ledger, "utf8"));
+  const before = readFileSync(doc, "utf8");
+  const after = withTickets(before, ticketsBlock(plan, keys));
+  if (after !== before) writeFileSync(doc, after);
+  process.stdout.write(`tickets: ${keys.size} key(s) in ${doc}\n`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/pipeline/scripts/build-references.mjs

@@ -13,6 +13,8 @@
 //
 //   build   (default)  state JSON  -> markdown table on stdout
 //   --check <doc.md>   state JSON + emitted doc -> coverage gate, exit 1 on drift
+//   --missing-panel    the sources the run could not read, as the quoted panel
+//                      at the top of the document; nothing when all were read
 //
 // Usage:
 //   node build-references.mjs state.json [--lang tr|en]
@@ -76,6 +78,7 @@ function rowsFrom(spec, lang) {
       type,
       cells: [cell(type), cell(source), cell(url), cell(ref), cell(role), access, cell(notes)],
       key: keyOf(url, source),
+      missing: String(access).startsWith(FAILED[lang]),
     });
   };
 
@@ -338,7 +341,7 @@ function main() {
   const statePath = argv[0];
   if (!statePath || statePath.startsWith("--")) {
     process.stderr.write(
-      "usage: build-references.mjs <state.json|-> [--lang tr|en] [--check <doc.md>]\n",
+      "usage: build-references.mjs <state.json|-> [--lang tr|en] [--check <doc.md>] [--missing-panel]\n",
     );
     process.exitCode = 2;
     return;
@@ -362,6 +365,16 @@ function main() {
     return;
   }
 
+  if (argv.includes("--missing-panel")) {
+    const missing = rowsFrom(spec, lang).filter((r) => r.missing);
+    if (missing.length) {
+      const title = lang === "tr" ? "> **Eksik girdiler:**" : "> **Missing inputs:**";
+      const items = missing.map((r) => `> - ${r.cells[0]} ${r.cells[1]}: ${r.cells[5]}`);
+      process.stdout.write(`${[title, ...items].join("\n")}\n`);
+    }
+    return;
+  }
+
   const docPath = argOf(argv, "--check");
   if (docPath) {
     const problems = check(spec, docPath, lang);