@titannio/webtoolkit-cli 1.3.0

package/dist/guards/internal-link-guard.js

@@ -0,0 +1,272 @@
+#!/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 * as fs from 'fs';
+import * as path from 'path';
+import { Project, SyntaxKind, } from 'ts-morph';
+import { BASE_JSX_EXTENSIONS, BASE_SOURCE_EXCLUDE_PATTERNS, assertConfiguredScanScope, compilePatterns, hasExtension, isMainModule, loadGuardConfig, resolveProjectPath } from './guard-config.js';
+const colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    gray: '\x1b[90m',
+};
+function shouldSkipFile(filePath, excludePatterns) {
+    if (!hasExtension(filePath, BASE_JSX_EXTENSIONS))
+        return true;
+    return excludePatterns.some((pattern) => pattern.test(filePath));
+}
+function collectFiles(rootDir, includePaths, excludePatterns) {
+    const files = [];
+    function walk(dir) {
+        if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+            return;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(fullPath);
+                continue;
+            }
+            if (entry.isFile() && !shouldSkipFile(fullPath, excludePatterns)) {
+                files.push(fullPath);
+            }
+        }
+    }
+    for (const relativePath of includePaths) {
+        walk(resolveProjectPath(rootDir, relativePath));
+    }
+    return files;
+}
+function isInternalHrefLiteral(value) {
+    const normalized = value.trim();
+    return normalized.startsWith('/') || normalized.startsWith('./') || normalized.startsWith('../');
+}
+function isExternalHttpHrefLiteral(value) {
+    const normalized = value.trim().toLowerCase();
+    return normalized.startsWith('http://') || normalized.startsWith('https://');
+}
+function parseJsxAttributeStaticValue(attr) {
+    if (!attr)
+        return null;
+    const initializer = attr.getInitializer();
+    if (!initializer)
+        return null;
+    if (initializer.getKind() === SyntaxKind.StringLiteral) {
+        return initializer.getText().slice(1, -1);
+    }
+    const expression = initializer.asKindOrThrow(SyntaxKind.JsxExpression).getExpression();
+    if (!expression)
+        return null;
+    if (expression.getKind() === SyntaxKind.StringLiteral || expression.getKind() === SyntaxKind.NoSubstitutionTemplateLiteral) {
+        return expression.getText().slice(1, -1);
+    }
+    return null;
+}
+function inspectHrefAttribute(attr) {
+    const initializer = attr.getInitializer();
+    const snippet = attr.getText();
+    if (!initializer)
+        return { kind: 'other', snippet };
+    if (initializer.getKind() === SyntaxKind.StringLiteral) {
+        const literalValue = initializer.getText().slice(1, -1);
+        if (literalValue.trim() === '#') {
+            return {
+                kind: 'placeholder',
+                reason: 'href="#"',
+                snippet,
+            };
+        }
+        if (isExternalHttpHrefLiteral(literalValue)) {
+            return {
+                kind: 'external',
+                reason: `href="${literalValue}"`,
+                snippet,
+            };
+        }
+        if (isInternalHrefLiteral(literalValue)) {
+            return {
+                kind: 'internal',
+                reason: `href="${literalValue}"`,
+                snippet,
+            };
+        }
+        return { kind: 'other', snippet };
+    }
+    const expression = initializer.asKindOrThrow(SyntaxKind.JsxExpression).getExpression();
+    if (!expression)
+        return { kind: 'other', snippet };
+    if (expression.getKind() === SyntaxKind.StringLiteral || expression.getKind() === SyntaxKind.NoSubstitutionTemplateLiteral) {
+        const text = expression.getText();
+        const value = text.slice(1, -1);
+        if (value.trim() === '#') {
+            return {
+                kind: 'placeholder',
+                reason: `href={${text}}`,
+                snippet,
+            };
+        }
+        if (isExternalHttpHrefLiteral(value)) {
+            return {
+                kind: 'external',
+                reason: `href={${text}}`,
+                snippet,
+            };
+        }
+        if (isInternalHrefLiteral(value)) {
+            return {
+                kind: 'internal',
+                reason: `href={${text}}`,
+                snippet,
+            };
+        }
+    }
+    const expressionText = expression.getText().trim();
+    const looksLikeInternalRouteExpression = expressionText.includes('ROUTES.') ||
+        expressionText.startsWith('`/') ||
+        expressionText.startsWith('"/') ||
+        expressionText.startsWith("'/") ||
+        expressionText.startsWith('`./') ||
+        expressionText.startsWith('`../');
+    if (looksLikeInternalRouteExpression) {
+        return {
+            kind: 'internal',
+            reason: `href={${expressionText}}`,
+            snippet,
+        };
+    }
+    return { kind: 'other', snippet };
+}
+function hasSecureRel(relValue) {
+    if (!relValue)
+        return false;
+    const tokens = new Set(relValue
+        .trim()
+        .split(/\s+/)
+        .map((token) => token.toLowerCase()));
+    return tokens.has('noopener') && tokens.has('noreferrer');
+}
+function getAnchorViolationsFromNode(node, sourceRelativePath) {
+    if (node.getTagNameNode().getText() !== 'a')
+        return [];
+    const attrs = node
+        .getAttributes()
+        .map((attr) => attr.asKind(SyntaxKind.JsxAttribute))
+        .filter((attr) => Boolean(attr));
+    const hrefAttr = attrs.find((attr) => attr.getNameNode().getText() === 'href');
+    const targetAttr = attrs.find((attr) => attr.getNameNode().getText() === 'target');
+    const relAttr = attrs.find((attr) => attr.getNameNode().getText() === 'rel');
+    const targetValue = parseJsxAttributeStaticValue(targetAttr);
+    const relValue = parseJsxAttributeStaticValue(relAttr);
+    const violations = [];
+    if (targetValue === '_blank' && !hasSecureRel(relValue)) {
+        violations.push({
+            filePath: sourceRelativePath,
+            line: (relAttr ?? targetAttr).getStartLineNumber(),
+            hrefSnippet: relAttr?.getText() ?? targetAttr.getText(),
+            reason: 'target="_blank" requires rel="noopener noreferrer"',
+        });
+    }
+    if (!hrefAttr)
+        return violations;
+    const check = inspectHrefAttribute(hrefAttr);
+    if (check.kind === 'other')
+        return violations;
+    if (check.kind === 'internal') {
+        violations.push({
+            filePath: sourceRelativePath,
+            line: hrefAttr.getStartLineNumber(),
+            hrefSnippet: check.snippet,
+            reason: check.reason,
+        });
+        return violations;
+    }
+    if (check.kind === 'placeholder') {
+        violations.push({
+            filePath: sourceRelativePath,
+            line: hrefAttr.getStartLineNumber(),
+            hrefSnippet: check.snippet,
+            reason: 'placeholder href detected (use button or real route instead of "#")',
+        });
+        return violations;
+    }
+    if (targetValue !== '_blank') {
+        violations.push({
+            filePath: sourceRelativePath,
+            line: hrefAttr.getStartLineNumber(),
+            hrefSnippet: check.snippet,
+            reason: `external link must use target="_blank" (${check.reason})`,
+        });
+    }
+    if (!hasSecureRel(relValue)) {
+        violations.push({
+            filePath: sourceRelativePath,
+            line: hrefAttr.getStartLineNumber(),
+            hrefSnippet: relAttr?.getText() ?? check.snippet,
+            reason: 'external link must include rel="noopener noreferrer"',
+        });
+    }
+    return violations;
+}
+export async function runInternalLinkGuard(options = {}) {
+    const rootDir = options.rootDir ?? process.cwd();
+    const config = options.config ?? await loadGuardConfig('internalLink', rootDir);
+    const excludePatterns = compilePatterns(config.excludePatterns, BASE_SOURCE_EXCLUDE_PATTERNS);
+    /* v8 ignore next -- both outcomes are asserted; V8 omits the fallthrough branch */
+    if (config.includePaths.length === 0)
+        throw new Error('guards.internalLink.includePaths must not be empty.');
+    console.info(`${colors.bright}${colors.blue}🔗 Checking internal navigation links...${colors.reset}`);
+    const files = collectFiles(rootDir, config.includePaths, excludePatterns);
+    assertConfiguredScanScope({
+        root: rootDir,
+        guardName: 'internal-link',
+        configPath: 'guards.internalLink.includePaths',
+        configuredPaths: config.includePaths,
+        eligibleFiles: files,
+    });
+    const project = new Project();
+    const violations = [];
+    for (const absoluteFilePath of files) {
+        const sourceFile = project.addSourceFileAtPath(absoluteFilePath);
+        const relativePath = path.relative(rootDir, absoluteFilePath);
+        sourceFile.getDescendantsOfKind(SyntaxKind.JsxOpeningElement).forEach((node) => {
+            violations.push(...getAnchorViolationsFromNode(node, relativePath));
+        });
+        sourceFile.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement).forEach((node) => {
+            violations.push(...getAnchorViolationsFromNode(node, relativePath));
+        });
+    }
+    if (violations.length === 0) {
+        console.info(`${colors.green}${colors.bright}✅ [OK]${colors.reset} Internal links are router-safe.`);
+        return 0;
+    }
+    console.info(`${colors.bright}${colors.yellow}⚠️  FOUND LINK POLICY VIOLATIONS${colors.reset}`);
+    console.info(`${colors.gray}Policies:${colors.reset}`);
+    console.info(`${colors.gray} - use <Link to=\"...\"> for internal app navigation${colors.reset}`);
+    console.info(`${colors.gray} - do not use href=\"#\" placeholders${colors.reset}`);
+    console.info(`${colors.gray} - external http(s) links must use target=\"_blank\" and rel=\"noopener noreferrer\"${colors.reset}\n`);
+    for (const violation of violations) {
+        console.info(`${colors.gray}${violation.filePath}:${violation.line}${colors.reset}`);
+        console.info(`   ${colors.red}→${colors.reset} ${violation.reason}`);
+        console.info(`   ${colors.gray}${violation.hrefSnippet}${colors.reset}\n`);
+    }
+    console.info(`${colors.bright}${colors.red}⚠️  IMPORTANT: Fix link policy violations before proceeding.${colors.reset}\n`);
+    return 1;
+}
+/* v8 ignore start -- executable adapter */
+if (isMainModule(import.meta.url)) {
+    runInternalLinkGuard().then((code) => {
+        process.exitCode = code;
+    }).catch((error) => {
+        console.error(error.message);
+        process.exitCode = 1;
+    });
+}
+/* v8 ignore stop */

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

