@terra-symposium/standards-quality 0.5.0 → 0.7.0

package/dist/runner.js

@@ -10,16 +10,16 @@ IMPORTS
 import ts from 'typescript';
 import { aliasFindings, declarationScope, isCallbackDeclaration, isProtectedPath, isRenamableDeclaration, namingFindings, renameDeclaration, renameId } from './naming.js';
 import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { buildGitHubReport, formatGitHubReport, hasGitHubAuth } from './github-report.js';
 import { checkImports } from './imports.js';
 import { collapseInlineIfs } from './inline-if.js';
 import { collapseTypesAndObjects } from './collapse.js';
-import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 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 { fileURLToPath } from 'node:url';
-import { buildGitHubReport, formatGitHubReport, hasGitHubAuth } from './github-report.js';
 import { fixObjectForwarding, objectForwardingFindings } from './object-forwarding.js';
-import { fixRegexDedup, fixRepeatedClasses, regexFindings, repeatedClassFindings, uiPatternFindings } from './patterns.js';
+import { fixRegexDedup, fixRepeatedClasses, regexFindings, repeatedClassFindings, runTailwindCanonical, uiPatternFindings } from './patterns.js';
 import { qualityProgress } from './progress.js';
 import { securityFindings } from './security.js';
 import { spawnSync } from 'node:child_process';
