@titannio/webtoolkit-cli 1.3.0

package/dist/guards/documentation-guard.js

@@ -0,0 +1,370 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, join, matchesGlob, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from '../config.js';
+const defaultExcludedDirectories = new Set(['.corepack', '.git', 'build', 'coverage', 'dist', 'node_modules']);
+function normalizePath(filePath) {
+    return filePath.replace(/\\/gu, '/');
+}
+function relativePath(root, filePath) {
+    return normalizePath(relative(root, filePath));
+}
+function isInsideRoot(root, filePath) {
+    const fromRoot = relative(root, filePath);
+    return fromRoot !== '..' && !fromRoot.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) && !isAbsolute(fromRoot);
+}
+function assertStringArray(value, label, required = false) {
+    if ((!required && value === undefined) || (Array.isArray(value) && value.every((item) => typeof item === 'string') && (!required || value.length > 0)))
+        return;
+    throw new Error(`${label} must be ${required ? 'a non-empty ' : 'an '}array of strings.`);
+}
+function assertSafePattern(pattern, label) {
+    const comparable = pattern.replaceAll('{basename}', 'file.md').replaceAll('{stem}', 'file');
+    if (isAbsolute(comparable) || normalizePath(comparable).split('/').includes('..')) {
+        throw new Error(`${label} must stay inside the repository: ${pattern}`);
+    }
+}
+export function validateDocumentationConfig(config) {
+    assertStringArray(config.files, 'documentation.files', true);
+    assertStringArray(config.excludeDirectories, 'documentation.excludeDirectories');
+    assertStringArray(config.requiredFiles, 'documentation.requiredFiles');
+    const patterns = [...config.files, ...(config.requiredFiles ?? [])];
+    const reachability = config.checks?.reachability;
+    if (reachability) {
+        assertStringArray(reachability.entrypoints, 'documentation.checks.reachability.entrypoints', true);
+        assertStringArray(reachability.files, 'documentation.checks.reachability.files', true);
+        patterns.push(...reachability.entrypoints, ...reachability.files);
+    }
+    if (config.collections !== undefined && !Array.isArray(config.collections))
+        throw new Error('documentation.collections must be an array.');
+    for (const [index, collection] of (config.collections ?? []).entries()) {
+        assertStringArray(collection.files, `documentation.collections[${index}].files`, true);
+        assertStringArray(collection.exclude, `documentation.collections[${index}].exclude`);
+        patterns.push(...collection.files, ...(collection.exclude ?? []));
+        if (collection.index)
+            patterns.push(collection.index);
+        if (collection.metadata && (typeof collection.metadata !== 'object' || Array.isArray(collection.metadata))) {
+            throw new Error(`documentation.collections[${index}].metadata must be an object.`);
+        }
+        const paired = collection.pairedDocuments;
+        if (paired) {
+            if (typeof paired.target !== 'string' || paired.target.length === 0)
+                throw new Error(`documentation.collections[${index}].pairedDocuments.target must be a string.`);
+            patterns.push(paired.target);
+            if (paired.index)
+                patterns.push(paired.index);
+            if (paired.table) {
+                assertStringArray(paired.table.header, `documentation.collections[${index}].pairedDocuments.table.header`, true);
+                if (!paired.table.header.includes(paired.table.fileColumn))
+                    throw new Error(`documentation.collections[${index}].pairedDocuments.table.fileColumn must name a header column.`);
+            }
+        }
+    }
+    if (config.inventories !== undefined && !Array.isArray(config.inventories))
+        throw new Error('documentation.inventories must be an array.');
+    for (const [index, inventory] of (config.inventories ?? []).entries()) {
+        if (typeof inventory.document !== 'string' || inventory.document.length === 0)
+            throw new Error(`documentation.inventories[${index}].document must be a string.`);
+        assertStringArray(inventory.sources, `documentation.inventories[${index}].sources`, true);
+        patterns.push(inventory.document, ...inventory.sources);
+    }
+    for (const pattern of patterns)
+        assertSafePattern(pattern, 'Documentation path');
+}
+function walkFiles(directory, excludedDirectories) {
+    return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+        const filePath = join(directory, entry.name);
+        if (entry.isDirectory())
+            return excludedDirectories.has(entry.name) ? [] : walkFiles(filePath, excludedDirectories);
+        /* v8 ignore next -- non-file directory entries are intentionally ignored */
+        if (!entry.isFile())
+            return [];
+        return [filePath];
+    });
+}
+function matches(filePath, patterns) {
+    return patterns.some((pattern) => matchesGlob(normalizePath(filePath), normalizePath(pattern)));
+}
+function inspectMarkdown(filePath) {
+    const content = readFileSync(filePath, 'utf8');
+    const headings = [];
+    const links = [];
+    const metadata = new Map();
+    let fence;
+    for (const [index, line] of content.split(/\r?\n/u).entries()) {
+        const fenceMatch = line.match(/^\s*(```+|~~~+)/u);
+        if (fenceMatch) {
+            fence = fence ? undefined : fenceMatch[1][0];
+            continue;
+        }
+        if (fence)
+            continue;
+        const heading = line.match(/^(#{1,6})\s+(.+?)\s*$/u);
+        if (heading)
+            headings.push({ level: heading[1].length, text: heading[2], line: index + 1 });
+        const metadataMatch = line.match(/^>\s+\*\*([^*]+):\*\*\s+(.+?)\s{0,2}$/u);
+        if (metadataMatch)
+            metadata.set(metadataMatch[1], metadataMatch[2]);
+        for (const linkMatch of line.matchAll(/!?\[[^\]]*\]\((<[^>]+>|[^\s)]+)(?:\s+["'][^"']*["'])?\)/gu)) {
+            links.push({ target: linkMatch[1].replace(/^<|>$/gu, ''), line: index + 1 });
+        }
+    }
+    return { headings, links, metadata, content };
+}
+function resolveLocalTarget(root, source, target) {
+    if (!target || target.startsWith('#') || target.startsWith('//') || /^[a-z][a-z\d+.-]*:/iu.test(target))
+        return undefined;
+    const pathPart = target.split(/[?#]/u, 1)[0];
+    if (!pathPart)
+        return undefined;
+    let decoded = pathPart;
+    try {
+        decoded = decodeURIComponent(pathPart);
+    }
+    catch {
+        // Keep the original path so malformed links are reported as missing.
+    }
+    return resolve(pathPart.startsWith('/') ? root : dirname(source), pathPart.startsWith('/') ? `.${decoded}` : decoded);
+}
+function resolvedMarkdownTarget(root, source, target) {
+    const resolved = resolveLocalTarget(root, source, target);
+    if (!resolved || !existsSync(resolved))
+        return resolved;
+    return statSync(resolved).isDirectory() ? join(resolved, 'README.md') : resolved;
+}
+function linkCount(root, source, parsed, target) {
+    return parsed.links.filter((link) => resolvedMarkdownTarget(root, source, link.target) === target).length;
+}
+function interpolate(template, source) {
+    const fileName = basename(source);
+    return template.replaceAll('{basename}', fileName).replaceAll('{stem}', basename(fileName, extname(fileName)));
+}
+function markdownCells(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|') || !trimmed.endsWith('|'))
+        return [];
+    return trimmed.slice(1, -1).split('|').map((cell) => cell.trim());
+}
+function validatePairContent(root, target, parsed, pair) {
+    const errors = [];
+    const display = relativePath(root, target);
+    if (pair.table) {
+        const lines = parsed.content.split(/\r?\n/u);
+        const headerIndex = lines.findIndex((line) => JSON.stringify(markdownCells(line)) === JSON.stringify(pair.table?.header));
+        if (headerIndex < 0) {
+            errors.push(`${display}: missing table header | ${pair.table.header.join(' | ')} |`);
+        }
+        else {
+            const columnIndex = pair.table.header.indexOf(pair.table.fileColumn);
+            const rows = [];
+            for (let index = headerIndex + 2; index < lines.length; index += 1) {
+                const cells = markdownCells(lines[index]);
+                if (cells.length === 0)
+                    break;
+                rows.push(cells);
+            }
+            const minRows = pair.table.minRows ?? 1;
+            if (rows.length < minRows)
+                errors.push(`${display}: table requires at least ${minRows} data row(s)`);
+            for (const row of rows) {
+                const references = [...(row[columnIndex] ?? '').matchAll(/`([^`]+)`/gu)].map((match) => match[1]);
+                const invalidReference = references.find((reference) => {
+                    const filePath = resolve(root, reference);
+                    return !isInsideRoot(root, filePath) || !existsSync(filePath) || !statSync(filePath).isFile();
+                });
+                if (references.length === 0 || invalidReference) {
+                    errors.push(`${display}: invalid or missing file reference in ${pair.table.fileColumn}: ${row[columnIndex] ?? ''}`);
+                }
+            }
+        }
+    }
+    if (pair.finalSection) {
+        const headings = parsed.headings.filter((heading) => heading.level === 2);
+        const section = headings.find((heading) => heading.text === pair.finalSection?.heading);
+        if (!section) {
+            errors.push(`${display}: missing final section ## ${pair.finalSection.heading}`);
+        }
+        else {
+            if (headings.at(-1) !== section)
+                errors.push(`${display}: ## ${pair.finalSection.heading} must be the final H2 section`);
+            const lines = parsed.content.split(/\r?\n/u).slice(section.line);
+            const items = lines.filter((line) => /^\s*-\s+\S/u.test(line)).length;
+            if (items < (pair.finalSection.minItems ?? 1))
+                errors.push(`${display}: final section requires at least ${pair.finalSection.minItems ?? 1} list item(s)`);
+        }
+    }
+    return errors;
+}
+export function checkDocumentation(root, config) {
+    validateDocumentationConfig(config);
+    const excluded = config.excludeDirectories ? new Set(config.excludeDirectories) : defaultExcludedDirectories;
+    const allFiles = walkFiles(root, excluded);
+    const relativeFiles = new Map(allFiles.map((file) => [file, relativePath(root, file)]));
+    const documentFiles = allFiles.filter((file) => matches(relativeFiles.get(file), config.files));
+    const parsed = new Map(documentFiles.map((file) => [file, inspectMarkdown(file)]));
+    const errors = [];
+    for (const [file, markdown] of parsed) {
+        const display = relativePath(root, file);
+        if (config.checks?.singleH1 !== false) {
+            const h1Count = markdown.headings.filter((heading) => heading.level === 1).length;
+            if (h1Count !== 1)
+                errors.push(`${display}: expected exactly one H1; found ${h1Count}`);
+        }
+        if (config.checks?.headingOrder !== false) {
+            for (let index = 1; index < markdown.headings.length; index += 1) {
+                const previous = markdown.headings[index - 1];
+                const current = markdown.headings[index];
+                if (current.level > previous.level + 1)
+                    errors.push(`${display}:${current.line}: heading jumps from H${previous.level} to H${current.level}`);
+            }
+        }
+        if (config.checks?.localLinks !== false) {
+            for (const link of markdown.links) {
+                const target = resolveLocalTarget(root, file, link.target);
+                if (target && (!isInsideRoot(root, target) || !existsSync(target)))
+                    errors.push(`${display}:${link.line}: broken or unsafe local link: ${link.target}`);
+            }
+        }
+    }
+    const reachability = config.checks?.reachability;
+    if (reachability) {
+        const roots = documentFiles.filter((file) => matches(relativeFiles.get(file), reachability.entrypoints));
+        const reachable = new Set(roots);
+        const queue = [...roots];
+        while (queue.length > 0) {
+            const source = queue.shift();
+            for (const link of parsed.get(source).links) {
+                const target = resolvedMarkdownTarget(root, source, link.target);
+                if (!target || reachable.has(target) || !parsed.has(target))
+                    continue;
+                reachable.add(target);
+                queue.push(target);
+            }
+        }
+        for (const file of documentFiles.filter((candidate) => matches(relativeFiles.get(candidate), reachability.files))) {
+            if (!reachable.has(file))
+                errors.push(`${relativePath(root, file)}: document is unreachable from configured entrypoints`);
+        }
+    }
+    for (const requiredFile of config.requiredFiles ?? []) {
+        if (!existsSync(resolve(root, requiredFile)))
+            errors.push(`${normalizePath(requiredFile)}: required documentation file is missing`);
+    }
+    for (const collection of config.collections ?? []) {
+        const sources = documentFiles.filter((file) => {
+            const display = relativeFiles.get(file);
+            return matches(display, collection.files) && !matches(display, collection.exclude ?? []);
+        });
+        const indexPath = collection.index ? resolve(root, collection.index) : undefined;
+        const indexMarkdown = indexPath && existsSync(indexPath) ? inspectMarkdown(indexPath) : undefined;
+        if (indexPath && !indexMarkdown)
+            errors.push(`${relativePath(root, indexPath)}: collection index is missing`);
+        const uniqueValues = new Map();
+        const generatedPairs = new Set();
+        for (const source of sources) {
+            const sourceMarkdown = parsed.get(source);
+            const display = relativePath(root, source);
+            if (indexPath && indexMarkdown && linkCount(root, indexPath, indexMarkdown, source) !== 1) {
+                errors.push(`${display}: expected exactly one link in ${relativePath(root, indexPath)}`);
+            }
+            for (const [field, rule] of Object.entries(collection.metadata ?? {})) {
+                const rawValue = sourceMarkdown.metadata.get(field);
+                if (!rawValue) {
+                    errors.push(`${display}: missing required metadata: ${field}`);
+                    continue;
+                }
+                const value = rawValue.replaceAll('`', '').trim();
+                if (rule.equals !== undefined && value !== interpolate(rule.equals, source))
+                    errors.push(`${display}: ${field} must equal ${interpolate(rule.equals, source)}`);
+                if (rule.unique) {
+                    const values = uniqueValues.get(field) ?? new Map();
+                    const previous = values.get(value);
+                    if (previous)
+                        errors.push(`${display}: duplicate ${field} with ${previous}: ${value}`);
+                    else
+                        values.set(value, display);
+                    uniqueValues.set(field, values);
+                }
+                if (rule.repositoryPaths) {
+                    const references = [...rawValue.matchAll(/`([^`]+)`/gu)].map((match) => match[1]);
+                    if (references.length < (rule.minItems ?? 1))
+                        errors.push(`${display}: ${field} requires at least ${rule.minItems ?? 1} repository path(s)`);
+                    for (const reference of references) {
+                        const target = resolve(root, reference);
+                        if (!isInsideRoot(root, target) || !existsSync(target))
+                            errors.push(`${display}: missing repository path in ${field}: ${reference}`);
+                    }
+                }
+            }
+            const pair = collection.pairedDocuments;
+            if (!pair)
+                continue;
+            const target = resolve(root, interpolate(pair.target, source));
+            generatedPairs.add(target);
+            if (linkCount(root, source, sourceMarkdown, target) !== 1)
+                errors.push(`${display}: expected exactly one link to ${relativePath(root, target)}`);
+            if (!existsSync(target)) {
+                errors.push(`${relativePath(root, target)}: paired document is missing`);
+                continue;
+            }
+            const targetMarkdown = parsed.get(target) ?? inspectMarkdown(target);
+            if (pair.index) {
+                const pairIndex = resolve(root, pair.index);
+                if (!existsSync(pairIndex) || linkCount(root, pairIndex, inspectMarkdown(pairIndex), target) !== 1) {
+                    errors.push(`${relativePath(root, target)}: expected exactly one link in ${relativePath(root, pairIndex)}`);
+                }
+            }
+            errors.push(...validatePairContent(root, target, targetMarkdown, pair));
+        }
+        const pair = collection.pairedDocuments;
+        if (pair) {
+            const pairDirectory = resolve(root, dirname(pair.target));
+            const pairIndex = pair.index ? resolve(root, pair.index) : undefined;
+            for (const file of documentFiles.filter((candidate) => dirname(candidate) === pairDirectory && candidate !== pairIndex)) {
+                if (!generatedPairs.has(file))
+                    errors.push(`${relativePath(root, file)}: paired document has no source document`);
+            }
+        }
+    }
+    for (const inventory of config.inventories ?? []) {
+        const inventoryPath = resolve(root, inventory.document);
+        if (!existsSync(inventoryPath)) {
+            errors.push(`${normalizePath(inventory.document)}: inventory document is missing`);
+            continue;
+        }
+        const sources = allFiles.filter((file) => matches(relativeFiles.get(file), inventory.sources));
+        const minMatches = inventory.minMatches ?? 0;
+        if (sources.length < minMatches)
+            errors.push(`${normalizePath(inventory.document)}: inventory requires at least ${minMatches} source match(es)`);
+        const content = readFileSync(inventoryPath, 'utf8');
+        for (const source of sources) {
+            const display = relativeFiles.get(source);
+            if (!content.includes(`\`${display}\``))
+                errors.push(`${normalizePath(inventory.document)}: source is not inventoried: ${display}`);
+        }
+    }
+    return errors.sort();
+}
+/* v8 ignore start -- executable adapter */
+async function main() {
+    const { config, configPath } = await loadConfig(process.cwd());
+    if (!configPath || !config.documentation)
+        throw new Error('documentation is not configured in .webtoolkit-cli/config.json.');
+    const root = dirname(dirname(configPath));
+    const errors = checkDocumentation(root, config.documentation);
+    if (errors.length > 0) {
+        console.error(errors.join('\n'));
+        process.exitCode = 1;
+        return;
+    }
+    console.info('Documentation is valid.');
+}
+/* v8 ignore stop */
+/* v8 ignore start -- executable adapter */
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    main().catch((error) => {
+        console.error(error.message);
+        process.exitCode = 1;
+    });
+}
+/* v8 ignore stop */

