@facilis.dev/analyze 0.0.0-stage → 0.1.1

package/dist/types-relations.js

@@ -0,0 +1,11 @@
+// Route relation-usage and view facts (D-157), split from types.ts so the base fact model
+// stays under the 300-line source limit. A fact that cannot be determined is explicit:
+// an empty usage is "nothing observed", never "nothing to check".
+/** Usage of a route the pass cannot scan (invalid wrapper): explicitly empty, not unknown. */
+export const EMPTY_ROUTE_RELATIONS = {
+    used: [],
+    unresolved: [],
+    rawSql: [],
+    opaque: false,
+    elevations: [],
+};

package/dist/types-workflows.d.ts

@@ -0,0 +1,36 @@
+import type { SourceRef, UnknownFact } from "./types.js";
+/** One step of a `defineWorkflow` chain, as the static subset reads it. */
+export interface WorkflowStepFact {
+    readonly index: number;
+    readonly kind: "job" | "approval";
+    /** Job name for a job step, approval title key for an approval step. */
+    readonly name: string | null;
+    /** Approval assignment permission, when the definition declares one. */
+    readonly permission: string | null;
+    /** Forward step index declared by `onReject.step`, when present. */
+    readonly onRejectStep: number | null;
+    readonly source: SourceRef;
+}
+/** One `server/workflows/**` definition. */
+export interface WorkflowFact {
+    readonly name: string;
+    readonly sourceFile: string;
+    readonly source: SourceRef;
+    readonly steps: readonly WorkflowStepFact[];
+    readonly unknown: readonly UnknownFact[];
+}
+/**
+ * Table surface of a workflow, derived from the jobs its steps reference (never declared):
+ * the sorted union of the referenced jobs' own `dbTables` (tables and views alike).
+ */
+export interface WorkflowTablesFact {
+    readonly name: string;
+    readonly sourceFile: string;
+    readonly source: SourceRef;
+    /** Sorted unique union of the referenced jobs' declared dbTables. */
+    readonly tables: readonly string[];
+    /** Job-step names with no definition under `server/jobs/**`; [] when all resolve. */
+    readonly unknownJobs: readonly string[];
+    /** True when a referenced job's dbTables is unreadable, so the union is incomplete. */
+    readonly unknown: boolean;
+}

package/dist/types-workflows.js

@@ -0,0 +1,3 @@
+// Workflow fact shapes, split from types.ts so the base fact model stays under the 300-line
+// source limit (D-135 W3). They are re-exported from types.ts, so existing imports keep working.
+export {};

package/dist/types.d.ts

