@produtype/core 0.3.0 → 0.3.1

package/README.md

@@ -99,7 +99,7 @@ Options:
 - `--format markdown|json` output format for the report or plan payload
 - `--summary` print summary only
 - `--output <path>` write output to file
-- `--profile <name>` evaluate expected product capabilities (`static-site`, `internal-tool`, `b2c-app`, `b2b-saas`, `ai-saas`, `marketplace`, `auto`, `observed-only`)
+- `--profile <name>` evaluate expected product capabilities (`static-site`, `internal-tool`, `b2c-app`, `b2b-saas`, `ai-saas`, `marketplace`, `game`, `client-app`, `auto`, `observed-only`)
 - `--fail-under <score>` (analyze only) exit with code 1 if the overall score is below the threshold — useful as a CI quality gate
 - `--min-maturity <level>` (analyze only) exit with code 1 if maturity is below `prototype|early|partial|production_ready`
 - `--ai` (analyze only) add an AI stack/architecture insight — opt-in, advisory only, does not affect the score
@@ -149,29 +149,44 @@ prodkit plan ../my-app --output prodkit-plan.md
 
 ## Supported stacks
 
-- **Backend (Node):** Express, Next.js, NestJS, Fastify, Hono, Elysia, Koa, AdonisJS,
-  SvelteKit, Remix, Nuxt, Nitro
-- **Backend (Python):** Django, FastAPI, Flask, Litestar, Starlette, Sanic, Tornado,
-  aiohttp
-- **Frontend:** React, Vue, Svelte, Angular, Solid, Qwik, Preact, Astro, Nuxt, Remix,
-  Vite, Tailwind, htmx
-- **Databases:** Postgres, MySQL, SQLite, MongoDB, Redis
-- **Hosted data platforms:** Supabase, Firebase, Neon, PlanetScale, Vercel Postgres,
-  Turso, Upstash, DynamoDB, Convex
-- **ORMs:** Prisma, Drizzle, TypeORM, Sequelize, Knex, MikroORM, Kysely, SQLAlchemy,
-  Tortoise, Peewee
-- Generic unknown app fallback
-
-Two of these distinctions are deliberate rather than incidental.
-
-A hosted platform is recorded separately from the engine underneath it. Supabase is
-Postgres and Turso is SQLite, so rules written about an engine keep working without
-knowing about the host, while "this data lives on infrastructure someone else
-operates" stays a question the report can ask on its own.
-
-Astro counts as a backend only when it is configured to serve requests — `output` set
-to `server` or `hybrid`, or an adapter installed. A static Astro site is a static
-site, and is not marked down for missing the things an application needs.
+<!-- stacks:start -->
+
+_Generated from the analyzer itself — run `npm run docs:stacks` after changing a detector._
+
+- **Backend:** Express, Next.js, NestJS, Fastify, Hono, Elysia, Koa, AdonisJS, SvelteKit, Remix, Nuxt, Nitro, Astro, Django, Flask, FastAPI, Litestar, Sanic, Tornado, aiohttp, Starlette, Gin, Echo, Fiber, chi, Gorilla, Beego, Go, Rails, Sinatra, Hanami, Roda, Grape, Ruby, Laravel, Symfony, Slim, CodeIgniter, CakePHP, Yii, PHP, ASP.NET Core, .NET
+- **Frontend:** React, Vite, Vue, Nuxt, Svelte, Angular, Astro, Solid, Qwik, Preact, Remix, htmx, Tailwind CSS, Electron
+- **Mobile:** Flutter
+- **Databases:** Postgres, MySQL, SQLite, SQL Server, MongoDB, Redis, Firestore, DynamoDB, Convex
+- **Hosted data platforms:** Supabase, Firebase, PlanetScale, Neon, Vercel Postgres, Turso, Upstash, DynamoDB, Convex
+- **ORMs:** Prisma, Drizzle, TypeORM, Sequelize, Knex, MikroORM, Kysely, SQLAlchemy, Tortoise, Peewee
+
+How some of these are decided:
+
+- **Express** — the dependency, or an import in the source
+- **Astro** — counted as a backend only when configured to serve requests
+- **Django** — manage.py, settings.py and urls.py together
+- **Flask** — the dependency, or an import in the source
+- **FastAPI** — the dependency, or an import in the source
+- **Go** — a go.mod with no framework in it — net/http is a real answer
+- **Ruby** — a Gemfile with no web framework in it
+- **PHP** — PHP sources with no framework in composer.json
+- **ASP.NET Core** — the Microsoft.NET.Sdk.Web SDK attribute
+- **.NET** — a .csproj with no web SDK
+- **Flutter** — pubspec.yaml — classified as a client application, not a backend
+- **Supabase** — recorded alongside the engine it is — Postgres
+- **Firebase** — Firestore
+- **PlanetScale** — MySQL
+- **Neon** — Postgres
+- **Vercel Postgres** — Postgres
+- **Turso** — SQLite
+- **Upstash** — Redis
+
+<!-- stacks:end -->
+
+A hosted platform is recorded separately from the engine underneath it, so rules
+written about an engine keep working without knowing about the host, while "this data
+lives on infrastructure someone else operates" stays a question the report can ask on
+its own.
 
 ## Current limitations
 

