@craft-ts/dev-tools 0.7.0-beta.13

package/src/scripts/architecture-graph.d.ts

@@ -0,0 +1,368 @@
+import type { DependencyGraph, DependencyGraphEdge, DependencyGraphEdgeFor, DependencyGraphEdgeKind, DependencyGraphNode, DependencyGraphNodeKind, DependencyGraphNodeRegistry, DependencyGraphProof } from './dependency-graph.js';
+export type ArchitectureProvidedOn = {
+    kind: DependencyGraphNodeKind;
+    name: string;
+    file?: string;
+};
+export type ArchitectureCatalog = {
+    version: 1;
+    graphHash: string;
+    routes: readonly string[];
+    services: readonly string[];
+    components: readonly string[];
+    primitives: readonly string[];
+    sources: readonly string[];
+    serverFunctionFamilies: readonly string[];
+    httpEndpoints: readonly {
+        method: string;
+        url: string;
+    }[];
+    uniques: readonly string[];
+    providers: readonly string[];
+    routeProviders: Readonly<Record<string, readonly string[]>>;
+    componentProviders: Readonly<Record<string, readonly string[]>>;
+    providedOn: Readonly<Record<string, readonly ArchitectureProvidedOn[]>>;
+    collisions: {
+        services: Readonly<Record<string, readonly string[]>>;
+        components: Readonly<Record<string, readonly string[]>>;
+        routes: Readonly<Record<string, readonly string[]>>;
+    };
+    browserBoundaryServices: readonly string[];
+    scopes: Readonly<Record<string, string>>;
+};
+export type ArchitectureNodeView<C extends ArchitectureCatalog = ArchitectureCatalog, K extends DependencyGraphNodeKind = DependencyGraphNodeKind> = {
+    id: string;
+    kind: K;
+    label: string;
+    filePath?: string;
+    line?: number;
+    details?: DependencyGraphNodeRegistry[K];
+    provider(name: CatalogProviders<C>): ArchitectureNodeView<C>;
+    providers(): ArchitectureNodeView<C>[];
+    outgoing(kind?: DependencyGraphEdgeKind): DependencyGraphEdge[];
+    incoming(kind?: DependencyGraphEdgeKind): DependencyGraphEdge[];
+    httpEndpoints(): {
+        method: string;
+        url: string;
+    }[];
+};
+export type ArchitectureServiceFilter = {
+    browserBoundary?: boolean;
+    scope?: string;
+};
+export type ArchitectureGraphView<C extends ArchitectureCatalog = ArchitectureCatalog> = {
+    graph: DependencyGraph;
+    catalog: C;
+    nodes<K extends DependencyGraphNodeKind>(kind: K): ArchitectureNodeView<C, K>[];
+    edges<K extends DependencyGraphEdgeKind>(kind: K): DependencyGraphEdgeFor<K>[];
+    pathsBetween(fromId: string, toId: string, maxDepth?: number): ArchitectureGraphPath[];
+    proofs(edge: DependencyGraphEdge): DependencyGraphProof[];
+    route(path: CatalogRoutes<C>, file?: string): ArchitectureNodeView<C>;
+    service(name: CatalogServices<C>, file?: string): ArchitectureNodeView<C>;
+    component(name: CatalogComponents<C>, file?: string): ArchitectureNodeView<C>;
+    craftMethod(name: string, file?: string): ArchitectureNodeView<C>;
+    httpEndpoint(method: CatalogHttp<C>['method'], url: CatalogHttp<C>['url']): ArchitectureNodeView<C>;
+    providedOn(name: CatalogProviders<C>): ArchitectureNodeView<C>[];
+    services(filter?: ArchitectureServiceFilter): ArchitectureNodeView<C>[];
+    usingHttp(): ArchitectureNodeView<C>[];
+    usingTemporal(): ArchitectureNodeView<C>[];
+    dependingOnBrowserBoundary(): ArchitectureNodeView<C>[];
+    craftMethods(): ArchitectureNodeView<C>[];
+    primitives(primitive?: string): ArchitectureNodeView<C>[];
+    sources(): ArchitectureNodeView<C>[];
+    serverFunctionFamilies(): ArchitectureNodeView<C>[];
+    serverFunctionMiddlewares(): ArchitectureNodeView<C>[];
+    clientFunctionMiddlewares(): ArchitectureNodeView<C>[];
+    handshakes(): ArchitectureNodeView<C>[];
+    serverFunctionFamily(id: string): ArchitectureNodeView<C>;
+    httpEndpoints(): ArchitectureNodeView<C>[];
+    unique(value: CatalogUniques<C>): ArchitectureNodeView<C>;
+    uniques(): ArchitectureNodeView<C>[];
+};
+export type ArchitectureGraphPath = {
+    readonly nodes: DependencyGraphNode[];
+    readonly edges: DependencyGraphEdge[];
+    readonly proofs: DependencyGraphProof[];
+};
+export type ExclusiveLinkViolation = {
+    from: string;
+    to: string;
+    kind: DependencyGraphEdgeKind;
+};
+export type SensitiveOutputProtectionOptions = {
+    readonly categories?: readonly string[];
+    readonly allowUnknown?: boolean;
+};
+export type SensitiveOutputProtectionViolation = {
+    readonly code: 'SENSITIVE_OUTPUT_UNPROTECTED' | 'SENSITIVE_OUTPUT_UNKNOWN_PROTECTION';
+    readonly classification: string;
+    readonly outputId: string;
+    readonly message: string;
+    readonly path: readonly string[];
+    readonly proofs: readonly DependencyGraphProof[];
+};
+type CatalogRoutes<C extends ArchitectureCatalog> = C['routes'][number];
+type CatalogServices<C extends ArchitectureCatalog> = C['services'][number];
+type CatalogComponents<C extends ArchitectureCatalog> = C['components'][number];
+type CatalogProviders<C extends ArchitectureCatalog> = C['providers'][number];
+type CatalogHttp<C extends ArchitectureCatalog> = C['httpEndpoints'][number];
+type CatalogUniques<C extends ArchitectureCatalog> = C['uniques'][number];
+export declare function graphHash(graph: DependencyGraph): string;
+export declare function relativeGraphPath(graph: DependencyGraph, filePath: string | undefined): string | undefined;
+export declare function buildArchitectureCatalog(graph: DependencyGraph): ArchitectureCatalog;
+export declare function architectureCatalogToTypeScript(catalog: ArchitectureCatalog): string;
+export declare function createArchitectureGraph<C extends ArchitectureCatalog = ArchitectureCatalog>(graph: DependencyGraph, catalog?: C): ArchitectureGraphView<C>;
+/**
+ * Enumerates short, explainable paths without imposing a domain-specific
+ * notion of what a backend node means. Rules can first select typed nodes and
+ * then ask this generic primitive for paths between their ids.
+ */
+export declare function dependencyGraphPathsBetween(graph: DependencyGraph, fromId: string, toId: string, maxDepth?: number): ArchitectureGraphPath[];
+/**
+ * Checks the first conservative security policy for classified server
+ * responses. Capabilities are repository-declared on middleware nodes through
+ * `analyzeDependencyGraph({ middlewareCapabilities })`.
+ */
+export declare function sensitiveOutputProtectionViolations(graph: DependencyGraph, options?: SensitiveOutputProtectionOptions): SensitiveOutputProtectionViolation[];
+export declare function assertSensitiveOutputsProtected(graph: DependencyGraph, options?: SensitiveOutputProtectionOptions): void;
+export declare function exclusiveLinkViolations(left: ArchitectureNodeView<ArchitectureCatalog>, right: ArchitectureNodeView<ArchitectureCatalog>): ExclusiveLinkViolation[];
+export declare function noExclusiveLink(left: ArchitectureNodeView<ArchitectureCatalog>, right: ArchitectureNodeView<ArchitectureCatalog>): void;
+export type CraftUniqueViolation = {
+    kind: 'duplicate' | 'non-static';
+    id: string;
+    label: string;
+    callSites: readonly {
+        filePath?: string;
+        line?: number;
+        ownerId?: string;
+    }[];
+};
+export declare function craftUniqueViolations(graph: DependencyGraph): CraftUniqueViolation[];
+export declare function assertCraftUnique(graph: DependencyGraph): void;
+export type CraftHandshakeDiagnosticCode = 'CRAFT_HANDSHAKE_MISSING_COUNTERPART' | 'CRAFT_HANDSHAKE_NOT_STATIC' | 'CRAFT_HANDSHAKE_DUPLICATE_NAME';
+export type CraftHandshakeViolation = {
+    readonly code: CraftHandshakeDiagnosticCode;
+    readonly message: string;
+    readonly name: string;
+    readonly filePath?: string;
+    readonly line?: number;
+};
+/**
+ * Vérifie qu'un `craftHandshake(...)` est bien tenu des deux côtés.
+ *
+ * C'est le pendant exact de `assertCraftUnique`, avec le prédicat inverse :
+ * `craftUnique` exige un seul site, un handshake en exige **un de chaque
+ * côté**. Le contrôle compare des identifiants, pas des noms de clés devinés
+ * dans l'AST : il n'a rien d'heuristique.
+ */
+export declare function craftHandshakeViolations(graph: DependencyGraph): CraftHandshakeViolation[];
+export declare function assertCraftHandshake(graph: DependencyGraph): void;
+export type RouteDiProofViolationKind = 'missing-di-proof' | 'unarmed-mapper' | 'missing-pending-proof' | 'missing-error-proof' | 'missing-exception-assert' | 'missing-global-error-proof' | 'missing-route-load-error-proof';
+export type RouteDiProofViolation = {
+    kind: RouteDiProofViolationKind;
+    label: string;
+    filePath?: string;
+    line?: number;
+};
+export declare function routeDiProofViolations(graph: DependencyGraph): RouteDiProofViolation[];
+export declare function assertRouteDiProofs(graph: DependencyGraph): void;
+export type RouteComponentFileViolation = {
+    kind: 'route-and-component-same-file' | 'components-share-file';
+    route: string;
+    component: string;
+    components: readonly string[];
+    routeFile: string;
+    componentFile: string;
+};
+export declare function routeComponentFileViolations(graph: DependencyGraph): RouteComponentFileViolation[];
+export declare function assertRouteComponentsInSeparateFiles(graph: DependencyGraph): void;
+export type HttpEndpointUniqueViolation = {
+    id: string;
+    label: string;
+    method: string;
+    url: string;
+    callSites: readonly {
+        ownerId?: string;
+        filePath?: string;
+        line?: number;
+    }[];
+};
+export declare function httpEndpointUniqueViolations(graph: DependencyGraph): HttpEndpointUniqueViolation[];
+export declare function assertHttpEndpointUnique(graph: DependencyGraph): void;
+export type CraftComputedPureViolation = {
+    kind: 'calls' | 'writes';
+    id: string;
+    label: string;
+    targetId: string;
+    targetLabel: string;
+    filePath?: string;
+    line?: number;
+};
+export declare function craftComputedPureViolations(graph: DependencyGraph): CraftComputedPureViolation[];
+export declare function assertCraftComputedPure(graph: DependencyGraph): void;
+export type DependencyCycle = {
+    ids: readonly string[];
+    labels: readonly string[];
+};
+export declare function dependencyCycleViolations(graph: DependencyGraph): DependencyCycle[];
+export declare function assertNoDependencyCycles(graph: DependencyGraph): void;
+export type AppConfigRouteCycle = {
+    appConfigFile: string;
+    routeFile: string;
+    routeLabels: readonly string[];
+};
+/**
+ * App configuration owns route registration. A route module may expose route
+ * metadata to the config, but the two modules must not import each other: the
+ * cycle makes the inferred provider context unstable and invites manual DI
+ * fallbacks.
+ */
+export declare function appConfigRouteCycleViolations(graph: DependencyGraph): AppConfigRouteCycle[];
+export declare function assertNoAppConfigRouteCycles(graph: DependencyGraph): void;
+export type PathBoundaryConstraint = {
+    source: string;
+    onlyDependOn?: readonly string[];
+    forbidTarget?: readonly string[];
+};
+export type PathBoundaryOptions = {
+    edgeKinds?: readonly DependencyGraphEdgeKind[];
+    constraints: readonly PathBoundaryConstraint[];
+};
+export type PathBoundaryViolation = {
+    fromId: string;
+    toId: string;
+    fromLabel: string;
+    toLabel: string;
+    fromPath: string;
+    toPath: string;
+    edgeKind: DependencyGraphEdgeKind;
+    source: string;
+    reason: 'allowlist' | 'denylist';
+};
+export declare function pathBoundaryViolations(graph: DependencyGraph, options: PathBoundaryOptions): PathBoundaryViolation[];
+export declare function assertPathBoundaries(graph: DependencyGraph, options: PathBoundaryOptions): void;
+export type MutationReactOnOptions = {
+    allow?: readonly string[];
+};
+export type MutationReactOnViolation = {
+    id: string;
+    label: string;
+    filePath?: string;
+    line?: number;
+};
+export declare function mutationReactOnViolations(graph: DependencyGraph, options?: MutationReactOnOptions): MutationReactOnViolation[];
+export declare function assertMutationHasReactOn(graph: DependencyGraph, options?: MutationReactOnOptions): void;
+export type PersistedUniqueViolation = {
+    id: string;
+    label: string;
+    primitive: string;
+    filePath?: string;
+    line?: number;
+};
+export declare function persistedPrimitiveUniqueViolations(graph: DependencyGraph): PersistedUniqueViolation[];
+export declare function assertPersistedPrimitiveHasUnique(graph: DependencyGraph): void;
+export type InsertSelectUniqueViolation = {
+    key: string;
+    hostId: string;
+    hostLabel: string;
+    callSites: readonly {
+        filePath?: string;
+        line?: number;
+    }[];
+};
+export declare function insertSelectUniqueViolations(graph: DependencyGraph): InsertSelectUniqueViolation[];
+export declare function assertInsertSelectUnique(graph: DependencyGraph): void;
+export type CraftEffectNetworkViolation = {
+    kind: 'http' | 'mutation';
+    id: string;
+    label: string;
+    targetId: string;
+    targetLabel: string;
+    filePath?: string;
+    line?: number;
+};
+export type LoaderRequirementContext = {
+    graph: DependencyGraph;
+    primitive: DependencyGraphNode;
+    target: DependencyGraphNode;
+    edge: DependencyGraphEdge;
+};
+export type LoaderRequirement = {
+    /** Human-readable name used in the diagnostic. */
+    label: string;
+    /** Returns true when this target satisfies the requirement. */
+    matches: (context: LoaderRequirementContext) => boolean;
+};
+export type PrimitiveLoaderRequirements = {
+    /** Primitive names to check. Requirements are OR-ed for each primitive. */
+    primitives: readonly string[];
+    requirements: readonly LoaderRequirement[];
+    /** Explicitly exempted primitive labels for intentional local-state examples. */
+    allow?: readonly string[];
+};
+export type PrimitiveLoaderRequirementViolation = {
+    primitive: string;
+    id: string;
+    label: string;
+    missing: readonly string[];
+    filePath?: string;
+    line?: number;
+};
+/**
+ * Checks that every selected resource has at least one qualifying dependency
+ * from its `loader`. This is intentionally predicate-based: query/mutation
+ * can use HTTP or server functions, while an Effect application can provide a
+ * rule that recognises Effect services or another domain boundary.
+ */
+export declare function primitiveLoaderRequirementViolations(graph: DependencyGraph, rule: PrimitiveLoaderRequirements): PrimitiveLoaderRequirementViolation[];
+export declare function assertPrimitiveLoaderRequirements(graph: DependencyGraph, rule: PrimitiveLoaderRequirements): void;
+export declare function queryMutationServerStateViolations(graph: DependencyGraph): PrimitiveLoaderRequirementViolation[];
+export declare function assertQueryMutationHasServerState(graph: DependencyGraph, options?: Pick<PrimitiveLoaderRequirements, 'allow'>): void;
+export declare function craftEffectNetworkViolations(graph: DependencyGraph): CraftEffectNetworkViolation[];
+export declare function assertCraftEffectNoNetwork(graph: DependencyGraph): void;
+export type CraftEffectImperativeSyncKind = 'state' | 'source' | 'query' | 'mutation' | 'asyncProcess';
+export type CraftEffectImperativeSyncViolation = {
+    kind: CraftEffectImperativeSyncKind;
+    action: 'writes' | 'calls';
+    id: string;
+    label: string;
+    targetId: string;
+    targetLabel: string;
+    filePath?: string;
+    line?: number;
+};
+export declare function craftEffectImperativeSyncViolations(graph: DependencyGraph): CraftEffectImperativeSyncViolation[];
+export declare function assertCraftEffectNoImperativeSync(graph: DependencyGraph): void;
+export type InteractiveElementNamedViolation = {
+    kind: 'missing' | 'non-static' | 'duplicate';
+    id: string;
+    label: string;
+    tag?: string;
+    callSites: readonly {
+        filePath?: string;
+        line?: number;
+    }[];
+};
+export declare function interactiveElementNamedViolations(graph: DependencyGraph): InteractiveElementNamedViolation[];
+export declare function assertInteractiveElementNamed(graph: DependencyGraph): void;
+export type ServerFunctionArchitectureDiagnosticCode = 'CRAFT_SERVER_FUNCTION_CLIENT_FAMILY_MISSING' | 'CRAFT_SERVER_FUNCTION_CLIENT_IMPORTS_SERVER' | 'CRAFT_SERVER_FUNCTION_CLIENT_CONTEXT_REQUIRES_CLIENT_EXPOSURE' | 'CRAFT_SERVER_FUNCTION_HANDSHAKE_NOT_ATTACHED' | 'CRAFT_SERVER_FUNCTION_HANDSHAKE_NOT_EXPECTED' | 'CRAFT_SERVER_FUNCTION_CONTRACT_MISMATCH' | 'CRAFT_SERVER_FUNCTION_DUPLICATE_ID' | 'CRAFT_SERVER_FUNCTION_ORPHAN_CLIENT_FACADE' | 'CRAFT_SERVER_FUNCTION_CLIENT_ID_NOT_UNIQUE' | 'CRAFT_SERVER_FUNCTION_CLIENT_ID_NOT_STATIC' | 'CRAFT_SERVER_FUNCTION_CLIENT_ID_MISMATCH' | 'CRAFT_SERVER_FUNCTION_CLIENT_DEFINITION_MISMATCH' | 'CRAFT_SERVER_FUNCTION_NAMING_CONVENTION_MISSING' | 'CRAFT_SERVER_FUNCTION_MIDDLEWARE_NAMING_CONVENTION_MISSING' | 'CRAFT_SERVER_FUNCTION_MIDDLEWARE_DUPLICATE_ID' | 'CRAFT_SERVER_FUNCTION_MIDDLEWARE_CYCLE' | 'CRAFT_SERVER_FUNCTION_MIDDLEWARE_IMPORTED_BY_CLIENT' | 'CRAFT_SERVER_FUNCTION_CLIENT_MIDDLEWARE_NAMING_CONVENTION_MISSING' | 'CRAFT_SERVER_FUNCTION_CLIENT_MIDDLEWARE_DUPLICATE_ID' | 'CRAFT_SERVER_FUNCTION_CLIENT_MIDDLEWARE_CYCLE' | 'CRAFT_SERVER_FUNCTION_CLIENT_MIDDLEWARE_IMPORTED_BY_SERVER' | 'CRAFT_SERVER_FUNCTION_CLIENT_CONTEXT_UNUSED';
+export type ServerFunctionArchitectureViolation = {
+    readonly code: ServerFunctionArchitectureDiagnosticCode;
+    readonly message: string;
+    readonly family: string;
+    readonly filePath?: string;
+    readonly line?: number;
+};
+/**
+ * Verifies the source-level server-function family contract. The rule is
+ * intentionally independent of a bundler: a production build must fail while
+ * the offending server import is still visible in the TypeScript graph.
+ */
+export declare function serverFunctionArchitectureViolations(graph: DependencyGraph): ServerFunctionArchitectureViolation[];
+export declare function assertServerFunctionArchitecture(graph: DependencyGraph): void;
+export type ArchitectureCheckTarget = 'development' | 'production';
+export declare function assertArchitecture(graph: DependencyGraph, options?: {
+    readonly target?: ArchitectureCheckTarget;
+}): void;
+export declare function assertDeclarativeArchitecture(graph: DependencyGraph, options?: MutationReactOnOptions): void;
+export {};