@ai-ecoverse/slicc-shared-web 1.0.0 → 1.1.0

package/README.md

@@ -5,22 +5,24 @@ Configuration shared by SLICC's web repos ([slicc-bios](https://github.com/ai-ec
 | File | What it is | How a repo uses it |
 |---|---|---|
 | `default.json` | Root Renovate preset: automerge on, one dependency per PR, exact pins, 7-day release age (14 for majors, 0 for vulnerability fixes and for our own `@ai-ecoverse` packages, which also jump the PR queue), and a manager for jsDelivr pins inside `src/` | `renovate.json`: `{ "extends": ["github>ai-ecoverse/slicc-shared-web"] }` |
-| `.github/workflows/node-ci.yml` | Reusable CI: `npm ci`, lint, Chromium, integration tests, hotspots in the job summary, coverage/profiles/screenshots as artifacts | `jobs: { ci: { uses: ai-ecoverse/slicc-shared-web/.github/workflows/node-ci.yml@<sha> } }` |
+| `.github/workflows/node-ci.yml` | Reusable CI: `npm ci`, lint, Chromium's system libraries, integration tests, hotspots in the job summary, coverage/profiles/screenshots as artifacts. The browser itself comes from each repo's `pretest` | `jobs: { ci: { uses: ai-ecoverse/slicc-shared-web/.github/workflows/node-ci.yml@vX.Y.Z } }` |
 | `biome.json` | Formatter settings and slicc's strict linter: cognitive complexity ≤ 25, functions ≤ 150 lines, no unused variables or imports, no floating or misused promises, naming conventions, `import type`/`export type`. Test files under `test/` get slicc's test exemptions | `biome.json`: `{ "extends": ["@ai-ecoverse/slicc-shared-web/biome"] }` |
 | `tsconfig.json` | TypeScript base for Node's type stripping | `tsconfig.json`: `{ "extends": "@ai-ecoverse/slicc-shared-web/tsconfig.json", "include": ["src/**/*.ts"] }` |
