@titannio/webtoolkit-cli 1.3.0

package/dist/guards/tsconfig-guard.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import ts from 'typescript';
+import { isMainModule, loadGuardConfig, resolveProjectPath } from './guard-config.js';
+const colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    green: '\x1b[32m',
+};
+function formatDiagnostics(relativePath, diagnostics) {
+    return diagnostics.map((diagnostic) => (`${relativePath}: TS${diagnostic.code}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')}`)).join('\n');
+}
+function readConfig(rootDir, relativePath) {
+    const absolutePath = resolveProjectPath(rootDir, relativePath);
+    if (!fs.existsSync(absolutePath))
+        throw new Error(`Config file not found: ${relativePath}`);
+    const result = ts.readConfigFile(absolutePath, ts.sys.readFile);
+    if (result.error) {
+        throw new Error(formatDiagnostics(relativePath, [result.error]));
+    }
+    const parsed = ts.parseJsonConfigFileContent(result.config, ts.sys, path.dirname(absolutePath), undefined, absolutePath);
+    if (parsed.errors.length > 0) {
+        throw new Error(formatDiagnostics(relativePath, parsed.errors));
+    }
+    return {
+        raw: result.config,
+        parsed,
+        absolutePath,
+    };
+}
+function pointsToSourceInternals(values) {
+    return values.some((value) => /(^|[/\\])src([/\\]|$)/u.test(value));
+}
+export async function runTsconfigGuard(options = {}) {
+    const rootDir = options.rootDir ?? process.cwd();
+    const config = options.config ?? await loadGuardConfig('tsconfig', rootDir);
+    /* v8 ignore next -- both outcomes are asserted; V8 omits the fallthrough branch */
+    if (config.configs.length === 0) {
+        throw new Error('guards.tsconfig.configs must not be empty.');
+    }
+    const errors = [];
+    for (const check of config.configs) {
+        const loaded = readConfig(rootDir, check.path);
+        const rawInclude = Array.isArray(loaded.raw.include) ? loaded.raw.include : [];
+        const aliases = loaded.parsed.options.paths ?? {};
+        for (const requiredInclude of check.requiredIncludes ?? []) {
+            if (!rawInclude.includes(requiredInclude)) {
+                errors.push(`${check.path}: include must contain "${requiredInclude}".`);
+            }
+        }
+        const expectedOptions = check.compilerOptions ?? {};
+        const converted = ts.convertCompilerOptionsFromJson(expectedOptions, path.dirname(loaded.absolutePath), check.path);
+        if (converted.errors.length > 0) {
+            throw new Error(formatDiagnostics(check.path, converted.errors));
+        }
+        for (const [option, expected] of Object.entries(expectedOptions)) {
+            const actual = loaded.parsed.options[option];
+            const normalizedExpected = converted.options[option];
+            if (actual !== normalizedExpected) {
+                errors.push(`${check.path}: compilerOptions.${option} must equal ${JSON.stringify(expected)}; found ${JSON.stringify(actual)}.`);
+            }
+        }
+        if (config.packageScope) {
+            for (const alias of Object.keys(aliases)) {
+                if (alias.startsWith(config.packageScope) && alias !== config.packageScope && !alias.startsWith(`${config.packageScope}/`)) {
+                    errors.push(`${check.path}: alias "${alias}" must use the "${config.packageScope}/package-name" convention.`);
+                }
+            }
+        }
+        for (const alias of check.publicAliases ?? []) {
+            const targets = aliases[alias] ?? [];
+            if (pointsToSourceInternals(targets)) {
+                errors.push(`${check.path}: public alias "${alias}" cannot point to package src internals.`);
+            }
+        }
+    }
+    for (const check of config.textFiles ?? []) {
+        const absolutePath = resolveProjectPath(rootDir, check.path);
+        if (!fs.existsSync(absolutePath))
+            throw new Error(`Text file not found: ${check.path}`);
+        const content = fs.readFileSync(absolutePath, 'utf8');
+        for (const forbidden of check.forbiddenStrings) {
+            if (content.includes(forbidden))
+                errors.push(`${check.path}: contains forbidden text "${forbidden}".`);
+        }
+    }
+    if (errors.length > 0) {
+        console.error('\nTSConfig guard failed:');
+        for (const error of errors)
+            console.error(`  - ${error}`);
+        return 1;
+    }
+    console.info(`✅${colors.green}${colors.bright} [OK]${colors.reset} TSConfig guard in compliance`);
+    return 0;
+}
+/* v8 ignore start -- executable adapter */
+if (isMainModule(import.meta.url)) {
+    runTsconfigGuard().then((code) => {
+        process.exitCode = code;
+    }).catch((error) => {
+        console.error(error.message);
+        process.exitCode = 1;
+    });
+}
+/* v8 ignore stop */

package/dist/guards/workspace-manifest-guard.d.ts

