@rdjperron/lint 0.5.0 → 0.7.0

package/README.md

@@ -1,12 +1,14 @@
 # @rdjperron/lint
 
 One Oxlint JS plugin, `rdjperron`, with twenty rules against low-evidence code, the config data a
-project spreads into its own `vite.config.ts`, and the check that proves every rule still fires.
+project spreads into its own `vite.config.ts`, the check that proves every rule still fires, and
+the repository checks that hold a repo's documents to their own conventions.
 
 | Entry                    | What it gives you                                                                  |
 | ------------------------ | ---------------------------------------------------------------------------------- |
 | `@rdjperron/lint`        | The plugin. One `jsPlugins` entry, one prefix, twenty rules.                       |
 | `@rdjperron/lint/config` | `recommended`, the override builders, and the `fmt`, `ignore` and `staged` blocks. |
+| `@rdjperron/lint/repo`   | `checkRepo`, three checks on a repo's Markdown links and research names.           |
 | `rdjperron-lint-verify`  | The command that proves every rule still fires. No config, no arguments.           |
 
 Seventeen of the rules are a copy of [dmmulroy/anti-slop](https://github.com/dmmulroy/anti-slop),
@@ -184,6 +186,123 @@ one right after you move `vite-plus`, and in CI.
 One thing not to do: do not delete the fixtures. They are the only thing that catches a rule going
 dead.
 
+## Repository checks
+
+`@rdjperron/lint/repo` is for a repo that keeps living documents at its root and under `docs/`, and
+dated research in `_research/`. Prose can state those conventions and cannot enforce them.
+`checkRepo` reads the tree and returns what breaks them, so a test fails on a dead link or on a
+research entry with no date in its name.
+
+It is plain Node and imports no test runner. You call it from a test of your own:
+
+```ts
+// lib/repo.test.ts
+import { fileURLToPath, URL } from "node:url";
+
+import { CHECKS, checkRepo, HINTS, TITLES } from "@rdjperron/lint/repo";
+import { describe, expect, it } from "vitest";
+
+const faults = checkRepo({ root: fileURLToPath(new URL("..", import.meta.url)) });
+
+describe("the tree", () => {
+  for (const check of CHECKS) {
+    it(TITLES[check], () => {
+      expect(faults[check], HINTS[check]).toEqual([]);
+    });
+  }
+});
+```
+
+Loop over `CHECKS` rather than listing the checks by hand. A check added in a later version then
+runs in your repo the day you move the pin, and nobody has to remember to assert it.
+
+`checkRepo` returns one array of faults per check, empty where the check holds. A fault is one
+line that opens with a path relative to the root, with the line number when the fault has one:
+
+```
+README.md:63 points at docs/not-there.md, which is not there
+_research/notes.md is not named YYYYMMDD.HHMM.topic.md or YYYYMMDD.topic/
+e2e/README.md, named by `linked`, is not there
+```
+
+`TITLES` holds what each check promises, for the test's name. `HINTS` holds one sentence per check
+saying how to fix it, which the example passes to `expect` as the failure message. `CHECKS` is the
+three names: `scans`, `links`, `research`.
+
+`checkRepo` does not throw on a tree or a config it cannot read. A linked document that is a
+directory, a symbolic link that leads nowhere and a root that does not exist are each a fault in
+`scans`, and a link whose percent-escapes do not decode is a fault in `links`.
+
+### What each check holds
+
+| Check      | What it holds                                                                                                                                                                                                                                                                                                         |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `links`    | Every relative Markdown link in the living documents points at a path that exists. So does every link in a research folder's `README.md` that stays inside the research directory. A URL with a scheme, a `//host` and a bare `#anchor` are skipped, and an anchor after a path is dropped before the path is tested. |
+| `research` | Each entry of `_research/` is a file `YYYYMMDD.HHMM.topic.md` or a folder `YYYYMMDD.topic/` that holds a `README.md`. The topic is lowercase letters, digits and hyphens.                                                                                                                                             |
+| `scans`    | Every path the config names is there and is the right kind, a file or a directory. A default that is there is the right kind too. No symbolic link at one of those paths, or that a walk meets, leads nowhere.                                                                                                        |
+
+`scans` exists because a check that reads nothing passes. Move `e2e/README.md` without touching
+the config and its links would stop being read while the test stays green. With `scans` the
+missing document is a fault.
+
+`scans` holds paths, not matches. A repo with no relative link yet is clean, so a repository can
+turn the test on from its first commit, with its root alone for a config. A default that is absent
+is not a fault: a repo may have no `BACKLOG.md`, no `docs` directory and no research yet. A path
+the config names must be there, in `documents`, `docs` or `linked`. The research directory is the
+one exception, and may be absent even when the config names it. Absent means nothing is at the
+path: a symbolic link that leads nowhere is a fault, at a default path too.
+
+The living documents are `README.md`, `AGENTS.md` and `BACKLOG.md` at the root, every `.md` file
+under `docs/`, and the documents `linked` names. Every relative link in them is held, a link into
+the research included.
+
+The research is frozen once written, so the checks read little of it. The body of a research
+entry is not checked for links, since it names paths as they stood on its date. Only a research
+folder's `README.md` has its links held, and only the links that stay inside the research
+directory. A link out of it, to `../../docs/product.md` say, pointed at a document of its day, and
+the living tree has moved on since, so it is not held. This goes for the research directory
+wherever it is, under `docs/` included, and for a document inside it that `linked` names.
+
+### The config
+
+Every path is relative to the root, and `docs`, `./docs` and `docs/` name the same one.
+
+| Field       | Default                              | What it is                                                                                                                                      |
+| ----------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `root`      | required                             | The repository root. A relative one is resolved against the working directory.                                                                  |
+| `skip`      | `node_modules` `_generated` `dist`   | Names the walk of `docs` does not enter, wherever they sit. Yours are added to the default list.                                                |
+| `documents` | `README.md` `AGENTS.md` `BACKLOG.md` | The living documents at the root. A default that is absent is passed over. Yours replace the default list, and each one you name must be there. |
+| `docs`      | `docs`                               | The directory whose every `.md` file is a living document. Left at its default, it may be absent.                                               |
+| `linked`    | none                                 | More living documents, such as `e2e/README.md`. Each must be there.                                                                             |
+| `research`  | `_research`                          | The research directory. It may be absent.                                                                                                       |
+
+`skip` matches a name at any depth, so `skip: ["fixtures"]` leaves out every `fixtures` directory
+under `docs`. It acts on what the walk finds under `docs`, and removes neither a document you name
+in `documents` or `linked` nor an entry of the research directory. To stop holding a named
+document, take it off its list.
+
+`DEFAULT_DOCUMENTS` and `DEFAULT_SKIP` are exported, for a config that adds to a list the field
+replaces.
+
+### What the checks do not do
+
+They hold form, not truth. A link that resolves may point at the wrong document. A research entry
+with a correct name may be empty.
+
+They also leave these alone:
+
+- An anchor is not checked against the headings of its target.
+- A link written as bare text, as `<path>`, inside an HTML tag, with a title in single quotes or
+  with parentheses in its path is not read as a link, or is read wrong.
+- A link that opens with `/` is tested against the filesystem root, not the repository's.
+- A link out of the research is not tested at all, so one that was already dead on its day passes.
+- The date in a research name is not checked to be a real date.
+- Any file directly under the research directory that is not a dated note is a fault, a
+  `README.md` or a `.DS_Store` included.
+- A linked directory is not entered, since it may lead back to one of its own parents.
+
+Reading the documents against the code is still a review's job.
+
 ## The rules
 
 Each rule file opens with the reason the rule exists and the case where it is legitimate to
@@ -248,6 +367,44 @@ Land a new rule at `warn`, fix or scope what fires, then promote it. When a rule
 code or add a narrowly scoped override with the measurement that justifies it. Never weaken the
 rule, add a cast, or rename a symbol to dodge the check.
 
+## Moving from 0.6
+
+0.7.0 takes the decision register out of the repository checks. `checkRepo` no longer reads a
+register, and no longer scans code for the `D<n>` numbers that cited its rows. A repo that keeps a
+register stays on 0.6.0, which stays published.
+
+| Gone                                  | What it was for                                                                                                                     |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| The `register` check                  | It held `docs/decisions.md` to one well-formed line per row, each number given once.                                                |
+| The `citations` check                 | It held every `D<n>` in the scanned files to a live row of the register.                                                            |
+| `codeRoots`                           | The directories scanned for citations. It was required, so delete it from your config.                                              |
+| `extensions` and `DEFAULT_EXTENSIONS` | The extensions the citation scan read.                                                                                              |
+| `register`                            | The path of the register.                                                                                                           |
+| `leftOut`                             | Paths left out of the citation scan, for files whose contents read like `D<n>` numbers. Under `docs`, `skip` does the same by name. |
+
+`CHECKS` is now `scans`, `links`, `research`, and `TITLES`, `HINTS` and the returned faults carry
+those three keys. A test that loops over `CHECKS` needs no other edit. A test that filtered the
+faults by hand to live without a register deletes the filter.
+
+Three things change in what stays:
+
+- `scans` no longer asks for a register or for code roots, and a default that is absent is not a
+  fault: a `docs` directory the config does not name, and any of `README.md`, `AGENTS.md` and
+  `BACKLOG.md` when the config leaves `documents` alone. A path the config names must still be
+  there.
+- A research folder's `README.md` is held only for the links that stay inside the research
+  directory. A link from it to a living document that has since moved or gone no longer fails.
+  The same goes for a document inside the research directory that `linked` names: its links out
+  of the research are no longer held.
+- `skip` acts on the walk of `docs` alone, since no code root and no file at the root is walked
+  any more.
+
+## Moving from 0.5
+
+Nothing is removed and nothing changes. 0.6.0 adds `@rdjperron/lint/repo`. A repo that carries the
+checks as a test file of its own replaces that file with the example under "Repository checks",
+and keeps only its config.
+
 ## Moving from 0.4
 
 Nothing is removed. One builder changed what it does, and three are new.

package/dist/repo.d.mts

@@ -0,0 +1,60 @@
+//#region src/repo.d.ts
+/**
+ * The promises a repository's prose can only state, held as faults instead.
+ *
+ *   - a relative Markdown link points at something that is there;
+ *   - a research entry is named by its date, and a dated folder opens with a README;
+ *   - every path the config names is there.
+ *
+ * Every path in a fault is relative to the root, so it reads as the path you would type to open
+ * the offender. Nothing here imports a test runner: the consumer's test asserts on what
+ * `checkRepo` returns. It never throws on a tree or a config it cannot read: that is a fault too.
+ */
+export interface RepoConfig {
+  /**
+   * The repository root, absolute. Every other path in this config is relative to it, and
+   * `docs`, `./docs` and `docs/` name the same one.
+   */
+  root: string;
+  /**
+   * Directory and file names the walk of `docs` does not enter, wherever they sit. Added to
+   * `DEFAULT_SKIP`.
+   */
+  skip?: readonly string[];
+  /**
+   * The living documents at the root. Replaces `DEFAULT_DOCUMENTS`, any of which a repo may
+   * lack.
+   */
+  documents?: readonly string[];
+  /**
+   * The directory whose every Markdown file is a living document. `docs` by default, and a repo
+   * that names none may have none.
+   */
+  docs?: string;
+  /** More documents whose links are held as the living ones' are. */
+  linked?: readonly string[];
+  /** The research directory. `_research` by default, and a repo may have none yet. */
+  research?: string;
+}
+export declare const CHECKS: readonly ["scans", "links", "research"];
+export type Check = (typeof CHECKS)[number];
+/** The faults of each check, empty where the check holds. */
+export type RepoFaults = { readonly [check in Check]: readonly string[]; };
+/** What each check promises, for the title of the consumer's test. */
+export declare const TITLES: {
+  scans: string;
+  links: string;
+  research: string;
+};
+/** What to do about a failing check, for the message of the consumer's assertion. */
+export declare const HINTS: {
+  scans: string;
+  links: string;
+  research: string;
+};
+export declare const DEFAULT_DOCUMENTS: readonly string[];
+/** Vendored, generated and built trees. */
+export declare const DEFAULT_SKIP: readonly string[];
+export declare function checkRepo(config: RepoConfig): RepoFaults;
+//#endregion
+//# sourceMappingURL=repo.d.mts.map

package/dist/repo.mjs

@@ -0,0 +1,221 @@
+import { lstatSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, posix, relative, resolve, sep } from "node:path";
+//#region src/repo.ts
+/**
+* The promises a repository's prose can only state, held as faults instead.
+*
+*   - a relative Markdown link points at something that is there;
+*   - a research entry is named by its date, and a dated folder opens with a README;
+*   - every path the config names is there.
+*
+* Every path in a fault is relative to the root, so it reads as the path you would type to open
+* the offender. Nothing here imports a test runner: the consumer's test asserts on what
+* `checkRepo` returns. It never throws on a tree or a config it cannot read: that is a fault too.
+*/
+const CHECKS = [
+	"scans",
+	"links",
+	"research"
+];
+/** What each check promises, for the title of the consumer's test. */
+const TITLES = {
+	scans: "every path the config names is there, and every symbolic link leads somewhere",
+	links: "every relative Markdown link resolves",
+	research: "every research entry is named by its date, and every dated folder has a README"
+};
+/** What to do about a failing check, for the message of the consumer's assertion. */
+const HINTS = {
+	scans: "A check that reads nothing passes on nothing. Correct the path in the config, or remove it with the thing it named.",
+	links: "Fix the path, or delete the link with the thing it pointed at.",
+	research: "The research sorts by name, so the name carries the date. Date an entry by the day it was opened, and give a folder a README that says what is in it."
+};
+const DEFAULT_DOCUMENTS = [
+	"README.md",
+	"AGENTS.md",
+	"BACKLOG.md"
+];
+/** Vendored, generated and built trees. */
+const DEFAULT_SKIP = [
+	"node_modules",
+	"_generated",
+	"dist"
+];
+function kindOf(tree, path) {
+	try {
+		return statSync(join(tree.root, path)).isDirectory() ? "directory" : "file";
+	} catch {
+		return "absent";
+	}
+}
+function isSymbolicLink(tree, path) {
+	try {
+		return lstatSync(join(tree.root, path)).isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+function names(tree, path) {
+	try {
+		return readdirSync(join(tree.root, path)).toSorted();
+	} catch {
+		return [];
+	}
+}
+function child(base, name) {
+	return base === "" ? name : `${base}/${name}`;
+}
+function walk(tree, base) {
+	return names(tree, base).flatMap((name) => {
+		const path = child(base, name);
+		if (tree.skip.has(name)) return [];
+		const kind = kindOf(tree, path);
+		if (kind === "file") return [path];
+		if (kind === "absent") tree.broken.add(path);
+		return kind === "directory" && !isSymbolicLink(tree, path) ? walk(tree, path) : [];
+	});
+}
+/** `docs`, `./docs` and `docs/` are one path, and the root itself is the empty one. */
+function normal(path) {
+	const clean = posix.normalize(path).replace(/\/+$/, "");
+	return clean === "." ? "" : clean;
+}
+function lineOf(source, index) {
+	return source.slice(0, index).split("\n").length;
+}
+/** A single note, `YYYYMMDD.HHMM.topic.md`. */
+const DATED_NOTE = /^\d{8}\.\d{4}\.[a-z0-9-]+\.md$/;
+/** Research of several files, `YYYYMMDD.topic/`. */
+const DATED_FOLDER = /^\d{8}\.[a-z0-9-]+$/;
+function researchFaults(tree, entries) {
+	return entries.flatMap((entry) => {
+		if (!(entry.folder ? DATED_FOLDER : DATED_NOTE).test(entry.name)) return [`${entry.path} is not named YYYYMMDD.HHMM.topic.md or YYYYMMDD.topic/`];
+		return entry.folder && kindOf(tree, `${entry.path}/README.md`) !== "file" ? [`${entry.path}/ has no README.md`] : [];
+	});
+}
+/** `](target)`, with an optional title. Bare `path.md` inside backticks is not a link. */
+const LINK = /\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+/** A scheme, a protocol-relative host or a bare anchor: the target is outside the tree. */
+const OUTSIDE = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i;
+function decoded(target) {
+	try {
+		return decodeURI(target.split("#")[0] ?? "");
+	} catch {
+		return;
+	}
+}
+function linksIn(tree, file) {
+	const source = readFileSync(join(tree.root, file), "utf8");
+	return [...source.matchAll(LINK)].flatMap((match) => {
+		const target = match[1] ?? "";
+		const path = decoded(target);
+		if (OUTSIDE.test(target)) return [];
+		const points = path === void 0 ? void 0 : relative(tree.root, resolve(tree.root, dirname(file), path)).replaceAll(sep, "/");
+		return [{
+			from: file,
+			target,
+			line: lineOf(source, match.index),
+			points
+		}];
+	});
+}
+function linkFaults(tree, links) {
+	return links.flatMap((link) => {
+		const at = `${link.from}:${link.line} points at ${link.target}`;
+		if (link.points === void 0) return [`${at}, whose percent-escapes do not decode`];
+		return kindOf(tree, link.points) === "absent" ? [`${at}, which is not there`] : [];
+	});
+}
+function isUnder(path, base) {
+	return base === "" || path === base || path.startsWith(`${base}/`);
+}
+function allNamed(by, paths, want) {
+	return paths.map((path) => ({
+		path: normal(path),
+		by,
+		want
+	}));
+}
+function namedOr(option, path, fallback, want) {
+	return path === void 0 ? {
+		path: fallback,
+		by: `the default of \`${option}\``,
+		want
+	} : {
+		path: normal(path),
+		by: `named by \`${option}\``,
+		want
+	};
+}
+function namedFault(tree, named) {
+	const kind = kindOf(tree, named.path);
+	if (kind === named.want) return [];
+	return [`${named.path === "" ? "." : named.path}, ${named.by}, is ${kind === "absent" ? "not there" : `not a ${named.want}`}`];
+}
+function usable(tree, named) {
+	return named.flatMap((one) => kindOf(tree, one.path) === one.want ? [one.path] : []);
+}
+const NO_FAULTS = {
+	scans: [],
+	links: [],
+	research: []
+};
+function checkRepo(config) {
+	const tree = {
+		root: resolve(config.root),
+		skip: /* @__PURE__ */ new Set([...DEFAULT_SKIP, ...config.skip ?? []]),
+		broken: /* @__PURE__ */ new Set()
+	};
+	if (kindOf(tree, "") !== "directory") return {
+		...NO_FAULTS,
+		scans: [`${tree.root}, named by \`root\`, is not a directory`]
+	};
+	const docs = namedOr("docs", config.docs, "docs", "directory");
+	const research = namedOr("research", config.research, "_research", "directory");
+	const documents = config.documents === void 0 ? allNamed("a default of `documents`", DEFAULT_DOCUMENTS, "file") : allNamed("named by `documents`", config.documents, "file");
+	const linked = allNamed("named by `linked`", config.linked ?? [], "file");
+	const entries = names(tree, research.path).flatMap((name) => {
+		const path = child(research.path, name);
+		const kind = kindOf(tree, path);
+		if (kind === "absent") tree.broken.add(path);
+		return kind === "absent" ? [] : [{
+			path,
+			name,
+			folder: kind === "directory"
+		}];
+	});
+	const frozen = (file) => isUnder(file, research.path);
+	const held = (link) => !frozen(link.from) || link.points === void 0 || frozen(link.points);
+	const living = [
+		...usable(tree, documents),
+		...walk(tree, docs.path).filter((file) => file.endsWith(".md") && !frozen(file)),
+		...usable(tree, linked)
+	];
+	const linking = /* @__PURE__ */ new Set([...living, ...entries.flatMap((entry) => {
+		const readme = `${entry.path}/README.md`;
+		return entry.folder && kindOf(tree, readme) === "file" ? [readme] : [];
+	})]);
+	const mayBeAbsent = /* @__PURE__ */ new Set([
+		...config.documents === void 0 ? documents : [],
+		...config.docs === void 0 ? [docs] : [],
+		research
+	]);
+	return {
+		scans: [...[
+			...documents,
+			docs,
+			...linked,
+			research
+		].flatMap((one) => {
+			if (kindOf(tree, one.path) !== "absent") return [one];
+			if (!isSymbolicLink(tree, one.path)) return mayBeAbsent.has(one) ? [] : [one];
+			tree.broken.add(one.path);
+			return [];
+		}).flatMap((one) => namedFault(tree, one)), ...[...tree.broken].toSorted().map((path) => `${path} is a symbolic link that leads nowhere`)],
+		links: linkFaults(tree, [...linking].flatMap((file) => linksIn(tree, file)).filter(held)),
+		research: researchFaults(tree, entries)
+	};
+}
+//#endregion
+export { CHECKS, DEFAULT_DOCUMENTS, DEFAULT_SKIP, HINTS, TITLES, checkRepo };
+
+//# sourceMappingURL=repo.mjs.map

package/dist/repo.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo.mjs","names":[],"sources":["../src/repo.ts"],"sourcesContent":["/**\n * The promises a repository's prose can only state, held as faults instead.\n *\n *   - a relative Markdown link points at something that is there;\n *   - a research entry is named by its date, and a dated folder opens with a README;\n *   - every path the config names is there.\n *\n * Every path in a fault is relative to the root, so it reads as the path you would type to open\n * the offender. Nothing here imports a test runner: the consumer's test asserts on what\n * `checkRepo` returns. It never throws on a tree or a config it cannot read: that is a fault too.\n */\n\nimport { lstatSync, readdirSync, readFileSync, statSync } from \"node:fs\";\nimport { dirname, join, posix, relative, resolve, sep } from \"node:path\";\n\nexport interface RepoConfig {\n  /**\n   * The repository root, absolute. Every other path in this config is relative to it, and\n   * `docs`, `./docs` and `docs/` name the same one.\n   */\n  root: string;\n  /**\n   * Directory and file names the walk of `docs` does not enter, wherever they sit. Added to\n   * `DEFAULT_SKIP`.\n   */\n  skip?: readonly string[];\n  /**\n   * The living documents at the root. Replaces `DEFAULT_DOCUMENTS`, any of which a repo may\n   * lack.\n   */\n  documents?: readonly string[];\n  /**\n   * The directory whose every Markdown file is a living document. `docs` by default, and a repo\n   * that names none may have none.\n   */\n  docs?: string;\n  /** More documents whose links are held as the living ones' are. */\n  linked?: readonly string[];\n  /** The research directory. `_research` by default, and a repo may have none yet. */\n  research?: string;\n}\n\nexport const CHECKS = [\"scans\", \"links\", \"research\"] as const;\n\nexport type Check = (typeof CHECKS)[number];\n\n/** The faults of each check, empty where the check holds. */\nexport type RepoFaults = { readonly [check in Check]: readonly string[] };\n\n/** What each check promises, for the title of the consumer's test. */\nexport const TITLES = {\n  scans: \"every path the config names is there, and every symbolic link leads somewhere\",\n  links: \"every relative Markdown link resolves\",\n  research: \"every research entry is named by its date, and every dated folder has a README\",\n} satisfies { readonly [check in Check]: string };\n\n/** What to do about a failing check, for the message of the consumer's assertion. */\nexport const HINTS = {\n  scans:\n    \"A check that reads nothing passes on nothing. Correct the path in the config, or remove it \" +\n    \"with the thing it named.\",\n  links: \"Fix the path, or delete the link with the thing it pointed at.\",\n  research:\n    \"The research sorts by name, so the name carries the date. Date an entry by the day it was \" +\n    \"opened, and give a folder a README that says what is in it.\",\n} satisfies { readonly [check in Check]: string };\n\nexport const DEFAULT_DOCUMENTS: readonly string[] = [\"README.md\", \"AGENTS.md\", \"BACKLOG.md\"];\n\n/** Vendored, generated and built trees. */\nexport const DEFAULT_SKIP: readonly string[] = [\"node_modules\", \"_generated\", \"dist\"];\n\ninterface Tree {\n  root: string;\n  skip: ReadonlySet<string>;\n  /** Symbolic links a walk met that lead nowhere. */\n  broken: Set<string>;\n}\n\ntype Kind = \"file\" | \"directory\" | \"absent\";\n\nfunction kindOf(tree: Tree, path: string): Kind {\n  try {\n    return statSync(join(tree.root, path)).isDirectory() ? \"directory\" : \"file\";\n  } catch {\n    return \"absent\";\n  }\n}\n\nfunction isSymbolicLink(tree: Tree, path: string): boolean {\n  try {\n    return lstatSync(join(tree.root, path)).isSymbolicLink();\n  } catch {\n    return false;\n  }\n}\n\nfunction names(tree: Tree, path: string): string[] {\n  try {\n    return readdirSync(join(tree.root, path)).toSorted();\n  } catch {\n    return [];\n  }\n}\n\nfunction child(base: string, name: string): string {\n  return base === \"\" ? name : `${base}/${name}`;\n}\n\n// A linked directory is not entered: it may lead back to one of its own parents.\nfunction walk(tree: Tree, base: string): string[] {\n  return names(tree, base).flatMap((name) => {\n    const path = child(base, name);\n    if (tree.skip.has(name)) return [];\n    const kind = kindOf(tree, path);\n    if (kind === \"file\") return [path];\n    if (kind === \"absent\") tree.broken.add(path);\n    return kind === \"directory\" && !isSymbolicLink(tree, path) ? walk(tree, path) : [];\n  });\n}\n\n/** `docs`, `./docs` and `docs/` are one path, and the root itself is the empty one. */\nfunction normal(path: string): string {\n  const clean = posix.normalize(path).replace(/\\/+$/, \"\");\n  return clean === \".\" ? \"\" : clean;\n}\n\nfunction lineOf(source: string, index: number): number {\n  return source.slice(0, index).split(\"\\n\").length;\n}\n\n/** A single note, `YYYYMMDD.HHMM.topic.md`. */\nconst DATED_NOTE = /^\\d{8}\\.\\d{4}\\.[a-z0-9-]+\\.md$/;\n\n/** Research of several files, `YYYYMMDD.topic/`. */\nconst DATED_FOLDER = /^\\d{8}\\.[a-z0-9-]+$/;\n\ninterface Entry {\n  path: string;\n  name: string;\n  folder: boolean;\n}\n\nfunction researchFaults(tree: Tree, entries: readonly Entry[]): string[] {\n  return entries.flatMap((entry) => {\n    if (!(entry.folder ? DATED_FOLDER : DATED_NOTE).test(entry.name)) {\n      return [`${entry.path} is not named YYYYMMDD.HHMM.topic.md or YYYYMMDD.topic/`];\n    }\n    return entry.folder && kindOf(tree, `${entry.path}/README.md`) !== \"file\"\n      ? [`${entry.path}/ has no README.md`]\n      : [];\n  });\n}\n\n/** `](target)`, with an optional title. Bare `path.md` inside backticks is not a link. */\nconst LINK = /\\]\\(([^)\\s]+)(?:\\s+\"[^\"]*\")?\\)/g;\n\n/** A scheme, a protocol-relative host or a bare anchor: the target is outside the tree. */\nconst OUTSIDE = /^(?:[a-z][a-z0-9+.-]*:|\\/\\/|#)/i;\n\ninterface Link {\n  from: string;\n  target: string;\n  line: number;\n  /** Where the target leads, relative to the root. Absent when its escapes do not decode. */\n  points: string | undefined;\n}\n\nfunction decoded(target: string): string | undefined {\n  try {\n    return decodeURI(target.split(\"#\")[0] ?? \"\");\n  } catch {\n    return undefined;\n  }\n}\n\nfunction linksIn(tree: Tree, file: string): Link[] {\n  const source = readFileSync(join(tree.root, file), \"utf8\");\n  return [...source.matchAll(LINK)].flatMap((match) => {\n    const target = match[1] ?? \"\";\n    const path = decoded(target);\n    if (OUTSIDE.test(target)) return [];\n    // `relative` answers with `\\` on Windows, and every path here has `/` between its names.\n    const points =\n      path === undefined\n        ? undefined\n        : relative(tree.root, resolve(tree.root, dirname(file), path)).replaceAll(sep, \"/\");\n    return [{ from: file, target, line: lineOf(source, match.index), points }];\n  });\n}\n\nfunction linkFaults(tree: Tree, links: readonly Link[]): string[] {\n  return links.flatMap((link) => {\n    const at = `${link.from}:${link.line} points at ${link.target}`;\n    if (link.points === undefined) return [`${at}, whose percent-escapes do not decode`];\n    return kindOf(tree, link.points) === \"absent\" ? [`${at}, which is not there`] : [];\n  });\n}\n\nfunction isUnder(path: string, base: string): boolean {\n  return base === \"\" || path === base || path.startsWith(`${base}/`);\n}\n\ninterface Named {\n  path: string;\n  /** How the path came to be named, for the fault. */\n  by: string;\n  want: Kind;\n}\n\nfunction allNamed(by: string, paths: readonly string[], want: Kind): Named[] {\n  return paths.map((path) => ({ path: normal(path), by, want }));\n}\n\nfunction namedOr(option: string, path: string | undefined, fallback: string, want: Kind): Named {\n  return path === undefined\n    ? { path: fallback, by: `the default of \\`${option}\\``, want }\n    : { path: normal(path), by: `named by \\`${option}\\``, want };\n}\n\nfunction namedFault(tree: Tree, named: Named): string[] {\n  const kind = kindOf(tree, named.path);\n  if (kind === named.want) return [];\n  const shown = named.path === \"\" ? \".\" : named.path;\n  return [`${shown}, ${named.by}, is ${kind === \"absent\" ? \"not there\" : `not a ${named.want}`}`];\n}\n\nfunction usable(tree: Tree, named: readonly Named[]): string[] {\n  return named.flatMap((one) => (kindOf(tree, one.path) === one.want ? [one.path] : []));\n}\n\nconst NO_FAULTS: RepoFaults = { scans: [], links: [], research: [] };\n\nexport function checkRepo(config: RepoConfig): RepoFaults {\n  const tree: Tree = {\n    root: resolve(config.root),\n    skip: new Set([...DEFAULT_SKIP, ...(config.skip ?? [])]),\n    broken: new Set(),\n  };\n  if (kindOf(tree, \"\") !== \"directory\") {\n    return { ...NO_FAULTS, scans: [`${tree.root}, named by \\`root\\`, is not a directory`] };\n  }\n\n  const docs = namedOr(\"docs\", config.docs, \"docs\", \"directory\");\n  const research = namedOr(\"research\", config.research, \"_research\", \"directory\");\n  const documents =\n    config.documents === undefined\n      ? allNamed(\"a default of `documents`\", DEFAULT_DOCUMENTS, \"file\")\n      : allNamed(\"named by `documents`\", config.documents, \"file\");\n  const linked = allNamed(\"named by `linked`\", config.linked ?? [], \"file\");\n\n  const entries = names(tree, research.path).flatMap((name) => {\n    const path = child(research.path, name);\n    const kind = kindOf(tree, path);\n    if (kind === \"absent\") tree.broken.add(path);\n    return kind === \"absent\" ? [] : [{ path, name, folder: kind === \"directory\" }];\n  });\n\n  // Inside the research only a folder's README is held, and only for the links that stay inside\n  // it: an entry is frozen once it is on the main branch, and the living tree moves on.\n  const frozen = (file: string): boolean => isUnder(file, research.path);\n  const held = (link: Link): boolean =>\n    !frozen(link.from) || link.points === undefined || frozen(link.points);\n\n  const living = [\n    ...usable(tree, documents),\n    ...walk(tree, docs.path).filter((file) => file.endsWith(\".md\") && !frozen(file)),\n    ...usable(tree, linked),\n  ];\n  const linking = new Set([\n    ...living,\n    ...entries.flatMap((entry) => {\n      const readme = `${entry.path}/README.md`;\n      return entry.folder && kindOf(tree, readme) === \"file\" ? [readme] : [];\n    }),\n  ]);\n\n  // A default names a place a repo may not have, and the research one it may not have yet. A\n  // path the config names has to be there.\n  const mayBeAbsent = new Set([\n    ...(config.documents === undefined ? documents : []),\n    ...(config.docs === undefined ? [docs] : []),\n    research,\n  ]);\n  // Absent means nothing is at the path, and a link that leads nowhere is something.\n  const expected = [...documents, docs, ...linked, research].flatMap((one) => {\n    if (kindOf(tree, one.path) !== \"absent\") return [one];\n    if (!isSymbolicLink(tree, one.path)) return mayBeAbsent.has(one) ? [] : [one];\n    tree.broken.add(one.path);\n    return [];\n  });\n\n  return {\n    scans: [\n      ...expected.flatMap((one) => namedFault(tree, one)),\n      ...[...tree.broken].toSorted().map((path) => `${path} is a symbolic link that leads nowhere`),\n    ],\n    links: linkFaults(tree, [...linking].flatMap((file) => linksIn(tree, file)).filter(held)),\n    research: researchFaults(tree, entries),\n  };\n}\n"],"mappings":"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"}

package/dist/verify.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { s as plugin, t as RULE_IDS } from "./config-CD2iCM6L.mjs";
 import { createRequire } from "node:module";
-import { spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdtempSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 //#region src/verify.ts
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rdjperron/lint",
-  "version": "0.5.0",
-  "description": "One Oxlint JS plugin, `rdjperron`: 20 rules against low-evidence code, with the config data, the fixture that proves each rule fires, and the command that checks it.",
+  "version": "0.7.0",
+  "description": "One Oxlint JS plugin, `rdjperron`: 20 rules against low-evidence code, with the config data, the fixture that proves each rule fires, the command that checks it, and the repository checks that hold a repo's Markdown links and research names.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,8 +26,22 @@
       "types": "./dist/config.d.mts",
       "default": "./dist/config.mjs"
     },
+    "./repo": {
+      "types": "./dist/repo.d.mts",
+      "default": "./dist/repo.mjs"
+    },
     "./package.json": "./package.json"
   },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test",
+    "check": "vp check",
+    "typecheck": "tsc --noEmit",
+    "verify:lint-fixtures": "node src/verify.ts --plugin ./src/index.ts",
+    "ready": "vp check && vp test && vp run typecheck && vp run build && vp run verify:lint-fixtures && vp pm pack -- --dry-run",
+    "prepare": "vp config",
+    "prepublishOnly": "vp run ready"
+  },
   "dependencies": {
     "@oxlint/plugins": "^1.79.0"
   },
@@ -48,12 +62,5 @@
   "engines": {
     "node": ">=24"
   },
-  "scripts": {
-    "build": "vp pack",
-    "test": "vp test",
-    "check": "vp check",
-    "typecheck": "tsc --noEmit",
-    "verify:lint-fixtures": "node src/verify.ts --plugin ./src/index.ts",
-    "ready": "vp check && vp test && vp run typecheck && vp run build && vp run verify:lint-fixtures && vp pm pack -- --dry-run"
-  }
-}
+  "packageManager": "pnpm@12.4.2"
+}