@fougere/cli 0.12.5-alpha.0 → 0.12.6-alpha.0

package/fronds/analysis/handlers/CheckHandler.ts

@@ -1,217 +0,0 @@
-import { Shapes } from '@fougere/schema';
-import safeRegex from 'safe-regex';
-import {
-  buildGraph,
-  clusterEntities,
-  resolveEffectiveOperations,
-  type Diagnostic,
-} from '@fougere/core';
-import { adaptersOf, crossFrondImports, handlerDeclarations, outsideConventions } from '@fougere/compiler';
-import { resolveConventions } from '@fougere/core';
-import ProjectScan from '../services/ProjectScan.js';
-import { statSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { FACADE_OUT, DEFAULT_OUT } from './BuildHandler.js';
-import { remotesOf } from '@fougere/core/node';
-
-export interface CheckResult {
-  fronds: number;
-  handlers: number;
-  findings: Diagnostic[];
-}
-
-/** Shared with `fougere graph` — one threshold, so the two never disagree. */
-const DOMAIN_SPLIT_MIN_ENTITIES = 6;
-
-/**
- * What does not hold in this app — derived from its declarations, not from tests.
- *
- * It scans rather than boots — see `ProjectScan`, which states what that costs.
- *
- * It raises no operation-resolution rule of its own: those findings come from the same
- * EffectiveOperation resolver boot consumes. The remaining findings come from their
- * existing owners — scan diagnostics, the import reader and domain clustering. A second
- * opinion here would report what the runtime does not serve, precisely what a checker
- * must avoid.
- *
- * A rule about an ABSENCE is only sound if the analysis attests it looked, which is
- * why the scan's diagnostics had to exist before this command could.
- */
-export default class CheckHandler {
-  constructor(private projectScan: ProjectScan) {}
-
-  /** Report what does not hold in a Fougere app, without booting it. */
-  async execute(input: { root?: string }): Promise<CheckResult> {
-    const { fronds, diagnostics, config, root } = await this.projectScan.at(input.root);
-    // This is the same pure resolution the boot consumes. No app lifecycle, database,
-    // migration, seed or adapter mount is needed for a global semantic check.
-    const model = resolveEffectiveOperations(fronds, {
-      diagnostics,
-      remotes: remotesOf(config),
-      adapters: config.adapters,
-    });
-    const findings: Diagnostic[] = [...model.diagnostics];
-    const handlers = fronds.reduce((count, frond) => count + frond.handlers.length, 0);
-
-    /**
-     * Entity groups with no `ref()` between them, in one frond. Reported as a FACT, not a
-     * verdict: it means either a missing relation or a frond that has not been named, and
-     * nothing here can tell which. `fougere graph` shows the groups.
-     */
-    if (fronds.length === 1) {
-      // `clusterEntities`, not `suggestSplit`: the latter invents a cut on a connected
-      // graph, which is its job and not this question. Here only real components count.
-      const nodes = buildGraph(fronds);
-      const clusters = clusterEntities(nodes);
-      // Same threshold as `fougere graph`'s own tip: below it, two components are a small
-      // app that has not grown its links yet, not a frond holding two domains.
-      if (clusters.length > 1 && nodes.size >= DOMAIN_SPLIT_MIN_ENTITIES) {
-        findings.push({
-          severity: 'warning',
-          code: 'frond-holds-several-domains',
-          filePath: fronds[0].source.path,
-          message: `'${fronds[0].name}': ${clusters.length} entity groups with no relation between `
-            + `them (${clusters.map((c) => c.name).join(', ')}). Either a relation is missing, or `
-            + `they are separate fronds — see \`fougere graph\`.`,
-        });
-      }
-    }
-
-    /**
-     * An entity addressing an adapter this project does not depend on. Judged HERE and
-     * not at boot: a process only knows the adapters it loaded, so an entity stating a
-     * Postgres column type in an app running on `adapter/memory` is indistinguishable
-     * from a typo. A project's dependencies name every adapter it could ever load.
-     *
-     * Silent when the project depends on none — there would be nothing to compare against,
-     * and reporting every key as unknown is worse than saying nothing.
-     */
-    const known = await adaptersOf(root);
-    if (known.length > 0) {
-      for (const frond of fronds) {
-        for (const entity of frond.entities) {
-          for (const name of Object.keys(entity.entityClass.getAdapters() ?? {})) {
-            if (known.includes(name)) continue;
-            findings.push({
-              severity: 'warning',
-              code: 'unknown-adapter',
-              filePath: entity.filePath,
-              subject: entity.name,
-              message: `states \`adapters: { ${name} }\`, and this project depends on no adapter `
-                + `that answers to it. It depends on ${known.join(', ')}. Nothing reads the entry, `
-                + 'so it is inert — a typo, or a dependency that was never added.',
-            });
-          }
-        }
-      }
-    }
-
-    /**
-     * A `pattern` that backtracks super-linearly. The pattern is fixed at declaration and
-     * the string tested against it is not: whoever calls the facade chooses it, so the cost
-     * of one match is theirs to set. Judged HERE because a regex says the same thing on
-     * every run — checking it per row would pay for a verdict that never changes.
-     *
-     * `safe-regex` reads the star height, which is the common shape and not every one:
-     * `(a|a)*b` backtracks too and passes. Reported as a suspicion, never as a refusal.
-     */
-    for (const frond of fronds) {
-      for (const entity of frond.entities) {
-        for (const [key, field] of Object.entries(entity.entityClass.getFields())) {
-          for (const pattern of Shapes.patterns(field.shape)) {
-            if (safeRegex(pattern)) continue;
-            findings.push({
-              severity: 'warning',
-              code: 'super-linear-pattern',
-              filePath: entity.filePath,
-              subject: `${entity.name}.${key}`,
-              message: `states \`pattern: ${JSON.stringify(pattern)}\`, whose nested repetition `
-                + 'backtracks super-linearly. A value a caller chooses can hold the event loop '
-                + 'for seconds — rewrite the repeated group, or bound the field with `max`.',
-            });
-          }
-        }
-      }
-    }
-
-    /**
-     * A warning, not a refusal: it resolves today and the app runs. What it costs is
-     * paid once, late — the day the frond it reaches into is deployed on its own.
-     */
-    for (const reach of await crossFrondImports(fronds)) {
-      findings.push({
-        severity: 'warning',
-        code: reach.rule,
-        filePath: reach.filePath,
-        message: reach.message,
-      });
-    }
-
-    const conventions = resolveConventions(config.conventions);
-
-    /**
-     * What no convention names. Reported before the declarations below, because a frond
-     * with nowhere to put a word is why the word ends up in a handler.
-     */
-    for (const unplaced of await outsideConventions(fronds, conventions)) {
-      findings.push({
-        severity: 'warning',
-        code: unplaced.rule,
-        filePath: unplaced.filePath,
-        subject: unplaced.frond,
-        message: unplaced.message,
-      });
-    }
-
-    /**
-     * The same shape of warning, one file lower: what the handler holds still runs, and
-     * what it costs is the next caller — a test, a second operation, another handler —
-     * that cannot reach it without moving it first.
-     */
-    for (const held of await handlerDeclarations(fronds, conventions)) {
-      findings.push({
-        severity: 'warning',
-        code: held.rule,
-        filePath: held.filePath,
-        subject: `${held.handler}.${held.subject}`,
-        message: held.message,
-      });
-    }
-
-    findings.push(...facadeFindings(root, fronds));
-
-    return { fronds: fronds.length, handlers, findings };
-  }
-}
-
-/**
- * A facade module older than the handlers it was read off.
- *
- * An ABSENT module needs no finding: a page importing one fails to resolve, loudly, and a
- * backend project never imports one at all — warning there would fire on every project that
- * does not want a facade, which is most of them.
- *
- * A STALE one is the silent case. The import resolves, the operations are the old ones, and a
- * renamed op compiles against a name nothing serves any more. An mtime is the whole check.
- */
-function facadeFindings(root: string, fronds: readonly { handlers: readonly { filePath: string }[] }[]): Diagnostic[] {
-  const facade = join(root, dirname(DEFAULT_OUT), FACADE_OUT);
-  const written = statSync(facade, { throwIfNoEntry: false })?.mtimeMs;
-  if (written === undefined) return [];
-
-  const newer = fronds
-    .flatMap((frond) => frond.handlers)
-    .filter((handler) => (statSync(handler.filePath, { throwIfNoEntry: false })?.mtimeMs ?? 0) > written);
-
-  if (newer.length === 0) return [];
-
-  return [{
-    severity: 'warning',
-    code: 'facade-stale',
-    filePath: facade,
-    subject: `${newer.length} handler${newer.length > 1 ? 's' : ''}`,
-    message: 'The facade module is older than the handlers it was read off, so a page checks its '
-      + 'calls against operations that may no longer exist. Run `fougere build`.',
-  }];
-}
-

package/fronds/analysis/handlers/DevtoolsHandler.ts

@@ -1,97 +0,0 @@
-import { createHttpTransport } from '@fougere/transport-http/client';
-import type { CallPage, CallRecord } from '@fougere/core';
-import ProjectScan from '../services/ProjectScan.js';
-import { remotesOf } from '@fougere/core/node';
-
-/**
- * Where an app answers in development — Nuxt, Next and the site all sit there, so it is a
- * convention and not a setting. A port belongs to the HOST, though, and this project states
- * none: an app served anywhere else is named the way `FOUGERE_LOG_LEVEL` names a level the
- * file did not, and `--url` still wins over both.
- */
-const LOCAL = 'http://127.0.0.1:3000';
-
-function local(): string {
-  return trimmed(process.env.FOUGERE_URL || LOCAL);
-}
-
-/** One address that was asked, and what came back from it. */
-export interface CallSource {
-  url: string;
-  /** The frond `remotes:` names at this address, when that is where it came from. */
-  frond?: string;
-  cursor: number;
-  inFlight: number;
-  dropped: number;
-  /** Present instead of the numbers when the address did not answer, or serves no log. */
-  refusal?: string;
-}
-
-/**
- * Every app of this project, read at once.
- *
- * A reader pulls: no app registers anywhere, and an app started alone depends on nothing.
- * The price is knowing the addresses, which the project already states — `remotes:` says
- * where a call goes, so it also says where the other half of a call can be watched.
- */
-export interface CallsView {
-  sources: CallSource[];
-  /** Every call, oldest first, each carrying the address it was read from. */
-  calls: (CallRecord & { source: string })[];
-}
-
-export default class DevtoolsHandler {
-  constructor(private projectScan: ProjectScan) {}
-
-  /** Read what the running apps have dispatched since a cursor per address. */
-  async execute(input: { url?: string; root?: string; since?: Record<string, number> }): Promise<CallsView> {
-    const asked = input.url ? [{ url: trimmed(input.url) }] : await this.addresses(input.root);
-    const since = input.since ?? {};
-
-    const read = await Promise.all(asked.map(async (one): Promise<CallSource & { calls: CallRecord[] }> => {
-      try {
-        const page = await createHttpTransport(one.url)(
-          { entity: 'rpc', op: 'calls' },
-          { params: {}, query: {}, input: { since: since[one.url] ?? 0 }, state: {} },
-        ) as CallPage;
-
-        return { ...one, cursor: page.cursor, inFlight: page.inFlight, dropped: page.dropped, calls: page.calls };
-      } catch (err) {
-        // An address that does not answer is a source with a reason, not a missing source:
-        // an app not started and an app without the package are different facts, and both
-        // are worth seeing beside the ones that answered.
-        return { ...one, cursor: since[one.url] ?? 0, inFlight: 0, dropped: 0, calls: [], refusal: said(err) };
-      }
-    }));
-
-    return {
-      sources: read.map(({ calls: _calls, ...source }) => source),
-      calls: read
-        .flatMap(({ url, calls }) => calls.map((call) => ({ ...call, source: url })))
-        .sort((a, b) => a.startedAt - b.startedAt || a.seq - b.seq),
-    };
-  }
-
-  /**
-   * The addresses this project declares, plus the local one.
-   *
-   * `remotes:` is the operator's statement of where a call goes; reading it here is not a
-   * second source of truth, it is the same one read for the other direction.
-   */
-  private async addresses(root?: string): Promise<{ url: string; frond?: string }[]> {
-    const { config } = await this.projectScan.at(root);
-    const here = local();
-    const remotes = Object.entries(remotesOf(config))
-      .map(([frond, url]) => ({ url: trimmed(url), frond }));
-
-    return [{ url: here }, ...remotes.filter((one) => one.url !== here)];
-  }
-}
-
-function trimmed(url: string): string {
-  return url.replace(/\/$/, '');
-}
-
-function said(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}

package/fronds/analysis/handlers/ExplainHandler.ts

@@ -1,263 +0,0 @@
-import {
-  addressOf,
-  resolveEffectiveOperations,
-  type EffectiveOperation,
-  type OperationContract,
-} from '@fougere/core';
-import { relative } from 'node:path';
-import ProjectScan from '../services/ProjectScan.js';
-import { ANONYMOUS_SCHEMA_NAME, type SchemaView } from '@fougere/schema';
-import { remotesOf } from '@fougere/core/node';
-
-type Cardinality = NonNullable<OperationContract['cardinality']>;
-type Binding = EffectiveOperation['binding'][number];
-
-export type ExplainedBinding =
-  | { kind: 'collector'; typeName: string }
-  | { kind: 'fact'; factName: string }
-  | { kind: 'param'; name: string; coerce?: 'number' | 'boolean' }
-  | { kind: 'input' }
-  | { kind: 'context' }
-  | { kind: 'query' };
-
-export interface ExplainedParameter {
-  name: string;
-  type: string | null;
-  optional: boolean;
-  nullable: boolean;
-  undefinable: boolean;
-  binding: ExplainedBinding | null;
-}
-
-export interface ExplainedCollector {
-  typeName: string;
-  class: string;
-  file: string;
-}
-
-/** Stable, JSON-shaped projection of core's canonical EffectiveOperation. */
-export interface ExplainResult {
-  operation: string;
-  handler: {
-    class: string;
-    address: string;
-    method: string;
-    file: string | null;
-  };
-  kind: 'query' | 'command';
-  description: string | null;
-  input: string | null;
-  output: { type: string; cardinality: Cardinality | null } | null;
-  parameters: ExplainedParameter[];
-  collectors: ExplainedCollector[];
-  contexts: string[];
-  semantics: EffectiveOperation['semantics'];
-  exposure: {
-    surfaces: string[];
-    adapters: string[];
-  };
-  placement: {
-    frond: string;
-    runtime: 'local' | 'remote';
-    remote: string | null;
-  };
-  /** Where the work GOES, next to where it answers — and how much of it leaves the process. */
-  reach: {
-    fronds: { frond: string; runtime: 'local' | 'remote' }[];
-    hops: number;
-  };
-}
-
-/** What this project serves, when no single operation was named. */
-export interface ExplainListing {
-  fronds: {
-    name: string;
-    runtime: 'local' | 'remote';
-    remote: string | null;
-    operations: number;
-  }[];
-  operations: string[];
-}
-
-interface Selector {
-  frond?: string;
-  surface?: string;
-  address: string;
-  op: string;
-}
-
-/** Read one operation directly from the model boot and check also consume. */
-export default class ExplainHandler {
-  constructor(private projectScan: ProjectScan) {}
-
-  /** The names this project serves — the list `explain` used to spell in a refusal only. */
-  async list(input: { root?: string }): Promise<ExplainListing> {
-    const { scan, model } = await this.modelOf(input.root);
-    const remotes = remotesOf(scan.config);
-    const counted = new Map<string, number>();
-    for (const operation of model.operations) {
-      const frond = operation.placement.frond;
-      counted.set(frond, (counted.get(frond) ?? 0) + 1);
-    }
-
-    return {
-      fronds: scan.fronds.map((frond) => ({
-        name: frond.name,
-        runtime: remotes[frond.name] ? 'remote' as const : 'local' as const,
-        remote: remotes[frond.name] ?? null,
-        operations: counted.get(frond.name) ?? 0,
-      })).sort((a, b) => a.name.localeCompare(b.name)),
-      operations: model.operations.map((operation) => operation.id).sort(),
-    };
-  }
-
-  private async modelOf(root?: string) {
-    const scan = await this.projectScan.at(root);
-
-    return {
-      scan,
-      model: resolveEffectiveOperations(scan.fronds, {
-        diagnostics: scan.diagnostics,
-        remotes: remotesOf(scan.config),
-        adapters: scan.config.adapters,
-      }),
-    };
-  }
-
-  /** Print the contract one operation will be served under. */
-  async execute(input: { operation?: string; root?: string; json?: boolean }): Promise<ExplainResult> {
-    const requested = input.operation?.trim();
-    if (!requested) throw new Error('Usage: fougere explain <Operation> [--json] [--root <directory>]');
-
-    const selector = parseSelector(requested);
-    const { scan, model } = await this.modelOf(input.root);
-    const candidates = model.operations.filter((operation) => matches(operation, selector));
-
-    if (candidates.length === 0) {
-      const failed = model.resolutionDiagnostics.find((diagnostic) =>
-        diagnostic.subject?.toLowerCase().includes(`.${selector.op.toLowerCase()}`)
-        && diagnostic.subject.toLowerCase().includes(selector.address.toLowerCase()));
-      if (failed) throw new Error(`[${failed.code}] ${failed.message}`);
-
-      const available = model.operations.map((operation) => operation.id).sort();
-      throw new Error(
-        `Unknown operation '${requested}'. `
-        + (available.length > 0
-          ? `Available operations: ${available.join(', ')}.`
-          : 'This project exposes no resolved operation.'),
-      );
-    }
-
-    if (candidates.length > 1) {
-      throw new Error(
-        `Ambiguous operation '${requested}'. Matches: `
-        + `${candidates.map((operation) => operation.id).sort().join(', ')}. `
-        + 'Use one of these qualified names.',
-      );
-    }
-
-    const selected = candidates[0]!;
-    const invalid = model.resolutionDiagnostics.find((diagnostic) =>
-      diagnostic.subject?.startsWith(`${selected.handler.className}.${selected.name}`));
-    if (invalid) throw new Error(`[${invalid.code}] ${invalid.message}`);
-
-    return project(selected, scan.root);
-  }
-}
-
-function project(operation: EffectiveOperation, root: string): ExplainResult {
-  return {
-    operation: operation.operation,
-    handler: {
-      class: operation.implementation.className,
-      address: operation.handler.address,
-      method: operation.implementation.method,
-      file: operation.implementation.filePath
-        ? relative(root, operation.implementation.filePath)
-        : null,
-    },
-    kind: operation.kind,
-    description: operation.description ?? null,
-    input: inputTypeOf(operation),
-    output: outputOf(operation),
-    parameters: operation.parameters.map((parameter) => ({
-      name: parameter.name,
-      type: parameter.type,
-      optional: parameter.optional,
-      nullable: parameter.nullable,
-      undefinable: parameter.undefinable,
-      binding: bindingOf(parameter.binding),
-    })),
-    collectors: operation.collectors.map((collector) => ({
-      typeName: collector.typeName,
-      class: collector.className,
-      file: relative(root, collector.filePath),
-    })),
-    contexts: operation.contexts,
-    semantics: operation.semantics,
-    exposure: operation.exposure,
-    placement: {
-      frond: operation.placement.frond,
-      runtime: operation.placement.runtime,
-      remote: operation.placement.remote ?? null,
-    },
-    reach: operation.reach,
-  };
-}
-
-function parseSelector(value: string): Selector {
-  const dot = value.lastIndexOf('.');
-  if (dot <= 0 || dot === value.length - 1) {
-    throw new Error(`Invalid operation '${value}'. Expected '<Handler>.<method>', for example 'Post.publish'.`);
-  }
-
-  const path = value.slice(0, dot).split('/').filter(Boolean);
-  if (path.length === 0 || path.length > 3) {
-    throw new Error(`Invalid operation '${value}'. Expected 'Post.publish', 'blog/Post.publish', or 'blog/public/Post.publish'.`);
-  }
-
-  const qualifiers = path.slice(0, -1);
-
-  return {
-    ...(qualifiers[0] ? { frond: qualifiers[0] } : {}),
-    ...(qualifiers[1] ? { surface: qualifiers[1] } : {}),
-    address: addressOf(path.at(-1)!),
-    op: value.slice(dot + 1),
-  };
-}
-
-function matches(operation: EffectiveOperation, selector: Selector): boolean {
-  return operation.handler.address.toLowerCase() === selector.address.toLowerCase()
-    && operation.name === selector.op
-    && (!selector.frond || operation.placement.frond === selector.frond)
-    && (!selector.surface || operation.exposure.surfaces.includes(selector.surface));
-}
-
-function inputTypeOf(operation: EffectiveOperation): string | null {
-  const body = operation.parameters.find((parameter) => parameter.binding.source.kind === 'input');
-
-  return body?.type ?? schemaName(operation.input) ?? null;
-}
-
-function outputOf(operation: EffectiveOperation): ExplainResult['output'] {
-  const type = schemaName(operation.output) ?? parsedOutput(operation.signature?.returnType?.raw);
-
-  return type ? { type, cardinality: operation.cardinality ?? null } : null;
-}
-
-function schemaName(schema: SchemaView | undefined): string | undefined {
-  if (!schema) return undefined;
-  if (schema.name && schema.name !== ANONYMOUS_SCHEMA_NAME) return schema.name;
-
-  return schema.derivation?.sourceName;
-}
-
-function parsedOutput(raw: string | undefined): string | undefined {
-  if (!raw) return undefined;
-
-  return raw.startsWith('Promise<') && raw.endsWith('>') ? raw.slice(8, -1) : raw;
-}
-
-function bindingOf(binding: Binding): ExplainedBinding {
-  return { ...binding.source } as ExplainedBinding;
-}