@webpieces/api-doc-model 0.0.1

package/src/extract/JsDoc.d.ts

@@ -0,0 +1,33 @@
+import * as ts from 'typescript';
+/**
+ * The PROSE half of the model: the JSDoc body, the `@format` tag and the `@mcp` override.
+ *
+ * `{@link Foo.bar}` is flattened to `Foo.bar` HERE, at this boundary, and that placement is the
+ * point: a link is a TypeScript editor affordance, and every downstream renderer — OpenAPI
+ * `description`, an MCP tool description, an HTML page — would otherwise each have to know the inline
+ * tag grammar and each get it slightly differently wrong. One flattening, at extraction.
+ */
+export declare class JsDoc {
+    /** The body text, links flattened, trimmed. Empty string when undocumented. */
+    readonly description: string;
+    /** The `@format` block tag's text, e.g. `email` / `date-time`. */
+    readonly format: string | undefined;
+    /**
+     * The `@mcp` block tag's text — the OPTIONAL agent-facing override. Undefined means the
+     * author wrote none, which a renderer answers by falling back to {@link description}. The
+     * fallback is NOT applied here: "the author wrote an agent-facing sentence" and "we reused
+     * the human one" are different facts, and only the first is worth trusting.
+     */
+    readonly mcp: string | undefined;
+    private constructor();
+    /** Read the JSDoc attached to one declaration. */
+    static read(node: ts.Node): JsDoc;
+    /**
+     * A comment's text with every inline tag replaced by its own text: `{@link Foo.bar}` -> `Foo.bar`,
+     * `{@link Foo.bar|the widget}` -> `the widget`.
+     *
+     * TypeScript hands a commented node either a plain string or an array of parts, and the link
+     * parts are the ones with structure. Both shapes are handled here so no caller has to.
+     */
+    private static flatten;
+}

package/src/extract/JsDoc.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsDoc = void 0;
+const tslib_1 = require("tslib");
+const ts = tslib_1.__importStar(require("typescript"));
+/**
+ * The PROSE half of the model: the JSDoc body, the `@format` tag and the `@mcp` override.
+ *
+ * `{@link Foo.bar}` is flattened to `Foo.bar` HERE, at this boundary, and that placement is the
+ * point: a link is a TypeScript editor affordance, and every downstream renderer — OpenAPI
+ * `description`, an MCP tool description, an HTML page — would otherwise each have to know the inline
+ * tag grammar and each get it slightly differently wrong. One flattening, at extraction.
+ */
+class JsDoc {
+    description;
+    format;
+    mcp;
+    constructor(
+    /** The body text, links flattened, trimmed. Empty string when undocumented. */
+    description, 
+    /** The `@format` block tag's text, e.g. `email` / `date-time`. */
+    format, 
+    /**
+     * The `@mcp` block tag's text — the OPTIONAL agent-facing override. Undefined means the
+     * author wrote none, which a renderer answers by falling back to {@link description}. The
+     * fallback is NOT applied here: "the author wrote an agent-facing sentence" and "we reused
+     * the human one" are different facts, and only the first is worth trusting.
+     */
+    mcp) {
+        this.description = description;
+        this.format = format;
+        this.mcp = mcp;
+    }
+    /** Read the JSDoc attached to one declaration. */
+    // webpieces-disable no-function-outside-class -- static factory; JsDoc has a private constructor so a caller cannot invent prose
+    static read(node) {
+        const symbolLike = node;
+        const blocks = symbolLike.jsDoc ?? [];
+        const bodies = [];
+        let format;
+        let mcp;
+        for (const block of blocks) {
+            bodies.push(JsDoc.flatten(block.comment));
+            for (const tag of block.tags ?? []) {
+                const name = tag.tagName.text;
+                const text = JsDoc.flatten(tag.comment);
+                if (name === 'format' && text !== '') {
+                    format = text;
+                }
+                else if (name === 'mcp' && text !== '') {
+                    mcp = text;
+                }
+            }
+        }
+        return new JsDoc(bodies.join('\n').trim(), format, mcp);
+    }
+    /**
+     * A comment's text with every inline tag replaced by its own text: `{@link Foo.bar}` -> `Foo.bar`,
+     * `{@link Foo.bar|the widget}` -> `the widget`.
+     *
+     * TypeScript hands a commented node either a plain string or an array of parts, and the link
+     * parts are the ones with structure. Both shapes are handled here so no caller has to.
+     */
+    // webpieces-disable no-function-outside-class -- private static helper of this class
+    static flatten(comment) {
+        if (comment === undefined) {
+            return '';
+        }
+        if (typeof comment === 'string') {
+            return comment.trim();
+        }
+        const parts = [];
+        for (const part of comment) {
+            if (ts.isJSDocLink(part) || ts.isJSDocLinkCode(part) || ts.isJSDocLinkPlain(part)) {
+                // `text` is whatever followed the target ('|the widget'); the NAME is the target.
+                const label = part.text.replace(/^[|\s]+/, '').trim();
+                const target = part.name ? part.name.getText() : '';
+                parts.push(label !== '' ? label : target);
+            }
+            else {
+                parts.push(part.text);
+            }
+        }
+        return parts.join('').trim();
+    }
+}
+exports.JsDoc = JsDoc;
+//# sourceMappingURL=JsDoc.js.map

