@produtype/core 0.29.2 → 0.31.0

package/dist/analyzer/analyzeProject.js

@@ -556,9 +556,12 @@ async function analyzeProject(projectPath) {
         }
     }
     const npmDeps = {};
+    const runtimeNpmDeps = {};
     for (const workspace of workspaces) {
         mergeDeps(npmDeps, workspace.packageJson?.dependencies);
         mergeDeps(npmDeps, workspace.packageJson?.devDependencies);
+        // Kept apart for one question only: whether this repository serves requests.
+        mergeDeps(runtimeNpmDeps, workspace.packageJson?.dependencies);
     }
     /**
      * What the code imports, when nothing declared it.
@@ -606,6 +609,7 @@ async function analyzeProject(projectPath) {
     const ctx = {
         root,
         files: { all: allFiles, source: sourceFiles, config: configFiles, unreadable: unreadableLanguages(allFiles) },
+        runtimeNpmDeps,
         packageJson,
         pythonDeps,
         phpDeps: unique(phpDeps),

package/dist/analyzer/detectBackend.js

@@ -8,8 +8,20 @@ const catalogue_1 = require("./catalogue");
 async function detectBackend(ctx) {
     const frameworks = [];
     const evidence = [];
+    /**
+     * Shipped, not merely present.
+     *
+     * axios declares `express` in devDependencies to run a test server against itself,
+     * and was read as having a backend — which kept a library out of the `library`
+     * profile. A server framework the product does not ship with is a fixture. The
+     * fallback below still reads the source, so a project that runs Express without
+     * declaring it is found anyway.
+     *
+     * Not one repository in the local corpus declares a backend framework only in
+     * devDependencies, so this changes nothing there and fixes a public library.
+     */
     // Express
