FilesExpand file tree

main

/

generate-cli-docs.test.ts

Copy path

Blame

More file actions

Blame

More file actions

Latest commit

 

History

History

History

69 lines (64 loc) · 3.01 KB

main

/

generate-cli-docs.test.ts

Copy path

Top

File metadata and controls

• Code
• Blame

69 lines (64 loc) · 3.01 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

import { readFileSync } from 'node:fs'

import path from 'node:path'

import { describe, expect, it } from 'vitest'

import { describeOption, GUIDE_PAGES, OUTPUT_DIR } from './generate-cli-docs'

/** `describeOption` reads only these two fields; the rest of the Option is irrelevant. */

function option(fields: { description?: string; defaultValue?: unknown }) {

return fields as Parameters<typeof describeOption>[0]

}

function guide(page: string): string {

return readFileSync(path.join(OUTPUT_DIR, `${page}.mdx`), 'utf8')

}

describe('an option default rendered into the reference table', () => {

/**

* A repeatable flag's Commander default is `[]` — the accumulator its

* collector appends to, not a value anyone would type. `String([])` is the

* empty string, so the table carried a dangling "Defaults to ``."

*/

it('omits the clause for a repeatable flag with an empty accumulator', () => {

const cell = describeOption(

option({

description: 'Only follow runs of this workflow (repeatable)',

defaultValue: [],

})

)

expect(cell).toBe('Only follow runs of this workflow (repeatable).')

expect(cell).not.toContain('Defaults to')

})

})

/**

* The id shapes the CLI states in its own root help (`HELP_EPILOGUE`,

* `packages/sim-cli/src/program.ts`): workflow, knowledge-base, workspace and

* run ids are bare UUIDs, table ids carry `tbl_`, file ids carry `wf_`.

*

* The guides are hand-written and the generator neither writes nor inspects

* them, so nothing else stops their placeholder ids from teaching a scheme the

* API does not use — which is how `wf_7Yb2` came to name a workflow ~10 times.

*/

const FOREIGN_ID_PREFIXES = ['ws_', 'kb_', 'run_', 'file_', 'doc_', 'org_'] as const

describe('placeholder ids in the hand-written guides', () => {

it('uses no prefix the API never issues', () => {

// No `\b` before the prefix: `printf 'wf_…\nfile_2\n'` carries a literal

// `\n`, and a word-anchored sweep reads straight past the `file_2` after it.

const candidate = new RegExp(`(.?)(${FOREIGN_ID_PREFIXES.join('|')})([A-Za-z0-9]+)(.?)`, 'g')

const offenders: string[] = []

for (const page of GUIDE_PAGES) {

guide(page)

.split('\n')

.forEach((line, index) => {

// A literal `\n` inside a quoted `printf` separates two ids, so it has

// to read as a boundary — otherwise the sweep sees `nfile_2`, takes

// the `n` for a word character, and skips the second id entirely.

const scan = line.replace(/\\[nrt]/g, ' ')

for (const [, before, prefix, rest, after] of scan.matchAll(candidate)) {

// A shell variable is read with `$` and written with `=`; the

// recipes name one `run_id`, which is not an id placeholder.

if (before === '$' || before === '{' || after === '=') continue

if (/[\w-]/.test(before)) continue

offenders.push(`${page}.mdx:${index + 1}: ${prefix}${rest}`)

}

})

}

expect(offenders).toEqual([])

})

})