@@ -53,6 +53,7 @@ const CLI_CMDS = new Set([
     'dead-code',
     'security',
     'repeated-classes',
+    'tailwind-canonical',
     'regex-dedup',
     'ui-patterns',
     'imports',
@@ -190,6 +191,7 @@ export function createQualityCfg(cfg) {
     const defaultSkipped = ['.git', 'node_modules', 'dist', 'build', 'coverage', 'test-results', '.next', '.astro', '.sanity', '.netlify', '.cache', '.output', '.vercel', '.nuxt', '.husky'];
     return {
         ...cfg,
+        manualWarnings: cfg.manualWarnings ?? 'error',
         renameExports: cfg.renameExports ?? false,
         root: resolve(cfg.root),
         sourceRoots: cfg.sourceRoots.map((p) => resolve(cfg.root, p)),
@@ -564,12 +566,10 @@ function focusedEslintCfgSrc(cfg, flatCfg, files) {
     return `
 import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
-
 const root = ${JSON.stringify(cfg.root)};
 const configPath = ${JSON.stringify(flatCfg)};
 const sourceFiles = ${JSON.stringify(files)};
 const filePatterns = ${JSON.stringify(patterns)};
-
 try {
 	const requireFromRepo = createRequire(resolve(root, 'package.json'));
 	const { ESLint } = requireFromRepo('eslint');
@@ -1040,10 +1040,13 @@ function assertKnipPath(cfg, path, label) {
         throw new Error(`Knip returned a ${label} symlink outside the repository: ${path}`);
     return absolute;
 }
-/** Converts Knip's validated issue inventory into dead-code review findings.
+/**
+ * Converts Knip's validated issue inventory into dead-code review findings.
+ *
  * @param cfg Quality configuration defining scope and explicit entry-point contracts.
  * @param importedConsumers Export names referenced by configured source files.
- * @returns Knip findings with safe export-modifier changes marked autofixable.
+ *
+ * @return Knip findings with safe export-modifier changes marked autofixable.
  */
 function collectKnipFindings(cfg, importedConsumers = importedExportConsumers(cfg)) {
     const issues = readKnipIssues(cfg);
@@ -1078,11 +1081,14 @@ function collectKnipFindings(cfg, importedConsumers = importedExportConsumers(cf
     }
     return findings;
 }
-/** Checks whether a name is a configured framework-discovered route export.
+/**
+ * Checks whether a name is a configured framework-discovered route export.
+ *
  * @param cfg Quality configuration containing framework entry exports.
  * @param file Repository-relative source filename reported by Knip.
  * @param name Exported identifier to check.
- * @returns Whether the configured file or supported TypeScript route pattern includes the export.
+ *
+ * @return Whether the configured file or supported TypeScript route pattern includes the export.
  */
 function isFrameworkEntryExport(cfg, file, name) {
     const publicRoute = !basename(file).startsWith('_');
@@ -1093,9 +1099,12 @@ function isFrameworkEntryExport(cfg, file, name) {
         return pathMatches && names.includes(name);
     });
 }
-/** Selects the TypeScript parser mode from a source filename's extension.
+/**
+ * Selects the TypeScript parser mode from a source filename's extension.
+ *
  * @param file Source filename to classify.
- * @returns The JavaScript, JSX, TypeScript, or TSX compiler script kind.
+ *
+ * @return The JavaScript, JSX, TypeScript, or TSX compiler script kind.
  */
 function deadCodeScriptKind(file) {
     if (/\.tsx$/i.test(file))
@@ -1106,10 +1115,13 @@ function deadCodeScriptKind(file) {
         return ts.ScriptKind.JS;
     return ts.ScriptKind.TS;
 }
-/** Checks whether Knip identified a direct named export that can become private.
+/**
+ * Checks whether Knip identified a direct named export that can become private.
+ *
  * @param file Absolute source filename containing the export.
  * @param name Exported identifier reported by Knip.
- * @returns Whether the export modifier can be removed without an ambiguous rewrite.
+ *
+ * @return Whether the export modifier can be removed without an ambiguous rewrite.
  */
 function knipExportCanBeMadePrivate(file, name) {
     if (!existsSync(file) || file.endsWith('.astro'))
@@ -1222,9 +1234,12 @@ function fixKnipExports(cfg, changedFiles) {
 }
 /** Finds export names that configured source files import and actually reference. */
 const importedExportConsumerCache = new WeakMap();
-/** Builds a cache of exported names referenced by configured source consumers.
+/**
+ * Builds a cache of exported names referenced by configured source consumers.
+ *
  * @param cfg Quality configuration defining roots, aliases, and skipped paths.
- * @returns Export names grouped by their resolved absolute source file.
+ *
+ * @return Export names grouped by their resolved absolute source file.
  */
 function importedExportConsumers(cfg) {
     const srcFiles = filesFor(cfg, true).filter((path) => C_M_JS_TS_X_CLASS_2.test(path) || path.endsWith('.astro'));
@@ -1309,12 +1324,15 @@ function importedExportConsumers(cfg) {
     importedExportConsumerCache.set(cfg, { signature, consumers });
     return consumers;
 }
-/** Accepts proposed edits only when they add no TypeScript errors to changed files.
+/**
+ * Accepts proposed edits only when they add no TypeScript errors to changed files.
+ *
  * @param program TypeScript program representing the original source.
  * @param proposed Proposed source text keyed by absolute filename.
  * @param original Original source text for the same files.
  * @param onBatch Optional progress callback for each validation batch.
- * @returns Accepted source edits and filenames rejected by the type-safety check.
+ *
+ * @return Accepted source edits and filenames rejected by the type-safety check.
  */
 function acceptTypeSafeEdits(program, proposed, original, onBatch) {
     const rejected = new Set();
@@ -1342,11 +1360,14 @@ function acceptTypeSafeEdits(program, proposed, original, onBatch) {
         rejected,
     };
 }
-/** Prints dead-code findings and sets a failing process status for autofixable issues.
+/**
+ * Prints dead-code findings and fails when errors or blocking manual findings remain.
+ *
  * @param findings Findings collected by the dead-code coordinator.
+ * @param manualWarnings Policy for manual-only findings.
  * @param typeSafetyVerified Whether the candidate autofixes passed TypeScript safety checks.
  */
-function printDeadCodeFindings(findings, typeSafetyVerified = true) {
+function printDeadCodeFindings(findings, manualWarnings, typeSafetyVerified = true) {
     if (reportStages) {
         const stage = reportStages.get('dead-code');
         if (stage) {
@@ -1359,16 +1380,20 @@ function printDeadCodeFindings(findings, typeSafetyVerified = true) {
         console.error('  ✓ dead-code checks passed; no autofixable findings or manual warnings remain');
         return;
     }
-    const errs = findings.filter((finding) => finding.severity === 'error');
-    const warnings = findings.filter((finding) => finding.severity === 'warning');
+    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) {
-        console.error(`  - [${finding.severity.toUpperCase()}] ${finding.rule}: ${finding.file}:${finding.line} ${finding.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}`);
         const autofix = !finding.autofixable ? 'not safe or not supported' : typeSafetyVerified ? 'available' : 'candidate; fix mode checks TypeScript before writing';
         console.error(`      Autofix: ${autofix}`);
         console.error(`      Agent action: ${finding.agentAction}`);
     }
-    console.error(`  ${errs.length} error${errs.length === 1 ? '' : 's'}; ${warnings.length} manual warning${warnings.length === 1 ? '' : 's'}.`);
+    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.');
     if (errs.length)
         process.exitCode = 1;
 }
@@ -1527,17 +1552,21 @@ function runDeadCode(cfg, fix, all, verify = true, emit = true) {
         }
         : finding);
     if (emit)
-        printDeadCodeFindings(finalFindings, fix);
+        printDeadCodeFindings(finalFindings, cfg.manualWarnings ?? 'error', fix);
     return finalFindings;
 }
-/** Runs dead-code detectors once without modifying the source tree.
+/**
+ * Runs dead-code detectors once without modifying the source tree.
+ *
  * @param cfg Quality configuration defining source scope and tools.
  * @param all Whether to inspect all configured source files.
  */
 function runDeadCodeReadOnly(cfg, all) {
     runDeadCode(cfg, false, all);
 }
-/** Dispatches the dead-code coordinator in fix or read-only mode.
+/**
+ * Dispatches the dead-code coordinator in fix or read-only mode.
+ *
  * @param cfg Quality configuration defining source scope and tools.
  * @param fix Whether eligible changes may be applied to source files.
  * @param all Whether to inspect all configured source files.
@@ -1588,6 +1617,7 @@ function printFindings(findings, fmt) {
 }
 /**
  * Run the optional, read-only GitHub analytics stage.
+ *
  * @param cfg Quality configuration containing repositories and expected settings.
  * @param repos Repository overrides supplied to `terra-quality github`.
  * @param explicit Whether GitHub reporting was requested as the command itself.
@@ -1595,8 +1625,8 @@ function printFindings(findings, fmt) {
  */
 function runGitHubCheck(cfg, repos = [], explicit = false, warn = false) {
     qualityHeader('github', 'Reading open issues, Dependabot, code scanning, and secret scanning alerts');
-    const targets = repos.length ? repos : (cfg.github?.repositories ?? [inferGitHubRepo(cfg.root)].filter((repo) => Boolean(repo)));
-    if (!targets.length) {
+    const tgts = repos.length ? repos : (cfg.github?.repositories ?? [inferGitHubRepo(cfg.root)].filter((repo) => Boolean(repo)));
+    if (!tgts.length) {
         const detail = 'Set github.repositories in quality.json or pass --repository owner/name.';
         reportGitHubData = { schemaVersion: 1, generatedAt: new Date().toISOString(), state: 'partial', detail, repositories: [] };
         updateGitHubStage('failed', 0);
@@ -1614,7 +1644,7 @@ function runGitHubCheck(cfg, repos = [], explicit = false, warn = false) {
         return;
     }
     try {
-        reportGitHubData = buildGitHubReport(targets, cfg.github?.requiredFeatures, undefined, cfg.github?.featureExemptions);
+        reportGitHubData = buildGitHubReport(tgts, cfg.github?.requiredFeatures, undefined, cfg.github?.featureExemptions);
         const findings = reportGitHubData.repositories.flatMap((repo) => repo.findings);
         const failed = reportGitHubData.state === 'partial';
         updateGitHubStage(failed ? 'failed' : findings.length ? 'findings' : 'passed', findings.length);
@@ -1634,7 +1664,9 @@ function runGitHubCheck(cfg, repos = [], explicit = false, warn = false) {
         process.exitCode = 1;
     }
 }
-/** Update the JSON summary for the active GitHub report stage.
+/**
+ * Update the JSON summary for the active GitHub report stage.
+ *
  * @param status Result state to record.
  * @param findings Number of GitHub findings in the report.
  */
@@ -1645,8 +1677,11 @@ function updateGitHubStage(status, findings) {
         stage.findings = findings;
     }
 }
-/** Infer the current repository slug from its GitHub origin remote.
+/**
+ * Infer the current repository slug from its GitHub origin remote.
+ *
  * @param root Repository root to inspect.
+ *
  * @return The owner/name slug, or undefined for a non-GitHub remote.
  */
 function inferGitHubRepo(root) {
@@ -1675,6 +1710,25 @@ function runGenericChecks(cfg, analysis) {
             process.exitCode = 1;
     }
 }
+/**
+ * Runs the configured Tailwind canonical-class check and records its CLI report stage.
+ *
+ * @param cfg Quality configuration containing the Tailwind stylesheet and source roots.
+ * @param fix Whether to write Tailwind's canonical class suggestions.
+ *
+ * @return Promise resolving when the diagnostic or autofix completes.
+ */
+function runTailwindCanonicalCheck(cfg, fix) {
+    qualityHeader('tailwind-canonical', `${fix ? 'Fixing and checking' : 'Checking'} canonical Tailwind classes`);
+    return runTailwindCanonical(cfg, fix).then(() => undefined, (error) => {
+        const stage = reportStages?.get('tailwind-canonical');
+        if (stage) {
+            stage.status = 'failed';
+            stage.findings = Number(/failed with (\d+) suggestion/.exec(error instanceof Error ? error.message : '')?.[1] ?? 0);
+        }
+        throw error;
+    });
+}
 /**
  * Renames safe repository-local declarations and repairs matching references.
  *
@@ -2043,25 +2097,20 @@ function runDocumentation(cfg, opts, args, quiet) {
  * @param cfg Normalized quality configuration for the current repository.
  * @param args CLI arguments to dispatch.
  *
- * @return Nothing; command failures are reflected in the process exit code.
+ * @return A completion promise for asynchronous checks, or nothing for synchronous commands.
  */
 export function runQualityCli(cfg, args = process.argv.slice(2)) {
     validCliArgs(args);
     const reportIdx = args.indexOf('--report-json');
     const reportPath = reportIdx < 0 ? undefined : args[reportIdx + 1];
     const cmdArgs = reportIdx < 0 ? args : args.filter((_, i) => i !== reportIdx && i !== reportIdx + 1);
-    if (!reportPath) {
-        dispatchQualityCli(cfg, cmdArgs);
-        return;
-    }
+    if (!reportPath)
+        return dispatchQualityCli(cfg, cmdArgs);
     reportStages = new Map();
     reportStageName = undefined;
     reportGitHubData = undefined;
-    try {
-        dispatchQualityCli(cfg, cmdArgs);
-    }
-    finally {
-        const executed = [...reportStages.values()].filter((s) => {
+    const writeReport = () => {
+        const executed = [...(reportStages?.values() ?? [])].filter((s) => {
             if (s.name.includes('/') || s.name.startsWith('recommendation:'))
                 return false;
             const names = { imports: 'import', naming: 'name', aliases: 'alias', forwarding: 'forward', documentation: 'document', typecheck: 'type' };
@@ -2072,6 +2121,8 @@ export function runQualityCli(cfg, args = process.argv.slice(2)) {
                 return false;
             if (s.name === 'repeated-classes' && !cfg.repeatedClasses)
                 return false;
+            if (s.name === 'tailwind-canonical' && !cfg.tailwindCanonical)
+                return false;
             if (s.name === 'regex-dedup' && !cfg.regexDedup)
                 return false;
             if (s.name === 'ui-patterns' && !cfg.uiPatterns)
@@ -2091,6 +2142,7 @@ export function runQualityCli(cfg, args = process.argv.slice(2)) {
             'aliases',
             'security',
             'repeated-classes',
+            'tailwind-canonical',
             'regex-dedup',
             'ui-patterns',
             'github',
@@ -2106,13 +2158,25 @@ export function runQualityCli(cfg, args = process.argv.slice(2)) {
         writeFileSync(resolve(cfg.root, reportPath), `${JSON.stringify(report, null, 2)}\n`);
         reportStages = undefined;
         reportStageName = undefined;
+    };
+    try {
+        const result = dispatchQualityCli(cfg, cmdArgs);
+        if (result instanceof Promise)
+            return result.finally(writeReport);
+    }
+    catch (err) {
+        writeReport();
+        throw err;
     }
+    writeReport();
 }
 /**
  * Route validated arguments to the requested quality command.
  *
  * @param cfg Normalized repository quality configuration.
  * @param args Validated CLI arguments.
+ *
+ * @return A completion promise for asynchronous checks, or nothing for synchronous commands.
  */
 function dispatchQualityCli(cfg, args) {
     validCliArgs(args);
@@ -2123,7 +2187,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, security, and domain.');
+        console.info('Commands include quality, history, github, document, format, lint, knip, types, single-use, dead-code, tailwind-canonical, security, 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;
     }
@@ -2136,6 +2200,11 @@ 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))
+        return runTailwindCanonicalCheck(cfg, fix('tailwindCanonical')).then(() => {
+            const checks = { ...cfg.enabledChecks, 'tailwind-canonical': false };
+            return dispatchQualityCli({ ...cfg, enabledChecks: checks }, args);
+        });
     if (cmd === 'github') {
         runGitHubCheck(cfg, optVals(args, '--repository'), true, args.includes('--warn'));
         return;
@@ -2187,6 +2256,11 @@ function dispatchQualityCli(cfg, args) {
         runDeadCodeCmd(cfg, qualityAutofixEnabled(cfg, 'dead-code', opts.fix), opts.all);
         return;
     }
+    if (cmd === 'tailwind-canonical') {
+        if (!qualityCheckEnabled(cfg, 'tailwind-canonical') || !cfg.tailwindCanonical)
+            return;
+        return runTailwindCanonicalCheck(cfg, fix('tailwindCanonical'));
+    }
     if (cmd === 'security' || cmd === 'repeated-classes' || cmd === 'regex-dedup' || cmd === 'ui-patterns') {
         if (cmd === 'repeated-classes' && fix('repeatedClasses')) {
             const result = fixRepeatedClasses(cfg);
@@ -2303,7 +2377,7 @@ function dispatchQualityCli(cfg, args) {
  * @param file Optional path to the quality configuration file.
  * @param args CLI arguments passed to the dispatcher.
  *
- * @return Nothing; command failures are reflected in the process exit code.
+ * @return A completion promise for asynchronous checks, or nothing for synchronous commands.
  */
 export function runQualityFromCfg(file, args = process.argv.slice(2)) {
     validCliArgs(args);
@@ -2331,7 +2405,7 @@ export function runQualityFromCfg(file, args = process.argv.slice(2)) {
         if (!flatCfg)
             throw new Error(`ESLint flat config is required for ${cmd}. Add eslint.config.js, eslint.config.mjs, or eslint.config.ts at ${cfg.root} before running Terra Quality.`);
     }
-    runQualityCli(cfg, args);
+    return runQualityCli(cfg, args);
 }
 /**
  * Reject unknown commands and flags before loading configuration or invoking a fixer.
@@ -2364,15 +2438,19 @@ function validCliArgs(args) {
  *
  * @param args CLI arguments.
  * @param flag Flag whose following value is returned.
+ *
  * @return The flag value, or undefined when the flag was not supplied.
  */
 function optVal(args, flag) {
     const idx = args.indexOf(flag);
     return idx < 0 ? undefined : args[idx + 1];
 }
-/** Read each occurrence of a repeated CLI option.
+/**
+ * Read each occurrence of a repeated CLI option.
+ *
  * @param args Validated command-line arguments.
  * @param flag Repeated flag to read.
+ *
  * @return Values supplied after each occurrence of the flag.
  */
 function optVals(args, flag) {
@@ -2477,5 +2555,8 @@ export function runTypecheck(cfg, args = []) {
     console.error(`  ${result.status ? '✗ failed' : '✓ passed'}`);
 }
 if (process.argv[1] && realpathSync(resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url)))
-    runQualityFromCfg();
+    Promise.resolve(runQualityFromCfg()).catch((error) => {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+    });
 //# sourceMappingURL=runner.js.map