@affordances/lint 0.0.0-stage → 0.0.0

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @affordances/lint
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Two lint rules for Affordances apps, for ESLint and oxlint's JS plugins:
+
+- `affordances/require-affordance` warns when a control calls a server action (`action`, `formAction`, `onClick`, or `onSubmit` using an import from an `actions` module) outside an `<Affordance>`.
+- `affordances/static-action-name` errors when `defineAction` has no `name`, or a name that isn't a string literal, which codegen can't read.
+
+```bash
+vlt install -D @affordances/lint
+```
+
+```js
+// eslint.config.js
+import affordances from '@affordances/lint'
+
+export default [affordances.configs.recommended]
+```
+
+Docs: [https://github.com/vltpkg/affordances/blob/main/apps/docs/content/guides/lint.mdx](https://github.com/vltpkg/affordances/blob/main/apps/docs/content/guides/lint.mdx)

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { Rule } from "eslint";
+declare const plugin: {
+  meta: {
+    name: string;
+  };
+  rules: {
+    'require-affordance': Rule.RuleModule;
+    'static-action-name': Rule.RuleModule;
+  };
+  configs: Record<string, unknown>;
+};
+export { plugin as default };

package/dist/index.js

@@ -0,0 +1,93 @@
+// src/index.ts
+const isActionsModule = (source) => /(^|\/)actions(\.[jt]sx?)?$/.test(source);
+const jsxName = (node) => node.name.type === "JSXIdentifier" ? node.name.name : void 0;
+const referenced = (expression) => {
+	if (!expression) return [];
+	if (expression.type === "Identifier") return [expression.name];
+	if (expression.type === "CallExpression") {
+		const callee = expression.callee;
+		if (callee.type === "MemberExpression") return referenced(callee.object);
+		return referenced(callee);
+	}
+	if (expression.type === "ArrowFunctionExpression" || expression.type === "FunctionExpression") {
+		const body = expression.body;
+		if (body.type !== "BlockStatement") return referenced(body);
+		return body.body.flatMap((statement) => statement.type === "ExpressionStatement" ? referenced(statement.expression) : statement.type === "ReturnStatement" ? referenced(statement.argument) : []);
+	}
+	if (expression.type === "AwaitExpression") return referenced(expression.argument);
+	return [];
+};
+const plugin = {
+	meta: { name: "affordances" },
+	rules: {
+		"require-affordance": {
+			meta: {
+				type: "suggestion",
+				docs: { description: "Wrap controls that call a server action in <Affordance>, so agents can find them" },
+				schema: [],
+				messages: { missing: "{{name}} is a server action, but this control isn’t inside <Affordance>. Wrap it so agents and the dev overlay can find it." }
+			},
+			create(context) {
+				const actions = /* @__PURE__ */ new Set();
+				return {
+					ImportDeclaration(node) {
+						if (typeof node.source.value !== "string" || !isActionsModule(node.source.value)) return;
+						for (const spec of node.specifiers) if (spec.type === "ImportSpecifier") actions.add(spec.local.name);
+					},
+					JSXAttribute(attribute) {
+						const node = attribute;
+						const name = node.name.name;
+						if (name !== "action" && name !== "formAction" && name !== "onClick" && name !== "onSubmit") return;
+						const value = node.value;
+						if (value?.type !== "JSXExpressionContainer") return;
+						const used = referenced(value.expression).filter((id) => actions.has(id));
+						if (!used.length) return;
+						for (let parent = node.parent; parent; parent = parent.parent) if (parent.type === "JSXElement" && jsxName(parent.openingElement) === "Affordance") return;
+						context.report({
+							node: attribute,
+							messageId: "missing",
+							data: { name: used[0] }
+						});
+					}
+				};
+			}
+		},
+		"static-action-name": {
+			meta: {
+				type: "problem",
+				docs: { description: "defineAction needs a string literal name, so the manifest can be built statically" },
+				schema: [],
+				messages: {
+					literal: "defineAction’s `name` must be a string literal.",
+					missing: "defineAction needs a `name`."
+				}
+			},
+			create(context) {
+				return { CallExpression(node) {
+					const callee = node.callee;
+					if ((callee.type === "Identifier" ? callee.name : callee.type === "MemberExpression" && callee.property.type === "Identifier" ? callee.property.name : void 0) !== "defineAction") return;
+					const [config] = node.arguments;
+					if (config?.type !== "ObjectExpression") return;
+					const name = config.properties.find((p) => p.type === "Property" && p.key.type === "Identifier" && p.key.name === "name");
+					if (!name || name.type !== "Property") return context.report({
+						node,
+						messageId: "missing"
+					});
+					if (name.value.type !== "Literal" || typeof name.value.value !== "string") context.report({
+						node: name.value,
+						messageId: "literal"
+					});
+				} };
+			}
+		}
+	},
+	configs: {}
+};
+plugin.configs.recommended = {
+	plugins: { affordances: plugin },
+	rules: {
+		"affordances/require-affordance": "warn",
+		"affordances/static-action-name": "error"
+	}
+};
+export { plugin as default };

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@affordances/lint",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "Affordances lint rules for ESLint and oxlint: require-affordance, static-action-name",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vltpkg/affordances.git",
+    "directory": "packages/lint"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "devDependencies": {
+    "eslint": "^10"
+  },
+  "peerDependencies": {
+    "eslint": ">=9"
+  },
+  "peerDependenciesMeta": {
+    "eslint": {
+      "optional": true
+    }
+  }
+}