@@ -0,0 +1,21 @@
+import type { WorkspaceManifestGuardConfig } from '../config.js';
+import { type ManifestDependencies } from './singleton-deps-guard.js';
+type WorkspaceManifest = ManifestDependencies & {
+    name?: unknown;
+};
+type LoadedManifest = {
+    absoluteDirectory: string;
+    filePath: string;
+    manifest: WorkspaceManifest;
+};
+export type WorkspaceManifestIssue = {
+    filePath: string;
+    dependency?: string;
+    message: string;
+};
+export declare function inspectWorkspaceManifests(rootDir: string, manifests: LoadedManifest[], config: WorkspaceManifestGuardConfig): WorkspaceManifestIssue[];
+export declare function runWorkspaceManifestGuard(options?: {
+    rootDir?: string;
+    config?: WorkspaceManifestGuardConfig;
+}): Promise<number>;
+export {};

package/dist/guards/workspace-manifest-guard.js

@@ -0,0 +1,210 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { assertConfiguredScanScope, isMainModule, loadGuardConfig, resolveProjectPath, } from './guard-config.js';
+import { MANIFEST_FIELDS, } from './singleton-deps-guard.js';
+const require = createRequire(import.meta.url);
+const semver = require('semver');
+const runtimeFields = ['dependencies', 'peerDependencies', 'optionalDependencies'];
+function normalizedRelativePath(rootDir, filePath) {
+    return path.relative(rootDir, filePath).replaceAll('\\', '/');
+}
+function pathKey(value) {
+    const normalized = path.resolve(value);
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+function readManifest(rootDir, manifestPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${normalizedRelativePath(rootDir, manifestPath)}: invalid package.json: ${error.message}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${normalizedRelativePath(rootDir, manifestPath)}: package.json must contain an object.`);
+    }
+    return {
+        absoluteDirectory: path.dirname(manifestPath),
+        filePath: normalizedRelativePath(rootDir, manifestPath),
+        manifest: parsed,
+    };
+}
+function collectManifests(rootDir, packageRoots) {
+    const manifestPaths = [];
+    for (const configuredRoot of packageRoots) {
+        const absoluteRoot = resolveProjectPath(rootDir, configuredRoot);
+        if (!fs.existsSync(absoluteRoot) || !fs.statSync(absoluteRoot).isDirectory())
+            continue;
+        for (const entry of fs.readdirSync(absoluteRoot, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const manifestPath = path.join(absoluteRoot, entry.name, 'package.json');
+            if (fs.existsSync(manifestPath) && fs.statSync(manifestPath).isFile()) {
+                manifestPaths.push(manifestPath);
+            }
+        }
+    }
+    assertConfiguredScanScope({
+        root: rootDir,
+        guardName: 'workspace-manifest',
+        configPath: 'guards.workspaceManifest.packageRoots',
+        configuredPaths: packageRoots,
+        eligibleFiles: manifestPaths,
+    });
+    return manifestPaths.sort().map((manifestPath) => readManifest(rootDir, manifestPath));
+}
+function isValidWorkspaceRange(value) {
+    const range = value.slice('workspace:'.length);
+    return range === '*' || range === '^' || range === '~' || semver.validRange(range) !== null;
+}
+function hasNonSemverProtocol(value) {
+    return /^(?:file|link|npm|git(?:\+\w+)?|https?|ssh|github|gitlab|bitbucket):/u.test(value);
+}
+function isValidVersionSpecifier(value, field) {
+    if (value.startsWith('workspace:'))
+        return isValidWorkspaceRange(value);
+    if (semver.validRange(value) !== null || hasNonSemverProtocol(value))
+        return true;
+    return field !== 'peerDependencies' && /^[A-Za-z][\w.-]*$/u.test(value);
+}
+function dependencyEntries(manifest) {
+    return MANIFEST_FIELDS.flatMap((field) => (Object.entries(manifest[field] ?? {}).map(([dependency, version]) => ({
+        field,
+        dependency,
+        version,
+    }))));
+}
+function requirementPackage(rootDir, manifestByDirectory, configuredPath, configPath) {
+    const absoluteDirectory = resolveProjectPath(rootDir, configuredPath);
+    const loaded = manifestByDirectory.get(pathKey(absoluteDirectory));
+    if (!loaded) {
+        throw new Error(`workspace-manifest: ${configPath} must reference a discovered workspace package containing package.json: ${configuredPath}`);
+    }
+    return loaded;
+}
+function checkPeerRequirement(rootDir, requirement, index, manifestByDirectory) {
+    const issues = [];
+    for (const [providerIndex, providerPath] of requirement.providers.entries()) {
+        const provider = requirementPackage(rootDir, manifestByDirectory, providerPath, `guards.workspaceManifest.peerRequirements[${index}].providers[${providerIndex}]`);
+        if (!provider.manifest.peerDependencies?.[requirement.dependency]) {
+            issues.push({
+                filePath: provider.filePath,
+                dependency: requirement.dependency,
+                message: 'must be declared in peerDependencies for this provider',
+            });
+        }
+        if (provider.manifest.dependencies?.[requirement.dependency] ||
+            provider.manifest.optionalDependencies?.[requirement.dependency]) {
+            issues.push({
+                filePath: provider.filePath,
+                dependency: requirement.dependency,
+                message: 'must not be declared in provider runtime dependencies',
+            });
+        }
+    }
+    for (const [consumerIndex, consumerPath] of requirement.consumers.entries()) {
+        const consumer = requirementPackage(rootDir, manifestByDirectory, consumerPath, `guards.workspaceManifest.peerRequirements[${index}].consumers[${consumerIndex}]`);
+        const directRuntimeDeclaration = runtimeFields.some((field) => (Boolean(consumer.manifest[field]?.[requirement.dependency])));
+        if (!directRuntimeDeclaration) {
+            issues.push({
+                filePath: consumer.filePath,
+                dependency: requirement.dependency,
+                message: 'must be declared directly in a runtime dependency section for this consumer',
+            });
+        }
+    }
+    return issues;
+}
+export function inspectWorkspaceManifests(rootDir, manifests, config) {
+    const issues = [];
+    const manifestsByName = new Map();
+    const duplicateNames = new Set();
+    for (const loaded of manifests) {
+        if (typeof loaded.manifest.name !== 'string' || loaded.manifest.name.trim() === '') {
+            issues.push({ filePath: loaded.filePath, message: 'workspace package name is required' });
+            continue;
+        }
+        const existing = manifestsByName.get(loaded.manifest.name);
+        if (existing) {
+            duplicateNames.add(loaded.manifest.name);
+            issues.push({
+                filePath: loaded.filePath,
+                dependency: loaded.manifest.name,
+                message: `duplicates workspace package name from ${existing.filePath}`,
+            });
+        }
+        else {
+            manifestsByName.set(loaded.manifest.name, loaded);
+        }
+    }
+    const internalNames = new Set([...manifestsByName.keys()].filter((name) => !duplicateNames.has(name)));
+    for (const loaded of manifests) {
+        for (const { field, dependency, version } of dependencyEntries(loaded.manifest)) {
+            if (!isValidVersionSpecifier(version, field)) {
+                issues.push({
+                    filePath: loaded.filePath,
+                    dependency,
+                    message: `has invalid version range ${JSON.stringify(version)} in ${field}`,
+                });
+            }
+            if (config.requireWorkspaceProtocol &&
+                internalNames.has(dependency) &&
+                !version.startsWith('workspace:')) {
+                issues.push({
+                    filePath: loaded.filePath,
+                    dependency,
+                    message: `must use the workspace: protocol in ${field}`,
+                });
+            }
+        }
+        const dependencies = new Set(runtimeFields.flatMap((field) => (Object.keys(loaded.manifest[field] ?? {}))));
+        for (const dependency of dependencies) {
+            const declaredFields = runtimeFields.filter((field) => (Boolean(loaded.manifest[field]?.[dependency])));
+            if (declaredFields.length > 1) {
+                issues.push({
+                    filePath: loaded.filePath,
+                    dependency,
+                    message: `is declared in conflicting runtime sections: ${declaredFields.join(', ')}`,
+                });
+            }
+        }
+    }
+    const manifestByDirectory = new Map(manifests.map((loaded) => [pathKey(loaded.absoluteDirectory), loaded]));
+    for (const [index, requirement] of config.peerRequirements.entries()) {
+        issues.push(...checkPeerRequirement(rootDir, requirement, index, manifestByDirectory));
+    }
+    return issues.sort((left, right) => (left.filePath.localeCompare(right.filePath) ||
+        (left.dependency ?? '').localeCompare(right.dependency ?? '') ||
+        left.message.localeCompare(right.message)));
+}
+export async function runWorkspaceManifestGuard(options = {}) {
+    const rootDir = options.rootDir ?? process.cwd();
+    const config = options.config ?? await loadGuardConfig('workspaceManifest', rootDir);
+    /* v8 ignore next -- both outcomes are asserted; V8 omits the fallthrough branch */
+    if (config.packageRoots.length === 0) {
+        throw new Error('guards.workspaceManifest.packageRoots must not be empty.');
+    }
+    const manifests = collectManifests(rootDir, config.packageRoots);
+    const issues = inspectWorkspaceManifests(rootDir, manifests, config);
+    if (issues.length === 0) {
+        console.info(`Workspace manifests are valid (${manifests.length} packages).`);
+        return 0;
+    }
+    console.error('Workspace manifest guard failed:');
+    for (const issue of issues) {
+        const dependency = issue.dependency ? ` [${issue.dependency}]` : '';
+        console.error(`  - ${issue.filePath}${dependency}: ${issue.message}`);
+    }
+    return 1;
+}
+/* v8 ignore start -- executable adapter */
+if (isMainModule(import.meta.url)) {
+    runWorkspaceManifestGuard().then((code) => {
+        process.exitCode = code;
+    }).catch((error) => {
+        console.error(error.message);
+        process.exitCode = 1;
+    });
+}
+/* v8 ignore stop */

package/dist/jsdoc-report.d.ts

@@ -0,0 +1,7 @@
+import type { WebToolkitCliConfig } from './config.js';
+type Runtime = {
+    cwd: string;
+    config: WebToolkitCliConfig;
+};
+export declare function runJSDocReport(runtime: Runtime, rawArgs: string[]): Promise<void>;
+export {};