@@ -0,0 +1,226 @@
+import type { JobFact, JobRelationsFact } from "./types-jobs.js";
+import type { RouteRelationsFact, ViewFact } from "./types-relations.js";
+import type { ProjectGraph } from "./types-graph.js";
+import type { WorkflowFact, WorkflowTablesFact } from "./types-workflows.js";
+/**
+ * Fact model of the AST analyzer (docs/findings/ast-dsl-contract.md).
+ *
+ * Facts are parser-independent and always carry their source. A fact that cannot be
+ * determined is represented explicitly (null or an unknown entry), never as an empty value:
+ * in particular "dbTables unknown" (null) is not "no DB tables" ([]).
+ */
+export interface SourceRef {
+    readonly file: string;
+    readonly line: number;
+}
+export interface UnknownFact {
+    readonly code: string;
+    readonly reason: string;
+    readonly source: SourceRef;
+}
+export type Severity = "error" | "warning" | "info";
+export interface Diagnostic {
+    readonly code: string;
+    readonly severity: Severity;
+    readonly message: string;
+    readonly source: SourceRef | null;
+}
+export interface LocaleCatalogs {
+    readonly [locale: string]: Readonly<Record<string, string>>;
+}
+export interface ConfigFacts {
+    readonly parsed: boolean;
+    readonly source: SourceRef | null;
+    readonly permissions: readonly string[];
+    readonly roles: Readonly<Record<string, readonly string[]>>;
+    readonly defaultRole: string | null;
+    readonly defaultLocale: string | null;
+    readonly locales: readonly string[];
+    readonly migrationsDir: string;
+    readonly tenantColumns: readonly string[];
+    readonly ownerColumns: readonly string[];
+    readonly unknown: readonly UnknownFact[];
+}
+export type ColumnDefaultKind = "literal" | "now" | "random" | "unknown";
+export interface ColumnDefaultFact {
+    readonly kind: ColumnDefaultKind;
+    readonly value: string | null;
+}
+export interface ForeignKeyFact {
+    readonly columns: readonly string[];
+    readonly targetTable: string;
+    readonly targetColumns: readonly string[];
+    readonly onDelete: string | null;
+    readonly onUpdate: string | null;
+    readonly source: SourceRef;
+}
+export interface ColumnFact {
+    /** Drizzle property key in the table object (the dbColumns domain). */
+    readonly property: string;
+    /** SQL column name (first literal argument of the builder, or the property key). */
+    readonly name: string;
+    readonly builder: string;
+    /** Display type derived from the builder and its arguments. */
+    readonly type: string;
+    readonly notNull: boolean;
+    readonly primaryKey: boolean;
+    readonly unique: boolean;
+    readonly default: ColumnDefaultFact | null;
+    readonly source: SourceRef;
+    readonly unknown: readonly UnknownFact[];
+}
+export type PolicyCommand = "SELECT" | "INSERT" | "UPDATE" | "DELETE" | "ALL";
+export interface PolicyFact {
+    readonly name: string;
+    readonly command: PolicyCommand;
+    readonly restrictive: boolean;
+    readonly source: SourceRef;
+    readonly unknown: readonly UnknownFact[];
+}
+export interface ScopeFact {
+    readonly column: string;
+    readonly kind: "tenant" | "owner";
+}
+export interface TableFact {
+    readonly name: string;
+    /** TypeScript binding holding the table, when declared as a const. */
+    readonly binding: string | null;
+    readonly columns: readonly ColumnFact[];
+    readonly primaryKey: readonly string[];
+    readonly foreignKeys: readonly ForeignKeyFact[];
+    readonly policies: readonly PolicyFact[];
+    readonly rlsEnabled: boolean;
+    readonly scope: ScopeFact | null;
+    readonly source: SourceRef;
+    readonly unknown: readonly UnknownFact[];
+}
+export interface RelationFact {
+    readonly from: string;
+    readonly to: string;
+    readonly cardinality: "one" | "many";
+    readonly fields: readonly string[];
+    readonly references: readonly string[];
+    readonly source: SourceRef;
+    readonly unknown: readonly UnknownFact[];
+}
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT" | "ALL";
+export type WrapperState = "valid" | "invalid" | "unknown";
+export interface RouteInputFact {
+    readonly body: boolean;
+    /** A multipart/form-data schema (D-053); mutually exclusive with `body`. */
+    readonly form: boolean;
+    readonly query: boolean;
+    readonly params: boolean;
+}
+export type ElevationKind = "sudo" | "system";
+/** One audited elevation call in a route handler (D-099): `ctx.sudo` / `ctx.system`. */
+export interface ElevationFact {
+    readonly kind: ElevationKind;
+    /** Tables passed to the elevation; [] when the array cannot be read statically. */
+    readonly tables: readonly string[];
+    /** The audit operation label, when statically readable. */
+    readonly operation: string | null;
+    readonly source: SourceRef;
+    readonly unknown: readonly UnknownFact[];
+}
+export interface RouteFact {
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly sourceFile: string;
+    readonly source: SourceRef;
+    readonly wrapper: WrapperState;
+    /** null = unknown; [] = explicitly public. */
+    readonly permission: readonly string[] | null;
+    /**
+     * True when the wrapper declares the route callable from another origin; false when absent;
+     * null when the declaration cannot be read statically (a cross-origin route is never assumed).
+     */
+    readonly crossSite: boolean | null;
+    /** null = unknown; [] = explicitly no DB. */
+    readonly dbTables: readonly string[] | null;
+    /** null = unknown; [] = explicitly no columns. */
+    readonly dbColumns: readonly string[] | null;
+    /** rawSql: true allows `db.execute` (D-157); false when absent; null when unreadable. */
+    readonly rawSql: boolean | null;
+    /** Static db usage of the handler, project-local helper calls followed (D-157). */
+    readonly relations: RouteRelationsFact;
+    readonly description: string | null;
+    readonly input: RouteInputFact;
+    /** True when the handler body reads the request body (SPEC §9.3 rule 8). */
+    readonly handlerBodyRead: boolean;
+    /** True when the handler body reads the multipart form (SPEC §9.3 rule 8, D-053). */
+    readonly handlerFormRead: boolean;
+    /** Audited elevation calls in the handler, in source order. */
+    readonly elevations: readonly ElevationFact[];
+    readonly unknown: readonly UnknownFact[];
+}
+export type ImportKind = "named" | "default" | "namespace" | "side-effect" | "export-from" | "dynamic" | "require";
+/** One module reference of a source file: static import, re-export, dynamic import or require. */
+export interface ImportFact {
+    readonly specifier: string;
+    readonly kind: ImportKind;
+    /** Local binding the reference introduces; null for side-effect/re-export/dynamic forms. */
+    readonly local: string | null;
+    /** Imported name for named imports ("default" for a default import); null otherwise. */
+    readonly imported: string | null;
+    readonly source: SourceRef;
+}
+/** One literal `t("key")` call; interpolated keys are skipped because they are not static. */
+export interface TranslationCallFact {
+    readonly key: string;
+    readonly source: SourceRef;
+}
+/** One call to a bare identifier (`drizzle(...)`, `t(...)`): enough for the security rules. */
+export interface CallFact {
+    readonly name: string;
+    readonly source: SourceRef;
+}
+export interface FileFacts {
+    /** Project-relative path of the parsed source file. */
+    readonly path: string;
+    readonly imports: readonly ImportFact[];
+    readonly translationCalls: readonly TranslationCallFact[];
+    readonly calls: readonly CallFact[];
+}
+export type PageKind = "page" | "component" | "lib" | "other";
+export type PathKind = "literal" | "concat" | "template" | "builder" | "dynamic" | "unknown";
+export interface RouteCallFact {
+    readonly expression: string;
+    readonly kind: PathKind;
+    readonly staticPrefix: string | null;
+    readonly matchedRouteIds: readonly string[];
+    readonly source: SourceRef;
+    readonly unknown: readonly UnknownFact[];
+}
+export interface PageFact {
+    readonly path: string;
+    readonly kind: PageKind;
+    readonly calls: readonly RouteCallFact[];
+    readonly source: SourceRef;
+    readonly unknown: readonly UnknownFact[];
+}
+export type { GraphEdge, GraphEdgeKind, GraphNode, GraphNodeData, GraphNodeKind, PageLink, PageNodeData, PagePreview, PagePreviewNode, ProjectGraph, RouteNodeData, ScreenFacts, TableNodeData, ViewNodeData, WorkflowNodeData, WorkflowStepNodeData, } from "./types-graph.js";
+export type { RouteElevationUsage, RouteRelationUse, RouteRelationsFact, ViewFact, } from "./types-relations.js";
+export type { WorkflowFact, WorkflowStepFact, WorkflowTablesFact } from "./types-workflows.js";
+export interface Analysis {
+    readonly revision: string;
+    readonly files: readonly string[];
+    readonly config: ConfigFacts;
+    readonly routes: readonly RouteFact[];
+    readonly tables: readonly TableFact[];
+    readonly relations: readonly RelationFact[];
+    /** Declarative views (D-157): facts, and graph nodes since D-160. */
+    readonly views: readonly ViewFact[];
+    readonly pages: readonly PageFact[];
+    readonly workflows: readonly WorkflowFact[];
+    /** Job definitions, with D-157 applied to the db client their `run` body sees. */
+    readonly jobs: readonly JobFact[];
+    readonly jobRelations: Readonly<Record<string, JobRelationsFact>>;
+    /** Each workflow's table surface, derived from the jobs its steps reference. */
+    readonly workflowTables: readonly WorkflowTablesFact[];
+    /** Module facts for every parsed source file, in path order. */
+    readonly fileFacts: readonly FileFacts[];
+    readonly locales: LocaleCatalogs;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly graph: ProjectGraph;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@facilis.dev/analyze",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Facilis AST analyzer: static facts for the project DSL (routes, schema, relations, pages) with an injected parser.",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/index.js",
+    "./fs": "./dist/fs.js",
+    "./node": "./dist/node.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.15.0"
+  },
+  "peerDependencies": {
+    "oxc-parser": "0.157.0"
+  },
+  "peerDependenciesMeta": {
+    "oxc-parser": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/facilis-dev/facilis.git",
+    "directory": "packages/analyze"
+  },
+  "homepage": "https://github.com/facilis-dev/facilis/tree/main/packages/analyze#readme",
+  "bugs": {
+    "url": "https://github.com/facilis-dev/facilis/issues"
+  },
+  "keywords": [
+    "facilis",
+    "framework",
+    "vite",
+    "nitro",
+    "low-code"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}

