@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/_lib/foreign_scan.ts

@@ -0,0 +1,106 @@
+/**
+ * The unclaimed-file scan under this package's own deploy roots.
+ *
+ * Moved verbatim out of `src/scripts/_cli/cmd_doctor.ts`
+ * (road-to-a-tree-that-keeps-its-neighbours Phase 2.6). The behaviour is
+ * unchanged — this is a module boundary, not a rewrite.
+ *
+ * Two reasons it earns its own file. `cmd_doctor.ts` is 2,100 lines above the
+ * `check_source_size_budget` ceiling, so the census line that now links this
+ * listing is paid for by a MOVE rather than by raising the tree-wide excess.
+ * And the neighbour census answers a strictly larger question than this scan
+ * does — this one lists FILES under paths this package deploys to, the census
+ * lists ARTEFACTS wherever a host keeps them — so the two belong beside each
+ * other rather than nested inside a doctor renderer.
+ *
+ * What this scan does NOT do, stated because the two listings look alike: it
+ * never leaves a deploy root, so a neighbour's skill in `~/.claude/skills` or
+ * hook entry in `.cursor/hooks.json` is invisible to it. That gap is the
+ * census's subject, and the census links back here rather than repeating the
+ * paths this one already prints.
+ */
+
+import * as fs from 'node:fs';
+
+/**
+ * `Path.rglob("*")` — every descendant path (dirs + files), recursively.
+ *
+ * Order is not relied upon by callers (they sort the matched set), but the
+ * walk is deterministic (sorted per directory) to keep behaviour stable.
+ */
+export function rglob(root: string, isDir: (p: string) => boolean, join: (a: string, b: string) => string): string[] {
+    const out: string[] = [];
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const ent of entries) {
+            const full = join(dir, ent.name);
+            out.push(full);
+            let dirLike = ent.isDirectory();
+            if (ent.isSymbolicLink()) {
+                // pathlib rglob follows into symlinked dirs.
+                dirLike = isDir(full);
+            }
+            if (dirLike) {
+                walk(full);
+            }
+        }
+    };
+    walk(root);
+    return out;
+}
+
+export interface ForeignScanDeps {
+    pathExists: (p: string) => boolean;
+    isDir: (p: string) => boolean;
+    isFile: (p: string) => boolean;
+    resolvePath: (p: string) => string;
+    join: (a: string, b: string) => string;
+    /** Resolve one declared deploy root against the consumer root. */
+    resolveRoot: (projectRoot: string, rel: string) => string;
+    defaultRoots: readonly string[];
+}
+
+/**
+ * Walk every declared deploy root and surface unclaimed files. Only regular
+ * files under `deploy_roots` count; bookkeeping is on the resolved final path.
+ */
+export function scanForeign(
+    projectRoot: string,
+    manifest: Record<string, unknown>,
+    known: Set<string>,
+    deps: ForeignScanDeps,
+): string[] {
+    const roots = (manifest['deploy_roots'] as unknown[] | undefined) || Array.from(deps.defaultRoots);
+    const foreign: string[] = [];
+    const seen = new Set<string>();
+    for (const root_rel of roots) {
+        const root = deps.resolveRoot(projectRoot, String(root_rel));
+        if (!deps.pathExists(root) || !deps.isDir(root)) {
+            continue;
+        }
+        for (const child of rglob(root, deps.isDir, deps.join)) {
+            if (!deps.isFile(child)) {
+                continue;
+            }
+            let resolved: string;
+            try {
+                resolved = deps.resolvePath(child);
+            } catch {
+                resolved = child;
+            }
+            if (known.has(resolved) || seen.has(resolved)) {
+                continue;
+            }
+            seen.add(resolved);
+            foreign.push(child);
+        }
+    }
+    foreign.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return foreign;
+}

package/src/scripts/_lib/git_base_ref.ts

