@roughen/cli 0.3.0

package/lib/verify.mjs

@@ -0,0 +1,299 @@
+import { execFileSync } from 'node:child_process';
+import { readFile, lstat, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { judgeRevision, countBanned, lint, revisableRules, revisionLengthTolerance } from '@roughen/core';
+import { loadConfig, copyOptions } from './config.mjs';
+import { formatFor } from './lint-file.mjs';
+import { parseSource, extractCopy, virtualDocuments, groupText, countWords } from './jsx.mjs';
+
+/**
+ * `roughen verify`: did a rewrite keep its facts and leave the code alone?
+ * Compares each file before and after, string by string, with the same copy
+ * reader and the same judgment (core's judgeRevision) every other surface
+ * uses. Read-only: it reads files and asks git for the old versions.
+ */
+
+const positional = new Set(['loc', 'start', 'end', 'extra', 'range', 'leadingComments', 'trailingComments', 'innerComments', 'comments', 'tokens']);
+const isString = (node) => node && (node.type === 'StringLiteral' || node.type === 'JSXText' || node.type === 'TemplateElement' || node.type === 'DirectiveLiteral');
+const stringValue = (node) => node.type === 'TemplateElement' ? node.value.raw : node.value;
+const normalize = (text) => text.replace(/\s+/g, ' ').trim();
+/** A file's rewritten copy may change by 15% or by this many words, whichever is more. */
+const lengthSlackWords = 10;
+
+/**
+ * Every string-bearing node in traversal order, with where it sits: the
+ * property key, JSX attribute or element, and whether it's an import path.
+ * Two ASTs with the same shape list their strings in the same order.
+ */
+function strings(ast) {
+  const out = [];
+  const visit = (node, context) => {
+    if (!node || typeof node.type !== 'string') return;
+    if (isString(node)) { out.push({ node, text: stringValue(node), context }); return; }
+    let next = context;
+    if (node.type === 'ObjectProperty' && !node.computed) next = { ...context, key: node.key.name ?? node.key.value, attribute: null };
+    else if (node.type === 'JSXAttribute') next = { ...context, attribute: node.name.name ?? `${node.name.namespace?.name}:${node.name.name?.name}`, key: null };
+    else if (node.type === 'JSXElement') next = { ...context, tag: node.openingElement.name.name ?? null, attribute: null, key: null };
+    else if (node.type === 'ImportDeclaration' || node.type === 'ExportAllDeclaration' || (node.type === 'ExportNamedDeclaration' && node.source) || node.type === 'ImportExpression'
+      || (node.type === 'CallExpression' && (node.callee?.type === 'Import' || node.callee?.name === 'require'))) next = { ...context, import: true };
+    for (const key of Object.keys(node)) {
+      if (positional.has(key)) continue;
+      const value = node[key];
+      if (Array.isArray(value)) for (const item of value) visit(item, next);
+      else if (value && typeof value === 'object') visit(value, next);
+    }
+  };
+  visit(ast.program, {});
+  return out;
+}
+
+/** The first place two ASTs differ other than in string contents, as an offset into `after`, or -1. */
+function firstCodeDifference(before, after) {
+  const differs = (a, b, holder) => {
+    if (Array.isArray(a) || Array.isArray(b)) {
+      if (!Array.isArray(a) || !Array.isArray(b)) return holder;
+      for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        if (i >= a.length || i >= b.length) return b[i]?.start ?? b[b.length - 1]?.end ?? holder;
+        const found = differs(a[i], b[i], b[i]?.start ?? holder);
+        if (found >= 0) return found;
+      }
+      return -1;
+    }
+    if (a && typeof a === 'object' && b && typeof b === 'object') {
+      if (a.type !== b.type) return b.start ?? holder;
+      const at = b.start ?? holder;
+      const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+      for (const key of keys) {
+        if (positional.has(key)) continue;
+        if (isString(a) && (key === 'value' || key === 'raw' || key === 'cooked')) continue;
+        const found = differs(a[key], b[key], at);
+        if (found >= 0) return found;
+      }
+      return -1;
+    }
+    return a === b ? -1 : holder;
+  };
+  return differs(before.program, after.program, 0);
+}
+
+const lineAt = (source, offset) => source.slice(0, Math.max(0, offset)).split('\n').length;
+const excerpt = (text, limit = 120) => { const value = normalize(text); return value.length > limit ? `${value.slice(0, limit - 1)}…` : value; };
+const where = (context) => context.attribute ? `attribute ${context.attribute}` : context.key ? `key ${context.key}` : context.tag ? `<${context.tag}> text` : 'a string';
+
+/**
+ * Banned characters and patterns in a file's copy (body and short: what a
+ * reader sees, minus verbatim quotes), so a before and after compare.
+ */
+function bannedIn(source, fragments, voice) {
+  const { body, short } = virtualDocuments(source, fragments);
+  return countBanned(`${body.text}\n\n${short.text}`, voice, 'text');
+}
+
+/**
+ * Verifies one JS/TS/JSX file's copy edit. `config` is the file's loaded
+ * roughen config (voice bans, register, copy keys).
+ */
+export function verifyCopy(before, after, { file, config = {} }) {
+  const report = { file, format: 'copy', changedStrings: 0, errors: [], warnings: [] };
+  const error = (line, message, extra = {}) => report.errors.push({ line, message, ...extra });
+  const warn = (line, message, extra = {}) => report.warnings.push({ line, message, ...extra });
+  let beforeAst;
+  try { beforeAst = parseSource(before, file); } catch (caught) { report.skipped = `the old version doesn't parse (${caught.message}), so there's nothing to compare against`; return report; }
+  let afterAst;
+  try { afterAst = parseSource(after, file); } catch (caught) { error(caught.loc?.line ?? 1, `The file no longer parses: ${caught.message}`); return report; }
+  const beforeStrings = strings(beforeAst); const afterStrings = strings(afterAst);
+  const difference = firstCodeDifference(beforeAst, afterAst);
+  if (difference >= 0) {
+    error(lineAt(after, difference), 'Code changed, not just copy: the file differs from the original outside its strings. A copy edit changes text only; revert the code change or review it separately.');
+    // A renamed key or a changed attribute leaves the strings in step; anything else can't be paired.
+    if (beforeStrings.length !== afterStrings.length) return report;
+    warn(lineAt(after, difference), 'The strings were still compared in order, since the code change left their number the same.');
+  }
+  const options = copyOptions(file, config);
+  const beforeFragments = extractCopy(before, file, { ...options, ast: beforeAst });
+  const afterFragments = extractCopy(after, file, { ...options, ast: afterAst });
+  const byStart = (fragments) => new Map(fragments.map((fragment) => [fragment.start, fragment]));
+  const beforeAt = byStart(beforeFragments); const afterAt = byStart(afterFragments);
+  const fragmentFor = (map, node) => map.get(node.type === 'StringLiteral' || node.type === 'DirectiveLiteral' ? node.start + 1 : node.start) ?? null;
+  const voice = { bannedCharacters: config.voice?.bannedCharacters, bannedPatterns: config.voice?.bannedPatterns };
+  const groups = new Map(); // before group id → the pair of group texts to judge
+  for (let i = 0; i < beforeStrings.length; i++) {
+    const was = beforeStrings[i]; const now = afterStrings[i];
+    if (normalize(was.text) === normalize(now.text)) continue;
+    report.changedStrings++;
+    const line = lineAt(after, now.node.start);
+    const texts = { before: excerpt(was.text), after: excerpt(now.text) };
+    if (was.context.import) { error(line, 'An import path changed.', texts); continue; }
+    const old = fragmentFor(beforeAt, was.node);
+    const fresh = fragmentFor(afterAt, now.node);
+    if (!old && !fresh) { error(line, `A string that isn't copy changed (${where(now.context)}). Copy edits don't touch code values; if it is copy, add its key to copy.body in roughen.config.`, texts); continue; }
+    if (!old) warn(line, `Roughen reads this string as copy only after the edit (${where(now.context)}); check it renders as text.`, texts);
+    const role = old?.role ?? fresh.role;
+    if (role === 'protected') { error(line, `A protected string changed (${old?.verbatim ? 'quoted words' : old?.key ?? where(now.context)}). H1s, titles and headlines, FAQ questions, keywords, schema names, quotes and citations stay exactly as written.`, texts); continue; }
+    if (role === 'short' && /^h[2-6]$/.test(old?.key ?? '')) warn(line, `A heading changed (${old.key}). Headings are allowed to change, but check they still match the page's outline and search intent.`, texts);
+    const id = old ? `b${old.group}` : `a${fresh.group}`;
+    if (!groups.has(id)) {
+      const beforeText = old ? groupText(before, beforeFragments.filter((fragment) => fragment.group === old.group)) : was.text;
+      const afterText = fresh ? groupText(after, afterFragments.filter((fragment) => fragment.group === fresh.group)) : now.text;
+      groups.set(id, { line, beforeText, afterText });
+    }
+  }
+  // Each changed string (or JSX sentence split by inline elements) must keep its facts.
+  let wordsBefore = 0; let wordsAfter = 0;
+  for (const { line, beforeText, afterText } of groups.values()) {
+    const words = countWords(beforeText);
+    wordsBefore += words; wordsAfter += countWords(afterText);
+    const judgment = judgeRevision(beforeText, afterText, { format: 'text', rules: [], voice, lengthTolerance: Math.max(revisionLengthTolerance, words ? 2 / words : 1) });
+    const texts = { before: excerpt(beforeText), after: excerpt(afterText) };
+    const { missing, added } = judgment.preservation;
+    const lost = [...missing.numbers.map((item) => `number ${item}`), ...missing.links.map((item) => `link ${item}`), ...missing.quotes.map((item) => `quotation ${excerpt(item, 60)}`)];
+    const invented = [...added.numbers.map((item) => `number ${item}`), ...added.links.map((item) => `link ${item}`)];
+    if (lost.length) error(line, `Facts missing after the edit: ${lost.join(', ')}.`, texts);
+    if (invented.length) error(line, `The edit adds facts the original didn't have: ${invented.join(', ')}.`, texts);
+    if (judgment.bannedAfter > judgment.bannedBefore) error(line, `The edit adds ${judgment.bannedAfter - judgment.bannedBefore} banned character(s) or pattern(s).`, texts);
+    else {
+      const dashes = (text) => (text.match(/—/g) ?? []).length;
+      if (dashes(afterText) > dashes(beforeText)) warn(line, `The edit adds ${dashes(afterText) - dashes(beforeText)} em dash(es).`, texts);
+    }
+    if (Math.abs(judgment.preservation.lengthRatio - 1) > Math.max(revisionLengthTolerance, words ? 2 / words : 1)) warn(line, `Length is ${Math.round(judgment.preservation.lengthRatio * 100)}% of the original string.`, texts);
+  }
+  report.changedWords = { before: wordsBefore, after: wordsAfter };
+  // Across everything the edit rewrote: within 15%, with ten words of slack so one reworded label isn't a failure.
+  if (wordsBefore && Math.abs(wordsAfter - wordsBefore) > Math.max(revisionLengthTolerance * wordsBefore, lengthSlackWords)) {
+    error(1, `The rewritten copy is ${Math.round((wordsAfter / wordsBefore) * 100)}% of its original length (${wordsBefore} words before, ${wordsAfter} after); keep it within ${Math.round(revisionLengthTolerance * 100)}%.`);
+  }
+  // The file's habits, measured on its body copy the way the linter measures them.
+  const bodyBefore = virtualDocuments(before, beforeFragments).body.text;
+  const bodyAfter = virtualDocuments(after, afterFragments).body.text;
+  const rules = firingRules(bodyBefore, bodyAfter, 'text', config.register);
+  const habits = judgeRevision(bodyBefore, bodyAfter, { format: 'text', rules, register: config.register });
+  report.habits = { rules, before: habits.flaggedBefore, after: habits.flaggedAfter };
+  report.banned = { before: bannedIn(before, beforeFragments, voice), after: bannedIn(after, afterFragments, voice) };
+  judgeHabits(report, error, warn);
+  return report;
+}
+
+/** Rules that ask for a rewrite of either version: a habit the edit introduced counts too. */
+function firingRules(before, after, format, register) {
+  return [...new Set([...revisableRules(lint(before, { format, register })), ...revisableRules(lint(after, { format, register }))])];
+}
+
+/** Shared by copy and prose files: habits and bans may only go down. */
+function judgeHabits(report, error, warn) {
+  const { habits, banned } = report;
+  if (banned.after > banned.before) error(1, `The file has more banned characters or patterns than before (${banned.before} → ${banned.after}).`);
+  if (habits.after > habits.before) error(1, `The edit adds flagged habits (${habits.rules.join(', ')}): ${habits.before} before, ${habits.after} after.`);
+  else if (report.changedStrings && habits.rules.length && habits.after === habits.before) warn(1, `The flagged habits didn't decrease (${habits.rules.join(', ')}: ${habits.before} before and after).`);
+}
+
+/** Verifies a Markdown, MDX, HTML or text file with core's judgment, whole. */
+export function verifyProse(before, after, { file, format, config = {} }) {
+  const report = { file, format, changedStrings: before === after ? 0 : 1, errors: [], warnings: [] };
+  const error = (line, message) => report.errors.push({ line, message });
+  const warn = (line, message) => report.warnings.push({ line, message });
+  const voice = { bannedCharacters: config.voice?.bannedCharacters, bannedPatterns: config.voice?.bannedPatterns };
+  const judgment = judgeRevision(before, after, { format, register: config.register, voice, rules: firingRules(before, after, format, config.register) });
+  for (const reason of judgment.preservation.reasons) error(1, reason);
+  report.habits = { rules: judgment.rules, before: judgment.flaggedBefore, after: judgment.flaggedAfter };
+  report.banned = { before: judgment.bannedBefore, after: judgment.bannedAfter };
+  judgeHabits(report, error, warn);
+  return report;
+}
+
+/** One file, either kind. */
+export function verifySource(before, after, { file, config = {} }) {
+  const format = formatFor(file);
+  if (!format) return { file, skipped: 'not a file Roughen reads', errors: [], warnings: [], changedStrings: 0 };
+  if (before === after) return { file, format, changedStrings: 0, errors: [], warnings: [] };
+  return format === 'copy' ? verifyCopy(before, after, { file, config }) : verifyProse(before, after, { file, format, config });
+}
+
+function git(cwd, args) {
+  return execFileSync('git', ['-c', 'core.quotepath=off', ...args], { cwd, encoding: 'utf8', maxBuffer: 1 << 28, stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+/** Whether `ref` names a commit in the repository at `cwd`. */
+export function isCommit(cwd, ref) {
+  try { git(cwd, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]); return true; } catch { return false; }
+}
+
+/**
+ * Verifies every changed file under `paths` (default: the repository)
+ * against `ref`: the before is the file at that commit, the after is the
+ * working tree. New and deleted files are listed, not judged.
+ */
+export async function verifyGit({ paths = ['.'], ref = 'HEAD', cwd = process.cwd(), configPath } = {}) {
+  // git reports its top level with symlinks resolved (/var is /private/var on macOS), so paths must be too.
+  const real = async (item) => {
+    const absolute = path.resolve(cwd, item);
+    try { return await realpath(absolute); } catch { try { return path.join(await realpath(path.dirname(absolute)), path.basename(absolute)); } catch { return absolute; } }
+  };
+  const resolved = await Promise.all((paths.length ? paths : ['.']).map(real));
+  const start = resolved[0];
+  let startDir = start;
+  try { if (!(await lstat(start)).isDirectory()) startDir = path.dirname(start); } catch { startDir = path.dirname(start); }
+  let root;
+  try { root = git(startDir, ['rev-parse', '--show-toplevel']).trim(); } catch { throw new Error(`${start} isn't inside a git repository; use --before and --after to compare two files`); }
+  if (!isCommit(root, ref)) throw new Error(`${ref} isn't a commit in ${root}`);
+  const commit = git(root, ['rev-parse', '--short', `${ref}^{commit}`]).trim();
+  const pathspecs = resolved.map((item) => path.relative(root, item) || '.');
+  const changed = git(root, ['diff', '--name-status', '-z', '--no-renames', ref, '--', ...pathspecs]).split('\0').filter(Boolean);
+  const files = [];
+  const notes = [];
+  for (let i = 0; i < changed.length; i += 2) {
+    const [status, name] = [changed[i], changed[i + 1]];
+    if (!formatFor(name)) continue;
+    if (status === 'D') { notes.push({ file: name, note: 'deleted' }); continue; }
+    if (status === 'A') { notes.push({ file: name, note: 'new since the ref: nothing to compare; lint it instead' }); continue; }
+    const absolute = path.join(root, name);
+    const before = git(root, ['show', `${ref}:${name}`]);
+    const after = await readFile(absolute, 'utf8');
+    const { config } = await loadConfig(absolute, configPath);
+    files.push({ ...verifySource(before, after, { file: absolute, config }), file: name });
+  }
+  for (const name of git(root, ['ls-files', '--others', '--exclude-standard', '-z', '--', ...pathspecs]).split('\0').filter(Boolean)) {
+    if (formatFor(name)) notes.push({ file: name, note: 'untracked: nothing to compare; lint it instead' });
+  }
+  return summarize({ root, ref, commit, files, notes });
+}
+
+/** Two files outside git: an original and its rewrite. */
+export async function verifyFiles({ before, after, configPath }) {
+  const [original, revised] = await Promise.all([readFile(before, 'utf8'), readFile(after, 'utf8')]);
+  const { config } = await loadConfig(after, configPath);
+  const file = path.resolve(after);
+  return summarize({ root: path.dirname(file), ref: path.resolve(before), commit: null, files: [{ ...verifySource(original, revised, { file, config }), file: path.basename(after) }], notes: [] });
+}
+
+function summarize(result) {
+  const files = result.files.filter((file) => file.changedStrings || file.errors.length || file.skipped);
+  const errors = files.reduce((sum, file) => sum + file.errors.length, 0);
+  const warnings = files.reduce((sum, file) => sum + file.warnings.length, 0);
+  return { ...result, files, errors, warnings, ok: errors === 0 };
+}
+
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+
+/** The verify report as text. */
+export function renderVerify(result, { details = true } = {}) {
+  const lines = [`Roughen verify: ${plural(result.files.length, 'changed file')} against ${result.commit ? `${result.ref} (${result.commit})` : result.ref}.`];
+  for (const file of result.files) {
+    lines.push('');
+    if (file.skipped) { lines.push(`${file.file}: skipped, ${file.skipped}.`); continue; }
+    const head = `${file.file}: ${plural(file.changedStrings, 'changed string')}${file.format === 'copy' ? '' : ` (${file.format})`}. ${file.errors.length ? plural(file.errors.length, 'error') : 'OK'}${file.warnings.length ? `, ${plural(file.warnings.length, 'warning')}` : ''}.`;
+    lines.push(head);
+    for (const [kind, items] of [['error', file.errors], ['warn ', file.warnings]]) {
+      for (const item of items) {
+        lines.push(`  ${kind} line ${item.line}: ${item.message}`);
+        if (details && item.before !== undefined) lines.push(`        before: ${item.before}`, `        after:  ${item.after}`);
+      }
+    }
+    if (file.habits) {
+      const habits = file.habits.rules.length ? `flagged habits ${file.habits.before} → ${file.habits.after} (${file.habits.rules.join(', ')})` : 'no flagged habits';
+      lines.push(`  ${habits}; banned ${file.banned.before} → ${file.banned.after}${file.changedWords ? `; changed copy ${file.changedWords.before} → ${file.changedWords.after} words` : ''}.`);
+    }
+  }
+  for (const note of result.notes) lines.push('', `${note.file}: ${note.note}.`);
+  lines.push('', result.ok ? `No errors${result.warnings ? `; ${plural(result.warnings, 'warning')} to review` : ''}.` : `${plural(result.errors, 'error')} in ${plural(result.files.filter((file) => file.errors.length).length, 'file')}${result.warnings ? `, and ${plural(result.warnings, 'warning')}` : ''}.`);
+  return `${lines.join('\n')}\n`;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@roughen/cli",
+  "version": "0.3.0",
+  "description": "Lint prose and page copy locally with Roughen, and print revision briefs.",
+  "license": "MIT",
+  "keywords": [
+    "prose",
+    "linter",
+    "cli",
+    "writing",
+    "ai-writing",
+    "copy",
+    "nextjs",
+    "site-copy"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.13"
+  },
+  "bin": {
+    "roughen": "./bin/roughen.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@babel/parser": "7.29.8",
+    "@roughen/config": "^0.2.0",
+    "@roughen/core": "^0.3.0"
+  },
+  "scripts": {
+    "build": "node --check bin/roughen.mjs && node --check lib/config.mjs && node --check lib/lint-file.mjs && node --check lib/jsx.mjs"
+  }
+}