@terra-symposium/standards-quality 0.8.0 → 0.9.0

package/dist/runner.js

@@ -16,12 +16,14 @@ import { collapseInlineIfs } from './inline-if.js';
 import { collapseTypesAndObjects } from './collapse.js';
 import { deadCodeEditsIntroduceTypeErrors, deadCodeTypeProgram, fixSingleUseDeclarations, singleUseFindings } from './single-use.js';
 import { documentSrcFile, documentationFindings, duplicateImportFindings, maintainSrcFile, protectLongImports } from './documentation.js';
-import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { fixObjectForwarding, objectForwardingFindings } from './object-forwarding.js';
 import { fixRegexDedup, fixRepeatedClasses, regexFindings, repeatedClassFindings, runTailwindCanonical, uiPatternFindings } from './patterns.js';
 import { qualityProgress } from './progress.js';
+import { qualityNodeReporterOptions } from './node-reporter.js';
 import { securityFindings } from './security.js';
+import { uiComponentRecommendations } from './ui-recommendations.js';
 import { spawnSync } from 'node:child_process';
 import { srcFiles, workingSrcFiles } from './files.js';
 import { writeHistoryReport } from './history-report.js';
@@ -31,6 +33,12 @@ import { PROTECTED_IDENTIFIERS } from './naming.js';
 /*//////////////////////////////////////////////////
 REGEX
 //////////////////////////////////////////////////*/
+const BPLAYWRIGHT_B_U_REGEX = /\bplaywright\b/u;
+const BWORKSPACE_TEST_RUNNER_JS_B_U_REGEX = /\bworkspace-test-runner\.js\b/u;
+const NON_WORKSPACE_DIRS = new Set(['.git', '.next', '.nuxt', '.turbo', '.vercel', '.vite', '.astro', 'build', 'coverage', 'dist', 'node_modules', 'out', 'vendor']);
+/*//////////////////////////////////////////////////
+REGEX
+//////////////////////////////////////////////////*/
 const R_N_REGEX = /\r?\n/;
 const SHARED_REGEX = /\/\*|\/\//;
 /*//////////////////////////////////////////////////
@@ -56,6 +64,7 @@ const CLI_CMDS = new Set([
     'tailwind-canonical',
     'regex-dedup',
     'ui-patterns',
+    'ui-recommendations',
     'imports',
     'aliases',
     'forwarding',
@@ -74,11 +83,13 @@ const ESLINT_GLOB_SPECIALS = new Set(['*', '?', '[', ']', '{', '}', '(', ')', '!
 let reportStages;
 let reportStageName;
 let reportGitHubData;
+let outputPhase;
 /*//////////////////////////////////////////////////
 REGEX
 //////////////////////////////////////////////////*/
 const C_M_JS_TS_X_REGEX = /\.(?:c|m)?(?:js|ts)x?$/;
 const C_M_JS_TS_X_CLASS_2 = /\.(?:(?:c|m)?(?:js|ts)x?)$/;