package/dist/analyzer/analyzeProject.js

@@ -43,6 +43,9 @@ const detectFrontend_1 = require("./detectFrontend");
 const detectBackend_1 = require("./detectBackend");
 const detectDatabase_1 = require("./detectDatabase");
 const detectAudit_1 = require("./detectAudit");
+const detectGame_1 = require("./detectGame");
+const detectClientLogic_1 = require("./detectClientLogic");
+const detectErrorReporting_1 = require("./detectErrorReporting");
 const detectDocker_1 = require("./detectDocker");
 const detectEnv_1 = require("./detectEnv");
 const detectAuth_1 = require("./detectAuth");
@@ -135,8 +138,44 @@ function isTestOrExamplePath(file) {
         || /(^|\/)test[-_][^/]+\.(ts|tsx|js|jsx|mjs|cjs|py)$/i.test(file)
         || /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs|py)$/i.test(file);
 }
+/**
+ * Extensions the detectors can read.
+ *
+ * PHP, Go, Ruby, Java, C# and Rust are here because a detector that greps for a
+ * hardcoded secret, an open CORS policy or an unprotected upload does not care what
+ * language surrounds the line. Stack detection still leans on manifests, so a Laravel
+ * application is not fully understood by being readable — but being readable is the
+ * difference between a partial reading and none.
+ */
+const SOURCE_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs|py|php|go|rb|java|cs|rs|kt|swift|dart)$/;
 function pickSource(files) {
-    return files.filter((f) => /\.(ts|tsx|js|jsx|mjs|cjs|py)$/.test(f) && !isTestOrExamplePath(f));
+    return files.filter((f) => SOURCE_EXTENSIONS.test(f) && !isTestOrExamplePath(f));
+}
+/**
+ * Languages present in the repository that nothing here can read.
+ *
+ * The failure this exists to stop: a published PHP application, 57 source files, was
+ * analysed from the single JavaScript file in it. The report named a backend of
+ * "unknown", raised a critical for missing authentication that is written in PHP, and
+ * said "Warnings: none" — confident, detailed, and built on two per cent of the code.
+ *
+ * Being wrong is recoverable. Being wrong while announcing no reservations is not.
+ */
+const KNOWN_UNREADABLE = [
+    [/\.(ex|exs)$/, 'Elixir'],
+    [/\.(scala|sc)$/, 'Scala'],
+    [/\.(clj|cljs)$/, 'Clojure'],
+    [/\.(cpp|cc|hpp)$/, 'C++'],
+    [/\.(erl|hrl)$/, 'Erlang'],
+    [/\.(hs)$/, 'Haskell'],
+    [/\.(pl|pm)$/, 'Perl'],
+    [/\.(lua)$/, 'Lua'],
+];
+function unreadableLanguages(files) {
+    return KNOWN_UNREADABLE
+        .map(([pattern, language]) => ({ language, files: files.filter((f) => pattern.test(f)).length }))
+        .filter((entry) => entry.files > 0)
+        .sort((a, b) => b.files - a.files);
 }
 function pickConfig(files) {
     return files.filter((f) => /(package\.json|tsconfig|vite\.config|docker|compose|requirements\.txt|pyproject\.toml|settings\.py|\.env)/i.test(f));
@@ -270,6 +309,119 @@ async function analyzeProject(projectPath) {
         });
     }
     const pythonDeps = unique(workspaces.flatMap((w) => [...w.requirementsDeps, ...w.pyprojectDeps]));
