@davidvornholt/standards 0.22.1 → 0.23.0

package/README.md

@@ -33,7 +33,7 @@ standards poller --print-units --config <path>
 
 `check` also rejects the raw token formed by `biome-` + `ignore` anywhere in lock-listed canonical files. The intentionally blunt policy keeps synced sources compatible with consumer Biome configurations without invoking Biome or maintaining language-aware comment parsing.
 
-`github --check` compares the live GitHub repository (including the canonical squash-only repository settings, rulesets, and declared labels) against the merged declaration in `.github/settings.json` + `.github/settings.local.json`; `github --apply` converges that declared state. The canonical declaration enables squash while disabling merge commits and rebases, and its default-branch ruleset independently allows only squash. Undeclared live labels remain untouched, while undeclared repository-owned rulesets are removed. `check` runs the same comparison whenever `.github/settings.json` is present, and fails closed: declared state the token cannot see fails the gate with a message naming the token fix instead of passing unverified. The canonical workflow sets `STANDARDS_SKIP_GITHUB_CHECK=true` only in its unprivileged quality step because its isolated `github-settings` job runs the live comparison with its own workflow token; this is a workflow-internal integration seam, not a general way to disable the local gate. The CLI prints an explicit diagnostic whenever that exact value skips either `check`'s live phase or `github --check`; `github --apply` is never skipped. `--apply` re-diffs the PATCH response, so a setting GitHub accepts with HTTP 200 but silently ignores (plan-unavailable features) is a reported failure, not a false success. A repository whose GitHub plan cannot enforce rulesets can declare that in the seam (see `rulesetEnforcement` below); both commands then skip rulesets and plan-gated repository settings, converge the rest, and print an unprotected-branch notice on every run.
+`github --check` compares the live GitHub repository (including the canonical squash-only repository settings, rulesets, and declared labels) against the merged declaration in `.github/settings.json` + `.github/settings.local.json`; `github --apply` converges that declared state. The canonical declaration enables squash while disabling merge commits and rebases, and its default-branch ruleset independently allows only squash. Undeclared live labels remain untouched, while undeclared repository-owned rulesets are removed. `check` runs the same comparison whenever `.github/settings.json` is present, and fails closed: declared state the token cannot see fails the gate with a message naming the token fix instead of passing unverified. The canonical workflow sets `STANDARDS_SKIP_GITHUB_CHECK=true` only in its unprivileged quality step because its `check` aggregator job runs the live comparison with its own workflow token; this is a workflow-internal integration seam, not a general way to disable the local gate. The CLI prints an explicit diagnostic whenever that exact value skips either `check`'s live phase or `github --check`; `github --apply` is never skipped. `--apply` re-diffs the PATCH response, so a setting GitHub accepts with HTTP 200 but silently ignores (plan-unavailable features) is a reported failure, not a false success. A repository whose GitHub plan cannot enforce rulesets can declare that in the seam (see `rulesetEnforcement` below); both commands then skip rulesets and plan-gated repository settings, converge the rest, and print an unprotected-branch notice on every run.
 
 `structure` enforces the canonical monorepo structure contract: workspace scripts (`check-types`, `lint`, `lint:fix`, `test`), root gate scripts, filtered Turbo convenience aliases, internal `0.0.0`/`workspace:*` versioning, package `exports`, shared tsconfig inheritance, and browser a11y wiring. Only a workspace containing an explicit `*.a11y.ts` suite must provide a `test:a11y` script and direct `@axe-core/playwright` and `@playwright/test` dependencies. `check` includes `structure`, so these rules gate every consumer PR.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.22.1",
+  "version": "0.23.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {

package/src/cli.ts

@@ -1216,13 +1216,13 @@ const runCheckCommand = async (consumer: string): Promise<boolean> => {
 };
 
 // The canonical workflow sets this only for its unprivileged quality job,
