devkit-quality 0.1.0 → 0.1.1

package/dist/rules/duplication.js

@@ -12,13 +12,23 @@ const finding_1 = require("../finding");
 const config_1 = require("../config");
 const DEFAULT_MIN_TOKENS = 40;
 const WINDOW_STEP = 5;
+function importRanges(sourceFile) {
+    return sourceFile.statements
+        .filter((statement) => typescript_1.default.isImportDeclaration(statement) || typescript_1.default.isImportEqualsDeclaration(statement) || (typescript_1.default.isExportDeclaration(statement) && !!statement.moduleSpecifier))
+        .map((statement) => [statement.getStart(sourceFile), statement.getEnd()]);
+}
 function tokenize(sourceFile, languageVariant) {
     const scanner = typescript_1.default.createScanner(typescript_1.default.ScriptTarget.ES2022, true, languageVariant, sourceFile.text);
+    // Import headers are near-identical across files by nature (especially tests) and are not
+    // extractable logic, so they are left out of clone detection.
+    const skipped = importRanges(sourceFile);
     const tokens = [];
     let kind = scanner.scan();
     while (kind !== typescript_1.default.SyntaxKind.EndOfFileToken) {
         const pos = scanner.getTokenStart();
-        tokens.push({ text: scanner.getTokenText(), line: sourceFile.getLineAndCharacterOfPosition(pos).line + 1, kind });
+        if (!skipped.some(([start, end]) => pos >= start && pos < end)) {
+            tokens.push({ text: scanner.getTokenText(), line: sourceFile.getLineAndCharacterOfPosition(pos).line + 1, kind });
+        }
         kind = scanner.scan();
     }
     return tokens;
@@ -42,11 +52,14 @@ function severityForSpan(spanTokens, minTokens) {
     return 'LOW';
 }
 function mergeRanges(ranges) {
-    const sorted = [...ranges].sort((a, b) => a.startLineA - b.startLineA);
+    const sorted = [...ranges].sort((a, b) => a.startIndexA - b.startIndexA || a.startIndexB - b.startIndexB);
     const merged = [];
     for (const range of sorted) {
         const last = merged[merged.length - 1];
-        if (last && range.startLineA <= last.endLineA + 1 && range.startLineB <= last.endLineB + 1) {
+        // Consecutive windows of the same clone advance by the same offset on both sides.
+        const sameClone = last && range.startIndexA <= last.endIndexA && range.startIndexB - range.startIndexA === last.startIndexB - last.startIndexA;
+        if (sameClone) {
+            last.endIndexA = Math.max(last.endIndexA, range.endIndexA);
             last.endLineA = Math.max(last.endLineA, range.endLineA);
             last.endLineB = Math.max(last.endLineB, range.endLineB);
         }
@@ -95,7 +108,8 @@ function runDuplicationRules(context) {
             for (let j = i + 1; j < entries.length; j += 1) {
                 const a = entries[i];
                 const b = entries[j];
-                if (a.file === b.file && a.startIndex === b.startIndex)
+                // Within one file, overlapping windows are repetitive code, not a copy-paste.
+                if (a.file === b.file && Math.abs(a.startIndex - b.startIndex) < minTokens)
                     continue;
                 const key = a.file <= b.file ? `${a.file}::${b.file}` : `${b.file}::${a.file}`;
                 const [first, second] = a.file <= b.file ? [a, b] : [b, a];
@@ -105,7 +119,10 @@ function runDuplicationRules(context) {
                     startLineA: first.startLine,
                     endLineA: first.endLine,
                     startLineB: second.startLine,
-                    endLineB: second.endLine
+                    endLineB: second.endLine,
+                    startIndexA: first.startIndex,
+                    endIndexA: first.startIndex + minTokens,
+                    startIndexB: second.startIndex
                 });
             }
         }
@@ -115,13 +132,11 @@ function runDuplicationRules(context) {
         const [fileA, fileB] = key.split('::');
         const merged = mergeRanges(ranges);
         for (const range of merged) {
-            const spanLines = range.endLineA - range.startLineA + 1;
-            if (spanLines * WINDOW_STEP < minTokens)
-                continue;
+            const spanTokens = range.endIndexA - range.startIndexA;
             findings.push((0, finding_1.buildFinding)({
                 ruleId: 'DUP001',
                 category: 'duplication',
-                severity: severityForSpan(spanLines * WINDOW_STEP, minTokens),
+                severity: severityForSpan(spanTokens, minTokens),
                 confidence: 'MEDIUM',
                 file: fileA,
                 line: range.startLineA,

package/dist/rules/errorHandling.js

@@ -65,7 +65,9 @@ function runErrorHandlingRules(context) {
         const visit = (node) => {
             if (typescript_1.default.isCatchClause(node)) {
                 const statements = node.block.statements;
-                if ((0, config_1.isRuleEnabled)(context.config, 'ERR001') && statements.length === 0) {
+                // A comment inside the block documents an intentional ignore, which is what the rule asks for.
+                const documented = /\/\/|\/\*/.test(node.block.getText());
+                if ((0, config_1.isRuleEnabled)(context.config, 'ERR001') && statements.length === 0 && !documented) {
                     const { line, column } = (0, walk_1.lineAndColumn)(sourceFile, node.getStart());
                     findings.push((0, finding_1.buildFinding)({
                         ruleId: 'ERR001', category: 'errorHandling', severity: 'MEDIUM', confidence: 'CERTAIN', file: relativePath, line, column,

package/dist/rules/hygiene.js

@@ -14,6 +14,10 @@ const walk_1 = require("../ast/walk");
 const BACKUP_FILE_PATTERN = /(\.bak|\.orig|\.tmp|~)$/i;
 const ENV_FILE_PATTERN = /^\.env(\..+)?$/i;
 const ENV_SAFE_SUFFIXES = /\.(example|sample|template|dist)$/i;
+// A file that builds a CLI program (imports an argv/command-parsing library) treats console
+// output as its actual product, not a debug leftover. Still flagged, at lower confidence, so it
+// stays visible but does not carry the same weight as a stray console.log in business logic.
+const CLI_LIBRARY_IMPORT = /\bfrom\s+['"](?:commander|yargs|cac|meow|sade|clipanion)['"]|\brequire\(\s*['"](?:commander|yargs|cac|meow|sade|clipanion)['"]\s*\)/;
 function runHygieneRules(context) {
     const findings = [];
     for (const file of context.files) {
@@ -22,14 +26,19 @@ function runHygieneRules(context) {
         if (!sourceFile)
             continue;
         const relativePath = node_path_1.default.relative(context.projectRoot, file).replace(/\\/g, '/');
+        const isCliEntryFile = CLI_LIBRARY_IMPORT.test(text);
         const visit = (node) => {
             if ((0, config_1.isRuleEnabled)(context.config, 'HYGIENE001') && typescript_1.default.isCallExpression(node) && typescript_1.default.isPropertyAccessExpression(node.expression) &&
                 typescript_1.default.isIdentifier(node.expression.expression) && node.expression.expression.text === 'console' &&
                 ['log', 'debug', 'warn', 'error'].includes(node.expression.name.text)) {
                 const { line, column } = (0, walk_1.lineAndColumn)(sourceFile, node.getStart());
                 findings.push((0, finding_1.buildFinding)({
-                    ruleId: 'HYGIENE001', category: 'hygiene', severity: 'LOW', confidence: 'CERTAIN', file: relativePath, line, column,
-                    message: 'Debug statement found', description: 'Console output remains in source code.', evidence: node.getText().slice(0, 160),
+                    ruleId: 'HYGIENE001', category: 'hygiene', severity: 'LOW', confidence: isCliEntryFile ? 'LOW' : 'CERTAIN', file: relativePath, line, column,
+                    message: 'Debug statement found',
+                    description: isCliEntryFile
+                        ? 'Console output remains in source code. This file builds a CLI program, so this may be intended output rather than a debug leftover.'
+                        : 'Console output remains in source code.',
+                    evidence: node.getText().slice(0, 160),
                     suggestion: 'Remove or gate debug logging before production deployment.', fixAvailable: true
                 }));
             }

package/dist/rules/security.js

@@ -62,24 +62,38 @@ function containsUntrustedInput(expression) {
 function hasPathSanitizer(node) {
     return /(?:normalize|sanitize|safePath|allowedPaths|allowlist)\s*\(/i.test(node.getText());
 }
+// Unquoted `key: value` / `KEY=value` assignments as found in .env, YAML, TOML, INI and properties files.
+const CONFIG_SECRET_PATTERN = /\b([A-Za-z0-9_.-]*(?:api[_-]?key|secret|token|passw(?:or)?d|private[_-]?key|access[_-]?key|client[_-]?secret|auth)[A-Za-z0-9_.-]*)\b["']?\s*[:=]\s*["']?([^\s"',;}]{8,})/i;
+const PLACEHOLDER_VALUE = /example|sample|dummy|placeholder|changeme|your[_-]|xxxx|<[^>]*>|\$\{|\{\{|process\.env|^\*+$/i;
+const DOCUMENTATION_FILE = /\.(?:md|mdx|markdown|rst|txt|adoc)$/i;
 function runSecretScan(context) {
     if (!(0, config_1.isRuleEnabled)(context.config, 'SEC001'))
         return [];
     const findings = [];
-    for (const file of context.files) {
+    const sourceFiles = new Set(context.files);
+    for (const file of [...context.files, ...context.textFiles]) {
         const text = (0, discovery_1.readFileSafe)(file);
         const relativePath = node_path_1.default.relative(context.projectRoot, file).replace(/\\/g, '/');
         const lines = text.split(/\r\n|\r|\n/);
         const isTestFixture = (0, discovery_1.isTestFile)(relativePath) || /(?:^|\/)(?:fixtures?|__mocks__)(?:\/|$)/i.test(relativePath);
+        const isSource = sourceFiles.has(file);
+        const isDocumentation = DOCUMENTATION_FILE.test(relativePath);
         for (let i = 0; i < lines.length; i += 1) {
             const providerPattern = secretPatterns_1.SECRET_PATTERNS.find((pattern) => pattern.regex.test(lines[i]));
-            const fallbackMatch = !providerPattern && !isTestFixture ? lines[i].match(SECRET_PATTERN) : null;
-            if (providerPattern || (fallbackMatch && (0, secretPatterns_1.looksHighEntropy)(fallbackMatch[2]))) {
+            let fallbackMatch = null;
+            if (!providerPattern && !isTestFixture && !isDocumentation) {
+                const candidate = lines[i].match(isSource ? SECRET_PATTERN : CONFIG_SECRET_PATTERN);
+                if (candidate && !PLACEHOLDER_VALUE.test(candidate[2]))
+                    fallbackMatch = candidate;
+            }
+            if (providerPattern || (fallbackMatch && (0, secretPatterns_1.looksHighEntropy)(fallbackMatch[2], isSource ? 20 : 16))) {
+                // Fixtures and docs legitimately carry example credentials; keep them visible but discounted.
+                const discounted = isTestFixture || isDocumentation || /EXAMPLE/.test(lines[i]);
                 findings.push((0, finding_1.buildFinding)({
                     ruleId: 'SEC001',
                     category: 'security',
                     severity: 'HIGH',
-                    confidence: providerPattern ? 'HIGH' : 'MEDIUM',
+                    confidence: discounted ? 'LOW' : providerPattern ? 'HIGH' : 'MEDIUM',
                     file: relativePath,
                     line: i + 1,
                     column: providerPattern ? lines[i].search(providerPattern.regex) + 1 : lines[i].indexOf(fallbackMatch[0]) + 1,
@@ -293,8 +307,8 @@ function scanTemplateFilesForUnsafeBindings(context) {
     if (!(0, config_1.isRuleEnabled)(context.config, 'SEC004'))
         return [];
     const findings = [];
-    for (const file of context.allFiles) {
-        if (!/\.(?:vue|html)$/i.test(file))
+    for (const file of context.textFiles) {
+        if (!/\.(?:vue|html|svelte)$/i.test(file))
             continue;
         const text = (0, discovery_1.readFileSafe)(file);
         const lines = text.split(/\r\n|\r|\n/);

package/dist/scanner.js

@@ -11,7 +11,6 @@ const discovery_1 = require("./discovery");
 const parse_1 = require("./ast/parse");
 const moduleGraph_1 = require("./moduleGraph");
 const config_1 = require("./config");
-const ignore_1 = require("./ignore");
 const complexity_1 = require("./rules/complexity");
 const deadCode_1 = require("./rules/deadCode");
 const dependencies_1 = require("./rules/dependencies");
@@ -53,29 +52,80 @@ function estimateDuplicatedLines(findings) {
     }
     return total;
 }
-function scanRepository(projectRoot) {
+function countLanguages(files) {
+    const counts = {};
+    for (const file of files) {
+        const base = node_path_1.default.basename(file);
+        const key = node_path_1.default.extname(file).toLowerCase() || (base.startsWith('.') ? base : '(none)');
+        counts[key] = (counts[key] ?? 0) + 1;
+    }
+    return counts;
+}
+const RULE_PHASES = [
+    ['Dead code', deadCode_1.runDeadCodeRules],
+    ['Dependencies', dependencies_1.runDependencyRules],
+    ['Duplication', duplication_1.runDuplicationRules],
+    ['Error handling', errorHandling_1.runErrorHandlingRules],
+    ['Redundant logic', redundancy_1.runRedundancyRules],
+    ['Type safety', (context) => [...(0, typescript_2.runTypeScriptRules)(context), ...(0, javascript_1.runJavaScriptRules)(context)]],
+    ['Security', security_1.runSecurityRules],
+    ['Architecture', architecture_1.runArchitectureRules],
+    ['Hygiene', hygiene_1.runHygieneRules]
+];
+// discovery, program, type-check, module graph, function metrics + rule phases + scoring
+const TOTAL_STEPS = 5 + RULE_PHASES.length + 1;
+function scanRepository(projectRoot, onProgress = () => undefined) {
+    const startedAt = Date.now();
+    let step = 0;
+    const phase = (label, current, total) => {
+        onProgress({ step, totalSteps: TOTAL_STEPS, label, current, total });
+    };
+    const nextPhase = (label) => {
+        step += 1;
+        phase(label);
+    };
+    nextPhase('Discovering files');
     const config = (0, config_1.loadConfig)(projectRoot);
-    const allFiles = (0, discovery_1.walkDirectory)(projectRoot);
-    const { files, generatedFiles } = (0, discovery_1.filterScannedFiles)(allFiles, projectRoot, config, (0, ignore_1.loadIgnorePatterns)(projectRoot));
+    const discovery = (0, discovery_1.discoverFiles)(projectRoot, config);
+    const { files, allFiles, textFiles, generatedFiles } = discovery;
     const packageJsonPath = node_path_1.default.join(projectRoot, 'package.json');
-    const packageJson = node_fs_1.default.existsSync(packageJsonPath) ? JSON.parse((0, discovery_1.readFileSafe)(packageJsonPath)) : null;
+    let packageJson = null;
+    if (node_fs_1.default.existsSync(packageJsonPath)) {
+        try {
+            packageJson = JSON.parse((0, discovery_1.readFileSafe)(packageJsonPath));
+        }
+        catch {
+            packageJson = null;
+        }
+    }
+    nextPhase(`Parsing ${files.length} source files`);
     const program = (0, parse_1.createProgram)(files);
+    // Type-check every file up front: the program caches diagnostics, so the rule phases that
+    // need them are cheap afterwards, and this (the slowest step) can report per-file progress.
+    nextPhase('Type-checking');
+    files.forEach((file, index) => {
+        phase('Type-checking', index + 1, files.length);
+        const sourceFile = program.getSourceFile(file);
+        if (!sourceFile)
+            return;
+        try {
+            program.getSemanticDiagnostics(sourceFile);
+        }
+        catch {
+            // A checker crash on one file must not abort the whole scan; rules skip it the same way.
+        }
+    });
+    nextPhase('Building module graph');
     const moduleGraph = (0, moduleGraph_1.buildModuleGraph)(projectRoot, files, packageJson, config);
-    const context = { projectRoot, files, allFiles, program, moduleGraph, config, packageJson };
+    const context = { projectRoot, files, allFiles, textFiles, program, moduleGraph, config, packageJson };
+    nextPhase('Measuring complexity');
     const functionMetrics = (0, complexity_1.collectFunctionMetrics)(context);
-    const allFindings = [
-        ...(0, deadCode_1.runDeadCodeRules)(context),
-        ...(0, dependencies_1.runDependencyRules)(context),
-        ...(0, complexity_1.runComplexityRules)(context, functionMetrics),
-        ...(0, duplication_1.runDuplicationRules)(context),
-        ...(0, errorHandling_1.runErrorHandlingRules)(context),
-        ...(0, redundancy_1.runRedundancyRules)(context),
-        ...(0, typescript_2.runTypeScriptRules)(context),
-        ...(0, javascript_1.runJavaScriptRules)(context),
-        ...(0, security_1.runSecurityRules)(context),
-        ...(0, architecture_1.runArchitectureRules)(context),
-        ...(0, hygiene_1.runHygieneRules)(context)
-    ];
+    const allFindings = [...(0, complexity_1.runComplexityRules)(context, functionMetrics)];
+    for (const [label, run] of RULE_PHASES) {
+        nextPhase(label);
+        allFindings.push(...run(context));
+    }
+    nextPhase('Scoring');
     const findings = allFindings.filter((finding) => {
         const sourceFile = context.program.getSourceFile(node_path_1.default.resolve(projectRoot, finding.file));
         return !sourceFile || !(0, suppressions_1.isSuppressed)(sourceFile, finding.line, finding.ruleId);
@@ -85,11 +135,10 @@ function scanRepository(projectRoot) {
     let commentLOC = 0;
     const largestFiles = [];
     for (const file of files) {
-        const text = (0, discovery_1.readFileSafe)(file);
-        const relativePath = node_path_1.default.relative(projectRoot, file).replace(/\\/g, '/');
-        const isTest = (0, discovery_1.isTestFile)(relativePath);
+        const text = program.getSourceFile(file)?.text ?? (0, discovery_1.readFileSafe)(file);
+        const relativePath = (0, discovery_1.toRelative)(projectRoot, file);
         const loc = (0, discovery_1.countLines)(text);
-        if (isTest) {
+        if ((0, discovery_1.isTestFile)(relativePath)) {
             testLOC += loc;
         }
         else {
@@ -100,8 +149,8 @@ function scanRepository(projectRoot) {
             largestFiles.push({ file: relativePath, loc });
         }
     }
-    const sourceFiles = files.filter((file) => !(0, discovery_1.isTestFile)(file)).length;
-    const testFiles = files.filter((file) => (0, discovery_1.isTestFile)(file)).length;
+    const testFiles = files.filter((file) => (0, discovery_1.isTestFile)((0, discovery_1.toRelative)(projectRoot, file))).length;
+    const sourceFiles = files.length - testFiles;
     const dependencyCount = [
         ...Object.keys(packageJson?.dependencies ?? {}),
         ...Object.keys(packageJson?.devDependencies ?? {})
@@ -137,14 +186,28 @@ function scanRepository(projectRoot) {
         deadCodePercentage: functionCount + classCount > 0 ? Math.min(100, (deadCodeFindingCount / (functionCount + classCount)) * 100) : 0,
         testToSourceRatio: sourceLOC > 0 ? testLOC / sourceLOC : 0
     };
-    const { overallScore, categoryScores, securityScore } = (0, scoring_1.computeScores)(findings, sourceLOC);
+    const architectureConfigured = Object.keys(config.architecture?.layers ?? {}).length > 0;
+    const { overallScore, categoryScores, securityScore, securityCapped } = (0, scoring_1.computeScores)(findings, sourceLOC + testLOC, { architectureConfigured });
+    const coverage = {
+        discoveryMethod: discovery.method,
+        discoveredFiles: allFiles.length,
+        analyzedFiles: files.length,
+        textFilesScanned: textFiles.length,
+        generatedFilesSkipped: generatedFiles.length,
+        tooLargeFilesSkipped: discovery.skipped.tooLarge,
+        binaryFilesSkipped: discovery.skipped.binary,
+        languages: countLanguages(allFiles),
+        durationMs: Date.now() - startedAt
+    };
     return {
         repository: projectRoot,
         score: overallScore,
         categoryScores,
         securityScore,
+        securityCapped,
         findings,
         metrics,
-        generatedFiles
+        generatedFiles,
+        coverage
     };
 }

package/dist/scoring.js

@@ -1,18 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CATEGORY_WEIGHTS = void 0;
+exports.SECURITY_CAP = exports.CATEGORY_WEIGHTS = void 0;
 exports.computeScores = computeScores;
 exports.summarizeTopDeductions = summarizeTopDeductions;
+exports.summarizeHotspots = summarizeHotspots;
+const discovery_1 = require("./discovery");
 exports.CATEGORY_WEIGHTS = {
-    deadCode: 0.2,
+    deadCode: 0.15,
     dependencies: 0.1,
     complexity: 0.15,
     duplication: 0.1,
-    redundantLogic: 0.1,
+    redundantLogic: 0.05,
     errorHandling: 0.1,
     typescript: 0.1,
-    architecture: 0.1,
-    hygiene: 0.05
+    architecture: 0.05,
+    hygiene: 0.05,
+    security: 0.15
 };
 const SEVERITY_WEIGHT = {
     CRITICAL: 3,
@@ -28,27 +31,48 @@ const CONFIDENCE_WEIGHT = {
     LOW: 0.3
 };
 const LOC_CHUNK = 500;
+/** Findings in tests still matter, but less than the same problem in shipped code. */
+const TEST_FILE_WEIGHT = 0.5;
+/** A credible leaked secret or injection sink caps the overall score, however clean the rest is. */
+exports.SECURITY_CAP = 6.9;
 function findingPenalty(finding) {
-    return SEVERITY_WEIGHT[finding.severity] * CONFIDENCE_WEIGHT[finding.confidence];
+    const base = SEVERITY_WEIGHT[finding.severity] * CONFIDENCE_WEIGHT[finding.confidence];
+    return (0, discovery_1.isTestFile)(finding.file) ? base * TEST_FILE_WEIGHT : base;
 }
-function normalizedCategoryScore(findings, sourceLOC) {
+/**
+ * Quality categories are scored by density (penalty per 500 LOC), so a large codebase is not
+ * punished for its size. Security tolerance grows only with the square root of size and is capped
+ * at 3x: one leaked key is just as serious in a 50k-line repository as in a 500-line one.
+ */
+function normalizedCategoryScore(findings, loc, category) {
     const penalty = findings.reduce((sum, finding) => sum + findingPenalty(finding), 0);
-    const normalizer = Math.max(sourceLOC / LOC_CHUNK, 1);
+    const chunks = Math.max(loc / LOC_CHUNK, 1);
+    const normalizer = category === 'security' ? Math.min(Math.sqrt(chunks), 3) : chunks;
     return Math.max(0, Math.min(10, 10 - penalty / normalizer));
 }
-function computeScores(findings, sourceLOC) {
+function hasCredibleSecurityIssue(findings) {
+    return findings.some((finding) => finding.category === 'security' &&
+        (finding.severity === 'HIGH' || finding.severity === 'CRITICAL') &&
+        (finding.confidence === 'HIGH' || finding.confidence === 'CERTAIN') &&
+        !(0, discovery_1.isTestFile)(finding.file));
+}
+function computeScores(findings, loc, options = {}) {
+    const architectureConfigured = options.architectureConfigured ?? true;
+    const categories = Object.keys(exports.CATEGORY_WEIGHTS).filter((category) => category !== 'architecture' || architectureConfigured);
     const categoryScores = {};
-    for (const category of Object.keys(exports.CATEGORY_WEIGHTS)) {
+    for (const category of categories) {
         const categoryFindings = findings.filter((finding) => finding.category === category);
-        categoryScores[category] = Number(normalizedCategoryScore(categoryFindings, sourceLOC).toFixed(1));
+        categoryScores[category] = Number(normalizedCategoryScore(categoryFindings, loc, category).toFixed(1));
     }
-    const overallScore = Object.entries(exports.CATEGORY_WEIGHTS).reduce((sum, [category, weight]) => sum + weight * categoryScores[category], 0);
-    const securityFindings = findings.filter((finding) => finding.category === 'security');
-    const securityScore = Number(normalizedCategoryScore(securityFindings, sourceLOC).toFixed(1));
+    const totalWeight = categories.reduce((sum, category) => sum + exports.CATEGORY_WEIGHTS[category], 0);
+    const weighted = categories.reduce((sum, category) => sum + exports.CATEGORY_WEIGHTS[category] * categoryScores[category], 0) / totalWeight;
+    const securityCapped = hasCredibleSecurityIssue(findings) && weighted > exports.SECURITY_CAP;
+    const overallScore = securityCapped ? exports.SECURITY_CAP : weighted;
     return {
         overallScore: Number(overallScore.toFixed(1)),
         categoryScores,
-        securityScore
+        securityScore: categoryScores.security,
+        securityCapped
     };
 }
 function summarizeTopDeductions(findings, limit = 8) {
@@ -66,3 +90,17 @@ function summarizeTopDeductions(findings, limit = 8) {
     }
     return [...byRule.values()].sort((a, b) => b.totalPenalty - a.totalPenalty).slice(0, limit);
 }
+/** Files ranked by total penalty: where fixing things moves the score the most. */
+function summarizeHotspots(findings, limit = 5) {
+    const rank = { INFO: 0, LOW: 1, MEDIUM: 2, HIGH: 3, CRITICAL: 4 };
+    const byFile = new Map();
+    for (const finding of findings) {
+        const entry = byFile.get(finding.file) ?? { file: finding.file, count: 0, penalty: 0, worst: 'INFO' };
+        entry.count += 1;
+        entry.penalty += findingPenalty(finding);
+        if (rank[finding.severity] > rank[entry.worst])
+            entry.worst = finding.severity;
+        byFile.set(finding.file, entry);
+    }
+    return [...byFile.values()].sort((a, b) => b.penalty - a.penalty).slice(0, limit);
+}

package/dist/suppressions.js

@@ -1,21 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectSuppressions = collectSuppressions;
+exports.collectFileSuppression = collectFileSuppression;
 exports.isSuppressed = isSuppressed;
 const comments_1 = require("./ast/comments");
+const RULE_ID_LIST = '([A-Z]{2,}\\d{3}(?:\\s*,\\s*[A-Z]{2,}\\d{3})*)';
+const NEXT_LINE_PATTERN = new RegExp(`devkit-disable-next-line(?:\\s+${RULE_ID_LIST})?`, 'i');
+const FILE_PATTERN = new RegExp(`devkit-disable-file(?:\\s+${RULE_ID_LIST})?`, 'i');
+function parseRuleIdList(match) {
+    return match[1] ? new Set(match[1].split(',').map((id) => id.trim().toUpperCase())) : null;
+}
 function collectSuppressions(sourceFile) {
     const directives = [];
     for (const range of (0, comments_1.collectCommentRanges)(sourceFile)) {
         const text = sourceFile.text.slice(range.pos, range.end);
-        const match = /devkit-disable-next-line(?:\s+([A-Z]{2,}\d{3}(?:\s*,\s*[A-Z]{2,}\d{3})*))?/i.exec(text);
+        const match = NEXT_LINE_PATTERN.exec(text);
         if (!match)
             continue;
         const line = sourceFile.getLineAndCharacterOfPosition(range.end).line + 2;
-        const ruleIds = match[1] ? new Set(match[1].split(',').map((id) => id.trim().toUpperCase())) : null;
-        directives.push({ line, ruleIds });
+        directives.push({ line, ruleIds: parseRuleIdList(match) });
     }
     return directives;
 }
+/**
+ * `// devkit-disable-file` (optionally followed by rule IDs) anywhere in a file silences those
+ * rules for the whole file — for a vendored copy, a generated-looking file that content
+ * detection missed, or a file a team has deliberately decided not to clean up yet.
+ */
+function collectFileSuppression(sourceFile) {
+    for (const range of (0, comments_1.collectCommentRanges)(sourceFile)) {
+        const match = FILE_PATTERN.exec(sourceFile.text.slice(range.pos, range.end));
+        if (match)
+            return { ruleIds: parseRuleIdList(match) };
+    }
+    return null;
+}
 function isSuppressed(sourceFile, line, ruleId) {
-    return collectSuppressions(sourceFile).some((directive) => directive.line === line && (!directive.ruleIds || directive.ruleIds.has(ruleId.toUpperCase())));
+    const upperRuleId = ruleId.toUpperCase();
+    const fileSuppression = collectFileSuppression(sourceFile);
+    if (fileSuppression && (!fileSuppression.ruleIds || fileSuppression.ruleIds.has(upperRuleId))) {
+        return true;
+    }
+    return collectSuppressions(sourceFile).some((directive) => directive.line === line && (!directive.ruleIds || directive.ruleIds.has(upperRuleId)));
 }