Files
stack/packages/project/src/read.mjs
T

97 lines
5.5 KiB
JavaScript

import { projectRepo, documentPath, ProjectError } from './paths.mjs';
import { git, gitBytes, inspectGit } from './git.mjs';
import { validateRecord } from './validate.mjs';
const MAX_BYTES = 1024 * 1024;
const SHA = /^[0-9a-f]{40}$/;
const fail = (code, message) => { throw new ProjectError(code, message); };
function argumentsFor(args, allowed) {
if (!args || typeof args !== 'object' || Array.isArray(args) || Object.keys(args).some(k => !allowed.includes(k)))
fail('project-read-path', 'unknown read arguments');
}
function text(bytes) {
try {
const value = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
if (value.includes('\0')) fail('project-read-content', 'NUL in blob');
return value;
} catch { fail('project-read-content', 'expected bounded UTF-8 without NUL'); }
}
export async function committedBlob(repo, revision, path, maxBytes = MAX_BYTES) {
const entry = await git(repo, ['ls-tree', '-z', revision, '--', path]);
if (!entry) fail('project-read-missing', 'file absent at revision');
const match = /^(100644|100755) blob ([0-9a-f]{40})\t([^\0]+)\0$/.exec(entry);
if (!match || match[3] !== path) fail('project-read-content', 'expected regular Git blob');
const size = Number(await git(repo, ['cat-file', '-s', match[2]]));
if (!Number.isSafeInteger(size) || size < 0 || size > maxBytes)
fail('project-read-content', 'blob exceeds size bound');
return { blob: match[2], bytes: size, content: text(await gitBytes(repo, ['cat-file', 'blob', match[2]], maxBytes)) };
}
async function blob(repo, revision, path) {
return (await committedBlob(repo, revision, path)).content;
}
// The repository, its HEAD and the revision to read, with the committed project identity checked
// against the caller's business and project. Shared by the file read and the file list.
export async function openRevision({ business, project, dataRoot, commit }) {
const repo = projectRepo({ business, project, dataRoot });
await inspectGit(repo);
let head;
try { head = await git(repo, ['rev-parse', '--verify', 'HEAD^{commit}']); }
catch { fail('project-read-commit', 'repository has no readable HEAD commit'); }
const revision = commit === undefined ? head : commit;
if (typeof revision !== 'string' || !SHA.test(revision)) fail('project-read-commit', 'expected full commit ID');
try {
if (await git(repo, ['cat-file', '-t', revision]) !== 'commit') fail('project-read-commit', 'not a commit');
await git(repo, ['merge-base', '--is-ancestor', revision, head]);
} catch { fail('project-read-commit', 'commit is not reachable from HEAD'); }
let metadata;
try { metadata = JSON.parse(await blob(repo, revision, 'project.json')); }
catch { fail('project-invalid', 'missing or invalid committed project metadata'); }
if (validateRecord('project', metadata).length || metadata.business !== business.id || metadata.project !== project)
fail('project-invalid', 'committed project identity does not match context');
return { repo, head, revision };
}
// The documents a person can open in the Console (row 148): the spec and the Markdown directly
// under docs/, as committed at HEAD. Names only; a read opens one.
export async function listProjectFiles(args) {
argumentsFor(args, ['business', 'project', 'dataRoot']);
const { head, repo } = await openRevision(args);
const listing = await gitBytes(repo, ['ls-tree', '-z', head, '--', 'spec/north-star.md', 'docs/'], 256 * 1024);
let entries;
try { entries = new TextDecoder('utf-8', { fatal: true }).decode(listing).split('\0'); }
catch { fail('project-git', 'invalid UTF-8 Git listing'); }
if (entries.pop() !== '') fail('project-git', 'invalid Git listing');
const files = [];
for (const entry of entries) {
const match = /^(100644|100755) blob [0-9a-f]{40}\t([^\0]+)$/.exec(entry);
if (match && documentPath(match[2])) files.push({ path: match[2] });
}
files.sort((a, b) => a.path < b.path ? -1 : 1);
return { head, files };
}
export async function readProjectFile(args) {
argumentsFor(args, ['business', 'project', 'dataRoot', 'path', 'commit']);
const { business, project, dataRoot, path, commit } = args;
if (!documentPath(path)) fail('project-read-path', 'expected spec/north-star.md or a named Markdown doc');
const { repo, head, revision } = await openRevision({ business, project, dataRoot, commit });
const content = await blob(repo, revision, path);
const bytes = await gitBytes(repo, ['log', '-z', '--max-count=101',
'--format=%H%x00%an%x00%ae%x00%aI%x00%s', revision, '--', path], 256 * 1024);
let fields;
try { fields = new TextDecoder('utf-8', { fatal: true }).decode(bytes).split('\0'); }
catch { fail('project-git', 'invalid UTF-8 Git history'); }
if (fields.pop() !== '' || !fields.length || fields.length % 5 !== 0)
fail('project-git', 'invalid Git history');
const log = [];
for (let i = 0; i < fields.length; i += 5) {
const [commit, name, email, at, subject] = fields.slice(i, i + 5);
if (!SHA.test(commit) || !Number.isFinite(Date.parse(at))) fail('project-git', 'invalid Git history');
log.push({ commit, author: { name, email }, at: new Date(at).toISOString(), subject });
}
return { repo, path, head, revision, commit: log[0].commit, content, author: log[0].author,
log: log.slice(0, 100), truncated: log.length > 100 };
}
export async function readSpec(args) {
argumentsFor(args, ['business', 'project', 'dataRoot', 'commit']);
const result = await readProjectFile({ ...args, path: 'spec/north-star.md' });
return { ...result, confirmed: result.author.name === args.business.human };
}