2022-03-07 00:21:16 -06:00
|
|
|
import {readFile} from 'fs/promises';
|
2022-03-09 14:43:54 -06:00
|
|
|
import {
|
|
|
|
basename,
|
|
|
|
dirname,
|
|
|
|
extname,
|
|
|
|
join,
|
|
|
|
} from 'path';
|
2022-03-07 00:21:16 -06:00
|
|
|
|
|
|
|
import {transformAsync} from '@babel/core';
|
|
|
|
import traverse from '@babel/traverse';
|
|
|
|
import {
|
2022-03-09 08:51:10 -06:00
|
|
|
isArrayExpression,
|
|
|
|
isArrowFunctionExpression,
|
2022-03-07 00:21:16 -06:00
|
|
|
isIdentifier,
|
|
|
|
isLiteral,
|
|
|
|
isMemberExpression,
|
|
|
|
isObjectExpression,
|
|
|
|
isStringLiteral,
|
|
|
|
isThisExpression,
|
2022-08-10 10:09:02 -05:00
|
|
|
isVariableDeclaration,
|
2022-03-07 00:21:16 -06:00
|
|
|
} from '@babel/types';
|
|
|
|
import {require as R} from '@flecks/core/server';
|
|
|
|
import {parse as parseComment} from 'comment-parser';
|
|
|
|
import glob from 'glob';
|
|
|
|
|
|
|
|
const flecksCorePath = dirname(__non_webpack_require__.resolve('@flecks/core/package.json'));
|
|
|
|
|
|
|
|
class ParserState {
|
|
|
|
|
|
|
|
constructor() {
|
2022-03-09 08:51:10 -06:00
|
|
|
this.buildConfigs = [];
|
2022-03-09 14:43:54 -06:00
|
|
|
this.configs = {};
|
2022-03-07 00:21:16 -06:00
|
|
|
this.hooks = {};
|
|
|
|
this.todos = [];
|
|
|
|
}
|
|
|
|
|
2022-03-09 08:51:10 -06:00
|
|
|
addBuildConfig(config, comment) {
|
|
|
|
this.buildConfigs.push({comment, config});
|
|
|
|
}
|
|
|
|
|
2022-03-09 14:43:54 -06:00
|
|
|
addConfig(config, comment, filename, defaultValue) {
|
|
|
|
const ext = extname(filename);
|
|
|
|
const trimmed = join(dirname(filename), basename(filename, ext)).replace('/src', '');
|
|
|
|
const fleck = 'index' === basename(trimmed) ? dirname(trimmed) : trimmed;
|
|
|
|
if (!this.configs[fleck]) {
|
|
|
|
this.configs[fleck] = [];
|
|
|
|
}
|
|
|
|
this.configs[fleck].push({
|
|
|
|
comment,
|
|
|
|
config,
|
|
|
|
defaultValue,
|
|
|
|
});
|
|
|
|
}
|
|
|
|
|
2022-03-07 00:21:16 -06:00
|
|
|
addImplementation(hook, filename, loc) {
|
|
|
|
this.hooks[hook] = this.hooks[hook] || {};
|
|
|
|
this.hooks[hook].implementations = this.hooks[hook].implementations || [];
|
|
|
|
this.hooks[hook].implementations.push({filename, loc});
|
|
|
|
}
|
|
|
|
|
|
|
|
addInvocation(hook, type, filename, loc) {
|
|
|
|
this.hooks[hook] = this.hooks[hook] || {};
|
|
|
|
this.hooks[hook].invocations = this.hooks[hook].invocations || [];
|
|
|
|
this.hooks[hook].invocations.push({filename, loc, type});
|
|
|
|
}
|
|
|
|
|
|
|
|
addSpecification(hook, specification) {
|
|
|
|
this.hooks[hook] = this.hooks[hook] || {};
|
|
|
|
this.hooks[hook].specification = specification;
|
|
|
|
}
|
|
|
|
|
|
|
|
addTodo(comment, filename) {
|
|
|
|
this.todos.push({filename, loc: comment.loc, text: comment.value.trim()});
|
|
|
|
}
|
|
|
|
|
|
|
|
}
|
|
|
|
|
2022-03-09 08:24:52 -06:00
|
|
|
const implementationVisitor = (fn) => ({
|
2022-08-10 10:09:02 -05:00
|
|
|
ExportNamedDeclaration(path) {
|
2022-03-09 08:24:52 -06:00
|
|
|
const {declaration} = path.node;
|
2022-08-10 10:09:02 -05:00
|
|
|
if (isVariableDeclaration(declaration)) {
|
|
|
|
const {declarations} = declaration;
|
|
|
|
declarations.forEach((declarator) => {
|
|
|
|
if ('hooks' === declarator.id.name) {
|
|
|
|
if (isObjectExpression(declarator.init)) {
|
|
|
|
const {properties} = declarator.init;
|
2022-03-09 08:24:52 -06:00
|
|
|
properties.forEach((property) => {
|
|
|
|
const {key} = property;
|
|
|
|
if (isLiteral(key)) {
|
|
|
|
fn(property);
|
|
|
|
}
|
|
|
|
});
|
|
|
|
}
|
|
|
|
}
|
|
|
|
});
|
|
|
|
}
|
|
|
|
},
|
|
|
|
});
|
|
|
|
|
2022-03-09 12:05:17 -06:00
|
|
|
const FlecksBuildConfigs = (state) => (
|
2022-03-09 08:51:10 -06:00
|
|
|
implementationVisitor((property) => {
|
|
|
|
if ('@flecks/core.build.config' === property.key.value) {
|
|
|
|
if (isArrowFunctionExpression(property.value)) {
|
|
|
|
if (isArrayExpression(property.value.body)) {
|
|
|
|
property.value.body.elements.forEach((element) => {
|
|
|
|
let config;
|
|
|
|
if (isStringLiteral(element)) {
|
|
|
|
config = element.value;
|
|
|
|
}
|
|
|
|
if (isArrayExpression(element)) {
|
|
|
|
if (element.elements.length > 0 && isStringLiteral(element.elements[0])) {
|
|
|
|
config = element.elements[0].value;
|
|
|
|
}
|
|
|
|
}
|
2022-03-09 14:43:54 -06:00
|
|
|
if (config) {
|
2022-03-09 08:51:10 -06:00
|
|
|
state.addBuildConfig(
|
|
|
|
config,
|
2022-03-09 14:43:54 -06:00
|
|
|
(element.leadingComments?.length > 0)
|
|
|
|
? element.leadingComments.pop().value.split('\n')
|
|
|
|
.map((line) => line.trim())
|
|
|
|
.map((line) => line.replace(/^\*/, ''))
|
|
|
|
.map((line) => line.trim())
|
|
|
|
.filter((line) => !!line)
|
|
|
|
.join(' ')
|
|
|
|
.trim()
|
|
|
|
: '*No description provided.*',
|
|
|
|
);
|
|
|
|
}
|
|
|
|
});
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
})
|
|
|
|
);
|
|
|
|
|
|
|
|
const FlecksConfigs = (state, filename, source) => (
|
|
|
|
implementationVisitor((property) => {
|
|
|
|
if ('@flecks/core.config' === property.key.value) {
|
|
|
|
if (isArrowFunctionExpression(property.value)) {
|
|
|
|
if (isObjectExpression(property.value.body)) {
|
|
|
|
property.value.body.properties.forEach((property) => {
|
|
|
|
if (isIdentifier(property.key) || isStringLiteral(property.key)) {
|
|
|
|
state.addConfig(
|
|
|
|
property.key.name || property.key.value,
|
|
|
|
(property.leadingComments?.length > 0)
|
|
|
|
? property.leadingComments.pop().value.split('\n')
|
|
|
|
.map((line) => line.trim())
|
|
|
|
.map((line) => line.replace(/^\*/, ''))
|
|
|
|
.map((line) => line.trim())
|
|
|
|
.filter((line) => !!line)
|
|
|
|
.join(' ')
|
|
|
|
.trim()
|
|
|
|
: '*No description provided.*',
|
|
|
|
filename,
|
|
|
|
source.slice(property.value.start, property.value.end),
|
2022-03-09 08:51:10 -06:00
|
|
|
);
|
|
|
|
}
|
|
|
|
});
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
})
|
|
|
|
);
|
|
|
|
|
2022-03-07 00:21:16 -06:00
|
|
|
const FlecksInvocations = (state, filename) => ({
|
|
|
|
CallExpression(path) {
|
|
|
|
if (isMemberExpression(path.node.callee)) {
|
|
|
|
if (
|
|
|
|
(isIdentifier(path.node.callee.object) && 'flecks' === path.node.callee.object.name)
|
|
|
|
|| (
|
|
|
|
(
|
|
|
|
isThisExpression(path.node.callee.object)
|
|
|
|
&& (filename === join(flecksCorePath, 'src', 'flecks.js'))
|
|
|
|
)
|
|
|
|
)
|
|
|
|
) {
|
|
|
|
if (isIdentifier(path.node.callee.property)) {
|
|
|
|
if (path.node.callee.property.name.match(/^invoke.*/)) {
|
|
|
|
if (path.node.arguments.length > 0) {
|
|
|
|
if (isStringLiteral(path.node.arguments[0])) {
|
|
|
|
state.addInvocation(
|
|
|
|
path.node.arguments[0].value,
|
|
|
|
path.node.callee.property.name,
|
|
|
|
filename,
|
|
|
|
path.node.loc,
|
|
|
|
);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
if ('up' === path.node.callee.property.name) {
|
|
|
|
if (path.node.arguments.length > 0) {
|
|
|
|
if (isStringLiteral(path.node.arguments[0])) {
|
|
|
|
state.addInvocation(
|
|
|
|
path.node.arguments[0].value,
|
|
|
|
'invokeSequentialAsync',
|
|
|
|
filename,
|
|
|
|
path.node.loc,
|
|
|
|
);
|
|
|
|
state.addInvocation(
|
2022-03-08 16:03:06 -06:00
|
|
|
'@flecks/core.starting',
|
2022-03-07 00:21:16 -06:00
|
|
|
'invokeFlat',
|
|
|
|
filename,
|
|
|
|
path.node.loc,
|
|
|
|
);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
if ('gather' === path.node.callee.property.name) {
|
|
|
|
if (path.node.arguments.length > 0) {
|
|
|
|
if (isStringLiteral(path.node.arguments[0])) {
|
|
|
|
state.addInvocation(
|
|
|
|
path.node.arguments[0].value,
|
2022-03-08 14:50:16 -06:00
|
|
|
'invokeMerge',
|
2022-03-07 00:21:16 -06:00
|
|
|
filename,
|
|
|
|
path.node.loc,
|
|
|
|
);
|
|
|
|
state.addInvocation(
|
|
|
|
`${path.node.arguments[0].value}.decorate`,
|
|
|
|
'invokeComposed',
|
|
|
|
filename,
|
|
|
|
path.node.loc,
|
|
|
|
);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
},
|
|
|
|
});
|
|
|
|
|
|
|
|
const FlecksImplementations = (state, filename) => (
|
2022-03-07 02:08:24 -06:00
|
|
|
implementationVisitor(({key}) => {
|
2022-03-07 00:21:16 -06:00
|
|
|
state.addImplementation(
|
|
|
|
key.value,
|
|
|
|
filename,
|
2022-03-07 02:08:24 -06:00
|
|
|
key.loc,
|
2022-03-07 00:21:16 -06:00
|
|
|
);
|
|
|
|
})
|
|
|
|
);
|
|
|
|
|
|
|
|
const FlecksSpecifications = (state, source) => (
|
2022-03-07 02:08:24 -06:00
|
|
|
implementationVisitor((property) => {
|
2022-03-07 00:21:16 -06:00
|
|
|
if (property.leadingComments) {
|
|
|
|
const {key, value: example} = property;
|
|
|
|
const [{value}] = property.leadingComments;
|
|
|
|
const [{description, tags}] = parseComment(`/**\n${value}\n*/`, {spacing: 'preserve'});
|
|
|
|
const params = tags
|
|
|
|
.filter(({tag}) => 'param' === tag)
|
|
|
|
.map(({description, name, type}) => ({description, name, type}));
|
|
|
|
state.addSpecification(
|
|
|
|
key.value,
|
|
|
|
{
|
|
|
|
description,
|
|
|
|
example: source.slice(example.start, example.end),
|
|
|
|
params,
|
|
|
|
},
|
|
|
|
);
|
|
|
|
}
|
|
|
|
})
|
|
|
|
);
|
|
|
|
|
|
|
|
const FlecksTodos = (state, filename) => ({
|
|
|
|
enter(path) {
|
|
|
|
if (path.node.leadingComments) {
|
|
|
|
path.node.leadingComments.forEach((comment) => {
|
|
|
|
if (comment.value.toLowerCase().match('@todo')) {
|
|
|
|
state.addTodo(comment, filename);
|
|
|
|
}
|
|
|
|
});
|
|
|
|
}
|
|
|
|
},
|
|
|
|
});
|
|
|
|
|
|
|
|
export const parseCode = async (code) => {
|
|
|
|
const config = {
|
|
|
|
ast: true,
|
|
|
|
code: false,
|
|
|
|
};
|
|
|
|
const {ast} = await transformAsync(code, config);
|
|
|
|
return ast;
|
|
|
|
};
|
|
|
|
|
|
|
|
export const parseFile = async (filename, resolved, state) => {
|
|
|
|
const buffer = await readFile(filename);
|
2022-03-09 14:43:54 -06:00
|
|
|
const source = buffer.toString('utf8');
|
|
|
|
const ast = await parseCode(source);
|
2022-03-09 08:51:10 -06:00
|
|
|
traverse(ast, FlecksBuildConfigs(state, resolved));
|
2022-03-09 14:43:54 -06:00
|
|
|
traverse(ast, FlecksConfigs(state, resolved, source));
|
2022-03-07 00:21:16 -06:00
|
|
|
traverse(ast, FlecksInvocations(state, resolved));
|
|
|
|
traverse(ast, FlecksImplementations(state, resolved));
|
|
|
|
traverse(ast, FlecksTodos(state, resolved));
|
|
|
|
};
|
|
|
|
|
|
|
|
const fleckSources = async (path) => (
|
|
|
|
new Promise((r, e) => (
|
|
|
|
glob(
|
|
|
|
join(path, 'src', '**', '*.js'),
|
|
|
|
(error, result) => (error ? e(error) : r(result)),
|
|
|
|
)
|
|
|
|
))
|
|
|
|
);
|
|
|
|
|
|
|
|
export const parseFleckRoot = async (root, state) => {
|
|
|
|
const resolved = dirname(R.resolve(join(root, 'package.json')));
|
|
|
|
const sources = await fleckSources(resolved);
|
|
|
|
await Promise.all(
|
|
|
|
sources.map(async (source) => {
|
2022-03-07 02:44:48 -06:00
|
|
|
// @todo Aliased fleck paths are gonna be bad.
|
2022-03-07 00:21:16 -06:00
|
|
|
await parseFile(source, join(root, source.slice(resolved.length)), state);
|
|
|
|
}),
|
|
|
|
);
|
|
|
|
try {
|
|
|
|
const buffer = await readFile(join(resolved, 'build', 'dox', 'hooks.js'));
|
|
|
|
const source = buffer.toString('utf8');
|
|
|
|
const ast = await parseCode(source);
|
|
|
|
traverse(ast, FlecksSpecifications(state, source));
|
|
|
|
}
|
|
|
|
catch (error) {
|
|
|
|
if ('ENOENT' !== error.code) {
|
|
|
|
throw error;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
};
|
|
|
|
|
|
|
|
export const parseFlecks = async (flecks) => {
|
|
|
|
const state = new ParserState();
|
|
|
|
const paths = Object.keys(flecks.resolver);
|
|
|
|
const roots = Array.from(new Set(
|
|
|
|
paths
|
|
|
|
.map((path) => flecks.root(path))
|
|
|
|
.filter((e) => !!e),
|
|
|
|
));
|
|
|
|
await Promise.all(
|
|
|
|
roots
|
|
|
|
.map(async (root) => {
|
|
|
|
await parseFleckRoot(root, state);
|
|
|
|
}),
|
|
|
|
);
|
|
|
|
return state;
|
|
|
|
};
|