@facilis.dev/analyze 0.0.0-stage → 0.1.0

package/src/passes/workflows.ts

@@ -0,0 +1,213 @@
+// `server/workflows/**` definitions -> WorkflowFacts (docs/WORKFLOWS.md §6, D-135).
+//
+// The default export is the only source: a `defineWorkflow()` call from `@facilis.dev/core`
+// whose argument is an object literal. Resolvers (`input`, `params`) are functions, so the
+// reader takes the static fields one by one instead of evaluating the whole definition.
+
+import {
+  callArguments,
+  identifierName,
+  nodeArray,
+  objectEntries,
+  propertyName,
+  propertyValue,
+  unwrapExpression,
+  type AstNode,
+} from "../ast/node.ts";
+import { warning } from "../diagnostics.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import { sourceRef } from "../source.ts";
+import { evaluateStatic, type StaticContext } from "../static-eval.ts";
+import type { Diagnostic, UnknownFact, WorkflowFact, WorkflowStepFact } from "../types.ts";
+import {
+  defaultExportExpression,
+  isLocallyDeclared,
+  isRecord,
+  relativePath,
+  sortDiagnostics,
+} from "./static-read.ts";
+
+const CORE_SPECIFIER = "@facilis.dev/core";
+const WORKFLOW_DIR = "server/workflows/";
+const STATIC_CODE = "workflow-definition-static";
+
+export interface WorkflowResult {
+  readonly workflows: readonly WorkflowFact[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+/** Read every workflow definition the project declares; invalid files become warnings. */
+export function buildWorkflowFacts(graph: ModuleGraph): WorkflowResult {
+  const workflows: WorkflowFact[] = [];
+  const diagnostics: Diagnostic[] = [];
+  for (const file of graph.files.values()) {
+    const relative = relativePath(graph.root, file.path);
+    if (!relative.startsWith(WORKFLOW_DIR) || relative.endsWith(".test.ts")) continue;
+    scanFile(graph, file, workflows, diagnostics);
+  }
+  return { workflows, diagnostics: sortDiagnostics(diagnostics) };
+}
+
+function scanFile(
+  graph: ModuleGraph,
+  file: ProjectFile,
+  workflows: WorkflowFact[],
+  diagnostics: Diagnostic[],
+): void {
+  const context: StaticContext = { graph, file: file.path };
+  const expression = defaultExportExpression(file);
+  const ref = sourceRef(file.path, file.source, expression?.start ?? 0);
+  const problem = definitionProblem(file, expression);
+  if (problem !== null || expression === undefined || expression.type !== "CallExpression") {
+    diagnostics.push(
+      warning(
+        "workflow-definition",
+        problem ?? "the default export is not a defineWorkflow() call",
+        ref,
+      ),
+    );
+    return;
+  }
+  const literal = objectLiteral(callArguments(expression)[0]);
+  if (literal === undefined) {
+    diagnostics.push(
+      warning("workflow-definition", "the definition argument is not an object literal", ref),
+    );
+    return;
+  }
+  const fields = fieldMap(literal);
+  const name = staticString(fields.get("name"), context);
+  if (name === null) {
+    diagnostics.push(
+      warning("workflow-definition", "the workflow name cannot be read statically", ref),
+    );
+    return;
+  }
+  const unknown: UnknownFact[] = [];
+  const steps = readSteps(fields.get("steps"), context, file.path, file.source, unknown);
+  workflows.push({ name, sourceFile: file.path, source: ref, steps, unknown });
+}
+
+/** The default export must be the `defineWorkflow` import from `@facilis.dev/core`. */
+function definitionProblem(file: ProjectFile, expression: AstNode | undefined): string | null {
+  if (expression === undefined) return "the workflow file has no default export";
+  if (expression.type !== "CallExpression") {
+    return "the default export is not a defineWorkflow() call";
+  }
+  const callee = unwrapExpression(expression.callee);
+  const name = callee?.type === "Identifier" ? identifierName(callee) : undefined;
+  if (name === undefined) return "the defineWorkflow callee cannot be resolved";
+  if (isLocallyDeclared(file, name)) return '"' + name + '" is shadowed by a local declaration';
+  const imported = file.module.imports.find((entry) => entry.local === name);
+  if (
+    imported === undefined ||
+    imported.specifier !== CORE_SPECIFIER ||
+    imported.imported !== "defineWorkflow"
+  ) {
+    return "the default export is not the defineWorkflow import from @facilis.dev/core";
+  }
+  return null;
+}
+
+function readSteps(
+  node: AstNode | undefined,
+  context: StaticContext,
+  file: string,
+  source: string,
+  unknown: UnknownFact[],
+): WorkflowStepFact[] {
+  const array = node === undefined ? undefined : unwrapExpression(node);
+  if (array === undefined || array.type !== "ArrayExpression") {
+    unknown.push({
+      code: STATIC_CODE,
+      reason: "steps must be an array literal",
+      source: sourceRef(file, source, array?.start ?? 0),
+    });
+    return [];
+  }
+  const steps: WorkflowStepFact[] = [];
+  nodeArray(array, "elements").forEach((element, index) => {
+    const ref = sourceRef(file, source, element.start ?? 0);
+    const literal = objectLiteral(element);
+    const fields = literal === undefined ? new Map<string, AstNode>() : fieldMap(literal);
+    const job = fields.get("job");
+    const approval = fields.get("approval");
+    if (job !== undefined) {
+      const name = staticString(job, context);
+      unknownIfNull(unknown, ref, index, "job name", name);
+      steps.push({ index, kind: "job", name, permission: null, onRejectStep: null, source: ref });
+      return;
+    }
+    if (approval !== undefined) {
+      const approvalLiteral = objectLiteral(approval);
+      const approvalFields =
+        approvalLiteral === undefined ? new Map<string, AstNode>() : fieldMap(approvalLiteral);
+      const titleKey = staticString(approvalFields.get("titleKey"), context);
+      const permission = staticString(approvalFields.get("permission"), context);
+      const onRejectStep = rejectStepOf(approvalFields.get("onReject"), context);
+      unknownIfNull(unknown, ref, index, "approval title key", titleKey);
+      steps.push({
+        index,
+        kind: "approval",
+        name: titleKey,
+        permission,
+        onRejectStep,
+        source: ref,
+      });
+      return;
+    }
+    unknown.push({
+      code: STATIC_CODE,
+      reason: "step " + index + " is neither a job nor an approval",
+      source: ref,
+    });
+  });
+  return steps;
+}
+
+function rejectStepOf(node: AstNode | undefined, context: StaticContext): number | null {
+  if (node === undefined) return null;
+  const evaluated = evaluateStatic(node, context);
+  if (!evaluated.ok || !isRecord(evaluated.value)) return null;
+  const step = evaluated.value["step"];
+  return typeof step === "number" && Number.isInteger(step) && step >= 0 ? step : null;
+}
+
+function unknownIfNull(
+  unknown: UnknownFact[],
+  ref: WorkflowFact["source"],
+  index: number,
+  label: string,
+  value: string | null,
+): void {
+  if (value !== null) return;
+  unknown.push({
+    code: STATIC_CODE,
+    reason: "step " + index + ": " + label + " cannot be read statically",
+    source: ref,
+  });
+}
+
+function staticString(node: AstNode | undefined, context: StaticContext): string | null {
+  if (node === undefined) return null;
+  const evaluated = evaluateStatic(node, context);
+  return evaluated.ok && typeof evaluated.value === "string" && evaluated.value.length > 0
+    ? evaluated.value
+    : null;
+}
+
+function objectLiteral(node: AstNode | undefined): AstNode | undefined {
+  const value = node === undefined ? undefined : unwrapExpression(node);
+  return value?.type === "ObjectExpression" ? value : undefined;
+}
+
+function fieldMap(literal: AstNode): Map<string, AstNode> {
+  const fields = new Map<string, AstNode>();
+  for (const entry of objectEntries(literal)) {
+    if (entry.type === "SpreadElement") continue;
+    const key = propertyName(entry);
+    const value = propertyValue(entry);
+    if (key !== undefined && value !== undefined) fields.set(key, value);
+  }
+  return fields;
+}

package/src/path-resolver.ts

@@ -0,0 +1,146 @@
+/** Project-relative path handling and module specifier resolution (no Node APIs). */
+
+export interface PathAlias {
+  readonly prefix: string;
+  readonly target: string;
+}
+
+export interface PathResolverInput {
+  readonly exists: (path: string) => boolean;
+  readonly readJson: (path: string) => unknown;
+  readonly root: string;
+  readonly aliases?: readonly PathAlias[];
+}
+
+export interface PathResolver {
+  resolve(from: string, specifier: string): string | null;
+  tryFile(path: string): string | null;
+}
+
+export const SOURCE_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".mts",
+  ".cts",
+] as const;
+
+export function normalizePath(path: string): string {
+  const parts = path.replace(/\\/g, "/").split("/");
+  const out: string[] = [];
+  for (const part of parts) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") {
+      out.pop();
+      continue;
+    }
+    out.push(part);
+  }
+  return out.join("/");
+}
+
+export function dirname(path: string): string {
+  const index = path.lastIndexOf("/");
+  return index === -1 ? "" : path.slice(0, index);
+}
+
+export function joinPath(base: string, relative: string): string {
+  return normalizePath(base.length === 0 ? relative : base + "/" + relative);
+}
+
+function packageSpecifier(specifier: string): { pkg: string; subpath: string } {
+  const parts = specifier.split("/");
+  if (specifier.startsWith("@")) {
+    return { pkg: parts.slice(0, 2).join("/"), subpath: parts.slice(2).join("/") };
+  }
+  return { pkg: parts[0] ?? specifier, subpath: parts.slice(1).join("/") };
+}
+
+function exportTargets(exports: unknown): string[] {
+  if (typeof exports === "string") return [exports];
+  if (Array.isArray(exports)) return exports.flatMap(exportTargets);
+  if (typeof exports !== "object" || exports === null) return [];
+  const record = exports as Record<string, unknown>;
+  const out: string[] = [];
+  for (const key of ["import", "default", "browser", "node"]) {
+    if (key in record) out.push(...exportTargets(record[key]));
+  }
+  return out;
+}
+
+export function createPathResolver(input: PathResolverInput): PathResolver {
+  const root = normalizePath(input.root);
+  const aliases: PathAlias[] = [
+    { prefix: "~/", target: root },
+    { prefix: "~", target: root },
+    ...(input.aliases ?? []),
+  ];
+
+  const tryFile = (path: string): string | null => {
+    if (input.exists(path)) return path;
+    for (const extension of SOURCE_EXTENSIONS) {
+      if (input.exists(path + extension)) return path + extension;
+    }
+    for (const extension of SOURCE_EXTENSIONS) {
+      const index = joinPath(path, "index" + extension);
+      if (input.exists(index)) return index;
+    }
+    return null;
+  };
+
+  const resolvePackage = (specifier: string): string | null => {
+    const { pkg, subpath } = packageSpecifier(specifier);
+    const prefix = "node_modules/" + pkg;
+    const packageJson = input.readJson(prefix + "/package.json");
+    if (typeof packageJson !== "object" || packageJson === null) return null;
+    const record = packageJson as Record<string, unknown>;
+    if (subpath.length > 0) {
+      const exports = record["exports"];
+      if (typeof exports === "object" && exports !== null) {
+        const entry = (exports as Record<string, unknown>)["./" + subpath];
+        for (const target of exportTargets(entry)) {
+          const resolved = tryFile(joinPath(prefix, target));
+          if (resolved !== null) return resolved;
+        }
+      }
+      return tryFile(joinPath(prefix, subpath));
+    }
+    const exports = record["exports"];
+    if (typeof exports === "object" && exports !== null) {
+      const entry = (exports as Record<string, unknown>)["."];
+      for (const target of exportTargets(entry)) {
+        const resolved = tryFile(joinPath(prefix, target));
+        if (resolved !== null) return resolved;
+      }
+    }
+    for (const target of ["main", "module"]) {
+      const value = record[target];
+      if (typeof value === "string") {
+        const resolved = tryFile(joinPath(prefix, value));
+        if (resolved !== null) return resolved;
+      }
+    }
+    return tryFile(joinPath(prefix, "src/index.ts")) ?? tryFile(joinPath(prefix, "index.ts"));
+  };
+
+  const resolve = (from: string, rawSpecifier: string): string | null => {
+    const specifier = rawSpecifier.trim();
+    if (specifier.length === 0) return null;
+    for (const alias of aliases) {
+      if (specifier === alias.prefix || specifier.startsWith(alias.prefix)) {
+        const rest = specifier.slice(alias.prefix.length);
+        const target = alias.target.length === 0 ? rest : joinPath(alias.target, rest);
+        const resolved = tryFile(target);
+        if (resolved !== null) return resolved;
+      }
+    }
+    if (specifier.startsWith(".")) return tryFile(joinPath(dirname(from), specifier));
+    if (specifier.startsWith("/")) return tryFile(normalizePath(specifier));
+    return resolvePackage(specifier);
+  };
+
+  return { resolve, tryFile };
+}

