@produtype/core 0.26.1 → 0.27.0

package/dist/analyzer/detectAuth.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectAuth = detectAuth;
 const detectContext_1 = require("./detectContext");
 const textSearch_1 = require("../utils/textSearch");
+const roleChecks_1 = require("./structural/roleChecks");
 const absenceEvidence_1 = require("./absenceEvidence");
 /**
  * In a product that talks to a model, `role` usually means who is speaking.
@@ -156,15 +157,34 @@ async function detectAuth(ctx) {
     ], 20);
     const emailVerificationSignals = await (0, textSearch_1.searchInFiles)(ctx.root, sourceFiles, [/verify\s*email/i, /email[_-]?verification/i, /confirm\s*email/i, /isEmailVerified/i], 20);
     const sessionSignals = await (0, textSearch_1.searchInFiles)(ctx.root, sourceFiles, [/session/i, /cookie/i, /jwt/i, /refresh\s*token/i, /httpOnly/i], 25);
-    const roleSignals = excludeChatTurnRoles(await (0, textSearch_1.searchInFiles)(ctx.root, sourceFiles, [
-        /requireRole/i,
-        /isAdmin/i,
-        /SUPER_ADMIN/i,
-        /req\.user\.role/i,
-        /user\.role/i,
-        /role\s*===/i,
-        /roles\.includes\(/i,
-    ], 20));
+    /**
+     * Structure first, text underneath.
+     *
+     * `excludeChatTurnRoles` below is three patches written in one day, each against a
+     * shape the last one missed: a chat transcript, a game's `part.role`, JSX picking an
+     * icon. A syntax tree asks the question all three were really about — does this
+     * comparison guard something, or label something — and answers it for shapes nobody
+     * has thought of yet.
+     *
+     * `null` means the question could not be asked, because the optional TypeScript
+     * dependency is not installed. It is not "no roles found": the two are different
+     * answers and confusing them is the mistake this product exists to avoid. When it is
+     * null, the text search below runs exactly as before.
+     */
+    const structuralRoles = await (0, roleChecks_1.readRoleChecks)(ctx.root, sourceFiles);
+    const guardedRoles = structuralRoles?.filter((check) => check.kind === 'guard') ?? null;
+    /**
+     * Two kinds of signal, and only one of them was ever ambiguous.
+     *
+     * `requireRole(...)`, `isAdmin`, `roles.includes(...)` say what they are in the text:
+     * nobody writes `requireRole` to render a label. The comparison — `x.role === 'y'` —
+     * is the one that meant three different things in three repositories, and it is the
+     * one the tree answers.
+     */
+    const unambiguousRoles = await (0, textSearch_1.searchInFiles)(ctx.root, sourceFiles, [/requireRole/i, /isAdmin/i, /SUPER_ADMIN/i, /roles\.includes\(/i], 20);
+    const comparedRoles = guardedRoles
+        ?? excludeChatTurnRoles(await (0, textSearch_1.searchInFiles)(ctx.root, sourceFiles, [/req\.user\.role/i, /user\.role/i, /role\s*===/i], 20));
+    const roleSignals = [...unambiguousRoles, ...comparedRoles].slice(0, 20);
     const permissionSignals = await (0, textSearch_1.searchInFiles)(ctx.root, sourceFiles, [/requirePermission/i, /permission_classes/i, /permissions\.py/i, /authorize\(/i, /\bcan\(/i], 20);
     const resourceLevelSignals = await (0, textSearch_1.searchInFiles)(ctx.root, sourceFiles, [
         /requirePermission/i,

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

@@ -0,0 +1,4 @@
+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;

package/dist/analyzer/structural/loadTypeScript.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadTypeScript = loadTypeScript;
+exports.resetTypeScriptCache = resetTypeScriptCache;
+/**
+ * The TypeScript compiler, loaded when something needs to read structure rather than text.
+ *
+ * This analyzer reads source as prose: it searches for words and reports what it finds.
+ * That is why `/otp/i` matched `VarError::NotPresent`, why `memberId` matched
+ * `ScopedMemberId` in a compiler's symbol table, and why a chat transcript
+ * (`{m.role === "user" ? "Utente" : "Assistente"}`) was read as an authorization model.
+ * Each was patched with a narrower pattern, and a narrower pattern is still a pattern.
+ *
+ * A syntax tree answers questions a regular expression cannot ask: whether a comparison
+ * guards an action or picks a label, whether an identifier is a property or a string in
+ * a table, whether a call is made or merely named.
+ *
+ * Optional, and loaded the way this package already loads the MCP SDK and the AI layer:
+ * a variable specifier so the build does not require it, and a null return rather than a
+ * throw when it is absent. Text search remains the floor. Structure is what a project
+ * that has TypeScript installed — which is most projects with TypeScript in them — gets
+ * on top.
+ */
+let cached;
+const SPECIFIER = 'typescript';
+async function loadTypeScript() {
+    if (cached !== undefined)
+        return cached;
+    try {
+        const loaded = (await import(/* webpackIgnore: true */ SPECIFIER));
+        cached = 'createSourceFile' in loaded ? loaded : loaded.default;
+    }
+    catch {
+        cached = null;
+    }
+    return cached;
+}
+/** For tests that need to observe both paths without reinstalling anything. */
+function resetTypeScriptCache() {
+    cached = undefined;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Whether a comparison against a role decides something or displays something.
+ *
+ * Three separate patches were written for this in one day, each against a shape the
+ * previous one did not cover: a chat transcript comparing `m.role` to `"assistant"`, a
+ * game comparing `part.role` to `'leftGate'`, and JSX picking an icon from
+ * `{m.role === 'editor' ? <Pencil /> : <Eye />}`. All three are the same question, and
+ * text cannot ask it: does this comparison guard an action, or choose a label?
+ *
+ * A syntax tree can. A guard is a condition whose branch leaves — returns, throws, calls
+ * `next()`, answers with a status. A label is a condition whose branches are values: a
+ * string, an element, an emoji.
+ */
+export type RoleCheckKind = 'guard' | 'label';
+export interface RoleCheck {
+    file: string;
+    line: number;
+    snippet: string;
+    kind: RoleCheckKind;
+}
+/**
+ * Reads role comparisons structurally, or returns null when it cannot.
+ *
+ * `null` is not "no roles found" — it is "this question was not asked", and the caller
+ * falls back to searching text. The two answers must not be confused: one is evidence,
+ * the other is silence, which is the distinction this whole product is built on.
+ */
+export declare function readRoleChecks(root: string, files: string[], limit?: number): Promise<RoleCheck[] | null>;

package/dist/analyzer/structural/roleChecks.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRoleChecks = readRoleChecks;
+const readTextFileSafe_1 = require("../../utils/readTextFileSafe");
+const loadTypeScript_1 = require("./loadTypeScript");
+const READABLE = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
+/**
+ * The same line the text layer refuses to quote.
+ *
+ * A parser is happy to read a bundle of forty thousand characters on one line, and a
+ * reader is not: the evidence would be a fragment of generated output nobody wrote. The
+ * text search skips such a line; so does this, for the same reason and at the same
+ * length.
+ */
+const MAX_READABLE_LINE = 500;
+function isGenerated(text) {
+    return text.split(/\r?\n/).some((line) => line.length > MAX_READABLE_LINE);
+}
+/**
+ * What a branch does when it refuses: the shapes that mean "and stop here".
+ *
+ * A `return` is not enough on its own. `if (role === 'assistant') { return 'Assistant'; }`
+ * returns a label, and reading that as a guard put a chat transcript back where the
+ * regexes had it. A refusal returns nothing, or returns the answer to a request; a label
+ * returns a value.
+ */
+function leaves(ts, node) {
+    let found = false;
+    const visit = (child) => {
+        if (found)
+            return;
+        if (ts.isThrowStatement(child)) {
+            found = true;
+            return;
+        }
+        if (ts.isReturnStatement(child)) {
+            // `return;` stops. `return 'Assistant';` answers with a label.
+            if (!child.expression || !isJustAValue(ts, child.expression)) {
+                found = true;
+            }
+            return;
+        }
+        if (ts.isCallExpression(child)) {
+            const text = child.expression.getText();
+            // `next()`, `res.status(403)`, `abort()`, `redirect()` — an answer, not a value.
+            if (/(^|\.)(next|abort|redirect|forbid|deny|unauthorized)$/i.test(text) || /\.status$/.test(text)) {
+                found = true;
+                return;
+            }
+        }
+        ts.forEachChild(child, visit);
+    };
+    visit(node);
+    return found;
+}
+/** A branch that is only a value: a string, an element, a number, an emoji. */
+function isJustAValue(ts, node) {
+    return ts.isStringLiteral(node)
+        || ts.isNoSubstitutionTemplateLiteral(node)
+        || ts.isTemplateExpression(node)
+        || ts.isNumericLiteral(node)
+        || ts.isJsxElement(node)
+        || ts.isJsxSelfClosingElement(node)
+        || ts.isJsxFragment(node);
+}
+function mentionsARole(ts, node) {
+    if (ts.isPropertyAccessExpression(node))
+        return /^roles?$/i.test(node.name.getText());
+    if (ts.isIdentifier(node))
+        return /^roles?$/i.test(node.getText());
+    if (ts.isElementAccessExpression(node))
+        return /['"`]roles?['"`]/i.test(node.argumentExpression.getText());
+    return false;
+}
+/**
+ * Classifies every comparison against something called `role` in one file.
+ *
+ * Deliberately narrow: only `===`, `==`, `!==` and `!=` against a role, which is the
+ * shape all three misreadings had. `roles.includes(x)` and `requireRole(...)` are
+ * already unambiguous in text and need no tree.
+ */
+function readFile(ts, file, text) {
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const checks = [];
+    const visit = (node) => {
+        if (ts.isBinaryExpression(node)
+            && [ts.SyntaxKind.EqualsEqualsEqualsToken, ts.SyntaxKind.EqualsEqualsToken,
+                ts.SyntaxKind.ExclamationEqualsEqualsToken, ts.SyntaxKind.ExclamationEqualsToken]
+                .includes(node.operatorToken.kind)
+            && (mentionsARole(ts, node.left) || mentionsARole(ts, node.right))) {
+            const { line } = source.getLineAndCharacterOfPosition(node.getStart(source));
+            const parent = node.parent;
+            let kind = 'label';
+            if (parent && ts.isIfStatement(parent) && parent.expression === node) {
+                kind = leaves(ts, parent.thenStatement) || (parent.elseStatement && leaves(ts, parent.elseStatement))
+                    ? 'guard'
+                    : 'label';
+            }
+            else if (parent && ts.isConditionalExpression(parent) && parent.condition === node) {
+                // A ternary whose arms are both values is picking one. Anything else may act.
+                kind = isJustAValue(ts, parent.whenTrue) && isJustAValue(ts, parent.whenFalse) ? 'label' : 'guard';
+            }
+            else if (parent && (ts.isJsxExpression(parent) || ts.isJsxAttribute(parent))) {
+                kind = 'label';
+            }
+            else if (parent && ts.isReturnStatement(parent)) {
+                // `return user.role === 'admin'` is a predicate somebody calls to decide.
+                kind = 'guard';
+            }
+            else if (parent && (ts.isArrowFunction(parent) || ts.isParenthesizedExpression(parent))) {
+                /**
+                 * `const canPublish = (member) => member.role === ROLE_EDITOR;`
+                 *
+                 * A function whose whole body is the comparison exists to be asked. Reading it
+                 * as a label lost the one real role check in a fixture written to contain
+                 * exactly one.
+                 */
+                kind = 'guard';
+            }
+            checks.push({
+                file,
+                line: line + 1,
+                snippet: node.getText(source).replace(/\s+/g, ' ').slice(0, 200),
+                kind,
+            });
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return checks;
+}
+/**
+ * Reads role comparisons structurally, or returns null when it cannot.
+ *
+ * `null` is not "no roles found" — it is "this question was not asked", and the caller
+ * falls back to searching text. The two answers must not be confused: one is evidence,
+ * the other is silence, which is the distinction this whole product is built on.
+ */
+async function readRoleChecks(root, files, limit = 40) {
+    const ts = await (0, loadTypeScript_1.loadTypeScript)();
+    if (!ts)
+        return null;
+    const readable = files.filter((file) => READABLE.test(file));
+    if (readable.length === 0)
+        return [];
+    const checks = [];
+    for (const file of readable) {
+        if (checks.length >= limit)
+            break;
+        const text = await (0, readTextFileSafe_1.readTextFileSafe)(root, file);
+        if (!text || isGenerated(text))
+            continue;
+        try {
+            checks.push(...readFile(ts, file, text));
+        }
+        catch {
+            // A file the parser refuses is a file this reading does not cover. The text search
+            // underneath still sees it.
+        }
+    }
+    return checks.slice(0, limit);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@produtype/core",
-  "version": "0.26.1",
+  "version": "0.27.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": {
@@ -48,11 +48,15 @@
     "zod": "^3.23.8"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0"
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "typescript": ">=5.0.0"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/sdk": {
       "optional": true
+    },
+    "typescript": {
+      "optional": true
     }
   },
   "devDependencies": {