package/dist/guards/guard-config.d.ts

@@ -0,0 +1,19 @@
+import type { GuardsConfig } from '../config.js';
+export declare const BASE_ARTIFACT_EXCLUDE_PATTERNS: string[];
+export declare const BASE_SOURCE_EXTENSIONS: Set<string>;
+export declare const BASE_TYPESCRIPT_EXTENSIONS: Set<string>;
+export declare const BASE_JSX_EXTENSIONS: Set<string>;
+export declare const BASE_SOURCE_EXCLUDE_PATTERNS: string[];
+export declare const BASE_LAYER_EXCLUDE_PATTERNS: string[];
+export declare function loadGuardConfig<K extends keyof GuardsConfig>(name: K, cwd?: string): Promise<NonNullable<GuardsConfig[K]>>;
+export declare function compilePatterns(patterns?: string[], basePatterns?: string[]): RegExp[];
+export declare function hasExtension(filePath: string, extensions: Set<string>): boolean;
+export declare function resolveProjectPath(root: string, configuredPath: string): string;
+export declare function assertConfiguredScanScope(options: {
+    root: string;
+    guardName: string;
+    configPath: string;
+    configuredPaths: string[];
+    eligibleFiles: string[];
+}): void;
+export declare function isMainModule(moduleUrl: string, argv?: string[]): boolean;

