@webda/content-mapper 0.0.0-stage → 4.0.0-beta.4

package/lib/schema/action.js

@@ -0,0 +1,190 @@
+/**
+ * Action schemas — the `<Class>.<method>.input` and `.output` entries in the
+ * top-level `schemas` map.
+ *
+ * An `@Action` or `@Operation` method gets two schemas describing its call:
+ * one for the arguments, one for what it resolves to. They are built very
+ * differently, and the asymmetry is visible in the committed artefact:
+ *
+ * - `.input` is a **hand-built** object whose properties are one generated
+ *   document per parameter, each stripped of its `$schema`. The root never
+ *   passed through the converter, so it has no `$schema`, no
+ *   `additionalProperties`, and its keys stay in declaration order.
+ * - `.output` **is** a generated document, `$schema` and all, taken from the
+ *   resolved return type.
+ *
+ * Both are then flattened by {@link normalizeDefinitions}.
+ */
+import { SignatureKind, SymbolFlags } from "typescript/unstable/sync";
+import * as is from "typescript/unstable/ast/is";
+import { SchemaConverter } from "./converter.js";
+/**
+ * Schema for an action's arguments.
+ *
+ * Every parameter is included — there is no filter for `context` / `ctx`, so
+ * an `OperationContext` argument is expanded in full. That is odd for
+ * something called an operation *input*, and it is what the committed
+ * artefact contains, so it is reproduced rather than improved here.
+ * @param method - the decorated method
+ * @param options - project and checker
+ * @returns the arguments schema
+ */
+export function generateActionInput(method, options) {
+    const { checker, project } = options;
+    const signature = callSignatureOf(method, options);
+    // Hand-built, not converted: this root is why `.input` carries no
+    // `$schema` and keeps its keys in declaration order.
+    const schema = { type: "object", properties: {} };
+    const required = [];
+    for (const parameter of signature?.getParameters() ?? []) {
+        const converter = new SchemaConverter({ project, checker, mode: "input" });
+        const parameterType = checker.getTypeOfSymbolAtLocation(parameter, method.parent);
+        const parameterSchema = converter.fromType(parameterType, method.parent);
+        delete parameterSchema.$schema;
+        schema.properties[parameter.name] = parameterSchema;
+        if (!isOptionalParameter(parameter, project))
+            required.push(parameter.name);
+    }
+    // Omitted entirely when empty, and in declaration order rather than sorted
+    // — unlike every `required` the converter itself produces.
+    if (required.length > 0)
+        schema.required = required;
+    return normalizeDefinitions(schema);
+}
+/**
+ * Schema for what an action resolves to.
+ * @param method - the decorated method
+ * @param options - project and checker
+ * @returns the return schema, or undefined when it cannot be resolved
+ */
+export function generateActionOutput(method, options) {
+    const { checker, project } = options;
+    const signature = callSignatureOf(method, options, true);
+    if (!signature)
+        return undefined;
+    const returned = checker.getReturnTypeOfSignature(signature);
+    const resolved = unwrapPromise(returned, checker);
+    if (!resolved)
+        return undefined;
+    const converter = new SchemaConverter({ project, checker, mode: "output" });
+    return normalizeDefinitions(converter.fromType(resolved, method.parent));
+}
+/**
+ * The first call signature of a method.
+ * @param method - the method declaration
+ * @param options - project and checker
+ * @param apparent - resolve through the apparent type, as the output path does
+ * @returns the signature, when the method has one
+ */
+function callSignatureOf(method, options, apparent = false) {
+    const { checker } = options;
+    const methodType = checker.getTypeAtLocation(method);
+    const source = apparent ? checker.getApparentType(methodType) : methodType;
+    return checker.getSignaturesOfType(source, SignatureKind.Call)[0];
+}
+/**
+ * Unwrap one level of `Promise<T>`.
+ *
+ * Matched by symbol name, as `@webda/compiler` does — which means a class of
+ * your own called `Promise` is unwrapped too.
+ * @param type - the declared return type
+ * @param checker - the resident checker
+ * @returns the awaited type, or the original
+ */
+function unwrapPromise(type, checker) {
+    if (type.getSymbol()?.name !== "Promise" || !type.isTypeReference())
+        return type;
+    const args = checker.getTypeArguments(type);
+    return args.length > 0 ? args[0] : type;
+}
+/**
+ * Whether a parameter may be omitted at the call site.
+ * @param parameter - the parameter symbol
+ * @param project - project used to resolve declaration handles
+ * @returns true when optional or defaulted
+ */
+function isOptionalParameter(parameter, project) {
+    if ((parameter.flags & SymbolFlags.Optional) !== 0)
+        return true;
+    return parameter.declarations.some(handle => {
+        const declaration = handle.resolve(project);
+        if (!declaration || !is.isParameterDeclaration(declaration))
+            return false;
+        return declaration.questionToken !== undefined || declaration.initializer !== undefined;
+    });
+}
+/**
+ * Hoist every nested `definitions` block to the root and drop dangling refs.
+ *
+ * Applied to action schemas only. Two real failures motivate it, both of
+ * which crash AJV rather than merely looking untidy: a bound generic keeps
+ * its `definitions` on a sub-schema where a root-relative `$ref` cannot see
+ * it, and an unbound generic produces a definition whose key does not match
+ * the `$ref` pointing at it. Hoisting fixes the first; pruning the `$ref` —
+ * leaving an unconstrained `{}` — contains the second.
+ * Accepts any JSON value: the guard against non-objects is deliberate, so
+ * callers never have to check before flattening.
+ * @param schema - the schema to flatten, mutated in place
+ * @returns the same value
+ * @typeParam T - the value type, preserved
+ */
+export function normalizeDefinitions(schema) {
+    if (!schema || typeof schema !== "object")
+        return schema;
+    const target = schema;
+    const collected = {};
+    const collect = (node) => {
+        if (!node || typeof node !== "object")
+            return;
+        if (Array.isArray(node)) {
+            node.forEach(collect);
+            return;
+        }
+        const record = node;
+        if (record.definitions && typeof record.definitions === "object") {
+            for (const [key, value] of Object.entries(record.definitions)) {
+                // First writer wins: sibling definitions sharing a key describe the
+                // same type, because the key is the type's own name.
+                collected[key] ??= value;
+            }
+            delete record.definitions;
+        }
+        for (const key of Object.keys(record)) {
+            if (key === "$ref")
+                continue;
+            collect(record[key]);
+        }
+    };
+    collect(target);
+    if (Object.keys(collected).length > 0)
+        target.definitions = { ...target.definitions, ...collected };
+    const resolvable = (ref) => {
+        if (!ref.startsWith("#/definitions/"))
+            return true;
+        const raw = ref.slice("#/definitions/".length);
+        let decoded = raw;
+        try {
+            decoded = decodeURIComponent(raw);
+        }
+        catch {
+            decoded = raw;
+        }
+        return raw in collected || decoded in collected;
+    };
+    const prune = (node) => {
+        if (!node || typeof node !== "object")
+            return;
+        if (Array.isArray(node)) {
+            node.forEach(prune);
+            return;
+        }
+        const record = node;
+        if (typeof record.$ref === "string" && !resolvable(record.$ref))
+            delete record.$ref;
+        for (const key of Object.keys(record))
+            prune(record[key]);
+    };
+    prune(target);
+    return schema;
+}
+//# sourceMappingURL=action.js.map

