@rsaglobaltech/specgate 0.8.1

package/dist/scripts/alm/cli.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * `alm` — keep the traceability matrix and the enterprise ALM
+ * (Jira / Azure Boards) in sync.
+ *
+ * Usage:
+ *   specgate alm sync   [--project-dir <dir>] [--dry-run]
+ *   specgate alm pull   [--label <name>] [--project-dir <dir>] [--dry-run]
+ *   specgate alm link   <REQ-id> <issue-key> [--project-dir <dir>]
+ *   specgate alm status [--project-dir <dir>]
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const project_root_1 = require("../lib/project-root");
+const core_1 = require("./core");
+const clients_1 = require("./clients");
+const diagnostics_1 = require("../lib/diagnostics");
+const PullCommand_1 = require("../cli/commands/alm/PullCommand");
+function logInfo(msg) {
+    process.stdout.write(`ℹ️ [INFO] ${msg}\n`);
+}
+function logWarn(msg) {
+    process.stdout.write(`⚠️ [WARN] ${msg}\n`);
+}
+function logError(msg) {
+    process.stderr.write(`❌ [ERROR] ${msg}\n`);
+}
+function usage() {
+    process.stdout.write("Usage:\n" +
+        "  specgate alm sync   [--project-dir <dir>] [--dry-run]\n" +
+        "  specgate alm link   <REQ-id> <issue-key> [--project-dir <dir>]\n" +
+        "  specgate alm status [--project-dir <dir>]\n" +
+        "  specgate alm pull   [--label <name>] [--project-dir <dir>] [--dry-run]\n\n" +
+        "sync   Creates an ALM issue for every unlinked REQ, closes issues whose REQ\n" +
+        "       is Implemented, and reports drift (issue done, REQ still open).\n" +
+        "link   Manually map an existing issue to a requirement.\n" +
+        "status Print the current REQ ↔ issue mapping without network access.\n" +
+        "pull   Open a change per labelled issue. The scenario is left unwritten:\n" +
+        "       a ticket carries no acceptance criterion, so that part is yours.\n\n" +
+        "Configuration: alm.config.yaml at the project root (provider, base_url,\n" +
+        "project_key, token_env). Tokens come from the environment, never the file.\n");
+}
+function parseCommon(argv) {
+    const opts = { projectDir: ".", dryRun: false, rest: [] };
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--project-dir" && argv[i + 1])
+            opts.projectDir = argv[++i];
+        else if (argv[i] === "--dry-run")
+            opts.dryRun = true;
+        else if (argv[i] === "--help" || argv[i] === "-h") {
+            usage();
+            process.exit(0);
+        }
+        else
+            opts.rest.push(argv[i]);
+    }
+    return opts;
+}
+async function main() {
+    let argv = process.argv.slice(2);
+    if (argv[0] === "alm")
+        argv = argv.slice(1);
+    const sub = argv[0];
+    const opts = parseCommon(argv.slice(1));
+    let projectDir;
+    try {
+        projectDir = (0, project_root_1.resolveProjectDir)(opts.projectDir, { requireSentinel: true });
+    }
+    catch (err) {
+        logError(err.message);
+        process.exit(2);
+    }
+    if (sub === "status") {
+        const map = (0, core_1.readAlmMap)(projectDir);
+        const reqs = (0, core_1.extractRequirements)(projectDir);
+        for (const req of reqs) {
+            const linked = map[req.id];
+            process.stdout.write(`${req.id}  [${req.status}]  →  ${linked ? linked.issue : "(unlinked)"}\n`);
+        }
+        process.exit(0);
+    }
+    if (sub === "link") {
+        const [reqId, issueKey] = opts.rest;
+        if (!reqId || !issueKey) {
+            logError("alm link expects: <REQ-id> <issue-key>");
+            usage();
+            process.exit(2);
+        }
+        if (!/^REQ-\d+$/.test(reqId)) {
+            logError(`'${reqId}' is not a REQ id (expected REQ-NNN).`);
+            process.exit(2);
+        }
+        const map = (0, core_1.readAlmMap)(projectDir);
+        map[reqId] = { issue: issueKey, url: null };
+        const written = (0, core_1.writeAlmMap)(projectDir, map, false);
+        logInfo(`Linked ${reqId} → ${issueKey} (${written}). Commit the mapping file.`);
+        process.exit(0);
+    }
+    if (sub === "sync") {
+        try {
+            const cfg = (0, core_1.readAlmConfig)(projectDir);
+            // Keys nothing reads are reported before the first request, not after a
+            // sync that quietly ignored half the file.
+            const configFindings = (0, core_1.lintAlmConfig)(cfg, projectDir);
+            if (configFindings.length > 0)
+                (0, diagnostics_1.printDiagnostics)(configFindings, process.stdout);
+            const client = (0, clients_1.makeClient)(cfg, undefined, projectDir);
+            const map = (0, core_1.readAlmMap)(projectDir);
+            const reqs = (0, core_1.extractRequirements)(projectDir);
+            const actions = await (0, core_1.syncRequirements)(reqs, map, client, { dryRun: opts.dryRun });
+            let drift = 0;
+            for (const a of actions) {
+                if (a.action === "drift") {
+                    drift++;
+                    logWarn(`DRIFT ${a.req}: ${a.detail}`);
+                }
+                else if (a.action !== "in-sync") {
+                    logInfo(`${a.action} ${a.req}${a.issue ? ` → ${a.issue}` : ""}`);
+                }
+            }
+            if (!opts.dryRun)
+                (0, core_1.writeAlmMap)(projectDir, map, false);
+            const summary = actions.reduce((acc, a) => {
+                acc[a.action] = (acc[a.action] || 0) + 1;
+                return acc;
+            }, {});
+            logInfo(`Summary: ${JSON.stringify(summary)}`);
+            if (drift > 0) {
+                logWarn(`${drift} drift finding(s) — reconcile the matrix or the board.`);
+                process.exit(1);
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            logError(err.message);
+            process.exit(1);
+        }
+    }
+    if (sub === "pull") {
+        // Implemented outside `scripts/alm/` on purpose: ADR-0021 forbids this
+        // subsystem from writing the spec tree, and a pull has to produce files.
+        // The ALM half reads the board; the change lifecycle writes the proposal.
+        await (0, PullCommand_1.main)(argv.slice(1));
+        return;
+    }
+    logError(`Unknown alm sub-command: ${sub || "(none)"}. Expected: sync, link, status, pull`);
+    usage();
+    process.exit(2);
+}
+main().catch((err) => {
+    logError(err && err.message ? err.message : String(err));
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/scripts/alm/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../scripts/alm/cli.ts"],"names":[],"mappings":"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"}

package/dist/scripts/alm/clients.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.githubClient = exports.azureClient = exports.jiraClient = void 0;
+exports.makeClient = makeClient;
+const providers_1 = require("./providers");
+/**
+ * Client construction, resolved through the provider registry.
+ *
+ * This file used to *be* the two connectors, selected by a ternary on
+ * `cfg.provider`. The connectors now live in `providers/` behind the
+ * `AlmProvider` port (see `port.ts` for why), and what is left here is the
+ * lookup plus the names the rest of the tree already imports.
+ *
+ * A client carries its provider's capabilities, because the core has to know
+ * what an ALM cannot do — `syncRequirements` reports a requirement it cannot
+ * close rather than throwing — and the client is the only thing it holds.
+ */
+function makeClient(cfg, fetchImpl, projectDir) {
+    return (0, providers_1.getProvider)(cfg.provider, projectDir).create(cfg, fetchImpl);
+}
+// The two provider-specific factories, kept under the names they have always
+// had. Callers that want one connector directly — the tests do — should not
+// have to know the registry exists.
+const jiraClient = (cfg, fetchImpl) => (0, providers_1.getProvider)("jira").create(cfg, fetchImpl);
+exports.jiraClient = jiraClient;
+const azureClient = (cfg, fetchImpl) => (0, providers_1.getProvider)("azure").create(cfg, fetchImpl);
+exports.azureClient = azureClient;
+const githubClient = (cfg, fetchImpl) => (0, providers_1.getProvider)("github").create(cfg, fetchImpl);
+exports.githubClient = githubClient;
+//# sourceMappingURL=clients.js.map

package/dist/scripts/alm/clients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.js","sourceRoot":"","sources":["../../../scripts/alm/clients.ts"],"names":[],"mappings":";;;AAeA,gCAEC;AAjBD,2CAA0C;AAG1C;;;;;;;;;;;GAWG;AACH,SAAgB,UAAU,CAAC,GAAc,EAAE,SAAqB,EAAE,UAAmB;IACnF,OAAO,IAAA,uBAAW,EAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;AACtE,CAAC;AAED,6EAA6E;AAC7E,4EAA4E;AAC5E,oCAAoC;AAC7B,MAAM,UAAU,GAAG,CAAC,GAAc,EAAE,SAAqB,EAAa,EAAE,CAC7E,IAAA,uBAAW,EAAC,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;AADhC,QAAA,UAAU,cACsB;AAEtC,MAAM,WAAW,GAAG,CAAC,GAAc,EAAE,SAAqB,EAAa,EAAE,CAC9E,IAAA,uBAAW,EAAC,OAAO,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;AADjC,QAAA,WAAW,eACsB;AAEvC,MAAM,YAAY,GAAG,CAAC,GAAc,EAAE,SAAqB,EAAa,EAAE,CAC/E,IAAA,uBAAW,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;AADlC,QAAA,YAAY,gBACsB"}

package/dist/scripts/alm/core.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * ALM (Jira / Azure Boards) synchronisation core — provider-agnostic.
+ *
+ * Enterprise requirements live in the ALM, not in markdown; without a link
+ * the traceability matrix and the board drift apart (friction F7). This
+ * module keeps them honest:
+ *
+ *   - every REQ in the traceability matrix maps to exactly one ALM issue
+ *     (mapping persisted in .specops/alm-map.json, committed);
+ *   - REQs without an issue get one created;
+ *   - a REQ reaching Implemented/Verified/Released transitions its issue
+ *     to Done;
+ *   - an issue closed while its REQ is still open is reported as DRIFT.
+ *
+ * All network access goes through an injected `client` so the logic is
+ * fully testable offline: { createIssue, getIssueStatus, closeIssue }.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DONE_STATUSES = exports.CONFIG_FILENAME = exports.MAP_RELPATH = void 0;
+exports.readAlmConfig = readAlmConfig;
+exports.lintAlmConfig = lintAlmConfig;
+exports.readAlmMap = readAlmMap;
+exports.writeAlmMap = writeAlmMap;
+exports.extractRequirements = extractRequirements;
+exports.syncRequirements = syncRequirements;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const YamlLite_1 = require("../../packages/core/src/domain/YamlLite");
+const diagnostics_1 = require("../lib/diagnostics");
+const providers_1 = require("./providers");
+const port_1 = require("./port");
+exports.MAP_RELPATH = path.join(".specops", "alm-map.json");
+exports.CONFIG_FILENAME = "alm.config.yaml";
+/** Matrix statuses that mean "this requirement is delivered". */
+exports.DONE_STATUSES = new Set(["Implemented", "Verified", "Released"]);
+// ── Config ────────────────────────────────────────────────────────────────────
+/**
+ * Read alm.config.yaml. Tokens are NEVER stored in the file — only the
+ * name of the environment variable that holds them.
+ */
+function readAlmConfig(projectDir) {
+    const cfgPath = path.join(projectDir, exports.CONFIG_FILENAME);
+    if (!fs.existsSync(cfgPath)) {
+        // Built from the declarations rather than written out: a hand-kept example
+        // teaches whichever provider it was written for. It used to show
+        // `project_key`, which GitHub does not read at all — the same key its own
+        // linter now warns about.
+        const perProvider = providers_1.PROVIDERS.map((p) => `  # ${p.label}\n` +
+            `  provider: ${p.id}\n` +
+            [...p.config.required].map((k) => `  ${k}: …`).join("\n") +
+            (p.config.optional.length > 0 ? `\n  # optional: ${[...p.config.optional].join(", ")}` : "")).join("\n\n");
+        throw new Error(`${exports.CONFIG_FILENAME} not found in ${projectDir}.\n` +
+            "Fix: create it with `alm_version: 1` and one of:\n\n" +
+            `${perProvider}\n\n` +
+            "Credentials are never in this file: `token_env` names the environment " +
+            "variable that holds the token.");
+    }
+    // The parser cannot know this document's shape; the port declares it, so the
+    // cast happens once, here, at the file boundary.
+    const cfg = ((0, YamlLite_1.parseYamlLite)(fs.readFileSync(cfgPath, "utf8")) || {});
+    if (!cfg.provider)
+        throw new Error(`${exports.CONFIG_FILENAME}: missing required key 'provider'.`);
+    // Which keys are required is the provider's business, not this function's.
+    // Asking every provider for the same four was how a Jira config with no
+    // `user_env` passed here and failed at network time instead.
+    const provider = (0, providers_1.getProvider)(cfg.provider, projectDir);
+    for (const key of provider.config.required) {
+        if (!cfg[key]) {
+            throw new Error(`${exports.CONFIG_FILENAME}: missing required key '${key}' for provider '${provider.id}'.\n` +
+                `Fix: add it. ${provider.label} requires: ${provider.config.required.join(", ")}.`);
+        }
+    }
+    return cfg;
+}
+/**
+ * Report the keys in a config that nothing will read.
+ *
+ * `harness.config.yaml` rejects an unknown key outright, on the grounds that a
+ * key nobody reads is worse than a missing one because the file looks
+ * configured. The same reasoning applies here, but this file predates the
+ * check and rejecting outright would break a working pipeline over a stray
+ * line — so it warns, and says which provider *would* have read the key. That
+ * second half is the useful part: `done_state` is real, and doing nothing on
+ * a Jira project is exactly the failure this reports.
+ *
+ * @returns {object[]} diagnostics, empty when every key is read
+ */
+function lintAlmConfig(cfg, projectDir) {
+    const provider = (0, providers_1.getProvider)(cfg.provider, projectDir);
+    const read = new Set([
+        ...port_1.CORE_CONFIG_KEYS,
+        ...provider.config.required,
+        ...provider.config.optional,
+    ]);
+    const diagnostics = [];
+    for (const key of Object.keys(cfg)) {
+        if (read.has(key))
+            continue;
+        const alsoIn = providers_1.PROVIDERS.filter((p) => p.id !== provider.id && [...p.config.required, ...p.config.optional].includes(key)).map((p) => p.id);
+        diagnostics.push((0, diagnostics_1.warning)("alm_config_unread_key", alsoIn.length > 0
+            ? `'${key}' is read by ${alsoIn.join(", ")}, not by ${provider.id} — it does nothing here.`
+            : `'${key}' is read by no ALM provider.`, {
+            target: key,
+            file: exports.CONFIG_FILENAME,
+            fix: alsoIn.length > 0
+                ? `Remove '${key}', or switch provider to ${alsoIn[0]} if that is what you meant.`
+                : `Remove '${key}'. ${provider.label} reads: ${[...read].sort().join(", ")}.`,
+        }));
+    }
+    return diagnostics;
+}
+// ── Mapping file ──────────────────────────────────────────────────────────────
+function readAlmMap(projectDir) {
+    const mapPath = path.join(projectDir, exports.MAP_RELPATH);
+    if (!fs.existsSync(mapPath))
+        return {};
+    return JSON.parse(fs.readFileSync(mapPath, "utf8"));
+}
+function writeAlmMap(projectDir, map, dryRun) {
+    const mapPath = path.join(projectDir, exports.MAP_RELPATH);
+    if (dryRun)
+        return mapPath;
+    fs.mkdirSync(path.dirname(mapPath), { recursive: true });
+    fs.writeFileSync(mapPath, `${JSON.stringify(map, null, 2)}\n`, "utf8");
+    return mapPath;
+}
+// ── Requirement extraction ────────────────────────────────────────────────────
+/**
+ * Read REQ ids + aggregated status from the traceability matrix, and their
+ * titles from spec.md. A REQ is "done" when every one of its rows carries a
+ * done status.
+ * @returns Array<{ id, title, status: "done"|"open" }>
+ */
+function extractRequirements(projectDir) {
+    const tracePath = path.join(projectDir, "docs", "specs", "traceability.md");
+    if (!fs.existsSync(tracePath)) {
+        throw new Error(`No traceability matrix at ${tracePath} — run adopt/init first.`);
+    }
+    const spec = fs.existsSync(path.join(projectDir, "spec.md"))
+        ? fs.readFileSync(path.join(projectDir, "spec.md"), "utf8")
+        : "";
+    const titles = {};
+    for (const m of spec.matchAll(/^##\s+(REQ-\d+)\s*[—-]\s*(.+)$/gm)) {
+        titles[m[1]] = m[2].trim();
+    }
+    const rowsByReq = new Map();
+    for (const line of fs.readFileSync(tracePath, "utf8").split("\n")) {
+        if (!line.trim().startsWith("|") || line.includes("---"))
+            continue;
+        const cells = line.split("|").map((c) => c.trim());
+        const req = cells.find((c) => /^REQ-\d+$/.test(c));
+        if (!req)
+            continue;
+        const status = cells[cells.length - 2] || "";
+        if (!rowsByReq.has(req))
+            rowsByReq.set(req, []);
+        rowsByReq.get(req).push(status);
+    }
+    return [...rowsByReq.entries()].map(([id, statuses]) => ({
+        id,
+        title: titles[id] || id,
+        status: statuses.length > 0 && statuses.every((s) => exports.DONE_STATUSES.has(s)) ? "done" : "open",
+    }));
+}
+// ── Sync ──────────────────────────────────────────────────────────────────────
+/**
+ * Reconcile requirements with the ALM through the injected client.
+ * @param {Array<{id,title,status}>} requirements
+ * @param {Record<string,{issue:string}>} map REQ → issue mapping (mutated)
+ * @param {{createIssue,getIssueStatus,closeIssue}} client
+ * @param {{ dryRun?: boolean }} opts
+ * @returns {Promise<Array<{req,action,issue,detail?}>>} actions taken/planned
+ */
+async function syncRequirements(requirements, map, client, opts) {
+    const dryRun = !!(opts && opts.dryRun);
+    const actions = [];
+    for (const req of requirements) {
+        const linked = map[req.id];
+        if (!linked) {
+            if (dryRun) {
+                actions.push({ req: req.id, action: "would-create", issue: null });
+                continue;
+            }
+            const issue = await client.createIssue(req.id, req.title);
+            map[req.id] = { issue: issue.key, url: issue.url || null };
+            actions.push({ req: req.id, action: "created", issue: issue.key });
+            continue;
+        }
+        const issueStatus = await client.getIssueStatus(linked.issue); // "open" | "done"
+        if (req.status === "done" && issueStatus !== "done") {
+            // A provider that cannot close says so up front, and the run reports it
+            // per requirement rather than throwing halfway through the queue.
+            if (client.capabilities && client.capabilities.close === false) {
+                actions.push({
+                    req: req.id,
+                    action: "close-unsupported",
+                    issue: linked.issue,
+                    detail: `${req.id} is done, but this provider cannot close ${linked.issue} — close it by hand.`,
+                });
+                continue;
+            }
+            if (!dryRun)
+                await client.closeIssue(linked.issue);
+            actions.push({
+                req: req.id,
+                action: dryRun ? "would-close" : "closed",
+                issue: linked.issue,
+            });
+        }
+        else if (req.status !== "done" && issueStatus === "done") {
+            actions.push({
+                req: req.id,
+                action: "drift",
+                issue: linked.issue,
+                detail: `${linked.issue} is done in the ALM but ${req.id} is not Implemented in traceability.md`,
+            });
+        }
+        else {
+            actions.push({ req: req.id, action: "in-sync", issue: linked.issue });
+        }
+    }
+    return actions;
+}
+//# sourceMappingURL=core.js.map

package/dist/scripts/alm/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../../scripts/alm/core.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsBH,sCAyCC;AAeD,sCAiCC;AAID,gCAIC;AAED,kCAMC;AAUD,kDA6BC;AAYD,4CAkDC;AAlOD,4CAA8B;AAC9B,gDAAkC;AAClC,sEAAwE;AACxE,oDAA6C;AAC7C,2CAAqD;AACrD,iCAA0C;AAG7B,QAAA,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;AACpD,QAAA,eAAe,GAAG,iBAAiB,CAAC;AAEjD,iEAAiE;AACpD,QAAA,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;AAE9E,iFAAiF;AAEjF;;;GAGG;AACH,SAAgB,aAAa,CAAC,UAAU;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,uBAAe,CAAC,CAAC;IACvD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,2EAA2E;QAC3E,iEAAiE;QACjE,0EAA0E;QAC1E,0BAA0B;QAC1B,MAAM,WAAW,GAAG,qBAAS,CAAC,GAAG,CAC/B,CAAC,CAAC,EAAE,EAAE,CACJ,OAAO,CAAC,CAAC,KAAK,IAAI;YAClB,eAAe,CAAC,CAAC,EAAE,IAAI;YACvB,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YACzD,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAC/F,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEf,MAAM,IAAI,KAAK,CACb,GAAG,uBAAe,iBAAiB,UAAU,KAAK;YAChD,sDAAsD;YACtD,GAAG,WAAW,MAAM;YACpB,wEAAwE;YACxE,gCAAgC,CACnC,CAAC;IACJ,CAAC;IACD,6EAA6E;IAC7E,iDAAiD;IACjD,MAAM,GAAG,GAAG,CAAC,IAAA,wBAAa,EAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAyB,CAAC;IAC5F,IAAI,CAAC,GAAG,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,uBAAe,oCAAoC,CAAC,CAAC;IAE3F,2EAA2E;IAC3E,wEAAwE;IACxE,6DAA6D;IAC7D,MAAM,QAAQ,GAAG,IAAA,uBAAW,EAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACvD,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC3C,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CACb,GAAG,uBAAe,2BAA2B,GAAG,mBAAmB,QAAQ,CAAC,EAAE,MAAM;gBAClF,gBAAgB,QAAQ,CAAC,KAAK,cAAc,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACrF,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,aAAa,CAAC,GAAG,EAAE,UAAmB;IACpD,MAAM,QAAQ,GAAG,IAAA,uBAAW,EAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACvD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC;QACnB,GAAG,uBAAgB;QACnB,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ;QAC3B,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ;KAC5B,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,EAAE,CAAC;IACvB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5B,MAAM,MAAM,GAAG,qBAAS,CAAC,MAAM,CAC7B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAC1F,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAEnB,WAAW,CAAC,IAAI,CACd,IAAA,qBAAO,EACL,uBAAuB,EACvB,MAAM,CAAC,MAAM,GAAG,CAAC;YACf,CAAC,CAAC,IAAI,GAAG,gBAAgB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,QAAQ,CAAC,EAAE,0BAA0B;YAC3F,CAAC,CAAC,IAAI,GAAG,+BAA+B,EAC1C;YACE,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,uBAAe;YACrB,GAAG,EACD,MAAM,CAAC,MAAM,GAAG,CAAC;gBACf,CAAC,CAAC,WAAW,GAAG,4BAA4B,MAAM,CAAC,CAAC,CAAC,6BAA6B;gBAClF,CAAC,CAAC,WAAW,GAAG,MAAM,QAAQ,CAAC,KAAK,WAAW,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;SAClF,CACF,CACF,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,iFAAiF;AAEjF,SAAgB,UAAU,CAAC,UAAU;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,mBAAW,CAAC,CAAC;IACnD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IACvC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,SAAgB,WAAW,CAAC,UAAU,EAAE,GAAG,EAAE,MAAM;IACjD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,mBAAW,CAAC,CAAC;IACnD,IAAI,MAAM;QAAE,OAAO,OAAO,CAAC;IAC3B,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvE,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,iFAAiF;AAEjF;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,UAAU;IAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAC5E,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,6BAA6B,SAAS,0BAA0B,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,IAAI,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;QAC1D,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAC3D,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,MAAM,GAAG,EAAE,CAAC;IAClB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,kCAAkC,CAAC,EAAE,CAAC;QAClE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7B,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,GAAG,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAClE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,SAAS;QACnE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACnD,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACnD,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAChD,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,OAAO,CAAC,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;QACvD,EAAE;QACF,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE;QACvB,MAAM,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,qBAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;KAC7F,CAAC,CAAC,CAAC;AACN,CAAC;AAED,iFAAiF;AAEjF;;;;;;;GAOG;AACI,KAAK,UAAU,gBAAgB,CAAC,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI;IACpE,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,EAAE,CAAC;IAEnB,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAE3B,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACnE,SAAS;YACX,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;YAC1D,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,IAAI,IAAI,EAAE,CAAC;YAC3D,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;YACnE,SAAS;QACX,CAAC;QAED,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,kBAAkB;QACjF,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,WAAW,KAAK,MAAM,EAAE,CAAC;YACpD,wEAAwE;YACxE,kEAAkE;YAClE,IAAI,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,YAAY,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;gBAC/D,OAAO,CAAC,IAAI,CAAC;oBACX,GAAG,EAAE,GAAG,CAAC,EAAE;oBACX,MAAM,EAAE,mBAAmB;oBAC3B,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,MAAM,EAAE,GAAG,GAAG,CAAC,EAAE,4CAA4C,MAAM,CAAC,KAAK,sBAAsB;iBAChG,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YACD,IAAI,CAAC,MAAM;gBAAE,MAAM,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnD,OAAO,CAAC,IAAI,CAAC;gBACX,GAAG,EAAE,GAAG,CAAC,EAAE;gBACX,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ;gBACzC,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,WAAW,KAAK,MAAM,EAAE,CAAC;YAC3D,OAAO,CAAC,IAAI,CAAC;gBACX,GAAG,EAAE,GAAG,CAAC,EAAE;gBACX,MAAM,EAAE,OAAO;gBACf,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,2BAA2B,GAAG,CAAC,EAAE,wCAAwC;aACjG,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/scripts/alm/port.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * `AlmProvider` — the contract every ALM connector implements.
+ *
+ * The two connectors that existed before this module were a ternary in
+ * `clients.ts` over `provider === "jira"`, which scales to two and no further.
+ * Worse, nothing recorded *which configuration keys each provider reads*, and
+ * three consequences of that shipped:
+ *
+ *   1. a Jira config with no `user_env` passes validation and fails later with
+ *      "Environment variable JIRA_USER is not set" — a variable the file never
+ *      named;
+ *   2. `alm.config.yaml` accepts any key at all, so `nonsense_key: 42` and a
+ *      `user_env` on an Azure config are read by nobody and reported by
+ *      nobody. `harness.config.yaml` takes the opposite position, in this same
+ *      repository, and says why: a key nobody reads is worse than a missing
+ *      one, because the file looks configured;
+ *   3. `done_state` is read by Azure and ignored by Jira, which discovers the
+ *      transition from the workflow. Setting it on a Jira project does
+ *      nothing, silently.
+ *
+ * So a provider declares three things, and each is read by something:
+ *
+ *   `config`        which keys it requires and which it merely accepts.
+ *                   `lintAlmConfig` reports the rest.
+ *   `capabilities`  which operations it can perform. `syncRequirements`
+ *                   degrades instead of throwing when one is missing.
+ *   `create`        the factory, taking the validated config and a fetch
+ *                   implementation so every provider is testable offline.
+ *
+ * The declaration is not decoration: `tests/unit/alm-conformance.test.ts`
+ * runs the same suite against every registered provider and fails when an
+ * implementation and its declaration disagree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CORE_CONFIG_KEYS = exports.CAPABILITY_METHOD = exports.CAPABILITIES = void 0;
+exports.checkProviderDeclaration = checkProviderDeclaration;
+/** Every capability name, for the checks that iterate them. */
+exports.CAPABILITIES = [
+    "create",
+    "readStatus",
+    "close",
+    "listIssues",
+];
+/** The client method each capability promises. */
+exports.CAPABILITY_METHOD = {
+    create: "createIssue",
+    readStatus: "getIssueStatus",
+    close: "closeIssue",
+    listIssues: "listIssues",
+};
+/** Config keys the core itself reads, whatever the provider. */
+exports.CORE_CONFIG_KEYS = ["alm_version", "provider"];
+/**
+ * Check a provider declaration is well formed.
+ *
+ * Called by the conformance kit rather than at import time: a malformed
+ * provider is a bug in this repository, not a condition a user can reach, and
+ * paying for the check on every CLI start would be a tax on everyone.
+ *
+ * @returns problems, empty when the declaration is sound
+ */
+function checkProviderDeclaration(provider) {
+    if (!provider || typeof provider !== "object")
+        return ["provider is not an object"];
+    const candidate = provider;
+    const problems = [];
+    const at = (msg) => problems.push(`${candidate.id ?? "(anonymous)"}: ${msg}`);
+    if (typeof candidate.id !== "string" || !candidate.id)
+        at("declares no id");
+    if (typeof candidate.label !== "string" || !candidate.label)
+        at("declares no label");
+    if (typeof candidate.create !== "function")
+        at("declares no create() factory");
+    problems.push(...checkConfigContract(candidate));
+    problems.push(...checkCapabilities(candidate));
+    return problems;
+}
+function checkConfigContract(candidate) {
+    const label = candidate.id ?? "(anonymous)";
+    const config = candidate.config;
+    if (!config || typeof config !== "object")
+        return [`${label}: declares no config contract`];
+    const problems = [];
+    for (const bucket of ["required", "optional"]) {
+        if (!Array.isArray(config[bucket]))
+            problems.push(`${label}: config.${bucket} is not an array`);
+    }
+    const declared = [...(config.required ?? []), ...(config.optional ?? [])];
+    const duplicated = declared.filter((key, i) => declared.indexOf(key) !== i);
+    if (duplicated.length > 0)
+        problems.push(`${label}: declares ${duplicated.join(", ")} twice`);
+    for (const key of declared) {
+        if (exports.CORE_CONFIG_KEYS.includes(key))
+            problems.push(`${label}: re-declares the core key '${key}'`);
+    }
+    return problems;
+}
+function checkCapabilities(candidate) {
+    const label = candidate.id ?? "(anonymous)";
+    const caps = candidate.capabilities;
+    if (!caps || typeof caps !== "object")
+        return [`${label}: declares no capabilities`];
+    const problems = [];
+    for (const capability of exports.CAPABILITIES) {
+        if (typeof caps[capability] !== "boolean") {
+            problems.push(`${label}: capability '${capability}' is not declared as a boolean`);
+        }
+    }
+    const extra = Object.keys(caps).filter((name) => !exports.CAPABILITIES.includes(name));
+    if (extra.length > 0) {
+        problems.push(`${label}: declares unknown capabilit(y/ies): ${extra.join(", ")}`);
+    }
+    return problems;
+}
+//# sourceMappingURL=port.js.map

package/dist/scripts/alm/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../../../scripts/alm/port.ts"],"names":[],"mappings":"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"}