@nestia/migrate 14.0.0 → 14.0.2

package/lib/executable/NestiaMigrateInquirer.js

@@ -12,8 +12,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NestiaMigrateInquirer = void 0;
 const commander_1 = require("commander");
 const inquirer_1 = require("inquirer");
+/**
+ * Reads the options of the command from flags, asking interactively for what is
+ * missing.
+ *
+ * @evidence contracts/common.md#principled-implementation Each option is taken from its flag when given, and asked with a prompt otherwise, so the same command runs non-interactively when every flag is present.
+ * @evidence contracts/common.md#clear-and-simple-design One function and the output type; the prompt helpers are local.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The prompts are the standard `inquirer` ones, and a flag always wins over a prompt.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 var NestiaMigrateInquirer;
 (function (NestiaMigrateInquirer) {
+    /**
+     * Parses the flags and asks for the missing options.
+     *
+     * A boolean flag given without a value is `true`, and one given a value is
+     * true only for the text `true`.
+     *
+     * @evidence contracts/common.md#principled-implementation Commander parses the flags, the action asks a prompt for each undefined option, and boolean flags are normalized by one rule, so the result has every field set.
+     * @evidence contracts/common.md#clear-and-simple-design One function that wires the parser and the prompts around one action.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It asks only for what is missing.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the boolean flag rule.
+     */
     NestiaMigrateInquirer.parse = () => __awaiter(this, void 0, void 0, function* () {
         // PREPARE ASSETS
         commander_1.program.option("--mode [nest/sdk]", "migration mode");
@@ -55,35 +75,17 @@ var NestiaMigrateInquirer;
         });
         // DO CONSTRUCT
         return action((partial) => __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e;
+            var _a, _b, _c, _d, _e, _f, _g;
             (_a = partial.mode) !== null && _a !== void 0 ? _a : (partial.mode = yield select("mode")("Migration mode")(["NestJS", "SDK"], (value) => (value === "NestJS" ? "nest" : "sdk")));
             (_b = partial.input) !== null && _b !== void 0 ? _b : (partial.input = yield input("input")("Swagger file location"));
             (_c = partial.output) !== null && _c !== void 0 ? _c : (partial.output = yield input("output")("Response directory path"));
             (_d = partial.package) !== null && _d !== void 0 ? _d : (partial.package = yield input("package")("Package name"));
-            (_e = partial.keyword) !== null && _e !== void 0 ? _e : (partial.keyword = (yield select("keyword")("Keyword parameter mode")([
-                "true",
-                "false",
-            ])) === "true");
-            if (partial.keyword)
-                partial.keyword = partial.keyword === "true";
-            else
-                partial.keyword =
-                    (yield select("keyword")("Keyword parameter mode")([
-                        "true",
-                        "false",
-                    ])) === "true";
-            if (partial.simulate)
-                partial.simulate = partial.simulate === "true";
-            else
-                partial.simulate =
-                    (yield select("simulate")("Mokup Simulator")(["true", "false"])) ===
-                        "true";
-            if (partial.e2e)
-                partial.e2e = partial.e2e === "true";
-            else
-                partial.e2e =
-                    (yield select("e2e")("Generate E2E tests")(["true", "false"])) ===
-                        "true";
+            // a flag given alone is `true`, and one given a value is its text
+            const flag = (value) => value === undefined ? undefined : value === true || value === "true";
+            const ask = (name, message) => __awaiter(this, void 0, void 0, function* () { return (yield select(name)(message)(["true", "false"])) === "true"; });
+            partial.keyword = (_e = flag(partial.keyword)) !== null && _e !== void 0 ? _e : (yield ask("keyword", "Keyword parameter mode"));
+            partial.simulate = (_f = flag(partial.simulate)) !== null && _f !== void 0 ? _f : (yield ask("simulate", "Mokup Simulator"));
+            partial.e2e = (_g = flag(partial.e2e)) !== null && _g !== void 0 ? _g : (yield ask("e2e", "Generate E2E tests"));
             return partial;
         }));
     });

package/lib/executable/NestiaMigrateInquirer.js.map

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

package/lib/executable/NestiaMigrateInquirer.mjs

@@ -42,13 +42,11 @@ let NestiaMigrateInquirer;
 			partial.input ??= await input("input")("Swagger file location");
 			partial.output ??= await input("output")("Response directory path");
 			partial.package ??= await input("package")("Package name");
-			partial.keyword ??= await select("keyword")("Keyword parameter mode")(["true", "false"]) === "true";
-			if (partial.keyword) partial.keyword = partial.keyword === "true";
-			else partial.keyword = await select("keyword")("Keyword parameter mode")(["true", "false"]) === "true";
-			if (partial.simulate) partial.simulate = partial.simulate === "true";
-			else partial.simulate = await select("simulate")("Mokup Simulator")(["true", "false"]) === "true";
-			if (partial.e2e) partial.e2e = partial.e2e === "true";
-			else partial.e2e = await select("e2e")("Generate E2E tests")(["true", "false"]) === "true";
+			const flag = (value) => value === void 0 ? void 0 : value === true || value === "true";
+			const ask = async (name, message) => await select(name)(message)(["true", "false"]) === "true";
+			partial.keyword = flag(partial.keyword) ?? await ask("keyword", "Keyword parameter mode");
+			partial.simulate = flag(partial.simulate) ?? await ask("simulate", "Mokup Simulator");
+			partial.e2e = flag(partial.e2e) ?? await ask("e2e", "Generate E2E tests");
 			return partial;
 		});
 	};

package/lib/factories/ExpressionFactory.d.ts

