jsii 5.4.24-dev.0 → 5.4.24
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/docs.js +1 -1
- package/lib/docs.js.map +1 -1
- package/lib/version.d.ts +2 -2
- package/lib/version.js +2 -2
- package/lib/version.js.map +1 -1
- package/package.json +3 -3
package/lib/docs.js
CHANGED
|
@@ -196,7 +196,7 @@ const SUMMARY_MAX_WORDS = 20;
|
|
|
196
196
|
* long, we'll take the first sentence (terminated by a punctuation).
|
|
197
197
|
*/
|
|
198
198
|
function summaryLine(str) {
|
|
199
|
-
const paras = str.split(
|
|
199
|
+
const paras = str.split(/(\r?\n){2}/);
|
|
200
200
|
if (paras.length > 1 && paras[0].split(' ').length < SUMMARY_MAX_WORDS) {
|
|
201
201
|
return paras[0];
|
|
202
202
|
}
|
package/lib/docs.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"docs.js","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Doc Comment parsing\n *\n * I tried using TSDoc here.\n *\n * Pro:\n * - Future standard.\n * - Does validating parsing and complains on failure.\n * - Has a more flexible interpretation of the @example tag (starts in text mode).\n *\n * Con:\n * - Different tags from JSDoc (@defaultValue instead of @default, \"@param name\n * description\" instead \"@param name description\".\n * - @example tag has a different interpretation than VSCode and JSDoc\n * (VSCode/JSDoc starts in code mode), which is confusing for syntax\n * highlighting in the editor.\n * - Allows no unknown tags.\n * - Wants to be in charge of parsing TypeScript, integrating into other build is\n * possible but harder.\n * - Parse to a DOM with no easy way to roundtrip back to equivalent MarkDown.\n *\n * Especially the last point: while parsing to and storing the parsed docs DOM\n * in the jsii assembly is superior in the long term (for example for\n * converting to different output formats, JavaDoc, C# docs, refdocs which all\n * accept slightly different syntaxes), right now we can get 80% of the bang\n * for 10% of the buck by just reading, storing and reproducing MarkDown, which\n * is Readable Enough(tm).\n *\n * If we ever want to attempt TSDoc again, this would be a good place to look at:\n *\n * https://github.com/Microsoft/tsdoc/blob/master/api-demo/src/advancedDemo.ts\n */\nimport * as spec from '@jsii/spec';\nimport * as ts from 'typescript';\n\n/**\n * Tags that we recognize\n */\nenum DocTag {\n PARAM = 'param',\n DEFAULT = 'default',\n DEFAULT_VALUE = 'defaultValue',\n DEPRECATED = 'deprecated',\n RETURNS = 'returns',\n RETURN = 'return',\n STABLE = 'stable',\n EXPERIMENTAL = 'experimental',\n SEE = 'see',\n SUBCLASSABLE = 'subclassable',\n EXAMPLE = 'example',\n STABILITY = 'stability',\n STRUCT = 'struct',\n\n // Not forwarded, this is compiler-internal.\n JSII = 'jsii',\n}\n\nconst RECOGNIZED_TAGS: ReadonlySet<String> = new Set(Object.values(DocTag));\n\n/**\n * Parse all doc comments that apply to a symbol into JSIIDocs format\n */\nexport function parseSymbolDocumentation(sym: ts.Symbol, typeChecker: ts.TypeChecker): DocsParsingResult {\n const comment = ts.displayPartsToString(sym.getDocumentationComment(typeChecker)).trim();\n const tags = reabsorbExampleTags(sym.getJsDocTags());\n\n // Right here we'll just guess that the first declaration site is the most important one.\n return parseDocParts(comment, tags);\n}\n\n/**\n * Return the list of parameter names that are referenced in the docstring for this symbol\n */\nexport function getReferencedDocParams(sym: ts.Symbol): string[] {\n const ret = new Array<string>();\n for (const tag of sym.getJsDocTags()) {\n if (tag.name === DocTag.PARAM) {\n const parts = ts.displayPartsToString(tag.text).split(' ');\n ret.push(parts[0]);\n }\n }\n return ret;\n}\n\nfunction parseDocParts(comments: string | undefined, tags: ts.JSDocTagInfo[]): DocsParsingResult {\n const diagnostics = new Array<string>();\n const docs: spec.Docs = {};\n const hints: TypeSystemHints = {};\n\n [docs.summary, docs.remarks] = splitSummary(comments);\n\n const tagNames = new Map<string, string | undefined>();\n for (const tag of tags) {\n // 'param' gets parsed as a tag and as a comment for a method\n // 'jsii' is internal-only and shouldn't surface in the API doc\n if (tag.name !== DocTag.PARAM && tag.name !== DocTag.JSII) {\n tagNames.set(tag.name, tag.text && ts.displayPartsToString(tag.text));\n }\n }\n\n function eatTag(...names: string[]): string | undefined {\n for (const name of names) {\n if (tagNames.has(name)) {\n const ret = tagNames.get(name);\n tagNames.delete(name);\n return ret ?? '';\n }\n }\n return undefined;\n }\n\n if (eatTag(DocTag.STRUCT) != null) {\n hints.struct = true;\n }\n\n docs.default = eatTag(DocTag.DEFAULT, DocTag.DEFAULT_VALUE);\n docs.deprecated = eatTag(DocTag.DEPRECATED);\n docs.example = eatTag(DocTag.EXAMPLE);\n docs.returns = eatTag(DocTag.RETURNS, DocTag.RETURN);\n docs.see = eatTag(DocTag.SEE);\n docs.subclassable = eatTag(DocTag.SUBCLASSABLE) !== undefined ? true : undefined;\n\n docs.stability = parseStability(eatTag(DocTag.STABILITY), diagnostics);\n // @experimental is a shorthand for '@stability experimental', same for '@stable'\n const experimental = eatTag(DocTag.EXPERIMENTAL) !== undefined;\n const stable = eatTag(DocTag.STABLE) !== undefined;\n // Can't combine them\n if (countBools(docs.stability !== undefined, experimental, stable) > 1) {\n diagnostics.push('Use only one of @stability, @experimental or @stable');\n }\n if (experimental) {\n docs.stability = spec.Stability.Experimental;\n }\n if (stable) {\n docs.stability = spec.Stability.Stable;\n }\n\n // Can combine '@stability deprecated' with '@deprecated <reason>'\n if (docs.deprecated !== undefined) {\n if (docs.stability !== undefined && docs.stability !== spec.Stability.Deprecated) {\n diagnostics.push(\"@deprecated tag requires '@stability deprecated' or no @stability at all.\");\n }\n docs.stability = spec.Stability.Deprecated;\n }\n\n if (docs.example?.includes('```')) {\n // This is currently what the JSDoc standard expects, and VSCode highlights it in\n // this way as well. TSDoc disagrees and says that examples start in text mode\n // which I tend to agree with, but that hasn't become a widely used standard yet.\n //\n // So we conform to existing reality.\n diagnostics.push('@example must be code only, no code block fences allowed.');\n }\n\n if (docs.deprecated?.trim() === '') {\n diagnostics.push('@deprecated tag needs a reason and/or suggested alternatives.');\n }\n\n if (tagNames.size > 0) {\n docs.custom = {};\n for (const [key, value] of tagNames.entries()) {\n docs.custom[key] = value ?? 'true'; // Key must have a value or it will be stripped from the assembly\n }\n }\n\n return { docs, diagnostics, hints };\n}\n\nexport interface DocsParsingResult {\n docs: spec.Docs;\n hints: TypeSystemHints;\n diagnostics?: string[];\n}\n\nexport interface TypeSystemHints {\n /**\n * Only present on interfaces. This indicates that interface must be handled as a struct/data type\n * even through it's name starts with a capital letter `I`.\n */\n struct?: boolean;\n}\n\n/**\n * Split the doc comment into summary and remarks\n *\n * Normally, we'd expect people to split into a summary line and detail lines using paragraph\n * markers. However, a LOT of people do not do this, and just paste a giant comment block into\n * the docstring. If we detect that situation, we will try and extract the first sentence (using\n * a period) as the summary.\n */\nexport function splitSummary(docBlock: string | undefined): [string | undefined, string | undefined] {\n if (!docBlock) {\n return [undefined, undefined];\n }\n const summary = summaryLine(docBlock);\n const remarks = uberTrim(docBlock.slice(summary.length));\n return [endWithPeriod(noNewlines(summary.trim())), remarks];\n}\n\n/**\n * Replace newlines with spaces for use in tables\n */\nfunction noNewlines(s: string) {\n return s.replace(/\\r?\\n/g, ' ');\n}\n\nfunction endWithPeriod(s: string) {\n return ENDS_WITH_PUNCTUATION_REGEX.test(s) ? s : `${s}.`;\n}\n\n/**\n * Trims a string and turns it into `undefined` if the result would have been an\n * empty string.\n */\nfunction uberTrim(str: string): string | undefined {\n str = str.trim();\n return str === '' ? undefined : str;\n}\n\nconst SUMMARY_MAX_WORDS = 20;\n\n/**\n * Find the summary line for a doc comment\n *\n * In principle we'll take the first paragraph, but if there are no paragraphs\n * (because people don't put in paragraph breaks) or the first paragraph is too\n * long, we'll take the first sentence (terminated by a punctuation).\n */\nfunction summaryLine(str: string) {\n const paras = str.split('\\n\\n');\n if (paras.length > 1 && paras[0].split(' ').length < SUMMARY_MAX_WORDS) {\n return paras[0];\n }\n\n const m = FIRST_SENTENCE_REGEX.exec(str);\n if (m) {\n return m[1];\n }\n\n return paras[0];\n}\n\nconst PUNCTUATION = ['!', '?', '.', ';'].map((s) => `\\\\${s}`).join('');\nconst ENDS_WITH_PUNCTUATION_REGEX = new RegExp(`[${PUNCTUATION}]$`);\nconst FIRST_SENTENCE_REGEX = new RegExp(`^([^${PUNCTUATION}]+[${PUNCTUATION}][ \\n\\r])`); // Needs a whitespace after the punctuation.\n\nfunction intBool(x: boolean): number {\n return x ? 1 : 0;\n}\n\nfunction countBools(...x: boolean[]) {\n return x.map(intBool).reduce((a, b) => a + b, 0);\n}\n\nfunction parseStability(s: string | undefined, diagnostics: string[]): spec.Stability | undefined {\n if (s === undefined) {\n return undefined;\n }\n\n switch (s) {\n case 'stable':\n return spec.Stability.Stable;\n case 'experimental':\n return spec.Stability.Experimental;\n case 'external':\n return spec.Stability.External;\n case 'deprecated':\n return spec.Stability.Deprecated;\n }\n diagnostics.push(`Unrecognized @stability: '${s}'`);\n return undefined;\n}\n\n/**\n * Unrecognized tags that follow an '@ example' tag will be absorbed back into the example value\n *\n * The TypeScript parser by itself is naive and will start parsing a new tag there.\n *\n * We do this until we encounter a supported @ keyword.\n */\nfunction reabsorbExampleTags(tags: ts.JSDocTagInfo[]): ts.JSDocTagInfo[] {\n const ret = [...tags];\n\n let i = 0;\n while (i < ret.length) {\n if (ret[i].name === 'example') {\n while (i + 1 < ret.length && !RECOGNIZED_TAGS.has(ret[i + 1].name)) {\n // Incorrectly classified as @tag, absorb back into example\n ret[i].text ??= [];\n ret[i].text!.push({\n text: `@${ret[i + 1].name}${ret[i + 1].text}`,\n kind: '',\n });\n ret.splice(i + 1, 1);\n }\n }\n i++;\n }\n\n return ret;\n}\n"]}
|
|
1
|
+
{"version":3,"file":"docs.js","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Doc Comment parsing\n *\n * I tried using TSDoc here.\n *\n * Pro:\n * - Future standard.\n * - Does validating parsing and complains on failure.\n * - Has a more flexible interpretation of the @example tag (starts in text mode).\n *\n * Con:\n * - Different tags from JSDoc (@defaultValue instead of @default, \"@param name\n * description\" instead \"@param name description\".\n * - @example tag has a different interpretation than VSCode and JSDoc\n * (VSCode/JSDoc starts in code mode), which is confusing for syntax\n * highlighting in the editor.\n * - Allows no unknown tags.\n * - Wants to be in charge of parsing TypeScript, integrating into other build is\n * possible but harder.\n * - Parse to a DOM with no easy way to roundtrip back to equivalent MarkDown.\n *\n * Especially the last point: while parsing to and storing the parsed docs DOM\n * in the jsii assembly is superior in the long term (for example for\n * converting to different output formats, JavaDoc, C# docs, refdocs which all\n * accept slightly different syntaxes), right now we can get 80% of the bang\n * for 10% of the buck by just reading, storing and reproducing MarkDown, which\n * is Readable Enough(tm).\n *\n * If we ever want to attempt TSDoc again, this would be a good place to look at:\n *\n * https://github.com/Microsoft/tsdoc/blob/master/api-demo/src/advancedDemo.ts\n */\nimport * as spec from '@jsii/spec';\nimport * as ts from 'typescript';\n\n/**\n * Tags that we recognize\n */\nenum DocTag {\n PARAM = 'param',\n DEFAULT = 'default',\n DEFAULT_VALUE = 'defaultValue',\n DEPRECATED = 'deprecated',\n RETURNS = 'returns',\n RETURN = 'return',\n STABLE = 'stable',\n EXPERIMENTAL = 'experimental',\n SEE = 'see',\n SUBCLASSABLE = 'subclassable',\n EXAMPLE = 'example',\n STABILITY = 'stability',\n STRUCT = 'struct',\n\n // Not forwarded, this is compiler-internal.\n JSII = 'jsii',\n}\n\nconst RECOGNIZED_TAGS: ReadonlySet<String> = new Set(Object.values(DocTag));\n\n/**\n * Parse all doc comments that apply to a symbol into JSIIDocs format\n */\nexport function parseSymbolDocumentation(sym: ts.Symbol, typeChecker: ts.TypeChecker): DocsParsingResult {\n const comment = ts.displayPartsToString(sym.getDocumentationComment(typeChecker)).trim();\n const tags = reabsorbExampleTags(sym.getJsDocTags());\n\n // Right here we'll just guess that the first declaration site is the most important one.\n return parseDocParts(comment, tags);\n}\n\n/**\n * Return the list of parameter names that are referenced in the docstring for this symbol\n */\nexport function getReferencedDocParams(sym: ts.Symbol): string[] {\n const ret = new Array<string>();\n for (const tag of sym.getJsDocTags()) {\n if (tag.name === DocTag.PARAM) {\n const parts = ts.displayPartsToString(tag.text).split(' ');\n ret.push(parts[0]);\n }\n }\n return ret;\n}\n\nfunction parseDocParts(comments: string | undefined, tags: ts.JSDocTagInfo[]): DocsParsingResult {\n const diagnostics = new Array<string>();\n const docs: spec.Docs = {};\n const hints: TypeSystemHints = {};\n\n [docs.summary, docs.remarks] = splitSummary(comments);\n\n const tagNames = new Map<string, string | undefined>();\n for (const tag of tags) {\n // 'param' gets parsed as a tag and as a comment for a method\n // 'jsii' is internal-only and shouldn't surface in the API doc\n if (tag.name !== DocTag.PARAM && tag.name !== DocTag.JSII) {\n tagNames.set(tag.name, tag.text && ts.displayPartsToString(tag.text));\n }\n }\n\n function eatTag(...names: string[]): string | undefined {\n for (const name of names) {\n if (tagNames.has(name)) {\n const ret = tagNames.get(name);\n tagNames.delete(name);\n return ret ?? '';\n }\n }\n return undefined;\n }\n\n if (eatTag(DocTag.STRUCT) != null) {\n hints.struct = true;\n }\n\n docs.default = eatTag(DocTag.DEFAULT, DocTag.DEFAULT_VALUE);\n docs.deprecated = eatTag(DocTag.DEPRECATED);\n docs.example = eatTag(DocTag.EXAMPLE);\n docs.returns = eatTag(DocTag.RETURNS, DocTag.RETURN);\n docs.see = eatTag(DocTag.SEE);\n docs.subclassable = eatTag(DocTag.SUBCLASSABLE) !== undefined ? true : undefined;\n\n docs.stability = parseStability(eatTag(DocTag.STABILITY), diagnostics);\n // @experimental is a shorthand for '@stability experimental', same for '@stable'\n const experimental = eatTag(DocTag.EXPERIMENTAL) !== undefined;\n const stable = eatTag(DocTag.STABLE) !== undefined;\n // Can't combine them\n if (countBools(docs.stability !== undefined, experimental, stable) > 1) {\n diagnostics.push('Use only one of @stability, @experimental or @stable');\n }\n if (experimental) {\n docs.stability = spec.Stability.Experimental;\n }\n if (stable) {\n docs.stability = spec.Stability.Stable;\n }\n\n // Can combine '@stability deprecated' with '@deprecated <reason>'\n if (docs.deprecated !== undefined) {\n if (docs.stability !== undefined && docs.stability !== spec.Stability.Deprecated) {\n diagnostics.push(\"@deprecated tag requires '@stability deprecated' or no @stability at all.\");\n }\n docs.stability = spec.Stability.Deprecated;\n }\n\n if (docs.example?.includes('```')) {\n // This is currently what the JSDoc standard expects, and VSCode highlights it in\n // this way as well. TSDoc disagrees and says that examples start in text mode\n // which I tend to agree with, but that hasn't become a widely used standard yet.\n //\n // So we conform to existing reality.\n diagnostics.push('@example must be code only, no code block fences allowed.');\n }\n\n if (docs.deprecated?.trim() === '') {\n diagnostics.push('@deprecated tag needs a reason and/or suggested alternatives.');\n }\n\n if (tagNames.size > 0) {\n docs.custom = {};\n for (const [key, value] of tagNames.entries()) {\n docs.custom[key] = value ?? 'true'; // Key must have a value or it will be stripped from the assembly\n }\n }\n\n return { docs, diagnostics, hints };\n}\n\nexport interface DocsParsingResult {\n docs: spec.Docs;\n hints: TypeSystemHints;\n diagnostics?: string[];\n}\n\nexport interface TypeSystemHints {\n /**\n * Only present on interfaces. This indicates that interface must be handled as a struct/data type\n * even through it's name starts with a capital letter `I`.\n */\n struct?: boolean;\n}\n\n/**\n * Split the doc comment into summary and remarks\n *\n * Normally, we'd expect people to split into a summary line and detail lines using paragraph\n * markers. However, a LOT of people do not do this, and just paste a giant comment block into\n * the docstring. If we detect that situation, we will try and extract the first sentence (using\n * a period) as the summary.\n */\nexport function splitSummary(docBlock: string | undefined): [string | undefined, string | undefined] {\n if (!docBlock) {\n return [undefined, undefined];\n }\n const summary = summaryLine(docBlock);\n const remarks = uberTrim(docBlock.slice(summary.length));\n return [endWithPeriod(noNewlines(summary.trim())), remarks];\n}\n\n/**\n * Replace newlines with spaces for use in tables\n */\nfunction noNewlines(s: string) {\n return s.replace(/\\r?\\n/g, ' ');\n}\n\nfunction endWithPeriod(s: string) {\n return ENDS_WITH_PUNCTUATION_REGEX.test(s) ? s : `${s}.`;\n}\n\n/**\n * Trims a string and turns it into `undefined` if the result would have been an\n * empty string.\n */\nfunction uberTrim(str: string): string | undefined {\n str = str.trim();\n return str === '' ? undefined : str;\n}\n\nconst SUMMARY_MAX_WORDS = 20;\n\n/**\n * Find the summary line for a doc comment\n *\n * In principle we'll take the first paragraph, but if there are no paragraphs\n * (because people don't put in paragraph breaks) or the first paragraph is too\n * long, we'll take the first sentence (terminated by a punctuation).\n */\nfunction summaryLine(str: string) {\n const paras = str.split(/(\\r?\\n){2}/);\n if (paras.length > 1 && paras[0].split(' ').length < SUMMARY_MAX_WORDS) {\n return paras[0];\n }\n\n const m = FIRST_SENTENCE_REGEX.exec(str);\n if (m) {\n return m[1];\n }\n\n return paras[0];\n}\n\nconst PUNCTUATION = ['!', '?', '.', ';'].map((s) => `\\\\${s}`).join('');\nconst ENDS_WITH_PUNCTUATION_REGEX = new RegExp(`[${PUNCTUATION}]$`);\nconst FIRST_SENTENCE_REGEX = new RegExp(`^([^${PUNCTUATION}]+[${PUNCTUATION}][ \\n\\r])`); // Needs a whitespace after the punctuation.\n\nfunction intBool(x: boolean): number {\n return x ? 1 : 0;\n}\n\nfunction countBools(...x: boolean[]) {\n return x.map(intBool).reduce((a, b) => a + b, 0);\n}\n\nfunction parseStability(s: string | undefined, diagnostics: string[]): spec.Stability | undefined {\n if (s === undefined) {\n return undefined;\n }\n\n switch (s) {\n case 'stable':\n return spec.Stability.Stable;\n case 'experimental':\n return spec.Stability.Experimental;\n case 'external':\n return spec.Stability.External;\n case 'deprecated':\n return spec.Stability.Deprecated;\n }\n diagnostics.push(`Unrecognized @stability: '${s}'`);\n return undefined;\n}\n\n/**\n * Unrecognized tags that follow an '@ example' tag will be absorbed back into the example value\n *\n * The TypeScript parser by itself is naive and will start parsing a new tag there.\n *\n * We do this until we encounter a supported @ keyword.\n */\nfunction reabsorbExampleTags(tags: ts.JSDocTagInfo[]): ts.JSDocTagInfo[] {\n const ret = [...tags];\n\n let i = 0;\n while (i < ret.length) {\n if (ret[i].name === 'example') {\n while (i + 1 < ret.length && !RECOGNIZED_TAGS.has(ret[i + 1].name)) {\n // Incorrectly classified as @tag, absorb back into example\n ret[i].text ??= [];\n ret[i].text!.push({\n text: `@${ret[i + 1].name}${ret[i + 1].text}`,\n kind: '',\n });\n ret.splice(i + 1, 1);\n }\n }\n i++;\n }\n\n return ret;\n}\n"]}
|
package/lib/version.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/** The short version number for this JSII compiler (e.g: `X.Y.Z`) */
|
|
2
|
-
export declare const SHORT_VERSION = "5.4.24
|
|
2
|
+
export declare const SHORT_VERSION = "5.4.24";
|
|
3
3
|
/** The qualified version number for this JSII compiler (e.g: `X.Y.Z (build #######)`) */
|
|
4
|
-
export declare const VERSION = "5.4.24
|
|
4
|
+
export declare const VERSION = "5.4.24 (build 31c832c)";
|
|
5
5
|
/** The release line identifier for this JSII compiler (e.g: `X.Y`) */
|
|
6
6
|
export declare const RELEASE_LINE = "5.4";
|
|
7
7
|
//# sourceMappingURL=version.d.ts.map
|
package/lib/version.js
CHANGED
|
@@ -4,9 +4,9 @@ exports.RELEASE_LINE = exports.VERSION = exports.SHORT_VERSION = void 0;
|
|
|
4
4
|
const typescript_1 = require("typescript");
|
|
5
5
|
// GENERATED: This file is generated by build-tools/code-gen.ts -- Do not edit by hand!
|
|
6
6
|
/** The short version number for this JSII compiler (e.g: `X.Y.Z`) */
|
|
7
|
-
exports.SHORT_VERSION = '5.4.24
|
|
7
|
+
exports.SHORT_VERSION = '5.4.24';
|
|
8
8
|
/** The qualified version number for this JSII compiler (e.g: `X.Y.Z (build #######)`) */
|
|
9
|
-
exports.VERSION = '5.4.24
|
|
9
|
+
exports.VERSION = '5.4.24 (build 31c832c)';
|
|
10
10
|
/** The release line identifier for this JSII compiler (e.g: `X.Y`) */
|
|
11
11
|
exports.RELEASE_LINE = typescript_1.versionMajorMinor;
|
|
12
12
|
//# sourceMappingURL=version.js.map
|
package/lib/version.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";;;AAAA,2CAA+C;AAE/C,uFAAuF;AAEvF,qEAAqE;AACxD,QAAA,aAAa,GAAG,
|
|
1
|
+
{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";;;AAAA,2CAA+C;AAE/C,uFAAuF;AAEvF,qEAAqE;AACxD,QAAA,aAAa,GAAG,QAAQ,CAAC;AAEtC,yFAAyF;AAC5E,QAAA,OAAO,GAAG,wBAAwB,CAAC;AAEhD,sEAAsE;AACzD,QAAA,YAAY,GAAG,8BAAiB,CAAC","sourcesContent":["import { versionMajorMinor } from 'typescript';\n\n// GENERATED: This file is generated by build-tools/code-gen.ts -- Do not edit by hand!\n\n/** The short version number for this JSII compiler (e.g: `X.Y.Z`) */\nexport const SHORT_VERSION = '5.4.24';\n\n/** The qualified version number for this JSII compiler (e.g: `X.Y.Z (build #######)`) */\nexport const VERSION = '5.4.24 (build 31c832c)';\n\n/** The release line identifier for this JSII compiler (e.g: `X.Y`) */\nexport const RELEASE_LINE = versionMajorMinor;\n"]}
|
package/package.json
CHANGED
|
@@ -70,8 +70,8 @@
|
|
|
70
70
|
"ts-node": "^10.9.2"
|
|
71
71
|
},
|
|
72
72
|
"dependencies": {
|
|
73
|
-
"@jsii/check-node": "1.
|
|
74
|
-
"@jsii/spec": "^1.
|
|
73
|
+
"@jsii/check-node": "1.101.0",
|
|
74
|
+
"@jsii/spec": "^1.101.0",
|
|
75
75
|
"case": "^1.6.3",
|
|
76
76
|
"chalk": "^4",
|
|
77
77
|
"downlevel-dts": "^0.11.0",
|
|
@@ -93,7 +93,7 @@
|
|
|
93
93
|
"publishConfig": {
|
|
94
94
|
"access": "public"
|
|
95
95
|
},
|
|
96
|
-
"version": "5.4.24
|
|
96
|
+
"version": "5.4.24",
|
|
97
97
|
"types": "lib/index.d.ts",
|
|
98
98
|
"exports": {
|
|
99
99
|
".": "./lib/index.js",
|