@oneuptime/common 13.0.0 → 13.0.1

package/build/dist/Server/Utils/CodeRepository/GitHub/GitHubCommandParser.js

@@ -0,0 +1,297 @@
+import GitHubCommandType, { GitHubCommandSurface, } from "../../../../Types/CodeRepository/GitHubCommand";
+/*
+ * Named rather than inlined at the call sites: eslint's wrap-regex wants a
+ * regex literal that is the receiver of a method call wrapped in parentheses,
+ * and prettier removes those parentheses again — a fix loop with no fixed
+ * point. A named constant satisfies both, and reads better anyway.
+ */
+// A markdown blockquote line, including GitHub's nested "> >" quote-replies.
+const BLOCKQUOTE_LINE = /^[ \t]*>/;
+// What may follow a verb for it to count as the whole verb.
+const VERB_TERMINATOR = /^[\s:,.!?]/;
+// Whether an instruction contains a word at all.
+const ALPHANUMERIC = /[A-Za-z0-9]/;
+/*
+ * Turns the body of a GitHub issue / pull request comment into a command for
+ * the OneUptime app, or into null when the app was not addressed at all.
+ *
+ * Everything here is a PURE function of (body, appSlug, surface): no IO, no
+ * environment reads. That is deliberate — this is the gate that decides
+ * whether arbitrary text from a repository is allowed to start a paid agent
+ * run, so it has to be exhaustively testable on its own.
+ *
+ * Three properties matter more than richness of grammar:
+ *
+ *   1. A mention inside a QUOTE or a CODE BLOCK is not a command. GitHub's
+ *      "Quote reply" button copies the parent comment into a `>` block, so
+ *      without this every reply to one of the app's own comments would
+ *      re-trigger it — a comment loop that spends the project's fix budget.
+ *
+ *   2. A mention must be a whole word. `@oneuptime-staging` and
+ *      `support@oneuptime.com` are not mentions of `@oneuptime`.
+ *
+ *   3. An unrecognized verb is NOT an error. "@oneuptime the retry loop here
+ *      looks wrong" is the most natural way to ask for a revision, so the
+ *      surface decides the default: pull request -> Revise, issue ->
+ *      Implement. Only an EMPTY mention falls back to Help.
+ */
+class GitHubCommandParser {
+    /*
+     * Remove every region a mention must not count in, in the order they nest:
+     * fenced code blocks (which may themselves contain `>` lines and backticks),
+     * then inline code spans, then blockquotes.
+     *
+     * Fences are scanned line by line rather than with one regex: an UNCLOSED
+     * fence has to swallow the rest of the comment, and expressing that with a
+     * lazy quantifier and an end-of-input alternative is exactly the kind of
+     * subtlety that silently stops working.
+     */
+    static stripNonCommandRegions(body) {
+        const lines = body.split("\n");
+        const original = [];
+        const searchable = [];
+        let openFence = null;
+        for (const line of lines) {
+            const fence = line.match(/^[ \t]*(```+|~~~+)/);
+            if (openFence) {
+                /*
+                 * Inside a fence: only a closing fence of the SAME character and AT
+                 * LEAST the same length ends it (CommonMark). Comparing only the
+                 * character would let a ``` line inside a ```` block close it, and
+                 * everything after would be read as live text — the loop guard
+                 * failing open on exactly the comment most likely to contain a
+                 * mention: one showing someone how to use the app.
+                 */
+                if (fence &&
+                    fence[1] &&
+                    fence[1][0] === openFence[0] &&
+                    fence[1].length >= openFence.length) {
+                    openFence = null;
+                }
+                continue;
+            }
+            if (fence && fence[1]) {
+                openFence = fence[1];
+                continue;
+            }
+            // Blockquotes, including the nested `> >` GitHub writes for quote-replies.
+            if (BLOCKQUOTE_LINE.test(line)) {
+                continue;
+            }
+            original.push(line);
+            /*
+             * Inline code is BLANKED, not removed — replaced by the same number of
+             * spaces. Removing it would shift every index after it, and the
+             * instruction is sliced out of the ORIGINAL text so that a request like
+             * "revise this to use \`Array<T>\`" reaches the agent with the code the
+             * person actually typed. Blanking keeps the two strings the same length,
+             * so one index means the same place in both.
+             */
+            searchable.push(line.replace(/`[^`\n]*`/g, (match) => {
+                return " ".repeat(match.length);
+            }));
+        }
+        return {
+            original: original.join("\n"),
+            searchable: searchable.join("\n"),
+        };
+    }
+    // Escape a GitHub App slug for safe embedding in a RegExp.
+    static escapeForRegExp(value) {
+        return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    /*
+     * Matches `@slug` and `@slug[bot]` where a person actually addressed the app.
+     *
+     * Both guards are allow-lists rather than deny-lists, because the deny-list
+     * versions were wrong in ways that cost real money:
+     *
+     *   - LEADING. A negated ASCII class let "café@oneuptime.com" through — the
+     *     "é" is not an ASCII word character, so the address parsed as a mention
+     *     and started a paid run. An address's local part can end in any letter
+     *     in any script, so the only sound rule is to name what MAY precede a
+     *     mention: nothing (start of text), whitespace, or the punctuation
+     *     people actually wrap a mention in.
+     *
+     *   - TRAILING. `\b` sits happily between "oneuptime" and the "-" of
+     *     "@oneuptime-staging", a different account. And a plain
+     *     "not a letter or digit" lookahead let "@oneuptime.com is our site"
+     *     through. So a following "." is refused only when it starts something
+     *     domain-shaped; "thanks @oneuptime." at the end of a sentence is still
+     *     a mention.
+     */
+    static buildMentionRegExp(appSlug) {
+        const slug = GitHubCommandParser.escapeForRegExp(appSlug.trim());
+        return new RegExp(`(^|[\\s(\\[{*_~"'\`])@${slug}(\\[bot\\])?(?![A-Za-z0-9_-])(?!\\.[A-Za-z0-9])`, "gi");
+    }
+    /*
+     * The verb is only recognized at the START of the instruction. "@oneuptime
+     * the reviewer asked for X" must not be read as a Review command just
+     * because the word appears somewhere in it.
+     */
+    static matchVerb(instruction) {
+        const normalized = instruction
+            .toLowerCase()
+            .replace(/^[\s:,.!?-]+/, "");
+        for (const entry of GitHubCommandParser.verbPhrases) {
+            for (const phrase of entry.phrases) {
+                if (normalized === phrase) {
+                    return entry.commandType;
+                }
+                if (normalized.startsWith(phrase) &&
+                    VERB_TERMINATOR.test(normalized.slice(phrase.length))) {
+                    return entry.commandType;
+                }
+            }
+        }
+        return null;
+    }
+    static defaultCommandFor(surface) {
+        return surface === GitHubCommandSurface.PullRequest
+            ? GitHubCommandType.Revise
+            : GitHubCommandType.Implement;
+    }
+    /*
+     * Whether a candidate instruction says anything at all.
+     *
+     * "@mention 👍" and "@mention !!" are not requests to start work, but they
+     * are not empty strings either, so a bare truthiness check sent them to the
+     * surface default and spent a full agent run on a thumbs-up. A command needs
+     * a word in it.
+     */
+    static hasSubstance(instruction) {
+        return ALPHANUMERIC.test(instruction);
+    }
+    /*
+     * Returns null when the app was not mentioned in a commandable position —
+     * the overwhelmingly common case, since this runs on every comment in every
+     * connected repository.
+     *
+     * Every mention is considered, not just the first. A comment that mentions
+     * the app in passing and THEN gives it an order — "@oneuptime[bot] said it
+     * was flaky, so @oneuptime review this again" — is ordinary English, and
+     * reading only the first mention turns the order into part of an
+     * instruction string nobody wrote. So: the first mention followed by a
+     * recognized verb wins; failing that, the first mention that says anything
+     * at all; failing that, Help.
+     */
+    static parse(data) {
+        if (!data.body || !data.appSlug || !data.appSlug.trim()) {
+            return null;
+        }
+        const stripped = GitHubCommandParser.stripNonCommandRegions(data.body);
+        const mentionRegExp = GitHubCommandParser.buildMentionRegExp(data.appSlug);
+        let sawMention = false;
+        let firstSubstantive = null;
+        let mention = null;
+        while ((mention = mentionRegExp.exec(stripped.searchable)) !== null) {
+            sawMention = true;
+            /*
+             * Sliced out of the ORIGINAL text at the same index — see
+             * stripNonCommandRegions for why the two strings stay index-aligned.
+             */
+            const instruction = stripped.original
+                .slice(mention.index + mention[0].length)
+                .trim();
+            if (!GitHubCommandParser.hasSubstance(instruction)) {
+                continue;
+            }
+            const verb = GitHubCommandParser.matchVerb(instruction);
+            if (verb) {
+                return { commandType: verb, instruction: instruction };
+            }
+            if (!firstSubstantive) {
+                firstSubstantive = {
+                    commandType: GitHubCommandParser.defaultCommandFor(data.surface),
+                    instruction: instruction,
+                };
+            }
+        }
+        if (firstSubstantive) {
+            return firstSubstantive;
+        }
+        if (sawMention) {
+            /*
+             * A mention with nothing to act on — bare, or only punctuation. A
+             * request for orientation, not a licence to start work on whatever the
+             * thread happens to be about.
+             */
+            return { commandType: GitHubCommandType.Help, instruction: "" };
+        }
+        return null;
+    }
+    /*
+     * Whether a command can be carried out on the surface it was written on.
+     * Kept beside the grammar so the two cannot drift: a Review on an issue and
+     * an Implement on a pull request are both real user mistakes that deserve a
+     * helpful reply rather than a silently dropped comment.
+     */
+    static isSupportedOnSurface(data) {
+        if (data.commandType === GitHubCommandType.Review ||
+            data.commandType === GitHubCommandType.Revise) {
+            return data.surface === GitHubCommandSurface.PullRequest;
+        }
+        if (data.commandType === GitHubCommandType.Implement) {
+            return data.surface === GitHubCommandSurface.Issue;
+        }
+        return true;
+    }
+}
+/*
+ * Explicit verbs that OVERRIDE the surface default. Longest phrases first so
+ * "code review" is not shadowed by "review".
+ *
+ * Deliberately small. Every phrase here is one a user could not plausibly
+ * mean any other way; anything ambiguous ("fix this", "sort this out") is
+ * better served by the surface default than by a guess.
+ */
+GitHubCommandParser.verbPhrases = [
+    {
+        phrases: [
+            "code review",
+            "please review",
+            "can you review",
+            "review this",
+            "review",
+        ],
+        commandType: GitHubCommandType.Review,
+    },
+    {
+        phrases: [
+            "please revise",
+            "revise this",
+            "revise",
+            "rework this",
+            "rework",
+            "redo this",
+            "redo",
+        ],
+        commandType: GitHubCommandType.Revise,
+    },
+    {
+        phrases: [
+            "please implement",
+            "implement this",
+            "implement",
+            "work on this",
+            "work on it",
+            "pick this up",
+            "take this",
+        ],
+        commandType: GitHubCommandType.Implement,
+    },
+    {
+        phrases: ["what can you do", "commands", "usage", "help"],
+        commandType: GitHubCommandType.Help,
+    },
+    {
+        phrases: ["status", "progress"],
+        commandType: GitHubCommandType.Status,
+    },
+    {
+        phrases: ["cancel", "stop", "abort"],
+        commandType: GitHubCommandType.Cancel,
+    },
+];
+export default GitHubCommandParser;
+//# sourceMappingURL=GitHubCommandParser.js.map

package/build/dist/Server/Utils/CodeRepository/GitHub/GitHubCommandParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubCommandParser.js","sourceRoot":"","sources":["../../../../../../Server/Utils/CodeRepository/GitHub/GitHubCommandParser.ts"],"names":[],"mappings":"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"}