@event4u/agent-config 6.0.0 → 7.0.0

package/src/scripts/lint_artefact_frontmatter.ts

@@ -0,0 +1,359 @@
+#!/usr/bin/env tsx
+/**
+ * Lint Phase-4 discovery frontmatter on every artefact.
+ *
+ * TypeScript twin of `src/scripts/lint_artefact_frontmatter.py` (ADR-200,
+ * Phase 4 / Wave 4b). The CLI contract is mirrored EXACTLY — `--quiet`
+ * flag, exit codes (0 clean, 1 violation), stdout/stderr split,
+ * byte-identical finding messages (including Python-shaped list repr),
+ * same scan trees and order, same `validate_frontmatter.parse_frontmatter`
+ * splitter, same closed vocabularies.
+ *
+ * Walks skills / rules / commands / templates under `.agent-src.uncondensed/`
+ * and asserts per-file that the five ADR-013 keys are present and
+ * well-formed.
+ *
+ * Exits 0 clean, 1 on any violation.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+import { parse_frontmatter } from './validate_frontmatter.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+// Module-level paths are test seams (the Python tests monkeypatch ROOT / SRC
+// / VOCAB_DIR). Mutable lets + setters mirror that.
+let ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+let SRC = path.join(ROOT, '.agent-src.uncondensed');
+let VOCAB_DIR = path.join(ROOT, 'src', 'config', 'discovery');
+
+/** Test seam: override the module-level scan roots (mirrors monkeypatch). */
+function _set_paths(opts: { root?: string; src?: string; vocabDir?: string }): void {
+    if (opts.root !== undefined) {
+        ROOT = opts.root;
+    }
+    if (opts.src !== undefined) {
+        SRC = opts.src;
+    }
+    if (opts.vocabDir !== undefined) {
+        VOCAB_DIR = opts.vocabDir;
+    }
+}
+
+const LIFECYCLES = new Set(['active', 'deprecated', 'experimental', 'archived']);
+const TRUST_LEVELS = new Set([
+    'core',
+    'professional',
+    'experimental',
+    'advisory',
+    'restricted',
+]);
+const TRUST_CONFIDENCE = new Set(['high', 'medium', 'low']);
+
+function _load_vocab(): [Set<string>, Set<string>, Set<string>] {
+    const ws = (parseYaml(fs.readFileSync(path.join(VOCAB_DIR, 'workspaces.yml'), 'utf-8'), {
+        version: '1.1',
+    }) || []) as Array<Record<string, unknown>>;
+    const packs = (parseYaml(fs.readFileSync(path.join(VOCAB_DIR, 'packs.yml'), 'utf-8'), {
+        version: '1.1',
+    }) || []) as Array<Record<string, unknown>>;
+    const rawUn = (parseYaml(
+        fs.readFileSync(path.join(VOCAB_DIR, 'unassigned-artefacts.yml'), 'utf-8'),
+        { version: '1.1' },
+    ) || []) as Array<Record<string, unknown>>;
+    const wsIds = new Set(ws.map((e) => e['id'] as string));
+    const packIds = new Set(packs.map((e) => e['id'] as string));
+    const quarantine = new Set(rawUn.map((e) => e['path'] as string));
+    return [wsIds, packIds, quarantine];
+}
+
+function _iter_artefacts(): string[] {
+    const out: string[] = [];
+    for (const p of _rglobSorted(path.join(SRC, 'skills'), 'SKILL.md')) {
+        out.push(p);
+    }
+    for (const p of _rglobSorted(path.join(SRC, 'rules'), '*.md')) {
+        out.push(p);
+    }
+    for (const p of _rglobSorted(path.join(SRC, 'commands'), '*.md')) {
+        out.push(p);
+    }
+    if (_exists(path.join(SRC, 'templates'))) {
+        for (const p of _rglobSorted(path.join(SRC, 'templates'), '*.md')) {
+            out.push(p);
+        }
+    }
+    return out;
+}
+
+function _check_one(
+    p: string,
+    wsIds: Set<string>,
+    packIds: Set<string>,
+    quarantine: Set<string>,
+): string[] {
+    const rel = _relPosix(p);
+    const errs: string[] = [];
+    if (quarantine.has(rel)) {
+        const text = fs.readFileSync(p, 'utf-8');
+        const [fm] = parse_frontmatter(text);
+        if (
+            isPlainObject(fm) &&
+            ['workspaces', 'packs', 'lifecycle', 'trust', 'install'].some((k) => k in fm)
+        ) {
+            errs.push(
+                `${rel}: quarantined in unassigned-artefacts.yml but carries` +
+                    ' discovery frontmatter — remove one or the other.',
+            );
+        }
+        return errs;
+    }
+
+    const text = fs.readFileSync(p, 'utf-8');
+    const [fm] = parse_frontmatter(text);
+    if (!isPlainObject(fm)) {
+        errs.push(`${rel}: missing or unparseable frontmatter`);
+        return errs;
+    }
+
+    for (const key of ['workspaces', 'packs', 'lifecycle', 'trust', 'install']) {
+        if (!(key in fm)) {
+            errs.push(`${rel}: missing required key \`${key}\``);
+        }
+    }
+    if (errs.length) {
+        return errs;
+    }
+
+    const ws = fm['workspaces'];
+    if (!Array.isArray(ws) || ws.length === 0) {
+        errs.push(`${rel}: workspaces must be a non-empty list`);
+    } else {
+        const bad = ws.filter((w) => !wsIds.has(w as string));
+        if (bad.length) {
+            errs.push(`${rel}: workspaces not in workspaces.yml: ${_pyRepr(bad)}`);
+        }
+    }
+
+    const packs = fm['packs'];
+    if (!Array.isArray(packs) || packs.length === 0) {
+        errs.push(`${rel}: packs must be a non-empty list`);
+    } else {
+        const bad = packs.filter((p2) => !packIds.has(p2 as string));
+        if (bad.length) {
+            errs.push(`${rel}: packs not in packs.yml: ${_pyRepr(bad)}`);
+        }
+    }
+
+    if ('pack' in fm) {
+        const owner = fm['pack'];
+        if (typeof owner !== 'string' || !packIds.has(owner)) {
+            errs.push(`${rel}: pack \`${owner}\` not a known pack id in packs.yml`);
+        }
+    }
+
+    const lc = fm['lifecycle'];
+    if (typeof lc !== 'string' || !LIFECYCLES.has(lc)) {
+        errs.push(`${rel}: lifecycle \`${lc}\` not in ${_sortedListRepr(LIFECYCLES)}`);
+    }
+
+    const trust = fm['trust'];
+    if (!isPlainObject(trust)) {
+        errs.push(`${rel}: trust must be a mapping`);
+    } else {
+        const level = (trust as Record<string, unknown>)['level'];
+        if (typeof level !== 'string' || !TRUST_LEVELS.has(level)) {
+            errs.push(
+                `${rel}: trust.level \`${_unwrap(level)}\` not in ${_sortedListRepr(TRUST_LEVELS)}`,
+            );
+        }
+        const confidence = (trust as Record<string, unknown>)['confidence'];
+        if (typeof confidence !== 'string' || !TRUST_CONFIDENCE.has(confidence)) {
+            errs.push(
+                `${rel}: trust.confidence \`${_unwrap(confidence)}\` not in` +
+                    ` ${_sortedListRepr(TRUST_CONFIDENCE)}`,
+            );
+        }
+        const hrr = (trust as Record<string, unknown>)['human_review_required'];
+        if (typeof hrr !== 'boolean') {
+            errs.push(`${rel}: trust.human_review_required must be bool`);
+        }
+    }
+
+    const install = fm['install'];
+    if (!isPlainObject(install)) {
+        errs.push(`${rel}: install must be a mapping`);
+    } else {
+        if (typeof (install as Record<string, unknown>)['default'] !== 'boolean') {
+            errs.push(`${rel}: install.default must be bool`);
+        }
+        if (typeof (install as Record<string, unknown>)['removable'] !== 'boolean') {
+            errs.push(`${rel}: install.removable must be bool`);
+        }
+    }
+    return errs;
+}
+
+interface Args {
+    quiet: boolean;
+}
+
+function parse_args(argv: readonly string[]): Args {
+    let quiet = false;
+    for (const arg of argv) {
+        if (arg === '--quiet') {
+            quiet = true;
+        } else if (arg === '-h' || arg === '--help') {
+            process.stdout.write('usage: lint_artefact_frontmatter [-h] [--quiet]\n');
+            process.exit(0);
+        } else {
+            process.stderr.write(`lint_artefact_frontmatter: error: unrecognized arguments: ${arg}\n`);
+            process.exit(2);
+        }
+    }
+    return { quiet };
+}
+
+function main(argv?: readonly string[]): number {
+    const args = parse_args(argv ?? process.argv.slice(2));
+
+    const [wsIds, packIds, quarantine] = _load_vocab();
+    const artefacts = _iter_artefacts();
+    const allErrs: string[] = [];
+    for (const p of artefacts) {
+        allErrs.push(..._check_one(p, wsIds, packIds, quarantine));
+    }
+
+    if (allErrs.length) {
+        for (const e of allErrs) {
+            process.stderr.write(`ERROR: ${e}\n`);
+        }
+        process.stderr.write(
+            `\n${allErrs.length} violation(s) across ${artefacts.length} artefact(s).\n`,
+        );
+        return 1;
+    }
+    if (!args.quiet) {
+        process.stdout.write(
+            `✅  lint-artefact-frontmatter: ${artefacts.length} artefact(s) clean` +
+                ` (quarantine: ${quarantine.size}).\n`,
+        );
+    }
+    return 0;
+}
+
+// --- helpers --------------------------------------------------------------
+
+function _exists(p: string): boolean {
+    try {
+        fs.statSync(p);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/** Recursive glob matching `Path.rglob(pattern)`, returned sorted by full path. */
+function _rglobSorted(root: string, pattern: string): string[] {
+    const out: string[] = [];
+    const matchExt = pattern === '*.md' ? '.md' : null;
+    const matchExact = pattern === 'SKILL.md' ? 'SKILL.md' : null;
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                walk(full);
+            } else if (e.isFile()) {
+                if (matchExact !== null && e.name === matchExact) {
+                    out.push(full);
+                } else if (matchExt !== null && e.name.endsWith(matchExt)) {
+                    out.push(full);
+                }
+            }
+        }
+    };
+    if (_exists(root)) {
+        walk(root);
+    }
+    return out.sort();
+}
+
+function _relPosix(p: string): string {
+    return path.relative(ROOT, p).split(path.sep).join('/');
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Render a value the way Python embeds it in `\`${value}\`` — None for null. */
+function _unwrap(v: unknown): string {
+    if (v === null || v === undefined) {
+        return 'None';
+    }
+    if (v === true) {
+        return 'True';
+    }
+    if (v === false) {
+        return 'False';
+    }
+    return String(v);
+}
+
+/** Mirror Python list repr of strings: ['a', 'b']. */
+function _pyRepr(arr: unknown[]): string {
+    return '[' + arr.map((x) => _pyReprScalar(x)).join(', ') + ']';
+}
+
+function _pyReprScalar(v: unknown): string {
+    if (v === null || v === undefined) {
+        return 'None';
+    }
+    if (v === true) {
+        return 'True';
+    }
+    if (v === false) {
+        return 'False';
+    }
+    if (typeof v === 'number') {
+        return String(v);
+    }
+    if (typeof v === 'string') {
+        return `'${v.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+    }
+    return String(v);
+}
+
+/** Mirror Python `sorted(set)` repr as a list literal of single-quoted strings. */
+function _sortedListRepr(s: Set<string>): string {
+    return '[' + [...s].sort().map((x) => `'${x}'`).join(', ') + ']';
+}
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export {
+    LIFECYCLES,
+    TRUST_LEVELS,
+    TRUST_CONFIDENCE,
+    _set_paths,
+    _load_vocab,
+    _iter_artefacts,
+    _check_one,
+    parse_args,
+    main,
+};

package/src/scripts/lint_bench_ab.ts

@@ -0,0 +1,319 @@
+#!/usr/bin/env tsx
+/**
+ * Validate the A/B bench corpora + `docs/benchmark.md` shape.
+ *
+ * TypeScript twin of `src/scripts/lint_bench_ab.py` (ADR-200, Phase 4 /
+ * Wave 4b). The CLI contract is mirrored EXACTLY — `--quiet` flag, exit
+ * codes (0 success, 1 first violation), stdout/stderr split, byte-identical
+ * finding messages (including the `lint_bench_ab: <relpath>: <msg>` prefix
+ * and the Python `repr()`-shaped value formatting), same check order, same
+ * YAML loader (`yaml.safe_load`).
+ *
+ * Phase 5 Step 3 of `agents/roadmaps/road-to-package-impact-benchmark.md`.
+ *
+ * Exit 0 on success, 1 on the first violation (with file + line where
+ * possible).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const TRACK_A_PATH = path.join(REPO_ROOT, 'internal', 'bench', 'corpora', 'ab-tracka.yaml');
+const TRACK_B_PATH = path.join(REPO_ROOT, 'internal', 'bench', 'corpora', 'ab-trackb.yaml');
+const DOCS_PATH = path.join(REPO_ROOT, 'docs', 'benchmark.md');
+
+const REQUIRED_SECTIONS = [
+    // docs/benchmark.md is the v2 discipline-axis report (rendered by
+    // bench_ab_v2_stats.py --markdown). The v1 Headline/Track-A/Track-B/History
+    // structure was retired with the v1 binary-capability frame.
+    '## Honesty labels',
+    '## Gate verdict',
+    '## Methodology',
+] as const;
+
+const TRACK_A_CATEGORIES = new Set(['rule', 'skill']);
+const TRACK_B_CATEGORIES = new Set(['bugfix', 'feature', 'refactor', 'uiaudit', 'testadd']);
+
+// CPython set-literal repr is hash-ordered, not insertion-ordered. These
+// frozen messages reproduce the exact `{...}` text the Python linter emits
+// in a category-mismatch finding (verified against CPython 3.x):
+//   {'rule', 'skill'}
+//   {'testadd', 'feature', 'uiaudit', 'refactor', 'bugfix'}
+const _TRACK_A_CATEGORIES_REPR = "{'rule', 'skill'}";
+const _TRACK_B_CATEGORIES_REPR = "{'testadd', 'feature', 'uiaudit', 'refactor', 'bugfix'}";
+
+class LintError extends Error {}
+
+function _relTo(p: string): string {
+    return path.relative(REPO_ROOT, p);
+}
+
+function _fail(p: string, msg: string): never {
+    process.stderr.write(`lint_bench_ab: ${_relTo(p)}: ${msg}\n`);
+    throw new LintError(msg);
+}
+
+/** Python repr() for an arbitrary loaded value, ASCII-shaped. */
+function _pyRepr(value: unknown): string {
+    if (value === null || value === undefined) {
+        return 'None';
+    }
+    if (value === true) {
+        return 'True';
+    }
+    if (value === false) {
+        return 'False';
+    }
+    if (typeof value === 'number') {
+        return String(value);
+    }
+    if (typeof value === 'string') {
+        let out = "'";
+        for (const ch of value) {
+            if (ch === '\\') {
+                out += '\\\\';
+            } else if (ch === "'") {
+                out += "\\'";
+            } else if (ch === '\n') {
+                out += '\\n';
+            } else if (ch === '\r') {
+                out += '\\r';
+            } else if (ch === '\t') {
+                out += '\\t';
+            } else {
+                out += ch;
+            }
+        }
+        return out + "'";
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map((v) => _pyRepr(v)).join(', ') + ']';
+    }
+    if (isPlainObject(value)) {
+        const parts = Object.entries(value as Record<string, unknown>).map(
+            ([k, v]) => `${_pyRepr(k)}: ${_pyRepr(v)}`,
+        );
+        return '{' + parts.join(', ') + '}';
+    }
+    return String(value);
+}
+
+function _load(p: string): unknown {
+    return parseYaml(fs.readFileSync(p, 'utf-8'), { version: '1.1' });
+}
+
+function _get(obj: unknown, key: string): unknown {
+    return isPlainObject(obj) ? (obj as Record<string, unknown>)[key] : undefined;
+}
+
+function lint_track_a(): void {
+    if (!_exists(TRACK_A_PATH)) {
+        _fail(TRACK_A_PATH, 'missing corpus file');
+    }
+    const data = _load(TRACK_A_PATH);
+    if (_get(data, 'version') !== 1) {
+        _fail(TRACK_A_PATH, `version must be 1 (got ${_pyRepr(_get(data, 'version'))})`);
+    }
+    if (_get(data, 'corpus_id') !== 'ab-tracka') {
+        _fail(
+            TRACK_A_PATH,
+            `corpus_id must be 'ab-tracka' (got ${_pyRepr(_get(data, 'corpus_id'))})`,
+        );
+    }
+    const prompts = _get(data, 'prompts') || [];
+    if (!Array.isArray(prompts)) {
+        _fail(TRACK_A_PATH, 'prompts must be a list');
+    }
+    if (prompts.length < 30) {
+        _fail(TRACK_A_PATH, `prompts must have ≥ 30 entries (found ${prompts.length})`);
+    }
+    const ids = new Set<unknown>();
+    for (let i = 0; i < prompts.length; i += 1) {
+        const prompt = prompts[i];
+        const loc = `prompts[${i}]`;
+        if (!isPlainObject(prompt)) {
+            _fail(TRACK_A_PATH, `${loc} must be a mapping`);
+        }
+        const pid = _get(prompt, 'id');
+        if (typeof pid !== 'string' || !pid) {
+            _fail(TRACK_A_PATH, `${loc}.id must be a non-empty string`);
+        }
+        if (ids.has(pid)) {
+            _fail(TRACK_A_PATH, `${loc}.id duplicates an earlier id (${_pyRepr(pid)})`);
+        }
+        ids.add(pid);
+        const cat = _get(prompt, 'category');
+        if (typeof cat !== 'string' || !TRACK_A_CATEGORIES.has(cat)) {
+            _fail(
+                TRACK_A_PATH,
+                `${loc}.category must be in ${_TRACK_A_CATEGORIES_REPR} (got ${_pyRepr(cat)})`,
+            );
+        }
+        const target = _get(prompt, 'expected_target');
+        if (typeof target !== 'string' || !target) {
+            _fail(TRACK_A_PATH, `${loc}.expected_target must be a non-empty string`);
+        }
+        const keywords = _get(prompt, 'expected_keywords');
+        if (keywords !== null && keywords !== undefined && !Array.isArray(keywords)) {
+            _fail(TRACK_A_PATH, `${loc}.expected_keywords must be a list when present`);
+        }
+        const pr = _get(prompt, 'prompt');
+        if (typeof pr !== 'string' || !pr) {
+            _fail(TRACK_A_PATH, `${loc}.prompt must be a non-empty string`);
+        }
+    }
+}
+
+function lint_track_b(): void {
+    if (!_exists(TRACK_B_PATH)) {
+        _fail(TRACK_B_PATH, 'missing corpus file');
+    }
+    const data = _load(TRACK_B_PATH);
+    if (_get(data, 'version') !== 1) {
+        _fail(TRACK_B_PATH, `version must be 1 (got ${_pyRepr(_get(data, 'version'))})`);
+    }
+    if (_get(data, 'corpus_id') !== 'ab-trackb') {
+        _fail(
+            TRACK_B_PATH,
+            `corpus_id must be 'ab-trackb' (got ${_pyRepr(_get(data, 'corpus_id'))})`,
+        );
+    }
+    const tasks = _get(data, 'tasks') || [];
+    if (!Array.isArray(tasks)) {
+        _fail(TRACK_B_PATH, 'tasks must be a list');
+    }
+    if (tasks.length < 10) {
+        _fail(TRACK_B_PATH, `tasks must have ≥ 10 entries (found ${tasks.length})`);
+    }
+    const ids = new Set<unknown>();
+    for (let i = 0; i < tasks.length; i += 1) {
+        const task = tasks[i];
+        const loc = `tasks[${i}]`;
+        if (!isPlainObject(task)) {
+            _fail(TRACK_B_PATH, `${loc} must be a mapping`);
+        }
+        const tid = _get(task, 'id');
+        if (typeof tid !== 'string' || !tid) {
+            _fail(TRACK_B_PATH, `${loc}.id must be a non-empty string`);
+        }
+        if (ids.has(tid)) {
+            _fail(TRACK_B_PATH, `${loc}.id duplicates an earlier id (${_pyRepr(tid)})`);
+        }
+        ids.add(tid);
+        const cat = _get(task, 'category');
+        if (typeof cat !== 'string' || !TRACK_B_CATEGORIES.has(cat)) {
+            _fail(
+                TRACK_B_PATH,
+                `${loc}.category must be in ${_TRACK_B_CATEGORIES_REPR} (got ${_pyRepr(cat)})`,
+            );
+        }
+        const pr = _get(task, 'prompt');
+        if (typeof pr !== 'string' || !pr) {
+            _fail(TRACK_B_PATH, `${loc}.prompt must be a non-empty string`);
+        }
+        const seeds = _get(task, 'seed_files');
+        if (!Array.isArray(seeds)) {
+            _fail(TRACK_B_PATH, `${loc}.seed_files must be a list`);
+        }
+        const crit = _get(task, 'success_criteria');
+        if (!isPlainObject(crit) || Object.keys(crit as object).length === 0) {
+            _fail(TRACK_B_PATH, `${loc}.success_criteria must be a non-empty mapping`);
+        }
+    }
+}
+
+function lint_doc(quiet: boolean): void {
+    if (!_exists(DOCS_PATH)) {
+        if (!quiet) {
+            process.stdout.write(
+                `lint_bench_ab: ${_relTo(DOCS_PATH)} not yet rendered ` +
+                    '(run task bench:ab:diff) — skipping doc shape check\n',
+            );
+        }
+        return;
+    }
+    const body = fs.readFileSync(DOCS_PATH, 'utf-8');
+    const missing = REQUIRED_SECTIONS.filter((section) => !body.includes(section));
+    if (missing.length) {
+        _fail(DOCS_PATH, `missing required sections: ${_pyRepr(missing)}`);
+    }
+}
+
+interface Args {
+    quiet: boolean;
+}
+
+function parse_args(argv: readonly string[]): Args {
+    let quiet = false;
+    for (const arg of argv) {
+        if (arg === '--quiet') {
+            quiet = true;
+        } else if (arg === '-h' || arg === '--help') {
+            process.stdout.write('usage: lint_bench_ab [-h] [--quiet]\n');
+            process.exit(0);
+        } else {
+            process.stderr.write(`lint_bench_ab: error: unrecognized arguments: ${arg}\n`);
+            process.exit(2);
+        }
+    }
+    return { quiet };
+}
+
+function main(argv?: readonly string[]): number {
+    const args = parse_args(argv ?? process.argv.slice(2));
+    try {
+        lint_track_a();
+        lint_track_b();
+        lint_doc(args.quiet);
+    } catch (exc) {
+        if (exc instanceof LintError) {
+            return 1;
+        }
+        throw exc;
+    }
+    if (!args.quiet) {
+        process.stdout.write('lint_bench_ab: OK\n');
+    }
+    return 0;
+}
+
+// --- helpers --------------------------------------------------------------
+
+function _exists(p: string): boolean {
+    try {
+        fs.statSync(p);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export {
+    REPO_ROOT,
+    TRACK_A_PATH,
+    TRACK_B_PATH,
+    DOCS_PATH,
+    REQUIRED_SECTIONS,
+    LintError,
+    lint_track_a,
+    lint_track_b,
+    lint_doc,
+    parse_args,
+    main,
+};