@activatus/code-standards 2.0.0 → 3.0.1

package/scripts/renameSymbol.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+// Renames a TypeScript symbol everywhere it is used, with TypeScript's own rename: the same engine as an
+// editor's Rename Symbol (F2). For agents working from the command line. Never use find-and-replace.
+//
+// Run it from the project root, with the file where the symbol is declared:
+//   node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs <file> <currentName> <newName>
+// For example:
+//   node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs components/ui/button/types.ts ButtonProperties ButtonProps
+//
+// To do many renames in one run, list them in a text file, one per line: <file> <currentName> <newName>.
+// Blank lines and lines starting with # are skipped. The renames run in order.
+//   node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs --list renames.txt
+import { readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+// process.argv starts with the node binary and this script's path.
+const FIRST_ARGUMENT_INDEX = 2;
+const LIST_FLAG = "--list";
+// A rename line has three parts: file, current name, new name.
+const RENAME_PARTS = 3;
+const USAGE = [
+	"Usage: node renameSymbol.mjs <file> <currentName> <newName>",
+	"   or: node renameSymbol.mjs --list <file of renames>",
+].join("\n");
+
+// Uses the project's own TypeScript, so the rename matches the project's compiler exactly.
+const requireFromProject = createRequire(
+	path.join(process.cwd(), "package.json"),
+);
+const typescript = requireFromProject("typescript");
+
+const readProjectSettings = () => {
+	const configPath = typescript.findConfigFile(
+		process.cwd(),
+		typescript.sys.fileExists,
+		"tsconfig.json",
+	);
+
+	if (!configPath) {
+		throw new Error(
+			"No tsconfig.json found. Run this from the project root.",
+		);
+	}
+
+	const configFile = typescript.readConfigFile(
+		configPath,
+		typescript.sys.readFile,
+	);
+
+	return typescript.parseJsonConfigFileContent(
+		configFile.config,
+		typescript.sys,
+		path.dirname(configPath),
+	);
+};
+
+const createLanguageService = ({ projectSettings }) => {
+	const host = {
+		getScriptFileNames: () => projectSettings.fileNames,
+		getScriptVersion: () => "0",
+		getScriptSnapshot: (fileName) =>
+			typescript.sys.fileExists(fileName)
+				? typescript.ScriptSnapshot.fromString(
+						typescript.sys.readFile(fileName),
+					)
+				: undefined,
+		getCurrentDirectory: () => process.cwd(),
+		getCompilationSettings: () => projectSettings.options,
+		getDefaultLibFileName: (options) =>
+			typescript.getDefaultLibFilePath(options),
+		fileExists: typescript.sys.fileExists,
+		readFile: typescript.sys.readFile,
+		readDirectory: typescript.sys.readDirectory,
+		directoryExists: typescript.sys.directoryExists,
+		getDirectories: typescript.sys.getDirectories,
+	};
+
+	return typescript.createLanguageService(
+		host,
+		typescript.createDocumentRegistry(),
+	);
+};
+
+// The first place the name appears as a declaration in the file: an interface, type, function, variable or parameter.
+const findDeclarationPosition = ({ sourceFile, currentName }) => {
+	const visit = (node) => {
+		const isDeclarationName =
+			typescript.isIdentifier(node) &&
+			node.text === currentName &&
+			node.parent?.name === node;
+
+		return isDeclarationName
+			? node.getStart(sourceFile)
+			: typescript.forEachChild(node, visit);
+	};
+
+	return visit(sourceFile);
+};
+
+const endOf = (location) =>
+	location.textSpan.start + location.textSpan.length;
+
+const applyEdits = ({ renameLocations, newName }) => {
+	const locationsByFile = Map.groupBy(
+		renameLocations,
+		(location) => location.fileName,
+	);
+
+	for (const [fileName, locations] of locationsByFile) {
+		const originalText = readFileSync(fileName, "utf8");
+		const sortedFromStart = locations.toSorted(
+			(first, second) => first.textSpan.start - second.textSpan.start,
+		);
+		const pieces = sortedFromStart.flatMap((location, index) => {
+			const previousEnd =
+				index === 0 ? 0 : endOf(sortedFromStart[index - 1]);
+			const replacement = `${location.prefixText ?? ""}${newName}${location.suffixText ?? ""}`;
+
+			return [
+				originalText.slice(previousEnd, location.textSpan.start),
+				replacement,
+			];
+		});
+		const lastLocation = sortedFromStart.at(-1);
+
+		writeFileSync(
+			fileName,
+			pieces.join("") + originalText.slice(endOf(lastLocation)),
+		);
+	}
+
+	return locationsByFile.size;
+};
+
+const renameSymbol = ({ filePath, currentName, newName }) => {
+	const projectSettings = readProjectSettings();
+	const languageService = createLanguageService({ projectSettings });
+	const fileName = path.resolve(filePath);
+	const sourceFile = languageService
+		.getProgram()
+		?.getSourceFile(fileName);
+
+	if (!sourceFile) {
+		throw new Error(
+			`${filePath} is not part of the TypeScript project in tsconfig.json.`,
+		);
+	}
+
+	const position = findDeclarationPosition({
+		sourceFile,
+		currentName,
+	});
+
+	if (position === undefined) {
+		throw new Error(`${currentName} is not declared in ${filePath}.`);
+	}
+
+	const renameInfo = languageService.getRenameInfo(
+		fileName,
+		position,
+		{
+			allowRenameOfImportPath: false,
+		},
+	);
+
+	if (!renameInfo.canRename) {
+		throw new Error(
+			`TypeScript cannot rename ${currentName}: ${renameInfo.localizedErrorMessage}`,
+		);
+	}
+
+	const renameLocations = languageService.findRenameLocations(
+		fileName,
+		position,
+		false,
+		false,
+		{
+			providePrefixAndSuffixTextForRename: true,
+		},
+	);
+	const fileCount = applyEdits({ renameLocations, newName });
+	const fileWord = fileCount === 1 ? "file" : "files";
+
+	return `Renamed ${currentName} to ${newName}: ${renameLocations.length} places in ${fileCount} ${fileWord}.`;
+};
+
+// Each line of a list file is one rename: <file> <currentName> <newName>.
+const readRenameList = (listPath) =>
+	readFileSync(listPath, "utf8")
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line !== "" && !line.startsWith("#"))
+		.map((line) => {
+			const [filePath, currentName, newName] = line.split(
+				/\s+/u,
+				RENAME_PARTS,
+			);
+
+			return { filePath, currentName, newName };
+		});
+
+const isCompleteRename = ({ filePath, currentName, newName }) =>
+	Boolean(filePath && currentName && newName);
+
+const commandArguments = process.argv.slice(FIRST_ARGUMENT_INDEX);
+const [firstArgument, secondArgument] = commandArguments;
+const renames =
+	firstArgument === LIST_FLAG && secondArgument
+		? readRenameList(secondArgument)
+		: [
+				{
+					filePath: commandArguments[0],
+					currentName: commandArguments[1],
+					newName: commandArguments[2],
+				},
+			];
+
+if (
+	renames.length > 0 &&
+	renames.every((rename) => isCompleteRename(rename))
+) {
+	// Each rename reloads the project, so it sees the renames before it.
+	for (const rename of renames) {
+		console.log(renameSymbol(rename));
+	}
+} else {
+	console.error(USAGE);
+	process.exitCode = 1;
+}