@@ -3,7 +3,21 @@ import { type NumericLiteral, type PrefixUnaryExpression } from "@ttsc/factory";
  * Numeric-literal helper that handles negative values via a leading
  * `MinusToken` prefix unary, matching how the TypeScript factory itself emits
  * negative numeric literals.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the number literal builder that the generators need.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only builds nodes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
  */
 export declare namespace ExpressionFactory {
+    /**
+     * Builds a numeric literal, using a prefix minus for a negative value,
+     * because a negative numeric literal is not a valid node.
+     *
+     * @evidence contracts/common.md#principled-implementation TypeScript represents a negative number as a prefix unary minus applied to a positive literal, so the function builds that shape for values below zero and a plain literal otherwise.
+     * @evidence contracts/common.md#clear-and-simple-design One conditional.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the syntax tree grammar.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the negative case.
+     */
     const number: (value: number) => NumericLiteral | PrefixUnaryExpression;
 }

package/lib/factories/ExpressionFactory.js

@@ -6,9 +6,23 @@ const factory_1 = require("@ttsc/factory");
  * Numeric-literal helper that handles negative values via a leading
  * `MinusToken` prefix unary, matching how the TypeScript factory itself emits
  * negative numeric literals.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the number literal builder that the generators need.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only builds nodes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
  */
 var ExpressionFactory;
 (function (ExpressionFactory) {
+    /**
+     * Builds a numeric literal, using a prefix minus for a negative value,
+     * because a negative numeric literal is not a valid node.
+     *
+     * @evidence contracts/common.md#principled-implementation TypeScript represents a negative number as a prefix unary minus applied to a positive literal, so the function builds that shape for values below zero and a plain literal otherwise.
+     * @evidence contracts/common.md#clear-and-simple-design One conditional.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the syntax tree grammar.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the negative case.
+     */
     ExpressionFactory.number = (value) => value < 0
         ? factory_1.factory.createPrefixUnaryExpression(factory_1.SyntaxKind.MinusToken, factory_1.factory.createNumericLiteral(Math.abs(value)))
         : factory_1.factory.createNumericLiteral(value);

package/lib/factories/ExpressionFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"ExpressionFactory.js","sourceRoot":"","sources":["../../src/factories/ExpressionFactory.ts"],"names":[],"mappings":";;;AAAA,2CAKuB;AAEvB;;;;GAIG;AACH,IAAiB,iBAAiB,CAUjC;AAVD,WAAiB,iBAAiB;IACnB,wBAAM,GAAG,CACpB,KAAa,EAC2B,EAAE,CAC1C,KAAK,GAAG,CAAC;QACP,CAAC,CAAC,iBAAO,CAAC,2BAA2B,CACjC,oBAAU,CAAC,UAAU,EACrB,iBAAO,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAC9C;QACH,CAAC,CAAC,iBAAO,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;AAC5C,CAAC,EAVgB,iBAAiB,aAAjB,iBAAiB,GAAjB,iBAAiB,QAUjC"}
+{"version":3,"file":"ExpressionFactory.js","sourceRoot":"","sources":["../../src/factories/ExpressionFactory.ts"],"names":[],"mappings":";;;AAAA,2CAKuB;AAEvB;;;;;;;;;GASG;AACH,IAAiB,iBAAiB,CAmBjC;AAnBD,WAAiB,iBAAiB;IAChC;;;;;;;;OAQG;IACU,wBAAM,GAAG,CACpB,KAAa,EAC2B,EAAE,CAC1C,KAAK,GAAG,CAAC;QACP,CAAC,CAAC,iBAAO,CAAC,2BAA2B,CACjC,oBAAU,CAAC,UAAU,EACrB,iBAAO,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAC9C;QACH,CAAC,CAAC,iBAAO,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;AAC5C,CAAC,EAnBgB,iBAAiB,aAAjB,iBAAiB,GAAjB,iBAAiB,QAmBjC"}

package/lib/factories/IdentifierFactory.d.ts

@@ -2,21 +2,41 @@ import { type Expression, type Identifier, type ParameterDeclaration, type Strin
 /**
  * Identifier and member-access helpers. The surface kept here is the subset
  * nestia generators actually call (`identifier`, `access`, `parameter`).
+ *
+ * @evidence contracts/common.md#principled-implementation The functions decide between an identifier and a string literal by the syntax of the name, so any string can be used as a key.
+ * @evidence contracts/common.md#clear-and-simple-design Three small functions and one private predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The variable-name test is a regular expression of the language's identifier syntax, which is inlined so that the package need not load a larger namespace.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
  */
 export declare namespace IdentifierFactory {
     /**
      * Build an identifier or string literal depending on whether `name` is a
      * valid JavaScript identifier.
+     *
+     * @evidence contracts/common.md#principled-implementation The name is tested against the identifier grammar `[A-Za-z_$][A-Za-z0-9_$]*`, which is conservative: a valid name outside it, such as one with non-ASCII letters, becomes a quoted key, which is equivalent.
+     * @evidence contracts/common.md#clear-and-simple-design One conditional.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The test applies to every name.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the two results.
      */
     const identifier: (name: string) => Identifier | StringLiteral;
     /**
      * Member access on `input` by `key`. Falls back to element access when the
      * key is not a valid identifier.
+     *
+     * @evidence contracts/common.md#principled-implementation The postfix is built by `identifier`, and its kind selects the property form or the element form, with the chain token added when requested.
+     * @evidence contracts/common.md#clear-and-simple-design One function delegating the naming rule.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It never concatenates source text.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the forms.
      */
     const access: (input: Expression, key: string, chain?: boolean) => Expression;
     /**
      * Parameter declaration with default `any` type when the caller omits one.
      * Passing a `QuestionToken` as `init` marks the parameter optional.
+     *
+     * @evidence contracts/common.md#principled-implementation An initializer that is the question token becomes the optional marker and is not an initializer, and any other initializer is passed through.
+     * @evidence contracts/common.md#clear-and-simple-design One function with one branch.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the declaration grammar.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the optional marker and the default type.
      */
     const parameter: (name: string | Identifier, type?: TypeNode, init?: Expression | Token) => ParameterDeclaration;
 }

package/lib/factories/IdentifierFactory.js

@@ -10,12 +10,22 @@ const isVariableName = (str) => VARIABLE_REGEX.test(str);
 /**
  * Identifier and member-access helpers. The surface kept here is the subset
  * nestia generators actually call (`identifier`, `access`, `parameter`).
+ *
+ * @evidence contracts/common.md#principled-implementation The functions decide between an identifier and a string literal by the syntax of the name, so any string can be used as a key.
+ * @evidence contracts/common.md#clear-and-simple-design Three small functions and one private predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The variable-name test is a regular expression of the language's identifier syntax, which is inlined so that the package need not load a larger namespace.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
  */
 var IdentifierFactory;
 (function (IdentifierFactory) {
     /**
      * Build an identifier or string literal depending on whether `name` is a
      * valid JavaScript identifier.
+     *
+     * @evidence contracts/common.md#principled-implementation The name is tested against the identifier grammar `[A-Za-z_$][A-Za-z0-9_$]*`, which is conservative: a valid name outside it, such as one with non-ASCII letters, becomes a quoted key, which is equivalent.
+     * @evidence contracts/common.md#clear-and-simple-design One conditional.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The test applies to every name.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the two results.
      */
     IdentifierFactory.identifier = (name) => isVariableName(name)
         ? factory_1.factory.createIdentifier(name)
@@ -23,6 +33,11 @@ var IdentifierFactory;
     /**
      * Member access on `input` by `key`. Falls back to element access when the
      * key is not a valid identifier.
+     *
+     * @evidence contracts/common.md#principled-implementation The postfix is built by `identifier`, and its kind selects the property form or the element form, with the chain token added when requested.
+     * @evidence contracts/common.md#clear-and-simple-design One function delegating the naming rule.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It never concatenates source text.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the forms.
      */
     IdentifierFactory.access = (input, key, chain) => {
         const postfix = IdentifierFactory.identifier(key);
@@ -37,6 +52,11 @@ var IdentifierFactory;
     /**
      * Parameter declaration with default `any` type when the caller omits one.
      * Passing a `QuestionToken` as `init` marks the parameter optional.
+     *
+     * @evidence contracts/common.md#principled-implementation An initializer that is the question token becomes the optional marker and is not an initializer, and any other initializer is passed through.
+     * @evidence contracts/common.md#clear-and-simple-design One function with one branch.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the declaration grammar.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the optional marker and the default type.
      */
     IdentifierFactory.parameter = (name, type, init) => {
         const isQuestionToken = !!init &&

package/lib/factories/IdentifierFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"IdentifierFactory.js","sourceRoot":"","sources":["../../src/factories/IdentifierFactory.ts"],"names":[],"mappings":";;;AAAA,2CASuB;AAEvB,+CAA4C;AAE5C,yEAAyE;AACzE,yEAAyE;AACzE,MAAM,cAAc,GAAG,4BAA4B,CAAC;AACpD,MAAM,cAAc,GAAG,CAAC,GAAW,EAAW,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE1E;;;GAGG;AACH,IAAiB,iBAAiB,CA6DjC;AA7DD,WAAiB,iBAAiB;IAChC;;;OAGG;IACU,4BAAU,GAAG,CAAC,IAAY,EAA8B,EAAE,CACrE,cAAc,CAAC,IAAI,CAAC;QAClB,CAAC,CAAC,iBAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC;QAChC,CAAC,CAAC,iBAAO,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAExC;;;OAGG;IACU,wBAAM,GAAG,CACpB,KAAiB,EACjB,GAAW,EACX,KAAe,EACH,EAAE;QACd,MAAM,OAAO,GAAG,4BAAU,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,OAAO,CAAC,IAAI,KAAK,eAAe;YAClC,OAAO,KAAK,KAAK,IAAI;gBACnB,CAAC,CAAC,iBAAO,CAAC,wBAAwB,CAC9B,KAAK,EACL,iBAAO,CAAC,WAAW,CAAC,oBAAU,CAAC,gBAAgB,CAAC,EAChD,OAAO,CACR;gBACH,CAAC,CAAC,iBAAO,CAAC,6BAA6B,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC5D,OAAO,KAAK,KAAK,IAAI;YACnB,CAAC,CAAC,iBAAO,CAAC,yBAAyB,CAC/B,KAAK,EACL,iBAAO,CAAC,WAAW,CAAC,oBAAU,CAAC,gBAAgB,CAAC,EAChD,OAAO,CACR;YACH,CAAC,CAAC,iBAAO,CAAC,8BAA8B,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC7D,CAAC,CAAC;IAEF;;;OAGG;IACU,2BAAS,GAAG,CACvB,IAAyB,EACzB,IAAe,EACf,IAAyB,EACH,EAAE;QACxB,MAAM,eAAe,GACnB,CAAC,CAAC,IAAI;YACN,IAAI,CAAC,IAAI,KAAK,OAAO;YACpB,IAAc,CAAC,KAAK,KAAK,oBAAU,CAAC,aAAa,CAAC;QACrD,OAAO,iBAAO,CAAC,0BAA0B,CACvC,SAAS,EACT,SAAS,EACT,IAAI,EACJ,eAAe;YACb,CAAC,CAAC,iBAAO,CAAC,WAAW,CAAC,oBAAU,CAAC,aAAa,CAAC;YAC/C,CAAC,CAAC,SAAS,EACb,IAAI,aAAJ,IAAI,cAAJ,IAAI,GAAI,yBAAW,CAAC,OAAO,CAAC,KAAK,CAAC,EAClC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,IAA+B,CAC/D,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC,EA7DgB,iBAAiB,aAAjB,iBAAiB,GAAjB,iBAAiB,QA6DjC"}
+{"version":3,"file":"IdentifierFactory.js","sourceRoot":"","sources":["../../src/factories/IdentifierFactory.ts"],"names":[],"mappings":";;;AAAA,2CASuB;AAEvB,+CAA4C;AAE5C,yEAAyE;AACzE,yEAAyE;AACzE,MAAM,cAAc,GAAG,4BAA4B,CAAC;AACpD,MAAM,cAAc,GAAG,CAAC,GAAW,EAAW,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE1E;;;;;;;;GAQG;AACH,IAAiB,iBAAiB,CA4EjC;AA5ED,WAAiB,iBAAiB;IAChC;;;;;;;;OAQG;IACU,4BAAU,GAAG,CAAC,IAAY,EAA8B,EAAE,CACrE,cAAc,CAAC,IAAI,CAAC;QAClB,CAAC,CAAC,iBAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC;QAChC,CAAC,CAAC,iBAAO,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAExC;;;;;;;;OAQG;IACU,wBAAM,GAAG,CACpB,KAAiB,EACjB,GAAW,EACX,KAAe,EACH,EAAE;QACd,MAAM,OAAO,GAAG,4BAAU,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,OAAO,CAAC,IAAI,KAAK,eAAe;YAClC,OAAO,KAAK,KAAK,IAAI;gBACnB,CAAC,CAAC,iBAAO,CAAC,wBAAwB,CAC9B,KAAK,EACL,iBAAO,CAAC,WAAW,CAAC,oBAAU,CAAC,gBAAgB,CAAC,EAChD,OAAO,CACR;gBACH,CAAC,CAAC,iBAAO,CAAC,6BAA6B,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC5D,OAAO,KAAK,KAAK,IAAI;YACnB,CAAC,CAAC,iBAAO,CAAC,yBAAyB,CAC/B,KAAK,EACL,iBAAO,CAAC,WAAW,CAAC,oBAAU,CAAC,gBAAgB,CAAC,EAChD,OAAO,CACR;YACH,CAAC,CAAC,iBAAO,CAAC,8BAA8B,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC7D,CAAC,CAAC;IAEF;;;;;;;;OAQG;IACU,2BAAS,GAAG,CACvB,IAAyB,EACzB,IAAe,EACf,IAAyB,EACH,EAAE;QACxB,MAAM,eAAe,GACnB,CAAC,CAAC,IAAI;YACN,IAAI,CAAC,IAAI,KAAK,OAAO;YACpB,IAAc,CAAC,KAAK,KAAK,oBAAU,CAAC,aAAa,CAAC;QACrD,OAAO,iBAAO,CAAC,0BAA0B,CACvC,SAAS,EACT,SAAS,EACT,IAAI,EACJ,eAAe;YACb,CAAC,CAAC,iBAAO,CAAC,WAAW,CAAC,oBAAU,CAAC,aAAa,CAAC;YAC/C,CAAC,CAAC,SAAS,EACb,IAAI,aAAJ,IAAI,cAAJ,IAAI,GAAI,yBAAW,CAAC,OAAO,CAAC,KAAK,CAAC,EAClC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,IAA+B,CAC/D,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC,EA5EgB,iBAAiB,aAAjB,iBAAiB,GAAjB,iBAAiB,QA4EjC"}

package/lib/factories/LiteralFactory.d.ts

@@ -1,9 +1,25 @@
 import { type Expression } from "@ttsc/factory";
 /**
  * Recursive value-to-AST-literal builder. Hands back already-AST inputs
- * unchanged (so callers can mix factory output with raw JS values inside the
- * same object/array), and emits the appropriate literal node otherwise.
+ * unchanged for arrow functions, calls and identifiers (so callers can mix
+ * those factory expressions with raw values inside objects/arrays), and emits
+ * the appropriate literal node otherwise.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace maps null, booleans, numbers, strings, bigint text, arrays and object entries to literal expressions, passes through the three accepted AST kinds, maps functions to undefined and refuses unsupported primitive types.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function and two private helpers for containers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is by type, with no value special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
  */
 export declare namespace LiteralFactory {
+    /**
+     * Builds the expression of a value: `null`, a boolean, a number, a string, a
+     * bigint as its text, an array, an object without its `undefined` members, or
+     * an expression node as it is.
+     *
+     * @evidence contracts/common.md#principled-implementation The value is dispatched by type in a fixed order; nodes of the kinds arrow function, call, and identifier pass through, functions become `undefined`, and an unsupported type is a `TypeError`, so the result is total over the listed types.
+     * @evidence contracts/common.md#clear-and-simple-design One function with one branch per type.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The dispatch is general, and a bigint becomes text because a literal bigint is not supported by the target syntax here.
+     * @evidence contracts/common.md#meaningful-documentation The comment lists the mapping.
+     */
     const write: (input: any) => Expression;
 }

package/lib/factories/LiteralFactory.js

@@ -14,11 +14,27 @@ const isNode = (value) => typeof value === "object" &&
     typeof value.kind === "string";
 /**
  * Recursive value-to-AST-literal builder. Hands back already-AST inputs
- * unchanged (so callers can mix factory output with raw JS values inside the
- * same object/array), and emits the appropriate literal node otherwise.
+ * unchanged for arrow functions, calls and identifiers (so callers can mix
+ * those factory expressions with raw values inside objects/arrays), and emits
+ * the appropriate literal node otherwise.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace maps null, booleans, numbers, strings, bigint text, arrays and object entries to literal expressions, passes through the three accepted AST kinds, maps functions to undefined and refuses unsupported primitive types.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function and two private helpers for containers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is by type, with no value special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
  */
 var LiteralFactory;
 (function (LiteralFactory) {
+    /**
+     * Builds the expression of a value: `null`, a boolean, a number, a string, a
+     * bigint as its text, an array, an object without its `undefined` members, or
+     * an expression node as it is.
+     *
+     * @evidence contracts/common.md#principled-implementation The value is dispatched by type in a fixed order; nodes of the kinds arrow function, call, and identifier pass through, functions become `undefined`, and an unsupported type is a `TypeError`, so the result is total over the listed types.
+     * @evidence contracts/common.md#clear-and-simple-design One function with one branch per type.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The dispatch is general, and a bigint becomes text because a literal bigint is not supported by the target syntax here.
+     * @evidence contracts/common.md#meaningful-documentation The comment lists the mapping.
+     */
     LiteralFactory.write = (input) => {
         if (input === null)
             return factory_1.factory.createNull();

package/lib/factories/LiteralFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"LiteralFactory.js","sourceRoot":"","sources":["../../src/factories/LiteralFactory.ts"],"names":[],"mappings":";;;AAAA,2CAAyD;AAEzD,2DAAwD;AACxD,2DAAwD;AAExD,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAS;IACxC,eAAe;IACf,gBAAgB;IAChB,YAAY;CACb,CAAC,CAAC;AAEH,MAAM,MAAM,GAAG,CAAC,KAAc,EAAuB,EAAE,CACrD,OAAO,KAAK,KAAK,QAAQ;IACzB,KAAK,KAAK,IAAI;IACd,OAAQ,KAA4B,CAAC,IAAI,KAAK,QAAQ,CAAC;AAEzD;;;;GAIG;AACH,IAAiB,cAAc,CAgC9B;AAhCD,WAAiB,cAAc;IAChB,oBAAK,GAAG,CAAC,KAAU,EAAc,EAAE;QAC9C,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,iBAAO,CAAC,UAAU,EAAE,CAAC;QAChD,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACrE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;QACnD,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,WAAW,CAAC,KAAe,CAAC,CAAC;QACnE,IAAI,OAAO,KAAK,KAAK,SAAS;YAC5B,OAAO,KAAK,CAAC,CAAC,CAAC,iBAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,iBAAO,CAAC,WAAW,EAAE,CAAC;QAC9D,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,qCAAiB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,iBAAO,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;QACzE,IAAI,OAAO,KAAK,KAAK,QAAQ;YAC3B,OAAO,iBAAO,CAAC,mBAAmB,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QACvD,IAAI,OAAO,KAAK,KAAK,UAAU;YAC7B,OAAO,iBAAO,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;QAC/C,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;IACvE,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,CAAC,GAAW,EAAc,EAAE,CAC9C,iBAAO,CAAC,6BAA6B,CACnC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC;SAChB,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC;SAC1C,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CACpB,iBAAO,CAAC,wBAAwB,CAC9B,qCAAiB,CAAC,UAAU,CAAC,GAAG,CAAC,EACjC,oBAAK,CAAC,KAAK,CAAC,CACb,CACF,EACH,IAAI,CACL,CAAC;IAEJ,MAAM,UAAU,GAAG,CAAC,KAAqB,EAAc,EAAE,CACvD,iBAAO,CAAC,4BAA4B,CAAC,KAAK,CAAC,GAAG,CAAC,oBAAK,CAAC,EAAE,IAAI,CAAC,CAAC;AACjE,CAAC,EAhCgB,cAAc,aAAd,cAAc,GAAd,cAAc,QAgC9B"}
+{"version":3,"file":"LiteralFactory.js","sourceRoot":"","sources":["../../src/factories/LiteralFactory.ts"],"names":[],"mappings":";;;AAAA,2CAAyD;AAEzD,2DAAwD;AACxD,2DAAwD;AAExD,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAS;IACxC,eAAe;IACf,gBAAgB;IAChB,YAAY;CACb,CAAC,CAAC;AAEH,MAAM,MAAM,GAAG,CAAC,KAAc,EAAuB,EAAE,CACrD,OAAO,KAAK,KAAK,QAAQ;IACzB,KAAK,KAAK,IAAI;IACd,OAAQ,KAA4B,CAAC,IAAI,KAAK,QAAQ,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,IAAiB,cAAc,CA0C9B;AA1CD,WAAiB,cAAc;IAC7B;;;;;;;;;OASG;IACU,oBAAK,GAAG,CAAC,KAAU,EAAc,EAAE;QAC9C,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,iBAAO,CAAC,UAAU,EAAE,CAAC;QAChD,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACrE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;QACnD,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,WAAW,CAAC,KAAe,CAAC,CAAC;QACnE,IAAI,OAAO,KAAK,KAAK,SAAS;YAC5B,OAAO,KAAK,CAAC,CAAC,CAAC,iBAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,iBAAO,CAAC,WAAW,EAAE,CAAC;QAC9D,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,qCAAiB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,iBAAO,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;QACzE,IAAI,OAAO,KAAK,KAAK,QAAQ;YAC3B,OAAO,iBAAO,CAAC,mBAAmB,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QACvD,IAAI,OAAO,KAAK,KAAK,UAAU;YAC7B,OAAO,iBAAO,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;QAC/C,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;IACvE,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,CAAC,GAAW,EAAc,EAAE,CAC9C,iBAAO,CAAC,6BAA6B,CACnC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC;SAChB,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC;SAC1C,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CACpB,iBAAO,CAAC,wBAAwB,CAC9B,qCAAiB,CAAC,UAAU,CAAC,GAAG,CAAC,EACjC,oBAAK,CAAC,KAAK,CAAC,CACb,CACF,EACH,IAAI,CACL,CAAC;IAEJ,MAAM,UAAU,GAAG,CAAC,KAAqB,EAAc,EAAE,CACvD,iBAAO,CAAC,4BAA4B,CAAC,KAAK,CAAC,GAAG,CAAC,oBAAK,CAAC,EAAE,IAAI,CAAC,CAAC;AACjE,CAAC,EA1CgB,cAAc,aAAd,cAAc,GAAd,cAAc,QA0C9B"}

package/lib/factories/StatementFactory.d.ts

@@ -1,11 +1,36 @@
 import { type Expression, type TypeNode, type VariableStatement } from "@ttsc/factory";
-/** Variable-statement helpers. `constant` emits `const`, `mut` emits `let`. */
+/**
+ * Variable-statement helpers. `constant` emits `const`, `mut` emits `let`.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace builds `let` and `const` statements from a name, an optional type, and an optional value.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only builds nodes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 export declare namespace StatementFactory {
+    /**
+     * Builds a `let` statement; a declaration without a type and without an
+     * initializer is typed `any`.
+     *
+     * @evidence contracts/common.md#principled-implementation A `let` without both a type and an initializer would be implicitly any, so the type is stated explicitly in that case.
+     * @evidence contracts/common.md#clear-and-simple-design One expression.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the declaration grammar.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the default type.
+     */
     const mut: (props: {
         name: string;
         type?: TypeNode | undefined;
         initializer?: Expression | undefined;
     }) => VariableStatement;
+    /**
+     * Builds a `const` statement from a name, an optional type, and an optional
+     * value.
+     *
+     * @evidence contracts/common.md#principled-implementation The declaration list carries the const flag and the given parts.
+     * @evidence contracts/common.md#clear-and-simple-design One expression.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the declaration grammar.
+     * @evidence contracts/common.md#meaningful-documentation The comment states its inputs.
+     */
     const constant: (props: {
         name: string;
         type?: TypeNode | undefined;

package/lib/factories/StatementFactory.js

@@ -3,9 +3,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.StatementFactory = void 0;
 const factory_1 = require("@ttsc/factory");
 const TypeFactory_1 = require("./TypeFactory");
-/** Variable-statement helpers. `constant` emits `const`, `mut` emits `let`. */
+/**
+ * Variable-statement helpers. `constant` emits `const`, `mut` emits `let`.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace builds `let` and `const` statements from a name, an optional type, and an optional value.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only builds nodes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 var StatementFactory;
 (function (StatementFactory) {
+    /**
+     * Builds a `let` statement; a declaration without a type and without an
+     * initializer is typed `any`.
+     *
+     * @evidence contracts/common.md#principled-implementation A `let` without both a type and an initializer would be implicitly any, so the type is stated explicitly in that case.
+     * @evidence contracts/common.md#clear-and-simple-design One expression.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the declaration grammar.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the default type.
+     */
     StatementFactory.mut = (props) => factory_1.factory.createVariableStatement(undefined, factory_1.factory.createVariableDeclarationList([
         factory_1.factory.createVariableDeclaration(props.name, undefined, props.type !== undefined
             ? props.type
@@ -13,6 +29,15 @@ var StatementFactory;
                 ? TypeFactory_1.TypeFactory.keyword("any")
                 : undefined, props.initializer),
     ], factory_1.NodeFlags.Let));
+    /**
+     * Builds a `const` statement from a name, an optional type, and an optional
+     * value.
+     *
+     * @evidence contracts/common.md#principled-implementation The declaration list carries the const flag and the given parts.
+     * @evidence contracts/common.md#clear-and-simple-design One expression.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the declaration grammar.
+     * @evidence contracts/common.md#meaningful-documentation The comment states its inputs.
+     */
     StatementFactory.constant = (props) => factory_1.factory.createVariableStatement(undefined, factory_1.factory.createVariableDeclarationList([
         factory_1.factory.createVariableDeclaration(props.name, undefined, props.type, props.value),
     ], factory_1.NodeFlags.Const));

package/lib/factories/StatementFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"StatementFactory.js","sourceRoot":"","sources":["../../src/factories/StatementFactory.ts"],"names":[],"mappings":";;;AAAA,2CAMuB;AAEvB,+CAA4C;AAE5C,+EAA+E;AAC/E,IAAiB,gBAAgB,CA4ChC;AA5CD,WAAiB,gBAAgB;IAClB,oBAAG,GAAG,CAAC,KAInB,EAAqB,EAAE,CACtB,iBAAO,CAAC,uBAAuB,CAC7B,SAAS,EACT,iBAAO,CAAC,6BAA6B,CACnC;QACE,iBAAO,CAAC,yBAAyB,CAC/B,KAAK,CAAC,IAAI,EACV,SAAS,EACT,KAAK,CAAC,IAAI,KAAK,SAAS;YACtB,CAAC,CAAC,KAAK,CAAC,IAAI;YACZ,CAAC,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS;gBAC/B,CAAC,CAAC,yBAAW,CAAC,OAAO,CAAC,KAAK,CAAC;gBAC5B,CAAC,CAAC,SAAS,EACf,KAAK,CAAC,WAAW,CAClB;KACF,EACD,mBAAS,CAAC,GAAG,CACd,CACF,CAAC;IAES,yBAAQ,GAAG,CAAC,KAIxB,EAAqB,EAAE,CACtB,iBAAO,CAAC,uBAAuB,CAC7B,SAAS,EACT,iBAAO,CAAC,6BAA6B,CACnC;QACE,iBAAO,CAAC,yBAAyB,CAC/B,KAAK,CAAC,IAAI,EACV,SAAS,EACT,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,KAAK,CACZ;KACF,EACD,mBAAS,CAAC,KAAK,CAChB,CACF,CAAC;AACN,CAAC,EA5CgB,gBAAgB,aAAhB,gBAAgB,GAAhB,gBAAgB,QA4ChC"}
+{"version":3,"file":"StatementFactory.js","sourceRoot":"","sources":["../../src/factories/StatementFactory.ts"],"names":[],"mappings":";;;AAAA,2CAMuB;AAEvB,+CAA4C;AAE5C;;;;;;;GAOG;AACH,IAAiB,gBAAgB,CA8DhC;AA9DD,WAAiB,gBAAgB;IAC/B;;;;;;;;OAQG;IACU,oBAAG,GAAG,CAAC,KAInB,EAAqB,EAAE,CACtB,iBAAO,CAAC,uBAAuB,CAC7B,SAAS,EACT,iBAAO,CAAC,6BAA6B,CACnC;QACE,iBAAO,CAAC,yBAAyB,CAC/B,KAAK,CAAC,IAAI,EACV,SAAS,EACT,KAAK,CAAC,IAAI,KAAK,SAAS;YACtB,CAAC,CAAC,KAAK,CAAC,IAAI;YACZ,CAAC,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS;gBAC/B,CAAC,CAAC,yBAAW,CAAC,OAAO,CAAC,KAAK,CAAC;gBAC5B,CAAC,CAAC,SAAS,EACf,KAAK,CAAC,WAAW,CAClB;KACF,EACD,mBAAS,CAAC,GAAG,CACd,CACF,CAAC;IAEJ;;;;;;;;OAQG;IACU,yBAAQ,GAAG,CAAC,KAIxB,EAAqB,EAAE,CACtB,iBAAO,CAAC,uBAAuB,CAC7B,SAAS,EACT,iBAAO,CAAC,6BAA6B,CACnC;QACE,iBAAO,CAAC,yBAAyB,CAC/B,KAAK,CAAC,IAAI,EACV,SAAS,EACT,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,KAAK,CACZ;KACF,EACD,mBAAS,CAAC,KAAK,CAChB,CACF,CAAC;AACN,CAAC,EA9DgB,gBAAgB,aAAhB,gBAAgB,GAAhB,gBAAgB,QA8DhC"}

package/lib/factories/SupportedStringFormats.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The string formats of the OpenAPI document that the typia `Format` tag
+ * validates, so a schema carrying one of them is generated as a `Format` tag
+ * and a schema carrying any other format stays a plain `string`.
+ */
+export declare const SUPPORTED_STRING_FORMATS: ReadonlySet<string>;

package/lib/factories/SupportedStringFormats.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_STRING_FORMATS = void 0;
+/**
+ * The string formats of the OpenAPI document that the typia `Format` tag
+ * validates, so a schema carrying one of them is generated as a `Format` tag
+ * and a schema carrying any other format stays a plain `string`.
+ */
+exports.SUPPORTED_STRING_FORMATS = new Set([
+    "byte",
+    "password",
+    "regex",
+    "uuid",
+    "email",
+    "hostname",
+    "idn-email",
+    "idn-hostname",
+    "iri",
+    "iri-reference",
+    "ipv4",
+    "ipv6",
+    "uri",
+    "uri-reference",
+    "uri-template",
+    "url",
+    "date-time",
+    "date",
+    "time",
+    "duration",
+    "json-pointer",
+    "relative-json-pointer",
+]);
+//# sourceMappingURL=SupportedStringFormats.js.map

package/lib/factories/SupportedStringFormats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SupportedStringFormats.js","sourceRoot":"","sources":["../../src/factories/SupportedStringFormats.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACU,QAAA,wBAAwB,GAAwB,IAAI,GAAG,CAAC;IACnE,MAAM;IACN,UAAU;IACV,OAAO;IACP,MAAM;IACN,OAAO;IACP,UAAU;IACV,WAAW;IACX,cAAc;IACd,KAAK;IACL,eAAe;IACf,MAAM;IACN,MAAM;IACN,KAAK;IACL,eAAe;IACf,cAAc;IACd,KAAK;IACL,WAAW;IACX,MAAM;IACN,MAAM;IACN,UAAU;IACV,cAAc;IACd,uBAAuB;CACxB,CAAC,CAAC"}

package/lib/factories/SupportedStringFormats.mjs

@@ -0,0 +1,34 @@
+//#region src/factories/SupportedStringFormats.ts
+/**
+* The string formats of the OpenAPI document that the typia `Format` tag
+* validates, so a schema carrying one of them is generated as a `Format` tag
+* and a schema carrying any other format stays a plain `string`.
+*/
+const SUPPORTED_STRING_FORMATS = /* @__PURE__ */ new Set([
+	"byte",
+	"password",
+	"regex",
+	"uuid",
+	"email",
+	"hostname",
+	"idn-email",
+	"idn-hostname",
+	"iri",
+	"iri-reference",
+	"ipv4",
+	"ipv6",
+	"uri",
+	"uri-reference",
+	"uri-template",
+	"url",
+	"date-time",
+	"date",
+	"time",
+	"duration",
+	"json-pointer",
+	"relative-json-pointer"
+]);
+//#endregion
+export { SUPPORTED_STRING_FORMATS };
+
+//# sourceMappingURL=SupportedStringFormats.mjs.map

package/lib/factories/SupportedStringFormats.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"SupportedStringFormats.mjs","names":[],"sources":[],"mappings":""}

package/lib/factories/TypeFactory.d.ts

@@ -5,6 +5,11 @@ import { type KeywordTypeNode, SyntaxKind } from "@ttsc/factory";
  * Wraps {@link factory.createKeywordTypeNode} with a name-based interface so
  * generator code reads as `TypeFactory.keyword("any")` instead of selecting the
  * `SyntaxKind.AnyKeyword` token by hand.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace maps the names of the nine keyword types to their syntax kinds.
+ * @evidence contracts/common.md#clear-and-simple-design One table, one type, and one function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only builds nodes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
  */
 export declare namespace TypeFactory {
     const KEYWORDS: {
@@ -18,7 +23,23 @@ export declare namespace TypeFactory {
         readonly never: SyntaxKind.NeverKeyword;
         readonly undefined: SyntaxKind.UndefinedKeyword;
     };
+    /**
+     * The names of the supported keyword types.
+     *
+     * @evidence contracts/common.md#principled-implementation The type is the key set of the table that maps names to syntax kinds, so a new keyword is one table entry.
+     * @evidence contracts/common.md#clear-and-simple-design One derived type.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment names the set.
+     */
     export type Keyword = keyof typeof KEYWORDS;
+    /**
+     * Builds the keyword type node of a keyword name.
+     *
+     * @evidence contracts/common.md#principled-implementation The name is looked up in the table, so an unsupported name is a compile error.
+     * @evidence contracts/common.md#clear-and-simple-design One lookup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the type grammar.
+     * @evidence contracts/common.md#meaningful-documentation The comment states its input.
+     */
     export const keyword: (type: Keyword) => KeywordTypeNode;
     export {};
 }

package/lib/factories/TypeFactory.js

@@ -8,6 +8,11 @@ const factory_1 = require("@ttsc/factory");
  * Wraps {@link factory.createKeywordTypeNode} with a name-based interface so
  * generator code reads as `TypeFactory.keyword("any")` instead of selecting the
  * `SyntaxKind.AnyKeyword` token by hand.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace maps the names of the nine keyword types to their syntax kinds.
+ * @evidence contracts/common.md#clear-and-simple-design One table, one type, and one function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only builds nodes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
  */
 var TypeFactory;
 (function (TypeFactory) {
@@ -22,6 +27,14 @@ var TypeFactory;
         never: factory_1.SyntaxKind.NeverKeyword,
         undefined: factory_1.SyntaxKind.UndefinedKeyword,
     };
+    /**
+     * Builds the keyword type node of a keyword name.
+     *
+     * @evidence contracts/common.md#principled-implementation The name is looked up in the table, so an unsupported name is a compile error.
+     * @evidence contracts/common.md#clear-and-simple-design One lookup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the type grammar.
+     * @evidence contracts/common.md#meaningful-documentation The comment states its input.
+     */
     TypeFactory.keyword = (type) => factory_1.factory.createKeywordTypeNode(KEYWORDS[type]);
 })(TypeFactory || (exports.TypeFactory = TypeFactory = {}));
 //# sourceMappingURL=TypeFactory.js.map

package/lib/factories/TypeFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"TypeFactory.js","sourceRoot":"","sources":["../../src/factories/TypeFactory.ts"],"names":[],"mappings":";;;AAAA,2CAA0E;AAE1E;;;;;;GAMG;AACH,IAAiB,WAAW,CAiB3B;AAjBD,WAAiB,WAAW;IAC1B,MAAM,QAAQ,GAAG;QACf,IAAI,EAAE,oBAAU,CAAC,WAAW;QAC5B,GAAG,EAAE,oBAAU,CAAC,UAAU;QAC1B,OAAO,EAAE,oBAAU,CAAC,cAAc;QAClC,OAAO,EAAE,oBAAU,CAAC,cAAc;QAClC,MAAM,EAAE,oBAAU,CAAC,aAAa;QAChC,MAAM,EAAE,oBAAU,CAAC,aAAa;QAChC,MAAM,EAAE,oBAAU,CAAC,aAAa;QAChC,KAAK,EAAE,oBAAU,CAAC,YAAY;QAC9B,SAAS,EAAE,oBAAU,CAAC,gBAAgB;KAC9B,CAAC;IAIE,mBAAO,GAAG,CAAC,IAAa,EAAmB,EAAE,CACxD,iBAAO,CAAC,qBAAqB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;AAClD,CAAC,EAjBgB,WAAW,aAAX,WAAW,GAAX,WAAW,QAiB3B"}
+{"version":3,"file":"TypeFactory.js","sourceRoot":"","sources":["../../src/factories/TypeFactory.ts"],"names":[],"mappings":";;;AAAA,2CAA0E;AAE1E;;;;;;;;;;;GAWG;AACH,IAAiB,WAAW,CAiC3B;AAjCD,WAAiB,WAAW;IAC1B,MAAM,QAAQ,GAAG;QACf,IAAI,EAAE,oBAAU,CAAC,WAAW;QAC5B,GAAG,EAAE,oBAAU,CAAC,UAAU;QAC1B,OAAO,EAAE,oBAAU,CAAC,cAAc;QAClC,OAAO,EAAE,oBAAU,CAAC,cAAc;QAClC,MAAM,EAAE,oBAAU,CAAC,aAAa;QAChC,MAAM,EAAE,oBAAU,CAAC,aAAa;QAChC,MAAM,EAAE,oBAAU,CAAC,aAAa;QAChC,KAAK,EAAE,oBAAU,CAAC,YAAY;QAC9B,SAAS,EAAE,oBAAU,CAAC,gBAAgB;KAC9B,CAAC;IAYX;;;;;;;OAOG;IACU,mBAAO,GAAG,CAAC,IAAa,EAAmB,EAAE,CACxD,iBAAO,CAAC,qBAAqB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;AAClD,CAAC,EAjCgB,WAAW,aAAX,WAAW,GAAX,WAAW,QAiC3B"}

package/lib/factories/TypeLiteralFactory.d.ts

@@ -1,4 +1,22 @@
 import ts from "../internal/ts";
+/**
+ * Builds type nodes from JavaScript values, so a value can be written as a
+ * literal type.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace maps booleans, numbers, strings, null, arrays as tuples, and objects as type literals, and anything else to `any`.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function and small private builders per kind.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is by type, with no value special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 export declare namespace TypeLiteralFactory {
+    /**
+     * Builds the literal type of a value: a literal for a primitive, a tuple for
+     * an array, a type literal for an object, and `any` for other values.
+     *
+     * @evidence contracts/common.md#principled-implementation The value is dispatched by type, negative numbers use a prefix minus as expressions do, and object keys that are not identifiers are quoted.
+     * @evidence contracts/common.md#clear-and-simple-design One function with one branch per kind.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The dispatch is general.
+     * @evidence contracts/common.md#meaningful-documentation The comment lists the mapping.
+     */
     const generate: (value: any) => ts.TypeNode;
 }