@rsaglobaltech/specgate 0.8.1

package/dist/packages/core/src/domain/InboundChange.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Turning a board issue into a proposal a human can review.
+ *
+ * ADR-0021 fixes the shape of this: an ALM issue never becomes a matrix row.
+ * It becomes a `change` — a proposal and a delta — which then passes through
+ * `change validate` and `change archive` like any change written by hand. The
+ * board is a mirror, and a mirror does not get to define a requirement.
+ *
+ * **The scenarios are left empty on purpose, and that is the whole design.**
+ * A Jira ticket has a title, a description and a status. It does not contain an
+ * executable acceptance criterion, and deriving Gherkin from prose would be
+ * inventing the one thing the spec exists to pin down. The empty scenario is
+ * not an unfinished feature: it is the marker for the only work that cannot be
+ * automated, and `change validate` will refuse the change until a person — or
+ * the `spec-author` role — fills it in.
+ *
+ * Pure: an issue in, markdown out. Reading the board is the provider's job and
+ * writing the folder is the change lifecycle's, which is also what keeps the
+ * ALM subsystem free of any write path into the spec tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inboundChangeId = inboundChangeId;
+exports.planInboundChange = planInboundChange;
+/** `ACME-42 Add dynamic pricing` → `alm-acme-42`. Stable, so a second pull is idempotent. */
+function inboundChangeId(issueKey) {
+    const slug = String(issueKey)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return `alm-${slug || "issue"}`;
+}
+/** A capability name that will not surprise anyone: the issue's own key. */
+function capabilityFor(issue) {
+    return inboundChangeId(issue.key).replace(/^alm-/, "") || "inbound";
+}
+/**
+ * The proposal, seeded from what the board actually holds.
+ *
+ * The issue's own words go in verbatim and are labelled as such. Summarising
+ * them would put this tool's paraphrase where the reporter's intent should be,
+ * and the reviewer would have no way to tell which was which.
+ */
+function renderProposal(issue, reqId) {
+    const body = issue.body.trim();
+    return [
+        `# Proposal: ${issue.title.trim() || issue.key}`,
+        "",
+        "## Intent",
+        "",
+        `Raised as ${issue.key}${issue.url ? ` (${issue.url})` : ""}.`,
+        "",
+        "> Imported verbatim from the board. It has not been edited, summarised or",
+        "> interpreted — what the reporter wrote is what a reviewer should read.",
+        "",
+        body
+            ? body
+                .split("\n")
+                .map((l) => `> ${l}`)
+                .join("\n")
+            : "> _(the issue has no description)_",
+        "",
+        "## Scope",
+        "",
+        "In scope:",
+        "",
+        `- ${reqId}, as described above`,
+        "",
+        "Out of scope:",
+        "",
+        "- <!-- A proposal that excludes nothing has not been thought about. -->",
+        "",
+        "## Acceptance criteria",
+        "",
+        "**Not yet written, and that is the point.** A board issue carries a title,",
+        "a description and a status; it does not carry an executable acceptance",
+        "criterion. Write the scenario in the delta before this change can be",
+        "validated.",
+        "",
+    ].join("\n");
+}
+/**
+ * The delta, with a requirement and an unwritten scenario.
+ *
+ * The scenario heading exists so the shape is obvious and the gap is visible;
+ * its steps are a TODO rather than a guess. `change validate` fails while they
+ * stay that way, which is the intended behaviour, not an inconvenience.
+ */
+function renderDelta(issue, reqId, scenarioId) {
+    const title = issue.title.trim() || issue.key;
+    return [
+        `# Delta — ${capabilityFor(issue)}`,
+        "",
+        "## ADDED Requirements",
+        "",
+        `### Requirement: ${reqId} — ${title}`,
+        "",
+        `The system SHALL satisfy what ${issue.key} describes.`,
+        "",
+        "<!-- Replace this sentence with the requirement in your own words. The",
+        "     issue's text is in proposal.md; a requirement is not its description. -->",
+        "",
+        `#### Scenario: ${scenarioId} — TODO`,
+        "",
+        "- GIVEN <!-- the precondition -->",
+        "- WHEN <!-- the action -->",
+        "- THEN <!-- the observable outcome -->",
+        "",
+        "<!-- These steps are deliberately unwritten. The board cannot supply them:",
+        "     a ticket has no executable acceptance criterion, and inventing one",
+        "     would defeat the only check this tool can make. `change validate`",
+        "     stays red until they say something real. -->",
+        "",
+        `<!-- csda:trace origin=alm:${issue.key} -->`,
+        "",
+    ].join("\n");
+}
+/** Everything needed to write one change folder, decided without touching a disk. */
+function planInboundChange(issue, reqId, scenarioId) {
+    return {
+        changeId: inboundChangeId(issue.key),
+        capability: capabilityFor(issue),
+        proposal: renderProposal(issue, reqId),
+        delta: renderDelta(issue, reqId, scenarioId),
+    };
+}
+//# sourceMappingURL=InboundChange.js.map

