@limetech/kompendium 1.1.1

package/dist/generator.ts

@@ -0,0 +1,302 @@
+import { JsonDocs, Config, Logger } from '@stencil/core/internal';
+import { defaultConfig } from './config';
+import { addSources } from './source';
+import lnk from 'lnk';
+import { createMenu } from './menu';
+import { copyFile, mkdir, readFile, stat, writeFile } from 'fs/promises';
+import { exists } from './filesystem';
+import { createWatcher } from './watch';
+import { findGuides } from './guides';
+import { KompendiumConfig, KompendiumData, TypeDescription } from '../types';
+import { parseFile } from './typedoc';
+import { createSchemas } from './schema';
+import { createIndex } from './search';
+
+export const kompendium = (config: Partial<KompendiumConfig> = {}) => {
+    if (!generateDocs()) {
+        return () => null;
+    }
+
+    return kompendiumGenerator(config);
+};
+
+let logger: Logger;
+
+export function kompendiumGenerator(
+    config: Partial<KompendiumConfig>,
+): (docs: JsonDocs, stencilConfig: Config) => Promise<void> {
+    config = {
+        ...defaultConfig,
+        ...config,
+    };
+    initialize(config);
+
+    return async (docs: JsonDocs, stencilConfig: Config) => {
+        logger = stencilConfig.logger;
+        const timeSpan = logger.createTimeSpan('kompendium started');
+
+        const [jsonDocs, title, readme, guides, types] = await Promise.all([
+            addSources(docs),
+            getProjectTitle(config),
+            getReadme(),
+            findGuides(config),
+            getTypes(config, stencilConfig.tsconfig),
+        ]);
+
+        const data: KompendiumData = {
+            docs: jsonDocs,
+            title: title,
+            logo: config.logo,
+            menu: createMenu(docs, guides, types),
+            readme: readme,
+            guides: guides,
+            types: types,
+            schemas: createSchemas(docs.components, types),
+            index: null,
+        };
+
+        data.index = createIndex(data);
+
+        await writeData(config, data);
+
+        timeSpan.finish('kompendium finished');
+    };
+}
+
+async function initialize(config: Partial<KompendiumConfig>) {
+    const path = `${config.publicPath}/kompendium.json`;
+
+    if (isWatcher()) {
+        createWatcher(path, 'unlink', onUnlink(config));
+    }
+
+    await createOutputDirs(config);
+}
+
+const onUnlink = (config: Partial<KompendiumConfig>) => () => {
+    createSymlink(config);
+};
+
+async function createSymlink(config: Partial<KompendiumConfig>) {
+    const source = `${config.path}/kompendium.json`;
+    const target = `${config.publicPath}/kompendium.json`;
+
+    if (!(await exists(source))) {
+        return;
+    }
+
+    if (await exists(target)) {
+        return;
+    }
+
+    lnk([source], config.publicPath);
+}
+
+async function getProjectTitle(
+    config: Partial<KompendiumConfig>,
+): Promise<string> {
+    if (config.title) {
+        return config.title;
+    }
+
+    const json = await readFile('./package.json', 'utf8');
+    const data = JSON.parse(json);
+
+    return data.name
+        .replace(/^@[^/]+?\//, '')
+        .split('-')
+        .join(' ');
+}
+
+async function writeData(
+    config: Partial<KompendiumConfig>,
+    data: KompendiumData,
+) {
+    // Always write to the kompendium config folder (typically `.kompendium` in
+    // the root of the project) to avoid Stencil deleting the file during build.
+    const filePath = `${config.path}/kompendium.json`;
+
+    await writeFile(filePath, JSON.stringify(data), 'utf8');
+
+    if (isProd()) {
+        // In production, we used to write the kompendium.json file to the
+        // public path. We now copy the file to the public path for backwards
+        // compatibility with projects that do not have problems with Stencil
+        // deleting the file during build. For projects that do have this
+        // problem, they can always copy the file from the config folder.
+        const publicFilePath = `${config.publicPath}/kompendium.json`;
+        if (!(await exists(config.publicPath))) {
+            await mkdir(config.publicPath, { recursive: true });
+        }
+
+        await copyFile(filePath, publicFilePath);
+    }
+
+    if (isWatcher()) {
+        createSymlink(config);
+    }
+}
+
+async function createOutputDirs(config: Partial<KompendiumConfig>) {
+    let path = config.path;
+    if (!(await exists(path))) {
+        mkdir(path, { recursive: true });
+    }
+
+    path = config.publicPath;
+    if (!(await exists(path))) {
+        mkdir(path, { recursive: true });
+    }
+}
+
+async function getReadme(): Promise<string> {
+    const files = ['readme.md', 'README.md', 'README', 'readme'];
+    let data = null;
+
+    for (const file of files) {
+        if (data) {
+            continue;
+        }
+
+        if (!(await exists(file))) {
+            continue;
+        }
+
+        data = await readFile(file, 'utf8');
+    }
+
+    if (!data) {
+        logger.warn('README did not exist');
+    }
+
+    return data;
+}
+
+function generateDocs(): boolean {
+    return !!process.argv.includes('--docs');
+}
+
+function isWatcher(): boolean {
+    return !!process.argv.includes('--watch');
+}
+
+function isProd(): boolean {
+    return !(
+        process.argv.includes('--dev') ||
+        process.argv.includes('test') ||
+        process.argv.find((arg) => arg.includes('jest-worker'))
+    );
+}
+
+async function getTypes(
+    config: Partial<KompendiumConfig>,
+    tsconfig?: string,
+): Promise<TypeDescription[]> {
+    logger.debug('Getting type information...');
+    let types = await readTypes(config);
+    const cache = await readCache(config);
+
+    if (types.length === 0 || (await isModified(types, cache))) {
+        logger.debug('Parsing types...');
+        const data = parseFile(config.typeRoot, tsconfig);
+        await saveData(config, data);
+        types = data;
+    }
+
+    return types;
+}
+
+async function isModified(types: any[], cache: Record<string, number>) {
+    if (Object.keys(cache).length === 0) {
+        return true;
+    }
+
+    const filenames = getUniqueSourceFilenames(types);
+    const stats = await Promise.all(filenames.map(tryStatFile));
+
+    return stats.some((fileStat, index) =>
+        hasFileChangedSinceCached(filenames[index], fileStat, cache),
+    );
+}
+
+function getUniqueSourceFilenames(types: any[]): string[] {
+    const filenames = types.map((t) => t.sources).flat();
+
+    return [...new Set(filenames)];
+}
+
+function tryStatFile(filename: string) {
+    return stat(filename).catch(() => null);
+}
+
+function hasFileChangedSinceCached(
+    filename: string,
+    fileStat: Awaited<ReturnType<typeof stat>> | null,
+    cache: Record<string, number>,
+): boolean {
+    if (!fileStat) {
+        logger.debug(`${filename} cannot be accessed, marking as modified`);
+
+        return true;
+    }
+
+    const result = cache[filename] !== fileStat.mtimeMs;
+
+    logger.debug(`${filename} was ${result ? '' : 'not'} modified!`);
+
+    return result;
+}
+
+async function saveData(
+    config: Partial<KompendiumConfig>,
+    types: TypeDescription[],
+) {
+    const filenames = getUniqueSourceFilenames(types);
+    const stats = await Promise.all(filenames.map(tryStatFile));
+    const cache = buildCacheFromFileStats(filenames, stats);
+
+    await Promise.all([writeCache(config, cache), writeTypes(config, types)]);
+}
+
+function buildCacheFromFileStats(
+    filenames: string[],
+    stats: Array<Awaited<ReturnType<typeof stat>> | null>,
+): Record<string, number> {
+    const cache: Record<string, number> = {};
+
+    stats.forEach((fileStat, index) => {
+        if (fileStat) {
+            cache[filenames[index]] = fileStat.mtimeMs;
+        }
+    });
+
+    return cache;
+}
+
+async function readCache(config: Partial<KompendiumConfig>) {
+    try {
+        const data = await readFile(`${config.path}/cache.json`, 'utf8');
+
+        return JSON.parse(data);
+    } catch {
+        return {};
+    }
+}
+
+async function writeCache(config: Partial<KompendiumConfig>, data: any) {
+    await writeFile(`${config.path}/cache.json`, JSON.stringify(data), 'utf8');
+}
+
+async function readTypes(config: Partial<KompendiumConfig>) {
+    try {
+        const data = await readFile(`${config.path}/types.json`, 'utf8');
+
+        return JSON.parse(data);
+    } catch {
+        return [];
+    }
+}
+
+async function writeTypes(config: Partial<KompendiumConfig>, data: any) {
+    await writeFile(`${config.path}/types.json`, JSON.stringify(data), 'utf8');
+}

package/dist/guides.ts

@@ -0,0 +1,49 @@
+import { basename, dirname, resolve } from 'path';
+import { readFile } from 'fs/promises';
+import { KompendiumGuide, KompendiumConfig, Guide } from '../types';
+
+export async function findGuides(
+    config: Partial<KompendiumConfig>,
+): Promise<KompendiumGuide[]> {
+    const nodes = config.guides.map(createMenuNode('/')).flat();
+    const promises = nodes.map(createGuide);
+
+    return Promise.all(promises);
+}
+
+interface MenuNode {
+    menupath: string;
+    filepath: string;
+}
+
+export const createMenuNode =
+    (path: string) =>
+    (guide: Guide): MenuNode | MenuNode[] => {
+        if (typeof guide !== 'string') {
+            const newPath = path + guide.name + '/';
+
+            return guide.children.map(createMenuNode(newPath)).flat();
+        }
+
+        return {
+            menupath: path,
+            filepath: guide,
+        };
+    };
+
+export const createGuide = async ({
+    menupath: path,
+    filepath,
+}: MenuNode): Promise<KompendiumGuide> => {
+    const content = await readFile(filepath, 'utf8');
+
+    return {
+        dirPath: dirname(filepath),
+        fileName: basename(filepath),
+        filePath: resolve(filepath),
+        data: {
+            path: path + basename(filepath),
+        },
+        content: content,
+    };
+};

package/dist/index.cjs.js

@@ -0,0 +1 @@
+module.exports = require('./cjs/index.cjs.js');

package/dist/index.js

@@ -0,0 +1 @@
+export * from './esm/index.js';

package/dist/index.ts

@@ -0,0 +1 @@
+export { kompendium } from './generator';

package/dist/kompendium/index.esm.js

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=index.esm.js.map

package/dist/kompendium/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}