From 88657c9fa6b41379e0dd7ecd23932823dfd5e0ea Mon Sep 17 00:00:00 2001 From: Slate Rehm Date: Tue, 1 Sep 2026 18:41:43 -0500 Subject: [PATCH] docs(semark): align skill guidance with check-semark.mjs Correct Oxlint plugin guidance, source scope, audit labels, and method signature checker scope. Run Semark validation inside pnpm check. Co-authored-by: Cursor --- .../semark-protocol/references/audit.md | 15 ++++++++++++++ .../semark-protocol/references/install.md | 20 ++++++++++--------- .../semark-protocol/rules/method-signature.md | 16 ++++++++++----- .../semark-protocol/rules/source-scope.md | 13 ++++++++++-- .../semark-protocol/rules/validation.md | 15 +++++++++----- .github/workflows/ci.yml | 3 --- .github/workflows/release.yml | 1 - AGENTS.md | 5 ++++- package.json | 2 +- 9 files changed, 63 insertions(+), 27 deletions(-) diff --git a/.agents/skills/semark-protocol/references/audit.md b/.agents/skills/semark-protocol/references/audit.md index 64cf704..8bc34a9 100644 --- a/.agents/skills/semark-protocol/references/audit.md +++ b/.agents/skills/semark-protocol/references/audit.md @@ -22,6 +22,21 @@ Do not infer semantic inaccuracy from wording alone. Read more evidence when a f depends on behavior. Use the implementation, related types, callers, and tests as evidence when necessary. +## Map checker labels to audit categories + +When the repository uses `scripts/check-semark.mjs`, translate checker labels in the +`[label]` field to audit categories: + +| Checker label | Audit categories | +| --- | --- | +| `readme-coverage` | `README_MISSING`, `README_NAME_INVALID` | +| `file-signature` | `FILE_SIGNATURE_MISSING`, `FILE_SIGNATURE_POSITION`, `FILE_SIGNATURE_FORMAT`, `TSDOC_INVALID`, `TAG_ORDER_INVALID`, `LENGTH_LIMIT` | +| `method-signature` | `METHOD_SIGNATURE_MISSING`, `METHOD_SIGNATURE_POSITION`, `METHOD_SIGNATURE_FORMAT`, `TSDOC_INVALID`, `TAG_ORDER_INVALID`, `LENGTH_LIMIT` | +| `comment-policy` | `COMMENT_UNAUTHORIZED`, `DIRECTIVE_INVALID` | + +Use `SIGNATURE_STALE`, `NAME_AMBIGUOUS`, and `CONFIGURATION_INVALID` when the finding +does not map to a checker label. + ## Use stable finding categories - `README_MISSING` diff --git a/.agents/skills/semark-protocol/references/install.md b/.agents/skills/semark-protocol/references/install.md index bdcde0e..a197fb0 100644 --- a/.agents/skills/semark-protocol/references/install.md +++ b/.agents/skills/semark-protocol/references/install.md @@ -73,9 +73,14 @@ existing comment. ## Add validation -If the repository uses Oxlint, configure the GitHub Packages registry for the -`@paperkeel` scope. Install `@paperkeel/oxlint-plugin-semark`. Load it through -`jsPlugins` and enable `semark/valid` in the root Oxlint configuration. +Add the smallest local tool that can check the configured scope, placement, tags, +order, lengths, directives, and comment policy. This repository uses +`scripts/check-semark.mjs` through `pnpm semark:check`. + +In other repositories that use Oxlint, you may optionally install +`@paperkeel/oxlint-plugin-semark`. Configure the GitHub Packages registry for the +`@paperkeel` scope. Load the plugin through `jsPlugins` and enable `semark/valid` in +the root Oxlint configuration. Keep the scope-to-registry mapping in the project `.npmrc` file. Keep the token mapping in the trusted user-level `.npmrc` file. Do not commit a package token. @@ -85,12 +90,9 @@ For GitHub Actions, grant the consuming repository read access under the package `actions/setup-node` with the GitHub Packages registry and `@paperkeel` scope. Pass the repository `GITHUB_TOKEN` as `NODE_AUTH_TOKEN` to the dependency installation step. -Use a repository-local validator for requirements outside the Oxlint rule boundary. -These requirements can include README coverage, migration scope, exclusions, naming, -and changed-code signature updates. - -If the repository does not use Oxlint, add the smallest local tool that can check the -configured scope, placement, tags, order, lengths, directives, and comment policy. +Use a repository-local validator for requirements outside the local-script or Oxlint +rule boundary. These requirements can include README coverage, migration scope, +exclusions, naming, and changed-code signature updates. Make the check return a nonzero status for violations. Report the file, source location, and violation type. diff --git a/.agents/skills/semark-protocol/rules/method-signature.md b/.agents/skills/semark-protocol/rules/method-signature.md index 922fbc1..7b20834 100644 --- a/.agents/skills/semark-protocol/rules/method-signature.md +++ b/.agents/skills/semark-protocol/rules/method-signature.md @@ -1,16 +1,22 @@ # Method signatures -Add one method signature to each callable implementation with a stable source location. -Coverage includes: +Add one method signature to each callable implementation with a block body and a +stable source location. Coverage includes: - function declarations +- generator functions (`function*`) - class methods and constructors - accessors -- named function expressions -- arrow functions or function expressions assigned to a variable or property +- named function expressions with a block body +- arrow functions or function expressions assigned to a variable or property when the + body is a block - object methods - callbacks with a block body -- hooks and exported callables +- hooks and exported callables with a block body + +Expression-bodied arrow functions and single-expression callbacks are out of scope for +`scripts/check-semark.mjs` in this repository. Repositories with a different validator +may enforce them. Do not add a separate signature to an overload declaration without a body. The implementation signature documents the complete overload behavior. Exclude ambient diff --git a/.agents/skills/semark-protocol/rules/source-scope.md b/.agents/skills/semark-protocol/rules/source-scope.md index e107273..8219d2d 100644 --- a/.agents/skills/semark-protocol/rules/source-scope.md +++ b/.agents/skills/semark-protocol/rules/source-scope.md @@ -1,7 +1,16 @@ # Source scope -Apply Semark to hand-authored `.ts`, `.tsx`, `.mts`, and `.cts` files. Include source -files, tests, build scripts, and TypeScript configuration files in this scope. +Apply Semark to hand-authored `.ts`, `.tsx`, `.mts`, and `.cts` files in the +configured source roots. + +Default source roots: + +- repository root, non-recursive: only top-level TypeScript files +- `apps/**`, recursive +- `packages/**`, recursive + +Files in other directories, such as `scripts/`, are out of scope unless the +repository configuration extends the roots. Exclude these files by default: diff --git a/.agents/skills/semark-protocol/rules/validation.md b/.agents/skills/semark-protocol/rules/validation.md index b2f0187..a044313 100644 --- a/.agents/skills/semark-protocol/rules/validation.md +++ b/.agents/skills/semark-protocol/rules/validation.md @@ -19,12 +19,17 @@ the descriptions. Check unauthorized comments and invalid directives in every Semark installation. Apply this check to the configured source scope. -If the repository uses Oxlint, load `@paperkeel/oxlint-plugin-semark` through -`jsPlugins`. Enable `semark/valid` as an error. +Repositories may validate Semark with a local script or with Oxlint. -Use repository validation for requirements outside the Oxlint rule boundary. These -requirements include README coverage, semantic accuracy, naming, exclusions, migration -scope, and changed-code signature updates. +This repository uses `scripts/check-semark.mjs` through `pnpm semark:check`. + +In other repositories that use Oxlint, you may optionally load +`@paperkeel/oxlint-plugin-semark` through `jsPlugins` and enable `semark/valid` as an +error. The Oxlint plugin is not required here. + +Use repository validation for requirements outside the local-script or Oxlint rule +boundary. These requirements include README coverage, semantic accuracy, naming, +exclusions, migration scope, and changed-code signature updates. Run the configured Semark check before you complete a change. Correct violations that your change causes. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d02f4a5..4b0dc0a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -28,9 +28,6 @@ jobs: - name: Install dependencies run: pnpm install --frozen-lockfile - - name: Validate Semark Protocol - run: pnpm semark:check - - name: Check source run: pnpm check diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8ea0609..6c54381 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -50,7 +50,6 @@ jobs: run: | test "$DEPLOY_SHA" = "$GITHUB_SHA" || { echo "The release event does not match the target commit." >&2; exit 1; } test "$DEPLOY_SHA" = "$(git rev-parse HEAD)" || { echo "The checkout does not match the release commit." >&2; exit 1; } - pnpm semark:check pnpm check pnpm build pnpm exec wrangler deploy --dry-run --config apps/api/wrangler.jsonc diff --git a/AGENTS.md b/AGENTS.md index 6c5f633..3344a02 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,4 +47,7 @@ or keep source comments except Semark file signatures, method signatures, and approved directives. Update an affected signature in the same change as the documented behavior. All applicable TypeScript files in the root, `apps/*`, and `packages/*` comply. Declaration-only `.d.ts` files use the protocol default -exclusion. Run `pnpm semark:check` before you complete a change. +exclusion. Validate Semark with `scripts/check-semark.mjs` through +`pnpm semark:check`. This repository does not use the +`@paperkeel/oxlint-plugin-semark` Oxlint plugin. Run `pnpm check` before each +commit; it includes Semark validation. diff --git a/package.json b/package.json index 5ac37dd..23b531b 100644 --- a/package.json +++ b/package.json @@ -20,7 +20,7 @@ "scripts": { "bootstrap:check": "node scripts/check-bootstrap-boundary.mjs", "build": "pnpm -r --if-present build", - "check": "pnpm bootstrap:check && pnpm format:check && pnpm lint && pnpm typecheck && pnpm test", + "check": "pnpm semark:check && pnpm bootstrap:check && pnpm format:check && pnpm lint && pnpm typecheck && pnpm test", "dev": "alchemy dev --stage dev", "deploy": "alchemy deploy --stage prod --yes", "format": "oxfmt .",