@opentermsarchive/engine 16.0.1 → 16.1.0

package/src/archivist/tracking-results/terms-result/index.test.js

@@ -0,0 +1,228 @@
+import { expect } from 'chai';
+
+import TermsResult from './index.js';
+
+const VALID_PARAMS = {
+  serviceId: 'Google',
+  termsType: 'Terms of Service',
+  status: 'ok',
+  event: {
+    date: '2026-01-10T10:30:00Z',
+    serviceName: 'Google',
+    sourceDocuments: [{
+      id: 'terms',
+      fetch: 'https://policies.google.com/terms',
+      select: '.content',
+      remove: '.banner',
+      filter: ['removeLinks'],
+      executeClientScripts: false,
+      mimeType: 'text/html',
+      snapshotId: 'def456',
+    }],
+  },
+};
+
+describe('TermsResult', () => {
+  let subject;
+
+  describe('#constructor', () => {
+    it('normalises params to their JSON round-trip, dropping undefined-valued keys', () => {
+      subject = new TermsResult({
+        ...VALID_PARAMS,
+        event: {
+          ...VALID_PARAMS.event,
+          sourceDocuments: [{
+            id: 'terms',
+            fetch: 'https://policies.google.com/terms',
+            select: '.content',
+            remove: undefined,
+            filter: undefined,
+          }],
+        },
+      });
+
+      expect(subject.event.sourceDocuments[0]).to.deep.equal({
+        id: 'terms',
+        fetch: 'https://policies.google.com/terms',
+        select: '.content',
+      });
+      expect(subject.event.sourceDocuments[0]).to.not.have.property('remove');
+      expect(subject.event.sourceDocuments[0]).to.not.have.property('filter');
+    });
+  });
+
+  describe('#validate', () => {
+    context('when all required params are present', () => {
+      it('does not throw', () => {
+        subject = new TermsResult(VALID_PARAMS);
+        expect(subject.validate.bind(subject)).to.not.throw();
+      });
+    });
+
+    [ 'serviceId', 'termsType', 'status', 'event' ].forEach(requiredParam => {
+      describe(`"${requiredParam}"`, () => {
+        context('when missing', () => {
+          it('throws an error', () => {
+            const params = { ...VALID_PARAMS };
+
+            delete params[requiredParam];
+            subject = new TermsResult(params);
+            expect(subject.validate.bind(subject)).to.throw(RegExp(requiredParam));
+          });
+        });
+
+        context('when null', () => {
+          it('throws an error', () => {
+            subject = new TermsResult({ ...VALID_PARAMS, [requiredParam]: null });
+            expect(subject.validate.bind(subject)).to.throw(RegExp(requiredParam));
+          });
+        });
+      });
+    });
+
+    describe('"status"', () => {
+      context('when not a valid value', () => {
+        it('throws an error', () => {
+          subject = new TermsResult({ ...VALID_PARAMS, status: 'unknown' });
+          expect(subject.validate.bind(subject)).to.throw(/status/);
+        });
+      });
+
+      [ 'ok', 'failed' ].forEach(validStatus => {
+        context(`when set to "${validStatus}"`, () => {
+          it('does not throw', () => {
+            const params = { ...VALID_PARAMS, status: validStatus };
+
+            if (validStatus === 'failed') {
+              params.event = { ...VALID_PARAMS.event, reasons: ['[fetch] HTTP code 503'] };
+            }
+
+            subject = new TermsResult(params);
+            expect(subject.validate.bind(subject)).to.not.throw();
+          });
+        });
+      });
+    });
+
+    describe('"event.date"', () => {
+      context('when missing', () => {
+        it('throws an error', () => {
+          subject = new TermsResult({ ...VALID_PARAMS, event: { ...VALID_PARAMS.event, date: undefined } });
+          expect(subject.validate.bind(subject)).to.throw(/event\.date/);
+        });
+      });
+    });
+
+    describe('"event.serviceName"', () => {
+      context('when missing', () => {
+        it('throws an error', () => {
+          subject = new TermsResult({ ...VALID_PARAMS, event: { ...VALID_PARAMS.event, serviceName: undefined } });
+          expect(subject.validate.bind(subject)).to.throw(/event\.serviceName/);
+        });
+      });
+    });
+
+    describe('"event.sourceDocuments"', () => {
+      context('when not an array', () => {
+        it('throws an error', () => {
+          subject = new TermsResult({ ...VALID_PARAMS, event: { ...VALID_PARAMS.event, sourceDocuments: 'not-an-array' } });
+          expect(subject.validate.bind(subject)).to.throw(/event\.sourceDocuments/);
+        });
+      });
+    });
+
+    describe('"event.reasons" when status is "failed"', () => {
+      context('when missing', () => {
+        it('throws an error', () => {
+          subject = new TermsResult({ ...VALID_PARAMS, status: 'failed' });
+          expect(subject.validate.bind(subject)).to.throw(/event\.reasons/);
+        });
+      });
+
+      context('when empty', () => {
+        it('throws an error', () => {
+          subject = new TermsResult({ ...VALID_PARAMS, status: 'failed', event: { ...VALID_PARAMS.event, reasons: [] } });
+          expect(subject.validate.bind(subject)).to.throw(/event\.reasons/);
+        });
+      });
+
+      context('when non-empty', () => {
+        it('does not throw', () => {
+          subject = new TermsResult({
+            ...VALID_PARAMS,
+            status: 'failed',
+            event: { ...VALID_PARAMS.event, reasons: ['[fetch] HTTP code 503'] },
+          });
+          expect(subject.validate.bind(subject)).to.not.throw();
+        });
+      });
+    });
+
+    describe('"event.transientError"', () => {
+      context('when present but reasons is empty', () => {
+        it('throws an error', () => {
+          subject = new TermsResult({
+            ...VALID_PARAMS,
+            event: { ...VALID_PARAMS.event, transientError: { reasons: [] } },
+          });
+          expect(subject.validate.bind(subject)).to.throw(/transientError/);
+        });
+      });
+
+      context('when present but reasons is missing (non-object with a truthy value)', () => {
+        it('throws an error', () => {
+          subject = new TermsResult({
+            ...VALID_PARAMS,
+            event: { ...VALID_PARAMS.event, transientError: 'not-an-object' }, // Scalar truthy value has no .reasons array
+          });
+          expect(subject.validate.bind(subject)).to.throw(/transientError/);
+        });
+      });
+
+      context('when present but reasons is not an array', () => {
+        it('throws an error', () => {
+          subject = new TermsResult({
+            ...VALID_PARAMS,
+            event: { ...VALID_PARAMS.event, transientError: { reasons: 'a-string' } },
+          });
+          expect(subject.validate.bind(subject)).to.throw(/transientError/);
+        });
+      });
+
+      context('when present with non-empty reasons', () => {
+        it('does not throw', () => {
+          subject = new TermsResult({
+            ...VALID_PARAMS,
+            event: { ...VALID_PARAMS.event, transientError: { reasons: ['[fetch] HTTP code 503'] } },
+          });
+          expect(subject.validate.bind(subject)).to.not.throw();
+        });
+      });
+    });
+
+    describe('"status"', () => {
+      context('when the value is the right type but wrong case ("OK" instead of "ok")', () => {
+        it('throws an error', () => {
+          subject = new TermsResult({ ...VALID_PARAMS, status: 'OK' });
+          expect(subject.validate.bind(subject)).to.throw(/status/);
+        });
+      });
+    });
+
+    describe('"event.sourceDocuments"', () => {
+      context('when null', () => {
+        it('throws an error', () => {
+          subject = new TermsResult({ ...VALID_PARAMS, event: { ...VALID_PARAMS.event, sourceDocuments: null } });
+          expect(subject.validate.bind(subject)).to.throw(/event\.sourceDocuments/);
+        });
+      });
+
+      context('when an empty array', () => {
+        it('does not throw', () => {
+          subject = new TermsResult({ ...VALID_PARAMS, event: { ...VALID_PARAMS.event, sourceDocuments: [] } });
+          expect(subject.validate.bind(subject)).to.not.throw();
+        });
+      });
+    });
+  });
+});

