@ankhorage/doctor 0.14.11 → 0.14.13

package/src/capabilityCatalogAst.ts

@@ -1,22 +1,35 @@
 import { promises as fs } from 'node:fs';
-import path from 'node:path';
 
 import * as ts from 'typescript';
 
-import { resolveContractsCatalogImportAsync } from './capabilityCatalogContractsImport.js';
-
-type StaticValue = string | number | boolean | null | readonly StaticValue[] | StaticRecord;
-interface StaticRecord {
-  readonly [key: string]: StaticValue;
-}
+import {
+  findImportBinding,
+  findStaticDeclaration,
+  hasExportModifier,
+  isConstDeclaration,
+  unwrapExpression,
+} from './capabilityCatalogAstSource.js';
+import { resolveImportPathAsync, resolveLocalImportPathAsync } from './capabilityCatalogImport.js';
+import {
+  isStaticArray,
+  isStaticRecord,
+  readStaticArray,
+  readStaticProperty,
+  type StaticRecord,
+  type StaticValue,
+} from './capabilityCatalogStaticValue.js';
 
 /*** Evaluate one named catalog export from the supported static TypeScript subset. */
 export async function capabilityCatalogAstAsync(
   packageRoot: string,
   modulePath: string,
   exportName: string,
+  materializedCatalog?: unknown,
 ): Promise<unknown> {
-  return new StaticCatalogResolver(packageRoot).resolveAsync(modulePath, exportName);
+  return new StaticCatalogResolver(packageRoot, materializedCatalog).resolveAsync(
+    modulePath,
+    exportName,
+  );
 }
 
 /*** Resolve static local imports and expressions without loading target modules. */
