@roughen/core 0.3.0

package/dist/sentences.js

@@ -0,0 +1,95 @@
+import { protectedTokenRanges } from './protected-tokens.js';
+const abbreviations = new Set([
+    'dr', 'mr', 'mrs', 'ms', 'prof', 'sr', 'jr', 'st',
+    'e.g', 'i.e', 'etc', 'cf', 'vs', 'al',
+    'inc', 'ltd', 'co', 'corp', 'dept', 'est',
+]);
+/** Width of the letter code point ending at `end`, or 0. Surrogate pairs decode as `/u` does. */
+function letterBefore(text, end) {
+    const low = text.charCodeAt(end - 1);
+    const high = text.charCodeAt(end - 2);
+    const width = low >= 0xDC00 && low <= 0xDFFF && high >= 0xD800 && high <= 0xDBFF ? 2 : end > 0 ? 1 : 0;
+    return width && /^\p{L}$/u.test(text.slice(end - width, end)) ? width : 0;
+}
+/**
+ * The chain `/([\p{L}]+(?:\.[\p{L}]+)*)$/u` matches on `text.slice(0, end)`,
+ * scanned backward in time proportional to the chain instead of the text.
+ */
+function precedingChain(text, end) {
+    let start = end;
+    for (let width = 0;;) {
+        if ((width = letterBefore(text, start)))
+            start -= width;
+        else if (start < end && text[start - 1] === '.' && letterBefore(text, start - 1))
+            start--;
+        else
+            return text.slice(start, end);
+    }
+}
+/** Deterministic segmentation with original UTF-16 ranges; it does not infer authorship. */
+export function segmentSentences(text, offset = 0) {
+    if (!Number.isSafeInteger(offset) || offset < 0)
+        throw new RangeError('Sentence offset must be a non-negative safe integer.');
+    const result = [];
+    const protectedRanges = protectedTokenRanges(text);
+    const push = (start, end) => {
+        while (start < end && /\s/.test(text[start]))
+            start++;
+        while (end > start && /\s/.test(text[end - 1]))
+            end--;
+        if (end <= start)
+            return;
+        const sentence = text.slice(start, end);
+        const wordCount = (sentence.match(/[\p{L}\p{N}]+(?:['’.-][\p{L}\p{N}]+)*/gu) ?? []).length;
+        if (wordCount)
+            result.push({ text: sentence, range: [offset + start, offset + end], wordCount });
+    };
+    let start = 0;
+    let protectedIndex = 0;
+    // Every mark before `settled` shares a terminal group already found not to end a sentence.
+    let settled = 0;
+    const opener = /[\p{Lu}\p{Lt}\p{N}"'“‘([{]/uy;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (!/[.!?]/.test(char) || i < settled)
+            continue;
+        while (protectedIndex < protectedRanges.length && protectedRanges[protectedIndex][1] <= i)
+            protectedIndex++;
+        const protectedRange = protectedRanges[protectedIndex];
+        if (protectedRange && i >= protectedRange[0] && i < protectedRange[1])
+            continue;
+        if (char === '.') {
+            if (text[i - 1] === '.' || text[i + 1] === '.')
+                continue;
+            if (/\d/.test(text[i - 1] ?? '') && /\d/.test(text[i + 1] ?? ''))
+                continue;
+        }
+        let end = i + 1;
+        while (/[.!?]/.test(text[end] ?? '') && end < text.length)
+            end++;
+        while (/["'”’\])}]/.test(text[end] ?? '') && end < text.length)
+            end++;
+        let next = end;
+        while (next < text.length && /\s/.test(text[next]))
+            next++;
+        opener.lastIndex = next;
+        if (!(next === text.length || (next > end && opener.test(text)))) {
+            settled = end;
+            continue;
+        }
+        // The abbreviation lookback runs last, so only a real boundary candidate pays for it.
+        if (char === '.') {
+            const preceding = precedingChain(text, i);
+            if (abbreviations.has(preceding.toLowerCase()))
+                continue;
+            if (/^(?:\p{Lu}\.)*\p{Lu}$/u.test(preceding))
+                continue;
+        }
+        push(start, end);
+        start = next;
+        i = next - 1;
+    }
+    push(start, text.length);
+    return result;
+}
+//# sourceMappingURL=sentences.js.map

package/dist/sentences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentences.js","sourceRoot":"","sources":["../src/sentences.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,140 @@
+/** All ranges are half-open UTF-16 offsets into the untouched source string. */
+export type Range = [number, number];
+export type Format = 'text' | 'md' | 'mdx' | 'html' | 'source';
+export type Severity = 'error' | 'warn' | 'info';
+export type FixSafety = 'safe' | 'careful' | 'manual';
+export interface Block {
+    kind: 'paragraph' | 'heading' | 'listItem' | 'blockquote' | 'code' | 'html';
+    /** A length-preserving prose view. Protected syntax is replaced with spaces. */
+    text: string;
+    sourceRange: Range;
+    depth?: number;
+    skip: boolean;
+}
+export interface Document {
+    source: string;
+    format: Format;
+    blocks: Block[];
+    protectedRanges: Range[];
+    /** Code: fences, spans, frontmatter, raw HTML code and expressions. A subset of protectedRanges. */
+    codeRanges: Range[];
+    /** Verbatim quotations and blockquotes. A subset of protectedRanges. */
+    quoteRanges: Range[];
+}
+export interface MarkdownLinkTarget {
+    /** Exact source spelling, including any Markdown backslash escapes. */
+    target: string;
+    sourceRange: Range;
+    kind: 'inline' | 'reference-definition';
+}
+export interface Sentence {
+    text: string;
+    range: Range;
+    wordCount: number;
+}
+export interface Finding {
+    ruleId: string;
+    severity: Severity;
+    message: string;
+    why: string;
+    range: Range;
+    loc: {
+        line: number;
+        column: number;
+        endLine: number;
+        endColumn: number;
+    };
+    fix?: {
+        range: Range;
+        text: string;
+    };
+    fixSafety: FixSafety;
+    /** Confidence in the described mechanical match, never authorship probability. */
+    confidence: number;
+    evidence?: Record<string, number | string>;
+}
+export type RuleFinding = Omit<Finding, 'ruleId' | 'severity' | 'loc'>;
+export type RuleSetting = Severity | 'off' | [Severity | 'off', Record<string, unknown>];
+/**
+ * Which human baseline the density rules measure against. 'article' is the
+ * 110 human articles every threshold was fit on; 'marketing' swaps in the
+ * thresholds fit on human marketing pages where they differ (list saturation).
+ */
+export type Register = 'article' | 'marketing';
+/** A character the project bans outright in copy, reported at every occurrence. */
+export interface BannedCharacter {
+    character: string;
+    use?: string;
+    why?: string;
+}
+/** A pattern (a regular expression source) the project bans outright in copy. */
+export interface BannedPattern {
+    pattern: string;
+    flags?: string;
+    message?: string;
+    use?: string;
+}
+export interface Config {
+    format?: Format;
+    fix?: boolean;
+    careful?: boolean;
+    register?: Register;
+    rules?: Record<string, RuleSetting>;
+    voice?: {
+        banned?: {
+            term: string;
+            use?: string;
+        }[];
+        required?: string[];
+        /** Absolute bans, whatever the density: em dashes on a site that forbids them, say. */
+        bannedCharacters?: (string | BannedCharacter)[];
+        bannedPatterns?: BannedPattern[];
+    };
+}
+export type DensityFamily = 'series' | 'contrast' | 'generalizer' | 'reveal' | 'emDash' | 'semicolon';
+/** Instances of each structural habit in editable body prose, with the words they're measured against. */
+export interface DensityProfile {
+    words: number;
+    instances: Record<DensityFamily, Range[]>;
+}
+export interface RuleContext {
+    document: Document;
+    config: Config;
+    register: Register;
+    options: Record<string, unknown>;
+    /** Sentences of editable body prose (paragraphs and list items), in source order. */
+    sentences: Sentence[];
+    profile: DensityProfile;
+}
+export interface Rule {
+    id: string;
+    severity: Severity;
+    description: string;
+    /** Registry order is the stable tie-breaker for overlapping fixes. */
+    check(context: RuleContext): RuleFinding[];
+}
+export interface Metrics {
+    sentenceWords: number[];
+    sentenceCount: number;
+    wordCount: number;
+    meanSentenceLength: number | null;
+    sentenceLengthCV: number | null;
+    meanAbsoluteSuccessiveDifference: number | null;
+}
+export interface Result {
+    /** With fix:true these findings refer to fixed, otherwise to the input. */
+    findings: Finding[];
+    /** No calibrated corpus exists yet. Never invent a texture or AI score. */
+    score: null;
+    calibration: {
+        status: 'unavailable';
+        reason: string;
+    };
+    metrics: Metrics;
+    fixed?: string;
+    fixes?: {
+        applied: number;
+        passes: number;
+        converged: boolean;
+    };
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist-cjs/baselines.d.ts

@@ -0,0 +1,55 @@
+/** Human-writing baselines behind Roughen's density and rhythm rules. */
+export declare const baselines: {
+    readonly corpus: {
+        readonly id: "human-110";
+        readonly documents: 110;
+        readonly description: "Pre-2021 human-written technical, service, content and UX articles (discovery-001 and pilot-001 originals).";
+    };
+    /** 95th percentile of per-document instances per 1,000 body words (documents of 300+ words). */
+    readonly density: {
+        series: {
+            p95: number;
+        };
+        contrast: {
+            p95: number;
+        };
+        generalizer: {
+            p95: number;
+        };
+        reveal: {
+            p95: number;
+        };
+        emDash: {
+            p95: number;
+        };
+        semicolon: {
+            p95: number;
+        };
+    };
+    readonly sentences: {
+        /** 95th percentile of per-document mean sentence length, in words. */
+        readonly meanWordsP95: 22.67;
+        /** 90th percentile of individual human sentence lengths, in words. */
+        readonly longWords: 28;
+    };
+    readonly rhythm: {
+        /** 5th percentile of the coefficient of variation of sentence length. */
+        readonly cvP5: 0.341;
+    };
+    /** Thresholds fit on other registers. Anything a register doesn't set falls back to the values above. */
+    readonly registers: {
+        readonly marketing: {
+            readonly corpus: {
+                readonly id: "marketing-001-fit";
+                readonly documents: 164;
+                readonly measured: 112;
+                readonly description: "Pre-2021 human marketing pages (marketing-001), the 70% fit split by host. Unrated.";
+            };
+            readonly density: {
+                series: {
+                    p95: number;
+                };
+            };
+        };
+    };
+};

package/dist-cjs/baselines.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.baselines = void 0;
+/** Human-writing baselines behind Roughen's density and rhythm rules. */
+exports.baselines = {
+    corpus: {
+        id: 'human-110',
+        documents: 110,
+        description: 'Pre-2021 human-written technical, service, content and UX articles (discovery-001 and pilot-001 originals).',
+    },
+    /** 95th percentile of per-document instances per 1,000 body words (documents of 300+ words). */
+    density: {
+        series: { p95: 8.43 },
+        contrast: { p95: 1.94 },
+        generalizer: { p95: 4.36 },
+        reveal: { p95: 0 },
+        emDash: { p95: 5.97 },
+        semicolon: { p95: 2.58 },
+    },
+    sentences: {
+        /** 95th percentile of per-document mean sentence length, in words. */
+        meanWordsP95: 22.67,
+        /** 90th percentile of individual human sentence lengths, in words. */
+        longWords: 28,
+    },
+    rhythm: {
+        /** 5th percentile of the coefficient of variation of sentence length. */
+        cvP5: 0.341,
+    },
+    /** Thresholds fit on other registers. Anything a register doesn't set falls back to the values above. */
+    registers: {
+        marketing: {
+            corpus: {
+                id: 'marketing-001-fit',
+                documents: 164,
+                measured: 112,
+                description: 'Pre-2021 human marketing pages (marketing-001), the 70% fit split by host. Unrated.',
+            },
+            density: {
+                series: { p95: 19.87 },
+            },
+        },
+    },
+};
+//# sourceMappingURL=baselines.js.map

package/dist-cjs/baselines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baselines.js","sourceRoot":"","sources":["../src/baselines.ts"],"names":[],"mappings":";;;AAGA,yEAAyE;AAC5D,QAAA,SAAS,GAAG;IACvB,MAAM,EAAE;QACN,EAAE,EAAE,WAAW;QACf,SAAS,EAAE,GAAG;QACd,WAAW,EAAE,6GAA6G;KAC3H;IACD,gGAAgG;IAChG,OAAO,EAAE;QACP,MAAM,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE;QACrB,QAAQ,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE;QACvB,WAAW,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE;QAC1B,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE;QAClB,MAAM,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE;QACrB,SAAS,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE;KACwB;IAClD,SAAS,EAAE;QACT,sEAAsE;QACtE,YAAY,EAAE,KAAK;QACnB,sEAAsE;QACtE,SAAS,EAAE,EAAE;KACd;IACD,MAAM,EAAE;QACN,yEAAyE;QACzE,IAAI,EAAE,KAAK;KACZ;IACD,yGAAyG;IACzG,SAAS,EAAE;QACT,SAAS,EAAE;YACT,MAAM,EAAE;gBACN,EAAE,EAAE,mBAAmB;gBACvB,SAAS,EAAE,GAAG;gBACd,QAAQ,EAAE,GAAG;gBACb,WAAW,EAAE,qFAAqF;aACnG;YACD,OAAO,EAAE;gBACP,MAAM,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE;aACmC;SAC5D;KACF;CACO,CAAC"}

package/dist-cjs/brief.d.ts

@@ -0,0 +1,45 @@
+import type { Finding, Range, Result } from './types.js';
+export interface BriefItem {
+    ruleId: string;
+    /** What to do, in one instruction. */
+    instruction: string;
+    /** Why the change helps a reader. */
+    why: string;
+    /** How many of the excerpts to rewrite. Density rules only need to drop below the baseline. */
+    rewriteAtLeast: number;
+    excerpts: {
+        text: string;
+        line: number;
+        range: [number, number];
+    }[];
+}
+export interface RevisionBrief {
+    /** False when nothing needs a model-assisted revision. */
+    needed: boolean;
+    items: BriefItem[];
+    /** Always-on rules for any rewrite: what must not change. */
+    constraints: string[];
+    /** The brief rendered as plain text for a prompt or hook message. */
+    text: string;
+}
+export interface BriefOptions {
+    /** Excerpts shown per rule. Default 8. */
+    maxExcerpts?: number;
+    /** Include info-severity findings. Default false. */
+    includeInfo?: boolean;
+    /** Extra constraints from the caller, such as project voice rules. */
+    constraints?: string[];
+}
+/**
+ * Deterministic revision instructions from lint findings. Roughen never calls
+ * a model; the host (Claude, Signal) does the rewrite and then checks it with
+ * comparePreservation. Single source of truth for how findings become
+ * rewrite instructions on every surface.
+ */
+export declare function revisionBrief(source: string, result: Pick<Result, 'findings'>, options?: BriefOptions): RevisionBrief;
+/**
+ * Findings inside `regions`, with each density rule's rewrite target scaled to
+ * the share of its instances found there. Single source of truth for
+ * region-scoped review: the plugin's edit hook and Signal's per-section revision.
+ */
+export declare function scopeFindings(findings: readonly Finding[], regions: readonly Range[]): Finding[];

package/dist-cjs/brief.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.revisionBrief = revisionBrief;
+exports.scopeFindings = scopeFindings;
+const ranges_js_1 = require("./ranges.js");
+const preserve_js_1 = require("./preserve.js");
+const constraints = [
+    'Keep every number, price, date, name, link, code sample and quotation exactly as written.',
+    "Don't add facts, examples, statistics or claims that aren't already in the text.",
+    'Keep the headings and the order of sections.',
+    `Keep the length within ${Math.round(preserve_js_1.revisionLengthTolerance * 100)}% of the original.`,
+    "Change only the flagged passages. Leave sentences that aren't flagged alone.",
+];
+// Bans are reported per occurrence and every one must go, whichever character or pattern it is.
+const banRules = new Set(['voice/banned-character', 'voice/banned-pattern']);
+function instructionFor(finding, group) {
+    const count = Number(finding.evidence?.count ?? 1);
+    const at = Number(finding.evidence?.rewriteAtLeast ?? 1);
+    switch (finding.ruleId) {
+        case 'voice/banned-character': {
+            const characters = [...new Set(group.map((item) => `“${item.evidence?.character}”`))].join(', ');
+            const advice = [...new Set(group.map((item) => item.evidence?.advice).filter(Boolean))].join(' ');
+            return `Remove banned characters: rewrite all ${group.length} of these passages without ${characters}, which the project bans outright.${advice ? ` ${advice}` : ''}`;
+        }
+        case 'voice/banned-pattern': return `Remove banned phrasing: rewrite all ${group.length} of these passages. The project bans each outright.`;
+        case 'structure/list-saturation': return `Cut comma series: rewrite at least ${at} of these ${count} "A, B, and C" lists so the sentence names the one or two items that matter and says something specific about them.`;
+        case 'structure/contrast-frame': return `Drop contrast formulas: rewrite at least ${at} of these ${count} "X, not Y" / "isn't X. It's Y" constructions as direct statements.`;
+        case 'hedge/generalizer': return `Replace hedges with specifics: in at least ${at} of these ${count} places, swap "usually/often/typically" for the actual condition, number or example, or cut it.`;
+        case 'structure/reveal-frame': return `Lead with the point: remove at least ${at} of these ${count} announcements ("The real question is…", ", which is why").`;
+        case 'punctuation/em-dash': return `Thin out em dashes: rewrite at least ${at} of these ${count} as commas, parentheses, a colon or two sentences. Keep the ones that mark a real interruption.`;
+        case 'punctuation/semicolon': return `Split semicolons: turn at least ${at} of these ${count} into two sentences, or a comma and "and", "but" or "so".`;
+        case 'rhythm/long-sentences': return `Shorten long sentences: split at least ${at} of these ${count} where the thought turns. Don't cut facts to do it.`;
+        case 'rhythm/low-variance': return 'Vary the rhythm in the highlighted run: join two short related sentences or break a long one where the thought turns.';
+        default: return finding.message;
+    }
+}
+/**
+ * Deterministic revision instructions from lint findings. Roughen never calls
+ * a model; the host (Claude, Signal) does the rewrite and then checks it with
+ * comparePreservation. Single source of truth for how findings become
+ * rewrite instructions on every surface.
+ */
+function revisionBrief(source, result, options = {}) {
+    const max = options.maxExcerpts ?? 8;
+    const groups = new Map();
+    for (const finding of result.findings) {
+        if (finding.fixSafety !== 'manual' && finding.fix)
+            continue; // automatic fixes need no model
+        if (finding.severity === 'info' && !options.includeInfo)
+            continue;
+        if (finding.range[0] === finding.range[1] && !finding.ruleId.startsWith('voice/'))
+            continue;
+        groups.set(finding.ruleId, [...(groups.get(finding.ruleId) ?? []), finding]);
+    }
+    const items = [...groups].map(([ruleId, findings]) => ({
+        ruleId,
+        instruction: instructionFor(findings[0], findings),
+        why: findings[0].why,
+        rewriteAtLeast: banRules.has(ruleId) ? findings.length : Number(findings[0].evidence?.rewriteAtLeast ?? findings.length),
+        excerpts: findings.slice(0, max).map((finding) => ({
+            text: excerpt(source, finding.range),
+            // Lines come from `source`, so a caller can brief one section of a larger document.
+            line: source.slice(0, finding.range[0]).split('\n').length,
+            range: finding.range,
+        })),
+    }));
+    const allConstraints = [...constraints, ...(options.constraints ?? [])];
+    const text = items.length ? [
+        'Revise the flagged passages below. Each item says what to change and why.',
+        '',
+        ...items.flatMap((item, index) => [
+            `${index + 1}. ${item.instruction}`,
+            `   Why: ${item.why.split('. ')[0]}.`,
+            ...item.excerpts.map((entry) => `   - line ${entry.line}: “${entry.text}”`),
+            ...(item.excerpts.length < (groups.get(item.ruleId)?.length ?? 0) ? [`   - …and ${(groups.get(item.ruleId).length) - item.excerpts.length} more`] : []),
+        ]),
+        '',
+        'Constraints:',
+        ...allConstraints.map((constraint) => `- ${constraint}`),
+    ].join('\n') : '';
+    return { needed: items.length > 0, items, constraints: allConstraints, text };
+}
+/** The flagged span with a little context, on one line. */
+function excerpt(source, [start, end]) {
+    const from = Math.max(0, source.lastIndexOf('\n', start - 1) + 1, start - 60);
+    const newline = source.indexOf('\n', end);
+    const to = Math.min(newline < 0 ? source.length : newline, end + 60);
+    const text = source.slice(from, to).replace(/\s+/g, ' ').trim();
+    return `${from > 0 && source[from - 1] !== '\n' ? '…' : ''}${text}${to < source.length && source[to] !== '\n' ? '…' : ''}`;
+}
+/**
+ * Findings inside `regions`, with each density rule's rewrite target scaled to
+ * the share of its instances found there. Single source of truth for
+ * region-scoped review: the plugin's edit hook and Signal's per-section revision.
+ */
+function scopeFindings(findings, regions) {
+    const totals = new Map();
+    for (const finding of findings)
+        totals.set(finding.ruleId, (totals.get(finding.ruleId) ?? 0) + 1);
+    const inside = findings.filter((finding) => regions.some((region) => (0, ranges_js_1.rangesIntersect)(region, finding.range)
+        || (finding.range[0] === finding.range[1] && finding.range[0] >= region[0] && finding.range[0] <= region[1])));
+    const shares = new Map();
+    for (const finding of inside)
+        shares.set(finding.ruleId, (shares.get(finding.ruleId) ?? 0) + 1);
+    return inside.map((finding) => {
+        const target = finding.evidence?.rewriteAtLeast;
+        if (target === undefined)
+            return finding;
+        const share = shares.get(finding.ruleId);
+        const scaled = Math.min(share, Math.ceil((Number(target) * share) / totals.get(finding.ruleId)));
+        return { ...finding, evidence: { ...finding.evidence, count: share, rewriteAtLeast: scaled } };
+    });
+}
+//# sourceMappingURL=brief.js.map

package/dist-cjs/brief.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brief.js","sourceRoot":"","sources":["../src/brief.ts"],"names":[],"mappings":"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"}

package/dist-cjs/document.d.ts

@@ -0,0 +1,5 @@
+import type { Document, Format, MarkdownLinkTarget } from './types.js';
+/** Single source of truth for the lossless prose view used by every rule. */
+export declare function parseDocument(source: string, format?: Format): Document;
+/** Literal Markdown targets outside canonical code/verbatim-quotation ranges. */
+export declare function collectMarkdownLinkTargets(source: string, format?: Format): MarkdownLinkTarget[];