@produtype/core 0.28.0 → 0.29.1

package/dist/analyzer/readingDepth.d.ts

@@ -0,0 +1,45 @@
+/**
+ * How closely this analyzer read each language it found.
+ *
+ * The product's whole argument is that it says only what it can show. It has been
+ * saying, with the same confidence in both cases, things it read from a syntax tree and
+ * things it guessed from a word — and the report gave a reader no way to tell which.
+ *
+ * Measured rather than asserted: 68 keyword searches against 1 structural claim, and 6
+ * of 18 readable extensions covered by a parser. A report on a Go project and a report
+ * on a TypeScript project looked equally sure of themselves, and were not.
+ *
+ * Three depths, in the order they deserve to be trusted:
+ *
+ * - `parsed`: a syntax tree answered the question. `{m.role === 'user' ? 'You' : 'Bot'}`
+ *   is a label and `if (!roles.includes(actor.role)) return res.status(403)` is a guard,
+ *   and nothing about the words tells them apart.
+ * - `searched`: the file was read as text and matched against keywords. Everything this
+ *   analyzer has always done, and where every defect of 18 September lived.
+ * - `skipped`: the language was seen and not read at all.
+ */
+export type ReadingDepth = 'parsed' | 'searched' | 'skipped';
+export interface LanguageReading {
+    language: string;
+    files: number;
+    depth: ReadingDepth;
+}
+/**
+ * What was read, and how, for every language present in the repository.
+ *
+ * Counts source files rather than all files: a language that appears only in an ignored
+ * directory was not read because it was not the project's, which is a different fact and
+ * one the reader does not need here.
+ */
+export declare function readingDepths(sourceFiles: string[], unreadable: Array<{
+    language: string;
+    files: number;
+}>): LanguageReading[];
+/**
+ * The sentence a reader needs, or nothing.
+ *
+ * Silent where everything was parsed: a report that congratulates itself on reading
+ * properly is noise. It speaks when some of the reading was shallower than the rest,
+ * which is the case that misleads.
+ */
+export declare function describeReadingDepth(readings: LanguageReading[]): string | undefined;

package/dist/analyzer/readingDepth.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readingDepths = readingDepths;
+exports.describeReadingDepth = describeReadingDepth;
+const catalogue_1 = require("./catalogue");
+/**
+ * The extensions a parser reads today.
+ *
+ * One list, so that adding Python to the structural layer changes what the report claims
+ * about Python in the same commit that makes it true. A second copy of this would drift
+ * within a week, which is the failure this file exists to stop somebody else making.
+ */
+const PARSED_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
+/** Languages whose files are read as text but never parsed. */
+function depthFor(files) {
+    if (files.length === 0)
+        return 'skipped';
+    return files.every((file) => PARSED_EXTENSIONS.test(file)) ? 'parsed' : 'searched';
+}
+/**
+ * What was read, and how, for every language present in the repository.
+ *
+ * Counts source files rather than all files: a language that appears only in an ignored
+ * directory was not read because it was not the project's, which is a different fact and
+ * one the reader does not need here.
+ */
+function readingDepths(sourceFiles, unreadable) {
+    const readings = [];
+    for (const { label, extensions } of catalogue_1.LANGUAGES) {
+        const files = sourceFiles.filter((file) => extensions.test(file));
+        if (files.length === 0)
+            continue;
+        readings.push({ language: label, files: files.length, depth: depthFor(files) });
+    }
+    for (const entry of unreadable) {
+        readings.push({ language: entry.language, files: entry.files, depth: 'skipped' });
+    }
+    return readings.sort((left, right) => right.files - left.files);
+}
+/**
+ * The sentence a reader needs, or nothing.
+ *
+ * Silent where everything was parsed: a report that congratulates itself on reading
+ * properly is noise. It speaks when some of the reading was shallower than the rest,
+ * which is the case that misleads.
+ */
+function describeReadingDepth(readings) {
+    const searched = readings.filter((entry) => entry.depth === 'searched');
+    const skipped = readings.filter((entry) => entry.depth === 'skipped');
+    if (searched.length === 0 && skipped.length === 0)
+        return undefined;
+    const parts = [];
+    if (searched.length > 0) {
+        parts.push(`${searched.map((entry) => entry.language).join(', ')} ${searched.length === 1 ? 'was' : 'were'} read as text and matched against keywords, not parsed`);
+    }
+    if (skipped.length > 0) {
+        parts.push(`${skipped.map((entry) => `${entry.language} (${entry.files} files)`).join(', ')} not read at all`);
+    }
+    return `How this repository was read: ${parts.join('; ')}. A keyword can appear in a comment, a test fixture or a variable name, so findings in those languages rest on weaker evidence than the ones this analyzer parsed.`;
+}

