@h1v35/hivex 0.2.0 → 0.2.2

package/src/markdown.ts

@@ -1,98 +1,160 @@
 import { createHash } from 'node:crypto';
-import { basename } from 'node:path';
+import pathModule from 'node:path';
 import { fromMarkdown } from 'mdast-util-from-markdown';
-import { toString } from 'mdast-util-to-string';
 import { gfmFromMarkdown } from 'mdast-util-gfm';
 import { gfm } from 'micromark-extension-gfm';
 import { frontmatterFromMarkdown } from 'mdast-util-frontmatter';
 import { frontmatter } from 'micromark-extension-frontmatter';
 import { normalizeIdentifier } from 'micromark-util-normalize-identifier';
+import { toString as mdastToString } from 'mdast-util-to-string';
 import { parseDocument } from 'yaml';
 
 export const hash = (text: string) => createHash('sha256').update(text).digest('hex');
-export const isMarkdownPath = (path: string) => /\.(?:md|markdown|mdown)$/i.test(path);
+export const isMarkdownPath = (path: string) => /\.(?:md|markdown|mdown)$/iu.test(path);
 
-export function parseMarkdown(content: string) {
+export const parseMarkdown = function parseMarkdown(content: string) {
   return fromMarkdown(content, {
     extensions: [gfm(), frontmatter(['yaml'])],
     mdastExtensions: [gfmFromMarkdown(), frontmatterFromMarkdown(['yaml'])],
   });
-}
+};
 
-type MarkdownNode = {
+interface MarkdownNode {
   type: string;
   children?: MarkdownNode[];
   url?: string;
   identifier?: string;
-  position?: { start: { line: number; offset?: number }; end: { line: number; offset?: number } };
-};
+  position?: {
+    start: { line: number; offset?: number };
+    end: { line: number; offset?: number };
+  };
+}
 
-export function* descendants(tree: MarkdownNode): Generator<MarkdownNode> {
+export const descendants = function* descendants(tree: MarkdownNode): Generator<MarkdownNode> {
   const pending = [tree];
   while (pending.length) {
     const node = pending.pop();
-    if (!node) break;
+    if (!node) {
+      break;
+    }
     yield node;
-    for (let index = (node.children?.length ?? 0) - 1; index >= 0; index--) {
+    for (let index = (node.children?.length ?? 0) - 1; index >= 0; index -= 1) {
       const child = node.children?.[index];
-      if (child) pending.push(child);
+      if (child) {
+        pending.push(child);
+      }
     }
   }
-}
+};
 
-function metadata(tree: ReturnType<typeof parseMarkdown>) {
-  const node = tree.children.find((entry) => entry.type === 'yaml');
-  if (node?.type !== 'yaml') return { title: null, status: null };
+const emptyMetadata = { status: null, title: null };
+
+const yamlValue = function yamlValue(content: string): unknown {
+  let parsed: ReturnType<typeof parseDocument>;
   try {
-    const parsed = parseDocument(node.value, { uniqueKeys: true });
-    if (parsed.errors.length) return { title: null, status: null };
-    const value: unknown = parsed.toJS({ maxAliasCount: 0 });
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-      return { title: null, status: null };
-    return {
-      title:
-        'title' in value && typeof value.title === 'string' && value.title.trim()
-          ? value.title
-          : null,
-      status: 'status' in value && typeof value.status === 'string' ? value.status : null,
-    };
+    parsed = parseDocument(content, { uniqueKeys: true });
   } catch {
-    return { title: null, status: null };
+    return null;
   }
-}
+  if (parsed.errors.length) {
+    return null;
+  }
+  try {
+    return parsed.toJS({ maxAliasCount: 0 });
+  } catch {
+    return null;
+  }
+};
+
+const isRecord = function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+};
+
+const metadata = function metadata(tree: ReturnType<typeof parseMarkdown>) {
+  const node = tree.children.find((entry) => entry.type === 'yaml');
+  if (node?.type !== 'yaml') {
+    return emptyMetadata;
+  }
+  const value = yamlValue(node.value);
+  if (!isRecord(value)) {
+    return emptyMetadata;
+  }
+  const { status: statusValue, title: titleValue } = value;
+  return {
+    status: typeof statusValue === 'string' ? statusValue : null,
+    title: typeof titleValue === 'string' && titleValue.trim().length > 0 ? titleValue : null,
+  };
+};
 
