@rsaglobaltech/specgate 0.21.0 → 0.22.1

package/dist/scripts/lib/ticket-keys.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * The ticket key travels with the work (ADR-0039): a Git host linked to Jira
+ * shows a ticket's branch, commits and pull request only when they name its
+ * key. On a ticket's branch, a commit that does not is invisible to the
+ * ticket, so `check` says which.
+ */
+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.baseFor = baseFor;
+exports.ticketKeyFindings = ticketKeyFindings;
+exports.ticketKeyOf = ticketKeyOf;
+exports.harnessCommitMessage = harnessCommitMessage;
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const diagnostics_1 = require("./diagnostics");
+const base_ids_1 = require("./base-ids");
+const GitSafety_1 = require("../../packages/core/src/domain/GitSafety");
+/** `feature/KAN-13-register-vehicle-entry` → `KAN-13`. */
+const TICKET_BRANCH = /^(?:feature|bugfix|hotfix)\/([A-Z][A-Z0-9_]+-\d+)(?:-|$)/;
+function git(dir, args) {
+    return (0, node_child_process_1.spawnSync)("git", ["-C", dir, ...args], { encoding: "utf8" });
+}
+/** The base: `--base`, SPECGATE_BASE or origin's default, else develop, main, master. */
+function baseFor(dir, given) {
+    const resolved = (0, base_ids_1.resolveBase)(dir, given);
+    if (resolved) {
+        // Throws for a ref git would read as an option: a base that cannot be
+        // used is an error, never "no base" — that would mean HEAD.
+        (0, GitSafety_1.assertSafeGitRef)(resolved, "base");
+        return resolved;
+    }
+    for (const name of ["develop", "main", "master"]) {
+        if (git(dir, ["rev-parse", "--verify", "--quiet", `refs/heads/${name}`]).status === 0)
+            return name;
+    }
+    return null;
+}
+function ticketKeyFindings(dir, given) {
+    const branch = git(dir, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (branch.status !== 0)
+        return [];
+    const key = TICKET_BRANCH.exec(branch.stdout.trim())?.[1];
+    if (!key)
+        return [];
+    let base;
+    try {
+        base = baseFor(dir, given);
+    }
+    catch {
+        return [];
+    }
+    if (!base || base === branch.stdout.trim())
+        return [];
+    const log = git(dir, ["log", `${base}..HEAD`, "--format=%h%x09%s"]);
+    if (log.status !== 0)
+        return [];
+    const named = new RegExp(`(^|[^A-Z0-9_-])${key}(?![0-9])`);
+    return log.stdout
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => line.split("\t"))
+        .filter(([, subject]) => !named.test(subject ?? ""))
+        .map(([sha, subject]) => (0, diagnostics_1.warning)("ticket_key_missing", `Commit ${sha} "${subject}" does not name ${key}.`, {
+        target: sha,
+        fix: `Reword it to start with ${key} (git commit --amend for the last one), so Jira shows it in ${key}.`,
+    }));
+}
+const CHANGES = path.join("docs", "specs", "changes");
+const JIRA_KEY = /^[A-Z][A-Z0-9_]+-\d+$/;
+function specFiles(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+        const full = path.join(dir, e.name);
+        return e.isDirectory() ? specFiles(full) : e.name === "spec.md" ? [full] : [];
+    });
+}
+/** The ticket of the open change whose delta holds `requirement`, or null (REQ-156). */
+function ticketKeyOf(projectDir, requirement) {
+    const changes = path.join(projectDir, CHANGES);
+    if (!fs.existsSync(changes))
+        return null;
+    const heading = new RegExp(`^###\\s+Requirement:\\s+${requirement}(?![0-9])`, "m");
+    for (const e of fs.readdirSync(changes, { withFileTypes: true })) {
+        if (!e.isDirectory() || e.name === "archive" || e.name.startsWith("."))
+            continue;
+        const dir = path.join(changes, e.name);
+        if (!specFiles(path.join(dir, "specs")).some((f) => heading.test(fs.readFileSync(f, "utf8"))))
+            continue;
+        const yaml = path.join(dir, "change.yaml");
+        const key = fs.existsSync(yaml)
+            ? /^ticket:\s*(\S+)\s*$/m.exec(fs.readFileSync(yaml, "utf8"))?.[1]
+            : undefined;
+        return key && JIRA_KEY.test(key) ? key : null;
+    }
+    return null;
+}
+/** The harness's commit for a requirement: the ticket key first when it has one. */
+function harnessCommitMessage(projectDir, requirement, attempt, maxAttempts) {
+    const key = ticketKeyOf(projectDir, requirement);
+    const subject = key
+        ? `${key} ${requirement}: implement via specgate harness`
+        : `feat(${requirement}): implement via specgate harness`;
+    return `${subject}\n\nAttempt ${attempt}/${maxAttempts}.`;
+}
+//# sourceMappingURL=ticket-keys.js.map

