stack/packages/project/src/read.mjs

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'); }
}
async function blob(repo, revision, path) {
  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 > MAX_BYTES)
    fail('project-read-content', 'blob exceeds size bound');
  return text(await gitBytes(repo, ['cat-file', 'blob', match[2]], MAX_BYTES));
}
// 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.
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 };
}