@brighterly/lib-fe-codestyle 1.0.0 → 1.0.2

package/dist/cli.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * `codestyle` — a thin argv switch over the engine. No engine logic lives here.
+ *
+ * Exit codes: 0 clean · 1 a finding at error, a failed proof, a stale doc or a failed step ·
+ * 2 the tool itself failed (usage, config).
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { ConfigError } from './config/define-config.js';
+import { findConfig, loadConfig } from './config/load-config.js';
+import { renderDocs } from './engine/docs.js';
+import { migrate } from './engine/migrate.js';
+import { buildRegistry } from './engine/registry.js';
+import { check } from './engine/run.js';
+import { runSelfTest } from './engine/self-test.js';
+import { createReader, toRelative, todayUtc } from './engine/util.js';
+import { packageRules } from './rules/index.js';
+import { validate } from './validate/index.js';
+const USAGE = `usage: codestyle <command> [--root=<path>] [flags]
+
+commands:
+  check       run the rules — --staged | --stdin --file=<path>, --json, --only=<a,b>, --rule=<name>,
+              --tags=<a,b>, --no-self-test, --no-color
+  list        print every rule: name · level · owner · tags
+  self-test   prove this repo's custom rules (--package: the package's own rules)
+  docs        render every config.docs entry (--check: fail when an output is stale)
+  validate    run the config.validate steps
+  precommit   check --staged, then the config.precommit steps
+  migrate     rewrite 0.5.x ignores and ids, print a codestyle.config.ts skeleton (--write: apply)
+`;
+/** Run a step in the repo root, its output streamed through. */
+const shell = (cmd, cwd) => spawnSync(cmd, { shell: true, stdio: 'inherit', cwd }).status === 0;
+/**
+ * A collecting exit: the engine calls it and returns, so one command can chain several. Safe
+ * because engine code always `return exit(...)` — nothing runs after an exit call.
+ */
+const collect = () => {
+    let last = 0;
+    return { exit: ((c) => { last = c; }), code: () => last };
+};
+const main = async (argv) => {
+    const rootArg = argv.find(a => a.startsWith('--root='));
+    const root = rootArg ? resolve(rootArg.slice('--root='.length)) : process.cwd();
+    const [command, ...rest] = argv.filter(a => a !== rootArg);
+    const usage = (message) => {
+        if (message)
+            console.error(`codestyle: ${message}`);
+        console.error(USAGE);
+        return 2;
+    };
+    if (command === '--help' || command === '-h') {
+        console.log(USAGE);
+        return 0;
+    }
+    if (rest.includes('--help')) {
+        if (!['check', 'list', 'self-test', 'docs', 'validate', 'precommit', 'migrate'].includes(command ?? ''))
+            return usage(`unknown command "${command}"`);
+        console.log(USAGE);
+        return 0;
+    }
+    /** Commands other than check take only the flags they name. */
+    const onlyFlags = (allowed) => rest.find(a => !allowed.includes(a)) ?? null;
+    const load = async () => {
+        const config = await loadConfig(root);
+        return { config, registry: buildRegistry(config), configFile: toRelative(root, findConfig(root)) };
+    };
+    switch (command) {
+        case 'check': {
+            const run = collect();
+            await check({ root, argv: rest, exit: run.exit });
+            return run.code();
+        }
+        case 'list': {
+            const bad = onlyFlags([]);
+            if (bad)
+                return usage(`list takes no flag "${bad}"`);
+            const { registry } = await load();
+            for (const r of registry.all)
+                console.log(`${r.rule.name} · ${r.level} · ${r.owner} · ${r.tags.length ? r.tags.join(',') : '-'}`);
+            return 0;
+        }
+        case 'self-test': {
+            const bad = onlyFlags(['--package']);
+            if (bad)
+                return usage(`self-test takes no flag "${bad}"`);
+            let rules = packageRules;
+            let settings = {};
+            if (!rest.includes('--package')) {
+                const { config, registry } = await load();
+                rules = registry.all.filter(r => r.owner === 'custom').map(r => r.rule);
+                settings = config.settings;
+            }
+            const { ok, failures, checked } = await runSelfTest({ rules, settings, today: todayUtc() });
+            if (ok)
+                console.log(`self-test: ${checked.length} rule(s) proven`);
+            for (const f of failures)
+                console.error(`self-test: ${f}`);
+            return ok ? 0 : 1;
+        }
+        case 'docs': {
+            const bad = onlyFlags(['--check']);
+            if (bad)
+                return usage(`docs takes no flag "${bad}"`);
+            const { config, registry, configFile } = await load();
+            if (config.docs.length === 0)
+                throw new ConfigError(`docs: no entries in ${configFile}`);
+            const read = createReader(root);
+            let stale = 0;
+            for (const entry of config.docs) {
+                const rendered = renderDocs(entry, registry, read);
+                const out = resolve(root, entry.output);
+                if (rest.includes('--check')) {
+                    // A missing output is as stale as an edited one.
+                    const current = existsSync(out) ? readFileSync(out, 'utf8') : null;
+                    if (current !== rendered) {
+                        stale++;
+                        console.error(`codestyle docs --check: ${entry.output} is stale — run codestyle docs`);
+                    }
+                    continue;
+                }
+                mkdirSync(dirname(out), { recursive: true });
+                writeFileSync(out, rendered);
+                console.log(`wrote ${entry.output}`);
+            }
+            return stale ? 1 : 0;
+        }
+        case 'validate': {
+            const bad = onlyFlags([]);
+            if (bad)
+                return usage(`validate takes no flag "${bad}"`);
+            const { config, configFile } = await load();
+            if (config.validate.length === 0)
+                throw new ConfigError(`validate: declare validate steps in ${configFile}`);
+            const run = collect();
+            await validate(config.validate, { exit: run.exit, exec: cmd => ({ ok: shell(cmd, root) }) });
+            return run.code();
+        }
+        case 'precommit': {
+            const { config } = await load();
+            const run = collect();
+            await check({ root, argv: ['--staged', ...rest.filter(a => a !== '--staged')], exit: run.exit });
+            if (run.code() !== 0)
+                return run.code();
+            if (config.precommit.length === 0)
+                return 0;
+            const steps = collect();
+            await validate(config.precommit, { exit: steps.exit, exec: cmd => ({ ok: shell(cmd, root) }) });
+            return steps.code();
+        }
+        case 'migrate': {
+            const bad = onlyFlags(['--write']);
+            if (bad)
+                return usage(`migrate takes no flag "${bad}"`);
+            const write = rest.includes('--write');
+            const { rewritten, configSkeleton, notes } = migrate(root, { write });
+            for (const n of notes)
+                console.log(n);
+            for (const f of rewritten)
+                console.log(`${write ? 'rewrote' : 'would rewrite'} ${f}`);
+            if (configSkeleton && write)
+                console.log('wrote codestyle.config.ts');
+            else if (configSkeleton)
+                console.log(`\n${configSkeleton}`);
+            return 0;
+        }
+        default:
+            return usage(command ? `unknown command "${command}"` : 'no command given');
+    }
+};
+// Never `process.exit()` after output: a pipe drains asynchronously (macOS cuts a 64 KiB+ --json at
+// the first buffer). Setting `exitCode` lets the process end on its own once stdout has drained.
+main(process.argv.slice(2)).then(code => { process.exitCode = code; }, (e) => {
+    // Any failure of the tool itself is exit 2 — never the 1 that means "an error-level finding".
+    // A ConfigError is the author's to fix and gets one line; anything else keeps its stack.
+    if (!(e instanceof ConfigError) && e instanceof Error && e.stack)
+        console.error(e.stack);
+    console.error(`codestyle: ${e instanceof Error ? e.message : String(e)}`);
+    process.exitCode = 2;
+});

