@webpresso/agent-config 0.4.1 → 0.4.3

package/README.md

@@ -29,11 +29,44 @@ also re-exports the shared low-level primitives sourced from
 - `@webpresso/agent-config/vitest/*`
 - `@webpresso/agent-config/stryker`
 - `@webpresso/agent-config/workers-test`
+- `@webpresso/agent-config/oxlint/*` (policy plugins)
 
 The Vitest surface includes stable group ordering, explicit staged-worker
 selection, and root-aware Node project construction. Consumers keep ownership
 of package-specific worker defaults, include patterns, aliases, and setup files.
 
+## Oxlint policy plugins (consumer SSOT)
+
+Monorepo and other consumer repos load shared policy plugins from
+**`@webpresso/agent-config/oxlint/*`** — not from `@webpresso/agent-kit`.
+
+| Subpath                                              | Purpose                                   |
+| ---------------------------------------------------- | ----------------------------------------- |
+| `@webpresso/agent-config/oxlint/code-safety`         | `as-any` / swallowed-error audit          |
+| `@webpresso/agent-config/oxlint/foundation-purity`   | foundation tier purity                    |
+| `@webpresso/agent-config/oxlint/graphql-conventions` | GraphQL app conventions                   |
+| `@webpresso/agent-config/oxlint/import-hygiene`      | relative-parent, SEA schema/ui ban        |
+| `@webpresso/agent-config/oxlint/monorepo-paths`      | hardcoded repo-root / cross-package paths |
+| `@webpresso/agent-config/oxlint/query-patterns`      | TanStack Query patterns                   |
+| `@webpresso/agent-config/oxlint/testing-quality`     | weak assertion / mock hygiene             |
+| `@webpresso/agent-config/oxlint/tier-boundaries`     | package-tier import direction             |
+| `@webpresso/agent-config/oxlint/path-roles`          | shared path classifiers (no AST)          |
+
+Example `jsPlugins` (package names resolve through Node `exports`; oxlint uses
+createRequire so each subpath needs `default`/`require` conditions):
+
+```json
+{
+  "jsPlugins": [
+    "@webpresso/agent-config/oxlint/import-hygiene",
+    "@webpresso/agent-config/oxlint/tier-boundaries"
+  ]
+}
+```
+
+agent-kit re-exports the same modules for its inject-relative `oxlintrc.json`
+used by `wp lint` on consumers that do not ship a local `.oxlintrc`.
+
 ## Relationship to other packages
 
 - `@webpresso/agent-config` — consumer-installed package surface

package/dist/esm/oxlint/code-safety.d.ts

@@ -0,0 +1,18 @@
+declare const plugin: {
+    meta: {
+        name: string;
+    };
+    rules: {
+        "as-any-audit": {
+            create(context: any): {
+                TSAsExpression(node: any): void;
+            };
+        };
+        "no-swallowed-errors": {
+            create(context: any): {
+                CatchClause(node: any): void;
+            };
+        };
+    };
+};
+export default plugin;

package/dist/esm/oxlint/code-safety.js