package/dist/report/buildReport.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildReport = buildReport;
 const ruleEngine_1 = require("../rules/ruleEngine");
+const readingDepth_1 = require("../analyzer/readingDepth");
 const score_1 = require("./score");
 const types_1 = require("./types");
 const evaluateExpectations_1 = require("../expectations/evaluateExpectations");
@@ -296,6 +297,12 @@ function buildReport(analysis, options) {
         // to know that one rests on seventeen verdicts and the other on nine.
         assessedChecks,
         verifiedChecks: passedChecksForMaturity,
+        /**
+         * How closely each language was read, so a reader can weigh a finding by more than
+         * its severity. A keyword match in Go and a parsed guard in TypeScript were being
+         * presented with the same confidence.
+         */
+        readingDepth: (0, readingDepth_1.readingDepths)(analysis.files.source, analysis.files.unreadable),
         detectors: detectorDiagnostics(analysis),
         selectedProfile: requestedProfile,
         inferredProfile: productProfile?.inferredProfile,

package/dist/report/markdownReport.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderMarkdown = renderMarkdown;
+const readingDepth_1 = require("../analyzer/readingDepth");
 function profileSummary(report) {
     const profile = report.productProfile;
     if (!profile) {
@@ -242,6 +243,16 @@ function renderMarkdown(report) {
             ]
             : []),
         `- Diagnostics: ${report.diagnostics.analyzedFileCount} analyzed / ${report.diagnostics.skippedFileCount} skipped / ${report.diagnostics.workspaceCount} workspaces / ${report.diagnostics.detectorCount} detectors`,
+        /**
+         * How the code was read, beside how much of it there was.
+         *
+         * A keyword match in Go and a parsed guard in TypeScript were printed with the same
+         * confidence, and nothing in the report distinguished them. Silent when everything
+         * was parsed: a report congratulating itself on reading properly is noise.
+         */
+        ...((0, readingDepth_1.describeReadingDepth)(report.diagnostics.readingDepth)
+            ? [`- ${(0, readingDepth_1.describeReadingDepth)(report.diagnostics.readingDepth)}`]
+            : []),
         `- Expectation mode: ${report.diagnostics.expectationMode}`,
         `- ProdKit version: ${report.diagnostics.prodkitVersion}`,
         `- Detector diagnostics: ${report.diagnostics.detectors.filter((d) => d.status === 'completed').length} completed / ${report.diagnostics.detectors.filter((d) => d.status === 'skipped').length} skipped`,

package/dist/report/types.d.ts

@@ -47,6 +47,7 @@ export interface Finding {
 }
 export type MaturityLevel = '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 {
     analyzedFileCount: number;
     skippedFileCount: number;
@@ -56,6 +57,14 @@ export interface ReportDiagnostics {
     assessedChecks: number;
     /** Of those, the ones that ran and found what they were looking for. */
     verifiedChecks: number;
+    /**
+     * How closely each language present was read.
+     *
+     * A finding matched from a keyword in Go and a finding read from a syntax tree in
+     * TypeScript were presented with identical confidence. They are not the same kind of
+     * fact, and the reader is entitled to know which one they have.
+     */
+    readingDepth: LanguageReading[];
     detectors: Array<{
         id: string;
         status: 'completed' | 'skipped';

package/package.json

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