package/static/templates/.editorconfig

@@ -4,25 +4,22 @@ root = true
 charset = utf-8
 end_of_line = lf
 indent_size = 2
-indent_style = space
+indent_style = tab
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[*.md]
+# Markdown reads a tab as four spaces, so it uses spaces.
+[*.{md,mdx}]
+indent_style = space
 trim_trailing_whitespace = false
 max_line_length = off
 
+# YAML does not allow tabs.
 [*.{yml,yaml}]
+indent_style = space
 indent_size = 2
 
-[*.json]
-indent_size = 2
-
-[Makefile]
-indent_style = tab
-
-[*.go]
-indent_style = tab
-
+# Python's own style guide uses 4 spaces.
 [*.py]
+indent_style = space
 indent_size = 4

package/static/templates/AGENTS.md

@@ -1,6 +1,8 @@
 # [Project Name]
 
-> **NEVER COMMIT CODE.** Do not run `git commit`, `git push`, `git merge`, `git rebase` or `git stash`, and do not create, switch or delete branches. Make the changes, leave them uncommitted in the working tree, and tell the person what you changed. A person reviews and commits every change.
+> [The project's most important rule for agents, stated first so every agent sees it. Usually whether an agent may commit, push or make branches. One line, or a short section if it needs more, such as which agents may commit, when, and how the others ask. See "Project workflow" below.]
+
+> **"go" means carry on.** When the person sends only "go", carry on with the current task. It is never permission to commit, push or open a Pull Request, and it needs no reply asking what they meant.
 
 ## Project overview
 
@@ -35,12 +37,15 @@
 | Type-check | `pnpm typecheck` |
 | Docs site | `pnpm docs:dev` (then open `/docs`) |
 
-## Development workflow
+## Project workflow
+
+[How this project runs its work. These are the project's own decisions, not part of the code standards. Say where they are written up (usually `docs/development/`), then list the rules an agent must follow:]
 
-- **Branches**: `<type>/<short-description>` in kebab-case, e.g. `feat/invoice-export`, `fix/login-redirect-loop`. Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`. Never work directly on `main`.
-- **Commits**: Conventional Commits (`feat: add invoice export`). **People commit — AI agents never do.**
-- **Pull requests**: [review and CI requirements]
-- **Merging**: [merge strategy, e.g. squash and merge]
+- **Who commits**: [whether AI agents may commit, push or make branches, and when]
+- **Branches**: [how branches are named]
+- **Commit messages**: [the commit message format]
+- **Pull requests**: [review and CI requirements, and where Pull Requests merge to]
+- **Merging and releases**: [merge strategy, and how work reaches production]
 
 ## Environment variables
 
@@ -89,15 +94,15 @@ Follow these rules in every change:
   | Never | Always |
   | --- | --- |
   | `btn`, `msg`, `val`, `(e) =>`, `(item, i) =>` | `button`, `message`, `value`, `(event) =>`, `(item, index) =>` |
-  | `inputRef` | `inputReference` |
-  | `deps`, `repo`, `env`, `timeoutMs`, `MAX_` | `dependencies`, `repository`, `environment`, `timeoutMilliseconds`, `MAXIMUM_` |
+  | `deps`, `env`, `timeoutMs`, `MAX_` | `dependencies`, `environment`, `timeoutMilliseconds`, `MAXIMUM_` |
   | `<T>`, `"sm" \| "lg"` | `<ItemType>`, `"small" \| "large"` |
   | `name="email1"` | `name="emailAddress"` |
-  | `lib/`, `helpers/`, `utilities/`, `helpers.ts` | `library/`, `utils/`, a file named after what it does |
+  | `helpers/`, `utilities/`, `helpers.ts` | `utils/`, a file named after what it does |
 
 - **`id` is a word.** Write `id`, `userId`, `user_id` — never `identifier` and never `userID`. `identifier` is only for an outside system's separate field of that name (Linear's readable `ACT-73`).
-- **Dictionary words stay short:** `id`, `docs`, `props`, `utils`, `app`, `url`, `api`, `uat`, `pdf`, `html`, `css`, `json`, `readme`. Case them as words: `imageUrl`, not `imageURL`. Any other short name is written in full. A new dictionary word is added to the Dictionary in the Human-Readable Names standard first (https://activatus-code-standards.vercel.app/Standards/human-readable-names#dictionary), never just used.
+- **Dictionary words stay short:** `id`, `docs`, `lib`, `props`, `ref`, `repo`, `utils`, `app`, `url`, `api`, `uat`, `pdf`, `html`, `css`, `json`, `readme`. Case them as words: `imageUrl`, not `imageURL`. Any other short name is written in full. A new dictionary word is added to the Dictionary in the Human-Readable Names standard first (https://activatus-code-standards.vercel.app/Standards/human-readable-names#dictionary), never just used.
 - **Names owned by someone else stay exactly as they are** — Linear's `id` and `pageInfo`, Node's `cwd` option and `process.env`, React's `ref` and `children`, shadcn/ui's `cn` helper, Next.js's `params`, `searchParams` and `LayoutProps`, HTML attributes, Tailwind classes. The rule is for names we write, not names from someone else's code. Renaming them breaks the code. Give the value a full-word name as soon as it comes into our code: `const workingDirectory = process.cwd();`, then pass `{ cwd: workingDirectory }`.
+- **When a name clashes with a third-party import, rename our own thing first**, to a more specific full-word name: our `createProjectDatabaseClient`, next to Supabase's `createClient`. Rename the import only when both names are third-party, or ours is fixed by a framework (a Next.js route's `GET`). Then use the owner plus the original name, `Link as LucideLinkIcon`. Never rename an import for taste, and never shorten it.
 - **Form fields especially.** A field has one name everywhere it goes: the input's `name` and `id`, the form schema, the API request, the type and the database column (`emailAddress` / `email_address`). Every field has a visible `<label>` in plain English — never a placeholder instead. Option values are words (`"monthly"`), not numbers. Validation messages name the field and say what to do.
 - **The linter only checks some names.** Folders, props, form fields, database columns, routes and environment variables are not linted — check every one of them yourself.
 - **Always `const`.** Never `var`. Use `let` only when a value must be reassigned, with `// eslint-disable-next-line no-restricted-syntax -- <reason>` on the line above.
@@ -112,7 +117,7 @@ Follow these rules in every change:
 - **No nested ternaries. No boolean flag parameters.**
 - **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
 - **Named exports only**, except where a tool requires a default export.
-- **Type names end in `Props` or `Type`.**
+- **Type names end in `Props` or `Type`**, and say what the thing is, not the job it does. A type that only describes one field of a function's props is written inside the `Props`: `StartAgentRunProps` holds its `dependencies`, with no separate `StartAgentRunDependenciesType`.
 - **One component per file.** Server and client components live in separate files.
 - **Component file order**: imports, component, variables, state, `useMemo` values, `useCallback` functions, effects, render. No inline functions in render.
 - **Reusable functions live in a `utils/` folder** — global, section or component level — one folder per function, with an `index.ts`.
@@ -152,8 +157,6 @@ Skill files live in `.agents/skills/`, mirrored to `.claude/commands/`.
 
 ## Out of scope for AI agents
 
-- **Never commit code.** No `git commit`, `git push`, `git merge`, `git rebase` or `git stash`. Leave every change uncommitted for a person to review.
-- Do not create, switch or delete branches.
 - Do not write secrets, tokens or `.env` values into any file.
 - Do not change dependencies or lockfiles unless the task requires it.
 - Do not edit generated files, or third-party code in `node_modules/` or `vendor/`.

package/static/templates/docs/development/coding-standards.md

@@ -12,6 +12,10 @@ This project follows the Activatus Code Standards, installed as the `@activatus/
 
 [For each standard this project skips or changes: its number and name from the setup list, what is different, and why. For example: "7. Prettier — skipped: the project uses Biome for formatting." If nothing differs, write "No differences".]
 
+## Unfinished changes
+
+[Changes from a code standards version that are not done yet, each with its version and number, what is left, and where it is being done. For example: "Version 2, change 4: the standard ESLint config is not switched on yet. Being done in ACT-120." If there are none, write "None".]
+
 ## Related
 
 - [Writing Docs](../overview/writing-docs.md)

package/static/templates/docsSite/docusaurus.config.mjs

@@ -0,0 +1,144 @@
+import { themes as prismThemes } from "prism-react-renderer";
+
+const TITLE_SEPARATOR = " — ";
+const FIRST_GROUP = "overview";
+
+// Each doc is titled "# Group — Menu item". The folder is the menu group and the
+// part after the dash is the menu item. Overview comes first; everything else is alphabetical.
+const generateSidebarItems = async ({
+	defaultSidebarItemsGenerator,
+	docs: pages,
+	...remainingArguments
+}) => {
+	const items = await defaultSidebarItemsGenerator({
+		docs: pages,
+		...remainingArguments,
+	});
+	const titleById = new Map(
+		pages.map((page) => [page.id, page.title]),
+	);
+
+	const labelled = items.map((item) => {
+		if (item.type !== "category") {
+			return item;
+		}
+
+		const children = item.items
+			.map((child) => {
+				if (child.type !== "doc") {
+					return child;
+				}
+				const title = titleById.get(child.id) ?? child.id;
+				const label = title.includes(TITLE_SEPARATOR)
+					? title.split(TITLE_SEPARATOR)[1]
+					: title;
+				return { ...child, label };
+			})
+			.sort((first, second) =>
+				first.label.localeCompare(second.label),
+			);
+
+		const firstDoc = item.items.find((child) => child.type === "doc");
+		const firstTitle = firstDoc
+			? (titleById.get(firstDoc.id) ?? "")
+			: "";
+		const label = firstTitle.includes(TITLE_SEPARATOR)
+			? firstTitle.split(TITLE_SEPARATOR)[0]
+			: item.label;
+		const folder = firstDoc ? firstDoc.id.split("/")[0] : item.label;
+
+		return {
+			...item,
+			label,
+			items: children,
+			customProps: { folder },
+		};
+	});
+
+	return labelled.sort((first, second) => {
+		const firstFolder = first.customProps?.folder ?? "";
+		const secondFolder = second.customProps?.folder ?? "";
+		if (firstFolder === FIRST_GROUP) {
+			return -1;
+		}
+		if (secondFolder === FIRST_GROUP) {
+			return 1;
+		}
+		return String(first.label).localeCompare(String(second.label));
+	});
+};
+
+// TODO: set the project name
+const PROJECT_NAME = "Project Name";
+
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+	title: `${PROJECT_NAME} Docs`,
+	favicon: "images/logo.svg",
+
+	// The docs are only ever served behind the app's /docs route, so this URL is a placeholder.
+	url: "http://localhost:3000",
+	baseUrl: "/docs/",
+
+	// Internal docs must never be indexed by search engines.
+	noIndex: true,
+
+	onBrokenLinks: "throw",
+
+	markdown: {
+		// Plain .md files are read as CommonMark, so < and { in a doc never break the build.
+		format: "detect",
+		mermaid: true,
+	},
+
+	presets: [
+		[
+			"classic",
+			/** @type {import('@docusaurus/preset-classic').Options} */ ({
+				docs: {
+					// The Markdown lives in the project's root docs/ folder, not inside this site.
+					path: "../docs",
+					routeBasePath: "/",
+					sidebarPath: "./sidebars.mjs",
+					sidebarItemsGenerator: generateSidebarItems,
+				},
+				blog: false,
+				theme: {
+					customCss: "./src/css/custom.css",
+				},
+			}),
+		],
+	],
+
+	themes: [
+		["@getcanary/docusaurus-theme-search-pagefind", {}],
+		"@docusaurus/theme-mermaid",
+	],
+
+	themeConfig:
+		/** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({
+			tableOfContents: {
+				minHeadingLevel: 2,
+				maxHeadingLevel: 3,
+			},
+			colorMode: {
+				defaultMode: "light",
+				respectPrefersColorScheme: true,
+			},
+			navbar: {
+				title: `${PROJECT_NAME} Docs`,
+				logo: {
+					alt: "Logo",
+					src: "images/logo.svg",
+				},
+				items: [],
+			},
+			prism: {
+				theme: prismThemes.oneLight,
+				darkTheme: prismThemes.oneDark,
+				additionalLanguages: ["bash", "json"],
+			},
+		}),
+};
+
+export default config;

package/static/templates/docsSite/sidebars.mjs

@@ -0,0 +1,7 @@
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebars = {
+	// Built from the folder structure of the project's docs/ folder
+	docsSidebar: [{ type: "autogenerated", dirName: "." }],
+};
+
+export default sidebars;

package/static/templates/docsSite/src/css/custom.css

@@ -1 +1,7 @@
 /* Theme overrides for the docs site. Empty by default: the stock theme is the standard look. */
+
+/* Code is indented with tabs. Show each tab 2 characters wide, as the editors do. */
+pre,
+code {
+	tab-size: 2;
+}

package/static/templates/docsSite/tsconfig.json

@@ -1,7 +1,7 @@
 {
-  "extends": "@docusaurus/tsconfig",
-  "compilerOptions": {
-    "baseUrl": "."
-  },
-  "exclude": [".docusaurus", "build"]
+	"extends": "@docusaurus/tsconfig",
+	"compilerOptions": {
+		"baseUrl": "."
+	},
+	"exclude": [".docusaurus", "build"]
 }