@event4u/agent-config 9.7.0 → 9.9.0

package/src/scripts/_lib/persistence/detect_prisma_growth.ts

@@ -0,0 +1,74 @@
+/**
+ * R-A7 growth-budget for Prisma schemas (F7) —
+ * road-to-scale-and-history-discipline Phase 5.
+ *
+ * An append-only-shaped model (name or `@@map` target matching the shared
+ * append-only vocabulary: *_logs, *_events, *_history, audits, jobs, queue,
+ * sessions, notifications, …) must declare a retention policy as a doc
+ * comment on the model (`/// retention: <policy>`) or carry a
+ * `/// no-retention: <reason>` waiver. Same semantics as the raw-SQL
+ * adapter's R-A7 check, applied to schema.prisma.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import type { Finding } from './types.js';
+import { is_ignored_dir } from './types.js';
+import { is_append_only_name } from './adapter_raw_sql.js';
+
+const RETENTION_RE = /\/\/\/?\s*retention\s*:\s*\S/;
+const NO_RETENTION_RE = /\/\/\/?\s*no-retention\s*:\s*(\S.*)$/m;
+
+export function detect_prisma_growth(files: Array<{ path: string; content: string }>): Finding[] {
+    const findings: Finding[] = [];
+    for (const f of files) {
+        const lines = f.content.split('\n');
+        for (let i = 0; i < lines.length; i += 1) {
+            const m = lines[i]!.match(/^\s*model\s+(\w+)\s*\{/);
+            if (!m) continue;
+            // Model body: find the closing brace (prisma blocks are flat).
+            let end = i;
+            for (let j = i + 1; j < lines.length; j += 1) {
+                if (/^\s*\}/.test(lines[j]!)) {
+                    end = j;
+                    break;
+                }
+            }
+            const body = lines.slice(i, end + 1).join('\n');
+            const mapped = body.match(/@@map\(\s*["'](\w+)["']\s*\)/);
+            const table_name = mapped ? mapped[1]! : m[1]!;
+            if (!is_append_only_name(table_name)) continue;
+
+            // Retention/waiver: doc comments directly above the model or inside it.
+            const head = lines.slice(Math.max(0, i - 3), i).join('\n');
+            if (RETENTION_RE.test(head) || RETENTION_RE.test(body)) continue;
+            const waiver = (head + '\n' + body).match(NO_RETENTION_RE);
+            findings.push({
+                failure_class: 'F7',
+                rule: 'R-A7',
+                file: f.path,
+                line: i + 1,
+                message: `model ${m[1]} (table ${table_name}) looks append-only but declares no retention policy (add "/// retention: <policy>" or a no-retention waiver)`,
+                tier: 'gate',
+                ...(waiver ? { waived: true, waiver_reason: waiver[1]!.trim() } : {}),
+            });
+        }
+    }
+    return findings;
+}
+
+export function scan_dir(dir: string): Finding[] {
+    const files: Array<{ path: string; content: string }> = [];
+    const walk = (d: string): void => {
+        for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+            const p = path.join(d, e.name);
+            if (e.isDirectory()) {
+                if (!is_ignored_dir(e.name)) walk(p);
+            } else if (e.name.endsWith('.prisma')) {
+                files.push({ path: p, content: fs.readFileSync(p, 'utf8') });
+            }
+        }
+    };
+    walk(dir);
+    return detect_prisma_growth(files);
+}

package/src/scripts/_lib/persistence/offload_catalog.ts

@@ -0,0 +1,73 @@
+/**
+ * Offloadable-call catalog for R-A8 (thin-request-path, F9) and R-A10
+ * (durable-async, F11) — spike S0.5, road-to-scale-and-history-discipline.
+ *
+ * The catalog is CONFIG DATA, not detector logic: a positive list of
+ * expensive call classes per stack. A single indexed insert or a cache op is
+ * never in the catalog — over-application (queueing trivially cheap work) is
+ * the failure mode this shape prevents.
+ */
+
+export interface CatalogEntry {
+    /** Regex source matched against a single (masked) code line. */
+    pattern: string;
+    /** Human label used in the finding message. */
+    label: string;
+    /**
+     * Whether losing this work silently is unacceptable (drives F11 for
+     * fire-and-forget shapes): promised emails, billing, webhooks out.
+     */
+    must_not_lose: boolean;
+}
+
+export interface StackCatalog {
+    /** Offloadable call classes — firing inside a request handler is F9. */
+    offloadable: CatalogEntry[];
+    /**
+     * Patterns that are the CORRECT offload shape — their presence on the
+     * same line neutralizes an offloadable match (e.g. Mail::queue).
+     */
+    allowed_alternatives: string[];
+}
+
+export const ELOQUENT_CATALOG: StackCatalog = {
+    offloadable: [
+        { pattern: String.raw`\bMail::send\s*\(`, label: 'synchronous mail send', must_not_lose: true },
+        { pattern: String.raw`\bMail::to\s*\([^)]*\)\s*->\s*send\s*\(`, label: 'synchronous mail send', must_not_lose: true },
+        { pattern: String.raw`\bHttp::`, label: 'outbound HTTP call', must_not_lose: false },
+        { pattern: String.raw`\b(PDF|Pdf)::loadView\s*\(`, label: 'PDF generation', must_not_lose: false },
+        { pattern: String.raw`\bExcel::store\s*\(`, label: 'spreadsheet export to storage', must_not_lose: false },
+        { pattern: String.raw`\bImage::make\s*\(`, label: 'image processing chain', must_not_lose: false },
+        { pattern: String.raw`\bBrowsershot::`, label: 'headless-browser rendering', must_not_lose: false },
+        { pattern: String.raw`new\s+\\?Stripe\\StripeClient\b|\bStripe\\\w+::`, label: 'payment SDK call', must_not_lose: true },
+        { pattern: String.raw`\bTwilio\\|\bnew\s+\\?Twilio\b`, label: 'SMS/voice SDK call', must_not_lose: true },
+        { pattern: String.raw`\bOpenAI::|\bAnthropic\\|\bAnthropic::`, label: 'ML/AI inference call', must_not_lose: false },
+    ],
+    allowed_alternatives: [
+        String.raw`\bMail::queue\s*\(`,
+        String.raw`->\s*queue\s*\(`,
+    ],
+};
+
+export const TS_CATALOG: StackCatalog = {
+    offloadable: [
+        { pattern: String.raw`\.sendMail\s*\(`, label: 'synchronous mail send', must_not_lose: true },
+        { pattern: String.raw`\b(fetch|axios(\.\w+)?)\s*\(\s*['"\`]https?://`, label: 'outbound HTTP call', must_not_lose: false },
+        { pattern: String.raw`\bpuppeteer\.launch\s*\(|\bchromium\.launch\s*\(`, label: 'headless-browser rendering', must_not_lose: false },
+        { pattern: String.raw`\bsharp\s*\([^)]*\)\s*\.`, label: 'image processing chain', must_not_lose: false },
+        { pattern: String.raw`\.chat\.completions\.create\s*\(|\banthropic\.messages\.create\s*\(`, label: 'ML/AI inference call', must_not_lose: false },
+        { pattern: String.raw`\bstripe\.\w+(\.\w+)*\.create\s*\(`, label: 'payment SDK call', must_not_lose: true },
+        { pattern: String.raw`\.updateMany\s*\(\s*\{\s*data\s*:`, label: 'unbounded bulk mutation', must_not_lose: false },
+    ],
+    allowed_alternatives: [
+        String.raw`\bqueue\.add\s*\(`,
+        String.raw`\.add\s*\(\s*['"\`]`,
+    ],
+};
+
+/**
+ * Job-class names whose loss is unacceptable — drives the
+ * dispatchAfterResponse / fire-and-forget F11 checks.
+ */
+export const MUST_NOT_LOSE_NAME_RE =
+    /(Mail|Email|Invoice|Webhook|Payment|Billing|Notification|Receipt)/;

