@produtype/core 0.19.1 → 0.21.0

package/dist/analyzer/analyzeProject.js

@@ -652,8 +652,16 @@ async function analyzeProject(projectPath) {
                 // Said out loud, because a dependency nobody declared is a weaker fact than one
                 // that is pinned in a lockfile, and the reader is entitled to know which of the
                 // two this reading rests on.
+                /**
+                 * Which manifest was missing, not "a manifest".
+                 *
+                 * "No dependency manifest was found: dependencies were read from Python imports"
+                 * was printed for a Flutter application with a `pubspec.yaml` in its root — the
+                 * same file the analyzer had just read to identify Flutter. The sentence is about
+                 * the Python and browser dependency lists specifically, so it says so.
+                 */
                 ...(inferredDependencySources.length > 0
-                    ? [`No dependency manifest was found: dependencies were read from ${inferredDependencySources.join(' and ')}, so versions are unknown.`]
+                    ? [`Some dependencies were read from ${inferredDependencySources.join(' and ')} rather than from a manifest, so their versions are unknown.`]
                     : []),
             ],
             workspaces: workspaceStacks,

package/dist/analyzer/detectPackageManager.js

@@ -1,6 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectPackageManager = detectPackageManager;
+/**
+ * Manifests outside Node and Python, each one a file this analyzer already parses.
+ *
+ * Order matters only where two can coexist: a Gradle build with a `pom.xml` beside it is
+ * built by Gradle, and a `.csproj` next to a `packages.config` is NuGet either way.
+ *
+ * Read from the file list rather than from the workspace record, because the workspace
+ * record was built for Node and Python and knows nothing about these — which is the
+ * reason a Flutter project came out as `unknown` in the first place.
+ */
+const OTHER_MANIFESTS = [
+    { manager: 'pub', pattern: /(^|\/)pubspec\.yaml$/ },
+    { manager: 'composer', pattern: /(^|\/)composer\.json$/ },
+    { manager: 'go modules', pattern: /(^|\/)go\.mod$/ },
+    { manager: 'bundler', pattern: /(^|\/)Gemfile$/ },
+    { manager: 'gradle', pattern: /(^|\/)build\.gradle(\.kts)?$/ },
+    { manager: 'maven', pattern: /(^|\/)pom\.xml$/ },
+    { manager: 'nuget', pattern: /\.(csproj|fsproj|vbproj)$/i },
+];
+function resolveFromOtherManifests(files) {
+    for (const { manager, pattern } of OTHER_MANIFESTS) {
+        const match = files.find((file) => pattern.test(file));
+        if (match)
+            return { manager, confidence: 'manifest', warnings: [], evidence: [match] };
+    }
+    return null;
+}
 function resolveWorkspaceManager(workspace) {
     const warnings = [];
     if (workspace.lockfiles.includes('pnpm-lock.yaml')) {
@@ -39,7 +66,12 @@ async function detectPackageManager(ctx) {
         };
     });
     const rootWorkspace = workspaceManagers.find((w) => w.root === '.');
