@smeltjs/core 0.3.0 → 0.4.0

package/dist/agents/lint.js

@@ -0,0 +1,761 @@
+import { nodeFsReader } from '../repomap/reader.js';
+import { citing, GUIDE } from './guide.js';
+import { ancestorDirs, readInstructionSet, resolvesInTree } from './instructions.js';
+/**
+ * `smelt agents lint` — the audit of the blob an agent loads on **every** request.
+ *
+ * smelt's whole subject is what a context window is spent on, and an instruction file
+ * is the one blob every request pays for whether or not it is relevant. So the lint is
+ * the same three moves smelt makes everywhere else, aimed at a file nobody measures:
+ *
+ *  1. **Measure, never threshold** (ruling R2). Bytes per level, the most any single
+ *     request loads, and the repository-wide surface — three numbers, each labelled
+ *     with the question it answers, because a monorepo makes the last two differ and
+ *     printing one under the other's heading is a lie about a cost. Plus an imperative
+ *     count that says out loud it is a heuristic. The only number that can fail a run
+ *     is `agents.budgetBytes` in `smelt.config.json` — *the user's own*. There is no
+ *     built-in budget, for exactly the reason `--budget` has none.
+ *  2. **Explain every finding** (Law 2, in the {@link ElisionReason} discipline). A
+ *     finding is a stable `rule` id plus a sentence, and the sentence ends in a phrase
+ *     from the guide it is applying, attributed — see `./guide.ts`.
+ *  3. **Resolve against the real tree** (ruling R3). `dead-path` and `dead-link` are
+ *     the checks nobody else makes, because everyone else is linting Markdown while
+ *     the thing that has rotted is the *repository the Markdown describes*. A renamed
+ *     `src/auth/handlers.ts` does not make the file invalid; it makes it a lie that
+ *     the agent believes on every request.
+ *
+ * **Advisory by default.** Findings exit 0. `--strict` turns any finding into exit 1
+ * for CI, because a check that cannot be enforced is a check nobody runs, and a check
+ * that is enforced by default is smelt deciding somebody's house style for them.
+ *
+ * The heuristics here are heuristics, and the report says so where it matters: the
+ * imperative count carries "(heuristic)" in its own label and in every receipt,
+ * `generated-boilerplate` calls itself the softest rule in its own explanation, and the
+ * closing line of every run states that findings are advisory and exit 0 unless
+ * `--strict` was asked for. A rule that fires on a file the guide would call minimal is
+ * not automatically a bug in the file — it may be a bug in the rule, or in the guide,
+ * and the answer is worth writing down either way (ruling R9; see this repository's own
+ * `AGENTS.md`).
+ */
+/* ------------------------------------------------------------------------------------
+ * Rule ids — stable, and the whole machine-readable surface of a finding
+ * ---------------------------------------------------------------------------------- */
+/** A path-like token in the prose that resolves to nothing in the tree. The flagship. */
+export const DEAD_PATH_RULE = 'dead-path';
+/** A Markdown link whose relative target is not in the tree. */
+export const DEAD_LINK_RULE = 'dead-link';
+/** "always", "never", ALL-CAPS forcing. */
+export const FORCING_LANGUAGE_RULE = 'forcing-language';
+/** A directory tree, or a run of bare path lines. */
+export const STRUCTURE_DUMP_RULE = 'structure-dump';
+/** The fingerprints an init script leaves. The softest rule here, and it says so. */
+export const GENERATED_BOILERPLATE_RULE = 'generated-boilerplate';
+/** A code-style rule that loads on every request to be relevant on some of them. */
+export const LANGUAGE_RULE_RULE = 'language-rule';
+/** A mirror (CLAUDE.md / GEMINI.md) that has diverged from its AGENTS.md. */
+export const MIRROR_DRIFT_RULE = 'mirror-drift';
+/** The same instruction present at a level and at one of its ancestors. */
+export const RESTATED_AT_LEVEL_RULE = 'restated-at-level';
+/**
+ * The rules a finding can carry, in report order.
+ *
+ * `Object.freeze`-flat on purpose: the ids are a wire surface. They go into `--json`,
+ * into CI greps and into whatever a user filters on, so they are declared once and
+ * never spelled again in prose.
+ */
+export const AGENTS_LINT_RULES = [
+    DEAD_PATH_RULE,
+    DEAD_LINK_RULE,
+    FORCING_LANGUAGE_RULE,
+    STRUCTURE_DUMP_RULE,
+    GENERATED_BOILERPLATE_RULE,
+    LANGUAGE_RULE_RULE,
+    MIRROR_DRIFT_RULE,
+    RESTATED_AT_LEVEL_RULE,
+];
+/**
+ * The imperative counter's rule id (ruling R6).
+ *
+ * **Deliberately not in {@link AGENTS_LINT_RULES}.** An imperative is not a defect —
+ * an instruction file is *made* of imperatives — so counting them is a measurement,
+ * like `outputBytes`, and putting them among the findings would make `--strict` red on
+ * every real AGENTS.md and therefore useless. Each counted line still carries a
+ * receipt naming the verb that matched, because a heuristic whose matches you cannot
+ * inspect is a number nobody can check.
+ */
+export const IMPERATIVE_LINE_RULE = 'imperative-line';
+/**
+ * Lint the merged set under `root`.
+ *
+ * Pure over its inputs and its reader: nothing is written, and every filesystem touch
+ * goes through {@link RepoReader}, which has no writer on it.
+ */
+export function lintAgents(options) {
+    const reader = options.reader ?? nodeFsReader();
+    const set = readInstructionSet({
+        root: options.root,
+        reader,
+        ...(options.ignore === undefined ? {} : { ignore: options.ignore }),
+    });
+    const findings = [];
+    const imperatives = [];
+    for (const level of set.levels) {
+        // The imperative count is a companion to the byte total, so it is counted over
+        // exactly what the byte total is counted over: the primaries. A mirror is an
+        // alternative spelling of a level, not a second level — counting it would make
+        // the headline number describe a request nobody makes.
+        imperatives.push(...countImperatives(level.primary, scanLines(level.primary.text)));
+        // The rules, though, run over the primary **and every mirror that has actually
+        // diverged**: a drifted CLAUDE.md is what Claude Code loads, so its own dead paths
+        // are real. A symlink or a byte-identical copy is skipped — it would mint a
+        // duplicate of every finding on the primary and say nothing new.
+        const linted = [
+            level.primary,
+            ...level.mirrors.filter((mirror) => standingOf(level.primary, mirror) === 'drift'),
+        ];
+        for (const file of linted) {
+            const lines = scanLines(file.text);
+            findings.push(...findDeadLinks(file, lines, options.root, reader));
+            findings.push(...findDeadPaths(file, lines, options.root, reader));
+            findings.push(...findForcingLanguage(file, lines));
+            findings.push(...findStructureDumps(file, lines));
+            findings.push(...findGeneratedBoilerplate(file, lines));
+            findings.push(...findLanguageRules(file, lines));
+        }
+        findings.push(...findMirrorDrift(level.primary, level.mirrors));
+    }
+    findings.push(...findRestatedAcrossLevels(set));
+    return {
+        root: options.root,
+        levels: set.levels.map((level) => ({
+            dir: level.dir,
+            path: level.primary.path,
+            bytes: level.primary.bytes,
+            mirrors: level.mirrors.map((mirror) => ({
+                path: mirror.path,
+                bytes: mirror.bytes,
+                standing: standingOf(level.primary, mirror),
+            })),
+        })),
+        totalBytes: set.totalBytes,
+        perRequestBytes: set.perRequestBytes,
+        ...(options.budgetBytes === undefined ? {} : { budgetBytes: options.budgetBytes }),
+        imperatives,
+        findings: findings.toSorted(byRuleThenPlace),
+    };
+}
+/** How far over the user's budget the merged set is, or `undefined` when it fits. */
+export function overBudgetBytes(report) {
+    if (report.budgetBytes === undefined)
+        return undefined;
+    const over = report.totalBytes - report.budgetBytes;
+    return over > 0 ? over : undefined;
+}
+/** Findings in report order: rule first, then where they were found. */
+function byRuleThenPlace(a, b) {
+    const rank = ruleOrder(a.reason.rule) - ruleOrder(b.reason.rule) ||
+        (a.file < b.file ? -1 : a.file > b.file ? 1 : 0) ||
+        a.line - b.line;
+    return rank;
+}
+function ruleOrder(rule) {
+    const index = AGENTS_LINT_RULES.indexOf(rule);
+    return index === -1 ? AGENTS_LINT_RULES.length : index;
+}
+/**
+ * Split a file into lines, marking fenced code.
+ *
+ * The distinction matters in both directions: a `const x = 1` inside a fence is an
+ * *example*, not a `language-rule`, and a tree drawing is only a `structure-dump`
+ * because it is a fence full of paths. Rules that read prose skip fences; the one
+ * rule that reads fences skips prose.
+ */
+function scanLines(text) {
+    const out = [];
+    let fence;
+    text.split('\n').forEach((line, index) => {
+        const marker = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+        const opensFence = marker !== null && fence === undefined;
+        if (marker !== null) {
+            if (fence === undefined)
+                fence = marker[1].slice(0, 1);
+            else if (marker[1].startsWith(fence))
+                fence = undefined;
+            out.push({ number: index + 1, text: line, fenced: true, opensFence });
+            return;
+        }
+        out.push({ number: index + 1, text: line, fenced: fence !== undefined, opensFence: false });
+    });
+    return out;
+}
+/** A line stripped of list bullets, heading hashes, blockquote marks and bold runs. */
+function bareText(text) {
+    return text
+        .replace(/^\s*(?:[-*+]\s+|\d+[.)]\s+|#{1,6}\s+|>\s*)+/, '')
+        .replace(/\*\*/g, '')
+        .trim();
+}
+/* ------------------------------------------------------------------------------------
+ * imperative-line — a labelled heuristic (R6)
+ * ---------------------------------------------------------------------------------- */
+/**
+ * The openers counted as an instruction.
+ *
+ * A closed list, deliberately: an open-ended part-of-speech guess would be a number
+ * nobody could reproduce, and this figure is reported beside a byte count that *is*
+ * exact. The modal openers the guide itself names — always / never / do not / must /
+ * should — are here alongside the verbs an instruction file actually opens with.
+ */
+const IMPERATIVE_OPENERS = [
+    'add',
+    'always',
+    'avoid',
+    'build',
+    'check',
+    'commit',
+    'create',
+    'do',
+    'document',
+    'ensure',
+    'follow',
+    'format',
+    'ignore',
+    'implement',
+    'install',
+    'keep',
+    'lint',
+    'make',
+    'must',
+    'name',
+    'never',
+    'place',
+    'prefer',
+    'put',
+    'read',
+    'refuse',
+    'remove',
+    'return',
+    'run',
+    'should',
+    'skip',
+    'test',
+    'throw',
+    'treat',
+    'update',
+    'use',
+    'verify',
+    'write',
+];
+/**
+ * Count the lines that read as instructions, one receipt each.
+ *
+ * Reported as `imperatives (heuristic)` and never as a precise figure, because it is
+ * not one: "Run `pnpm verify`" counts and "The gate is `pnpm verify`" does not, and
+ * both are the same instruction. The number is useful as a *scale* — the guide cites
+ * ~150-200 as what a frontier thinking model follows consistently — and useless as a
+ * threshold, which is why nothing here compares it to anything.
+ */
+function countImperatives(file, lines) {
+    const out = [];
+    for (const line of lines) {
+        if (line.fenced)
+            continue;
+        const bare = bareText(line.text);
+        if (bare === '')
+            continue;
+        const opener = /^(do not|[A-Za-z']+)/.exec(bare.toLowerCase())?.[1];
+        if (opener === undefined)
+            continue;
+        const matched = opener === 'do not' ? 'do not' : opener === "don't" ? "don't" : opener;
+        const counted = matched === 'do not' ||
+            matched === "don't" ||
+            IMPERATIVE_OPENERS.includes(matched.replace(/'.*$/, ''));
+        if (!counted)
+            continue;
+        out.push({
+            file: file.path,
+            line: line.number,
+            reason: {
+                rule: IMPERATIVE_LINE_RULE,
+                explanation: `opens with "${matched}", so it is counted as one instruction (heuristic)` +
+                    citing(GUIDE.instructionCeiling),
+            },
+        });
+    }
+    return out;
+}
+/* ------------------------------------------------------------------------------------
+ * dead-link — a Markdown link whose target left the tree
+ * ---------------------------------------------------------------------------------- */
+/** `[text](target)`, with the target captured. */
+const MARKDOWN_LINK = /\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+/**
+ * CommonMark lets a link destination be wrapped in angle brackets — `[x](<a b.md>)`,
+ * the only way to write one containing a space. The brackets are delimiters, not part
+ * of the path, and statting `<src/kept.ts>` never resolves: the rule would report a
+ * live file as dead, which is the exact failure this rule exists to avoid making.
+ */
+function stripAngles(target) {
+    return target.startsWith('<') && target.endsWith('>') ? target.slice(1, -1) : target;
+}
+function findDeadLinks(file, lines, root, reader) {
+    const out = [];
+    for (const line of lines) {
+        if (line.fenced)
+            continue;
+        for (const match of line.text.matchAll(MARKDOWN_LINK)) {
+            const target = stripFragment(stripAngles(match[1]));
+            if (target === '' || isExternal(target))
+                continue;
+            const resolved = resolveAgainst(file.dir, target);
+            if (resolved === undefined)
+                continue;
+            if (resolvesInTree(root, reader, resolved))
+                continue;
+            out.push({
+                file: file.path,
+                line: line.number,
+                reason: {
+                    rule: DEAD_LINK_RULE,
+                    explanation: `links to \`${target}\`, which is not in the tree — the pointer the root ` +
+                        `file exists to be goes nowhere` +
+                        citing(GUIDE.pointsElsewhere),
+                },
+            });
+        }
+    }
+    return out;
+}
+/* ------------------------------------------------------------------------------------
+ * dead-path — the flagship (R3)
+ * ---------------------------------------------------------------------------------- */
+/** A token with a directory separator: `src/auth`, `./scripts/build.mjs`, `docs/`. */
+const SLASHED = /^\.{0,2}\/?[\w.+-]+(?:\/[\w.+-]+)*\/?$/;
+/** A bare file name whose extension says "this is a file in this repo". */
+const CODE_FILE = /^[\w.-]+\.(?:[cm]?[jt]sx?|json|md|ya?ml|toml|py|rs|go|rb|java|sh|sql|css|html)$/;
+/**
+ * A host name: what `example.com/guide` is, and what a repository path never is.
+ *
+ * A scheme-less URL is the one thing that is shaped exactly like a relative path —
+ * dotted word, slash, more words — and the guide this very tool cites is written
+ * `aihero.dev/a-complete-guide-to-agents-md` in smelt's own help text. Only the
+ * segment before the first slash is tested, so `scripts/build.sh` is untouched: `sh`
+ * is a TLD *and* an extension, and which one it is depends entirely on where the dot
+ * sits relative to the separator.
+ */
+const DOMAIN_HOST = /^[\w-]+(?:\.[\w-]+)*\.(?:com|org|net|io|dev|ai|app|co|me|sh|so|to|xyz|gg|cloud|page|info|blog)$/i;
+/**
+ * `Node.js`, `Vue.js`, `Bun.sh`, `Three.js` — a product, not a file in this tree.
+ *
+ * Narrow on purpose: one capitalised word, then one of the five suffixes products are
+ * actually named with. It costs a bare mention of a PascalCase `Button.js`, which is
+ * a real filename — but that is a finding not made, and this is a false accusation not
+ * made, and on the flagship rule those two are not worth the same.
+ */
+const PRODUCT_NAME = /^[A-Z][A-Za-z]*\.(?:js|sh|ai|dev|io)$/;
+function findDeadPaths(file, lines, root, reader) {
+    const out = [];
+    const seen = new Set();
+    for (const line of lines) {
+        if (line.fenced)
+            continue;
+        // Markdown link targets belong to `dead-link`; blank them so one dead pointer is
+        // never reported twice under two rules.
+        const withoutLinks = line.text.replace(MARKDOWN_LINK, '[]()');
+        for (const token of pathCandidates(withoutLinks)) {
+            const key = `${String(line.number)}${token}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const resolved = resolveAgainst(file.dir, token);
+            // A token that climbed out of the tree with `..` is not a path this lint can
+            // rule on: it names something outside the repository, and both "dead" and
+            // "alive" would be guesses about a directory nobody handed us.
+            if (resolved === undefined)
+                continue;
+            if (resolvesInTree(root, reader, resolved))
+                continue;
+            out.push({
+                file: file.path,
+                line: line.number,
+                reason: {
+                    rule: DEAD_PATH_RULE,
+                    explanation: `names \`${token}\`, which resolves to nothing in this tree — an agent ` +
+                        `reads this on every request and looks there anyway` +
+                        citing(GUIDE.stalenessPoisons),
+                },
+            });
+        }
+    }
+    return out;
+}
+/**
+ * The path-like tokens on one line.
+ *
+ * Inline code spans first, because a path in an instruction file is nearly always in
+ * backticks; then bare words, filtered hard. The filters are the interesting part —
+ * every one of them is a false positive this rule made before it had them:
+ *
+ *  - `https://…`, `mailto:` — not tree paths.
+ *  - `@smeltjs/core`, `@types/node` — package names, which look exactly like paths.
+ *  - `src/**\/*.ts` — a glob describes a set, and a set does not resolve.
+ *  - `pnpm run build`, `and/or` — anything with whitespace, and anything whose
+ *    segments carry no extension and no separator worth trusting.
+ *  - `v1.2/v2` style version prose, caught by requiring a real segment shape.
+ *  - `example.com/guide`, `aihero.dev/…` — a URL somebody wrote without its scheme.
+ *  - `Node.js`, `Vue.js`, `Bun.sh` — products whose names end in an extension.
+ *
+ * The last two are why a token *without* a separator is a candidate only when it came
+ * out of a code span. In running prose a dotted bare word is far more often a product
+ * than a file, and this rule's whole value is that a reader believes it: one confident
+ * sentence accusing `Node.js` of having left the tree costs more trust than a dozen
+ * real findings earn. In backticks the author has said "this is a thing in my
+ * repository", and the rule takes them at their word.
+ */
+function pathCandidates(text) {
+    const tokens = [];
+    const add = (raw, fromCodeSpan) => {
+        const token = raw.replace(/[),.:;]+$/, '').trim();
+        if (token === '' || !isPathLike(token, fromCodeSpan))
+            return;
+        tokens.push(token);
+    };
+    const withoutCode = text.replace(/`([^`]+)`/g, (_whole, inner) => {
+        add(inner, true);
+        return ' ';
+    });
+    for (const word of withoutCode.split(/\s+/))
+        add(word, false);
+    return tokens;
+}
+/**
+ * Is `token` a path into this tree?
+ *
+ * `fromCodeSpan` is the author's own signal, and it decides the one ambiguous case: a
+ * dotted word with no separator. See {@link pathCandidates}.
+ */
+function isPathLike(token, fromCodeSpan) {
+    if (isExternal(token))
+        return false;
+    if (token.startsWith('@'))
+        return false;
+    if (/[*?[\]{}<>|"'`\\]/.test(token))
+        return false;
+    if (token.startsWith('#'))
+        return false;
+    if (!SLASHED.test(token))
+        return false;
+    if (token.includes('/')) {
+        // `example.com/guide` — a URL with its scheme left off, not a directory.
+        return !DOMAIN_HOST.test(token.split('/')[0] ?? '');
+    }
+    return fromCodeSpan && !PRODUCT_NAME.test(token) && CODE_FILE.test(token);
+}
+/** True for anything that is not a path into this tree. */
+function isExternal(target) {
+    return /^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('//') || target.startsWith('#');
+}
+function stripFragment(target) {
+    const cut = target.indexOf('#');
+    return cut === -1 ? target : target.slice(0, cut);
+}
+/**
+ * A token in a nested instruction file is relative to *that* file's directory, which
+ * is the whole reason a nested file can hold a link the root one cannot. `../` is
+ * resolved rather than refused, so a nested file may point back up the tree.
+ *
+ * `undefined` when the token climbs past the repository root. It used to clamp there —
+ * `stack.pop()` on an empty stack is a no-op — which silently turned `../sibling/x.ts`
+ * into `sibling/x.ts` and then answered a question about the wrong file, in whichever
+ * direction happened to be wrong. Outside the tree, this lint has nothing to say.
+ */
+function resolveAgainst(dir, token) {
+    const base = dir === '' ? [] : dir.split('/');
+    const parts = token.replace(/\/+$/, '').split('/');
+    const stack = [...base];
+    for (const part of parts) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            if (stack.length === 0)
+                return undefined;
+            stack.pop();
+        }
+        else
+            stack.push(part);
+    }
+    return stack.join('/');
+}
+/* ------------------------------------------------------------------------------------
+ * forcing-language
+ * ---------------------------------------------------------------------------------- */
+/** ALL-CAPS words a reader meets as shouting rather than as an acronym. */
+const SHOUTED = /\b(ALWAYS|NEVER|MUST|DO NOT|DON'T|REQUIRED|MANDATORY|CRITICAL|IMPORTANT)\b/;
+/** The two words the guide names in its own example of what *not* to write. */
+const FORCING_WORDS = /\b(always|never)\b/i;
+function findForcingLanguage(file, lines) {
+    const out = [];
+    for (const line of lines) {
+        if (line.fenced)
+            continue;
+        const shouted = SHOUTED.exec(line.text)?.[1];
+        const forcing = shouted ?? FORCING_WORDS.exec(line.text)?.[1];
+        if (forcing === undefined)
+            continue;
+        out.push({
+            file: file.path,
+            line: line.number,
+            reason: {
+                rule: FORCING_LANGUAGE_RULE,
+                explanation: `forces with "${forcing}" — forcing language spends tokens on emphasis ` +
+                    `rather than on information` +
+                    citing(GUIDE.lightTouch),
+            },
+        });
+    }
+    return out;
+}
+/* ------------------------------------------------------------------------------------
+ * structure-dump
+ * ---------------------------------------------------------------------------------- */
+/**
+ * The characters a generated tree listing is drawn with.
+ *
+ * Both charsets: `tree` draws box-drawing by default and `|--` / `` `-- `` under
+ * `--charset=ascii`, and the ASCII form is what lands in a file written on a machine
+ * whose terminal was not UTF-8. Missing it made the whole rule silent on a fenced
+ * ASCII tree — and because fenced lines skip `dead-path` too, that block produced no
+ * finding of any kind.
+ */
+const TREE_DRAWING = /[├└│─]|^\s*(?:\|--|`--|\|\s{3}|\+--)/;
+/** How many path-ish lines in a row read as a dump rather than as an example. */
+const DUMP_RUN = 3;
+function findStructureDumps(file, lines) {
+    const out = [];
+    // A fenced block whose body is a tree drawing.
+    let fenceStart;
+    let drawn = 0;
+    for (const line of lines) {
+        if (line.opensFence) {
+            fenceStart = line;
+            drawn = 0;
+            continue;
+        }
+        if (!line.fenced) {
+            fenceStart = undefined;
+            continue;
+        }
+        if (fenceStart === undefined)
+            continue;
+        if (TREE_DRAWING.test(line.text))
+            drawn += 1;
+        if (drawn === 2) {
+            out.push(structureFinding(file, fenceStart.number, 'a directory tree'));
+            fenceStart = undefined;
+        }
+    }
+    // A run of bare path lines in prose — the same dump without the box characters.
+    let run = 0;
+    let runStart = 0;
+    for (const line of lines) {
+        if (line.fenced) {
+            run = 0;
+            continue;
+        }
+        const bare = bareText(line.text);
+        // A line whose whole content is one token is a path line, not prose — so the
+        // code-span rule `dead-path` needs against running text has nothing to guard here.
+        const isPathLine = bare !== '' && isPathLike(bare.replace(/`/g, '').split(/\s+/)[0] ?? '', true);
+        if (isPathLine && bare.split(/\s+/).length <= 2) {
+            if (run === 0)
+                runStart = line.number;
+            run += 1;
+            if (run === DUMP_RUN)
+                out.push(structureFinding(file, runStart, 'a run of path lines'));
+        }
+        else {
+            run = 0;
+        }
+    }
+    return out;
+}
+function structureFinding(file, line, what) {
+    return {
+        file: file.path,
+        line,
+        reason: {
+            rule: STRUCTURE_DUMP_RULE,
+            explanation: `spends the every-request budget on ${what} — layout is the fact in a ` +
+                `repository that changes most often, so it is also the fact that rots first` +
+                citing(GUIDE.describeCapabilities),
+        },
+    };
+}
+/* ------------------------------------------------------------------------------------
+ * generated-boilerplate — the softest rule here, and it says so
+ * ---------------------------------------------------------------------------------- */
+/** The fingerprints an init script leaves behind, with what each one is. */
+const BOILERPLATE_SIGNATURES = [
+    [/\bauto-?generated\b/i, 'an "auto-generated" marker'],
+    [/\bgenerated by\b/i, 'a "generated by" credit'],
+    [/<!--\s*generated/i, 'a generated-block comment'],
+    [/\b(?:claude|codex|gemini|cursor|agents?)\s+init\b/i, 'an init-command credit'],
+    [/\bthis file was (?:created|generated)\b/i, 'a "this file was generated" line'],
+    [/\bdo not edit\b/i, 'a "do not edit" banner'],
+];
+function findGeneratedBoilerplate(file, lines) {
+    const out = [];
+    for (const line of lines) {
+        if (line.fenced)
+            continue;
+        for (const [pattern, what] of BOILERPLATE_SIGNATURES) {
+            if (!pattern.test(line.text))
+                continue;
+            out.push({
+                file: file.path,
+                line: line.number,
+                reason: {
+                    rule: GENERATED_BOILERPLATE_RULE,
+                    explanation: `carries ${what}, which suggests this file was generated rather than ` +
+                        `written. This is the softest rule here: a signature is circumstantial, ` +
+                        `and a hand-written file may honestly carry one, so it never means more ` +
+                        `than "read this file again"` +
+                        citing(GUIDE.neverGenerate),
+                },
+            });
+            break;
+        }
+    }
+    return out;
+}
+/* ------------------------------------------------------------------------------------
+ * language-rule
+ * ---------------------------------------------------------------------------------- */
+/** Style rules that pay their every-request cost only when the agent writes code. */
+const LANGUAGE_RULE_SIGNATURES = [
+    [/\bconst\b[^\n]*\blet\b|\blet\b[^\n]*\bconst\b/, 'a const/let rule'],
+    [/\binterface\b[^\n]*\btype\b|\btype\b[^\n]*\binterface\b/, 'an interface-vs-type rule'],
+    [/\bstrict[- ]?null(?:checks)?\b/i, 'a strict-null rule'],
+    [/\bsemi-?colons?\b/i, 'a semicolon rule'],
+    [/\b(?:single|double) quotes\b/i, 'a quote-style rule'],
+    [/\barrow functions?\b/i, 'an arrow-function rule'],
+    [/\bnamed exports?\b|\bdefault exports?\b/i, 'an export-style rule'],
+    [
+        /\btabs? (?:over|versus|vs\.?) spaces?\b|\bspaces? (?:over|versus|vs\.?) tabs?\b/i,
+        'an indentation rule',
+    ],
+];
+function findLanguageRules(file, lines) {
+    const out = [];
+    for (const line of lines) {
+        if (line.fenced)
+            continue;
+        for (const [pattern, what] of LANGUAGE_RULE_SIGNATURES) {
+            if (!pattern.test(line.text))
+                continue;
+            out.push({
+                file: file.path,
+                line: line.number,
+                reason: {
+                    rule: LANGUAGE_RULE_RULE,
+                    explanation: `states ${what}, which is paid for on every request and is relevant on ` +
+                        `few of them — move it behind a link and it costs only the tasks it applies to` +
+                        citing(GUIDE.loadWhenRelevant),
+                },
+            });
+            break;
+        }
+    }
+    return out;
+}
+/* ------------------------------------------------------------------------------------
+ * mirror-drift (R4)
+ * ---------------------------------------------------------------------------------- */
+function standingOf(primary, mirror) {
+    if (mirror.symlink)
+        return 'symlink';
+    return mirror.text === primary.text ? 'copy' : 'drift';
+}
+/**
+ * A mirror that has diverged from its `AGENTS.md`.
+ *
+ * A byte-identical copy is **not** a finding: it is not drift, and calling it one
+ * would be smelt enforcing the guide's suggestion rather than reporting a fact. What
+ * the report does say, beside every copy, is that a symlink cannot drift — which is
+ * the guide's suggestion offered, exactly as `smelt hooks` offers rather than does.
+ */
+function findMirrorDrift(primary, mirrors) {
+    return mirrors
+        .filter((mirror) => standingOf(primary, mirror) === 'drift')
+        .map((mirror) => ({
+        file: mirror.path,
+        line: 1,
+        reason: {
+            rule: MIRROR_DRIFT_RULE,
+            explanation: `has diverged from \`${primary.path}\` (${String(mirror.bytes)} bytes against ` +
+                `${String(primary.bytes)}) — two harnesses are now reading two different sets ` +
+                `of instructions from one repository` +
+                citing(GUIDE.symlinkMirror),
+        },
+    }));
+}
+/* ------------------------------------------------------------------------------------
+ * restated-at-level (R8)
+ * ---------------------------------------------------------------------------------- */
+/** Below this, a repeated line is a heading or a bullet marker, not an instruction. */
+const RESTATEMENT_MIN_CHARS = 40;
+/**
+ * The same instruction present at a level **and at one of its ancestors**.
+ *
+ * The guide's rule is that a nested file *merges with* the root, so a line written in
+ * both is a line the agent is handed twice — paid for twice, and the second copy
+ * carrying the risk that only one of them is ever updated. Reported on the deeper file,
+ * because that is the copy the ancestor already covers.
+ *
+ * **Only ancestors.** A merge runs up the tree, never across it: an agent working in
+ * `pkg/a` loads the root file and `pkg/a`'s, and never `pkg/b`'s. So a line two
+ * siblings happen to share is not a line anybody is handed twice, and reporting it as
+ * one would print an explanation about a merge that does not happen — a finding whose
+ * sentence is false, which is worse than no finding at all (Law 2).
+ */
+function findRestatedAcrossLevels(set) {
+    /** dir → the lines that level states, each with the file that states them. */
+    const stated = new Map();
+    const out = [];
+    // Levels arrive root-first (`readInstructionSet` sorts by depth), so every ancestor
+    // of a level has already been recorded by the time the level is read.
+    for (const level of set.levels) {
+        const file = level.primary;
+        const local = new Map();
+        stated.set(level.dir, local);
+        const ancestors = ancestorDirs(level.dir);
+        scanLines(file.text).forEach((line) => {
+            if (line.fenced)
+                return;
+            const normalized = bareText(line.text).toLowerCase().replace(/\s+/g, ' ');
+            if (normalized.length < RESTATEMENT_MIN_CHARS)
+                return;
+            if (local.has(normalized))
+                return;
+            local.set(normalized, file.path);
+            const earlier = ancestors
+                .map((dir) => stated.get(dir)?.get(normalized))
+                .find((path) => path !== undefined);
+            if (earlier === undefined)
+                return;
+            out.push({
+                file: file.path,
+                line: line.number,
+                reason: {
+                    rule: RESTATED_AT_LEVEL_RULE,
+                    explanation: `repeats a line already in \`${earlier}\`, which is above it — the levels ` +
+                        `merge, so the agent is handed this twice and only one copy will be kept ` +
+                        `up to date` +
+                        citing(GUIDE.nestedMerge),
+                },
+            });
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=lint.js.map