package/src/analyze.ts

@@ -0,0 +1,119 @@
+import { buildPageFacts, type TransportSpec } from "./passes/clients.ts";
+import { buildConfigFacts } from "./passes/config.ts";
+import { buildFileFacts } from "./passes/file-facts.ts";
+import { readLocaleCatalogs } from "./passes/i18n.ts";
+import { buildJobFacts } from "./passes/jobs.ts";
+import { buildJobRelationFacts } from "./passes/job-relations.ts";
+import { buildRouteFacts } from "./passes/routes.ts";
+import { buildRouteRelationFacts } from "./passes/route-relations.ts";
+import { routeSystemTableDiagnostics } from "./passes/route-tables.ts";
+import { buildSchemaFacts } from "./passes/schema.ts";
+import { buildScreens } from "./passes/screens.ts";
+import { buildViewFacts } from "./passes/views.ts";
+import { buildWorkflowFacts } from "./passes/workflows.ts";
+import { buildWorkflowTableFacts } from "./passes/workflow-tables.ts";
+import { buildProjectGraph } from "./graph.ts";
+import { createModuleGraph, type ModuleGraph } from "./module-graph.ts";
+import type { PathAlias } from "./path-resolver.ts";
+import type { Parser } from "./parser.ts";
+import { computeRevision } from "./revision.ts";
+import { diagnostic } from "./diagnostics.ts";
+import type { Analysis, Diagnostic } from "./types.ts";
+
+export interface AnalyzeInput {
+  /** Project-relative path -> source. The analyzer never touches the filesystem itself. */
+  readonly files: ReadonlyMap<string, string>;
+  readonly parser: Parser;
+  /** Project root inside the file map (defaults to the map root). */
+  readonly rootDir?: string;
+  readonly aliases?: readonly PathAlias[];
+  readonly transport?: TransportSpec;
+}
+
+/** The sanctioned client transport (docs/findings/ast-dsl-contract.md §3.4). */
+export const DEFAULT_TRANSPORT: TransportSpec = {
+  module: "src/lib/api.ts",
+  exportName: "api",
+};
+
+/** Analyze a project snapshot into the fact model + project graph. Pure and synchronous. */
+export function analyzeProject(input: AnalyzeInput): Analysis {
+  const graph: ModuleGraph = createModuleGraph({
+    files: input.files,
+    parser: input.parser,
+    root: input.rootDir ?? "",
+    ...(input.aliases === undefined ? {} : { aliases: input.aliases }),
+  });
+  const config = buildConfigFacts(graph);
+  const routes = buildRouteFacts(graph, config.facts);
+  const schema = buildSchemaFacts(graph, config.facts);
+  const views = buildViewFacts(graph);
+  // D-157: the declaration check runs after the schema and the views, because a route's
+  // `dbTables` and its usage are compared against both (tables and views).
+  const routeRelations = buildRouteRelationFacts(graph, routes.routes, schema.tables, views.views);
+  // D-157 applies to jobs too: their `run` sees the system-scoped db client, tables and
+  // views alike, and the relation index is the same one the route pass builds its cases on.
+  const jobs = buildJobFacts(graph);
+  const jobRelations = buildJobRelationFacts(graph, jobs.jobs, schema.tables, views.views);
+  const workflows = buildWorkflowFacts(graph);
+  // A workflow declares no tables: its surface is derived from the jobs its steps reference.
+  const workflowTables = buildWorkflowTableFacts(workflows.workflows, jobs.jobs);
+  const locales = readLocaleCatalogs(graph);
+  const pages = buildPageFacts(graph, routes.routes, input.transport ?? DEFAULT_TRANSPORT);
+  const screens = buildScreens(graph, pages.pages);
+  const fileFacts = buildFileFacts(graph);
+
+  const diagnostics: Diagnostic[] = [];
+  for (const file of graph.files.values()) {
+    for (const error of file.errors) {
+      diagnostics.push(diagnostic("parse-error", "error", error.message, error.source));
+    }
+  }
+  diagnostics.push(
+    ...[
+      ...config.diagnostics,
+      ...routes.diagnostics,
+      ...schema.diagnostics,
+      ...views.diagnostics,
+      ...routeRelations.diagnostics,
+      ...jobs.diagnostics,
+      ...jobRelations.diagnostics,
+      ...locales.diagnostics,
+      ...pages.diagnostics,
+      ...routeSystemTableDiagnostics(routes.routes, schema.tables),
+      ...workflows.diagnostics,
+      ...workflowTables.diagnostics,
+    ].filter(
+      // Framework sources are shipped code: their facts stay, but their lint-style
+      // diagnostics are not the project's. Project files start outside node_modules/.
+      (entry) => entry.source === null || !entry.source.file.startsWith("node_modules/"),
+    ),
+  );
+
+  return {
+    revision: computeRevision(input.files),
+    files: [...graph.files.keys()].toSorted((left, right) => left.localeCompare(right)),
+    config: config.facts,
+    routes: routeRelations.routes,
+    tables: schema.tables,
+    relations: schema.relations,
+    views: views.views,
+    pages: pages.pages,
+    workflows: workflows.workflows,
+    jobs: jobs.jobs,
+    jobRelations: jobRelations.relations,
+    workflowTables: workflowTables.facts,
+    fileFacts,
+    locales: locales.locales,
+    diagnostics,
+    graph: buildProjectGraph({
+      routes: routes.routes,
+      tables: schema.tables,
+      relations: schema.relations,
+      pages: pages.pages,
+      views: views.views,
+      screens,
+      workflows: workflows.workflows,
+    }),
+  };
+}

