@neurcode-ai/governance-runtime 0.1.3 → 0.1.5

package/dist/architecture-graph.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Repository Architecture Graph — V2.
+ *
+ * Turns the path/owner profile into an architecture-aware model that can reason
+ * about module boundaries, ownership, dependency direction, and sensitive
+ * surfaces during agentic development.
+ *
+ * Source-free guarantees:
+ *   - Import *specifiers* (module strings) may be read locally to infer edges,
+ *     but raw source, diffs, and file contents are NEVER stored on the graph.
+ *     The graph holds only module ids, owners, surface tags, and module→module
+ *     dependency edges — architecture metadata, not code.
+ *   - Deterministic: same inputs → same `architectureHash`.
+ *
+ * The extractor + resolver are pure functions so the CLI can read local files,
+ * derive specifiers, build edges, and discard the content immediately.
+ */
+import { type OwnershipBoundary, type SensitiveBoundary } from './profile';
+import type { ArchitectureObligationCategory, ArchitectureObligationSeverity } from './architecture-obligations';
+export declare const ARCHITECTURE_GRAPH_SCHEMA_VERSION: 2;
+/** Architectural surface kinds a module can expose. */
+export type ArchitectureSurfaceKind = 'auth' | 'security' | 'secrets' | 'crypto' | 'payments' | 'database' | 'migration' | 'public-api';
+export interface ArchitectureModule {
+    /** Collapsed module id, e.g. "src/billing" or "packages/cli". */
+    id: string;
+    /** Glob matching the module's files, e.g. "src/billing/**". */
+    glob: string;
+    fileCount: number;
+    /** CODEOWNERS owners for the module (GitHub last-rule-wins semantics). */
+    owners: string[];
+    /** Sensitive tags inherited from the profile's sensitive boundaries. */
+    sensitiveTags: SensitiveBoundary['tag'][];
+    /** Architectural surfaces this module exposes. */
+    surfaces: ArchitectureSurfaceKind[];
+    /** True when the module is inside an approval-required boundary. */
+    approvalRequired: boolean;
+    /** Dominant language of the module's files. */
+    language: string;
+}
+/** A directed dependency edge: `from` imports `to` (so `to` is upstream). */
+export interface ArchitectureDependencyEdge {
+    /** Consumer module id (the importer / downstream module). */
+    from: string;
+    /** Provider module id (the imported / upstream module). */
+    to: string;
+    /** Number of resolved import references contributing to this edge. */
+    weight: number;
+}
+export interface ArchitectureGraphStats {
+    moduleCount: number;
+    edgeCount: number;
+    analyzedFiles: number;
+    resolvedImports: number;
+    languages: string[];
+}
+export interface RepoArchitectureGraph {
+    schemaVersion: typeof ARCHITECTURE_GRAPH_SCHEMA_VERSION;
+    generatedAt: string;
+    moduleDepth: number;
+    modules: ArchitectureModule[];
+    edges: ArchitectureDependencyEdge[];
+    stats: ArchitectureGraphStats;
+    /** Deterministic fingerprint of modules + edges (source-free). */
+    architectureHash: string;
+}
+/** Source-free representation of one file's imports (specifiers only). */
+export interface ModuleImportRecord {
+    filePath: string;
+    specifiers: string[];
+}
+export interface BuildArchitectureGraphInput {
+    /** Repo-relative paths (e.g. from `git ls-files`). */
+    paths: string[];
+    ownershipBoundaries?: OwnershipBoundary[];
+    sensitiveBoundaries?: SensitiveBoundary[];
+    approvalRequiredGlobs?: string[];
+    /** Per-file import specifiers (read locally, never stored). */
+    imports?: ModuleImportRecord[];
+    /** Directory depth used to collapse files into modules (default 2). */
+    moduleDepth?: number;
+    now?: string;
+}
+/**
+ * Collapse a file path to a module id using the first `depth` directory
+ * segments. Root-level files map to the synthetic module ".".
+ *
+ * When a repository contains an embedded service/app fixture, preserve the
+ * prefix up to a recognizable app root (`src`, `packages`, `services`, etc.)
+ * and then apply depth from there. Without this, paths such as
+ * `fixtures/demo-svc/src/billing/charge.py` collapse to `fixtures/demo-svc`,
+ * mixing billing/auth/migration ownership into one misleading module.
+ */
+export declare function moduleIdForPath(filePath: string, depth?: number): string;
+/**
+ * Extract import specifiers (module strings) from a single file's content.
+ *
+ * Returns only the quoted/dotted module specifiers — never source text. The
+ * caller reads file content locally and discards it after calling this.
+ */
+export declare function extractImportSpecifiers(filePath: string, content: string): string[];
+/**
+ * Resolve an import specifier to a repo-relative source file, if it points to a
+ * known in-repo module. External packages (e.g. "fastapi", "react") resolve to
+ * null and are intentionally excluded from the internal dependency graph.
+ */
+export declare function resolveImportSpecifier(fromFile: string, specifier: string, knownPaths: Set<string>): string | null;
+/**
+ * Build the deterministic repository architecture graph. Pure and source-free:
+ * the only edge inputs are import *specifiers*, and only module→module edges
+ * are retained.
+ */
+export declare function buildArchitectureGraph(input: BuildArchitectureGraphInput): RepoArchitectureGraph;
+export declare function findModuleForPath(graph: RepoArchitectureGraph, filePath: string): ArchitectureModule | null;
+/** Modules that import the given module (its downstream consumers). */
+export declare function dependentsOf(graph: RepoArchitectureGraph, moduleId: string): string[];
+/** Modules the given module imports (its upstream providers / dependencies). */
+export declare function dependenciesOf(graph: RepoArchitectureGraph, moduleId: string): string[];
+export interface GraphObligationSeed {
+    id: string;
+    category: ArchitectureObligationCategory;
+    title: string;
+    description: string;
+    severity: ArchitectureObligationSeverity;
+    /** Module id this obligation guards. */
+    module: string;
+    /** Glob used for path-scoped feedback + approval matching. */
+    requiredPath: string;
+    triggeredBy: string[];
+    requiredEvidence: string[];
+    surface: ArchitectureSurfaceKind | 'dependency';
+    /** How the obligation can be satisfied (source-free). */
+    satisfy: {
+        /** An active approval covering the module satisfies it. */
+        approval: boolean;
+        /** Accepted-plan text matching this (case-insensitive) regex satisfies it. */
+        planPattern?: string;
+        /** A guarded test-path edit within the module satisfies it. */
+        moduleTest?: boolean;
+    };
+}
+/** Modules considered "in play" for a set of candidate paths/globs. */
+export declare function modulesInPlay(graph: RepoArchitectureGraph, candidatePaths: string[]): ArchitectureModule[];
+/**
+ * Derive graph obligation seeds for the modules currently in play. Deterministic
+ * and ordered by id.
+ */
+export declare function deriveGraphObligationSeeds(args: {
+    graph: RepoArchitectureGraph;
+    candidatePaths: string[];
+}): GraphObligationSeed[];
+/** True when a graph obligation can be satisfied by editing the module's tests. */
+export declare function isModuleTestSatisfiable(obligationId: string): boolean;
+//# sourceMappingURL=architecture-graph.d.ts.map

package/dist/architecture-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"architecture-graph.d.ts","sourceRoot":"","sources":["../src/architecture-graph.ts"],"names":[],"mappings":"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"}