package/src/revision.ts

@@ -0,0 +1,25 @@
+import { normalizePath } from "./path-resolver.ts";
+
+/** Deterministic, browser-safe revision of the analyzed file set. */
+export function computeRevision(files: ReadonlyMap<string, string>): string {
+  const entries = [...files]
+    .map(([path, source]) => [normalizePath(path), source] as const)
+    .toSorted(([left], [right]) => left.localeCompare(right));
+  let hash = 0x811c9dc5;
+  for (const [path, source] of entries) {
+    hash = mix(hash, path);
+    hash = mix(hash, "\u0000");
+    hash = mix(hash, source);
+    hash = mix(hash, "\u0001");
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+function mix(hash: number, value: string): number {
+  let next = hash;
+  for (let index = 0; index < value.length; index += 1) {
+    next ^= value.charCodeAt(index);
+    next = Math.imul(next, 0x01000193) >>> 0;
+  }
+  return next;
+}

package/src/source.ts

@@ -0,0 +1,15 @@
+import type { SourceRef } from "./types.ts";
+
+/** 1-based line number of a source offset. */
+export function lineOf(source: string, offset: number): number {
+  let line = 1;
+  const end = Math.min(Math.max(offset, 0), source.length);
+  for (let index = 0; index < end; index += 1) {
+    if (source.charCodeAt(index) === 10) line += 1;
+  }
+  return line;
+}
+
+export function sourceRef(file: string, source: string, offset: number): SourceRef {
+  return { file, line: lineOf(source, offset) };
+}

package/src/static-eval.ts

@@ -0,0 +1,242 @@
+import {
+  asNode,
+  identifierName,
+  literalString,
+  memberName,
+  nodeArray,
+  objectEntries,
+  propertyName,
+  propertyValue,
+  unwrapExpression,
+  type AstNode,
+} from "./ast/node.ts";
+import { defaultExportDeclaration, localInitializer } from "./module-info.ts";
+import type { ModuleGraph } from "./module-graph.ts";
+
+export type StaticEvaluation =
+  { readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly reason: string };
+
+export interface StaticContext {
+  readonly graph: ModuleGraph;
+  readonly file: string;
+}
+
+const MAX_DEPTH = 16;
+
+function fail(reason: string): StaticEvaluation {
+  return { ok: false, reason };
+}
+
+function fromValue(value: unknown): StaticEvaluation {
+  return { ok: true, value };
+}
+
+/**
+ * Evaluate the static subset (docs/findings/ast-dsl-contract.md §4): literals, arrays,
+ * objects, templates without dynamic parts, same-file consts and one-hop project imports.
+ * Never executes code; anything else fails and the caller records an unknown fact.
+ */
+export function evaluateStatic(
+  node: AstNode | undefined,
+  context: StaticContext,
+  depth = 0,
+): StaticEvaluation {
+  if (node === undefined) return fail("missing value");
+  if (depth > MAX_DEPTH) return fail("static evaluation is too deep or cyclic");
+  const unwrapped = unwrapExpression(node) ?? node;
+  switch (unwrapped.type) {
+    case "Literal":
+      return "value" in unwrapped ? fromValue(unwrapped.value) : fail("unsupported literal");
+    case "TemplateLiteral":
+      return evaluateTemplate(unwrapped, context, depth);
+    case "ArrayExpression":
+      return evaluateArray(unwrapped, context, depth);
+    case "ObjectExpression":
+      return evaluateObject(unwrapped, context, depth);
+    case "UnaryExpression":
+      return evaluateUnary(unwrapped, context, depth);
+    case "BinaryExpression":
+      return evaluateBinary(unwrapped, context, depth);
+    case "MemberExpression":
+      return evaluateMember(unwrapped, context, depth);
+    case "Identifier":
+      return evaluateIdentifier(unwrapped, context, depth);
+    default:
+      return fail('"' + unwrapped.type + '" is not in the static subset');
+  }
+}
+
+function evaluateIdentifier(
+  node: AstNode,
+  context: StaticContext,
+  depth: number,
+): StaticEvaluation {
+  const name = identifierName(node);
+  if (name === undefined) return fail("missing identifier name");
+  if (name === "undefined") return fromValue(undefined);
+  const current = context.graph.file(context.file);
+  if (current === undefined) return fail("unknown file " + context.file);
+  const local = localInitializer(current.program, name);
+  if (local !== undefined) return evaluateStatic(local, context, depth + 1);
+  const binding = context.graph.resolveBinding(context.file, name);
+  if (binding === null) return fail('cannot resolve "' + name + '" statically');
+  const target = context.graph.file(binding.file);
+  if (target === undefined) return fail("unknown module " + binding.file);
+  if (binding.name === "default") {
+    const declaration = defaultExportDeclaration(target.program);
+    if (declaration === undefined) return fail("module has no default export");
+    return evaluateStatic(declaration, { graph: context.graph, file: target.path }, depth + 1);
+  }
+  const initializer = localInitializer(target.program, binding.name);
+  if (initializer === undefined) return fail('cannot resolve "' + binding.name + '" statically');
+  return evaluateStatic(initializer, { graph: context.graph, file: target.path }, depth + 1);
+}
+
+function evaluateTemplate(node: AstNode, context: StaticContext, depth: number): StaticEvaluation {
+  const quasis = nodeArray(node, "quasis");
+  const expressions = nodeArray(node, "expressions");
+  let out = "";
+  for (const [index, quasi] of quasis.entries()) {
+    // TemplateElement.value is a plain { raw, cooked } record, not an AST node.
+    const value = quasi?.value as { cooked?: unknown } | undefined;
+    const cooked = value?.cooked;
+    out += typeof cooked === "string" ? cooked : "";
+    const expression = expressions[index];
+    if (expression === undefined) continue;
+    const evaluated = evaluateStatic(expression, context, depth + 1);
+    if (!evaluated.ok) return evaluated;
+    if (
+      typeof evaluated.value !== "string" &&
+      typeof evaluated.value !== "number" &&
+      typeof evaluated.value !== "boolean"
+    ) {
+      return fail("template interpolation is not a primitive");
+    }
+    out += String(evaluated.value);
+  }
+  return fromValue(out);
+}
+
+function evaluateArray(node: AstNode, context: StaticContext, depth: number): StaticEvaluation {
+  const out: unknown[] = [];
+  for (const element of nodeArray(node, "elements")) {
+    const evaluated = evaluateStatic(element, context, depth + 1);
+    if (!evaluated.ok) return evaluated;
+    out.push(evaluated.value);
+  }
+  return fromValue(out);
+}
+
+function evaluateObject(node: AstNode, context: StaticContext, depth: number): StaticEvaluation {
+  const out: Record<string, unknown> = {};
+  for (const entry of objectEntries(node)) {
+    if (entry.type === "SpreadElement") {
+      const argument = asNode(entry.argument);
+      const spread = evaluateStatic(argument, context, depth + 1);
+      if (!spread.ok) return spread;
+      if (typeof spread.value !== "object" || spread.value === null) {
+        return fail("object spread is not an object literal");
+      }
+      Object.assign(out, spread.value);
+      continue;
+    }
+    const key = propertyName(entry);
+    if (key === undefined) return fail("computed object key is not in the static subset");
+    const evaluated = evaluateStatic(propertyValue(entry), context, depth + 1);
+    if (!evaluated.ok) return evaluated;
+    out[key] = evaluated.value;
+  }
+  return fromValue(out);
+}
+
+function evaluateUnary(node: AstNode, context: StaticContext, depth: number): StaticEvaluation {
+  const argument = asNode(node.argument);
+  const evaluated = evaluateStatic(argument, context, depth + 1);
+  if (!evaluated.ok) return evaluated;
+  if (node.operator === "-" && typeof evaluated.value === "number") {
+    return fromValue(-evaluated.value);
+  }
+  if (node.operator === "!" && typeof evaluated.value === "boolean") {
+    return fromValue(!evaluated.value);
+  }
+  return fail("unsupported unary expression");
+}
+
+const NUMERIC_OPERATORS = new Set(["+", "-", "*", "/", "%"]);
+
+function evaluateBinary(node: AstNode, context: StaticContext, depth: number): StaticEvaluation {
+  const operator = node.operator;
+  if (typeof operator !== "string" || !NUMERIC_OPERATORS.has(operator)) {
+    return fail("unsupported binary expression");
+  }
+  const left = evaluateStatic(asNode(node.left), context, depth + 1);
+  if (!left.ok) return left;
+  const right = evaluateStatic(asNode(node.right), context, depth + 1);
+  if (!right.ok) return right;
+  if (operator === "+" && (typeof left.value === "string" || typeof right.value === "string")) {
+    if (typeof left.value !== "string" && typeof left.value !== "number") {
+      return fail("binary + operands are not primitives");
+    }
+    if (typeof right.value !== "string" && typeof right.value !== "number") {
+      return fail("binary + operands are not primitives");
+    }
+    return fromValue(String(left.value) + String(right.value));
+  }
+  if (typeof left.value !== "number" || typeof right.value !== "number") {
+    return fail("binary " + operator + " operands are not numbers");
+  }
+  switch (operator) {
+    case "+":
+      return fromValue(left.value + right.value);
+    case "-":
+      return fromValue(left.value - right.value);
+    case "*":
+      return fromValue(left.value * right.value);
+    case "/":
+      return fromValue(left.value / right.value);
+    case "%":
+      return fromValue(left.value % right.value);
+    default:
+      return fail("unsupported binary expression");
+  }
+}
+
+function evaluateMember(node: AstNode, context: StaticContext, depth: number): StaticEvaluation {
+  const name = memberName(node);
+  if (name === undefined) return fail("unsupported member expression");
+  const object = evaluateStatic(asNode(node.object), context, depth + 1);
+  if (!object.ok) return object;
+  if (typeof object.value !== "object" || object.value === null) {
+    return fail("member access on a non-object");
+  }
+  const record = object.value as Record<string, unknown>;
+  return Object.hasOwn(record, name) ? fromValue(record[name]) : fail("missing property " + name);
+}
+
+/** Convenience: a string or undefined, with the failure reason. */
+export function staticString(
+  node: AstNode | undefined,
+  context: StaticContext,
+): { ok: true; value: string } | { ok: false; reason: string } {
+  const evaluated = evaluateStatic(node, context);
+  if (!evaluated.ok) return evaluated;
+  return typeof evaluated.value === "string"
+    ? { ok: true, value: evaluated.value }
+    : { ok: false, reason: "expected a string literal" };
+}
+
+/** Convenience: a string[] or undefined, with the failure reason. */
+export function staticStringArray(
+  node: AstNode | undefined,
+  context: StaticContext,
+): { ok: true; value: string[] } | { ok: false; reason: string } {
+  const evaluated = evaluateStatic(node, context);
+  if (!evaluated.ok) return evaluated;
+  if (!Array.isArray(evaluated.value)) return { ok: false, reason: "expected a string[] literal" };
+  if (!evaluated.value.every((item): item is string => typeof item === "string")) {
+    return { ok: false, reason: "expected a string[] literal" };
+  }
+  return { ok: true, value: [...evaluated.value] };
+}
+
+export { literalString };