@venizia/vulcan 0.4.10-4 → 0.4.10-5
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.
- package/base/checks/wiki-source-links.ts +17 -1
- package/package.json +3 -3
- package/src/visualize/assets.ts +2 -2
- package/src/wiki/command.ts +10 -3
- package/src/wiki/source-links.ts +57 -18
|
@@ -2,7 +2,23 @@
|
|
|
2
2
|
* Gate: every source path the wiki and the knowledge bundle name is tracked by git. Run from the
|
|
3
3
|
* repository root, through `make wiki-links-check WIKI_REPO=<owner/name>` or directly:
|
|
4
4
|
* bun node_modules/@venizia/vulcan/base/checks/wiki-source-links.ts --repo <owner/name>
|
|
5
|
+
* The folders it checks come from the `layout` of `.configs/vulcan.config.mts`; with no layout, the default list.
|
|
5
6
|
*/
|
|
7
|
+
import { ConfigLoader } from '../../src/config/index.ts';
|
|
6
8
|
import { runSourceLinksCommand } from '../../src/wiki/index.ts';
|
|
7
9
|
|
|
8
|
-
|
|
10
|
+
const root = process.cwd();
|
|
11
|
+
const loaded = await ConfigLoader.load({ root });
|
|
12
|
+
const note = ConfigLoader.unreadableNote({ loaded });
|
|
13
|
+
|
|
14
|
+
if (note !== undefined) {
|
|
15
|
+
console.error(`wiki-source-links: ${note}`);
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
process.exit(
|
|
19
|
+
runSourceLinksCommand({
|
|
20
|
+
args: process.argv.slice(2),
|
|
21
|
+
root,
|
|
22
|
+
layout: loaded.ok ? loaded.config.layout : undefined,
|
|
23
|
+
}),
|
|
24
|
+
);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan",
|
|
3
|
-
"version": "0.4.10-
|
|
3
|
+
"version": "0.4.10-5",
|
|
4
4
|
"description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
|
|
5
5
|
"homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
|
|
6
6
|
"bugs": {
|
|
@@ -45,8 +45,8 @@
|
|
|
45
45
|
},
|
|
46
46
|
"dependencies": {
|
|
47
47
|
"@clack/prompts": "1.8.1",
|
|
48
|
-
"@venizia/vulcan-atlas": "0.4.10-
|
|
49
|
-
"@venizia/vulcan-okf": "0.4.10-
|
|
48
|
+
"@venizia/vulcan-atlas": "0.4.10-5",
|
|
49
|
+
"@venizia/vulcan-okf": "0.4.10-5",
|
|
50
50
|
"zod": "^4.6.7"
|
|
51
51
|
},
|
|
52
52
|
"devDependencies": {
|
package/src/visualize/assets.ts
CHANGED
|
@@ -124,7 +124,7 @@ const BASE_CSS = [
|
|
|
124
124
|
// The hero slab: the state, the title, the verdict, and the flow when the spec has one.
|
|
125
125
|
`.hero{padding-block:56px}`,
|
|
126
126
|
`.hero .state{display:inline-flex;align-items:center;gap:10px;margin-bottom:28px;color:var(--c);font:650 14.5px/1 var(--font);text-transform:uppercase;letter-spacing:.07em}`,
|
|
127
|
-
`.hero h1{font-size:clamp(32px,5vw,72px);line-height:1.02;max-width:30ch;letter-spacing:-.045em;color:var(--ink)}`,
|
|
127
|
+
`.hero h1{font-size:clamp(32px,5vw,72px);line-height:1.02;max-width:30ch;letter-spacing:-.045em;color:var(--ink);overflow-wrap:anywhere}`,
|
|
128
128
|
`.hero .lede{margin-top:28px;font-size:clamp(18px,1.6vw,22px);max-width:46ch;color:var(--body)}`,
|
|
129
129
|
`.hero .cap{margin-top:14px;max-width:60ch;color:var(--muted)}`,
|
|
130
130
|
`.hero .meta{margin-top:22px;display:flex;flex-wrap:wrap;gap:4px 20px;font:500 13px/1.4 var(--code);color:var(--muted)}`,
|
|
@@ -327,7 +327,7 @@ const BASE_CSS = [
|
|
|
327
327
|
// A phone: panels stack, the bar keeps only the title, the state, present and the switch.
|
|
328
328
|
`@media (max-width:860px){.own,.facts,.q,.estep,.diff,.ev,.log li,.idea{grid-template-columns:minmax(0,1fr)}.q{gap:18px}.idea .centre{order:-1;grid-column:1;grid-row:auto}.idea .branch:nth-child(n){grid-column:1}.estep{gap:12px}.estep .no{font-size:56px}`,
|
|
329
329
|
`.part{padding-top:64px}.hero{padding-block:40px}.figure{margin-top:36px}.foot{margin-top:80px}.sh{margin-bottom:26px}.own .nx,.own .stop{padding:26px 22px}.opt{padding:26px 22px 28px}.q{padding:24px 22px 26px}.ba{padding:24px 22px}`,
|
|
330
|
-
`.top .links,.top .sep,.top .stamp{display:none}.top .wrap{gap:10px}.top .ttl{max-width:none;flex:1 1 auto}.top nav{margin-left:0}`,
|
|
330
|
+
`.top .links,.top .sep,.top .stamp{display:none}.top .wrap{gap:10px}.top .ttl{max-width:none;flex:1 1 auto}.top nav{margin-left:0;flex:none}`,
|
|
331
331
|
`.stack thead{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0)}.stack,.stack tbody,.stack tr,.stack td{display:block;width:100%}.stack tr{padding:14px 0;border-top:1px solid var(--line)}.stack tbody tr:first-child{border-top:0;padding-top:0}.stack td{border:0;padding:3px 0}`,
|
|
332
332
|
`.stack td[data-label]::before{content:attr(data-label);display:block;font:600 13px/1.3 var(--font);color:var(--muted);margin-bottom:2px}}`,
|
|
333
333
|
`@media (max-width:520px){body{font-size:16px}#present{display:none}.tile{padding:22px 20px}.steps{grid-template-columns:minmax(0,1fr)}.say{grid-template-columns:minmax(0,1fr)}}`,
|
package/src/wiki/command.ts
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
import { existsSync } from 'node:fs';
|
|
2
2
|
import { ExitCodes } from '../common/index.ts';
|
|
3
|
+
import type { ILayout } from '../common/layout-folder.ts';
|
|
3
4
|
import { AnchorCheck } from './anchors.ts';
|
|
4
5
|
import { WikiDefaults, WikiFlags } from './constants.ts';
|
|
5
|
-
import { SourceLinkCheck } from './source-links.ts';
|
|
6
|
+
import { SourceLinkCheck, SourceRoots } from './source-links.ts';
|
|
6
7
|
|
|
7
8
|
/** The value after `--flag`, or the fallback; `undefined` when the flag has no value after it. */
|
|
8
9
|
const valueOf = (opts: { args: string[]; flag: string; fallback?: string }): string | undefined => {
|
|
@@ -25,9 +26,14 @@ const listOf = (opts: { value: string }): string[] =>
|
|
|
25
26
|
|
|
26
27
|
/**
|
|
27
28
|
* `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
|
+
* repository root; the other flags replace the defaults (comma-separated lists). The source folders it checks come
|
|
30
|
+
* from the project's `layout` (`SourceRoots.of`); the caller reads the config and passes the layout.
|
|
29
31
|
*/
|
|
30
|
-
export const runSourceLinksCommand = (opts: {
|
|
32
|
+
export const runSourceLinksCommand = (opts: {
|
|
33
|
+
args: string[];
|
|
34
|
+
root: string;
|
|
35
|
+
layout?: ILayout;
|
|
36
|
+
}): number => {
|
|
31
37
|
const { args } = opts;
|
|
32
38
|
const repo = valueOf({ args, flag: WikiFlags.REPO });
|
|
33
39
|
const directories = valueOf({
|
|
@@ -62,6 +68,7 @@ export const runSourceLinksCommand = (opts: { args: string[]; root: string }): n
|
|
|
62
68
|
directories: listOf({ value: directories }),
|
|
63
69
|
skipProseUnder: listOf({ value: skipProse }),
|
|
64
70
|
skipFiles: listOf({ value: skip }),
|
|
71
|
+
roots: SourceRoots.of({ layout: opts.layout }),
|
|
65
72
|
});
|
|
66
73
|
|
|
67
74
|
for (const miss of missing) {
|
package/src/wiki/source-links.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { existsSync, readdirSync, readFileSync } from 'node:fs';
|
|
2
2
|
import { join, relative, resolve } from 'node:path';
|
|
3
3
|
import { GitFiles } from '../common/git-files.ts';
|
|
4
|
+
import { LayoutFolder, LayoutKeys } from '../common/layout-folder.ts';
|
|
5
|
+
import type { ILayout } from '../common/layout-folder.ts';
|
|
4
6
|
import { TextValue } from '../common/text.ts';
|
|
5
7
|
import { WikiDefaults } from './constants.ts';
|
|
6
8
|
|
|
@@ -12,16 +14,44 @@ import { WikiDefaults } from './constants.ts';
|
|
|
12
14
|
* value (checked only under `.agents/knowledge`). `git ls-files` is the truth, not the disk: a
|
|
13
15
|
* gitignored artifact is not on GitHub.
|
|
14
16
|
*/
|
|
15
|
-
const SOURCE_ROOTS = ['packages/', 'examples/', 'scripts/', 'docs/', '.agents/'];
|
|
16
17
|
const SOURCE_EXTENSIONS = ['ts', 'tsx', 'md', 'json', 'mjs', 'js', 'yaml', 'yml'];
|
|
17
18
|
const RESOURCE_LINE_PATTERN = /^resource:\s*(.+)$/;
|
|
18
19
|
const LINE_SUFFIX_PATTERN = /(:\d+|#L\d+)$/;
|
|
19
20
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
21
|
+
/**
|
|
22
|
+
* The folders whose paths the check holds to git: where a project's source lives. With a `layout` they are the layout's
|
|
23
|
+
* folders (backend, frontend, shared, other) and the folders every project has; without one, the list VULCAN's own
|
|
24
|
+
* repository uses.
|
|
25
|
+
*/
|
|
26
|
+
export class SourceRoots {
|
|
27
|
+
/** The folders every project has: its docs, its scripts and its agent files. */
|
|
28
|
+
static readonly FIXED = ['docs/', 'scripts/', '.agents/'];
|
|
29
|
+
/** What the check reads when the config has no layout. */
|
|
30
|
+
static readonly DEFAULT = ['packages/', 'examples/', ...SourceRoots.FIXED];
|
|
31
|
+
|
|
32
|
+
/** Each root ends with `/`. A layout folder the config would refuse is left out, and so is a repeat. */
|
|
33
|
+
static of(opts: { layout?: ILayout }): string[] {
|
|
34
|
+
const folders = LayoutKeys.ALL.flatMap((key) =>
|
|
35
|
+
LayoutFolder.valid({ value: opts.layout?.[key] }),
|
|
36
|
+
);
|
|
37
|
+
|
|
38
|
+
if (folders.length === 0) {
|
|
39
|
+
return SourceRoots.DEFAULT;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
return [...new Set([...folders.map((folder) => `${folder}/`), ...SourceRoots.FIXED])];
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** A backticked path under a root. `{}` and `*` mark a template or a glob and `<>` a placeholder, never one real file. */
|
|
46
|
+
static backtickPatternOf(opts: { roots: string[] }): RegExp {
|
|
47
|
+
const roots = opts.roots.map((root) => TextValue.escapeLiteral({ text: root })).join('|');
|
|
48
|
+
|
|
49
|
+
return new RegExp(
|
|
50
|
+
`\`((?:${roots})[^\`{}*<>]+?\\.(?:${SOURCE_EXTENSIONS.join('|')})(?::\\d+|#L\\d+)?)\``,
|
|
51
|
+
'g',
|
|
52
|
+
);
|
|
53
|
+
}
|
|
54
|
+
}
|
|
25
55
|
|
|
26
56
|
export interface IMissingSourceLink {
|
|
27
57
|
file: string;
|
|
@@ -74,7 +104,12 @@ const walkMarkdown = (opts: { directory: string }): string[] => {
|
|
|
74
104
|
});
|
|
75
105
|
};
|
|
76
106
|
|
|
77
|
-
const extractPaths = (opts: {
|
|
107
|
+
const extractPaths = (opts: {
|
|
108
|
+
text: string;
|
|
109
|
+
repo: string;
|
|
110
|
+
skipProse: boolean;
|
|
111
|
+
pattern: RegExp;
|
|
112
|
+
}): string[] => {
|
|
78
113
|
const github = new RegExp(
|
|
79
114
|
`${TextValue.escapeLiteral({ text: opts.repo })}/(?:blob|tree)/main/([^\\s)\\]"'\`<>]+)`,
|
|
80
115
|
'g',
|
|
@@ -87,7 +122,7 @@ const extractPaths = (opts: { text: string; repo: string; skipProse: boolean }):
|
|
|
87
122
|
return found;
|
|
88
123
|
}
|
|
89
124
|
|
|
90
|
-
const prose = [...opts.text.matchAll(
|
|
125
|
+
const prose = [...opts.text.matchAll(opts.pattern)].map((match) =>
|
|
91
126
|
(match[1] ?? '').replace(LINE_SUFFIX_PATTERN, ''),
|
|
92
127
|
);
|
|
93
128
|
|
|
@@ -95,8 +130,11 @@ const extractPaths = (opts: { text: string; repo: string; skipProse: boolean }):
|
|
|
95
130
|
};
|
|
96
131
|
|
|
97
132
|
/** The `resource:` line of a concept's frontmatter, or none when it has no tracked prefix. */
|
|
98
|
-
const extractResource = (opts: {
|
|
99
|
-
|
|
133
|
+
const extractResource = (opts: {
|
|
134
|
+
lines: string[];
|
|
135
|
+
roots: string[];
|
|
136
|
+
}): { line: number; path: string } | undefined => {
|
|
137
|
+
const { lines, roots } = opts;
|
|
100
138
|
|
|
101
139
|
if (lines[0] !== '---') {
|
|
102
140
|
return undefined;
|
|
@@ -115,11 +153,7 @@ const extractResource = (opts: { lines: string[] }): { line: number; path: strin
|
|
|
115
153
|
.replace(/^["']|["']$/g, '')
|
|
116
154
|
.replace(/\/+$/, '');
|
|
117
155
|
|
|
118
|
-
if (
|
|
119
|
-
value !== undefined &&
|
|
120
|
-
value !== '' &&
|
|
121
|
-
SOURCE_ROOTS.some((root) => value.startsWith(root))
|
|
122
|
-
) {
|
|
156
|
+
if (value !== undefined && value !== '' && roots.some((root) => value.startsWith(root))) {
|
|
123
157
|
return { line: index + 1, path: value };
|
|
124
158
|
}
|
|
125
159
|
}
|
|
@@ -130,7 +164,8 @@ const extractResource = (opts: { lines: string[] }): { line: number; path: strin
|
|
|
130
164
|
export class SourceLinkCheck {
|
|
131
165
|
/**
|
|
132
166
|
* 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.
|
|
167
|
+
* that git does not track. `skipFiles` are generated pages that are never held to the gate. `roots` are the
|
|
168
|
+
* folders a path must start with to be checked (`SourceRoots.of`); the default list when left out.
|
|
134
169
|
*/
|
|
135
170
|
static check(opts: {
|
|
136
171
|
root: string;
|
|
@@ -138,8 +173,12 @@ export class SourceLinkCheck {
|
|
|
138
173
|
directories: string[];
|
|
139
174
|
skipProseUnder: string[];
|
|
140
175
|
skipFiles: string[];
|
|
176
|
+
roots?: string[];
|
|
141
177
|
}): { checked: number; missing: IMissingSourceLink[] } {
|
|
142
178
|
const { root, repo, skipFiles, skipProseUnder } = opts;
|
|
179
|
+
const roots =
|
|
180
|
+
opts.roots === undefined || opts.roots.length === 0 ? SourceRoots.DEFAULT : opts.roots;
|
|
181
|
+
const pattern = SourceRoots.backtickPatternOf({ roots });
|
|
143
182
|
const tracked = loadTracked({ root });
|
|
144
183
|
const exists = (path: string): boolean =>
|
|
145
184
|
tracked.files.has(path) || tracked.directories.has(path);
|
|
@@ -157,7 +196,7 @@ export class SourceLinkCheck {
|
|
|
157
196
|
const skipProse = skipProseUnder.some((skip) => isUnder({ path, directory: skip }));
|
|
158
197
|
const lines = readFileSync(file, 'utf8').split('\n');
|
|
159
198
|
const resource = isUnder({ path, directory: WikiDefaults.KNOWLEDGE_DIRECTORY })
|
|
160
|
-
? extractResource({ lines })
|
|
199
|
+
? extractResource({ lines, roots })
|
|
161
200
|
: undefined;
|
|
162
201
|
|
|
163
202
|
if (resource !== undefined) {
|
|
@@ -169,7 +208,7 @@ export class SourceLinkCheck {
|
|
|
169
208
|
}
|
|
170
209
|
|
|
171
210
|
for (const [index, text] of lines.entries()) {
|
|
172
|
-
for (const found of extractPaths({ text, repo, skipProse })) {
|
|
211
|
+
for (const found of extractPaths({ text, repo, skipProse, pattern })) {
|
|
173
212
|
checked += 1;
|
|
174
213
|
|
|
175
214
|
if (!exists(found)) {
|