@venizia/vulcan 0.4.5 → 0.4.6

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 (51) hide show
  1. package/LICENSE.md +1 -1
  2. package/README.md +13 -0
  3. package/base/checks/wiki-anchors.ts +8 -0
  4. package/base/checks/wiki-source-links.ts +8 -0
  5. package/base/hooks/guard-git.ts +9 -2
  6. package/base/hooks/guard-writes.ts +4 -0
  7. package/base/hooks/session-start.ts +14 -4
  8. package/base/make/vulcan.mk +12 -1
  9. package/base/references/delegation-brief.md +5 -4
  10. package/base/rules.md +2 -2
  11. package/base/skills/docs-writing/SKILL.md +1 -1
  12. package/base/skills/docs-writing/references/agent-documents.md +1 -1
  13. package/base/skills/knowledge-sync/SKILL.md +1 -1
  14. package/base/skills/plan-a-change/SKILL.md +1 -1
  15. package/base/skills/report-back/SKILL.md +1 -1
  16. package/base/skills/retro/SKILL.md +1 -1
  17. package/base/skills/review-a-change/SKILL.md +1 -1
  18. package/base/skills/ship/SKILL.md +1 -1
  19. package/base/skills/visualize-work/SKILL.md +33 -11
  20. package/base/skills/visualize-work/references/spec.md +77 -12
  21. package/package.json +4 -4
  22. package/src/config/schema.ts +58 -4
  23. package/src/doctor/checks.ts +29 -1
  24. package/src/doctor/runner.ts +2 -0
  25. package/src/hooks/common/constants.ts +5 -0
  26. package/src/hooks/guard-git.ts +22 -2
  27. package/src/hooks/guard-outside.ts +20 -3
  28. package/src/hooks/guard-writes.ts +17 -6
  29. package/src/hooks/index.ts +2 -0
  30. package/src/hooks/project-guards.ts +123 -0
  31. package/src/hooks/project-tmp.ts +36 -0
  32. package/src/hooks/session-digest.ts +5 -0
  33. package/src/manifest/render.ts +38 -0
  34. package/src/sync/claude-launch.ts +48 -0
  35. package/src/sync/index.ts +1 -0
  36. package/src/sync/local-choice.ts +2 -0
  37. package/src/visualize/assets.ts +195 -54
  38. package/src/visualize/charts.ts +235 -0
  39. package/src/visualize/constants.ts +106 -1
  40. package/src/visualize/diagrams.ts +224 -0
  41. package/src/visualize/icons.ts +28 -0
  42. package/src/visualize/layout.ts +58 -8
  43. package/src/visualize/page.ts +152 -146
  44. package/src/visualize/schema.ts +246 -0
  45. package/src/visualize/sections.ts +370 -0
  46. package/src/visualize/validate.ts +100 -7
  47. package/src/wiki/anchors.ts +118 -0
  48. package/src/wiki/command.ts +110 -0
  49. package/src/wiki/constants.ts +30 -0
  50. package/src/wiki/index.ts +4 -0
  51. package/src/wiki/source-links.ts +186 -0