-    const selected = rootWorkspace ?? workspaceManagers.find((w) => w.manager !== 'unknown');
+    const fromWorkspaces = rootWorkspace ?? workspaceManagers.find((w) => w.manager !== 'unknown');
+    // Node and Python first, because the workspace record is built from their manifests and
+    // knows which of several it found. Anything else is resolved from the file list.
+    const selected = fromWorkspaces && fromWorkspaces.manager !== 'unknown'
+        ? fromWorkspaces
+        : resolveFromOtherManifests(ctx.files.all) ?? fromWorkspaces;
     if (selected) {
         return {
             manager: selected.manager,

package/dist/analyzer/types.d.ts

@@ -1,4 +1,16 @@
-export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'pip' | 'poetry' | 'python' | 'unknown';
+/**
+ * The names this tool can put to how a project declares its dependencies.
+ *
+ * It held seven, all of them Node or Python, so a Flutter application with a
+ * `pubspec.yaml` in its root reported "Package manager: unknown (unknown)" — in the
+ * same summary that had just read that file to identify Flutter. Five of the
+ * seventy-eight repositories in the verification corpus were in that position, across
+ * Dart, PHP, Kotlin and C#.
+ *
+ * Only managers whose manifest this analyzer actually reads are named here. A name it
+ * cannot back with a parsed file would be a guess from a filename.
+ */
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'pip' | 'poetry' | 'python' | 'pub' | 'composer' | 'go modules' | 'bundler' | 'gradle' | 'maven' | 'nuget' | 'unknown';
 export type PackageManagerConfidence = 'lockfile' | 'manifest' | 'inferred' | 'unknown';
 export interface WorkspaceStack {
     root: string;

package/dist/cli.js

@@ -42,10 +42,20 @@ const buildReport_1 = require("./report/buildReport");
 const markdownReport_1 = require("./report/markdownReport");
 const jsonReport_1 = require("./report/jsonReport");
 const buildPlan_1 = require("./planner/buildPlan");
+const productProfiles_1 = require("./expectations/productProfiles");
 const markdownPlan_1 = require("./planner/markdownPlan");
 const jsonPlan_1 = require("./planner/jsonPlan");
 const pathUtils_1 = require("./utils/pathUtils");
 const version_1 = require("./version");
+/**
+ * The profiles this tool actually has, read from the same table the analyzer uses.
+ *
+ * The list was typed out by hand and named eight of them: `library`, `game`,
+ * `client-app` and `mobile-app` had been added since, so a user asking `--help` which
+ * profiles exist was told four fewer than they could pass — including every profile that
+ * covers something other than a web application.
+ */
+const PROFILE_OPTION_LIST = (0, productProfiles_1.productProfileChoices)().map((choice) => choice.id).join('|');
 const allowedProfiles = ['observed-only', 'static-site', 'internal-tool', 'b2c-app', 'b2b-saas', 'ai-saas', 'marketplace', 'game', 'client-app', 'mobile-app', 'library', 'auto'];
 const maturityOrder = ['prototype', 'early', 'partial', 'production_ready'];
 function normalizeProfile(profile) {
@@ -128,7 +138,15 @@ function summarize(report) {
         report.detectedStack.warnings.length > 0 ? `Warnings: ${report.detectedStack.warnings.join('; ')}` : 'Warnings: none',
         `Workspaces: ${workspaceSummary}`,
         `Score: ${report.overallScore}/100`,
-        `Maturity: ${report.maturityLevel}${report.inconclusive ? ' (INCONCLUSIVE: project not recognized, score capped)' : ''}`,
+        /**
+         * The reasons, not a verdict about the project.
+         *
+         * This said "project not recognized" whatever the cause, two lines under
+         * "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}`) : []),
         // 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
@@ -211,9 +229,10 @@ async function runCli(argv = process.argv) {
         .version(version_1.PRODKit_VERSION);
     program
         .command('analyze')
+        .description('Read a repository and report what production would demand of it.')
         .argument('<path-to-project>', 'Path to target repository')
         .option('--format <format>', 'Output format: markdown|json')
-        .option('--profile <profile>', 'Product profile: observed-only|static-site|internal-tool|b2c-app|b2b-saas|ai-saas|marketplace|auto')
+        .option('--profile <profile>', `Product profile: ${PROFILE_OPTION_LIST}`)
         .option('--summary', 'Print summary only')
         .option('--output <path>', 'Output file path (optional)')
         .option('--fail-under <score>', 'Exit with an error if overall score is below this threshold (0-100)')
@@ -247,9 +266,10 @@ async function runCli(argv = process.argv) {
     });
     program
         .command('plan')
+        .description('Turn a report into an ordered list of remediation tasks.')
         .argument('<path-to-project>', 'Path to target repository')
         .option('--format <format>', 'Output format: markdown|json')
-        .option('--profile <profile>', 'Product profile: observed-only|static-site|internal-tool|b2c-app|b2b-saas|ai-saas|marketplace|auto')
+        .option('--profile <profile>', `Product profile: ${PROFILE_OPTION_LIST}`)
         .option('--summary', 'Print summary only')
         .option('--output <path>', 'Output file path (optional)')
         .action(async (targetPath, options) => {

package/dist/report/buildReport.js

@@ -154,7 +154,21 @@ function buildReport(analysis, options) {
      * verdicts or fewer and thirty reach ten or more; not one lands in between. Four
      * verdicts cannot characterise a product, however many files it has.
      */
-    const tooLittleAssessed = assessedChecks < score_1.MIN_ASSESSED_FOR_A_READING;
+    /**
+     * Only where the analysis was asked for a full reading.
+     *
+     * In observed-only mode nothing but the rules runs, and a small project reaches three
+     * or four verdicts because the expectations that would produce the rest were never
+     * requested — not because it is unreadable. The command-line tool defaults to that
+     * mode, and this rule, written against the profile path, turned twenty-three of its
+     * reports into "project not recognized": a Flutter application, a Vue application, a
+     * .NET game, each of them named on the line above by the same summary.
+     *
+     * Found by running the tool the way somebody who installed it would, rather than by
+     * calling the API the way the tests do.
+     */
+    const tooLittleAssessed = requestedProfile !== 'observed-only'
+        && assessedChecks < score_1.MIN_ASSESSED_FOR_A_READING;
     const inconclusive = nothingIdentified || tooLittleAssessed;
     // Each reason says which of the two it was, because they call for different things:
     // one is a repository this analyzer cannot read, the other is one there is barely

package/dist/rules/rules.js

@@ -203,9 +203,24 @@ exports.rules = [
                 category: 'env',
                 status,
                 severity: sevForStatus(status, 'medium'),
+                /**
+                 * One sentence per answer.
+                 *
+                 * "Environment template looks available or env usage was not detected" is two
+                 * different findings sharing a line, and sixty-two of the seventy-eight
+                 * repositories in the corpus were shown it: nineteen that have a template, and
+                 * forty-three that read no environment variables at all. A reader cannot tell
+                 * which one they are, and those call for opposite actions — one is done, the
+                 * other was never asked.
+                 *
+                 * The status already knew. This is the same mistake the privacy check was
+                 * corrected for, still being made one rule above it.
+                 */
                 description: missing
                     ? 'The project reads environment variables but no .env.example was detected.'
-                    : 'Environment template looks available or env usage was not detected.',
+                    : status === 'passed'
+                        ? 'An environment template is present alongside the variables this project reads.'
+                        : 'Nothing here reads environment variables, so there is no template to check.',
                 recommendation: 'Provide a safe .env.example containing required keys and no secrets.',
                 evidence: det?.evidence ?? [],
             });
@@ -338,7 +353,19 @@ exports.rules = [
                 category: 'security',
                 status,
                 severity: sevForStatus(status, 'medium'),
-                description: hasRate ? 'Rate limiting signals detected.' : 'No auth-focused rate limiting detected.',
+                /**
+                 * `unknown` here means the check does not apply — this detector only reads
+                 * Express middleware, and a Django project has rate limiting somewhere it cannot
+                 * see. Saying "no rate limiting detected" for that is reporting the analyzer's
+                 * blind spot as the project's gap.
+                 */
+                description: status === 'passed'
+                    ? 'Rate limiting signals detected on the authentication surface.'
+                    : status === 'missing'
+                        ? 'No auth-focused rate limiting detected.'
+                        : !hasAuth
+                            ? 'Nothing here authenticates anybody, so there is no login surface to throttle.'
+                            : 'This check reads Express middleware, and this project does not use it — any throttling it has is somewhere this cannot see.',
                 recommendation: 'Apply express-rate-limit (or equivalent) to login/register/password reset endpoints.',
                 /**
                  * The claim is about rate limiting, so the evidence is about rate limiting.
@@ -453,7 +480,9 @@ exports.rules = [
                     ? 'Uploads look publicly exposed without auth checks.'
                     : status === 'partial'
                         ? 'Uploads are exposed and some auth signals exist, review route protection.'
-                        : 'No obvious public upload exposure signal detected.',
+                        : status === 'passed'
+                            ? 'Upload handling was found, and none of it is publicly exposed.'
+                            : 'No upload handling was found in this repository.',
                 recommendation: 'Protect upload routes with authz, validate MIME/type, and prefer private object storage.',
                 evidence: up?.evidence ?? [],
             });
@@ -475,7 +504,13 @@ exports.rules = [
                 category: 'auth',
                 status,
                 severity: sevForStatus(status, 'medium'),
-                description: status === 'missing' ? 'No clear authentication signals detected.' : 'Authentication signals detected.',
+                description: status === 'missing'
+                    ? 'No clear authentication signals detected.'
+                    : status === 'unknown'
+                        ? 'Nothing in this repository serves requests or holds accounts, so there is nobody here to authenticate.'
+                        : status === 'partial'
+                            ? 'Authentication signals detected, but not a complete flow.'
+                            : 'Authentication signals detected.',
                 recommendation: 'Implement robust auth flow and secure credential handling.',
                 evidence: auth?.evidence ?? [],
             });
@@ -515,7 +550,11 @@ exports.rules = [
                     ? 'Permission-level authorization signals detected.'
                     : status === 'partial'
                         ? 'Only basic role checks detected.'
-                        : 'No resource-level authorization signals detected.',
+                        : status === 'missing'
+                            ? 'No resource-level authorization signals detected.'
+                            : !hasAuth
+                                ? 'Nothing here authenticates anybody, so there are no callers to authorize.'
+                                : 'Nothing in this repository serves requests, so there are no records to guard.',
                 recommendation: 'Add policy/resource-level checks beyond coarse role gates.',
                 evidence: [...(roles?.evidence ?? []), ...(permissions?.evidence ?? []), ...(resourceLevel?.evidence ?? [])],
             });
@@ -598,9 +637,15 @@ exports.rules = [
                 category: 'gdpr',
                 status,
                 severity: sevForStatus(status, 'medium'),
-                description: hasUsers && !hasGdpr
+                description: status === 'missing'
                     ? 'Auth/users signals found but no GDPR/privacy controls detected.'
-                    : 'Privacy/GDPR signals detected or not applicable from available evidence.',
+                    : status === 'passed'
+                        ? 'Consent, export, erasure or retention controls detected.'
+                        : hasGdpr
+                            ? 'Privacy controls were found, but nothing here serves requests or holds accounts for them to apply to.'
+                            : !hasUserFacingSurface(analysis)
+                                ? 'Nothing in this repository serves requests or holds accounts, so there is no personal data flow here to check.'
+                                : 'No accounts or user records were detected, so there is nothing here for these duties to attach to.',
                 recommendation: 'Implement consent, export/erasure workflows, and retention policies.',
                 evidence: [
                     ...(consent?.evidence ?? []),
@@ -771,7 +816,9 @@ exports.rules = [
                     ? 'Nothing in this repository is deployed as a running service, so how it reaches people — a registry, a store, a host — is decided outside it.'
                     : status === 'missing'
                         ? 'No meaningful deployment artifacts or prod/runtime signals detected.'
-                        : 'Deployment artifacts or runtime production signals detected.',
+                        : status === 'partial'
+                            ? 'Deployment artifacts detected, but the production-aware runtime settings are incomplete.'
+                            : 'Deployment artifacts and production-aware runtime settings detected.',
                 /**
                  * Graceful shutdown is left out where there is no signal to catch: PHP-FPM and
                  * CGI hand each request to a worker that exits when it is done, and telling a
@@ -814,11 +861,13 @@ exports.rules = [
                 category: 'deployment',
                 status,
                 severity: sevForStatus(status, 'low'),
-                description: docker?.present
-                    ? 'Docker signals found.'
-                    : containerisable
-                        ? 'No Docker artifacts found.'
-                        : 'Nothing here is deployed as a container.',
+                description: status === 'passed'
+                    ? 'A Dockerfile and a compose file were found.'
+                    : status === 'partial'
+                        ? 'Docker artifacts were found, but not the whole set — a Dockerfile without a compose file, or the reverse.'
+                        : containerisable
+                            ? 'No Docker artifacts found.'
+                            : 'Nothing here is deployed as a container.',
                 recommendation: containerisable ? 'Provide Dockerfile and healthchecks for reproducible deployments.' : '',
                 evidence: docker?.evidence ?? [],
             });

package/dist/utils/fileScanner.js

@@ -102,6 +102,16 @@ exports.DEFAULT_IGNORE = [
     'Intermediate/**',
     'DerivedData/**',
     '**/Pods/**',
+    /**
+     * Flutter's own generated tooling, and the word it chose for it.
+     *
+     * `ios/Flutter/ephemeral/` holds scripts Flutter writes and rewrites — one of them a
+     * Python helper for lldb. Its imports were being read as the project's dependencies,
+     * so a Dart application's report said some of its dependencies came from Python
+     * imports. The directory says what it is in its name.
+     */
+    '**/Flutter/ephemeral/**',
+    '**/.dart_tool/**',
     '**/Carthage/Build/**',
     // Composer, Go modules and Bundler all install into `vendor/`. The name means the
     // same thing in each: not ours.

package/package.json

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