package/src/ast/node.ts

@@ -0,0 +1,102 @@
+/**
+ * Minimal ESTree narrowing helpers shared by every analyzer pass.
+ *
+ * The AST shape is parser-independent: oxc-parser (Node, browser) and any future adapter
+ * produce plain ESTree / TS-ESTree nodes. Passes never import a parser package.
+ */
+export interface AstNode {
+  type: string;
+  start?: number;
+  end?: number;
+  [key: string]: unknown;
+}
+
+export function isAstNode(value: unknown): value is AstNode {
+  if (typeof value !== "object" || value === null) return false;
+  return typeof (value as { type?: unknown }).type === "string";
+}
+
+export function asNode(value: unknown): AstNode | undefined {
+  return isAstNode(value) ? value : undefined;
+}
+
+export function nodeArray(node: AstNode, key: string): AstNode[] {
+  const value = node[key];
+  if (!Array.isArray(value)) return [];
+  return value.filter(isAstNode);
+}
+
+export function identifierName(node: unknown): string | undefined {
+  const candidate = asNode(node);
+  if (!candidate || candidate.type !== "Identifier") return undefined;
+  return typeof candidate.name === "string" ? candidate.name : undefined;
+}
+
+export function literalString(node: unknown): string | undefined {
+  const candidate = asNode(node);
+  if (!candidate || candidate.type !== "Literal") return undefined;
+  return typeof candidate.value === "string" ? candidate.value : undefined;
+}
+
+/** Name of an object-literal property, or undefined for computed/spread entries. */
+export function propertyName(property: AstNode): string | undefined {
+  if (property.type !== "Property") return undefined;
+  const key = asNode(property.key);
+  if (!key) return undefined;
+  if (key.type === "Identifier") {
+    return property.computed === true ? undefined : identifierName(key);
+  }
+  if (key.type === "Literal" && (typeof key.value === "string" || typeof key.value === "number")) {
+    return String(key.value);
+  }
+  return undefined;
+}
+
+export function propertyValue(property: AstNode): AstNode | undefined {
+  return asNode(property.value);
+}
+
+/** Object-literal entries, including spread elements. */
+export function objectEntries(node: AstNode): AstNode[] {
+  return nodeArray(node, "properties");
+}
+
+export function isCallTo(node: unknown, calleeName: string): node is AstNode {
+  const candidate = asNode(node);
+  if (!candidate || candidate.type !== "CallExpression") return false;
+  return identifierName(candidate.callee) === calleeName;
+}
+
+export function callArguments(node: AstNode): AstNode[] {
+  return nodeArray(node, "arguments");
+}
+
+const UNWRAPPED_EXPRESSIONS = new Set([
+  "ParenthesizedExpression",
+  "TSAsExpression",
+  "TSSatisfiesExpression",
+  "TSNonNullExpression",
+  "TSInstantiationExpression",
+  "ChainExpression",
+]);
+
+/** Strip parentheses and TypeScript-only wrappers from an expression. */
+export function unwrapExpression(value: unknown): AstNode | undefined {
+  let node = asNode(value);
+  while (node && UNWRAPPED_EXPRESSIONS.has(node.type)) {
+    node = asNode(node.expression);
+  }
+  return node;
+}
+
+/** A call expression after unwrapping parentheses/TS wrappers. */
+export function callExpression(value: unknown): AstNode | undefined {
+  const node = unwrapExpression(value);
+  return node?.type === "CallExpression" ? node : undefined;
+}
+
+export function memberName(node: AstNode): string | undefined {
+  if (node.type !== "MemberExpression") return undefined;
+  if (node.computed === true) return literalString(node.property);
+  return identifierName(node.property);
+}