package/dist/scripts/lib/ticket-keys.js.map

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

package/dist/scripts/propose.js

@@ -4,14 +4,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.propose = propose;
 const ChangeCommand_1 = require("./cli/commands/change/ChangeCommand");
 const DraftCommand_1 = require("./cli/commands/spec/DraftCommand");
+const TicketCommand_1 = require("./cli/commands/change/TicketCommand");
 /**
  * `specgate propose` — the first of the daily verbs (ADR-0035). An idea opens
  * a change, as `change new` does; `--from-brief` drafts the next module of
- * docs/brief.md, as `draft` does. One engine each, two ways in.
+ * docs/brief.md, as `draft` does; `--from-ticket` takes a Jira ticket as the
+ * source text instead (ADR-0039).
  */
 function propose(argv) {
+    if (argv.includes("--from-ticket")) {
+        void new TicketCommand_1.TicketCommand(argv).execute();
+        return;
+    }
     if (argv.includes("--from-brief")) {
-        new DraftCommand_1.DraftCommand(argv.filter((a) => a !== "--from-brief")).execute();
+        new DraftCommand_1.DraftCommand(argv.filter((a) => a !== "--from-brief"), "propose --from-brief").execute();
         return;
     }
     new ChangeCommand_1.CliCommand(["new", ...argv], "propose").execute();

package/dist/scripts/propose.js.map

@@ -1 +1 @@
-{"version":3,"file":"propose.js","sourceRoot":"","sources":["../../scripts/propose.ts"],"names":[],"mappings":";;;AASA,0BAMC;AAdD,uEAAiE;AACjE,mEAAgE;AAEhE;;;;GAIG;AACH,SAAgB,OAAO,CAAC,IAAc;IACpC,IAAI,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QAClC,IAAI,2BAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,cAAc,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QACrE,OAAO;IACT,CAAC;IACD,IAAI,0BAAU,CAAC,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;AACxD,CAAC;AAED,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM;IAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"propose.js","sourceRoot":"","sources":["../../scripts/propose.ts"],"names":[],"mappings":";;;AAWA,0BAaC;AAvBD,uEAAiE;AACjE,mEAAgE;AAChE,uEAAoE;AAEpE;;;;;GAKG;AACH,SAAgB,OAAO,CAAC,IAAc;IACpC,IAAI,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QACnC,KAAK,IAAI,6BAAa,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;QACvC,OAAO;IACT,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QAClC,IAAI,2BAAY,CACd,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,cAAc,CAAC,EACxC,sBAAsB,CACvB,CAAC,OAAO,EAAE,CAAC;QACZ,OAAO;IACT,CAAC;IACD,IAAI,0BAAU,CAAC,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;AACxD,CAAC;AAED,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM;IAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/scripts/vcs/github-pr.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * One pull request per ticket, on GitHub (ADR-0039 §4).
+ *
+ * The pull request belongs to the repository, not to the ALM: this lives
+ * outside `scripts/alm/`, whose port still only creates, reads, closes and
+ * lists issues. It opens or updates a pull request, and nothing else — no
+ * merge, no close, no branch deletion. The token comes from the environment
+ * variable `pr.token_env` names and is never printed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prConfig = prConfig;
+exports.mergeBody = mergeBody;
+exports.openOrUpdatePr = openOrUpdatePr;
+const http_client_1 = require("../alm/providers/http-client");
+/** The `pr:` block of `alm.config.yaml`, checked; throws with a fix. */
+function prConfig(raw) {
+    const pr = (raw && typeof raw === "object" ? raw : {});
+    const provider = String(pr.provider ?? "github");
+    if (provider !== "github") {
+        throw new Error(`pr.provider '${provider}' is not supported.\nFix: set pr.provider: github.`);
+    }
+    const repo = String(pr.repo ?? "");
+    if (!/^[\w.-]+\/[\w.-]+$/.test(repo)) {
+        throw new Error("alm.config.yaml has no pr.repo.\nFix: add\npr:\n  provider: github\n  repo: <owner>/<repo>\n  base: develop\n  token_env: GITHUB_TOKEN");
+    }
+    const apiUrl = String(pr.base_url ?? "https://api.github.com").replace(/\/$/, "");
+    (0, http_client_1.assertSecureUrl)(apiUrl, "pr.base_url");
+    return {
+        repo,
+        base: String(pr.base ?? "develop"),
+        tokenEnv: String(pr.token_env ?? "GITHUB_TOKEN"),
+        apiUrl,
+    };
+}
+const BLOCK = /<!-- specgate:pr [^>]*-->[\s\S]*?<!-- \/specgate:pr -->/;
+/** The block's opening marker, its closer deleted: everything after it was ours. */
+const OPENED = /<!-- specgate:pr [^>]*-->[\s\S]*$/;
+/** The description with Specgate's block replaced, or added after what is there. */
+function mergeBody(current, block) {
+    if (BLOCK.test(current))
+        return current.replace(BLOCK, () => block);
+    if (OPENED.test(current))
+        return current.replace(OPENED, () => block);
+    return current.trim() ? `${current.trimEnd()}\n\n${block}` : block;
+}
+async function openOrUpdatePr(cfg, pr, fetchImpl = globalThis.fetch) {
+    const token = process.env[cfg.tokenEnv];
+    if (!token) {
+        throw new Error(`Environment variable ${cfg.tokenEnv} is not set.\n` +
+            "Fix: export a token that may write pull requests to this repository " +
+            "(a fine-grained token for this repository with Pull requests: read and write; pushing uses your git credentials).");
+    }
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/vnd.github+json",
+        "Content-Type": "application/json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    };
+    const call = async (path, what, init = {}) => {
+        const res = await fetchImpl(`${cfg.apiUrl}${path}`, { ...init, headers });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`GitHub: ${what} failed: HTTP ${res.status} ${text.slice(0, 300)}`);
+        }
+        return (await res.json());
+    };
+    const owner = cfg.repo.split("/")[0];
+    const open = await call(`/repos/${cfg.repo}/pulls?head=${encodeURIComponent(`${owner}:${pr.head}`)}` +
+        `&base=${encodeURIComponent(cfg.base)}&state=open`, `list the pull requests of ${pr.head}`);
+    const mine = open.find((p) => !p.base || p.base.ref === cfg.base);
+    if (mine) {
+        // What a person wrote stays: the title, once it names the ticket, and
+        // every line outside Specgate's own block of the description.
+        const patch = { body: mergeBody(mine.body ?? "", pr.body) };
+        const key = pr.key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        if (!new RegExp(`(^|[^A-Z0-9_-])${key}(?![0-9])`).test(mine.title ?? ""))
+            patch.title = pr.title;
+        const updated = await call(`/repos/${cfg.repo}/pulls/${mine.number}`, `update pull request #${mine.number}`, { method: "PATCH", body: JSON.stringify(patch) });
+        return { number: updated.number, url: updated.html_url, action: "updated" };
+    }
+    const created = await call(`/repos/${cfg.repo}/pulls`, `open a pull request for ${pr.head}`, {
+        method: "POST",
+        body: JSON.stringify({ title: pr.title, head: pr.head, base: cfg.base, body: pr.body }),
+    });
+    return { number: created.number, url: created.html_url, action: "created" };
+}
+//# sourceMappingURL=github-pr.js.map

package/dist/scripts/vcs/github-pr.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsaglobaltech/specgate",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "Specs as executable contracts — requirements, scenarios and traceability that CI enforces.",
   "license": "MIT",
   "type": "commonjs",

package/templates/base/AGENTS.md.tpl

@@ -22,12 +22,13 @@ The loop is propose → test → apply → archive:
 Each step in detail: the `/specgate:*` commands, or
 `specgate change instructions <artifact> --json`.
 
-## From a plan or brief
+## From a brief or a Jira ticket
 
-`specgate propose --from-brief` names the next module of `docs/brief.md`;
-`specgate propose --from-brief <module>` opens it and writes `DRAFTING.md` —
-follow it, then re-run until "Ready to review". Never archive a draft
-yourself: a person reviews it, and it is archived after it is applied.
+`specgate propose --from-brief <module>` or `specgate propose --from-ticket
+<KEY>` opens the draft and writes `DRAFTING.md` — follow it, then re-run until
+"Ready to review". Never archive a draft yourself: a person reviews it. Never
+edit a change's `ticket.md`; start every commit message with the ticket key
+(`KAN-13 REQ-007: …`), and never use Smart Commits (`#done`): they write to Jira.
 
 ## Never