activate-agentmd 2.4.0

package/src/lib/versions.js

@@ -0,0 +1,190 @@
+/**
+ * versions.js
+ *
+ * Version pins: the antidote to training-data cutoffs.
+ *
+ * A model's weights remember the API that was current when it was trained —
+ * Pydantic's `.dict()`, Next.js's synchronous `params`, Tailwind's config
+ * file. The project's manifests know which major it actually runs. This
+ * module reads those majors and turns them into short, explicit rules that
+ * `link` writes next to the standards, so the agent is told "this is v2, the
+ * v1 methods are gone" before it writes a line.
+ *
+ * Each entry is hand-written and version-specific on purpose: a wrong pin is
+ * worse than none, so only the breaking differences a model routinely gets
+ * wrong are listed.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/** lib -> major -> rules. Keys are npm names, PyPI names, or "go" / "python". */
+const PINS = {
+  next: {
+    label: "Next.js",
+    13: ["App Router (`app/`) exists but `pages/` is still common; check which this project uses before adding routes."],
+    14: ["App Router with Server Actions (stable). Navigate with `next/navigation`, not `next/router`, inside `app/`."],
+    15: [
+      "Request APIs are async: `await params`, `await searchParams`, `await cookies()`, `await headers()` — synchronous access is deprecated.",
+      "`fetch` is no longer cached by default; opt in with `cache: 'force-cache'` or `revalidate`.",
+      "Ships React 19: `ref` is a prop, `use()` and `useActionState` are available.",
+    ],
+    16: [
+      "Turbopack is the default bundler; do not add webpack-only config without checking it is still needed.",
+      "Request APIs are async only — `params`, `searchParams`, `cookies()`, `headers()` must be awaited; synchronous access was removed.",
+      "`middleware.ts` is `proxy.ts`; the old filename is not picked up.",
+      "Ships React 19: `ref` is a prop, `use()` and `useActionState` are available.",
+    ],
+  },
+  react: {
+    label: "React",
+    18: ["Mount with `createRoot` (not `ReactDOM.render`). Effects double-invoke in StrictMode during development — write them idempotently."],
+    19: [
+      "`ref` is a regular prop on function components — do not use `forwardRef`.",
+      "Use `use()` to read promises/context, `useActionState` and `useFormStatus` for forms; Actions can be passed to `<form action>`.",
+      "`propTypes` and `defaultProps` on function components are ignored; use TypeScript and default parameters.",
+    ],
+  },
+  pydantic: {
+    label: "Pydantic",
+    1: ["Pydantic v1 API: `.dict()`, `.json()`, `@validator`, `class Config`. Do not use v2 names (`model_dump`, `field_validator`)."],
+    2: [
+      "Use `.model_dump()` / `.model_dump_json()` / `.model_validate()` — `.dict()`, `.json()`, `.parse_obj()` are deprecated v1 names.",
+      "Validators are `@field_validator` and `@model_validator`; `@validator` and `@root_validator` are deprecated.",
+      "Configure with `model_config = ConfigDict(...)`, not an inner `class Config`. Use `TypeAdapter` for non-model types.",
+    ],
+  },
+  sqlalchemy: {
+    label: "SQLAlchemy",
+    2: [
+      "Use 2.0 style: `select()` with `session.execute()` / `session.scalars()`; `session.query()` is legacy.",
+      "Declare models with `DeclarativeBase`, `Mapped[...]` and `mapped_column()`; `declarative_base()` and `Column` are legacy.",
+    ],
+  },
+  django: {
+    label: "Django",
+    5: ["Django 5: `db_default` and `GeneratedField` exist; `USE_L10N` was removed; async ORM methods (`aget`, `acreate`, `afirst`) are available."],
+  },
+  prisma: {
+    label: "Prisma",
+    5: ["Prisma 5: `prisma.$extends` for extensions; `@prisma/client` generated in `node_modules` — run `prisma generate` after schema changes."],
+    6: ["Prisma 6: same API as 5; `omit` in queries is stable. Run `prisma generate` after schema changes."],
+    7: [
+      "Prisma 7 has no Rust query engine by default: instantiate the client with a driver adapter (for example `@prisma/adapter-pg`), not a bare `new PrismaClient()`.",
+      "Connection config lives in `prisma.config.ts`, not in the schema's `datasource url`.",
+    ],
+  },
+  tailwindcss: {
+    label: "Tailwind CSS",
+    3: ["Tailwind v3: `tailwind.config.js` with `content` globs, `@tailwind base/components/utilities` in CSS."],
+    4: [
+      "Tailwind v4 is CSS-first: `@import \"tailwindcss\"`, design tokens in `@theme`, `@custom-variant` — there is no `tailwind.config.js` unless the project added `@config`.",
+      "`@apply` in a separate CSS file needs `@reference`. Renamed utilities: `shadow-sm`→`shadow-xs`, `outline-none`→`outline-hidden`, `ring`→`ring-3`, `rounded-sm`→`rounded-xs`.",
+    ],
+  },
+  express: {
+    label: "Express",
+    5: [
+      "Express 5: rejected promises from async handlers reach error middleware automatically — no `next(err)` wrappers needed.",
+      "`req.query` is a read-only getter; route syntax is path-to-regexp v8 (`/{*splat}` instead of `*`, optional segments with `{}`); `res.redirect('back')` is gone.",
+    ],
+  },
+  zod: {
+    label: "Zod",
+    4: [
+      "Zod 4: use top-level formats `z.email()`, `z.uuid()`, `z.url()` — `z.string().email()` is deprecated.",
+      "Error details are `.issues` (not `.errors`); the `message` option is `error`; use `z.strictObject` / `z.looseObject` instead of `.strict()` / `.passthrough()`.",
+    ],
+  },
+  eslint: {
+    label: "ESLint",
+    9: ["ESLint 9 uses flat config (`eslint.config.js`); `.eslintrc*` is ignored unless `ESLINT_USE_FLAT_CONFIG=false`."],
+  },
+  vue: {
+    label: "Vue",
+    3: ["Vue 3: Composition API with `<script setup>`, `defineProps` / `defineEmits`; Options API still works. Vue 2 is end-of-life — do not add Vue 2 patterns like `Vue.extend`."],
+  },
+  go: {
+    label: "Go",
+    // keyed by "1.NN" from the go directive
+    "1.22": ["Go 1.22+: loop variables are per-iteration; `for i := range 10` works; `net/http` ServeMux supports methods and wildcards (`mux.HandleFunc(\"GET /items/{id}\", …)`)."],
+    "1.23": ["Go 1.23+: range-over-func iterators (`iter.Seq`); everything from 1.22 (per-iteration loop vars, method patterns in ServeMux)."],
+    "1.24": ["Go 1.24+: generic type aliases; `testing.B.Loop` for benchmarks; `go tool` directives in go.mod; everything from 1.22/1.23."],
+    "1.25": ["Go 1.25+: `testing/synctest` for concurrent tests; container-aware GOMAXPROCS; everything from 1.22–1.24."],
+  },
+  python: {
+    label: "Python",
+    "3.12": ["Python 3.12+: `type` statement and `class C[T]` generics (PEP 695), `typing.override`, f-strings may nest quotes; `distutils` is gone."],
+    "3.13": ["Python 3.13+: `warnings.deprecated`; everything from 3.12 (PEP 695 generics, `typing.override`)."],
+  },
+};
+
+const major = (range) => {
+  const m = /(\d+)/.exec(String(range || ""));
+  return m ? m[1] : null;
+};
+
+/** Read the majors this project runs, from whichever manifests exist. */
+function detectVersions(cwd) {
+  const found = [];
+  const push = (lib, version, via) => {
+    const table = PINS[lib];
+    if (!table || !version || !table[version]) return;
+    if (found.some((f) => f.lib === lib)) return;
+    found.push({ lib, label: table.label, version, via, rules: table[version] });
+  };
+
+  const pkgPath = path.join(cwd, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    let pkg = null;
+    try { pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")); } catch {}
+    const deps = pkg ? { ...pkg.dependencies, ...pkg.devDependencies } : {};
+    for (const lib of ["next", "react", "prisma", "tailwindcss", "express", "zod", "eslint", "vue"]) {
+      const range = deps[lib] ?? (lib === "prisma" ? deps["@prisma/client"] : undefined);
+      if (range) push(lib, major(range), `package.json (${lib} ${range})`);
+    }
+  }
+
+  for (const file of ["pyproject.toml", "requirements.txt"]) {
+    const p = path.join(cwd, file);
+    if (!fs.existsSync(p)) continue;
+    let text = "";
+    try { text = fs.readFileSync(p, "utf-8"); } catch { continue; }
+    for (const lib of ["pydantic", "sqlalchemy", "django"]) {
+      // "pydantic>=2.6", 'pydantic = "^2"', "SQLAlchemy==2.0.30"
+      const m = new RegExp(`(?:^|[\\s"'\\[])${lib}\\s*(?:=\\s*)?["']?\\s*[~^>=!<]*=?\\s*(\\d+)`, "im").exec(text);
+      if (m) push(lib, m[1], `${file} (${lib} ${m[0].trim().replace(/^["'\[]/, "")})`);
+    }
+    const py = /requires-python\s*=\s*["']\s*[>=~^]*\s*3\.(\d+)/i.exec(text);
+    if (py) push("python", `3.${py[1]}`, `${file} (requires-python)`);
+  }
+
+  const goMod = path.join(cwd, "go.mod");
+  if (fs.existsSync(goMod)) {
+    const m = /^go\s+(\d+\.\d+)/m.exec(fs.readFileSync(goMod, "utf-8"));
+    if (m) {
+      // Pin to the highest table entry at or below the declared version.
+      const declared = Number(m[1].split(".")[1]);
+      const known = Object.keys(PINS.go).filter((k) => k !== "label").map((k) => Number(k.split(".")[1])).filter((n) => n <= declared).sort((a, b) => b - a)[0];
+      if (known !== undefined) push("go", `1.${known}`, `go.mod (go ${m[1]})`);
+    }
+  }
+
+  return found;
+}
+
+/** Markdown block written into the agent config by `link`. */
+function renderPins(pins) {
+  if (!pins.length) return "";
+  const lines = ["### Version pins (detected from this project)", "", "The model's training data may predate these versions. Follow them over habit:", ""];
+  for (const p of pins) {
+    lines.push(`**${p.label} ${p.version}** — _${p.via}_`);
+    for (const r of p.rules) lines.push(`- ${r}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+module.exports = { PINS, detectVersions, renderPins };