package/dist/guards/guard-config.js

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from '../config.js';
+export const BASE_ARTIFACT_EXCLUDE_PATTERNS = [
+    '(^|[/\\\\])node_modules([/\\\\]|$)',
+    '(^|[/\\\\])dist([/\\\\]|$)',
+    '(^|[/\\\\])build([/\\\\]|$)',
+    '(^|[/\\\\])coverage([/\\\\]|$)',
+];
+export const BASE_SOURCE_EXTENSIONS = new Set([
+    '.cjs',
+    '.cts',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.mts',
+    '.ts',
+    '.tsx',
+]);
+export const BASE_TYPESCRIPT_EXTENSIONS = new Set(['.cts', '.mts', '.ts', '.tsx']);
+export const BASE_JSX_EXTENSIONS = new Set(['.jsx', '.tsx']);
+export const BASE_SOURCE_EXCLUDE_PATTERNS = [
+    ...BASE_ARTIFACT_EXCLUDE_PATTERNS,
+    '\\.(test|spec)([.-]|$)',
+    '(^|[/\\\\])tests?([/\\\\]|$)',
+    '(^|[/\\\\])__tests__([/\\\\]|$)',
+    '\\.stories\\.',
+];
+export const BASE_LAYER_EXCLUDE_PATTERNS = [
+    ...BASE_SOURCE_EXCLUDE_PATTERNS,
+    '\\.(config|setup)\\.',
+];
+export async function loadGuardConfig(name, cwd = process.cwd()) {
+    const { config, configPath } = await loadConfig(cwd);
+    const guardConfig = config.guards?.[name];
+    if (!configPath || !guardConfig) {
+        throw new Error(`guards.${name} is not configured in .webtoolkit-cli/config.json.`);
+    }
+    return guardConfig;
+}
+export function compilePatterns(patterns = [], basePatterns = []) {
+    return [...basePatterns, ...patterns].map((pattern) => {
+        try {
+            return new RegExp(pattern);
+        }
+        catch {
+            throw new Error(`Invalid regular expression in guard configuration: ${pattern}`);
+        }
+    });
+}
+export function hasExtension(filePath, extensions) {
+    const extension = filePath.slice(filePath.lastIndexOf('.')).toLowerCase();
+    return extensions.has(extension);
+}
+export function resolveProjectPath(root, configuredPath) {
+    const absolutePath = path.resolve(root, configuredPath);
+    const relativePath = path.relative(root, absolutePath);
+    if (path.isAbsolute(configuredPath) || relativePath === '..' || relativePath.startsWith(`..${path.sep}`)) {
+        throw new Error(`Guard path must stay inside the project: ${configuredPath}`);
+    }
+    return absolutePath;
+}
+export function assertConfiguredScanScope(options) {
+    for (const configuredPath of options.configuredPaths) {
+        const absolutePath = resolveProjectPath(options.root, configuredPath);
+        let stats;
+        try {
+            stats = fs.statSync(absolutePath);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                throw new Error(`${options.guardName}: ${options.configPath} contains a missing directory: ${configuredPath}`);
+            }
+            throw error;
+        }
+        if (!stats.isDirectory()) {
+            throw new Error(`${options.guardName}: ${options.configPath} must contain directories; received: ${configuredPath}`);
+        }
+    }
+    if (options.eligibleFiles.length === 0) {
+        throw new Error(`${options.guardName}: ${options.configPath} matched zero eligible files in: ${options.configuredPaths.join(', ')}`);
+    }
+}
+export function isMainModule(moduleUrl, argv = process.argv) {
+    return Boolean(argv[1]) && path.resolve(argv[1]) === fileURLToPath(moduleUrl);
+}

package/dist/guards/internal-link-guard.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+/**
+ * Internal Link Guard
+ *
+ * Prevents internal SPA navigation through raw <a href="...">.
+ * For React routes, use <Link to="..."> from react-router-dom.
+ */
+import type { PathScanGuardConfig } from '../config.js';
+export declare function runInternalLinkGuard(options?: {
+    rootDir?: string;
+    config?: PathScanGuardConfig;
+}): Promise<number>;