@mlmcps/ml-specs-mcp 1.0.0

package/scripts/lib/knowledge.mjs

@@ -0,0 +1,91 @@
+// The knowledge layer: standing constraints on disk, in docs/CONSTRAINTS.md.
+//
+// Pure Node, no dependencies. Writes one file, only when asked.
+//
+// Why a markdown file and not a database: this is read by people during spec
+// review far more often than by this code, and a change to what is in force
+// should diff in a pull request like any other change. A store only a machine
+// can read becomes a store nobody checks — which is worse than none, because it
+// looks like governance while enforcing nothing.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const BEGIN = '<!-- sdd:constraints -->';
+const END = '<!-- /sdd:constraints -->';
+const REFRESHED = '<!-- sdd:refreshed ';
+const LINE = /^-\s+`([A-Za-z0-9_.-]+)`\s+\[([^\]]*)\]\s+(.+)$/;
+
+const HEADER = `# Standing constraints
+
+Constraints in force while authoring any spec. Generated — change the source
+(the NFR table, or the incident that produced a lesson) rather than this file.
+
+`;
+
+export function read(path) {
+  if (!existsSync(path)) return [];
+  const body = readFileSync(path, 'utf8');
+  if (!body.includes(BEGIN)) return [];
+  const block = body.split(BEGIN)[1].split(END)[0];
+
+  const out = [];
+  for (const line of block.split('\n')) {
+    const m = LINE.exec(line.trim());
+    if (!m) continue;
+    const scope = m[2].split(',').map((s) => s.trim()).filter(Boolean);
+    out.push({ id: m[1], scope: scope.length ? scope : ['*'], text: m[3] });
+  }
+  return out;
+}
+
+/** Days since the file was last written, or null if it never was. */
+export function staleness(path, today = new Date()) {
+  if (!existsSync(path)) return null;
+  const m = readFileSync(path, 'utf8').match(new RegExp(`${REFRESHED}(\\d{4}-\\d{2}-\\d{2})`));
+  if (!m) return null;
+  const then = new Date(`${m[1]}T00:00:00Z`);
+  return Math.floor((today - then) / 86400000);
+}
+
+/**
+ * What a spec touching these repos inherits. A constraint scoped `*` applies
+ * everywhere; a spec that names no repo yet still inherits the estate-wide ones,
+ * which is the common case early in a spec's life.
+ */
+export function forRepos(constraints, repos = []) {
+  if (!repos.length) return constraints.filter((c) => c.scope.includes('*'));
+  return constraints.filter((c) => c.scope.includes('*') || repos.some((r) => c.scope.includes(r)));
+}
+
+/** Upsert by id. Returns the ids that actually changed, so a caller need not
+ *  claim a write that was a no-op. */
+export function write(path, incoming, today = new Date()) {
+  const existing = new Map(read(path).map((c) => [c.id, c]));
+  const changed = [];
+
+  for (const c of incoming) {
+    const prev = existing.get(c.id);
+    if (!prev || prev.text !== c.text || prev.scope.join() !== c.scope.join()) changed.push(c.id);
+    existing.set(c.id, c);
+  }
+
+  const rows = [...existing.values()].sort((a, b) => a.id.localeCompare(b.id));
+  const lines = rows.length
+    ? rows.map((c) => `- \`${c.id}\` [${c.scope.join(', ')}] ${c.text}`)
+    : ['_none — no NFR has been compiled and no incident has produced a lesson._'];
+
+  const stamp = today.toISOString().slice(0, 10);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${HEADER}${REFRESHED}${stamp} -->\n\n${BEGIN}\n${lines.join('\n')}\n${END}\n`);
+  return changed;
+}
+
+/** The block stamped into a new or briefed spec, so constraints are in front of
+ *  whoever writes it rather than in a file they are trusted to have read. */
+export function renderForSpec(constraints) {
+  if (!constraints.length) return '';
+  return ['## Constraints in force', '',
+          '_Read while authoring. Generated from the knowledge layer._', '',
+          ...constraints.map((c) => `- **${c.id}** — ${c.text}`)].join('\n') + '\n';
+}

package/scripts/lib/nfr.mjs

@@ -0,0 +1,119 @@
+// Non-functional requirements: reading them, and compiling them into the two
+// things that actually enforce them.
+//
+// Pure Node, no dependencies. Read-only; the caller decides what to write.
+//
+// Why this exists: NFRs enter a project at the top — "the API shall be
+// performant" — and then vanish. They do not decompose into user stories, so a
+// story breakdown flattens them into prose that nothing checks. They decompose
+// into exactly two things: a standing constraint read while authoring every
+// spec, and a blocking pipeline gate. `compile` produces both or throws, so an
+// NFR cannot be admitted and then quietly lost.
+
+const TOOL_FOR = {
+  performance: 'load',
+  security: 'sast',
+  availability: 'policy',
+  compliance: 'policy',
+};
+
+export const NFR_KINDS = Object.keys(TOOL_FOR);
+const OPERATORS = ['<', '<=', '>', '>=', '=='];
+
+/**
+ * An NFR without a machine-checkable threshold is a wish. Refusing it here is
+ * the whole point: a wish gets flattened into a feature spec and lost, and
+ * nobody notices until the load test that was never written would have caught it.
+ */
+export function compile(nfr) {
+  const t = nfr.threshold;
+  if (!t || !Number.isFinite(Number(t.value)) || !t.metric) {
+    throw new Error(
+      `${nfr.id} has no machine-checkable threshold, so it cannot become a pipeline gate. ` +
+      `Give it metric/operator/value, or drop it — an NFR nothing can fail is not a requirement.`);
+  }
+  if (!OPERATORS.includes(t.operator)) {
+    throw new Error(`${nfr.id} has operator "${t.operator}"; expected one of ${OPERATORS.join(' ')}`);
+  }
+  const tool = TOOL_FOR[nfr.kind];
+  if (!tool) {
+    throw new Error(`${nfr.id} has kind "${nfr.kind}"; expected one of ${NFR_KINDS.join(', ')}`);
+  }
+
+  const assertion = `${t.metric} ${t.operator} ${t.value}${t.unit ?? ''}`;
+  return {
+    constraint: { id: nfr.id, scope: nfr.appliesTo?.length ? nfr.appliesTo : ['*'],
+                  text: `${nfr.statement} (${assertion})` },
+    gate: { nfr: nfr.id, tool, metric: t.metric, operator: t.operator,
+            value: Number(t.value), unit: t.unit ?? '', assertion, blocking: true },
+  };
+}
+
+/**
+ * The guard that keeps this honest: an NFR id must never appear inside an
+ * acceptance criterion. That is the exact failure mode — the NFR flattened into
+ * a feature spec, where it stops being enforced and starts being a sentence.
+ */
+export function findFlattened(specs) {
+  const hits = [];
+  for (const spec of specs) {
+    for (const ac of spec.criteria ?? []) {
+      for (const id of spec.nfrs ?? []) {
+        if (ac.text.includes(id)) hits.push({ spec: spec.id, criterion: ac.id, nfr: id, text: ac.text });
+      }
+    }
+  }
+  return hits;
+}
+
+/** The gate block a pipeline consumes. */
+export const toPipelineYaml = (gates) =>
+  gates.length === 0
+    ? '# no NFR gates compiled\n'
+    : gates.map((g) =>
+        `- gate: ${g.nfr}\n  tool: ${g.tool}\n  assert: ${g.assertion}\n  blocking: true`).join('\n');
+
+// --- reading -----------------------------------------------------------------
+// A markdown table, to match docs/ESTATE.md — this file is read by people during
+// spec review far more often than by this code, and a format only a machine can
+// read becomes a format nobody checks.
+
+const ROW = /^\|(.+)\|\s*$/;
+const SEP = /^\|[\s:|-]+\|\s*$/;
+const clean = (v) => (v ?? '').replace(/[`*]/g, '').trim();
+const PLACEHOLDER = /^(<.*>|_TBD_|—|-|)$/;
+
+export function parseNfrMarkdown(text) {
+  const out = [];
+  let header = null;
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (SEP.test(trimmed)) continue;
+    const m = ROW.exec(trimmed);
+    if (!m) { header = null; continue; }
+    const cells = m[1].split('|').map(clean);
+
+    if (!header) {
+      const lower = cells.map((c) => c.toLowerCase());
+      header = lower.includes('nfr') && lower.some((c) => c.includes('metric')) ? lower : null;
+      continue;
+    }
+
+    const at = (name) => {
+      const i = header.findIndex((h) => h.includes(name));
+      return i === -1 ? '' : (cells[i] ?? '');
+    };
+    const id = at('nfr');
+    if (!id || PLACEHOLDER.test(id)) continue;
+
+    out.push({
+      id,
+      kind: (at('kind') || 'compliance').toLowerCase(),
+      statement: at('statement'),
+      threshold: { metric: at('metric'), operator: at('op') || '<',
+                   value: Number(at('value')), unit: at('unit') },
+      appliesTo: at('applies').split(',').map(clean).filter((v) => v && !PLACEHOLDER.test(v)),
+    });
+  }
+  return out;
+}