package/src/extract/JsDoc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsDoc.js","sourceRoot":"","sources":["../../../../../../packages/docs/api-doc-model/src/extract/JsDoc.ts"],"names":[],"mappings":";;;;AAAA,uDAAiC;AAQjC;;;;;;;GAOG;AACH,MAAa,KAAK;IAGD;IAEA;IAOA;IAXb;IACI,+EAA+E;IACtE,WAAmB;IAC5B,kEAAkE;IACzD,MAA0B;IACnC;;;;;OAKG;IACM,GAAuB;QATvB,gBAAW,GAAX,WAAW,CAAQ;QAEnB,WAAM,GAAN,MAAM,CAAoB;QAO1B,QAAG,GAAH,GAAG,CAAoB;IACjC,CAAC;IAEJ,kDAAkD;IAClD,iIAAiI;IACjI,MAAM,CAAC,IAAI,CAAC,IAAa;QACrB,MAAM,UAAU,GAAG,IAAoB,CAAC;QACxC,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,IAAI,EAAE,CAAC;QACtC,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,IAAI,MAA0B,CAAC;QAC/B,IAAI,GAAuB,CAAC;QAE5B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAC1C,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;gBACjC,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC;gBAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBACxC,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;oBACnC,MAAM,GAAG,IAAI,CAAC;gBAClB,CAAC;qBAAM,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;oBACvC,GAAG,GAAG,IAAI,CAAC;gBACf,CAAC;YACL,CAAC;QACL,CAAC;QAED,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;;OAMG;IACH,qFAAqF;IAC7E,MAAM,CAAC,OAAO,CAAC,OAA2D;QAC9E,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,EAAE,CAAC;QACd,CAAC;QACD,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;QAC1B,CAAC;QACD,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YACzB,IAAI,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;gBAChF,kFAAkF;gBAClF,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;gBACtD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpD,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAC9C,CAAC;iBAAM,CAAC;gBACJ,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACjC,CAAC;CACJ;AApED,sBAoEC","sourcesContent":["import * as ts from 'typescript';\n\n/**\n * A node the compiler has attached JSDoc blocks to. `jsDoc` is internal to the TypeScript API and is\n * therefore not on `ts.Node`, so it is named HERE, once, instead of being cast at the use site.\n */\ntype JsDocCarrier = ts.Node & { jsDoc?: ts.JSDoc[] };\n\n/**\n * The PROSE half of the model: the JSDoc body, the `@format` tag and the `@mcp` override.\n *\n * `{@link Foo.bar}` is flattened to `Foo.bar` HERE, at this boundary, and that placement is the\n * point: a link is a TypeScript editor affordance, and every downstream renderer — OpenAPI\n * `description`, an MCP tool description, an HTML page — would otherwise each have to know the inline\n * tag grammar and each get it slightly differently wrong. One flattening, at extraction.\n */\nexport class JsDoc {\n    private constructor(\n        /** The body text, links flattened, trimmed. Empty string when undocumented. */\n        readonly description: string,\n        /** The `@format` block tag's text, e.g. `email` / `date-time`. */\n        readonly format: string | undefined,\n        /**\n         * The `@mcp` block tag's text — the OPTIONAL agent-facing override. Undefined means the\n         * author wrote none, which a renderer answers by falling back to {@link description}. The\n         * fallback is NOT applied here: \"the author wrote an agent-facing sentence\" and \"we reused\n         * the human one\" are different facts, and only the first is worth trusting.\n         */\n        readonly mcp: string | undefined,\n    ) {}\n\n    /** Read the JSDoc attached to one declaration. */\n    // webpieces-disable no-function-outside-class -- static factory; JsDoc has a private constructor so a caller cannot invent prose\n    static read(node: ts.Node): JsDoc {\n        const symbolLike = node as JsDocCarrier;\n        const blocks = symbolLike.jsDoc ?? [];\n        const bodies: string[] = [];\n        let format: string | undefined;\n        let mcp: string | undefined;\n\n        for (const block of blocks) {\n            bodies.push(JsDoc.flatten(block.comment));\n            for (const tag of block.tags ?? []) {\n                const name = tag.tagName.text;\n                const text = JsDoc.flatten(tag.comment);\n                if (name === 'format' && text !== '') {\n                    format = text;\n                } else if (name === 'mcp' && text !== '') {\n                    mcp = text;\n                }\n            }\n        }\n\n        return new JsDoc(bodies.join('\\n').trim(), format, mcp);\n    }\n\n    /**\n     * A comment's text with every inline tag replaced by its own text: `{@link Foo.bar}` -> `Foo.bar`,\n     * `{@link Foo.bar|the widget}` -> `the widget`.\n     *\n     * TypeScript hands a commented node either a plain string or an array of parts, and the link\n     * parts are the ones with structure. Both shapes are handled here so no caller has to.\n     */\n    // webpieces-disable no-function-outside-class -- private static helper of this class\n    private static flatten(comment: string | ts.NodeArray<ts.JSDocComment> | undefined): string {\n        if (comment === undefined) {\n            return '';\n        }\n        if (typeof comment === 'string') {\n            return comment.trim();\n        }\n        const parts: string[] = [];\n        for (const part of comment) {\n            if (ts.isJSDocLink(part) || ts.isJSDocLinkCode(part) || ts.isJSDocLinkPlain(part)) {\n                // `text` is whatever followed the target ('|the widget'); the NAME is the target.\n                const label = part.text.replace(/^[|\\s]+/, '').trim();\n                const target = part.name ? part.name.getText() : '';\n                parts.push(label !== '' ? label : target);\n            } else {\n                parts.push(part.text);\n            }\n        }\n        return parts.join('').trim();\n    }\n}\n"]}

package/src/extract/SourceLocation.d.ts

@@ -0,0 +1,11 @@
+import * as ts from 'typescript';
+/**
+ * Pointer-style locations, in ONE place.
+ *
+ * Every `UnmappedType` and every {@link ApiDocExtractionError} carries one, and they have to agree:
+ * an agent that is handed two different spellings of "where" for the same file cannot tell whether
+ * it is looking at one problem or two.
+ */
+export declare class SourceLocation {
+    static of(node: ts.Node): string;
+}

package/src/extract/SourceLocation.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SourceLocation = void 0;
+/**
+ * Pointer-style locations, in ONE place.
+ *
+ * Every `UnmappedType` and every {@link ApiDocExtractionError} carries one, and they have to agree:
+ * an agent that is handed two different spellings of "where" for the same file cannot tell whether
+ * it is looking at one problem or two.
+ */
+class SourceLocation {
+    // webpieces-disable no-function-outside-class -- static helper on the class that defines the format
+    static of(node) {
+        const file = node.getSourceFile();
+        if (!file) {
+            return '<unknown>';
+        }
+        const position = file.getLineAndCharacterOfPosition(node.getStart(file));
+        return `${file.fileName}:${position.line + 1}:${position.character + 1}`;
+    }
+}
+exports.SourceLocation = SourceLocation;
+//# sourceMappingURL=SourceLocation.js.map

package/src/extract/SourceLocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceLocation.js","sourceRoot":"","sources":["../../../../../../packages/docs/api-doc-model/src/extract/SourceLocation.ts"],"names":[],"mappings":";;;AAEA;;;;;;GAMG;AACH,MAAa,cAAc;IACvB,oGAAoG;IACpG,MAAM,CAAC,EAAE,CAAC,IAAa;QACnB,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI,EAAE,CAAC;YACR,OAAO,WAAW,CAAC;QACvB,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,6BAA6B,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QACzE,OAAO,GAAG,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,GAAG,CAAC,IAAI,QAAQ,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;IAC7E,CAAC;CACJ;AAVD,wCAUC","sourcesContent":["import * as ts from 'typescript';\n\n/**\n * Pointer-style locations, in ONE place.\n *\n * Every `UnmappedType` and every {@link ApiDocExtractionError} carries one, and they have to agree:\n * an agent that is handed two different spellings of \"where\" for the same file cannot tell whether\n * it is looking at one problem or two.\n */\nexport class SourceLocation {\n    // webpieces-disable no-function-outside-class -- static helper on the class that defines the format\n    static of(node: ts.Node): string {\n        const file = node.getSourceFile();\n        if (!file) {\n            return '<unknown>';\n        }\n        const position = file.getLineAndCharacterOfPosition(node.getStart(file));\n        return `${file.fileName}:${position.line + 1}:${position.character + 1}`;\n    }\n}\n"]}

package/src/extract/TypeResolver.d.ts

@@ -0,0 +1,111 @@
+import * as ts from 'typescript';
+import { DocumentedType, UnmappedType } from '../model/ApiDocModel';
+import { TypeRef } from '../model/TypeRef';
+/**
+ * Resolve declared TypeScript types into {@link TypeRef}s, registering every NAMED type it meets as
+ * a {@link DocumentedType} a renderer can `$ref`.
+ *
+ * ## It walks TYPE NODES, not checker types, and that is load-bearing
+ *
+ * `type Integer = number` resolves, in the checker, to `number` — the alias is gone. Integer-ness is
+ * therefore invisible to a checker-driven walk, and the whole reason `Integer` is the PREFERRED
+ * spelling is that it COMPOSES: `Integer[]` and `Record<string, Integer>` say exactly which thing is
+ * an integer, where a decorator on `counts?: number[]` cannot (the same ambiguity the deleted
+ * `arrayItems` argument had). Walking the written syntax is what keeps that composition readable.
+ *
+ * ## Cycles terminate BY CONSTRUCTION
+ *
+ * Every named type is ONE entry in the model, registered before its fields are walked, so a type
+ * that refers back to itself resolves to a `$ref` at the second visit and stops. There is NO depth
+ * counter anywhere — a deep-but-finite graph of 7, 20 or 200 named hops is fully expanded, because
+ * truncating one would silently publish an incomplete document. The ONLY thing that is cut is a
+ * self-referential ANONYMOUS type, and it is cut by NODE IDENTITY (it has no name to `$ref`), with an
+ * {@link UnmappedType} recorded so #982's guard has something to name.
+ */
+export declare class TypeResolver {
+    private readonly checker;
+    private readonly types;
+    private readonly unmapped;
+    /** Named types already registered (or mid-registration) — the cycle stop for the NAMED case. */
+    private readonly registered;
+    /** Anonymous type literals currently being expanded — the cycle stop for the ANONYMOUS case. */
+    private readonly expandingAnonymous;
+    constructor(checker: ts.TypeChecker);
+    /** Every named type reached so far, by name. */
+    collectedTypes(): ReadonlyMap<string, DocumentedType>;
+    /** Everything that could not be represented — recorded, never dropped. */
+    collectedUnmapped(): readonly UnmappedType[];
+    /** Resolve one written type, registering whatever named types it reaches. */
+    resolve(node: ts.TypeNode, ownerName: string): TypeRef;
+    /** `string` / `number` / `boolean` / `null` / `unknown`, or undefined for anything else. */
+    private static keywordOf;
+    private resolveLiteral;
+    /**
+     * A union, after `null` / `undefined` have been dropped (the FIELD records those as nullable /
+     * optional — see {@link fieldOf} — because `{}` and `{x: null}` are different wire documents).
+     *
+     * Three outcomes, in this order:
+     *  - every branch a string literal  -> an ENUM
+     *  - one branch left                -> that branch
+     *  - every branch a named object    -> a UNION, with a DERIVED discriminator when every branch
+     *                                      carries the same property typed as ONE string literal
+     *  - anything else                  -> an {@link UnmappedType}. No invented discriminator, ever:
+     *                                      a union TypeScript itself cannot narrow is not one a
+     *                                      renderer may claim to.
+     */
+    private resolveUnion;
+    /** `null` and `undefined` branches — recorded as nullable/optional on the FIELD, not in the union. */
+    private static isNullish;
+    /**
+     * The DERIVED discriminator: the property every branch declares as exactly ONE string literal,
+     * with a value no two branches share. Derived, never invented — if the source does not narrow,
+     * neither does the document.
+     */
+    private deriveDiscriminator;
+    /** A union written as a named `type X = A | B` becomes its own model entry, so #982 can `$ref` it. */
+    private registerUnionAlias;
+    /**
+     * `Integer`, `Array<T>`, `Record<string, V>`, `Promise<T>`, and everything named — an interface,
+     * a class, or a type alias. Anything else (a `Map`, a `Date`, a generic parameter) is recorded
+     * rather than guessed at.
+     */
+    private resolveReference;
+    /** `type X = ...` — registered under X when it has a shape of its own, else transparent. */
+    private resolveAlias;
+    /** A TS `enum` of string members — the one non-union enum shape a document can carry. */
+    private registerStringEnum;
+    /**
+     * Register a named object shape, RESERVING THE NAME BEFORE walking its fields. That order is the
+     * whole cycle story: a type that refers back to itself meets `registered.has(name)` on the second
+     * visit and resolves to a `$ref`, so the walk terminates with no counter and no truncation.
+     */
+    private registerNamedObject;
+    /**
+     * An inline `{ ... }`. It has no name to `$ref`, so it is registered under an OWNER-DERIVED one
+     * (`Parent.field`) — a renderer needs a target, and a name derived from where the shape is
+     * written is the only honest one available.
+     *
+     * A self-referential anonymous type is cut HERE, by NODE IDENTITY. It cannot be a `$ref` (there
+     * is no declared name to point at) and it cannot be expanded (it would never end), so it is
+     * recorded as unmapped and the walk returns.
+     */
+    private resolveAnonymousObject;
+    /** ONE property of a DTO — its type, its optionality, its prose and its numeric constraints. */
+    private fieldOf;
+    /**
+     * `@WpMin` / `@WpMax` on a non-numeric field is a BUILD FAILURE, not a warning. A minimum on a
+     * string is not something a renderer can emit sensibly, and a document that silently dropped it
+     * would publish a contract weaker than the one its author wrote down.
+     */
+    private assertNumericConstraintsFit;
+    /** `@WpInt()` decorates the FIELD, so the integer flag is pushed onto the right leaf. */
+    private static markInteger;
+    private static declaresUndefined;
+    private static declaresNull;
+    private static hasDecorator;
+    private static decoratorCall;
+    private numericArgument;
+    /** The declaration a type name points at, through imports and aliases. */
+    private declarationOf;
+    private recordUnmapped;
+}