package/src/scripts/_lib/persistence/types.ts

@@ -0,0 +1,109 @@
+/**
+ * Shared types for the persistence-lint substrate (lint_persistence).
+ *
+ * Failure classes F1–F11 and rule ids R-A1…R-A11 / R-B1…R-B5 are defined in
+ * agents/roadmaps/archive/road-to-scale-and-history-discipline.md (roadmap) and,
+ * post-merge, in the scale-discipline / history-discipline pack rules.
+ *
+ * "Deterministic" throughout means: deterministic PATTERN detection with an
+ * auditable waiver process — the linter identifies the pattern class
+ * mechanically; instance-level correctness is contextual and handled by a
+ * reasoned waiver, never by the linter claiming judgment it does not have.
+ */
+
+export type FailureClass =
+    | 'F1' // N+1 queries
+    | 'F2' // missing indexes
+    | 'F3' // unbounded selects
+    | 'F6' // unsafe migrations
+    | 'F7' // unbounded table growth
+    | 'F8' // missing audit history
+    | 'F9' // sync work in request path
+    | 'F11'; // non-durable async
+
+export type FindingTier = 'gate' | 'advice';
+
+export interface Finding {
+    failure_class: FailureClass;
+    rule: string; // e.g. "R-A6"
+    file: string; // repo-relative path
+    line: number; // 1-indexed
+    message: string;
+    tier: FindingTier;
+    /** Set when the offending line carries a recognized waiver. */
+    waived?: boolean;
+    /** The waiver reason text, when present. */
+    waiver_reason?: string;
+}
+
+export interface ScanResult {
+    findings: Finding[];
+    /** Files the adapter looked at (for coverage reporting). */
+    scanned_files: string[];
+    /** Waivers encountered, incl. empty-reason violations. */
+    waivers: WaiverRecord[];
+}
+
+export interface WaiverRecord {
+    file: string;
+    line: number;
+    kind: string; // 'no-index' | 'sync-required' | 'accepted-loss' | 'no-retention' | 'migration-unsafe'
+    reason: string; // empty string = hygiene violation
+}
+
+/**
+ * Waiver comment grammar (shared across adapters):
+ *   PHP/TS:  // <kind>: <reason>     e.g. // no-index: read-heavy analytics column
+ *   SQL:     -- <kind>: <reason>
+ * Recognized kinds: no-index, sync-required, accepted-loss, no-retention,
+ * migration-unsafe.
+ */
+export const WAIVER_KINDS = [
+    'no-index',
+    'sync-required',
+    'accepted-loss',
+    'no-retention',
+    'migration-unsafe',
+] as const;
+
+const WAIVER_RE = new RegExp(
+    String.raw`(?://|--|#)\s*(${WAIVER_KINDS.join('|')})\s*:\s*(.*)$`,
+);
+
+/** Parse a waiver on the given line (or the line directly above). */
+export function parse_waiver(lines: string[], idx0: number): WaiverRecord | null {
+    for (const i of [idx0, idx0 - 1]) {
+        if (i < 0 || i >= lines.length) continue;
+        const m = lines[i]!.match(WAIVER_RE);
+        if (m) {
+            return { file: '', line: i + 1, kind: m[1]!, reason: (m[2] ?? '').trim() };
+        }
+    }
+    return null;
+}
+
+/** Directory names every persistence walker skips (dependency/build trees). */
+export const IGNORED_DIRS: ReadonlySet<string> = new Set([
+    'vendor',
+    'node_modules',
+    'storage',
+    '.git',
+    'bootstrap',
+    'dist',
+    'build',
+    '.next',
+    'coverage',
+    // Test trees are not production read paths — R-A1/A2/A3/A8 target
+    // production code; test-suite queries run against small fixtures. The
+    // scan ROOT itself is never name-checked, so pointing the linter AT a
+    // fixture tree still works.
+    'tests',
+    'Tests',
+    'test',
+    '__tests__',
+    'spec',
+]);
+
+export function is_ignored_dir(name: string): boolean {
+    return IGNORED_DIRS.has(name) || name.startsWith('.');
+}