-    if ((0, detectContext_1.hasDep)(ctx, 'express')) {
+    if ((0, detectContext_1.hasRuntimeDep)(ctx, 'express')) {
         frameworks.push('express');
         evidence.push({ type: 'dependency', value: 'express' });
     }
@@ -30,7 +42,7 @@ async function detectBackend(ctx) {
     // frontend-only meant an application with server routes, sessions and database
     // access was scored as though it had none of them.
     for (const [framework, dep] of catalogue_1.NODE_BACKEND_FRAMEWORKS) {
-        if ((0, detectContext_1.hasDep)(ctx, dep)) {
+        if ((0, detectContext_1.hasRuntimeDep)(ctx, dep)) {
             frameworks.push(framework);
             evidence.push({ type: 'dependency', value: dep });
         }

package/dist/analyzer/detectContext.d.ts

@@ -38,9 +38,25 @@ export interface DetectContext {
     swiftDeps: string[];
     /** Lowercased combined dependency map (deps + devDeps). */
     npmDeps: Record<string, string>;
+    /**
+     * Dependencies the product ships with, without the ones it only builds and tests with.
+     *
+     * `npmDeps` merges both, which is right for almost every question — React in
+     * devDependencies still means React — and wrong for one: a server framework. axios
+     * declares `express` in devDependencies to run a test server, and was read as having
+     * a backend, which kept it out of the `library` profile it plainly belongs to.
+     */
+    runtimeNpmDeps: Record<string, string>;
     workspaces: WorkspaceManifest[];
 }
 export declare function hasDep(ctx: DetectContext, name: string): boolean;
+/**
+ * Declared as something the product runs on, not merely something present.
+ *
+ * Used for server frameworks only. A test server in devDependencies is a fixture; the
+ * question "does this repository serve requests" is answered by what it ships.
+ */
+export declare function hasRuntimeDep(ctx: DetectContext, name: string): boolean;
 export declare function hasAnyDep(ctx: DetectContext, names: string[]): string[];
 export declare function hasPyDep(ctx: DetectContext, name: string): boolean;
 export declare function hasAnyPyDep(ctx: DetectContext, names: string[]): string[];

package/dist/analyzer/detectContext.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasDep = hasDep;
+exports.hasRuntimeDep = hasRuntimeDep;
 exports.hasAnyDep = hasAnyDep;
 exports.hasPyDep = hasPyDep;
 exports.hasAnyPyDep = hasAnyPyDep;
@@ -15,6 +16,15 @@ exports.hasAnyDotnetDep = hasAnyDotnetDep;
 function hasDep(ctx, name) {
     return Object.prototype.hasOwnProperty.call(ctx.npmDeps, name.toLowerCase());
 }
+/**
+ * Declared as something the product runs on, not merely something present.
+ *
+ * Used for server frameworks only. A test server in devDependencies is a fixture; the
+ * question "does this repository serve requests" is answered by what it ships.
+ */
+function hasRuntimeDep(ctx, name) {
+    return Object.prototype.hasOwnProperty.call(ctx.runtimeNpmDeps, name.toLowerCase());
+}
 function hasAnyDep(ctx, names) {
     return names.filter((n) => hasDep(ctx, n));
 }

package/dist/analyzer/detectMobile.js

@@ -133,6 +133,63 @@ async function androidGradleFiles(ctx) {
     }
     return found;
 }
+/**
+ * Directory names that are part of a platform's layout rather than the project's.
+ *
+ * `src/ClientApp/Platforms/Android/AndroidManifest.xml` belongs to a project called
+ * ClientApp; the three segments after it are how MAUI arranges a project, not where the
+ * project begins. Walking past them finds the root a person would name.
+ */
+const PLATFORM_LAYOUT = new Set([
+    'platforms', 'android', 'ios', 'maccatalyst', 'app', 'src', 'main', 'res', 'xcshareddata',
+]);
+function mobileProjectRoot(marker) {
+    const segments = marker.split('/').slice(0, -1);
+    /**
+     * `.xcodeproj` sits beside the sources, not above them.
+     *
+     * `DonGeremIA.xcodeproj/project.pbxproj` names a project whose Swift files are in
+     * `DonGeremIA/`, a sibling. Stopping at the bundle put the project root somewhere no
+     * source file lives and scored a Swift application at zero.
+     */
+    while (segments.length > 0
+        && (PLATFORM_LAYOUT.has(segments[segments.length - 1].toLowerCase())
+            || /\.(xcodeproj|xcworkspace)$/i.test(segments[segments.length - 1]))) {
+        segments.pop();
+    }
+    return segments.join('/');
+}
+/**
+ * How much of the repository the mobile project actually is.
+ *
+ * dotnet/eShop contains a real MAUI client — the markers are not a false positive — and
+ * it is one project of a dozen: 137 source files of 515, beside a web application and
+ * eight services. The repository was reported as a mobile application because a true
+ * signal about a part was read as a fact about the whole.
+ *
+ * Every repository in the verification corpus that *is* a phone application scores 1
+ * here: the manifest sits at its root. The gap between that and eShop's 0.27 is where
+ * the line goes.
+ */
+function mobileSourceShare(sourceFiles, markers) {
+    if (sourceFiles.length === 0)
+        return 0;
+    /**
+     * No file marker means the platform came from a dependency.
+     *
+     * A Flutter project is recognised by `flutter` in its `pubspec.yaml`, and a React
+     * Native one by its `package.json` — a fact about the project's own manifest rather
+     * than about a subdirectory. Scoring those at zero made every Flutter application in
+     * the corpus stop being a mobile application.
+     */
+    if (markers.length === 0)
+        return 1;
+    const roots = new Set(markers.map(mobileProjectRoot));
+    if (roots.has(''))
+        return 1;
+    const inside = sourceFiles.filter((file) => [...roots].some((root) => file.startsWith(`${root}/`)));
+    return inside.length / sourceFiles.length;
+}
 async function detectMobile(ctx) {
     const iosFiles = matchesAny(ctx.files.all, IOS_MARKERS);
     const androidFiles = [...matchesAny(ctx.files.all, ANDROID_MARKERS), ...(await androidGradleFiles(ctx))];
@@ -158,6 +215,7 @@ async function detectMobile(ctx) {
         platformEvidence.push({ type: 'file', value: androidFiles[0], file: androidFiles[0] });
     }
     const isMobile = platforms.length > 0;
+    const share = mobileSourceShare(ctx.files.source, [...iosFiles, ...androidFiles]);
     /**
      * Every capability below reports `present: false` when this is not a mobile project,
      * with no evidence — the profile that asks about them is the only one that applies
@@ -286,7 +344,7 @@ async function detectMobile(ctx) {
             key: 'mobile.platform',
             present: true,
             evidence: platformEvidence,
-            details: { platforms },
+            details: { platforms, sourceShare: share },
         },
         {
             key: 'mobile.permissions',

package/dist/analyzer/detectPackaging.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectPackaging = detectPackaging;
 const readTextFileSafe_1 = require("../utils/readTextFileSafe");
+const detectContext_1 = require("./detectContext");
 /**
  * Whether a project is fit to be installed and depended on by someone else.
  *
@@ -30,8 +31,48 @@ const TEST_FILE = /(^|\/)(tests?|__tests__|spec)\/|\.(test|spec)\.[cm]?[jt]sx?$|
 function collect(files, pattern, limit = 3) {
     return files.filter((file) => pattern.test(file)).slice(0, limit);
 }
+/**
+ * Generators whose whole job is to build a documentation website.
+ *
+ * A package with a docs site in its repository was being read as whatever that site is
+ * built with. zod is a validation library and came back a client application; vite came
+ * back a client application; ruff — a linter written in Rust, with every packaging
+ * signal present — came back a static site, read from its React playground. Five public
+ * libraries out of five, all for this reason.
+ *
+ * The site that documents a product is not the product.
+ */
+const DOCS_GENERATORS = [
+    '@docusaurus/core', 'vitepress', 'nextra', '@astrojs/starlight', 'vuepress', 'docz',
+    'docsify-cli', 'mintlify', '@11ty/eleventy', 'mkdocs', 'mkdocs-material', 'sphinx',
+];
+/**
+ * Where a documentation site lives when it has no generator of its own.
+ *
+ * A hand-built docs site or a playground sits in a directory named for what it is. This
+ * is only consulted for the front-end files: a `docs/` folder full of Markdown says
+ * nothing either way, and a repository whose application happens to live under `www/`
+ * is not caught because the question asked is whether *every* front-end file is in one
+ * of these.
+ */
+const DOCS_DIRECTORIES = /^(docs?|website|playground|examples?|demo|www)\//i;
+const FRONTEND_FILE = /\.(tsx|jsx|vue|svelte|astro)$/;
 async function detectPackaging(ctx) {
     const all = ctx.files.all;
+    /**
+     * Whether the front end in this repository is its documentation rather than its product.
+     *
+     * Two ways to know, and both have to be about the front end specifically. A docs
+     * generator in the dependencies says so outright. Failing that, every front-end file
+     * living under a directory named for documentation says the same thing more quietly —
+     * and *every* matters: one component under `examples/` beside an application is an
+     * example, while an application that is entirely under `examples/` does not exist.
+     */
+    const docsGenerators = [...(0, detectContext_1.hasAnyDep)(ctx, DOCS_GENERATORS), ...(0, detectContext_1.hasAnyPyDep)(ctx, DOCS_GENERATORS)];
+    const frontendFiles = ctx.files.source.filter((file) => FRONTEND_FILE.test(file));
+    const frontendAllInDocs = frontendFiles.length > 0
+        && frontendFiles.every((file) => DOCS_DIRECTORIES.test(file));
+    const documentationSite = docsGenerators.length > 0 || frontendAllInDocs;
     const licenseFiles = collect(all, LICENSE_FILE);
     const declaredLicense = typeof ctx.packageJson?.license === 'string';
     const licenseEvidence = [
@@ -119,6 +160,21 @@ async function detectPackaging(ctx) {
             evidence: licenseEvidence,
             details: { files: licenseFiles.length, declared: declaredLicense },
         },
+        {
+            /**
+             * A site that documents the product, as distinct from the product.
+             *
+             * Its own detector rather than a flag on the stack, because it is evidence a
+             * reader can check: either a generator in the manifest or the directory every
+             * front-end file sits in.
+             */
+            key: 'docs.site',
+            present: documentationSite,
+            evidence: docsGenerators.length > 0
+                ? docsGenerators.map((dep) => ({ type: 'dependency', value: dep }))
+                : frontendFiles.slice(0, 5).map((file) => ({ type: 'file', value: file, file })),
+            details: { generators: docsGenerators, frontendFiles: frontendFiles.length, allUnderDocs: frontendAllInDocs },
+        },
         {
             key: 'docs.readme',
             present: readmeFiles.length > 0,

package/dist/expectations/profileSignals.d.ts

@@ -49,6 +49,14 @@ export interface ProfileFacts {
     gameEngine: boolean;
     /** A manifest that names and versions this, so something else can depend on it. */
     publishable: boolean;
+    /**
+     * The front end in this repository is its documentation, not its product.
+     *
+     * zod, axios, vite and ruff were all read from their docs sites: five public libraries
+     * out of five, none identified as a library. The site that documents a product is not
+     * the product.
+     */
+    documentationSite: boolean;
     /** Somewhere for a consumer to import: main, module, exports, bin, a console script. */
     entrypoints: boolean;
     packagedLicense: boolean;
@@ -56,6 +64,14 @@ export interface ProfileFacts {
     gameSignals: number;
     /** Ships to a phone: Flutter, React Native, or an iOS/Android project in the tree. */
     mobilePlatforms: string[];
+    /**
+     * How much of the repository the mobile project is, between 0 and 1.
+     *
+     * A true signal about one project was being read as a fact about the whole: eShop's
+     * MAUI client is 137 source files of 515, beside a web application and eight services,
+     * and the repository came back as a phone application.
+     */
+    mobileShare: number;
     sourceFiles: number;
 }
 export declare function readFacts(analysis: ProjectAnalysis): ProfileFacts;

package/dist/expectations/profileSignals.js

@@ -28,11 +28,13 @@ function readFacts(analysis) {
         containerised: present('deployment.docker'),
         gameEngine: present('game.engine'),
         publishable: complete('packaging.manifest'),
+        documentationSite: present('docs.site'),
         entrypoints: present('packaging.entrypoints'),
         packagedLicense: present('packaging.license'),
         tests: present('quality.tests'),
         gameSignals: Number(analysis.detectors['game.engine']?.details?.supportingSignals ?? 0),
         mobilePlatforms: analysis.detectors['mobile.platform']?.details?.platforms ?? [],
+        mobileShare: analysis.detectors['mobile.platform']?.details?.sourceShare ?? 0,
         sourceFiles: analysis.files.source.length,
     };
 }
@@ -134,7 +136,15 @@ const RULES = [
          */
         profile: 'mobile-app',
         refines: 'client-app',
-        admissible: (f) => f.mobilePlatforms.length > 0 && !f.tenancy,
+        /**
+         * The mobile project has to be the repository, not a project inside it.
+         *
+         * Every repository in the corpus that is a phone application has its manifest at the
+         * root and scores 1. eShop scores 0.27 and is a .NET system with a MAUI client in it.
+         * Half is the line, and it sits in the gap between those two rather than in the
+         * middle of a distribution.
+         */
+        admissible: (f) => f.mobilePlatforms.length > 0 && f.mobileShare >= 0.5 && !f.tenancy,
         signals: [
             { identifies: true, label: 'a mobile project in the repository', weight: 5, holds: (f) => f.mobilePlatforms.length > 0 },
             {
@@ -175,7 +185,18 @@ const RULES = [
          * project serves requests, and a package is not served.
          */
         profile: 'library',
-        admissible: (f) => f.publishable && f.entrypoints && !f.frontend && !f.backend && f.mobilePlatforms.length === 0,
+        /**
+         * A front end that is documentation does not make a package an application.
+         *
+         * The gate used to be "no front end at all", which is right for a plain package and
+         * wrong for every library with a docs site — which is to say, every library anybody
+         * has heard of. A backend still disqualifies: a package is not served.
+         */
+        admissible: (f) => f.publishable
+            && f.entrypoints
+            && (!f.frontend || f.documentationSite)
+            && !f.backend
+            && f.mobilePlatforms.length === 0,
         signals: [
             { identifies: true, label: 'a manifest that names and versions it', weight: 3, holds: (f) => f.publishable },
             { identifies: true, label: 'an entry point for something else to import', weight: 2, holds: (f) => f.entrypoints },

package/package.json

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