@facilis.dev/analyze 0.0.0-stage → 0.1.1

package/dist/passes/static-read.js

@@ -0,0 +1,151 @@
+/**
+ * Helpers shared by the analyzer passes: the static object reader (§4 of the AST DSL
+ * contract) and deterministic diagnostic ordering.
+ *
+ * The reader is deliberately partial: every property is evaluated on its own so one computed
+ * value cannot hide its siblings. It never executes project code and it never defaults an
+ * unreadable value - the caller decides whether the unknown is a security error.
+ */
+import { identifierName, objectEntries, propertyName, propertyValue, unwrapExpression, } from "../ast/node.js";
+import { declarationNames, defaultExportDeclaration, localInitializer } from "../module-info.js";
+import { sourceRef } from "../source.js";
+import { evaluateStatic } from "../static-eval.js";
+const MAX_RESOLVE_DEPTH = 8;
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function projectPath(root, path) {
+    return root.length === 0 ? path : root + "/" + path;
+}
+/** Project-relative path with the graph root stripped (the opposite of projectPath). */
+export function relativePath(root, path) {
+    return root.length === 0 || !path.startsWith(root + "/") ? path : path.slice(root.length + 1);
+}
+export function refOf(context, node) {
+    const file = context.graph.file(context.file);
+    const offset = node !== undefined && typeof node.start === "number" ? node.start : 0;
+    return sourceRef(context.file, file?.source ?? "", offset);
+}
+function objectLiteral(node, context, depth = 0) {
+    if (node === undefined || depth > MAX_RESOLVE_DEPTH)
+        return undefined;
+    const unwrapped = unwrapExpression(node);
+    if (unwrapped === undefined)
+        return undefined;
+    if (unwrapped.type === "ObjectExpression")
+        return unwrapped;
+    const file = context.graph.file(context.file);
+    const name = identifierName(unwrapped);
+    if (file === undefined || name === undefined)
+        return undefined;
+    return objectLiteral(localInitializer(file.program, name), context, depth + 1);
+}
+/** Partial, non-executing reader for object literals in the static subset. */
+export function readStaticObject(node, context, options) {
+    const fields = new Map();
+    const unknown = [];
+    if (node === undefined)
+        return { fields, unknown };
+    const record = (reason, at, structural) => {
+        if (structural || options.report) {
+            unknown.push({ code: options.code, reason, source: refOf(context, at) });
+        }
+    };
+    const literal = objectLiteral(node, context);
+    if (literal !== undefined) {
+        for (const entry of objectEntries(literal)) {
+            if (entry.type === "SpreadElement") {
+                record("spread in an object literal cannot be read statically", entry, true);
+                continue;
+            }
+            const key = propertyName(entry);
+            if (key === undefined) {
+                record("computed object key cannot be read statically", entry, true);
+                continue;
+            }
+            const valueNode = propertyValue(entry);
+            const evaluated = evaluateStatic(valueNode, context);
+            if (evaluated.ok) {
+                fields.set(key, { value: evaluated.value, ok: true, node: valueNode, reason: null });
+            }
+            else {
+                fields.set(key, { value: undefined, ok: false, node: valueNode, reason: evaluated.reason });
+                record(evaluated.reason, valueNode ?? entry, false);
+            }
+        }
+        return { fields, unknown };
+    }
+    const evaluated = evaluateStatic(node, context);
+    if (evaluated.ok && isRecord(evaluated.value)) {
+        for (const [key, value] of Object.entries(evaluated.value)) {
+            fields.set(key, { value, ok: true, node: undefined, reason: null });
+        }
+        return { fields, unknown };
+    }
+    record(evaluated.ok ? "value is not an object" : evaluated.reason, node, true);
+    return { fields, unknown };
+}
+/**
+ * The default export, unwrapped and resolved through a same-file const or a
+ * `export { handler as default }` statement.
+ */
+export function defaultExportExpression(file) {
+    const declaration = defaultExportDeclaration(file.program);
+    if (declaration !== undefined) {
+        const unwrapped = unwrapExpression(declaration);
+        const name = unwrapped?.type === "Identifier" ? identifierName(unwrapped) : undefined;
+        return name === undefined ? unwrapped : unwrapExpression(localInitializer(file.program, name));
+    }
+    const entry = file.module.exports.find((item) => item.exported === "default" && item.local !== null);
+    if (entry === undefined || entry.local === null)
+        return undefined;
+    return unwrapExpression(localInitializer(file.program, entry.local));
+}
+/** A top-level function/class declaration by name (localInitializer covers variables only). */
+export function findDeclaration(program, name) {
+    for (const raw of Array.isArray(program.body) ? program.body : []) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const statement = raw;
+        const declaration = statement.type === "ExportNamedDeclaration" &&
+            statement.declaration !== null &&
+            typeof statement.declaration === "object"
+            ? statement.declaration
+            : statement;
+        if ((declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration") &&
+            identifierName(declaration.id) === name) {
+            return declaration;
+        }
+    }
+    return undefined;
+}
+/** True when the module declares the name itself: a local shadow invalidates an import. */
+export function isLocallyDeclared(file, name) {
+    const body = Array.isArray(file.program.body) ? file.program.body : [];
+    for (const raw of body) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const statement = raw;
+        const declaration = statement.type === "ExportNamedDeclaration" &&
+            statement.declaration !== null &&
+            typeof statement.declaration === "object"
+            ? statement.declaration
+            : statement;
+        if (declarationNames(declaration).includes(name))
+            return true;
+    }
+    return false;
+}
+/** Stable diagnostic order (file, line, code, message) so snapshots never flap. */
+export function sortDiagnostics(diagnostics) {
+    return [...diagnostics].toSorted((left, right) => {
+        const fileOrder = (left.source?.file ?? "").localeCompare(right.source?.file ?? "");
+        if (fileOrder !== 0)
+            return fileOrder;
+        const lineOrder = (left.source?.line ?? 0) - (right.source?.line ?? 0);
+        if (lineOrder !== 0)
+            return lineOrder;
+        const codeOrder = left.code.localeCompare(right.code);
+        return codeOrder !== 0 ? codeOrder : left.message.localeCompare(right.message);
+    });
+}

