@davidvornholt/standards 0.22.2 → 0.23.0

package/package.json

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

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;