@rse/ase 1.0.7 → 2.0.1

package/dst/ase-task-store-issues.js

@@ -0,0 +1,237 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { DateTime } from "luxon";
+import * as TaskFormat from "./ase-task-format.js";
+/*  the reserved labels: the project registry entry (carrying the lifecycle model
+    and task id scheme in its description), the soft deletion marker, and the
+    "ase:<key>:<value>" labels of the header keys without a native counterpart  */
+export const LABEL_PROJECT = "ase:project";
+export const LABEL_DELETED = "ase:deleted";
+export const LABEL_KEY_RE = /^ase:([A-Za-z]+):(.*)$/;
+/*  the hidden metadata header of an attachment comment  */
+const ATTACH_RE = /^<!-- ase:attachment\n([\s\S]*?)\n-->\n?([\s\S]*)$/;
+/*  escape a hidden metadata value, so it can never close the HTML comment  */
+const escapeValue = (value) => value.replace(/&/g, "&amp;").replace(/-->/g, "--&gt;");
+const unescapeValue = (value) => value.replace(/--&gt;/g, "-->").replace(/&amp;/g, "&");
+/*  the timestamp of the task plan format for an ISO timestamp of the issue tracker  */
+export const stamp = (iso) => DateTime.fromISO(iso).toFormat("yyyy-LL-dd HH:mm");
+/*  the task id of an issue number, and the issue number of a task id (0 if not conforming)  */
+export const idOf = (scheme, n) => `${scheme.prefix}${String(n).padStart(scheme.width, "0")}${scheme.suffix}`;
+export const numberOf = (scheme, id) => {
+    const n = TaskFormat.seqNumber(scheme, id);
+    return n > 0 && idOf(scheme, n) === id ? n : 0;
+};
+/*  the description of the "ase:project" label for a registry entry, and vice versa  */
+export const registryDescription = (entry) => `lifecycle=${entry.lifecycle} idscheme=${entry.idscheme}` + ((entry.seqmark ?? 0) > 0 ? ` seqmark=${String(entry.seqmark)}` : "");
+export const registryEntry = (description) => {
+    const m = /^lifecycle=(\S+) idscheme=(\S+)(?: seqmark=(\d+))?$/.exec(description ?? "");
+    return {
+        lifecycle: m?.[1] ?? "solo",
+        idscheme: m?.[2] ?? "seq:#%d",
+        ...(m?.[3] !== undefined ? { seqmark: Number.parseInt(m[3], 10) } : {})
+    };
+};
+/*  reject a task id scheme of a project registration other than a "seq" one  */
+export const requireSeqScheme = (idscheme, service) => {
+    if (TaskFormat.parseIdScheme(idscheme).kind !== "seq")
+        throw new Error(`task id scheme "${idscheme}" not supported, as task ids are ${service} issue numbers ` +
+            "(use a \"seq\" task id scheme like \"seq:#%d\")");
+};
+export const registryContext = (prjId, entry, service) => {
+    const lifecycle = Object.hasOwn(TaskFormat.taskLifecycles, entry.lifecycle) ?
+        TaskFormat.taskLifecycles[entry.lifecycle] : TaskFormat.taskLifecycles.solo;
+    const scheme = TaskFormat.parseIdScheme(entry.idscheme);
+    if (scheme.kind !== "seq")
+        throw new Error(`project "${prjId}" carries task id scheme "${entry.idscheme}", but ${service} requires a "seq" one`);
+    return { lifecycle, scheme };
+};
+/*  decode the labels of an issue into the header: the "ase:<key>:<value>" labels of the
+    keys without native counterpart (and of an unassignable "Assignee") and the tags, with
+    a legacy "ase:Branch:<name>" label migrated into "Changeset" (see TaskFormat.migrateBranch);
+    returns the state of the "ase:Status:<state>" label, as it only refines the issue state  */
+export const labelHeader = (header, names, nativeKeys) => {
+    const tags = [];
+    let status;
+    let branch;
+    for (const name of names) {
+        const m = LABEL_KEY_RE.exec(name);
+        if (m === null && !name.startsWith("ase:"))
+            tags.push(name);
+        else if (m !== null && m[1] === "Status")
+            status = m[2];
+        else if (m !== null && m[1] === "Branch")
+            branch = m[2];
+        else if (m !== null && (!nativeKeys.includes(m[1]) || m[1] === "Assignee"))
+            header[m[1]] = m[2];
+    }
+    if (tags.length > 0)
+        header.Tags = tags;
+    if (branch !== undefined) {
+        const changeset = TaskFormat.migrateBranch(branch);
+        if (changeset !== undefined && header.Changeset === undefined)
+            header.Changeset = changeset;
+    }
+    return status;
+};
+/*  encode the header into labels: the "ase:<key>:<value>" labels of the keys
+    without native counterpart and the tags (except the reserved "ase:" ones)  */
+export const headerLabels = (header, nativeKeys) => {
+    const labels = [];
+    for (const [key, value] of Object.entries(header))
+        if (!nativeKeys.includes(key) && typeof value === "string")
+            labels.push(`ase:${key}:${value}`);
+    for (const tag of Array.isArray(header.Tags) ? header.Tags : []) {
+        if (tag.startsWith("ase:"))
+            throw new Error(`tag "${tag}" collides with the reserved "ase:" labels`);
+        labels.push(tag);
+    }
+    return labels;
+};
+/*  derive "Status" from the issue state: a closed issue carries a finished state
+    ("CANCELLED" if cancelled, else the finished one of its label, else the first
+    finished one), an open issue the unfinished one of its label (else none)  */
+export const issueStatus = (lifecycle, closed, cancelled, label) => {
+    if (closed)
+        return cancelled ? "CANCELLED" :
+            label !== undefined && label !== "CANCELLED" && lifecycle.finished.includes(label) ? label : lifecycle.finished[0];
+    return label !== undefined && !lifecycle.finished.includes(label) ? label : undefined;
+};
+/*  derive the body of a task plan from an issue: the "#   TASK:" heading from the
+    issue title plus the issue body, and the issue title and body from a task plan  */
+export const issueBody = (title, text) => {
+    const body = (text ?? "").replace(/\r\n/g, "\n").replace(/\n+$/, "");
+    return `#   TASK: ${title}\n` + (body !== "" ? `\n${body}\n` : "");
+};
+export const planIssue = (taskId, plan) => ({
+    title: TaskFormat.taskTitle(plan.body) || taskId,
+    body: plan.body.replace(/^#[ \t]+TASK:.*(?:\n|$)/m, "").replace(/^\n+/, "").replace(/\n+$/, "")
+});
+/*  whether an attachment is embedded as-is (Markdown) instead of as fenced code block  */
+const isMarkdown = (type) => /^text\/markdown\b/i.test(type ?? "");
+/*  whether two attachments are equal  */
+export const same = (a, b) => {
+    const ka = Object.keys(a).sort();
+    const kb = Object.keys(b).sort();
+    return ka.length === kb.length && ka.every((key, i) => key === kb[i] && a[key] === b[key]);
+};
+/*  derive the attachment of a comment: an attachment comment carries its keys in
+    the hidden metadata header (with "Data" giving the "|4+" or "|4-" chomping)
+    followed by the data (fenced, unless Markdown), with a legacy "preflight" draft
+    kind migrated into "draft" (see TaskFormat.migrateAttachment), and any other
+    comment reads as a Markdown attachment  */
+export const commentAttachment = (body, author, created, modified) => {
+    const text = (body ?? "").replace(/\r\n/g, "\n");
+    const m = ATTACH_RE.exec(text);
+    if (m === null)
+        return {
+            Type: "text/markdown",
+            Desc: `comment by @${author}`,
+            Created: stamp(created),
+            Modified: stamp(modified),
+            Data: text
+        };
+    const attachment = {};
+    let chomp;
+    for (const line of m[1].split("\n")) {
+        const kv = /^([A-Za-z]+):[ \t]*(.*)$/.exec(line);
+        if (kv === null)
+            continue;
+        if (kv[1] === "Data")
+            chomp = kv[2].trim();
+        else
+            attachment[kv[1]] = unescapeValue(kv[2].trimEnd());
+    }
+    if (chomp !== undefined) {
+        const data = isMarkdown(attachment.Type) ?
+            m[2].replace(/\n+$/, "") :
+            m[2].replace(/^[^\n]*\n/, "").replace(/\n?[^\n]*$/, "");
+        attachment.Data = data !== "" && chomp !== "|4-" ? `${data}\n` : data;
+    }
+    return TaskFormat.migrateAttachment(attachment);
+};
+/*  render the comment of an attachment (see above), with the key column rule
+    of TaskFormat.keyLine (a key too long for the column keeps one space)  */
+export const attachmentComment = (attachment) => {
+    const lines = Object.keys(attachment).filter((key) => key !== "Data")
+        .map((key) => `${key}:`.padEnd(Math.max(11, key.length + 2)) + escapeValue(attachment[key]));
+    let text = "";
+    if (attachment.Data !== undefined) {
+        const data = attachment.Data.replace(/\n$/, "");
+        lines.push("Data:".padEnd(11) + (attachment.Data !== "" && !attachment.Data.endsWith("\n") ? "|4-" : "|4+"));
+        if (isMarkdown(attachment.Type))
+            text = data;
+        else {
+            const fence = "`".repeat(Math.max(3, ...Array.from(data.matchAll(/`+/g), (run) => run[0].length + 1)));
+            const lang = /diff/i.test(attachment.Type ?? "") ? "diff" : /yaml/i.test(attachment.Type ?? "") ? "yaml" : "";
+            text = `${fence}${lang}\n${data}${data !== "" ? "\n" : ""}${fence}`;
+        }
+    }
+    return `<!-- ase:attachment\n${lines.join("\n")}\n-->\n${text}`;
+};
+/*  determine the operations synchronizing the comments (given by their attachments)
+    with the wanted attachments: the attachments of their longest common subsequence
+    keep their comments untouched, and in each gap before a kept attachment (and in the
+    final gap) the remaining ones are paired by position and updated, with surplus
+    comments deleted and surplus attachments created, so deleting or changing an
+    attachment touches its own comment only (and never the ones of others, like the
+    comments of humans); as comments can only be appended, an attachment inserted
+    before a kept one falls back to the rewriting of all comments by position  */
+export const attachmentSync = (current, wanted) => {
+    /*  determine the equality of all attachment pairs and the lengths
+        of the longest common subsequences of all suffix pairs  */
+    const n = current.length;
+    const m = wanted.length;
+    const eq = Array.from({ length: n }, () => new Array(m).fill(false));
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--)
+        for (let j = m - 1; j >= 0; j--) {
+            eq[i][j] = same(current[i], wanted[j]);
+            lcs[i][j] = eq[i][j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    /*  determine the pairs of the longest common subsequence (plus the end as sentinel)  */
+    const pairs = [];
+    for (let i = 0, j = 0; i < n && j < m;) {
+        if (eq[i][j])
+            pairs.push([i++, j++]);
+        else if (lcs[i + 1][j] >= lcs[i][j + 1])
+            i++;
+        else
+            j++;
+    }
+    pairs.push([n, m]);
+    /*  synchronize the gaps before the pairs  */
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    for (const [pi, pj] of pairs) {
+        const olds = pi - i;
+        const news = pj - j;
+        if (news > olds && pi < n) {
+            /*  fallback: rewrite all comments by position  */
+            ops.length = 0;
+            for (let k = 0; k < Math.max(n, m); k++) {
+                if (k >= m)
+                    ops.push({ op: "delete", index: k });
+                else if (k >= n)
+                    ops.push({ op: "create", attachment: wanted[k] });
+                else if (!eq[k][k])
+                    ops.push({ op: "update", index: k, attachment: wanted[k] });
+            }
+            break;
+        }
+        for (let k = 0; k < Math.max(olds, news); k++) {
+            if (k >= news)
+                ops.push({ op: "delete", index: i + k });
+            else if (k >= olds)
+                ops.push({ op: "create", attachment: wanted[j + k] });
+            else
+                ops.push({ op: "update", index: i + k, attachment: wanted[j + k] });
+        }
+        i = pi + 1;
+        j = pj + 1;
+    }
+    return ops;
+};

package/dst/ase-task-store-plugin-api.js

@@ -0,0 +1,6 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+export {};