+const WORKSPACE_MANIFESTS = new Map();
 const ANSI_ESCAPE = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, 'g');
 /*//////////////////////////////////////////////////
 HELPERS
@@ -235,9 +246,294 @@ function qualityHeader(name, detail) {
         reportStageName = name;
         reportStages.set(name, { name, status: 'passed', findings: 0 });
     }
+    if (outputPhase) {
+        const indent = name.startsWith('dead-code/') || (outputPhase === 'Tests' && name.startsWith('command:')) ? '    ' : '  ';
+        const labels = {
+            'dead-code/safe-fixes': 'Safe fixes',
+            'dead-code/verification': 'Verification',
+            'dead-code/knip-fix': 'Knip import-consumer scan',
+            'dead-code/eslint-fix': 'ESLint unused-declaration scan',
+            'dead-code/single-use': 'Single-use declaration/reference scan and classification',
+            'dead-code/knip': 'Knip reachability verification',
+            'dead-code': 'Dead code',
+        };
+        const label = labels[name] ?? name.replace(/^command:/u, '').replace(/(^|[-/])([a-z])/gu, (_match, separator, letter) => `${separator === '-' ? ' ' : separator}${letter.toUpperCase()}`);
+        console.error(`${indent}${label}`);
+        if (detail)
+            console.error(`${indent}  ${detail}`);
+        return;
+    }
     console.error(`\n=== ${name} ===`);
     console.error(detail);
 }
+/**
+ * Starts one fixed output phase for the full quality command.
+ *
+ * @param phase Phase heading owned by the Quality runner.
+ *
+ * @return Nothing; the heading is written once before the phase checks.
+ */
+function beginQualityPhase(phase) {
+    outputPhase = phase;
+    console.error(`\n${phase.toUpperCase()}`);
+}
+/**
+ * Finds package manifests once so filtered workspace scripts can be classified.
+ *
+ * @param root Repository root whose package scripts are selected.
+ *
+ * @return Workspace package manifests outside generated and dependency directories.
+ */
+function workspaceManifests(root) {
+    const cached = WORKSPACE_MANIFESTS.get(root);
+    if (cached)
+        return cached;
+    const manifests = [];
+    const visit = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = resolve(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!NON_WORKSPACE_DIRS.has(entry.name) && !entry.name.startsWith('.'))
+                    visit(path);
+                continue;
+            }
+            if (entry.name !== 'package.json' || !entry.isFile())
+                continue;
+            try {
+                const pkg = JSON.parse(readFileSync(path, 'utf8'));
+                manifests.push({ directory: dir, ...(typeof pkg.name === 'string' ? { name: pkg.name } : {}), scripts: pkg.scripts ?? {} });
+            }
+            catch {
+                continue;
+            }
+        }
+    };
+    visit(root);
+    WORKSPACE_MANIFESTS.set(root, manifests);
+    return manifests;
+}
+/**
+ * Finds the selected package script name without treating option values as check names.
+ *
+ * @param check Configured command whose arguments may select a package script.
+ *
+ * @return Script name for `run`, `run-script`, or a direct package-manager script command.
+ */
+function scriptNameForInvocation(check) {
+    const args = check.args ?? [];
+    const runIdx = args.findIndex((arg) => arg === 'run' || arg === 'run-script');
+    if (runIdx >= 0)
+        return args[runIdx + 1] ?? '';
+    if (!/^(?:pnpm|npm|yarn|bun)(?:\.cmd)?$/iu.test(basename(check.command)))
+        return '';
+    for (let idx = 0; idx < args.length; idx++) {
+        const arg = args[idx];
+        if (arg === '--filter') {
+            idx++;
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            if (arg === '--workspace-concurrency' || arg === '--reporter' || arg === '--dir')
+                idx++;
+            continue;
+        }
+        if (arg.startsWith('-'))
+            continue;
+        return arg;
+    }
+    return '';
+}
+/**
+ * Returns repository package filters supplied to a package-manager command.
+ *
+ * @param check Configured command whose arguments may select workspace packages.
+ *
+ * @return Explicit `--filter` selectors in argument order.
+ */
+function workspaceFilters(check) {
+    const args = check.args ?? [];
+    const selectors = [];
+    for (let idx = 0; idx < args.length; idx++) {
+        const arg = args[idx];
+        if (arg === '--filter' && args[idx + 1])
+            selectors.push(args[++idx]);
+        else if (arg.startsWith('--filter='))
+            selectors.push(arg.slice('--filter='.length));
+    }
+    return selectors;
+}
+/**
+ * Reads package scripts selected by a direct or filtered package-manager command.
+ *
+ * @param cfg Quality configuration containing the repository root.
+ * @param check Configured command whose script may identify its test runner or phase.
+ *
+ * @return Script text from the root package or selected workspace packages.
+ */
+function scriptsForInvocation(cfg, check) {
+    const scriptName = scriptNameForInvocation(check);
+    if (!scriptName)
+        return [];
+    const selectors = workspaceFilters(check);
+    const packages = selectors.length
+        ? workspaceManifests(cfg.root).filter((manifest) => selectors.some((selector) => matchesWorkspaceFilter(cfg.root, selector, manifest)))
+        : workspaceManifests(cfg.root).filter((manifest) => manifest.directory === cfg.root);
+    return packages.map((manifest) => manifest.scripts[scriptName]).filter((script) => typeof script === 'string');
+}
+/**
+ * Matches an exact workspace name or a simple repository-relative package filter.
+ *
+ * @param root Repository root that owns workspace package paths.
+ * @param selector Package name or path expression following `--filter`.
+ * @param manifest Candidate workspace package metadata.
+ *
+ * @return Whether the selector can be matched to this package without guessing.
+ */
+function matchesWorkspaceFilter(root, selector, manifest) {
+    const packageSelector = selector.replace(/^\.\.\./u, '').replace(/\.\.\.$/u, '');
+    const pathSelector = packageSelector.startsWith('.') || (!packageSelector.startsWith('@') && packageSelector.includes('/'));
+    if (!pathSelector)
+        return manifest.name === packageSelector;
+    const norm = packageSelector.replace(/^\.\//u, '').replace(/\*.*$/u, '').replace(/\/$/u, '');
+    const packagePath = resolve(root, norm || '.');
+    const hasGlob = /[*?{[]/u.test(packageSelector);
+    if (!hasGlob)
+        return manifest.directory === packagePath;
+    const relativePackage = relative(packagePath, manifest.directory);
+    if (relativePackage === '..' || relativePackage.startsWith(`..${sep}`) || isAbsolute(relativePackage))
+        return false;
+    if (packageSelector.includes('**'))
+        return true;
+    return !relativePackage.includes(sep);
+}
+/**
+ * Reads one display string for the command and its selected package script.
+ *
+ * @param cfg Quality configuration containing the repository root.
+ * @param check Configured command to describe.
+ *
+ * @return Lowercase command and script text; free-form argument values are excluded.
+ */
+function invocationText(cfg, check) {
+    return `${check.name} ${check.command} ${scriptNameForInvocation(check)} ${scriptsForInvocation(cfg, check).join(' ')}`.toLowerCase();
+}
+/**
+ * Identifies test commands without adding grouping metadata to quality.json.
+ *
+ * @param cfg Quality configuration containing repository commands.
+ * @param check Configured command to classify.
+ *
+ * @return Whether the command selects a test suite.
+ */
+function isTestInvocation(cfg, check) {
+    return (testRunner(cfg, check) !== 'unknown' ||
+        /\b(?:test|tests|spec|specs|playwright|vitest|jest|mocha|e2e|contract|integration)\b/u.test(invocationText(cfg, check)) ||
+        (check.args ?? []).some((arg) => arg === '--test' || arg.startsWith('--test=')));
+}
+/**
+ * Assigns a configured command to the fixed runner phase order.
+ *
+ * @param cfg Quality configuration containing repository commands.
+ * @param check Configured command to classify.
+ *
+ * @return The output and execution phase selected by Terra Quality.
+ */
+function phaseForInvocation(cfg, check) {
+    const text = invocationText(cfg, check);
+    if (isTestInvocation(cfg, check))
+        return 'Tests';
+    if (/\b(?:format|prettier)\b/u.test(text))
+        return 'Format';
+    if (/\b(?:typecheck|type-check|types|tsc|astro\s+check)\b/u.test(text))
+        return 'Framework / type checks';
+    if (/\b(?:build|compile|bundle)\b/u.test(text))
+        return 'Build';
+    if (/\b(?:github|diff|repository-health|repo-health)\b/u.test(text))
+        return 'Repository health';
+    return 'Static quality';
+}
+/**
+ * Groups selected tests by the kind of boundary they exercise.
+ *
+ * @param cfg Quality configuration containing repository commands.
+ * @param check Configured test command to classify.
+ *
+ * @return Stable display category for the test suite.
+ */
+function testGroup(cfg, check) {
+    const text = invocationText(cfg, check);
+    if (testRunner(cfg, check) === 'playwright' || /\b(?:playwright|browser|e2e|visual|cloud)\b/u.test(text))
+        return 'Browser / Cloud';
+    if (/\b(?:integration|database|postgres|neon|http|api)\b/u.test(text))
+        return 'Integration';
+    if (/\b(?:unit|contract)\b/u.test(text))
+        return 'Unit / Contract';
+    return 'Other tests';
+}
+/**
+ * Identifies the runner family for configured test-command reporting.
+ *
+ * @param cfg Quality configuration containing repository commands.
+ * @param check Configured test command to classify.
+ *
+ * @return Node, Playwright, or unknown when the runner cannot be inferred safely.
+ */
+function testRunner(cfg, check) {
+    const text = invocationText(cfg, check);
+    const args = check.args ?? [];
+    if (BPLAYWRIGHT_B_U_REGEX.test(text) || /\bplaywright\b/iu.test(args.join(' ')))
+        return 'playwright';
+    const nodeCmd = /^(?:node|node\.exe)$/iu.test(basename(check.command));
+    const nodeTestArgs = args.some((arg) => arg === '--test' || arg.startsWith('--test=')) || args.some((arg) => /\.(?:mjs|cjs)$/iu.test(arg));
+    if ((nodeCmd && nodeTestArgs) || BWORKSPACE_TEST_RUNNER_JS_B_U_REGEX.test(text) || /\bnode\s+[^\n]*--test\b/u.test(text) || /\bpnpm\s+-r\s+test\b/u.test(text))
+        return 'node';
+    return 'unknown';
+}
+/**
+ * Removes configured Node test reporters so the shared reporter remains authoritative.
+ *
+ * @param args Selected Node or package-manager arguments.
+ *
+ * @return Arguments without CLI reporter selections or their destination values.
+ */
+function withoutNodeReporterArgs(args) {
+    const retained = [];
+    for (let idx = 0; idx < args.length; idx++) {
+        const arg = args[idx];
+        if (arg === '--test-reporter' || arg === '--test-reporter-destination') {
+            idx++;
+            continue;
+        }
+        if (arg.startsWith('--test-reporter=') || arg.startsWith('--test-reporter-destination='))
+            continue;
+        retained.push(arg);
+    }
+    return retained;
+}
+/**
+ * Removes duplicate configured test invocations while preserving the first selected name.
+ *
+ * @param checks Configured commands in their source order.
+ *
+ * @return Commands with repeated executable-and-argument vectors removed.
+ */
+function uniqueTestSuites(checks) {
+    const seen = new Set();
+    return checks.filter((check) => {
+        const key = JSON.stringify([check.command, check.args ?? []]);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
 /**
  * Converts tool output into compact single-line messages without terminal control codes.
  *
@@ -290,6 +586,143 @@ function run(cfg, cmd, args, opts = {}) {
         console.error(`  ${cmd} failed: ${result.error.message}`);
     return result.status ?? 1;
 }
+/**
+ * Runs one selected test command with shared case reporting when its runner is known.
+ *
+ * @param cfg Quality configuration defining the repository root.
+ * @param check Test command selected by quality.json.
+ * @param completed One-based completed-suite count.
+ * @param total Number of selected, deduplicated suites.
+ * @param lastGroup Previously printed test category, if any.
+ *
+ * @return Updated group label and the command exit status.
+ */
+function runTestSuite(cfg, check, completed, total, lastGroup) {
+    const group = testGroup(cfg, check);
+    if (group !== lastGroup)
+        console.error(`\n  ${group}`);
+    const runner = testRunner(cfg, check);
+    const args = [...(check.args ?? [])];
+    const env = { ...process.env };
+    let inheritOutput = runner !== 'unknown';
+    if (runner === 'node') {
+        const reporterUrl = new URL('./node-reporter.js', import.meta.url).href;
+        env.NODE_OPTIONS = qualityNodeReporterOptions(env.NODE_OPTIONS, reporterUrl);
+        env.TERRA_QUALITY_NODE_REPORTER_OWNER = '1';
+        args.splice(0, args.length, ...withoutNodeReporterArgs(args));
+    }
+    else if (runner === 'playwright') {
+        const reporterPath = resolve(dirname(fileURLToPath(import.meta.url)), 'playwright-reporter.js');
+        const reporterArg = `--reporter=${reporterPath}`;
+        const selectedArgs = [];
+        for (let idx = 0; idx < args.length; idx++) {
+            const arg = args[idx];
+            if (arg === '--reporter') {
+                idx++;
+                continue;
+            }
+            if (!arg.startsWith('--reporter='))
+                selectedArgs.push(arg);
+        }
+        args.splice(0, args.length, ...selectedArgs);
+        const packageScript = /\b(?:pnpm|npm|yarn)\b/u.test(check.command) && args.some((arg) => arg === 'run' || arg === 'run-script');
+        if (packageScript) {
+            if (!args.includes('--'))
+                args.push('--');
+            args.push(reporterArg);
+        }
+        else {
+            const separator = args.indexOf('--');
+            if (separator < 0)
+                args.push(reporterArg);
+            else
+                args.splice(separator, 0, reporterArg);
+        }
+    }
+    else {
+        inheritOutput = false;
+    }
+    qualityHeader(`command:${check.name}`, `Running ${check.command} ${(check.args ?? []).join(' ')}`.trim());
+    const result = spawnSync(check.command, args, { cwd: cfg.root, stdio: inheritOutput ? 'inherit' : ['inherit', 'pipe', 'pipe'], env, maxBuffer: TOOL_OUTPUT_MAX_BUFFER });
+    if (!inheritOutput) {
+        printChildOutput(result.stdout);
+        printChildOutput(result.stderr);
+    }
+    if (result.error)
+        console.error(`    ${check.command} failed: ${result.error.message}`);
+    const status = result.status ?? 1;
+    if (reportStages && reportStageName) {
+        const stage = reportStages.get(reportStageName);
+        if (stage && status)
+            stage.status = 'failed';
+    }
+    if (status)
+        process.exitCode = status;
+    console.error(`  ${status ? '✗ failed' : '✓ passed'}`);
+    qualityProgress('Test suites', completed, total);
+    return { group, status };
+}
+/**
+ * Runs configured checks assigned to one fixed phase.
+ *
+ * @param cfg Quality configuration containing selected repository commands.
+ * @param phase Fixed Quality runner phase to execute.
+ *
+ * @return Number of commands that failed in this phase.
+ */
+function runQualityPhase(cfg, phase) {
+    const cmds = (cfg.qualityCommands ?? []).filter((check) => qualityCmdEnabled(cfg, check.name) && phaseForInvocation(cfg, check) === phase);
+    let failures = 0;
+    let lastGroup;
+    if (phase === 'Tests') {
+        const suites = uniqueTestSuites(cmds);
+        if (!suites.length) {
+            console.error('  No configured test suites.');
+            return 0;
+        }
+        const groupOrder = ['Unit / Contract', 'Integration', 'Browser / Cloud', 'Other tests'];
+        suites.sort((left, right) => groupOrder.indexOf(testGroup(cfg, left)) - groupOrder.indexOf(testGroup(cfg, right)));
+        qualityProgress('Test suites', 0, suites.length);
+        console.error('');
+        for (const [idx, check] of suites.entries()) {
+            const result = runTestSuite(cfg, check, idx + 1, suites.length, lastGroup);
+            lastGroup = result.group;
+            if (result.status)
+                failures += 1;
+        }
+        return failures;
+    }
+    for (const check of cmds) {
+        qualityHeader(`command:${check.name}`, `Running ${check.command} ${(check.args ?? []).join(' ')}`.trim());
+        const status = run(cfg, check.command, check.args ?? []);
+        if (status) {
+            failures += 1;
+            process.exitCode = status;
+        }
+        console.error(`  ${status ? '✗ failed' : '✓ passed'}`);
+    }
+    return failures;
+}
+/**
+ * Identifies an exact configured Git whitespace check.
+ *
+ * @param check Configured repository-health command.
+ *
+ * @return Whether the invocation duplicates the built-in `git diff --check`.
+ */
+function isGitDiffCheck(check) {
+    return basename(check.command).toLowerCase() === 'git' && check.args?.length === 2 && check.args[0] === 'diff' && check.args[1] === '--check';
+}
+/**
+ * Detects whether an enabled repository-health command already performs Git's diff check.
+ *
+ * @param cfg Normalized repository configuration.
+ *
+ * @return Whether a selected exact Git diff check is present.
+ */
+function hasCfgdGitDiffCheck(cfg) {
+    return (cfg.qualityCommands ?? []).some((check) => qualityCmdEnabled(cfg, check.name) && isGitDiffCheck(check));
+}
 /**
  * Captures source text so automatic tools can report changed-file counts without
  * replaying their successful per-file output.
@@ -823,18 +1256,6 @@ function runCfgdCmd(cfg, name) {
         process.exitCode = status;
     console.error(`  ${status ? '✗ failed' : '✓ passed'}`);
 }
-/**
- * Runs every enabled configured quality command once.
- *
- * @param cfg Quality configuration containing repository commands.
- *
- * @return Nothing; command failures are reflected in the process exit code.
- */
-function runCfgdCmds(cfg) {
-    for (const check of cfg.qualityCommands ?? [])
-        if (qualityCmdEnabled(cfg, check.name))
-            runCfgdCmd(cfg, check.name);
-}
 /**
  * Runs configured advisory checks after Knip without turning recommendations into failures.
  *
@@ -1383,7 +1804,7 @@ function printDeadCodeFindings(findings, manualWarnings, typeSafetyVerified = tr
     const errs = findings.filter((finding) => finding.severity === 'error' || manualWarnings === 'error');
     const warnings = findings.filter((finding) => finding.severity === 'warning' && manualWarnings !== 'error');
     const manualCount = findings.filter((finding) => finding.severity === 'warning').length;
-    for (const finding of findings) {
+    for (const finding of [...findings].sort((left, right) => left.file.localeCompare(right.file) || left.line - right.line || left.rule.localeCompare(right.rule) || left.name.localeCompare(right.name))) {
         const severity = finding.severity === 'warning' && manualWarnings === 'error' ? 'ERROR' : finding.severity.toUpperCase();
         console.error(`  - [${severity}] ${finding.rule}: ${finding.file}:${finding.line} ${finding.name}`);
         console.error(`      Reason: ${finding.reason}`);
@@ -1393,7 +1814,7 @@ function printDeadCodeFindings(findings, manualWarnings, typeSafetyVerified = tr
     }
     console.error(`  ${errs.length} error${errs.length === 1 ? '' : 's'}; ${manualCount} manual finding${manualCount === 1 ? '' : 's'}${manualWarnings === 'warning' ? ` (${warnings.length} warning${warnings.length === 1 ? '' : 's'})` : ''}.`);
     if (manualWarnings === 'error' && manualCount > 0)
-        console.error('  Manual findings block quality by default. Fix each finding one by one, rerun quality, and continue only when all are resolved before committing.');
+        console.error('  Resolve each manual finding one by one, in the order listed, before committing.');
     if (errs.length)
         process.exitCode = 1;
 }
@@ -1411,6 +1832,14 @@ function printDeadCodeFindings(findings, manualWarnings, typeSafetyVerified = tr
 function runDeadCode(cfg, fix, all, verify = true, emit = true) {
     if (emit)
         qualityHeader('dead-code', `${fix ? 'Fixing safe cases and checking' : 'Read-only check of'} unused files, exports, declarations, and single-use code`);
+    let verificationStarted = false;
+    const beginVerification = () => {
+        if (verificationStarted)
+            return;
+        verificationStarted = true;
+        if (emit)
+            qualityHeader('dead-code/verification', 'Verify remaining unused files, exports, declarations, and single-use code');
+    };
     const changedFiles = new Set();
     const srcSnapshot = fix ? new Map(filesFor(cfg, true).map((f) => [f, readFileSync(f, 'utf8')])) : new Map();
     const initialInventory = fix ? new Set(srcSnapshot.keys()) : new Set();
@@ -1420,6 +1849,7 @@ function runDeadCode(cfg, fix, all, verify = true, emit = true) {
     if (fix && emit)
         console.error('  TypeScript baseline ready.');
     const typeRejectedFiles = new Set();
+    const singleUseVerificationFindings = [];
     const eslintReportsByPath = new Map();
     const eslintScannedContents = new Map();
     let importedConsumersForRun;
@@ -1437,6 +1867,8 @@ function runDeadCode(cfg, fix, all, verify = true, emit = true) {
         return dirtyFiles.length ? scanEslint(dirtyFiles) : [];
     };
     if (fix) {
+        if (emit)
+            qualityHeader('dead-code/safe-fixes', 'Apply only mechanically proven fixes');
         if (qualityCheckEnabled(cfg, 'knip')) {
             if (emit)
                 qualityHeader('dead-code/knip-fix', 'Removing only unambiguous unused export modifiers');
@@ -1445,7 +1877,7 @@ function runDeadCode(cfg, fix, all, verify = true, emit = true) {
         importedConsumersForRun = qualityCheckEnabled(cfg, 'knip') || qualityCheckEnabled(cfg, 'lint') ? importedExportConsumers(cfg) : undefined;
         if (qualityCheckEnabled(cfg, 'lint')) {
             if (emit)
-                console.error('  Scanning configured files for safe unused-declaration fixes...');
+                qualityHeader('dead-code/eslint-fix', 'Scan configured files and apply only safe unused-declaration fixes');
             let reportsToFix = scanEslint();
             for (let round = 0; round < 5; round++) {
                 if (!reportsToFix.some((report) => report.messages.some((message) => message.ruleId === 'unused-imports/no-unused-vars')))
@@ -1461,12 +1893,12 @@ function runDeadCode(cfg, fix, all, verify = true, emit = true) {
             }
         }
         if (emit)
-            console.error('  Checking and inlining safe single-use declarations...');
+            qualityHeader('dead-code/single-use', 'Scan declarations and references, classify candidates, and inline only proven cases');
         const singleUseChangedFiles = new Set();
         fixSingleUseDeclarations(cfg, singleUseChangedFiles, (pass, filesChanged) => {
             if (emit)
                 console.error(`  Single-use rewrite pass ${pass} starting (${filesChanged} source files changed so far).`);
-        });
+        }, singleUseVerificationFindings);
         for (const file of singleUseChangedFiles)
             changedFiles.add(file);
         const currInventory = new Set(filesFor(cfg, true));
@@ -1484,6 +1916,8 @@ function runDeadCode(cfg, fix, all, verify = true, emit = true) {
             if (curr !== original)
                 proposed.set(file, curr);
         }
+        if (verify)
+            beginVerification();
         if (proposed.size) {
             if (!typeProgram)
                 throw new Error('Dead-code edit validation requires its baseline TypeScript program.');
@@ -1504,11 +1938,14 @@ function runDeadCode(cfg, fix, all, verify = true, emit = true) {
                 if (readFileSync(file, 'utf8') !== text)
                     writeFileSync(file, text);
         }
+        if (verify)
+            beginVerification();
         if (qualityCheckEnabled(cfg, 'lint'))
             scanDirtyEslintFiles();
     }
     if (!verify)
         return [];
+    beginVerification();
     const findings = [];
     if (qualityCheckEnabled(cfg, 'knip')) {
         if (emit)
@@ -1520,7 +1957,8 @@ function runDeadCode(cfg, fix, all, verify = true, emit = true) {
             scanEslint();
         findings.push(...unusedDeclarationFindings(cfg, [...eslintReportsByPath.values()]));
     }
-    for (const single of singleUseFindings(cfg))
+    const finalSingleUseFindings = fix && !typeRejectedFiles.size ? singleUseVerificationFindings : singleUseFindings(cfg);
+    for (const single of finalSingleUseFindings)
         findings.push({
             rule: 'typescript/single-use',
             file: single.file,
@@ -2030,8 +2468,14 @@ export function runQuality(cfg, strict = false, all = true, analysis) {
     const duplicateImports = qualityCheckEnabled(cfg, 'import') ? duplicateImportFindings(ctx.files) : [];
     if (qualityCheckEnabled(cfg, 'import')) {
         qualityHeader('imports', 'Checking local import resolution');
-        printFindings(result.imports, (f) => `Unresolved import: ${f.importer} -> ${f.specifier}`);
-        printFindings(duplicateImports, (f) => `Duplicate named import: ${f.file}:${f.line} repeats an import from ${f.module}`);
+        if (!result.imports.length && !duplicateImports.length)
+            console.error('  ✓ clean');
+        else {
+            if (result.imports.length)
+                printFindings(result.imports, (f) => `Unresolved import: ${f.importer} -> ${f.specifier}`);
+            if (duplicateImports.length)
+                printFindings(duplicateImports, (f) => `Duplicate named import: ${f.file}:${f.line} repeats an import from ${f.module}`);
+        }
     }
     if (qualityCheckEnabled(cfg, 'name')) {
         qualityHeader('naming', 'Checking concise, consistent symbol names');
@@ -2170,6 +2614,107 @@ export function runQualityCli(cfg, args = process.argv.slice(2)) {
     }
     writeReport();
 }
+/**
+ * Runs the full quality matrix in package-owned phase order.
+ *
+ * @param cfg Normalized repository configuration.
+ * @param args Validated command arguments.
+ * @param opts Scope and write controls parsed by the CLI.
+ *
+ * @return A promise only when the asynchronous Tailwind check is selected.
+ */
+function runFullQuality(cfg, args, opts) {
+    const fix = (check) => qualityAutofixEnabled(cfg, check, opts.fix);
+    const scoped = scopedCfg(cfg, opts.all);
+    if (opts.fix) {
+        outputPhase = 'PREPARING SAFE FIXES';
+        console.error('\nPREPARING SAFE FIXES');
+    }
+    if (opts.fix && qualityCheckEnabled(cfg, 'name') && fix('name')) {
+        const namingScope = scopedCfg(cfg, opts.all);
+        if (namingFindings(namingScope).length)
+            fixNames(cfg, opts.all);
+    }
+    if (fix('forward') && qualityCheckEnabled(cfg, 'forward')) {
+        const result = fixObjectForwarding(scoped);
+        if (result.fixed || result.skipped)
+            console.info(`Forwarding fixer: ${result.fixed} exact duplicates removed${result.skipped ? `; ${result.skipped} advisory cases retained` : ''}.`);
+    }
+    if (fix('repeatedClasses') && qualityCheckEnabled(cfg, 'repeated-classes')) {
+        const result = fixRepeatedClasses(scoped);
+        if (result.fixed || result.skipped)
+            console.info(`Class fixer: ${result.fixed} attributes replaced${result.skipped ? `; ${result.skipped} advisory cases retained` : ''}.`);
+    }
+    if (fix('regexDedup') && qualityCheckEnabled(cfg, 'regex-dedup')) {
+        const result = fixRegexDedup(scoped);
+        if (result.fixed || result.skipped)
+            console.info(`Regex fixer: ${result.fixed} literals replaced${result.skipped ? `; ${result.skipped} advisory cases retained` : ''}.`);
+    }
+    if (fix('lint') && qualityCheckEnabled(cfg, 'lint'))
+        runLint(cfg, { ...opts, fix: true }, true, true);
+    if (opts.fix && qualityCheckEnabled(cfg, 'alias'))
+        aliasFindings(scoped, true);
+    if (qualityCheckEnabled(cfg, 'document')) {
+        const documentationIssues = documentationFindings(scopedCfg(cfg, opts.all)).filter((finding) => finding.severity === 'error');
+        if (documentationIssues.length)
+            runDocumentation(cfg, opts, ['document', ...new Set(documentationIssues.map((finding) => resolve(cfg.root, finding.file))), '--quiet'], true);
+    }
+    if (opts.fix && qualityCheckEnabled(cfg, 'import') && qualityAutofixEnabled(cfg, 'document', opts.fix)) {
+        const repeated = duplicateImportFindings(filesFor(cfg, opts.all));
+        for (const file of new Set(repeated.map((finding) => finding.file)))
+            maintainSrcFile(cfg.root, file);
+    }
+    outputPhase = undefined;
+    beginQualityPhase('Format');
+    if (qualityCheckEnabled(cfg, 'format'))
+        runFormatter(cfg, { ...opts, fix: fix('format') }, opts.all ? [] : filesFor(cfg, false));
+    if (!opts.skipCommands)
+        runQualityPhase(cfg, 'Format');
+    beginQualityPhase('Static quality');
+    const continueStaticAndLater = () => {
+        if (qualityCheckEnabled(cfg, 'dead-code'))
+            runDeadCodeCmd(cfg, qualityAutofixEnabled(cfg, 'dead-code', opts.fix), opts.all);
+        if (qualityCheckEnabled(cfg, 'lint'))
+            runLint(cfg, { ...opts, fix: false }, true, true);
+        const analysis = createQualityAnalysis(scoped);
+        runGenericChecks(scoped, analysis);
+        runQuality(cfg, opts.strict, opts.all, analysis);
+        if (!opts.skipCommands)
+            runQualityPhase(cfg, 'Static quality');
+        if (!opts.skipRecommendations)
+            runRecommendationCmds(cfg);
+        beginQualityPhase('Tests');
+        const testFailures = opts.skipCommands ? 0 : runQualityPhase(cfg, 'Tests');
+        const testSuites = opts.skipCommands ? 0 : uniqueTestSuites((cfg.qualityCommands ?? []).filter((check) => qualityCmdEnabled(cfg, check.name) && phaseForInvocation(cfg, check) === 'Tests')).length;
+        beginQualityPhase('Framework / type checks');
+        if (qualityCheckEnabled(cfg, 'type') && (cfg.tools?.tsc || cfg.typecheckCommand)) {
+            runTypecheck(cfg);
+            if (cfg.typecheckExtensions?.length && !cfg.typecheckRoots?.length && !cfg.typecheckCommand)
+                runProjectTypecheck(cfg);
+        }
+        if (!opts.skipCommands)
+            runQualityPhase(cfg, 'Framework / type checks');
+        beginQualityPhase('Build');
+        if (!opts.skipCommands)
+            runQualityPhase(cfg, 'Build');
+        beginQualityPhase('Repository health');
+        if (!opts.skipCommands)
+            runQualityPhase(cfg, 'Repository health');
+        if (qualityCheckEnabled(cfg, 'diff') && !hasCfgdGitDiffCheck(cfg))
+            runDiffCheck(cfg);
+        if (qualityCheckEnabled(cfg, 'github') && cfg.github?.repositories?.length)
+            runGitHubCheck(cfg, [], false, args.includes('--warn'));
+        console.error(`\nSUMMARY checks complete · ${testSuites} suites · ${testFailures} failed ${testFailures === 1 ? 'suite' : 'suites'} · ${process.exitCode ? 'checks failed' : 'all checks passed'}`);
+        outputPhase = undefined;
+    };
+    if (cfg.tailwindCanonical && qualityCheckEnabled(cfg, 'tailwind-canonical'))
+        return runTailwindCanonicalCheck(cfg, fix('tailwindCanonical')).then(continueStaticAndLater, (error) => {
+            process.exitCode = 1;
+            console.error(`  Tailwind canonical check failed: ${error instanceof Error ? error.message : String(error)}`);
+            continueStaticAndLater();
+        });
+    continueStaticAndLater();
+}
 /**
  * Route validated arguments to the requested quality command.
  *
@@ -2187,7 +2732,7 @@ function dispatchQualityCli(cfg, args) {
     }
     if (args.includes('--help') || args.includes('-h')) {
         console.info('Usage: terra-quality <command> [options]');
-        console.info('Commands include quality, history, github, document, format, lint, knip, types, single-use, dead-code, tailwind-canonical, security, and domain.');
+        console.info('Commands include quality, history, github, document, format, lint, knip, types, single-use, dead-code, tailwind-canonical, security, ui-recommendations, and domain.');
         console.info('Options: --all, --warn, --strict, --skip-commands, --skip-recommendations, --report-json <path>, --repository owner/name; history also accepts --branch <name> and --base-sha <sha>.');
         return;
     }
@@ -2200,7 +2745,10 @@ function dispatchQualityCli(cfg, args) {
         skipRecommendations: args.includes('--skip-recommendations'),
     };
     const fix = (check) => qualityAutofixEnabled(cfg, check, opts.fix);
-    if (cfg.tailwindCanonical && qualityCheckEnabled(cfg, 'tailwind-canonical') && ['quality', 'quality:all', 'quality:baseline', 'imports', 'quality:patterns', 'types:architecture'].includes(cmd))
+    if (cfg.tailwindCanonical &&
+        qualityCheckEnabled(cfg, 'tailwind-canonical') &&
+        !['quality', 'quality:all', 'quality:baseline'].includes(cmd) &&
+        ['imports', 'quality:patterns', 'types:architecture'].includes(cmd))
         return runTailwindCanonicalCheck(cfg, fix('tailwindCanonical')).then(() => {
             const checks = { ...cfg.enabledChecks, 'tailwind-canonical': false };
             return dispatchQualityCli({ ...cfg, enabledChecks: checks }, args);
@@ -2285,6 +2833,13 @@ function dispatchQualityCli(cfg, args) {
             process.exitCode = 1;
         return;
     }
+    if (cmd === 'ui-recommendations') {
+        const findings = uiComponentRecommendations(cfg);
+        console.info(`UI component recommendations (${findings.length})`);
+        for (const finding of findings)
+            console.info(`  ${finding.file}:${finding.line}:${finding.column} <${finding.element}> → <${finding.component}> (import from '${finding.import}') — ${finding.reason}`);
+        return;
+    }
     if (cfg.qualityCommands?.some((c) => c.name === cmd)) {
         runCfgdCmd(cfg, cmd);
         return;
@@ -2307,69 +2862,8 @@ function dispatchQualityCli(cfg, args) {
         runQuality(cfg, opts.strict, opts.all);
         return;
     }
-    if (cmd === 'quality' || cmd === 'quality:all' || cmd === 'quality:baseline') {
-        if (opts.fix && qualityCheckEnabled(cfg, 'alias'))
-            aliasFindings(cfg, true);
-        if (fix('name') && qualityCheckEnabled(cfg, 'name')) {
-            const namingScope = scopedCfg(cfg, opts.all);
-            if (namingFindings(namingScope).length)
-                fixNames(cfg, opts.all);
-        }
-        const scoped = scopedCfg(cfg, opts.all);
-        if (fix('forward') && qualityCheckEnabled(cfg, 'forward')) {
-            const result = fixObjectForwarding(scoped);
-            if (result.fixed || result.skipped)
-                console.info(`Forwarding fixer: ${result.fixed} exact duplicates removed${result.skipped ? `; ${result.skipped} advisory cases retained` : ''}.`);
-        }
-        if (fix('repeatedClasses') && qualityCheckEnabled(cfg, 'repeated-classes')) {
-            const result = fixRepeatedClasses(scoped);
-            if (result.fixed || result.skipped)
-                console.info(`Class fixer: ${result.fixed} attributes replaced${result.skipped ? `; ${result.skipped} advisory cases retained` : ''}.`);
-        }
-        if (fix('regexDedup') && qualityCheckEnabled(cfg, 'regex-dedup')) {
-            const result = fixRegexDedup(scoped);
-            if (result.fixed || result.skipped)
-                console.info(`Regex fixer: ${result.fixed} literals replaced${result.skipped ? `; ${result.skipped} advisory cases retained` : ''}.`);
-        }
-        if (fix('lint') && qualityCheckEnabled(cfg, 'lint'))
-            runLint(cfg, { ...opts, fix: true }, true, true);
-        if (qualityCheckEnabled(cfg, 'document')) {
-            const documentationIssues = documentationFindings(scopedCfg(cfg, opts.all)).filter((f) => f.severity === 'error');
-            if (documentationIssues.length)
-                runDocumentation(cfg, opts, ['document', ...new Set(documentationIssues.map((f) => resolve(cfg.root, f.file))), '--quiet'], true);
-        }
-        if (fix('format') && qualityCheckEnabled(cfg, 'format'))
-            runFormatter(cfg, { ...opts, fix: true }, opts.all ? [] : filesFor(cfg, false));
-        if (opts.fix && qualityCheckEnabled(cfg, 'alias'))
-            aliasFindings(scoped, true);
-        if (qualityCheckEnabled(cfg, 'dead-code'))
-            runDeadCodeCmd(cfg, qualityAutofixEnabled(cfg, 'dead-code', opts.fix), opts.all);
-        if (qualityCheckEnabled(cfg, 'lint'))
-            runLint(cfg, { ...opts, fix: false }, true, true);
-        const analysis = createQualityAnalysis(scoped);
-        runGenericChecks(scoped, analysis);
-        if (qualityCheckEnabled(cfg, 'type') && cfg.tools?.tsc) {
-            runTypecheck(cfg);
-            if (cfg.typecheckExtensions?.length && !cfg.typecheckRoots?.length)
-                runProjectTypecheck(cfg);
-        }
-        if (!opts.skipCommands)
-            runCfgdCmds(cfg);
-        if (!opts.skipRecommendations)
-            runRecommendationCmds(cfg);
-        if (opts.fix && qualityCheckEnabled(cfg, 'import') && qualityAutofixEnabled(cfg, 'document', opts.fix)) {
-            const repeated = duplicateImportFindings(filesFor(cfg, opts.all));
-            for (const file of new Set(repeated.map((finding) => finding.file)))
-                maintainSrcFile(cfg.root, file);
-        }
-        runQuality(cfg, opts.strict, opts.all, analysis);
-        if (qualityCheckEnabled(cfg, 'diff'))
-            runDiffCheck(cfg);
-        if (opts.fix && qualityCheckEnabled(cfg, 'diff'))
-            runDiffCheck(cfg);
-        if (qualityCheckEnabled(cfg, 'github') && cfg.github?.repositories?.length)
-            runGitHubCheck(cfg, [], false, args.includes('--warn'));
-    }
+    if (cmd === 'quality' || cmd === 'quality:all' || cmd === 'quality:baseline')
+        return runFullQuality(cfg, args, opts);
 }
 /**
  * Loads the repository configuration and runs the CLI in one boundary call.