package/dist/packages/core/src/domain/InboundChange.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InboundChange.js","sourceRoot":"","sources":["../../../../../packages/core/src/domain/InboundChange.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;AAmBH,0CAMC;AA2FD,8CAWC;AA7GD,6FAA6F;AAC7F,SAAgB,eAAe,CAAC,QAAgB;IAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC;SAC1B,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC3B,OAAO,OAAO,IAAI,IAAI,OAAO,EAAE,CAAC;AAClC,CAAC;AAED,4EAA4E;AAC5E,SAAS,aAAa,CAAC,KAAmB;IACxC,OAAO,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,SAAS,CAAC;AACtE,CAAC;AAED;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,KAAmB,EAAE,KAAa;IACxD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAC/B,OAAO;QACL,eAAe,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,EAAE;QAChD,EAAE;QACF,WAAW;QACX,EAAE;QACF,aAAa,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG;QAC9D,EAAE;QACF,2EAA2E;QAC3E,yEAAyE;QACzE,EAAE;QACF,IAAI;YACF,CAAC,CAAC,IAAI;iBACD,KAAK,CAAC,IAAI,CAAC;iBACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;iBACpB,IAAI,CAAC,IAAI,CAAC;YACf,CAAC,CAAC,oCAAoC;QACxC,EAAE;QACF,UAAU;QACV,EAAE;QACF,WAAW;QACX,EAAE;QACF,KAAK,KAAK,sBAAsB;QAChC,EAAE;QACF,eAAe;QACf,EAAE;QACF,yEAAyE;QACzE,EAAE;QACF,wBAAwB;QACxB,EAAE;QACF,4EAA4E;QAC5E,wEAAwE;QACxE,sEAAsE;QACtE,YAAY;QACZ,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,KAAmB,EAAE,KAAa,EAAE,UAAkB;IACzE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,CAAC;IAC9C,OAAO;QACL,aAAa,aAAa,CAAC,KAAK,CAAC,EAAE;QACnC,EAAE;QACF,uBAAuB;QACvB,EAAE;QACF,oBAAoB,KAAK,MAAM,KAAK,EAAE;QACtC,EAAE;QACF,iCAAiC,KAAK,CAAC,GAAG,aAAa;QACvD,EAAE;QACF,wEAAwE;QACxE,gFAAgF;QAChF,EAAE;QACF,kBAAkB,UAAU,SAAS;QACrC,EAAE;QACF,mCAAmC;QACnC,4BAA4B;QAC5B,wCAAwC;QACxC,EAAE;QACF,4EAA4E;QAC5E,yEAAyE;QACzE,wEAAwE;QACxE,mDAAmD;QACnD,EAAE;QACF,8BAA8B,KAAK,CAAC,GAAG,MAAM;QAC7C,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,qFAAqF;AACrF,SAAgB,iBAAiB,CAC/B,KAAmB,EACnB,KAAa,EACb,UAAkB;IAElB,OAAO;QACL,QAAQ,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC;QACpC,UAAU,EAAE,aAAa,CAAC,KAAK,CAAC;QAChC,QAAQ,EAAE,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC;QACtC,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,CAAC;KAC7C,CAAC;AACJ,CAAC"}