package/dist/config/define-config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `defineConfig` — the one call a consumer's `codestyle.config.ts` makes. It validates the
+ * shape, fills the defaults and brands the result so the loader can tell a real config from a
+ * stray default export. Every failure is a thrown `ConfigError` naming the key path.
+ */
+import type { CodestyleConfig, ResolvedConfig } from './schema.js';
+/** A config the tool cannot run with. The CLI turns it into exit 2. */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare const defineConfig: (config: CodestyleConfig) => ResolvedConfig;

package/dist/config/define-config.js

@@ -0,0 +1,33 @@
+/**
+ * `defineConfig` — the one call a consumer's `codestyle.config.ts` makes. It validates the
+ * shape, fills the defaults and brands the result so the loader can tell a real config from a
+ * stray default export. Every failure is a thrown `ConfigError` naming the key path.
+ */
+import { configProblem, DEFAULT_FILES, DEFAULT_IGNORES, DEFAULT_RULE_SOURCES } from './schema.js';
+/** A config the tool cannot run with. The CLI turns it into exit 2. */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+export const defineConfig = (config) => {
+    const problem = configProblem(config);
+    if (problem !== null)
+        throw new ConfigError(`codestyle config: ${problem}`);
+    const resolved = {
+        settings: { ...config.settings },
+        rules: { ...config.rules },
+        custom: [...(config.custom ?? [])],
+        overrides: [...(config.overrides ?? [])],
+        files: [...(config.files ?? DEFAULT_FILES)],
+        ignores: [...(config.ignores ?? DEFAULT_IGNORES)],
+        ruleSources: [...(config.ruleSources ?? DEFAULT_RULE_SOURCES)],
+        docs: [...(config.docs ?? [])],
+        validate: [...(config.validate ?? [])],
+        precommit: [...(config.precommit ?? [])],
+    };
+    // The loader reads this mark to tell a resolved config from a stray default export.
+    Object.defineProperty(resolved, Symbol.for('codestyle.config'), { value: true, enumerable: false });
+    return resolved;
+};

