@venizia/vulcan-okf 0.3.13 → 0.4.1

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan-okf",
3
- "version": "0.3.13",
3
+ "version": "0.4.1",
4
4
  "description": "VULCAN knowledge tooling: OKF v0.2 conformance check (plus --strict house rules), gen, coverage and the offline graph explorer for a project's .agents/knowledge bundle. Bun-only.",
5
5
  "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/okf",
6
6
  "bugs": {
@@ -47,7 +47,7 @@
47
47
  "devDependencies": {
48
48
  "@types/bun": "1.4.3",
49
49
  "@types/cytoscape-fcose": "2.2.5",
50
- "@venizia/dev-configs": "0.3.5",
50
+ "@venizia/dev-configs": "0.4.0",
51
51
  "eslint": "10.13.0",
52
52
  "oxlint": "1.89.0",
53
53
  "oxlint-tsgolint": "7.0.2004",
@@ -37,7 +37,9 @@ const tagPatternOf = (opts: { project: IOkfProject; dir: string; version: string
37
37
  const tagsOf = (opts: { root: string }): string[] => {
38
38
  const result = spawnSync('git', ['tag', '--list'], { cwd: opts.root, encoding: 'utf8' });
39
39
 
40
- return result.status === 0 ? (result.stdout ?? '').split('\n').filter(tag => tag.length > 0) : [];
40
+ return result.status === 0
41
+ ? (result.stdout ?? '').split('\n').filter((tag) => tag.length > 0)
42
+ : [];
41
43
  };
42
44
 
43
45
  /**
@@ -53,12 +55,12 @@ export const collectChangelogProblems = (): string[] => {
53
55
  return [];
54
56
  }
55
57
 
56
- const names = new Map(project.packages.map(entry => [entry.name, entry.dir]));
58
+ const names = new Map(project.packages.map((entry) => [entry.name, entry.dir]));
57
59
  const problems: string[] = [];
58
60
  let tags: string[] | undefined;
59
61
 
60
62
  for (const file of readdirSync(directory)
61
- .filter(name => DATED_ENTRY.test(name))
63
+ .filter((name) => DATED_ENTRY.test(name))
62
64
  .sort()) {
63
65
  const path = relative(project.root, join(directory, file));
64
66
  let frontmatter: TRecord;
@@ -110,7 +112,7 @@ export const collectChangelogProblems = (): string[] => {
110
112
 
111
113
  const pattern = tagPatternOf({ project, dir, version: override[2] });
112
114
 
113
- if (!tags.some(tag => pattern.test(tag))) {
115
+ if (!tags.some((tag) => pattern.test(tag))) {
114
116
  const expected = project.tagPattern
115
117
  .replace(/<(?:dir|package)>/g, dir)
116
118
  .replace(/<version>/g, override[2])
@@ -10,8 +10,8 @@ import { repoRelative, walkFiles } from '../source/index.ts';
10
10
 
11
11
  export const readBundleFiles = (): IBundleFile[] =>
12
12
  walkFiles({ dir: readOkfProject().bundle })
13
- .filter(file => file.endsWith('.md'))
14
- .map(file => ({
13
+ .filter((file) => file.endsWith('.md'))
14
+ .map((file) => ({
15
15
  path: relative(readOkfProject().bundle, file),
16
16
  text: readFileSync(file, 'utf8'),
17
17
  }));
@@ -24,10 +24,10 @@ export const formatIssue = (opts: { issue: IConformanceIssue }): string =>
24
24
  export const check = async (opts: { strict: boolean }): Promise<void> => {
25
25
  const files = readBundleFiles();
26
26
  const issues = checkBundle({ files });
27
- const warnings = issues.filter(issue => issue.severity === IssueSeverities.WARNING);
27
+ const warnings = issues.filter((issue) => issue.severity === IssueSeverities.WARNING);
28
28
  const problems = issues
29
- .filter(issue => issue.severity === IssueSeverities.ERROR)
30
- .map(issue => formatIssue({ issue }));
29
+ .filter((issue) => issue.severity === IssueSeverities.ERROR)
30
+ .map((issue) => formatIssue({ issue }));
31
31
 
32
32
  if (opts.strict) {
33
33
  problems.push(...collectHouseProblems({ files, ...(await loadGeneration()) }));
@@ -36,20 +36,20 @@ export const check = async (opts: { strict: boolean }): Promise<void> => {
36
36
  if (warnings.length) {
37
37
  console.error(
38
38
  `check: ${warnings.length} warning(s):\n` +
39
- warnings.map(issue => ' - ' + formatIssue({ issue })).join('\n'),
39
+ warnings.map((issue) => ' - ' + formatIssue({ issue })).join('\n'),
40
40
  );
41
41
  }
42
42
 
43
43
  if (problems.length) {
44
44
  console.error(
45
45
  `check: ${problems.length} problem(s):\n` +
46
- problems.map(problem => ' - ' + problem).join('\n'),
46
+ problems.map((problem) => ' - ' + problem).join('\n'),
47
47
  );
48
48
  process.exit(1);
49
49
  }
50
50
 
51
51
  const conceptCount = files.filter(
52
- file => !RESERVED_FILES.has(file.path.split('/').pop() ?? ''),
52
+ (file) => !RESERVED_FILES.has(file.path.split('/').pop() ?? ''),
53
53
  ).length;
54
54
  const scope = opts.strict
55
55
  ? `OKF v${OkfVersions.LATEST} + house rules`
@@ -41,7 +41,7 @@ export const sameContent = (opts: { left: string; right: string }): boolean => {
41
41
  const normalize = (value: string) =>
42
42
  value
43
43
  .split('\n')
44
- .map(line => line.replace(/\s+$/, ''))
44
+ .map((line) => line.replace(/\s+$/, ''))
45
45
  .join('\n')
46
46
  .trim();
47
47
 
@@ -66,7 +66,7 @@ export const collectHouseProblems = (opts: {
66
66
  );
67
67
  }
68
68
 
69
- const ids = new Set(concepts.map(concept => concept.id));
69
+ const ids = new Set(concepts.map((concept) => concept.id));
70
70
 
71
71
  for (const concept of concepts) {
72
72
  for (const target of concept.links) {
@@ -91,7 +91,7 @@ export const collectHouseProblems = (opts: {
91
91
  }
92
92
  }
93
93
 
94
- const filePaths = new Set(opts.files.map(file => `/${file.path.replace(/\.md$/, '')}`));
94
+ const filePaths = new Set(opts.files.map((file) => `/${file.path.replace(/\.md$/, '')}`));
95
95
  const resources = resourceKeysOf({ concepts });
96
96
 
97
97
  const { axes, problems: axisProblems } = collectCoverageAxes();
@@ -151,7 +151,7 @@ export const collectHouseProblems = (opts: {
151
151
  problems.push(...collectChangelogProblems());
152
152
 
153
153
  // A long agent-read file opens with its contents - an agent may read its first lines only.
154
- problems.push(...collectContentsProblems({ skip: new Set(pages.map(page => page.path)) }));
154
+ problems.push(...collectContentsProblems({ skip: new Set(pages.map((page) => page.path)) }));
155
155
 
156
156
  return problems;
157
157
  };
@@ -19,8 +19,8 @@ export const resourceKeysOf = (opts: {
19
19
  }): Set<string> =>
20
20
  new Set(
21
21
  opts.concepts
22
- .filter(concept => !concept.reserved && concept.resource !== '')
23
- .map(concept => resourceKeyOf({ value: concept.resource })),
22
+ .filter((concept) => !concept.reserved && concept.resource !== '')
23
+ .map((concept) => resourceKeyOf({ value: concept.resource })),
24
24
  );
25
25
 
26
26
  /**
@@ -53,19 +53,19 @@ export const collectCoverageAxes = (): {
53
53
  for (const axis of project.coverage) {
54
54
  const matched = [
55
55
  ...new Bun.Glob(axis.path).scanSync({ cwd: project.root, onlyFiles: false, dot: false }),
56
- ].filter(path => statSync(join(project.root, path)).isDirectory());
56
+ ].filter((path) => statSync(join(project.root, path)).isDirectory());
57
57
 
58
58
  if (matched.length === 0) {
59
59
  problems.push(`coverage: axis '${axis.name}' (${axis.path}) matches no directory`);
60
60
  continue;
61
61
  }
62
62
 
63
- const excluded = axis.exclude.map(pattern => new Bun.Glob(pattern));
63
+ const excluded = axis.exclude.map((pattern) => new Bun.Glob(pattern));
64
64
  const kept = matched.filter(
65
- path =>
65
+ (path) =>
66
66
  !project.denylist.has(basename(path)) &&
67
67
  !axis.denylist.includes(basename(path)) &&
68
- !excluded.some(glob => glob.match(path)),
68
+ !excluded.some((glob) => glob.match(path)),
69
69
  );
70
70
 
71
71
  if (kept.length === 0) {
@@ -75,12 +75,12 @@ export const collectCoverageAxes = (): {
75
75
  continue;
76
76
  }
77
77
 
78
- const items = [...new Set(kept.map(path => basename(path)))].sort();
78
+ const items = [...new Set(kept.map((path) => basename(path)))].sort();
79
79
 
80
80
  axes.push({
81
81
  name: axis.name,
82
82
  items,
83
- paths: Object.fromEntries(kept.map(path => [basename(path), path])),
83
+ paths: Object.fromEntries(kept.map((path) => [basename(path), path])),
84
84
  });
85
85
  }
86
86
 
@@ -14,8 +14,8 @@ export const pad = (opts: { value: string; width: number }): string => {
14
14
  };
15
15
 
16
16
  export const coverage = async (): Promise<void> => {
17
- const concepts = loadConceptsOrExit().filter(concept => !concept.reserved);
18
- const ids = new Set(concepts.map(concept => concept.id));
17
+ const concepts = loadConceptsOrExit().filter((concept) => !concept.reserved);
18
+ const ids = new Set(concepts.map((concept) => concept.id));
19
19
 
20
20
  const hasId = (opts: { id: string }): boolean => ids.has(opts.id);
21
21
  const resources = resourceKeysOf({ concepts });
@@ -30,7 +30,7 @@ export const coverage = async (): Promise<void> => {
30
30
  }): void => {
31
31
  const { name, items, covered } = opts;
32
32
 
33
- const missing = items.filter(item => !covered(item));
33
+ const missing = items.filter((item) => !covered(item));
34
34
  const value = items.length - missing.length;
35
35
 
36
36
  structCovered += value;
@@ -57,7 +57,7 @@ export const coverage = async (): Promise<void> => {
57
57
  struct({
58
58
  name: axis.name,
59
59
  items: axis.items,
60
- covered: item => isItemCovered({ axis, item, ids, resources }),
60
+ covered: (item) => isItemCovered({ axis, item, ids, resources }),
61
61
  });
62
62
  }
63
63
 
@@ -79,13 +79,13 @@ export const coverage = async (): Promise<void> => {
79
79
  const facts = renderer.collect({ context });
80
80
  const row = renderer.coverage({ facts });
81
81
  const rendered = renderer.render?.({ context, facts });
82
- const paths = rendered === undefined ? [] : [rendered].flat().map(file => file.path);
82
+ const paths = rendered === undefined ? [] : [rendered].flat().map((file) => file.path);
83
83
 
84
84
  ref({
85
85
  name: row.name,
86
86
  count: row.count,
87
87
  generated:
88
- paths.length > 0 && paths.every(path => hasId({ id: '/' + path.replace(/\.md$/, '') })),
88
+ paths.length > 0 && paths.every((path) => hasId({ id: '/' + path.replace(/\.md$/, '') })),
89
89
  });
90
90
  }
91
91
 
@@ -19,7 +19,7 @@ const currentOf = (opts: { path: string }): string | undefined =>
19
19
  */
20
20
  export const gen = async (): Promise<void> => {
21
21
  const { renderers, regions } = await loadGeneration();
22
- const regionWrites = regions.flatMap(region => {
22
+ const regionWrites = regions.flatMap((region) => {
23
23
  const current = currentOf({ path: region.file });
24
24
 
25
25
  if (current === undefined) {
@@ -40,7 +40,7 @@ export const gen = async (): Promise<void> => {
40
40
  return text === current ? [] : [{ region, text }];
41
41
  });
42
42
  const rendered = renderPages({ renderers });
43
- const pages = rendered.filter(page => currentOf({ path: page.path }) !== page.content);
43
+ const pages = rendered.filter((page) => currentOf({ path: page.path }) !== page.content);
44
44
 
45
45
  for (const { region, text } of regionWrites) {
46
46
  writeFileSync(region.file, text);
@@ -54,7 +54,7 @@ export const gen = async (): Promise<void> => {
54
54
  }
55
55
 
56
56
  // Every project's long agent-read files carry a contents list, whatever it renders.
57
- const contents = writeContents({ skip: new Set(rendered.map(page => page.path)) });
57
+ const contents = writeContents({ skip: new Set(rendered.map((page) => page.path)) });
58
58
 
59
59
  for (const file of contents) {
60
60
  console.log(`gen: wrote the contents list of ${file}`);
@@ -18,14 +18,14 @@ const LOG_FILE = 'log.md';
18
18
  const contentsTargets = (opts: { skip: Set<string> }): string[] => {
19
19
  const project = readOkfProject();
20
20
  const bundle = walkFiles({ dir: project.bundle }).filter(
21
- file =>
21
+ (file) =>
22
22
  file.endsWith('.md') &&
23
23
  !opts.skip.has(file) &&
24
24
  file !== join(project.bundle, LOG_FILE) &&
25
25
  !isGenerated({ text: readFileSync(file, 'utf8') }),
26
26
  );
27
27
 
28
- return [...bundle.sort(), ...project.contentsFiles.filter(file => existsSync(file))];
28
+ return [...bundle.sort(), ...project.contentsFiles.filter((file) => existsSync(file))];
29
29
  };
30
30
 
31
31
  const shown = (opts: { file: string }): string => relative(readOkfProject().root, opts.file);
@@ -33,18 +33,19 @@ const shown = (opts: { file: string }): string => relative(readOkfProject().root
33
33
  /** Every agent-read file whose contents list is missing or stale - `check --strict` fails on them. */
34
34
  export const collectContentsProblems = (opts: { skip: Set<string> }): string[] =>
35
35
  contentsTargets(opts)
36
- .filter(file => {
36
+ .filter((file) => {
37
37
  const text = readFileSync(file, 'utf8');
38
38
 
39
39
  return withContents({ text }) !== text;
40
40
  })
41
41
  .map(
42
- file => `contents: ${shown({ file })} has no fresh contents list - run \`vulcan x okf gen\``,
42
+ (file) =>
43
+ `contents: ${shown({ file })} has no fresh contents list - run \`vulcan x okf gen\``,
43
44
  );
44
45
 
45
46
  /** Writes every contents list `gen` owes; the files written, from the root. */
46
47
  export const writeContents = (opts: { skip: Set<string> }): string[] =>
47
- contentsTargets(opts).flatMap(file => {
48
+ contentsTargets(opts).flatMap((file) => {
48
49
  const text = readFileSync(file, 'utf8');
49
50
  const next = withContents({ text });
50
51
 
@@ -195,7 +195,7 @@ export const withContents = (opts: { text: string }): string => {
195
195
  }
196
196
 
197
197
  const { start, end } = markers({ id: CONTENTS_ID });
198
- const list = headings.map(heading => `- [${heading.text}](#${heading.anchor})`).join('\n');
198
+ const list = headings.map((heading) => `- [${heading.text}](#${heading.anchor})`).join('\n');
199
199
  const block = `${start}\n**Contents**\n\n${list}\n${end}\n\n`;
200
200
  const at = insertionPointOf({ text: bare });
201
201
 
@@ -60,8 +60,8 @@ const namesPerDir = (opts: {
60
60
  const pattern = new RegExp(opts.pattern.source, flags);
61
61
 
62
62
  return opts.dirs
63
- .filter(dir => existsSync(join(opts.root, dir)))
64
- .map(dir => {
63
+ .filter((dir) => existsSync(join(opts.root, dir)))
64
+ .map((dir) => {
65
65
  const names = new Set<string>();
66
66
 
67
67
  for (const file of sourceFiles({ dir: join(opts.root, dir) })) {
@@ -78,7 +78,7 @@ const namesPerDir = (opts: {
78
78
 
79
79
  const page: IRenderPage = {
80
80
  // No `generated.at` - a timestamp would make every regeneration look like a change.
81
- header: opts =>
81
+ header: (opts) =>
82
82
  [
83
83
  '---',
84
84
  'type: Reference',
@@ -92,7 +92,7 @@ const page: IRenderPage = {
92
92
  '',
93
93
  '',
94
94
  ].join('\n'),
95
- note: opts =>
95
+ note: (opts) =>
96
96
  `> Generated from source - do not edit; run \`make okf-gen\`.${opts.seeAlso === '' ? '' : ` ${opts.seeAlso}`}\n\n`,
97
97
  };
98
98
 
@@ -111,7 +111,7 @@ export const createRenderContext = (opts: { options: Record<string, unknown> }):
111
111
  root,
112
112
  dirs,
113
113
  pattern: new RegExp(`export\\s+(?:abstract\\s+)?class\\s+(\\w+${suffix})\\b`),
114
- }).map(entry => ({ dir: entry.dir, classes: entry.names })),
114
+ }).map((entry) => ({ dir: entry.dir, classes: entry.names })),
115
115
  exportedNames: ({ dirs, pattern }) => namesPerDir({ root, dirs, pattern }),
116
116
  },
117
117
  page,
@@ -43,7 +43,7 @@ export const renderPages = (opts: { renderers: ILoadedRenderer[] }): IRenderedPa
43
43
  throw new Error(`okf: renderer '${renderer.id}' writes ${file.path}, outside the bundle`);
44
44
  }
45
45
 
46
- const owner = pages.find(page => page.path === path);
46
+ const owner = pages.find((page) => page.path === path);
47
47
 
48
48
  if (owner !== undefined) {
49
49
  throw new Error(
@@ -105,21 +105,21 @@ export const loadGeneration = async (): Promise<{
105
105
  const renderers: ILoadedRenderer[] = [];
106
106
 
107
107
  for (const entry of project.renderers) {
108
- if (renderers.some(loaded => loaded.renderer.id === entry.id)) {
108
+ if (renderers.some((loaded) => loaded.renderer.id === entry.id)) {
109
109
  throw new Error(`okf: two renderers with id '${entry.id}'`);
110
110
  }
111
111
 
112
112
  renderers.push(await loadRenderer({ root: project.root, entry }));
113
113
  }
114
114
 
115
- const regions = project.regions.map(region => {
115
+ const regions = project.regions.map((region) => {
116
116
  if (region.id === CONTENTS_ID) {
117
117
  throw new Error(
118
118
  `okf: region id '${CONTENTS_ID}' is reserved for the contents list okf writes - rename the region`,
119
119
  );
120
120
  }
121
121
 
122
- const loaded = renderers.find(candidate => candidate.renderer.id === region.renderer) ?? {
122
+ const loaded = renderers.find((candidate) => candidate.renderer.id === region.renderer) ?? {
123
123
  renderer: builtInRenderer({ id: region.renderer }),
124
124
  context: createRenderContext({ options: {} }),
125
125
  };
@@ -49,7 +49,7 @@ const sourceMapRenderer = defineRenderer({
49
49
  const total = facts.reduce((sum, entry) => sum + entry.total, 0);
50
50
 
51
51
  const body = facts
52
- .map(entry => {
52
+ .map((entry) => {
53
53
  const heading = `## ${entry.pkg} (${entry.total} source files)`;
54
54
 
55
55
  // A package may keep a flat src/ (no subsystem dirs) - render prose, not an empty table.
@@ -57,7 +57,7 @@ const sourceMapRenderer = defineRenderer({
57
57
  return [heading, '', '_Flat `src/` - no subsystem directories._'].join('\n');
58
58
  }
59
59
 
60
- const rows = entry.subsystems.map(sub => `| \`${sub.name}/\` | ${sub.files} |`);
60
+ const rows = entry.subsystems.map((sub) => `| \`${sub.name}/\` | ${sub.files} |`);
61
61
 
62
62
  return [heading, '', '| Subsystem | Files |', '|---|---|', ...rows].join('\n');
63
63
  })
@@ -96,7 +96,7 @@ const makefileTargetsRenderer = defineRenderer({
96
96
  id: 'makefile-targets',
97
97
  collect: () => collectMakefileTargets(),
98
98
  render: ({ context, facts }) => {
99
- const rows = facts.map(target => {
99
+ const rows = facts.map((target) => {
100
100
  return `| \`make ${target.name}\` | ${target.deps ? `\`${target.deps}\`` : '-'} | ${target.description || '-'} |`;
101
101
  });
102
102
 
@@ -146,8 +146,8 @@ const bindingKeysRenderer = defineRenderer({
146
146
  const total = facts.reduce((sum, entry) => sum + entry.keys.length, 0);
147
147
 
148
148
  const body = facts
149
- .map(entry => {
150
- const rows = entry.keys.map(key => `| \`${key.key}\` | \`${key.value}\` |`);
149
+ .map((entry) => {
150
+ const rows = entry.keys.map((key) => `| \`${key.key}\` | \`${key.value}\` |`);
151
151
 
152
152
  return [`## ${entry.name}`, '', '| Constant | Key |', '|---|---|', ...rows].join('\n');
153
153
  })
@@ -190,7 +190,7 @@ const packagesTableRenderer = defineRenderer({
190
190
  id: 'packages-table',
191
191
  collect: () => collectPackageManifests(),
192
192
  region: ({ facts }) => {
193
- const rows = facts.map(entry => {
193
+ const rows = facts.map((entry) => {
194
194
  return `| [\`${entry.dir}\`](/packages/${entry.dir}.md) | \`${entry.name}\` | ${entry.description || '-'} |`;
195
195
  });
196
196
 
package/src/lib.ts CHANGED
@@ -61,9 +61,9 @@ const walkMarkdown = (opts: { dir: string }): string[] => {
61
61
  */
62
62
  export const stripCode = (opts: { text: string }): string => {
63
63
  return opts.text
64
- .replace(/```[\s\S]*?```/g, block => block.replace(/[^\n]/g, ' '))
65
- .replace(/~~~[\s\S]*?~~~/g, block => block.replace(/[^\n]/g, ' '))
66
- .replace(/`[^`\n]*`/g, span => ' '.repeat(span.length));
64
+ .replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, ' '))
65
+ .replace(/~~~[\s\S]*?~~~/g, (block) => block.replace(/[^\n]/g, ' '))
66
+ .replace(/`[^`\n]*`/g, (span) => ' '.repeat(span.length));
67
67
  };
68
68
 
69
69
  const MARKDOWN_LINK = /\]\(([^)\s]+)\)/g;
@@ -87,7 +87,7 @@ const resolveLinkTarget = (opts: { target: string; fromId: string }): string | u
87
87
  export const extractLinks = (opts: { text: string; id: string }): string[] => {
88
88
  const prose = stripCode({ text: opts.text });
89
89
  const targets = [...prose.matchAll(MARKDOWN_LINK)]
90
- .map(match => resolveLinkTarget({ target: match[1], fromId: opts.id }))
90
+ .map((match) => resolveLinkTarget({ target: match[1], fromId: opts.id }))
91
91
  .filter((target): target is string => target !== undefined);
92
92
 
93
93
  return [...new Set(targets)];
@@ -124,13 +124,13 @@ const asTags = (opts: { value: unknown }): string[] => {
124
124
  const { value } = opts;
125
125
 
126
126
  if (Array.isArray(value)) {
127
- return value.map(tag => String(tag).trim()).filter(Boolean);
127
+ return value.map((tag) => String(tag).trim()).filter(Boolean);
128
128
  }
129
129
 
130
130
  if (typeof value === 'string') {
131
131
  return value
132
132
  .split(',')
133
- .map(tag => tag.trim())
133
+ .map((tag) => tag.trim())
134
134
  .filter(Boolean);
135
135
  }
136
136
 
@@ -140,7 +140,7 @@ const asTags = (opts: { value: unknown }): string[] => {
140
140
  export const loadConcepts = (): Concept[] => {
141
141
  const { bundle } = readOkfProject();
142
142
 
143
- return walkMarkdown({ dir: bundle }).map(file => {
143
+ return walkMarkdown({ dir: bundle }).map((file) => {
144
144
  const raw = readFileSync(file, 'utf8');
145
145
  const base = file.split('/').pop() ?? '';
146
146
  const reserved = RESERVED_FILES.has(base);
@@ -40,7 +40,7 @@ const brandOf = (opts: { root: string }): string => {
40
40
  };
41
41
 
42
42
  const packagesOf = (opts: { value: unknown; root: string }): IOkfPackage[] =>
43
- arrayOf(opts).flatMap(item => {
43
+ arrayOf(opts).flatMap((item) => {
44
44
  const entry = recordOf({ value: item });
45
45
  const dir = entry.dir;
46
46
 
@@ -57,7 +57,7 @@ const packagesOf = (opts: { value: unknown; root: string }): IOkfPackage[] =>
57
57
  });
58
58
 
59
59
  const renderersOf = (opts: { value: unknown }): IOkfRendererEntry[] =>
60
- arrayOf(opts).flatMap(item => {
60
+ arrayOf(opts).flatMap((item) => {
61
61
  if (typeof item === 'string') {
62
62
  return [{ id: item, options: {} }];
63
63
  }
@@ -81,7 +81,7 @@ const renderersOf = (opts: { value: unknown }): IOkfRendererEntry[] =>
81
81
  });
82
82
 
83
83
  const regionsOf = (opts: { value: unknown; bundle: string }): IOkfRegionEntry[] =>
84
- arrayOf(opts).flatMap(item => {
84
+ arrayOf(opts).flatMap((item) => {
85
85
  const entry = recordOf({ value: item });
86
86
  const { id, file, renderer } = entry;
87
87
 
@@ -93,7 +93,7 @@ const regionsOf = (opts: { value: unknown; bundle: string }): IOkfRegionEntry[]
93
93
  const coverageOf = (opts: {
94
94
  value: unknown;
95
95
  }): { name: string; path: string; exclude: string[]; denylist: string[] }[] =>
96
- arrayOf(opts).flatMap(item => {
96
+ arrayOf(opts).flatMap((item) => {
97
97
  const entry = recordOf({ value: item });
98
98
 
99
99
  return typeof entry.name === 'string' && typeof entry.path === 'string'
@@ -113,11 +113,11 @@ const GLOB_CHARACTERS = /[*?[\]{}]/;
113
113
  /** `okf.contents.files`: literal paths and globs from the root, as absolute paths, each file once, in the order given. */
114
114
  const contentsFilesOf = (opts: { patterns: string[]; root: string }): string[] => [
115
115
  ...new Set(
116
- opts.patterns.flatMap(pattern =>
116
+ opts.patterns.flatMap((pattern) =>
117
117
  GLOB_CHARACTERS.test(pattern)
118
118
  ? [...new Bun.Glob(pattern).scanSync({ cwd: opts.root, onlyFiles: true })]
119
119
  .sort()
120
- .map(file => resolve(opts.root, file))
120
+ .map((file) => resolve(opts.root, file))
121
121
  : [resolve(opts.root, pattern)],
122
122
  ),
123
123
  ),
@@ -196,7 +196,7 @@ export const readOkfProject = (): IOkfProject => {
196
196
  denylist: new Set(stringsOf({ value: okf.denylist })),
197
197
  viz: {
198
198
  outputs: (outputs.length > 0 ? outputs : [OkfProjectConstants.DEFAULT_VIZ_OUTPUT]).map(
199
- output => resolve(root, output),
199
+ (output) => resolve(root, output),
200
200
  ),
201
201
  brand: stringOf({ value: viz.brand, fallback: brandOf({ root }) }),
202
202
  ...(copy === undefined ? {} : { copy }),
@@ -21,7 +21,7 @@ export const collectBindingKeys = (opts: { file: string }): BindingClass[] => {
21
21
  // value class that cannot span lines stops a non-string member from swallowing the next constant.
22
22
  const keys = [
23
23
  ...cls[2].matchAll(/^\s*static\s+readonly\s+(\w+)\s*[:=][^'"`\n]*['"`]([^'"`\n]+)['"`]/gm),
24
- ].map(match => ({ key: match[1], value: match[2] }));
24
+ ].map((match) => ({ key: match[1], value: match[2] }));
25
25
 
26
26
  if (keys.length) {
27
27
  out.push({ name: cls[1], keys });
@@ -65,7 +65,7 @@ export const collectMakefileTargets = (): MakeTarget[] => {
65
65
  const reason = (made.stderr ?? '')
66
66
  .toString()
67
67
  .split('\n')
68
- .find(line => line.includes('*** ') && !line.includes("No rule to make target ':'"));
68
+ .find((line) => line.includes('*** ') && !line.includes("No rule to make target ':'"));
69
69
 
70
70
  if (reason !== undefined) {
71
71
  throw new Error(`okf: make failed: ${reason}`);
@@ -74,7 +74,7 @@ export const collectMakefileTargets = (): MakeTarget[] => {
74
74
  const db = (made.stdout ?? '').toString();
75
75
  const lines = db.split('\n');
76
76
 
77
- const packagesLine = lines.find(line => line.startsWith('PACKAGES := ')) ?? '';
77
+ const packagesLine = lines.find((line) => line.startsWith('PACKAGES := ')) ?? '';
78
78
  const packages = packagesLine.slice('PACKAGES := '.length).split(' ').filter(Boolean);
79
79
  const pkgPattern = `(${[...packages, 'core'].join('|')})`;
80
80
 
@@ -94,7 +94,7 @@ export const collectMakefileTargets = (): MakeTarget[] => {
94
94
  }
95
95
 
96
96
  const commented = new Map<string, string>();
97
- const makefiles = (lines.find(line => line.startsWith('MAKEFILE_LIST := ')) ?? '')
97
+ const makefiles = (lines.find((line) => line.startsWith('MAKEFILE_LIST := ')) ?? '')
98
98
  .slice('MAKEFILE_LIST := '.length)
99
99
  .split(' ')
100
100
  .filter(Boolean);
@@ -125,7 +125,7 @@ export const collectMakefileTargets = (): MakeTarget[] => {
125
125
  }
126
126
 
127
127
  const description =
128
- help.find(entry => entry.pattern.test(match[1]))?.description ??
128
+ help.find((entry) => entry.pattern.test(match[1]))?.description ??
129
129
  commented.get(match[1]) ??
130
130
  '';
131
131
 
@@ -146,16 +146,16 @@ export const collectSourceMap = (): SourceMapEntry[] => {
146
146
  }
147
147
 
148
148
  const subsystems = listDirs({ dir: src })
149
- .filter(name => name !== '__tests__')
150
- .map(name => ({ name, files: sourceFiles({ dir: join(src, name) }).length }))
151
- .filter(entry => entry.files > 0)
149
+ .filter((name) => name !== '__tests__')
150
+ .map((name) => ({ name, files: sourceFiles({ dir: join(src, name) }).length }))
151
+ .filter((entry) => entry.files > 0)
152
152
  .sort((a, b) => b.files - a.files || a.name.localeCompare(b.name));
153
153
 
154
154
  out.push({
155
155
  pkg,
156
156
  // Relative to src/: a project that itself sits under a __tests__ directory still counts its files.
157
157
  total: sourceFiles({ dir: src }).filter(
158
- file => !`/${relative(src, file)}`.includes('/__tests__/'),
158
+ (file) => !`/${relative(src, file)}`.includes('/__tests__/'),
159
159
  ).length,
160
160
  subsystems,
161
161
  });
@@ -38,13 +38,13 @@ export const listDirs = (opts: { dir: string }): string[] => {
38
38
  }
39
39
 
40
40
  return readdirSync(dir)
41
- .filter(name => !PRUNE_DIRS.has(name) && statSync(join(dir, name)).isDirectory())
41
+ .filter((name) => !PRUNE_DIRS.has(name) && statSync(join(dir, name)).isDirectory())
42
42
  .sort();
43
43
  };
44
44
 
45
45
  export const sourceFiles = (opts: { dir: string }): string[] => {
46
46
  return walkFiles({ dir: opts.dir }).filter(
47
- file => file.endsWith('.ts') && !file.endsWith('.d.ts'),
47
+ (file) => file.endsWith('.ts') && !file.endsWith('.d.ts'),
48
48
  );
49
49
  };
50
50
 
@@ -61,19 +61,19 @@ export const repoRelative = (opts: { path: string }): string => {
61
61
  export const listPackages = (): { dir: string; path: string }[] => {
62
62
  const project = readOkfProject();
63
63
  const configured = project.packages
64
- .filter(entry => !entry.retired && existsSync(entry.path))
65
- .map(entry => ({ dir: entry.dir, path: entry.path }));
64
+ .filter((entry) => !entry.retired && existsSync(entry.path))
65
+ .map((entry) => ({ dir: entry.dir, path: entry.path }));
66
66
  const listed =
67
67
  project.packages.length > 0
68
68
  ? configured
69
- : listDirs({ dir: join(project.root, 'packages') }).map(dir => ({
69
+ : listDirs({ dir: join(project.root, 'packages') }).map((dir) => ({
70
70
  dir,
71
71
  path: join(project.root, 'packages', dir),
72
72
  }));
73
73
 
74
74
  return listed
75
- .filter(entry => !project.denylist.has(entry.dir))
75
+ .filter((entry) => !project.denylist.has(entry.dir))
76
76
  .sort((left, right) => (left.dir < right.dir ? -1 : left.dir > right.dir ? 1 : 0));
77
77
  };
78
78
 
79
- export const packageDirs = (): string[] => listPackages().map(entry => entry.dir);
79
+ export const packageDirs = (): string[] => listPackages().map((entry) => entry.dir);
@@ -230,7 +230,7 @@ const checkIndex = (opts: { file: IBundleFile }): IConformanceIssue[] => {
230
230
  }
231
231
 
232
232
  const issues: IConformanceIssue[] = [];
233
- const extraKeys = Object.keys(parsed.data).filter(key => key !== SpecConstants.VERSION_KEY);
233
+ const extraKeys = Object.keys(parsed.data).filter((key) => key !== SpecConstants.VERSION_KEY);
234
234
 
235
235
  if (extraKeys.length > 0) {
236
236
  issues.push(
@@ -305,7 +305,7 @@ const checkLog = (opts: { file: IBundleFile }): IConformanceIssue[] => {
305
305
 
306
306
  /** OKF v0.2 conformance (§11) plus soft guidance. Never throws: every finding is an issue. */
307
307
  export const checkBundle = (opts: { files: IBundleFile[] }): IConformanceIssue[] =>
308
- opts.files.flatMap(file => {
308
+ opts.files.flatMap((file) => {
309
309
  switch (getBaseName({ path: file.path })) {
310
310
  case ReservedFiles.INDEX: {
311
311
  return checkIndex({ file });
@@ -25,10 +25,10 @@ const escapeScriptClose = (opts: { text: string }): string =>
25
25
  opts.text.replace(/<\/(script)/gi, '<\\/$1');
26
26
 
27
27
  export const buildVizData = (opts: { concepts: Concept[] }): IVizData => {
28
- const concepts = opts.concepts.filter(concept => !concept.reserved);
29
- const ids = new Set(concepts.map(concept => concept.id));
28
+ const concepts = opts.concepts.filter((concept) => !concept.reserved);
29
+ const ids = new Set(concepts.map((concept) => concept.id));
30
30
 
31
- const nodes: IVizNode[] = concepts.map(concept => ({
31
+ const nodes: IVizNode[] = concepts.map((concept) => ({
32
32
  id: concept.id,
33
33
  type: concept.type,
34
34
  title: concept.title,
@@ -39,7 +39,7 @@ export const buildVizData = (opts: { concepts: Concept[] }): IVizData => {
39
39
  group: extractSection({ id: concept.id }),
40
40
  degree: 0,
41
41
  }));
42
- const nodeById = new Map(nodes.map(node => [node.id, node]));
42
+ const nodeById = new Map(nodes.map((node) => [node.id, node]));
43
43
 
44
44
  const edges: IVizEdge[] = [];
45
45
  const seen = new Set<string>();
@@ -67,15 +67,15 @@ export const buildVizData = (opts: { concepts: Concept[] }): IVizData => {
67
67
 
68
68
  const project = readOkfProject();
69
69
  const known = new Set(project.sections.order);
70
- const present = new Set(nodes.map(node => node.group));
70
+ const present = new Set(nodes.map((node) => node.group));
71
71
  const ordered = [
72
- ...project.sections.order.filter(section => present.has(section)),
73
- ...[...present].filter(section => !known.has(section)).sort(),
72
+ ...project.sections.order.filter((section) => present.has(section)),
73
+ ...[...present].filter((section) => !known.has(section)).sort(),
74
74
  ];
75
- const sections: IVizSection[] = ordered.map(key => ({
75
+ const sections: IVizSection[] = ordered.map((key) => ({
76
76
  key,
77
77
  label: toSectionTitle({ key, labels: project.sections.labels }),
78
- count: nodes.filter(node => node.group === key).length,
78
+ count: nodes.filter((node) => node.group === key).length,
79
79
  }));
80
80
 
81
81
  return {
@@ -110,7 +110,7 @@ export const bundleVizClient = async (): Promise<string> => {
110
110
  const [output] = result.outputs;
111
111
 
112
112
  if (!result.success || output === undefined) {
113
- const reasons = result.logs.map(log => String(log)).join('\n');
113
+ const reasons = result.logs.map((log) => String(log)).join('\n');
114
114
 
115
115
  console.error(
116
116
  `[bundleVizClient] failed to bundle ${relative(readOkfProject().root, CLIENT_ENTRY)}\n${reasons}`,
@@ -83,8 +83,8 @@ export class KnowledgeExplorer {
83
83
  ) {
84
84
  this.strings = UI_STRINGS[opts.locale];
85
85
  this.copy = opts.data.copy[opts.locale];
86
- this.nodeById = new Map(opts.data.nodes.map(node => [node.id, node]));
87
- this.neighbours = new Map(opts.data.nodes.map(node => [node.id, new Set<string>()]));
86
+ this.nodeById = new Map(opts.data.nodes.map((node) => [node.id, node]));
87
+ this.neighbours = new Map(opts.data.nodes.map((node) => [node.id, new Set<string>()]));
88
88
 
89
89
  for (const edge of opts.data.edges) {
90
90
  this.neighbours.get(edge.source)?.add(edge.target);
@@ -124,7 +124,7 @@ export class KnowledgeExplorer {
124
124
 
125
125
  private getNodesInSection(opts: { key: string }): IVizNode[] {
126
126
  return this.opts.data.nodes
127
- .filter(node => node.group === opts.key)
127
+ .filter((node) => node.group === opts.key)
128
128
  .sort((left, right) => left.title.localeCompare(right.title));
129
129
  }
130
130
 
@@ -172,7 +172,7 @@ export class KnowledgeExplorer {
172
172
 
173
173
  private findSidebarGroup(opts: { key: string }): HTMLElement | undefined {
174
174
  return [...this.opts.elements.side.querySelectorAll<HTMLElement>('.grp')].find(
175
- group => group.dataset.key === opts.key,
175
+ (group) => group.dataset.key === opts.key,
176
176
  );
177
177
  }
178
178
 
@@ -203,13 +203,13 @@ export class KnowledgeExplorer {
203
203
  this.setActive({});
204
204
 
205
205
  const cards = this.opts.data.sections
206
- .map(section => {
206
+ .map((section) => {
207
207
  const nodes = this.getNodesInSection({ key: section.key });
208
208
  const hidden = nodes.length - VizConstants.HOME_CARD_ITEMS;
209
209
  const links = nodes
210
210
  .slice(0, VizConstants.HOME_CARD_ITEMS)
211
211
  .map(
212
- node =>
212
+ (node) =>
213
213
  `<a data-go="${escapeAttribute({ text: node.id })}">${escapeHtml({ text: node.title })}</a>`,
214
214
  )
215
215
  .join('');
@@ -248,16 +248,16 @@ export class KnowledgeExplorer {
248
248
  this.setActive({ id: node.id });
249
249
 
250
250
  const label =
251
- this.opts.data.sections.find(section => section.key === node.group)?.label ?? node.group;
251
+ this.opts.data.sections.find((section) => section.key === node.group)?.label ?? node.group;
252
252
  const accent = this.getSectionColor({ key: node.group });
253
253
  const related = [...(this.neighbours.get(node.id) ?? [])]
254
- .map(id => this.nodeById.get(id))
254
+ .map((id) => this.nodeById.get(id))
255
255
  .filter((neighbour): neighbour is IVizNode => neighbour !== undefined)
256
256
  .sort((left, right) => left.title.localeCompare(right.title));
257
257
 
258
258
  const chips = related
259
259
  .map(
260
- neighbour =>
260
+ (neighbour) =>
261
261
  `<span class="chip" data-go="${escapeAttribute({ text: neighbour.id })}">` +
262
262
  `<span class="d" style="background:${this.getSectionColor({ key: neighbour.group })}"></span>${escapeHtml({ text: neighbour.title })}</span>`,
263
263
  )
@@ -270,7 +270,7 @@ export class KnowledgeExplorer {
270
270
  `<span class="badge" style="background:${accent}">${escapeHtml({ text: node.type })}</span>` +
271
271
  `<h1>${escapeHtml({ text: node.title })}</h1><p class="lead">${escapeHtml({ text: node.description })}</p>` +
272
272
  (node.tags.length
273
- ? `<div class="tags">#${node.tags.map(tag => escapeHtml({ text: tag })).join(' #')}</div>`
273
+ ? `<div class="tags">#${node.tags.map((tag) => escapeHtml({ text: tag })).join(' #')}</div>`
274
274
  : '') +
275
275
  (node.resource
276
276
  ? `<div class="src">${escapeHtml({ text: this.strings.source })}: ${escapeHtml({ text: node.resource })}</div>`
@@ -317,7 +317,7 @@ export class KnowledgeExplorer {
317
317
 
318
318
  for (const group of side.querySelectorAll<HTMLElement>('.grp')) {
319
319
  const anyVisible = [...group.querySelectorAll('.it')].some(
320
- item => !item.classList.contains('hide'),
320
+ (item) => !item.classList.contains('hide'),
321
321
  );
322
322
 
323
323
  group.style.display = query === '' || anyVisible ? '' : 'none';
@@ -334,8 +334,8 @@ export class KnowledgeExplorer {
334
334
  }
335
335
 
336
336
  const hits = this.opts.data.nodes
337
- .map(node => ({ node, score: scoreNode({ node, query }) }))
338
- .filter(hit => hit.score > 0)
337
+ .map((node) => ({ node, score: scoreNode({ node, query }) }))
338
+ .filter((hit) => hit.score > 0)
339
339
  .sort((left, right) => right.score - left.score)
340
340
  .slice(0, VizConstants.SEARCH_RESULT_LIMIT);
341
341
 
@@ -383,7 +383,7 @@ export class KnowledgeExplorer {
383
383
  });
384
384
  }
385
385
 
386
- document.addEventListener('click', event => {
386
+ document.addEventListener('click', (event) => {
387
387
  if (!(event.target instanceof Element)) {
388
388
  return;
389
389
  }
@@ -483,14 +483,14 @@ export class KnowledgeExplorer {
483
483
 
484
484
  const { nodes, edges, sections } = this.opts.data;
485
485
  const elements: cytoscape.ElementDefinition[] = [
486
- ...sections.map(section => ({
486
+ ...sections.map((section) => ({
487
487
  data: {
488
488
  id: `${SECTION_NODE_PREFIX}${section.key}`,
489
489
  label: section.label.toUpperCase(),
490
490
  kind: 'section',
491
491
  },
492
492
  })),
493
- ...nodes.map(node => ({
493
+ ...nodes.map((node) => ({
494
494
  data: {
495
495
  id: node.id,
496
496
  label: node.title,
@@ -499,7 +499,7 @@ export class KnowledgeExplorer {
499
499
  degree: node.degree,
500
500
  },
501
501
  })),
502
- ...edges.map(edge => ({
502
+ ...edges.map((edge) => ({
503
503
  data: { id: `${edge.source}>${edge.target}`, source: edge.source, target: edge.target },
504
504
  })),
505
505
  ];
@@ -513,8 +513,8 @@ export class KnowledgeExplorer {
513
513
  layout: FCOSE_LAYOUT,
514
514
  });
515
515
 
516
- graph.on('tap', 'node[!kind]', event => this.openConcept({ id: event.target.id() }));
517
- graph.on('mouseover', 'node[!kind]', event => {
516
+ graph.on('tap', 'node[!kind]', (event) => this.openConcept({ id: event.target.id() }));
517
+ graph.on('mouseover', 'node[!kind]', (event) => {
518
518
  const neighbourhood = event.target.closedNeighborhood();
519
519
 
520
520
  graph.elements().difference(neighbourhood).addClass('dim');
@@ -20,8 +20,8 @@ const ELEMENT_IDS = [
20
20
 
21
21
  /** Every element the template must carry; a missing one is reported by name, never thrown on. */
22
22
  const collectElements = (): IExplorerElements | undefined => {
23
- const byId = new Map(ELEMENT_IDS.map(id => [id, document.getElementById(id)]));
24
- const missing = ELEMENT_IDS.filter(id => byId.get(id) === null);
23
+ const byId = new Map(ELEMENT_IDS.map((id) => [id, document.getElementById(id)]));
24
+ const missing = ELEMENT_IDS.filter((id) => byId.get(id) === null);
25
25
  const search = byId.get('search');
26
26
 
27
27
  if (missing.length > 0 || !(search instanceof HTMLInputElement)) {
@@ -33,11 +33,11 @@ const splitCells = (opts: { line: string }): string[] =>
33
33
  .replace(/^\|/, '')
34
34
  .replace(/\|$/, '')
35
35
  .split('|')
36
- .map(cell => cell.trim());
36
+ .map((cell) => cell.trim());
37
37
 
38
38
  const renderRow = (opts: { line: string; cellTag: 'th' | 'td' }): string =>
39
39
  `<tr>${splitCells({ line: opts.line })
40
- .map(cell => `<${opts.cellTag}>${renderInline({ text: cell })}</${opts.cellTag}>`)
40
+ .map((cell) => `<${opts.cellTag}>${renderInline({ text: cell })}</${opts.cellTag}>`)
41
41
  .join('')}</tr>`;
42
42
 
43
43
  /**
@@ -26,8 +26,8 @@ export const UI_STRINGS: Record<TLocale, IUiStrings> = {
26
26
  mapHint: 'Drag to pan · scroll to zoom · click a node to read it',
27
27
  concepts: 'concepts',
28
28
  areas: 'areas',
29
- formatResults: opts => `${opts.count} result${opts.count === 1 ? '' : 's'}`,
30
- formatMore: opts => `+ ${opts.count} more`,
29
+ formatResults: (opts) => `${opts.count} result${opts.count === 1 ? '' : 's'}`,
30
+ formatMore: (opts) => `+ ${opts.count} more`,
31
31
  },
32
32
  [Locales.VI]: {
33
33
  search: 'Tìm trong kiến thức…',
@@ -38,8 +38,8 @@ export const UI_STRINGS: Record<TLocale, IUiStrings> = {
38
38
  mapHint: 'Kéo để di chuyển · cuộn để zoom · click vào node để đọc',
39
39
  concepts: 'khái niệm',
40
40
  areas: 'lĩnh vực',
41
- formatResults: opts => `${opts.count} kết quả`,
42
- formatMore: opts => `+ ${opts.count} nữa`,
41
+ formatResults: (opts) => `${opts.count} kết quả`,
42
+ formatMore: (opts) => `+ ${opts.count} nữa`,
43
43
  },
44
44
  };
45
45