@produtype/core 0.27.0 → 0.29.1

package/dist/analyzer/analyzeProject.js

@@ -144,6 +144,15 @@ function isTestOrExamplePath(file) {
     // as a marketplace taking a cut. A field set to null is evidence of absence.
     return /(^|\/)(__tests__|__mocks__|mocks?|tests?|test-data|fixtures|frontend-example)(\/|$)/i.test(file)
         || /(^|\/)test[-_][^/]+\.(ts|tsx|js|jsx|mjs|cjs|py)$/i.test(file)
+        /**
+         * The other half of the convention.
+         *
+         * `test_settings.py` was recognised and `settings_tests.py` was not, so a Django
+         * project's test configuration was read as production and its `STRIPE_SECRET_KEY =
+         * "sk_test_fake"` raised a critical — the severity that bars a report from the top
+         * band — against a line written to be fake.
+         */
+        || /[-_]tests?\.(ts|tsx|js|jsx|mjs|cjs|py)$/i.test(file)
         || /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs|py)$/i.test(file);
 }
 /**

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/dist/utils/fileScanner.d.ts

@@ -4,9 +4,6 @@ export interface ScanOptions {
     patterns?: string[];
     ignore?: string[];
 }
-/**
- * Scan files relative to a root project path. Returns paths relative to cwd.
- */
 export declare function scanFiles(opts: ScanOptions): Promise<string[]>;
 /**
  * Quick check: does at least one path matching glob exist?

package/dist/utils/fileScanner.js

@@ -49,6 +49,20 @@ exports.DEFAULT_IGNORE = [
     '**/coverage/**',
     '**/venv/**',
     '**/.venv/**',
+    /**
+     * Where Python puts what you installed, whatever the surrounding directory is called.
+     *
+     * `venv/` and `.venv/` were ignored by name, and a repository whose virtualenv was
+     * called `venv52/` had 7331 of its 8438 source files read as its own: botocore, boto3,
+     * the whole of pip's output. It produced a critical — `SECRET_KEY =
+     * 'AWS_SECRET_ACCESS_KEY'`, which is botocore naming an environment variable — against
+     * a project that had not written it.
+     *
+     * This is `node_modules` for Python, and like `node_modules` it cannot be anything
+     * else. The name of the virtualenv is a guess; `site-packages` is a fact.
+     */
+    '**/site-packages/**',
+    '**/dist-packages/**',
     '**/__pycache__/**',
     '**/.next/**',
     '**/.turbo/**',
@@ -124,6 +138,24 @@ exports.DEFAULT_IGNORE = [
 /**
  * Scan files relative to a root project path. Returns paths relative to cwd.
  */
+/**
+ * The file Python writes at the root of a virtualenv, and the only reliable way to
+ * recognise one.
+ *
+ * A virtualenv can be called anything: `venv52`, `env-3.11`, `.direnv`. Its scripts live
+ * in `bin/` and its packages in `lib/pythonX/site-packages/`, but the marker at the root
+ * is always this. Finding it means everything beside it was installed rather than
+ * written.
+ */
+const VIRTUALENV_MARKER = 'pyvenv.cfg';
+function withoutVirtualenvs(files) {
+    const roots = files
+        .filter((file) => file === VIRTUALENV_MARKER || file.endsWith(`/${VIRTUALENV_MARKER}`))
+        .map((file) => file.slice(0, file.length - VIRTUALENV_MARKER.length));
+    if (roots.length === 0)
+        return files;
+    return files.filter((file) => !roots.some((root) => root !== '' && file.startsWith(root)));
+}
 async function scanFiles(opts) {
     const patterns = opts.patterns ?? ['**/*'];
     const ignore = [...exports.DEFAULT_IGNORE, ...(opts.ignore ?? [])];
@@ -135,7 +167,7 @@ async function scanFiles(opts) {
         ignore,
         suppressErrors: true,
     });
-    return entries.map((e) => e.split(path.sep).join('/'));
+    return withoutVirtualenvs(entries.map((e) => e.split(path.sep).join('/')));
 }
 /**
  * Quick check: does at least one path matching glob exist?

package/package.json

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