@@ -24,7 +37,14 @@ class StaticCatalogResolver {
   readonly #symbols = new Map<string, StaticValue>();
   readonly #activeSymbols: string[] = [];
 
-  constructor(private readonly packageRoot: string) {}
+  private readonly materializedCatalog: readonly StaticValue[] | null;
+
+  constructor(
+    private readonly packageRoot: string,
+    materializedCatalog?: unknown,
+  ) {
+    this.materializedCatalog = readStaticArray(materializedCatalog);
+  }
 
   /*** Resolve a named local export without importing or running its module. */
   async resolveAsync(
@@ -98,6 +118,7 @@ class StaticCatalogResolver {
     if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
     if (node.kind === ts.SyntaxKind.NullKeyword) return null;
     if (ts.isIdentifier(node)) return environment.resolveAsync(node.text);
+    if (ts.isPropertyAccessExpression(node)) return this.propertyAccessAsync(node, environment);
     if (ts.isArrayLiteralExpression(node)) return this.arrayAsync(node, environment);
     if (ts.isObjectLiteralExpression(node)) return this.objectAsync(node, environment);
     if (ts.isTemplateExpression(node)) return this.templateAsync(node, environment);
@@ -105,6 +126,29 @@ class StaticCatalogResolver {
     throw new Error(`Unsupported static capability expression: ${node.getText()}.`);
   }
 
+  /*** Evaluate one static object property while preserving dynamic-expression diagnostics. */
+  async propertyAccessAsync(
+    node: ts.PropertyAccessExpression,
+    environment: StaticCatalogScope,
+  ): Promise<StaticValue> {
+    try {
+      return readStaticProperty(
+        await this.evaluateAsync(node.expression, environment),
+        node.name.text,
+        node.getText(),
+      );
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        error.message.startsWith('Unsupported dynamic capability value:')
+      )
+        throw new Error(`Unsupported static capability expression: ${node.getText()}.`, {
+          cause: error,
+        });
+      throw error;
+    }
+  }
+
   /*** Evaluate a static array literal. */
   arrayAsync(
     node: ts.ArrayLiteralExpression,
@@ -180,9 +224,21 @@ class StaticCatalogResolver {
     environment: StaticCatalogScope,
   ): Promise<readonly StaticValue[]> {
     const result: StaticValue[] = [];
-    for (const element of elements) {
-      if (ts.isSpreadElement(element)) throw new Error('Catalog array spreads are not supported.');
-      result.push(await this.evaluateAsync(element, environment));
+    for (const [index, element] of elements.entries()) {
+      if (ts.isSpreadElement(element)) {
+        if (await environment.isPackageLocalDerivedCallAsync(element.expression)) {
+          if (index !== elements.length - 1 || this.materializedCatalog === null)
+            throw new Error(
+              'Derived catalog function spreads must be trailing and have materialized package metadata.',
+            );
+          result.push(...this.materializedCatalog.slice(result.length));
+          continue;
+        }
+        const spread = await this.evaluateAsync(element.expression, environment);
+        if (!isStaticArray(spread))
+          throw new Error('Catalog array spreads must resolve to static arrays.');
+        result.push(...spread);
+      } else result.push(await this.evaluateAsync(element, environment));
     }
     return result;
   }
@@ -233,6 +289,30 @@ class StaticCatalogScope {
     );
   }
 
+  /*** Detect one zero-argument function imported from a package-local source module. */
+  async isPackageLocalDerivedCallAsync(expression: ts.Expression): Promise<boolean> {
+    const node = unwrapExpression(expression);
+    if (
+      !ts.isCallExpression(node) ||
+      node.arguments.length !== 0 ||
+      !ts.isIdentifier(node.expression)
+    )
+      return false;
+    const imported = findImportBinding(this.source, node.expression.text);
+    if (
+      imported === undefined ||
+      !ts.isStringLiteral(imported.moduleSpecifier) ||
+      !imported.moduleSpecifier.text.startsWith('.')
+    )
+      return false;
+    await resolveLocalImportPathAsync(
+      this.packageRoot,
+      this.modulePath,
+      imported.moduleSpecifier.text,
+    );
+    return true;
+  }
+
   /*** Add a static callback parameter without evaluating unrelated module symbols. */
   withValue(name: string, value: StaticValue): StaticCatalogScope {
     return new StaticCatalogScope(
@@ -244,107 +324,3 @@ class StaticCatalogScope {
     );
   }
 }
-
-/*** Find the static top-level declaration that owns a local identifier. */
-function findStaticDeclaration(
-  source: ts.SourceFile,
-  name: string,
-): ts.VariableDeclaration | undefined {
-  return source.statements
-    .filter((statement): statement is ts.VariableStatement => ts.isVariableStatement(statement))
-    .filter((statement) => isConstDeclaration(statement.declarationList))
-    .flatMap((statement) => statement.declarationList.declarations)
-    .find((declaration) => ts.isIdentifier(declaration.name) && declaration.name.text === name);
-}
-
-/*** Find the import declaration that introduces a referenced local identifier. */
-function findImportBinding(source: ts.SourceFile, name: string): ts.ImportDeclaration | undefined {
-  return source.statements
-    .filter((statement): statement is ts.ImportDeclaration => ts.isImportDeclaration(statement))
-    .find((statement) => {
-      const clause = statement.importClause;
-      return (
-        clause?.name?.text === name ||
-        (clause?.namedBindings !== undefined &&
-          ts.isNamedImports(clause.namedBindings) &&
-          clause.namedBindings.elements.some((element) => element.name.text === name))
-      );
-    });
-}
-
-/*** Determine whether a declaration list is immutable static catalog input. */
-function isConstDeclaration(list: ts.VariableDeclarationList): boolean {
-  return (list.flags & ts.NodeFlags.Const) !== 0;
-}
-
-interface ResolvedStaticImport {
-  readonly packageRoot: string;
-  readonly path: string;
-}
-
-/*** Resolve an allowed static import without executing its target package. */
-async function resolveImportPathAsync(
-  packageRoot: string,
-  fromPath: string,
-  specifier: string,
-): Promise<ResolvedStaticImport> {
-  if (specifier.startsWith('.'))
-    return resolveLocalImportPathAsync(packageRoot, fromPath, specifier);
-  return resolveContractsCatalogImportAsync(packageRoot, fromPath, specifier);
-}
-
-/*** Resolve a relative static import that remains within its owning package. */
-async function resolveLocalImportPathAsync(
-  packageRoot: string,
-  fromPath: string,
-  specifier: string,
-): Promise<ResolvedStaticImport> {
-  const candidate = path.resolve(path.dirname(fromPath), specifier);
-  if (!isInsidePackage(packageRoot, candidate) && candidate !== packageRoot)
-    throw new Error('Capability catalogs may not import outside their package.');
-  for (const extension of ['', '.ts', '.tsx', '.js', '.mjs', '/index.ts'])
-    if (await isFileAsync(`${candidate}${extension}`))
-      return { packageRoot, path: `${candidate}${extension}` };
-  throw new Error(`Unable to resolve static capability import ${specifier}.`);
-}
-
-/*** Unwrap TypeScript syntax which does not alter a runtime value. */
-function unwrapExpression(expression: ts.Expression): ts.Expression {
-  return ts.isAsExpression(expression) ||
-    ts.isSatisfiesExpression(expression) ||
-    ts.isParenthesizedExpression(expression)
-    ? unwrapExpression(expression.expression)
-    : expression;
-}
-
-/*** Narrow a static value to a descriptor-shaped record. */
-function isStaticRecord(value: StaticValue): value is StaticRecord {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-/*** Narrow a static value to an array. */
-function isStaticArray(value: StaticValue): value is readonly StaticValue[] {
-  return Array.isArray(value);
-}
-
-/*** Detect an exported variable statement. */
-function hasExportModifier(statement: ts.VariableStatement): boolean {
-  return (
-    statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false
-  );
-}
-
-/*** Check whether a resolved path remains within the inspected package root. */
-function isInsidePackage(packageRoot: string, candidate: string): boolean {
-  const relativePath = path.relative(packageRoot, candidate);
-  return relativePath !== '' && !relativePath.startsWith(`..${path.sep}`) && relativePath !== '..';
-}
-
-/*** Check whether one candidate is a regular file. */
-async function isFileAsync(candidate: string): Promise<boolean> {
-  try {
-    return (await fs.stat(candidate)).isFile();
-  } catch {
-    return false;
-  }
-}

package/src/capabilityCatalogAstSource.ts

@@ -0,0 +1,52 @@
+import * as ts from 'typescript';
+
+/*** Find the static top-level declaration that owns a local identifier. */
+export function findStaticDeclaration(
+  source: ts.SourceFile,
+  name: string,
+): ts.VariableDeclaration | undefined {
+  return source.statements
+    .filter((statement): statement is ts.VariableStatement => ts.isVariableStatement(statement))
+    .filter((statement) => isConstDeclaration(statement.declarationList))
+    .flatMap((statement) => statement.declarationList.declarations)
+    .find((declaration) => ts.isIdentifier(declaration.name) && declaration.name.text === name);
+}
+
+/*** Find the import declaration that introduces a referenced local identifier. */
+export function findImportBinding(
+  source: ts.SourceFile,
+  name: string,
+): ts.ImportDeclaration | undefined {
+  return source.statements
+    .filter((statement): statement is ts.ImportDeclaration => ts.isImportDeclaration(statement))
+    .find((statement) => {
+      const clause = statement.importClause;
+      return (
+        clause?.name?.text === name ||
+        (clause?.namedBindings !== undefined &&
+          ts.isNamedImports(clause.namedBindings) &&
+          clause.namedBindings.elements.some((element) => element.name.text === name))
+      );
+    });
+}
+
+/*** Determine whether a declaration list is immutable static catalog input. */
+export function isConstDeclaration(list: ts.VariableDeclarationList): boolean {
+  return (list.flags & ts.NodeFlags.Const) !== 0;
+}
+
+/*** Unwrap TypeScript syntax which does not alter a runtime value. */
+export function unwrapExpression(expression: ts.Expression): ts.Expression {
+  return ts.isAsExpression(expression) ||
+    ts.isSatisfiesExpression(expression) ||
+    ts.isParenthesizedExpression(expression)
+    ? unwrapExpression(expression.expression)
+    : expression;
+}
+
+/*** Detect an exported variable statement. */
+export function hasExportModifier(statement: ts.VariableStatement): boolean {
+  return (
+    statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false
+  );
+}

package/src/capabilityCatalogImport.ts

@@ -0,0 +1,69 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import { resolveContractsCatalogImportAsync } from './capabilityCatalogContractsImport.js';
+
+export interface ResolvedStaticImport {
+  readonly packageRoot: string;
+  readonly path: string;
+}
+
+/*** Resolve an allowed static import without executing its target package. */
+export async function resolveImportPathAsync(
+  packageRoot: string,
+  fromPath: string,
+  specifier: string,
+): Promise<ResolvedStaticImport> {
+  if (specifier.startsWith('.'))
+    return resolveLocalImportPathAsync(packageRoot, fromPath, specifier);
+  return resolveContractsCatalogImportAsync(packageRoot, fromPath, specifier);
+}
+
+/*** Resolve a relative static import that remains within its owning package. */
+export async function resolveLocalImportPathAsync(
+  packageRoot: string,
+  fromPath: string,
+  specifier: string,
+): Promise<ResolvedStaticImport> {
+  const candidate = path.resolve(path.dirname(fromPath), specifier);
+  if (!isInsidePackage(packageRoot, candidate) && candidate !== packageRoot)
+    throw new Error('Capability catalogs may not import outside their package.');
+  for (const sourcePath of localSourceCandidates(candidate))
+    if (await isFileAsync(sourcePath)) return { packageRoot, path: sourcePath };
+  throw new Error(`Unable to resolve static capability import ${specifier}.`);
+}
+
+/*** Enumerate source files represented by one package-local ESM import specifier. */
+function localSourceCandidates(candidate: string): readonly string[] {
+  const extension = path.extname(candidate);
+  if (extension === '.js')
+    return [candidate.replace(/\.js$/u, '.ts'), candidate.replace(/\.js$/u, '.tsx'), candidate];
+  if (extension === '.mjs') return [candidate.replace(/\.mjs$/u, '.mts'), candidate];
+  if (extension === '.cjs') return [candidate.replace(/\.cjs$/u, '.cts'), candidate];
+  return [
+    candidate,
+    `${candidate}.ts`,
+    `${candidate}.tsx`,
+    `${candidate}.js`,
+    `${candidate}.mjs`,
+    `${candidate}.cjs`,
+    `${candidate}/index.ts`,
+    `${candidate}/index.tsx`,
+    `${candidate}/index.js`,
+  ];
+}
+
+/*** Check whether a resolved path remains within the inspected package root. */
+function isInsidePackage(packageRoot: string, candidate: string): boolean {
+  const relativePath = path.relative(packageRoot, candidate);
+  return relativePath !== '' && !relativePath.startsWith(`..${path.sep}`) && relativePath !== '..';
+}
+
+/*** Check whether one candidate is a regular file. */
+async function isFileAsync(candidate: string): Promise<boolean> {
+  try {
+    return (await fs.stat(candidate)).isFile();
+  } catch {
+    return false;
+  }
+}

package/src/capabilityCatalogStaticValue.ts

@@ -0,0 +1,48 @@
+export type StaticValue = string | number | boolean | null | readonly StaticValue[] | StaticRecord;
+
+export interface StaticRecord {
+  readonly [key: string]: StaticValue;
+}
+
+/*** Narrow a static value to a descriptor-shaped record. */
+export function isStaticRecord(value: StaticValue): value is StaticRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/*** Narrow a static value to an array. */
+export function isStaticArray(value: StaticValue): value is readonly StaticValue[] {
+  return Array.isArray(value);
+}
+
+/*** Read one property from a statically resolved object. */
+export function readStaticProperty(
+  value: StaticValue,
+  key: string,
+  expression: string,
+): StaticValue {
+  const property = isStaticRecord(value)
+    ? Object.entries(value).find(([propertyKey]) => propertyKey === key)?.[1]
+    : undefined;
+  if (property === undefined)
+    throw new Error(`Unsupported static capability property access: ${expression}.`);
+  return property;
+}
+
+/*** Read one JSON-compatible array as static catalog materialization input. */
+export function readStaticArray(value: unknown): readonly StaticValue[] | null {
+  return Array.isArray(value) && value.every(isStaticValue) ? value : null;
+}
+
+/*** Narrow untrusted JSON-compatible input to the static evaluator value model. */
+function isStaticValue(value: unknown): value is StaticValue {
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  )
+    return true;
+  if (Array.isArray(value)) return value.every(isStaticValue);
+  if (typeof value !== 'object') return false;
+  return Object.values(value).every(isStaticValue);
+}