waterplane 0.1.22 → 0.1.25
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/CHANGELOG.md +39 -0
- package/SECURITY.md +1 -1
- package/node_modules/@waterplane/shared/dist/healthindex/commits.d.ts +1 -1
- package/node_modules/@waterplane/shared/dist/healthindex/commits.js +2 -2
- package/node_modules/@waterplane/shared/dist/healthindex/commits.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/healthindex/coverage.d.ts +128 -0
- package/node_modules/@waterplane/shared/dist/healthindex/coverage.js +343 -0
- package/node_modules/@waterplane/shared/dist/healthindex/coverage.js.map +1 -0
- package/node_modules/@waterplane/shared/dist/healthindex/readings.d.ts +9 -1
- package/node_modules/@waterplane/shared/dist/healthindex/readings.js +122 -4
- package/node_modules/@waterplane/shared/dist/healthindex/readings.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/healthindex/repoindex.d.ts +5 -0
- package/node_modules/@waterplane/shared/dist/healthindex/repoindex.js +2 -0
- package/node_modules/@waterplane/shared/dist/healthindex/repoindex.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/healthindex/score.d.ts +3 -0
- package/node_modules/@waterplane/shared/dist/healthindex/score.js +52 -16
- package/node_modules/@waterplane/shared/dist/healthindex/score.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/healthindex/types.d.ts +82 -6
- package/node_modules/@waterplane/shared/dist/healthindex/types.js +35 -2
- package/node_modules/@waterplane/shared/dist/healthindex/types.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/healthindex/words.js +65 -6
- package/node_modules/@waterplane/shared/dist/healthindex/words.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/healthindex.d.ts +21 -7
- package/node_modules/@waterplane/shared/dist/healthindex.js +20 -7
- package/node_modules/@waterplane/shared/dist/healthindex.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/healthindexresponse.js +3 -2
- package/node_modules/@waterplane/shared/dist/healthindexresponse.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/healthspend.js +1 -1
- package/node_modules/@waterplane/shared/dist/hints.js +9 -0
- package/node_modules/@waterplane/shared/dist/hints.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/index.d.ts +2 -0
- package/node_modules/@waterplane/shared/dist/index.js +2 -0
- package/node_modules/@waterplane/shared/dist/index.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/intent/kind.d.ts +45 -1
- package/node_modules/@waterplane/shared/dist/intent/kind.js +60 -2
- package/node_modules/@waterplane/shared/dist/intent/kind.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/intent.d.ts +1 -1
- package/node_modules/@waterplane/shared/dist/intent.js +1 -1
- package/node_modules/@waterplane/shared/dist/intent.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/repohealth.d.ts +178 -0
- package/node_modules/@waterplane/shared/dist/repohealth.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/repohealthhabits.d.ts +15 -0
- package/node_modules/@waterplane/shared/dist/repohealthhabits.js +117 -0
- package/node_modules/@waterplane/shared/dist/repohealthhabits.js.map +1 -0
- package/node_modules/@waterplane/shared/dist/repohealthnative.d.ts +10 -0
- package/node_modules/@waterplane/shared/dist/repohealthnative.js +94 -0
- package/node_modules/@waterplane/shared/dist/repohealthnative.js.map +1 -0
- package/node_modules/@waterplane/shared/dist/repohealthread.js +23 -1
- package/node_modules/@waterplane/shared/dist/repohealthread.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/wire/agentreadings.d.ts +104 -0
- package/node_modules/@waterplane/shared/dist/wire/agentreadings.js +7 -0
- package/node_modules/@waterplane/shared/dist/wire/agentreadings.js.map +1 -0
- package/node_modules/@waterplane/shared/dist/wire/notify.d.ts +6 -1
- package/node_modules/@waterplane/shared/dist/wire/notify.js +6 -1
- package/node_modules/@waterplane/shared/dist/wire/notify.js.map +1 -1
- package/node_modules/@waterplane/shared/dist/wire/repo.d.ts +1 -1
- package/npm-shrinkwrap.json +2 -2
- package/package.json +1 -1
- package/packages/extensions/android-apps/waterplane-plugin.json +4 -1
- package/packages/extensions/copilot-usage/waterplane-plugin.json +7 -2
- package/packages/extensions/desktop/waterplane-plugin.json +5 -0
- package/packages/extensions/ocr/waterplane-plugin.json +5 -1
- package/packages/extensions/requirements/waterplane-plugin.json +3 -3
- package/packages/extensions/scorecard/waterplane-plugin.json +2 -1
- package/packages/extensions/token-stats/waterplane-plugin.json +4 -3
- package/packages/host/dist/agentclass.d.ts +105 -0
- package/packages/host/dist/agentclass.js +189 -0
- package/packages/host/dist/agentclass.js.map +1 -0
- package/packages/host/dist/agentintents.d.ts +18 -0
- package/packages/host/dist/agentintents.js +40 -7
- package/packages/host/dist/agentintents.js.map +1 -1
- package/packages/host/dist/agentreadings.d.ts +40 -0
- package/packages/host/dist/agentreadings.js +254 -0
- package/packages/host/dist/agentreadings.js.map +1 -0
- package/packages/host/dist/agentscan.d.ts +8 -0
- package/packages/host/dist/agentscan.js +329 -0
- package/packages/host/dist/agentscan.js.map +1 -0
- package/packages/host/dist/backends/index.js +12 -1
- package/packages/host/dist/backends/index.js.map +1 -1
- package/packages/host/dist/binguard.d.ts +13 -1
- package/packages/host/dist/binguard.js +28 -2
- package/packages/host/dist/binguard.js.map +1 -1
- package/packages/host/dist/exposure.d.ts +10 -0
- package/packages/host/dist/exposure.js +25 -0
- package/packages/host/dist/exposure.js.map +1 -1
- package/packages/host/dist/plugins/pluginassets.d.ts +17 -0
- package/packages/host/dist/plugins/pluginassets.js +27 -1
- package/packages/host/dist/plugins/pluginassets.js.map +1 -1
- package/packages/host/dist/plugins/pluginregistry.d.ts +3 -1
- package/packages/host/dist/plugins/pluginregistry.js +8 -1
- package/packages/host/dist/plugins/pluginregistry.js.map +1 -1
- package/packages/host/dist/reposkilltext.d.ts +2 -0
- package/packages/host/dist/reposkilltext.js +8 -2
- package/packages/host/dist/reposkilltext.js.map +1 -1
- package/packages/host/dist/routes/apirepowork.js +13 -0
- package/packages/host/dist/routes/apirepowork.js.map +1 -1
- package/packages/host/dist/routes/apisystem.js +17 -1
- package/packages/host/dist/routes/apisystem.js.map +1 -1
- package/packages/host/dist/routes/apitable.d.ts +4 -0
- package/packages/host/dist/routes/apitable.js.map +1 -1
- package/packages/host/dist/server/http.js +2 -1
- package/packages/host/dist/server/http.js.map +1 -1
- package/packages/host/dist/server/intentDeps.js +14 -1
- package/packages/host/dist/server/intentDeps.js.map +1 -1
- package/packages/host/dist/sessions/tmux.js +6 -1
- package/packages/host/dist/sessions/tmux.js.map +1 -1
- package/packages/host/dist/weekburn.js +7 -5
- package/packages/host/dist/weekburn.js.map +1 -1
- package/packages/web/dist/assets/demo-mKJo0QVO.js +26 -0
- package/packages/web/dist/assets/index-B6f7Lcp1.js +170 -0
- package/packages/web/dist/assets/index-DQIK94fc.css +1 -0
- package/packages/web/dist/assets/shared-Cd69oxHd.js +51 -0
- package/packages/web/dist/assets/sheets-BImsk1_Y.js +256 -0
- package/packages/web/dist/build-id.txt +1 -1
- package/packages/web/dist/buildstamp.json +1 -1
- package/packages/web/dist/index.html +5 -5
- package/packages/web/dist/sw.js +2 -2
- package/release.json +3 -3
- package/tools/repohealth/constants.mjs +34 -1
- package/tools/repohealth/fixture.json +5374 -38
- package/tools/repohealth/git.mjs +77 -0
- package/tools/repohealth/lang/dart-analyze.mjs +181 -0
- package/tools/repohealth/lang/dart-lex.mjs +494 -0
- package/tools/repohealth/lang/dart-resolve.mjs +95 -0
- package/tools/repohealth/lang/python-ast.mjs +602 -0
- package/tools/repohealth/lang/python-resolve.mjs +228 -0
- package/tools/repohealth/metrics/habits.mjs +286 -0
- package/tools/repohealth/metrics/native.mjs +542 -0
- package/tools/repohealth/metrics/untested.mjs +20 -8
- package/tools/repohealth/metrics/workspace.mjs +256 -0
- package/tools/repohealth/own.mjs +67 -5
- package/tools/repohealth/packs/dart.mjs +153 -85
- package/tools/repohealth/packs/python.mjs +51 -14
- package/tools/repohealth/plot.mjs +143 -1
- package/tools/repohealth/reach.mjs +98 -0
- package/tools/repohealth/scope.mjs +14 -1
- package/tools/repohealth/series.mjs +5 -0
- package/tools/repohealth/types.mjs +4 -0
- package/tools/repohealth.mjs +39 -5
- package/packages/web/dist/assets/demo-ad3g3HDa.js +0 -26
- package/packages/web/dist/assets/index-BllRvpkw.js +0 -170
- package/packages/web/dist/assets/index-DUiYLEts.css +0 -1
- package/packages/web/dist/assets/shared-DBaaGttP.js +0 -51
- package/packages/web/dist/assets/sheets-CrfRr6Um.js +0 -256
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Workspace: two readings about what a repo CARRIES, taken from the tree at
|
|
3
|
+
* the newest commit — tracked litter and docs that name paths which are gone.
|
|
4
|
+
*
|
|
5
|
+
* ── Why these are HEAD-only ────────────────────────────────────────────────
|
|
6
|
+
*
|
|
7
|
+
* Both are lists of names a person acts on (delete this, fix that sentence),
|
|
8
|
+
* and a list of last March's litter helps nobody. The metric is pure — a
|
|
9
|
+
* list of tree entries and a reader of text in, a row out — and
|
|
10
|
+
* `measureWorkspaceAt` is the one function that touches git, called by
|
|
11
|
+
* `repohealth.mjs` for the newest commit only. Every earlier row carries
|
|
12
|
+
* `{value: null, reason: "read at the newest commit only"}`; a point series
|
|
13
|
+
* of these would need a tree read per commit for a number nobody trends.
|
|
14
|
+
*
|
|
15
|
+
* ── Litter: tracked only, and it says so ───────────────────────────────────
|
|
16
|
+
*
|
|
17
|
+
* The engine reads committed objects and never the working tree (`git.mjs`'s
|
|
18
|
+
* header argues why: the tree is shared and half-edited). So this counts
|
|
19
|
+
* TRACKED binaries and build output — the litter that reached the history —
|
|
20
|
+
* and `scope: "tracked"` is on the value so the phone can say that untracked
|
|
21
|
+
* files were not looked at. A file is litter when its extension is in
|
|
22
|
+
* `LITTER_EXTS` (archives, packages, databases, logs, object files, editor
|
|
23
|
+
* leftovers) or one of its directories is in `LITTER_DIRS` (directories that
|
|
24
|
+
* only a build or a package manager writes). `build` and `out` are NOT in the
|
|
25
|
+
* list: they are ordinary names for source directories. Paths under
|
|
26
|
+
* `fixtures`/`testdata` are skipped — a test's zip is on purpose.
|
|
27
|
+
*
|
|
28
|
+
* ── Docs drift: candidate references, not proof ────────────────────────────
|
|
29
|
+
*
|
|
30
|
+
* A markdown file "names" a repo path when it writes one in an inline code
|
|
31
|
+
* span (`` `packages/web/src/App.tsx` ``) or a relative link target. Fenced
|
|
32
|
+
* code blocks are ignored (examples, not claims). A candidate must contain a
|
|
33
|
+
* `/` (links may be a bare relative file) and end in a file extension or `/`,
|
|
34
|
+
* hold no glob, placeholder or URL syntax, and not start in a build
|
|
35
|
+
* directory. It resolves when it exists from the repo root or from the
|
|
36
|
+
* document's own directory, as a file or a directory, or when it is the tail
|
|
37
|
+
* of a tracked path (package-relative writing). Changelogs
|
|
38
|
+
* are skipped: they are SUPPOSED to name what is gone.
|
|
39
|
+
*
|
|
40
|
+
* What this will still get wrong, and the list carries the evidence so a
|
|
41
|
+
* person can tell: a path to an ignored file (`.claude/outbox/x.gif`), to
|
|
42
|
+
* another repo, or to something a command creates. The count is "references
|
|
43
|
+
* that did not resolve", worded so.
|
|
44
|
+
*/
|
|
45
|
+
import { posix } from "node:path";
|
|
46
|
+
import { inExcludedDir } from "../source.mjs";
|
|
47
|
+
import { scopeEntries } from "../scope.mjs";
|
|
48
|
+
|
|
49
|
+
const LITTER_EXTS = new Set([
|
|
50
|
+
"apk", "aab", "ipa", "db", "sqlite", "sqlite3", "log", "zip", "tar", "tgz", "gz", "bz2", "xz",
|
|
51
|
+
"7z", "rar", "jar", "war", "exe", "dll", "so", "dylib", "o", "a", "class", "pyc", "pyo",
|
|
52
|
+
"dmp", "bak", "tmp", "swp", "swo", "pid",
|
|
53
|
+
]);
|
|
54
|
+
const LITTER_NAMES = new Set([".DS_Store", "Thumbs.db"]);
|
|
55
|
+
const LITTER_DIRS = new Set([
|
|
56
|
+
"dist", "node_modules", "target", ".next", ".nuxt", ".svelte-kit", ".gradle", "__pycache__",
|
|
57
|
+
"coverage", ".turbo", ".parcel-cache",
|
|
58
|
+
]);
|
|
59
|
+
const ON_PURPOSE_DIRS = new Set(["fixtures", "__fixtures__", "testdata", "test-data", "__snapshots__"]);
|
|
60
|
+
|
|
61
|
+
const none = (reason) => ({ value: null, reason });
|
|
62
|
+
|
|
63
|
+
/** @param {string} path */
|
|
64
|
+
function extOf(path) {
|
|
65
|
+
const name = path.slice(path.lastIndexOf("/") + 1);
|
|
66
|
+
const dot = name.lastIndexOf(".");
|
|
67
|
+
return dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Tracked litter in a tree.
|
|
72
|
+
* @param {{path: string, size: number}[]} entries
|
|
73
|
+
* @param {{HABITS_LIST_N: number}} prereg
|
|
74
|
+
*/
|
|
75
|
+
export function measureLitter(entries, prereg) {
|
|
76
|
+
const kinds = {};
|
|
77
|
+
const items = [];
|
|
78
|
+
let bytes = 0;
|
|
79
|
+
for (const e of entries) {
|
|
80
|
+
const segs = e.path.split("/");
|
|
81
|
+
const dirs = segs.slice(0, -1);
|
|
82
|
+
if (dirs.some((d) => ON_PURPOSE_DIRS.has(d))) continue;
|
|
83
|
+
const name = segs[segs.length - 1];
|
|
84
|
+
let kind = null;
|
|
85
|
+
if (LITTER_NAMES.has(name)) kind = name;
|
|
86
|
+
else if (LITTER_EXTS.has(extOf(e.path))) kind = extOf(e.path);
|
|
87
|
+
else if (dirs.some((d) => LITTER_DIRS.has(d))) kind = "build output";
|
|
88
|
+
if (!kind) continue;
|
|
89
|
+
kinds[kind] = (kinds[kind] ?? 0) + 1;
|
|
90
|
+
bytes += e.size;
|
|
91
|
+
items.push({ path: e.path, bytes: e.size, kind });
|
|
92
|
+
}
|
|
93
|
+
items.sort((a, b) => b.bytes - a.bytes || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
|
|
94
|
+
const sortedKinds = Object.fromEntries(Object.entries(kinds).sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)));
|
|
95
|
+
return {
|
|
96
|
+
value: {
|
|
97
|
+
scope: "tracked",
|
|
98
|
+
count: items.length,
|
|
99
|
+
bytes,
|
|
100
|
+
kinds: sortedKinds,
|
|
101
|
+
items: items.slice(0, prereg.HABITS_LIST_N),
|
|
102
|
+
},
|
|
103
|
+
};
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
const CHANGELOG = /(^|\/)(CHANGELOG|HISTORY|RELEASES?|NEWS)[^/]*\.mdx?$/i;
|
|
107
|
+
const FENCE = /^(```|~~~)[\s\S]*?^\1[^\n]*$/gm;
|
|
108
|
+
const TICK = /`([^`\n]{3,200})`/g;
|
|
109
|
+
const LINK = /\]\(\s*<?([^)\s>]{1,200})>?(?:\s+"[^"]*")?\s*\)/g;
|
|
110
|
+
const BAD_CHARS = /[*?{}<>$()|=,'"~@!\\\[\]…]|\.\.\./;
|
|
111
|
+
const DOMAIN_FIRST = /\.(com|org|net|io|dev|app|ai|co|so|sh)$/i;
|
|
112
|
+
|
|
113
|
+
/** Directories docs name that a build or an install creates. */
|
|
114
|
+
const GENERATED_FIRST = new Set([
|
|
115
|
+
"dist", "build", "out", "node_modules", "target", "coverage", ".next", "tmp", "temp",
|
|
116
|
+
]);
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* The repo-relative path candidates a markdown text names, as
|
|
120
|
+
* `{ref, link}` — `link` true for a link target (resolved from the document's
|
|
121
|
+
* directory first). Exported for the test.
|
|
122
|
+
* @param {string} text
|
|
123
|
+
*/
|
|
124
|
+
export function pathCandidates(text) {
|
|
125
|
+
const body = text.replace(FENCE, "");
|
|
126
|
+
const out = new Map();
|
|
127
|
+
const take = (raw, link) => {
|
|
128
|
+
let p = raw.trim();
|
|
129
|
+
if (!link && /\s/.test(p)) return;
|
|
130
|
+
if (link && /^([a-z][a-z0-9+.-]*:|#|\/)/i.test(p)) return;
|
|
131
|
+
// Cut at the first `#` / `?` and trim trailing punctuation by hand: the
|
|
132
|
+
// regex forms (/#.*$/, /[.,;:]+$/) scan quadratically on a run of them.
|
|
133
|
+
for (const mark of ["#", "?"]) { const at = p.indexOf(mark); if (at >= 0) p = p.slice(0, at); }
|
|
134
|
+
p = p.replace(/:\d+(?::\d+|-\d+)?$/, "");
|
|
135
|
+
let end = p.length;
|
|
136
|
+
while (end > 0 && ".,;:".includes(p[end - 1])) end--;
|
|
137
|
+
p = p.slice(0, end);
|
|
138
|
+
if (p.startsWith("./")) p = p.slice(2);
|
|
139
|
+
if (!p || BAD_CHARS.test(p) || p.startsWith("/")) return;
|
|
140
|
+
if (!link && !p.includes("/")) return;
|
|
141
|
+
const last = p.slice(p.lastIndexOf("/", p.length - 2) + 1);
|
|
142
|
+
if (!p.endsWith("/") && !/\.[A-Za-z0-9]{1,8}$/.test(last)) return;
|
|
143
|
+
const first = p.split("/")[0];
|
|
144
|
+
if (DOMAIN_FIRST.test(first) || GENERATED_FIRST.has(first)) return;
|
|
145
|
+
// The ref is the key: a link and a code span naming the same text are one.
|
|
146
|
+
if (!out.has(p)) out.set(p, link);
|
|
147
|
+
};
|
|
148
|
+
let m;
|
|
149
|
+
TICK.lastIndex = 0;
|
|
150
|
+
while ((m = TICK.exec(body))) take(m[1], false);
|
|
151
|
+
LINK.lastIndex = 0;
|
|
152
|
+
while ((m = LINK.exec(body))) take(m[1], true);
|
|
153
|
+
return [...out].map(([ref, link]) => ({ ref, link }));
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* Markdown references that do not resolve in the tree.
|
|
158
|
+
* @param {string[]} paths every tracked path
|
|
159
|
+
* @param {(path: string) => string} textOf the text of a tracked markdown file
|
|
160
|
+
* @param {{HABITS_LIST_N: number, DOCS_MAX_FILES: number, SRC: {excludeDirs: readonly string[]}}} prereg
|
|
161
|
+
*/
|
|
162
|
+
export function measureDocsDrift(paths, textOf, prereg) {
|
|
163
|
+
const docs = paths.filter(
|
|
164
|
+
(p) => /\.mdx?$/i.test(p) && !CHANGELOG.test(p) && !inExcludedDir(p, prereg.SRC.excludeDirs),
|
|
165
|
+
);
|
|
166
|
+
if (!docs.length) return none("the tree holds no markdown files");
|
|
167
|
+
if (docs.length > prereg.DOCS_MAX_FILES) {
|
|
168
|
+
return none(`${docs.length} markdown files is past the ${prereg.DOCS_MAX_FILES} this reading reads`);
|
|
169
|
+
}
|
|
170
|
+
const files = new Set(paths);
|
|
171
|
+
const dirs = new Set();
|
|
172
|
+
for (const p of paths) {
|
|
173
|
+
for (let i = p.indexOf("/"); i >= 0; i = p.indexOf("/", i + 1)) dirs.add(p.slice(0, i));
|
|
174
|
+
}
|
|
175
|
+
// Docs write package-relative paths (`src/index.ts` inside a package's
|
|
176
|
+
// notes), so a reference also resolves when it is the TAIL of a tracked path
|
|
177
|
+
// at a directory boundary. Conservative on purpose: it can hide a real break
|
|
178
|
+
// when a same-tailed file exists elsewhere, and cannot invent one.
|
|
179
|
+
const tails = new Set();
|
|
180
|
+
for (const p of [...files, ...dirs]) {
|
|
181
|
+
tails.add(p);
|
|
182
|
+
for (let i = p.indexOf("/"); i >= 0; i = p.indexOf("/", i + 1)) tails.add(p.slice(i + 1));
|
|
183
|
+
}
|
|
184
|
+
const exists = (p) => tails.has(p.endsWith("/") ? p.slice(0, -1) : p);
|
|
185
|
+
|
|
186
|
+
let refs = 0;
|
|
187
|
+
let broken = 0;
|
|
188
|
+
const items = [];
|
|
189
|
+
for (const doc of docs) {
|
|
190
|
+
const dir = posix.dirname(doc);
|
|
191
|
+
const cands = pathCandidates(textOf(doc));
|
|
192
|
+
const missing = [];
|
|
193
|
+
for (const { ref, link } of cands) {
|
|
194
|
+
const fromDoc = posix.normalize(posix.join(dir, ref));
|
|
195
|
+
const fromRoot = posix.normalize(ref);
|
|
196
|
+
if (fromDoc.startsWith("..") && fromRoot.startsWith("..")) continue;
|
|
197
|
+
refs++;
|
|
198
|
+
const hit = link
|
|
199
|
+
? (!fromDoc.startsWith("..") && exists(fromDoc)) || (!fromRoot.startsWith("..") && exists(fromRoot))
|
|
200
|
+
: (!fromRoot.startsWith("..") && exists(fromRoot)) || (!fromDoc.startsWith("..") && exists(fromDoc));
|
|
201
|
+
if (!hit) missing.push(ref);
|
|
202
|
+
}
|
|
203
|
+
if (missing.length) {
|
|
204
|
+
broken += missing.length;
|
|
205
|
+
items.push({ path: doc, broken: missing.length, of: cands.length, missing: missing.slice(0, 3) });
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
if (refs === 0) return none("no markdown file names a repo path in a code span or a link");
|
|
209
|
+
items.sort((a, b) => b.broken - a.broken || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
|
|
210
|
+
return {
|
|
211
|
+
value: {
|
|
212
|
+
docs: docs.length,
|
|
213
|
+
refs,
|
|
214
|
+
broken,
|
|
215
|
+
docsWithBroken: items.length,
|
|
216
|
+
items: items.slice(0, prereg.HABITS_LIST_N),
|
|
217
|
+
},
|
|
218
|
+
};
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/** Why an earlier row has neither reading. */
|
|
222
|
+
export const WORKSPACE_NOT_HEAD = "read at the newest commit only";
|
|
223
|
+
|
|
224
|
+
/** The row field for a commit that is not the newest one. */
|
|
225
|
+
export function workspaceElsewhere() {
|
|
226
|
+
return { litter: none(WORKSPACE_NOT_HEAD), docsDrift: none(WORKSPACE_NOT_HEAD) };
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
/**
|
|
230
|
+
* The newest commit's workspace row. The only function here that reads git.
|
|
231
|
+
*
|
|
232
|
+
* @param {string} root
|
|
233
|
+
* @param {string} sha
|
|
234
|
+
* @param {{listTree: Function, readBlobs: Function}} git
|
|
235
|
+
* @param {object} prereg
|
|
236
|
+
* @param {string|null} scope
|
|
237
|
+
*/
|
|
238
|
+
export function measureWorkspaceAt(root, sha, git, prereg, scope = null) {
|
|
239
|
+
const entries = scopeEntries(git.listTree(root, sha), scope);
|
|
240
|
+
const mds = entries.filter(
|
|
241
|
+
(e) => /\.mdx?$/i.test(e.path) && !CHANGELOG.test(e.path) && !inExcludedDir(e.path, prereg.SRC.excludeDirs),
|
|
242
|
+
);
|
|
243
|
+
let docsDrift;
|
|
244
|
+
if (mds.length > prereg.DOCS_MAX_FILES) {
|
|
245
|
+
docsDrift = measureDocsDrift(entries.map((e) => e.path), () => "", prereg);
|
|
246
|
+
} else {
|
|
247
|
+
const blobs = git.readBlobs(root, mds.map((e) => e.oid));
|
|
248
|
+
const byPath = new Map(mds.map((e) => [e.path, e.oid]));
|
|
249
|
+
docsDrift = measureDocsDrift(
|
|
250
|
+
entries.map((e) => e.path),
|
|
251
|
+
(p) => blobs.get(byPath.get(p))?.toString("utf8") ?? "",
|
|
252
|
+
prereg,
|
|
253
|
+
);
|
|
254
|
+
}
|
|
255
|
+
return { litter: measureLitter(entries, prereg), docsDrift };
|
|
256
|
+
}
|
package/tools/repohealth/own.mjs
CHANGED
|
@@ -10,9 +10,10 @@
|
|
|
10
10
|
* another's. A repo also knows things about itself no generic metric can — in
|
|
11
11
|
* waterplane, how many of the CLI screen readers have no proof on the
|
|
12
12
|
* installed `claude`. Those are declared by the repo, in a COMMITTED
|
|
13
|
-
* file, and they ride in the series row under `own`, a key no metric
|
|
14
|
-
* reading in `readings.mjs`
|
|
15
|
-
*
|
|
13
|
+
* file, and they ride in the series row under `own`, a key no metric and no
|
|
14
|
+
* reading in `readings.mjs` ever reads. The index reads ONE thing from it: a
|
|
15
|
+
* reading the repo marked as a gate (below). They change no definition, so
|
|
16
|
+
* `PREREG_VERSION` and the pack hash do not move.
|
|
16
17
|
*
|
|
17
18
|
* ── The declaration ────────────────────────────────────────────────────────
|
|
18
19
|
*
|
|
@@ -25,6 +26,19 @@
|
|
|
25
26
|
* "better": "lower", "unit": "signals",
|
|
26
27
|
* "run": ["node", "tools/screenfixtures.mjs", "--reading"] } ] }
|
|
27
28
|
*
|
|
29
|
+
* A reading may be marked a GATE — a line the repo itself calls critical:
|
|
30
|
+
*
|
|
31
|
+
* "gate": { "fails": "below", "at": 60 }
|
|
32
|
+
*
|
|
33
|
+
* `fails` is the side of `at` that fails (`below`: value < at; `above`:
|
|
34
|
+
* value > at; the line itself passes), and it must be the WORSE side of the
|
|
35
|
+
* reading's own `better` — a gate failing when the reading improves is a typo,
|
|
36
|
+
* refused like any other bad field (the reading is then not run, and the
|
|
37
|
+
* index counts the gate as UNKNOWN, never as passed). The engine only carries
|
|
38
|
+
* the declaration into the row; judging it is the index's
|
|
39
|
+
* (`shared/healthindex/coverage.ts`): a failing gate caps the headline, a gate
|
|
40
|
+
* whose reading is absent is unknown.
|
|
41
|
+
*
|
|
28
42
|
* The same file's `central` object re-tunes waterplane's OWN readings — one
|
|
29
43
|
* disabled, or measured by the repo's command instead — and is `central.mjs`'s
|
|
30
44
|
* business: it changes what the index reads, which nothing here ever does.
|
|
@@ -105,11 +119,14 @@ export function parseDeclaration(text) {
|
|
|
105
119
|
}
|
|
106
120
|
const readings = [];
|
|
107
121
|
const problems = [];
|
|
122
|
+
// Entries dropped for want of a key that had asked for a gate: the index counts each as an UNKNOWN gate (`unreadGates`).
|
|
123
|
+
let unreadGates = 0;
|
|
108
124
|
const seen = new Set();
|
|
109
125
|
doc.readings.forEach((raw, i) => {
|
|
110
126
|
const e = raw && typeof raw === "object" ? raw : {};
|
|
111
127
|
if (typeof e.key !== "string" || !KEY_RE.test(e.key)) {
|
|
112
128
|
problems.push(`entry ${i + 1} has no usable "key" (a letter, then up to 39 letters, digits, - or _)`);
|
|
129
|
+
if (e.gate !== undefined) unreadGates++;
|
|
113
130
|
return;
|
|
114
131
|
}
|
|
115
132
|
if (seen.has(e.key)) {
|
|
@@ -122,6 +139,8 @@ export function parseDeclaration(text) {
|
|
|
122
139
|
if (!isStr(e.means) || e.means.length > 400) why.push(`"means" must be one sentence under 400 characters`);
|
|
123
140
|
if (e.better !== "lower" && e.better !== "higher") why.push(`"better" must be "lower" or "higher"`);
|
|
124
141
|
if (e.unit !== undefined && (typeof e.unit !== "string" || e.unit.length > 16)) why.push(`"unit" must be a short word`);
|
|
142
|
+
const gate = gateOf(e.gate, e.better);
|
|
143
|
+
if (gate && gate.invalid) why.push(gate.invalid);
|
|
125
144
|
const runOk = Array.isArray(e.run) && e.run.length >= 1 && e.run.length <= 32
|
|
126
145
|
&& e.run.every((a) => typeof a === "string" && a.length > 0 && a.length <= 512 && !a.includes("\0"));
|
|
127
146
|
if (!runOk) why.push(`"run" must be an argv list of 1–32 non-empty strings`);
|
|
@@ -132,10 +151,28 @@ export function parseDeclaration(text) {
|
|
|
132
151
|
better: e.better === "lower" || e.better === "higher" ? e.better : null,
|
|
133
152
|
unit: typeof e.unit === "string" ? e.unit.slice(0, 16) : "",
|
|
134
153
|
run: runOk ? e.run.slice() : null,
|
|
154
|
+
...(gate ? { gate } : {}),
|
|
135
155
|
...(why.length ? { invalid: `not run — ${why.join("; ")}` } : {}),
|
|
136
156
|
});
|
|
137
157
|
});
|
|
138
|
-
return { readings, problems };
|
|
158
|
+
return { readings, problems, unreadGates };
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* A reading's `gate`, checked: undefined where none is declared,
|
|
163
|
+
* `{ fails, at }` where it is usable, `{ invalid }` where it is not. An
|
|
164
|
+
* invalid gate is still CARRIED (as `{ invalid }`), so the index can say a gate
|
|
165
|
+
* was meant and could not be read rather than silently dropping it.
|
|
166
|
+
*/
|
|
167
|
+
export function gateOf(g, better) {
|
|
168
|
+
if (g === undefined) return undefined;
|
|
169
|
+
const bad = (why) => ({ invalid: `"gate" ${why}` });
|
|
170
|
+
if (!g || typeof g !== "object" || Array.isArray(g)) return bad(`must be { "fails": "below" | "above", "at": <number> }`);
|
|
171
|
+
if (g.fails !== "below" && g.fails !== "above") return bad(`"fails" must be "below" or "above"`);
|
|
172
|
+
if (typeof g.at !== "number" || !Number.isFinite(g.at)) return bad(`"at" must be a number`);
|
|
173
|
+
const worse = better === "higher" ? "below" : better === "lower" ? "above" : null;
|
|
174
|
+
if (worse && g.fails !== worse) return bad(`fails "${g.fails}" but "better" is "${better}": a gate fails on the worse side`);
|
|
175
|
+
return { fails: g.fails, at: g.at };
|
|
139
176
|
}
|
|
140
177
|
|
|
141
178
|
/**
|
|
@@ -224,11 +261,36 @@ export function measureOwn(root, sha, git, opts = {}) {
|
|
|
224
261
|
means: d.means,
|
|
225
262
|
better: d.better,
|
|
226
263
|
unit: d.unit,
|
|
264
|
+
...(d.gate ? { gate: d.gate } : {}),
|
|
227
265
|
value: got.value,
|
|
228
266
|
...(got.reason ? { reason: got.reason } : {}),
|
|
229
267
|
};
|
|
230
268
|
});
|
|
231
|
-
return {
|
|
269
|
+
return {
|
|
270
|
+
file: OWN_FILE, readings,
|
|
271
|
+
...(decl.problems.length ? { problems: decl.problems } : {}),
|
|
272
|
+
...(decl.unreadGates ? { unreadGates: decl.unreadGates } : {}),
|
|
273
|
+
};
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/**
|
|
277
|
+
* The row's `own` where the repo's commands are NOT approved (`--no-own`):
|
|
278
|
+
* nothing is run, but the committed declaration is still read, so the index
|
|
279
|
+
* learns that gates exist and counts each UNKNOWN (never a silent pass).
|
|
280
|
+
* `notRun` marks the row so approval re-measures it (`update`). Undefined where
|
|
281
|
+
* the commit declares nothing.
|
|
282
|
+
*/
|
|
283
|
+
export function notRunOwn(root, sha, git) {
|
|
284
|
+
const text = git.readFileAt(root, sha, OWN_FILE);
|
|
285
|
+
if (text === null) return undefined;
|
|
286
|
+
const decl = parseDeclaration(text);
|
|
287
|
+
if (decl.none) return undefined;
|
|
288
|
+
if (decl.refused) return { file: OWN_FILE, refused: decl.refused };
|
|
289
|
+
const notRun = "not run — this desktop has not approved the repo's committed commands";
|
|
290
|
+
const gates = decl.readings.filter((d) => d.gate).map((d) => ({
|
|
291
|
+
key: d.key, name: d.name, unit: d.unit, gate: d.gate, value: null, reason: notRun,
|
|
292
|
+
}));
|
|
293
|
+
return { file: OWN_FILE, notRun, gates, ...(decl.unreadGates ? { unreadGates: decl.unreadGates } : {}) };
|
|
232
294
|
}
|
|
233
295
|
|
|
234
296
|
/** Whether the commit at `sha` declares own readings — for `plot`, which runs nothing. */
|