@produtype/core 0.16.2 → 0.18.0

package/dist/report/buildReport.js

@@ -127,18 +127,6 @@ function buildReport(analysis, options) {
         || analysis.stack.databases.length > 0
         || mobileDetected
         || gameEngineDetected;
-    const inconclusive = !stackDetected && analysis.workspaceStacks.length === 0;
-    const inconclusiveReasons = [];
-    if (inconclusive) {
-        inconclusiveReasons.push('No frontend, backend, or database stack signals were detected.');
-        inconclusiveReasons.push('No package manifest was found in any format this analyzer reads.');
-        if (analysis.files.source.length === 0) {
-            inconclusiveReasons.push('No recognizable source files were found.');
-        }
-    }
-    // An unrecognized project has almost no applicable detectors, so the absence
-    // of findings must not be rewarded with a high score: cap it at prototype.
-    const overallScore = inconclusive ? Math.min(combinedScore, 39) : combinedScore;
     /**
      * Coverage counts the expectations too, not only the observed rules.
      *
@@ -152,10 +140,63 @@ function buildReport(analysis, options) {
     const passedChecksForMaturity = findings.filter((f) => f.status === 'passed').length + satisfiedExpectations;
     const assessedChecks = findings.filter((f) => f.status !== 'unknown').length
         + Math.max(applicableExpectations - expectationFindings.length, 0);
-    const maturityLevel = (0, score_1.computeMaturity)(overallScore, {
-        passed: passedChecksForMaturity,
-        assessed: assessedChecks,
-    });
+    const coverage = { passed: passedChecksForMaturity, assessed: assessedChecks };
+    const nothingIdentified = !stackDetected && analysis.workspaceStacks.length === 0;
+    /**
+     * Too little reached a verdict to say anything about this project.
+     *
+     * The flag used to ask whether a manifest existed, and the claim it makes is about
+     * what was learned. Two repositories with the same three verdicts came out at 39 and
+     * at 84, and the only difference between them was a `requirements.txt`: a Python
+     * script with one was judged, an equally small one without it was called unreadable.
+     *
+     * Five is where the corpus splits. Of seventy-eight repositories, eleven reach four
+     * verdicts or fewer and thirty reach ten or more; not one lands in between. Four
+     * verdicts cannot characterise a product, however many files it has.
+     */
+    const tooLittleAssessed = assessedChecks < score_1.MIN_ASSESSED_FOR_A_READING;
+    const inconclusive = nothingIdentified || tooLittleAssessed;
+    // Each reason says which of the two it was, because they call for different things:
+    // one is a repository this analyzer cannot read, the other is one there is barely
+    // anything to read.
+    const inconclusiveReasons = [];
+    if (nothingIdentified) {
+        inconclusiveReasons.push('No frontend, backend, or database stack signals were detected.');
+        inconclusiveReasons.push('No package manifest was found in any format this analyzer reads.');
+        if (analysis.files.source.length === 0) {
+            inconclusiveReasons.push('No recognizable source files were found.');
+        }
+    }
+    if (tooLittleAssessed) {
+        inconclusiveReasons.push(`Only ${assessedChecks} check${assessedChecks === 1 ? '' : 's'} reached a verdict, which is too few to characterise this project.`);
+    }
+    // An unrecognized project has almost no applicable detectors, so the absence
+    // of findings must not be rewarded with a high score: cap it at prototype.
+    const scoreAfterInconclusive = inconclusive ? Math.min(combinedScore, 39) : combinedScore;
+    /**
+     * The number obeys the same rule as the label.
+     *
+     * The score starts at 100 and only ever subtracts, so a repository small enough that
+     * almost nothing applies to it keeps most of what it was handed. The maturity label
+     * has refused to call that production ready since the coverage rule was added — and
+     * the number beside it went on saying 98, above every real product in the verification
+     * corpus. A Python transcription script rested on three passing checks out of four and
+     * outscored this product's own web application, which rests on thirty.
+     *
+     * Nothing is subtracted for thin coverage, because there is nothing to subtract for:
+     * the report simply may not enter the top band on evidence that cannot support it.
+     */
+    /**
+     * An unresolved critical bars the top band too.
+     *
+     * Counted before the score is capped, because it is one of the two reasons the top
+     * band can be refused and both must reach the number, not only the label.
+     */
+    const openCriticals = findings.filter((f) => f.severity === 'critical' && f.status !== 'passed' && f.status !== 'unknown').length;
+    const overallScore = (0, score_1.mayClaimTopBand)(coverage, openCriticals)
+        ? scoreAfterInconclusive
+        : Math.min(scoreAfterInconclusive, score_1.TOP_BAND_CEILING);
+    const maturityLevel = (0, score_1.computeMaturity)(overallScore, coverage, openCriticals);
     const findingsByCategory = Object.fromEntries(types_1.CATEGORIES.map((c) => [c, []]));
     for (const f of findings)
         findingsByCategory[f.category].push(f);

package/dist/report/score.d.ts

@@ -10,4 +10,51 @@ export interface ScoreCoverage {
     passed: number;
     assessed: number;
 }
-export declare function computeMaturity(score: number, coverage?: ScoreCoverage): MaturityLevel;
+/**
+ * The fewest verdicts that can carry a reading at all.
+ *
+ * Below this the report has nothing to characterise: not a weak product, but a project
+ * this analyzer barely had anything to say about. In a corpus of seventy-eight
+ * repositories, eleven reach four verdicts or fewer and thirty reach ten or more —
+ * nothing lands in between, so the line sits in the gap rather than in the middle of a
+ * distribution.
+ */
+export declare const MIN_ASSESSED_FOR_A_READING = 5;
+/**
+ * The highest score a report can reach when it may not claim the top band.
+ *
+ * The band boundary itself, deliberately: a report that cannot support the words
+ * "production ready" must not print a number that reads like it either. Two things bar
+ * the top band — evidence too thin to support it, and an unresolved critical — and both
+ * land here.
+ */
+export declare const TOP_BAND_CEILING = 84;
+/**
+ * Whether the report checked enough to stand behind a top-band reading.
+ *
+ * Its own function because two things ask the question — the label and the number — and
+ * they were answering it differently. A repository small enough that almost nothing
+ * applies to it was labelled `partial` and scored 98, above every real product in the
+ * corpus; the label had learned that absence of findings is not evidence of quality and
+ * the score had not.
+ */
+export declare function coverageSupportsTopBand(coverage: ScoreCoverage): boolean;
+/**
+ * Whether a report may print a top-band number at all.
+ *
+ * The single place the two bars are stated, so the score and the label cannot drift
+ * apart again: they did, and the number went on reading 98 above every real product in
+ * the corpus while the label said `partial`.
+ */
+export declare function mayClaimTopBand(coverage: ScoreCoverage, openCriticals: number): boolean;
+/**
+ * How many critical findings are open.
+ *
+ * A separate argument rather than something derived from the score, because the score
+ * subtracts a fixed weight and then moves on: a project with forty-two passing checks
+ * and one unresolved critical came out at 91 and was called production ready. The
+ * category scores have refused to let a critical hide behind passing checks since the
+ * severity ceiling was added — "a category with one critical and nine passing checks is
+ * not 90% healthy" — and the report's own headline had not learned it.
+ */
+export declare function computeMaturity(score: number, coverage?: ScoreCoverage, openCriticals?: number): MaturityLevel;

package/dist/report/score.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOP_BAND_CEILING = exports.MIN_ASSESSED_FOR_A_READING = void 0;
 exports.computeScore = computeScore;
+exports.coverageSupportsTopBand = coverageSupportsTopBand;
+exports.mayClaimTopBand = mayClaimTopBand;
 exports.computeMaturity = computeMaturity;
 const penaltyBySeverity = {
     critical: 15,
@@ -25,7 +28,58 @@ function computeScore(findings) {
  * nothing.
  */
 const MIN_VERIFIED_FOR_PRODUCTION = 6;
-function computeMaturity(score, coverage) {
+/**
+ * The fewest verdicts that can carry a reading at all.
+ *
+ * Below this the report has nothing to characterise: not a weak product, but a project
+ * this analyzer barely had anything to say about. In a corpus of seventy-eight
+ * repositories, eleven reach four verdicts or fewer and thirty reach ten or more —
+ * nothing lands in between, so the line sits in the gap rather than in the middle of a
+ * distribution.
+ */
+exports.MIN_ASSESSED_FOR_A_READING = 5;
+/**
+ * The highest score a report can reach when it may not claim the top band.
+ *
+ * The band boundary itself, deliberately: a report that cannot support the words
+ * "production ready" must not print a number that reads like it either. Two things bar
+ * the top band — evidence too thin to support it, and an unresolved critical — and both
+ * land here.
+ */
+exports.TOP_BAND_CEILING = 84;
+/**
+ * Whether the report checked enough to stand behind a top-band reading.
+ *
+ * Its own function because two things ask the question — the label and the number — and
+ * they were answering it differently. A repository small enough that almost nothing
+ * applies to it was labelled `partial` and scored 98, above every real product in the
+ * corpus; the label had learned that absence of findings is not evidence of quality and
+ * the score had not.
+ */
+function coverageSupportsTopBand(coverage) {
+    return coverage.passed >= MIN_VERIFIED_FOR_PRODUCTION && coverage.passed * 2 >= coverage.assessed;
+}
+/**
+ * Whether a report may print a top-band number at all.
+ *
+ * The single place the two bars are stated, so the score and the label cannot drift
+ * apart again: they did, and the number went on reading 98 above every real product in
+ * the corpus while the label said `partial`.
+ */
+function mayClaimTopBand(coverage, openCriticals) {
+    return coverageSupportsTopBand(coverage) && openCriticals === 0;
+}
+/**
+ * How many critical findings are open.
+ *
+ * A separate argument rather than something derived from the score, because the score
+ * subtracts a fixed weight and then moves on: a project with forty-two passing checks
+ * and one unresolved critical came out at 91 and was called production ready. The
+ * category scores have refused to let a critical hide behind passing checks since the
+ * severity ceiling was added — "a category with one critical and nine passing checks is
+ * not 90% healthy" — and the report's own headline had not learned it.
+ */
+function computeMaturity(score, coverage, openCriticals = 0) {
     if (score <= 39)
         return 'prototype';
     if (score <= 64)
@@ -45,8 +99,12 @@ function computeMaturity(score, coverage) {
      * Absence of findings is not evidence of quality. The top band now requires the
      * report to be able to point at things it checked and found right.
      */
-    if (coverage && (coverage.passed < MIN_VERIFIED_FOR_PRODUCTION || coverage.passed * 2 < coverage.assessed)) {
+    if (coverage && !coverageSupportsTopBand(coverage)) {
         return 'partial';
     }
+    // Nothing is production ready while something critical is open in it. This is the one
+    // claim in the report a reader acts on without reading further.
+    if (openCriticals > 0)
+        return 'partial';
     return 'production_ready';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@produtype/core",
-  "version": "0.16.2",
+  "version": "0.18.0",
   "description": "Deterministic CLI and library that analyzes a web application repository and reports how far it is from production-ready for the kind of product it is meant to be.",
   "license": "MIT",
   "bin": {