package/dist/config/load-config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Find `codestyle.config.*` at the repo root, import it, and return what `defineConfig`
+ * produced. The brand `defineConfig` sets is the only proof a default export is a config —
+ * a plain object that merely looks like one never had its shape validated.
+ */
+import type { ResolvedConfig } from './schema.js';
+/** Looked up in this order; the first that exists wins. */
+export declare const CONFIG_FILES: string[];
+/** Absolute path of the first `CONFIG_FILES` entry under `root` that is a FILE, or null. */
+export declare const findConfig: (root: string) => string | null;
+/**
+ * `importer` is injectable so the Node-floor mapping can be tested on a Node that strips
+ * types; production always uses the native `import()`.
+ */
+export declare const loadConfig: (root: string, importer?: (url: string) => Promise<unknown>) => Promise<ResolvedConfig>;

package/dist/config/load-config.js

@@ -0,0 +1,52 @@
+/**
+ * Find `codestyle.config.*` at the repo root, import it, and return what `defineConfig`
+ * produced. The brand `defineConfig` sets is the only proof a default export is a config —
+ * a plain object that merely looks like one never had its shape validated.
+ */
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ConfigError } from './define-config.js';
+/** Looked up in this order; the first that exists wins. */
+export const CONFIG_FILES = ['codestyle.config.ts', 'codestyle.config.mts', 'codestyle.config.js', 'codestyle.config.mjs'];
+/** Absolute path of the first `CONFIG_FILES` entry under `root` that is a FILE, or null. */
+export const findConfig = (root) => {
+    for (const name of CONFIG_FILES) {
+        const file = resolve(root, name);
+        if (statSync(file, { throwIfNoEntry: false })?.isFile())
+            return file;
+    }
+    return null;
+};
+const nativeImport = (url) => import(url);
+const isBranded = (value) => typeof value === 'object' && value !== null && value[Symbol.for('codestyle.config')] === true;
+/**
+ * `importer` is injectable so the Node-floor mapping can be tested on a Node that strips
+ * types; production always uses the native `import()`.
+ */
+export const loadConfig = async (root, importer = nativeImport) => {
+    const file = findConfig(root);
+    if (file === null)
+        throw new ConfigError(`no codestyle.config.* in ${root}`);
+    let mod;
+    try {
+        mod = await importer(pathToFileURL(file).href);
+    }
+    catch (e) {
+        // Only the "this Node cannot load .ts" failure is ours to explain; anything else — a syntax
+        // error in the config, a missing import inside it — keeps its real stack.
+        const code = e?.code;
+        if (code === 'ERR_UNKNOWN_FILE_EXTENSION') {
+            throw new ConfigError(`${file} could not be loaded: Node 22.18+ is required to load a TypeScript config (native type stripping) — upgrade Node, or write the config as codestyle.config.mjs`);
+        }
+        // Type stripping only erases types: an enum, a namespace or a parameter property has runtime meaning.
+        if (code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX') {
+            throw new ConfigError(`${file} is not erasable-syntax TypeScript (${e.message}) — codestyle.config.ts may not use enums, namespaces or parameter properties`);
+        }
+        throw e;
+    }
+    const config = mod?.default;
+    if (!isBranded(config))
+        throw new ConfigError(`${file} must default-export defineConfig(...)`);
+    return config;
+};