package/lib/schema/action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.js","sourceRoot":"","sources":["../../src/schema/action.ts"],"names":[],"mappings":"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"}

package/lib/schema/annotations.d.ts

@@ -0,0 +1,63 @@
+/**
+ * JSDoc-to-JSON-Schema annotation mapping.
+ *
+ * Webda lets a JSDoc tag set a schema keyword directly — `@minimum 0`,
+ * `@format email`, `@deprecated` — and the committed `webda.module.json`
+ * contains the results, so the classification below is not a design choice but
+ * a compatibility surface. It reproduces `@webda/schema`'s `Annotations` table
+ * and `processJsDoc` exactly, including the behaviours that look like bugs:
+ *
+ * - an unclassified tag becomes a keyword of its own name, so `@see` and
+ *   `@returns` end up in the schema, and `@type number | string` **overwrites**
+ *   the structural `type`
+ * - a repeated tag collects into an array
+ * - a tag with no text becomes `true`
+ *
+ * Those are all present in the committed output. Diverging from them is a
+ * schema change, not a fix, so it does not belong in this port.
+ */
+import type { Checker, Project, Symbol as TsSymbol } from "typescript/unstable/sync";
+import type { JSONSchema7 } from "./types.ts";
+/** How a JSDoc tag name maps onto a JSON Schema keyword. */
+export declare const Annotations: {
+    /** Emitted with a `$` prefix — `@id x` becomes `$id: "x"`. */
+    readonly dollarPrefixed: readonly ["id", "comment", "ref"];
+    /** Presence alone sets the keyword to `true`; any text is discarded. */
+    readonly boolean: readonly ["deprecated", "readOnly", "writeOnly", "exclusiveMinimum", "exclusiveMaximum"];
+    /** Tag text is copied verbatim as a string. */
+    readonly string: readonly ["title", "description", "id", "format", "pattern", "ref", "comment", "contentMediaType", "contentEncoding", "discriminator", "markdownDescription", "deprecationMessage"];
+};
+/** A JSDoc comment and its tags, already rendered to text. */
+export interface SymbolDocs {
+    /** The free-text comment, empty when absent. */
+    comment: string;
+    /** Tags in declaration order. */
+    tags: {
+        name: string;
+        text: string;
+    }[];
+}
+/**
+ * Read a symbol's JSDoc comment and tags.
+ *
+ * Tags come straight from the checker; the comment is resolved by
+ * {@link documentationOf}, which reproduces behaviour the 7.1 API dropped —
+ * see `jsdoc.ts`.
+ * @param symbol - the symbol to document
+ * @param checker - the checker resolving the documentation
+ * @param project - project used to resolve declaration handles
+ * @returns comment text and tags
+ */
+export declare function readDocs(symbol: TsSymbol, checker: Checker, project: Project): SymbolDocs;
+/**
+ * Merge a symbol's JSDoc into a schema, in place.
+ *
+ * Applied in three passes so that the precedence matches `@webda/schema`:
+ * string tags, then boolean tags, then everything else.
+ * @param definition - the schema to enrich
+ * @param symbol - the symbol whose JSDoc to read; a no-op when undefined
+ * @param checker - the checker resolving the documentation
+ * @param project - project used to resolve declaration handles
+ */
+export declare function applyDocs(definition: JSONSchema7, symbol: TsSymbol | undefined, checker: Checker, project: Project): void;
+//# sourceMappingURL=annotations.d.ts.map