package/src/collection-api/routes/index.js

@@ -39,8 +39,8 @@ export default async function apiRouter(basePath) {
   const services = await Services.load();
   const collection = await getCollection();
   const versionsStorageConfig = config.get('@opentermsarchive/engine.recorder.versions.storage');
-  const versionsRepository = await RepositoryFactory.create(versionsStorageConfig).initialize();
-  const snapshotsRepository = await RepositoryFactory.create(config.get('@opentermsarchive/engine.recorder.snapshots.storage')).initialize();
+  const versionsRepository = await RepositoryFactory.create(versionsStorageConfig, { readOnly: true }).initialize(); // The API only reads the repositories the tracker writes to
+  const snapshotsRepository = await RepositoryFactory.create(config.get('@opentermsarchive/engine.recorder.snapshots.storage'), { readOnly: true }).initialize();
   const feedConfig = config.get('@opentermsarchive/engine.collection-api.feed');
   const datasetStorage = new DatasetStorage(config.get('@opentermsarchive/engine.dataset.storagePath'));
 

package/src/git/errors.js

@@ -0,0 +1 @@
+export class GitObjectNotFoundError extends Error {} // The requested commit, tree or file cannot be resolved in the repository (unknown SHA, shallow clone, rewritten history, file absent from the commit)

package/src/{archivist/recorder/repositories/git/git.js → git/index.js}

@@ -3,13 +3,42 @@ import path from 'path';
 
 import simpleGit from 'simple-git';
 
+import { GitObjectNotFoundError } from './errors.js';
 import { parseTrailers, formatTrailers } from './trailers.js';
 
+export { GitObjectNotFoundError } from './errors.js';
+
 process.env.LC_ALL = 'en_GB'; // Ensure git messages will be in English as some errors are handled by analysing the message content
 
 const fs = fsApi.promises;
 
+const OBJECT_NOT_FOUND_MESSAGES = /bad object|not a tree|invalid object name|unknown revision|does not exist|exists on disk, but not in/i;
+
 export default class Git {
+  static async getHeadSha(repositoryPath) { // Used by callers that need to capture the current state of a repository without instantiating a full Git wrapper (which would mutate the repo via `init`).
+    try {
+      const git = simpleGit(repositoryPath, { trimmed: true });
+
+      return await git.revparse(['HEAD']);
+    } catch (error) {
+      if (/not a git repository|does not exist|unknown revision|ambiguous argument|does not have any commits/i.test(error.message)) {
+        return null; // Not a repository, or an empty one: a legitimate "no commit to reference" answer
+      }
+
+      throw error; // An actual git failure, which callers must not conflate with the absence of a repository
+    }
+  }
+
+  static async listFilesAtCommit(repositoryPath, commit) {
+    const output = await readObjectAtCommit(repositoryPath, [ 'ls-tree', '--name-only', commit, '--', './' ]); // `repositoryPath` may be a subdirectory of the repository; git resolves the `./` pathspec against its cwd.
+
+    return output ? output.split('\n') : [];
+  }
+
+  static readFileAtCommit(repositoryPath, commit, fileName) { // Returns the content of `fileName` (relative to `repositoryPath`) at the given commit
+    return readObjectAtCommit(repositoryPath, [ 'show', `${commit}:./${fileName}` ]); // The `rev:./path` syntax makes git resolve the path against its cwd, which supports repositoryPath being a subdirectory of the repository
+  }
+
   constructor({ path: repositoryPath, author }) {
     this.path = repositoryPath;
     this.author = author;
@@ -17,30 +46,50 @@ export default class Git {
 
   async initialize() {
     if (!fsApi.existsSync(this.path)) {
-      await fs.mkdir(this.path, { recursive: true });
+      await fs.mkdir(this.path, { recursive: true }); // simple-git cannot be instantiated on a missing directory
+    }
+
+    this.#connect();
+    await this.git.init();
+
+    const configFile = path.resolve(this.path, '.git', 'config'); // Anchored to an absolute path: git resolves a relative `--file` argument against its own cwd (the repository), not against process.cwd, so a relative repository path would silently point the write at a nonexistent nested location
+
+    if (!fsApi.existsSync(configFile)) { // Defensive: init should always produce this file; if it does not, refuse to continue rather than risk writing config to an unintended location
+      throw new Error(`Git initialisation failed: expected config file at ${configFile} was not created`);
     }
 
+    // Each setting is written to the explicit config file path rather than via `addConfig` so neither simpleGit nor git itself can walk up to a parent .git and pollute the configuration of an enclosing project (e.g. the engine's own checkout when this.path is `./data/versions`).
+    return this.git
+      .raw([ 'config', '--file', configFile, 'core.autocrlf', 'false' ])
+      .raw([ 'config', '--file', configFile, 'push.default', 'current' ])
+      .raw([ 'config', '--file', configFile, 'user.name', this.author.name ])
+      .raw([ 'config', '--file', configFile, 'user.email', this.author.email ])
+      .raw([ 'config', '--file', configFile, 'core.quotePath', 'false' ]) // Disable Git's encoding of special characters in pathnames. For example, `service·A` will be encoded as `service\302\267A` without this setting, leading to issues. See https://git-scm.com/docs/git-config#Documentation/git-config.txt-corequotePath
+      .raw([ 'config', '--file', configFile, 'core.commitGraph', 'true' ]) // Enable `commit-graph` feature for efficient commit data storage, improving performance of operations like `git log`
+      .raw([ 'config', '--file', configFile, 'gc.writeCommitGraph', 'false' ]); // Prevent automatic `git gc` from also writing the commit-graph: the engine writes it explicitly (see `writeCommitGraph`/`updateCommitGraph`), and a concurrent gc write races those, which can leave a stale `commit-graph.lock` and make subsequent operations fail
+  }
+
+  open() {
+    if (!fsApi.existsSync(path.join(this.path, '.git'))) {
+      throw new Error(`Repository ${this.path} does not exist, it has to be created by a writer such as the tracker first`); // Without this check, git would silently walk up to an enclosing repository, such as the collection one
+    }
+
+    this.#connect();
+  }
+
+  #connect() {
     this.git = simpleGit(this.path, {
       trimmed: true,
       maxConcurrentProcesses: 1, // Concurrent runs on the same repository race the index and the commit-graph and can corrupt them
     });
-
-    await this.git.init();
-
-    return this.git
-      .addConfig('core.autocrlf', false)
-      .addConfig('push.default', 'current')
-      .addConfig('user.name', this.author.name)
-      .addConfig('user.email', this.author.email)
-      .addConfig('core.quotePath', false) // Disable Git's encoding of special characters in pathnames. For example, `service·A` will be encoded as `service\302\267A` without this setting, leading to issues. See https://git-scm.com/docs/git-config#Documentation/git-config.txt-corequotePath
-      .addConfig('core.commitGraph', true) // Enable `commit-graph` feature for efficient commit data storage, improving performance of operations like `git log`
-      .addConfig('gc.writeCommitGraph', false); // Prevent automatic `git gc` from also writing the commit-graph: the engine writes it explicitly (see `writeCommitGraph`/`updateCommitGraph`), and a concurrent gc write races those, which can leave a stale `commit-graph.lock` and make subsequent operations fail
   }
 
   add(filePath) {
     return this.git.add(this.relativePath(filePath));
   }
 
+  // Not safe to call concurrently: GIT_AUTHOR_DATE / GIT_COMMITTER_DATE are process-wide env vars, so two overlapping calls can stamp each other's commits.
+  // simple-git's `maxConcurrentProcesses: 1` serializes child processes but not the env-var mutation that precedes them. Callers must await each commit before issuing the next.
   async commit({ filePath, message, date = new Date(), trailers = {} }) {
     const commitDate = new Date(date).toISOString();
     let summary;
@@ -52,7 +101,7 @@ export default class Git {
       const trailersSection = formatTrailers(trailers);
       const finalMessage = trailersSection ? `${message}\n\n${trailersSection}` : message;
 
-      summary = await this.git.commit(finalMessage, filePath, ['--no-verify']); // Skip pre-commit and commit-msg hooks, as commits are programmatically managed, to optimize performance
+      summary = await this.git.commit(finalMessage, filePath ? this.relativePath(filePath) : [], ['--no-verify']); // Skip pre-commit and commit-msg hooks, as commits are programmatically managed, to optimize performance. The pathspec must be expressed relative to the repository root; passing the absolute or process-cwd-relative path causes git to look for it under the repo's working directory, which fails when the repo's own path components appear in the resolved location. Without a file path, the whole index is committed
     } finally {
       process.env.GIT_AUTHOR_DATE = '';
       process.env.GIT_COMMITTER_DATE = '';
@@ -77,7 +126,7 @@ export default class Git {
     return this.log([
       ...reverseOption, // When `reverse` is true, lists commits oldest-first; otherwise the default newest-first applies
       '--author-date-order', // Best-effort author-date ordering: with --max-count, git applies the cap topologically, so the page can miss strictly-newer commits that #getCommits' JS resort cannot recover
-      '--no-merges', // Exclude merge commits — records are stored as regular commits, never as merges
+      '--no-merges', // Exclude merge commits; records are stored as regular commits, never as merges
       '--name-only', // Append the modified file names below each commit, used by `toDomain` to extract the record's file path
       ...skipOption, // Optional `--skip=N`: drop the first N matching commits (pagination offset)
       ...maxCountOption, // Optional `--max-count=N`: cap the result to N commits (pagination limit)
@@ -129,6 +178,10 @@ export default class Git {
     return this.git.show(options);
   }
 
+  showBuffer(options) {
+    return this.git.showBuffer(options);
+  }
+
   async cleanUp() {
     await fs.rm(path.join(this.path, '.git', 'objects', 'info', 'commit-graph.lock'), { force: true }); // Remove a leftover commit-graph lock from a previous `commit-graph write` that was killed mid-write (e.g. the process was terminated during a deploy or restart). The commit-graph is a disposable cache rebuilt by `writeCommitGraph`, so clearing a stale lock is safe and prevents every subsequent run from failing.
     await this.git.reset('hard');
@@ -144,15 +197,6 @@ export default class Git {
     ]);
   }
 
-  restore(path, commit) {
-    return this.git.raw([
-      'restore',
-      '-s', commit, // Take the file contents from this specific commit rather than from the index
-      '--', // Everything after is a pathspec, not a revision or option
-      path,
-    ]);
-  }
-
   async destroyHistory() {
     await fs.rm(this.path, { recursive: true });
 
@@ -247,3 +291,15 @@ export default class Git {
     return { additions, deletions };
   }
 }
+
+async function readObjectAtCommit(repositoryPath, args) {
+  try {
+    return await simpleGit(repositoryPath, { trimmed: true, config: ['core.quotePath=false'] }).raw(args); // Disable pathname quoting for the same reason Git.initialize sets it on managed repositories: names with special characters (e.g. "service·A") must come back verbatim, and this repository's configuration is not under the engine's control
+  } catch (error) {
+    if (OBJECT_NOT_FOUND_MESSAGES.test(error.message)) {
+      throw new GitObjectNotFoundError(error.message); // Typed so callers can distinguish "this commit or file cannot be resolved, ever" from a transient git failure worth retrying
+    }
+
+    throw error;
+  }
+}

package/src/git/index.test.js

@@ -0,0 +1,266 @@
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { expect } from 'chai';
+import config from 'config';
+
+import Git, { GitObjectNotFoundError } from './index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RECORDER_PATH = path.resolve(__dirname, '../../', config.get('@opentermsarchive/engine.recorder.versions.storage.git.path'));
+
+describe('Git', () => {
+  const DEFAULT_CONTENT = 'default content';
+  const DEFAULT_COMMIT_MESSAGE = 'default commit message';
+  let subject;
+
+  before(() => {
+    subject = new Git({
+      path: RECORDER_PATH,
+      author: {
+        name: config.get('@opentermsarchive/engine.recorder.versions.storage.git.author.name'),
+        email: config.get('@opentermsarchive/engine.recorder.versions.storage.git.author.email'),
+      },
+    });
+
+    return subject.initialize();
+  });
+
+  describe('#commit', () => {
+    const expectedFilePath = `${RECORDER_PATH}/test.md`;
+
+    let commitId;
+
+    before(async () => {
+      await fs.writeFile(expectedFilePath, DEFAULT_CONTENT);
+
+      await subject.add(expectedFilePath);
+      commitId = await subject.commit({ filePath: expectedFilePath, message: DEFAULT_COMMIT_MESSAGE });
+    });
+
+    after(() => subject.destroyHistory());
+
+    it('returns a full length SHA1 commit ID', () => {
+      expect(commitId).to.match(/\b[0-9a-f]{40}\b/);
+    });
+
+    context('when stage area is dirty', () => {
+      const expectedFileName = 'file-to-commit.md';
+      const expectedFilePath = `${RECORDER_PATH}/${expectedFileName}`;
+      const unwantedFilePath = `${RECORDER_PATH}/unwanted-file.md`;
+      let commit;
+      let committedFiles;
+      let committedFileName;
+
+      before(async () => {
+        await fs.writeFile(expectedFilePath, DEFAULT_CONTENT);
+        await fs.writeFile(unwantedFilePath, DEFAULT_CONTENT);
+
+        await subject.add(expectedFilePath);
+        await subject.add(unwantedFilePath);
+
+        const commitId = await subject.commit({ filePath: expectedFilePath, message: DEFAULT_COMMIT_MESSAGE });
+
+        commit = await subject.getCommit([commitId]);
+
+        if (!commit) {
+          return;
+        }
+
+        ({ files: committedFiles } = commit.diff);
+        ([{ file: committedFileName }] = committedFiles);
+      });
+
+      after(() => subject.destroyHistory());
+
+      it('commits the specified file', () => {
+        expect(committedFileName).to.equal(expectedFileName);
+      });
+
+      it('commits only one file', () => {
+        expect(committedFiles).to.have.lengthOf(1);
+      });
+    });
+
+    context('when no file path is given', () => {
+      const stagedFileNames = [ 'first-staged-file.md', 'second-staged-file.md' ];
+      let committedFileNames;
+
+      before(async () => {
+        for (const fileName of stagedFileNames) {
+          const filePath = `${RECORDER_PATH}/${fileName}`;
+
+          await fs.writeFile(filePath, DEFAULT_CONTENT);
+          await subject.add(filePath);
+        }
+
+        const commitId = await subject.commit({ message: DEFAULT_COMMIT_MESSAGE });
+        const commit = await subject.getCommit([commitId]);
+
+        committedFileNames = commit.diff.files.map(({ file }) => file);
+      });
+
+      after(() => subject.destroyHistory());
+
+      it('commits all the staged files', () => {
+        expect(committedFileNames).to.have.members(stagedFileNames);
+      });
+    });
+  });
+
+  describe('#cleanUp', () => {
+    context('when a commit-graph lock has been left behind by an interrupted process', () => {
+      const infoDirectoryPath = path.join(RECORDER_PATH, '.git', 'objects', 'info');
+      const lockFilePath = path.join(infoDirectoryPath, 'commit-graph.lock');
+
+      before(async () => {
+        const filePath = `${RECORDER_PATH}/file-to-clean.md`;
+
+        await fs.writeFile(filePath, DEFAULT_CONTENT);
+        await subject.add(filePath);
+        await subject.commit({ filePath, message: DEFAULT_COMMIT_MESSAGE });
+
+        await fs.mkdir(infoDirectoryPath, { recursive: true });
+        await fs.writeFile(lockFilePath, '');
+
+        await subject.cleanUp();
+      });
+
+      after(() => subject.destroyHistory());
+
+      it('removes the stale commit-graph lock', async () => {
+        const infoDirectoryContent = await fs.readdir(infoDirectoryPath);
+
+        expect(infoDirectoryContent).to.not.include('commit-graph.lock');
+      });
+    });
+  });
+
+  describe('.getHeadSha', () => {
+    context('with a directory that does not exist', () => {
+      it('returns null', async () => {
+        expect(await Git.getHeadSha(path.join(os.tmpdir(), 'ota-nonexistent-directory'))).to.be.null;
+      });
+    });
+
+    context('with a directory that is not inside a Git repository', () => {
+      let directory;
+
+      before(async () => {
+        directory = await fs.mkdtemp(path.join(os.tmpdir(), 'ota-git-test-')); // Under the OS temp directory, so no enclosing Git repository can be found by walking up
+      });
+
+      after(() => fs.rm(directory, { recursive: true, force: true }));
+
+      it('returns null', async () => {
+        expect(await Git.getHeadSha(directory)).to.be.null;
+      });
+    });
+
+    context('with a repository that has no commits yet', () => {
+      let directory;
+
+      before(async () => {
+        directory = await fs.mkdtemp(path.join(os.tmpdir(), 'ota-git-test-'));
+        await new Git({ path: directory, author: { name: 'Test', email: 'test@example.com' } }).initialize();
+      });
+
+      after(() => fs.rm(directory, { recursive: true, force: true }));
+
+      it('returns null', async () => {
+        expect(await Git.getHeadSha(directory)).to.be.null;
+      });
+    });
+
+    context('with a repository that has commits', () => {
+      let commitId;
+
+      before(async () => {
+        const filePath = `${RECORDER_PATH}/test.md`;
+
+        await fs.writeFile(filePath, DEFAULT_CONTENT);
+        await subject.add(filePath);
+        commitId = await subject.commit({ filePath, message: DEFAULT_COMMIT_MESSAGE });
+      });
+
+      after(() => subject.destroyHistory());
+
+      it('returns the SHA of HEAD', async () => {
+        expect(await Git.getHeadSha(RECORDER_PATH)).to.equal(commitId);
+      });
+    });
+  });
+
+  describe('reading at a specific commit', () => {
+    let repositoryPath;
+    let subdirectoryPath;
+    let firstCommitSha;
+    let secondCommitSha;
+
+    before(async () => {
+      repositoryPath = await fs.mkdtemp(path.join(os.tmpdir(), 'ota-git-test-')); // Under the OS temp directory so the fixture repository is not nested in the engine's own repository
+      subdirectoryPath = path.join(repositoryPath, 'declarations');
+      await fs.mkdir(subdirectoryPath);
+
+      const git = new Git({ path: repositoryPath, author: { name: 'Test', email: 'test@example.com' } });
+
+      await git.initialize();
+
+      const firstFilePath = path.join(subdirectoryPath, 'Service A.json');
+
+      await fs.writeFile(firstFilePath, '{ "name": "Service A" }');
+      await git.add(firstFilePath);
+      firstCommitSha = await git.commit({ filePath: firstFilePath, message: 'Add Service A' });
+
+      const secondFilePath = path.join(subdirectoryPath, 'Service B.json');
+
+      await fs.writeFile(secondFilePath, '{ "name": "Service B" }');
+      await git.add(secondFilePath);
+      secondCommitSha = await git.commit({ filePath: secondFilePath, message: 'Add Service B' });
+    });
+
+    after(() => fs.rm(repositoryPath, { recursive: true, force: true }));
+
+    describe('.listFilesAtCommit', () => {
+      it('lists the files of the subdirectory as they were at the given commit', async () => {
+        expect(await Git.listFilesAtCommit(subdirectoryPath, firstCommitSha)).to.deep.equal(['Service A.json']);
+      });
+
+      it('reflects later commits when given their SHA', async () => {
+        expect(await Git.listFilesAtCommit(subdirectoryPath, secondCommitSha)).to.deep.equal([ 'Service A.json', 'Service B.json' ]);
+      });
+
+      it('throws a GitObjectNotFoundError for an unknown commit', async () => {
+        try {
+          await Git.listFilesAtCommit(subdirectoryPath, 'deadbeefdeadbeefdeadbeefdeadbeefdeadbeef');
+        } catch (error) {
+          expect(error).to.be.an.instanceOf(GitObjectNotFoundError);
+
+          return;
+        }
+
+        expect.fail('No error was thrown');
+      });
+    });
+
+    describe('.readFileAtCommit', () => {
+      it('returns the file content as it was at the given commit', async () => {
+        expect(await Git.readFileAtCommit(subdirectoryPath, firstCommitSha, 'Service A.json')).to.equal('{ "name": "Service A" }');
+      });
+
+      it('throws a GitObjectNotFoundError for a file absent from the commit', async () => {
+        try {
+          await Git.readFileAtCommit(subdirectoryPath, firstCommitSha, 'Service B.json');
+        } catch (error) {
+          expect(error).to.be.an.instanceOf(GitObjectNotFoundError);
+
+          return;
+        }
+
+        expect.fail('No error was thrown');
+      });
+    });
+  });
+});