@davidvornholt/standards 0.7.0 → 0.8.0

package/README.md

@@ -16,6 +16,8 @@ standards github --apply
 
 `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.
 
+`structure --profile source` validates the standards source repository itself, which is deliberately not a consumer. The profile pins its intentional exceptions so they cannot drift silently: exact, ordered root gate scripts that run this CLI from the local checkout (`structure --profile source`, `github --check`, and the Turbo gate) instead of a recursive `standards check`, and a non-private published bin-only CLI workspace that carries a stable release SemVer and exactly maps the `standards` bin to `src/cli.ts` without `exports`. Every other consumer rule still applies.
+
 ## Configuration
 
 - **`sync-standards.local.json`** (optional) — consumer-owned sync policy at the repo root, validated by `doctor`/`check` and every `init`/`sync` even when an explicit ref or local source makes its `"ref"` irrelevant. All fields optional; a missing file means the defaults. `"ref"` is a non-empty single-line string that pins a tag, branch, or full commit sha to sync from instead of `main` (an explicit `--ref` overrides it; a local-path `--from` source is used as-is and ignores only the validated pin). `"autoSync": false` is read by the standards-sync workflow, not the CLI, and skips the weekly scheduled run. Version 0.7.0 removes the legacy `STANDARDS_AUTO_SYNC` and `STANDARDS_SYNC_REF` variable behavior; consumers must upgrade the package and lockfile before adopting a policy file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -26,6 +26,8 @@
     "src/github-diff.ts",
     "src/github-settings.ts",
     "src/structure-check.ts",
+    "src/structure-profile.ts",
+    "src/structure-script.ts",
     "src/structure-workspace.ts"
   ],
   "scripts": {

package/src/cli.ts

@@ -36,7 +36,8 @@ import { CANONICAL_SETTINGS_FILE, LOCAL_SETTINGS_FILE } from './github-api';
 import { runGithubApply, runGithubCheck } from './github-commands';
 import { loadGithubSettings } from './github-settings';
 import { collectStructureProblems } from './structure-check';
-import { hasSafeCommand } from './structure-workspace';
+import type { StructureProfile } from './structure-profile';
+import { hasSafeCommand } from './structure-script';
 
 const { YAML: BunYaml } = await import('bun');
 
@@ -92,6 +93,7 @@ type CliOptions = {
   readonly from: string | undefined;
   readonly ref: string | undefined;
   readonly apply: boolean;
+  readonly profile: StructureProfile;
 };
 
 const sha256 = (buf: Buffer): string =>
@@ -781,6 +783,7 @@ Commands:
 
 Options:
   --dir <path>   Consumer directory to operate on (default: current directory)
+  --profile <p>  With structure: validate as a "consumer" (default) or as the standards "source" repository itself
   --from <src>   Upstream override for init/sync (GitHub repo or local path)
   --ref <ref>    Upstream tag, branch, or full commit sha for init/sync (remote Git/GitHub sources only; default: main)
   --dry-run      Preview a sync without writing anything
@@ -811,6 +814,13 @@ const setCommand = (current: Command | undefined, next: Command): Command => {
   return next;
 };
 
+const structureProfileOf = (value: string): StructureProfile => {
+  if (value === 'consumer' || value === 'source') {
+    return value;
+  }
+  throw new Error(`--profile must be "consumer" or "source": ${value}`);
+};
+
 const nextOptionValue = (
   argv: ReadonlyArray<string>,
   index: number,
@@ -830,6 +840,7 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
   let ref: string | undefined;
   let checkFlag = false;
   let apply = false;
+  let profile: StructureProfile | undefined;
 
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
@@ -851,6 +862,10 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
         from = nextOptionValue(argv, index);
         index += 1;
         break;
+      case '--profile':
+        profile = structureProfileOf(nextOptionValue(argv, index));
+        index += 1;
+        break;
       case '--ref':
         ref = nextOptionValue(argv, index);
         index += 1;
@@ -876,6 +891,9 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
   if (ref !== undefined && command !== 'init' && command !== 'sync') {
     throw new Error('--ref is only valid with the init and sync commands');
   }
+  if (profile !== undefined && command !== 'structure') {
+    throw new Error('--profile is only valid with the structure command');
+  }
 
   return {
     command,
@@ -884,13 +902,19 @@ const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
     from,
     ref,
     apply,
+    profile: profile ?? 'consumer',
   };
 };
 
 // Canonical monorepo structure gate: workspace and root script shapes,
 // internal versioning, `exports`, tsconfig inheritance, and a11y wiring.
-const runStructure = async (consumer: string): Promise<boolean> => {
-  const problems = await collectStructureProblems(consumer);
+// The `source` profile instead pins the standards template repository's own
+// deliberate exceptions to the consumer contract.
+const runStructure = async (
+  consumer: string,
+  profile: StructureProfile,
+): Promise<boolean> => {
+  const problems = await collectStructureProblems(consumer, profile);
   if (problems.length > 0) {
     console.error(
       `standards structure: ${problems.length} monorepo structure problem(s):`,
@@ -905,7 +929,7 @@ const runStructure = async (consumer: string): Promise<boolean> => {
 const runCheckCommand = async (consumer: string): Promise<boolean> => {
   const driftIsClean = await runCheck(consumer);
   const integrationIsValid = await runDoctor(consumer);
-  const structureIsValid = await runStructure(consumer);
+  const structureIsValid = await runStructure(consumer, 'consumer');
   // The GitHub gate activates with the synced declaration and then fails
   // closed: once .github/settings.json exists, an unreachable API or an
   // unreadable origin is a failure, not a skip.
@@ -1048,6 +1072,7 @@ const runGateCommand = (
   command: 'check' | 'doctor' | 'github' | 'structure',
   consumer: string,
   apply: boolean,
+  profile: StructureProfile,
 ): Promise<boolean> => {
   if (command === 'check') {
     return runCheckCommand(consumer);
@@ -1056,13 +1081,13 @@ const runGateCommand = (
     return runDoctor(consumer);
   }
   if (command === 'structure') {
-    return runStructure(consumer);
+    return runStructure(consumer, profile);
   }
   return apply ? runGithubApply(consumer) : runGithubCheck(consumer);
 };
 
 const main = async (): Promise<void> => {
-  const { command, consumer, dryRun, from, ref, apply } = parseArgs(
+  const { command, consumer, dryRun, from, ref, apply, profile } = parseArgs(
     process.argv.slice(2),
   );
 
@@ -1088,7 +1113,7 @@ const main = async (): Promise<void> => {
     return;
   }
 
-  if (!(await runGateCommand(command, consumer, apply))) {
+  if (!(await runGateCommand(command, consumer, apply, profile))) {
     process.exitCode = 1;
   }
 };

package/src/structure-check.ts

@@ -3,22 +3,16 @@ import { readdir, readFile } from 'node:fs/promises';
 import { isAbsolute, join } from 'node:path';
 import { isRecord } from './github-settings';
 import {
-  hasSafeCommand,
-  inspectWorkspace,
-  isSafeFilteredTurboAlias,
-  type Workspace,
-} from './structure-workspace';
+  missingPublishedCliProblems,
+  rootScriptExpectations,
+  type StructureProfile,
+} from './structure-profile';
+import { hasSafeCommands, isSafeFilteredTurboAlias } from './structure-script';
+import { inspectWorkspace, type Workspace } from './structure-workspace';
 
-const ROOT_CHECK = 'turbo run lint check-types test build test:a11y';
-const ROOT_CHECK_FIX = 'turbo run lint:fix check-types test build test:a11y';
-const ROOT_A11Y = 'turbo run test:a11y';
-
-const ROOT_FIXED_SCRIPTS = new Set([
-  'standards',
-  'check',
-  'check:fix',
-  'test:a11y',
-]);
+const ROOT_FIXED_SCRIPTS = new Set(
+  'standards,check,check:fix,test:a11y'.split(','),
+);
 const GLOB_SUFFIX = '/*';
 const WORKSPACES_REQUIREMENT =
   'package.json: "workspaces" must be a non-empty array of literal paths or one-level "<dir>/*" patterns';
@@ -136,19 +130,20 @@ const loadWorkspace = async (
 };
 const inspectRootScripts = (
   root: Record<string, unknown>,
+  profile: StructureProfile,
   requireA11y: boolean,
 ): ReadonlyArray<string> => {
   const scripts = isRecord(root.scripts) ? root.scripts : {};
-  const expectations: ReadonlyArray<readonly [string, string]> = [
-    ['check', ROOT_CHECK],
-    ['check:fix', ROOT_CHECK_FIX],
-    ...(requireA11y ? [['test:a11y', ROOT_A11Y] as const] : []),
-  ];
-  const gateProblems = expectations.flatMap(([name, fragment]) => {
+  const expectations = rootScriptExpectations(profile, requireA11y);
+  const gateProblems = expectations.flatMap(({ name, commands, exact }) => {
     const { [name]: script } = scripts;
-    return typeof script === 'string' && hasSafeCommand(script, fragment)
+    const requirement = commands.join(' && ');
+    return typeof script === 'string' &&
+      hasSafeCommands(script, commands, exact)
       ? []
-      : [`package.json: root script "${name}" must run ${fragment}`];
+      : [
+          `package.json: root script "${name}" must run ${exact ? 'exactly ' : ''}${requirement}`,
+        ];
   });
   const aliasProblems = Object.entries(scripts).flatMap(([name, script]) =>
     ROOT_FIXED_SCRIPTS.has(name) ||
@@ -163,6 +158,7 @@ const inspectRootScripts = (
 };
 export const collectStructureProblems = async (
   consumer: string,
+  profile: StructureProfile,
 ): Promise<ReadonlyArray<string>> => {
   const root = await readJson(join(consumer, 'package.json'));
   if (root === null) {
@@ -185,14 +181,15 @@ export const collectStructureProblems = async (
       .filter((name): name is string => typeof name === 'string'),
   );
   const inspections = await Promise.all(
-    workspaces.map((ws) => inspectWorkspace(ws, workspaceNames)),
+    workspaces.map((ws) => inspectWorkspace(ws, workspaceNames, profile)),
   );
   const requireA11y = inspections.some((i) => i.hasA11ySuite);
   return [
     ...declaration.problems,
     ...resolved.flatMap((r) => (r.problem === null ? [] : [r.problem])),
     ...loaded.flatMap((l) => (l.problem === null ? [] : [l.problem])),
-    ...inspectRootScripts(root, requireA11y),
+    ...missingPublishedCliProblems(profile, workspaces),
+    ...inspectRootScripts(root, profile, requireA11y),
     ...inspections.flatMap((i) => [...i.problems]),
   ];
 };

package/src/structure-profile.ts

@@ -0,0 +1,129 @@
+import { isRecord } from './github-settings';
+
+// Structure validation profiles. `consumer` is the contract every downstream
+// repo satisfies. `source` is the standards template repository itself, which
+// is deliberately not a consumer: its root gate runs the local CLI instead of
+// a recursive `standards check`, and it publishes the CLI workspace as a
+// released bin-only package. Pinning those exceptions here keeps them from
+// drifting silently while the normal quality gate stays green.
+export type StructureProfile = 'consumer' | 'source';
+
+const CONSUMER_CHECK = 'turbo run lint check-types test build test:a11y';
+const CONSUMER_CHECK_FIX =
+  'turbo run lint:fix check-types test build test:a11y';
+const ROOT_A11Y = 'turbo run test:a11y';
+
+export const PUBLISHED_CLI_WORKSPACE = 'packages/standards-cli';
+const PUBLISHED_CLI_PACKAGE = '@davidvornholt/standards';
+const SOURCE_CLI = `bun ${PUBLISHED_CLI_WORKSPACE}/src/cli.ts`;
+const RELEASE_SEMVER = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/u;
+
+export type RootScriptExpectation = {
+  readonly name: string;
+  readonly commands: ReadonlyArray<string>;
+  readonly exact: boolean;
+};
+
+const SOURCE_ROOT_EXPECTATIONS: ReadonlyArray<RootScriptExpectation> = [
+  { name: 'standards', commands: [SOURCE_CLI], exact: true },
+  {
+    name: 'check',
+    commands: [
+      `${SOURCE_CLI} structure --profile source`,
+      `${SOURCE_CLI} github --check`,
+      'turbo run lint check-types test',
+    ],
+    exact: true,
+  },
+  {
+    name: 'check:fix',
+    commands: [
+      `${SOURCE_CLI} structure --profile source`,
+      `${SOURCE_CLI} github --check`,
+      'turbo run lint:fix check-types test',
+    ],
+    exact: true,
+  },
+];
+
+export const rootScriptExpectations = (
+  profile: StructureProfile,
+  requireA11y: boolean,
+): ReadonlyArray<RootScriptExpectation> => [
+  ...(profile === 'source'
+    ? SOURCE_ROOT_EXPECTATIONS
+    : [
+        { name: 'check', commands: [CONSUMER_CHECK], exact: false },
+        { name: 'check:fix', commands: [CONSUMER_CHECK_FIX], exact: false },
+      ]),
+  ...(requireA11y
+    ? [{ name: 'test:a11y', commands: [ROOT_A11Y], exact: false }]
+    : []),
+];
+
+// The published CLI ships as a released bin-only package: it carries a release
+// SemVer instead of the internal "0.0.0" and exposes its public API through
+// "bin" instead of "exports". Everything else follows the normal rules.
+const inspectPublishedCli = (
+  manifest: Record<string, unknown>,
+): ReadonlyArray<string> => [
+  ...(manifest.name === PUBLISHED_CLI_PACKAGE
+    ? []
+    : [
+        `${PUBLISHED_CLI_WORKSPACE}: published CLI package name must be "${PUBLISHED_CLI_PACKAGE}"`,
+      ]),
+  ...(typeof manifest.version === 'string' &&
+  manifest.version !== '0.0.0' &&
+  RELEASE_SEMVER.test(manifest.version)
+    ? []
+    : [
+        `${PUBLISHED_CLI_WORKSPACE}: published CLI version must be a stable release SemVer, not "0.0.0"`,
+      ]),
+  ...(isRecord(manifest.bin) &&
+  Object.keys(manifest.bin).length === 1 &&
+  manifest.bin.standards === 'src/cli.ts'
+    ? []
+    : [
+        `${PUBLISHED_CLI_WORKSPACE}: published CLI bin must be exactly { "standards": "src/cli.ts" }`,
+      ]),
+  ...(manifest.private === true
+    ? [`${PUBLISHED_CLI_WORKSPACE}: published CLI must not be private`]
+    : []),
+  ...(manifest.exports === undefined
+    ? []
+    : [
+        `${PUBLISHED_CLI_WORKSPACE}: published CLI must be bin-only and must not define "exports"`,
+      ]),
+];
+
+export const inspectVersionAndExports = (
+  profile: StructureProfile,
+  rel: string,
+  manifest: Record<string, unknown>,
+): ReadonlyArray<string> => {
+  if (profile === 'source' && rel === PUBLISHED_CLI_WORKSPACE) {
+    return inspectPublishedCli(manifest);
+  }
+  return [
+    ...(manifest.version === '0.0.0'
+      ? []
+      : [`${rel}: internal workspace version must be "0.0.0"`]),
+    ...(rel.startsWith('packages/') && manifest.exports === undefined
+      ? [`${rel}: package must define its public API with "exports"`]
+      : []),
+  ];
+};
+
+// The source profile only means anything in the repository that owns and
+// publishes the CLI; failing loudly when that workspace is absent keeps the
+// profile from being applied to the wrong repository shape.
+export const missingPublishedCliProblems = (
+  profile: StructureProfile,
+  workspaces: ReadonlyArray<{ readonly rel: string }>,
+): ReadonlyArray<string> =>
+  profile === 'source' &&
+  !workspaces.some((ws) => ws.rel === PUBLISHED_CLI_WORKSPACE)
+    ? [
+        `${PUBLISHED_CLI_WORKSPACE}: the source profile requires the published CLI workspace`,
+      ]
+    : [];

package/src/structure-script.ts

@@ -0,0 +1,63 @@
+const UNSAFE_SCRIPT_SYNTAX = /[|;#"'`\r\n]/u;
+const SCRIPT_WHITESPACE = /\s+/u;
+const NON_EXECUTING_TURBO_OPTION = /^(?:-h|-v|--(?:dry|help|version))(?:=|$)/u;
+
+export const parseSafeCommands = (
+  script: string | null,
+): ReadonlyArray<ReadonlyArray<string>> | null => {
+  if (
+    script === null ||
+    script.trim() === '' ||
+    UNSAFE_SCRIPT_SYNTAX.test(script) ||
+    script.includes('$(')
+  ) {
+    return null;
+  }
+  const commands = script.split('&&').map((command) => command.trim());
+  return commands.some((command) => command === '' || command.includes('&'))
+    ? null
+    : commands.map((command) => command.split(SCRIPT_WHITESPACE));
+};
+
+export const hasSafeCommands = (
+  script: string | null,
+  expected: ReadonlyArray<string>,
+  exact: boolean,
+): boolean => {
+  const commands = parseSafeCommands(script)?.map((tokens) => tokens.join(' '));
+  if (commands === undefined) {
+    return false;
+  }
+  return exact
+    ? commands.length === expected.length &&
+        commands.every((command, index) => command === expected[index])
+    : expected.every((command) => commands.includes(command));
+};
+
+export const hasSafeCommand = (
+  script: string | null,
+  expected: string,
+): boolean => hasSafeCommands(script, [expected], false);
+
+export const isSafeFilteredTurboAlias = (script: string): boolean => {
+  const commands = parseSafeCommands(script);
+  if (commands?.length !== 1) {
+    return false;
+  }
+  const [tokens] = commands;
+  const filterAt = tokens.findIndex(
+    (token) => token === '--filter' || token.startsWith('--filter='),
+  );
+  const filter = tokens[filterAt];
+  const filterValue =
+    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('-');
+};