-| `lefthook.yml` | Pre-commit hooks: Biome, typecheck, no comments, no unit tests in git, diff coverage | `lefthook.yml`: `extends: [node_modules/@ai-ecoverse/slicc-shared-web/lefthook.yml]` |
-| `bin/` | `slicc-lint-comments` (the [slicc no-comment checker](https://github.com/ai-ecoverse/slicc/tree/main/packages/dev-tools/no-comment) at a pinned commit), `slicc-no-unit-tests`, `slicc-diff-cover` | `package.json` scripts and the hooks above |
+| `lefthook.yml` | Pre-commit hooks: Biome, typecheck, no comments, no unit tests in git, AGENTS.md, diff coverage | `lefthook.yml`: `extends: [node_modules/@ai-ecoverse/slicc-shared-web/lefthook.yml]` |
+| `mcr.config.mjs` | Unit-test coverage for JS and TS sources in `src/` (TS types are stripped first), written to `coverage/unit/lcov.info` | `test:unit`: `mcr -c node_modules/@ai-ecoverse/slicc-shared-web/mcr.config.mjs node --test 'test/unit/**/*.test.mjs'` |
+| `bin/` | `slicc-lint` runs every check below plus Biome and, if the repo has one, `typecheck`. `slicc-lint-comments` runs the [slicc no-comment checker](https://github.com/ai-ecoverse/slicc/tree/main/packages/dev-tools/no-comment) at a pinned commit, allowing AGENTS.md. `slicc-agents-md`, `slicc-no-unit-tests` and `slicc-diff-cover` complete the set | `lint`: `slicc-lint`, and the hooks above |
 
-Install it as a dev dependency straight from GitHub, pinned to a commit that Renovate keeps current:
+Install it from npm, and pin the reusable workflow to the matching `vX.Y.Z` tag. Renovate keeps both current without the usual waiting period:
 
 ```sh
-npm install --save-dev github:ai-ecoverse/slicc-shared-web
+npm install --save-dev --save-exact @ai-ecoverse/slicc-shared-web
 ```
 
-The hooks expect two scripts in each repo: `test:unit`, which writes `coverage/unit/lcov.info` (unit tests stay out of git), and, in TypeScript repos, `typecheck`. The reusable workflow expects `lint`, plus `test` for the integration tests.
+The hooks expect two scripts in each repo: `test:unit`, which writes `coverage/unit/lcov.info` (unit tests stay out of git), and, in TypeScript repos, `typecheck`. The reusable workflow expects `lint`, plus `test` for the integration tests, with a `pretest` that installs Chromium (`playwright-core install --no-shell chromium`). The diff-coverage hook runs `diff-cover` through `uvx`, so install [uv](https://docs.astral.sh/uv/) once.
 
 ## Rules every repo follows
 
-- No comments anywhere, and no `.md` files except README.md.
+- No comments anywhere, and no `.md` files except README.md and AGENTS.md.
+- Agent guidance committed to a repo lives in AGENTS.md only, at most 1,000 characters per file. The repo has no CLAUDE.md, not even as a symlink, since Claude reads AGENTS.md. The check covers tracked and untracked files; gitignored local files are personal and stay out of it.
 - Unit tests stay out of git, in a gitignored `test/unit/`. The pre-commit hook requires them to execute every staged line in `src/`.
 - Integration tests are committed and run in CI.

package/bin/slicc-agents-md.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+set -u
+limit=1000
+failed=0
+list="${TMPDIR:-/tmp}/slicc-agents-md.$$"
+git ls-files --cached --others --exclude-standard | grep -E '(^|/)(AGENTS|CLAUDE)\.md$' > "$list" || true
+while IFS= read -r file; do
+  case "$file" in
+    CLAUDE.md | */CLAUDE.md)
+      printf '%s: agent guidance lives in AGENTS.md only, with no CLAUDE.md file or symlink\n' "$file" >&2
+      failed=1
+      ;;
+    *)
+      chars=$(node -e "process.stdout.write(String([...require('node:fs').readFileSync(process.argv[1], 'utf8')].length))" "$file")
+      if [ "$chars" -gt "$limit" ]; then
+        printf '%s: %s characters, the limit is %s\n' "$file" "$chars" "$limit" >&2
+        failed=1
+      fi
+      ;;
+  esac
+done < "$list"
+rm -f "$list"
+exit "$failed"

package/bin/slicc-diff-cover.sh

@@ -1,3 +1,7 @@
 #!/bin/sh
 set -eu
+if ! command -v uvx > /dev/null 2>&1; then
+  printf 'slicc-diff-cover runs diff-cover through uvx; install uv first: https://docs.astral.sh/uv/getting-started/installation/\n' >&2
+  exit 1
+fi
 exec uvx diff-cover@10.6.0 "${1:-coverage/unit/lcov.info}" --compare-branch HEAD --ignore-unstaged --fail-under 100

package/bin/slicc-lint-comments.sh

@@ -8,4 +8,14 @@ if [ ! -f "$dir/check.mjs" ]; then
     curl -fsSL -o "$dir/$file.mjs" "https://raw.githubusercontent.com/ai-ecoverse/slicc/$sha/packages/dev-tools/no-comment/$file.mjs"
   done
 fi
-exec node "$dir/check.mjs" --force "$@"
+report=$(node "$dir/check.mjs" --force "$@" 2>&1) || true
+if [ -z "$report" ]; then
+  printf 'slicc-lint-comments: the no-comment checker produced no report\n' >&2
+  exit 1
+fi
+rest=$(printf '%s\n' "$report" | grep -vE '^ok: |^(.+/)?AGENTS\.md: documentation file is not allowed' || true)
+if [ -n "$rest" ]; then
+  printf '%s\n' "$rest" >&2
+  exit 1
+fi
+printf 'ok: no comments, and no documentation besides README.md and AGENTS.md\n'

package/bin/slicc-lint.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+set -eu
+bin=$(dirname "$(readlink -f "$0")")
+npx --no-install biome check .
+if node -e "process.exit(require('./package.json').scripts?.typecheck ? 0 : 1)"; then
+  npm run --silent typecheck
+fi
+"$bin/slicc-lint-comments.sh"
+"$bin/slicc-no-unit-tests.sh"
+"$bin/slicc-agents-md.sh"

package/lefthook.yml

@@ -11,6 +11,8 @@ pre-commit:
       run: npx --no-install slicc-lint-comments
     - name: no unit tests in git
       run: npx --no-install slicc-no-unit-tests
+    - name: AGENTS.md
+      run: npx --no-install slicc-agents-md
     - name: diff coverage
       glob: "src/**.{js,mjs,ts}"
       run: npm run --silent test:unit && npx --no-install slicc-diff-cover

package/mcr.config.mjs

@@ -0,0 +1,17 @@
+import { stripTypeScriptTypes } from 'node:module';
+
+const strip = (entry) => {
+  if (entry.url.endsWith('.ts')) entry.source = stripTypeScriptTypes(entry.source);
+};
+
+const ours = (url) =>
+  url.includes('/src/') && !url.includes('/node_modules/') && /\.(m?js|ts)$/.test(url);
+
+export default {
+  name: process.env.npm_package_name ?? 'unit',
+  outputDir: 'coverage/unit',
+  reports: ['lcovonly', 'console-details'],
+  all: { dir: 'src', filter: '**/*.{js,mjs,ts}', transformer: strip },
+  entryFilter: (entry) => ours(entry.url),
+  onEntry: strip,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-shared-web",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Shared Renovate, Biome, TypeScript, lefthook and GitHub Actions configuration for SLICC's web repos",
   "type": "module",
   "license": "Apache-2.0",
@@ -25,10 +25,13 @@
     "./biome": "./biome.json",
     "./tsconfig.json": "./tsconfig.json",
     "./lefthook.yml": "./lefthook.yml",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./mcr.config.mjs": "./mcr.config.mjs"
   },
   "bin": {
+    "slicc-agents-md": "bin/slicc-agents-md.sh",
     "slicc-diff-cover": "bin/slicc-diff-cover.sh",
+    "slicc-lint": "bin/slicc-lint.sh",
     "slicc-lint-comments": "bin/slicc-lint-comments.sh",
     "slicc-no-unit-tests": "bin/slicc-no-unit-tests.sh"
   },
@@ -37,10 +40,11 @@
     "biome.json",
     "default.json",
     "lefthook.yml",
+    "mcr.config.mjs",
     "tsconfig.json"
   ],
   "scripts": {
-    "lint": "biome check . && bin/slicc-lint-comments.sh && bin/slicc-no-unit-tests.sh && shellcheck bin/*.sh",
+    "lint": "bin/slicc-lint.sh && shellcheck bin/*.sh",
     "trust": "npx fledgling sync -y --skip-publish",
     "trust:dry": "npx fledgling sync --dry-run -y --skip-publish",
     "release": "semantic-release"