package/dist/packages/core/src/domain/Language.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * The language of generated prose.
+ *
+ * A Spanish team writing Spanish specs should not have `Added` and `Retired`
+ * appear in the middle of them — but they must not have `SHALL` translated
+ * either. The grammar is not prose: `SHALL`, `GIVEN`/`WHEN`/`THEN`,
+ * `## ADDED Requirements`, `REQ-NNN` and `csda:trace` are what the validator
+ * parses. Translating any of them breaks the file.
+ *
+ * So the split is explicit. Only the sentences a human reads are translated;
+ * the keywords never are, and there is a test asserting that.
+ *
+ * Set with `specgate config set language es`. Defaults to English.
+ *
+ * The tables and the tag-matching live here. Finding out which language a
+ * given project asked for reads its config, so that half is infrastructure —
+ * see `DiskLanguageRepository`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT = exports.PHRASES = exports.KEYWORDS = void 0;
+exports.phrasesFor = phrasesFor;
+exports.languageFor = languageFor;
+/** Never translated, in any language. These are parsed, not read. */
+exports.KEYWORDS = Object.freeze([
+    "SHALL",
+    "MUST",
+    "SHOULD",
+    "MAY",
+    "GIVEN",
+    "WHEN",
+    "THEN",
+    "AND",
+    "ADDED Requirements",
+    "MODIFIED Requirements",
+    "REMOVED Requirements",
+    "Requirement:",
+    "Scenario:",
+    "csda:trace",
+]);
+exports.PHRASES = {
+    en: {
+        systemShall: (behaviour) => `The system SHALL ${behaviour}.`,
+        systemShallMeet: (what) => `The system SHALL satisfy "${what}".`,
+        observableBehaviour: "<observable behaviour>",
+        priority: (value) => `_Priority: ${value}._`,
+        todoSteps: (name) => `- TODO: write the GIVEN / WHEN / THEN steps for "${name}"`,
+        todoStepsPlain: "- TODO: write the GIVEN / WHEN / THEN steps",
+        precondition: "<precondition>",
+        action: "<action>",
+        outcome: "<observable outcome>",
+        scenarioName: "<scenario name>",
+        shortName: "<short name>",
+        capability: "<capability>",
+        added: "Added",
+        modified: "Modified",
+        removed: "Retired",
+    },
+    es: {
+        systemShall: (behaviour) => `El sistema SHALL ${behaviour}.`,
+        systemShallMeet: (what) => `El sistema SHALL cumplir "${what}".`,
+        observableBehaviour: "<comportamiento observable>",
+        priority: (value) => `_Prioridad: ${value}._`,
+        todoSteps: (name) => `- TODO: escribir los pasos GIVEN / WHEN / THEN de "${name}"`,
+        todoStepsPlain: "- TODO: escribir los pasos GIVEN / WHEN / THEN",
+        precondition: "<precondición>",
+        action: "<acción>",
+        outcome: "<resultado observable>",
+        scenarioName: "<nombre del escenario>",
+        shortName: "<nombre corto>",
+        capability: "<capacidad>",
+        added: "Añadidos",
+        modified: "Modificados",
+        removed: "Retirados",
+    },
+    pt: {
+        systemShall: (behaviour) => `O sistema SHALL ${behaviour}.`,
+        systemShallMeet: (what) => `O sistema SHALL cumprir "${what}".`,
+        observableBehaviour: "<comportamento observável>",
+        priority: (value) => `_Prioridade: ${value}._`,
+        todoSteps: (name) => `- TODO: escrever os passos GIVEN / WHEN / THEN de "${name}"`,
+        todoStepsPlain: "- TODO: escrever os passos GIVEN / WHEN / THEN",
+        precondition: "<precondição>",
+        action: "<ação>",
+        outcome: "<resultado observável>",
+        scenarioName: "<nome do cenário>",
+        shortName: "<nome curto>",
+        capability: "<capacidade>",
+        added: "Adicionados",
+        modified: "Modificados",
+        removed: "Retirados",
+    },
+};
+exports.DEFAULT = "en";
+/**
+ * The phrase table for a language tag, falling back to the base tag and then
+ * to English. `null` or an unknown tag both mean English.
+ */
+function phrasesFor(tag) {
+    return exports.PHRASES[languageFor(tag)];
+}
+/** Which of the tables above a tag selects. */
+function languageFor(tag) {
+    if (!tag)
+        return exports.DEFAULT;
+    const lower = String(tag).toLowerCase();
+    if (exports.PHRASES[lower])
+        return lower;
+    const base = lower.split("-")[0];
+    return exports.PHRASES[base] ? base : exports.DEFAULT;
+}
+//# sourceMappingURL=Language.js.map

