@produtype/core 0.10.2 → 0.17.0

package/dist/analyzer/absenceEvidence.d.ts

@@ -0,0 +1,15 @@
+import type { DetectorEvidence } from './types';
+/**
+ * What was looked for, when nothing was found.
+ *
+ * A finding about something that is not there has no line to cite, and the report said
+ * so with "no direct evidence captured" — a sentence that reads like an admission of
+ * not having looked. It is the weakest thing in a report somebody paid for, and it is
+ * repeated: five findings in one GDPR section carried it in a row.
+ *
+ * The search itself is the evidence. A reader who sees "searched for an export
+ * endpoint: /gdpr/export, exportUserData, personalDataExport, dataSubject" can tell at
+ * a glance whether their own implementation would have been found, and say so when it
+ * would not. That is the difference between a claim and an assertion.
+ */
+export declare function searchedFor(what: string, terms: string[], claim?: string): DetectorEvidence[];

package/dist/analyzer/absenceEvidence.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchedFor = searchedFor;
+/**
+ * What was looked for, when nothing was found.
+ *
+ * A finding about something that is not there has no line to cite, and the report said
+ * so with "no direct evidence captured" — a sentence that reads like an admission of
+ * not having looked. It is the weakest thing in a report somebody paid for, and it is
+ * repeated: five findings in one GDPR section carried it in a row.
+ *
+ * The search itself is the evidence. A reader who sees "searched for an export
+ * endpoint: /gdpr/export, exportUserData, personalDataExport, dataSubject" can tell at
+ * a glance whether their own implementation would have been found, and say so when it
+ * would not. That is the difference between a claim and an assertion.
+ */
+function searchedFor(what, terms, claim) {
+    if (terms.length === 0)
+        return [];
+    return [{
+            type: 'search',
+            value: `searched for ${what}: ${terms.join(', ')}`,
+            ...(claim ? { claim } : {}),
+        }];
+}

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 absenceEvidence_1 = require("./absenceEvidence");
 function depEvidence(deps) {
     return deps.map((d) => ({ type: 'dependency', value: d }));
 }
@@ -56,7 +57,38 @@ async function detectAuth(ctx) {
         /\[\.\.\.nextauth\]/i,
     ], 30);
     const twoFaSignals = await (0, textSearch_1.searchInFiles)(ctx.root, sourceFiles, [/two[_-]?factor/i, /otp/i, /totp/i], 20);