package/src/ast/walk.ts

@@ -0,0 +1,37 @@
+import { isAstNode, type AstNode } from "./node.ts";
+
+const SKIPPED_KEYS = new Set(["type", "start", "end", "range"]);
+
+/**
+ * Depth-first walk over an ESTree node. The AST is plain data (no cycles), so a generic
+ * recursion is enough and keeps the analyzer independent of a parser-specific visitor.
+ */
+export function walk(node: AstNode, visit: (node: AstNode) => void): void {
+  visit(node);
+  for (const key of Object.keys(node)) {
+    if (SKIPPED_KEYS.has(key)) continue;
+    const value = node[key];
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        if (isAstNode(child)) walk(child, visit);
+      }
+      continue;
+    }
+    if (isAstNode(value)) walk(value, visit);
+  }
+}
+
+/** Visit descendants of a node, not the node itself. */
+export function walkChildren(node: AstNode, visit: (node: AstNode) => void): void {
+  for (const key of Object.keys(node)) {
+    if (SKIPPED_KEYS.has(key)) continue;
+    const value = node[key];
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        if (isAstNode(child)) walk(child, visit);
+      }
+      continue;
+    }
+    if (isAstNode(value)) walk(value, visit);
+  }
+}

package/src/diagnostics.ts

@@ -0,0 +1,22 @@
+import type { Diagnostic, Severity, SourceRef } from "./types.ts";
+
+export function diagnostic(
+  code: string,
+  severity: Severity,
+  message: string,
+  source: SourceRef | null,
+): Diagnostic {
+  return { code, severity, message, source };
+}
+
+export function error(code: string, message: string, source: SourceRef | null): Diagnostic {
+  return diagnostic(code, "error", message, source);
+}
+
+export function warning(code: string, message: string, source: SourceRef | null): Diagnostic {
+  return diagnostic(code, "warning", message, source);
+}
+
+export function info(code: string, message: string, source: SourceRef | null): Diagnostic {
+  return diagnostic(code, "info", message, source);
+}

