@unclex/ken-lint 0.0.0-stage → 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Xiaoxing Hu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,18 @@
1
- # Temporary Holding Version
1
+ # @unclex/ken-lint
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The knowledge-base lint of a ken root. Bundled in `@unclex/ken`, which runs it as `ken
4
+ lint`, with `KEN_ROOT` set to the root.
5
+
6
+ It walks the root's sections and reports, each with its file and what to do: a page in no
7
+ section README or in two, a page at the top outside any section, a link to a file that does
8
+ not exist, a code reference `<key>:<path>` whose file is not in the clone, and the caps
9
+ (front page 60 lines, section README 150, `AGENTS.md` 40). It exits 1 on any of those.
10
+ References into repos not cloned, and old pages nobody links to, are notes. Markdown is parsed as CommonMark, so links and references in code blocks are examples.
11
+
12
+ ```sh
13
+ ken lint
14
+ ken lint --help
15
+ ```
16
+
17
+ The caps are constants at the top of `src/lint.ts`. See "`ken-lint`" in `docs/prd.md` at
18
+ the repo root.
package/dist/cli.js ADDED
@@ -0,0 +1,47 @@
1
+ #!/usr/bin/env node
2
+ // The knowledge-base lint, an external subcommand of ken: see "`ken-lint`" in docs/prd.md.
3
+ import { AGENTS_MAX, FRONT_PAGE_MAX, lint, SECTION_README_MAX, STALE_DAYS } from "./lint.js";
4
+ const HELP = `ken lint
5
+
6
+ Check the knowledge base of the ken root, so it stays safe to read top down: front page,
7
+ section README, page. Hidden entries, the checkouts in .repos/ and the task folder are
8
+ skipped.
9
+
10
+ Errors, exit 1:
11
+ a page in no section README.md, or in more than one; a page at the top, outside a section
12
+ a Markdown link to a file that does not exist
13
+ a code reference <key>:<path> whose file is not in the clone (ken path resolves it)
14
+ the front page over ${FRONT_PAGE_MAX} lines, a section README.md over ${SECTION_README_MAX}, AGENTS.md over ${AGENTS_MAX}
15
+ Notes, exit 0:
16
+ code references into repos not cloned here, counted
17
+ pages nobody links to and nobody has changed in ${STALE_DAYS} days, proposed for .archive/
18
+
19
+ Links and references in code blocks are examples and not checked.
20
+
21
+ Examples:
22
+ ken lint
23
+ ken lint && git commit -am "systems: the join flow"`;
24
+ const args = process.argv.slice(2);
25
+ if (args.includes('--help') || args.includes('-h')) {
26
+ console.log(HELP);
27
+ process.exit(0);
28
+ }
29
+ if (args.length) {
30
+ console.error(`ken lint takes no arguments, got ${JSON.stringify(args.join(' '))}: it checks the whole root. Run \`ken lint\`; \`ken lint --help\` says what it checks.`);
31
+ process.exit(1);
32
+ }
33
+ const root = process.env.KEN_ROOT;
34
+ if (!root) {
35
+ console.error('ken-lint: KEN_ROOT is not set, so there is no root to check. Run it as `ken lint`, which sets it.');
36
+ process.exit(1);
37
+ }
38
+ try {
39
+ const { lines, errors } = lint(root);
40
+ for (const line of lines)
41
+ console.log(line);
42
+ process.exit(errors ? 1 : 0);
43
+ }
44
+ catch (e) {
45
+ console.error(`ken lint: ${e.message}`);
46
+ process.exit(1);
47
+ }
package/dist/lint.js ADDED
@@ -0,0 +1,250 @@
1
+ // The knowledge-base lint: is the root still safe to read top down? See "`ken-lint`" in
2
+ // docs/prd.md. Files are parsed as CommonMark, so a link, a code span and a label are what a
3
+ // Markdown reader sees, never a guess at where one ends.
4
+ import { spawnSync } from 'node:child_process';
5
+ import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
6
+ import { basename, dirname, join, relative, resolve, sep } from 'node:path';
7
+ import { fromMarkdown } from 'mdast-util-from-markdown';
8
+ // The caps, in lines, and the age of a page nobody links to before it is proposed for
9
+ // .archive/. The one place to change them.
10
+ export const FRONT_PAGE_MAX = 60;
11
+ export const SECTION_README_MAX = 150;
12
+ export const AGENTS_MAX = 40;
13
+ export const STALE_DAYS = 365;
14
+ // the names at the top of the root that are not pages: the front page, the reserved
15
+ // files, and the index and the checkouts, which are hidden too
16
+ const RESERVED = new Set([
17
+ 'README.md',
18
+ 'AGENTS.md',
19
+ 'CLAUDE.md',
20
+ 'log.md',
21
+ '.repos.index',
22
+ '.repos'
23
+ ]);
24
+ // `<host>/<owner>/<repo>:<path>`, each part as `ken path` takes it, in prose or a code span
25
+ const REFERENCE = /(?<![\w./:-])([\w-][\w.-]*\/[\w.-]+\/[\w.-]+):([^\s'"<>#,;*]+)/gi;
26
+ const IS_REFERENCE = /^[\w-][\w.-]*\/[\w.-]+\/[\w.-]+:/;
27
+ const ken = (args) => spawnSync('ken', args, { encoding: 'utf8' });
28
+ /** A word for sh, whatever it holds. */
29
+ const quote = (word) => `'${word.replaceAll("'", `'\\''`)}'`;
30
+ /**
31
+ * The task folder of the root, absolute, from its `.ken` as docs/files.md reads it: a repeated
32
+ * key is its last line, a value is trimmed. One it cannot read stops the lint.
33
+ */
34
+ function taskFolder(root) {
35
+ const file = join(root, '.ken');
36
+ const unknown = 'so the task folder is unknown';
37
+ let text;
38
+ try {
39
+ text = readFileSync(file, 'utf8');
40
+ }
41
+ catch (e) {
42
+ throw new Error(`${file} could not be read (${e.message}), ${unknown}. Every root holds a .ken: make it with \`ken init ${quote(root)}\`, then run \`ken lint\` again.`);
43
+ }
44
+ let folder = 'tasks';
45
+ for (const [i, line] of text.split('\n').entries()) {
46
+ if (!line.startsWith('task.folder='))
47
+ continue;
48
+ folder = line.slice('task.folder='.length).trim();
49
+ if (!folder) {
50
+ throw new Error(`${file} line ${i + 1}, ${JSON.stringify(line)}, sets task.folder to nothing, ${unknown}. It is a folder, relative to the root or absolute, like task.folder=tasks: fix the line, or delete it for the default, tasks.`);
51
+ }
52
+ }
53
+ return resolve(root, folder);
54
+ }
55
+ /** A path keeps its brackets, `src/app/[id]/page.ts`, not the prose's punctuation after it. */
56
+ function trimPath(path) {
57
+ const p = path.replace(/[.:!?]+$/, '');
58
+ const close = p.at(-1) ?? '';
59
+ const open = { ')': '(', ']': '[' }[close];
60
+ const count = (c) => p.split(c).length;
61
+ return open && count(open) < count(close) ? trimPath(p.slice(0, -1)) : p;
62
+ }
63
+ function decode(url) {
64
+ try {
65
+ return decodeURIComponent(url);
66
+ }
67
+ catch {
68
+ return url;
69
+ }
70
+ }
71
+ function visit(node, fn) {
72
+ fn(node);
73
+ if ('children' in node)
74
+ for (const child of node.children)
75
+ visit(child, fn);
76
+ }
77
+ /** Lint the root at `root`: one line per problem, then the summary; `errors` decides the exit. */
78
+ export function lint(root) {
79
+ // The task folder holds tasks, not pages: compared by real path, so a link to a folder above
80
+ // it does not reach it either. The checkouts are never walked, whatever link reaches into them.
81
+ const folder = taskFolder(root);
82
+ const tasks = existsSync(folder) ? realpathSync(folder) : folder;
83
+ const seen = new Set([realpathSync(root)]); // folders walked
84
+ const repos = existsSync(join(root, '.repos')) ? realpathSync(join(root, '.repos')) : undefined;
85
+ const problems = [];
86
+ const report = (kind, file, text, line) => problems.push(`${kind}: ${relative(root, file)}${line ? `:${line}` : ''}: ${text}`);
87
+ const lines = (file) => {
88
+ const text = readFileSync(file, 'utf8');
89
+ return text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
90
+ };
91
+ const cap = (file, max, why) => {
92
+ if (existsSync(file) && lines(file) > max) {
93
+ report('error', file, `${lines(file)} lines, over the cap of ${max}. ${why}`);
94
+ }
95
+ };
96
+ // The walk, as `find -L`: links followed, each folder read once. A page is keyed by its real
97
+ // path, so a link that reaches it by another path still finds it.
98
+ const pages = new Map();
99
+ const readmes = [];
100
+ const walk = (dir) => {
101
+ const real = realpathSync(dir);
102
+ if (real === tasks || seen.has(real))
103
+ return;
104
+ if (repos && (real === repos || real.startsWith(repos + sep)))
105
+ return;
106
+ seen.add(real);
107
+ for (const name of readdirSync(dir).sort()) {
108
+ const path = join(dir, name);
109
+ const stat = statSync(path, { throwIfNoEntry: false });
110
+ if (name.startsWith('.') || !stat)
111
+ continue;
112
+ if (stat.isDirectory())
113
+ walk(path);
114
+ else if (name === 'README.md')
115
+ readmes.push(path);
116
+ else if (name.endsWith('.md'))
117
+ pages.set(realpathSync(path), { path, listedBy: [] });
118
+ }
119
+ };
120
+ for (const name of readdirSync(root).sort()) {
121
+ const path = join(root, name);
122
+ if (name.startsWith('.') || RESERVED.has(name))
123
+ continue;
124
+ const stat = statSync(path, { throwIfNoEntry: false });
125
+ if (stat?.isDirectory())
126
+ walk(path);
127
+ // a page at the top is in no section: reported below
128
+ else if (stat && name.endsWith('.md'))
129
+ pages.set(realpathSync(path), { path, listedBy: [] });
130
+ }
131
+ cap(join(root, 'README.md'), FRONT_PAGE_MAX, 'The front page is read first for every question: keep one line per section and the few evergreen pages, and move the rest into pages.');
132
+ cap(join(root, 'AGENTS.md'), AGENTS_MAX, 'It is loaded on every turn: keep the non-obvious only, and move the rest into a page.');
133
+ for (const readme of readmes) {
134
+ cap(readme, SECTION_README_MAX, `Split the section: move groups of pages into subfolders, each with its own README.md, and list the subfolders in ${relative(root, readme)}.`);
135
+ }
136
+ // Links and code references, in the front pages, the section READMEs and the pages.
137
+ const inbound = new Set(); // real paths of pages some front page or page links to
138
+ const paths = new Map(); // reference -> `ken path` of it
139
+ const uncloned = new Map(); // key -> references into it not checked
140
+ const checkReference = (file, key, path, line) => {
141
+ const ref = `${key}:${path}`;
142
+ const r = paths.get(ref) ?? ken(['path', ref]);
143
+ paths.set(ref, r);
144
+ const out = r.stdout.trim();
145
+ if (r.status !== 0)
146
+ report('error', file, `\`ken path ${ref}\` failed: ${r.stderr.trim()}`, line);
147
+ else if (out.startsWith('https://'))
148
+ uncloned.set(key, (uncloned.get(key) ?? 0) + 1);
149
+ else if (!existsSync(out)) {
150
+ report('error', file, `${ref} names a file not in the clone. Find where it went, \`git -C "$(ken path code ${key})" log --oneline -- '${path}'\`, and fix the reference.`, line);
151
+ }
152
+ };
153
+ // in prose or a code span, a reference ends where the text says it does
154
+ const checkReferences = (file, text, line) => {
155
+ for (const m of text.matchAll(REFERENCE)) {
156
+ // the node's first line, plus the lines before the match within it
157
+ const at = line && line + text.slice(0, m.index).split('\n').length - 1;
158
+ checkReference(file, m[1] ?? '', trimPath(m[2] ?? ''), at);
159
+ }
160
+ };
161
+ const front = [join(root, 'README.md')].filter((f) => existsSync(f));
162
+ for (const file of [...front, ...readmes, ...[...pages.values()].map((p) => p.path)]) {
163
+ const tree = fromMarkdown(readFileSync(file, 'utf8'));
164
+ // a reference link renders through its definition; a definition alone renders nothing
165
+ const definitions = new Map();
166
+ visit(tree, (node) => {
167
+ if (node.type === 'definition' && !definitions.has(node.identifier)) {
168
+ definitions.set(node.identifier, node.url);
169
+ }
170
+ });
171
+ const listed = new Set();
172
+ // code blocks are examples: neither their links nor their references are checked
173
+ visit(tree, (node) => {
174
+ const line = node.position?.start.line;
175
+ if (node.type === 'text' || node.type === 'inlineCode') {
176
+ return checkReferences(file, node.value, line);
177
+ }
178
+ // every definition's target is checked once, at the definition; only a rendered link,
179
+ // inline or through a definition, lists a page or links to it
180
+ const url = node.type === 'link' || node.type === 'definition'
181
+ ? node.url
182
+ : node.type === 'linkReference'
183
+ ? definitions.get(node.identifier)
184
+ : undefined;
185
+ const checks = node.type !== 'linkReference';
186
+ if (url === undefined)
187
+ return;
188
+ // as a link's destination, a reference is the whole of it, URL-encoded: `%20` is a space
189
+ if (IS_REFERENCE.test(url)) {
190
+ const ref = url.replace(/#.*$/, '');
191
+ const colon = ref.indexOf(':');
192
+ if (checks)
193
+ checkReference(file, ref.slice(0, colon), decode(ref.slice(colon + 1)), line);
194
+ return;
195
+ }
196
+ // a URL or an anchor
197
+ if (/^[a-z][a-z0-9+.-]*:|^#|^\/\//i.test(url))
198
+ return;
199
+ const path = decode(url.replace(/[#?].*$/, ''));
200
+ const to = path.startsWith('/') ? join(root, path) : resolve(dirname(file), path);
201
+ if (!existsSync(to)) {
202
+ if (checks) {
203
+ report('error', file, `links to ${url}, which does not exist. Fix the path, or remove the link.`, line);
204
+ }
205
+ return;
206
+ }
207
+ if (node.type === 'definition')
208
+ return;
209
+ const real = realpathSync(to);
210
+ if (pages.has(real) && readmes.includes(file))
211
+ listed.add(real);
212
+ else if (real !== realpathSync(file))
213
+ inbound.add(real);
214
+ });
215
+ for (const page of listed)
216
+ pages.get(page)?.listedBy.push(file);
217
+ }
218
+ for (const [real, { path: page, listedBy }] of pages) {
219
+ if (dirname(page) === root) {
220
+ report('error', page, `a page at the top of the root, where only the front page and the reserved files live, so it is in no section. Move it into the section it belongs to with \`git mv\`, and add its line to that section's README.md.`);
221
+ }
222
+ else if (listedBy.length === 0) {
223
+ report('error', page, `listed in no section README.md, so an agent reading down from the front page never finds it. Add a line \`- [${basename(page, '.md')}](${encodeURI(basename(page))}): <what it says>\` to ${relative(root, join(dirname(page), 'README.md'))}, making it if missing.`);
224
+ }
225
+ else if (listedBy.length > 1) {
226
+ report('error', page, `listed in ${listedBy.length} section READMEs, ${listedBy.map((f) => relative(root, f)).join(' and ')}; a page has one home. Keep its line in one and drop it from the others.`);
227
+ }
228
+ if (inbound.has(real))
229
+ continue;
230
+ const log = spawnSync('git', ['log', '-1', '--format=%ct', '--', basename(page)], {
231
+ cwd: dirname(real),
232
+ encoding: 'utf8'
233
+ });
234
+ const changed = Number(log.stdout.trim()) * 1000;
235
+ if (!changed || Date.now() - changed < STALE_DAYS * 86_400_000)
236
+ continue;
237
+ const rel = relative(root, page);
238
+ report('note', page, `nobody links to it and nobody has changed it since ${new Date(changed).toISOString().slice(0, 10)}. If it is settled, propose archiving it: \`cd "$(ken path root)" && mkdir -p -- ${quote(join('.archive', dirname(rel)))} && git mv -- ${quote(rel)} ${quote(join('.archive', rel))}\`, then drop its line from its README.md.`);
239
+ }
240
+ if (uncloned.size) {
241
+ const keys = [...uncloned.keys()];
242
+ const count = [...uncloned.values()].reduce((a, b) => a + b, 0);
243
+ problems.push(`note: not checked: ${count} code references into ${keys.join(', ')}, not cloned here. To check them, run ${keys.map((k) => `\`ken get ${k}\``).join(' and ')}, then \`ken lint\` again.`);
244
+ }
245
+ const errors = problems.filter((p) => p.startsWith('error:')).length;
246
+ problems.push(errors
247
+ ? `ken lint: ${errors} errors in ${pages.size} pages. Fix each as it says, then run \`ken lint\` again.`
248
+ : `ken lint: no errors in ${pages.size} pages.`);
249
+ return { lines: problems, errors };
250
+ }
package/package.json CHANGED
@@ -1,6 +1,32 @@
1
1
  {
2
2
  "name": "@unclex/ken-lint",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.1",
4
+ "description": "The knowledge-base lint of a ken root: every page in one section README, every link and code reference resolving, the caps. Reached as `ken lint`.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/xiaoxinghu/ken.git",
10
+ "directory": "packages/ken-lint"
11
+ },
12
+ "homepage": "https://unclex.net",
13
+ "bin": {
14
+ "ken-lint": "./dist/cli.js"
15
+ },
16
+ "files": [
17
+ "dist"
18
+ ],
19
+ "engines": {
20
+ "node": ">=24"
21
+ },
22
+ "dependencies": {
23
+ "mdast-util-from-markdown": "^2.1.0"
24
+ },
25
+ "publishConfig": {
26
+ "access": "public"
27
+ },
28
+ "devDependencies": {
29
+ "@types/mdast": "^4.0.4"
30
+ },
31
+ "scripts": {}
6
32
  }