-    const apiKeySignals = await (0, textSearch_1.searchInFiles)(ctx.root, sourceFiles, [/x-api-key/i, /apiKey/i, /API_KEY/, /token\s*scope/i], 20);
+    const apiKeySignals = await (0, textSearch_1.searchInFiles)(ctx.root, sourceFiles, [
+        /**
+         * A key this project checks, not a key it holds.
+         *
+         * `apiKey` and `API_KEY` matched both, and almost every project that calls a
+         * model or a maps service has one of its own. `--api-key YOUR_API_KEY_HERE`, in
+         * the usage text of a script that downloads from YouTube, was enough to decide a
+         * one-page Streamlit application offers an API to other callers — and it was then
+         * asked at medium severity to restrict cross-origin access to it.
+         *
+         * What distinguishes a provider is reading a key out of an incoming request, or
+         * looking one up to see whether it is valid. Holding a secret is what a client
+         * does.
+         */
+        /x-api-key/i,
+        /**
+         * `authorization` on its own is how every session and bearer-token guard reads
+         * its header: `if (!req.headers.authorization) return res.status(401)` is
+         * authentication, not API keys, and matching it made a hardened Express fixture
+         * claim an API-key scheme it does not have.
+         */
+        /headers?\s*[[.(]\s*['"]?x-api-key/i,
+        /**
+         * A verb on its own does not say which side you are on. `check_api_key(api_key)`
+         * in a script that downloads from YouTube is a client making sure its own key
+         * looks right before spending a request on it. What it cannot be is a store of
+         * keys you issued.
+         */
+        /api[_-]?keys?\s*\.\s*(find|where|get|create)/i,
+        /hashed?[_-]?(api[_-]?)?key/i,
+        /token\s*scope/i,
+    ], 20);
     const passwordResetSignals = await (0, textSearch_1.searchInFiles)(ctx.root, sourceFiles, [
         /forgot\s*password/i,
         /password[_-]?reset/i,
@@ -194,12 +226,19 @@ async function detectAuth(ctx) {
         {
             key: 'auth.passwordReset',
             present: passwordResetSignals.length > 0,
-            evidence: snippetEvidence(passwordResetSignals),
+            // The terms, where nothing matched. "No direct evidence captured" reads like
+            // "we did not look"; this lets a reader whose flow is called `recoverAccess`
+            // see in one line why it was missed.
+            evidence: passwordResetSignals.length > 0
+                ? snippetEvidence(passwordResetSignals)
+                : (0, absenceEvidence_1.searchedFor)('a password reset flow', ['"forgot password"', 'password_reset', 'password-reset', '"reset token"', 'django.contrib.auth.urls', 'PasswordResetView', 'devise_for', 'Auth::routes(']),
         },
         {
             key: 'auth.emailVerification',
             present: emailVerificationSignals.length > 0,
-            evidence: snippetEvidence(emailVerificationSignals),
+            evidence: emailVerificationSignals.length > 0
+                ? snippetEvidence(emailVerificationSignals)
+                : (0, absenceEvidence_1.searchedFor)('email verification', ['"verify email"', 'email_verification', 'email-verification', '"confirm email"', 'isEmailVerified']),
         },
         {
             key: 'auth.sessionStrategy',

package/dist/analyzer/detectDeployment.js

@@ -4,15 +4,75 @@ exports.detectDeployment = detectDeployment;
 const textSearch_1 = require("../utils/textSearch");
 async function detectDeployment(ctx) {
     const evidence = [];
-    const keyFiles = ['Dockerfile', 'docker-compose.yml', 'docker-compose.yaml', 'compose.yaml', 'Procfile', 'nginx.conf'];
-    const presentFiles = ctx.files.all.filter((f) => keyFiles.some((k) => f.endsWith(k)) || f.startsWith('.github/workflows/'));
-    for (const f of presentFiles)
+    /**
+     * What a project ships to say how it is run.
+     *
+     * The list held six names and missed the one that mattered on a real product:
+     * `docker-compose.prod.yml`, a production override with its usage documented in the
+     * first three lines. Continuous integration outside GitHub was invisible too, and so
+     * was every platform descriptor.
+     */
+    const keyFiles = [
+        'Dockerfile', 'Containerfile', 'docker-compose.yml', 'docker-compose.yaml', 'compose.yml', 'compose.yaml',
+        'Procfile', 'nginx.conf', 'fly.toml', 'render.yaml', 'railway.json', 'vercel.json', 'netlify.toml',
+        'app.yaml', 'Makefile', 'skaffold.yaml', 'Chart.yaml',
+        /**
+         * How a phone application ships. Its deployment story is a store pipeline, not a
+         * container: `Fastfile`, a Codemagic configuration, signing material and an export
+         * options plist are the artifacts that decide whether a release is reproducible.
+         */
+        'codemagic.yaml', 'Fastfile', 'Appfile', 'ExportOptions.plist', 'key.properties',
+    ];
+    const presentFiles = ctx.files.all.filter((f) => keyFiles.some((k) => f.endsWith(k))
+        // A compose override, whatever it is called: docker-compose.prod.yml, compose.staging.yaml.
+        || /(^|\/)(docker-)?compose\.[\w.-]+\.ya?ml$/i.test(f)
+        || f.startsWith('.github/workflows/')
+        || /(^|\/)(\.gitlab-ci\.yml|\.circleci\/config\.yml|azure-pipelines\.yml|Jenkinsfile|\.woodpecker\.ya?ml)$/i.test(f)
+        || /(^|\/)(k8s|kubernetes|helm|deploy|\.platform)\//i.test(f));
+    for (const f of presentFiles.slice(0, 20))
         evidence.push({ type: 'file', value: f });
-    const hits = await (0, textSearch_1.searchInFiles)(ctx.root, ctx.files.source, [/SIGTERM/i, /SIGINT/i, /NODE_ENV/i, /DEBUG\s*=\s*False/, /healthcheck/i], 20);
+    const hits = await (0, textSearch_1.searchInFiles)(ctx.root, ctx.files.source, [
+        /SIGTERM/i, /SIGINT/i,
+        /**
+         * How a project knows which environment it is in.
+         *
+         * This was `NODE_ENV` and `DEBUG = False` — Node and Django — so a PHP product
+         * reading `APP_ENV` and shipping a production compose override was reported as
+         * having no production-aware configuration at all. Every stack has a name for
+         * this and none of them is NODE_ENV.
+         *
+         * `DJANGO_SETTINGS_MODULE` is deliberately absent: `os.environ.setdefault` of it
+         * sits in every `manage.py` and `wsgi.py` Django has ever generated, so counting
+         * it made a project with no Docker, no CI and `DEBUG = True` report a complete
+         * deployment story on the strength of its own boilerplate.
+         */
+        /\b(NODE_ENV|APP_ENV|RAILS_ENV|RACK_ENV|ASPNETCORE_ENVIRONMENT|FLASK_ENV|GIN_MODE|ENVIRONMENT|PHP_ENV|ENV_NAME|DEPLOY_ENV)\b/,
+        /DEBUG\s*=\s*False/,
+        /healthcheck/i,
+    ], 20);
     for (const m of hits)
         evidence.push({ type: 'snippet', value: m.snippet, file: m.file, line: m.line });
+    /**
+     * Graceful shutdown is a question about a long-lived process.
+     *
+     * PHP-FPM and CGI hand each request to a worker that exits when it is done; there is
+     * no signal for the application to catch, and asking for one is a Node and Go idiom
+     * pointed at a process model that does not have it.
+     *
+     * Decided on the presence of PHP alone: a PHP product's `public/js` does not change
+     * how its requests are served, and requiring the absence of JavaScript meant no real
+     * PHP application ever qualified.
+     */
+    /** PHP-FPM hands each request to a worker that exits when it is done. */
+    const perRequestRuntime = ctx.files.source.some((f) => f.endsWith('.php'));
     const graceful = hits.some((h) => /SIGTERM|SIGINT/i.test(h.snippet));
-    const prodAware = hits.some((h) => /NODE_ENV|DEBUG\s*=\s*False/.test(h.snippet));
+    /**
+     * A file that exists only to describe production is production awareness, whatever
+     * the source says. It is also the more reliable signal of the two.
+     */
+    const productionDescriptor = presentFiles.some((f) => /prod|production/i.test(f));
+    const prodAware = productionDescriptor
+        || hits.some((h) => /\b(NODE_ENV|APP_ENV|RAILS_ENV|RACK_ENV|ASPNETCORE_ENVIRONMENT|FLASK_ENV|GIN_MODE|ENVIRONMENT|PHP_ENV|ENV_NAME|DEPLOY_ENV)\b/.test(h.snippet) || /DEBUG\s*=\s*False/.test(h.snippet));
     return {
         key: 'deployment.readiness',
         present: presentFiles.length > 0 || hits.length > 0,
@@ -22,6 +82,8 @@ async function detectDeployment(ctx) {
             dockerArtifacts: presentFiles.some((f) => /Dockerfile|compose/.test(f)),
             ci: presentFiles.some((f) => f.startsWith('.github/workflows/')),
             gracefulShutdown: graceful,
+            /** False where the runtime hands each request to a worker that exits on its own. */
+            gracefulShutdownApplies: !perRequestRuntime,
             productionAware: prodAware,
         },
     };

package/dist/analyzer/detectGdpr.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectGdpr = detectGdpr;
 const textSearch_1 = require("../utils/textSearch");
+const absenceEvidence_1 = require("./absenceEvidence");
 function toEvidence(matches) {
     return matches.map((m) => ({ type: 'snippet', value: m.snippet, file: m.file, line: m.line }));
 }
@@ -23,31 +24,43 @@ async function detectGdpr(ctx) {
         /delete personal data older than/i,
     ], 20);
     const adminQueue = await (0, textSearch_1.searchInFiles)(ctx.root, ctx.files.source, [/privacy.*queue/i, /gdpr.*queue/i, /data subject request/i, /dsar/i, /admin.*privacy/i], 20);
+    /**
+     * Written out once so the evidence for an absence cannot drift from the search that
+     * produced it: these are the same terms the patterns above match.
+     */
+    const TERMS = {
+        consent: ['a consent record', ['cookie-consent', 'consentGiven', 'privacyConsent', 'gdprConsent']],
+        export: ['an export of personal data', ['/gdpr/export', 'exportUserData', 'personalDataExport', 'dataSubject', 'rightToAccess', '"data portability"']],
+        erasure: ['an erasure flow', ['erasure', '"delete account"', '"right to be forgotten"', '"delete user data"', '"delete personal data"']],
+        retention: ['a retention or purge policy', ['gdpr/privacy near retention/purge/delete', 'retention/purge/delete near personal data', '"delete personal data older than"']],
+        adminQueue: ['a data-subject request queue', ['privacy queue', 'gdpr queue', '"data subject request"', 'dsar', 'admin privacy']],
+    };
+    const evidenceOr = (matches, key) => (matches.length > 0 ? toEvidence(matches) : (0, absenceEvidence_1.searchedFor)(...TERMS[key]));
     return [
         {
             key: 'gdpr.consent.route',
             present: consent.length > 0,
-            evidence: toEvidence(consent),
+            evidence: evidenceOr(consent, 'consent'),
         },
         {
             key: 'gdpr.export.route',
             present: exportRoute.length > 0,
-            evidence: toEvidence(exportRoute),
+            evidence: evidenceOr(exportRoute, 'export'),
         },
         {
             key: 'gdpr.erasure.route',
             present: erasure.length > 0,
-            evidence: toEvidence(erasure),
+            evidence: evidenceOr(erasure, 'erasure'),
         },
         {
             key: 'gdpr.retention.job',
             present: retention.length > 0,
-            evidence: toEvidence(retention),
+            evidence: evidenceOr(retention, 'retention'),
         },
         {
             key: 'gdpr.adminQueue',
             present: adminQueue.length > 0,
-            evidence: toEvidence(adminQueue),
+            evidence: evidenceOr(adminQueue, 'adminQueue'),
         },
     ];
 }

package/dist/analyzer/detectObservability.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectObservability = detectObservability;
 const detectContext_1 = require("./detectContext");
 const textSearch_1 = require("../utils/textSearch");
+const absenceEvidence_1 = require("./absenceEvidence");
 async function detectObservability(ctx) {
     const evidence = [];
     const logDeps = (0, detectContext_1.hasAnyDep)(ctx, ['winston', 'pino', 'morgan', 'bunyan']);
@@ -38,17 +39,54 @@ async function detectObservability(ctx) {
     // Structured logging without a logging library is still structured logging. What
     // matters is that entries are machine-readable and correlated, not which package
     // produced them.
-    const structuredHits = await (0, textSearch_1.searchInFiles)(ctx.root, ctx.files.source, [/JSON\.stringify\(\s*\{[^}]*level/i, /logger\.(info|warn|error|debug)\s*\(/, /structuredLog/i], 15);
+    const structuredHits = await (0, textSearch_1.searchInFiles)(ctx.root, ctx.files.source, [
+        /JSON\.stringify\(\s*\{[^}]*level/i,
+        /logger\.(info|warn|error|debug)\s*\(/,
+        /structuredLog/i,
+        /**
+         * The same idea in the languages this was blind to.
+         *
+         * It looked for `logger.info(` and a JSON.stringify with a level field, which are
+         * JavaScript and Python idioms, and reported "no structured logging dependency
+         * detected" about a PHP application whose global exception handler logs every
+         * exception. Go, Java, Ruby and Rust were invisible for the same reason.
+         */
+        /Monolog\\Logger|LoggerInterface|->(info|warning|error|debug)\(/,
+        /\bslog\.(Info|Warn|Error|Debug)\(|\bzap\.|\blogrus\.|\blog\.Printf\(/,
+        /LoggerFactory\.getLogger|org\.slf4j/,
+        /Rails\.logger/,
+        /\btracing::(info|warn|error|debug)!|\blog::(info|warn|error)!/,
+    ], 15);
     for (const m of structuredHits)
         evidence.push({ type: 'snippet', value: m.snippet, file: m.file, line: m.line, claim: 'logging' });
+    /**
+     * Logging at all, as distinct from logging something a machine can read.
+     *
+     * `error_log($e)` is a real answer to "will we know this happened", and a different
+     * answer from Monolog with a request id. Reporting the first as nothing to show made
+     * the finding wrong; reporting it as structured would make the recommendation wrong.
+     * It is `partial`, and now it can be said.
+     */
+    const plainLogging = await (0, textSearch_1.searchInFiles)(ctx.root, ctx.files.source, [/\berror_log\s*\(/, /\bsyslog\s*\(/, /console\.(error|warn)\s*\(/, /\bprintStackTrace\s*\(/], 10);
+    for (const m of plainLogging)
+        evidence.push({ type: 'snippet', value: m.snippet, file: m.file, line: m.line, claim: 'logging' });
     const hasStructuredLogging = logDeps.length > 0 || structuredHits.length > 0;
+    const hasAnyLogging = hasStructuredLogging || plainLogging.length > 0;
+    if (!hasHealth) {
+        evidence.push(...(0, absenceEvidence_1.searchedFor)('a health endpoint', ['/health', '/healthz', '/readyz', 'a health, healthz, readyz, liveness or readiness route file'], 'health'));
+    }
+    if (!hasAnyLogging) {
+        evidence.push(...(0, absenceEvidence_1.searchedFor)('logging', ['winston', 'pino', 'morgan', 'bunyan', 'Monolog', 'slog', 'zap', 'logrus', 'slf4j', 'Rails.logger', 'tracing::', 'logger.info/warn/error/debug', 'error_log(', 'JSON.stringify with a level field'], 'logging'));
+    }
     return {
         key: 'observability.core',
-        present: hasStructuredLogging || hits.length > 0 || healthFiles.length > 0,
+        present: hasAnyLogging || hits.length > 0 || healthFiles.length > 0,
         complete: hasHealth && hasStructuredLogging,
         evidence,
         details: {
             structuredLogging: hasStructuredLogging,
+            /** Any logging at all, structured or not. */
+            anyLogging: hasAnyLogging,
             healthEndpoint: hasHealth,
             requestId: hasReqId,
             sentry: sentryDeps.length > 0,

package/dist/analyzer/detectSecurity.js

@@ -4,6 +4,7 @@ exports.detectSecurity = detectSecurity;
 const detectContext_1 = require("./detectContext");
 const readTextFileSafe_1 = require("../utils/readTextFileSafe");
 const textSearch_1 = require("../utils/textSearch");
+const absenceEvidence_1 = require("./absenceEvidence");
 function detectCorsConfig(text, file) {
     const loose = [];
     const strict = [];
@@ -99,6 +100,22 @@ async function detectSecurity(ctx) {
         evidence.push({ type: 'snippet', value: m.snippet, file: m.file, line: m.line, claim: 'cors' });
     for (const m of corsStrict)
         evidence.push({ type: 'snippet', value: m.snippet, file: m.file, line: m.line, claim: 'cors' });
+    /**
+     * What was looked for, where nothing was found.
+     *
+     * "No direct evidence captured" reads like "we did not look". These are the same
+     * terms the searches above use, so a reader whose rate limiter is a decorator called
+     * `@throttle` can see in one line why it was missed, and say so.
+     */
+    if (!helmet) {
+        evidence.push(...(0, absenceEvidence_1.searchedFor)('security headers', ['helmet', 'django-csp', 'Content-Security-Policy', 'Strict-Transport-Security', 'X-Content-Type-Options', 'X-Frame-Options', 'SECURE_HSTS_SECONDS', 'securityHeaders'], 'headers'));
+    }
+    if (!rateLimit) {
+        evidence.push(...(0, absenceEvidence_1.searchedFor)('rate limiting', ['express-rate-limit', '@upstash/ratelimit', 'rate-limiter-flexible', 'django-ratelimit', 'slowapi', 'rateLimit(', 'rate_limit', 'Retry-After', '429', 'TooManyRequests'], 'rate-limit'));
+    }
+    if (corsLoose.length === 0 && corsStrict.length === 0) {
+        evidence.push(...(0, absenceEvidence_1.searchedFor)('cross-origin configuration', ['cors(', 'Access-Control-Allow-Origin', 'ALLOWED_ORIGINS', 'allowedOrigins'], 'cors'));
+    }
     const webhookSig = await (0, textSearch_1.searchInFiles)(ctx.root, source, [/constructEvent\(/, /webhook.*signature/i], 10);
     const bodyLimit = await (0, textSearch_1.searchInFiles)(ctx.root, source, [/express\.json\(\s*\{[^}]*limit\s*:/i], 10);
     const contentTypeCheck = await (0, textSearch_1.searchInFiles)(ctx.root, source, [/content-type/i, /req\.is\(/], 10);

package/dist/analyzer/types.d.ts

@@ -27,7 +27,19 @@ export interface StackInfo {
     workspaces: WorkspaceStack[];
 }
 export interface DetectorEvidence {
-    type: 'file' | 'dependency' | 'snippet' | 'note';
+    /**
+     * `search` records a look that came back empty.
+     *
+     * A report about a missing capability has nothing to point at, so eleven findings of
+     * thirty-two in a real report carried the line "no direct evidence captured" — which
+     * reads like "we did not look" rather than "we looked and it is not there". The
+     * reader cannot tell the difference, and an independent review said so.
+     *
+     * The evidence for an absence is the search that found nothing, and the detectors
+     * already know what they searched for. Saying it turns an assertion into something
+     * the reader can check and disagree with.
+     */
+    type: 'file' | 'dependency' | 'snippet' | 'note' | 'search';
     value: string;
     file?: string;
     line?: number;

package/dist/expectations/evaluateExpectations.d.ts

@@ -1,5 +1,19 @@
 import type { ProjectAnalysis } from '../analyzer/types';
-import type { DeclaredIntent, ExpectationEvaluationOutput, ProductProfile } from './types';
+import type { CapabilityImportance, DeclaredIntent, ExpectationEvaluationOutput, ExpectedCapability, ProductProfile } from './types';
+/**
+ * Nine of the twelve used to hardcode their suffix.
+ *
+ * `security.headers` said `.required` even where a profile asks for it as a
+ * recommendation, `deployment.docker` said `.recommended` even where it is required,
+ * and `auth.api-keys` produced a finding titled "(required)" at high severity whose id
+ * read `expectation.auth.api-keys.recommended`. A reader sees both lines, three apart,
+ * and they disagree.
+ *
+ * The suffix is part of the key, so it cannot simply be dropped; it can be made true.
+ * `getRemediationEntry` already matches across the two suffixes — it was written for
+ * exactly this — so the plan still finds its task.
+ */
+export declare function toFindingId(capability: ExpectedCapability, importance: CapabilityImportance): string;
 export declare function evaluateExpectedCapabilities(args: {
     analysis: ProjectAnalysis;
     selectedProfile: Exclude<ProductProfile, 'auto' | 'observed-only'>;