package/dist/passes/views.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `db/views/**` -> ViewFacts (D-157, SPEC §11.2).
+ *
+ * A view is declared one per file with `defineView({ name, columns, query, tables?,
+ * permission? })` from @facilis.dev/db (D-097/D-098). The route-relations pass resolves a view
+ * object used in `from(...)` to this fact, so a route declares the view's SQL name in
+ * `dbTables` instead of its base tables. D-160 adds the view nodes and their edges to the
+ * project graph; this pass stays facts-only.
+ *
+ * The declaration is read through the bounded static subset; an unreadable name/tables/
+ * permission is an explicit unknown, never a guessed value.
+ */
+import type { ModuleGraph } from "../module-graph.js";
+import type { Diagnostic, ViewFact } from "../types.js";
+export interface ViewScan {
+    readonly views: readonly ViewFact[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** Read `db/views/**` into view facts. */
+export declare function buildViewFacts(graph: ModuleGraph): ViewScan;

package/dist/passes/views.js

@@ -0,0 +1,101 @@
+/**
+ * `db/views/**` -> ViewFacts (D-157, SPEC §11.2).
+ *
+ * A view is declared one per file with `defineView({ name, columns, query, tables?,
+ * permission? })` from @facilis.dev/db (D-097/D-098). The route-relations pass resolves a view
+ * object used in `from(...)` to this fact, so a route declares the view's SQL name in
+ * `dbTables` instead of its base tables. D-160 adds the view nodes and their edges to the
+ * project graph; this pass stays facts-only.
+ *
+ * The declaration is read through the bounded static subset; an unreadable name/tables/
+ * permission is an explicit unknown, never a guessed value.
+ */
+import { callArguments, identifierName, unwrapExpression } from "../ast/node.js";
+import { createDslResolver, isViewFile, nodeRef, schemaDiagnostics, topLevelDeclarators, } from "./schema-dsl.js";
+import { readStaticObject } from "./static-read.js";
+function viewUnknown(reason, source) {
+    return { code: "view-static", reason, source };
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.every((entry) => typeof entry === "string") ? [...value] : null;
+}
+/** The `defineView(...)` call an initializer holds, when it is the @facilis.dev/db DSL. */
+function viewCall(init, resolver) {
+    const expression = unwrapExpression(init);
+    if (expression?.type !== "CallExpression")
+        return null;
+    const symbol = resolver(expression.callee);
+    return symbol?.pkg === "facilis-db" && symbol.name === "defineView" ? expression : null;
+}
+function buildViewDraft(graph, file, declarator, call) {
+    const source = nodeRef(file, call);
+    const binding = identifierName(declarator.id) ?? null;
+    const unknowns = [];
+    const options = readStaticObject(callArguments(call)[0], { graph, file: file.path }, { code: "view-static", report: false });
+    unknowns.push(...options.unknown);
+    const nameField = options.fields.get("name");
+    let name = binding ?? "unknown";
+    if (nameField !== undefined && nameField.ok && typeof nameField.value === "string") {
+        if (nameField.value.length > 0)
+            name = nameField.value;
+        else
+            unknowns.push(viewUnknown("view name is not a static string", source));
+    }
+    else if (nameField !== undefined && !nameField.ok) {
+        unknowns.push(viewUnknown("view name is missing or not statically readable", source));
+    }
+    else {
+        unknowns.push(viewUnknown("view name is missing or not a static string", source));
+    }
+    let tables = [];
+    const tablesField = options.fields.get("tables");
+    if (tablesField !== undefined) {
+        const read = tablesField.ok ? stringArray(tablesField.value) : null;
+        if (read === null) {
+            unknowns.push(viewUnknown("view tables are not a static string[]", source));
+        }
+        else {
+            tables = read;
+        }
+    }
+    const permissionField = options.fields.get("permission");
+    let permission = null;
+    let access = "invoker";
+    if (permissionField !== undefined) {
+        if (permissionField.ok && typeof permissionField.value === "string") {
+            permission = permissionField.value;
+            access = "definer";
+        }
+        else {
+            // We cannot tell an invoker declaration from a definer one: keep the mode unknown.
+            access = null;
+            unknowns.push(viewUnknown("view permission is not a static string", source));
+        }
+    }
+    return {
+        view: { name, binding, tables, permission, access, source, unknown: unknowns },
+        diagnostics: schemaDiagnostics(unknowns),
+    };
+}
+/** Read `db/views/**` into view facts. */
+export function buildViewFacts(graph) {
+    const files = [...graph.files.values()]
+        .filter((file) => isViewFile(graph, file.path))
+        .toSorted((left, right) => left.path.localeCompare(right.path));
+    const views = [];
+    const diagnostics = [];
+    for (const file of files) {
+        const resolver = createDslResolver(graph, file);
+        for (const declarator of topLevelDeclarators(file.program)) {
+            const call = viewCall(declarator.init, resolver);
+            if (call === null)
+                continue;
+            const draft = buildViewDraft(graph, file, declarator, call);
+            views.push(draft.view);
+            diagnostics.push(...draft.diagnostics);
+        }
+    }
+    return { views, diagnostics };
+}

package/dist/passes/workflow-tables.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Workflow table surface, derived from the jobs its steps reference (user decision: derived,
+ * never declared). A workflow declares no tables of its own: the union of the referenced jobs'
+ * `dbTables` is what the workflow can reach, and the runtime inherits each job's guard.
+ *
+ * Approval steps contribute nothing. A referenced job with an unreadable `dbTables` makes the
+ * union explicitly unknown; a referenced job with no definition keeps its name visible in
+ * `unknownJobs` and is a warning, never a silent hole.
+ */
+import type { Diagnostic, WorkflowFact } from "../types.js";
+import type { JobFact } from "../types-jobs.js";
+import type { WorkflowTablesFact } from "../types-workflows.js";
+export interface WorkflowTablesResult {
+    readonly facts: readonly WorkflowTablesFact[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** Derive every workflow's table surface from its job steps. */
+export declare function buildWorkflowTableFacts(workflows: readonly WorkflowFact[], jobs: readonly JobFact[]): WorkflowTablesResult;

package/dist/passes/workflow-tables.js

@@ -0,0 +1,71 @@
+/**
+ * Workflow table surface, derived from the jobs its steps reference (user decision: derived,
+ * never declared). A workflow declares no tables of its own: the union of the referenced jobs'
+ * `dbTables` is what the workflow can reach, and the runtime inherits each job's guard.
+ *
+ * Approval steps contribute nothing. A referenced job with an unreadable `dbTables` makes the
+ * union explicitly unknown; a referenced job with no definition keeps its name visible in
+ * `unknownJobs` and is a warning, never a silent hole.
+ */
+import { warning } from "../diagnostics.js";
+import { sortDiagnostics } from "./static-read.js";
+/** One job definition per name; the manifest enforces uniqueness, first wins here. */
+function jobRegistry(jobs) {
+    const byName = new Map();
+    for (const job of jobs) {
+        if (!byName.has(job.name))
+            byName.set(job.name, job);
+    }
+    return byName;
+}
+/** Derive every workflow's table surface from its job steps. */
+export function buildWorkflowTableFacts(workflows, jobs) {
+    const registry = jobRegistry(jobs);
+    const facts = [];
+    const diagnostics = [];
+    for (const workflow of workflows) {
+        const tables = new Set();
+        const unknownJobs = new Set();
+        const missingAt = new Map();
+        let unknown = false;
+        for (const step of workflow.steps) {
+            if (step.kind !== "job")
+                continue;
+            // A job step whose name is unreadable is already a workflow-definition unknown, but the
+            // derived surface must not pretend it is complete.
+            if (step.name === null) {
+                unknown = true;
+                continue;
+            }
+            const job = registry.get(step.name);
+            if (job === undefined) {
+                unknownJobs.add(step.name);
+                if (!missingAt.has(step.name))
+                    missingAt.set(step.name, step.source);
+                continue;
+            }
+            if (job.dbTables === null) {
+                unknown = true;
+                continue;
+            }
+            for (const table of job.dbTables)
+                tables.add(table);
+        }
+        for (const name of [...unknownJobs].toSorted()) {
+            diagnostics.push(warning("workflow-job-unknown", 'workflow "' +
+                workflow.name +
+                '" references job "' +
+                name +
+                '" but no definition exists in server/jobs', missingAt.get(name) ?? workflow.source));
+        }
+        facts.push({
+            name: workflow.name,
+            sourceFile: workflow.sourceFile,
+            source: workflow.source,
+            tables: [...tables].toSorted(),
+            unknownJobs: [...unknownJobs].toSorted(),
+            unknown,
+        });
+    }
+    return { facts, diagnostics: sortDiagnostics(diagnostics) };
+}

package/dist/passes/workflows.d.ts

@@ -0,0 +1,8 @@
+import type { ModuleGraph } from "../module-graph.js";
+import type { Diagnostic, WorkflowFact } from "../types.js";
+export interface WorkflowResult {
+    readonly workflows: readonly WorkflowFact[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** Read every workflow definition the project declares; invalid files become warnings. */
+export declare function buildWorkflowFacts(graph: ModuleGraph): WorkflowResult;

package/dist/passes/workflows.js

@@ -0,0 +1,160 @@
+// `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, } from "../ast/node.js";
+import { warning } from "../diagnostics.js";
+import { sourceRef } from "../source.js";
+import { evaluateStatic } from "../static-eval.js";
+import { defaultExportExpression, isLocallyDeclared, isRecord, relativePath, sortDiagnostics, } from "./static-read.js";
+const CORE_SPECIFIER = "@facilis.dev/core";
+const WORKFLOW_DIR = "server/workflows/";
+const STATIC_CODE = "workflow-definition-static";
+/** Read every workflow definition the project declares; invalid files become warnings. */
+export function buildWorkflowFacts(graph) {
+    const workflows = [];
+    const diagnostics = [];
+    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, file, workflows, diagnostics) {
+    const context = { 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 = [];
+    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, expression) {
+    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, context, file, source, unknown) {
+    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 = [];
+    nodeArray(array, "elements").forEach((element, index) => {
+        const ref = sourceRef(file, source, element.start ?? 0);
+        const literal = objectLiteral(element);
+        const fields = literal === undefined ? new Map() : 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() : 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, context) {
+    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, ref, index, label, value) {
+    if (value !== null)
+        return;
+    unknown.push({
+        code: STATIC_CODE,
+        reason: "step " + index + ": " + label + " cannot be read statically",
+        source: ref,
+    });
+}
+function staticString(node, context) {
+    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) {
+    const value = node === undefined ? undefined : unwrapExpression(node);
+    return value?.type === "ObjectExpression" ? value : undefined;
+}
+function fieldMap(literal) {
+    const fields = new Map();
+    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/dist/path-resolver.d.ts

@@ -0,0 +1,20 @@
+/** 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 declare const SOURCE_EXTENSIONS: readonly [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"];
+export declare function normalizePath(path: string): string;
+export declare function dirname(path: string): string;
+export declare function joinPath(base: string, relative: string): string;
+export declare function createPathResolver(input: PathResolverInput): PathResolver;