ekohacks 0.3.0 → 0.4.0

package/README.md

@@ -10,6 +10,8 @@ The release command is built: the four stories in [`stories/`](stories/) are imp
 
 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.
 
+`ekohacks docs sync` is the other half, specified in [`stories/8-docs-sync.md`](stories/8-docs-sync.md): it writes the edits the check can prove — the entry-point block, the prose counts — and scaffolds a stub page for an entry point the docs just gained, leaving the prose to a person. [`stories/9-docs-draft.md`](stories/9-docs-draft.md) specifies drafting that prose and opening a PR for a human to review; it is written down, not built.
+
 ## 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,31 +2,36 @@
 // 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, readdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
 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 { docsCheck, docsSync } 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',
+    '       ekohacks docs sync [--dry-run]',
 ].join('\n');
+const FLAGS = ['--yes', '--dry-run'];
 const argv = process.argv.slice(2);
 const yes = argv.includes('--yes');
-const [command, ...rest] = argv.filter((arg) => arg !== '--yes');
+const dryRun = argv.includes('--dry-run');
+const [command, ...rest] = argv.filter((arg) => !FLAGS.includes(arg));
 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') {
+    const subject = rest[0];
+    if (rest.length !== 1 || (subject !== 'check' && subject !== 'sync')) {
         console.error(USAGE);
         process.exit(2);
     }
@@ -46,6 +51,22 @@ if (command === 'docs') {
             }
         }
     }
+    if (subject === 'sync') {
+        const { edits } = docsSync({ pkg: manifest.name, exports: manifest.exports, files });
+        if (edits.length === 0) {
+            console.log('  the docs are already in step');
+            process.exit(0);
+        }
+        for (const edit of edits) {
+            const verb = existsSync(edit.path) ? 'updated' : 'created';
+            if (!dryRun) {
+                mkdirSync(dirname(edit.path), { recursive: true });
+                writeFileSync(edit.path, edit.content);
+            }
+            console.log(`  ${dryRun ? `would have ${verb}` : verb} ${edit.path}`);
+        }
+        process.exit(0);
+    }
     const report = await docsCheck({
         pkg: manifest.name,
         exports: manifest.exports,

package/dist/logic/docs.js

@@ -50,9 +50,12 @@ const COUNT_WORDS = {
     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));
+// One definition of what a claim looks like, read by the check and rewritten by the sync — two
+// copies of it would be their own drift. Built fresh at each use: a shared global regex carries
+// its lastIndex from call to call.
+const COUNT_CLAIM_SOURCE = String.raw `\b(\d+|zero|one|two|three|four|five|six|seven|eight|nine|ten)[\s-]+entry[\s-]+points?\b`;
+const countClaims = () => new RegExp(COUNT_CLAIM_SOURCE, 'gi');
+const countClaimsIn = (content) => [...content.matchAll(countClaims())].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
@@ -108,3 +111,123 @@ export const docsCheck = async ({ pkg, exports, files, runner, }) => {
         : { name: 'docs build', passed: false, reason: `${DOCS_BUILD_COMMAND} failed` });
     return { checks };
 };
