@wringer/gunshi 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/README.md +25 -24
  2. package/dist/build-cli-wringer.d.ts +2 -0
  3. package/dist/build-guide-command.d.ts +2 -0
  4. package/dist/build-guide-ports.d.ts +4 -0
  5. package/dist/build-guide-wringer.d.ts +2 -0
  6. package/dist/build-lint-command.d.ts +1 -1
  7. package/dist/check-feature-file.d.ts +5 -0
  8. package/dist/collect-dead-globs.d.ts +3 -3
  9. package/dist/collect-unclaimed-files.d.ts +2 -0
  10. package/dist/parse-feature-table-span.d.ts +11 -0
  11. package/dist/parse-guide-topic.d.ts +6 -0
  12. package/dist/parse-skill-metadata.d.ts +1 -1
  13. package/dist/pick-guide-data.d.ts +20 -0
  14. package/dist/read-guide.d.ts +3 -0
  15. package/dist/read-template-hash.d.ts +1 -0
  16. package/dist/resolve-lint-failures.d.ts +6 -1
  17. package/dist/run-cli.d.ts +3 -1
  18. package/dist/run-verify.d.ts +3 -0
  19. package/dist/scrub-parsed-invocation.d.ts +3 -0
  20. package/{skills/wringer/references → guide}/create.md +29 -25
  21. package/{skills/wringer/references → guide}/fresh-subagent-brief.md +2 -0
  22. package/{skills/wringer/references → guide}/maintain.md +29 -22
  23. package/guide/overview.md +135 -0
  24. package/{skills/wringer/references → guide}/prove.md +16 -13
  25. package/guide/template/verify/SKILL.md +172 -0
  26. package/guide/template/verify/references/feature-add-item.md +20 -0
  27. package/{skills/wringer → guide}/template/verify-registry.ts +2 -1
  28. package/package.json +10 -9
  29. package/src/build-cli-wringer.ts +32 -0
  30. package/src/build-guide-command.ts +37 -0
  31. package/src/build-guide-ports.ts +73 -0
  32. package/src/build-guide-wringer.ts +19 -0
  33. package/src/build-lint-command.ts +32 -6
  34. package/src/check-feature-file.ts +105 -0
  35. package/src/collect-dead-globs.ts +18 -11
  36. package/src/collect-unclaimed-files.ts +17 -0
  37. package/src/parse-feature-table-span.ts +56 -0
  38. package/src/parse-guide-topic.ts +14 -0
  39. package/src/parse-skill-metadata.ts +8 -6
  40. package/src/pick-guide-data.ts +47 -0
  41. package/src/read-guide.ts +49 -0
  42. package/src/read-template-hash.ts +42 -0
  43. package/src/render-human-envelope.ts +7 -0
  44. package/src/resolve-lint-failures.ts +182 -11
  45. package/src/run-cli.ts +17 -2
  46. package/src/run-verify.ts +38 -15
  47. package/src/scrub-parsed-invocation.ts +32 -0
  48. package/src/wringer-gunshi.ts +7 -24
  49. package/dist/build-linted-wringer.d.ts +0 -2
  50. package/dist/find-skill-copy-refusal.d.ts +0 -8
  51. package/dist/parse-skill-install-args.d.ts +0 -3
  52. package/dist/template-version.d.ts +0 -1
  53. package/dist/write-skill-copy.d.ts +0 -12
  54. package/skills/wringer/SKILL.md +0 -143
  55. package/skills/wringer/template/verify/SKILL.md +0 -176
  56. package/skills/wringer/template/verify/references/feature-map.md +0 -17
  57. package/src/build-linted-wringer.ts +0 -16
  58. package/src/find-skill-copy-refusal.ts +0 -34
  59. package/src/parse-skill-install-args.ts +0 -25
  60. package/src/template-version.ts +0 -3
  61. package/src/write-skill-copy.ts +0 -75
  62. /package/{skills/wringer → guide}/template/verify.ts +0 -0
