@travetto/doc 5.0.0-rc.1 → 5.0.0-rc.10
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/__index__.ts +2 -1
- package/package.json +3 -3
- package/src/jsx.ts +4 -4
- package/src/mapping/mod-mapping.ts +16 -12
- package/src/render/code-highlight.ts +9 -9
- package/src/render/context.ts +9 -8
- package/src/render/html.ts +3 -3
- package/src/render/markdown.ts +3 -3
- package/src/render/renderer.ts +11 -15
- package/src/util/file.ts +41 -44
- package/src/util/resolve.ts +10 -10
- package/src/util/run.ts +4 -5
- package/support/cli.doc.ts +4 -4
package/__index__.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
1
|
export { JSXElement as DocJSXElement, isJSXElement as isDocJSXElement } from './jsx-runtime';
|
|
2
2
|
export { c, d, JSXElementByFn as DocJSXElementByFn } from './src/jsx';
|
|
3
|
-
export { MOD_MAPPING as mod } from './src/mapping/mod-mapping';
|
|
3
|
+
export { MOD_MAPPING as mod } from './src/mapping/mod-mapping';
|
|
4
|
+
export { DocFileUtil } from './src/util/file';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@travetto/doc",
|
|
3
|
-
"version": "5.0.0-rc.
|
|
3
|
+
"version": "5.0.0-rc.10",
|
|
4
4
|
"description": "Documentation support for the Travetto framework",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"docs",
|
|
@@ -24,12 +24,12 @@
|
|
|
24
24
|
"directory": "module/doc"
|
|
25
25
|
},
|
|
26
26
|
"dependencies": {
|
|
27
|
-
"@travetto/
|
|
27
|
+
"@travetto/runtime": "^5.0.0-rc.10",
|
|
28
28
|
"@types/prismjs": "^1.26.4",
|
|
29
29
|
"prismjs": "^1.29.0"
|
|
30
30
|
},
|
|
31
31
|
"peerDependencies": {
|
|
32
|
-
"@travetto/cli": "^5.0.0-rc.
|
|
32
|
+
"@travetto/cli": "^5.0.0-rc.11"
|
|
33
33
|
},
|
|
34
34
|
"peerDependenciesMeta": {
|
|
35
35
|
"@travetto/cli": {
|
package/src/jsx.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { createElement, JSXElement, JSXComponentFunction as CompFn } from '@travetto/doc/jsx-runtime';
|
|
2
|
-
import { TypedObject } from '@travetto/
|
|
2
|
+
import { castTo, TypedObject } from '@travetto/runtime';
|
|
3
3
|
|
|
4
4
|
import { LIB_MAPPING } from './mapping/lib-mapping';
|
|
5
5
|
import { MOD_MAPPING } from './mapping/mod-mapping';
|
|
@@ -65,7 +65,7 @@ export type JSXElements = { [K in keyof C]: JSXElementByFn<K>; };
|
|
|
65
65
|
|
|
66
66
|
export const EMPTY_ELEMENT = EMPTY;
|
|
67
67
|
|
|
68
|
-
const invertedC = new Map<Function, string>(TypedObject.entries(c).map(p => [p[1], p[0]]
|
|
68
|
+
const invertedC = new Map<Function, string>(TypedObject.entries(c).map<[Function, string]>(p => [p[1], p[0]]));
|
|
69
69
|
|
|
70
70
|
export function getComponentName(fn: Function | string): string {
|
|
71
71
|
if (typeof fn === 'string') {
|
|
@@ -81,7 +81,7 @@ function CodeLinker(titleOrNode: string | JSXElement, src?: string, startRe?: Re
|
|
|
81
81
|
if (typeof titleOrNode === 'string') {
|
|
82
82
|
props = { title: titleOrNode, src: src!, startRe: startRe! };
|
|
83
83
|
} else if (titleOrNode.type === Code) {
|
|
84
|
-
const node
|
|
84
|
+
const node: JSXElementByFn<'Code'> = castTo(titleOrNode);
|
|
85
85
|
props = {
|
|
86
86
|
title: node.props.title,
|
|
87
87
|
src: node.props.src,
|
|
@@ -90,7 +90,7 @@ function CodeLinker(titleOrNode: string | JSXElement, src?: string, startRe?: Re
|
|
|
90
90
|
} else {
|
|
91
91
|
throw new Error(`Unsupported element type: ${titleOrNode.type}`);
|
|
92
92
|
}
|
|
93
|
-
return createElement(c.CodeLink, props)
|
|
93
|
+
return createElement(c.CodeLink, props);
|
|
94
94
|
}
|
|
95
95
|
|
|
96
96
|
export const d = {
|
|
@@ -1,12 +1,4 @@
|
|
|
1
1
|
export const MOD_MAPPING = {
|
|
2
|
-
Asset: {
|
|
3
|
-
name: '@travetto/asset', folder: '@travetto/asset', displayName: 'Asset',
|
|
4
|
-
description: 'Modular library for storing and retrieving binary assets'
|
|
5
|
-
},
|
|
6
|
-
AssetRest: {
|
|
7
|
-
name: '@travetto/asset-rest', folder: '@travetto/asset-rest', displayName: 'Asset Rest Support',
|
|
8
|
-
description: 'Provides integration between the travetto asset and rest module.'
|
|
9
|
-
},
|
|
10
2
|
Auth: {
|
|
11
3
|
name: '@travetto/auth', folder: '@travetto/auth', displayName: 'Authentication',
|
|
12
4
|
description: 'Authentication scaffolding for the Travetto framework'
|
|
@@ -31,10 +23,6 @@ export const MOD_MAPPING = {
|
|
|
31
23
|
name: '@travetto/auth-rest-session', folder: '@travetto/auth-rest-session', displayName: 'Rest Auth Session',
|
|
32
24
|
description: 'Rest authentication session integration support for the Travetto framework'
|
|
33
25
|
},
|
|
34
|
-
Base: {
|
|
35
|
-
name: '@travetto/base', folder: '@travetto/base', displayName: 'Base',
|
|
36
|
-
description: 'Environment config and common utilities for travetto applications.'
|
|
37
|
-
},
|
|
38
26
|
Cache: {
|
|
39
27
|
name: '@travetto/cache', folder: '@travetto/cache', displayName: 'Caching',
|
|
40
28
|
description: 'Caching functionality with decorators for declarative use.'
|
|
@@ -115,10 +103,18 @@ export const MOD_MAPPING = {
|
|
|
115
103
|
name: '@travetto/model-elasticsearch', folder: '@travetto/model-elasticsearch', displayName: 'Elasticsearch Model Source',
|
|
116
104
|
description: 'Elasticsearch backing for the travetto model module, with real-time modeling support for Elasticsearch mappings.'
|
|
117
105
|
},
|
|
106
|
+
ModelFile: {
|
|
107
|
+
name: '@travetto/model-file', folder: '@travetto/model-file', displayName: 'File Model Support',
|
|
108
|
+
description: 'File system backing for the travetto model module.'
|
|
109
|
+
},
|
|
118
110
|
ModelFirestore: {
|
|
119
111
|
name: '@travetto/model-firestore', folder: '@travetto/model-firestore', displayName: 'Firestore Model Support',
|
|
120
112
|
description: 'Firestore backing for the travetto model module.'
|
|
121
113
|
},
|
|
114
|
+
ModelMemory: {
|
|
115
|
+
name: '@travetto/model-memory', folder: '@travetto/model-memory', displayName: 'Memory Model Support',
|
|
116
|
+
description: 'Memory backing for the travetto model module.'
|
|
117
|
+
},
|
|
122
118
|
ModelMongo: {
|
|
123
119
|
name: '@travetto/model-mongo', folder: '@travetto/model-mongo', displayName: 'MongoDB Model Support',
|
|
124
120
|
description: 'Mongo backing for the travetto model module.'
|
|
@@ -135,6 +131,10 @@ export const MOD_MAPPING = {
|
|
|
135
131
|
name: '@travetto/model-query', folder: '@travetto/model-query', displayName: 'Data Model Querying',
|
|
136
132
|
description: 'Datastore abstraction for advanced query support.'
|
|
137
133
|
},
|
|
134
|
+
ModelQueryLanguage: {
|
|
135
|
+
name: '@travetto/model-query-language', folder: '@travetto/model-query-language', displayName: 'Data Model Query Language',
|
|
136
|
+
description: 'Datastore query language.'
|
|
137
|
+
},
|
|
138
138
|
ModelRedis: {
|
|
139
139
|
name: '@travetto/model-redis', folder: '@travetto/model-redis', displayName: 'Redis Model Support',
|
|
140
140
|
description: 'Redis backing for the travetto model module.'
|
|
@@ -219,6 +219,10 @@ export const MOD_MAPPING = {
|
|
|
219
219
|
name: '@travetto/rest-upload', folder: '@travetto/rest-upload', displayName: 'Rest Upload Support',
|
|
220
220
|
description: 'Provides integration between the travetto asset and rest module.'
|
|
221
221
|
},
|
|
222
|
+
Runtime: {
|
|
223
|
+
name: '@travetto/runtime', folder: '@travetto/runtime', displayName: 'Runtime',
|
|
224
|
+
description: 'Runtime for travetto applications.'
|
|
225
|
+
},
|
|
222
226
|
Scaffold: {
|
|
223
227
|
name: '@travetto/scaffold', folder: '@travetto/scaffold', displayName: 'App Scaffold',
|
|
224
228
|
description: 'App Scaffold for the Travetto framework'
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { default as
|
|
1
|
+
import { default as prismJs } from 'prismjs';
|
|
2
2
|
|
|
3
3
|
import 'prismjs/plugins/normalize-whitespace/prism-normalize-whitespace.js';
|
|
4
4
|
import 'prismjs/components/prism-typescript.js';
|
|
@@ -12,20 +12,20 @@ import 'prismjs/components/prism-sql.js';
|
|
|
12
12
|
import 'prismjs/components/prism-properties.js';
|
|
13
13
|
import 'prismjs/components/prism-bash.js';
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
prismJs.plugins.NormalizeWhitespace.setDefaults({
|
|
16
16
|
'remove-trailing': true,
|
|
17
17
|
'remove-indent': true,
|
|
18
18
|
'left-trim': true,
|
|
19
19
|
'right-trim': true
|
|
20
20
|
});
|
|
21
21
|
|
|
22
|
-
const nw =
|
|
22
|
+
const nw = prismJs.plugins.NormalizeWhitespace;
|
|
23
23
|
|
|
24
24
|
const tokenMapping: { [key: string]: string } = {
|
|
25
|
-
gt: '>',
|
|
26
|
-
lt: '<',
|
|
27
|
-
quot: '"',
|
|
28
|
-
apos: "'"
|
|
25
|
+
'>': '>',
|
|
26
|
+
'<': '<',
|
|
27
|
+
'"': '"',
|
|
28
|
+
''': "'"
|
|
29
29
|
};
|
|
30
30
|
|
|
31
31
|
export function highlight(text: string, lang: string): string | undefined {
|
|
@@ -35,10 +35,10 @@ export function highlight(text: string, lang: string): string | undefined {
|
|
|
35
35
|
|
|
36
36
|
text = text
|
|
37
37
|
.replace(/&#(\d+);/g, (x, code) => String.fromCharCode(code))
|
|
38
|
-
.replace(/&
|
|
38
|
+
.replace(/&[a-z][^;]*;/g, a => tokenMapping[a] || a);
|
|
39
39
|
|
|
40
40
|
try {
|
|
41
|
-
return
|
|
41
|
+
return prismJs.highlight(text, prismJs.languages[lang], lang)
|
|
42
42
|
.replace(/(@\s*<span[^>]*)function("\s*>)/g, (a, pre, post) => `${pre}meta${post}`)
|
|
43
43
|
.replace(/[{}]/g, a => `{{'${a}'}}`);
|
|
44
44
|
} catch (err) {
|
package/src/render/context.ts
CHANGED
|
@@ -1,6 +1,9 @@
|
|
|
1
|
+
import path from 'node:path';
|
|
2
|
+
|
|
1
3
|
import { createElement, JSXRuntimeTag } from '@travetto/doc/jsx-runtime';
|
|
2
4
|
|
|
3
|
-
import {
|
|
5
|
+
import { PackageUtil } from '@travetto/manifest';
|
|
6
|
+
import { castTo, RuntimeIndex } from '@travetto/runtime';
|
|
4
7
|
|
|
5
8
|
import { JSXElementByFn, c } from '../jsx';
|
|
6
9
|
import { DocResolveUtil, ResolvedCode, ResolvedRef, ResolvedSnippetLink } from '../util/resolve';
|
|
@@ -37,7 +40,7 @@ export class RenderContext {
|
|
|
37
40
|
|
|
38
41
|
const manifestPkg = PackageUtil.readPackage(RuntimeIndex.getModule('@travetto/manifest')!.sourcePath);
|
|
39
42
|
|
|
40
|
-
this.file = path.
|
|
43
|
+
this.file = path.resolve(file);
|
|
41
44
|
this.baseUrl = baseUrl;
|
|
42
45
|
this.repoRoot = repoRoot;
|
|
43
46
|
this.travettoBaseUrl = repoRoot.includes('travetto.github') ? repoRoot : manifestPkg.travetto!.doc!.baseUrl!;
|
|
@@ -105,18 +108,16 @@ export class RenderContext {
|
|
|
105
108
|
* Resolve code link
|
|
106
109
|
*/
|
|
107
110
|
async resolveCodeLink(node: JSXElementByFn<'CodeLink'>): Promise<ResolvedSnippetLink> {
|
|
108
|
-
|
|
109
|
-
return DocResolveUtil.resolveCodeLink(src, node.props.startRe);
|
|
111
|
+
return DocResolveUtil.resolveCodeLink(node.props.src, node.props.startRe);
|
|
110
112
|
}
|
|
111
113
|
|
|
112
114
|
/**
|
|
113
115
|
* Resolve code/config
|
|
114
116
|
*/
|
|
115
117
|
async resolveCode(node: JSXElementByFn<'Code' | 'Config'>): Promise<ResolvedCode> {
|
|
116
|
-
const src = typeof node.props.src === 'string' ? node.props.src : RuntimeIndex.getFunctionMetadata(node.props.src)!.source;
|
|
117
118
|
return node.props.startRe ?
|
|
118
|
-
DocResolveUtil.resolveSnippet(src, node.props.startRe, node.props.endRe, node.props.outline) :
|
|
119
|
-
DocResolveUtil.resolveCode(src, node.props.language, node.props.outline);
|
|
119
|
+
DocResolveUtil.resolveSnippet(node.props.src, node.props.startRe, node.props.endRe, node.props.outline) :
|
|
120
|
+
DocResolveUtil.resolveCode(node.props.src, node.props.language, node.props.outline);
|
|
120
121
|
}
|
|
121
122
|
|
|
122
123
|
/**
|
|
@@ -124,6 +125,6 @@ export class RenderContext {
|
|
|
124
125
|
*/
|
|
125
126
|
createElement<K extends keyof typeof c>(name: K, props: JSXElementByFn<K>['props']): JSXElementByFn<K> {
|
|
126
127
|
// @ts-expect-error
|
|
127
|
-
return createElement(c[name], props)
|
|
128
|
+
return castTo(createElement(c[name], props));
|
|
128
129
|
}
|
|
129
130
|
}
|
package/src/render/html.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import fs from 'node:fs/promises';
|
|
2
2
|
|
|
3
3
|
import { JSXElement } from '@travetto/doc/jsx-runtime';
|
|
4
|
-
import {
|
|
5
|
-
import {
|
|
4
|
+
import { Runtime, RuntimeIndex } from '@travetto/runtime';
|
|
5
|
+
import { PackageUtil } from '@travetto/manifest';
|
|
6
6
|
|
|
7
7
|
import { highlight } from './code-highlight';
|
|
8
8
|
import { RenderProvider, RenderState } from '../types';
|
|
@@ -145,7 +145,7 @@ yarn add ${el.props.pkg}
|
|
|
145
145
|
Header: async ({ props }) => `<h1>${props.title} ${props.description ? `\n<small>${props.description}</small>\n` : ''}</h1>\n`,
|
|
146
146
|
|
|
147
147
|
StdHeader: async state => {
|
|
148
|
-
const mod = state.el.props.mod ??
|
|
148
|
+
const mod = state.el.props.mod ?? Runtime.main.name;
|
|
149
149
|
const pkg = PackageUtil.readPackage(RuntimeIndex.getModule(mod)!.sourcePath);
|
|
150
150
|
const title = pkg.travetto?.displayName ?? pkg.name;
|
|
151
151
|
const desc = pkg.description;
|
package/src/render/markdown.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import fs from 'node:fs/promises';
|
|
2
|
-
import {
|
|
3
|
-
import { PackageUtil
|
|
2
|
+
import { Runtime, RuntimeIndex } from '@travetto/runtime';
|
|
3
|
+
import { PackageUtil } from '@travetto/manifest';
|
|
4
4
|
|
|
5
5
|
import { RenderProvider } from '../types';
|
|
6
6
|
import { c, getComponentName } from '../jsx';
|
|
@@ -109,7 +109,7 @@ ${context.cleanText(content.text)}
|
|
|
109
109
|
Header: async ({ props }) => `# ${props.title}\n${props.description ? `## ${props.description}\n` : ''}\n`,
|
|
110
110
|
|
|
111
111
|
StdHeader: async state => {
|
|
112
|
-
const mod = state.el.props.mod ??
|
|
112
|
+
const mod = state.el.props.mod ?? Runtime.main.name;
|
|
113
113
|
const pkg = PackageUtil.readPackage(RuntimeIndex.getModule(mod)!.sourcePath);
|
|
114
114
|
const title = pkg.travetto?.displayName ?? pkg.name;
|
|
115
115
|
const desc = pkg.description;
|
package/src/render/renderer.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import path from 'node:path';
|
|
2
2
|
|
|
3
|
-
import { type ManifestContext, PackageUtil
|
|
3
|
+
import { type ManifestContext, PackageUtil } from '@travetto/manifest';
|
|
4
4
|
import { isJSXElement, JSXElement, JSXFragmentType } from '@travetto/doc/jsx-runtime';
|
|
5
|
+
import { castTo, Runtime } from '@travetto/runtime';
|
|
5
6
|
|
|
6
7
|
import { EMPTY_ELEMENT, getComponentName, JSXElementByFn, c } from '../jsx';
|
|
7
8
|
import { DocumentShape, RenderProvider, RenderState } from '../types';
|
|
@@ -19,12 +20,7 @@ const providers = { [Html.ext]: Html, [Markdown.ext]: Markdown };
|
|
|
19
20
|
export class DocRenderer {
|
|
20
21
|
|
|
21
22
|
static async get(file: string, manifest: Pick<ManifestContext, 'workspace'>): Promise<DocRenderer> {
|
|
22
|
-
const
|
|
23
|
-
if (!mod) {
|
|
24
|
-
throw new Error(`Unable to render ${file}, not in the manifest`);
|
|
25
|
-
}
|
|
26
|
-
const res: DocumentShape = await import(mod);
|
|
27
|
-
|
|
23
|
+
const res = await Runtime.importFrom<DocumentShape>(file);
|
|
28
24
|
const pkg = PackageUtil.readPackage(manifest.workspace.path);
|
|
29
25
|
const repoBaseUrl = pkg.travetto?.doc?.baseUrl ?? manifest.workspace.path;
|
|
30
26
|
return new DocRenderer(res,
|
|
@@ -59,8 +55,7 @@ export class DocRenderer {
|
|
|
59
55
|
let final: JSXElement = node;
|
|
60
56
|
// Render simple element if needed
|
|
61
57
|
if (typeof node.type === 'function' && node.type !== JSXFragmentType) {
|
|
62
|
-
|
|
63
|
-
const out = node.type(node.props);
|
|
58
|
+
const out = castTo<Function>(node.type)(node.props);
|
|
64
59
|
final = out !== EMPTY_ELEMENT ? out : final;
|
|
65
60
|
}
|
|
66
61
|
|
|
@@ -92,12 +87,12 @@ export class DocRenderer {
|
|
|
92
87
|
case 'number':
|
|
93
88
|
case 'bigint':
|
|
94
89
|
case 'boolean': return `${node}`;
|
|
95
|
-
|
|
96
|
-
const
|
|
97
|
-
if (
|
|
98
|
-
const title = (await DocFileUtil.isDecorator(node.name,
|
|
90
|
+
case 'function': {
|
|
91
|
+
const source = DocFileUtil.readSource(node);
|
|
92
|
+
if (source.file) {
|
|
93
|
+
const title = (await DocFileUtil.isDecorator(node.name, source.file)) ? `@${node.name}` : node.name;
|
|
99
94
|
const el = this.#support.createElement('CodeLink', {
|
|
100
|
-
src:
|
|
95
|
+
src: source.file,
|
|
101
96
|
startRe: new RegExp(`(class|function)\\s+(${node.name})`),
|
|
102
97
|
title
|
|
103
98
|
});
|
|
@@ -109,9 +104,10 @@ export class DocRenderer {
|
|
|
109
104
|
state.createState = (key, props) => this.createState(state, key, props);
|
|
110
105
|
return await renderer.CodeLink(state);
|
|
111
106
|
}
|
|
112
|
-
|
|
107
|
+
break;
|
|
113
108
|
}
|
|
114
109
|
}
|
|
110
|
+
throw new Error(`Unknown object type: ${typeof node}`);
|
|
115
111
|
}
|
|
116
112
|
}
|
|
117
113
|
|
package/src/util/file.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import
|
|
1
|
+
import { readFileSync, existsSync } from 'node:fs';
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
|
|
4
|
-
import {
|
|
4
|
+
import { Runtime, RuntimeIndex } from '@travetto/runtime';
|
|
5
5
|
|
|
6
6
|
const ESLINT_PATTERN = /\s*\/\/ eslint.*$/g;
|
|
7
7
|
const ENV_KEY = /Env.([^.]+)[.]key/g;
|
|
@@ -24,58 +24,56 @@ export class DocFileUtil {
|
|
|
24
24
|
return /^[@:A-Za-z0-9\/\\\-_.]+[.]([a-z]{2,10})$/.test(src);
|
|
25
25
|
}
|
|
26
26
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
27
|
+
static readSource(src: string | Function): { content: string, language: string, file: string } {
|
|
28
|
+
let file: string | undefined;
|
|
29
|
+
let content: string | undefined;
|
|
30
|
+
|
|
31
|
+
if (typeof src === 'string') {
|
|
32
|
+
if (src.includes('\n') || src.includes(' ')) {
|
|
33
|
+
content = src;
|
|
34
|
+
} else {
|
|
35
|
+
const resolved = path.resolve(src);
|
|
36
|
+
if (existsSync(resolved)) {
|
|
37
|
+
content = readFileSync(resolved, 'utf8');
|
|
38
|
+
file = resolved;
|
|
39
|
+
} else {
|
|
40
|
+
file = RuntimeIndex.getSourceFile(src);
|
|
41
|
+
content = readFileSync(file, 'utf8');
|
|
42
|
+
}
|
|
40
43
|
}
|
|
44
|
+
} else {
|
|
45
|
+
file = Runtime.getSourceFile(src);
|
|
46
|
+
content = readFileSync(file, 'utf8');
|
|
41
47
|
}
|
|
42
|
-
return resolved;
|
|
43
|
-
}
|
|
44
48
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
*
|
|
48
|
-
* @param file
|
|
49
|
-
* @returns
|
|
50
|
-
*/
|
|
51
|
-
static async read(file: string): Promise<{ content: string, language: string, file: string }> {
|
|
52
|
-
file = await this.resolveFile(file);
|
|
53
|
-
|
|
54
|
-
const ext = path.extname(file);
|
|
55
|
-
const language = this.#extToLang[ext] ?? ext.replace('.', '');
|
|
56
|
-
|
|
57
|
-
let text: string | undefined;
|
|
58
|
-
if (language) {
|
|
59
|
-
text = await fs.readFile(file, 'utf8');
|
|
60
|
-
|
|
61
|
-
text = text.split(/\n/)
|
|
49
|
+
if (content) {
|
|
50
|
+
content = content.split(/\n/)
|
|
62
51
|
.map(x => x
|
|
63
52
|
.replace(ESLINT_PATTERN, '')
|
|
64
53
|
.replace(ENV_KEY, (_, k) => `'${k}'`)
|
|
65
54
|
)
|
|
66
|
-
.
|
|
67
|
-
.
|
|
55
|
+
.join('\n')
|
|
56
|
+
.replace(/^\/\/# sourceMap.*$/gsm, '')
|
|
57
|
+
.replace(/[ ]*[/][/][ ]*@ts-expect-error[^\n]*\n/gsm, '') // Excluding errors
|
|
58
|
+
.replace(/^[ ]*[/][/][ ]*[{][{][^\n]*\n/gsm, '') // Excluding conditional comments, full-line
|
|
59
|
+
.replace(/[ ]*[/][/][ ]*[{][{][^\n]*/gsm, ''); // Excluding conditional comments
|
|
68
60
|
}
|
|
69
61
|
|
|
70
|
-
|
|
62
|
+
if (file !== undefined) {
|
|
63
|
+
const ext = path.extname(file);
|
|
64
|
+
const language = this.#extToLang[ext] ?? ext.replace('.', '');
|
|
65
|
+
return { content, file, language };
|
|
66
|
+
} else {
|
|
67
|
+
return { content, file: '', language: '' };
|
|
68
|
+
}
|
|
71
69
|
}
|
|
72
70
|
|
|
73
|
-
static async readCodeSnippet(
|
|
74
|
-
const res =
|
|
75
|
-
const lines = res.content.split(/\n/
|
|
71
|
+
static async readCodeSnippet(src: string | Function, startPattern: RegExp): Promise<{ file: string, startIdx: number, lines: string[], language: string }> {
|
|
72
|
+
const res = this.readSource(src);
|
|
73
|
+
const lines = res.content.split(/\n/);
|
|
76
74
|
const startIdx = lines.findIndex(l => startPattern.test(l));
|
|
77
75
|
if (startIdx < 0) {
|
|
78
|
-
throw new Error(`Pattern ${startPattern.source} not found in ${
|
|
76
|
+
throw new Error(`Pattern ${startPattern.source} not found in ${src}`);
|
|
79
77
|
}
|
|
80
78
|
return { file: res.file, startIdx, lines, language: res.language };
|
|
81
79
|
}
|
|
@@ -84,15 +82,14 @@ export class DocFileUtil {
|
|
|
84
82
|
* Determine if a file is a decorator
|
|
85
83
|
*/
|
|
86
84
|
static async isDecorator(name: string, file: string): Promise<boolean> {
|
|
87
|
-
file = await this.resolveFile(file);
|
|
88
85
|
|
|
89
86
|
const key = `${name}:${file}`;
|
|
90
87
|
if (key in this.#decCache) {
|
|
91
88
|
return this.#decCache[key];
|
|
92
89
|
}
|
|
93
90
|
|
|
94
|
-
const
|
|
95
|
-
|
|
91
|
+
const res = await this.readSource(file);
|
|
92
|
+
const text = res.content.split(/\n/g);
|
|
96
93
|
|
|
97
94
|
const start = text.findIndex(x => new RegExp(`function ${name}\\b`).test(x));
|
|
98
95
|
let ret = false;
|
package/src/util/resolve.ts
CHANGED
|
@@ -13,7 +13,7 @@ export class DocResolveUtil {
|
|
|
13
13
|
static async resolveRef(title: string, file: string): Promise<ResolvedRef> {
|
|
14
14
|
|
|
15
15
|
let line = 0;
|
|
16
|
-
const res = await DocFileUtil.
|
|
16
|
+
const res = await DocFileUtil.readSource(file);
|
|
17
17
|
file = res.file;
|
|
18
18
|
|
|
19
19
|
if (res.content) {
|
|
@@ -31,22 +31,22 @@ export class DocResolveUtil {
|
|
|
31
31
|
return { title, file, line };
|
|
32
32
|
}
|
|
33
33
|
|
|
34
|
-
static async resolveCode(content: string, language?: string, outline = false): Promise<ResolvedCode> {
|
|
34
|
+
static async resolveCode(content: string | Function, language?: string, outline = false): Promise<ResolvedCode> {
|
|
35
|
+
const res = DocFileUtil.readSource(content);
|
|
36
|
+
let text = res.content;
|
|
37
|
+
|
|
35
38
|
let file: string | undefined;
|
|
36
|
-
if (
|
|
37
|
-
const res = await DocFileUtil.read(content);
|
|
39
|
+
if (res.file) {
|
|
38
40
|
language = res.language;
|
|
39
41
|
file = res.file;
|
|
40
|
-
content = res.content;
|
|
41
42
|
if (outline) {
|
|
42
|
-
|
|
43
|
+
text = DocFileUtil.buildOutline(text);
|
|
43
44
|
}
|
|
44
45
|
}
|
|
45
|
-
|
|
46
|
-
return { text: content, language: language!, file };
|
|
46
|
+
return { text, language: language!, file };
|
|
47
47
|
}
|
|
48
48
|
|
|
49
|
-
static async resolveSnippet(file: string, startPattern: RegExp, endPattern?: RegExp, outline = false): Promise<ResolvedSnippet> {
|
|
49
|
+
static async resolveSnippet(file: Function | string, startPattern: RegExp, endPattern?: RegExp, outline = false): Promise<ResolvedSnippet> {
|
|
50
50
|
const { lines, startIdx, language, file: resolvedFile } = await DocFileUtil.readCodeSnippet(file, startPattern);
|
|
51
51
|
|
|
52
52
|
const endIdx = endPattern ? lines.findIndex((l, i) => i > startIdx && endPattern.test(l)) : lines.length;
|
|
@@ -59,7 +59,7 @@ export class DocResolveUtil {
|
|
|
59
59
|
return { text, language, line: startIdx + 1, file: resolvedFile };
|
|
60
60
|
}
|
|
61
61
|
|
|
62
|
-
static async resolveCodeLink(file: string, startPattern: RegExp): Promise<ResolvedSnippetLink> {
|
|
62
|
+
static async resolveCodeLink(file: Function | string, startPattern: RegExp): Promise<ResolvedSnippetLink> {
|
|
63
63
|
const { startIdx, file: resolvedFile } = await DocFileUtil.readCodeSnippet(file, startPattern);
|
|
64
64
|
return { file: resolvedFile, line: startIdx + 1 };
|
|
65
65
|
}
|
package/src/util/run.ts
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import os from 'node:os';
|
|
2
2
|
import util from 'node:util';
|
|
3
3
|
import { spawn, ChildProcess } from 'node:child_process';
|
|
4
|
+
import path from 'node:path';
|
|
4
5
|
|
|
5
|
-
import {
|
|
6
|
-
import { Env, ExecUtil, RuntimeContext } from '@travetto/base';
|
|
6
|
+
import { Env, ExecUtil, Runtime, RuntimeIndex } from '@travetto/runtime';
|
|
7
7
|
|
|
8
8
|
export const COMMON_DATE = new Date('2029-03-14T00:00:00.000').getTime();
|
|
9
9
|
|
|
@@ -47,7 +47,7 @@ export class DocRunUtil {
|
|
|
47
47
|
|
|
48
48
|
/** Build cwd from config */
|
|
49
49
|
static cwd(cfg: RunConfig): string {
|
|
50
|
-
return path.
|
|
50
|
+
return path.resolve(cfg.module ? RuntimeIndex.getModule(cfg.module)?.sourcePath! : Runtime.mainSourcePath);
|
|
51
51
|
}
|
|
52
52
|
|
|
53
53
|
/**
|
|
@@ -58,7 +58,7 @@ export class DocRunUtil {
|
|
|
58
58
|
text = util.stripVTControlCharacters(text.trim())
|
|
59
59
|
.replaceAll(cwd, '.')
|
|
60
60
|
.replaceAll(os.tmpdir(), '/tmp')
|
|
61
|
-
.replaceAll(
|
|
61
|
+
.replaceAll(Runtime.workspace.path, '<workspace-root>')
|
|
62
62
|
.replace(/[/]tmp[/][a-z_A-Z0-9\/\-]+/g, '/tmp/<temp-folder>')
|
|
63
63
|
.replace(/^(\s*framework:\s*')(\d+[.]\d+)[^']*('[,]?\s*)$/gm, (_, pre, ver, post) => `${pre}${ver}.x${post}`)
|
|
64
64
|
.replace(/^(\s*nodeVersion:\s*'v)(\d+)[^']*('[,]?\s*)$/gm, (_, pre, ver, post) => `${pre}${ver}.x.x${post}`)
|
|
@@ -90,7 +90,6 @@ export class DocRunUtil {
|
|
|
90
90
|
...Env.TRV_CLI_IPC.export(undefined),
|
|
91
91
|
...Env.TRV_MANIFEST.export(''),
|
|
92
92
|
...Env.TRV_BUILD.export('none'),
|
|
93
|
-
...Env.TRV_BUILD_REENTRANT.export(true),
|
|
94
93
|
...Env.TRV_ROLE.export(undefined),
|
|
95
94
|
...Env.TRV_MODULE.export(config.module ?? ''),
|
|
96
95
|
...(config.envName ? Env.TRV_ENV.export(config.envName) : {}),
|
package/support/cli.doc.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { spawn } from 'node:child_process';
|
|
|
3
3
|
import path from 'node:path';
|
|
4
4
|
|
|
5
5
|
import { PackageUtil } from '@travetto/manifest';
|
|
6
|
-
import { ExecUtil, Env, watchCompiler,
|
|
6
|
+
import { ExecUtil, Env, watchCompiler, Runtime } from '@travetto/runtime';
|
|
7
7
|
import { CliCommandShape, CliCommand, CliValidationError, CliUtil } from '@travetto/cli';
|
|
8
8
|
import { MinLength } from '@travetto/schema';
|
|
9
9
|
|
|
@@ -32,7 +32,7 @@ export class DocCommand implements CliCommandShape {
|
|
|
32
32
|
}
|
|
33
33
|
|
|
34
34
|
preBind(): void {
|
|
35
|
-
const workspacePkg = PackageUtil.readPackage(
|
|
35
|
+
const workspacePkg = PackageUtil.readPackage(Runtime.workspace.path);
|
|
36
36
|
this.outputs = workspacePkg.travetto?.doc?.outputs ?? ['README.md'];
|
|
37
37
|
}
|
|
38
38
|
|
|
@@ -56,7 +56,7 @@ export class DocCommand implements CliCommandShape {
|
|
|
56
56
|
for await (const { action, file } of watchCompiler({ restartOnExit: true })) {
|
|
57
57
|
if (action === 'update' && file === this.input) {
|
|
58
58
|
const proc = spawn('npx', ['trv', ...args], {
|
|
59
|
-
cwd:
|
|
59
|
+
cwd: Runtime.mainSourcePath,
|
|
60
60
|
shell: false,
|
|
61
61
|
env: { ...process.env, ...Env.TRV_QUIET.export(true) },
|
|
62
62
|
stdio: 'inherit'
|
|
@@ -68,7 +68,7 @@ export class DocCommand implements CliCommandShape {
|
|
|
68
68
|
|
|
69
69
|
async render(): Promise<void> {
|
|
70
70
|
const { DocRenderer } = await import('../src/render/renderer');
|
|
71
|
-
const ctx = await DocRenderer.get(this.input,
|
|
71
|
+
const ctx = await DocRenderer.get(this.input, Runtime);
|
|
72
72
|
const outputs = this.outputs.map(output =>
|
|
73
73
|
output.includes('.') ? [path.extname(output).replace('.', ''), path.resolve(output)] :
|
|
74
74
|
[output, null] as const
|