@@ -0,0 +1,89 @@
+// @ts-nocheck
+// Webpresso code safety rules — replaces GritQL patterns:
+// - as_any_audit (audit unsafe `as any` casts)
+// - no_swallowed_errors (catch blocks that only console.error)
+const asAnyAudit = {
+    create(context) {
+        return {
+            TSAsExpression(node) {
+                const annotation = node.typeAnnotation;
+                if (annotation.type === "TSAnyKeyword" ||
+                    (annotation.type === "TSTypeReference" &&
+                        annotation.typeName?.type === "Identifier" &&
+                        annotation.typeName.name === "any")) {
+                    context.report({
+                        node: annotation,
+                        message: "Unsafe `as any` cast. Use a specific type, `as unknown`, or a type guard instead.",
+                    });
+                }
+            },
+        };
+    },
+};
+const ALLOWED_ACTIONS = new Set(["throw", "setError", "toast", "reportError", "return"]);
+function hasAllowedAction(body) {
+    if (!body || body.type !== "BlockStatement")
+        return false;
+    for (const stmt of body.body) {
+        if (stmt.type === "ThrowStatement")
+            return true;
+        if (stmt.type === "ReturnStatement")
+            return true;
+        if (stmt.type === "ExpressionStatement" && stmt.expression.type === "CallExpression") {
+            const callee = stmt.expression.callee;
+            // setError(...), reportError(...)
+            if (callee.type === "Identifier" && ALLOWED_ACTIONS.has(callee.name))
+                return true;
+            // toast.error(...)
+            if (callee.type === "MemberExpression" &&
+                callee.object.type === "Identifier" &&
+                ALLOWED_ACTIONS.has(callee.object.name)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function hasConsoleError(body) {
+    if (!body || body.type !== "BlockStatement")
+        return false;
+    for (const stmt of body.body) {
+        if (stmt.type === "ExpressionStatement" &&
+            stmt.expression.type === "CallExpression" &&
+            stmt.expression.callee.type === "MemberExpression" &&
+            stmt.expression.callee.object.type === "Identifier" &&
+            stmt.expression.callee.object.name === "console" &&
+            stmt.expression.callee.property.type === "Identifier" &&
+            stmt.expression.callee.property.name === "error") {
+            return true;
+        }
+    }
+    return false;
+}
+const noSwallowedErrors = {
+    create(context) {
+        return {
+            CatchClause(node) {
+                const body = node.body;
+                if (!body || body.type !== "BlockStatement")
+                    return;
+                if (body.body.length === 0)
+                    return;
+                if (hasConsoleError(body) && !hasAllowedAction(body)) {
+                    context.report({
+                        node,
+                        message: "Catch block only logs with console.error — error is swallowed. Re-throw, return an error value, or use toast.error()/setError()/reportError().",
+                    });
+                }
+            },
+        };
+    },
+};
+const plugin = {
+    meta: { name: "webpresso-safety" },
+    rules: {
+        "as-any-audit": asAnyAudit,
+        "no-swallowed-errors": noSwallowedErrors,
+    },
+};
+export default plugin;

package/dist/esm/oxlint/foundation-purity.d.ts

@@ -0,0 +1,21 @@
+declare const plugin: {
+    meta: {
+        name: string;
+    };
+    rules: {
+        "no-framework-imports": {
+            create(context: any): {
+                ImportDeclaration?: undefined;
+                ExportNamedDeclaration?: undefined;
+                ExportAllDeclaration?: undefined;
+                ImportExpression?: undefined;
+            } | {
+                ImportDeclaration(node: any): void;
+                ExportNamedDeclaration(node: any): void;
+                ExportAllDeclaration(node: any): void;
+                ImportExpression(node: any): void;
+            };
+        };
+    };
+};
+export default plugin;

package/dist/esm/oxlint/foundation-purity.js

@@ -0,0 +1,52 @@
+// @ts-nocheck
+// Foundation purity — prevents framework coupling in the foundation tier.
+// Flags imports from hono, express, fastify, koa in packages/foundation/ files.
+const FORBIDDEN_FRAMEWORKS = new Set(["hono", "express", "fastify", "koa"]);
+function isForbiddenImport(source) {
+    return typeof source === "string" && FORBIDDEN_FRAMEWORKS.has(source.split("/")[0]);
+}
+function isFoundationFile(context) {
+    const filename = typeof context.getFilename === "function" ? context.getFilename() : context.filename;
+    return filename.replaceAll("\\", "/").includes("/packages/foundation/");
+}
+const noFrameworkImports = {
+    create(context) {
+        if (!isFoundationFile(context))
+            return {};
+        function checkImport(source, node) {
+            if (isForbiddenImport(source)) {
+                context.report({
+                    node,
+                    message: `Foundation packages must not depend on HTTP frameworks. Remove import from "${source}" — framework adapters belong in apps or feature packages.`,
+                });
+            }
+        }
+        return {
+            ImportDeclaration(node) {
+                checkImport(node.source.value, node.source);
+            },
+            ExportNamedDeclaration(node) {
+                if (!node.source)
+                    return;
+                checkImport(node.source.value, node.source);
+            },
+            ExportAllDeclaration(node) {
+                if (!node.source)
+                    return;
+                checkImport(node.source.value, node.source);
+            },
+            ImportExpression(node) {
+                if (node.source.type !== "Literal")
+                    return;
+                checkImport(node.source.value, node.source);
+            },
+        };
+    },
+};
+const plugin = {
+    meta: { name: "webpresso-foundation-purity" },
+    rules: {
+        "no-framework-imports": noFrameworkImports,
+    },
+};
+export default plugin;

package/dist/esm/oxlint/graphql-conventions.d.ts

@@ -0,0 +1,23 @@
+declare const plugin: {
+    meta: {
+        name: string;
+    };
+    rules: {
+        "no-singular-graphql-fields": {
+            create(context: any): {
+                TemplateLiteral(node: any): void;
+                Literal(node: any): void;
+            };
+        };
+        "no-inline-graphql-in-app": {
+            create(context: any): {
+                TaggedTemplateExpression?: undefined;
+                TemplateLiteral?: undefined;
+            } | {
+                TaggedTemplateExpression(node: any): void;
+                TemplateLiteral(node: any): void;
+            };
+        };
+    };
+};
+export default plugin;

package/dist/esm/oxlint/graphql-conventions.js

@@ -0,0 +1,202 @@
+// @ts-nocheck
+// Webpresso GraphQL convention rules:
+// - no-singular-graphql-fields: Prevents use of singular table names in GraphQL queries/mutations
+//
+// Hasura auto-generates GraphQL root fields from table names. All Webpresso tables use plural names
+// (e.g., `users`, `organizations`, `projects`). Using singular names (e.g., `user(limit: 1)`)
+// causes runtime errors: "field 'user' not found in type: 'query_root'"
+//
+// This rule scans template literals and string literals for known singular patterns and reports them.
+import { isWebAppSurface, normalizeFilename } from "./path-roles.js";
+// Mapping of singular table patterns to their correct plural/actual GraphQL field names.
+// Format: [singular, correct, description]
+const SINGULAR_TABLE_RULES = [
+    ["user", "users", "users"],
+    ["organization", "organizations", "organizations"],
+    ["member", "members", "members"],
+    ["project", "projects", "projects"],
+    ["entity", "meta_entities", "meta_entities"],
+];
+// Build regex patterns for each singular table name.
+// These detect GraphQL root field usage patterns:
+//   - Query fields:        `user(`, `user {`, `user_by_pk`, `user_aggregate`
+//   - Insert mutations:    `insert_user_one`, `insert_user(`
+//   - Update mutations:    `update_user_by_pk`, `update_user(`
+//   - Delete mutations:    `delete_user_by_pk`, `delete_user(`
+function buildPatterns() {
+    const patterns = [];
+    for (const [singular, correct, label] of SINGULAR_TABLE_RULES) {
+        // Intentional internal-only dynamic regex: `singular` values come from the
+        // static SINGULAR_TABLE_RULES table above, not from user input.
+        // Query root fields: `user {`, `user_by_pk`, `user_aggregate`, `user(where:`, `user(limit:`
+        // Must NOT match plural forms (e.g., `users(`) or compound words (e.g., `user_id`)
+        // For `singular(`, requires GraphQL-like arg after `(` to avoid false positives
+        // on English text like "organization (RLS Block)"
+        patterns.push({
+            regex: new RegExp(`(?<![a-zA-Z_])${singular}(?:` +
+                `\\s*\\{` + // `user {` (field selection)
+                `|_by_pk` + // `user_by_pk`
+                `|_aggregate` + // `user_aggregate`
+                `|\\s*\\(\\s*(?:where|limit|offset|order_by|distinct_on|\\$)` + // `user(where:`, `user(limit:`, `user($var`
+                `)(?!s)`),
+            singular,
+            correct,
+            label,
+            type: "query",
+        });
+        // Insert mutations: `insert_user_one`, `insert_user(`
+        patterns.push({
+            regex: new RegExp(`insert_${singular}(?:_one|\\s*\\()`),
+            singular,
+            correct,
+            label,
+            type: "insert",
+        });
+        // Update mutations: `update_user_by_pk`, `update_user(`
+        patterns.push({
+            regex: new RegExp(`update_${singular}(?:_by_pk|\\s*\\()`),
+            singular,
+            correct,
+            label,
+            type: "update",
+        });
+        // Delete mutations: `delete_user_by_pk`, `delete_user(`
+        patterns.push({
+            regex: new RegExp(`delete_${singular}(?:_by_pk|\\s*\\()`),
+            singular,
+            correct,
+            label,
+            type: "delete",
+        });
+    }
+    return patterns;
+}
+const PATTERNS = buildPatterns();
+const INLINE_GRAPHQL_EXEMPT_PATH_SEGMENTS = [
+    "/.webpresso/generated/",
+    "/packages/sdk/schema-engine/src/emitters/",
+    "/packages/feature/app-core/src/daemon/",
+];
+function getFilename(context) {
+    if (typeof context.getFilename === "function") {
+        return normalizeFilename(context.getFilename());
+    }
+    return normalizeFilename(context.filename);
+}
+function isClientQuerySurface(filename) {
+    const normalized = normalizeFilename(filename);
+    if (!/\.tsx?$/.test(normalized))
+        return false;
+    if (INLINE_GRAPHQL_EXEMPT_PATH_SEGMENTS.some((segment) => normalized.includes(segment))) {
+        return false;
+    }
+    const isFeatureSurface = normalized.includes("/packages/feature/") && normalized.includes("/src/");
+    return isWebAppSurface(normalized) || isFeatureSurface;
+}
+function getNodeStart(node) {
+    if (Array.isArray(node?.range) && typeof node.range[0] === "number") {
+        return node.range[0];
+    }
+    return typeof node?.start === "number" ? node.start : null;
+}
+function isGraphqlCommentTagged(context, node) {
+    const sourceText = context.sourceCode?.getText?.();
+    const start = getNodeStart(node);
+    if (typeof sourceText !== "string" || typeof start !== "number") {
+        return false;
+    }
+    return /\/\*\s*GraphQL\s*\*\/\s*$/.test(sourceText.slice(Math.max(0, start - 40), start));
+}
+function isGqlTag(tag) {
+    if (!tag)
+        return false;
+    if (tag.type === "Identifier")
+        return tag.name === "gql";
+    return (tag.type === "MemberExpression" &&
+        !tag.computed &&
+        tag.property?.type === "Identifier" &&
+        tag.property.name === "gql");
+}
+function checkStringForSingularFields(context, node, text) {
+    // Quick pre-check: skip strings that don't look like GraphQL
+    // GraphQL queries contain `{` or `query` or `mutation` or `subscription`
+    if (!text.includes("{") &&
+        !text.includes("query") &&
+        !text.includes("mutation") &&
+        !text.includes("subscription")) {
+        return;
+    }
+    for (const pattern of PATTERNS) {
+        if (!pattern.regex.test(text))
+            continue;
+        const correctedField = pattern.type === "query"
+            ? pattern.correct
+            : pattern.type === "insert"
+                ? `insert_${pattern.correct}_one`
+                : pattern.type === "update"
+                    ? `update_${pattern.correct}_by_pk`
+                    : `delete_${pattern.correct}_by_pk`;
+        const matched = text.match(pattern.regex)?.[0] ?? `${pattern.singular}`;
+        context.report({
+            node,
+            message: `Singular GraphQL field name '${matched}' — Hasura uses plural table names. ` +
+                `Use '${correctedField}' instead. ` +
+                `All tables use plural names (e.g., users, organizations, projects, members, meta_entities).`,
+        });
+        // Report only the first match per string to avoid noise
+        return;
+    }
+}
+const noSingularGraphqlFields = {
+    create(context) {
+        return {
+            // Check template literals (most GraphQL queries use backticks)
+            TemplateLiteral(node) {
+                // Combine all quasis (static parts) of the template literal
+                const text = node.quasis.map((q) => q.value?.raw ?? q.value?.cooked ?? "").join("");
+                checkStringForSingularFields(context, node, text);
+            },
+            // Check regular string literals (some queries use single/double quotes)
+            Literal(node) {
+                if (typeof node.value !== "string")
+                    return;
+                checkStringForSingularFields(context, node, node.value);
+            },
+        };
+    },
+};
+const noInlineGraphqlInApp = {
+    create(context) {
+        if (!isClientQuerySurface(getFilename(context))) {
+            return {};
+        }
+        function report(node) {
+            context.report({
+                node,
+                message: "Inline GraphQL is banned in client query surfaces. Use generated SDK operations or shared query option factories instead.",
+            });
+        }
+        return {
+            TaggedTemplateExpression(node) {
+                if (!isGqlTag(node.tag))
+                    return;
+                report(node);
+            },
+            TemplateLiteral(node) {
+                if (node.parent?.type === "TaggedTemplateExpression")
+                    return;
+                if (!isGraphqlCommentTagged(context, node))
+                    return;
+                report(node);
+            },
+        };
+    },
+};
+const plugin = {
+    meta: { name: "webpresso-graphql" },
+    rules: {
+        "no-singular-graphql-fields": noSingularGraphqlFields,
+        "no-inline-graphql-in-app": noInlineGraphqlInApp,
+    },
+};
+export default plugin;

package/dist/esm/oxlint/import-hygiene.d.ts

@@ -0,0 +1,38 @@
+export { isAgentKitSeaTreeFile, isPlatformAppFile, isSdkPackageFile, normalizeFilename, } from "./path-roles.js";
+/** Package imports forbidden in agent-kit SEA surfaces (schema + ui paint kits). */
+export declare function isSeaForbiddenPackageImport(source: any): boolean;
+export declare const SEA_FORBIDDEN_IMPORT_MESSAGE = "Agent-kit SEA surfaces (compose / wp_ui_*) must not import `@webpresso/schema` or `@webpresso/ui`. Use the two-tier block registry snapshot/project file and local Zod/HTML paint instead (offline / nondeterminism lock).";
+declare const plugin: {
+    meta: {
+        name: string;
+    };
+    rules: {
+        "no-relative-parent-imports": {
+            create(context: any): {
+                ImportDeclaration(node: any): void;
+                ExportNamedDeclaration(node: any): void;
+                ExportAllDeclaration(node: any): void;
+                ImportExpression(node: any): void;
+            };
+        };
+        "no-src-path-imports": {
+            create(context: any): {
+                ImportDeclaration(node: any): void;
+            };
+        };
+        "no-relative-mock-paths": {
+            create(context: any): {
+                CallExpression(node: any): void;
+            };
+        };
+        "no-forbidden-package-imports": {
+            create(context: any): {
+                ImportDeclaration(node: any): void;
+                ExportNamedDeclaration(node: any): void;
+                ExportAllDeclaration(node: any): void;
+                ImportExpression(node: any): void;
+            };
+        };
+    };
+};
+export default plugin;