package/dist/packages/core/src/domain/Language.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Language.js","sourceRoot":"","sources":["../../../../../packages/core/src/domain/Language.ts"],"names":[],"mappings":"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"}

package/dist/packages/core/src/domain/Lockfile.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Lockfile = void 0;
+class Lockfile {
+    specops_version;
+    csda_version;
+    packs;
+    static CURRENT_SCHEMA_VERSION = 1;
+    static FILENAME = ".specops.lock";
+    constructor(specops_version, csda_version, packs) {
+        this.specops_version = specops_version;
+        this.csda_version = csda_version;
+        this.packs = packs;
+    }
+    static createEmpty(csdaVersion = "0.0.0") {
+        return new Lockfile(Lockfile.CURRENT_SCHEMA_VERSION, csdaVersion, []);
+    }
+    static parse(raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`Invalid ${Lockfile.FILENAME}: ${err.message}`);
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`Invalid ${Lockfile.FILENAME}: root must be an object`);
+        }
+        const declared = parsed.specops_version;
+        if (typeof declared === "number" && declared > Lockfile.CURRENT_SCHEMA_VERSION) {
+            throw new Error(`${Lockfile.FILENAME} was written by a newer version of this CLI ` +
+                `(lockfile format ${declared}, this CLI understands ${Lockfile.CURRENT_SCHEMA_VERSION}).\n` +
+                "Fix: upgrade with `npm install -g create-spec-driven-app@latest`, or ask " +
+                "whoever committed the lockfile which version they used.");
+        }
+        const packs = Array.isArray(parsed.packs) ? parsed.packs : [];
+        return new Lockfile(declared || Lockfile.CURRENT_SCHEMA_VERSION, parsed.csda_version || "0.0.0", packs);
+    }
+    upsertPack(entry) {
+        if (!entry || !entry.repo || !entry.pack_id) {
+            throw new Error("upsertPack: entry.repo and entry.pack_id are required");
+        }
+        const idx = this.packs.findIndex((p) => p.repo === entry.repo && p.pack_id === entry.pack_id);
+        if (idx >= 0) {
+            this.packs[idx] = { ...this.packs[idx], ...entry };
+        }
+        else {
+            this.packs.push({ ...entry });
+        }
+        this.packs.sort((a, b) => {
+            const r = String(a.repo).localeCompare(String(b.repo));
+            return r !== 0 ? r : String(a.pack_id).localeCompare(String(b.pack_id));
+        });
+    }
+    toJSON() {
+        return {
+            specops_version: this.specops_version,
+            csda_version: this.csda_version,
+            packs: this.packs,
+        };
+    }
+}
+exports.Lockfile = Lockfile;
+//# sourceMappingURL=Lockfile.js.map

package/dist/packages/core/src/domain/Lockfile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Lockfile.js","sourceRoot":"","sources":["../../../../../packages/core/src/domain/Lockfile.ts"],"names":[],"mappings":"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"}