+    /**
+     * Composer requirements. A published PHP application in the corpus reported a
+     * backend of "unknown" because nothing read this file, while 57 source files sat
+     * beside it saying plainly what the project was.
+     */
+    /**
+     * go.mod and the Gemfile, read the same way and for the same reason as composer.json:
+     * a repository whose manifest nothing here parses is reported with a backend of
+     * "unknown" while its source sits in plain sight.
+     *
+     * Both are parsed with regular expressions rather than properly. A go.mod require
+     * block and a `gem 'name'` line are simple enough that a parser would be more code
+     * than it is worth, and a manifest this cannot read yields no dependencies rather
+     * than a wrong answer.
+     */
+    const goDeps = [];
+    for (const file of allFiles.filter((f) => /(^|\/)go\.mod$/.test(f))) {
+        const raw = (await (0, readTextFileSafe_1.readTextFileSafe)(root, file)) ?? '';
+        for (const line of raw.split('\n')) {
+            const match = /^\s*(?:require\s+)?([a-z0-9][\w.-]*(?:\.[a-z]{2,})?\/[\w./-]+)\s+v/i.exec(line);
+            if (match)
+                goDeps.push(match[1].toLowerCase());
+        }
+    }
+    /**
+     * pubspec.yaml, read for its two dependency blocks.
+     *
+     * YAML with a hand-written reader again, and the shape here is forgiving: the blocks
+     * are `dependencies:` and `dev_dependencies:`, and each entry is a name at one level
+     * of indentation. Nested constraints — a git source, an sdk pin — sit deeper and are
+     * skipped, which is right: what matters is which package is used, not where it comes
+     * from.
+     */
+    const dartDeps = [];
+    for (const file of allFiles.filter((f) => /(^|\/)pubspec\.yaml$/.test(f))) {
+        const raw = (await (0, readTextFileSafe_1.readTextFileSafe)(root, file)) ?? '';
+        let inDeps = false;
+        for (const line of raw.split('\n')) {
+            if (/^(dev_)?dependencies\s*:/.test(line)) {
+                inDeps = true;
+                continue;
+            }
+            // Any other top-level key ends the block. Without this, everything below
+            // `dependencies:` to the end of the file would be read as a package.
+            if (/^[a-z_]+\s*:/i.test(line)) {
+                inDeps = false;
+                continue;
+            }
+            if (!inDeps)
+                continue;
+            const match = /^\s{2}([a-z0-9_]+)\s*:/i.exec(line);
+            if (match)
+                dartDeps.push(match[1].toLowerCase());
+        }
+    }
+    /**
+     * .csproj, which is XML rather than JSON or one-entry-per-line.
+     *
+     * Parsed with regular expressions like the others, and here that decision needs more
+     * defending: XML has real nesting, and a regex cannot see it. What is being read is
+     * two flat things — the Sdk attribute on the root element and the Include attribute
+     * of each PackageReference — and neither depends on where it sits in the tree. A
+     * project file this cannot read yields nothing, which is the same failure as an
+     * unreadable package.json.
+     *
+     * The Sdk attribute carries more than any dependency: `Microsoft.NET.Sdk.Web` is
+     * what makes a project a web application, and it appears in no package list.
+     */
+    const dotnetDeps = [];
+    let dotnetWebSdk = false;
+    for (const file of allFiles.filter((f) => /\.(csproj|fsproj|vbproj)$/i.test(f))) {
+        const raw = (await (0, readTextFileSafe_1.readTextFileSafe)(root, file)) ?? '';
+        if (/Sdk\s*=\s*["']Microsoft\.NET\.Sdk\.Web["']/i.test(raw))
+            dotnetWebSdk = true;
+        for (const match of raw.matchAll(/<PackageReference\s+Include\s*=\s*["']([^"']+)["']/gi)) {
+            dotnetDeps.push(match[1].toLowerCase());
+        }
+        // A framework reference is how an application declares it needs the web runtime.
+        for (const match of raw.matchAll(/<FrameworkReference\s+Include\s*=\s*["']([^"']+)["']/gi)) {
+            dotnetDeps.push(match[1].toLowerCase());
+        }
+    }
+    const rubyDeps = [];
+    for (const file of allFiles.filter((f) => /(^|\/)Gemfile$/.test(f))) {
+        const raw = (await (0, readTextFileSafe_1.readTextFileSafe)(root, file)) ?? '';
+        for (const line of raw.split('\n')) {
+            // Skip commented-out gems, which are otherwise indistinguishable from real ones.
+            if (/^\s*#/.test(line))
+                continue;
+            const match = /^\s*gem\s+['"]([^'"]+)['"]/.exec(line);
+            if (match)
+                rubyDeps.push(match[1].toLowerCase());
+        }
+    }
+    const composerFiles = allFiles.filter((file) => /(^|\/)composer\.json$/.test(file));
+    const phpDeps = [];
+    for (const file of composerFiles) {
+        const raw = await (0, readTextFileSafe_1.readTextFileSafe)(root, file);
+        if (!raw)
+            continue;
+        try {
+            const parsed = JSON.parse(raw);
+            const require_ = parsed?.require ?? {};
+            const requireDev = parsed?.['require-dev'] ?? {};
+            for (const name of [...Object.keys(require_), ...Object.keys(requireDev)]) {
+                phpDeps.push(name.toLowerCase());
+            }
+        }
+        catch {
+            // A composer.json that does not parse tells us nothing; it is not an error worth
+            // failing an analysis over.
+        }
+    }
     const npmDeps = {};
     for (const workspace of workspaces) {
         mergeDeps(npmDeps, workspace.packageJson?.dependencies);
@@ -299,10 +451,16 @@ async function analyzeProject(projectPath) {
         files: { all: allFiles, source: sourceFiles, config: configFiles },
         packageJson,
         pythonDeps,
+        phpDeps: unique(phpDeps),
+        goDeps: unique(goDeps),
+        rubyDeps: unique(rubyDeps),
+        dotnetDeps: unique(dotnetDeps),
+        dotnetWebSdk,
+        dartDeps: unique(dartDeps),
         npmDeps,
         workspaces,
     };
-    const [pm, frontend, backend, database, docker, env, auth, security, uploads, gdpr, billing, observability, jobs, marketplace, aiSafety, engagement, deployment, audit] = await Promise.all([
+    const [pm, frontend, backend, database, docker, env, auth, security, uploads, gdpr, billing, observability, jobs, marketplace, aiSafety, engagement, deployment, audit, game, clientLogic, errorReporting] = await Promise.all([
         (0, detectPackageManager_1.detectPackageManager)(ctx),
         (0, detectFrontend_1.detectFrontend)(ctx),
         (0, detectBackend_1.detectBackend)(ctx),
@@ -321,6 +479,9 @@ async function analyzeProject(projectPath) {
         (0, detectNotifications_1.detectEngagement)(ctx),
         (0, detectDeployment_1.detectDeployment)(ctx),
         (0, detectAudit_1.detectAudit)(ctx),
+        (0, detectGame_1.detectGame)(ctx),
+        (0, detectClientLogic_1.detectClientLogic)(ctx),
+        (0, detectErrorReporting_1.detectErrorReporting)(ctx),
     ]);
     const detectors = (0, detectStack_1.mergeDetectors)([
         pm.result,
@@ -329,6 +490,9 @@ async function analyzeProject(projectPath) {
         database.result,
         ...database.extra,
         audit,
+        ...game,
+        clientLogic,
+        errorReporting,
         docker,
         ...env,
         ...auth,
@@ -354,7 +518,17 @@ async function analyzeProject(projectPath) {
             orms: database.extra.find((d) => d.key === 'stack.orm')?.details?.orms ?? [],
             packageManager: pm.manager,
             packageManagerConfidence: pm.confidence,
-            warnings: pm.warnings,
+            /**
+             * A reading built on part of the code says so.
+             *
+             * The report for a published PHP application said "Warnings: none" while it had
+             * seen one file out of 57. Being wrong is recoverable; being wrong while
+             * announcing no reservations is not.
+             */
+            warnings: [
+                ...pm.warnings,
+                ...unreadableLanguages(allFiles).map((entry) => `${entry.files} ${entry.language} files were not analysed: this reading covers only part of the repository`),
+            ],
             workspaces: workspaceStacks,
             files: allFiles,
         }),

package/dist/analyzer/catalogue.d.ts

@@ -0,0 +1,65 @@
+/**
+ * What the analyzer recognises, in one place, as data.
+ *
+ * These tables used to live inside the detector functions, and the documentation of
+ * them lived in a README and on a website — three copies of the same list, two of them
+ * maintained by hand. They had already drifted apart. Anything that answers "does it
+ * work on my stack?" now reads this, and the detectors iterate the same arrays, so a
+ * framework cannot be recognised without being listed or listed without being
+ * recognised.
+ *
+ * Entries whose detection is not a dependency lookup are still listed here, with
+ * `detectedFrom` saying what actually settles it, because a catalogue that quietly
+ * omitted Express or Django would be answering the question wrongly in the direction
+ * that loses users.
+ */
+/** Node backend frameworks, each conclusive from one dependency. */
+export declare const NODE_BACKEND_FRAMEWORKS: Array<[string, string]>;
+/** Go frameworks, read from go.mod. */
+export declare const GO_BACKEND_FRAMEWORKS: Array<[string, string[]]>;
+/** Ruby frameworks, read from the Gemfile. */
+export declare const RUBY_BACKEND_FRAMEWORKS: Array<[string, string[]]>;
+/** PHP frameworks, read from composer.json. */
+export declare const PHP_BACKEND_FRAMEWORKS: Array<[string, string[]]>;
+/**
+ * Python frameworks settled by a dependency alone. Django, Flask and FastAPI are not
+ * here: each also has a source-level fallback, so each has its own block in the
+ * detector and its own entry in the catalogue below.
+ */
+export declare const PYTHON_BACKEND_FRAMEWORKS: Array<[string, string]>;
+/** Frontend frameworks settled by their signature dependency. */
+export declare const FRONTEND_FRAMEWORKS: Array<[string, string[]]>;
+export interface CatalogueEntry {
+    /** The identifier the report uses. */
+    id: string;
+    /** What a person calls it. */
+    label: string;
+    /** What settles it, for the cases a dependency name does not. */
+    detectedFrom?: string;
+}
+export interface StackCatalogue {
+    backend: CatalogueEntry[];
+    frontend: CatalogueEntry[];
+    mobile: CatalogueEntry[];
+    databases: CatalogueEntry[];
+    dataPlatforms: CatalogueEntry[];
+    orms: CatalogueEntry[];
+    languages: CatalogueEntry[];
+}
+export declare function labelFor(id: string): string;
+/**
+ * Whether this id has a name written for it, rather than falling back to itself.
+ *
+ * Exists for the test: several of these are genuinely lowercase — aiohttp, chi, htmx —
+ * so "the label looks like an id" cannot tell a missing name from a correct one. A new
+ * framework added to a table with no label is the drift worth catching, and this is
+ * what catches it.
+ */
+export declare function hasLabel(id: string): boolean;
+/**
+ * Everything the analyzer can name, as a catalogue meant to be read by a person.
+ *
+ * Built from the same arrays the detectors iterate, plus explicit entries for the
+ * frameworks whose detection is not a dependency lookup.
+ */
+export declare function supportedStacks(): StackCatalogue;

package/dist/analyzer/catalogue.js

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * What the analyzer recognises, in one place, as data.
+ *
+ * These tables used to live inside the detector functions, and the documentation of
+ * them lived in a README and on a website — three copies of the same list, two of them
+ * maintained by hand. They had already drifted apart. Anything that answers "does it
+ * work on my stack?" now reads this, and the detectors iterate the same arrays, so a
+ * framework cannot be recognised without being listed or listed without being
+ * recognised.
+ *
+ * Entries whose detection is not a dependency lookup are still listed here, with
+ * `detectedFrom` saying what actually settles it, because a catalogue that quietly
+ * omitted Express or Django would be answering the question wrongly in the direction
+ * that loses users.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FRONTEND_FRAMEWORKS = exports.PYTHON_BACKEND_FRAMEWORKS = exports.PHP_BACKEND_FRAMEWORKS = exports.RUBY_BACKEND_FRAMEWORKS = exports.GO_BACKEND_FRAMEWORKS = exports.NODE_BACKEND_FRAMEWORKS = void 0;
+exports.labelFor = labelFor;
+exports.hasLabel = hasLabel;
+exports.supportedStacks = supportedStacks;
+/** Node backend frameworks, each conclusive from one dependency. */
+exports.NODE_BACKEND_FRAMEWORKS = [
+    ['next', 'next'],
+    ['nestjs', '@nestjs/core'],
+    ['fastify', 'fastify'],
+    ['hono', 'hono'],
+    ['elysia', 'elysia'],
+    ['koa', 'koa'],
+    ['adonis', '@adonisjs/core'],
+    ['sveltekit', '@sveltejs/kit'],
+    ['remix', '@remix-run/node'],
+    ['remix', '@remix-run/server-runtime'],
+    ['nuxt', 'nuxt'],
+    ['nitro', 'nitropack'],
+];
+/** Go frameworks, read from go.mod. */
+exports.GO_BACKEND_FRAMEWORKS = [
+    ['gin', ['gin-gonic/gin']],
+    ['echo', ['labstack/echo', 'labstack/echo/v4']],
+    ['fiber', ['gofiber/fiber', 'gofiber/fiber/v2']],
+    ['chi', ['go-chi/chi', 'go-chi/chi/v5']],
+    ['gorilla', ['gorilla/mux']],
+    ['beego', ['beego/beego']],
+];
+/** Ruby frameworks, read from the Gemfile. */
+exports.RUBY_BACKEND_FRAMEWORKS = [
+    ['rails', ['rails']],
+    ['sinatra', ['sinatra']],
+    ['hanami', ['hanami']],
+    ['roda', ['roda']],
+    ['grape', ['grape']],
+];
+/** PHP frameworks, read from composer.json. */
+exports.PHP_BACKEND_FRAMEWORKS = [
+    ['laravel', ['laravel/framework', 'laravel/laravel']],
+    ['symfony', ['symfony/framework-bundle', 'symfony/symfony']],
+    ['slim', ['slim/slim']],
+    ['codeigniter', ['codeigniter4/framework']],
+    ['cakephp', ['cakephp/cakephp']],
+    ['yii', ['yiisoft/yii2']],
+];
+/**
+ * Python frameworks settled by a dependency alone. Django, Flask and FastAPI are not
+ * here: each also has a source-level fallback, so each has its own block in the
+ * detector and its own entry in the catalogue below.
+ */
+exports.PYTHON_BACKEND_FRAMEWORKS = [
+    ['litestar', 'litestar'],
+    ['sanic', 'sanic'],
+    ['tornado', 'tornado'],
+    ['aiohttp', 'aiohttp'],
+    ['starlette', 'starlette'],
+];
+/** Frontend frameworks settled by their signature dependency. */
+exports.FRONTEND_FRAMEWORKS = [
+    ['vue', ['vue']],
+    ['nuxt', ['nuxt']],
+    ['svelte', ['svelte', '@sveltejs/kit']],
+    ['angular', ['@angular/core']],
+    ['astro', ['astro']],
+    ['solid', ['solid-js']],
+    ['qwik', ['@builder.io/qwik']],
+    ['preact', ['preact']],
+    ['remix', ['@remix-run/react']],
+    ['htmx', ['htmx.org']],
+];
+/** Display names for ids the tables above produce. */
+const LABELS = {
+    next: 'Next.js',
+    nestjs: 'NestJS',
+    fastify: 'Fastify',
+    hono: 'Hono',
+    elysia: 'Elysia',
+    koa: 'Koa',
+    adonis: 'AdonisJS',
+    sveltekit: 'SvelteKit',
+    remix: 'Remix',
+    nuxt: 'Nuxt',
+    nitro: 'Nitro',
+    gin: 'Gin',
+    echo: 'Echo',
+    fiber: 'Fiber',
+    chi: 'chi',
+    gorilla: 'Gorilla',
+    beego: 'Beego',
+    rails: 'Rails',
+    sinatra: 'Sinatra',
+    hanami: 'Hanami',
+    roda: 'Roda',
+    grape: 'Grape',
+    laravel: 'Laravel',
+    symfony: 'Symfony',
+    slim: 'Slim',
+    codeigniter: 'CodeIgniter',
+    cakephp: 'CakePHP',
+    yii: 'Yii',
+    litestar: 'Litestar',
+    sanic: 'Sanic',
+    tornado: 'Tornado',
+    aiohttp: 'aiohttp',
+    starlette: 'Starlette',
+    vue: 'Vue',
+    svelte: 'Svelte',
+    angular: 'Angular',
+    astro: 'Astro',
+    solid: 'Solid',
+    qwik: 'Qwik',
+    preact: 'Preact',
+    htmx: 'htmx',
+    react: 'React',
+    vite: 'Vite',
+    tailwindcss: 'Tailwind CSS',
+    electron: 'Electron',
+    flutter: 'Flutter',
+    express: 'Express',
+    flask: 'Flask',
+    fastapi: 'FastAPI',
+    django: 'Django',
+    'aspnet-core': 'ASP.NET Core',
+    dotnet: '.NET',
+    go: 'Go',
+    ruby: 'Ruby',
+    php: 'PHP',
+    postgres: 'Postgres',
+    mysql: 'MySQL',
+    sqlite: 'SQLite',
+    sqlserver: 'SQL Server',
+    mongodb: 'MongoDB',
+    redis: 'Redis',
+    firestore: 'Firestore',
+    dynamodb: 'DynamoDB',
+    convex: 'Convex',
+    supabase: 'Supabase',
+    firebase: 'Firebase',
+    planetscale: 'PlanetScale',
+    neon: 'Neon',
+    'vercel-postgres': 'Vercel Postgres',
+    turso: 'Turso',
+    upstash: 'Upstash',
+    prisma: 'Prisma',
+    drizzle: 'Drizzle',
+    typeorm: 'TypeORM',
+    sequelize: 'Sequelize',
+    knex: 'Knex',
+    'mikro-orm': 'MikroORM',
+    kysely: 'Kysely',
+    sqlalchemy: 'SQLAlchemy',
+    tortoise: 'Tortoise',
+    peewee: 'Peewee',
+};
+function labelFor(id) {
+    return LABELS[id] ?? id;
+}
+/**
+ * Whether this id has a name written for it, rather than falling back to itself.
+ *
+ * Exists for the test: several of these are genuinely lowercase — aiohttp, chi, htmx —
+ * so "the label looks like an id" cannot tell a missing name from a correct one. A new
+ * framework added to a table with no label is the drift worth catching, and this is
+ * what catches it.
+ */
+function hasLabel(id) {
+    return id in LABELS;
+}
+function entries(ids) {
+    // Deduplicated because a framework can be reached by more than one dependency:
+    // Remix is two packages, and the catalogue is a list of frameworks, not of packages.
+    const seen = new Set();
+    return ids
+        .filter((id) => (seen.has(id) ? false : (seen.add(id), true)))
+        .map((id) => ({ id, label: labelFor(id) }));
+}
+/**
+ * Everything the analyzer can name, as a catalogue meant to be read by a person.
+ *
+ * Built from the same arrays the detectors iterate, plus explicit entries for the
+ * frameworks whose detection is not a dependency lookup.
+ */
+function supportedStacks() {
+    return {
+        backend: [
+            { id: 'express', label: 'Express', detectedFrom: 'the dependency, or an import in the source' },
+            ...entries(exports.NODE_BACKEND_FRAMEWORKS.map(([id]) => id)),
+            {
+                id: 'astro',
+                label: 'Astro',
+                detectedFrom: 'counted as a backend only when configured to serve requests',
+            },
+            { id: 'django', label: 'Django', detectedFrom: 'manage.py, settings.py and urls.py together' },
+            { id: 'flask', label: 'Flask', detectedFrom: 'the dependency, or an import in the source' },
+            { id: 'fastapi', label: 'FastAPI', detectedFrom: 'the dependency, or an import in the source' },
+            ...entries(exports.PYTHON_BACKEND_FRAMEWORKS.map(([id]) => id)),
+            ...entries(exports.GO_BACKEND_FRAMEWORKS.map(([id]) => id)),
+            { id: 'go', label: 'Go', detectedFrom: 'a go.mod with no framework in it — net/http is a real answer' },
+            ...entries(exports.RUBY_BACKEND_FRAMEWORKS.map(([id]) => id)),
+            { id: 'ruby', label: 'Ruby', detectedFrom: 'a Gemfile with no web framework in it' },
+            ...entries(exports.PHP_BACKEND_FRAMEWORKS.map(([id]) => id)),
+            { id: 'php', label: 'PHP', detectedFrom: 'PHP sources with no framework in composer.json' },
+            { id: 'aspnet-core', label: 'ASP.NET Core', detectedFrom: 'the Microsoft.NET.Sdk.Web SDK attribute' },
+            { id: 'dotnet', label: '.NET', detectedFrom: 'a .csproj with no web SDK' },
+        ],
+        frontend: [
+            { id: 'react', label: 'React' },
+            { id: 'vite', label: 'Vite' },
+            ...entries(exports.FRONTEND_FRAMEWORKS.map(([id]) => id)),
+            { id: 'tailwindcss', label: 'Tailwind CSS' },
+            { id: 'electron', label: 'Electron' },
+        ],
+        mobile: [
+            {
+                id: 'flutter',
+                label: 'Flutter',
+                detectedFrom: 'pubspec.yaml — classified as a client application, not a backend',
+            },
+        ],
+        databases: entries(['postgres', 'mysql', 'sqlite', 'sqlserver', 'mongodb', 'redis', 'firestore', 'dynamodb', 'convex']),
+        dataPlatforms: [
+            { id: 'supabase', label: 'Supabase', detectedFrom: 'recorded alongside the engine it is — Postgres' },
+            { id: 'firebase', label: 'Firebase', detectedFrom: 'Firestore' },
+            { id: 'planetscale', label: 'PlanetScale', detectedFrom: 'MySQL' },
+            { id: 'neon', label: 'Neon', detectedFrom: 'Postgres' },
+            { id: 'vercel-postgres', label: 'Vercel Postgres', detectedFrom: 'Postgres' },
+            { id: 'turso', label: 'Turso', detectedFrom: 'SQLite' },
+            { id: 'upstash', label: 'Upstash', detectedFrom: 'Redis' },
+            { id: 'dynamodb', label: 'DynamoDB' },
+            { id: 'convex', label: 'Convex' },
+        ],
+        orms: entries([
+            'prisma',
+            'drizzle',
+            'typeorm',
+            'sequelize',
+            'knex',
+            'mikro-orm',
+            'kysely',
+            'sqlalchemy',
+            'tortoise',
+            'peewee',
+        ]),
+        languages: entries(['typescript', 'javascript', 'python', 'php', 'go', 'ruby', 'java', 'csharp', 'rust', 'kotlin', 'swift', 'dart']).map((entry) => ({ ...entry, label: labelFor(entry.id) === entry.id ? entry.id.replace(/^\w/, (c) => c.toUpperCase()) : labelFor(entry.id) })),
+    };
+}

package/dist/analyzer/catalogueMarkdown.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The catalogue rendered as the README's "Supported stacks" section.
+ *
+ * Lives in the source rather than in the script that writes it, so a test can render
+ * it and compare against the file. That is what keeps the README from drifting: the
+ * list is generated, and the check that it was regenerated is part of the suite.
+ */
+export declare function renderSupportedStacksMarkdown(): string;