@capagents/forgeqe 1.0.7 → 1.0.8

package/src/ste.ts

@@ -0,0 +1,184 @@
+/**
+ * How closely a prompt follows ASD-STE100 Simplified Technical English: the share of its sentences that keep the
+ * writing rules that can be checked in text. The full standard also needs its approved-word dictionary, which is
+ * licensed; WORDS holds the common words it does not approve, each with the approved word to use instead.
+ *
+ * Rules checked, per sentence (a list item is one or more sentences):
+ * - length: an instruction has 20 words or fewer; a description has 25 or fewer;
+ * - one instruction per sentence: an instruction does not join a second one with ";" or "and then";
+ * - active voice: an instruction is not passive ("is sent", "are written");
+ * - words: no word from WORDS (e.g., "ensure", "utilize", "prior to");
+ * and per paragraph: 6 sentences or fewer.
+ *
+ * Words are counted as written; text in `code`, a {{placeholder}}, and a "quoted example" each count as one word,
+ * because each is a name the reader takes in whole.
+ */
+
+/** Common words ASD-STE100 does not approve, with the approved word to use instead. */
+export const WORDS: Record<string, string> = {
+  "additional": "more",
+  "approximately": "about",
+  "assist": "help",
+  "attempt": "try",
+  "commence": "start",
+  "comprise": "contain",
+  "e.g.": "for example",
+  "ensure": "make sure",
+  "ensures": "makes sure",
+  "etc.": "a full list, or \"and other\"",
+  "i.e.": "that is",
+  "in order to": "to",
+  "obtain": "get",
+  "prior to": "before",
+  "require": "need",
+  "requires": "needs",
+  "sufficient": "enough",
+  "terminate": "stop",
+  "utilize": "use",
+  "utilise": "use",
+  "via": "through",
+  "whilst": "while",
+  "don't": "do not",
+  "doesn't": "does not",
+  "can't": "cannot",
+  "won't": "will not",
+  "isn't": "is not",
+  "aren't": "are not",
+  "shouldn't": "do not",
+  "wouldn't": "would not",
+  "it's": "it is",
+}
+
+/** Verbs a sentence starts with when it is an instruction (after a leading "If …," or "When …," clause). */
+const VERBS = new Set(
+  (
+    "accept act add answer append apply ask assert attach avoid build call change check choose cite click close compare confirm copy count cover create " +
+    "decide delete derive describe dismiss do edit end explain fill find finish fix flag focus follow generate get give group include insert install " +
+    "join keep leave let limit link list load look make map mark mention merge move name navigate note open pass pick plan point post prefer press put " +
+    "quote raise read record refer remove rename reply report rerun resolve respond retry return review run save say scroll select send set show skip " +
+    "sort split start state stay stop summarise summarize take tell test treat trust try type update use verify wait work write never always"
+  ).split(" "),
+)
+
+const LEAD = /^(if|when|whenever|before|after|unless|while|once|until|for|in|on|with|without|where|to)\b[^,]{0,140},\s+/i
+const PASSIVE = /\b(is|are|was|were|be|been|being)\s+(\w+ly\s+)?(\w+ed|written|sent|given|made|done|shown|taken|known|seen|found|run|built|kept|left|set|put|read|chosen|broken|held)\b/i
+
+export type SentenceIssue = "length" | "two instructions" | "passive" | "word"
+
+export type SteSentence = { text: string; words: number; instruction: boolean; issues: { rule: SentenceIssue; detail: string }[] }
+
+export type SteScore = {
+  /** Sentences that keep every rule, of all sentences, 0 to 1. */
+  score: number
+  sentences: number
+  compliant: number
+  /** Paragraphs with more than 6 sentences. */
+  longParagraphs: number
+  issues: SteSentence[]
+}
+
+/** Text a reader takes in as one word: `code`, {{placeholders}}, and "quoted examples". */
+function collapse(text: string): string {
+  return text
+    .replace(/`[^`]*`/g, "CODE")
+    .replace(/\{\{[^}]*\}\}/g, "NAME")
+    .replace(/"[^"\n]{1,200}"/g, "QUOTE")
+    .replace(/“[^”\n]{1,200}”/g, "QUOTE")
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+}
+
+export function countWords(text: string): number {
+  return (collapse(text).match(/[A-Za-z0-9][\w'’./-]*/g) || []).length
+}
+
+export function isInstruction(sentence: string): boolean {
+  const s = collapse(sentence).replace(/^[\s>*_-]+/, "").replace(LEAD, "")
+  const first = (s.match(/^[A-Za-z']+/)?.[0] || "").toLowerCase()
+  return VERBS.has(first)
+}
+
+/** Sentences of a prompt, by paragraph: list items, and sentences inside them, each one; code blocks and headings left out. */
+const ITEM_MARK = "\u0001"
+
+export function steParagraphs(markdown: string): string[][] {
+  const paragraphs: string[][] = []
+  let fence = false
+  let current: string[] = []
+  const end = () => {
+    if (current.length) paragraphs.push(current)
+    current = []
+  }
+  const blocks: string[] = []
+  for (const raw of markdown.replace(/\r/g, "").split("\n")) {
+    if (/^\s*(```|~~~)/.test(raw)) {
+      fence = !fence
+      continue
+    }
+    if (fence) continue
+    const line = raw.trimEnd()
+    if (!line.trim() || /^#{1,6}\s/.test(line) || /^\s*\|/.test(line) || /^\{\{>/.test(line.trim())) {
+      if (blocks.length) blocks.push("\n")
+      blocks.push("\n")
+      continue
+    }
+    if (/^\s*([-*+]|\d+[.)])\s+/.test(line)) blocks.push("\n", ITEM_MARK + line.replace(/^\s*([-*+]|\d+[.)])\s+/, ""))
+    else blocks.push(` ${line.trim()}`)
+  }
+  // A blank line ends a paragraph. A list is not a paragraph: each item is its own, so only prose counts toward 6.
+  for (const part of blocks.join("").split(/\n\n+/)) {
+    for (const item of part.split("\n")) {
+      if (item.startsWith(ITEM_MARK)) {
+        end()
+        current = splitSentences(item.slice(ITEM_MARK.length))
+        end()
+      } else for (const sentence of splitSentences(item)) current.push(sentence)
+    }
+    end()
+  }
+  end()
+  return paragraphs.filter((p) => p.length)
+}
+
+function splitSentences(text: string): string[] {
+  const t = text.trim()
+  if (!t) return []
+  // Protect what has a full stop inside: abbreviations, versions, file names, and quoted text.
+  const masked = t.replace(/"[^"]*"|`[^`]*`|\b(e\.g|i\.e|etc|vs|approx)\.|\w\.\w/g, (m) => m.replace(/[.!?]/g, "\u0000"))
+  return masked
+    .split(/(?<=[.!?])\s+(?=[A-Z"`(*])/)
+    .map((s) => s.replace(/\u0000/g, ".").trim())
+    .filter((s) => /[A-Za-z]/.test(s))
+}
+
+export function checkSentence(text: string): SteSentence {
+  const words = countWords(text)
+  const instruction = isInstruction(text)
+  const issues: SteSentence["issues"] = []
+  const limit = instruction ? 20 : 25
+  if (words > limit) issues.push({ rule: "length", detail: `${words} words; ${instruction ? "an instruction" : "a description"} has ${limit} or fewer` })
+  const plain = collapse(text)
+  if (instruction && (/;\s+\w/.test(plain) || /,?\s+and then\s+/i.test(plain))) issues.push({ rule: "two instructions", detail: "one instruction per sentence" })
+  if (instruction && PASSIVE.test(plain)) issues.push({ rule: "passive", detail: `"${plain.match(PASSIVE)![0]}": use the active voice` })
+  const lower = ` ${plain.toLowerCase()} `
+  for (const [word, use] of Object.entries(WORDS)) {
+    const at = lower.search(new RegExp(`[^a-z]${word.replace(/[.]/g, "\\.")}[^a-z]`))
+    if (at >= 0) issues.push({ rule: "word", detail: `"${word}": use ${use}` })
+  }
+  return { text, words, instruction, issues }
+}
+
+export function steScore(markdown: string): SteScore {
+  const paragraphs = steParagraphs(markdown)
+  const all = paragraphs.flat().map(checkSentence)
+  const compliant = all.filter((s) => !s.issues.length).length
+  return {
+    score: all.length ? compliant / all.length : 1,
+    sentences: all.length,
+    compliant,
+    longParagraphs: paragraphs.filter((p) => p.length > 6).length,
+    issues: all.filter((s) => s.issues.length),
+  }
+}
+
+/** The share of sentences every built-in prompt keeps to; a project's own prompts are scored against it too. */
+export const STE_TARGET = 0.8

package/src/tui/refine-panel.tsx

@@ -49,7 +49,20 @@ export function RefinePanel(props: { state: RefineState; width: number; onChoose
           <text fg={theme.err}>{state.message}</text>
         ) : (
           <>
-            <text fg={theme.text}>{state.result.refined}</text>
+            {/* The request as it is sent: its labelled parts (Goal, Context, Steps, Rules, Result) stand out. */}
+            {state.result.refined.split("\n").map((line, i) => {
+              const label = /^(Goal|Context|Steps|Rules|Result):/.exec(line)
+              return label ? (
+                <text key={i}>
+                  <span fg={COLOR}>{label[0]}</span>
+                  <span fg={theme.text}>{line.slice(label[0].length)}</span>
+                </text>
+              ) : (
+                <text key={i} fg={line.trim() ? theme.text : undefined}>
+                  {line || " "}
+                </text>
+              )
+            })}
             {section("Checked", theme.ok, "✓", state.result.grounded.filter((g) => g.checked).map((g) => g.fact))}
             {section("Assumed", theme.warn, "~", [...state.result.grounded.filter((g) => !g.checked).map((g) => g.fact), ...state.result.assumed])}
             {section("Missing — answer these in your request", theme.err, "?", state.result.missing)}