gent-cli 14.0.0 → 20.0.0

package/src/utils/attributes.js

@@ -0,0 +1,280 @@
+/**
+ * ============================================================================
+ * Attributes - gitattributes lookup and text/EOL conversion
+ * ============================================================================
+ *
+ * PURPOSE:
+ *   Decide how a path's bytes differ between the object store and the working
+ *   tree, and refuse — before writing anything — when the answer depends on a
+ *   transformation Gent does not implement.
+ *
+ * SUPPORTED:
+ *   text, -text, text=auto, eol=lf, eol=crlf, the `binary` macro,
+ *   core.autocrlf and core.eol.
+ *
+ * REFUSED (never guessed):
+ *   filter=* (including Git LFS) and working-tree-encoding. A path carrying
+ *   either raises UnsupportedFeatureError, so an operation stops before it
+ *   corrupts content by storing the wrong bytes.
+ *
+ * DIRECTION:
+ *   toIndex()    working tree -> object store ("clean")
+ *   toWorktree() object store -> working tree ("smudge")
+ *   Blobs are stored with LF line endings; CRLF is a working-tree property.
+ * ============================================================================
+ */
+
+const path = require('path');
+
+const { readFileOrNull } = require('./lockfile');
+const { IgnorePattern } = require('./ignore');
+const { UnsupportedFeatureError, feature } = require('./feature-support');
+
+/** Attributes that decide content transformation. */
+const BINARY_MACRO = { text: false, diff: false, merge: false };
+
+/**
+ * @param {Buffer} buffer
+ * @returns {Boolean} Git's heuristic: a NUL byte in the first 8000 bytes
+ */
+function looksBinary(buffer) {
+    const limit = Math.min(buffer.length, 8000);
+    return buffer.indexOf(0, 0) >= 0 && buffer.indexOf(0, 0) < limit;
+}
+
+/**
+ * One `<pattern> <attr>...` line.
+ */
+class AttributeRule {
+    /**
+     * @param {String} line
+     * @param {String} base - POSIX directory the file sits in
+     */
+    constructor(line, base) {
+        const parts = line.trim().split(/\s+/);
+        const pattern = parts.shift();
+        this.matcher = new IgnorePattern(pattern.endsWith('/') ? pattern : pattern, base);
+        this.attributes = {};
+
+        for (const token of parts) {
+            if (token.startsWith('-')) { this.attributes[token.slice(1)] = false; continue; }
+            if (token.startsWith('!')) { this.attributes[token.slice(1)] = undefined; continue; }
+            const eq = token.indexOf('=');
+            if (eq < 0) { this.attributes[token] = true; continue; }
+            this.attributes[token.slice(0, eq)] = token.slice(eq + 1);
+        }
+    }
+
+    /**
+     * @param {String} relativePath
+     * @param {Boolean} isDirectory
+     * @returns {Boolean}
+     */
+    matches(relativePath, isDirectory) {
+        return this.matcher.matches(relativePath, isDirectory);
+    }
+}
+
+/**
+ * @param {String} text
+ * @param {String} base
+ * @returns {Array<AttributeRule>}
+ */
+function parseAttributes(text, base = '') {
+    const rules = [];
+    for (const raw of text.split('\n')) {
+        const line = raw.replace(/\r$/, '').trim();
+        if (!line || line.startsWith('#')) continue;
+        rules.push(new AttributeRule(line, base));
+    }
+    return rules;
+}
+
+class AttributesMatcher {
+    /**
+     * @param {Object} repo
+     */
+    constructor(repo) {
+        this.repo = repo;
+        this.baseRules = [];
+        this.perDirectory = new Map();
+        this.loaded = false;
+
+        this.autocrlf = repo.config.get('core.autocrlf', 'false').toLowerCase();
+        this.eol = repo.config.get('core.eol', 'native').toLowerCase();
+        this.safecrlf = repo.config.get('core.safecrlf', 'false').toLowerCase();
+    }
+
+    async load() {
+        if (this.loaded) return;
+        this.loaded = true;
+
+        const infoAttributes = await readFileOrNull(path.join(this.repo.commondir, 'info', 'attributes'));
+        if (infoAttributes) this.baseRules.push(...parseAttributes(infoAttributes.toString('utf-8')));
+    }
+
+    /**
+     * @param {String} directory
+     * @returns {Promise<Array<AttributeRule>>}
+     */
+    async rulesFor(directory) {
+        if (this.perDirectory.has(directory)) return this.perDirectory.get(directory);
+
+        const filePath = path.join(this.repo.worktree, ...(directory ? directory.split('/') : []), '.gitattributes');
+        const text = await readFileOrNull(filePath);
+        const rules = text ? parseAttributes(text.toString('utf-8'), directory) : [];
+        this.perDirectory.set(directory, rules);
+        return rules;
+    }
+
+    /**
+     * @param {String} relativePath
+     * @returns {Promise<Object>} resolved attribute values
+     */
+    async attributesFor(relativePath) {
+        await this.load();
+
+        const resolved = {};
+        const apply = (rule) => {
+            if (!rule.matches(relativePath, false)) return;
+            const source = rule.attributes.binary === true ? { ...BINARY_MACRO, ...rule.attributes } : rule.attributes;
+            for (const [key, value] of Object.entries(source)) {
+                if (key === 'binary') continue;
+                resolved[key] = value;
+            }
+        };
+
+        for (const rule of this.baseRules) apply(rule);
+
+        const components = relativePath.split('/');
+        for (let depth = 0; depth < components.length; depth++) {
+            for (const rule of await this.rulesFor(components.slice(0, depth).join('/'))) apply(rule);
+        }
+        return resolved;
+    }
+
+    /**
+     * Refuse paths whose bytes depend on an unimplemented transformation.
+     * @param {String} relativePath
+     * @param {Object} attributes
+     * @param {String} what
+     */
+    assertConvertible(relativePath, attributes, what) {
+        const problems = [];
+        if (attributes.filter !== undefined && attributes.filter !== false) {
+            problems.push({
+                ...feature('attributes.filter'),
+                detail: `'${relativePath}' has filter=${attributes.filter}; its stored bytes are produced by an external program.`
+            });
+        }
+        if (attributes['working-tree-encoding'] !== undefined && attributes['working-tree-encoding'] !== false) {
+            problems.push({
+                id: 'attributes.encoding',
+                status: 'unsupported',
+                title: 'working-tree-encoding attribute',
+                detail: `'${relativePath}' declares working-tree-encoding=${attributes['working-tree-encoding']}.`,
+                remedy: 'Check this path out with Git, or remove the attribute.'
+            });
+        }
+        if (problems.length) throw new UnsupportedFeatureError(problems, what);
+    }
+
+    /**
+     * Decide whether CRLF conversion applies to a path.
+     * @param {String} relativePath
+     * @param {Buffer} sample - content used for the text=auto heuristic
+     * @returns {Promise<{convert: Boolean, worktreeEol: 'lf'|'crlf'}>}
+     */
+    async conversionFor(relativePath, sample) {
+        const attributes = await this.attributesFor(relativePath);
+        this.assertConvertible(relativePath, attributes, 'converting line endings');
+
+        let isText;
+        if (attributes.text === false) isText = false;
+        else if (attributes.text === true) isText = true;
+        else if (attributes.text === 'auto') isText = !looksBinary(sample);
+        else if (this.autocrlf === 'true' || this.autocrlf === 'input') isText = !looksBinary(sample);
+        else isText = false;
+
+        if (!isText) return { convert: false, worktreeEol: 'lf' };
+
+        let worktreeEol;
+        if (attributes.eol === 'crlf') worktreeEol = 'crlf';
+        else if (attributes.eol === 'lf') worktreeEol = 'lf';
+        else if (this.autocrlf === 'true') worktreeEol = 'crlf';
+        else if (this.autocrlf === 'input') worktreeEol = 'lf';
+        else if (this.eol === 'crlf') worktreeEol = 'crlf';
+        else if (this.eol === 'native') worktreeEol = process.platform === 'win32' ? 'crlf' : 'lf';
+        else worktreeEol = 'lf';
+
+        return { convert: true, worktreeEol };
+    }
+
+    /**
+     * Working tree bytes -> stored blob bytes.
+     * @param {String} relativePath
+     * @param {Buffer} content
+     * @returns {Promise<Buffer>}
+     */
+    async toIndex(relativePath, content) {
+        const { convert } = await this.conversionFor(relativePath, content);
+        if (!convert) return content;
+        return normalizeToLf(content);
+    }
+
+    /**
+     * Stored blob bytes -> working tree bytes.
+     * @param {String} relativePath
+     * @param {Buffer} content
+     * @returns {Promise<Buffer>}
+     */
+    async toWorktree(relativePath, content) {
+        const { convert, worktreeEol } = await this.conversionFor(relativePath, content);
+        if (!convert || worktreeEol !== 'crlf') return content;
+        return normalizeToCrlf(content);
+    }
+}
+
+/**
+ * @param {Buffer} content
+ * @returns {Buffer}
+ */
+function normalizeToLf(content) {
+    if (!content.includes(0x0d)) return content;
+
+    const out = Buffer.allocUnsafe(content.length);
+    let written = 0;
+    for (let i = 0; i < content.length; i++) {
+        if (content[i] === 0x0d && content[i + 1] === 0x0a) continue;   // drop the CR of a CRLF
+        out[written++] = content[i];
+    }
+    return out.subarray(0, written);
+}
+
+/**
+ * @param {Buffer} content
+ * @returns {Buffer}
+ */
+function normalizeToCrlf(content) {
+    const lf = normalizeToLf(content);
+    let count = 0;
+    for (let i = 0; i < lf.length; i++) if (lf[i] === 0x0a) count++;
+    if (count === 0) return lf;
+
+    const out = Buffer.allocUnsafe(lf.length + count);
+    let written = 0;
+    for (let i = 0; i < lf.length; i++) {
+        if (lf[i] === 0x0a) out[written++] = 0x0d;
+        out[written++] = lf[i];
+    }
+    return out;
+}
+
+module.exports = {
+    AttributesMatcher,
+    AttributeRule,
+    parseAttributes,
+    looksBinary,
+    normalizeToLf,
+    normalizeToCrlf
+};