package/scripts/lib/policy.mjs

@@ -0,0 +1,114 @@
+// The branch policy that makes a pipeline into a gate.
+//
+// A build that runs and reports changes nothing. The load-bearing artifact is
+// the POLICY: build validation, scoped to the protected branch, blocking.
+//
+// The audit half matters more than the install half. A gate quietly demoted to
+// advisory — to unblock a release, reasonably, on a Friday — is how this kind of
+// governance dies: nothing breaks, no test fails, and the first anyone notices
+// is an audit months later.
+//
+// Pure Node, no dependencies. Every call goes through an injected transport.
+
+import { basicAuth, request } from './http.mjs';
+
+/** ADO's well-known policy type for "Build validation". */
+export const BUILD_VALIDATION_TYPE = '0609b952-1397-4640-95ec-e00a01b2c241';
+
+export function adoPolicy({ org, project, pat, apiVersion = '7.1', transport = request }) {
+  const base = `https://dev.azure.com/${org}/${encodeURIComponent(project)}/_apis`;
+  const headers = { Authorization: basicAuth('', pat) };
+
+  return {
+    tool: 'ado-repos',
+
+    async install(repo, branch, buildRef) {
+      await transport(`${base}/policy/configurations?api-version=${apiVersion}`, {
+        method: 'POST', headers,
+        body: {
+          isEnabled: true,
+          isBlocking: true,          // the whole point; there is no flag to turn this off here
+          type: { id: BUILD_VALIDATION_TYPE },
+          settings: {
+            buildDefinitionId: /^\d+$/.test(String(buildRef)) ? Number(buildRef) : buildRef,
+            displayName: 'SDD spec gate',
+            manualQueueOnly: false,
+            queueOnSourceUpdateOnly: true,
+            validDuration: 720,
+            scope: [{ refName: `refs/heads/${branch}`, matchKind: 'Exact', repositoryId: repo }],
+          },
+        },
+      });
+      return { repo, branch, tool: 'ado-repos', present: true, blocking: true, findings: [] };
+    },
+
+    async audit(repo, branch) {
+      const res = await transport(
+        `${base}/policy/configurations?repositoryId=${encodeURIComponent(repo)}` +
+        `&refName=refs/heads/${branch}&api-version=${apiVersion}`, { headers });
+
+      const builds = (res.value ?? []).filter((c) => c.type?.id === BUILD_VALIDATION_TYPE);
+      if (!builds.length) {
+        return { repo, branch, tool: 'ado-repos', present: false, blocking: false,
+                 findings: [{ severity: 'blocker', message: `no build-validation policy on refs/heads/${branch}` }] };
+      }
+
+      const p = builds[0];
+      const s = p.settings ?? {};
+      const findings = [];
+      if (!p.isEnabled) findings.push({ severity: 'blocker', message: 'policy exists but is disabled' });
+      if (!p.isBlocking) findings.push({ severity: 'blocker', message: 'policy is advisory — the build reports but cannot fail the merge' });
+      if (s.manualQueueOnly) findings.push({ severity: 'blocker', message: 'manualQueueOnly is set — the gate only runs if someone remembers' });
+      if (s.queueOnSourceUpdateOnly === false) findings.push({ severity: 'warning', message: 'does not re-run on source update; a later push is ungated' });
+      if (builds.length > 1) findings.push({ severity: 'warning', message: `${builds.length} build policies on this branch — which one is the gate?` });
+
+      return { repo, branch, tool: 'ado-repos', present: true,
+               blocking: Boolean(p.isBlocking && p.isEnabled), findings };
+    },
+  };
+}
+
+export function githubPolicy({ owner, token, apiBase = 'https://api.github.com', transport = request }) {
+  const headers = { Authorization: `Bearer ${token}`, 'X-GitHub-Api-Version': '2022-11-28' };
+  const url = (repo, branch) => `${apiBase}/repos/${owner}/${repo}/branches/${encodeURIComponent(branch)}/protection`;
+
+  return {
+    tool: 'github',
+
+    async install(repo, branch, buildRef) {
+      await transport(url(repo, branch), { method: 'PUT', headers, body: {
+        required_status_checks: { strict: true, contexts: [buildRef] },
+        enforce_admins: true,
+        required_pull_request_reviews: { required_approving_review_count: 1 },
+        restrictions: null,
+      } });
+      return { repo, branch, tool: 'github', present: true, blocking: true, findings: [] };
+    },
+
+    async audit(repo, branch) {
+      const raw = await transport(url(repo, branch), { headers });
+      const contexts = raw.required_status_checks?.contexts ?? [];
+      if (!contexts.length) {
+        return { repo, branch, tool: 'github', present: false, blocking: false,
+                 findings: [{ severity: 'blocker', message: `no required status check on ${branch}` }] };
+      }
+      const findings = [];
+      if (!raw.required_status_checks?.strict) {
+        findings.push({ severity: 'warning', message: 'strict is off — a stale branch can merge without re-running the gate' });
+      }
+      // On GitHub an admin bypass is the equivalent of an advisory policy.
+      if (!raw.enforce_admins?.enabled) {
+        findings.push({ severity: 'blocker', message: 'enforce_admins is off — administrators can merge past the gate' });
+      }
+      return { repo, branch, tool: 'github', present: true,
+               blocking: !findings.some((f) => f.severity === 'blocker'), findings };
+    },
+  };
+}
+
+export const auditOk = (a) => a.present && a.blocking && !a.findings.some((f) => f.severity === 'blocker');
+
+export const auditSummary = (a) =>
+  !a.present ? 'no spec gate on this branch'
+  : !a.blocking ? 'spec gate is ADVISORY — it cannot fail the merge, so it is not a gate'
+  : 'spec gate present and blocking';

