@heyramzi/lint 0.0.0-stage → 1.32.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramzi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,278 @@
-# Temporary Holding Version
+# @heyramzi/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.
+Shared lint rules for Studio projects: one oxlint plugin, the oxlint base config, and the gates a repo's pre-push hook runs.
+
+## Included Tools
+
+- **Oxlint plugin**: the rules below, loaded through `jsPlugins`.
+- **Oxlint base config**: `@heyramzi/lint/oxlint`.
+- **Gates**: `heyramzi-commit-msg`, `heyramzi-comment-length`, `heyramzi-file-tokens`, `heyramzi-inline-path`, `heyramzi-jev-code`, `heyramzi-repo-rules`, `heyramzi-slop` and `heyramzi-svelte-markup`.
+
+There's no ESLint side. The Studio stack doesn't run ESLint, so the flat configs and the
+`heyramzi-lint` pre-commit CLI are gone.
+
+Formatting is not here. Vite+ reads oxfmt settings from the `fmt` block in a repo's
+`vite.config.ts` and ignores `.oxfmtrc.json`, so a shared one was never read: it set tabs,
+single quotes and no semicolons against a measured house style of the opposite, and it was
+deleted on 14 Sep 2026.
+
+## Rules
+
+| Rule | Description |
+| --- | --- |
+| `max-function-lines` | Enforces a maximum number of lines per function. |
+| `no-ai-words` | Blocks common "AI slop" words (e.g., "delve", "embarking"). |
+| `no-emoji` | Prevents the use of raw emojis in source code. `*.test.*`, `*.spec.*`, `__fixtures__/` and `fixtures/` files are exempt. Product code that writes emoji as data turns it off per file with an `overrides` entry (see [Config over comments](#config-over-comments)). |
+| `no-hardcoded-models` | Error. A model id (`claude-…`, `gemini-…`, `gpt-…`, `grok-…`) in a string. Import `MODEL_IDS` or `MODEL_CATALOG` from `@heyramzi/ai`. Files named `ladder.ts`, test and fixture files, and `packages/ai` define or test the ids, so they pass. |
+| `no-inline-svg` | Encourages the use of external SVG components or icons. |
+| `no-inline-path` | Disallows inline SVG `<path>` elements in components. SVGs must be separate files and imported. |
+| `no-raw-try-catch` | Requires the use of structured error handling helpers. |
+| `svelte-section-order` | Enforces a specific order for Svelte 5 section comments. |
+| `no-class` | Prevents the use of classes in favor of functional composition. |
+| `no-default-export` | Enforces named exports for better discoverability and refactoring. |
+| `no-relative-imports` | Error in every preset. Blocks relative specifiers in `import`, `export … from`, `import()`, `require` and `vi.mock`; only `./$types` is exempt. `--fix` rewrites each to the most specific alias covering the target: package.json `imports` first, then tsconfig `paths` for files that tsconfig includes. `.mjs`, `.cjs` and `*.config.*` files get `imports` only, because they run before a bundler applies aliases. A target no alias covers is reported with no fix: add the alias. |
+| `no-relative-type-imports` | Deprecated and off: `no-relative-imports` covers type imports. |
+| `no-em-dash` | Error. Em and en dashes in comments, strings, template text and Svelte text. A spaced hyphen (` - `) fails there too, except where it isn't a dash: a string whose whole value is one em or en dash (an empty-value placeholder), a string or template that is code judged on content (SQL keywords like `SELECT … FROM` or `WHERE`, CSS `calc(` or `var(--`, GLSL `gl_` or `vec2`, JS `function x(`, `=>` or `const x =`), a markdown bullet at the start of a template line or comment line, `<style>`, and `sql`/`css`/`gql`/`html`/`raw` templates. Test and fixture files (`*.test.*`, `*.spec.*`, `__fixtures__/`, `fixtures/`) pass a spaced hyphen because their strings are inputs under test. A real em or en dash fails everywhere except a bare placeholder and a tagged template. |
+| `no-svelte4-syntax` | Error. `export let` and `$:` in a `.svelte` file. Svelte 4 markup is the markup gate's job. |
+| `no-app-stores` | Error. An import from `$app/stores`; read `page` from `$app/state`. |
+| `no-rune-outside-svelte-file` | Error. A rune in a file Svelte doesn't compile, which throws `rune_outside_svelte` at runtime. Rename it `.svelte.ts`. |
+| `no-rune-shadowing-binding` | Error. A top-level binding named `state`, `derived`, `effect`… in a file that calls that rune, which throws `store_invalid_shape`. |
+| `props-interface` | Error, with `--fix`. `type Props = {...}` in a component; write `interface Props`. A union, conditional or mapped type stays a type. |
+| `redirect-external-needs-option` | Error. `redirect()` to a literal absolute URL without `{ external: true }`, a 500 in SvelteKit 3. |
+| `no-redundant-prop-fallback` | Error. A `\|\|` or `??` fallback repeating the default a prop already has, in parameters, `$props()` and markup. |
+| `no-vitest-import-in-vite-plus` | Error. An import from `vitest` in a Vite+ package with no `vitest` dependency of its own; import from `vite-plus/test`. |
+| `no-skipped-or-focused-tests` | Error. `.only`, `.skip("title", fn)`, `xit`, `fit` and kin. A Playwright conditional skip, `test.skip(cond, "reason")`, passes. |
+| `convex-*` | 10 rules, an `overrides` entry on `**/convex/**` in the base config. Error: `require-args` (and the old function syntax), `no-deprecated-crons`, `internal-only` (crons, scheduler, HTTP actions), `no-get-metadata`, `runtime-imports`. Warn while old hits remain: `require-returns`, `no-filter`, `no-v-any`, `no-date-now-in-query`, `index-name`. `convex-react-client-module-scope` is error everywhere. Replaces the `@convex-dev/eslint-plugin` the skill claimed and no repo installed. |
+
+## The alias convention `no-relative-imports` enforces
+
+Every repo in Studio now carries the same shape, applied on 17 Sep 2026 across 26 packages and
+about 13,000 import lines:
+
+- **Runtime aliases live in package.json `imports`**: `"#convex/*": "./convex/*"`. Node, tsx,
+  Vite, esbuild (so Convex), webpack (so Remotion) and WXT all resolve them, and a script run by
+  plain `node` resolves them too, which tsconfig `paths` never does.
+- **TypeScript needs a mirror.** TypeScript 6 does not read `imports`: it matches the subpath and
+  then reports "does not exist in package.json scope", which surfaces as a wall of TS2307. Mirror
+  each entry into the `paths` of the tsconfig that covers those files.
+- **In a SvelteKit app the mirror goes in `kit.alias`**, not in `tsconfig.json`. A `paths` block
+  in the app's own tsconfig replaces the generated one wholesale, which kills `$lib` and makes
+  `svelte-kit sync` warn; `kit.alias` is written into `.svelte-kit/tsconfig.json` instead.
+- **A package that publishes `dist` needs a condition**, or the built file keeps a `#` specifier
+  that points at source the consumer cannot resolve:
+  `"#src/*": { "types": "./src/*", "default": "./dist/*" }`. An array of fallback targets does
+  not work: Node takes the first target and fails rather than trying the second.
+- **A target outside the package** (a sibling directory, a file at the monorepo root) cannot be
+  an `imports` target, because those must start with `./`. Use `kit.alias` or tsconfig `paths`.
+- The rule reads both sources and picks the deepest alias covering the target, so `$lib` wins
+  over `@/` inside `src/lib`. `.mjs`, `.cjs` and `*.config.*` files get `imports` only: they run
+  before a bundler applies an alias.
+
+## Type-Evidence Rules
+
+Ported from [dmmulroy/anti-slop](https://github.com/dmmulroy/anti-slop) (MIT). They reject
+type claims with no evidence behind them.
+
+| Rule | Preset | Description |
+| --- | --- | --- |
+| `no-chained-type-assertions` | `warn` | Blocks `x as unknown as T`. The top type launders the claim so the second assertion always compiles. `as const` chains are allowed. |
+| `no-conditional-empty-object-spread` | `warn` | Blocks `...(cond ? { a } : {})` and `...(cond && { a })`. Build the object in statements and add the property only when it exists. |
+| `no-known-value-widening` | `warn` | Blocks annotating a literal, object, array or function with `unknown`, `any`, `object` or `Record<string, unknown>`. Keep inference or use `satisfies`. Empty containers are exempt. |
+| `require-safety-comment-for-type-assertion` | `off` | Requires a `SAFETY:` comment stating the invariant behind every non-const assertion. Off in the preset: the existing assertion backlog is large enough to bury every other rule. Turn it on per project when that project is ready to pay it down. |
+
+## Installation
+
+```bash
+pnpm add -D @heyramzi/lint
+```
+
+## Usage
+
+### OXLint Configuration
+
+Extend the shared config in `.oxlintrc.json`:
+
+```json
+{
+  "extends": ["@heyramzi/lint/oxlint"],
+  "jsPlugins": ["@heyramzi/lint"]
+}
+```
+
+The `jsPlugins` entry activates the shared stop-slop rules (`no-em-dash`,
+`no-ai-words`, `svelte-section-order`, etc.) inside oxlint.
+
+### Ignores: each repo carries its own
+
+oxlint resolves an extended config's `ignorePatterns` against that config's folder, which in a
+consuming repo is `node_modules/@heyramzi/lint/config`, so they match nothing there. Checked on
+the installed oxlint: a base `ignorePatterns` of `**/.agents/**` still lints `.agents/a.js`.
+An `overrides` entry in the base does reach the repo, but it can only switch listed rules off,
+and the correctness rules run from `categories`, so it can't stand in for an ignore.
+
+Every repo therefore copies this block into its own `.oxlintrc.json` (the same list is
+`ignorePatterns` in `config/oxlintrc.json`):
+
+```json
+"ignorePatterns": [
+  "**/.agents/**", "**/.claude/**", "**/.opencode/**", "**/_generated/**",
+  "**/vendor/**", "**/.upstream/**", "**/*.generated.*", "**/public/**",
+  "**/node_modules/**", "**/dist/**", "build/**", "**/.svelte-kit/**", "**/.next/**",
+  "**/.output/**", "**/.vercel/**", "**/.wrangler/**", "**/coverage/**",
+  "**/scripts/secrets.mjs", "**/scripts/secrets-auto.mjs", "**/scripts/secrets.d.mts"
+]
+```
+
+The last three are the shims `packages/secrets/src/wire.mjs` writes into each package.
+`count-hits.mjs` applies the base list to every count, then names the repos that don't carry it.
+
+### Config over comments
+
+A file that has to break a rule on purpose gets an `overrides` entry in that repo's
+`.oxlintrc.json`, never a disable comment. Product code that writes emoji as data (a parser
+reading check-mark emoji, a template that seeds a Notion page) looks like this:
+
+```json
+"overrides": [
+  { "files": ["**/project/emoji.ts", "**/clickup/clickup-task-fields.ts"],
+    "rules": { "@heyramzi/lint/no-emoji": "off" } }
+]
+```
+
+Test and fixture files need no entry: `no-emoji` skips them already.
+
+### Comment Length Gate
+
+The conduct core caps a comment at 30 words. `heyramzi-comment-length` enforces it over a
+whole repo: block comments, HTML comments and runs of consecutive line comments (`//`, `#`, `--`).
+
+```bash
+pnpm exec heyramzi-comment-length  # non-zero when any comment runs over the cap
+```
+
+It's a hard cap. There's no allowlist, no baseline and no `--update`: a file over the cap fails
+until the comment is cut down, whether it's new or years old.
+
+The same gate fails a comment that marks a hack left in place: a `TODO`, `FIXME` or `HACK` tag,
+"for now", a temporary fix, backward compat, a legacy alias or path, or `@deprecated`. Agents
+copy these along with the hack. Fix what the comment names, then delete it. A word inside
+backticks is a quote and passes. The list is `MARKERS` in `comment-length.js`.
+
+Every tracked `.ts .tsx .js .jsx .mjs .cjs .svelte .swift .py .sh .bash .zsh .css .sql` file is
+read (the hack markers above apply to the first seven only), minus generated and vendored
+trees (`dist`, `build`, `.svelte-kit`, `paraglide`, `vendor`, …) and symlinks. Narrow or widen
+it with an optional `commentLength` key in the repo's root `package.json`:
+
+```json
+{
+  "commentLength": {
+    "targets": ["app/src", "packages"],
+    "extensions": ["ts", "svelte"],
+    "ignore": ["_site"],
+    "max": 30
+  }
+}
+```
+
+The gate only bites when a hook runs it. `bash ai-doc/scripts/pre-push-hooks.sh [repo]`
+(vibe-kit) writes a managed pre-push block into every Studio repo's active hook, whatever its
+`core.hooksPath` (husky, Vite+ `.vite-hooks`, or `.git/hooks`); re-run it after a hook reset.
+
+### Inline Path Gate
+
+Components must not contain inline SVG `<path>` elements: vector graphics belong in separate `.svg` files and imported (e.g. `import icon from './icon.svg?raw'`), keeping component files concise. `heyramzi-inline-path` enforces it.
+
+```bash
+pnpm exec heyramzi-inline-path  # non-zero when any component holds an inline path
+```
+
+Like the comment length gate, it's a hard rule. There's no allowlist, no baseline and no
+suppression comment: every inline `<path d="...">` fails until it moves to a `.svg` file.
+
+Installed into every Studio repo's active pre-push hook by `bash ai-doc/scripts/pre-push-hooks.sh`.
+
+### File Token Gate
+
+No staged file may run past 5,000 tokens, counted as bytes / 4. `heyramzi-file-tokens` reads the
+staged blobs, not the working copy, so it judges exactly what the commit records.
+
+It skips what no person or agent writes by hand: lockfiles, `CHANGELOG.md`, `*.generated.*`,
+minified bundles, source maps, snapshots, SVGs, binaries, generated and vendored trees (`dist`,
+`_generated`, `vendor`, the `.claude/` projections, …), files whose first 2 KB carry a codegen
+header (`@generated`, `Do not edit`, `Generated by`), and paths `.gitattributes` marks
+`linguist-generated`. A pure rename passes. There's no config and no allowlist: a hand-written
+file over the cap is split, and the refusal says how.
+
+`bash ai-doc/scripts/pre-commit-hooks.sh [repo]` (vibe-kit) writes the managed pre-commit block
+into every Studio repo's active hook, the same way `pre-push-hooks.sh` does for pre-push. It
+replaced `eslint/max-lines` (600 code lines) and `CLIs/scripts/check-module-size.mjs`.
+
+### UI Rules Gate
+
+`heyramzi-ui-rules` judges staged files, or `PUSH_FILES` under the pre-push hook, and `--all` for the
+whole tree. It fails on what the impeccable detector misses, and each failure says what to write instead:
+`transition: all`, `scale(0)`, `ease-in`, literal or bare `duration-*`, padding on `.t-acc-panel`, `t-*`
+classes in Swift, zoom-blocking viewports, `user-select: none` on body, `outline-slate|zinc|neutral`, raw
+`:hover` outside `@media (hover: hover)`, a vendored shadcn kit, an `app.css` with no `@source` for
+`@heyramzi/ui/src`, `adapter-cloudflare` without `paths.relative: false`, and a `static/` file under a route.
+No allowlist and no config.
+
+### Svelte Markup Gate
+
+oxlint never reads a `.svelte` template, and skips a file with no `<script>`, so
+`heyramzi-svelte-markup` reads the markup. It fails `<slot>` (outside a custom element),
+`<svelte:component>`, an `on:` directive, a `class:` carrying a Tailwind arbitrary value (it never
+applies; use `style:`), and a self-closing non-void HTML element.
+
+```bash
+pnpm exec heyramzi-svelte-markup        # the pushed .svelte files, or all of them outside a push
+pnpm exec heyramzi-svelte-markup --all  # every tracked .svelte file
+```
+
+Generated and vendored trees are skipped (`DEFAULT_IGNORED` in `svelte-markup.js`). It runs in the
+managed `push gates` block. No allowlist and no config.
+
+### Repo Rules Gate
+
+`heyramzi-repo-rules` judges staged files, and `--all` every tracked file for an audit. Each
+failure says what to do instead. It reads the staged blob, so it judges what the commit records.
+
+- **Package manager:** a staged `package-lock.json`, `yarn.lock`, `bun.lock` or `bun.lockb` fails.
+- **@heyramzi dependencies:** a `link:`, `file:` or path spec fails, and so does any lockfile
+  entry with an `integrity` and no `tarball` URL.
+- **Import maps:** a published `@heyramzi/*` package with `#src` imports maps `"#src/*.js"` to
+  `./src/*.ts` when it ships src, or `"#src/*"` to `{ types, default }` when it ships dist.
+- **Credentials:** an `_authToken` line in a committed `.npmrc`, and the dead
+  `GITHUB_PRIVATE_PACKAGES_TOKEN` name in an install file.
+- **Workflows:** a hosted runner, a write to `~/.npmrc`, a `pull_request` trigger, and any Node
+  that isn't 24.
+- **Toolchain:** ESLint, knip, Prettier, Biome and Husky (dependency, script or config file),
+  hooks copied into `.git/hooks`, the fallow shape (dependency, `.fallowrc.json` schema first, 5
+  scripts, the `fallow` reference in `vibekit.json`, no tracked `.fallow/*.bin`), an
+  `.oxlintrc.json` that doesn't extend the shared base, and a `lint` block in `vite.config`.
+- **Compose:** an `image:` that's `:latest` or untagged, unless the service builds it.
+- **Fossil names:** an added path named `-old`, `-v2`, `-final` or `copy`, or under `misc/` or
+  `temp/`.
+
+No allowlist, no config.
+
+### Commit Message Gate
+
+`heyramzi-commit-msg <file>` is a `commit-msg` hook. It refuses an em or en dash anywhere in the
+message, in every repo. In a repo with a root `release-please-config.json` it also wants a
+Conventional Commit subject (`type(scope): summary`), because release-please reads the type to
+pick the version. Merge, revert, fixup and squash subjects pass.
+
+The same repos refuse a `!` after the type and a `BREAKING CHANGE` footer. A breaking change is a
+minor here, and release-please would cut a major from either one. A major only comes from a
+`Release-As: X.0.0` footer written by hand. The `ui` repo has no release-please config, so the
+gate also treats a root `scripts/release.sh` that mentions `Release-As` as one of those repos.
+
+## Development
+
+- `pnpm test`: runs `node --test` over the rule and gate tests.
+- `node packages/lint/scripts/count-hits.mjs [repo ...]` (from vibe-kit): runs this working copy
+  over one Studio repo or all of them and prints error hits per rule per repo. `--warn` adds
+  warnings, `--rule <name>` filters, `--files` lists each hit, `--json` prints JSON. It writes a
+  temp config into each repo root for the run, because oxlint resolves `ignorePatterns` and plugin
+  paths against the config's folder, then deletes it.

package/bin/heyramzi-comment-length.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * The comment-length gate. Rule: `ai-doc/references/agents-core.md`. Usage and
+ * the `commentLength` config: this package's README.
+ *
+ *   heyramzi-comment-length  # non-zero when any comment runs over the cap
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { exit } from "node:process";
+
+import {
+  DEFAULT_EXTENSIONS,
+  DEFAULT_IGNORED,
+  MAX_WORDS,
+  check,
+  markerHits,
+  maxCommentWords,
+  selectFiles,
+} from "#lint/comment-length.js";
+import { gateFiles } from "#lint/gate-files.js";
+
+const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+const config = readConfig(repoRoot);
+const max = config.max ?? MAX_WORDS;
+
+const args = process.argv.slice(2);
+const all = args.includes("--all");
+const targets = args.filter((arg) => !arg.startsWith("-"));
+if (all) delete process.env.PUSH_FILES;
+
+const ignored = [...DEFAULT_IGNORED, ...(config.ignore ?? [])];
+const candidates =
+  targets.length > 0
+    ? targets
+    : process.env.PUSH_FILES !== undefined
+      ? process.env.PUSH_FILES.split("\n").filter(Boolean)
+      : tracked(repoRoot);
+const files = gateFiles(repoRoot, selectFiles(candidates, { ...config, ignored }));
+
+gate(files);
+
+function readConfig(root) {
+  const manifest = path.join(root, "package.json");
+  if (!existsSync(manifest)) return {};
+  return JSON.parse(readFileSync(manifest, "utf8")).commentLength ?? {};
+}
+
+function tracked(root) {
+  const patterns = (config.extensions ?? DEFAULT_EXTENSIONS).map(
+    (ext) => `*.${ext.replace(/^\./, "")}`,
+  );
+  return execFileSync("git", ["ls-files", ...patterns], { cwd: root, encoding: "utf8" })
+    .trim()
+    .split("\n")
+    .filter(Boolean);
+}
+
+function extOf(file) {
+  return file.slice(file.lastIndexOf(".") + 1);
+}
+
+function measure(files) {
+  const lengths = {};
+  for (const file of files) {
+    lengths[file] = maxCommentWords(readFileSync(path.join(repoRoot, file), "utf8"), extOf(file));
+  }
+  return lengths;
+}
+
+function gate(files) {
+  const failures = check(measure(files), max);
+  const markers = files.flatMap((file) =>
+    markerHits(readFileSync(path.join(repoRoot, file), "utf8"), extOf(file)).map((hit) => ({
+      file,
+      ...hit,
+    })),
+  );
+  if (failures.length === 0 && markers.length === 0) {
+    console.log(`comment length: every comment is ${max} words or fewer, with no hack markers`);
+    return;
+  }
+
+  for (const { file, words } of failures) {
+    console.error(`${file}: longest comment ${words} words (over ${max})`);
+  }
+  if (failures.length > 0) console.error("\nCompress the comment to the point it makes.");
+  for (const { file, line, label } of markers) {
+    console.error(`${file}:${line}: ${label}`);
+  }
+  if (markers.length > 0) {
+    console.error(
+      "\nFix what the comment names, or delete it. No legacy name survives a refactor.",
+    );
+  }
+  exit(1);
+}

package/bin/heyramzi-commit-msg.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * The commit-msg gate. Usage: this package's README, "Commit Message Gate".
+ *
+ *   heyramzi-commit-msg .git/COMMIT_EDITMSG  # non-zero when the message breaks a rule
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { argv, exit } from "node:process";
+
+import { check, report } from "#lint/commit-msg.js";
+
+const messageFile = argv[2];
+if (!messageFile) {
+  console.error("commit-msg: pass the message file git hands the hook");
+  exit(2);
+}
+
+const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+const releaseScript = path.join(repoRoot, "scripts/release.sh");
+const conventional =
+  existsSync(path.join(repoRoot, "release-please-config.json")) ||
+  (existsSync(releaseScript) && readFileSync(releaseScript, "utf8").includes("Release-As"));
+const problems = check(readFileSync(messageFile, "utf8"), { conventional });
+
+if (problems.length > 0) {
+  console.error(report(problems));
+  exit(1);
+}

package/bin/heyramzi-file-tokens.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * The file-token gate over staged files. Usage: this package's README, "File Token Gate".
+ *
+ *   heyramzi-file-tokens  # non-zero when a staged file runs over 5,000 tokens
+ */
+
+import { execFileSync } from "node:child_process";
+import { exit } from "node:process";
+
+import {
+  MAX_TOKENS,
+  check,
+  generatedContent,
+  ignoredPath,
+  report,
+} from "#lint/file-tokens.js";
+
+const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+const git = (args, input) =>
+  execFileSync("git", args, { cwd: repoRoot, input, maxBuffer: 256 * 1024 * 1024 });
+
+const failures = check(stagedSizes(staged().filter((file) => !ignoredPath(file))));
+const real = failures.filter(({ file }) => !generated(file));
+
+if (real.length === 0) {
+  console.log(`file-tokens: every staged file is under ${MAX_TOKENS.toLocaleString("en-US")} tokens`);
+} else {
+  console.error(report(real));
+  exit(1);
+}
+
+/** Added, copied, modified and renamed files. A pure move (R100) changes nothing, so it passes. */
+function staged() {
+  const fields = git(["diff", "--cached", "--name-status", "-M", "-z", "--diff-filter=ACMR"])
+    .toString("utf8")
+    .split("\0");
+  const files = [];
+  for (let index = 0; index < fields.length - 1; ) {
+    const status = fields[index];
+    const paired = status.startsWith("R") || status.startsWith("C");
+    const target = fields[index + (paired ? 2 : 1)];
+    if (status !== "R100") files.push(target);
+    index += paired ? 3 : 2;
+  }
+  return files;
+}
+
+/** Byte size of each file's staged blob, which is what gets committed, not the working copy. */
+function stagedSizes(files) {
+  if (files.length === 0) return {};
+  const lines = git(["cat-file", "--batch-check=%(objectsize)"], files.map((file) => `:${file}`).join("\n"))
+    .toString("utf8")
+    .trim()
+    .split("\n");
+  return Object.fromEntries(
+    files.flatMap((file, index) => (/^\d+$/.test(lines[index]) ? [[file, Number(lines[index])]] : [])),
+  );
+}
+
+/** Content markers or `.gitattributes` say a machine wrote this file. Checked only for files over the cap. */
+function generated(file) {
+  const attribute = git(["check-attr", "--cached", "linguist-generated", "--", file]).toString("utf8");
+  if (/: (set|true)\s*$/.test(attribute)) return true;
+  return generatedContent(git(["cat-file", "blob", `:${file}`]).subarray(0, 8000));
+}

package/bin/heyramzi-inline-path.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * The inline-path gate. Disallows inline SVG <path> elements in components.
+ * SVGs must be separate files (.svg) and imported. Usage in packages/lint/README.md.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { exit } from "node:process";
+
+import {
+  DEFAULT_EXTENSIONS,
+  DEFAULT_IGNORED,
+  check,
+  countInlinePaths,
+  findInlinePaths,
+  selectFiles,
+} from "#lint/inline-path.js";
+import { gateFiles } from "#lint/gate-files.js";
+
+const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+const config = readConfig(repoRoot);
+
+const args = process.argv.slice(2);
+const all = args.includes("--all");
+const targets = args.filter((arg) => !arg.startsWith("-"));
+if (all) delete process.env.PUSH_FILES;
+
+const ignored = [...DEFAULT_IGNORED, ...(config.ignore ?? [])];
+const files = gateFiles(repoRoot, selectFiles(tracked(repoRoot), { ...config, ignored, targets }));
+
+gate(files);
+
+function readConfig(root) {
+  const manifest = path.join(root, "package.json");
+  if (!existsSync(manifest)) return {};
+  return JSON.parse(readFileSync(manifest, "utf8")).inlinePath ?? {};
+}
+
+function tracked(root) {
+  const extensions = config.extensions ?? DEFAULT_EXTENSIONS;
+  const patterns = extensions.map((ext) => `*.${ext.replace(/^\./, "")}`);
+  return execFileSync(
+    "git",
+    ["ls-files", "--cached", "--others", "--exclude-standard", ...patterns],
+    { cwd: root, encoding: "utf8" },
+  )
+    .trim()
+    .split("\n")
+    .filter(Boolean);
+}
+
+function measure(files) {
+  const counts = {};
+  for (const file of files) {
+    counts[file] = countInlinePaths(readFileSync(path.join(repoRoot, file), "utf8"));
+  }
+  return counts;
+}
+
+function gate(files) {
+  const failures = check(measure(files));
+  if (failures.length === 0) {
+    console.log("inline-path: no inline SVG paths");
+    return;
+  }
+
+  for (const { file, count } of failures) {
+    const details = findInlinePaths(readFileSync(path.join(repoRoot, file), "utf8"))
+      .map((m) => `  line ${m.line}: ${m.snippet}`)
+      .join("\n");
+    console.error(`${file}: ${count} inline path(s):\n${details}`);
+  }
+  console.error(
+    "\nSVGs must be separate files (.svg) and imported. Extract inline paths to separate .svg files.",
+  );
+  exit(1);
+}