@event4u/agent-config 16.3.0 → 16.5.0

package/dist/scripts/_lib/git_convention.js

@@ -0,0 +1,232 @@
+/**
+ * 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 { 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'];
+/** Mirrors the enums in `agent-settings.schema.json`; a test pins the parity. */
+export const GIT_CONVENTION_ENUMS = {
+    commit_format: ['ticket-scope', 'ticket-conventional'],
+    update_strategy: ['merge', 'rebase'],
+};
+function _parse(p) {
+    let text;
+    try {
+        if (!fs.statSync(p).isFile())
+            return { parsed: 'absent', data: null };
+        text = fs.readFileSync(p, 'utf-8');
+    }
+    catch (err) {
+        if (err.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, err) {
+    const line = err.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) {
+    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) {
+    let data;
+    try {
+        const YAML = _require('yaml');
+        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) {
+    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) {
+    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();
+        },
+    };
+}
+function _lookup(data, key) {
+    if (data === null || typeof data !== 'object')
+        return { present: false };
+    const git = data.git;
+    if (git === undefined || git === null)
+        return { present: false };
+    if (typeof git !== 'object' || Array.isArray(git))
+        return { present: true, notAMap: true };
+    const value = git[key];
+    if (value === undefined || value === null)
+        return { present: false };
+    return { present: true, value };
+}
+const BRANCH_PLACEHOLDERS = ['type', 'ticket', 'slug'];
+const BRANCH_SAMPLE = {
+    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) {
+    return pattern.replace(/\{(type|ticket|slug)\}/g, (_m, name) => BRANCH_SAMPLE[name]);
+}
+function _branchPatternReason(pattern) {
+    if (pattern === '')
+        return 'the pattern is empty';
+    const literal = pattern.replace(/\{([^{}]*)\}/g, (match, name) => {
+        return BRANCH_PLACEHOLDERS.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, value) {
+    // 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() {
+    const git = template_defaults().git ?? {};
+    const out = {};
+    for (const key of GIT_CONVENTION_KEYS) {
+        if (typeof git[key] === 'string')
+            out[key] = git[key];
+    }
+    return out;
+}
+/** The template default for a key, or null when the template sets none. */
+export function conventionDefault(key) {
+    return _defaults()[key] ?? null;
+}
+export function conventionReading(key, state, value, source, detail = null) {
+    const reason = isRefusal(state) ? `git-convention-${state}` : null;
+    return { key, value, source, state, reason, detail };
+}
+export function readGitConventionKey(key, source, defaults = _defaults()) {
+    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, defaults = _defaults()) {
+    const out = {};
+    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 = ['malformed', 'invalid', 'discarded', 'unresolvable'];
+export function isRefusal(state) {
+    return REFUSAL_STATES.includes(state);
+}
+/** One line naming the reason code, the key and the file. */
+export function describeRefusal(reading) {
+    return `${reading.reason ?? 'git-convention-ok'}: git.${reading.key} in ${reading.source ?? '(no file)'} — ${reading.detail ?? reading.state}`;
+}
+//# sourceMappingURL=git_convention.js.map