package/dist/config/schema.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The shape of `codestyle.config.ts` — types, defaults and the shape validators.
+ *
+ * Shape only: whether a rule NAME exists needs the registry (package rules + `custom`), and
+ * whether an override may set a level needs the rule's default — both are checked later.
+ * The validators return the first problem as text naming its key path, so the caller decides
+ * how to fail; they never print.
+ */
+import type { AnyRule, Level, RuleName, SharedRuleSettings } from '../engine/types.js';
+/** "This place, this reason": a level for some rules on some files. `reason` is mandatory. */
+export interface OverrideEntry {
+    files: string[];
+    rules: Record<RuleName, Level>;
+    reason: string;
+}
+/** One agent-facing doc rendered by `codestyle docs`: the rules carrying `tags` into `template`, written to `output`. */
+export interface DocsEntry {
+    template: string;
+    output: string;
+    tags?: string[];
+}
+/** One named shell step for `codestyle validate` / the pre-commit chain. */
+export interface Step {
+    name: string;
+    run: string;
+}
+export interface CodestyleConfig {
+    /** App landmarks the package rules read through `RuleContext.settings`. */
+    settings?: SharedRuleSettings & Record<string, string>;
+    /** Level per rule name, package and custom alike. A rule not named runs at its own default. */
+    rules?: Record<RuleName, Level>;
+    /** This repo's own rules (each carrying a proof) and check-less external declarations. */
+    custom?: AnyRule[];
+    overrides?: OverrideEntry[];
+    /** Scan roots. Default `DEFAULT_FILES`. */
+    files?: string[];
+    /** Directory names skipped while walking. Default `DEFAULT_IGNORES`. */
+    ignores?: string[];
+    /** Paths whose change triggers the self-test in `--staged`, exempt from meta-rule parsing. Default `DEFAULT_RULE_SOURCES`. */
+    ruleSources?: string[];
+    docs?: DocsEntry[];
+    validate?: Step[];
+    precommit?: Step[];
+}
+export interface ResolvedConfig extends Required<Omit<CodestyleConfig, 'docs' | 'validate' | 'precommit'>> {
+    docs: DocsEntry[];
+    validate: Step[];
+    precommit: Step[];
+}
+export declare const DEFAULT_FILES: readonly string[];
+export declare const DEFAULT_IGNORES: readonly string[];
+export declare const DEFAULT_RULE_SOURCES: readonly string[];
+/** Every top-level key a config may carry — anything else is a typo that would be a silent no-op. */
+export declare const CONFIG_KEYS: readonly (keyof CodestyleConfig)[];
+type Problem = string | null;
+/** The first shape problem in a config, or null. Keys left undefined take their defaults. */
+export declare const configProblem: (config: unknown) => Problem;
+export {};

package/dist/config/schema.js

