@produtype/core 0.2.2 → 0.3.1

package/README.md

@@ -4,7 +4,7 @@ ProdKit is a deterministic local CLI that analyzes an existing web application r
 
 It is designed for early-stage and AI-generated apps where architecture and security quality can vary significantly.
 
-ProdKit MVP is read-only: it never modifies the target repository.
+ProdKit is read-only: it never modifies the target repository.
 
 ## What ProdKit does
 
@@ -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
@@ -110,11 +110,13 @@ Optional AI layer:
 - **A separate package.** The AI features live in `@produtype/ai`, which is commercial
   and is not a dependency of this package. An open source install runs the
   deterministic analysis only, and `--ai` reports that the package is not installed
-  rather than failing.
+  rather than failing. That package brings its own model access; nothing needs to be
+  configured here to run the analysis.
 - ProdKit stays deterministic, offline, and read-only: nothing here makes a network
   call.
-- They require an `ANTHROPIC_API_KEY` and the optional `@anthropic-ai/sdk` package (`npm install @anthropic-ai/sdk`). Without them, the deterministic analysis is unaffected.
-- Repository content is redacted of secrets before anything is sent, and AI output is advisory only — it never changes the deterministic score.
+- When `@produtype/ai` is installed, it redacts secrets from repository content before
+  sending anything, and its output stays advisory — it never changes the deterministic
+  score.
 
 Profile warning:
 
@@ -145,145 +147,58 @@ prodkit plan ../my-app --format json
 prodkit plan ../my-app --output prodkit-plan.md
 ```
 
-## Supported stacks in MVP
+## Supported stacks
 
-- Backend: Express, NestJS, Fastify, Next.js (Node); Django, FastAPI, Flask (Python)
-- Frontend: React, Vue, Svelte, Angular, Nuxt, Vite
-- Generic unknown app fallback
+<!-- stacks:start -->
 
-## Acceptance commands
+_Generated from the analyzer itself — run `npm run docs:stacks` after changing a detector._
 
-```bash
-npm install
-npm run build
-npm test
-npm link
-prodkit analyze tests/fixtures/express-basic --format markdown
-prodkit analyze tests/fixtures/express-basic --format json
-prodkit analyze tests/fixtures/express-basic --output report.md
-prodkit plan tests/fixtures/express-basic
-prodkit plan tests/fixtures/express-basic --format json
-prodkit plan tests/fixtures/express-basic --output prodkit-plan.md
-```
+- **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
 
-- Deterministic heuristics only, with no AI explanation layer yet
+- Deterministic heuristics only: the AI layer is a separate package (see above)
 - Signal-based stack coverage across common Node/Python/JS frameworks + fallback
 - Signal-based detection can produce false positives/negatives
 - Plan output is deterministic and read-only only
-- No cloud dashboard/UI in MVP
+- No cloud dashboard or UI: this package is the CLI and the library
 
 ## Roadmap
 
-1. Deterministic analyzer
-2. Deterministic remediation planning
-3. AI explanation layer
-4. Apply/generate PRs
-5. Cloud GitHub integration
-6. Framework adapters
-7. Dashboard
-
-## Project layout
-
-```text
-prodkit/
-  package.json
-  tsconfig.json
-  README.md
-  src/
-    index.ts
-    cli.ts
-    analyzer/
-    planner/
-    rules/
-    report/
-    utils/
-  tests/
-    fixtures/
-    analyzer.test.ts
-    report.test.ts
-    planner.test.ts
-```
-
-## GitHub Action
-
-Gate a pull request on production readiness:
-
-```yaml
-- uses: denisbilli/prodkit@main
-  with:
-    profile: b2b-saas
-    fail-under: "65"
-```
-
-Inputs: `path`, `profile`, `fail-under`, `min-maturity`, `comment-summary`.
-Outputs: `score`, `maturity`, `launch-ready`.
-
-The executive summary is written to the job summary even when the thresholds fail the
-job — a check that fails without saying why is worse than no check at all.
-
-Requires the package to be published; until then, point the action at a local
-checkout.
-
-## MCP server
-
-ProdKit ships an MCP server so an agent can assess a repository without leaving the
-editor. It exposes the deterministic analysis only, makes no network calls, and the
-code being analysed never leaves the machine.
-
-Tools: `analyze_project`, `plan_remediation`, `compare_profiles`, `list_profiles`.
-
-ProdKit is not on npm yet — the name `prodkit` is taken by an unrelated package — so
-install it from a local checkout:
-
-```bash
-npm install && npm run build && npm link
-```
-
-Claude Code:
-
-```bash
-claude mcp add prodkit -- prodkit-mcp
-```
-
-Or, in a client that reads a JSON config:
-
-```json
-{
-  "mcpServers": {
-    "prodkit": {
-      "command": "prodkit-mcp"
-    }
-  }
-}
-```
-
-`compare_profiles` is the one to reach for first: it scores the same repository
-against every product profile in a single call, which is the question ProdKit exists
-to answer.
-
-## Releases
-
-Published from CI on a version tag, with
-[npm provenance](https://docs.npmjs.com/generating-provenance-statements): the tarball
-is cryptographically linked to the commit and the workflow run that produced it, so it
-can be verified rather than merely trusted. No publish token ever sits on a developer
-machine.
-
-To cut a release:
-
-```bash
-npm version patch   # or minor / major — commits and tags
-git push --follow-tags
-```
-
-The workflow refuses to publish if the tag and `package.json` disagree, and runs a
-check that the commercial AI layer is absent from `dist` before anything leaves.
-Release notes are generated from the commits since the previous tag.
-
-## License
-
-
+Shipped: the deterministic analyzer, deterministic remediation planning, and the
+optional AI layer as `@produtype/ai`.
 
-MIT
+Next: applying fixes as generated pull requests, and a hosted GitHub integration.

package/dist/analyzer/analyzeProject.js

@@ -42,6 +42,10 @@ const detectPackageManager_1 = require("./detectPackageManager");
 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");
@@ -134,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));
@@ -269,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);
@@ -298,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] = 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),
@@ -319,12 +478,21 @@ async function analyzeProject(projectPath) {
         (0, detectAiSafety_1.detectAiSafety)(ctx),
         (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,
         frontend.result,
         backend.result,
         database.result,
+        ...database.extra,
+        audit,
+        ...game,
+        clientLogic,
+        errorReporting,
         docker,
         ...env,
         ...auth,
@@ -346,9 +514,21 @@ async function analyzeProject(projectPath) {
             frontend: frontend.frameworks,
             backend: backend.frameworks,
             databases: database.databases,
+            dataPlatforms: database.extra.find((d) => d.key === 'stack.dataPlatform')?.details?.platforms ?? [],
+            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;