@route-intelligence/shared 2.1.0

package/dist/index.d.ts

@@ -0,0 +1,288 @@
+type RouteNodeType = 'route' | 'layout' | 'template' | 'loading' | 'error' | 'global-error' | 'not-found' | 'forbidden' | 'unauthorized' | 'middleware' | 'api-route' | 'redirect' | 'rewrite' | 'external-url';
+type RouteEdgeType = 'navigation' | 'redirect' | 'permanent-redirect' | 'rewrite' | 'import' | 'layout-parent' | 'template-parent' | 'conditional-navigation' | 'middleware-match' | 'api-call' | 'prefetch' | 'intercepted-by' | 'dependency';
+type ConditionKind = 'auth' | 'role' | 'permission' | 'feature-flag' | 'subscription' | 'locale' | 'env' | 'cookie' | 'header' | 'search-param' | 'query-param' | 'unknown';
+type ConditionConfidence = 'certain' | 'inferred' | 'heuristic';
+interface SourceLocation {
+    filePath: string;
+    line: number;
+    column: number;
+    endLine?: number;
+    endColumn?: number;
+}
+interface Condition {
+    kind: ConditionKind;
+    expression: string;
+    negated: boolean;
+    confidence: ConditionConfidence;
+}
+type DiagnosticSeverity = 'error' | 'warning' | 'info';
+type DiagnosticRuleId = 'dead-route' | 'dead-layout' | 'broken-link' | 'broken-redirect' | 'redirect-cycle' | 'circular-navigation' | 'shadowed-route' | 'duplicate-route' | 'impossible-route' | 'middleware-gap' | 'missing-error-boundary' | 'missing-loading' | 'open-redirect';
+interface Diagnostic {
+    ruleId: DiagnosticRuleId | string;
+    severity: DiagnosticSeverity;
+    message: string;
+    loc?: SourceLocation;
+    nodeId?: string;
+    edgeId?: string;
+}
+type NavigationSource = 'Link' | 'router.push' | 'router.replace' | 'router.prefetch' | 'router.back' | 'router.forward' | 'redirect' | 'permanentRedirect' | 'NextResponse.redirect' | 'NextResponse.rewrite' | 'window.location' | 'window.open' | 'history.pushState' | 'history.replaceState' | 'Navigate' | 'custom' | 'unknown';
+type RuntimeKind = 'nodejs' | 'edge' | 'browser';
+type RenderingKind = 'static' | 'dynamic' | 'isr' | 'streaming';
+interface NodeAttributes {
+    type: RouteNodeType;
+    path: string;
+    filePath: string;
+    segment: string;
+    isDynamic: boolean;
+    isCatchAll: boolean;
+    isOptionalCatchAll: boolean;
+    isParallelSlot: boolean;
+    slotName?: string;
+    isIntercepted: boolean;
+    interceptLevel?: '.' | '..' | '(..)(..)' | '...';
+    isRouteGroup: boolean;
+    groupName?: string;
+    runtime: RuntimeKind;
+    rendering: RenderingKind;
+    isClientComponent: boolean;
+    isServerComponent: boolean;
+    isReachable: boolean;
+    isDead: boolean;
+    depth: number;
+    tags: string[];
+    conditions: Condition[];
+    diagnostics: Diagnostic[];
+    loc: SourceLocation;
+}
+interface EdgeAttributes {
+    type: RouteEdgeType;
+    method?: 'push' | 'replace';
+    isExternal: boolean;
+    source: NavigationSource;
+    conditions: Condition[];
+    loc: SourceLocation;
+    diagnostics: Diagnostic[];
+}
+interface SerializedNode {
+    id: string;
+    attributes: NodeAttributes;
+}
+interface SerializedEdge {
+    id: string;
+    source: string;
+    target: string;
+    attributes: EdgeAttributes;
+}
+interface SerializedGraph {
+    version: '1.0';
+    generatedAt: string;
+    root: string;
+    nodes: SerializedNode[];
+    edges: SerializedEdge[];
+    metadata?: GraphMetadata;
+}
+interface GraphMetadata {
+    pluginIds: string[];
+    totalRoutes: number;
+    totalLayouts: number;
+    totalApiRoutes: number;
+    deadRouteCount: number;
+    cycleCount: number;
+    maintainabilityScore?: number;
+    riskScore?: number;
+}
+declare function createDefaultNodeAttributes(overrides: Partial<NodeAttributes> & Pick<NodeAttributes, 'type' | 'path' | 'filePath'>): NodeAttributes;
+declare function createDefaultEdgeAttributes(overrides: Partial<EdgeAttributes> & Pick<EdgeAttributes, 'type' | 'source'>): EdgeAttributes;
+
+interface PluginCapabilities {
+    supportsAppRouter: boolean;
+    supportsPagesRouter: boolean;
+    supportsMiddleware: boolean;
+    supportsApiRoutes: boolean;
+    supportsI18n: boolean;
+    supportsIncrementalAnalysis: boolean;
+}
+interface PluginConfig {
+    [key: string]: unknown;
+}
+interface ProjectContext {
+    root: string;
+    config: AnalyzerConfig;
+    pluginConfig: PluginConfig;
+}
+interface AnalyzerConfig {
+    root: string;
+    plugins: FrameworkPlugin[];
+    include?: string[];
+    exclude?: string[];
+    cache?: {
+        enabled: boolean;
+        directory: string;
+    };
+    output?: {
+        formats: string[];
+        directory: string;
+    };
+    rules?: Record<string, 'error' | 'warn' | 'off'>;
+}
+type RawRouteType = 'route' | 'layout' | 'template' | 'loading' | 'error' | 'global-error' | 'not-found' | 'forbidden' | 'unauthorized' | 'middleware' | 'api-route';
+interface RawRoute {
+    id: string;
+    type: RawRouteType;
+    filePath: string;
+    urlPath: string;
+    segment: string;
+    isDynamic: boolean;
+    isCatchAll: boolean;
+    isOptionalCatchAll: boolean;
+    isParallelSlot: boolean;
+    slotName?: string;
+    isIntercepted: boolean;
+    interceptLevel?: '.' | '..' | '(..)(..)' | '...';
+    isRouteGroup: boolean;
+    groupName?: string;
+    parentLayoutId?: string;
+    parentTemplateId?: string;
+    tags: string[];
+}
+type NavigationDestination = {
+    kind: 'static';
+    path: string;
+} | {
+    kind: 'template-literal';
+    template: string;
+    params: string[];
+} | {
+    kind: 'dynamic';
+    expression: string;
+} | {
+    kind: 'external';
+    url: string;
+};
+interface NavigationCall {
+    callee: string;
+    destination: NavigationDestination;
+    method?: 'push' | 'replace';
+    conditions: Condition[];
+    loc: SourceLocation;
+}
+interface JSXLink {
+    componentName: string;
+    destination: NavigationDestination;
+    prefetch?: boolean;
+    conditions: Condition[];
+    loc: SourceLocation;
+}
+interface SemanticImport {
+    moduleSpecifier: string;
+    namedImports: string[];
+    defaultImport?: string;
+    loc: SourceLocation;
+}
+interface SemanticExport {
+    name: string;
+    isDefault: boolean;
+    loc: SourceLocation;
+}
+interface ComponentDeclaration {
+    name: string;
+    isDefault: boolean;
+    loc: SourceLocation;
+}
+interface ConditionalBlock {
+    expression: string;
+    conditions: Condition[];
+    loc: SourceLocation;
+}
+interface SemanticFile {
+    readonly path: string;
+    readonly isClientComponent: boolean;
+    readonly isServerComponent: boolean;
+    readonly exports: ReadonlyArray<SemanticExport>;
+    readonly imports: ReadonlyArray<SemanticImport>;
+    readonly components: ReadonlyArray<ComponentDeclaration>;
+    readonly navigationCalls: ReadonlyArray<NavigationCall>;
+    readonly jsxLinks: ReadonlyArray<JSXLink>;
+    readonly conditionalBlocks: ReadonlyArray<ConditionalBlock>;
+    /** Escape hatch for plugin-specific analysis — typed as unknown to avoid ts-morph in shared */
+    readonly sourceFile: unknown;
+}
+interface DiscoveredEdge {
+    sourceId: string;
+    targetId?: string;
+    targetPath?: string;
+    type: RouteEdgeType;
+    source: NavigationSource;
+    method?: 'push' | 'replace';
+    isExternal: boolean;
+    conditions: Condition[];
+    loc: SourceLocation;
+}
+interface FileAnalysisResult {
+    filePath: string;
+    edges: DiscoveredEdge[];
+    conditions: Condition[];
+    tags: string[];
+    diagnostics: Diagnostic[];
+}
+interface RouteGraphLike {
+    hasNode(id: string): boolean;
+    getNodePath(id: string): string | undefined;
+    findNodeByPath(path: string): string | undefined;
+    addNode(id: string, attributes: NodeAttributes): void;
+    addEdge(id: string, source: string, target: string, attributes: EdgeAttributes): void;
+    getAllNodeIds(): string[];
+    getAllEdges(): Array<{
+        id: string;
+        source: string;
+        target: string;
+    }>;
+}
+interface FrameworkPlugin {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly capabilities: PluginCapabilities;
+    detect(ctx: ProjectContext): Promise<boolean>;
+    configure(ctx: ProjectContext): Promise<PluginConfig>;
+    discoverRoutes(ctx: ProjectContext): AsyncIterable<RawRoute>;
+    analyzeFile(file: SemanticFile, ctx: AnalysisContext): Promise<FileAnalysisResult>;
+    enrichGraph(graph: RouteGraphLike, ctx: ProjectContext): Promise<void>;
+    runDiagnostics(graph: RouteGraphLike): Promise<Diagnostic[]>;
+    onFileChange?(event: FileChangeEvent, ctx: ProjectContext): Promise<InvalidationSet>;
+}
+interface AnalysisContext extends ProjectContext {
+    graph: RouteGraphLike;
+    routes: Map<string, RawRoute>;
+}
+interface FileChangeEvent {
+    type: 'add' | 'change' | 'unlink';
+    path: string;
+}
+interface InvalidationSet {
+    files: string[];
+    nodeIds: string[];
+}
+interface GraphPatch {
+    addedNodes: Array<{
+        id: string;
+        attributes: NodeAttributes;
+    }>;
+    removedNodeIds: string[];
+    addedEdges: Array<{
+        id: string;
+        source: string;
+        target: string;
+        attributes: EdgeAttributes;
+    }>;
+    removedEdgeIds: string[];
+    modifiedNodeIds: string[];
+}
+interface AnalysisResult {
+    graph: RouteGraphLike;
+    diagnostics: Diagnostic[];
+    metadata: GraphMetadata;
+}
+declare function defineConfig(config: AnalyzerConfig): AnalyzerConfig;
+
+export { type AnalysisContext, type AnalysisResult, type AnalyzerConfig, type ComponentDeclaration, type Condition, type ConditionConfidence, type ConditionKind, type ConditionalBlock, type Diagnostic, type DiagnosticRuleId, type DiagnosticSeverity, type DiscoveredEdge, type EdgeAttributes, type FileAnalysisResult, type FileChangeEvent, type FrameworkPlugin, type GraphMetadata, type GraphPatch, type InvalidationSet, type JSXLink, type NavigationCall, type NavigationDestination, type NavigationSource, type NodeAttributes, type PluginCapabilities, type PluginConfig, type ProjectContext, type RawRoute, type RawRouteType, type RenderingKind, type RouteEdgeType, type RouteGraphLike, type RouteNodeType, type RuntimeKind, type SemanticExport, type SemanticFile, type SemanticImport, type SerializedEdge, type SerializedGraph, type SerializedNode, type SourceLocation, createDefaultEdgeAttributes, createDefaultNodeAttributes, defineConfig };