@@ -0,0 +1,172 @@
1
+ ---
2
+ name: verify
3
+ description:
4
+ 'Uses the Larder app the way a user would with `bun verify`, and records the verdict that a
5
+ feature works. Load it before you check a change in the running app, run the journey of a feature,
6
+ or put the verdicts in a PR.'
7
+ metadata:
8
+ wringer-template: 'sha256:5ad8a6ead397'
9
+ wringer-command: bun verify
10
+ ---
11
+
12
+ # Verify Larder
13
+
14
+ Use `bun verify` to start the app, use each feature your change touches the way a user would, and
15
+ record a verdict that it works. Put the report in the PR with `bun verify publish`, and hand back
16
+ the PR link and each feature you could not verify. The CI gate, `bun verify gate`, fails a PR that
17
+ changes a feature with no verdict.
18
+
19
+ The mistakes that cost the most time:
20
+
21
+ - **Using the app before `doctor` passes.** `bun verify doctor` checks that the app answers and that
22
+ each driver works. Until it passes on the run that `up` or `attach` started, any command that
23
+ touches the app fails with exit code 3.
24
+ - **Editing the app's code while `up` runs it.** The next command that touches the app fails with
25
+ `doctor-required`. Run `bun verify up --restart` and `bun verify doctor`, then the journey again.
26
+ - **Running `done` before you check the end state.** `done` checks only that one command of the
27
+ journey succeeded. Check the result yourself first.
28
+ - **Branching on the error message.** Branch on the exit code and `error.code`. The message text can
29
+ change in any release.
30
+
31
+ ## Key rules
32
+
33
+ - [Check a change](#check-a-change): for each changed feature, run its journey, check the end state,
34
+ then `done`.
35
+ - [Read the envelope](#read-the-envelope): branch on the exit code and `error.code`.
36
+ - [Targets](#targets): check a change on a target that `up` starts.
37
+ - [Commands](#commands): `bun verify --help` lists every command.
38
+ - [Update a feature file](#update-a-feature-file): fix a broken journey in the same PR, and run
39
+ `lint`.
40
+
41
+ ## References
42
+
43
+ Read a feature's file before you run its journey: what the feature does, how a user reaches it, the
44
+ journey of `bun verify` commands, and the end state that shows it works.
45
+
46
+ <!-- wringer:features -->
47
+
48
+ | Feature | Summary | File |
49
+ | -------- | -------------------------------- | ---------------------------------------------------------------- |
50
+ | add-item | Add an item from the pantry page | [references/feature-add-item.md](references/feature-add-item.md) |
51
+
52
+ <!-- /wringer:features -->
53
+
54
+ ## Check a change
55
+
56
+ 1. Run `bun verify report`. A feature in `data.report.features` shows `changed: true` when a file
57
+ under its `paths` differs from the default branch, committed or not. Each changed feature needs a
58
+ verdict.
59
+ 2. Unless your task names another target, start a run on `local`, with the commands in the
60
+ [Targets](#targets) table. Expect from `up` or `attach`: `ok: true`, and the app's endpoints in
61
+ `data.endpoints`.
62
+ 3. Run `bun verify doctor`. Expect: `data.passed: true`. When a check fails, fix its cause, and run
63
+ `doctor` again.
64
+ 4. Run the journey from the feature's file in [References](#references). Its first line,
65
+ `use --feature`, records each later command under that feature, and leaves the target as it is.
66
+ Expect: each command exits 0.
67
+ 5. Compare the app with the feature's end state:
68
+ - When it matches, and no command failed with `read-only`, go on to step 6.
69
+ - When your change broke the feature, fix the app's code. Then run `bun verify up --restart`,
70
+ `bun verify doctor` and the journey again.
71
+ - When your change means to change the end state, fix the feature's file, and run
72
+ `bun verify lint`. Then run the journey again.
73
+ - Otherwise, skip `done` for this feature. List it in your reply with the end state you expected
74
+ and the `data` you got.
75
+ 6. Run `bun verify done` to record a verdict for the feature that `use --feature` set. Expect:
76
+ `ok: true`. It fails with `check-failed` until a journey command succeeds after `doctor`.
77
+ 7. Repeat steps 4 to 6 for each feature with `changed: true`, and for each feature your task names,
78
+ in the order of the table in [References](#references). When [Targets](#targets) names a journey
79
+ to run last, run it last.
80
+ 8. Run `bun verify report --human` to read the report. Expect: `verified` on each changed feature.
81
+ After `done`, an edit to a file under a feature's `paths` makes its verdict `stale`; a commit
82
+ alone leaves each verdict as it was. Repeat steps 4 to 6 for each stale feature.
83
+ 9. Run `bun verify publish`. Expect: `ok: true`, and `data.action` of `created`, `replaced` or
84
+ `unchanged`. It writes the report into the description of the branch's open PR.
85
+ 10. End the run: `bun verify down` after `up`, or `bun verify detach` after `attach`.
86
+
87
+ ## Read the envelope
88
+
89
+ Each command prints one JSON envelope as its last line, or text for a person with `--human`. A
90
+ streaming command, such as `doctor`, prints JSON event lines before it. Read these fields:
91
+
92
+ - `ok`, then `data` on success, or `error.code`, `error.message` and `error.hint` on failure;
93
+ - `evidence`: the files the command kept, under `.wringer/`;
94
+ - `truncated` and `truncatedPath`: `data` was too large, and the file at `truncatedPath` holds it.
95
+
96
+ | Exit | `error.code` | Do |
97
+ | ---- | -------------------- | ------------------------------------------------------------------------------------------------- |
98
+ | 0 | none | Go on. |
99
+ | 1 | `check-failed` | Read the evidence. When `done` failed, run the journey again; else go on as step 5 says. |
100
+ | 2 | `usage` | Fix the command; `--help` shows its flags. |
101
+ | 3 | `read-only` | Leave the write undone, skip `done` for the feature, and list the write in your reply. |
102
+ | 3 | `doctor-required` | Run the commands in `error.hint`, then run the feature's journey again. |
103
+ | 3 | `not-running` | Start the run, as step 2 says. |
104
+ | 3 | `target-not-allowed` | Follow `error.hint`. |
105
+ | 4 | `environment` | Read `error.message`, fix the problem on this machine, such as a missing browser, and retry. |
106
+ | 4 | `internal` | Report the command and `error.message`: the CLI has a bug. |
107
+ | 5 | `timeout` | Retry once with twice the timeout; the default is `--timeout-ms=120000`. Report a second timeout. |
108
+
109
+ ## Targets
110
+
111
+ Start a launch target's app with `bun verify up`, and stop it with `bun verify down`. Connect to an
112
+ attach target, an app that runs apart from `bun verify`, with `bun verify attach`.
113
+ `bun verify detach` leaves it running. Your edits never reach an attach target's app, so check a
114
+ change on a launch target.
115
+
116
+ Run `bun verify use --target <target>` to point every later command at a target. `--target` on one
117
+ command points that command alone.
118
+
119
+ <!-- repo: targets -->
120
+
121
+ | Target | Start with | Access | Notes |
122
+ | -------- | ---------------------------------------------------------- | ---------- | ------------------------------------------------------ |
123
+ | `local` | `bun verify use --target local`, then `bun verify up` | read-write | Starts the app with `bun run dev`. |
124
+ | `shared` | `bun verify use --target shared`, then `bun verify attach` | read-only | An app that `bun verify` did not start. Never stop it. |
125
+
126
+ <!-- /repo -->
127
+
128
+ ## Commands
129
+
130
+ Run `bun verify --help` for the list, with each command marked `[read]` or `[write]`. Run
131
+ `bun verify <command> --help` for a command's flags. The top-level list shows only the name of a
132
+ group, such as `action`: run `bun verify <group> --help` for its commands.
133
+
134
+ - Write a negative number with `=`, as in `--offset=-5`.
135
+ - Pass an object as JSON text, as in `--filter '{"shelf":"top"}'`.
136
+
137
+ <!-- repo: commands -->
138
+
139
+ - `bun verify action add-item --name <name>` adds an item through the API.
140
+ - `bun verify items count` counts the items through the API, in `data.count`.
141
+
142
+ <!-- /repo -->
143
+
144
+ ## Update a feature file
145
+
146
+ <!-- repo: registry -->
147
+
148
+ The registry, `scripts/verify/verify-registry.ts`, declares the targets, actions, commands, doctor
149
+ checks and features, with each feature's `paths`.
150
+
151
+ <!-- /repo -->
152
+
153
+ - When a feature's journey stops working because the feature changed, fix the journey in the same
154
+ PR. You may edit any line of a feature file.
155
+ - A feature file needs `## Journey`, whose first `bash` line is `bun verify use --feature <name>`,
156
+ and `## End state`.
157
+ - In this SKILL.md, edit only these parts. An upgrade of the template replaces every other line.
158
+ - the frontmatter's `name` and `description`, and the `#` title;
159
+ - the lines inside each `<!-- repo: <name> -->` block;
160
+ - the table between the `wringer:features` markers: replace it with the output of
161
+ `bun verify features --markdown`.
162
+ - Leave `metadata.wringer-template` as it is. When `lint` fails with check `template`, run
163
+ `bun verify guide maintain`, and follow its steps to upgrade the template.
164
+ - Make each changed file match a feature's `paths` or a glob in the registry's `.ignore` list. The
165
+ gate fails on a changed file that matches neither. `bun verify features` lists each feature's
166
+ `paths`.
167
+ - After you change this skill, a feature file or the registry, run `bun verify lint`, and fix each
168
+ failure it reports.
169
+
170
+ **Reply:** the PR link that `bun verify publish` returned in `data.pr.url`, and each feature you
171
+ could not verify, with the command that failed and its `error.code`, or the end state you expected
172
+ and the `data` you got.
@@ -0,0 +1,20 @@
1
+ # add-item
2
+
3
+ A user adds an item to the pantry on the `/pantry` page, by typing a name and pressing Add. The
4
+ journey adds the item through the API that the form calls.
5
+
6
+ ## Journey
7
+
8
+ ```bash
9
+ bun verify use --feature add-item
10
+ bun verify items count
11
+ bun verify action add-item --name Oats
12
+ bun verify items count
13
+ bun verify http request --path /api/items
14
+ ```
15
+
16
+ ## End state
17
+
18
+ - The `data.count` of the second `items count` is one more than the first.
19
+ - The `data.json` of `http request` lists an item named `Oats`. An earlier run may have added one
20
+ too. Only the count proves this run added it.
@@ -78,6 +78,7 @@ export function createVerifyRegistry(): Wringer {
78
78
  summary: 'Add an item from the pantry page',
79
79
  paths: ['src/items/**', 'src/pages/pantry/**'],
80
80
  })
81
- .ignore('docs/**', '**/*.md', '**/*.test.ts', '.github/**', '.claude/**', 'scripts/verify/**')
81
+ .shared('scripts/verify/**')
82
+ .ignore('docs/**', '**/*.md', '**/*.test.ts', '.github/**', '.claude/**')
82
83
  .build();
83
84
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wringer/gunshi",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "The gunshi adapter for wringer: turns a wringer registry into a CLI",
5
5
  "homepage": "https://github.com/zgeoff/wringer/tree/main/packages/gunshi#readme",
6
6
  "bugs": "https://github.com/zgeoff/wringer/issues",
@@ -18,8 +18,8 @@
18
18
  "!src/**/*.test.ts",
19
19
  "dist",
20
20
  "!src/test-utils",
21
- "skills",
22
- "!skills/**/*.test.ts"
21
+ "guide",
22
+ "!guide/**/*.test.ts"
23
23
  ],
24
24
  "type": "module",
25
25
  "exports": {
@@ -38,16 +38,17 @@
38
38
  "dependencies": {
39
39
  "gunshi": "0.37.3",
40
40
  "tiny-invariant": "1.3.3",
41
- "ts-pattern": "5.9.2",
42
- "zod": "4.6.7"
41
+ "ts-pattern": "5.9.2"
43
42
  },
44
43
  "devDependencies": {
45
- "@wringer/core": "0.2.0",
46
- "@wringer/http": "0.1.2",
47
- "@zgeoff/testing": "0.3.0"
44
+ "@wringer/core": "0.3.0",
45
+ "@wringer/http": "0.1.3",
46
+ "@zgeoff/testing": "0.3.0",
47
+ "zod": "4.6.7"
48
48
  },
49
49
  "peerDependencies": {
50
- "@wringer/core": "0.2.0"
50
+ "@wringer/core": "0.3.0",
51
+ "zod": "^4.0.0"
51
52
  },
52
53
  "engines": {
53
54
  "bun": ">=1.3"
@@ -0,0 +1,32 @@
1
+ import { WringerError } from '@wringer/core';
2
+ import type { RegisteredCommand, Wringer } from '@wringer/core';
3
+ import { buildGuideCommand } from './build-guide-command.ts';
4
+ import { buildLintCommand } from './build-lint-command.ts';
5
+
6
+ // The registry with the `lint` and `guide` built-ins added. `lint` parses journey lines with
7
+ // gunshi, so this package adds them rather than core. `registryFile` is the registry's own file,
8
+ // which `lint` checks for cover.
9
+ export function buildCLIWringer(
10
+ wringer: Wringer,
11
+ skillFolder: string,
12
+ registryFile: string | null = null,
13
+ ): Wringer {
14
+ const added = [buildLintCommand(skillFolder, registryFile), buildGuideCommand()];
15
+
16
+ for (const command of added) {
17
+ const key = command.info.path.join(' ');
18
+
19
+ if (wringer.commands.has(key)) {
20
+ throw new WringerError('usage', { message: `Two commands share the name \`${key}\`.` });
21
+ }
22
+ }
23
+
24
+ return Object.freeze({
25
+ ...wringer,
26
+ commands: new Map([...wringer.commands, ...added.map((command) => toEntry(command))]),
27
+ });
28
+ }
29
+
30
+ function toEntry(command: RegisteredCommand): [string, RegisteredCommand] {
31
+ return [command.info.path.join(' '), command];
32
+ }
@@ -0,0 +1,37 @@
1
+ import { WringerError, buildBuiltinCommand } from '@wringer/core';
2
+ import type { RegisteredCommand } from '@wringer/core';
3
+ import { z } from 'zod';
4
+ import { guideDataSchema, pickGuideData } from './pick-guide-data.ts';
5
+ import type { GuideData } from './pick-guide-data.ts';
6
+ import { readGuide } from './read-guide.ts';
7
+
8
+ const guideArgsSchema = z.strictObject({
9
+ topic: z.string().min(1).optional().describe('The topic to print; leave out to list the topics'),
10
+ });
11
+
12
+ type GuideArgs = z.infer<typeof guideArgsSchema>;
13
+
14
+ // `guide` needs no run and no repo CLI state: it prints the guide shipped in the installed package.
15
+ export function buildGuideCommand(): RegisteredCommand {
16
+ return buildBuiltinCommand<GuideArgs, GuideData>({
17
+ path: ['guide'],
18
+ summary: 'Print the guide for adding a verify CLI to a repo, or one of its topics',
19
+ args: guideArgsSchema,
20
+ positionals: ['topic'],
21
+ data: guideDataSchema,
22
+ effect: 'read',
23
+ needsRun: false,
24
+ needsDoctor: false,
25
+ run: async (args) => {
26
+ const guide = await readGuide();
27
+
28
+ const data = pickGuideData(guide, args.topic);
29
+
30
+ if (data instanceof WringerError) {
31
+ throw data;
32
+ }
33
+
34
+ return data;
35
+ },
36
+ });
37
+ }
@@ -0,0 +1,73 @@
1
+ import {
2
+ WringerError,
3
+ createFileState,
4
+ createNodeRepoHost,
5
+ makeProcessSupervisorPort,
6
+ } from '@wringer/core';
7
+ import type { PullRequestHost, RepoHost, StateFileSystem } from '@wringer/core';
8
+ import type { CLIPorts } from './run-cli.ts';
9
+
10
+ type RepoPorts = Pick<CLIPorts, 'readRepoRoot' | 'openRepo'>;
11
+
12
+ // The ports for a registry that needs no repo: the folder it runs in stands for the root, whether
13
+ // or not it is a git worktree, and no run state is read or written.
14
+ export function buildGuidePorts(selfCommand: readonly string[]): RepoPorts {
15
+ return {
16
+ readRepoRoot: (cwd) => Promise.resolve(cwd),
17
+ openRepo: (root) => ({
18
+ state: createFileState({
19
+ stateDir: root,
20
+ lockTimeoutMs: 1000,
21
+ fs: buildEmptyFileSystem(),
22
+ }),
23
+ repoHost: buildGitlessRepoHost(),
24
+ supervisor: makeProcessSupervisorPort({ selfCommand, root, stateDir: root }),
25
+ pullRequests: buildRefusingPullRequestHost(),
26
+ }),
27
+ };
28
+ }
29
+
30
+ // A file system that holds nothing and takes no write, so `guide` reads no state from the folder it
31
+ // runs in and leaves none behind.
32
+ function buildEmptyFileSystem(): StateFileSystem {
33
+ return {
34
+ readText: () => Promise.resolve(null),
35
+ listNames: () => Promise.resolve([]),
36
+ readFileSize: () => Promise.resolve(0),
37
+ createDirectory: () => Promise.resolve(),
38
+ appendText: refuseWrite,
39
+ appendPrivateText: refuseWrite,
40
+ removeFile: refuseWrite,
41
+ truncateFile: refuseWrite,
42
+ writeTextAtomic: refuseWrite,
43
+ };
44
+ }
45
+
46
+ function refuseWrite(): Promise<never> {
47
+ return Promise.reject(
48
+ new WringerError('environment', {
49
+ message: 'The guide keeps no state.',
50
+ hint: 'Run a repo command through the repo verify CLI.',
51
+ }),
52
+ );
53
+ }
54
+
55
+ // A host whose git always fails, so the dispatcher labels the envelope with no SHA and `guide`
56
+ // reads nothing outside the package, even inside a worktree.
57
+ function buildGitlessRepoHost(): RepoHost {
58
+ return {
59
+ ...createNodeRepoHost(),
60
+ runGit: () =>
61
+ Promise.reject(new WringerError('environment', { message: 'The guide reads no git.' })),
62
+ };
63
+ }
64
+
65
+ function buildRefusingPullRequestHost(): PullRequestHost {
66
+ return { findOpen: refusePullRequest, readBody: refusePullRequest, writeBody: refusePullRequest };
67
+ }
68
+
69
+ function refusePullRequest(): Promise<never> {
70
+ return Promise.reject(
71
+ new WringerError('environment', { message: 'The guide reads no pull request.' }),
72
+ );
73
+ }
@@ -0,0 +1,19 @@
1
+ import { createWringer, local } from '@wringer/core';
2
+ import type { Wringer } from '@wringer/core';
3
+ import { buildGuideCommand } from './build-guide-command.ts';
4
+
5
+ // A registry whose only command is `guide`, for a repo that has no verify CLI yet.
6
+ export function buildGuideWringer(): Wringer {
7
+ const base = createWringer({ name: 'wringer-gunshi' })
8
+ .target('local', {
9
+ mode: 'attach',
10
+ access: 'read-only',
11
+ host: local(),
12
+ endpoints: () => ({}),
13
+ })
14
+ .build();
15
+
16
+ const guide = buildGuideCommand();
17
+
18
+ return Object.freeze({ ...base, commands: new Map([[guide.info.path.join(' '), guide]]) });
19
+ }
@@ -1,10 +1,11 @@
1
- import { join } from 'node:path';
1
+ import { realpath } from 'node:fs/promises';
2
+ import { isAbsolute, join, relative, resolve } from 'node:path';
2
3
  import { WringerError, buildBuiltinCommand } from '@wringer/core';
3
4
  import type { BuiltinContext, RegisteredCommand } from '@wringer/core';
4
5
  import { z } from 'zod';
5
6
  import { collectLintFiles } from './collect-lint-files.ts';
7
+ import { readTemplateHash } from './read-template-hash.ts';
6
8
  import { lintFailureSchema, resolveLintFailures } from './resolve-lint-failures.ts';
7
- import { templateVersion } from './template-version.ts';
8
9
 
9
10
  const lintArgsSchema = z.strictObject({});
10
11
 
@@ -19,7 +20,10 @@ const lintDataSchema = z.strictObject({
19
20
  type LintData = z.infer<typeof lintDataSchema>;
20
21
 
21
22
  // `lint` needs no run, so CI can call it on a fresh checkout.
22
- export function buildLintCommand(skillFolder: string): RegisteredCommand {
23
+ export function buildLintCommand(
24
+ skillFolder: string,
25
+ registryFile: string | null,
26
+ ): RegisteredCommand {
23
27
  return buildBuiltinCommand<LintArgs, LintData>({
24
28
  path: ['lint'],
25
29
  summary: 'Check the feature paths and the verify skill against the CLI, with no running app',
@@ -28,11 +32,15 @@ export function buildLintCommand(skillFolder: string): RegisteredCommand {
28
32
  effect: 'read',
29
33
  needsRun: false,
30
34
  needsDoctor: false,
31
- run: (_args, ctx) => runLint(ctx, skillFolder),
35
+ run: (_args, ctx) => runLint(ctx, skillFolder, registryFile),
32
36
  });
33
37
  }
34
38
 
35
- async function runLint(ctx: BuiltinContext, skillFolder: string): Promise<LintData> {
39
+ async function runLint(
40
+ ctx: BuiltinContext,
41
+ skillFolder: string,
42
+ registryFile: string | null,
43
+ ): Promise<LintData> {
36
44
  const root = ctx.session.root;
37
45
 
38
46
  const [listed, deleted] = await Promise.all([
@@ -62,8 +70,9 @@ async function runLint(ctx: BuiltinContext, skillFolder: string): Promise<LintDa
62
70
  wringer: ctx.wringer,
63
71
  files: lintFiles.files,
64
72
  skillPath,
73
+ registryFile: await resolveRegistryFile(root, registryFile),
65
74
  skillFiles,
66
- templateVersion,
75
+ templateHash: await readTemplateHash(),
67
76
  });
68
77
 
69
78
  const data = { skill: skillPath, commands: result.commands, failures: [...result.failures] };
@@ -76,6 +85,23 @@ async function runLint(ctx: BuiltinContext, skillFolder: string): Promise<LintDa
76
85
  return data;
77
86
  }
78
87
 
88
+ // The registry file as a path from the repo root, or null when it is unknown or outside the repo.
89
+ // Both sides go through `realpath`, so a symlinked checkout still compares equal.
90
+ async function resolveRegistryFile(root: string, file: string | null): Promise<string | null> {
91
+ if (file === null) {
92
+ return null;
93
+ }
94
+
95
+ const [realRoot, realFile] = await Promise.all([
96
+ realpath(root).catch(() => root),
97
+ realpath(resolve(root, file)).catch(() => resolve(root, file)),
98
+ ]);
99
+
100
+ const path = relative(realRoot, realFile).split('\\').join('/');
101
+
102
+ return path === '..' || path.startsWith('../') || isAbsolute(path) ? null : path;
103
+ }
104
+
79
105
  function buildLintError(data: LintData): WringerError | null {
80
106
  if (data.failures.length === 0) {
81
107
  return null;
@@ -0,0 +1,105 @@
1
+ export interface FeatureFileProblem {
2
+ readonly line: number;
3
+ readonly problem: string;
4
+ }
5
+
6
+ const openingFencePattern = /^\s*(?<marker>`{3,}|~{3,})\s*(?<info>.*)$/u;
7
+ const closingFencePattern = /^\s*(?<marker>`{3,}|~{3,})\s*$/u;
8
+ const headingPattern = /^##\s+(?<title>.*?)\s*#*\s*$/u;
9
+
10
+ interface Fence {
11
+ readonly marker: string;
12
+ readonly language: string;
13
+ readonly line: number;
14
+ }
15
+
16
+ // Why a feature file is misshapen: it lacks `## Journey` or `## End state`, its Journey holds no
17
+ // `bash` block, or the first line of that block is not `<cli> use --feature <name>`. `cliWords` is
18
+ // the words that call the CLI, or null when the skill's frontmatter does not give them.
19
+ export function checkFeatureFile(
20
+ text: string,
21
+ name: string,
22
+ cliWords: readonly string[] | null,
23
+ ): readonly FeatureFileProblem[] {
24
+ const lines = text.split(/\r?\n/u);
25
+ const problems: FeatureFileProblem[] = [];
26
+ let fence: Fence | null = null;
27
+ let section: string | null = null;
28
+ let journeyLine: number | null = null;
29
+ let hasEndState = false;
30
+ let firstBlock: { readonly line: number; readonly text: string | null } | null = null;
31
+ let inFirstBlock = false;
32
+
33
+ for (const [index, line] of lines.entries()) {
34
+ const lineNumber = index + 1;
35
+
36
+ if (fence === null) {
37
+ const opened = openingFencePattern.exec(line);
38
+
39
+ if (opened?.groups !== undefined) {
40
+ fence = {
41
+ marker: opened.groups['marker'] ?? '```',
42
+ language: (opened.groups['info'] ?? '').trim().split(/\s+/u)[0] ?? '',
43
+ line: lineNumber,
44
+ };
45
+
46
+ if (section === 'Journey' && firstBlock === null && fence.language === 'bash') {
47
+ firstBlock = { line: lineNumber, text: null };
48
+ inFirstBlock = true;
49
+ }
50
+
51
+ continue;
52
+ }
53
+
54
+ const title = headingPattern.exec(line)?.groups?.['title'];
55
+
56
+ if (title !== undefined) {
57
+ section = title;
58
+
59
+ if (title === 'Journey') {
60
+ journeyLine ??= lineNumber;
61
+ }
62
+
63
+ if (title === 'End state') {
64
+ hasEndState = true;
65
+ }
66
+ }
67
+
68
+ continue;
69
+ }
70
+
71
+ if (closingFencePattern.exec(line)?.groups?.['marker']?.startsWith(fence.marker) === true) {
72
+ fence = null;
73
+ inFirstBlock = false;
74
+ continue;
75
+ }
76
+
77
+ if (inFirstBlock && firstBlock?.text === null && line.trim() !== '') {
78
+ firstBlock = { line: lineNumber, text: line.trim().replace(/^\$\s+/u, '') };
79
+ }
80
+ }
81
+
82
+ if (journeyLine === null) {
83
+ problems.push({ line: 1, problem: 'The file has no `## Journey` section.' });
84
+ } else if (firstBlock?.text === null || firstBlock === null) {
85
+ problems.push({
86
+ line: journeyLine,
87
+ problem: 'The `## Journey` section has no `bash` block with a command in it.',
88
+ });
89
+ } else if (cliWords !== null) {
90
+ const expected = `${cliWords.join(' ')} use --feature ${name}`;
91
+
92
+ if (firstBlock.text !== expected) {
93
+ problems.push({
94
+ line: firstBlock.line,
95
+ problem: `The first line of the Journey's first \`bash\` block is \`${firstBlock.text}\`, and it must be \`${expected}\`.`,
96
+ });
97
+ }
98
+ }
99
+
100
+ if (!hasEndState) {
101
+ problems.push({ line: 1, problem: 'The file has no `## End state` section.' });
102
+ }
103
+
104
+ return problems;
105
+ }
@@ -1,21 +1,28 @@
1
- import type { FeatureDefinition } from '@wringer/core';
1
+ import type { Wringer } from '@wringer/core';
2
2
 
3
3
  export interface DeadGlob {
4
- readonly feature: string;
4
+ // `feature <name>`, `shared` or `ignore`.
5
+ readonly where: string;
5
6
  readonly glob: string;
6
7
  }
7
8
 
8
- // Each feature's `paths` glob that matches none of the repo's files. A dead glob maps no change to
9
- // its feature, so the gate never asks for that feature's verdict.
10
- export function collectDeadGlobs(
11
- features: readonly FeatureDefinition[],
12
- files: readonly string[],
13
- ): readonly DeadGlob[] {
14
- return features.flatMap((feature) =>
15
- feature.paths.flatMap((glob) => {
9
+ // Each feature, shared and ignore glob that matches none of the repo's files. A dead glob maps no
10
+ // change to its feature, or claims nothing, so it hides a rename or a typo.
11
+ export function collectDeadGlobs(wringer: Wringer, files: readonly string[]): readonly DeadGlob[] {
12
+ const groups = [
13
+ ...wringer.features.map((feature) => ({
14
+ where: `feature ${feature.name}`,
15
+ globs: feature.paths,
16
+ })),
17
+ { where: 'shared', globs: wringer.shared },
18
+ { where: 'ignore', globs: wringer.ignore },
19
+ ];
20
+
21
+ return groups.flatMap((group) =>
22
+ group.globs.flatMap((glob) => {
16
23
  const pattern = new Bun.Glob(glob);
17
24
 
18
- return files.some((file) => pattern.match(file)) ? [] : [{ feature: feature.name, glob }];
25
+ return files.some((file) => pattern.match(file)) ? [] : [{ where: group.where, glob }];
19
26
  }),
20
27
  );
21
28
  }
@@ -0,0 +1,17 @@
1
+ import { isGlobMatch } from '@wringer/core';
2
+ import type { Wringer } from '@wringer/core';
3
+
4
+ // Each file that no feature's `paths`, no shared glob and no ignore glob matches. The gate cannot
5
+ // tell what such a file changes, so it fails on it.
6
+ export function collectUnclaimedFiles(
7
+ wringer: Wringer,
8
+ files: readonly string[],
9
+ ): readonly string[] {
10
+ const globs = [
11
+ ...wringer.features.flatMap((feature) => feature.paths),
12
+ ...wringer.shared,
13
+ ...wringer.ignore,
14
+ ];
15
+
16
+ return files.filter((file) => !isGlobMatch(file, globs));
17
+ }