@amulet-laboratories/astrolabe 0.4.0

package/src/index.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Public type surface for @amulet-laboratories/astrolabe.
+ *
+ * The serialized graph (`AppGraph`) is the durable contract — treat it like an
+ * API. `schemaVersion` bumps when its shape changes in a breaking way.
+ */
+
+/** Canonical node kinds. Adapters map their framework's concepts onto these. */
+export type NodeType =
+  | 'entry'
+  | 'layout'
+  | 'middleware'
+  | 'plugin'
+  | 'route'
+  | 'component'
+  | 'lib-component'
+  | 'composable'
+  | 'store'
+  | 'collection'
+  | 'server'
+  | 'external'
+  | 'config'
+
+/** Canonical edge kinds — the verbs the graph draws between nodes. */
+export type EdgeKind = 'renders' | 'wraps' | 'guards' | 'uses' | 'queries' | 'fetches' | 'reads'
+
+export interface GraphNode {
+  id: string
+  type: NodeType
+  label: string
+  /** Repo-relative path, or a shortened package path for library nodes. */
+  file?: string
+  /** Kind-specific extras: loc, method, props, fields, pkg, group, files, … */
+  meta: Record<string, unknown>
+}
+
+export interface GraphEdge {
+  from: string
+  to: string
+  kind: EdgeKind
+}
+
+export interface Finding {
+  id: string
+  severity: 'warn' | 'info'
+  title: string
+  detail: string
+  /** Node ids this finding is about. */
+  nodes: string[]
+}
+
+export interface Dependency {
+  name: string
+  version: string
+  dev: boolean
+}
+
+export interface Stack {
+  nuxt: string | null
+  packageManager: string | null
+  node: string | null
+  dependencies: Dependency[]
+}
+
+/** The shareable project metadata — no absolute-internal or raw-config fields. */
+export interface Project {
+  name: string
+  description: string
+  root: string
+  modules: string[]
+  stack: Stack
+}
+
+export interface Stats {
+  files: number
+  loc: number
+  contentFiles: number
+}
+
+/** The serialized graph — what `scan()` resolves to and `renderHtml()` consumes. */
+export interface AppGraph {
+  schemaVersion: number
+  project: Project
+  warnings: string[]
+  nodes: GraphNode[]
+  edges: GraphEdge[]
+  findings: Finding[]
+  stats: Stats
+}
+
+/** Scan a web app directory into a serialized graph. */
+export function scan(dir: string): Promise<AppGraph>
+
+/** Render a scanned graph into the self-contained interactive HTML report. */
+export function renderHtml(graph: AppGraph): string
+
+/** The report's views — projections of the one graph. */
+export type ViewName = 'layers' | 'render' | 'data' | 'modules' | 'sitemap' | 'cleanup'
+
+/** Render a static SVG of one view — for embedding where JS can't run. */
+export function renderSvg(graph: AppGraph, opts?: { view?: ViewName; group?: boolean }): string
+
+export const SCHEMA_VERSION: number
+export const NODE_KINDS: Record<NodeType, { label: string }>
+export const EDGE_KINDS: Record<EdgeKind, string>
+
+/** Structural conformance check; returns [] when the graph is well-formed. */
+export function validateGraph(graph: Pick<AppGraph, 'nodes' | 'edges'>): string[]
+
+/** The graph builder an adapter writes into before core finalizes it. */
+export class Graph {
+  nodes: Map<string, GraphNode>
+  edges: Map<string, GraphEdge>
+  node(id: string, data: Omit<GraphNode, 'id'> & { meta?: Record<string, unknown> }): GraphNode
+  has(id: string): boolean
+  edge(from: string, to: string, kind: EdgeKind): void
+  serialize(): { nodes: GraphNode[]; edges: GraphEdge[] }
+}
+
+/** A framework adapter: recognizes an app and reads it into a canonical graph. */
+export interface Adapter {
+  name: string
+  detect(dir: string): boolean
+  scan(dir: string): Promise<{ project: Project; graph: Graph; warnings: string[] }>
+}
+
+export const ADAPTERS: Adapter[]
+
+/** The first registered adapter whose `detect()` matches; throws if none do. */
+export function detectAdapter(dir: string): Adapter
+
+/** A single node newly flagged (or cleared) by a finding, in a diff. */
+export interface FindingFlag {
+  id: string
+  title: string
+  severity: 'warn' | 'info'
+  node: string
+}
+
+/** The added/removed sets and stat deltas between two scanned graphs. */
+export interface GraphDiff {
+  nodes: { added: GraphNode[]; removed: GraphNode[] }
+  edges: { added: GraphEdge[]; removed: GraphEdge[] }
+  findings: { added: FindingFlag[]; removed: FindingFlag[] }
+  stats: Record<string, number>
+}
+
+/** Compare two scanned graphs, base → head. */
+export function diffGraphs(base: AppGraph, head: AppGraph): GraphDiff
+
+/** True when nodes, edges and findings are all unchanged. */
+export function isEmptyDiff(diff: GraphDiff): boolean
+
+/** A short Markdown summary of a diff — what a PR comment renders. */
+export function formatDiffMarkdown(diff: GraphDiff, opts?: { title?: string }): string

package/src/index.mjs

@@ -0,0 +1,29 @@
+/**
+ * Public API.
+ *
+ * `scan(dir)` detects which framework the app uses, runs that adapter, and
+ * finalizes its graph into the report shape. `renderHtml(graph)` turns that
+ * shape into the self-contained interactive page. The canonical schema and the
+ * adapter registry are exported for tools that consume the graph or add a
+ * framework.
+ */
+import { detectAdapter } from './adapters/registry.mjs'
+import { finalize, Graph } from './core/graph.mjs'
+import { SCHEMA_VERSION } from './core/schema.mjs'
+
+export { renderHtml } from './core/render.mjs'
+export { renderSvg } from './core/svg.mjs'
+export { Graph }
+export { SCHEMA_VERSION, NODE_KINDS, EDGE_KINDS, validateGraph } from './core/schema.mjs'
+export { ADAPTERS, detectAdapter } from './adapters/registry.mjs'
+export { diffGraphs, isEmptyDiff, formatDiffMarkdown } from './core/diff.mjs'
+
+/**
+ * Scan a web app at `dir` into a serialized graph:
+ * `{ schemaVersion, project, warnings, nodes, edges, findings, stats }`.
+ */
+export async function scan(dir) {
+  const adapter = detectAdapter(dir)
+  const result = await adapter.scan(dir)
+  return { schemaVersion: SCHEMA_VERSION, ...finalize(result) }
+}