@@ -0,0 +1,139 @@
+/**
+ * The shape of `codestyle.config.ts` — types, defaults and the shape validators.
+ *
+ * Shape only: whether a rule NAME exists needs the registry (package rules + `custom`), and
+ * whether an override may set a level needs the rule's default — both are checked later.
+ * The validators return the first problem as text naming its key path, so the caller decides
+ * how to fail; they never print.
+ */
+import { malformedUntil } from '../engine/util.js';
+export const DEFAULT_FILES = ['app', 'config', 'tests', 'codestyle'];
+export const DEFAULT_IGNORES = ['node_modules', '.nuxt', '.output', 'dist', 'coverage'];
+export const DEFAULT_RULE_SOURCES = ['codestyle/'];
+const LEVELS = ['off', 'warn', 'error'];
+/** Every top-level key a config may carry — anything else is a typo that would be a silent no-op. */
+export const CONFIG_KEYS = [
+    'settings', 'rules', 'custom', 'overrides', 'files', 'ignores', 'ruleSources', 'docs', 'validate', 'precommit',
+];
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const show = (v) => (typeof v === 'string' ? `"${v}"` : String(JSON.stringify(v)));
+const first = (problems) => {
+    for (const p of problems)
+        if (p)
+            return p;
+    return null;
+};
+const stringArray = (v, path, { nonEmpty = false } = {}) => {
+    if (!Array.isArray(v))
+        return `${path} must be an array of strings, got ${show(v)}`;
+    if (nonEmpty && v.length === 0)
+        return `${path} must name at least one entry`;
+    const bad = v.findIndex(x => typeof x !== 'string' || x === '');
+    return bad === -1 ? null : `${path}[${bad}] must be a non-empty string, got ${show(v[bad])}`;
+};
+const levelMap = (v, path) => {
+    if (!isObject(v))
+        return `${path} must be an object of rule name → level, got ${show(v)}`;
+    for (const [name, level] of Object.entries(v)) {
+        if (typeof level !== 'string' || !LEVELS.includes(level)) {
+            return `${path}["${name}"] must be one of off | warn | error, got ${show(level)}`;
+        }
+    }
+    return null;
+};
+const reason = (v, path) => {
+    if (typeof v !== 'string' || v.trim() === '')
+        return `${path} is required — an exemption without a reason cannot be reviewed`;
+    const tok = malformedUntil(v);
+    return tok === null ? null : `${path} carries "until ${tok}", which is not a YYYY-MM-DD date`;
+};
+const override = (v, path) => {
+    if (!isObject(v))
+        return `${path} must be an object { files, rules, reason }, got ${show(v)}`;
+    return first([
+        stringArray(v.files, `${path}.files`, { nonEmpty: true }),
+        levelMap(v.rules, `${path}.rules`),
+        reason(v.reason, `${path}.reason`),
+    ]);
+};
+const entries = (v, path, entry) => {
+    if (!Array.isArray(v))
+        return `${path} must be an array, got ${show(v)}`;
+    return first(v.map((e, i) => entry(e, `${path}[${i}]`)));
+};
+const docsEntry = (v, path) => {
+    if (!isObject(v))
+        return `${path} must be an object { template, output, tags? }, got ${show(v)}`;
+    if (typeof v.template !== 'string' || v.template === '')
+        return `${path}.template must be a non-empty string`;
+    if (typeof v.output !== 'string' || v.output === '')
+        return `${path}.output must be a non-empty string`;
+    return v.tags === undefined ? null : stringArray(v.tags, `${path}.tags`);
+};
+const step = (v, path) => {
+    if (!isObject(v))
+        return `${path} must be an object { name, run }, got ${show(v)}`;
+    if (typeof v.name !== 'string' || v.name === '')
+        return `${path}.name must be a non-empty string`;
+    return typeof v.run === 'string' && v.run !== '' ? null : `${path}.run must be a non-empty string`;
+};
+const nonEmptyString = (v, path) => (typeof v === 'string' && v !== '' ? null : `${path} must be a non-empty string, got ${show(v)}`);
+/**
+ * A custom entry is either an external declaration (`owner` set) or a checkable rule (no
+ * `owner`). The two shapes must not blur: a stray `owner` would turn a real rule into a
+ * declaration that never runs, and a misspelled `level` would count as neither error nor warn.
+ */
+const customEntry = (v, path) => {
+    if (!isObject(v))
+        return `${path} must be a rule object, got ${show(v)}`;
+    if (Object.hasOwn(v, 'owner')) {
+        return first([
+            nonEmptyString(v.name, `${path}.name`),
+            v.owner === 'eslint' || v.owner === 'test' ? null : `${path}.owner must be 'eslint' or 'test' (a rule this package runs has no owner), got ${show(v.owner)}`,
+            nonEmptyString(v.ref, `${path}.ref`),
+            nonEmptyString(v.title, `${path}.title`),
+            nonEmptyString(v.why, `${path}.why`),
+            v.tags === undefined ? null : stringArray(v.tags, `${path}.tags`),
+        ]);
+    }
+    return first([
+        nonEmptyString(v.name, `${path}.name`),
+        typeof v.level === 'string' && LEVELS.includes(v.level) ? null : `${path}.level must be one of off | warn | error, got ${show(v.level)}`,
+        stringArray(v.scope, `${path}.scope`, { nonEmpty: true }),
+        typeof v.check === 'function' ? null : `${path}.check must be a function`,
+        nonEmptyString(v.title, `${path}.title`),
+        nonEmptyString(v.why, `${path}.why`),
+        nonEmptyString(v.fix, `${path}.fix`),
+        v.tags === undefined ? null : stringArray(v.tags, `${path}.tags`),
+    ]);
+};
+const settings = (v) => {
+    if (!isObject(v))
+        return `settings must be an object of key → string, got ${show(v)}`;
+    for (const [k, val] of Object.entries(v))
+        if (typeof val !== 'string')
+            return `settings.${k} must be a string, got ${show(val)}`;
+    return null;
+};
+/** The first shape problem in a config, or null. Keys left undefined take their defaults. */
+export const configProblem = (config) => {
+    if (!isObject(config))
+        return `the config must be an object, got ${show(config)}`;
+    const unknown = Object.keys(config).find(k => !CONFIG_KEYS.includes(k));
+    if (unknown !== undefined)
+        return `unknown top-level key "${unknown}" — known keys: ${CONFIG_KEYS.join(', ')}`;
+    const c = config;
+    const has = (k) => c[k] !== undefined;
+    return first([
+        has('settings') ? settings(c.settings) : null,
+        has('rules') ? levelMap(c.rules, 'rules') : null,
+        has('custom') ? entries(c.custom, 'custom', customEntry) : null,
+        has('overrides') ? entries(c.overrides, 'overrides', override) : null,
+        has('files') ? stringArray(c.files, 'files') : null,
+        has('ignores') ? stringArray(c.ignores, 'ignores') : null,
+        has('ruleSources') ? stringArray(c.ruleSources, 'ruleSources') : null,
+        has('docs') ? entries(c.docs, 'docs', docsEntry) : null,
+        has('validate') ? entries(c.validate, 'validate', step) : null,
+        has('precommit') ? entries(c.precommit, 'precommit', step) : null,
+    ]);
+};