package/src/utils/canonical-journal.js

@@ -0,0 +1,122 @@
+/** Exact local checkpoints for canonical undo/redo. Private refs retain every
+ * object needed by a checkpoint when external Git runs garbage collection.
+ */
+const fs = require('fs').promises;
+const path = require('path');
+const crypto = require('crypto');
+const { GitIndex, IndexEntry } = require('./git-index');
+const { IgnoreMatcher, walkWorktree } = require('./ignore');
+const { serializeCommit, serializeTree, MODE } = require('./git-objects');
+const { writeAtomic, readFileOrNull } = require('./lockfile');
+const worktree = require('./worktree');
+
+const journalPath = repo => path.join(repo.gentWorktreeMetaDir, 'journal.json');
+async function read(repo) {
+    const bytes = await readFileOrNull(journalPath(repo));
+    return bytes ? JSON.parse(bytes.toString()) : { undo: [], redo: [] };
+}
+async function save(repo, journal) { await writeAtomic(journalPath(repo), JSON.stringify(journal)); }
+
+async function capture(repo) {
+    const index = await GitIndex.read(repo.indexPath);
+    const files = {};
+    const matcher = new IgnoreMatcher(repo);
+    const names = new Set(index.entries.map(e => e.path));
+    for await (const entry of walkWorktree(repo, matcher, { tracked: names })) names.add(entry.path);
+    for (const name of [...names].sort()) {
+        const file = await worktree.snapshotPath(repo, name);
+        if (file) files[name] = { mode: file.mode, oid: await repo.objects.write('blob', Buffer.from(file.content, 'base64')) };
+    }
+    const refs = Object.fromEntries([...(await repo.refs.list())].filter(([name]) => !name.startsWith('refs/gent/')).sort(([a], [b]) => a.localeCompare(b)));
+    const merge = {};
+    for (const name of ['MERGE_HEAD', 'MERGE_MSG', 'MERGE_MODE', 'ORIG_HEAD']) merge[name] = (await readFileOrNull(repo.gitPath(name)))?.toString('base64') ?? null;
+    return { head: await repo.refs.head(), refs, index: index.sourceBytes?.toString('base64') ?? null, files, merge };
+}
+
+async function retain(repo, state, prefix) {
+    const entries = [];
+    // These are retention objects, not worktree trees. Numeric names allow
+    // conflicted index stages and staged/unstaged versions to coexist.
+    for (const item of Object.values(state.files)) entries.push({ name: String(entries.length), mode: MODE.REGULAR, oid: item.oid });
+    if (state.index) {
+        for (const item of GitIndex.parse(Buffer.from(state.index, 'base64')).entries) {
+            if (item.mode === MODE.GITLINK) throw new Error('journal checkpoints do not support submodules');
+            entries.push({ name: String(entries.length), mode: MODE.REGULAR, oid: item.oid });
+        }
+    }
+    const tree = await repo.objects.write('tree', serializeTree(entries));
+    const identity = { name: 'Gent checkpoint', email: 'checkpoint@gent.local', timestamp: Math.floor(Date.now() / 1000), timezone: '+0000' };
+    const oid = await repo.objects.write('commit', serializeCommit({ tree, parents: state.head.oid ? [state.head.oid] : [], author: identity, committer: identity, message: Buffer.from('Gent undo checkpoint\n') }));
+    await repo.refs.update(`${prefix}/snapshot`, oid, { expectedOldOid: null, reason: 'retain undo checkpoint' });
+    let n = 0;
+    for (const target of new Set(Object.values(state.refs))) await repo.refs.update(`${prefix}/ref-${n++}`, target, { expectedOldOid: null, reason: 'retain undo ref' });
+}
+
+async function begin(repo, name) {
+    const before = await capture(repo);
+    const id = crypto.randomUUID();
+    await retain(repo, before, `refs/gent/journal/${id}/before`);
+    return { id, name, before };
+}
+
+async function finish(repo, entry) {
+    entry.after = await capture(repo);
+    await retain(repo, entry.after, `refs/gent/journal/${entry.id}/after`);
+    const journal = await read(repo);
+    journal.undo.push(entry);
+    journal.redo = [];
+    await save(repo, journal);
+}
+
+function sameState(a, b) {
+    // Index stat refreshes by other tools are harmless. Compare staged content
+    // and flags, not filesystem cache timestamps.
+    const semantic = state => {
+        const entries = state.index ? GitIndex.parse(Buffer.from(state.index, 'base64')).entries : [];
+        return { ...state, index: entries.map(e => ({ path: e.path, oid: e.oid, mode: e.mode, stage: e.stage, assumeValid: e.assumeValid, skipWorktree: e.skipWorktree, intentToAdd: e.intentToAdd })) };
+    };
+    return JSON.stringify(semantic(a)) === JSON.stringify(semantic(b));
+}
+
+async function restore(repo, redo = false) {
+    await worktree.assertNoPendingCheckout(repo, 'undo/redo');
+    const journal = await read(repo);
+    const source = redo ? journal.redo : journal.undo;
+    const entry = source[source.length - 1];
+    if (!entry) throw new Error(`nothing to ${redo ? 'redo' : 'undo'}`);
+    const expected = redo ? entry.before : entry.after;
+    const target = redo ? entry.after : entry.before;
+    const current = await capture(repo);
+    if (!sameState(current, expected)) throw new Error('repository changed since the recorded operation; refusing to overwrite intervening work');
+    const index = await GitIndex.read(repo.indexPath);
+    const targetIndex = target.index ? GitIndex.parse(Buffer.from(target.index, 'base64')) : new GitIndex();
+    const from = new Map(Object.entries(current.files));
+    const to = new Map(Object.entries(target.files));
+    const plan = await worktree.planCheckout(repo, { from, to, index, force: true });
+    // Snapshots store exact working bytes, so EOL conversion must not run twice.
+    for (const write of plan.writes) write.content = (await repo.objects.readBlob(write.oid)).toString('base64');
+    await worktree.applyCheckout(repo, plan, { index });
+    index.entries = targetIndex.entries;
+    index.extensions.clear();
+    await index.write(repo.indexPath);
+    for (const name of new Set([...Object.keys(current.refs), ...Object.keys(target.refs)])) {
+        if (current.refs[name] === target.refs[name]) continue;
+        if (target.refs[name]) await repo.refs.update(name, target.refs[name], { expectedOldOid: current.refs[name] || null, reason: redo ? 'redo' : 'undo' });
+        else await repo.refs.delete(name, { expectedOldOid: current.refs[name], reason: redo ? 'redo' : 'undo' });
+    }
+    // A branch ref may already have moved above; HEAD's expected oid follows it.
+    const expectedHead = { ...current.head, oid: current.head.ref ? (target.refs[current.head.ref] || null) : current.head.oid };
+    if (target.head.ref) await repo.refs.setHeadSymbolic(target.head.ref, redo ? 'redo' : 'undo', expectedHead);
+    else await repo.refs.setHeadDetached(target.head.oid, redo ? 'redo' : 'undo', expectedHead);
+    for (const [name, bytes] of Object.entries(target.merge)) {
+        if (bytes === null) await fs.rm(repo.gitPath(name), { force: true });
+        else await writeAtomic(repo.gitPath(name), Buffer.from(bytes, 'base64'));
+    }
+    source.pop();
+    (redo ? journal.undo : journal.redo).push(entry);
+    await save(repo, journal);
+    await worktree.completeCheckout(repo);
+    return entry.name;
+}
+
+module.exports = { begin, finish, restore, read };

