@roughen/cli 0.3.0

package/lib/jsx.mjs

@@ -0,0 +1,494 @@
+import { parse } from '@babel/parser';
+
+/**
+ * Reader-facing copy inside .tsx/.jsx/.ts/.js files: JSX text, copy-bearing
+ * JSX attributes, and string values of copy-named object properties. Parsing
+ * uses @babel/parser (a CLI dependency; core stays dependency-free), so
+ * Roughen never guesses at JavaScript grammar with regular expressions.
+ * Project TypeScript can't serve here: TypeScript 7 no longer exposes an
+ * in-process parser, and the fleet runs both 5.x and 7.x.
+ *
+ * Every fragment carries a role:
+ *   body       paragraphs and descriptions: every rule applies, and an editor may rewrite it
+ *   short      headings, labels, buttons, alt text: too short for density rules, still editable
+ *   protected  leave exactly as written: H1s, titles and headlines, FAQ questions (exact-match
+ *              search queries), keywords, schema names, and verbatim words (quotes,
+ *              testimonials, reviews, citations). Verbatim fragments aren't linted at all.
+ */
+
+// Attributes and keys whose string values are prose a visitor reads.
+const copyAttributes = new Set(['alt', 'title', 'aria-label', 'aria-description', 'placeholder', 'label', 'description', 'summary', 'caption', 'heading', 'subheading', 'subtitle', 'tagline', 'eyebrow', 'cta', 'ctaText', 'ctaLabel', 'buttonText', 'text', 'body', 'intro', 'answer', 'question']);
+const bodyKeys = new Set(['description', 'desc', 'body', 'text', 'content', 'intro', 'summary', 'excerpt', 'answer', 'blurb', 'lede', 'lead', 'copy', 'message', 'paragraph', 'paragraphs', 'details', 'detail', 'bio', 'metaDescription', 'longDescription', 'shortDescription', 'subtext', 'subcopy', 'note', 'explanation', 'definition', 'takeaway', 'overview', 'story']);
+const shortKeys = new Set(['heading', 'subheadline', 'subheading', 'subtitle', 'tagline', 'eyebrow', 'label', 'cta', 'ctaText', 'ctaLabel', 'buttonText', 'alt', 'aria-label', 'placeholder', 'caption', 'stat', 'headers', 'rows', 'cells']);
+const listKeys = new Set(['paragraphs', 'bullets', 'features', 'points', 'benefits', 'highlights', 'steps', 'deliverables', 'includes', 'included', 'items', 'pros', 'cons', 'notes', 'tips', 'examples', 'takeaways', 'rows', 'cells', 'headers']);
+// Search-facing strings: exact titles and questions people search for. Left exactly as written.
+const protectedKey = /^(?:(?:meta|seo|page|og|twitter|document)(?:Title|Headline)|(?:title|headline)(?:[A-Z0-9]\w*)?|question|q|keywords|h1)$/;
+// Verbatim words attributed to someone: any word of the key names one (clientQuote, TESTIMONIALS, sourceName).
+const verbatimWords = new Set(['quote', 'quotes', 'testimonial', 'testimonials', 'review', 'reviews', 'reviewer', 'author', 'attribution', 'citation', 'citations', 'cite', 'publisher']);
+const verbatimKeys = new Set(['sourceName', 'sourceTitle']);
+// Strings under these keys are code or data, never copy, however they read.
+const codeKey = /^(?:className|class|style|styles|css|sx|href|src|srcSet|url|uri|path|pathname|slug|id|key|ref|icon|image|img|logo|video|poster|variant|color|size|type|kind|tone|theme|as|rel|target|format|status|mode|d|fill|stroke|viewBox|sizes|loading|role|email|phone|tel|pattern|regex|query|sql|prompt|systemPrompt|system|instructions|model|template|mimeType|contentType|locale|lang|date|datetime|time|timezone|hash|token|apiKey|secret|env|method|route|redirect|destination|source|permanent|font|fontFamily|animation|transition|easing|gradient|background|border|shadow|cursor|display|position|transform|filter|mask|clipPath|align|justify|direction|name|slot|selector|event|action|endpoint|host|domain|canonical|robots|charset|viewport|manifest|@type|@context|@id)$|(?:ClassName|Class|Classes|Style|Styles|Url|Href|Src|Path|Slug|Id|Key|Icon|Image|Color|Variant|Prompt|Pattern|Regex|Query|Selector|Endpoint)$|^(?:data|on)[-A-Z]/;
+const schemaNameKeys = new Set(['name', 'alternateName', 'legalName']);
+const shortSuffixes = new Set(['title', 'heading', 'headline', 'label', 'cta', 'caption', 'eyebrow', 'tagline', 'subtitle']);
+const bodySuffixes = new Set(['description', 'text', 'copy', 'body', 'summary', 'intro', 'answer', 'paragraph', 'blurb', 'detail', 'details', 'note', 'message']);
+const headingTags = /^h[1-6]$/;
+// Children of these render as code, not copy: a <style>{`...`}</style> block is CSS.
+const codeTags = /^(?:style|script|code|pre)$/;
+// HTML entities JSX decodes in text and attribute strings. Plain JavaScript
+// strings don't decode them, so only JSX fragments are passed through this.
+const entities = {
+  amp: '&', apos: "'", quot: '"', lt: '<', gt: '>', nbsp: ' ', mdash: '—', ndash: '–', hellip: '…',
+  rsquo: '’', lsquo: '‘', rdquo: '”', ldquo: '“', rarr: '→', larr: '←', uarr: '↑', darr: '↓',
+  middot: '·', bull: '•', copy: '©', reg: '®', trade: '™', times: '×', deg: '°', laquo: '«', raquo: '»',
+  eacute: 'é', shy: '­', zwj: '‍', thinsp: ' ', ensp: ' ', emsp: ' ',
+};
+const entityPattern = /&(?:#x([0-9a-f]+)|#(\d+)|([a-z][a-z0-9]*));/gi;
+function decodeEntity(match, hex, decimal, named) {
+  if (hex || decimal) { const code = parseInt(hex ?? decimal, hex ? 16 : 10); return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : null; }
+  return entities[named.toLowerCase()] ?? null;
+}
+// Inline elements continue the surrounding sentence; everything else starts a new one.
+const inlineTags = /^(?:a|abbr|b|bdi|bdo|cite|code|data|dfn|em|i|kbd|mark|q|s|samp|small|span|strong|sub|sup|time|u|var|br|wbr|Link)$/;
+
+/** Words as Roughen counts them in copy reports. */
+export function countWords(text) {
+  return (text.match(/[\p{L}\p{N}]+(?:['’][\p{L}\p{N}]+)*/gu) ?? []).length;
+}
+
+/**
+ * Whether a string under a key Roughen doesn't know reads as prose: five or
+ * more words, mostly words, and a sentence (ending punctuation, or eight or
+ * more words). Class lists, paths, URLs and code don't qualify.
+ */
+export function proseShaped(text) {
+  const value = text.trim();
+  if (countWords(value) < 5 || /[{}<>=\\]|\$\{/.test(value)) return false;
+  if (/^(?:https?:|www\.|\/|\.{1,2}\/|#|@|mailto:)/i.test(value)) return false;
+  const tokens = value.split(/\s+/);
+  if (tokens.every((token) => /^[a-z0-9:\-/[\].#%!_()&>]+$/.test(token)) && tokens.some((token) => /[-:[]/.test(token))) return false;
+  // Mostly plain words: not URLs, paths, 'quoted-keywords' or numbers.
+  const plainWord = (token) => /^[("“‘]?\p{L}[\p{L}\p{M}'’-]*[)"”’.,;:!?]*$/u.test(token) && !/^'.*'[.,;:]?$/.test(token);
+  if (tokens.filter(plainWord).length / tokens.length < 0.6) return false;
+  return /[.!?…:)"'”’]$/.test(value) || countWords(value) >= 8;
+}
+
+/**
+ * Data modules named for attributed words (citations.js, testimonials.ts,
+ * industry-service-citations.js) hold them whole: every string is protected.
+ * Components (.jsx/.tsx) aren't, since a Reviews page has its own headings.
+ */
+export function protectedByName(file) {
+  if (!file || /\.[jt]sx$/i.test(file)) return false;
+  const base = file.split(/[\\/]/).pop().replace(/\.[^.]+$/, '');
+  return keyWords(base).some((word) => /^(?:citations?|testimonials?|reviews?|quotes?)$/.test(word));
+}
+
+// Text written for a model, not a reader.
+const promptWords = new Set(['prompt', 'prompts', 'system', 'instruction', 'instructions', 'template', 'templates', 'regex', 'pattern', 'patterns']);
+
+/** Short names and labels, most of them more than one word: "San Marco", "Naval Station Mayport". Not class lists, units or code. */
+function labelList(texts) {
+  if (texts.length < 3) return false;
+  const label = (text) => {
+    const value = text.trim();
+    return /^[\p{L}\p{N}"“'‘(]/u.test(value) && countWords(value) <= 12 && !/[{}<>=\\;]|\$\{|^https?:|^\/|:\s*\d/.test(value)
+      && !(/^[a-z0-9:\-/[\].#%!_()&>]+(?:\s+[a-z0-9:\-/[\].#%!_()&>]+)*$/.test(value) && /[-:[]/.test(value));
+  };
+  return texts.every(label) && texts.filter((text) => /\s/.test(text.trim())).length * 2 >= texts.length;
+}
+
+function keyWords(key) {
+  return key.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(/[\s_-]+/).filter(Boolean);
+}
+
+/**
+ * Single source of truth for what a property key or JSX attribute holds:
+ * 'ignore' (code or data), 'verbatim', 'protected', 'short', 'body', 'list'
+ * (items are body), or null when unknown (a prose-shaped value counts as body).
+ * Used by extraction, so linting, site reports and verify agree. A project's
+ * `copy` config adds keys to a role, and wins over the defaults.
+ */
+export function classifyKey(key, keys = {}) {
+  if (!key) return null;
+  if (keys.ignore?.includes(key)) return 'ignore';
+  if (keys.protected?.includes(key)) return 'protected';
+  if (keys.short?.includes(key)) return 'short';
+  if (keys.body?.includes(key)) return 'body';
+  if (codeKey.test(key)) return 'ignore';
+  const words = keyWords(key);
+  if (verbatimKeys.has(key) || verbatimWords.has(words[0]) || verbatimWords.has(words.at(-1))) return 'verbatim';
+  if (protectedKey.test(key)) return 'protected';
+  if (shortKeys.has(key)) return 'short';
+  if (listKeys.has(key)) return 'list';
+  if (bodyKeys.has(key)) return 'body';
+  // sectionTitle, cardHeading, introText, seoDescription: the last word names the role.
+  if (shortSuffixes.has(words.at(-1))) return 'short';
+  if (bodySuffixes.has(words.at(-1))) return 'body';
+  return null;
+}
+
+function name(node) {
+  if (!node) return null;
+  if (node.type === 'Identifier' || node.type === 'JSXIdentifier') return node.name;
+  if (node.type === 'StringLiteral') return node.value;
+  if (node.type === 'JSXNamespacedName') return `${node.namespace.name}:${node.name.name}`;
+  if (node.type === 'JSXMemberExpression') return `${name(node.object)}.${node.property.name}`;
+  return null;
+}
+
+const stringNode = (node) => node?.type === 'StringLiteral' || node?.type === 'TemplateLiteral';
+const literalText = (node) => node.type === 'StringLiteral' ? node.value : node.quasis.map((quasi) => quasi.value.cooked ?? quasi.value.raw).join(' ');
+
+/** Parses JS/TS/JSX the way extraction does. Throws a SyntaxError when the file doesn't parse. */
+export function parseSource(source, fileName) {
+  const jsx = !/\.(?:c|m)?ts$/i.test(fileName);
+  return parse(source, {
+    sourceType: 'unambiguous',
+    plugins: [...(/\.(?:c|m)?tsx?$/i.test(fileName) ? ['typescript'] : []), ...(jsx ? ['jsx'] : []), 'decorators-legacy'],
+    errorRecovery: false,
+  });
+}
+
+/**
+ * Fragments of copy with exact source ranges. `group` joins JSX text split by
+ * inline elements (`We build <strong>fast</strong> sites`) back into one
+ * sentence; `role` says what an editor may do with it (see above); `short`
+ * (role isn't body) marks what density rules skip; `key` names the key,
+ * attribute or tag it came from; `inferred` marks prose found under a key
+ * Roughen doesn't know. Options: `keys` ({ body, short, protected, ignore }
+ * arrays from the project's `copy` config) and `protectedFile` (every
+ * fragment is protected). Throws a SyntaxError when the file doesn't parse.
+ */
+export function extractCopy(source, fileName, { keys = {}, protectedFile = false, ast = parseSource(source, fileName) } = {}) {
+  const fragments = [];
+  let groupId = 0;
+  const add = (start, end, group, role, key, extra = {}) => {
+    if (end <= start || !source.slice(start, end).trim()) return;
+    const final = protectedFile && role !== 'verbatim' ? 'protected' : role;
+    fragments.push({ start, end, group, role: final === 'verbatim' ? 'protected' : final, short: final !== 'body', key: key ?? null, ...(final === 'verbatim' ? { verbatim: true } : {}), ...extra });
+  };
+  // A string or template literal. Template quasis share one group: the expressions between them are values.
+  const literal = (node, role, key, { jsxEntities = false, group = ++groupId, inferred = false } = {}) => {
+    const extra = { ...(jsxEntities ? { entities: true } : {}), ...(inferred ? { inferred: true } : {}) };
+    if (node?.type === 'StringLiteral') add(node.start + 1, node.end - 1, group, role, key, extra);
+    else if (node?.type === 'TemplateLiteral') for (const quasi of node.quasis) add(quasi.start, quasi.end, group, role, key, extra);
+  };
+  // Every string in a subtree takes one role: a testimonial object, a keywords array, a schema name.
+  const forced = (node, role, key) => {
+    if (!node || typeof node.type !== 'string') return;
+    if (stringNode(node)) { literal(node, role, key); return; }
+    if (node.type === 'JSXText') { add(node.start, node.end, ++groupId, role, key, { entities: true }); return; }
+    if (node.type === 'ObjectProperty') {
+      const inner = node.computed ? null : name(node.key);
+      if (classifyKey(inner, keys) === 'ignore') return;
+      forced(node.value, role, inner ?? key);
+      return;
+    }
+    if (node.type === 'JSXAttribute') { if (node.value) forced(node.value, role, name(node.name)); return; }
+    for (const field of Object.keys(node)) {
+      if (field === 'loc' || field === 'start' || field === 'end' || field === 'extra' || field === 'key' || field.endsWith('Comments') || field === 'callee') continue;
+      const value = node[field];
+      if (Array.isArray(value)) for (const item of value) forced(item, role, key);
+      else if (value && typeof value === 'object') forced(value, role, key);
+    }
+  };
+  // "a " + b + "c": the string pieces of a concatenation render as one string.
+  const concatenated = (node) => node?.type === 'BinaryExpression' && node.operator === '+' && [node.left, node.right].some((side) => stringNode(side) || concatenated(side));
+  const pieces = (node, role, key, group) => {
+    if (stringNode(node)) literal(node, role, key, { group });
+    else if (node?.type === 'BinaryExpression' && node.operator === '+') { pieces(node.left, role, key, group); pieces(node.right, role, key, group); }
+  };
+  // A value under a known key: strings take the key's role; arrays (of arrays) are items.
+  const keyed = (value, role, key) => {
+    if (stringNode(value)) { literal(value, role, key); return true; }
+    if (concatenated(value)) { pieces(value, role, key, ++groupId); return true; }
+    if (value?.type === 'ArrayExpression') {
+      for (const item of value.elements) if (!keyed(item, role, key) && item) visit(item, null);
+      return true;
+    }
+    return false;
+  };
+  // An unknown key is copy in this file if any of its values reads as prose:
+  // then its short values ("of leads lost to slow intake response") are copy too.
+  const proseKeys = new Set();
+  const scan = (node) => {
+    if (!node || typeof node.type !== 'string') return;
+    if (node.type === 'ObjectProperty' && !node.computed && stringNode(node.value) && proseShaped(literalText(node.value))) {
+      const key = name(node.key);
+      if (classifyKey(key, keys) === null) proseKeys.add(key);
+    }
+    for (const field of Object.keys(node)) {
+      if (field === 'loc' || field === 'start' || field === 'end' || field === 'extra' || field.endsWith('Comments')) continue;
+      const value = node[field];
+      if (Array.isArray(value)) for (const item of value) scan(item);
+      else if (value && typeof value === 'object') scan(value);
+    }
+  };
+  scan(ast.program);
+  // A value under an unknown key: prose-shaped strings are body copy, and a
+  // list of labels ("San Marco", "Mayo Clinic, Florida campus") is short copy.
+  const inferred = (value, key) => {
+    if (stringNode(value) && (proseKeys.has(key) || proseShaped(literalText(value)))) { literal(value, 'body', key, { inferred: true }); return true; }
+    if (value?.type === 'ArrayExpression' && value.elements.length && value.elements.every((item) => stringNode(item))) {
+      const texts = value.elements.map(literalText);
+      const role = texts.some(proseShaped) ? 'body' : labelList(texts) ? 'short' : null;
+      if (!role) return false;
+      for (const item of value.elements) literal(item, role, key, { inferred: true });
+      return true;
+    }
+    return false;
+  };
+  // ['Review your site', 'Send a quote'].map((item) => <li>{item}</li>): an array literal rendered in place.
+  const rendersJsx = (node) => {
+    let found = false;
+    const walk = (child) => {
+      if (found || !child || typeof child.type !== 'string') return;
+      if (child.type === 'JSXElement' || child.type === 'JSXFragment') { found = true; return; }
+      for (const field of Object.keys(child)) {
+        if (field === 'loc' || field === 'start' || field === 'end' || field === 'extra' || field.endsWith('Comments')) continue;
+        const value = child[field];
+        if (Array.isArray(value)) value.forEach(walk); else if (value && typeof value === 'object') walk(value);
+      }
+    };
+    walk(node);
+    return found;
+  };
+
+  const visit = (node, jsxGroup) => {
+    if (!node || typeof node.type !== 'string') return;
+    switch (node.type) {
+      case 'JSXElement': {
+        const tag = name(node.openingElement.name) ?? '';
+        for (const attribute of node.openingElement.attributes) visit(attribute, null);
+        if (codeTags.test(tag)) return;
+        const role = tag === 'h1' || tag === 'title' ? 'protected' : headingTags.test(tag) ? 'short' : 'body';
+        const group = jsxGroup && inlineTags.test(tag) ? jsxGroup : { id: ++groupId, role, tag };
+        for (const child of node.children) visit(child, group);
+        return;
+      }
+      case 'JSXFragment':
+        for (const child of node.children) visit(child, jsxGroup ?? { id: ++groupId, role: 'body', tag: null });
+        return;
+      case 'JSXText':
+        if (jsxGroup) add(node.start, node.end, jsxGroup.id, jsxGroup.role, jsxGroup.tag, { entities: true });
+        return;
+      case 'JSXExpressionContainer': {
+        const expression = node.expression;
+        // {"literal"} inside JSX children renders as text.
+        if (jsxGroup && stringNode(expression)) { literal(expression, jsxGroup.role, jsxGroup.tag, { group: jsxGroup.id }); return; }
+        // {open ? "Close" : "Open"} and {note && "Beta"}: each string branch renders on its own.
+        if (jsxGroup && (expression.type === 'ConditionalExpression' || expression.type === 'LogicalExpression')) {
+          const branches = expression.type === 'ConditionalExpression' ? [expression.test, expression.consequent, expression.alternate] : [expression.left, expression.right];
+          for (const branch of branches) {
+            if (stringNode(branch) && branch !== expression.test && !(expression.type === 'LogicalExpression' && expression.operator === '&&' && branch === expression.left)) literal(branch, jsxGroup.role, jsxGroup.tag);
+            else visit(branch, null);
+          }
+          return;
+        }
+        visit(expression, null);
+        return;
+      }
+      case 'JSXAttribute': {
+        const attribute = name(node.name);
+        if (!node.value) return;
+        const value = node.value.type === 'JSXExpressionContainer' ? node.value.expression : node.value;
+        const kind = classifyKey(attribute, keys);
+        // body="We&apos;ll" decodes; body={"We&apos;ll"} is a JavaScript string and doesn't.
+        const jsxEntities = value === node.value;
+        if (kind === 'ignore') { if (!stringNode(value)) visit(value, null); return; }
+        if (kind === 'verbatim') { forced(value, 'verbatim', attribute); return; }
+        if (kind === 'protected') { forced(value, 'protected', attribute); return; }
+        if (stringNode(value)) {
+          if (copyAttributes.has(attribute) || kind === 'short' || kind === 'body' || kind === 'list') literal(value, kind === 'short' ? 'short' : 'body', attribute, { jsxEntities });
+          else if (kind === null && proseShaped(literalText(value))) literal(value, 'body', attribute, { jsxEntities, inferred: true });
+          return;
+        }
+        // items={['Fast', 'Secure']}: a list prop's strings are copy too.
+        if ((kind || copyAttributes.has(attribute)) && keyed(value, kind === 'short' ? 'short' : 'body', attribute)) return;
+        if (!kind && inferred(value, attribute)) return;
+        visit(value, null);
+        return;
+      }
+      case 'ObjectExpression': {
+        const siblings = new Set(node.properties.map((property) => property.type === 'ObjectProperty' && !property.computed ? name(property.key) : null).filter(Boolean));
+        const schema = siblings.has('@type');
+        const faq = siblings.has('q') || siblings.has('question');
+        for (const property of node.properties) {
+          if (property.type !== 'ObjectProperty') { visit(property, null); continue; }
+          const key = property.computed ? null : name(property.key);
+          const value = property.value;
+          if (schema && schemaNameKeys.has(key)) { forced(value, 'protected', key); continue; }
+          // { q, a } is a question and its answer.
+          const kind = faq && key === 'a' ? 'body' : classifyKey(key, keys);
+          if (kind === 'ignore') { if (!stringNode(value)) visit(value, null); continue; }
+          if (kind === 'verbatim' || kind === 'protected') { forced(value, kind, key); continue; }
+          if (kind && keyed(value, kind === 'list' ? 'body' : kind, key)) continue;
+          if (!kind && key && inferred(value, key)) continue;
+          visit(value, null);
+        }
+        return;
+      }
+      case 'CallExpression': {
+        const callee = node.callee;
+        if (callee?.type === 'MemberExpression' && name(callee.property) === 'map' && callee.object.type === 'ArrayExpression' && callee.object.elements.length
+          && callee.object.elements.every((item) => stringNode(item)) && callee.object.elements.some((item) => /\s/.test(literalText(item).trim())) && rendersJsx(node.arguments[0])) {
+          keyed(callee.object, 'body', 'map');
+          for (const argument of node.arguments) visit(argument, null);
+          return;
+        }
+        for (const field of ['callee', 'arguments', 'typeArguments', 'typeParameters']) {
+          const value = node[field];
+          if (Array.isArray(value)) for (const item of value) visit(item, null); else visit(value, null);
+        }
+        return;
+      }
+      case 'VariableDeclarator':
+      case 'AssignmentPattern': {
+        // const description = "..." and ({ description = "..." }) hold copy like a description key does.
+        const [target, value] = node.type === 'VariableDeclarator' ? [node.id, node.init] : [node.left, node.right];
+        const key = target?.type === 'Identifier' ? target.name : null;
+        const kind = key && value ? classifyKey(key, keys) : null;
+        // const TESTIMONIALS = [...] holds verbatim words, whatever its items' keys.
+        if (kind === 'verbatim' && verbatimWords.has(keyWords(key).at(-1))) { forced(value, 'verbatim', key); return; }
+        if (kind === 'protected' && stringNode(value)) { literal(value, 'protected', key); return; }
+        if ((kind === 'body' || kind === 'short' || kind === 'list') && keyed(value, kind === 'short' ? 'short' : 'body', key)) return;
+        // const facts = ['…', '…']: an array of prose under any name that isn't a prompt or code.
+        if (kind === null && key && value?.type === 'ArrayExpression' && !keyWords(key).some((word) => promptWords.has(word)) && inferred(value, key)) return;
+        if (node.type === 'VariableDeclarator') visit(target, null);
+        visit(value, null);
+        return;
+      }
+      default:
+        for (const key of Object.keys(node)) {
+          if (key === 'loc' || key === 'start' || key === 'end' || key === 'extra' || key === 'leadingComments' || key === 'trailingComments' || key === 'innerComments') continue;
+          const value = node[key];
+          if (Array.isArray(value)) for (const item of value) visit(item, jsxGroup);
+          else if (value && typeof value === 'object') visit(value, jsxGroup);
+        }
+    }
+  };
+  visit(ast.program, null);
+  return fragments.sort((a, b) => a.start - b.start);
+}
+
+/**
+ * One virtual plain-text document per kind of copy, with a map back to the
+ * source. Body copy is joined into paragraphs so density rules see the page
+ * as a reader does; short and protected copy (headings, labels, titles) is
+ * linted separately, without density rules. Verbatim words aren't linted.
+ */
+export function virtualDocuments(source, fragments) {
+  const build = (items) => {
+    let text = '';
+    const segments = [];
+    let previousGroup = null;
+    let previousEnd = 0;
+    for (const fragment of items) {
+      // {' '} between inline elements renders as a space the fragments don't carry.
+      if (previousGroup !== null) text += fragment.group !== previousGroup ? '\n\n' : /\{\s*(['"`])\s+\1\s*\}/.test(source.slice(previousEnd, fragment.start)) ? ' ' : '';
+      previousEnd = fragment.end;
+      // Plain characters map back one to one. A decoded entity is its own
+      // segment: one virtual character standing for the whole `&apos;`.
+      const raw = source.slice(fragment.start, fragment.end);
+      let cursor = 0;
+      const plain = (to) => {
+        if (to <= cursor) return;
+        segments.push({ virtualStart: text.length, sourceStart: fragment.start + cursor, length: to - cursor, sourceLength: to - cursor });
+        text += raw.slice(cursor, to);
+      };
+      if (fragment.entities) {
+        for (const match of raw.matchAll(entityPattern)) {
+          const decoded = decodeEntity(...match);
+          if (decoded === null) continue;
+          plain(match.index);
+          segments.push({ virtualStart: text.length, sourceStart: fragment.start + match.index, length: decoded.length, sourceLength: match[0].length });
+          text += decoded;
+          cursor = match.index + match[0].length;
+        }
+      }
+      plain(raw.length);
+      previousGroup = fragment.group;
+    }
+    return { text, segments };
+  };
+  return {
+    body: build(fragments.filter((fragment) => fragment.role === 'body')),
+    short: build(fragments.filter((fragment) => fragment.role !== 'body' && !fragment.verbatim)),
+  };
+}
+
+/** The text a group of fragments renders, entities decoded: what a reader sees. */
+export function groupText(source, fragments) {
+  return virtualDocuments(source, fragments.map((fragment) => ({ ...fragment, role: 'body', verbatim: false }))).body.text;
+}
+
+// A point inside a segment. Plain segments map by offset; a decoded entity maps
+// to its start, or to its end once the point is past its first character.
+function sourcePoint(segment, offset) {
+  const sourceLength = segment.sourceLength ?? segment.length;
+  if (sourceLength === segment.length) return segment.sourceStart + offset;
+  return segment.sourceStart + (offset === 0 ? 0 : sourceLength);
+}
+
+/** Maps a virtual range back to the source, or null when it starts in a separator Roughen inserted. */
+export function toSourceRange(segments, [start, end]) {
+  const segment = segments.findLast((item) => item.virtualStart <= start);
+  if (!segment) return null;
+  const offset = start - segment.virtualStart;
+  if (offset >= segment.length && !(offset === segment.length && start === end)) return null;
+  if (start === end) { const point = sourcePoint(segment, offset); return [point, point]; }
+  // A range can cross segments: inline elements split a sentence, and entities split a fragment.
+  const last = segments.findLast((item) => item.virtualStart < end);
+  if (!last || end - last.virtualStart > last.length) return null;
+  return [sourcePoint(segment, offset), sourcePoint(last, end - last.virtualStart)];
+}
+
+/** The fragment containing a source offset, for tagging findings with a role. Fragments are sorted and disjoint. */
+export function fragmentAt(fragments, offset) {
+  let low = 0; let high = fragments.length - 1;
+  while (low <= high) {
+    const middle = (low + high) >>> 1;
+    const fragment = fragments[middle];
+    if (offset < fragment.start) high = middle - 1;
+    else if (offset >= fragment.end) low = middle + 1;
+    else return fragment;
+  }
+  return null;
+}
+
+/**
+ * Prose-shaped strings the copy reader didn't take, by where they sit
+ * ("key:prompt", "call:join", "attribute:data-tip"). Site reports list them
+ * so a project can add a key to its copy config if one of them is copy.
+ * Import paths and directives are skipped.
+ */
+export function missedCopy(source, ast, strings) {
+  const taken = strings.map((item) => item.range).sort((a, b) => a[0] - b[0]);
+  const covered = (node) => taken.some(([start, end]) => start < node.end && end > node.start);
+  const out = [];
+  const walk = (node, context) => {
+    if (!node || typeof node.type !== 'string') return;
+    if (node.type === 'ImportDeclaration' || node.type === 'ExportAllDeclaration' || node.type === 'Directive' || (node.type === 'ExportNamedDeclaration' && node.source)) return;
+    if (node.type === 'StringLiteral' || node.type === 'JSXText' || (node.type === 'TemplateLiteral' && node.expressions.length === 0)) {
+      const text = node.type === 'TemplateLiteral' ? node.quasis[0].value.raw : node.value;
+      if (proseShaped(text) && !covered(node)) out.push({ context: context ?? 'other', words: countWords(text) });
+      return;
+    }
+    let next = context;
+    // Keys and attributes that hold code (className, fontFamily) aren't candidates, however they read.
+    if ((node.type === 'ObjectProperty' && !node.computed && classifyKey(name(node.key)) === 'ignore') || (node.type === 'JSXAttribute' && classifyKey(name(node.name)) === 'ignore')) return;
+    if (node.type === 'ObjectProperty' && !node.computed) next = `key:${name(node.key)}`;
+    else if (node.type === 'JSXAttribute') next = `attribute:${name(node.name)}`;
+    else if (node.type === 'CallExpression') next = `call:${node.callee?.type === 'MemberExpression' ? name(node.callee.property) : name(node.callee)}`;
+    else if (node.type === 'VariableDeclarator') next = `variable:${node.id?.name ?? '?'}`;
+    else if (node.type === 'ReturnStatement') next = 'return';
+    for (const key of Object.keys(node)) {
+      if (key === 'loc' || key === 'start' || key === 'end' || key === 'extra' || key.endsWith('Comments')) continue;
+      const value = node[key];
+      if (Array.isArray(value)) for (const item of value) walk(item, next);
+      else if (value && typeof value === 'object') walk(value, next);
+    }
+  };
+  walk(ast.program, null);
+  return out;
+}

package/lib/lint-file.mjs

@@ -0,0 +1,86 @@
+import path from 'node:path';
+import { lint } from '@roughen/core';
+import { extractCopy, virtualDocuments, toSourceRange, fragmentAt, countWords } from './jsx.mjs';
+import { copyOptions } from './config.mjs';
+
+/** Single source of truth for which files Roughen reads, shared by the CLI and the Claude plugin. */
+export const proseFormats = { '.md': 'md', '.mdx': 'mdx', '.html': 'html', '.htm': 'html', '.txt': 'text' };
+export const sourceExtensions = new Set(['.tsx', '.jsx', '.ts', '.js', '.mjs', '.cjs', '.mts', '.cts']);
+
+/** 'md' | 'mdx' | 'html' | 'text' for prose, 'copy' for JS/TS source whose strings are linted. */
+export function formatFor(file) {
+  const extension = path.extname(file).toLowerCase();
+  if (proseFormats[extension]) return proseFormats[extension];
+  if (sourceExtensions.has(extension) && !/\.d\.[cm]?ts$/i.test(file)) return 'copy';
+  return null;
+}
+
+// Density rules measure paragraphs; headings, buttons and labels are too short to judge.
+const densityRules = ['structure/list-saturation', 'structure/contrast-frame', 'hedge/generalizer', 'structure/reveal-frame', 'rhythm/low-variance'];
+
+function locator(source) {
+  const starts = [0];
+  for (let i = 0; i < source.length; i++) if (source[i] === '\n') starts.push(i + 1);
+  return (offset) => {
+    let low = 0; let high = starts.length;
+    while (low + 1 < high) { const middle = (low + high) >>> 1; if (starts[middle] <= offset) low = middle; else high = middle; }
+    return { line: low + 1, column: offset - starts[low] + 1 };
+  };
+}
+
+/**
+ * Copy inside JS/TS: lint the page's body copy as one virtual document and its
+ * short copy separately, then map every finding back to the source file.
+ * Fixes are never applied to source files; findings are for review.
+ */
+function lintCopy(source, file, config, ast) {
+  const fragments = extractCopy(source, file, { ...copyOptions(file, config), ...(ast ? { ast } : {}) });
+  const { body, short } = virtualDocuments(source, fragments);
+  const base = { rules: config.rules, format: 'text', register: config.register };
+  // Banned terms and characters apply to every string a reader sees, headings included.
+  const voice = { banned: config.voice?.banned, bannedCharacters: config.voice?.bannedCharacters, bannedPatterns: config.voice?.bannedPatterns };
+  const bodyResult = lint(body.text, { ...base, voice });
+  const shortRules = { ...config.rules };
+  for (const id of densityRules) shortRules[id] = 'off';
+  const shortResult = lint(short.text, { ...base, rules: shortRules, voice });
+  const locate = locator(source);
+  const findings = [];
+  for (const [result, map] of [[bodyResult, body.segments], [shortResult, short.segments]]) {
+    for (const finding of result.findings) {
+      if (finding.ruleId === 'artifact/double-space') continue; // JSX collapses whitespace when it renders
+      const range = toSourceRange(map, finding.range);
+      if (!range) continue;
+      // A character spelled as an entity (&nbsp;, &rsquo;) was typed on purpose, not pasted in.
+      if (finding.ruleId.startsWith('artifact/') && /^&(?:#x[0-9a-f]+|#\d+|[a-z][a-z0-9]*);$/i.test(source.slice(...range))) continue;
+      const fixRange = finding.fix && toSourceRange(map, finding.fix.range);
+      const first = locate(range[0]); const last = locate(range[1]);
+      const { fix, ...rest } = finding;
+      // The role of the string it's in: an editor may rewrite body and short copy, never protected copy.
+      const fragment = fragmentAt(fragments, range[0]);
+      findings.push({ ...rest, range, loc: { ...first, endLine: last.line, endColumn: last.column }, ...(fix && fixRange ? { fix: { range: fixRange, text: fix.text } } : {}), role: fragment?.role ?? null, key: fragment?.key ?? null });
+    }
+  }
+  // Required terms count anywhere on the page, headings included.
+  const required = lint(`${body.text}\n\n${short.text}`, { format: 'text', rules: config.rules, voice: { required: config.voice?.required } })
+    .findings.filter((finding) => finding.ruleId === 'voice/required');
+  findings.push(...required.map((finding) => ({ ...finding, loc: { line: 1, column: 1, endLine: 1, endColumn: 1 } })));
+  findings.sort((a, b) => a.range[0] - b.range[0]);
+  return { ...bodyResult, findings, copy: copySummary(source, fragments, locate, body) };
+}
+
+/** Every copy string with its role, key and line, and word totals per role: what an editor may rewrite. */
+function copySummary(source, fragments, locate, body) {
+  const words = { body: 0, short: 0, protected: 0 };
+  const strings = fragments.map((fragment) => {
+    const count = countWords(source.slice(fragment.start, fragment.end));
+    words[fragment.role] += count;
+    return { range: [fragment.start, fragment.end], line: locate(fragment.start).line, role: fragment.role, key: fragment.key, words: count, ...(fragment.verbatim ? { verbatim: true } : {}), ...(fragment.inferred ? { inferred: true } : {}) };
+  });
+  return { fragments: fragments.length, bodyCharacters: body.text.length, words, strings };
+}
+
+/** Lints one file's text. `format` comes from formatFor; 'copy' means JS/TS source (`ast` reuses a parse). */
+export function lintSource(source, { file, format, config = {}, fix = false, careful = false, ast = null }) {
+  if (format === 'copy') return lintCopy(source, file ?? 'input.tsx', config, ast);
+  return lint(source, { rules: config.rules, voice: config.voice, register: config.register, format, fix, careful });
+}

package/lib/review.mjs

@@ -0,0 +1,60 @@
+import { applyFixes, revisionBrief, scopeFindings } from '@roughen/core';
+import { lintSource } from './lint-file.mjs';
+
+/** Lines listed before "and N more" in a protected-strings note. */
+const maxProtectedLines = 12;
+
+const lineList = (lines) => `${lines.slice(0, maxProtectedLines).join(', ')}${lines.length > maxProtectedLines ? `, and ${lines.length - maxProtectedLines} more` : ''}`;
+
+/**
+ * Protected strings in component copy: search-facing titles, H1s, FAQ
+ * questions, keywords, schema names, and verbatim words. The brief tells the
+ * editor to leave them alone, and findings inside them (a banned character in
+ * an H1, say) go to the owner instead of the rewrite list.
+ */
+function protectedNote(copy, findings, author) {
+  if (!copy) return null;
+  const strings = copy.strings.filter((item) => item.role === 'protected');
+  if (!strings.length) return null;
+  const lines = [...new Set(strings.map((item) => item.line))];
+  const flagged = findings.filter((finding) => finding.role === 'protected');
+  const flaggedLines = [...new Set(flagged.map((finding) => finding.loc.line))];
+  const constraint = author
+    ? `Fix only what's flagged in the ${strings.length} protected string(s) (line ${lineList(lines)}). H1s, titles and headlines, FAQ questions, keywords and schema names are matched exactly by search, and quotations and citations are someone's words, so don't otherwise reword them.`
+    : `Leave the ${strings.length} protected string(s) exactly as written: H1s, titles and headlines, FAQ questions, keywords, schema names, quotations and citations (line ${lineList(lines)}).`;
+  const note = flagged.length ? `${flagged.length} finding(s) sit in protected strings (line ${lineList(flaggedLines)}). Don't edit them; report them to the page's owner.` : '';
+  return { count: strings.length, lines, findings: flagged.length, constraint, note };
+}
+
+/**
+ * Single source of truth for reviewing a piece of copy on every surface: the
+ * CLI's --brief, the Claude plugin hook, the MCP server and site plans. Lints,
+ * optionally narrows to the regions just written, and returns the revision
+ * brief, the mechanical fixes Roughen can apply itself, and the safely fixed
+ * text. For component copy the brief covers only what an editor may rewrite.
+ */
+export function review(source, { file, format, config = {}, regions = null, maxExcerpts = 8, linted = null, author = false } = {}) {
+  linted ??= lintSource(source, { file, format, config });
+  const result = regions ? { ...linted, findings: scopeFindings(linted.findings, regions) } : linted;
+  const guarded = protectedNote(linted.copy, result.findings, author);
+  // Protection stops an editor rewriting strings someone else settled. Whoever
+  // just wrote the copy (the plugin hook's Claude) fixes its own findings, protected or not.
+  const editable = guarded && !author ? result.findings.filter((finding) => finding.role !== 'protected') : result.findings;
+  const brief = revisionBrief(source, { findings: editable }, { maxExcerpts, constraints: guarded ? [guarded.constraint] : [] });
+  if (guarded) {
+    brief.protected = { strings: guarded.count, lines: guarded.lines, findings: guarded.findings };
+    if (guarded.note && !author) brief.text = brief.text ? `${brief.text}\n\n${guarded.note}` : guarded.note;
+  }
+  // Invisible characters, assistant framing, spacing: no judgment needed.
+  const mechanical = editable.filter((finding) => finding.fix && finding.fixSafety === 'safe' && finding.severity !== 'info');
+  // Source files are never rewritten; their copy is reviewed in place.
+  const fixed = format === 'copy' ? null : applyFixes(source, result.findings);
+  return { result, brief, mechanical, fixed };
+}
+
+/** One line naming the mechanical issues, for surfaces that hand them to a writer. */
+export function mechanicalSummary(mechanical, limit = 6) {
+  if (!mechanical.length) return '';
+  const items = [...new Set(mechanical.map((finding) => `${finding.message} (line ${finding.loc.line})`))];
+  return `Remove ${mechanical.length} mechanical issue(s): ${items.slice(0, limit).join('; ')}${items.length > limit ? '; …' : ''}.`;
+}