@h1v35/hivex 0.2.1 → 0.3.0

package/src/project-initialization.ts

@@ -0,0 +1,319 @@
+import { lstatSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { HivexError } from './errors.ts';
+
+interface TemplateFile {
+  bytes: Buffer;
+  path: string;
+}
+
+interface FileOperation {
+  absolutePath: string;
+  bytes: Buffer;
+  path: string;
+  state: 'created' | 'preserved' | 'updated';
+}
+
+interface InitReport {
+  command: 'init';
+  created: string[];
+  modelCalls: 0;
+  preserved: string[];
+  updated: string[];
+}
+
+const ignoreRules = ['!/.hivex/', '/.hivex/*', '!/.hivex/graph.json'];
+const assetsPath = path.join(import.meta.dirname, '../skills/hivex/assets/project');
+const assetsUnavailableCode = 'INIT_ASSETS_UNAVAILABLE';
+const assetsInvalidCode = 'INIT_ASSETS_INVALID';
+
+const fail = function fail(code: string, message: string): never {
+  throw new HivexError({ code, message });
+};
+
+const safeRelativePath = function safeRelativePath(relativePath: string) {
+  const normalized = relativePath.replaceAll('\\', '/');
+  const parts = normalized.split('/');
+  const hasInvalidPath = [
+    !relativePath,
+    path.isAbsolute(relativePath),
+    normalized.startsWith('/'),
+    normalized.includes('\u{0}'),
+    relativePath.includes('\\'),
+  ].includes(true);
+  if (hasInvalidPath) {
+    return fail('INVALID_DESTINATION', 'Initialization paths must be relative project files');
+  }
+  if (parts.some((part) => ['', '.', '..'].includes(part))) {
+    return fail('INVALID_DESTINATION', 'Initialization paths must be relative project files');
+  }
+  return normalized;
+};
+
+const errorMessage = function errorMessage(error: unknown) {
+  return Error.isError(error) ? error.message : 'unknown error';
+};
+
+const templateEntries = function templateEntries(directory: string) {
+  try {
+    return readdirSync(directory, { withFileTypes: true }).toSorted((left, right) =>
+      left.name.localeCompare(right.name)
+    );
+  } catch (error) {
+    return fail(assetsUnavailableCode, `Unable to read project templates: ${errorMessage(error)}`);
+  }
+};
+
+const readTemplateFile = function readTemplateFile(
+  absolutePath: string,
+  relativePath: string
+): TemplateFile {
+  try {
+    return { bytes: readFileSync(absolutePath), path: relativePath };
+  } catch (error) {
+    return fail(
+      assetsUnavailableCode,
+      `Unable to read project template ${relativePath}: ${errorMessage(error)}`
+    );
+  }
+};
+
+const readTemplateFiles = function readTemplateFiles(
+  directory: string,
+  relativeDirectory = ''
+): TemplateFile[] {
+  const files: TemplateFile[] = [];
+  const visit = function visit(current: string, currentRelativeDirectory: string) {
+    for (const entry of templateEntries(current)) {
+      const relativePath = safeRelativePath(
+        currentRelativeDirectory ? `${currentRelativeDirectory}/${entry.name}` : entry.name
+      );
+      const absolutePath = path.join(current, entry.name);
+      if (entry.isSymbolicLink()) {
+        fail(assetsInvalidCode, `Project template must not be a symlink: ${relativePath}`);
+      } else if (entry.isDirectory()) {
+        visit(absolutePath, relativePath);
+      } else if (entry.isFile()) {
+        files.push(readTemplateFile(absolutePath, relativePath));
+      } else {
+        fail(assetsInvalidCode, `Project template is not a regular file: ${relativePath}`);
+      }
+    }
+  };
+  visit(directory, relativeDirectory);
+  return files;
+};
+
+const projectRoot = function projectRoot(requested: string) {
+  if (!requested.trim()) {
+    return fail('INVALID_ROOT', 'Project root must be a non-empty path');
+  }
+  const root = path.resolve(requested);
+  let stat;
+  try {
+    stat = lstatSync(root);
+  } catch (error) {
+    return fail('INVALID_ROOT', `Project root is not readable: ${errorMessage(error)}`);
+  }
+  if (stat.isSymbolicLink()) {
+    return fail('INVALID_ROOT', 'Project root must not be a symlink');
+  }
+  if (!stat.isDirectory()) {
+    return fail('INVALID_ROOT', 'Project root must be a directory');
+  }
+  return root;
+};
+
+const destination = function destination(root: string, relativePath: string) {
+  const absolutePath = path.resolve(root, relativePath);
+  const relative = path.relative(root, absolutePath);
+  if (
+    !relative ||
+    relative === '..' ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  ) {
+    return fail(
+      'INVALID_DESTINATION',
+      `Initialization path escapes the project root: ${relativePath}`
+    );
+  }
+
+  let current = root;
+  const parts = relative.split(path.sep);
+  for (const [index, part] of parts.entries()) {
+    current = path.join(current, part);
+    let stat;
+    try {
+      stat = lstatSync(current, { throwIfNoEntry: false });
+    } catch (error) {
+      return fail(
+        'INVALID_DESTINATION',
+        `Unable to inspect initialization path ${relativePath}: ${errorMessage(error)}`
+      );
+    }
+    if (stat === undefined) {
+      return { absolutePath, exists: false };
+    }
+    if (stat.isSymbolicLink()) {
+      return fail(
+        'INVALID_DESTINATION',
+        `Initialization path must not use symlinks: ${relativePath}`
+      );
+    }
+    const isFinal = index === parts.length - 1;
+    if ((!isFinal && !stat.isDirectory()) || (isFinal && !stat.isFile())) {
+      return fail(
+        'INVALID_DESTINATION',
+        `Initialization path is not a regular file: ${relativePath}`
+      );
+    }
+  }
+  return { absolutePath, exists: true };
+};
+
+const validateNestedIgnore = function validateNestedIgnore(root: string) {
+  const relativePath = '.hivex/.gitignore';
+  const target = destination(root, relativePath);
+  if (!target.exists) {
+    return;
+  }
+  let text: string;
+  try {
+    text = readFileSync(target.absolutePath, 'utf-8');
+  } catch (error) {
+    throw new HivexError({
+      code: 'INIT_READ_FAILED',
+      message: `Unable to read ${relativePath}: ${errorMessage(error)}`,
+    });
+  }
+  if (text.split(/\r?\n/u).some((line) => line.trim() !== '' && !line.startsWith('#'))) {
+    fail(
+      'INIT_IGNORE_CONFLICT',
+      '.hivex/.gitignore contains rules that can override snapshot visibility or local state privacy.'
+    );
+  }
+};
+
+const hasFinalIgnoreRules = function hasFinalIgnoreRules(text: string) {
+  const lines = text.split(/\r?\n/u);
+  while (lines.at(-1) === '') {
+    lines.pop();
+  }
+  const start = lines.length - ignoreRules.length;
+  return start >= 0 && ignoreRules.every((rule, index) => lines[start + index] === rule);
+};
+
+const ignoreUpdate = function ignoreUpdate(existing: Buffer | null) {
+  const block = `${ignoreRules.join('\n')}\n`;
+  if (existing === null) {
+    return Buffer.from(block);
+  }
+  const text = existing.toString('utf-8');
+  if (hasFinalIgnoreRules(text)) {
+    return null;
+  }
+  const separator = text.length === 0 || text.endsWith('\n') ? '' : '\n';
+  return Buffer.concat([existing, Buffer.from(`${separator}${block}`)]);
+};
+
+const templateOperations = function templateOperations(root: string, templates: TemplateFile[]) {
+  return templates.map(({ bytes, path: relativePath }) => {
+    const target = destination(root, relativePath);
+    return {
+      absolutePath: target.absolutePath,
+      bytes,
+      path: relativePath,
+      state: target.exists ? 'preserved' : 'created',
+    } satisfies FileOperation;
+  });
+};
+
+const ignoreOperation = function ignoreOperation(root: string) {
+  const relativePath = '.gitignore';
+  const target = destination(root, relativePath);
+  let existing: Buffer | null = null;
+  if (target.exists) {
+    try {
+      existing = readFileSync(target.absolutePath);
+    } catch (error) {
+      return fail('INIT_READ_FAILED', `Unable to read ${relativePath}: ${errorMessage(error)}`);
+    }
+  }
+  const bytes = ignoreUpdate(existing);
+  let state: FileOperation['state'] = 'created';
+  if (target.exists) {
+    state = bytes === null ? 'preserved' : 'updated';
+  }
+  return {
+    absolutePath: target.absolutePath,
+    bytes: bytes ?? existing ?? Buffer.alloc(0),
+    path: relativePath,
+    state,
+  } satisfies FileOperation;
+};
+
+const writeOperations = function writeOperations(operations: FileOperation[]) {
+  for (const operation of operations) {
+    if (operation.state === 'preserved') {
+      continue;
+    }
+    mkdirSync(path.dirname(operation.absolutePath), { recursive: true });
+    if (operation.state === 'created') {
+      writeFileSync(operation.absolutePath, operation.bytes, { flag: 'wx', mode: 0o644 });
+    } else {
+      writeFileSync(operation.absolutePath, operation.bytes);
+    }
+  }
+};
+
+const report = function report(operations: FileOperation[]): InitReport {
+  const paths = function paths(state: FileOperation['state']) {
+    return operations
+      .filter((operation) => operation.state === state)
+      .map((operation) => operation.path)
+      .toSorted((left, right) => left.localeCompare(right));
+  };
+  return {
+    command: 'init',
+    created: paths('created'),
+    modelCalls: 0,
+    preserved: paths('preserved'),
+    updated: paths('updated'),
+  };
+};
+
+const parseInitArguments = function parseInitArguments(argumentsList: string[]) {
+  try {
+    return parseArgs({
+      allowPositionals: true,
+      args: argumentsList,
+      options: { root: { type: 'string' } },
+      strict: true,
+    });
+  } catch (error) {
+    return fail(
+      'INVALID_ARGUMENT',
+      Error.isError(error) ? error.message : 'Invalid init arguments'
+    );
+  }
+};
+
+export const projectInitializationCommand = function projectInitializationCommand(
+  argumentsList: string[]
+) {
+  const parsed = parseInitArguments(argumentsList);
+  if (parsed.positionals.length !== 1 || parsed.positionals[0] !== 'init') {
+    return fail('INVALID_ARGUMENT', 'Use init [--root <project>]');
+  }
+  const root = projectRoot(parsed.values.root ?? process.cwd());
+  validateNestedIgnore(root);
+  const templates = readTemplateFiles(assetsPath);
+  if (!templates.length) {
+    return fail('INIT_ASSETS_UNAVAILABLE', 'No project templates are available');
+  }
+  const operations = [...templateOperations(root, templates), ignoreOperation(root)];
+  writeOperations(operations);
+  return report(operations);
+};

package/src/snapshot-command.ts

@@ -5,19 +5,26 @@ import { ingestionUnits } from './ingestion-units.ts';
 import { KnowledgeStore } from './knowledge-store.ts';
 import { readKnowledgeSnapshot, writeKnowledgeSnapshot } from './knowledge-snapshot.ts';
 import { loadProject } from './documents.ts';
+import { relocateSource } from './source-relocation.ts';
 import type { Graph } from './knowledge-model.ts';
 import type { Project } from './documents.ts';
+import type { SourceRelocation } from './source-relocation.ts';
 
 const sourceVersion = function sourceVersion([document, version]: [string, string]) {
   return { document, version };
 };
 
+const warningScopes = function warningScopes(warning: Graph['warnings'][number]) {
+  return typeof warning === 'string' ? [] : warning.scope;
+};
+
 const sourceVersions = function sourceVersions(project: Project, graph: Graph) {
   const references = [
     ...Object.entries(graph.documents).map(sourceVersion),
     ...Object.values(graph.units),
     ...graph.decisions,
     ...graph.relationships.flatMap((edge) => edge.evidence),
+    ...graph.warnings.flatMap(warningScopes),
   ];
   const current = new Set<string>();
   const stale = new Set<string>();
@@ -68,6 +75,15 @@ const snapshotReport = function snapshotReport(project: Project, graph: Graph, o
   };
 };
 
+const relocationReport = function relocationReport(project: Project, relocation: SourceRelocation) {
+  return {
+    ...snapshotReport(project, relocation.graph, 'relocate'),
+    from: { document: relocation.from, versions: relocation.fromVersions },
+    reused: relocation.reused,
+    to: { document: relocation.to, version: relocation.destinationVersion },
+  };
+};
+
 export const snapshotCommand = function snapshotCommand(argumentsList: string[]) {
   const { positionals, values } = parseArgs({
     allowPositionals: true,
@@ -75,18 +91,27 @@ export const snapshotCommand = function snapshotCommand(argumentsList: string[])
     options: { root: { type: 'string' } },
     strict: true,
   });
-  const [, operation] = positionals;
+  const [, operation, from, to] = positionals;
+  const isRelocate = operation === 'relocate';
+  const expectedPositionals = isRelocate ? 4 : 2;
+  const isValidOperation = operation === 'export' || operation === 'import' || isRelocate;
   if (
-    positionals.length !== 2 ||
-    positionals[0] !== 'snapshot' ||
-    (operation !== 'export' && operation !== 'import')
+    !isValidOperation ||
+    positionals.length !== expectedPositionals ||
+    positionals[0] !== 'snapshot'
   ) {
     throw new HivexError({
       code: 'INVALID_ARGUMENT',
-      message: 'Use snapshot export | import [--root <project>]',
+      message: 'Use snapshot export | import | relocate <from> <to> [--root <project>]',
     });
   }
   const project = loadProject(values.root ?? process.cwd());
+  if (isRelocate) {
+    using store = new KnowledgeStore(project.root, { update: true });
+    const relocation = relocateSource(store.graph(), project, from ?? '', to ?? '');
+    store.importGraph(relocation.graph);
+    return relocationReport(project, relocation);
+  }
   const incoming = operation === 'import' ? readKnowledgeSnapshot(project.root) : null;
   if (operation === 'import' && incoming === null) {
     throw new HivexError({

package/src/source-relocation.ts

@@ -0,0 +1,222 @@
+import { compareSerializedStrings } from './ordering.ts';
+import { HivexError } from './errors.ts';
+import { isMarkdownPath } from './markdown.ts';
+import type { Project } from './documents.ts';
+import type { Graph } from './knowledge-model.ts';
+
+const protectedParts = new Set(['', '.', '..', '.git', '.hivex', 'node_modules']);
+
+const isPortablePath = function isPortablePath(value: string) {
+  if (!isMarkdownPath(value) || value.startsWith('/')) {
+    return false;
+  }
+  if (value.includes('\\') || value.includes('\0')) {
+    return false;
+  }
+  return value.split('/').every((part) => !protectedParts.has(part));
+};
+
+const fail = function fail(code: string, message: string): never {
+  throw new HivexError({ code, message });
+};
+
+const relationshipVersions = function relationshipVersions(
+  relationship: Graph['relationships'][number],
+  document: string
+) {
+  return relationship.evidence
+    .filter((evidence) => evidence.document === document)
+    .flatMap((evidence) => (evidence.version === undefined ? [] : [evidence.version]));
+};
+
+const warningVersions = function warningVersions(
+  warning: Graph['warnings'][number],
+  document: string
+) {
+  if (typeof warning === 'string') {
+    return [];
+  }
+  return warning.scope.filter((scope) => scope.document === document).map((scope) => scope.version);
+};
+
+const sourceVersions = function sourceVersions(graph: Graph, document: string) {
+  const versions = [
+    graph.documents[document],
+    ...Object.values(graph.units)
+      .filter((unit) => unit.document === document)
+      .map((unit) => unit.version),
+    ...graph.decisions
+      .filter((decision) => decision.document === document)
+      .map((decision) => decision.version),
+    ...graph.relationships.flatMap((relationship) => relationshipVersions(relationship, document)),
+    ...graph.warnings.flatMap((warning) => warningVersions(warning, document)),
+  ].filter((version): version is string => version !== undefined);
+  return [...new Set(versions)].toSorted(compareSerializedStrings);
+};
+
+const hasKnowledge = function hasKnowledge(graph: Graph, document: string) {
+  if (graph.documents[document] !== undefined) {
+    return true;
+  }
+  if (Object.values(graph.units).some((unit) => unit.document === document)) {
+    return true;
+  }
+  if (graph.decisions.some((decision) => decision.document === document)) {
+    return true;
+  }
+  if (
+    graph.relationships.some((relationship) =>
+      relationship.evidence.some((evidence) => evidence.document === document)
+    )
+  ) {
+    return true;
+  }
+  return graph.warnings.some(
+    (warning) =>
+      typeof warning !== 'string' && warning.scope.some((scope) => scope.document === document)
+  );
+};
+
+const selectedDocument = function selectedDocument(project: Project, id: string) {
+  return project.documents.find((document) => document.id === id);
+};
+
+const mapCitation = function mapCitation<T extends { document: string }>(
+  citation: T,
+  from: string,
+  to: string
+) {
+  return citation.document === from ? { ...citation, document: to } : citation;
+};
+
+const mapUnitId = function mapUnitId(id: string, from: string, to: string) {
+  const prefix = `${from}:`;
+  return id.startsWith(prefix) ? `${to}${id.slice(from.length)}` : id;
+};
+
+const mapWarning = function mapWarning(
+  warning: Graph['warnings'][number],
+  from: string,
+  to: string
+): Graph['warnings'][number] {
+  return typeof warning === 'string'
+    ? warning
+    : { ...warning, scope: warning.scope.map((scope) => mapCitation(scope, from, to)) };
+};
+
+const mapDecision = function mapDecision(
+  decision: Graph['decisions'][number],
+  from: string,
+  to: string
+) {
+  return { ...decision, document: decision.document === from ? to : decision.document };
+};
+
+const mapRelationship = function mapRelationship(
+  relationship: Graph['relationships'][number],
+  from: string,
+  to: string
+) {
+  return {
+    ...relationship,
+    evidence: relationship.evidence.map((evidence) => mapCitation(evidence, from, to)),
+  };
+};
+
+const mapUnits = function mapUnits(
+  graph: Graph,
+  from: string,
+  to: string,
+  isCoverageRelocated: boolean
+) {
+  const entries = Object.entries(graph.units).flatMap(([id, unit]) => {
+    if (!isCoverageRelocated && (unit.document === from || unit.document === to)) {
+      return [];
+    }
+    if (unit.document !== from) {
+      return [[id, unit] as const];
+    }
+    const relocatedId = mapUnitId(id, from, to);
+    return [[relocatedId, { ...unit, document: to }] as const];
+  });
+  return Object.fromEntries(entries);
+};
+
+const mapDocuments = function mapDocuments(
+  graph: Graph,
+  from: string,
+  to: string,
+  options: { isCoverageRelocated: boolean; sourceVersion: string | undefined }
+) {
+  const entries = Object.entries(graph.documents).filter(([id]) => id !== from && id !== to);
+  if (options.isCoverageRelocated && options.sourceVersion !== undefined) {
+    entries.push([to, options.sourceVersion]);
+  }
+  return Object.fromEntries(entries);
+};
+
+export interface SourceRelocation {
+  destinationVersion: string;
+  from: string;
+  fromVersions: string[];
+  graph: Graph;
+  reused: boolean;
+  to: string;
+}
+
+export const relocateSource = function relocateSource(
+  graph: Graph,
+  project: Project,
+  from: string,
+  to: string
+): SourceRelocation {
+  if (from === to || !isPortablePath(from) || !isPortablePath(to)) {
+    fail(
+      'INVALID_ARGUMENT',
+      'Source relocation paths must be distinct project-local Markdown files'
+    );
+  }
+  if (!hasKnowledge(graph, from)) {
+    fail('SOURCE_NOT_FOUND', `Source is not present in knowledge: ${from}`);
+  }
+  if (selectedDocument(project, from) !== undefined) {
+    fail('INVALID_ARGUMENT', `Source must no longer be selected: ${from}`);
+  }
+  const destination = project.currentDocuments.find((document) => document.id === to);
+  if (destination === undefined) {
+    return fail('SOURCE_NOT_FOUND', `Destination is not a selected current Markdown source: ${to}`);
+  }
+  const versions = sourceVersions(graph, from);
+  const hasDestinationKnowledge = hasKnowledge(graph, to);
+  const hasUnversionedEvidence = graph.relationships
+    .flatMap((relationship) => relationship.evidence)
+    .some((evidence) => evidence.document === from && evidence.version === undefined);
+  const isReused =
+    !hasDestinationKnowledge &&
+    !hasUnversionedEvidence &&
+    versions.length > 0 &&
+    versions.every((version) => version === destination.hash);
+  const documents = mapDocuments(graph, from, to, {
+    isCoverageRelocated: isReused,
+    sourceVersion: graph.documents[from],
+  });
+  const units = mapUnits(graph, from, to, isReused);
+  const relocated: Graph = {
+    ...graph,
+    decisions: graph.decisions.map((decision) => mapDecision(decision, from, to)),
+    documents,
+    relationships: graph.relationships.map((relationship) =>
+      mapRelationship(relationship, from, to)
+    ),
+    units,
+    warnings: graph.warnings.map((warning) => mapWarning(warning, from, to)),
+  };
+  return {
+    destinationVersion: destination.hash,
+    from,
+    fromVersions: versions,
+    graph: relocated,
+    reused: isReused,
+    to,
+  };
+};