ekohacks 0.1.0 → 0.2.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,29 +2,76 @@
 // 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 { 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']) {
+    if (!existsSync(file)) {
+        console.error(`stopped: no ${file} in this directory`);
+        process.exit(1);
+    }
+}
 const read = (file) => readFileSync(file, 'utf8');
 const changelog = read('CHANGELOG.md');
-const pkg = JSON.parse(read('package.json')).name;
+const manifest = JSON.parse(read('package.json'));
+const pkg = manifest.name;
 const confirm = async (question) => {
     const readline = createInterface({ input: process.stdin, output: process.stdout });
     const answer = await readline.question(`${question} (y/n) `);
@@ -45,6 +92,7 @@ if (subcommand === undefined) {
         confirm,
         narrate,
         yes,
+        currentVersion: manifest.version,
     });
     if ('stopped' in result) {
         console.error(`stopped: ${result.stopped}`);
@@ -77,9 +125,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);
 }
@@ -91,6 +137,7 @@ const result = await cut({
     npm: NpmWrapper.create(),
     gh: GhWrapper.create(),
     narrate,
+    currentVersion: manifest.version,
 });
 if ('stopped' in result) {
     console.error(`stopped: ${result.stopped}`);

package/dist/logic/cut.js

@@ -7,11 +7,16 @@ import { NpmWrapper } from '../infrastructure/npm.js';
 // release PR, wait for CI, merge on green. It refuses to start unless preflight passed,
 // and every stop names the reason so a human can pick up by hand. The caller supplies the
 // wrappers and hears each step through narrate.
-export const cut = async ({ version, changelog, report, git, npm, gh, narrate, confirm = () => Promise.resolve(true), pollDelayMs = 15_000, }) => {
+export const cut = async ({ version, changelog, report, git, npm, gh, narrate, confirm = () => Promise.resolve(true), currentVersion, pollDelayMs = 15_000, }) => {
     const failed = report.checks.filter((check) => !check.passed);
     if (failed.length > 0) {
         return { stopped: `preflight failed: ${failed.map((check) => check.name).join(', ')}` };
     }
+    if (currentVersion === version) {
+        return {
+            stopped: `package.json is already at ${version}: the cut looks finished, run ekohacks release ship ${version}`,
+        };
+    }
     const branch = `release/v${version}`;
     if (await git.branchExists(branch)) {
         return { stopped: `branch ${branch} already exists from an earlier cut` };

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

@@ -9,7 +9,7 @@ import { ProcessRunner } from '../infrastructure/process.js';
 // the first failure with that stage's own reason. No stage's logic lives here — this
 // policy only composes the three and decides which pauses --yes may skip: the merge and
 // the Release. The gate always asks.
-export const release = async ({ version, changelog, lockfile, pkg, git, npm, gh, runner, confirm, narrate, yes = false, pollDelayMs, findRunAttempts, registryAttempts, }) => {
+export const release = async ({ version, changelog, lockfile, pkg, git, npm, gh, runner, confirm, narrate, yes = false, currentVersion, pollDelayMs, findRunAttempts, registryAttempts, }) => {
     const report = await preflight({ version, changelog, npm, pkg, git, lockfile, runner });
     for (const check of report.checks) {
         narrate(check.passed ? `ok ${check.name}` : `FAIL ${check.name}: ${check.reason}`);
@@ -24,6 +24,7 @@ export const release = async ({ version, changelog, lockfile, pkg, git, npm, gh,
         gh,
         narrate,
         confirm: skippable,
+        currentVersion,
         pollDelayMs,
     });
     if ('stopped' in cutResult) {

package/package.json

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