@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.
@@ -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
- process.exit(runSourceLinksCommand({ args: process.argv.slice(2), root: process.cwd() }));
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-4",
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-4",
49
- "@venizia/vulcan-okf": "0.4.10-4",
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": {
@@ -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)}}`,
@@ -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: { args: string[]; root: string }): number => {
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) {
@@ -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
- // `{}` and `*` mark a template or a glob and `<>` a placeholder, never one real file.
21
- const BACKTICK_PATTERN = new RegExp(
22
- `\`((?:${SOURCE_ROOTS.map((root) => TextValue.escapeLiteral({ text: root })).join('|')})[^\`{}*<>]+?\\.(?:${SOURCE_EXTENSIONS.join('|')})(?::\\d+|#L\\d+)?)\``,
23
- 'g',
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: { text: string; repo: string; skipProse: boolean }): string[] => {
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(BACKTICK_PATTERN)].map((match) =>
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: { lines: string[] }): { line: number; path: string } | undefined => {
99
- const { lines } = opts;
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)) {