package/src/fs.ts

@@ -0,0 +1,59 @@
+/**
+ * Node filesystem loader for the analyzer (exported as `@facilis.dev/analyze/fs`).
+ *
+ * Kept apart from the `./node` parser adapter: a Vite config that runs in the browser VM
+ * needs to read a project directory but must not load a native/wasm parser. The loader only
+ * reads and filters the file map; the caller injects the parser (D-092).
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, sep } from "node:path";
+
+const SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".json"];
+const ALWAYS_SKIPPED = new Set([".git", "dist", "coverage", ".turbo", ".facilis", ".output"]);
+
+export interface LoadProjectOptions {
+  /** Package scopes allowed under node_modules (default: @facilis.dev). */
+  readonly nodeModuleScopes?: readonly string[];
+}
+
+/** Read a project directory into the analyzer's path -> source map. */
+export function loadProjectFiles(
+  root: string,
+  options: LoadProjectOptions = {},
+): Map<string, string> {
+  const scopes = options.nodeModuleScopes ?? ["@facilis.dev"];
+  const files = new Map<string, string>();
+  const walk = (directory: string, relativeDirectory: string): void => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (ALWAYS_SKIPPED.has(entry.name)) continue;
+      const full = join(directory, entry.name);
+      const path =
+        relativeDirectory.length === 0 ? entry.name : relativeDirectory + "/" + entry.name;
+      const stat = entry.isSymbolicLink() ? statSync(full) : null;
+      const isDirectory = stat === null ? entry.isDirectory() : stat.isDirectory();
+      const isFile = stat === null ? entry.isFile() : stat.isFile();
+      if (isDirectory) {
+        if (entry.name === "node_modules") {
+          for (const scope of scopes) {
+            const scopeDirectory = join(full, scope);
+            try {
+              readdirSync(scopeDirectory);
+            } catch {
+              continue;
+            }
+            walk(scopeDirectory, path + "/" + scope);
+          }
+          continue;
+        }
+        walk(full, path);
+        continue;
+      }
+      if (!isFile) continue;
+      if (!SOURCE_EXTENSIONS.some((extension) => entry.name.endsWith(extension))) continue;
+      files.set(path.split(sep).join("/"), readFileSync(full, "utf8"));
+    }
+  };
+  walk(root, "");
+  return files;
+}