package/dist/{invariants → engine}/ast.d.ts

@@ -22,6 +22,14 @@ export declare const findJsonParseCalls: (file: string, source: string) => Promi
     line: number;
     guarded: boolean;
 }[]>;
+/**
+ * The 1-based lines of a file that run inside a component lifetime: the body of a `<script setup>`
+ * block, and the body of any function named `use…` (a composable) or `setup` (Options API /
+ * `defineComponent`), including everything nested inside them. A store action, a plugin, a plain
+ * helper or module-level code is outside: VueUse's automatic cleanup has no scope to attach to there,
+ * so a rule that recommends a VueUse composable must stay silent on those lines.
+ */
+export declare const componentScopeLines: (file: string, source: string) => Promise<Set<number>>;
 /**
  * Every static import that survives compilation: default, named, namespace and bare side-effect
  * imports plus `export … from` re-exports, in .ts files and in every script block of a .vue file.

package/dist/{invariants → engine}/ast.js

@@ -83,6 +83,57 @@ export const findJsonParseCalls = async (file, source) => {
     }
     return out;
 };
+/**
+ * The 1-based lines of a file that run inside a component lifetime: the body of a `<script setup>`
+ * block, and the body of any function named `use…` (a composable) or `setup` (Options API /
+ * `defineComponent`), including everything nested inside them. A store action, a plugin, a plain
+ * helper or module-level code is outside: VueUse's automatic cleanup has no scope to attach to there,
+ * so a rule that recommends a VueUse composable must stay silent on those lines.
+ */
+export const componentScopeLines = async (file, source) => {
+    const t = await ts();
+    const lines = new Set();
+    const add = (from, to) => { for (let l = from; l <= to; l++)
+        lines.add(l); };
+    if (file.endsWith('.vue')) {
+        const re = /<script\b([^>]*)>([\s\S]*?)<\/script>/g;
+        let m;
+        while ((m = re.exec(source)) !== null) {
+            if (!/\bsetup\b/.test(m[1] ?? '') || m[2] === undefined)
+                continue;
+            const bodyStart = m.index + m[0].length - m[2].length - '</script>'.length;
+            const first = source.slice(0, bodyStart).split('\n').length;
+            add(first, first + m[2].split('\n').length - 1);
+        }
+    }
+    const SCOPED = /^(?:use[A-Z0-9]|setup$)/;
+    const nameOf = (node) => {
+        if ((t.isFunctionDeclaration(node) || t.isMethodDeclaration(node) || t.isFunctionExpression(node)) && node.name && t.isIdentifier(node.name))
+            return node.name.text;
+        const parent = node.parent;
+        if (!parent)
+            return null;
+        if (t.isVariableDeclaration(parent) && t.isIdentifier(parent.name))
+            return parent.name.text;
+        if (t.isPropertyAssignment(parent) && (t.isIdentifier(parent.name) || t.isStringLiteral(parent.name)))
+            return parent.name.text;
+        return null;
+    };
+    for (const script of scriptsOf(file, source)) {
+        const sf = t.createSourceFile(file, script.code, t.ScriptTarget.Latest, true);
+        const lineOf = (pos) => sf.getLineAndCharacterOfPosition(pos).line + 1 + script.lineOffset;
+        const visit = (node) => {
+            const isFn = t.isFunctionDeclaration(node) || t.isFunctionExpression(node) || t.isArrowFunction(node) || t.isMethodDeclaration(node);
+            if (isFn && SCOPED.test(nameOf(node) ?? '')) {
+                add(lineOf(node.getStart(sf)), lineOf(node.getEnd()));
+                return;
+            }
+            t.forEachChild(node, visit);
+        };
+        visit(sf);
+    }
+    return lines;
+};
 /**
  * Every static import that survives compilation: default, named, namespace and bare side-effect
  * imports plus `export … from` re-exports, in .ts files and in every script block of a .vue file.

package/dist/engine/docs.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `codestyle docs` rendering: an agent-facing rules file (a consumer's `.claude/rules/e2e.md`)
+ * generated from a template plus the registry, so the text an agent reads can never drift from
+ * the rules that actually run. Pure — the template arrives through `read`, the output is
+ * returned; the CLI writes it (and compares it under `--check`).
+ */
+import type { DocsEntry } from '../config/schema.js';
+import type { Registry } from './registry.js';
+/**
+ * Render one `config.docs` entry. Rules carrying any of `entry.tags` are selected (every rule
+ * when `tags` is absent or empty), in registry order; checkable rules not set `off` go into the rules table,
+ * `eslint`/`test`-owned declarations into a second table that is left out when there are none.
+ */
+export declare const renderDocs: (entry: DocsEntry, registry: Registry, read: (p: string) => string | null) => string;

