@produtype/core 0.45.0 → 0.47.0

package/dist/report/buildReport.js

@@ -287,6 +287,15 @@ function buildReport(analysis, options) {
     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);
@@ -334,7 +343,7 @@ function buildReport(analysis, options) {
         categoryScores,
         profile: productProfile,
         maturity: maturityLevel,
-        observedScore,
+        observedScore: reportedObservedScore,
         overallScore,
         inconclusive,
         inconclusiveReasons,
@@ -365,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/complianceMapping.d.ts

@@ -9,8 +9,28 @@ export interface ComplianceReference {
 export interface ComplianceObligation extends ComplianceReference {
     /** Findings that leave this obligation unmet. */
     findingIds: string[];
+    /**
+     * `unknown` where every check behind this obligation came back `unknown`.
+     *
+     * This was a boolean, and `met` was the default: an obligation whose only supporting
+     * check could not reach a verdict was reported as satisfied. Measured across
+     * seventy-eight repositories, 84 of 163 obligations marked met rested on not one
+     * passing check — most of them OWASP A01, broken access control, declared met
+     * because a single check said it did not know.
+     *
+     * The comment on the builder already stated the principle and the code applied it
+     * only halfway: it omitted obligations that nothing mapped to, and marked met the
+     * ones that mapped to silence.
+     */
+    status: 'met' | 'unmet' | 'unknown';
+    /** @deprecated Read `status`. True only where `status` is `met`. */
     met: boolean;
 }
+/**
+ * Exported so a test can ask the same question the builder asks, rather than keeping
+ * a second copy of the prefix table that would drift from this one.
+ */
+export declare function referencesFor(finding: Finding): ComplianceReference[];
 /**
  * Returns every obligation touched by the analysis, marking as unmet those with at
  * least one actionable finding attached. An obligation nothing mapped to is omitted

package/dist/report/complianceMapping.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.referencesFor = referencesFor;
 exports.buildComplianceMapping = buildComplianceMapping;
 /**
  * Maps findings onto the obligations a reader has to answer to.
@@ -82,6 +83,10 @@ const RULES = [
         references: [{ framework: 'owasp-top-10', reference: 'A08', title: 'Software and data integrity failures' }],
     },
 ];
+/**
+ * Exported so a test can ask the same question the builder asks, rather than keeping
+ * a second copy of the prefix table that would drift from this one.
+ */
 function referencesFor(finding) {
     for (const rule of RULES) {
         if (finding.id.startsWith(rule.prefix))
@@ -108,15 +113,39 @@ function buildComplianceMapping(findings) {
                 obligations.set(key, {
                     ...reference,
                     findingIds: actionable ? [finding.id] : [],
-                    met: !actionable,
+                    status: 'unknown',
+                    met: false,
+                    verified: finding.status === 'passed',
                 });
                 continue;
             }
-            if (actionable) {
+            if (actionable)
                 existing.findingIds.push(finding.id);
-                existing.met = false;
-            }
+            if (finding.status === 'passed')
+                existing.verified = true;
         }
     }
-    return [...obligations.values()].sort((left, right) => left.framework.localeCompare(right.framework) || left.reference.localeCompare(right.reference));
+    /**
+     * An obligation is met when something was checked and found right.
+     *
+     * Three outcomes, because the reader needs to tell them apart before quoting any of
+     * this to an auditor: something is wrong here, something was verified here, and
+     * nothing here reached a verdict.
+     */
+    for (const obligation of obligations.values()) {
+        obligation.status = obligation.findingIds.length > 0
+            ? 'unmet'
+            : obligation.verified ? 'met' : 'unknown';
+        obligation.met = obligation.status === 'met';
+    }
+    return [...obligations.values()]
+        .map((obligation) => ({
+        framework: obligation.framework,
+        reference: obligation.reference,
+        title: obligation.title,
+        findingIds: obligation.findingIds,
+        status: obligation.status,
+        met: obligation.met,
+    }))
+        .sort((left, right) => left.framework.localeCompare(right.framework) || left.reference.localeCompare(right.reference));
 }

package/dist/report/executiveSummary.d.ts

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

package/dist/report/executiveSummary.js

@@ -158,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));
     /**

package/dist/report/markdownReport.js

@@ -40,8 +40,10 @@ function profileSummary(report) {
         `- Selected profile: ${profile.selectedProfile}`,
         `- Profile: ${profile.profileTitle}`,
         `- Description: ${profile.profileDescription}`,
-        `- Observed score: ${report.observedScore}/100`,
-        `- Expected capability score: ${report.expectedCapabilityScore}/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`,
@@ -134,25 +136,47 @@ 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} |`),
         '',
     ];
 }
 function complianceSection(report) {
     if (report.compliance.length === 0)
         return [];
-    const unmet = report.compliance.filter((obligation) => !obligation.met);
-    if (unmet.length === 0)
+    /**
+     * Exposure and silence, listed apart.
+     *
+     * This filtered on `!met`, which was two different things wearing one label: an
+     * obligation with findings against it, and an obligation whose every check came
+     * back unknown. The second was printed under "Compliance Exposure" with a findings
+     * count of zero — a reader would quote that to an auditor as a gap when it is the
+     * absence of an answer.
+     */
+    const unmet = report.compliance.filter((obligation) => obligation.status === 'unmet');
+    const unassessed = report.compliance.filter((obligation) => obligation.status === 'unknown');
+    if (unmet.length === 0 && unassessed.length === 0)
         return [];
     return [
         '## Compliance Exposure',
         '',
         '_Advisory mapping, not a compliance certification. Obligations nothing mapped to are omitted rather than reported as met._',
         '',
-        '| Framework | Reference | Obligation | Findings |',
-        '| --- | --- | --- | --- |',
-        ...unmet.map((obligation) => `| ${obligation.framework} | ${obligation.reference} | ${obligation.title} | ${obligation.findingIds.length} |`),
-        '',
+        ...(unmet.length > 0
+            ? [
+                '| Framework | Reference | Obligation | Findings |',
+                '| --- | --- | --- | --- |',
+                ...unmet.map((obligation) => `| ${obligation.framework} | ${obligation.reference} | ${obligation.title} | ${obligation.findingIds.length} |`),
+                '',
+            ]
+            : ['No obligation in this mapping has a finding against it.', '']),
+        ...(unassessed.length > 0
+            ? [
+                `Not assessed — every check behind these came back unknown, so this report says nothing either way about ${unassessed.length === 1 ? 'it' : 'them'}:`,
+                '',
+                ...unassessed.map((obligation) => `- ${obligation.framework} ${obligation.reference}: ${obligation.title}`),
+                '',
+            ]
+            : []),
     ];
 }
 function renderMarkdown(report) {
@@ -222,7 +246,7 @@ function renderMarkdown(report) {
         '## Score',
         '',
         report.overallScore === null ? '- Overall score: not scored' : `- Overall score: ${report.overallScore}/100`,
-        `- Observed score: ${report.observedScore}/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)' : ''}`,
         /**
@@ -238,7 +262,7 @@ function renderMarkdown(report) {
             : []),
         ...(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

@@ -88,7 +88,8 @@ 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;
     /**
      * `null` where the reading is inconclusive, which is the same rule this product

package/package.json

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