@llm4ts/shell 2.12.0 → 2.13.1

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

@@ -0,0 +1,283 @@
+import * as Schema from "effect/Schema";
+// The typed catalog of one SOAP service: what `soap-discover` persists as
+// `catalog.json` and every later step (sample authoring, masking by field,
+// analysis, the 1:1 mapping, the REST design) reads. It is produced by the
+// deterministic WSDL/XSD reader, never by a model. Anything the reader does
+// not model is recorded as an open question instead of being guessed.
+export const CatalogVersion = 1;
+export const XsdNamespace = "http://www.w3.org/2001/XMLSchema";
+/** A qualified name in Clark notation, `{namespace}local`. */
+export const QName = Schema.String;
+export const qname = (namespace, local) => `{${namespace}}${local}`;
+export const splitClark = (name) => {
+    const close = name.indexOf("}");
+    return name.startsWith("{") && close > 0
+        ? { namespace: name.slice(1, close), local: name.slice(close + 1) }
+        : { namespace: "", local: name };
+};
+export const localName = (name) => splitClark(name).local;
+export const isBuiltin = (name) => splitClark(name).namespace === XsdNamespace;
+export const Occurs = Schema.Union([Schema.Int, Schema.Literal("unbounded")]);
+export class Facets extends Schema.Class("Facets")({
+    enumeration: Schema.optionalKey(Schema.Array(Schema.String)),
+    pattern: Schema.optionalKey(Schema.Array(Schema.String)),
+    length: Schema.optionalKey(Schema.Int),
+    minLength: Schema.optionalKey(Schema.Int),
+    maxLength: Schema.optionalKey(Schema.Int),
+    totalDigits: Schema.optionalKey(Schema.Int),
+    fractionDigits: Schema.optionalKey(Schema.Int),
+    minInclusive: Schema.optionalKey(Schema.String),
+    maxInclusive: Schema.optionalKey(Schema.String),
+    minExclusive: Schema.optionalKey(Schema.String),
+    maxExclusive: Schema.optionalKey(Schema.String),
+    whiteSpace: Schema.optionalKey(Schema.Literals(["preserve", "replace", "collapse"]))
+}) {
+}
+/** A model group (`xs:sequence`, `xs:choice`, `xs:all`) of a complex type's content. */
+export class ModelGroup extends Schema.Class("ModelGroup")({
+    /** Index of the group within its type's `groups`. */
+    id: Schema.Int,
+    kind: Schema.Literals(["sequence", "choice", "all"]),
+    minOccurs: Schema.Int,
+    maxOccurs: Occurs,
+    /** The enclosing group; absent for a group at the top of the content. */
+    parent: Schema.optionalKey(Schema.Int),
+    /** Index into the type's `fields` of the first field at or after the group's start. */
+    start: Schema.Int
+}) {
+}
+/** An element particle's own occurrence bounds, before its groups' bounds fold in. */
+export const ParticleOccurs = Schema.Struct({ min: Schema.Int, max: Occurs });
+/** A child element of a complex type's content model. */
+export class ElementField extends Schema.Class("ElementField")({
+    name: Schema.String,
+    /** Namespace of the element as it appears on the wire (`""` when unqualified). */
+    namespace: Schema.String,
+    type: QName,
+    /**
+     * Effective bounds within one instance of the type: an optional group
+     * makes its elements optional, a repeating group makes them repeat.
+     */
+    minOccurs: Schema.Int,
+    maxOccurs: Occurs,
+    nillable: Schema.Boolean,
+    /** Set when the field sits inside an `xs:choice`: the innermost choice's index within the type. */
+    choice: Schema.optionalKey(Schema.Int),
+    /** Within a choice: the alternative this field belongs to (a sequence is one alternative). */
+    branch: Schema.optionalKey(Schema.Int),
+    /** The innermost model group (index into the type's `groups`); the exact content model. */
+    group: Schema.optionalKey(Schema.Int),
+    /** The element particle's own bounds within `group`. */
+    occurs: Schema.optionalKey(ParticleOccurs),
+    /** `fixed=`: the only value the element may hold. */
+    fixed: Schema.optionalKey(Schema.String),
+    documentation: Schema.optionalKey(Schema.String)
+}) {
+}
+export class AttributeField extends Schema.Class("AttributeField")({
+    name: Schema.String,
+    /** Namespace of the attribute on the wire; absent when unqualified. */
+    namespace: Schema.optionalKey(Schema.String),
+    type: QName,
+    required: Schema.Boolean,
+    /** `fixed=`: the only value the attribute may hold. */
+    fixed: Schema.optionalKey(Schema.String),
+    documentation: Schema.optionalKey(Schema.String)
+}) {
+}
+export class ComplexTypeDef extends Schema.Class("ComplexTypeDef")({
+    _tag: Schema.tag("complex"),
+    name: QName,
+    /** True for a type declared inline in an element; its name is synthesized. */
+    anonymous: Schema.Boolean,
+    /** `xs:extension` base, already flattened into `fields`/`attributes`. */
+    base: Schema.optionalKey(QName),
+    fields: Schema.Array(ElementField),
+    /** The model groups the fields sit in (see `ElementField.group`). */
+    groups: Schema.optionalKey(Schema.Array(ModelGroup)),
+    attributes: Schema.Array(AttributeField),
+    /** Simple content (`xs:simpleContent`): the text value's type. */
+    textType: Schema.optionalKey(QName),
+    documentation: Schema.optionalKey(Schema.String)
+}) {
+}
+export class SimpleTypeDef extends Schema.Class("SimpleTypeDef")({
+    _tag: Schema.tag("simple"),
+    name: QName,
+    anonymous: Schema.Boolean,
+    /** The restriction base (an `xs:` builtin or another simple type). */
+    base: QName,
+    facets: Facets,
+    /** `xs:list` and `xs:union` types; absent for a restriction. */
+    variety: Schema.optionalKey(Schema.Literals(["list", "union"])),
+    /** A list's item type. */
+    itemType: Schema.optionalKey(QName),
+    documentation: Schema.optionalKey(Schema.String)
+}) {
+}
+export const TypeDef = Schema.Union([ComplexTypeDef, SimpleTypeDef]);
+export class ElementDecl extends Schema.Class("ElementDecl")({
+    name: QName,
+    type: QName,
+    nillable: Schema.Boolean,
+    fixed: Schema.optionalKey(Schema.String),
+    documentation: Schema.optionalKey(Schema.String)
+}) {
+}
+export const SoapVersion = Schema.Literals(["1.1", "1.2"]);
+export class FaultRef extends Schema.Class("FaultRef")({
+    name: Schema.String,
+    element: QName
+}) {
+}
+export class Operation extends Schema.Class("Operation")({
+    name: Schema.String,
+    soapAction: Schema.String,
+    soapVersion: SoapVersion,
+    binding: Schema.String,
+    /** Document/literal wrapped: the request element carries the operation name. */
+    wrapped: Schema.Boolean,
+    input: QName,
+    output: Schema.optionalKey(QName),
+    faults: Schema.Array(FaultRef),
+    documentation: Schema.optionalKey(Schema.String)
+}) {
+}
+export class Endpoint extends Schema.Class("Endpoint")({
+    service: Schema.String,
+    port: Schema.String,
+    binding: Schema.String,
+    soapVersion: SoapVersion,
+    address: Schema.String
+}) {
+}
+export const OpenQuestionCode = Schema.Literals([
+    "xsd-any",
+    "xsd-any-attribute",
+    "substitution-group",
+    "abstract",
+    "group-ref",
+    "attribute-group",
+    "complex-restriction",
+    "mixed-content",
+    "list-or-union",
+    "unresolved-type",
+    "unresolved-element",
+    "unresolved-attribute",
+    "redefine",
+    "non-literal-part",
+    "unsupported-binding",
+    "multi-part-message",
+    "missing-address"
+]);
+export class OpenQuestion extends Schema.Class("OpenQuestion")({
+    code: OpenQuestionCode,
+    /** Where: `<document>:<line>`, plus the owning type or operation when known. */
+    location: Schema.String,
+    subject: Schema.String,
+    detail: Schema.String
+}) {
+}
+export class WsdlCatalog extends Schema.Class("WsdlCatalog")({
+    version: Schema.Literal(CatalogVersion),
+    wsdlVersion: Schema.Literals(["1.1", "2.0"]),
+    targetNamespace: Schema.String,
+    /** Every document read, root first, as given or resolved. */
+    documents: Schema.Array(Schema.String),
+    endpoints: Schema.Array(Endpoint),
+    operations: Schema.Array(Operation),
+    elements: Schema.Array(ElementDecl),
+    types: Schema.Array(TypeDef),
+    openQuestions: Schema.Array(OpenQuestion)
+}) {
+}
+export const typeByName = (catalog, name) => catalog.types.find((type) => type.name === name);
+export const elementByName = (catalog, name) => catalog.elements.find((element) => element.name === name);
+export const operationByName = (catalog, name) => catalog.operations.find((operation) => operation.name === name);
+/**
+ * The content model of a complex type as a particle tree, rooted in a
+ * sequence that occurs once (an extension's base content, then its own).
+ * A catalog written before model groups were recorded is rebuilt from the
+ * fields' choice and branch ids.
+ */
+export const contentModel = (type) => {
+    const groups = type.groups ?? [];
+    const exact = type.fields.every((field) => field.group !== undefined);
+    const legacyElement = (field) => ({
+        kind: "element",
+        field,
+        min: field.minOccurs,
+        max: field.maxOccurs
+    });
+    if (!exact || groups.length === 0) {
+        // Top-level entries: a field, or the id of a choice at its first field.
+        const top = [];
+        const choices = new Map();
+        for (const field of type.fields) {
+            if (field.choice === undefined) {
+                top.push(field);
+                continue;
+            }
+            const branches = choices.get(field.choice) ?? new Map();
+            if (!choices.has(field.choice))
+                top.push(field.choice);
+            choices.set(field.choice, branches);
+            branches.set(field.branch, [...(branches.get(field.branch) ?? []), field]);
+        }
+        const children = top.map((entry) => {
+            if (typeof entry !== "number")
+                return legacyElement(entry);
+            const alternatives = [...(choices.get(entry)?.values() ?? [])].map((members) => members.length === 1 && members[0] !== undefined
+                ? legacyElement(members[0])
+                : { kind: "sequence", min: 1, max: 1, children: members.map(legacyElement) });
+            return { kind: "choice", min: 1, max: 1, children: alternatives };
+        });
+        return { kind: "sequence", min: 1, max: 1, children };
+    }
+    // Children of each group in document order: a group sits before the
+    // field it starts at; groups starting together keep their id order.
+    const entries = [];
+    const childrenOf = (parent) => entries
+        .filter((entry) => entry.parent === parent)
+        .sort((left, right) => left.order[0] - right.order[0] ||
+        left.order[1] - right.order[1] ||
+        left.order[2] - right.order[2])
+        .map((entry) => entry.build());
+    groups.forEach((group) => {
+        entries.push({
+            parent: group.parent,
+            order: [group.start, 0, group.id],
+            build: () => ({
+                kind: group.kind,
+                min: group.minOccurs,
+                max: group.maxOccurs,
+                children: childrenOf(group.id)
+            })
+        });
+    });
+    type.fields.forEach((field, index) => {
+        entries.push({
+            parent: field.group,
+            order: [index, 1, 0],
+            build: () => ({
+                kind: "element",
+                field,
+                min: field.occurs?.min ?? field.minOccurs,
+                max: field.occurs?.max ?? field.maxOccurs
+            })
+        });
+    });
+    return { kind: "sequence", min: 1, max: 1, children: childrenOf(undefined) };
+};
+/** Every element field under a particle, in order. */
+export const particleFields = (particle) => particle.kind === "element" ? [particle.field] : particle.children.flatMap(particleFields);
+/** Whether a particle can be satisfied by no elements at all. */
+export const emptiable = (particle) => {
+    if (particle.min === 0)
+        return true;
+    if (particle.kind === "element")
+        return false;
+    return particle.kind === "choice"
+        ? particle.children.some(emptiable)
+        : particle.children.every(emptiable);
+};

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))
+    };
+};