package/dist/engine/docs.js

@@ -0,0 +1,72 @@
+/**
+ * `codestyle docs` rendering: an agent-facing rules file (a consumer's `.claude/rules/e2e.md`)
+ * generated from a template plus the registry, so the text an agent reads can never drift from
+ * the rules that actually run. Pure — the template arrives through `read`, the output is
+ * returned; the CLI writes it (and compares it under `--check`).
+ */
+import { ConfigError } from '../config/define-config.js';
+import { isExternal } from './types.js';
+const MARKER = '<!-- rules -->';
+/**
+ * Split a leading YAML front-matter block (`---` on line 1, closed by the next line that is exactly
+ * `---`) off the template. Readers of an agent rules file only recognise front matter on line 1, so it
+ * must stay first; without a closing line there is no front matter.
+ */
+const splitFrontMatter = (template) => {
+    const none = { front: '', rest: template };
+    const lines = template.split('\n');
+    if (lines[0] !== '---')
+        return none;
+    const close = lines.indexOf('---', 1);
+    if (close === -1)
+        return none;
+    const front = lines.slice(0, close + 1).join('\n') + '\n';
+    return { front, rest: template.slice(front.length) };
+};
+/**
+ * Pipes break the table; a bare `<key>` is eaten by any HTML renderer of the file; a newline
+ * (multi-line template-literal prose) ends the row — so whitespace runs collapse to one space.
+ */
+const cell = (s) => s.replace(/\s+/g, ' ').trim().replace(/\|/g, '\\|').replace(/</g, '&lt;');
+const rulesTable = (entries) => [
+    '## Rules',
+    '',
+    '| Rule | Level | Title | Why | Fix |',
+    '|---|---|---|---|---|',
+    ...entries.map(({ rule, level }) => {
+        const fix = isExternal(rule) ? '' : rule.fix;
+        return `| **${rule.name}** | ${level} | ${cell(rule.title)} | ${cell(rule.why)} | ${cell(fix)} |`;
+    }),
+];
+const externalTable = (entries) => [
+    '## Owned elsewhere',
+    '',
+    '| Rule | Owner | Ref | Title | Why |',
+    '|---|---|---|---|---|',
+    ...entries.map(({ rule, owner }) => `| **${rule.name}** | ${owner} | \`${cell(isExternal(rule) ? rule.ref : '')}\` | ${cell(rule.title)} | ${cell(rule.why)} |`),
+];
+/**
+ * Render one `config.docs` entry. Rules carrying any of `entry.tags` are selected (every rule
+ * when `tags` is absent or empty), in registry order; checkable rules not set `off` go into the rules table,
+ * `eslint`/`test`-owned declarations into a second table that is left out when there are none.
+ */
+export const renderDocs = (entry, registry, read) => {
+    const template = read(entry.template);
+    if (template === null)
+        throw new ConfigError(`docs: template ${entry.template} not found`);
+    const markers = template.split(MARKER).length - 1;
+    if (markers === 0)
+        throw new ConfigError(`docs: ${entry.template} has no ${MARKER} marker`);
+    if (markers > 1)
+        throw new ConfigError(`docs: ${entry.template} has more than one ${MARKER} marker`);
+    const tags = entry.tags ?? [];
+    const selected = tags.length ? registry.all.filter(r => r.tags.some(t => tags.includes(t))) : registry.all;
+    // An agent rules file lists what must be followed: a rule switched off is not.
+    const checkable = selected.filter(r => !isExternal(r.rule) && r.level !== 'off');
+    const external = selected.filter(r => isExternal(r.rule));
+    const tables = [...rulesTable(checkable), ...(external.length ? ['', ...externalTable(external)] : [])].join('\n');
+    const header = `<!-- generated by \`codestyle docs\` from ${entry.template} — edit the template, not this file -->`;
+    const { front, rest } = splitFrontMatter(template);
+    const body = rest.replace(MARKER, () => tables);
+    return `${front}${header}\n${body}`.replace(/\n*$/, '\n');
+};