@produtype/core 0.44.0 → 0.46.0

package/dist/cli.js

@@ -98,7 +98,12 @@ function parseMinMaturity(value) {
     return value;
 }
 function enforceThresholds(report, failUnder, minMaturity) {
-    if (failUnder !== undefined && report.overallScore < failUnder) {
+    if (failUnder !== undefined && report.overallScore === null) {
+        // A gate asked for a number and there is none. Passing would say the project
+        // cleared a bar nobody measured it against.
+        throw new Error(`Score gate failed: this report has no score. ${report.inconclusiveReasons?.[0] ?? 'The reading was inconclusive.'}`);
+    }
+    if (failUnder !== undefined && report.overallScore !== null && report.overallScore < failUnder) {
         throw new Error(`Score gate failed: overall score ${report.overallScore} is below --fail-under ${failUnder}.`);
     }
     if (minMaturity !== undefined && maturityOrder.indexOf(report.maturityLevel) < maturityOrder.indexOf(minMaturity)) {
@@ -137,7 +142,7 @@ function summarize(report) {
         `Package manager: ${report.detectedStack.packageManager} (${report.detectedStack.packageManagerConfidence})`,
         report.detectedStack.warnings.length > 0 ? `Warnings: ${report.detectedStack.warnings.join('; ')}` : 'Warnings: none',
         `Workspaces: ${workspaceSummary}`,
-        `Score: ${report.overallScore}/100`,
+        report.overallScore === null ? 'Score: not scored' : `Score: ${report.overallScore}/100`,
         /**
          * The reasons, not a verdict about the project.
          *
@@ -145,8 +150,10 @@ function summarize(report) {
          * "Detected frontend: flutter" — the same summary naming the stack it had just
          * failed to recognise. The report has carried the reasons since the flag existed.
          */
-        `Maturity: ${report.maturityLevel}${report.inconclusive ? ' (INCONCLUSIVE, score capped)' : ''}`,
-        ...(report.inconclusive ? report.inconclusiveReasons.map((reason) => `  - ${reason}`) : []),
+        `Maturity: ${report.maturityLevel}`,
+        ...(report.inconclusive
+            ? ['INCONCLUSIVE — this report has no score, for these reasons:', ...report.inconclusiveReasons.map((reason) => `  - ${reason}`)]
+            : []),
         // Printed next to the score it is not allowed to change, so a reader who knows what
         // their project is can act on it in one step.
         ...(report.productProfile?.profileSuggestion

package/dist/mcp/server.js

@@ -201,7 +201,7 @@ async function createProdkitMcpServer() {
                     requiredTotal: report.productProfile?.gap.requiredTotal ?? 0,
                     verdict: report.executiveSummary.verdict,
                 };
-            }).sort((left, right) => right.overallScore - left.overallScore);
+            }).sort((left, right) => (right.overallScore ?? -1) - (left.overallScore ?? -1));
             return textResult({
                 observedOnlyScore: observed.observedScore,
                 detectedStack: observed.detectedStack,

package/dist/planner/types.d.ts

@@ -29,7 +29,8 @@ export interface RemediationPhase {
 export interface RemediationPlan {
     projectPath: string;
     generatedAt: string;
-    score: number;
+    /** `null` where the report could not form a reading. */
+    score: number | null;
     maturityLevel: string;
     summary: string;
     phases: RemediationPhase[];

package/dist/report/buildReport.js

@@ -246,9 +246,19 @@ function buildReport(analysis, options) {
     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;
+    /**
+     * An inconclusive reading has no score.
+     *
+     * This was a cap at 39, so that an unrecognised project could not be rewarded for
+     * the absence of findings. The intent was right and the output was not: eleven
+     * repositories in the corpus came out at exactly 39, and one of them — a Python
+     * transcription script — had no findings at all. A reader saw "39/100, prototype"
+     * about a repository whose own report said it could not be read.
+     *
+     * `null` is the rule this product applies everywhere else. The reasons already
+     * collected above are the answer in its place.
+     */
+    const scoreAfterInconclusive = combinedScore;
     /**
      * The number obeys the same rule as the label.
      *
@@ -269,10 +279,23 @@ function buildReport(analysis, options) {
      * 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 overallScore = inconclusive
+        ? null
+        : (0, score_1.mayClaimTopBand)(coverage, openCriticals)
+            ? scoreAfterInconclusive
+            : Math.min(scoreAfterInconclusive, score_1.TOP_BAND_CEILING);
+    const maturityLevel = overallScore === null
+        ? 'inconclusive'
+        : (0, score_1.computeMaturity)(overallScore, coverage, openCriticals);
+    /**
+     * The observed half goes with it.
+     *
+     * "Overall score: not scored" printed directly above "Observed score: 100/100" —
+     * the report refusing to characterise a repository and then praising it in the next
+     * line. The observed number is the same arithmetic over the same three checks: if
+     * it cannot support a reading it cannot support half of one either.
+     */
+    const reportedObservedScore = inconclusive ? null : observedScore;
     const findingsByCategory = Object.fromEntries(types_1.CATEGORIES.map((c) => [c, []]));
     for (const f of findings)
         findingsByCategory[f.category].push(f);
@@ -320,7 +343,7 @@ function buildReport(analysis, options) {
         categoryScores,
         profile: productProfile,
         maturity: maturityLevel,
-        observedScore,
+        observedScore: reportedObservedScore,
         overallScore,
         inconclusive,
         inconclusiveReasons,
@@ -351,7 +374,7 @@ function buildReport(analysis, options) {
     return {
         projectPath: analysis.projectPath,
         generatedAt: new Date().toISOString(),
-        observedScore,
+        observedScore: reportedObservedScore,
         expectedCapabilityScore: expectationScore,
         overallScore,
         maturityLevel,

package/dist/report/categoryScores.d.ts

@@ -2,7 +2,14 @@ import type { Category, Finding } from './types';
 export interface CategoryScore {
     category: Category;
     /** 0-100. 100 means nothing actionable was found in this category. */
-    score: number;
+    /**
+     * `null` where nothing in the analysis touched this category.
+     *
+     * `notAssessed` has been beside it for a while and the number went on saying 100.
+     * On a report with no overall score at all, twelve categories still read 100 of 100
+     * — a repository the analyzer could not read, presented as perfect in twelve areas.
+     */
+    score: number | null;
     findingCount: number;
     /** Checks that ran and found what they were looking for. */
     verifiedCount: number;

package/dist/report/categoryScores.js

@@ -103,9 +103,10 @@ function buildCategoryScores(findings) {
          */
         const worstOpen = actionable.reduce((worst, finding) => (SEVERITY_WEIGHT[finding.severity] > SEVERITY_WEIGHT[worst] ? finding.severity : worst), 'info');
         const ceiling = SEVERITY_CEILING[worstOpen];
+        const notAssessed = categoryFindings.every((finding) => finding.status === 'unknown');
         return {
             category,
-            score: Math.max(0, Math.min(100, proportional, ceiling)),
+            score: notAssessed ? null : Math.max(0, Math.min(100, proportional, ceiling)),
             findingCount: actionable.length,
             /** Checks in this category that ran and found what they were looking for. */
             verifiedCount: assessed.filter((finding) => finding.status === 'passed').length,
@@ -122,7 +123,7 @@ function buildCategoryScores(findings) {
              * A Django school platform with no payments anywhere was reported as having
              * "no issues found in taking payments", as a strength.
              */
-            notAssessed: categoryFindings.every((finding) => finding.status === 'unknown'),
+            notAssessed,
         };
     });
 }
@@ -130,6 +131,6 @@ function buildCategoryScores(findings) {
 function weakestCategories(scores, limit = 3) {
     return [...scores]
         .filter((entry) => !entry.notAssessed && entry.findingCount > 0)
-        .sort((left, right) => left.score - right.score || right.criticalCount - left.criticalCount)
+        .sort((left, right) => (left.score ?? 100) - (right.score ?? 100) || right.criticalCount - left.criticalCount)
         .slice(0, limit);
 }

package/dist/report/executiveSummary.d.ts

@@ -20,8 +20,8 @@ export declare function buildExecutiveSummary(args: {
     categoryScores: CategoryScore[];
     profile: ProductExpectationResult | undefined;
     maturity: MaturityLevel;
-    observedScore: number;
-    overallScore: number;
+    observedScore: number | null;
+    overallScore: number | null;
     inconclusive: boolean;
     /** Why, when the report could not form a reading. Named in the verdict. */
     inconclusiveReasons?: string[];

package/dist/report/executiveSummary.js

@@ -30,6 +30,7 @@ const CATEGORY_LABEL = {
     docs: 'saying what this is',
 };
 const MATURITY_LABEL = {
+    inconclusive: 'not characterised, because too little of it could be read',
     prototype: 'a prototype',
     early: 'an early build',
     partial: 'partly ready',
@@ -157,7 +158,7 @@ function buildStrengths(categoryScores, findings) {
     const passedCategories = new Set(passed.map((finding) => finding.category));
     const strongCategories = categoryScores
         .filter((entry) => !entry.notAssessed
-        && entry.score >= 80
+        && (entry.score ?? 0) >= 80
         && entry.findingCount === 0
         && passedCategories.has(entry.category));
     /**
@@ -192,9 +193,11 @@ function buildExecutiveSummary(args) {
         }
         return `${label}: ${entry.findingCount} ${entry.findingCount === 1 ? 'issue' : 'issues'} to address`;
     });
-    const scoreExplanation = args.profile
-        ? `${args.observedScore} of 100 on what the code does today, ${args.overallScore} of 100 once measured against what ${args.profile.profileTitle} normally requires.`
-        : `${args.observedScore} of 100 on what the code does today, with no product expectations applied.`;
+    const scoreExplanation = args.overallScore === null
+        ? `Not scored. ${args.inconclusiveReasons?.[0] ?? 'Too little of this repository could be read to characterise it.'}`
+        : args.profile
+            ? `${args.observedScore} of 100 on what the code does today, ${args.overallScore} of 100 once measured against what ${args.profile.profileTitle} normally requires.`
+            : `${args.observedScore} of 100 on what the code does today, with no product expectations applied.`;
     return {
         verdict,
         launchReady,

package/dist/report/markdownReport.js

@@ -40,9 +40,11 @@ function profileSummary(report) {
         `- Selected profile: ${profile.selectedProfile}`,
         `- Profile: ${profile.profileTitle}`,
         `- Description: ${profile.profileDescription}`,
-        `- Observed score: ${report.observedScore}/100`,
-        `- Expected capability score: ${report.expectedCapabilityScore}/100`,
-        `- Final score: ${report.overallScore}/100`,
+        report.observedScore === null ? '- Observed score: not scored' : `- Observed score: ${report.observedScore}/100`,
+        report.expectedCapabilityScore === undefined
+            ? '- Expected capability score: not measured'
+            : `- Expected capability score: ${report.expectedCapabilityScore}/100`,
+        report.overallScore === null ? '- Final score: not scored' : `- Final score: ${report.overallScore}/100`,
         '- Capability summary:',
         `- Required: ${requiredPresent} present / ${requiredMissing} missing / ${requiredPartial} partial`,
         `- Recommended: ${recommendedPresent} present / ${recommendedMissing} missing / ${recommendedPartial} partial`,
@@ -134,7 +136,7 @@ function categoryScoreSection(report) {
          */
         '| Area | Score | Verified | Open findings | Critical |',
         '| --- | --- | --- | --- | --- |',
-        ...assessed.map((entry) => `| ${entry.category} | ${entry.score}/100 | ${entry.verifiedCount} of ${entry.assessedCount} | ${entry.findingCount} | ${entry.criticalCount} |`),
+        ...assessed.map((entry) => `| ${entry.category} | ${entry.score === null ? 'not scored' : `${entry.score}/100`} | ${entry.verifiedCount} of ${entry.assessedCount} | ${entry.findingCount} | ${entry.criticalCount} |`),
         '',
     ];
 }
@@ -221,8 +223,8 @@ function renderMarkdown(report) {
         '',
         '## Score',
         '',
-        `- Overall score: ${report.overallScore}/100`,
-        `- Observed score: ${report.observedScore}/100`,
+        report.overallScore === null ? '- Overall score: not scored' : `- Overall score: ${report.overallScore}/100`,
+        report.observedScore === null ? '- Observed score: not scored' : `- Observed score: ${report.observedScore}/100`,
         ...(report.expectedCapabilityScore !== undefined ? [`- Expected capability score: ${report.expectedCapabilityScore}/100`] : []),
         `- Maturity level: ${report.maturityLevel}${report.inconclusive ? ' (inconclusive)' : ''}`,
         /**
@@ -233,12 +235,12 @@ function renderMarkdown(report) {
          * one of them rested on two verified checks while the other rested on twelve.
          */
         `- Verified: ${report.diagnostics.verifiedChecks} of ${report.diagnostics.assessedChecks} checks that reached a verdict`,
-        ...(report.overallScore > 84 && report.maturityLevel !== 'production_ready'
+        ...(report.overallScore !== null && report.overallScore > 84 && report.maturityLevel !== 'production_ready'
             ? ['- Note: the score is high because little was found, not because much was verified. Too few checks apply to this repository to call it production ready.']
             : []),
         ...(report.inconclusive
             ? [
-                '- Assessment: INCONCLUSIVE — the score is capped because the project could not be recognized:',
+                '- Assessment: INCONCLUSIVE — this report has no score, for these reasons:',
                 ...report.inconclusiveReasons.map((r) => `  - ${r}`),
             ]
             : []),

package/dist/report/types.d.ts

@@ -45,7 +45,16 @@ export interface Finding {
      */
     businessImpact?: string;
 }
-export type MaturityLevel = 'prototype' | 'early' | 'partial' | 'production_ready';
+/**
+ * `inconclusive` is a band of its own, not the bottom of the scale.
+ *
+ * A repository this analyzer could not read is not a prototype. It used to be called
+ * one, with a score of 39 beside it — the cap applied so that absence of findings
+ * could not be rewarded — and eleven repositories in the corpus came out at exactly
+ * 39: a wake-word engine, a database manager, an Advent of Code repository. One of
+ * them had no findings at all. The number was not measuring them; it was the cap.
+ */
+export type MaturityLevel = 'inconclusive' | 'prototype' | 'early' | 'partial' | 'production_ready';
 export type ExpectationMode = 'observed-only' | 'explicit-profile' | 'auto-applied' | 'auto-inconclusive';
 import type { LanguageReading } from '../analyzer/readingDepth';
 export interface ReportDiagnostics {
@@ -79,9 +88,15 @@ export interface ReportDiagnostics {
 export interface ProductionReadinessReport {
     projectPath: string;
     generatedAt: string;
-    observedScore: number;
+    /** `null` where the reading is inconclusive, for the same reason `overallScore` is. */
+    observedScore: number | null;
     expectedCapabilityScore?: number;
-    overallScore: number;
+    /**
+     * `null` where the reading is inconclusive, which is the same rule this product
+     * applies everywhere else: a number that was not measured is not reported. The
+     * reasons in `inconclusiveReasons` are the answer in its place.
+     */
+    overallScore: number | null;
     maturityLevel: MaturityLevel;
     inconclusive: boolean;
     inconclusiveReasons: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@produtype/core",
-  "version": "0.44.0",
+  "version": "0.46.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": {