package/dist/index.js

@@ -0,0 +1,43 @@
+// src/graph.types.ts
+function createDefaultNodeAttributes(overrides) {
+  return {
+    segment: "",
+    isDynamic: false,
+    isCatchAll: false,
+    isOptionalCatchAll: false,
+    isParallelSlot: false,
+    isIntercepted: false,
+    isRouteGroup: false,
+    runtime: "nodejs",
+    rendering: "static",
+    isClientComponent: false,
+    isServerComponent: true,
+    isReachable: false,
+    isDead: false,
+    depth: 0,
+    tags: [],
+    conditions: [],
+    diagnostics: [],
+    loc: { filePath: overrides.filePath, line: 1, column: 1 },
+    ...overrides
+  };
+}
+function createDefaultEdgeAttributes(overrides) {
+  return {
+    isExternal: false,
+    conditions: [],
+    loc: { filePath: "", line: 0, column: 0 },
+    diagnostics: [],
+    ...overrides
+  };
+}
+
+// src/plugin.types.ts
+function defineConfig(config) {
+  return config;
+}
+export {
+  createDefaultEdgeAttributes,
+  createDefaultNodeAttributes,
+  defineConfig
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@route-intelligence/shared",
+  "version": "2.1.0",
+  "description": "Shared types and utilities for Route Intelligence",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@route-intelligence/tsconfig": "*",
+    "@types/node": "^22.15.32",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}