package/dist/packages/core/src/domain/PackContribution.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * A change, expressed as a fragment of `pack.yaml`.
+ *
+ * `specops contribute` sends work back upstream: a capability the project
+ * wrote or amended becomes requirements and scenarios a pack maintainer can
+ * merge. This is the inverse of `PackDelta`, which turns a pack bump into a
+ * change — and like it, the interesting part is a rendering, so it is pure and
+ * the git work stays outside.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deltaToPackFragment = deltaToPackFragment;
+exports.contributionReadme = contributionReadme;
+const SpecParser_1 = require("./SpecParser");
+const yamlString = (v) => 
+// Backslash first: escaping only the quote leaves `\\` before it able to
+// escape the escape, and the value breaks out of its own string.
+`"${String(v === undefined || v === null ? "" : v)
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')}"`;
+/**
+ * Express a delta's requirements in the pack's own model shape.
+ *
+ * The inverse of `as_change.deriveDelta`: that reads `pack.yaml` and writes a
+ * delta, this reads a delta and writes a `pack.yaml` fragment. Round-tripping
+ * the two is what makes the pack and the project speak one language.
+ */
+function deltaToPackFragment(delta, opts) {
+    const o = opts || {};
+    const requirements = [];
+    const scenarios = [];
+    const emit = (req, disposition) => {
+        const trace = req.trace || {};
+        requirements.push([
+            `  - id: ${req.id || "REQ-TODO"}`,
+            `    title: ${yamlString(req.name)}`,
+            `    priority: ${trace.priority || "Should"}`,
+            `    description: ${yamlString((0, SpecParser_1.blockText)(req.text).split("\n")[0])}`,
+            `    status: Draft`,
+            disposition ? `    # ${disposition}` : null,
+        ]
+            .filter(Boolean)
+            .join("\n"));
+        for (const sc of req.scenarios || []) {
+            scenarios.push([
+                `  - id: ${yamlString(sc.id || "SCN-TODO")}`,
+                `    requirement_id: ${req.id || "REQ-TODO"}`,
+                trace.uc ? `    use_case: ${trace.uc}` : null,
+                trace.feature ? `    target: ${yamlString(trace.feature)}` : null,
+                `    scenario: ${yamlString(sc.name)}`,
+                trace.cmd ? `    command: ${trace.cmd}` : null,
+                trace.agg ? `    aggregate: ${trace.agg}` : null,
+                trace.evt ? `    events:\n      - ${trace.evt}` : null,
+            ]
+                .filter(Boolean)
+                .join("\n"));
+        }
+    };
+    for (const req of delta.added)
+        emit(req, null);
+    for (const req of delta.modified)
+        emit(req, "MODIFIED upstream — reconcile with the existing entry");
+    const removed = delta.removed.map((req) => `  # REMOVED locally: ${req.id || req.name}`);
+    const lines = [`# Contribution fragment${o.changeId ? ` — ${o.changeId}` : ""}`, ""];
+    if (requirements.length > 0) {
+        lines.push("requirements:", ...requirements, "");
+    }
+    if (scenarios.length > 0) {
+        lines.push("scenarios:", ...scenarios, "");
+    }
+    if (removed.length > 0) {
+        lines.push("# Requirements this project retired locally:", ...removed, "");
+    }
+    if (requirements.length === 0 && scenarios.length === 0 && removed.length === 0) {
+        return null;
+    }
+    while (lines[lines.length - 1] === "")
+        lines.pop();
+    return `${lines.join("\n")}\n`;
+}
+function contributionReadme(changeId, packId, proposal, summary) {
+    return `# Contribution: ${changeId}
+
+Proposed upstream from a project consuming \`${packId}\`.
+
+## Summary
+
+- Added: ${summary.added.join(", ") || "—"}
+- Modified: ${summary.modified.join(", ") || "—"}
+- Removed locally: ${summary.removed.join(", ") || "—"}
+
+## Files in this contribution
+
+| File | What it is |
+| --- | --- |
+| \`fragment.yaml\` | The requirements and scenarios expressed in the pack's model shape. **Not merged into \`pack.yaml\` automatically** — a maintainer decides where each entry belongs and whether the ids collide. |
+| \`delta.md\` | The same change as a delta spec, for reading. |
+| \`proposal.md\` | The consuming project's original proposal. |
+
+## Original proposal
+
+${proposal || "_(the change carried no proposal.md)_"}
+`;
+}
+// ── Git staging ───────────────────────────────────────────────────────────────
+//# sourceMappingURL=PackContribution.js.map

package/dist/packages/core/src/domain/PackContribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PackContribution.js","sourceRoot":"","sources":["../../../../../packages/core/src/domain/PackContribution.ts"],"names":[],"mappings":"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"}