diff --git a/.github/review-routing/design-system-maintenance.md b/.github/review-routing/design-system-maintenance.md index e2a58a0d5d5a59..5730d0b2253147 100644 --- a/.github/review-routing/design-system-maintenance.md +++ b/.github/review-routing/design-system-maintenance.md @@ -2,4 +2,4 @@ reviewer: [aduth, ciampo] --- -Does this change how a component, a design token or a Sass mixin of the design system packages `@wordpress/components`, `@wordpress/ui`, `@wordpress/theme`, `@wordpress/base-styles` or `@wordpress/icons` looks or behaves for the people who use it, for example its styles, its interactions or its accessibility? Only changes to these packages count, not changes to application code that uses them. Answer no when what people see and do stays the same, such as for a refactor, or for a change to dependencies, tooling, tests, types or build configuration that keeps the same runtime behavior. +Does this change how a component, a design token or a Sass mixin of the design system packages `@wordpress/components`, `@wordpress/ui`, `@wordpress/theme`, `@wordpress/base-styles` or `@wordpress/icons` looks or behaves for the people who use it, for example its styles, its interactions or its accessibility? Only changes to these packages count, not changes to application code that uses them. Answer no when what people see and do stays the same, such as for a refactor, or for a change to tooling, tests, types or build configuration. A dependency update counts when it changes how these components look or behave. diff --git a/.github/review-routing/design-system-patterns.md b/.github/review-routing/design-system-patterns.md index 54ac93b5d84390..ad74cd75f4ef8f 100644 --- a/.github/review-routing/design-system-patterns.md +++ b/.github/review-routing/design-system-patterns.md @@ -1,6 +1,5 @@ --- reviewer: [aduth, ciampo] -threshold: 0.8 --- -Does this change implement a documented design system pattern: destructive actions, error messages, save and submit, or copy to clipboard? +Does this change build an interface that one of the design system patterns in `patterns` applies to? A pattern describes how to compose the interface components of `@wordpress/ui` and `@wordpress/components` for a common task. diff --git a/.github/review-routing/design-system-patterns.mts b/.github/review-routing/design-system-patterns.mts new file mode 100644 index 00000000000000..7a6880f2ac6cbc --- /dev/null +++ b/.github/review-routing/design-system-patterns.mts @@ -0,0 +1,37 @@ +import { readdir, readFile } from 'node:fs/promises'; + +const PATTERNS_DIRECTORY = new URL( + '../../storybook/stories/design-system/patterns/', + import.meta.url +); + +/** + * Lists the names of the documented design system patterns, from the heading + * of each pattern document in Storybook. + * + * @return The pattern names. + */ +export default async function () { + const names = ( await readdir( PATTERNS_DIRECTORY ) ) + // The introduction describes patterns in general, not one pattern. + .filter( + ( name ) => name.endsWith( '.mdx' ) && name !== 'introduction.mdx' + ) + .sort(); + + const patterns = await Promise.all( + names.map( async ( name ) => { + const source = await readFile( + new URL( name, PATTERNS_DIRECTORY ), + 'utf8' + ); + const heading = source.match( /^# (.+)$/m ); + if ( ! heading ) { + throw new Error( `${ name } has no heading.` ); + } + return heading[ 1 ].trim(); + } ) + ); + + return { patterns }; +} diff --git a/.github/workflows/review-routing.yml b/.github/workflows/review-routing.yml index 2f2a4fad0e2ab5..65fee129155bc3 100644 --- a/.github/workflows/review-routing.yml +++ b/.github/workflows/review-routing.yml @@ -35,11 +35,13 @@ jobs: steps: # On `pull_request_target`, this checks out the base branch. The # tool has no runtime dependencies, so `npm run` needs no install. + # Add the paths that the `.mts` files of the rules read. - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: sparse-checkout: | tools/review-routing .github/review-routing + storybook/stories/design-system/patterns show-progress: ${{ runner.debug == '1' && 'true' || 'false' }} persist-credentials: false diff --git a/tools/review-routing/README.md b/tools/review-routing/README.md index dd1760f47b6802..081132e434bb03 100644 --- a/tools/review-routing/README.md +++ b/tools/review-routing/README.md @@ -21,6 +21,20 @@ Does this change add or change a public API of the design system packages? ... Ask about one kind of change in each file. A question that combines several conditions gives a less useful probability, and the model can let one condition hide another. To route several kinds of change to the same reviewer, add a file for each kind with the same `reviewer`. The tool decides each rule on its own and does not combine the rules of a reviewer, so the report shows the probability of each rule. To ask a new reviewer, or to opt yourself in to a kind of change, add a file. +### Reference data + +The model knows only what the question and the pull request tell it. To give it reference data, such as a list of names that changes as the project grows, add a TypeScript module with the same name and the `.mts` extension next to the routing file. Its default export takes no arguments and returns an object: + +```ts +export default async function () { + return { stores: [ 'core', 'core/editor' ] }; +} +``` + +The model then reads the question and the data as one object, `{ "question": "...", "stores": [ ... ] }`, so the question can name the field: "Does this change add an action to one of the stores in `stores`?" `--dry-run` prints this object. + +The tool runs this file each time that it loads the rules, also with `--dry-run`, so treat it like any other code that you run from a checkout. It runs with Node.js, from the base branch in CI, and can use only Node.js built-in modules. To read a file of the repository, make its path from `import.meta.url`, and add its directory to the sparse checkout in `.github/workflows/review-routing.yml`. + ## What the model reads Every rule reads the same evidence: diff --git a/tools/review-routing/src/cli.ts b/tools/review-routing/src/cli.ts index 4ef390750255ae..0adaa0a8ab296b 100644 --- a/tools/review-routing/src/cli.ts +++ b/tools/review-routing/src/cli.ts @@ -82,8 +82,13 @@ const { state, stats } = buildEvidence( pull, generated ); const request = buildRequest( state, rules, DECISION_MODEL ?? '' ); if ( values[ 'dry-run' ] ) { - const questions = rules.map( - ( rule ) => `### ${ rule.id }\n\n${ rule.instructions }` + const questions = Object.entries( request.questions ).map( + ( [ id, { instructions } ] ) => + `### ${ id }\n\n${ + typeof instructions === 'string' + ? instructions + : `\`\`\`json\n${ JSON.stringify( instructions, null, '\t' ) }\n\`\`\`` + }` ); process.stdout.write( `${ state }\n\n---\n\n# Questions\n\n${ questions.join( '\n\n' ) }\n` diff --git a/tools/review-routing/src/decision-api.ts b/tools/review-routing/src/decision-api.ts index 00a22a87b812db..ed2b86f1a868d6 100644 --- a/tools/review-routing/src/decision-api.ts +++ b/tools/review-routing/src/decision-api.ts @@ -14,7 +14,10 @@ export type DecisionApi = { export type DecisionRequest = { model: string; state: string; - questions: Record< string, { type: 'noul'; instructions: string } >; + questions: Record< + string, + { type: 'noul'; instructions: string | Record< string, unknown > } + >; }; type DecisionResponse = { @@ -32,7 +35,9 @@ type CloudflareEnvelope = { const TIMEOUT_MS = 120_000; /** - * Builds a request with one yes or no question for each routing rule. + * Builds a request with one yes or no question for each routing rule. A rule + * with reference data sends an object, with the question in its own field, as + * the System One documentation recommends. * * @param state Evidence for the model to read. * @param rules Routing rules. @@ -50,7 +55,12 @@ export function buildRequest( questions: Object.fromEntries( rules.map( ( rule ) => [ rule.id, - { type: 'noul', instructions: rule.instructions }, + { + type: 'noul', + instructions: rule.context + ? { question: rule.instructions, ...rule.context } + : rule.instructions, + }, ] ) ), }; diff --git a/tools/review-routing/src/routing-rules.ts b/tools/review-routing/src/routing-rules.ts index 7e1b5aab3ad255..5392fbde98d090 100644 --- a/tools/review-routing/src/routing-rules.ts +++ b/tools/review-routing/src/routing-rules.ts @@ -10,6 +10,8 @@ export type RoutingRule = { threshold: number; /** File body, sent to the model as the question. */ instructions: string; + /** Reference data from the rule's optional `.mts` file. */ + context?: Record< string, unknown >; }; export const DEFAULT_THRESHOLD = 0.7; @@ -70,6 +72,45 @@ export function parseRoutingRule( id: string, source: string ): RoutingRule { return { id, reviewers, threshold, instructions }; } +/** The imported `.mts` file of a rule. */ +type ContextModule = { default?: unknown }; + +/** + * Reads the reference data from the module of a rule's `.mts` file. Its + * default export takes no arguments and returns the data, which the model + * reads in named fields next to the question. + * + * @param id Rule id. + * @param module The imported module. + * @return The reference data. + */ +export async function readContext( + id: string, + module: ContextModule +): Promise< Record< string, unknown > > { + if ( typeof module.default !== 'function' ) { + throw new Error( `${ id }.mts: the default export is not a function.` ); + } + + const context: unknown = await module.default(); + if ( + typeof context !== 'object' || + context === null || + Object.getPrototypeOf( context ) !== Object.prototype + ) { + throw new Error( `${ id }.mts: the function must return an object.` ); + } + + // The question goes in this field, so the context cannot replace it. + if ( 'question' in context ) { + throw new Error( + `${ id }.mts: the object cannot have a \`question\`.` + ); + } + + return context as Record< string, unknown >; +} + /** * Reads every routing file in a directory. * @@ -79,16 +120,25 @@ export function parseRoutingRule( id: string, source: string ): RoutingRule { export async function loadRoutingRules( directory: URL = RULES_DIRECTORY ): Promise< RoutingRule[] > { - const names = ( await readdir( directory ) ) - .filter( ( name ) => name.endsWith( '.md' ) ) - .sort(); + const files = await readdir( directory ); + const names = files.filter( ( name ) => name.endsWith( '.md' ) ).sort(); return Promise.all( - names.map( async ( name ) => - parseRoutingRule( - path.basename( name, '.md' ), + names.map( async ( name ) => { + const id = path.basename( name, '.md' ); + const rule = parseRoutingRule( + id, await readFile( new URL( name, directory ), 'utf8' ) - ) - ) + ); + + if ( files.includes( `${ id }.mts` ) ) { + rule.context = await readContext( + id, + await import( new URL( `${ id }.mts`, directory ).href ) + ); + } + + return rule; + } ) ); } diff --git a/tools/review-routing/src/__tests__/decision-api.test.ts b/tools/review-routing/src/test/decision-api.test.ts similarity index 84% rename from tools/review-routing/src/__tests__/decision-api.test.ts rename to tools/review-routing/src/test/decision-api.test.ts index d95644c7eb1e7f..240cb4f07a20c0 100644 --- a/tools/review-routing/src/__tests__/decision-api.test.ts +++ b/tools/review-routing/src/test/decision-api.test.ts @@ -22,6 +22,19 @@ describe( 'buildRequest', () => { }, } ); } ); + + it( 'puts the question and the context of a rule in an object', () => { + const rule = { ...RULE, context: { components: [ 'Button' ] } }; + + expect( + buildRequest( 'state', [ rule ], 'jev' ).questions[ + 'design-system' + ].instructions + ).toEqual( { + question: 'Ask when UI changes.', + components: [ 'Button' ], + } ); + } ); } ); describe( 'readProbability', () => { diff --git a/tools/review-routing/src/__tests__/evidence.test.ts b/tools/review-routing/src/test/evidence.test.ts similarity index 100% rename from tools/review-routing/src/__tests__/evidence.test.ts rename to tools/review-routing/src/test/evidence.test.ts diff --git a/tools/review-routing/src/test/fixtures/routing-rules/with-context.md b/tools/review-routing/src/test/fixtures/routing-rules/with-context.md new file mode 100644 index 00000000000000..9d969a92a11178 --- /dev/null +++ b/tools/review-routing/src/test/fixtures/routing-rules/with-context.md @@ -0,0 +1,5 @@ +--- +reviewer: octocat +--- + +Ask when a store changes. diff --git a/tools/review-routing/src/test/fixtures/routing-rules/with-context.mts b/tools/review-routing/src/test/fixtures/routing-rules/with-context.mts new file mode 100644 index 00000000000000..d5e62021617cf7 --- /dev/null +++ b/tools/review-routing/src/test/fixtures/routing-rules/with-context.mts @@ -0,0 +1,3 @@ +export default async function () { + return { stores: [ 'core' ] }; +} diff --git a/tools/review-routing/src/test/fixtures/routing-rules/without-context.md b/tools/review-routing/src/test/fixtures/routing-rules/without-context.md new file mode 100644 index 00000000000000..9d969a92a11178 --- /dev/null +++ b/tools/review-routing/src/test/fixtures/routing-rules/without-context.md @@ -0,0 +1,5 @@ +--- +reviewer: octocat +--- + +Ask when a store changes. diff --git a/tools/review-routing/src/__tests__/generated-files.test.ts b/tools/review-routing/src/test/generated-files.test.ts similarity index 100% rename from tools/review-routing/src/__tests__/generated-files.test.ts rename to tools/review-routing/src/test/generated-files.test.ts diff --git a/tools/review-routing/src/__tests__/routing-rules.test.ts b/tools/review-routing/src/test/routing-rules.test.ts similarity index 69% rename from tools/review-routing/src/__tests__/routing-rules.test.ts rename to tools/review-routing/src/test/routing-rules.test.ts index 9acaf79c52864c..e0a75099119549 100644 --- a/tools/review-routing/src/__tests__/routing-rules.test.ts +++ b/tools/review-routing/src/test/routing-rules.test.ts @@ -3,6 +3,7 @@ import { DEFAULT_THRESHOLD, loadRoutingRules, parseRoutingRule, + readContext, } from '../routing-rules.ts'; describe( 'parseRoutingRule', () => { @@ -72,6 +73,29 @@ describe( 'parseRoutingRule', () => { } ); } ); +describe( 'readContext', () => { + it( 'reads the object that the default export returns', async () => { + expect( + await readContext( 'data', { + default: async () => ( { stores: [ 'core' ] } ), + } ) + ).toEqual( { stores: [ 'core' ] } ); + } ); + + it.each( [ + [ 'a default export that is not a function', { default: {} } ], + [ 'a function that returns an array', { default: () => [] } ], + [ + 'an object with a question', + { default: () => ( { question: 'Ask.' } ) }, + ], + ] )( 'rejects a module with %s', async ( _, module ) => { + await expect( readContext( 'data', module ) ).rejects.toThrow( + /^data\.mts: / + ); + } ); +} ); + describe( 'loadRoutingRules', () => { it( 'reads the routing files in the repository', async () => { const rules = await loadRoutingRules(); @@ -80,4 +104,13 @@ describe( 'loadRoutingRules', () => { 'design-system-api' ); } ); + + it( 'reads the context of a rule from its .mts file', async () => { + const [ withContext, withoutContext ] = await loadRoutingRules( + new URL( './fixtures/routing-rules/', import.meta.url ) + ); + + expect( withContext.context ).toEqual( { stores: [ 'core' ] } ); + expect( withoutContext.context ).toBeUndefined(); + } ); } ); diff --git a/tools/review-routing/tsconfig.json b/tools/review-routing/tsconfig.json index d7364fe68f6888..c9101d1ea64909 100644 --- a/tools/review-routing/tsconfig.json +++ b/tools/review-routing/tsconfig.json @@ -1,5 +1,9 @@ { "$schema": "https://json.schemastore.org/tsconfig.json", "extends": "@wordpress/monorepo-tools/tsconfig/node.base.json", - "include": [ "src" ] + "compilerOptions": { + // The `.mts` files of the routing rules are outside this directory. + "rootDir": "../.." + }, + "include": [ "src", "../../.github/review-routing/*.mts" ] }