@@ -0,0 +1,92 @@
+/**
+ * The one reading of a `--base` value, shared by `sync_pr_branch` and
+ * `check_branch_freshness`.
+ *
+ * The two resolvers used to accept different spellings: one prefixed every
+ * value with `origin/`, the other asked the server for `refs/heads/<value>`
+ * verbatim. A name copied from one tool's output into the other then named a
+ * ref nobody has (`origin/origin/main`, `refs/heads/origin/main`), and the
+ * freshness gate read that absent ref as an unreachable remote and passed.
+ *
+ * A value that already names where it lives is kept as given: a
+ * remote-tracking ref and `<remote>/x` for a configured remote. `refs/heads/x`
+ * names the branch on origin, so it maps to `refs/remotes/origin/x`: the local
+ * branch of that name is the same clone-time copy a bare name avoids, and a
+ * fetch never updates it. Anything else is a branch name on origin, slashes
+ * included, because `release/1.x` is a branch name and not a remote called
+ * `release`.
+ */
+
+export interface BaseRef {
+    /** The remote the server-side SHA is asked of. */
+    readonly remote: string;
+    /** The branch name on that remote. */
+    readonly branch: string;
+    /** The ref git operations use locally: as given, or `origin/<branch>` for a bare name. */
+    readonly ref: string;
+}
+
+const REMOTE_TRACKING = 'refs/remotes/';
+const LOCAL_HEADS = 'refs/heads/';
+
+/**
+ * The usage error for a `--base` given a blank value, or null for one that
+ * names something. Every tool that accepts `--base` rejects a blank one: an
+ * unset variable expands to nothing, and reading that as "no override" judged
+ * the run against the default branch without a word.
+ */
+export function blankBaseError(value: string): string | null {
+    return value.trim() === '' ? '--base was given an empty value — name the base branch (an unset variable expands to nothing); nothing was read or merged' : null;
+}
+
+/**
+ * The usage error for any `--base` value that must not reach git: a blank one,
+ * or one whose branch name starts with `-`, which git would read as an option.
+ * No branch can carry that name (`git check-ref-format --branch` refuses it).
+ */
+export function baseValueError(value: string, remotes: readonly string[] = []): string | null {
+    const blank = blankBaseError(value);
+    if (blank !== null) return blank;
+    const v = value.trim();
+    const branch = v.startsWith('-') ? v : (parseBaseRef(v, remotes)?.branch ?? v);
+    return branch.startsWith('-') ? `--base ${JSON.stringify(v)} names a branch that starts with "-", which git reads as an option — no branch has that name; nothing was read or merged` : null;
+}
+
+/** Read a `--base` value; null when it is empty. `remotes` are the configured remote names. */
+export function parseBaseRef(value: string, remotes: readonly string[] = []): BaseRef | null {
+    const v = value.trim();
+    if (v === '') return null;
+    if (v.startsWith(LOCAL_HEADS) && v.length > LOCAL_HEADS.length) {
+        const branch = v.slice(LOCAL_HEADS.length);
+        return { remote: 'origin', branch, ref: `${REMOTE_TRACKING}origin/${branch}` };
+    }
+    if (v.startsWith('refs/')) return splitResolvedRef(v);
+    const slash = v.indexOf('/');
+    const known = new Set(['origin', ...remotes]);
+    if (slash > 0 && slash < v.length - 1 && known.has(v.slice(0, slash))) {
+        return { remote: v.slice(0, slash), branch: v.slice(slash + 1), ref: v };
+    }
+    return { remote: 'origin', branch: v, ref: `origin/${v}` };
+}
+
+/**
+ * Split a ref that was already resolved by `parseBaseRef` or reported by git
+ * (`origin/main`, `refs/heads/main`). A full ref outside the branch namespaces
+ * keeps its whole name as the branch, so the server answers it as unknown.
+ */
+export function splitResolvedRef(ref: string): BaseRef {
+    if (ref.startsWith(LOCAL_HEADS)) return { remote: 'origin', branch: ref.slice(LOCAL_HEADS.length), ref };
+    if (ref.startsWith(REMOTE_TRACKING)) {
+        const rest = ref.slice(REMOTE_TRACKING.length);
+        const slash = rest.indexOf('/');
+        if (slash > 0) return { remote: rest.slice(0, slash), branch: rest.slice(slash + 1), ref };
+    }
+    if (ref.startsWith('refs/')) return { remote: 'origin', branch: ref, ref };
+    const slash = ref.indexOf('/');
+    return slash > 0 ? { remote: ref.slice(0, slash), branch: ref.slice(slash + 1), ref } : { remote: 'origin', branch: ref, ref: `origin/${ref}` };
+}
+
+/** `<remote>/<branch>`, the name a human reads and `task push-ready BASE=` accepts. */
+export function displayBase(b: BaseRef): string {
+    return `${b.remote}/${b.branch}`;
+}

package/src/scripts/_lib/git_convention.ts

