@jterrazz/typescript 9.3.0 → 10.1.0

package/lib/check-markdown.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+
+/**
+ * A repository's prose, held to what a page owes its reader: its coordinates
+ * resolve, and its blocks breathe.
+ *
+ * Two families. **Coordinates** — every relative link and every backticked
+ * repo-relative path names something on disk, because a page that cites a file
+ * it cannot reach has already drifted from the tree it describes. **Floors** —
+ * the mechanical half of "How a page reads": a paragraph that runs past twelve
+ * lines, a fenced block that runs fifteen without breathing, a `##` section of
+ * thirty lines of prose broken by neither a `###` nor a list. The three numbers
+ * are a floor, not the craft the doctrine asks for; the gap between them is a
+ * reader's pass, not a red gate.
+ *
+ * Usage: node check-markdown.js [root] [--ignore-pattern <glob>]…
+ *
+ * One line per violation, `<rule>  <path>  <message>`. Exit code: 0 when the
+ * prose holds, 1 otherwise. No `--fix`: there is no rewrite that can split a
+ * paragraph into the two ideas it was carrying.
+ */
+
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { argv, exit, stdout } from 'node:process';
+
+import { ignorePatternsOf, readText, trackedFiles } from './tracked-files.js';
+
+/** A paragraph, or one list item with its continuations, past this is a wall. */
+const PROSE_BLOCK_LIMIT = 12;
+
+/** A fenced block is measured by its longest run with no blank line in it. */
+const FENCE_RUN_LIMIT = 15;
+
+/** A `##` section carrying neither a `###` nor a list may run this long. */
+const SECTION_PROSE_LIMIT = 30;
+
+/** A generated projection is a machine's output, and its shape is its compiler's. */
+const GENERATED = 'docs/reference/';
+
+const LINK = /!?\[[^\]]*\]\((?<target>[^)\s]+)\)/gu;
+
+/**
+ * A backticked string that reads as a path into this repository. The roster of
+ * opening segments is closed on purpose: without it every `a/b` in a sentence
+ * — a URL fragment, a ratio, a unit — would be read as a coordinate.
+ *
+ * `docs/` and `src/` are deliberately absent, and for one reason: every
+ * repository has both, so a page teaching a convention writes `src/index.ts`
+ * or `docs/03-testing.md` about the READER's tree, not about its own. A
+ * relative link into either is still judged — that one names a real target.
+ */
+const BACKTICK_PATH = /`(?<path>(?:apps|bin|lib|packages|presets|specs|tests)\/[a-zA-Z\d._/-]+)`/gu;
+
+/** A fenced example illustrates; it does not cite. */
+const withoutFences = (markdown) => markdown.replaceAll(/^```.*?^```/gmsu, '');
+
+/** A harness header at the very top of a file: metadata, and never a paragraph. */
+const FRONTMATTER = /^---\n.*?\n---\n/su;
+const FENCE = /^\s*(?:```|~~~)/u;
+const LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s/u;
+const TABLE_ROW = /^\s*\|/u;
+const HEADING = /^(?<hashes>#{1,6})\s/u;
+
+/** Blanked line for line, so a reported line number still points at the page's. */
+function lines(markdown) {
+    return markdown.replace(FRONTMATTER, (block) => block.replaceAll(/[^\n]/gu, '')).split('\n');
+}
+
+/**
+ * A block is the reader's unit, not the parser's: a paragraph, or a single list
+ * item with its continuations. A blank line, a heading, a table row, a fence or
+ * the next list marker all stop one.
+ */
+function longProseBlocks(markdown) {
+    let inFence = false;
+    let length = 0;
+    let start = 0;
+    const found = [];
+    const close = () => {
+        if (length > PROSE_BLOCK_LIMIT) {
+            found.push(
+                `a block of ${length} lines at line ${start} — the floor is ${PROSE_BLOCK_LIMIT}`,
+            );
+        }
+        length = 0;
+    };
+
+    for (const [index, line] of lines(markdown).entries()) {
+        if (FENCE.test(line)) {
+            close();
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence) {
+            continue;
+        }
+        if (line.trim() === '' || HEADING.test(line) || TABLE_ROW.test(line)) {
+            close();
+            continue;
+        }
+        if (LIST_ITEM.test(line)) {
+            close();
+        }
+        if (length === 0) {
+            start = index + 1;
+        }
+        length += 1;
+    }
+    close();
+
+    return found;
+}
+
+/** A fenced block is measured by its longest unbroken run: grouping is blank lines. */
+function airlessFences(markdown) {
+    let inFence = false;
+    let fenceStart = 0;
+    let run = 0;
+    const found = [];
+    const close = () => {
+        if (run > FENCE_RUN_LIMIT) {
+            found.push(
+                `a fenced block at line ${fenceStart} runs ${run} lines unbroken — the floor is ${FENCE_RUN_LIMIT}`,
+            );
+        }
+        run = 0;
+    };
+
+    for (const [index, line] of lines(markdown).entries()) {
+        if (FENCE.test(line)) {
+            if (inFence) {
+                close();
+            } else {
+                fenceStart = index + 1;
+                run = 0;
+            }
+            inFence = !inFence;
+            continue;
+        }
+        if (!inFence) {
+            continue;
+        }
+        if (line.trim() === '') {
+            close();
+            continue;
+        }
+        run += 1;
+    }
+    close();
+
+    return found;
+}
+
+/** A `##` section of pure prose, carrying neither a `###` nor a list to break it up. */
+function flatSections(markdown) {
+    let inFence = false;
+    let title = '';
+    let start = 0;
+    let prose = 0;
+    let broken = false;
+    const found = [];
+    const close = () => {
+        if (title !== '' && !broken && prose > SECTION_PROSE_LIMIT) {
+            found.push(
+                `"${title}" at line ${start} runs ${prose} lines of prose with no ### and no list`,
+            );
+        }
+    };
+
+    for (const [index, line] of lines(markdown).entries()) {
+        if (FENCE.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence) {
+            continue;
+        }
+
+        const heading = HEADING.exec(line);
+        if (heading !== null) {
+            const level = (heading.groups?.hashes ?? '').length;
+            if (level <= 2) {
+                close();
+                /* An h1 titles the page; it is not one of its questions. */
+                title = level === 2 ? line.trim() : '';
+                start = index + 1;
+                prose = 0;
+                broken = false;
+            } else {
+                broken = true;
+            }
+            continue;
+        }
+        if (LIST_ITEM.test(line)) {
+            broken = true;
+            continue;
+        }
+        if (line.trim() !== '' && !TABLE_ROW.test(line)) {
+            prose += 1;
+        }
+    }
+    close();
+
+    return found;
+}
+
+/** A link a page owns: not a URL, not an anchor, not a mail address. */
+function isRelative(target) {
+    return (
+        target !== '' &&
+        !target.startsWith('http') &&
+        !target.startsWith('#') &&
+        !target.startsWith('mailto:') &&
+        !target.startsWith('<')
+    );
+}
+
+/** Every violation of one page, in the order the rules are declared. */
+function auditPage(root, path, markdown) {
+    const found = [];
+    const cited = withoutFences(markdown);
+
+    for (const match of cited.matchAll(LINK)) {
+        const { target } = match.groups;
+        const clean = target.split('#')[0] ?? '';
+        if (!isRelative(target) || clean === '') {
+            continue;
+        }
+        if (!existsSync(resolve(root, dirname(path), clean))) {
+            found.push({
+                message: `${target} resolves to nothing on disk`,
+                rule: 'markdown-link-missing',
+            });
+        }
+    }
+
+    for (const match of cited.matchAll(BACKTICK_PATH)) {
+        const target = match.groups.path.replace(/\/$/u, '');
+        if (!existsSync(join(root, target)) && !existsSync(resolve(root, dirname(path), target))) {
+            found.push({
+                message: `\`${target}\` names nothing on disk`,
+                rule: 'markdown-path-missing',
+            });
+        }
+    }
+
+    for (const reason of longProseBlocks(markdown)) {
+        found.push({ message: reason, rule: 'markdown-block-long' });
+    }
+    for (const reason of airlessFences(markdown)) {
+        found.push({ message: reason, rule: 'markdown-fence-long' });
+    }
+    for (const reason of flatSections(markdown)) {
+        found.push({ message: reason, rule: 'markdown-section-flat' });
+    }
+
+    return found;
+}
+
+const root = resolve(argv.slice(2).find((argument) => !argument.startsWith('--')) ?? '.');
+const pages = trackedFiles(root, { ignorePatterns: ignorePatternsOf(argv) }).filter(
+    (path) =>
+        path.endsWith('.md') && !path.startsWith(GENERATED) && !path.includes(`/${GENERATED}`),
+);
+
+let failed = false;
+for (const path of pages) {
+    const markdown = readText(root, path);
+    if (markdown === null) {
+        continue;
+    }
+    for (const violation of auditPage(root, path, markdown)) {
+        stdout.write(`${violation.rule}  ${path}  ${violation.message}\n`);
+        failed = true;
+    }
+}
+
+exit(failed ? 1 : 0);

package/lib/check-names.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+/**
+ * What a project's own tree calls its parts.
+ *
+ * Two rosters, both closed, both here and nowhere else. A **grab-bag** name
+ * says nothing about what it holds, so it holds whatever nobody placed:
+ * `utils.ts` is what a folder called `utils/` grows out of, and the folder is
+ * what a missing subject grows out of. A **shortcut** says it in half — each
+ * one the short form of a word the tree spells out somewhere else, so two
+ * spellings of one idea end up sitting side by side.
+ *
+ * Usage: node check-names.js [root] [--ignore-pattern <glob>]…
+ *
+ * One line per violation, `<rule>  <path>  <message>`. Exit code: 0 when every
+ * name claims a subject, 1 otherwise. No `--fix`: renaming a file is a move,
+ * and choosing the name it moves to is the work the rule is asking for.
+ */
+
+import { resolve } from 'node:path';
+import { argv, exit, stdout } from 'node:process';
+
+import { ignorePatternsOf, trackedFiles } from './tracked-files.js';
+
+/** Names that say nothing: a folder or a file called one of these holds whatever nobody placed. */
+const GRAB_BAG = new Set([
+    'base',
+    'common',
+    'core',
+    'helpers',
+    'lib',
+    'misc',
+    'shared',
+    'stuff',
+    'tools',
+    'utils',
+]);
+
+/**
+ * Names that say it in half — each the short form of a word the tree writes out
+ * somewhere. The `_` marker does not excuse one: it states a position, not
+ * whether the name is whole. A name is read segment by segment, split on the
+ * hyphen, so `explore-repo` is caught.
+ */
+const SHORTCUTS = new Set([
+    'auth',
+    'cfg',
+    'impl',
+    'infra',
+    'k8s',
+    'pkg',
+    'repo',
+    'repos',
+    'svc',
+    'tmp',
+]);
+
+/**
+ * The roots the rule sweeps — where a project keeps what it wrote. Each root's
+ * OWN name is the toolchain's vocabulary, not the project's choice, so it is
+ * never judged: `lib/` is on both this list and the grab-bag roster, and only
+ * what a project put INSIDE it is the project's to name.
+ */
+const SWEPT = new Set(['apps', 'bin', 'lib', 'packages', 'specs', 'src', 'tests']);
+
+/** A `_` opens a row — a fixture, a golden, a template — and a row is not a subject. */
+const isOfTheRow = (name) => name.startsWith('_');
+
+/** A directory claims its own segment. */
+const isGrabBag = (name) => !isOfTheRow(name) && GRAB_BAG.has(name.toLowerCase());
+
+/** A name carries a truncation when any hyphen-separated segment of it is one. */
+const isShortcut = (name) =>
+    name
+        .toLowerCase()
+        .split('-')
+        .some((segment) => SHORTCUTS.has(segment));
+
+/** A file claims what stands before its first dot: `utils.ts` and `utils.test.ts` both claim `utils`. */
+const stemOf = (name) => name.split('.')[0] ?? '';
+
+/**
+ * Every name a set of paths puts on the tree, each mapped to the path that
+ * carries it: every directory below a swept root, and every file's stem.
+ */
+function namesOf(files) {
+    const named = new Map();
+
+    for (const file of files) {
+        const segments = file.split('/');
+        if (!SWEPT.has(segments[0]) || segments.length < 2) {
+            continue;
+        }
+
+        /* From the second segment on: the root's own name is not the project's. */
+        for (let index = 1; index < segments.length - 1; index += 1) {
+            const path = segments.slice(0, index + 1).join('/');
+            named.set(path, segments[index]);
+        }
+        named.set(file, stemOf(segments.at(-1)));
+    }
+
+    return [...named].toSorted(([left], [right]) => (left < right ? -1 : 1));
+}
+
+const root = resolve(argv.slice(2).find((argument) => !argument.startsWith('--')) ?? '.');
+const named = namesOf(trackedFiles(root, { ignorePatterns: ignorePatternsOf(argv) }));
+
+let failed = false;
+for (const [path, name] of named) {
+    if (isGrabBag(name)) {
+        stdout.write(
+            `names-grab-bag  ${path}  \`${name}\` names no subject — it holds whatever nobody placed\n`,
+        );
+        failed = true;
+    }
+    if (isShortcut(name)) {
+        stdout.write(
+            `names-shortcut  ${path}  \`${name}\` is a word written in half — spell it whole\n`,
+        );
+        failed = true;
+    }
+}
+
+exit(failed ? 1 : 0);

package/lib/check-publish.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+/**
+ * What a published package promises, held to what the tarball will contain.
+ *
+ * Every mistake this gate refuses is invisible in the repository and fatal in
+ * the registry: an `exports` entry pointing at a file nobody built, a subpath
+ * left out of `files` so it resolves in development and 404s in a consumer, a
+ * type declaration a modern resolver cannot see. The two tools that know those
+ * failure modes best run here — `publint` on the packed tarball, and
+ * `@arethetypeswrong/cli` on the declarations — beside the two joins only the
+ * source tree can answer.
+ *
+ * Usage: node check-publish.js [root] [--publint <path>] [--attw <path>]
+ *
+ * One line per violation of this gate's own rules, `<rule>  <path>
+ * <message>`; each tool's own report is printed verbatim under its name when it
+ * refuses. Exit code: 0 when the package is publishable, 1 otherwise. No
+ * `--fix`: an exports map is a contract, not a formatting choice.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, matchesGlob, resolve } from 'node:path';
+import { argv, exit, stdout } from 'node:process';
+
+/** Npm ships these whatever `files` says, so neither rule asks about them. */
+const ALWAYS_PACKED = /^(?:package\.json|readme|license|licence|changelog)/iu;
+
+/** Every string an exports map points at, wherever the conditions nest. */
+function targetsOf(exports) {
+    if (typeof exports === 'string') {
+        return [exports];
+    }
+    if (Array.isArray(exports)) {
+        return exports.flatMap((entry) => targetsOf(entry));
+    }
+    if (exports !== null && typeof exports === 'object') {
+        return Object.values(exports).flatMap((entry) => targetsOf(entry));
+    }
+
+    return [];
+}
+
+/** A target with no `./` in front, which is how `files` spells the same path. */
+const plain = (target) => target.replace(/^\.\//u, '');
+
+/**
+ * Whether a target resolves on disk. A wildcard names a family rather than a
+ * file, so what is asked of it is that the directory it reads from exists and
+ * holds something the pattern matches.
+ */
+function resolvesOnDisk(root, target) {
+    const path = plain(target);
+    if (!path.includes('*')) {
+        return existsSync(join(root, path));
+    }
+
+    const prefix = path.slice(0, path.indexOf('*'));
+    const directory = prefix.endsWith('/') ? prefix.slice(0, -1) : dirname(prefix);
+    try {
+        return readdirSync(join(root, directory)).some((name) =>
+            matchesGlob(join(directory, name), path),
+        );
+    } catch {
+        return false;
+    }
+}
+
+/** Whether `files` reaches a target: by its own entry, or by a directory above it. */
+function isPacked(files, target) {
+    const path = plain(target);
+    if (ALWAYS_PACKED.test(path)) {
+        return true;
+    }
+
+    return files.some((entry) => {
+        const packed = plain(entry).replace(/\/$/u, '');
+
+        return (
+            path === packed ||
+            path.startsWith(`${packed}/`) ||
+            matchesGlob(path, packed) ||
+            matchesGlob(path, `${packed}/**`)
+        );
+    });
+}
+
+/** One tool's verdict, with its report kept for the failing case. */
+function runTool(name, binary, args, root) {
+    const run = spawnSync(binary, args, { cwd: root, encoding: 'utf8' });
+    if (run.error) {
+        return { output: `${name} could not be run: ${run.error.message}\n`, status: 1 };
+    }
+
+    return { output: `${run.stdout ?? ''}${run.stderr ?? ''}`, status: run.status ?? 1 };
+}
+
+const flagged = (name, fallback) => {
+    const at = argv.indexOf(name);
+
+    return at === -1 || argv[at + 1] === undefined ? fallback : argv[at + 1];
+};
+
+const root = resolve(
+    argv.slice(2).find((argument, index) => {
+        const previous = argv[index + 1];
+
+        return !argument.startsWith('--') && previous !== '--publint' && previous !== '--attw';
+    }) ?? '.',
+);
+
+const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+const files = manifest.files ?? [];
+const targets = [
+    ...targetsOf(manifest.exports ?? {}),
+    ...(manifest.main === undefined ? [] : [manifest.main]),
+    ...(manifest.types === undefined ? [] : [manifest.types]),
+];
+
+let failed = false;
+
+for (const target of [...new Set(targets)].toSorted((left, right) => (left < right ? -1 : 1))) {
+    if (!resolvesOnDisk(root, target)) {
+        stdout.write(
+            `publish-exports-target  package.json  ${target} resolves to nothing on disk\n`,
+        );
+        failed = true;
+        continue;
+    }
+    if (files.length > 0 && !isPacked(files, target)) {
+        stdout.write(
+            `publish-files  package.json  ${target} is outside "files" — it resolves here and 404s in a consumer\n`,
+        );
+        failed = true;
+    }
+}
+
+for (const [name, binary, args] of [
+    ['publint', flagged('--publint', 'publint'), ['--strict']],
+    ['attw', flagged('--attw', 'attw'), ['--pack', '.', '--profile', 'esm-only']],
+]) {
+    const { output, status } = runTool(name, binary, args, root);
+    if (status !== 0) {
+        stdout.write(output);
+        failed = true;
+    }
+}
+
+exit(failed ? 1 : 0);

package/lib/check-secrets.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+/**
+ * No file the project would commit carries a live-looking credential.
+ *
+ * Two engines, one gate. Where `gitleaks` is on PATH it is the better scanner
+ * and this gate is its runner — `gitleaks dir . --redact`, so a finding names
+ * the file and never reprints the secret. Where it is not, ten patterns over
+ * the tracked text answer the same question well enough to stop the leak that
+ * actually happens: a token pasted into a note and committed with it.
+ *
+ * Which engine runs is decided HERE and not in `check.sh`, because the gate
+ * applies either way — bash decides whether a gate applies, and this one always
+ * does. What changes is only who answers.
+ *
+ * A hit is forgiven by one thing: the same line declaring itself fake. There is
+ * no exception list, and there will not be one — an allow-list of paths is the
+ * first place a real leak hides.
+ *
+ * Usage: node check-secrets.js [root] [--ignore-pattern <glob>]…
+ *
+ * One line per violation, `<rule>  <path>  <message>`. Exit code: 0 when
+ * nothing looks live, 1 otherwise. No `--fix`: a leaked credential is rotated,
+ * not reformatted.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { argv, exit, stdout } from 'node:process';
+
+import { ignorePatternsOf, readText, trackedFiles } from './tracked-files.js';
+
+/** The ten shapes, each with the rule id a finding is reported under. */
+const PATTERNS = [
+    {
+        pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/u,
+        rule: 'secrets-private-key',
+        what: 'a private key block',
+    },
+    { pattern: /\bAKIA[\dA-Z]{16}\b/u, rule: 'secrets-aws-key', what: 'an aws access key' },
+    {
+        pattern: /\bgh[oprsu]_[\dA-Za-z]{30,}\b/u,
+        rule: 'secrets-github-token',
+        what: 'a github token',
+    },
+    {
+        pattern: /\bxox[abprs]-[\dA-Za-z-]{10,}\b/u,
+        rule: 'secrets-slack-token',
+        what: 'a slack token',
+    },
+    {
+        pattern: /\btskey-[a-z]+-[\dA-Za-z]{6,}\b/u,
+        rule: 'secrets-tailscale-key',
+        what: 'a tailscale key',
+    },
+    { pattern: /\beyJ[\w-]{10,}\.eyJ[\w-]{10,}\./u, rule: 'secrets-jwt', what: 'a signed jwt' },
+    {
+        pattern: /\bglsa_[\dA-Za-z_]{20,}\b/u,
+        rule: 'secrets-grafana-token',
+        what: 'a grafana token',
+    },
+    { pattern: /\bsk-[\dA-Za-z]{20,}\b/u, rule: 'secrets-api-key', what: 'an api key' },
+    { pattern: /\bFR\d{2} ?(?:\d{4} ?){5}/u, rule: 'secrets-iban', what: 'an iban' },
+    { pattern: /\bst\.[\da-f]{24,}\b/u, rule: 'secrets-service-token', what: 'a service token' },
+];
+
+/** The one predicate that lets a hit through: the line must declare itself fake. */
+const isSynthetic = (line) => /dummy|example|fake|redacted|sample|synthetic/iu.test(line);
+
+/** Gitleaks, when the machine has it — the better scanner, run redacted. */
+function runGitleaks(root) {
+    const probe = spawnSync('gitleaks', ['version'], { stdio: 'ignore' });
+    if (probe.error) {
+        return null;
+    }
+
+    const run = spawnSync('gitleaks', ['dir', '.', '--no-banner', '--redact', '--exit-code', '1'], {
+        cwd: root,
+        encoding: 'utf8',
+    });
+
+    return { output: `${run.stdout ?? ''}${run.stderr ?? ''}`, status: run.status ?? 1 };
+}
+
+const root = resolve(argv.slice(2).find((argument) => !argument.startsWith('--')) ?? '.');
+
+const gitleaks = runGitleaks(root);
+if (gitleaks !== null) {
+    if (gitleaks.status !== 0) {
+        stdout.write(gitleaks.output);
+    }
+    exit(gitleaks.status === 0 ? 0 : 1);
+}
+
+let failed = false;
+for (const path of trackedFiles(root, { ignorePatterns: ignorePatternsOf(argv) })) {
+    const text = readText(root, path);
+    if (text === null) {
+        continue;
+    }
+
+    for (const [index, line] of text.split('\n').entries()) {
+        if (isSynthetic(line)) {
+            continue;
+        }
+        for (const { pattern, rule, what } of PATTERNS) {
+            if (pattern.test(line)) {
+                stdout.write(`${rule}  ${path}  line ${index + 1} looks like ${what}\n`);
+                failed = true;
+            }
+        }
+    }
+}
+
+exit(failed ? 1 : 0);