ekohacks 0.1.1 → 0.3.0

package/README.md

@@ -8,6 +8,8 @@ We run a distributed team shipping open source to npm with strict TDD and trunk
 
 The release command is built: the four stories in [`stories/`](stories/) are implemented, each delivered red first — a failing test is committed and reviewed before any production code exists. The suite is the specification. The acceptance test for the whole is the next real EkoLite release, run with `ekohacks release <version>`.
 
+The second command is `ekohacks docs check`, specified in [`stories/6-docs-check.md`](stories/6-docs-check.md): a gate that fails when a package's docs drift from its shipped exports map, born from the EkoLite 0.4.0 release shipping a wrong public surface. Its acceptance test is the same command run inside EkoLite.
+
 ## How this is built
 
 - A tested core policy behind nullable infrastructure, in the style of [James Shore's Testing Without Mocks](https://www.jamesshore.com/v2/projects/nullables): real wrappers around `git`, `gh` and `npm`, each with a `createNull()` that answers with configurable responses and records what was asked of it. No mocks, no spies.

package/dist/cli.js

@@ -2,24 +2,64 @@
 // The thin shell: read the repo's files, wire the real wrappers, print one line per
 // check and per step, exit 0 only when the command ran to its end. Everything worth
 // testing lives below.
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
 import { GhWrapper } from './infrastructure/gh.js';
 import { GitWrapper } from './infrastructure/git.js';
 import { NpmWrapper } from './infrastructure/npm.js';
 import { ProcessRunner } from './infrastructure/process.js';
 import { cut } from './logic/cut.js';
+import { docsCheck } from './logic/docs.js';
 import { preflight } from './logic/preflight.js';
 import { release } from './logic/release.js';
 import { ship } from './logic/ship.js';
+const USAGE = [
+    'usage: ekohacks release [preflight|cut|ship] <version> [--yes]',
+    '       ekohacks docs check',
+].join('\n');
 const argv = process.argv.slice(2);
 const yes = argv.includes('--yes');
 const [command, ...rest] = argv.filter((arg) => arg !== '--yes');
+const printChecks = (checks) => {
+    for (const check of checks) {
+        console.log(check.passed ? `  ok    ${check.name}` : `  FAIL  ${check.name}: ${check.reason}`);
+    }
+};
+if (command === 'docs') {
+    if (rest.length !== 1 || rest[0] !== 'check') {
+        console.error(USAGE);
+        process.exit(2);
+    }
+    if (!existsSync('package.json')) {
+        console.error('stopped: no package.json in this directory');
+        process.exit(1);
+    }
+    const manifest = JSON.parse(readFileSync('package.json', 'utf8'));
+    const files = [];
+    if (existsSync('README.md')) {
+        files.push({ path: 'README.md', content: readFileSync('README.md', 'utf8') });
+    }
+    if (existsSync('docs')) {
+        for (const entry of readdirSync('docs', { recursive: true, encoding: 'utf8' }).sort()) {
+            if (entry.endsWith('.md')) {
+                files.push({ path: `docs/${entry}`, content: readFileSync(`docs/${entry}`, 'utf8') });
+            }
+        }
+    }
+    const report = await docsCheck({
+        pkg: manifest.name,
+        exports: manifest.exports,
+        files,
+        runner: ProcessRunner.create(),
+    });
+    printChecks(report.checks);
+    process.exit(report.checks.every((check) => check.passed) ? 0 : 1);
+}
 const first = rest[0];
 const subcommand = first === 'preflight' || first === 'cut' || first === 'ship' ? first : undefined;
 const version = subcommand === undefined ? first : rest[1];
 if (command !== 'release' || version === undefined) {
-    console.error('usage: ekohacks release [preflight|cut|ship] <version> [--yes]');
+    console.error(USAGE);
     process.exit(2);
 }
 for (const file of ['CHANGELOG.md', 'package.json', 'package-lock.json']) {
@@ -66,6 +106,7 @@ if (subcommand === 'ship') {
         changelog,
         pkg,
         gh: GhWrapper.create(),
+        git: GitWrapper.create(),
         npm: NpmWrapper.create(),
         confirm,
         narrate,
@@ -85,9 +126,7 @@ const report = await preflight({
     git: GitWrapper.create(),
     runner: ProcessRunner.create(),
 });
-for (const check of report.checks) {
-    console.log(check.passed ? `  ok    ${check.name}` : `  FAIL  ${check.name}: ${check.reason}`);
-}
+printChecks(report.checks);
 if (subcommand === 'preflight') {
     process.exit(report.checks.every((check) => check.passed) ? 0 : 1);
 }

package/dist/infrastructure/git.js

@@ -11,12 +11,13 @@ export class GitWrapper {
             return stdout;
         });
     }
-    static createNull({ branch = 'main', dirty = false, behindOrigin = false, existingBranches = [], } = {}) {
+    static createNull({ branch = 'main', dirty = false, behindOrigin = false, existingBranches = [], versionOnMain = '0.0.0', } = {}) {
         const outputs = {
             'rev-parse --abbrev-ref HEAD': `${branch}\n`,
             'status --porcelain': dirty ? ' M some-file.ts\n' : '',
             'rev-parse main': behindOrigin ? 'local\n' : 'shared\n',
             'rev-parse origin/main': 'shared\n',
+            'show origin/main:package.json': `${JSON.stringify({ version: versionOnMain })}\n`,
         };
         for (const existing of existingBranches) {
             outputs[`branch --list ${existing}`] = `  ${existing}\n`;
@@ -38,6 +39,13 @@ export class GitWrapper {
     async branchExists(branch) {
         return (await this.runGit(['branch', '--list', branch])).trim() !== '';
     }
+    // The version main carries on origin, not in this checkout: the Release targets
+    // GitHub's main, so a stale local package.json must not answer for it.
+    async versionOnMain() {
+        await this.runGit(['fetch', 'origin', 'main']);
+        const manifest = await this.runGit(['show', 'origin/main:package.json']);
+        return JSON.parse(manifest).version;
+    }
     async mainInSyncWithOrigin() {
         await this.runGit(['fetch', 'origin', 'main']);
         const local = (await this.runGit(['rev-parse', 'main'])).trim();

package/dist/logic/docs.js

@@ -0,0 +1,110 @@
+import { ProcessRunner } from '../infrastructure/process.js';
+const DOCS_BUILD_COMMAND = 'npm run docs:build';
+const OPEN_MARKER = '<!-- ekohacks:entry-points -->';
+const CLOSE_MARKER = '<!-- /ekohacks:entry-points -->';
+// The public entry points an exports map declares, as the specifiers a consumer imports:
+// "." is the bare package name, "./react" is pkg/react. A package with no exports map —
+// or a conditions-only one, with no "." keys — has a single entry point: itself.
+export const entryPointsFrom = (pkg, exports) => {
+    if (typeof exports !== 'object' || exports === null) {
+        return [pkg];
+    }
+    const subpaths = Object.keys(exports).filter((key) => key.startsWith('.'));
+    if (subpaths.length === 0) {
+        return [pkg];
+    }
+    return subpaths
+        .filter((key) => key !== './package.json' && !key.includes('*'))
+        .map((key) => (key === '.' ? pkg : `${pkg}/${key.slice(2)}`));
+};
+const blockRegions = (content) => {
+    const regions = [];
+    let rest = content;
+    for (;;) {
+        const open = rest.indexOf(OPEN_MARKER);
+        if (open === -1) {
+            return { regions, unclosed: false };
+        }
+        const afterOpen = rest.slice(open + OPEN_MARKER.length);
+        const close = afterOpen.indexOf(CLOSE_MARKER);
+        if (close === -1) {
+            return { regions, unclosed: true };
+        }
+        regions.push(afterOpen.slice(0, close));
+        rest = afterOpen.slice(close + CLOSE_MARKER.length);
+    }
+};
+const specifiersIn = (region, pkg) => [...region.matchAll(/from\s+['"]([^'"]+)['"]|import\s+['"]([^'"]+)['"]/g)]
+    .map(([, fromSpecifier, bareSpecifier]) => fromSpecifier ?? bareSpecifier ?? '')
+    .filter((specifier) => specifier === pkg || specifier.startsWith(`${pkg}/`));
+const COUNT_WORDS = {
+    zero: 0,
+    one: 1,
+    two: 2,
+    three: 3,
+    four: 4,
+    five: 5,
+    six: 6,
+    seven: 7,
+    eight: 8,
+    nine: 9,
+    ten: 10,
+};
+const countClaimsIn = (content) => [
+    ...content.matchAll(/\b(\d+|zero|one|two|three|four|five|six|seven|eight|nine|ten)[\s-]+entry[\s-]+points?\b/gi),
+].map(([, claim = '']) => COUNT_WORDS[claim.toLowerCase()] ?? Number(claim));
+// The drift detector as a policy: the exports map is the truth, the docs carry their
+// claims in a block the tool owns, and every mismatch is a named check with the reason
+// a human needs to fix it. The caller supplies file contents and the runner; the policy
+// only judges.
+export const docsCheck = async ({ pkg, exports, files, runner, }) => {
+    const checks = [];
+    const scanned = files.filter((file) => !file.path.split('/').includes('.vitepress'));
+    const carriers = scanned.filter((file) => file.content.includes(OPEN_MARKER));
+    checks.push(carriers.length > 0
+        ? { name: 'entry points declared', passed: true }
+        : {
+            name: 'entry points declared',
+            passed: false,
+            reason: `no docs file carries an ${OPEN_MARKER} block`,
+        });
+    const entries = entryPointsFrom(pkg, exports);
+    for (const file of carriers) {
+        const name = `entry points in ${file.path}`;
+        const { regions, unclosed } = blockRegions(file.content);
+        if (unclosed) {
+            checks.push({ name, passed: false, reason: 'unclosed ekohacks:entry-points block' });
+            continue;
+        }
+        const documented = new Set(regions.flatMap((region) => specifiersIn(region, pkg)));
+        const notListed = entries.filter((entry) => !documented.has(entry));
+        const notExported = [...documented].filter((specifier) => !entries.includes(specifier));
+        const reasons = [
+            ...(notListed.length > 0 ? [`not listed: ${notListed.join(', ')}`] : []),
+            ...(notExported.length > 0 ? [`not in exports: ${notExported.join(', ')}`] : []),
+        ];
+        checks.push(reasons.length > 0
+            ? { name, passed: false, reason: reasons.join('; ') }
+            : { name, passed: true });
+    }
+    for (const file of scanned) {
+        const claims = countClaimsIn(file.content);
+        if (claims.length === 0) {
+            continue;
+        }
+        const name = `entry count in ${file.path}`;
+        const wrong = claims.filter((claim) => claim !== entries.length);
+        checks.push(wrong.length > 0
+            ? {
+                name,
+                passed: false,
+                reason: `claims ${wrong.join(' and ')} entry points, exports has ${entries.length}`,
+            }
+            : { name, passed: true });
+    }
+    const build = await runner.run(DOCS_BUILD_COMMAND);
+    checks.push(build.exitCode === 0
+        ? { name: 'docs build', passed: true }
+        : { name: 'docs build', passed: false, reason: `${DOCS_BUILD_COMMAND} failed` });
+    return { checks };
+};

package/dist/logic/release.js

@@ -35,6 +35,7 @@ export const release = async ({ version, changelog, lockfile, pkg, git, npm, gh,
         changelog,
         pkg,
         gh,
+        git,
         npm,
         confirm,
         confirmRelease: skippable,

package/dist/logic/ship.js

@@ -1,12 +1,19 @@
 import { setTimeout as delay } from 'node:timers/promises';
 import { changelogEntryFor } from './changelog.js';
 import { GhWrapper } from '../infrastructure/gh.js';
+import { GitWrapper } from '../infrastructure/git.js';
 import { NpmWrapper } from '../infrastructure/npm.js';
-// The tail of RELEASING.md as a policy: cut the GitHub Release, approve the publish
-// gate, follow the run to green, and only report success once the registry serves the
-// version. The one human decision stays human: the gate is never approved without the
-// confirm answering yes.
-export const ship = async ({ version, changelog, pkg, gh, npm, confirm, confirmRelease = () => Promise.resolve(true), narrate, pollDelayMs = 15_000, findRunAttempts = 8, registryAttempts = 20, workflow = 'publish.yml', }) => {
+// The tail of RELEASING.md as a policy: refuse a cut that has not landed on main, cut
+// the GitHub Release, approve the publish gate, follow the run to green, and only
+// report success once the registry serves the version. The one human decision stays
+// human: the gate is never approved without the confirm answering yes.
+export const ship = async ({ version, changelog, pkg, gh, git, npm, confirm, confirmRelease = () => Promise.resolve(true), narrate, pollDelayMs = 15_000, findRunAttempts = 8, registryAttempts = 20, workflow = 'publish.yml', }) => {
+    const onMain = await git.versionOnMain();
+    if (onMain !== version) {
+        return {
+            stopped: `main carries ${onMain ?? 'no version'}, not ${version}: the cut looks unfinished, run ekohacks release cut ${version}`,
+        };
+    }
     const tag = `v${version}`;
     if (!(await confirmRelease(`cut release ${tag}?`))) {
         return { stopped: 'release not approved' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ekohacks",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "The EkoHacks CLI: our everyday operations, automated one small command at a time.",
   "repository": {
     "type": "git",