package/scripts/lib/scm.mjs

@@ -0,0 +1,189 @@
+// Source control: branches and pull requests, for ADO Repos and GitHub.
+//
+// Deliberately separate from lib/tracker.mjs. A work item and a pull request are
+// different objects owned by different systems, and they diverge under exactly
+// the load this exists for: one spec fans out to N repositories but links to ONE
+// work item, so the cardinality differs. GitHub-plus-Jira is also an ordinary
+// combination that a merged interface could not express.
+//
+// GitHub ships alongside ADO because these customers migrate there for code
+// while keeping Boards or Jira for work — the two boundaries move independently.
+//
+// Pure Node, no dependencies. Every call goes through an injected transport.
+
+import { basicAuth, request } from './http.mjs';
+import { branchName, prTitle, keyFrom, specId, testCaseId } from './trace.mjs';
+
+const EMPTY_SHA = '0'.repeat(40);
+
+// --- Azure DevOps Repos ------------------------------------------------------
+
+export function adoRepos({ org, project, pat, apiVersion = '7.1', transport = request }) {
+  const repoBase = (repo) =>
+    `https://dev.azure.com/${org}/${encodeURIComponent(project)}/_apis/git/repositories/${encodeURIComponent(repo)}`;
+  const headers = { Authorization: basicAuth('', pat) };
+
+  return {
+    tool: 'ado-repos',
+
+    async defaultBranchSha(repo, branch = 'main') {
+      const res = await transport(`${repoBase(repo)}/refs?filter=heads/${branch}&api-version=${apiVersion}`, { headers });
+      const refs = res.value ?? [];
+      if (!refs.length) throw new Error(`ADO: ${repo} has no branch ${branch}`);
+      return String(refs[0].objectId);
+    },
+
+    async createBranch(repo, name, fromSha) {
+      // ADO has no "create branch" call — a branch is a ref updated from zeros.
+      await transport(`${repoBase(repo)}/refs?api-version=${apiVersion}`, {
+        method: 'POST', headers,
+        body: [{ name: `refs/heads/${name}`, oldObjectId: EMPTY_SHA, newObjectId: fromSha }],
+      });
+      return { repo, name, sha: fromSha };
+    },
+
+    async openPullRequest(repo, { source, target, title, body }) {
+      const raw = await transport(`${repoBase(repo)}/pullrequests?api-version=${apiVersion}`, {
+        method: 'POST', headers,
+        body: { sourceRefName: `refs/heads/${source}`, targetRefName: `refs/heads/${target}`,
+                title, description: body },
+      });
+      const id = String(raw.pullRequestId ?? '');
+      return { repo, id, title, source, target,
+               url: `https://dev.azure.com/${org}/${encodeURIComponent(project)}/_git/${encodeURIComponent(repo)}/pullrequest/${id}` };
+    },
+
+    async findPullRequests(repo, key) {
+      const res = await transport(
+        `${repoBase(repo)}/pullrequests?searchCriteria.status=all&api-version=${apiVersion}`, { headers });
+      return (res.value ?? [])
+        .filter((pr) => keyFrom('prTitle', pr.title ?? '') === key)
+        .map((pr) => ({ repo, id: String(pr.pullRequestId), title: pr.title,
+          source: String(pr.sourceRefName ?? '').replace(/^refs\/heads\//, ''),
+          target: String(pr.targetRefName ?? '').replace(/^refs\/heads\//, ''),
+          url: `https://dev.azure.com/${org}/_git/${encodeURIComponent(repo)}/pullrequest/${pr.pullRequestId}` }));
+    },
+  };
+}
+
+// --- GitHub ------------------------------------------------------------------
+
+export function github({ owner, token, apiBase = 'https://api.github.com', transport = request }) {
+  const headers = { Authorization: `Bearer ${token}`, 'X-GitHub-Api-Version': '2022-11-28' };
+  const url = (repo, path) => `${apiBase}/repos/${owner}/${repo}${path}`;
+
+  return {
+    tool: 'github',
+
+    async defaultBranchSha(repo, branch = 'main') {
+      const raw = await transport(url(repo, `/git/ref/heads/${branch}`), { headers });
+      return String(raw.object.sha);
+    },
+
+    async createBranch(repo, name, fromSha) {
+      await transport(url(repo, '/git/refs'), {
+        method: 'POST', headers, body: { ref: `refs/heads/${name}`, sha: fromSha } });
+      return { repo, name, sha: fromSha };
+    },
+
+    async openPullRequest(repo, { source, target, title, body }) {
+      // The shape difference from ADO: bare head/base, and it is called `body`.
+      const raw = await transport(url(repo, '/pulls'), {
+        method: 'POST', headers, body: { title, head: source, base: target, body } });
+      return { repo, id: String(raw.number ?? ''), title, source, target,
+               url: String(raw.html_url ?? `https://github.com/${owner}/${repo}/pulls`) };
+    },
+
+    async findPullRequests(repo, key) {
+      const raw = await transport(url(repo, '/pulls?state=all&per_page=100'), { headers });
+      return (raw ?? [])
+        .filter((pr) => keyFrom('prTitle', pr.title ?? '') === key)
+        .map((pr) => ({ repo, id: String(pr.number), title: pr.title,
+          source: pr.head?.ref ?? '', target: pr.base?.ref ?? '', url: pr.html_url ?? '' }));
+    },
+  };
+}
+
+// --- the governed path -------------------------------------------------------
+
+/** Reads only. Frozen, so the write methods are absent and stay absent. */
+export const readOnlyScm = (scm) => Object.freeze({
+  tool: scm.tool,
+  defaultBranchSha: (repo, branch) => scm.defaultBranchSha(repo, branch),
+  findPullRequests: (repo, key) => scm.findPullRequests(repo, key),
+});
+
+/**
+ * The only way a branch or pull request gets created. A pull request that cannot
+ * be traced back to an approved contract is exactly what this exists to prevent,
+ * so it is refused here rather than reported later.
+ */
+export function governedScm(scm, { target = 'main' } = {}) {
+  return {
+    tool: scm.tool,
+    async openFor(spec, repo, body) {
+      if (!spec.status || spec.status === 'Draft') {
+        throw new Error(`spec ${spec.id} is ${spec.status ?? 'unknown'}; no branch is cut before the approval gate`);
+      }
+      const name = spec.branch ?? branchName(spec.id, spec.title);
+      const title = prTitle(spec.id, spec.title);
+      // Both are derived, so these can only fail if a derivation changed without
+      // its parser changing with it.
+      if (keyFrom('branch', name) !== spec.id) throw new Error(`branch "${name}" does not carry spec ${spec.id}`);
+      if (keyFrom('prTitle', title) !== spec.id) throw new Error(`title "${title}" does not carry spec ${spec.id}`);
+
+      const sha = await scm.defaultBranchSha(repo, target);
+      const branch = await scm.createBranch(repo, name, sha);
+      const pr = await scm.openPullRequest(repo, { source: name, target, title, body });
+      return { branch, pr };
+    },
+  };
+}
+
+/**
+ * The pull request body. It carries the whole chain so a reviewer never has to
+ * hunt, and the criteria arrive as a checklist — their job is to confirm each
+ * one, not to infer what the change was for.
+ */
+export function pullRequestBody(spec, reason, { constraints = [] } = {}) {
+  const branch = spec.branch ?? branchName(spec.id, spec.title);
+  const lines = [
+    `## ${specId(spec.id)} — ${spec.title}`, '',
+    `**Why this repo:** ${reason}`,
+    `**Spec:** \`${spec.file}\` (status: ${spec.status})`,
+  ];
+  if (spec.ticket) lines.push(`**Ticket:** ${spec.ticket}`);
+  if (spec.repos?.length) lines.push(`**Fan-out:** ${spec.repos.join(', ')}`);
+  if (spec.nfrs?.length) lines.push(`**NFRs in force:** ${spec.nfrs.join(', ')}`);
+
+  lines.push('', '## Acceptance criteria', '');
+  lines.push(...((spec.criteria ?? []).length
+    ? spec.criteria.map((ac) => `- [${ac.checked ? 'x' : ' '}] ${ac.id} (${testCaseId(spec.id, ac.ordinal)}) — ${ac.text}`)
+    : ['_none — this spec should not have been approved._']));
+
+  if (constraints.length) {
+    lines.push('', '## Constraints in force', '', ...constraints.map((c) => `- **${c.id}** — ${c.text}`));
+  }
+
+  lines.push('', '---',
+    `Every branch in this fan-out is \`${branch}\`. Same key, so these pull requests are one change.`);
+  return lines.join('\n');
+}
+
+/** Which repos this change reaches: those named on the spec, plus those the
+ *  estate index says consume what it touches. */
+export function fanOutTargets(spec, impact = null) {
+  const targets = new Map();
+  for (const repo of spec.repos ?? []) targets.set(repo, 'named on the spec');
+  for (const d of impact?.directlyAffected ?? []) {
+    if (!targets.has(d.repo)) targets.set(d.repo, `consumes ${d.via.join(', ')}`);
+  }
+  for (const t of impact?.transitivelyAffected ?? []) {
+    if (!targets.has(t.repo)) targets.set(t.repo, `one hop: consumes ${t.via.join(', ')}`);
+  }
+  return [...targets].map(([repo, reason]) => ({
+    repo, reason,
+    branch: spec.branch ?? branchName(spec.id, spec.title),
+    title: prTitle(spec.id, spec.title),
+  }));
+}