@facilis.dev/analyze 0.0.0-stage → 0.1.1

package/dist/graph.js

@@ -0,0 +1,162 @@
+import { pageId, routeId, tableId, viewId, workflowId } from "./graph-ids.js";
+import { collectEdges } from "./graph-edges.js";
+function tableNode(table) {
+    const data = {
+        kind: "table",
+        table: table.name,
+        columns: table.columns,
+        rlsEnabled: table.rlsEnabled,
+        scope: table.scope,
+        policies: table.policies.map((policy) => ({
+            name: policy.name,
+            restrictive: policy.restrictive,
+        })),
+        framework: table.source.file.startsWith("node_modules/"),
+        unknown: table.unknown.length > 0 ||
+            table.columns.some((column) => column.unknown.length > 0) ||
+            table.policies.some((policy) => policy.unknown.length > 0),
+    };
+    return {
+        id: tableId(table.name),
+        kind: "table",
+        label: table.name,
+        sourceFile: table.source.file,
+        data,
+    };
+}
+function viewNode(view) {
+    const data = {
+        kind: "view",
+        view: view.name,
+        tables: view.tables,
+        permission: view.permission,
+        access: view.access,
+        unknown: view.unknown.length > 0 || view.access === null,
+    };
+    return {
+        id: viewId(view.name),
+        kind: "view",
+        label: view.name,
+        sourceFile: view.source.file,
+        data,
+    };
+}
+function workflowNode(workflow) {
+    const data = {
+        kind: "workflow",
+        name: workflow.name,
+        steps: workflow.steps.map((step) => ({
+            index: step.index,
+            kind: step.kind,
+            name: step.name,
+            permission: step.permission,
+            onRejectStep: step.onRejectStep,
+        })),
+        unknown: workflow.unknown.length > 0 || workflow.steps.some((step) => step.name === null),
+    };
+    return {
+        id: workflowId(workflow.name),
+        kind: "workflow",
+        label: workflow.name,
+        sourceFile: workflow.sourceFile,
+        data,
+    };
+}
+function routeNode(route, id) {
+    const data = {
+        kind: "route",
+        method: route.method,
+        path: route.path,
+        permission: route.permission ?? [],
+        wrapper: route.wrapper,
+        input: route.input,
+        dbTables: route.dbTables ?? [],
+        dbColumns: route.dbColumns ?? [],
+        elevations: route.elevations,
+        description: route.description,
+        unknown: route.unknown.length > 0 ||
+            route.wrapper === "unknown" ||
+            route.permission === null ||
+            route.dbTables === null,
+    };
+    return {
+        id,
+        kind: "route",
+        label: route.method + " " + route.path,
+        sourceFile: route.sourceFile,
+        data,
+    };
+}
+function pageNode(page, id, screens) {
+    const preview = screens.previews[page.path];
+    const data = {
+        kind: "page",
+        pagePath: page.path,
+        pageKind: page.kind,
+        callCount: page.calls.length,
+        ...(preview === undefined ? {} : { routePaths: preview.routePaths, preview }),
+    };
+    return {
+        id,
+        kind: "page",
+        label: page.path,
+        sourceFile: page.path,
+        data,
+    };
+}
+function collectNodes(input) {
+    const nodes = [];
+    const tableNames = new Set();
+    for (const table of input.tables) {
+        if (tableNames.has(table.name))
+            continue;
+        tableNames.add(table.name);
+        nodes.push(tableNode(table));
+    }
+    const viewNames = new Set();
+    for (const view of input.views) {
+        if (viewNames.has(view.name))
+            continue;
+        viewNames.add(view.name);
+        nodes.push(viewNode(view));
+    }
+    const routeIds = new Set();
+    for (const route of input.routes) {
+        const id = routeId(route);
+        if (routeIds.has(id))
+            continue;
+        routeIds.add(id);
+        nodes.push(routeNode(route, id));
+    }
+    const pageIds = new Set();
+    const screens = input.screens ?? { previews: {}, links: [] };
+    for (const page of input.pages) {
+        // The graph's page nodes are real pages only (the user's "pagine e basta"): components and
+        // lib files that happen to call an API stay analyzer facts, not boxes on the canvas.
+        if (page.kind !== "page")
+            continue;
+        const id = pageId(page.path);
+        if (pageIds.has(id))
+            continue;
+        pageIds.add(id);
+        nodes.push(pageNode(page, id, screens));
+    }
+    const workflowIds = new Set();
+    for (const workflow of input.workflows ?? []) {
+        const id = workflowId(workflow.name);
+        if (workflowIds.has(id))
+            continue;
+        workflowIds.add(id);
+        nodes.push(workflowNode(workflow));
+    }
+    return nodes;
+}
+/** Build the single project graph from facts. Ids and ordering are stable across runs. */
+export function buildProjectGraph(input) {
+    const nodes = collectNodes(input);
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    const edges = collectEdges(input, nodeIds);
+    nodes.sort((left, right) => left.id.localeCompare(right.id));
+    edges.sort((left, right) => left.id.localeCompare(right.id));
+    return { nodes, edges };
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @facilis.dev/analyze — static facts for the Facilis project DSL.
+ *
+ * Zero build-time execution: the caller supplies a file map and an injected parser; the
+ * analyzer interprets the declared DSL (routes, config, Drizzle schema, relations, pages).
+ * The Node parser adapter lives on the `@facilis.dev/analyze/node` subpath so the main entry
+ * stays browser-safe.
+ */
+export { analyzeProject, DEFAULT_TRANSPORT } from "./analyze.js";
+export type { AnalyzeInput } from "./analyze.js";
+export { buildProjectGraph } from "./graph.js";
+export type { GraphInput } from "./graph.js";
+export { ROUTE_DESCRIPTION_MAX_CHARS } from "./passes/route-description.js";
+export { createModuleGraph } from "./module-graph.js";
+export type { Binding, ModuleGraph, ProjectFile } from "./module-graph.js";
+export { createPathResolver, normalizePath } from "./path-resolver.js";
+export type { PathAlias } from "./path-resolver.js";
+export type { Parser, ParseError, ParsedModule } from "./parser.js";
+export { diagnostic, error, info, warning } from "./diagnostics.js";
+export { computeRevision } from "./revision.js";
+export { pageId, routeId, tableId, viewId, workflowId } from "./graph-ids.js";
+export type { TransportSpec } from "./passes/clients.js";
+export type { JobFact, JobRelationsFact } from "./types-jobs.js";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @facilis.dev/analyze — static facts for the Facilis project DSL.
+ *
+ * Zero build-time execution: the caller supplies a file map and an injected parser; the
+ * analyzer interprets the declared DSL (routes, config, Drizzle schema, relations, pages).
+ * The Node parser adapter lives on the `@facilis.dev/analyze/node` subpath so the main entry
+ * stays browser-safe.
+ */
+export { analyzeProject, DEFAULT_TRANSPORT } from "./analyze.js";
+export { buildProjectGraph } from "./graph.js";
+export { ROUTE_DESCRIPTION_MAX_CHARS } from "./passes/route-description.js";
+export { createModuleGraph } from "./module-graph.js";
+export { createPathResolver, normalizePath } from "./path-resolver.js";
+export { diagnostic, error, info, warning } from "./diagnostics.js";
+export { computeRevision } from "./revision.js";
+// The one id spelling shared by graph nodes and edges (D-092), for UI joins by node id.
+export { pageId, routeId, tableId, viewId, workflowId } from "./graph-ids.js";

package/dist/json.d.ts

@@ -0,0 +1,8 @@
+import { isAstNode } from "./ast/node.js";
+/** Parse a JSON file from the project file map; null when absent or malformed. */
+export declare function readJson(files: ReadonlyMap<string, string>, path: string): unknown;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Module source extensions the analyzer can parse. */
+export declare const SOURCE_EXTENSIONS: readonly [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"];
+export declare function isSourceFile(path: string): boolean;
+export { isAstNode };

package/dist/json.js

@@ -0,0 +1,31 @@
+import { isAstNode } from "./ast/node.js";
+/** Parse a JSON file from the project file map; null when absent or malformed. */
+export function readJson(files, path) {
+    const source = files.get(path);
+    if (source === undefined)
+        return null;
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        return null;
+    }
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Module source extensions the analyzer can parse. */
+export const SOURCE_EXTENSIONS = [
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".mts",
+    ".cts",
+];
+export function isSourceFile(path) {
+    return SOURCE_EXTENSIONS.some((extension) => path.endsWith(extension));
+}
+export { isAstNode };

package/dist/module-graph.d.ts

@@ -0,0 +1,33 @@
+import { type ModuleInfo } from "./module-info.js";
+import { type PathAlias } from "./path-resolver.js";
+import type { ParseError, Parser } from "./parser.js";
+import type { AstNode } from "./ast/node.js";
+export interface ProjectFile {
+    readonly path: string;
+    readonly source: string;
+    readonly program: AstNode;
+    readonly errors: readonly ParseError[];
+    readonly module: ModuleInfo;
+}
+export interface Binding {
+    readonly file: string;
+    readonly name: string;
+}
+export interface ModuleGraph {
+    readonly files: ReadonlyMap<string, ProjectFile>;
+    /** Every input file (including JSON/tsconfig/package.json), path -> source. */
+    readonly allFiles: ReadonlyMap<string, string>;
+    readonly root: string;
+    file(path: string): ProjectFile | undefined;
+    resolve(from: string, specifier: string): string | null;
+    resolveBinding(file: string, local: string): Binding | null;
+    resolveExport(file: string, name: string): Binding | null;
+    readJson(path: string): unknown;
+}
+export interface ModuleGraphInput {
+    readonly files: ReadonlyMap<string, string>;
+    readonly parser: Parser;
+    readonly root?: string;
+    readonly aliases?: readonly PathAlias[];
+}
+export declare function createModuleGraph(input: ModuleGraphInput): ModuleGraph;

package/dist/module-graph.js

@@ -0,0 +1,86 @@
+import { isSourceFile, readJson as parseJson } from "./json.js";
+import { parseModuleInfo } from "./module-info.js";
+import { createPathResolver, normalizePath } from "./path-resolver.js";
+export function createModuleGraph(input) {
+    const root = normalizePath(input.root ?? "");
+    const sources = new Map();
+    const files = new Map();
+    for (const [rawPath, source] of input.files) {
+        const path = normalizePath(rawPath);
+        sources.set(path, source);
+        if (!isSourceFile(path))
+            continue;
+        const parsed = input.parser.parse(path, source);
+        files.set(path, {
+            path,
+            source,
+            program: parsed.program,
+            errors: parsed.errors,
+            module: parseModuleInfo(path, source, parsed.program),
+        });
+    }
+    const resolver = createPathResolver({
+        exists: (path) => sources.has(path),
+        readJson: (path) => parseJson(sources, path),
+        root,
+        ...(input.aliases === undefined ? {} : { aliases: input.aliases }),
+    });
+    const resolveExport = (file, name, seen = new Set()) => {
+        const key = file + "#" + name;
+        if (seen.has(key))
+            return null;
+        seen.add(key);
+        const module = files.get(file);
+        if (module === undefined)
+            return null;
+        const direct = module.module.exports.find((entry) => entry.exported === name);
+        if (direct !== undefined) {
+            if (direct.source !== null) {
+                const target = resolver.resolve(file, direct.source);
+                if (target === null)
+                    return null;
+                if (direct.kind === "all")
+                    return resolveExport(target, "*", seen);
+                return resolveExport(target, direct.imported ?? name, seen);
+            }
+            if (direct.local !== null)
+                return resolveBinding(file, direct.local, seen);
+            return { file, name };
+        }
+        for (const entry of module.module.exports) {
+            if (entry.kind !== "all" || entry.source === null)
+                continue;
+            const target = resolver.resolve(file, entry.source);
+            if (target !== null) {
+                const found = resolveExport(target, name, new Set(seen));
+                if (found !== null)
+                    return found;
+            }
+        }
+        return null;
+    };
+    const resolveBinding = (file, local, seen = new Set()) => {
+        const module = files.get(file);
+        if (module === undefined)
+            return null;
+        const imported = module.module.imports.find((entry) => entry.local === local);
+        if (imported === undefined)
+            return { file, name: local };
+        if (imported.kind === "namespace")
+            return null;
+        const target = resolver.resolve(file, imported.specifier);
+        if (target === null)
+            return null;
+        return resolveExport(target, imported.imported ?? "default", new Set(seen));
+    };
+    return {
+        files,
+        allFiles: sources,
+        root,
+        file: (path) => files.get(normalizePath(path)),
+        resolve: resolver.resolve,
+        resolveBinding: (file, local) => resolveBinding(normalizePath(file), local),
+        resolveExport: (file, name) => resolveExport(normalizePath(file), name),
+        readJson: (path) => parseJson(sources, normalizePath(path)),
+    };
+}

package/dist/module-info.d.ts

@@ -0,0 +1,27 @@
+import { type AstNode } from "./ast/node.js";
+import type { SourceRef } from "./types.js";
+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[];
+}
+export declare function declarationNames(declaration: AstNode): string[];
+export declare function parseModuleInfo(file: string, source: string, program: AstNode): ModuleInfo;
+/** The declaration of "export default ...", unwrapped from the export statement. */
+export declare function defaultExportDeclaration(program: AstNode): AstNode | undefined;
+/** The initializer of a top-level const/let/var binding, when declared exactly once. */
+export declare function localInitializer(program: AstNode, name: string): AstNode | undefined;

package/dist/module-info.js

@@ -0,0 +1,143 @@
+import { identifierName, isAstNode, literalString, nodeArray } from "./ast/node.js";
+function refOf(file, source, node) {
+    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, source, program) {
+    const out = [];
+    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) {
+    if (declaration.type === "VariableDeclaration") {
+        return nodeArray(declaration, "declarations")
+            .map((item) => identifierName(item.id))
+            .filter((name) => name !== undefined);
+    }
+    if (declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration") {
+        const name = identifierName(declaration.id);
+        return name === undefined ? [] : [name];
+    }
+    return [];
+}
+function exportBindings(file, source, program) {
+    const out = [];
+    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, source, program) {
+    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) {
+    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, name) {
+    let found;
+    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/dist/node.d.ts

@@ -0,0 +1,16 @@
+import { type AnalyzeInput } from "./analyze.js";
+import type { PathAlias } from "./path-resolver.js";
+import { type LoadProjectOptions } from "./fs.js";
+import type { Parser } from "./parser.js";
+import type { Analysis } from "./types.js";
+/** Node/CI parser adapter. The browser uses a wasm adapter over the same contract. */
+export declare function createOxcParser(): Parser;
+export interface AnalyzeDirectoryOptions {
+    readonly aliases?: readonly PathAlias[];
+    readonly transport?: AnalyzeInput["transport"];
+    readonly load?: LoadProjectOptions;
+}
+export { loadProjectFiles } from "./fs.js";
+export type { LoadProjectOptions } from "./fs.js";
+/** Convenience for Node/CI: load a directory and analyze it. The browser passes its own map. */
+export declare function analyzeDirectory(root: string, options?: AnalyzeDirectoryOptions): Analysis;

package/dist/node.js

@@ -0,0 +1,41 @@
+import { parseSync } from "oxc-parser";
+import { analyzeProject } from "./analyze.js";
+import { asNode } from "./ast/node.js";
+import { loadProjectFiles } from "./fs.js";
+import { lineOf } from "./source.js";
+/** Node/CI parser adapter. The browser uses a wasm adapter over the same contract. */
+export function createOxcParser() {
+    return {
+        parse(filename, source) {
+            const result = parseSync(filename, source, {
+                astType: "ts",
+                sourceType: "module",
+                preserveParens: true,
+            });
+            const program = asNode(result.program);
+            if (program === undefined)
+                throw new Error("oxc-parser returned no program");
+            const errors = 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 { loadProjectFiles } from "./fs.js";
+/** Convenience for Node/CI: load a directory and analyze it. The browser passes its own map. */
+export function analyzeDirectory(root, options = {}) {
+    return analyzeProject({
+        files: loadProjectFiles(root, options.load),
+        parser: createOxcParser(),
+        ...(options.aliases === undefined ? {} : { aliases: options.aliases }),
+        ...(options.transport === undefined ? {} : { transport: options.transport }),
+    });
+}

package/dist/parser.d.ts

@@ -0,0 +1,16 @@
+import type { AstNode } from "./ast/node.js";
+import type { SourceRef } from "./types.js";
+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/dist/parser.js

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

package/dist/passes/clients.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 type { ModuleGraph } from "../module-graph.js";
+import type { Diagnostic, PageFact, RouteFact } from "../types.js";
+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[];
+}
+/** Map client files to the routes they call. */
+export declare function buildPageFacts(graph: ModuleGraph, routes: readonly RouteFact[], transport: TransportSpec): ClientResult;