@ai-agent-context/core 0.1.0

package/dist/model/types.d.ts

@@ -0,0 +1,402 @@
+/**
+ * Canonical data model of the repository knowledge graph.
+ *
+ * Everything in this file is a plain, serializable TypeScript type: the model is
+ * the single source of truth for both the analysis pipeline and the `.agent/`
+ * serialization layer. Heuristic results are never modelled as facts — they are
+ * modelled as {@link Detection} values carrying `confidence` and `evidence`.
+ */
+/** Normalized confidence in the `[0, 1]` range. Never `1` for heuristic results. */
+export type Confidence = number;
+/** A single piece of machine-readable justification for a heuristic statement. */
+export interface Evidence {
+    /** Where the evidence comes from, for example `package.json` or `src/a/b.ts`. */
+    source: string;
+    /** Human readable description of what was observed. */
+    detail: string;
+}
+/** A heuristic conclusion that is explicitly *not* asserted as an absolute fact. */
+export interface Detection<TValue extends string = string> {
+    value: TValue;
+    confidence: Confidence;
+    evidence: Evidence[];
+}
+/** Edge types supported by the knowledge graph. */
+export type Relationship = 'imports' | 'exports' | 'calls' | 'extends' | 'implements' | 'depends-on' | 'used-by' | 'contains';
+/** Node kinds inside the graph. */
+export type NodeKind = 'repository' | 'package' | 'module' | 'file' | 'symbol';
+/** Classification of a resolved dependency edge. */
+export type DependencyKind = 'internal-file' | 'internal-module' | 'workspace-package' | 'external-package' | 'node-builtin' | 'unresolved';
+/** Coarse file classification, language agnostic. */
+export type FileKind = 'source' | 'test' | 'config' | 'docs' | 'asset' | 'other';
+/** Why a directory/package was treated as an architectural module. */
+export type ModuleBasis = 'workspace-package' | 'index-file' | 'directory' | 'single-file';
+/** Neutral activity bucket. Deliberately avoids words such as "critical". */
+export type ChangeFrequency = 'none' | 'low' | 'medium' | 'high';
+/** Detected architectural roles. Heuristic — always reported with confidence. */
+export type ModuleRole = 'workspace-package' | 'application' | 'domain' | 'service' | 'adapter' | 'repository' | 'controller' | 'api-routes' | 'infrastructure' | 'eventing' | 'worker' | 'cli' | 'ui' | 'shared' | 'configuration' | 'test-support';
+/** Entry point categories. */
+export type EntryPointType = 'application' | 'cli' | 'library' | 'package-main' | 'package-bin' | 'package-export' | 'http-routes' | 'worker' | 'test';
+export interface GitFileSignals {
+    /** Commits touching this path inside the analysis window. */
+    historicalChanges: number;
+    /** Commits touching this path inside the "recent" window. */
+    recentChanges: number;
+    /** ISO date (`YYYY-MM-DD`) of the last change, if known. */
+    lastChanged: string | null;
+    /** Bucketed activity derived from the distribution of module activity. */
+    changeFrequency: ChangeFrequency;
+    /** Number of distinct authors observed for this path. */
+    contributorCount: number;
+}
+export interface GitModuleSignals extends GitFileSignals {
+    /** Most frequently observed authors (neutral ownership signal). */
+    topContributors: Array<{
+        name: string;
+        commits: number;
+    }>;
+    /** Commits whose message suggests an architectural change (bounded list). */
+    architectureChangeSignals: Array<{
+        sha: string;
+        date: string;
+        subject: string;
+    }>;
+}
+export interface FileNode {
+    /** POSIX path relative to the repository root. */
+    path: string;
+    /** SHA-256 of the file content. */
+    hash: string;
+    size: number;
+    /** Modification time in milliseconds since epoch (informational, local). */
+    mtimeMs: number;
+    /** Language id assigned by a language adapter, for example `typescript`. */
+    language: string;
+    kind: FileKind;
+    /** Owning module id, when the file belongs to a module. */
+    moduleId: string | null;
+    /** Owning workspace package name, when inside a workspace package. */
+    packageName: string | null;
+    /** Symbol ids declared in this file. */
+    symbolIds: string[];
+    /** Outgoing import/dependency specifiers observed in this file. */
+    importSpecifiers: string[];
+    /** Language-agnostic signals emitted by the language adapter. */
+    signals: string[];
+    /** `true` when the file was skipped because it matched sensitive patterns. */
+    sensitive: boolean;
+    parseStatus: ParseStatus;
+}
+export interface ModuleNode {
+    /** Stable id: workspace package name or path relative to the repository root. */
+    id: string;
+    path: string;
+    name: string;
+    basis: ModuleBasis;
+    /** Architectural roles, heuristic, each with confidence and evidence. */
+    roles: Detection<ModuleRole>[];
+    packageName: string | null;
+    isWorkspacePackage: boolean;
+    files: string[];
+    entryPoints: EntryPoint[];
+    /** Ids of modules this module depends on. */
+    dependsOn: string[];
+    /** Ids of modules that depend on this module. */
+    usedBy: string[];
+    /** Externally reachable exported symbols (agent-facing API surface). */
+    publicExports: Array<{
+        name: string;
+        kind: SymbolKind;
+        file: string;
+    }>;
+    /** Files of the module that re-export other modules (boundary candidates). */
+    boundaries: string[];
+    /** Aggregated language-agnostic signals of the module files. */
+    signals: string[];
+    /** Heuristic responsibilities, never asserted as facts. */
+    responsibilities: Detection[];
+    git: GitModuleSignals | null;
+    /** Test files inside the module. */
+    testFiles: string[];
+}
+export interface SymbolNode {
+    /** Stable id: `<file path>#<symbol name>`. */
+    id: string;
+    name: string;
+    kind: SymbolKind;
+    file: string;
+    moduleId: string | null;
+    exported: boolean;
+    isDefault: boolean;
+    extends: string[];
+    implements: string[];
+    /** 1-based line of the declaration. */
+    line: number;
+}
+export interface DependencyEdge {
+    /** Stable id: `<from>|<relationship>|<to>`. */
+    id: string;
+    from: string;
+    fromKind: NodeKind;
+    to: string;
+    toKind: NodeKind;
+    relationship: Relationship;
+    kind: DependencyKind;
+    /** Raw specifier as written in the source, when applicable. */
+    specifier?: string;
+    /** Import syntax flavour, when applicable. */
+    syntax?: ImportSyntax;
+    confidence: Confidence;
+    evidence: Evidence[];
+}
+export interface EntryPoint {
+    path: string;
+    moduleId: string | null;
+    type: EntryPointType;
+    confidence: Confidence;
+    evidence: Evidence[];
+    /** Additional context, for example the npm script or route method. */
+    details?: string;
+}
+export interface Convention {
+    id: string;
+    category: string;
+    statement: string;
+    confidence: Confidence;
+    evidence: Evidence[];
+    /** How the convention was derived. */
+    origin: 'observed' | 'config';
+}
+export type ParseStatus = 'ok' | 'partial' | 'failed' | 'skipped';
+export type ImportSyntax = 'static' | 'type-only' | 'dynamic' | 'require' | 'side-effect' | 'reexport' | 'import-equals';
+export type SymbolKind = 'class' | 'interface' | 'type' | 'enum' | 'function' | 'const' | 'variable' | 'method' | 'namespace';
+export type DecisionStatus = 'accepted' | 'proposed' | 'deprecated' | 'superseded' | 'rejected' | 'unknown';
+export interface Decision {
+    id: string;
+    title: string;
+    status: DecisionStatus;
+    /** Repository-relative path (or git reference) the decision was found in. */
+    source: string;
+    /** `explicit` = authored by humans in the repository, `inferred` = derived by heuristics. */
+    origin: 'explicit' | 'inferred';
+    kind: 'adr' | 'documented-section' | 'git-signal' | 'config-signal' | 'dependency-signal';
+    confidence: Confidence;
+    evidence: Evidence[];
+    excerpt?: string;
+}
+export interface WorkspacePackage {
+    name: string;
+    /** Repository-relative POSIX path. */
+    path: string;
+    version: string | null;
+    private: boolean;
+    type: 'module' | 'commonjs' | null;
+    runtimeDependencies: string[];
+    developmentDependencies: string[];
+    peerDependencies: string[];
+    scripts: Record<string, string>;
+    /** Declared entry fields from package.json (structural facts). */
+    entries: Array<{
+        field: 'main' | 'module' | 'types' | 'browser' | 'exports' | 'bin';
+        value: string;
+    }>;
+}
+export interface WorkspaceInfo {
+    packageManager: 'npm' | 'pnpm' | 'yarn' | 'bun' | 'unknown';
+    /** Repository signals only: a lockfile is a signal, not proof of runtime usage. */
+    packageManagerEvidence: Evidence[];
+    lockfiles: string[];
+    isMonorepo: boolean;
+    workspaceModel: 'npm-workspaces' | 'yarn-workspaces' | 'pnpm-workspaces' | 'bun-workspaces' | 'single-package';
+    workspaceGlobs: string[];
+    rootPackage: WorkspacePackage | null;
+    packages: WorkspacePackage[];
+}
+export interface ExternalDependency {
+    name: string;
+    scope: 'runtime' | 'development' | 'peer';
+    /** Workspace package names declaring this dependency. */
+    declaredBy: string[];
+    /** Number of internal modules importing it. */
+    importedByModules: number;
+    /** Heuristic importance classification with evidence. */
+    importance: Detection<'infrastructure' | 'framework' | 'tooling' | 'utility'>;
+}
+export interface Repository {
+    /** Absolute repository root. */
+    root: string;
+    name: string;
+    schemaVersion: number;
+    languages: string[];
+    workspace: WorkspaceInfo;
+    files: FileNode[];
+    modules: ModuleNode[];
+    symbols: SymbolNode[];
+    dependencies: DependencyEdge[];
+    entryPoints: EntryPoint[];
+    conventions: Convention[];
+    decisions: Decision[];
+    externalDependencies: ExternalDependency[];
+    /** Module-level dependency cycles (module ids, deterministic order). */
+    cycles: string[][];
+}
+export interface ChangeSet {
+    added: string[];
+    modified: string[];
+    deleted: string[];
+    unchanged: string[];
+    /** `false` when metadata was missing, forcing a cold scan. */
+    incremental: boolean;
+}
+export interface ScanReport {
+    changes: ChangeSet;
+    files: {
+        total: number;
+        source: number;
+        tests: number;
+        skipped: number;
+        failed: number;
+    };
+    modules: number;
+    dependencies: number;
+    externalDependencies: number;
+    entryPoints: number;
+    conventions: number;
+    decisions: number;
+    /** Number of files whose content was parsed during this scan. */
+    parsed: number;
+    /** Number of files whose parse result was reused from the local cache. */
+    reused: number;
+    /** Subgraph affected by this scan (used for incremental invalidation). */
+    affected: {
+        files: string[];
+        modules: string[];
+        dependents: string[];
+    };
+    durationMs: number;
+    warnings: DiagnosticPayload[];
+}
+export interface DiagnosticPayload {
+    code: string;
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+    source?: string;
+    hint?: string;
+}
+export interface ContextDiff {
+    files: {
+        added: string[];
+        modified: string[];
+        removed: string[];
+    };
+    modules: {
+        added: string[];
+        removed: string[];
+        roleChanges: Array<{
+            moduleId: string;
+            added: string[];
+            removed: string[];
+        }>;
+    };
+    entryPoints: {
+        added: string[];
+        removed: string[];
+    };
+    dependencies: {
+        added: Array<{
+            from: string;
+            to: string;
+            relationship: Relationship;
+            kind: DependencyKind;
+        }>;
+        removed: Array<{
+            from: string;
+            to: string;
+            relationship: Relationship;
+            kind: DependencyKind;
+        }>;
+        externalAdded: string[];
+        externalRemoved: string[];
+    };
+    conventions: {
+        added: string[];
+        removed: string[];
+        changed: string[];
+    };
+    decisions: {
+        added: string[];
+        removed: string[];
+    };
+    statistics: {
+        files: number;
+        modules: number;
+        dependencies: number;
+        entries: number;
+    };
+    hasChanges: boolean;
+    /** Hash of the previously persisted canonical context, when available. */
+    baseline: string | null;
+}
+export interface SearchResult {
+    type: 'file' | 'module' | 'symbol' | 'decision' | 'convention' | 'entry-point' | 'dependency';
+    id: string;
+    score: number;
+    /** Deterministic explanation of why the node matched. */
+    reason: string;
+    /** Short, agent-friendly excerpt. */
+    snippet?: string;
+}
+export interface ModuleExplanation {
+    module: {
+        id: string;
+        path: string;
+        name: string;
+        basis: ModuleBasis;
+        roles: Detection<ModuleRole>[];
+        responsibilities: Detection[];
+    };
+    summary: string;
+    entryPoints: EntryPoint[];
+    dependsOn: Array<{
+        id: string;
+        path: string;
+        relationships: Relationship[];
+        files: number;
+    }>;
+    usedBy: Array<{
+        id: string;
+        path: string;
+        relationships: Relationship[];
+        files: number;
+    }>;
+    externalDependencies: Array<{
+        name: string;
+        scope: ExternalDependency['scope'];
+        importance: Detection;
+    }>;
+    publicApi: Array<{
+        name: string;
+        kind: SymbolKind;
+        file: string;
+    }>;
+    internalSymbols: Array<{
+        name: string;
+        kind: SymbolKind;
+        file: string;
+    }>;
+    conventions: Convention[];
+    decisions: Decision[];
+    tests: {
+        files: string[];
+        testCount: number;
+    };
+    git: GitModuleSignals | null;
+    /** Modules and files that would be affected by a change in this module. */
+    impact: {
+        modules: string[];
+        files: string[];
+    };
+    relatedFiles: string[];
+    warnings: DiagnosticPayload[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/model/types.d.ts.map

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

package/dist/model/types.js

@@ -0,0 +1,10 @@
+/**
+ * Canonical data model of the repository knowledge graph.
+ *
+ * Everything in this file is a plain, serializable TypeScript type: the model is
+ * the single source of truth for both the analysis pipeline and the `.agent/`
+ * serialization layer. Heuristic results are never modelled as facts — they are
+ * modelled as {@link Detection} values carrying `confidence` and `evidence`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/model/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/model/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/pipeline/scan-pipeline.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The scanning pipeline: the single orchestration path used by the CLI, the
+ * programmatic API and the MCP adapter.
+ *
+ * Order matters and is explicit:
+ *
+ * ```text
+ * config в†’ local state в†’ scanner (incremental) в†’ workspace в†’ knowledge graph
+ *        в†’ architecture roles / entry points в†’ git signals в†’ conventions
+ *        в†’ decisions в†’ canonical documents в†’ diff в†’ persist в†’ local state
+ * ```
+ *
+ * Nothing here writes to `.agent/` when `dryRun` is set, which is how `status`
+ * and `diff` stay side-effect free.
+ */
+import type { LanguageRegistry } from '../adapters/language/registry.ts';
+import type { ParsedFile } from '../adapters/language/types.ts';
+import type { KnowledgeGraph } from '../core/graph/knowledge-graph.ts';
+import type { ContextDiff, ScanReport, WorkspaceInfo } from '../model/types.ts';
+import type { AgentContextConfig, ConfigOverrides } from '../config/types.ts';
+import { DiagnosticsCollector, Logger, type ProgressReporter } from '../logging/diagnostics.ts';
+import { GitAdapter, type GitAvailability } from '../adapters/git/git-adapter.ts';
+import { type ScanOutput } from '../core/scanner/scanner.ts';
+import { type LocalState } from '../core/scanner/cache.ts';
+import { type PersistedContext } from '../core/serialization/reader.ts';
+import { type WriteContextResult } from '../core/serialization/writer.ts';
+import type { ContextDocuments } from '../core/serialization/types.ts';
+export interface PipelineOptions {
+    root: string;
+    /** Configuration overrides coming from CLI flags. */
+    overrides?: ConfigOverrides;
+    configPath?: string;
+    logger?: Logger;
+    registry?: LanguageRegistry;
+    progress?: ProgressReporter;
+    /** Compute everything but write nothing (`status`, `diff`). */
+    dryRun?: boolean;
+    /** Ignore the local state and re-read every file. */
+    force?: boolean;
+    /** Injectable clock (tests), used for timestamps and git windows. */
+    now?: () => number;
+    /** Injectable git adapter (tests, or when git is not on PATH). */
+    gitAdapter?: GitAdapter;
+}
+export interface PipelineResult {
+    config: AgentContextConfig;
+    configHash: string;
+    graph: KnowledgeGraph;
+    parsed: Map<string, ParsedFile>;
+    documents: ContextDocuments;
+    report: ScanReport;
+    diff: ContextDiff;
+    persisted: PersistedContext;
+    written: WriteContextResult | null;
+    state: LocalState;
+    workspace: WorkspaceInfo;
+    git: {
+        availability: GitAvailability;
+        commitsAnalyzed: number;
+    };
+    diagnostics: DiagnosticsCollector;
+}
+/** Rebuilds the workspace model from the parsed `package.json` files. */
+export declare function detectWorkspaceFromScan(scan: ScanOutput): WorkspaceInfo;
+/** Runs the whole pipeline. */
+export declare function runPipeline(options: PipelineOptions): Promise<PipelineResult>;
+/** Stable hash of the canonical documents; used by `status`. */
+export declare function documentHash(documents: ContextDocuments): string;
+//# sourceMappingURL=scan-pipeline.d.ts.map

package/dist/pipeline/scan-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-pipeline.d.ts","sourceRoot":"","sources":["../../src/pipeline/scan-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,EAAE,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAIhG,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAClF,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7E,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,0BAA0B,CAAC;AASxF,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAC9F,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAExF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAGvE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,kEAAkE;IAClE,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAChC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACnC,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,aAAa,CAAC;IACzB,GAAG,EAAE;QAAE,YAAY,EAAE,eAAe,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,WAAW,EAAE,oBAAoB,CAAC;CACnC;AAED,yEAAyE;AACzE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,GAAG,aAAa,CAmBvE;AA8DD,+BAA+B;AAC/B,wBAAsB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAwJnF;AAmDD,gEAAgE;AAChE,wBAAgB,YAAY,CAAC,SAAS,EAAE,gBAAgB,GAAG,MAAM,CAEhE"}