package/lib/schema/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/schema/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAErF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,4DAA4D;AAC5D,eAAO,MAAM,WAAW;IACtB,8DAA8D;aAC9D,cAAc,YAAG,IAAI,EAAE,SAAS,EAAE,KAAK;IACvC,wEAAwE;aACxE,OAAO,YAAG,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,kBAAkB,EAAE,kBAAkB;IACvF,+CAA+C;aAC/C,MAAM,YACJ,OAAO,EACP,aAAa,EACb,IAAI,EACJ,QAAQ,EACR,SAAS,EACT,KAAK,EAEL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EAEjB,eAAe,EACf,qBAAqB,EACrB,oBAAoB;CAEd,CAAC;AAuBX,8DAA8D;AAC9D,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACxC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,UAAU,CAOzF;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,WAAW,EACvB,MAAM,EAAE,QAAQ,GAAG,SAAS,EAC5B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,OAAO,GACf,IAAI,CAoCN"}

package/lib/schema/annotations.js

@@ -0,0 +1,116 @@
+import { documentationOf } from "./jsdoc.js";
+/** How a JSDoc tag name maps onto a JSON Schema keyword. */
+export const Annotations = {
+    /** Emitted with a `$` prefix — `@id x` becomes `$id: "x"`. */
+    dollarPrefixed: ["id", "comment", "ref"],
+    /** Presence alone sets the keyword to `true`; any text is discarded. */
+    boolean: ["deprecated", "readOnly", "writeOnly", "exclusiveMinimum", "exclusiveMaximum"],
+    /** Tag text is copied verbatim as a string. */
+    string: [
+        "title",
+        "description",
+        "id",
+        "format",
+        "pattern",
+        "ref",
+        // Draft-07 additions.
+        "comment",
+        "contentMediaType",
+        "contentEncoding",
+        // Webda extensions.
+        "discriminator",
+        "markdownDescription",
+        "deprecationMessage"
+    ]
+};
+/**
+ * Tags whose payload TypeScript consumes as a type expression, braces or not.
+ *
+ * `parseEnumTag` and `parseThisTag` call `parseJSDocTypeExpression` with
+ * `mayOmitBraces: true`, so `@enum ["draft", "published"]` parses the array
+ * as a *type* and leaves the comment empty. The 6.x services layer reported
+ * that empty text; 7.1 hands back the raw payload instead.
+ *
+ * Reproducing 6.x here is deliberate. Webda's annotation layer turns an
+ * unrecognised tag into a keyword of its own name, so the raw payload would
+ * start populating `enum` — which is arguably what the author meant, and is
+ * also a behaviour change that produces nonsense where the union already
+ * supplied an `enum` (the two get concatenated). It belongs in its own
+ * commit, not in a port whose contract is byte-identical output.
+ *
+ * `@type` is deliberately absent: `parseTypeTag` requires braces, so
+ * `@type number | string` keeps its text in both versions — and the
+ * committed schemas contain it.
+ */
+const TYPE_EXPRESSION_TAGS = ["enum", "this"];
+/**
+ * Read a symbol's JSDoc comment and tags.
+ *
+ * Tags come straight from the checker; the comment is resolved by
+ * {@link documentationOf}, which reproduces behaviour the 7.1 API dropped —
+ * see `jsdoc.ts`.
+ * @param symbol - the symbol to document
+ * @param checker - the checker resolving the documentation
+ * @param project - project used to resolve declaration handles
+ * @returns comment text and tags
+ */
+export function readDocs(symbol, checker, project) {
+    return {
+        comment: documentationOf(symbol, checker, project),
+        tags: symbol
+            .getJsDocTags(checker)
+            .map(tag => ({ name: tag.name, text: TYPE_EXPRESSION_TAGS.includes(tag.name) ? "" : (tag.text ?? "") }))
+    };
+}
+/**
+ * Merge a symbol's JSDoc into a schema, in place.
+ *
+ * Applied in three passes so that the precedence matches `@webda/schema`:
+ * string tags, then boolean tags, then everything else.
+ * @param definition - the schema to enrich
+ * @param symbol - the symbol whose JSDoc to read; a no-op when undefined
+ * @param checker - the checker resolving the documentation
+ * @param project - project used to resolve declaration handles
+ */
+export function applyDocs(definition, symbol, checker, project) {
+    if (!symbol)
+        return;
+    const docs = readDocs(symbol, checker, project);
+    const target = definition;
+    if (docs.comment)
+        target.description = docs.comment;
+    for (const tag of docs.tags) {
+        if (!Annotations.string.includes(tag.name))
+            continue;
+        target[Annotations.dollarPrefixed.includes(tag.name) ? `$${tag.name}` : tag.name] = tag.text;
+    }
+    for (const tag of docs.tags) {
+        if (Annotations.boolean.includes(tag.name))
+            target[tag.name] = true;
+    }
+    for (const tag of docs.tags) {
+        if (Annotations.boolean.includes(tag.name) || Annotations.string.includes(tag.name))
+            continue;
+        let value;
+        try {
+            value = JSON.parse(tag.text);
+        }
+        catch {
+            value = tag.text === "" ? true : tag.text;
+        }
+        // Truthiness, not `!== undefined`: a falsy existing value is overwritten
+        // rather than collected. `@webda/schema` does the same, and the committed
+        // schemas were generated that way.
+        const existing = target[tag.name];
+        if (Array.isArray(existing)) {
+            existing.push(value);
+        }
+        else if (existing) {
+            target[tag.name] = [existing, value];
+        }
+        else {
+            target[tag.name] = value;
+        }
+    }
+}
+//# sourceMappingURL=annotations.js.map

package/lib/schema/annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/schema/annotations.ts"],"names":[],"mappings":"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"}