-export function describeMarkdown(path: string, content: string) {
+export const describeMarkdown = function describeMarkdown(path: string, content: string) {
   const tree = parseMarkdown(content);
   const front = metadata(tree);
   const heading = tree.children.find((node) => node.type === 'heading');
   const definitions = new Map<string, string>();
   for (const node of descendants(tree)) {
-    if (node.type === 'definition' && node.identifier && node.url) {
+    if (node.type !== 'definition') {
+      continue;
+    }
+    if (
+      typeof node.identifier === 'string' &&
+      node.identifier.length > 0 &&
+      typeof node.url === 'string' &&
+      node.url.length > 0
+    ) {
       const id = normalizeIdentifier(node.identifier);
-      if (!definitions.has(id)) definitions.set(id, node.url);
+      if (!definitions.has(id)) {
+        definitions.set(id, node.url);
+      }
     }
   }
   const links = [...descendants(tree)].flatMap((node) => {
-    if (node.type === 'link' && node.url) return [node.url];
-    if (node.type !== 'linkReference' || !node.identifier) return [];
+    if (node.type === 'link' && typeof node.url === 'string' && node.url.length > 0) {
+      return [node.url];
+    }
+    if (
+      node.type !== 'linkReference' ||
+      typeof node.identifier !== 'string' ||
+      node.identifier.length === 0
+    ) {
+      return [];
+    }
     const url = definitions.get(normalizeIdentifier(node.identifier));
-    return url ? [url] : [];
+    if (url === undefined) {
+      return [];
+    }
+    return [url];
   });
   return {
-    title: front.title ?? (heading ? toString(heading) : basename(path)),
-    status: front.status,
     links,
+    status: front.status,
+    title: front.title ?? (heading ? mdastToString(heading) : pathModule.basename(path)),
   };
-}
+};
 
-export function rawMarkdownLines(text: string): string[] {
-  const lines = (text.match(/[^\r\n]*(?:\r\n|\r|\n|$)/g) ?? []).filter((line) => line.length > 0);
+export const rawMarkdownLines = function rawMarkdownLines(text: string): string[] {
+  const lines: string[] = [];
+  let lineStart = 0;
+  let index = 0;
+  while (index < text.length) {
+    const character = text[index];
+    if (character === '\r' || character === '\n') {
+      const lineEnd = index + (character === '\r' && text[index + 1] === '\n' ? 2 : 1);
+      lines.push(text.slice(lineStart, lineEnd));
+      lineStart = lineEnd;
+      index = lineEnd;
+    } else {
+      index += 1;
+    }
+  }
+  if (lineStart < text.length) {
+    lines.push(text.slice(lineStart));
+  }
   return lines.length ? lines : [''];
-}
+};
 
-export const lineContent = (line: string) => line.replace(/(?:\r\n|\r|\n)$/, '');
+export const lineContent = (line: string) => line.replace(/(?:\r\n|\r|\n)$/u, '');
 
-export function sourceRange(text: string, from: number, to: number) {
+export const sourceRange = function sourceRange(text: string, from: number, to: number) {
   const selected = rawMarkdownLines(text).slice(from - 1, to);
   return selected.slice(0, -1).join('') + lineContent(selected.at(-1) ?? '');
-}
+};

package/src/model/connection.ts

@@ -1,26 +1,39 @@
-import { createInterface, type Interface } from 'node:readline';
-import type { Readable, Writable } from 'node:stream';
+import { createInterface } from 'node:readline';
 import { z } from 'zod';
+import { AppServerRpcError, RemoteErrorSchema } from './rpc-error.ts';
+import type { Interface } from 'node:readline';
+import type { Readable, Writable } from 'node:stream';
+
+export { AppServerRpcError } from './rpc-error.ts';
+
+const observeRejection = async (promise: Promise<unknown>): Promise<void> => {
+  try {
+    await promise;
+  } catch {
+    // The rejection is handled by the caller through the public promise.
+  }
+};
+
+const createEnding = () => {
+  const ending = Promise.withResolvers<never>();
+  void observeRejection(ending.promise);
+  return ending;
+};
 
 const IdSchema = z.union([z.string(), z.number().int()]);
-const RemoteErrorSchema = z.looseObject({
-  code: z.number().int(),
-  message: z.string(),
-  data: z.unknown().optional(),
-});
 const FrameSchema = z.looseObject({
+  error: RemoteErrorSchema.optional(),
   id: IdSchema.optional(),
   method: z.string().optional(),
   params: z.unknown().optional(),
   result: z.unknown().optional(),
-  error: RemoteErrorSchema.optional(),
 });
 type Frame = z.infer<typeof FrameSchema>;
 
 interface ConnectionOptions {
   readonly input: Writable;
   readonly output: Readable;
-  readonly onNotification: (method: string, params: unknown) => void;
+  readonly onNotification: (method: string, parameters: unknown) => void;
   readonly onInteractiveRequest?: (method: string) => void;
 }
 interface RequestOptions {
@@ -34,87 +47,113 @@ interface PendingRequest {
   readonly cleanup: () => void;
 }
 
-export class AppServerRpcError extends Error {
-  readonly code: number;
-  readonly data: unknown;
-
-  constructor(error: z.infer<typeof RemoteErrorSchema>) {
-    super(error.message);
-    this.name = 'AppServerRpcError';
-    this.code = error.code;
-    this.data = error.data;
-  }
+interface ConnectionListeners {
+  readonly close: () => void;
+  readonly data: (chunk: Buffer) => void;
+  readonly error: (error: Error) => void;
+  readonly line: (line: string) => void;
 }
 
 export class AppServerConnection {
   private readonly options: ConnectionOptions;
   private readonly reader: Interface;
   private readonly pending = new Map<string | number, PendingRequest>();
-  private readonly ending = Promise.withResolvers<never>();
+  private readonly ending = createEnding();
   private failure: Error | undefined;
+  private readonly listeners: ConnectionListeners;
   private nextId = 1;
   private trailingBytes = 0;
   private streamBytes = 0;
-  readonly closed = this.ending.promise;
 
   constructor(options: ConnectionOptions) {
     this.options = options;
-    options.output.on('data', this.measureChunk);
-    this.reader = createInterface({ input: options.output, crlfDelay: Infinity });
-    this.reader.on('line', this.receiveLine);
-    this.reader.on('close', this.receiveClose);
-    options.input.on('error', this.receiveStreamError);
-    options.output.on('error', this.receiveStreamError);
-    void this.closed.catch(() => undefined);
+    this.listeners = {
+      close: this.receiveClose.bind(this),
+      data: this.measureChunk.bind(this),
+      error: this.receiveStreamError.bind(this),
+      line: this.receiveLine.bind(this),
+    };
+    options.output.on('data', this.listeners.data);
+    this.reader = createInterface({
+      crlfDelay: Infinity,
+      input: options.output,
+    });
+    this.reader.on('line', this.listeners.line);
+    this.reader.on('close', this.listeners.close);
+    options.input.on('error', this.listeners.error);
+    options.output.on('error', this.listeners.error);
+  }
+
+  get closed(): Promise<never> {
+    return this.ending.promise;
   }
 
-  request(method: string, params: unknown, options: RequestOptions = {}): Promise<unknown> {
-    if (this.failure !== undefined) return Promise.reject(this.failure);
-    if (options.signal?.aborted) return Promise.reject(new Error('request cancelled'));
+  async request(
+    method: string,
+    parameters: unknown,
+    options: RequestOptions = {}
+  ): Promise<unknown> {
+    if (this.failure !== undefined) {
+      throw this.failure;
+    }
+    if (options.signal?.aborted === true) {
+      throw new Error('request cancelled');
+    }
     const timeout = options.timeoutMilliseconds ?? 30_000;
     if (!Number.isSafeInteger(timeout) || timeout <= 0) {
-      return Promise.reject(new Error('request timeout must be a positive integer'));
+      throw new Error('request timeout must be a positive integer');
     }
-    const id = this.nextId++;
+    const id = this.nextId;
+    this.nextId += 1;
     const result = Promise.withResolvers<unknown>();
-    const abort = () => this.rejectRequest(id, new Error('request cancelled'));
-    const timer = setTimeout(
-      () => this.rejectRequest(id, new Error(`request timed out: ${method}`)),
-      timeout,
-    );
+    const abort = (): void => {
+      this.rejectRequest(id, new Error('request cancelled'));
+    };
+    const timer = setTimeout(() => {
+      this.rejectRequest(id, new Error(`request timed out: ${method}`));
+    }, timeout);
     this.pending.set(id, {
-      resolve: result.resolve,
-      reject: result.reject,
       cleanup: () => {
         clearTimeout(timer);
         options.signal?.removeEventListener('abort', abort);
       },
+      reject: result.reject,
+      resolve: result.resolve,
     });
     options.signal?.addEventListener('abort', abort, { once: true });
-    this.send({ id, method, params });
-    return result.promise;
+    this.send({ id, method, params: parameters });
+    return await result.promise;
   }
 
-  notify(method: string, params?: unknown): void {
-    if (this.failure !== undefined) throw this.failure;
-    this.send({ method, params });
+  notify(method: string, parameters?: unknown): void {
+    if (this.failure !== undefined) {
+      throw this.failure;
+    }
+    this.send({ method, params: parameters });
   }
 
   dispose(): void {
     this.fail(new Error('connection closed'));
-    this.reader.off('line', this.receiveLine);
-    this.reader.off('close', this.receiveClose);
+    this.reader.off('line', this.listeners.line);
+    this.reader.off('close', this.listeners.close);
     this.reader.close();
-    this.options.input.off('error', this.receiveStreamError);
-    this.options.output.off('error', this.receiveStreamError);
-    this.options.output.off('data', this.measureChunk);
+    this.options.input.off('error', this.listeners.error);
+    this.options.output.off('error', this.listeners.error);
+    this.options.output.off('data', this.listeners.data);
   }
 
-  private readonly receiveClose = (): void => this.fail(new Error('connection closed'));
-  private readonly receiveStreamError = (error: Error): void => this.fail(error);
+  protected receiveClose(): void {
+    this.fail(new Error('connection closed'));
+  }
+
+  protected receiveStreamError(error: Error): void {
+    this.fail(error);
+  }
 
-  private readonly measureChunk = (chunk: Buffer): void => {
-    if (this.failure) return;
+  protected measureChunk(chunk: Buffer): void {
+    if (this.failure !== undefined) {
+      return;
+    }
     this.streamBytes += chunk.byteLength;
     if (this.streamBytes > 33_554_432) {
       this.fail(new Error('app-server stream exceeded 32 MiB'));
@@ -131,40 +170,52 @@ export class AppServerConnection {
       offset = newline + 1;
     }
     this.trailingBytes += chunk.byteLength - offset;
-    if (this.trailingBytes > 4_194_304) this.fail(new Error('app-server frame exceeded 4 MiB'));
-  };
+    if (this.trailingBytes > 4_194_304) {
+      this.fail(new Error('app-server frame exceeded 4 MiB'));
+    }
+  }
 
-  private readonly receiveLine = (line: string): void => {
-    if (this.failure !== undefined) return;
+  protected receiveLine(line: string): void {
+    if (this.failure !== undefined) {
+      return;
+    }
     try {
       const frame = FrameSchema.parse(JSON.parse(line) as unknown);
       this.receiveFrame(frame);
     } catch (error: unknown) {
       this.fail(new Error('invalid app-server frame', { cause: error }));
     }
-  };
+  }
 
-  private receiveFrame(frame: Frame): void {
+  protected receiveFrame(frame: Frame): void {
     if (frame.method !== undefined) {
       if (Object.hasOwn(frame, 'result') || frame.error !== undefined) {
         throw new Error('a method frame cannot also be a response');
       }
-      if (frame.id === undefined) this.options.onNotification(frame.method, frame.params);
-      else this.declineInteractiveRequest(frame.id, frame.method);
+      if (frame.id === undefined) {
+        this.options.onNotification(frame.method, frame.params);
+      } else {
+        this.declineInteractiveRequest(frame.id, frame.method);
+      }
       return;
     }
     if (frame.id === undefined || Object.hasOwn(frame, 'result') === (frame.error !== undefined)) {
       throw new Error('a response requires an id and exactly one outcome');
     }
     const pending = this.pending.get(frame.id);
-    if (pending === undefined) return;
+    if (pending === undefined) {
+      return;
+    }
     this.pending.delete(frame.id);
     pending.cleanup();
-    if (frame.error !== undefined) pending.reject(new AppServerRpcError(frame.error));
-    else pending.resolve(frame.result);
+    if (frame.error === undefined) {
+      pending.resolve(frame.result);
+      return;
+    }
+    pending.reject(new AppServerRpcError(frame.error));
   }
 
-  private declineInteractiveRequest(id: string | number, method: string): void {
+  protected declineInteractiveRequest(id: string | number, method: string): void {
     this.options.onInteractiveRequest?.(method);
     if (
       method === 'item/commandExecution/requestApproval' ||
@@ -174,34 +225,41 @@ export class AppServerConnection {
       return;
     }
     this.send({
+      error: {
+        code: -32_601,
+        message: 'interactive requests are outside this pilot',
+      },
       id,
-      error: { code: -32601, message: 'interactive requests are outside this pilot' },
     });
   }
 
-  private send(frame: unknown): void {
+  protected send(frame: unknown): void {
     try {
-      this.options.input.write(`${JSON.stringify(frame)}\n`, (error) => {
-        if (error !== null && error !== undefined) this.fail(error);
-      });
+      this.options.input.write(`${JSON.stringify(frame)}\n`);
     } catch (error: unknown) {
       this.fail(new Error('app-server write failed', { cause: error }));
     }
   }
 
-  private rejectRequest(id: string | number, error: Error): void {
+  protected rejectRequest(id: string | number, error: Error): void {
     const pending = this.pending.get(id);
-    if (pending === undefined) return;
+    if (pending === undefined) {
+      return;
+    }
     this.pending.delete(id);
     pending.cleanup();
     pending.reject(error);
   }
 
-  private fail(error: Error): void {
-    if (this.failure !== undefined) return;
+  protected fail(error: Error): void {
+    if (this.failure !== undefined) {
+      return;
+    }
     this.failure = error;
     this.reader.close();
-    for (const id of this.pending.keys()) this.rejectRequest(id, error);
+    for (const id of this.pending.keys()) {
+      this.rejectRequest(id, error);
+    }
     this.ending.reject(error);
   }
 }

package/src/model/failure.ts

@@ -1,33 +1,56 @@
 import { z } from 'zod';
-import { AppServerRpcError } from './connection.ts';
+import { AppServerRpcError } from './rpc-error.ts';
 import type { ProfileEvidence } from './profile.ts';
 
-export class ServerAdmissionFailure extends Error {
+class ServerAdmissionFailureError extends Error {
+  name = 'ServerAdmissionFailureError';
+  readonly admission: (ProfileEvidence & { launchPolicyHash: string }) | undefined;
   readonly cleanup: 'confirmed' | 'failed';
   readonly processId: number;
-  readonly admission: (ProfileEvidence & { launchPolicyHash: string }) | undefined;
-  constructor(options: {
-    cause: unknown;
-    cleanup: 'confirmed' | 'failed';
-    processId: number;
-    admission?: ProfileEvidence & { launchPolicyHash: string };
-  }) {
-    super('Native server admission failed', { cause: options.cause });
-    this.cleanup = options.cleanup;
-    this.processId = options.processId;
-    this.admission = options.admission;
+
+  constructor(
+    parameters: {
+      admission?: ProfileEvidence & { launchPolicyHash: string };
+      cause: unknown;
+      cleanup: 'confirmed' | 'failed';
+      processId: number;
+    },
+    options?: ErrorOptions
+  ) {
+    super('Native server admission failed', options);
+    Object.defineProperty(this, 'cause', {
+      configurable: true,
+      enumerable: false,
+      value: parameters.cause,
+      writable: true,
+    });
+    this.admission = parameters.admission;
+    this.cleanup = parameters.cleanup;
+    this.processId = parameters.processId;
   }
 }
 
-export function failureDiagnostic(error: unknown): Record<string, unknown> {
-  if (error instanceof ServerAdmissionFailure) return failureDiagnostic(error.cause);
-  if (error instanceof z.ZodError)
-    return {
-      kind: 'invalid-native-response',
-      fields: error.issues.map((issue) => issue.path.join('.')),
+export { ServerAdmissionFailureError as ServerAdmissionFailure };
+
+export const failureDiagnostic = (error: unknown): Record<string, unknown> => {
+  let current = error;
+  while (current instanceof ServerAdmissionFailureError) {
+    current = current.cause;
+  }
+  if (current instanceof z.ZodError) {
+    const diagnosticKind = { kind: 'invalid-native-response' };
+    const diagnosticFields = {
+      fields: current.issues.map((issue) => issue.path.join('.')),
     };
-  if (error instanceof AppServerRpcError) return { kind: 'rpc-rejection', code: error.code };
-  if (error instanceof Error && error.constructor === Error)
-    return { kind: 'native-admission', message: error.message };
+    return { ...diagnosticKind, ...diagnosticFields };
+  }
+  if (current instanceof AppServerRpcError) {
+    const diagnosticKind = { kind: 'rpc-rejection' };
+    const diagnosticCode = { code: current.code };
+    return { ...diagnosticKind, ...diagnosticCode };
+  }
+  if (Error.isError(current) && current.constructor === Error) {
+    return { kind: 'native-admission', message: current.message };
+  }
   return { kind: 'native-failure' };
-}
+};