@facilis.dev/analyze 0.0.0-stage → 0.1.0

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;

package/dist/path-resolver.js

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

package/dist/revision.d.ts

@@ -0,0 +1,2 @@
+/** Deterministic, browser-safe revision of the analyzed file set. */
+export declare function computeRevision(files: ReadonlyMap<string, string>): string;

package/dist/revision.js

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

package/dist/source.d.ts

@@ -0,0 +1,4 @@
+import type { SourceRef } from "./types.js";
+/** 1-based line number of a source offset. */
+export declare function lineOf(source: string, offset: number): number;
+export declare function sourceRef(file: string, source: string, offset: number): SourceRef;

package/dist/source.js

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

package/dist/static-eval.d.ts

@@ -0,0 +1,36 @@
+import { literalString, type AstNode } from "./ast/node.js";
+import type { ModuleGraph } from "./module-graph.js";
+export type StaticEvaluation = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export interface StaticContext {
+    readonly graph: ModuleGraph;
+    readonly file: string;
+}
+/**
+ * Evaluate the static subset (docs/findings/ast-dsl-contract.md §4): literals, arrays,
+ * objects, templates without dynamic parts, same-file consts and one-hop project imports.
+ * Never executes code; anything else fails and the caller records an unknown fact.
+ */
+export declare function evaluateStatic(node: AstNode | undefined, context: StaticContext, depth?: number): StaticEvaluation;
+/** Convenience: a string or undefined, with the failure reason. */
+export declare function staticString(node: AstNode | undefined, context: StaticContext): {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Convenience: a string[] or undefined, with the failure reason. */
+export declare function staticStringArray(node: AstNode | undefined, context: StaticContext): {
+    ok: true;
+    value: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+export { literalString };