package/src/structure-workspace.ts

@@ -1,6 +1,11 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isRecord } from './github-settings';
+import {
+  inspectVersionAndExports,
+  type StructureProfile,
+} from './structure-profile';
+import { hasSafeCommand, parseSafeCommands } from './structure-script';
 export type Workspace = {
   readonly rel: string;
   readonly dir: string;
@@ -20,11 +25,8 @@ const DEPENDENCY_FIELDS =
 const SHARED_TSCONFIG_PACKAGE = '@davidvornholt/typescript-config';
 const SHARED_TSCONFIG_PATH =
   /^@davidvornholt\/typescript-config\/(?:base|next|react-library)$/u;
-const UNSAFE_SCRIPT_SYNTAX = /[|;#"'`\r\n]/u;
-const SCRIPT_WHITESPACE = /\s+/u;
 const NON_EXECUTING_A11Y_OPTION =
   /^(?:-h|-V|--(?:debug|help|last-failed|list|only-changed|ui|version))(?:=|$)/u;
-const NON_EXECUTING_TURBO_OPTION = /^(?:-h|-v|--(?:dry|help|version))(?:=|$)/u;
 const IGNORED_DIRS = new Set('.git,.next,.turbo,dist,node_modules'.split(','));
 const scriptOf = (
   manifest: Record<string, unknown>,
@@ -34,57 +36,13 @@ const scriptOf = (
   const script = scripts[name];
   return typeof script === 'string' ? script : null;
 };
-const safeCommands = (
-  script: string | null,
-): ReadonlyArray<ReadonlyArray<string>> | null => {
-  if (
-    script === null ||
-    script.trim() === '' ||
-    UNSAFE_SCRIPT_SYNTAX.test(script) ||
-    script.includes('$(')
-  ) {
-    return null;
-  }
-  const commands = script.split('&&').map((command) => command.trim());
-  return commands.some((command) => command === '' || command.includes('&'))
-    ? null
-    : commands.map((command) => command.split(SCRIPT_WHITESPACE));
-};
-export const hasSafeCommand = (
-  script: string | null,
-  expected: string,
-): boolean =>
-  safeCommands(script)?.some((tokens) => tokens.join(' ') === expected) ??
-  false;
 const hasSafeA11yCommand = (script: string | null): boolean =>
-  safeCommands(script)?.some(
+  parseSafeCommands(script)?.some(
     (tokens) =>
       tokens[0] === 'playwright' &&
       tokens[1] === 'test' &&
       tokens.slice(2).every((token) => !NON_EXECUTING_A11Y_OPTION.test(token)),
   ) ?? false;
-export const isSafeFilteredTurboAlias = (script: string): boolean => {
-  const commands = safeCommands(script);
-  if (commands?.length !== 1) {
-    return false;
-  }
-  const [tokens] = commands;
-  const filterAt = tokens.findIndex(
-    (token) => token === '--filter' || token.startsWith('--filter='),
-  );
-  const filter = tokens[filterAt];
-  const filterValue =
-    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('-');
-};
 const containsA11ySuite = async (dir: string): Promise<boolean> => {
   const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
   if (
@@ -179,6 +137,7 @@ const inspectA11y = async (
 export const inspectWorkspace = async (
   ws: Workspace,
   workspaceNames: ReadonlySet<string>,
+  profile: StructureProfile,
 ) => {
   const [tsconfigProblems, a11y] = await Promise.all([
     inspectTsconfig(ws),
@@ -186,13 +145,8 @@ export const inspectWorkspace = async (
   ]);
   const problems = [
     ...inspectScripts(ws),
-    ...(ws.manifest.version === '0.0.0'
-      ? []
-      : [`${ws.rel}: internal workspace version must be "0.0.0"`]),
+    ...inspectVersionAndExports(profile, ws.rel, ws.manifest),
     ...inspectInternalDeps(ws, workspaceNames),
-    ...(ws.rel.startsWith('packages/') && ws.manifest.exports === undefined
-      ? [`${ws.rel}: package must define its public API with "exports"`]
-      : []),
     ...tsconfigProblems,
     ...a11y.problems,
   ];