@@ -0,0 +1,37 @@
+import type { PackageSurfaceGuardConfig } from '../config.js';
+type PackageManifest = {
+    main?: unknown;
+    module?: unknown;
+    types?: unknown;
+    typings?: unknown;
+    bin?: unknown;
+    exports?: unknown;
+};
+type ManifestTarget = {
+    field: string;
+    target: string;
+};
+export type PackageSurfaceIssue = {
+    packageDirectory: string;
+    field: string;
+    filePath: string;
+    message: string;
+};
+export type PackCommandResult = {
+    error?: Error;
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};
+type PackCommand = (packageDirectory: string) => PackCommandResult;
+export declare function collectManifestTargets(packageDirectory: string, manifest: PackageManifest): {
+    targets: ManifestTarget[];
+    issues: PackageSurfaceIssue[];
+};
+export declare function readPackedFiles(packageDirectory: string, runPack?: PackCommand): string[];
+export declare function runPackageSurfaceGuard(options?: {
+    rootDir?: string;
+    config?: PackageSurfaceGuardConfig;
+    runPack?: PackCommand;
+}): Promise<number>;
+export {};

package/dist/guards/package-surface-guard.js

@@ -0,0 +1,234 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveSpawnSpec } from '../process.js';
+import { compilePatterns, isMainModule, loadGuardConfig, resolveProjectPath, } from './guard-config.js';
+function normalizePackagePath(filePath) {
+    return filePath.replaceAll('\\', '/').replace(/^\.\//u, '');
+}
+function childField(parent, key) {
+    return /^[A-Za-z_$][\w$]*$/u.test(key)
+        ? `${parent}.${key}`
+        : `${parent}[${JSON.stringify(key)}]`;
+}
+function unsupportedTarget(packageDirectory, field, value) {
+    return {
+        packageDirectory,
+        field,
+        filePath: '',
+        message: `unsupported manifest target: ${JSON.stringify(value)}`,
+    };
+}
+function collectExports(packageDirectory, field, value, targets, issues) {
+    if (value === null)
+        return;
+    if (typeof value === 'string') {
+        targets.push({ field, target: value });
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => {
+            collectExports(packageDirectory, `${field}[${index}]`, entry, targets, issues);
+        });
+        return;
+    }
+    if (value && typeof value === 'object') {
+        for (const [key, entry] of Object.entries(value)) {
+            collectExports(packageDirectory, childField(field, key), entry, targets, issues);
+        }
+        return;
+    }
+    issues.push(unsupportedTarget(packageDirectory, field, value));
+}
+export function collectManifestTargets(packageDirectory, manifest) {
+    const targets = [];
+    const issues = [];
+    for (const field of ['main', 'module', 'types', 'typings']) {
+        const value = manifest[field];
+        if (value === undefined)
+            continue;
+        if (typeof value === 'string')
+            targets.push({ field, target: value });
+        else
+            issues.push(unsupportedTarget(packageDirectory, field, value));
+    }
+    if (manifest.bin !== undefined) {
+        if (typeof manifest.bin === 'string') {
+            targets.push({ field: 'bin', target: manifest.bin });
+        }
+        else if (manifest.bin && typeof manifest.bin === 'object' && !Array.isArray(manifest.bin)) {
+            for (const [name, value] of Object.entries(manifest.bin)) {
+                const field = childField('bin', name);
+                if (typeof value === 'string')
+                    targets.push({ field, target: value });
+                else
+                    issues.push(unsupportedTarget(packageDirectory, field, value));
+            }
+        }
+        else {
+            issues.push(unsupportedTarget(packageDirectory, 'bin', manifest.bin));
+        }
+    }
+    if (manifest.exports !== undefined) {
+        collectExports(packageDirectory, 'exports', manifest.exports, targets, issues);
+    }
+    return { targets, issues };
+}
+function runNpmPack(packageDirectory) {
+    const command = resolveSpawnSpec('npm', ['pack', '--dry-run', '--json', '--ignore-scripts']);
+    const result = spawnSync(command.command, command.args, {
+        cwd: packageDirectory,
+        encoding: 'utf8',
+        shell: false,
+    });
+    return {
+        error: result.error,
+        status: result.status,
+        stdout: result.stdout,
+        stderr: result.stderr,
+    };
+}
+export function readPackedFiles(packageDirectory, runPack = runNpmPack) {
+    const result = runPack(packageDirectory);
+    if (result.error) {
+        throw new Error(`package-surface: npm pack failed in ${packageDirectory}: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        const detail = result.stderr.trim();
+        throw new Error(`package-surface: npm pack failed in ${packageDirectory}${detail ? `: ${detail}` : '.'}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch (error) {
+        throw new Error(`package-surface: invalid npm pack JSON in ${packageDirectory}: ${error.message}`);
+    }
+    if (!Array.isArray(parsed) || parsed.length !== 1) {
+        throw new Error(`package-surface: npm pack JSON in ${packageDirectory} must contain one package.`);
+    }
+    const files = parsed[0].files;
+    if (!Array.isArray(files) || files.some((entry) => (!entry || typeof entry !== 'object' || typeof entry.path !== 'string'))) {
+        throw new Error(`package-surface: npm pack JSON in ${packageDirectory} has an invalid files list.`);
+    }
+    return files.map((entry) => normalizePackagePath(entry.path));
+}
+function loadManifest(rootDir, configuredDirectory) {
+    const absoluteDirectory = resolveProjectPath(rootDir, configuredDirectory);
+    if (!fs.existsSync(absoluteDirectory) || !fs.statSync(absoluteDirectory).isDirectory()) {
+        throw new Error(`package-surface: missing package directory: ${configuredDirectory}`);
+    }
+    const manifestPath = path.join(absoluteDirectory, 'package.json');
+    if (!fs.existsSync(manifestPath) || !fs.statSync(manifestPath).isFile()) {
+        throw new Error(`package-surface: package.json is missing in ${configuredDirectory}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`package-surface: invalid ${configuredDirectory}/package.json: ${error.message}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`package-surface: ${configuredDirectory}/package.json must contain an object.`);
+    }
+    return { absoluteDirectory, manifest: parsed };
+}
+function inspectTarget(packageDirectory, absoluteDirectory, target, packedFiles) {
+    if (target.target.includes('*')) {
+        return [{
+                packageDirectory,
+                field: target.field,
+                filePath: target.target,
+                message: 'wildcard manifest targets are unsupported',
+            }];
+    }
+    if (target.field.startsWith('exports') && !target.target.startsWith('./')) {
+        return [{
+                packageDirectory,
+                field: target.field,
+                filePath: target.target,
+                message: 'export target must start with ./',
+            }];
+    }
+    let absoluteTarget;
+    try {
+        absoluteTarget = resolveProjectPath(absoluteDirectory, target.target);
+    }
+    catch (error) {
+        return [{
+                packageDirectory,
+                field: target.field,
+                filePath: target.target,
+                message: error.message,
+            }];
+    }
+    const filePath = normalizePackagePath(target.target);
+    const issues = [];
+    if (!fs.existsSync(absoluteTarget) || !fs.statSync(absoluteTarget).isFile()) {
+        issues.push({
+            packageDirectory,
+            field: target.field,
+            filePath,
+            message: 'public target is missing after build',
+        });
+    }
+    if (!packedFiles.has(filePath)) {
+        issues.push({
+            packageDirectory,
+            field: target.field,
+            filePath,
+            message: 'public target is excluded from the npm package',
+        });
+    }
+    return issues;
+}
+export async function runPackageSurfaceGuard(options = {}) {
+    const rootDir = options.rootDir ?? process.cwd();
+    const config = options.config ?? await loadGuardConfig('packageSurface', rootDir);
+    const forbidden = compilePatterns(config.forbiddenPublishedPatterns);
+    const issues = [];
+    for (const packageDirectory of config.packageDirectories) {
+        const loaded = loadManifest(rootDir, packageDirectory);
+        const collected = collectManifestTargets(packageDirectory, loaded.manifest);
+        const packedFiles = readPackedFiles(loaded.absoluteDirectory, options.runPack);
+        const packedSet = new Set(packedFiles);
+        issues.push(...collected.issues);
+        for (const target of collected.targets) {
+            issues.push(...inspectTarget(packageDirectory, loaded.absoluteDirectory, target, packedSet));
+        }
+        for (const filePath of packedFiles) {
+            const index = forbidden.findIndex((pattern) => pattern.test(filePath));
+            if (index >= 0) {
+                issues.push({
+                    packageDirectory,
+                    field: 'npm pack',
+                    filePath,
+                    message: `matches forbidden pattern ${config.forbiddenPublishedPatterns[index]}`,
+                });
+            }
+        }
+    }
+    issues.sort((left, right) => ([left.packageDirectory, left.filePath, left.field, left.message].join('\0')
+        .localeCompare([right.packageDirectory, right.filePath, right.field, right.message].join('\0'))));
+    if (issues.length === 0) {
+        console.info(`Package surface is valid (${config.packageDirectories.length} packages).`);
+        return 0;
+    }
+    console.error('Package surface guard failed:');
+    for (const issue of issues) {
+        const filePath = issue.filePath ? ` ${issue.filePath}` : '';
+        console.error(`  - ${issue.packageDirectory} [${issue.field}]${filePath}: ${issue.message}`);
+    }
+    return 1;
+}
+/* v8 ignore start -- executable adapter */
+if (isMainModule(import.meta.url)) {
+    runPackageSurfaceGuard().then((code) => {
+        process.exitCode = code;
+    }).catch((error) => {
+        console.error(error.message);
+        process.exitCode = 1;
+    });
+}
+/* v8 ignore stop */

package/dist/guards/pnpm-workspace-config.d.ts

@@ -0,0 +1,2 @@
+export declare const PNPM_WORKSPACE_CONFIG_PATH: string;
+export declare function readPnpmWorkspaceOverrides(filePath?: string): Record<string, string>;

package/dist/guards/pnpm-workspace-config.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const PNPM_WORKSPACE_CONFIG_PATH = path.resolve(process.cwd(), 'pnpm-workspace.yaml');
+function unquoteYamlScalar(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith("'") && trimmed.endsWith("'")) ||
+        (trimmed.startsWith('"') && trimmed.endsWith('"'))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+export function readPnpmWorkspaceOverrides(filePath = PNPM_WORKSPACE_CONFIG_PATH) {
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.split(/\r?\n/);
+    const overrides = {};
+    let insideOverrides = false;
+    for (const line of lines) {
+        if (!insideOverrides) {
+            if (/^overrides:\s*$/.test(line)) {
+                insideOverrides = true;
+            }
+            continue;
+        }
+        if (/^\S/.test(line)) {
+            break;
+        }
+        const match = line.match(/^\s{2}([^:#][^:]*):\s*(.*?)\s*$/);
+        if (!match)
+            continue;
+        const packageName = unquoteYamlScalar(match[1]);
+        const version = unquoteYamlScalar(match[2]);
+        if (packageName && version) {
+            overrides[packageName] = version;
+        }
+    }
+    return overrides;
+}

package/dist/guards/rebuild-preflight.d.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import type { RebuildPreflightTargetConfig } from '../config.js';
+type TurboTask = {
+    task: string;
+    command: string;
+    package: string;
+    cache?: {
+        status?: string;
+    };
+};
+type TurboDryRunReport = {
+    tasks: TurboTask[];
+};
+export type RebuildPreflightReport = {
+    target: string;
+    warningTitle: string;
+    packagesNeedingRebuild: string[];
+};
+type RebuildPreflightOptions = {
+    repoRoot?: string;
+    target: string;
+};
+export declare function getTargetDefinition(target: string, targetDefinitions: Record<string, RebuildPreflightTargetConfig>): RebuildPreflightTargetConfig;
+export declare function parseTurboDryRun(stdout: string): TurboDryRunReport;
+export declare function extractPackagesNeedingRebuild(report: TurboDryRunReport, relevantBuildPackages: string[]): string[];
+export declare function getRebuildPreflightReport({ repoRoot, target, }: RebuildPreflightOptions): Promise<RebuildPreflightReport>;
+export declare function formatRebuildPreflightWarning(report: RebuildPreflightReport): string;
+export declare function printRebuildPreflightWarning(options: RebuildPreflightOptions): Promise<RebuildPreflightReport>;
+export {};