+// Walks the same markers blockRegions does, but rebuilds the document around each region so a
+// rewrite can be handed back in place. An unclosed block ends the walk with the rest of the
+// document untouched: the check already fails it by name, and a sync that guessed where the
+// block ended would be guessing with someone's prose.
+const mapBlocks = (content, rewrite) => {
+    let rest = content;
+    let out = '';
+    for (;;) {
+        const open = rest.indexOf(OPEN_MARKER);
+        if (open === -1) {
+            return out + rest;
+        }
+        const afterOpen = rest.slice(open + OPEN_MARKER.length);
+        const close = afterOpen.indexOf(CLOSE_MARKER);
+        if (close === -1) {
+            return out + rest;
+        }
+        out += rest.slice(0, open) + OPEN_MARKER + rewrite(afterOpen.slice(0, close)) + CLOSE_MARKER;
+        rest = afterOpen.slice(close + CLOSE_MARKER.length);
+    }
+};
+// A namespace import is the one form the exports map alone can justify: it needs the specifier
+// and nothing else. The local name is the last segment, camel-cased past any character an
+// identifier cannot carry.
+const importLineFor = (specifier) => {
+    const [first = specifier, ...rest] = (specifier.split('/').at(-1) ?? specifier).split(/[^a-zA-Z0-9]+/);
+    const local = [first, ...rest.map((part) => part.charAt(0).toUpperCase() + part.slice(1))].join('');
+    return `import * as ${local} from '${specifier}';`;
+};
+// Both edits to a block are line surgery on the specifiers it already lists: a line naming a
+// specifier the exports no longer declare goes, and a specifier no line names arrives after the
+// last one that survived. Lines naming another package are not the block's business — the check
+// ignores them, and so does this.
+const syncedBlock = (region, pkg, entries) => {
+    const kept = region
+        .split('\n')
+        .filter((line) => specifiersIn(line, pkg).every((specifier) => entries.includes(specifier)));
+    const documented = new Set(specifiersIn(kept.join('\n'), pkg));
+    const missing = entries.filter((entry) => !documented.has(entry));
+    const lastImport = kept.reduce((found, line, index) => (specifiersIn(line, pkg).length > 0 ? index : found), -1);
+    kept.splice(lastImport + 1, 0, ...missing.map(importLineFor));
+    return kept.join('\n');
+};
+// A page the tool can write without knowing anything it does not know: the import line it can
+// derive, and a TODO everywhere prose belongs. The sidebar is code the sync will not touch, so
+// the line a human has to add is spelled out rather than written.
+const stubFor = (specifier) => {
+    const name = specifier.split('/').at(-1) ?? specifier;
+    return {
+        path: `docs/${name}.md`,
+        content: [
+            `# ${specifier}`,
+            '',
+            '```ts',
+            importLineFor(specifier),
+            '',
+            '// TODO: an example that runs.',
+            '```',
+            '',
+            '## What works today',
+            '',
+            '- TODO: what a reader can rely on today, not what is planned.',
+            '',
+            '<!-- TODO: add this page to the sidebar in docs/.vitepress/config.mts:',
+            `     { text: '${name}', link: '/${name}' } -->`,
+            '',
+        ].join('\n'),
+    };
+};
+const wordForCount = (count) => Object.entries(COUNT_WORDS).find(([, value]) => value === count)?.[0];
+// A claim is rewritten in the form it was written: a digit stays a digit, a word stays a word
+// carrying the case it had. Past ten the table has no word, so the claim becomes a digit — the
+// same number the check reads either way.
+const countAs = (written, count) => {
+    const word = wordForCount(count);
+    if (/^\d+$/.test(written) || word === undefined) {
+        return String(count);
+    }
+    return written.charAt(0) === written.charAt(0).toUpperCase()
+        ? word.charAt(0).toUpperCase() + word.slice(1)
+        : word;
+};
+const syncedCounts = (content, count) => content.replace(countClaims(), (claim) => {
+    const written = claim.split(/[\s-]/)[0] ?? '';
+    return countAs(written, count) + claim.slice(written.length);
+});
+// The mechanical half of the drift the check names: the same inputs, and instead of a report
+// the files whose content should change, each as a whole new body. The shell does the writing,
+// so the policy stays pure — and a file this would leave alone never reaches the caller, which
+// is what makes a second run against a repo already in step write nothing.
+export const docsSync = ({ pkg, exports, files, }) => {
+    const entries = entryPointsFrom(pkg, exports);
+    const scanned = files.filter((file) => !file.path.split('/').includes('.vitepress'));
+    const edits = [];
+    for (const file of scanned) {
+        const synced = mapBlocks(file.content, (region) => syncedBlock(region, pkg, entries));
+        const content = syncedCounts(synced, entries.length);
+        if (content !== file.content) {
+            edits.push({ path: file.path, content });
+        }
+    }
+    // What the docs declared before this run is the baseline a stub is new against. An unclosed
+    // block declares nothing readable and a repo with no block at all has no baseline, so neither
+    // gets scaffolded: both are failures the check already names, and guessing past them would
+    // stamp pages across a repo on the strength of a marker somebody forgot to close.
+    const readable = scanned
+        .map((file) => blockRegions(file.content))
+        .filter((block) => !block.unclosed && block.regions.length > 0);
+    const declared = new Set(readable.flatMap((block) => block.regions.flatMap((region) => specifiersIn(region, pkg))));
+    const existing = new Set(files.map((file) => file.path));
+    if (readable.length > 0) {
+        for (const entry of entries.filter((entry) => entry !== pkg && !declared.has(entry))) {
+            const stub = stubFor(entry);
+            if (!existing.has(stub.path)) {
+                edits.push(stub);
+            }
+        }
+    }
+    return { edits };
+};

package/package.json

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