@@ -0,0 +1,110 @@
1
+ import { existsSync } from 'node:fs';
2
+ import { ExitCodes } from '../common/index.ts';
3
+ import { checkAnchors } from './anchors.ts';
4
+ import { WikiDefaults, WikiFlags } from './constants.ts';
5
+ import { checkSourceLinks } from './source-links.ts';
6
+
7
+ /** The value after `--flag`, or the fallback; `undefined` when the flag has no value after it. */
8
+ const valueOf = (opts: { args: string[]; flag: string; fallback?: string }): string | undefined => {
9
+ const at = opts.args.indexOf(opts.flag);
10
+
11
+ if (at === -1) {
12
+ return opts.fallback;
13
+ }
14
+
15
+ const value = opts.args[at + 1];
16
+
17
+ return value === undefined || value.startsWith('--') ? undefined : value;
18
+ };
19
+
20
+ const listOf = (opts: { value: string }): string[] =>
21
+ opts.value
22
+ .split(',')
23
+ .map((item) => item.trim())
24
+ .filter((item) => item !== '');
25
+
26
+ /**
27
+ * `wiki-source-links --repo <owner/name>`: every source path the wiki names is tracked by git. Run from the
28
+ * repository root; the other flags replace the defaults (comma-separated lists).
29
+ */
30
+ export const runSourceLinksCommand = (opts: { args: string[]; root: string }): number => {
31
+ const { args } = opts;
32
+ const repo = valueOf({ args, flag: WikiFlags.REPO });
33
+ const directories = valueOf({
34
+ args,
35
+ flag: WikiFlags.DIRS,
36
+ fallback: `${WikiDefaults.CONTENT_DIRECTORY},${WikiDefaults.KNOWLEDGE_DIRECTORY}`,
37
+ });
38
+ const skipProse = valueOf({
39
+ args,
40
+ flag: WikiFlags.SKIP_PROSE,
41
+ fallback: WikiDefaults.CHANGELOG_DIRECTORY,
42
+ });
43
+ const skip = valueOf({ args, flag: WikiFlags.SKIP, fallback: '' });
44
+
45
+ if (repo === undefined || !/^[\w.-]+\/[\w.-]+$/.test(repo)) {
46
+ console.error(
47
+ `wiki-source-links: ${WikiFlags.REPO} <owner/name> is required, for example ${WikiFlags.REPO} VENIZIA-AI/vulcan`,
48
+ );
49
+
50
+ return ExitCodes.FAILURE;
51
+ }
52
+
53
+ if (directories === undefined || skipProse === undefined || skip === undefined) {
54
+ console.error('wiki-source-links: a flag has no value after it');
55
+
56
+ return ExitCodes.FAILURE;
57
+ }
58
+
59
+ const { checked, missing } = checkSourceLinks({
60
+ root: opts.root,
61
+ repo,
62
+ directories: listOf({ value: directories }),
63
+ skipProseUnder: listOf({ value: skipProse }),
64
+ skipFiles: listOf({ value: skip }),
65
+ });
66
+
67
+ for (const miss of missing) {
68
+ console.log(`${miss.file}:${miss.line} ${miss.path}`);
69
+ }
70
+
71
+ console.log(`wiki-source-links: ${checked} paths checked, ${missing.length} missing`);
72
+
73
+ return missing.length > 0 ? ExitCodes.FAILURE : ExitCodes.OK;
74
+ };
75
+
76
+ /** `wiki-anchors`: every in-page anchor the wiki links to exists in the built site. Needs a build. */
77
+ export const runAnchorsCommand = (opts: { args: string[]; root: string }): number => {
78
+ const content = valueOf({
79
+ args: opts.args,
80
+ flag: WikiFlags.CONTENT,
81
+ fallback: WikiDefaults.CONTENT_DIRECTORY,
82
+ });
83
+ const dist = valueOf({
84
+ args: opts.args,
85
+ flag: WikiFlags.DIST,
86
+ fallback: WikiDefaults.DIST_DIRECTORY,
87
+ });
88
+
89
+ if (content === undefined || dist === undefined) {
90
+ console.error('wiki-anchors: a flag has no value after it');
91
+
92
+ return ExitCodes.FAILURE;
93
+ }
94
+
95
+ if (!existsSync(dist)) {
96
+ console.log('wiki-anchors: no build found - run `make docs` first');
97
+
98
+ return ExitCodes.FAILURE;
99
+ }
100
+
101
+ const { checked, broken } = checkAnchors({ content, dist });
102
+
103
+ for (const entry of broken) {
104
+ console.log(`${entry.file}:${entry.line} ${entry.reason}: ${entry.target}`);
105
+ }
106
+
107
+ console.log(`wiki-anchors: ${checked} anchors checked, ${broken.length} broken`);
108
+
109
+ return broken.length > 0 ? ExitCodes.FAILURE : ExitCodes.OK;
110
+ };
@@ -0,0 +1,30 @@
1
+ import type { TConstValue } from '../common/index.ts';
2
+
3
+ /** Why a wiki link is broken: its page does not exist, or the page has no such fragment. */
4
+ export class AnchorProblems {
5
+ static readonly MISSING_PAGE = 'missing page';
6
+ static readonly DEAD_ANCHOR = 'dead anchor';
7
+ static readonly SCHEME_SET = new Set<string>([this.MISSING_PAGE, this.DEAD_ANCHOR]);
8
+ static isValid(value: string): boolean {
9
+ return this.SCHEME_SET.has(value);
10
+ }
11
+ }
12
+
13
+ export type TAnchorProblem = TConstValue<typeof AnchorProblems>;
14
+
15
+ /** The folders and flags of the two wiki gates; a project overrides each with a flag. */
16
+ export class WikiDefaults {
17
+ static readonly CONTENT_DIRECTORY = 'docs/wiki/content';
18
+ static readonly DIST_DIRECTORY = 'docs/wiki/site/.vitepress/dist';
19
+ static readonly KNOWLEDGE_DIRECTORY = '.agents/knowledge';
20
+ static readonly CHANGELOG_DIRECTORY = 'docs/wiki/content/changelogs';
21
+ }
22
+
23
+ export class WikiFlags {
24
+ static readonly REPO = '--repo';
25
+ static readonly DIRS = '--dirs';
26
+ static readonly SKIP_PROSE = '--skip-prose';
27
+ static readonly SKIP = '--skip';
28
+ static readonly CONTENT = '--content';
29
+ static readonly DIST = '--dist';
30
+ }
@@ -0,0 +1,4 @@
1
+ export * from './anchors.ts';
2
+ export * from './command.ts';
3
+ export * from './constants.ts';
4
+ export * from './source-links.ts';
@@ -0,0 +1,186 @@
1
+ import { existsSync, readdirSync, readFileSync } from 'node:fs';
2
+ import { join, relative, resolve } from 'node:path';
3
+ import { WikiDefaults } from './constants.ts';
4
+
5
+ /**
6
+ * Every source path the wiki and the knowledge bundle name must be tracked by git. Three kinds of
7
+ * reference are read from each `.md` file: a `<repo>/blob/main/<path>` or `tree/main/<path>` GitHub link
8
+ * (a link into another repository is never checked), a backticked path under a source root (checked
9
+ * outside `skipProseUnder`, where a changelog may name history), and a knowledge concept's `resource:`
10
+ * value (checked only under `.agents/knowledge`). `git ls-files` is the truth, not the disk: a
11
+ * gitignored artifact is not on GitHub.
12
+ */
13
+ const SOURCE_ROOTS = ['packages/', 'examples/', 'scripts/', 'docs/', '.agents/'];
14
+ const SOURCE_EXTENSIONS = ['ts', 'tsx', 'md', 'json', 'mjs', 'js', 'yaml', 'yml'];
15
+ const RESOURCE_LINE_PATTERN = /^resource:\s*(.+)$/;
16
+ const LINE_SUFFIX_PATTERN = /(:\d+|#L\d+)$/;
17
+
18
+ const escapeRegExp = (opts: { text: string }): string =>
19
+ opts.text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
20
+
21
+ // `{}` and `*` mark a template or a glob and `<>` a placeholder, never one real file.
22
+ const BACKTICK_PATTERN = new RegExp(
23
+ `\`((?:${SOURCE_ROOTS.map((root) => escapeRegExp({ text: root })).join('|')})[^\`{}*<>]+?\\.(?:${SOURCE_EXTENSIONS.join('|')})(?::\\d+|#L\\d+)?)\``,
24
+ 'g',
25
+ );
26
+
27
+ export interface IMissingSourceLink {
28
+ file: string;
29
+ line: number;
30
+ path: string;
31
+ }
32
+
33
+ interface ITrackedPaths {
34
+ files: Set<string>;
35
+ directories: Set<string>;
36
+ }
37
+
38
+ const loadTracked = (opts: { root: string }): ITrackedPaths => {
39
+ const result = Bun.spawnSync(['git', 'ls-files', '-z'], { cwd: opts.root, timeout: 30_000 });
40
+
41
+ if (result.exitCode !== 0) {
42
+ throw new Error(`git ls-files failed in ${opts.root}: ${result.stderr.toString().trim()}`);
43
+ }
44
+
45
+ const files = new Set(result.stdout.toString().split('\0').filter(Boolean));
46
+ const directories = new Set<string>();
47
+
48
+ for (const file of files) {
49
+ const segments = file.split('/');
50
+
51
+ for (let depth = 1; depth < segments.length; depth += 1) {
52
+ directories.add(segments.slice(0, depth).join('/'));
53
+ }
54
+ }
55
+
56
+ return { files, directories };
57
+ };
58
+
59
+ const isUnder = (opts: { path: string; directory: string }): boolean =>
60
+ opts.path === opts.directory || opts.path.startsWith(`${opts.directory}/`);
61
+
62
+ const walkMarkdown = (opts: { directory: string }): string[] => {
63
+ if (!existsSync(opts.directory)) {
64
+ return [];
65
+ }
66
+
67
+ return readdirSync(opts.directory, { withFileTypes: true }).flatMap((entry) => {
68
+ const full = join(opts.directory, entry.name);
69
+
70
+ if (entry.isDirectory()) {
71
+ return walkMarkdown({ directory: full });
72
+ }
73
+
74
+ return entry.isFile() && entry.name.endsWith('.md') ? [full] : [];
75
+ });
76
+ };
77
+
78
+ const extractPaths = (opts: { text: string; repo: string; skipProse: boolean }): string[] => {
79
+ const github = new RegExp(
80
+ `${escapeRegExp({ text: opts.repo })}/(?:blob|tree)/main/([^\\s)\\]"'\`<>]+)`,
81
+ 'g',
82
+ );
83
+ const found = [...opts.text.matchAll(github)].map((match) =>
84
+ (match[1] ?? '').replace(LINE_SUFFIX_PATTERN, ''),
85
+ );
86
+
87
+ if (opts.skipProse) {
88
+ return found;
89
+ }
90
+
91
+ const prose = [...opts.text.matchAll(BACKTICK_PATTERN)].map((match) =>
92
+ (match[1] ?? '').replace(LINE_SUFFIX_PATTERN, ''),
93
+ );
94
+
95
+ return [...found, ...prose];
96
+ };
97
+
98
+ /** The `resource:` line of a concept's frontmatter, or none when it has no tracked prefix. */
99
+ const extractResource = (opts: { lines: string[] }): { line: number; path: string } | undefined => {
100
+ const { lines } = opts;
101
+
102
+ if (lines[0] !== '---') {
103
+ return undefined;
104
+ }
105
+
106
+ const close = lines.indexOf('---', 1);
107
+
108
+ if (close === -1) {
109
+ return undefined;
110
+ }
111
+
112
+ for (let index = 1; index < close; index += 1) {
113
+ const match = RESOURCE_LINE_PATTERN.exec(lines[index] ?? '');
114
+ const value = match?.[1]
115
+ ?.trim()
116
+ .replace(/^["']|["']$/g, '')
117
+ .replace(/\/+$/, '');
118
+
119
+ if (
120
+ value !== undefined &&
121
+ value !== '' &&
122
+ SOURCE_ROOTS.some((root) => value.startsWith(root))
123
+ ) {
124
+ return { line: index + 1, path: value };
125
+ }
126
+ }
127
+
128
+ return undefined;
129
+ };
130
+
131
+ /**
132
+ * Walks the `.md` files under `directories` (paths relative to `root`) and reports every source path
133
+ * that git does not track. `skipFiles` are generated pages that are never held to the gate.
134
+ */
135
+ export const checkSourceLinks = (opts: {
136
+ root: string;
137
+ repo: string;
138
+ directories: string[];
139
+ skipProseUnder: string[];
140
+ skipFiles: string[];
141
+ }): { checked: number; missing: IMissingSourceLink[] } => {
142
+ const { root, repo, skipFiles, skipProseUnder } = opts;
143
+ const tracked = loadTracked({ root });
144
+ const exists = (path: string): boolean =>
145
+ tracked.files.has(path) || tracked.directories.has(path);
146
+ const missing: IMissingSourceLink[] = [];
147
+ let checked = 0;
148
+
149
+ for (const directory of opts.directories) {
150
+ for (const file of walkMarkdown({ directory: resolve(root, directory) })) {
151
+ const path = relative(root, file);
152
+
153
+ if (skipFiles.some((skip) => isUnder({ path, directory: skip }))) {
154
+ continue;
155
+ }
156
+
157
+ const skipProse = skipProseUnder.some((skip) => isUnder({ path, directory: skip }));
158
+ const lines = readFileSync(file, 'utf8').split('\n');
159
+ const resource = isUnder({ path, directory: WikiDefaults.KNOWLEDGE_DIRECTORY })
160
+ ? extractResource({ lines })
161
+ : undefined;
162
+
163
+ if (resource !== undefined) {
164
+ checked += 1;
165
+
166
+ if (!exists(resource.path)) {
167
+ missing.push({ file: path, line: resource.line, path: resource.path });
168
+ }
169
+ }
170
+
171
+ for (const [index, text] of lines.entries()) {
172
+ for (const found of extractPaths({ text, repo, skipProse })) {
173
+ checked += 1;
174
+
175
+ if (!exists(found)) {
176
+ missing.push({ file: path, line: index + 1, path: found });
177
+ }
178
+ }
179
+ }
180
+ }
181
+ }
182
+
183
+ missing.sort((left, right) => left.file.localeCompare(right.file) || left.line - right.line);
184
+
185
+ return { checked, missing };
186
+ };