@@ -0,0 +1,291 @@
+/**
+ * The one reader of the `git.*` convention keys.
+ *
+ * `load_agent_settings` merges a layer that does not parse as if it were absent
+ * and drops user-global keys off its whitelist without a word, which is right
+ * for a setting whose default is harmless and wrong for these three: a team that
+ * declares `rebase` and gets a merge commit because an unrelated line elsewhere
+ * in the file has an unclosed bracket has had its convention overridden by a
+ * default nobody chose. So every key is reported with one of six states, and a
+ * caller that acts on the value refuses on anything but `valid` or `absent`:
+ *
+ * - `valid`     — the deciding layer parsed and the value is allowed;
+ * - `absent`    — no layer sets the key; the template default is reported;
+ * - `malformed` — a layer at or above the deciding one does not parse, so the
+ *                 value is unknowable;
+ * - `invalid`   — the deciding layer sets a value the schema does not allow;
+ * - `discarded` — only a user-global file sets the key, and the loader drops
+ *                 user-global keys that are not whitelisted;
+ * - `unresolvable` — the commit a committed declaration must be read at cannot
+ *                 be resolved, so whether it declares anything is unknown.
+ *
+ * Where the layers come from is a {@link GitConventionSource}, so a reader of a
+ * committed declaration can replace the checkout cascade without touching the
+ * state logic.
+ */
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import * as fs from 'node:fs';
+
+import type * as YamlModule from 'yaml';
+
+import { settings_layer_states, template_defaults, user_global_settings_paths } from './agent_settings.js';
+
+const _require = createRequire(import.meta.url);
+
+export const GIT_CONVENTION_KEYS = ['commit_format', 'branch_pattern', 'update_strategy'] as const;
+export type GitConventionKey = (typeof GIT_CONVENTION_KEYS)[number];
+
+export type GitConventionState = 'valid' | 'absent' | 'malformed' | 'invalid' | 'discarded' | 'unresolvable';
+
+/** Mirrors the enums in `agent-settings.schema.json`; a test pins the parity. */
+export const GIT_CONVENTION_ENUMS: Partial<Record<GitConventionKey, readonly string[]>> = {
+    commit_format: ['ticket-scope', 'ticket-conventional'],
+    update_strategy: ['merge', 'rebase'],
+};
+
+export type GitConventionReason =
+    | 'git-convention-malformed'
+    | 'git-convention-invalid'
+    | 'git-convention-discarded'
+    | 'git-convention-unresolvable';
+
+export interface GitConventionReading {
+    key: GitConventionKey;
+    value: string | null;
+    source: string | null;
+    state: GitConventionState;
+    reason: GitConventionReason | null;
+    detail: string | null;
+}
+
+export interface GitConventionLayer {
+    path: string;
+    parsed: 'absent' | 'valid' | 'malformed';
+    data: unknown;
+    /** False for a layer whose `git.*` values the loader discards. */
+    carries: boolean;
+    /** Why a `malformed` layer is unknown: it does not parse, or its document is not a map. */
+    why?: string;
+    /** Set when the document parses but is not the shape the file is read in; every key reads `invalid`. */
+    shapeError?: string;
+}
+
+export interface GitConventionSource {
+    /** Every layer, lowest precedence first. */
+    layers(): GitConventionLayer[];
+}
+
+export type GitConventionDefaults = Partial<Record<GitConventionKey, string>>;
+
+function _parse(p: string): Pick<GitConventionLayer, 'parsed' | 'data' | 'why'> {
+    let text: string;
+    try {
+        if (!fs.statSync(p).isFile()) return { parsed: 'absent', data: null };
+        text = fs.readFileSync(p, 'utf-8');
+    } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') return { parsed: 'absent', data: null };
+        return { parsed: 'malformed', data: null, why: 'the file cannot be read' };
+    }
+    return parseLayerText(text);
+}
+
+/**
+ * Where the parse failed. An unquoted pattern (`{ticket}-{slug}`) is a flow
+ * mapping to YAML, and the error says nothing about quoting.
+ */
+function _parseFailure(text: string, err: unknown): string {
+    const line = (err as { linePos?: { line: number }[] }).linePos?.[0]?.line;
+    if (line === undefined) return 'the file does not parse';
+    const quote = (text.split('\n')[line - 1] ?? '').includes('{') ? `; a value containing \`{\` must be quoted, e.g. ${_quoteExample('branch_pattern')}` : '';
+    return `the file does not parse at line ${line}${quote}`;
+}
+
+function _quoteExample(key: GitConventionKey): string {
+    return `${key}: "${key === 'branch_pattern' ? '{ticket}-{slug}' : (GIT_CONVENTION_ENUMS[key]?.[0] ?? '…')}"`;
+}
+
+/** One layer's text, parsed the way the settings loader parses a file. */
+export function parseLayerText(text: string): Pick<GitConventionLayer, 'parsed' | 'data' | 'why'> {
+    let data: unknown;
+    try {
+        const YAML = _require('yaml') as typeof YamlModule;
+        data = YAML.parse(text, { version: '1.1' });
+    } catch (err) {
+        return { parsed: 'malformed', data: null, why: _parseFailure(text, err) };
+    }
+    if (data === null || data === undefined) return { parsed: 'valid', data: {} };
+    // The loader ignores a document that is not a map, which is the same silent
+    // fallback as a parse error.
+    if (typeof data !== 'object' || Array.isArray(data)) return { parsed: 'malformed', data: null, why: 'the document is not a map' };
+    return { parsed: 'valid', data };
+}
+
+/** Explicit files: the user-global ones carry nothing, the developer ones carry. */
+export function fileSource(files: { userGlobal?: readonly string[]; developer?: readonly string[] }): GitConventionSource {
+    return {
+        layers: () => [
+            ...(files.userGlobal ?? []).map((p) => ({ path: p, carries: false, ..._parse(p) })),
+            ...(files.developer ?? []).map((p) => ({ path: p, carries: true, ..._parse(p) })),
+        ],
+    };
+}
+
+/** The layers `load_agent_settings({ cwd })` reads for the checkout at `cwd`. */
+export function checkoutSource(cwd: string): GitConventionSource {
+    return {
+        layers: () => {
+            const userGlobalCount = user_global_settings_paths().length;
+            const all = settings_layer_states({ cwd }).map((l) => l.path);
+            return fileSource({ userGlobal: all.slice(0, userGlobalCount), developer: all.slice(userGlobalCount) }).layers();
+        },
+    };
+}
+
+type Lookup = { present: false } | { present: true; value: unknown } | { present: true; notAMap: true };
+
+function _lookup(data: unknown, key: GitConventionKey): Lookup {
+    if (data === null || typeof data !== 'object') return { present: false };
+    const git = (data as Record<string, unknown>).git;
+    if (git === undefined || git === null) return { present: false };
+    if (typeof git !== 'object' || Array.isArray(git)) return { present: true, notAMap: true };
+    const value = (git as Record<string, unknown>)[key];
+    if (value === undefined || value === null) return { present: false };
+    return { present: true, value };
+}
+
+const BRANCH_PLACEHOLDERS = ['type', 'ticket', 'slug'] as const;
+const BRANCH_SAMPLE: Record<(typeof BRANCH_PLACEHOLDERS)[number], string> = {
+    type: 'feat',
+    ticket: 'DEV-1234',
+    slug: 'sample-change',
+};
+/** A rendered name reaches shell commands, so the literal alphabet is closed. */
+const BRANCH_LITERAL = /^[A-Za-z0-9._/-]*$/;
+
+/** The pattern with every placeholder filled from a fixed sample. */
+export function renderBranchSample(pattern: string): string {
+    return pattern.replace(/\{(type|ticket|slug)\}/g, (_m, name: keyof typeof BRANCH_SAMPLE) => BRANCH_SAMPLE[name]);
+}
+
+function _branchPatternReason(pattern: string): string | null {
+    if (pattern === '') return 'the pattern is empty';
+    const literal = pattern.replace(/\{([^{}]*)\}/g, (match, name: string) => {
+        return (BRANCH_PLACEHOLDERS as readonly string[]).includes(name) ? '' : `\u0000${match}`;
+    });
+    const unknown = /\u0000(\{[^{}]*\})/.exec(literal);
+    if (unknown !== null) {
+        return `unknown placeholder ${unknown[1]}; allowed: ${BRANCH_PLACEHOLDERS.map((p) => `{${p}}`).join(', ')}`;
+    }
+    if (/[{}]/.test(literal)) return 'an unbalanced brace';
+    if (!BRANCH_LITERAL.test(literal)) {
+        const bad = [...new Set(literal.replace(/[A-Za-z0-9._/-]/g, ''))].join('');
+        return `literal character(s) ${JSON.stringify(bad)} outside [A-Za-z0-9._/-]`;
+    }
+    if (!pattern.includes('{slug}')) return 'the pattern must contain {slug}';
+    const sample = renderBranchSample(pattern);
+    const check = spawnSync('git', ['check-ref-format', '--branch', sample], { encoding: 'utf8' });
+    // Without git the closed alphabet above is the whole check.
+    if (check.error === undefined && check.status !== 0) {
+        return `the sample \`${sample}\` fails git check-ref-format --branch`;
+    }
+    return null;
+}
+
+/** Why `value` is not allowed for `key`, or null when it is. */
+export function invalidReason(key: GitConventionKey, value: string): string | null {
+    // The schema neither trims nor folds case, so neither does this check.
+    if (value !== value.trim()) return `\`${value}\` has leading or trailing whitespace`;
+    const allowed = GIT_CONVENTION_ENUMS[key];
+    if (allowed !== undefined) {
+        if (allowed.includes(value)) return null;
+        const caseOnly = allowed.includes(value.toLowerCase()) ? ' (values are case-sensitive)' : '';
+        return `\`${value}\` is not one of ${allowed.map((v) => `\`${v}\``).join(', ')}${caseOnly}`;
+    }
+    return _branchPatternReason(value);
+}
+
+function _defaults(): GitConventionDefaults {
+    const git = (template_defaults() as { git?: Record<string, unknown> }).git ?? {};
+    const out: GitConventionDefaults = {};
+    for (const key of GIT_CONVENTION_KEYS) {
+        if (typeof git[key] === 'string') out[key] = git[key] as string;
+    }
+    return out;
+}
+
+/** The template default for a key, or null when the template sets none. */
+export function conventionDefault(key: GitConventionKey): string | null {
+    return _defaults()[key] ?? null;
+}
+
+export function conventionReading(
+    key: GitConventionKey,
+    state: GitConventionState,
+    value: string | null,
+    source: string | null,
+    detail: string | null = null,
+): GitConventionReading {
+    const reason: GitConventionReason | null = isRefusal(state) ? (`git-convention-${state}` as GitConventionReason) : null;
+    return { key, value, source, state, reason, detail };
+}
+
+export function readGitConventionKey(
+    key: GitConventionKey,
+    source: GitConventionSource,
+    defaults: GitConventionDefaults = _defaults(),
+): GitConventionReading {
+    const layers = source.layers();
+    const fallback = defaults[key] ?? null;
+    for (const layer of [...layers].reverse().filter((l) => l.carries)) {
+        if (layer.parsed === 'malformed') {
+            return conventionReading(key, 'malformed', null, layer.path, `${layer.why ?? 'the file cannot be read'}, so the value it may set is unknown`);
+        }
+        if (layer.shapeError !== undefined) return conventionReading(key, 'invalid', null, layer.path, layer.shapeError);
+        const found = _lookup(layer.data, key);
+        if (!found.present) continue;
+        if ('notAMap' in found) return conventionReading(key, 'invalid', null, layer.path, '`git:` is not a map');
+        if (typeof found.value !== 'string') {
+            const shown = typeof found.value === 'object' && found.value !== null ? JSON.stringify(found.value) : String(found.value);
+            return conventionReading(key, 'invalid', shown, layer.path, `the value is not a string — quote the value, e.g. ${_quoteExample(key)}`);
+        }
+        const value = found.value;
+        const why = invalidReason(key, value);
+        return why === null ? conventionReading(key, 'valid', value, layer.path) : conventionReading(key, 'invalid', value, layer.path, why);
+    }
+    for (const layer of [...layers].reverse().filter((l) => !l.carries && l.parsed === 'valid')) {
+        const found = _lookup(layer.data, key);
+        if (!found.present || 'notAMap' in found) continue;
+        const value = typeof found.value === 'string' ? found.value : String(found.value);
+        if (fallback !== null && value === fallback) continue;
+        return conventionReading(
+            key,
+            'discarded',
+            value,
+            layer.path,
+            'user-global files do not carry git.* keys; set it in the project settings file',
+        );
+    }
+    return conventionReading(key, 'absent', fallback, null);
+}
+
+export function readGitConvention(
+    source: GitConventionSource,
+    defaults: GitConventionDefaults = _defaults(),
+): Record<GitConventionKey, GitConventionReading> {
+    const out = {} as Record<GitConventionKey, GitConventionReading>;
+    for (const key of GIT_CONVENTION_KEYS) out[key] = readGitConventionKey(key, source, defaults);
+    return out;
+}
+
+/** Every state a caller must not act on; `show`, `sync` and the `/pr:merge` prose share this one set. */
+export const REFUSAL_STATES: readonly GitConventionState[] = ['malformed', 'invalid', 'discarded', 'unresolvable'];
+
+export function isRefusal(state: GitConventionState): boolean {
+    return REFUSAL_STATES.includes(state);
+}
+
+/** One line naming the reason code, the key and the file. */
+export function describeRefusal(reading: GitConventionReading): string {
+    return `${reading.reason ?? 'git-convention-ok'}: git.${reading.key} in ${reading.source ?? '(no file)'} — ${reading.detail ?? reading.state}`;
+}