@llm4ts/shell 2.12.0 → 2.13.0

package/kits/soap-ace/flows/lib/soap/Classification.js

@@ -0,0 +1,254 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { choice } from "@llm4ts/core/judgment/Schemas";
+import { certaintyOf, decide } from "@llm4ts/flow/Judgment";
+import { ComplexTypeDef, elementByName, typeByName } from "./Catalog.js";
+// Operation classification (read / mutating) decides two things: whether
+// the tool may call an operation at all in a given environment, and which
+// REST verb the design gives it. The tool only proposes: a name heuristic
+// always, a `Judgment` answer when a judgment seat is configured. The human
+// confirms by editing `operations.md` and flipping its status to
+// `confirmed`; until then every operation counts as unclassified and cannot
+// be called. An existing file is never overwritten.
+export const OperationClass = Schema.Literals(["read", "mutating", "unclassified"]);
+export class OperationsFileError extends Schema.TaggedError()("OperationsFileError", {
+    line: Schema.Int,
+    detail: Schema.String
+}) {
+    get message() {
+        return `operations.md:${this.line}: ${this.detail}`;
+    }
+}
+// Italian and English verbs seen in bank SOAP estates. Matched against the
+// operation name's leading word (camelCase, snake_case, or PascalCase).
+const readVerbs = [
+    "cerca",
+    "ricerca",
+    "leggi",
+    "lettura",
+    "lista",
+    "elenca",
+    "elenco",
+    "dettaglio",
+    "visualizza",
+    "consulta",
+    "verifica",
+    "controlla",
+    "calcola",
+    "simula",
+    "stato",
+    "get",
+    "list",
+    "find",
+    "search",
+    "read",
+    "inquiry",
+    "inquire",
+    "query",
+    "retrieve",
+    "check",
+    "validate",
+    "fetch",
+    "lookup",
+    "view",
+    "count"
+];
+const mutatingVerbs = [
+    "inserisci",
+    "inserimento",
+    "crea",
+    "creazione",
+    "aggiorna",
+    "aggiornamento",
+    "modifica",
+    "cancella",
+    "elimina",
+    "revoca",
+    "annulla",
+    "conferma",
+    "esegui",
+    "blocca",
+    "sblocca",
+    "autorizza",
+    "invia",
+    "registra",
+    "apri",
+    "chiudi",
+    "attiva",
+    "disattiva",
+    "storna",
+    "create",
+    "insert",
+    "add",
+    "update",
+    "modify",
+    "set",
+    "delete",
+    "remove",
+    "cancel",
+    "confirm",
+    "execute",
+    "submit",
+    "approve",
+    "authorize",
+    "block",
+    "unblock",
+    "open",
+    "close",
+    "activate",
+    "deactivate",
+    "send",
+    "register",
+    "post",
+    "put",
+    "transfer",
+    "pay"
+];
+/** The operation name's first word, lower-cased. */
+export const leadingWord = (name) => {
+    const match = /^[a-z]+|^[A-Z][a-z]+|^[A-Z]+(?![a-z])/.exec(name.replace(/^[_\W]+/, ""));
+    return (match?.[0] ?? name).toLowerCase();
+};
+export const heuristicClass = (name) => {
+    const word = leadingWord(name);
+    if (readVerbs.includes(word))
+        return { class: "read", reason: `name starts with "${word}"` };
+    if (mutatingVerbs.includes(word)) {
+        return { class: "mutating", reason: `name starts with "${word}"` };
+    }
+    return { class: "unclassified", reason: `no known verb in "${word}"` };
+};
+const fieldNames = (catalog, element) => {
+    if (element === undefined)
+        return [];
+    const type = typeByName(catalog, elementByName(catalog, element)?.type ?? "");
+    return type instanceof ComplexTypeDef ? type.fields.map((field) => field.name) : [];
+};
+const classQuestion = choice("Classify this SOAP operation of a bank's backend service. Would calling it change state in the backend (create, update, delete, confirm, execute, block, send), or does it only read?", {
+    read: "Only reads or computes: inquiries, lists, details, checks, simulations. Calling it twice has no additional effect.",
+    mutating: "Changes state: creates, updates, deletes, confirms, executes, blocks, revokes, or sends something."
+});
+/** Ask the judgment for one operation; `undefined` when it fails or does not answer. */
+export const judgeClass = (judgment, catalog, operation) => judgment
+    .judge({
+    state: {
+        operation: operation.name,
+        soapAction: operation.soapAction,
+        documentation: operation.documentation ?? "",
+        requestFields: fieldNames(catalog, operation.input),
+        responseFields: fieldNames(catalog, operation.output),
+        faults: operation.faults.map((fault) => fault.name)
+    },
+    questions: { class: classQuestion }
+})
+    .pipe(Effect.map((result) => {
+    const answer = result.answers["class"];
+    if (answer?.type !== "choice")
+        return undefined;
+    if (answer.choice !== "read" && answer.choice !== "mutating")
+        return undefined;
+    return { class: answer.choice, confidence: certaintyOf(answer), decision: decide(answer) };
+}), Effect.orElseSucceed(() => undefined));
+/**
+ * Combine the two signals. A judgment the policy would act on wins; one it
+ * would hold is ignored; in between, it wins only when the heuristic had no
+ * opinion. Disagreement stays visible in the file for the human to settle.
+ */
+export const proposeClass = (operation, heuristic, judged) => {
+    const proposed = judged === undefined || judged.decision === "hold"
+        ? heuristic.class
+        : judged.decision === "act" || heuristic.class === "unclassified"
+            ? judged.class
+            : heuristic.class;
+    return { operation, proposed, heuristic, judged };
+};
+export const classifyOperations = (catalog, judgment) => Effect.forEach(catalog.operations, (operation) => Effect.map(judgment === undefined
+    ? Effect.succeed(undefined)
+    : judgeClass(judgment, catalog, operation), (judged) => proposeClass(operation.name, heuristicClass(operation.name), judged)));
+const describeProposal = (proposal) => {
+    const judged = proposal.judged === undefined
+        ? ""
+        : `; judgment: ${proposal.judged.class} ${proposal.judged.confidence.toFixed(2)} (${proposal.judged.decision})`;
+    return `heuristic: ${proposal.heuristic.class}, ${proposal.heuristic.reason}${judged}`;
+};
+export const renderOperationsFile = (service, catalog, proposals) => {
+    const lines = [
+        `# Operations: ${service}`,
+        "",
+        "Status: proposed",
+        "",
+        "Review every `class:` below (read | mutating | unclassified), then change the",
+        "status above to `confirmed`. Until then every operation is unclassified:",
+        "nothing can be called, and the design cannot choose REST verbs. An",
+        "unclassified operation stays uncallable after confirmation. This file is",
+        "never overwritten; delete it to get fresh proposals.",
+        ""
+    ];
+    for (const proposal of proposals) {
+        const operation = catalog.operations.find((candidate) => candidate.name === proposal.operation);
+        lines.push(`## ${proposal.operation}`, "");
+        if (operation?.documentation !== undefined)
+            lines.push(operation.documentation, "");
+        lines.push(`- class: ${proposal.proposed}`, `- evidence: ${describeProposal(proposal)}`, "");
+    }
+    return lines.join("\n");
+};
+export const parseOperationsFile = (text) => Effect.suspend(() => {
+    const lines = text.split(/\r?\n/);
+    let confirmed;
+    let current;
+    const classes = new Map();
+    for (const [index, raw] of lines.entries()) {
+        const line = raw.trim();
+        const status = /^status:\s*(\S+)\s*$/i.exec(line);
+        if (status !== null && current === undefined) {
+            const value = status[1]?.toLowerCase();
+            if (value !== "proposed" && value !== "confirmed") {
+                return Effect.fail(new OperationsFileError({
+                    line: index + 1,
+                    detail: `status must be proposed or confirmed, found ${status[1] ?? ""}`
+                }));
+            }
+            confirmed = value === "confirmed";
+            continue;
+        }
+        const heading = /^##\s+(\S+)\s*$/.exec(line);
+        if (heading !== null) {
+            current = heading[1];
+            continue;
+        }
+        const declared = /^-\s*class:\s*(\S+)\s*$/i.exec(line);
+        if (declared !== null) {
+            if (current === undefined) {
+                return Effect.fail(new OperationsFileError({ line: index + 1, detail: "class: outside an operation" }));
+            }
+            const value = declared[1]?.toLowerCase();
+            if (value !== "read" && value !== "mutating" && value !== "unclassified") {
+                return Effect.fail(new OperationsFileError({
+                    line: index + 1,
+                    detail: `class of ${current} must be read, mutating, or unclassified`
+                }));
+            }
+            if (classes.has(current)) {
+                return Effect.fail(new OperationsFileError({ line: index + 1, detail: `${current} is classified twice` }));
+            }
+            classes.set(current, value);
+        }
+    }
+    if (confirmed === undefined) {
+        return Effect.fail(new OperationsFileError({ line: 1, detail: "missing Status: line" }));
+    }
+    return Effect.succeed({ confirmed, classes });
+});
+/** The class the tool acts on: only a confirmed file counts. */
+export const effectiveClass = (file, operation) => file === undefined || !file.confirmed
+    ? "unclassified"
+    : (file.classes.get(operation) ?? "unclassified");
+/** Catalog operations the file does not mention, and file entries the catalog lacks. */
+export const operationsDrift = (file, catalog) => {
+    const names = new Set(catalog.operations.map((operation) => operation.name));
+    return {
+        missing: [...names].filter((name) => !file.classes.has(name)),
+        unknown: [...file.classes.keys()].filter((name) => !names.has(name))
+    };
+};