-// where a separate isolated job runs the same live check with its own workflow
+// where the check aggregator job runs the same live check with its own workflow
 // token. Absent that exact workflow seam, local and explicit checks remain
 // fail-closed.
 const runGithubCheckGate = (consumer: string): Promise<boolean> => {
   if (process.env[SKIP_GITHUB_CHECK_ENV] === 'true') {
     console.log(
-      `standards github: live settings check skipped because ${SKIP_GITHUB_CHECK_ENV}=true; the canonical workflow's isolated github-settings job must own this check`,
+      `standards github: live settings check skipped because ${SKIP_GITHUB_CHECK_ENV}=true; the canonical workflow's check aggregator job must own this check`,
     );
     return Promise.resolve(true);
   }

package/src/github-live-drift.ts

@@ -35,7 +35,7 @@ import {
 import { type GithubSettings, isRecord } from './github-settings-parse';
 
 const LABEL_VISIBILITY_PROBLEM =
-  'declared labels not visible to this token, so the gate cannot verify them. Label reads need issues: read (or pull-requests: read); the canonical github-settings job already grants issues: read, so in CI this points at a stale synced workflow or an organization policy restricting the workflow token rather than anything to change in the declaration. Locally, use a token with one of those permissions';
+  'declared labels not visible to this token, so the gate cannot verify them. Label reads need issues: read (or pull-requests: read); the canonical check aggregator job already grants issues: read, so in CI this points at a stale synced workflow or an organization policy restricting the workflow token rather than anything to change in the declaration. Locally, use a token with one of those permissions';
 const PERMISSION_DENIAL_MESSAGES: ReadonlySet<string> = new Set([
   'Resource not accessible by integration',
   'Resource not accessible by personal access token',

package/src/poller-outcome.ts

@@ -54,9 +54,11 @@ const REVIEW_STATUSES: ReadonlySet<string> = new Set([
   'cannot-review',
 ]);
 
-// Conventional Commit subject: consumers lint PR titles in CI, so a
-// malformed title is caught here instead of as a red check later.
-const PR_TITLE_PATTERN = /^[a-z]+(?:\([^)]+\))?!?: .+/u;
+// Conventional Commit subject: squash merges promote the PR title to the
+// commit subject on main, and no CI gate lints it, so this validation is
+// the enforcement point for poller-authored PRs.
+const PR_TITLE_PATTERN =
+  /^(?:build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(?:\([a-z0-9./-]+\))?!?: [^ \n\r\u2028\u2029]/u;
 
 export const readFixOutcome = async (
   workDir: string,

package/src/structure-check.ts

@@ -7,7 +7,7 @@ import {
   rootScriptExpectations,
   type StructureProfile,
 } from './structure-profile';
-import { hasSafeCommands, isSafeFilteredTurboAlias } from './structure-script';
+import { filteredTurboAliasProblem, hasSafeCommands } from './structure-script';
 import { inspectWorkspace, type Workspace } from './structure-workspace';
 
 const ROOT_FIXED_SCRIPTS = new Set(
@@ -145,15 +145,13 @@ const inspectRootScripts = (
           `package.json: root script "${name}" must run ${exact ? 'exactly ' : ''}${requirement}`,
         ];
   });
-  const aliasProblems = Object.entries(scripts).flatMap(([name, script]) =>
-    ROOT_FIXED_SCRIPTS.has(name) ||
-    typeof script !== 'string' ||
-    isSafeFilteredTurboAlias(script)
-      ? []
-      : [
-          `package.json: root script "${name}" must delegate through Turbo with an explicit --filter`,
-        ],
-  );
+  const aliasProblems = Object.entries(scripts).flatMap(([name, script]) => {
+    if (ROOT_FIXED_SCRIPTS.has(name) || typeof script !== 'string') {
+      return [];
+    }
+    const problem = filteredTurboAliasProblem(name, script);
+    return problem === null ? [] : [problem];
+  });
   return [...gateProblems, ...aliasProblems];
 };
 export const collectStructureProblems = async (

package/src/structure-script.ts

@@ -2,6 +2,18 @@ const UNSAFE_SCRIPT_SYNTAX = /[|;#"'`\r\n]/u;
 const SCRIPT_WHITESPACE = /\s+/u;
 const NON_EXECUTING_TURBO_OPTION = /^(?:-h|-v|--(?:dry|help|version))(?:=|$)/u;
 
+type FilteredTurboAliasViolation =
+  | 'empty'
+  | 'filter-empty'
+  | 'filter-missing'
+  | 'filter-option'
+  | 'multiple-commands'
+  | 'non-executing-option'
+  | 'not-run'
+  | 'not-turbo'
+  | 'syntax'
+  | 'task';
+
 export const parseSafeCommands = (
   script: string | null,
 ): ReadonlyArray<ReadonlyArray<string>> | null => {
@@ -39,12 +51,32 @@ export const hasSafeCommand = (
   expected: string,
 ): boolean => hasSafeCommands(script, [expected], false);
 
-export const isSafeFilteredTurboAlias = (script: string): boolean => {
+const filteredTurboAliasViolation = (
+  script: string,
+): FilteredTurboAliasViolation | null => {
+  if (script.trim() === '') {
+    return 'empty';
+  }
   const commands = parseSafeCommands(script);
-  if (commands?.length !== 1) {
-    return false;
+  if (commands === null) {
+    return 'syntax';
+  }
+  if (commands.length !== 1) {
+    return 'multiple-commands';
   }
   const [tokens] = commands;
+  if (tokens[0] !== 'turbo') {
+    return 'not-turbo';
+  }
+  if (tokens[1] !== 'run') {
+    return 'not-run';
+  }
+  if (tokens.some((token) => NON_EXECUTING_TURBO_OPTION.test(token))) {
+    return 'non-executing-option';
+  }
+  if (tokens[2]?.startsWith('-') !== false) {
+    return 'task';
+  }
   const filterAt = tokens.findIndex(
     (token) => token === '--filter' || token.startsWith('--filter='),
   );
@@ -53,11 +85,40 @@ export const isSafeFilteredTurboAlias = (script: string): boolean => {
     filter === '--filter'
       ? tokens[filterAt + 1]
       : filter?.slice('--filter='.length);
-  return tokens[0] !== 'turbo' || tokens[1] !== 'run'
-    ? false
-    : tokens[2]?.startsWith('-') === false &&
-        !tokens.some((token) => NON_EXECUTING_TURBO_OPTION.test(token)) &&
-        filterValue !== undefined &&
-        filterValue !== '' &&
-        !filterValue.startsWith('-');
+  if (filter === undefined) {
+    return 'filter-missing';
+  }
+  if (filterValue === undefined || filterValue === '') {
+    return 'filter-empty';
+  }
+  return filterValue.startsWith('-') ? 'filter-option' : null;
 };
+
+export const filteredTurboAliasProblem = (
+  name: string,
+  script: string,
+): string | null => {
+  const violation = filteredTurboAliasViolation(script);
+  if (violation === null) {
+    return null;
+  }
+  const details: Record<FilteredTurboAliasViolation, string> = {
+    empty: 'must be a non-empty single filtered Turbo command',
+    'filter-empty': 'must pass a non-empty value to --filter',
+    'filter-missing': 'must pass an explicit --filter',
+    'filter-option': 'must pass a --filter value that is not another option',
+    'multiple-commands':
+      'must contain exactly one command; && command chains are not supported',
+    'non-executing-option':
+      'must execute a task; Turbo help, version, and dry-run options are not allowed',
+    'not-run': 'must invoke Turbo through "turbo run"',
+    'not-turbo': 'must invoke Turbo directly with "turbo"',
+    syntax:
+      'contains shell syntax the structure gate does not parse (quotes, |, ;, #, backticks, $(, CR/LF line breaks, or malformed ampersand separators); write one command with plain arguments, using --filter=./apps/* for a glob',
+    task: 'must put a task name immediately after "turbo run"',
+  };
+  return `package.json: root script "${name}" ${details[violation]}`;
+};
+
+export const isSafeFilteredTurboAlias = (script: string): boolean =>
+  filteredTurboAliasViolation(script) === null;