@produtype/core 0.72.0 → 0.73.0

package/dist/analyzer/analyzeProject.js

@@ -65,6 +65,7 @@ const detectNotifications_1 = require("./detectNotifications");
 const detectDeployment_1 = require("./detectDeployment");
 const detectStack_1 = require("./detectStack");
 const promises_1 = require("node:fs/promises");
+const loadTypeScript_1 = require("./structural/loadTypeScript");
 const packageJsonSchema = zod_1.z
     .object({
     name: zod_1.z.string().optional(),
@@ -841,6 +842,7 @@ async function analyzeProject(projectPath) {
     return {
         projectPath: root,
         scannedAt: new Date().toISOString(),
+        parsedStructure: await (0, loadTypeScript_1.typeScriptIsAvailable)(),
         stack: (0, detectStack_1.buildStackInfo)({
             frontend: frontend.frameworks,
             backend: backend.frameworks,

package/dist/analyzer/readingDepth.d.ts

@@ -34,12 +34,19 @@ export interface LanguageReading {
 export declare function readingDepths(sourceFiles: string[], unreadable: Array<{
     language: string;
     files: number;
-}>): LanguageReading[];
+}>, parserAvailable: boolean): 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.
+ *
+ * `parserAvailable` separates two shallow readings that look identical in the list and
+ * are not. Go is searched because nothing here will ever parse Go, and a reader can do
+ * nothing about it. JavaScript is searched only when the optional compiler is missing,
+ * and installing it changes the answer — on the fixture corpus, seven repositories of a
+ * hundred and thirty-three answer differently. Telling a reader to install a package is
+ * worth a clause; telling them their Go is read by keyword is worth a different one.
  */
-export declare function describeReadingDepth(readings: LanguageReading[]): string | undefined;
+export declare function describeReadingDepth(readings: LanguageReading[], parserAvailable: boolean): string | undefined;

package/dist/analyzer/readingDepth.js

@@ -11,10 +11,25 @@ const catalogue_1 = require("./catalogue");
  * 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) {
+/**
+ * The catalogue labels those extensions carry, so the missing-compiler clause fires for
+ * the languages it can actually do something about and stays quiet on a Go repository.
+ */
+const PARSED_EXTENSIONS_LANGUAGES = new Set(catalogue_1.LANGUAGES.filter(({ extensions }) => ['a.ts', 'a.tsx', 'a.js', 'a.jsx', 'a.mjs', 'a.cjs'].some((name) => extensions.test(name))).map(({ label }) => label));
+/**
+ * Languages whose files are read as text but never parsed.
+ *
+ * The extension says a parser *could* read this file; `parserAvailable` says one
+ * actually did. The optional TypeScript peer is absent on any machine that installed
+ * this package without it — `npx prodkit` against a repository is the ordinary case —
+ * and until this argument existed the report claimed `parsed` there just the same, on
+ * the strength of the file name.
+ */
+function depthFor(files, parserAvailable) {
     if (files.length === 0)
         return 'skipped';
+    if (!parserAvailable)
+        return 'searched';
     return files.every((file) => PARSED_EXTENSIONS.test(file)) ? 'parsed' : 'searched';
 }
 /**
@@ -24,13 +39,13 @@ function depthFor(files) {
  * 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) {
+function readingDepths(sourceFiles, unreadable, parserAvailable) {
     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) });
+        readings.push({ language: label, files: files.length, depth: depthFor(files, parserAvailable) });
     }
     for (const entry of unreadable) {
         readings.push({ language: entry.language, files: entry.files, depth: 'skipped' });
@@ -43,8 +58,15 @@ function readingDepths(sourceFiles, unreadable) {
  * 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.
+ *
+ * `parserAvailable` separates two shallow readings that look identical in the list and
+ * are not. Go is searched because nothing here will ever parse Go, and a reader can do
+ * nothing about it. JavaScript is searched only when the optional compiler is missing,
+ * and installing it changes the answer — on the fixture corpus, seven repositories of a
+ * hundred and thirty-three answer differently. Telling a reader to install a package is
+ * worth a clause; telling them their Go is read by keyword is worth a different one.
  */
-function describeReadingDepth(readings) {
+function describeReadingDepth(readings, parserAvailable) {
     const searched = readings.filter((entry) => entry.depth === 'searched');
     const skipped = readings.filter((entry) => entry.depth === 'skipped');
     if (searched.length === 0 && skipped.length === 0)
@@ -56,5 +78,14 @@ function describeReadingDepth(readings) {
     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.`;
+    const missingParser = !parserAvailable && readings.some((entry) => PARSED_EXTENSIONS_LANGUAGES.has(entry.language));
+    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.',
+        ...(missingParser
+            ? [
+                'The optional `typescript` peer dependency is not installed, so no JavaScript or TypeScript was parsed here either: every structural question — which literal reaches a signing call, whether a comparison guards a route or picks a label — went unasked. Install it alongside this package and re-run to get those answers.',
+            ]
+            : []),
+    ].join(' ');
 }

package/dist/analyzer/structural/loadTypeScript.d.ts

@@ -2,3 +2,14 @@ import type * as TypeScriptApi from 'typescript';
 export declare function loadTypeScript(): Promise<typeof TypeScriptApi | null>;
 /** For tests that need to observe both paths without reinstalling anything. */
 export declare function resetTypeScriptCache(): void;
+/**
+ * Whether the parser is there, for the report rather than for a reader.
+ *
+ * `readingDepths` printed `parsed` for every `.ts` and `.js` file on the strength of the
+ * extension alone, and said nothing when everything was parsed — so on a machine without
+ * the optional compiler the report was silent in exactly the case it needed to speak.
+ * Measured on the fixture corpus: seven of a hundred and thirty-three repositories
+ * answer differently with the compiler hidden, and one of them reports a hardcoded
+ * signing secret as `passed`.
+ */
+export declare function typeScriptIsAvailable(): Promise<boolean>;

package/dist/analyzer/structural/loadTypeScript.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadTypeScript = loadTypeScript;
 exports.resetTypeScriptCache = resetTypeScriptCache;
+exports.typeScriptIsAvailable = typeScriptIsAvailable;
 /**
  * The TypeScript compiler, loaded when something needs to read structure rather than text.
  *
@@ -39,3 +40,16 @@ async function loadTypeScript() {
 function resetTypeScriptCache() {
     cached = undefined;
 }
+/**
+ * Whether the parser is there, for the report rather than for a reader.
+ *
+ * `readingDepths` printed `parsed` for every `.ts` and `.js` file on the strength of the
+ * extension alone, and said nothing when everything was parsed — so on a machine without
+ * the optional compiler the report was silent in exactly the case it needed to speak.
+ * Measured on the fixture corpus: seven of a hundred and thirty-three repositories
+ * answer differently with the compiler hidden, and one of them reports a hardcoded
+ * signing secret as `passed`.
+ */
+async function typeScriptIsAvailable() {
+    return (await loadTypeScript()) !== null;
+}

package/dist/analyzer/types.d.ts

@@ -117,4 +117,12 @@ export interface ProjectAnalysis {
     workspaceStacks: WorkspaceStack[];
     files: ProjectFiles;
     detectors: Record<string, DetectorResult>;
+    /**
+     * Whether the optional TypeScript compiler was there while the detectors ran.
+     *
+     * Carried on the analysis rather than asked for at report time, because it is a fact
+     * about this reading and not about the machine printing it: the report's claim of how
+     * deeply it read has to match what the detectors were actually able to do.
+     */
+    parsedStructure: boolean;
 }

package/dist/report/buildReport.js

@@ -373,7 +373,8 @@ function buildReport(analysis, options) {
          * 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),
+        readingDepth: (0, readingDepth_1.readingDepths)(analysis.files.source, analysis.files.unreadable, analysis.parsedStructure),
+        parsedStructure: analysis.parsedStructure,
         detectors: detectorDiagnostics(analysis),
         selectedProfile: requestedProfile,
         inferredProfile: productProfile?.inferredProfile,

package/dist/report/markdownReport.js

@@ -274,8 +274,8 @@ function renderMarkdown(report) {
          * 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)}`]
+        ...((0, readingDepth_1.describeReadingDepth)(report.diagnostics.readingDepth, report.diagnostics.parsedStructure)
+            ? [`- ${(0, readingDepth_1.describeReadingDepth)(report.diagnostics.readingDepth, report.diagnostics.parsedStructure)}`]
             : []),
         `- Expectation mode: ${report.diagnostics.expectationMode}`,
         `- ProdKit version: ${report.diagnostics.prodkitVersion}`,

package/dist/report/types.d.ts

@@ -74,6 +74,14 @@ export interface ReportDiagnostics {
      * fact, and the reader is entitled to know which one they have.
      */
     readingDepth: LanguageReading[];
+    /**
+     * Whether the optional TypeScript compiler was loaded for this reading.
+     *
+     * Two readings with the same `readingDepth` list are not the same reading: JavaScript
+     * shows as `searched` only when the compiler was missing, and that is the one a reader
+     * can fix.
+     */
+    parsedStructure: boolean;
     detectors: Array<{
         id: string;
         status: 'completed' | 'skipped';

package/package.json

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