@facilis.dev/analyze 0.0.0-stage → 0.1.1

package/src/module-info.ts

@@ -0,0 +1,162 @@
+import { identifierName, isAstNode, literalString, nodeArray, type AstNode } from "./ast/node.ts";
+import type { SourceRef } from "./types.ts";
+
+export interface ImportBinding {
+  readonly specifier: string;
+  readonly imported: string | null;
+  readonly local: string;
+  readonly kind: "named" | "default" | "namespace";
+  readonly source: SourceRef;
+}
+
+export interface ExportBinding {
+  readonly exported: string;
+  readonly local: string | null;
+  readonly source: string | null;
+  readonly imported: string | null;
+  readonly kind: "named" | "default" | "reexport" | "all";
+  readonly ref: SourceRef;
+}
+
+export interface ModuleInfo {
+  readonly imports: readonly ImportBinding[];
+  readonly exports: readonly ExportBinding[];
+}
+
+function refOf(file: string, source: string, node: AstNode): SourceRef {
+  const offset = typeof node.start === "number" ? node.start : 0;
+  let line = 1;
+  for (let index = 0; index < offset && index < source.length; index += 1) {
+    if (source.charCodeAt(index) === 10) line += 1;
+  }
+  return { file, line };
+}
+
+function importBindings(file: string, source: string, program: AstNode): ImportBinding[] {
+  const out: ImportBinding[] = [];
+  for (const statement of nodeArray(program, "body")) {
+    if (statement.type !== "ImportDeclaration") continue;
+    const specifier = literalString(statement.source);
+    if (specifier === undefined) continue;
+    const ref = refOf(file, source, statement);
+    for (const item of nodeArray(statement, "specifiers")) {
+      if (item.type === "ImportDefaultSpecifier") {
+        const local = identifierName(item.local);
+        if (local !== undefined) {
+          out.push({ specifier, imported: "default", local, kind: "default", source: ref });
+        }
+      } else if (item.type === "ImportNamespaceSpecifier") {
+        const local = identifierName(item.local);
+        if (local !== undefined) {
+          out.push({ specifier, imported: null, local, kind: "namespace", source: ref });
+        }
+      } else if (item.type === "ImportSpecifier") {
+        const local = identifierName(item.local);
+        const imported = identifierName(item.imported) ?? literalString(item.imported);
+        if (local !== undefined && imported !== undefined) {
+          out.push({ specifier, imported, local, kind: "named", source: ref });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+export function declarationNames(declaration: AstNode): string[] {
+  if (declaration.type === "VariableDeclaration") {
+    return nodeArray(declaration, "declarations")
+      .map((item) => identifierName(item.id))
+      .filter((name): name is string => name !== undefined);
+  }
+  if (declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration") {
+    const name = identifierName(declaration.id);
+    return name === undefined ? [] : [name];
+  }
+  return [];
+}
+
+function exportBindings(file: string, source: string, program: AstNode): ExportBinding[] {
+  const out: ExportBinding[] = [];
+  for (const statement of nodeArray(program, "body")) {
+    const ref = refOf(file, source, statement);
+    if (statement.type === "ExportDefaultDeclaration") {
+      const declaration = isAstNode(statement.declaration) ? statement.declaration : undefined;
+      const local = declaration === undefined ? null : (identifierName(declaration) ?? null);
+      out.push({ exported: "default", local, source: null, imported: null, kind: "default", ref });
+      continue;
+    }
+    if (statement.type === "ExportAllDeclaration") {
+      const specifier = literalString(statement.source);
+      if (specifier !== undefined) {
+        out.push({
+          exported: "*",
+          local: null,
+          source: specifier,
+          imported: null,
+          kind: "all",
+          ref,
+        });
+      }
+      continue;
+    }
+    if (statement.type !== "ExportNamedDeclaration") continue;
+    const declaration = isAstNode(statement.declaration) ? statement.declaration : undefined;
+    if (declaration !== undefined) {
+      for (const name of declarationNames(declaration)) {
+        out.push({ exported: name, local: name, source: null, imported: null, kind: "named", ref });
+      }
+    }
+    const from = literalString(statement.source);
+    for (const item of nodeArray(statement, "specifiers")) {
+      if (item.type !== "ExportSpecifier") continue;
+      const exported = identifierName(item.exported) ?? literalString(item.exported);
+      const local = identifierName(item.local) ?? literalString(item.local);
+      if (exported === undefined || local === undefined) continue;
+      out.push({
+        exported,
+        local: from === undefined ? local : null,
+        source: from ?? null,
+        imported: from === undefined ? null : local,
+        kind: from === undefined ? "named" : "reexport",
+        ref,
+      });
+    }
+  }
+  return out;
+}
+
+export function parseModuleInfo(file: string, source: string, program: AstNode): ModuleInfo {
+  return {
+    imports: importBindings(file, source, program),
+    exports: exportBindings(file, source, program),
+  };
+}
+
+/** The declaration of "export default ...", unwrapped from the export statement. */
+export function defaultExportDeclaration(program: AstNode): AstNode | undefined {
+  for (const statement of nodeArray(program, "body")) {
+    if (statement.type !== "ExportDefaultDeclaration") continue;
+    return isAstNode(statement.declaration) ? statement.declaration : undefined;
+  }
+  return undefined;
+}
+
+/** The initializer of a top-level const/let/var binding, when declared exactly once. */
+export function localInitializer(program: AstNode, name: string): AstNode | undefined {
+  let found: AstNode | undefined;
+  for (const statement of nodeArray(program, "body")) {
+    const declaration =
+      statement.type === "VariableDeclaration"
+        ? statement
+        : statement.type === "ExportNamedDeclaration" && isAstNode(statement.declaration)
+          ? statement.declaration
+          : undefined;
+    if (declaration === undefined || declaration.type !== "VariableDeclaration") continue;
+    for (const item of nodeArray(declaration, "declarations")) {
+      if (identifierName(item.id) !== name) continue;
+      if (found !== undefined) return undefined;
+      found = isAstNode(item.init) ? item.init : undefined;
+    }
+  }
+  return found;
+}

package/src/node.ts

@@ -0,0 +1,54 @@
+import { parseSync } from "oxc-parser";
+
+import { analyzeProject, type AnalyzeInput } from "./analyze.ts";
+import { asNode } from "./ast/node.ts";
+import type { PathAlias } from "./path-resolver.ts";
+import { loadProjectFiles, type LoadProjectOptions } from "./fs.ts";
+import type { ParseError, Parser } from "./parser.ts";
+import { lineOf } from "./source.ts";
+import type { Analysis } from "./types.ts";
+
+/** Node/CI parser adapter. The browser uses a wasm adapter over the same contract. */
+export function createOxcParser(): Parser {
+  return {
+    parse(filename: string, source: string) {
+      const result = parseSync(filename, source, {
+        astType: "ts",
+        sourceType: "module",
+        preserveParens: true,
+      });
+      const program = asNode(result.program as unknown);
+      if (program === undefined) throw new Error("oxc-parser returned no program");
+      const errors: ParseError[] = result.errors.map((error) => {
+        const label = error.labels[0];
+        const start = label === undefined ? null : label.start;
+        return {
+          message: error.message,
+          start,
+          end: label === undefined ? null : label.end,
+          source: { file: filename, line: start === null ? 1 : lineOf(source, start) },
+        };
+      });
+      return { program, errors };
+    },
+  };
+}
+
+export interface AnalyzeDirectoryOptions {
+  readonly aliases?: readonly PathAlias[];
+  readonly transport?: AnalyzeInput["transport"];
+  readonly load?: LoadProjectOptions;
+}
+
+export { loadProjectFiles } from "./fs.ts";
+export type { LoadProjectOptions } from "./fs.ts";
+
+/** Convenience for Node/CI: load a directory and analyze it. The browser passes its own map. */
+export function analyzeDirectory(root: string, options: AnalyzeDirectoryOptions = {}): Analysis {
+  return analyzeProject({
+    files: loadProjectFiles(root, options.load),
+    parser: createOxcParser(),
+    ...(options.aliases === undefined ? {} : { aliases: options.aliases }),
+    ...(options.transport === undefined ? {} : { transport: options.transport }),
+  });
+}

package/src/parser.ts

@@ -0,0 +1,19 @@
+import type { AstNode } from "./ast/node.ts";
+import type { SourceRef } from "./types.ts";
+
+export interface ParseError {
+  readonly message: string;
+  readonly start: number | null;
+  readonly end: number | null;
+  readonly source: SourceRef;
+}
+
+export interface ParsedModule {
+  readonly program: AstNode;
+  readonly errors: readonly ParseError[];
+}
+
+/** Injected parser contract: the analyzer never imports a parser package itself. */
+export interface Parser {
+  parse(filename: string, source: string): ParsedModule;
+}

package/src/passes/clients.ts

@@ -0,0 +1,233 @@
+/**
+ * Client consumers -> PageFacts and page→route edges (§3.4 of the AST DSL contract).
+ *
+ * Exactly one transport is sanctioned (`api()` from `src/lib/api.ts` by default): the
+ * transport export is resolved through imports (aliases and namespace imports included) and
+ * every other network call in `src/**` is a `client-transport` error. The transport module
+ * itself is the only place allowed to call `fetch`, so it is not scanned as a consumer.
+ */
+
+import {
+  callArguments,
+  identifierName,
+  memberName,
+  unwrapExpression,
+  type AstNode,
+} from "../ast/node.ts";
+import { walk } from "../ast/walk.ts";
+import { error, warning } from "../diagnostics.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import type { StaticContext } from "../static-eval.ts";
+import type {
+  Diagnostic,
+  HttpMethod,
+  PageFact,
+  PageKind,
+  RouteCallFact,
+  RouteFact,
+  SourceRef,
+  UnknownFact,
+} from "../types.ts";
+import { extractPathExpression, matchRouteIds } from "./path-expression.ts";
+import {
+  projectPath,
+  readStaticObject,
+  relativePath,
+  refOf,
+  sortDiagnostics,
+} from "./static-read.ts";
+
+const SRC_DIR = "src/";
+const HTTP_METHODS = new Set([
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD",
+  "OPTIONS",
+  "TRACE",
+  "CONNECT",
+]);
+const NETWORK_CALLEES = new Set(["fetch", "axios", "ky", "got"]);
+
+export interface TransportSpec {
+  /** Project-relative module, e.g. `src/lib/api.ts`. */
+  readonly module: string;
+  /** Exported function that performs API calls, e.g. `api`. */
+  readonly exportName: string;
+}
+
+export interface ClientResult {
+  readonly pages: readonly PageFact[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+interface TransportBindings {
+  readonly names: ReadonlySet<string>;
+  readonly namespaces: ReadonlySet<string>;
+}
+
+function transportBindings(
+  graph: ModuleGraph,
+  file: ProjectFile,
+  transportPath: string,
+  exportName: string,
+): TransportBindings {
+  const names = new Set<string>();
+  const namespaces = new Set<string>();
+  for (const imported of file.module.imports) {
+    if (graph.resolve(file.path, imported.specifier) !== transportPath) continue;
+    if (imported.kind === "namespace") namespaces.add(imported.local);
+    else if ((imported.imported ?? "default") === exportName) names.add(imported.local);
+  }
+  return { names, namespaces };
+}
+
+function isTransportCall(call: AstNode, bindings: TransportBindings, exportName: string): boolean {
+  const callee = unwrapExpression(call.callee);
+  const direct = identifierName(callee);
+  if (direct !== undefined) return bindings.names.has(direct);
+  if (callee?.type !== "MemberExpression") return false;
+  const objectName = identifierName(unwrapExpression(callee.object));
+  return (
+    objectName !== undefined &&
+    bindings.namespaces.has(objectName) &&
+    memberName(callee) === exportName
+  );
+}
+
+/** Name of a network call that is not the transport, or null when the node is not one. */
+function networkCallName(node: AstNode): string | null {
+  if (node.type === "NewExpression") {
+    return identifierName(unwrapExpression(node.callee)) === "XMLHttpRequest"
+      ? "XMLHttpRequest"
+      : null;
+  }
+  if (node.type !== "CallExpression") return null;
+  const callee = unwrapExpression(node.callee);
+  const direct = identifierName(callee);
+  if (direct !== undefined && NETWORK_CALLEES.has(direct)) return direct;
+  if (callee?.type !== "MemberExpression") return null;
+  const objectName = identifierName(unwrapExpression(callee.object));
+  return objectName !== undefined && NETWORK_CALLEES.has(objectName) ? objectName : null;
+}
+
+interface MethodResult {
+  readonly method: HttpMethod;
+  readonly unknown: UnknownFact | null;
+}
+
+/** The request method comes from the second argument's static `method`, else GET. */
+function requestMethod(
+  init: AstNode | undefined,
+  context: StaticContext,
+  callRef: SourceRef,
+): MethodResult {
+  if (init === undefined) return { method: "GET", unknown: null };
+  const object = readStaticObject(init, context, { code: "page-path-static", report: false });
+  const field = object.fields.get("method");
+  if (field !== undefined && field.ok && typeof field.value === "string") {
+    const method = field.value.toUpperCase();
+    if (HTTP_METHODS.has(method)) return { method: method as HttpMethod, unknown: null };
+  }
+  // An unreadable options object hides the method; defaulting silently could produce a wrong
+  // page→route edge, so the assumption is recorded as unknown.
+  const unknown: UnknownFact | null =
+    field === undefined && object.unknown.length === 0
+      ? null
+      : {
+          code: "page-path-static",
+          reason: "the request method cannot be read statically; assuming GET",
+          source: callRef,
+        };
+  return { method: "GET", unknown };
+}
+
+function pageKind(relative: string): PageKind {
+  if (relative.startsWith("src/pages/")) return "page";
+  if (relative.startsWith("src/components/")) return "component";
+  if (relative.startsWith("src/lib/")) return "lib";
+  return "other";
+}
+
+function scanPage(
+  graph: ModuleGraph,
+  file: ProjectFile,
+  routes: readonly RouteFact[],
+  transportPath: string,
+  exportName: string,
+): { page: PageFact; diagnostics: readonly Diagnostic[] } {
+  const context: StaticContext = { graph, file: file.path };
+  const bindings = transportBindings(graph, file, transportPath, exportName);
+  const calls: RouteCallFact[] = [];
+  const diagnostics: Diagnostic[] = [];
+
+  walk(file.program, (node) => {
+    if (node.type !== "CallExpression" && node.type !== "NewExpression") return;
+    const transport = node.type === "CallExpression" && isTransportCall(node, bindings, exportName);
+    const network = transport ? null : networkCallName(node);
+    if (!transport && network === null) return;
+
+    const callRef = refOf(context, node);
+    const args = node.type === "CallExpression" ? callArguments(node) : [];
+    const extracted = extractPathExpression(args[0], context, node, "page-path-static");
+    const method = requestMethod(args[1], context, callRef);
+    const unknown: UnknownFact[] = [...extracted.unknown];
+    if (method.unknown !== null) unknown.push(method.unknown);
+
+    if (transport && extracted.path === null && extracted.staticPrefix === null) {
+      diagnostics.push(
+        warning("page-path-static", "the API path cannot be resolved statically", callRef),
+      );
+    }
+    if (!transport && network !== null) {
+      const reason = network + " outside the sanctioned transport module is not allowed";
+      unknown.push({ code: "client-transport", reason, source: callRef });
+      diagnostics.push(error("client-transport", reason, callRef));
+    }
+
+    calls.push({
+      expression: extracted.expression,
+      kind: extracted.kind,
+      staticPrefix: extracted.staticPrefix,
+      matchedRouteIds: matchRouteIds(routes, extracted.path, extracted.staticPrefix, method.method),
+      source: callRef,
+      unknown,
+    });
+  });
+
+  const page: PageFact = {
+    path: file.path,
+    kind: pageKind(relativePath(graph.root, file.path)),
+    calls,
+    source: { file: file.path, line: 1 },
+    unknown: [],
+  };
+  return { page, diagnostics };
+}
+
+/** Map client files to the routes they call. */
+export function buildPageFacts(
+  graph: ModuleGraph,
+  routes: readonly RouteFact[],
+  transport: TransportSpec,
+): ClientResult {
+  const transportPath = projectPath(graph.root, transport.module);
+  const files = [...graph.files.values()]
+    .filter((file) => {
+      const relative = relativePath(graph.root, file.path);
+      if (!relative.startsWith(SRC_DIR)) return false;
+      if (relative.includes(".test.")) return false;
+      return file.path !== transportPath;
+    })
+    .toSorted((left, right) => left.path.localeCompare(right.path));
+  const pages: PageFact[] = [];
+  const diagnostics: Diagnostic[] = [];
+  for (const file of files) {
+    const scanned = scanPage(graph, file, routes, transportPath, transport.exportName);
+    pages.push(scanned.page);
+    diagnostics.push(...scanned.diagnostics);
+  }
+  return { pages, diagnostics: sortDiagnostics(diagnostics) };
+}