package/src/utils/feature-support.js

@@ -0,0 +1,92 @@
+/**
+ * ============================================================================
+ * Feature Support Manifest
+ * ============================================================================
+ *
+ * PURPOSE:
+ *   One declaration of what Gent v13 supports, consumed by repository opening,
+ *   command preflight, the generated documentation and the test suites. The
+ *   data lives in feature-support.json so the Django API can load the exact
+ *   same bytes when server integration is implemented.
+ *
+ * RULE:
+ *   Nothing may claim support for a feature this manifest does not mark
+ *   'supported'. Detection happens *before* any state is modified, so an
+ *   unsupported repository is refused rather than half-converted.
+ *
+ * ============================================================================
+ */
+
+const manifest = require('./feature-support.json');
+
+const BY_ID = new Map(manifest.features.map(f => [f.id, f]));
+
+/**
+ * Raised when a repository or request needs something Gent does not implement.
+ * Carries the manifest entries so callers can render a consistent message.
+ */
+class UnsupportedFeatureError extends Error {
+    /**
+     * @param {Array<{id: String, title: String, detail: String, remedy?: String}>} features
+     * @param {String} [context] - what was being attempted
+     */
+    constructor(features, context) {
+        const list = features.map(f => `  - ${f.title}: ${f.detail}${f.remedy ? `\n    Fix: ${f.remedy}` : ''}`).join('\n');
+        super(`${context ? `${context}: ` : ''}unsupported repository feature\n${list}`);
+        this.name = 'UnsupportedFeatureError';
+        this.code = 'GENT_UNSUPPORTED';
+        this.features = features;
+        this.context = context || null;
+    }
+}
+
+/**
+ * Look up a manifest entry.
+ * @param {String} id
+ * @returns {Object}
+ */
+function feature(id) {
+    const f = BY_ID.get(id);
+    if (!f) throw new Error(`Unknown feature id '${id}' — add it to feature-support.json`);
+    return f;
+}
+
+/**
+ * @param {String} id
+ * @returns {Boolean}
+ */
+function isSupported(id) {
+    const status = feature(id).status;
+    return status === 'supported' || status === 'partial';
+}
+
+/**
+ * Throw if any of the given feature ids is not implemented.
+ * @param {Array<String>} ids
+ * @param {String} [context]
+ */
+function assertSupported(ids, context) {
+    const bad = ids.filter(id => feature(id).status === 'unsupported').map(feature);
+    if (bad.length) throw new UnsupportedFeatureError(bad, context);
+}
+
+/**
+ * All features in a given status, for documentation and status output.
+ * @param {String} status
+ * @returns {Array<Object>}
+ */
+function byStatus(status) {
+    return manifest.features.filter(f => f.status === status);
+}
+
+module.exports = {
+    manifest,
+    FORMAT_MARKER: manifest.formatMarker,
+    OBJECT_FORMAT: manifest.objectFormat,
+    REPOSITORY_FORMAT_VERSION: manifest.repositoryFormatVersion,
+    UnsupportedFeatureError,
+    feature,
+    isSupported,
+    assertSupported,
+    byStatus
+};