@anarchitects/governance-adapter-typescript 0.0.1

package/README.md

@@ -0,0 +1,155 @@
+# `@anarchitects/governance-adapter-typescript`
+
+Platform-independent TypeScript workspace discovery and normalization for Governance.
+
+## Overview
+
+`@anarchitects/governance-adapter-typescript` reads a TypeScript-oriented workspace as plain files and maps the result into contracts owned by `@anarchitects/governance-core`.
+
+The package focuses on discovery and normalization, not on owning the canonical Governance model. It is intended for hosts that need to inspect a TypeScript workspace outside Nx and then feed the normalized result into Governance Core.
+
+## Responsibilities
+
+This package is responsible for:
+
+- detecting whether a repository looks like a supported TypeScript workspace
+- parsing package-manager workspace configuration
+- parsing `tsconfig.json` and `tsconfig.base.json` resolution state
+- discovering TypeScript projects from workspace package roots
+- building a static TypeScript import graph
+- mapping discovered imports into Core-owned dependency inputs
+- deriving project tags from naming and path rules
+
+This package is not responsible for:
+
+- CLI command behavior
+- canonical Governance contracts
+- Nx graph loading
+- Nx metadata extraction
+- Nx plugin runtime behavior
+- Nx executors or generators
+
+## Supported Assumptions
+
+The current implementation assumes:
+
+- workspace detection based on plain package-manager files such as `pnpm-workspace.yaml` and `package.json#workspaces`
+- `tsconfig` parsing through root `tsconfig.json`, `tsconfig.base.json`, and deterministic `extends` chains
+- static analysis of relative imports, package-name imports, `compilerOptions.paths`, `baseUrl`, re-exports, and string-literal dynamic imports
+- project discovery from package-manager workspace roots rather than from Nx graph APIs
+
+## Public API
+
+The public package surface is intentionally adapter-oriented:
+
+```ts
+import {
+  buildTypeScriptImportGraph,
+  createGovernanceWorkspaceAdapter,
+  createTypeScriptWorkspaceAdapter,
+  detectTypeScriptWorkspace,
+  discoverTypeScriptProjects,
+  deriveProjectTags,
+  mapTypeScriptImportsToGovernanceDependencies,
+  parsePackageManagerWorkspace,
+  parseTsConfigResolution,
+  type TsConfigResolutionModel,
+  type TypeScriptImportGraph,
+  type TypeScriptProjectDiscoveryResult,
+  type TypeScriptWorkspaceDetectionResult,
+  type WorkspacePackageResolution,
+} from '@anarchitects/governance-adapter-typescript';
+```
+
+The root export currently includes:
+
+- `createTypeScriptWorkspaceAdapter(...)`
+- `createGovernanceWorkspaceAdapter(...)`
+- `detectTypeScriptWorkspace(...)`
+- `parsePackageManagerWorkspace(...)`
+- `parseTsConfigResolution(...)`
+- `discoverTypeScriptProjects(...)`
+- `buildTypeScriptImportGraph(...)`
+- `mapTypeScriptImportsToGovernanceDependencies(...)`
+- `deriveProjectTags(...)`
+- exported adapter result and diagnostic types from `types.ts`
+
+The current API is a set of composable adapter primitives. It does not expose a single all-in-one host runner.
+
+## Usage
+
+The typical workflow is:
+
+1. detect a supported workspace
+2. resolve workspace package roots
+3. discover projects
+4. resolve TypeScript path aliases
+5. build a static import graph
+6. map that graph into Core-owned dependency inputs
+
+```ts
+import {
+  buildTypeScriptImportGraph,
+  detectTypeScriptWorkspace,
+  discoverTypeScriptProjects,
+  mapTypeScriptImportsToGovernanceDependencies,
+  parsePackageManagerWorkspace,
+  parseTsConfigResolution,
+} from '@anarchitects/governance-adapter-typescript';
+
+const detection = detectTypeScriptWorkspace(process.cwd());
+
+if (!detection.supported) {
+  throw new Error('Unsupported TypeScript workspace.');
+}
+
+const workspacePackages = parsePackageManagerWorkspace(detection.workspaceRoot);
+const projectDiscovery = discoverTypeScriptProjects({
+  workspaceRoot: workspacePackages.workspaceRoot,
+  packageRoots: workspacePackages.packageRoots,
+});
+const tsconfig = parseTsConfigResolution(detection.workspaceRoot);
+const importGraph = buildTypeScriptImportGraph({
+  workspaceRoot: detection.workspaceRoot,
+  projects: projectDiscovery.projects,
+  tsconfig,
+});
+const dependencyMapping = mapTypeScriptImportsToGovernanceDependencies({
+  projects: projectDiscovery.projects,
+  importGraph,
+});
+```
+
+## Normalization into Governance Core
+
+This adapter normalizes into `@anarchitects/governance-core` contracts rather than defining a parallel model.
+
+In practice:
+
+- project discovery produces `GovernanceProjectInput` values
+- dependency mapping produces `GovernanceDependencyInput` values
+- diagnostics align with Core-owned diagnostic shapes where the exported types reference them
+
+Hosts can combine these results with Core-owned assessment, rule, signal, and extension APIs.
+
+## Package Boundaries
+
+`@anarchitects/governance-adapter-typescript` is explicitly non-Nx.
+
+That means:
+
+- no `@nx/devkit`
+- no `nx`
+- no Nx graph loading
+- no Nx plugin runtime assumptions
+- no executor or generator ownership
+
+The package reads repository files directly and stays usable in plain TypeScript or mixed monorepo environments without requiring Nx.
+
+For detailed package-boundary rules and the adapter ownership model, see
+[ADR 0001: Governance Package Boundaries for Core, CLI, Adapters, and Extensions](../../../docs/adr/0001-governance-package-boundaries.md).
+
+## Related Packages
+
+- `@anarchitects/governance-core` owns the canonical Governance contracts and deterministic evaluation logic
+- `@anarchitects/governance-cli` is a separate host/runtime package and should not be treated as part of this adapter’s public API

package/dist/detect-typescript-workspace.d.ts

@@ -0,0 +1,3 @@
+import { TypeScriptWorkspaceDetectionResult } from './types.js';
+export declare function detectTypeScriptWorkspace(workspacePath: string): TypeScriptWorkspaceDetectionResult;
+//# sourceMappingURL=detect-typescript-workspace.d.ts.map

package/dist/detect-typescript-workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-typescript-workspace.d.ts","sourceRoot":"","sources":["../src/detect-typescript-workspace.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,kCAAkC,EAEnC,MAAM,YAAY,CAAC;AAEpB,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,GACpB,kCAAkC,CAoDpC"}

package/dist/diagnostics.d.ts

@@ -0,0 +1,26 @@
+import { TypeScriptWorkspaceDetectionDiagnostic, TypeScriptWorkspaceIndicators } from './types.js';
+export declare function invalidPackageJsonDiagnostic(filePath: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function partialWorkspaceDetectionDiagnostic(indicators: TypeScriptWorkspaceIndicators): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function noWorkspaceIndicatorsDiagnostic(): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function invalidWorkspaceConfigDiagnostic(path: string, message: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function unsupportedWorkspaceFormatDiagnostic(path: string, message: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function noWorkspacePackagesFoundDiagnostic(patterns: readonly string[]): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function invalidTsConfigDiagnostic(path: string, message: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function invalidTsConfigExtendsDiagnostic(path: string, message: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function circularTsConfigExtendsDiagnostic(path: string, chain: readonly string[]): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function invalidPathAliasDiagnostic(path: string, message: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function invalidDiscoveryPatternDiagnostic(path: string, message: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function discoveryPatternNoMatchesDiagnostic(pattern: string, path: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function duplicateProjectRootDiagnostic(root: string, path: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function duplicateProjectNameDiagnostic(name: string, path: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function invalidTagTemplateDiagnostic(path: string, message: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function invalidProjectNameTemplateDiagnostic(path: string, message: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function sourceFileParseErrorDiagnostic(path: string, message: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function unresolvedImportDiagnostic(path: string, message: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function nonLiteralDynamicImportDiagnostic(path: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function unsupportedImportSyntaxDiagnostic(path: string, message: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function sourceFileOutsideProjectDiagnostic(path: string, filePath: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function resolvedImportOutsideProjectDiagnostic(path: string, filePath: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function unresolvedInternalImportDiagnostic(path: string, sourceFile: string, specifier: string): TypeScriptWorkspaceDetectionDiagnostic;
+export declare function ambiguousProjectMatchDiagnostic(path: string, filePath: string, projectIds: readonly string[]): TypeScriptWorkspaceDetectionDiagnostic;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sCAAsC,EACtC,6BAA6B,EAC9B,MAAM,YAAY,CAAC;AAIpB,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,GACf,sCAAsC,CAOxC;AAED,wBAAgB,mCAAmC,CACjD,UAAU,EAAE,6BAA6B,GACxC,sCAAsC,CAUxC;AAED,wBAAgB,+BAA+B,IAAI,sCAAsC,CAOxF;AAED,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,sCAAsC,CAOxC;AAED,wBAAgB,oCAAoC,CAClD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,sCAAsC,CAOxC;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,sCAAsC,CASxC;AAED,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,sCAAsC,CAOxC;AAED,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,sCAAsC,CAOxC;AAED,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,sCAAsC,CAUxC;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,sCAAsC,CAOxC;AAED,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,sCAAsC,CAOxC;AAED,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,sCAAsC,CAOxC;AAED,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,sCAAsC,CAOxC;AAED,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,sCAAsC,CAOxC;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,sCAAsC,CAOxC;AAED,wBAAgB,oCAAoC,CAClD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,sCAAsC,CAOxC;AAED,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,sCAAsC,CAOxC;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,sCAAsC,CAOxC;AAED,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,GACX,sCAAsC,CAQxC;AAED,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,sCAAsC,CAOxC;AAED,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,sCAAsC,CAOxC;AAED,wBAAgB,sCAAsC,CACpD,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,sCAAsC,CAOxC;AAED,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,sCAAsC,CAOxC;AAED,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,sCAAsC,CAUxC"}

package/dist/import-graph.d.ts

@@ -0,0 +1,8 @@
+import { GovernanceProjectInput } from '@anarchitects/governance-core';
+import { TsConfigResolutionModel, TypeScriptImportGraph } from './types.js';
+export declare function buildTypeScriptImportGraph(options: {
+    workspaceRoot: string;
+    projects: readonly GovernanceProjectInput[];
+    tsconfig?: TsConfigResolutionModel;
+}): TypeScriptImportGraph;
+//# sourceMappingURL=import-graph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"import-graph.d.ts","sourceRoot":"","sources":["../src/import-graph.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAK5E,OAAO,KAAK,EACV,uBAAuB,EAEvB,qBAAqB,EAGtB,MAAM,YAAY,CAAC;AAIpB,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC5C,QAAQ,CAAC,EAAE,uBAAuB,CAAC;CACpC,GAAG,qBAAqB,CAyCxB"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { detectTypeScriptWorkspace } from './detect-typescript-workspace.js';
+export { buildTypeScriptImportGraph } from './import-graph.js';
+export { DEFAULT_TYPESCRIPT_PROJECT_DISCOVERY_CONFIG, createGovernanceWorkspaceAdapter, createTypeScriptWorkspaceAdapter, governanceWorkspaceAdapter, type CreateGovernanceWorkspaceAdapterOptions, type CreateTypeScriptWorkspaceAdapterOptions, } from './workspace-adapter.js';
+export { mapTypeScriptImportsToGovernanceDependencies } from './map-imports-to-projects.js';
+export { parsePackageManagerWorkspace } from './parse-package-manager-workspace.js';
+export { parseTsConfigResolution } from './parse-tsconfig.js';
+export { discoverTypeScriptProjects } from './project-discovery.js';
+export { deriveProjectTags, type DerivedProjectTags } from './tag-mapping.js';
+export type { TsConfigResolutionModel, TypeScriptImportEdge, TypeScriptImportGraph, TypeScriptImportKind, TypeScriptProjectDependencyMappingResult, TypeScriptProjectDiscoveryConfig, TypeScriptProjectDiscoveryResult, TypeScriptProjectDiscoveryRule, TypeScriptSourceFileNode, TypeScriptWorkspaceDetectionDiagnostic, TypeScriptWorkspaceDetectionResult, TypeScriptWorkspaceDetectionStatus, TypeScriptWorkspaceIndicators, TypeScriptWorkspacePackageManager, WorkspacePackageResolution, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAC7E,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EACL,2CAA2C,EAC3C,gCAAgC,EAChC,gCAAgC,EAChC,0BAA0B,EAC1B,KAAK,uCAAuC,EAC5C,KAAK,uCAAuC,GAC7C,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,4CAA4C,EAAE,MAAM,8BAA8B,CAAC;AAC5F,OAAO,EAAE,4BAA4B,EAAE,MAAM,sCAAsC,CAAC;AACpF,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,YAAY,EACV,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,wCAAwC,EACxC,gCAAgC,EAChC,gCAAgC,EAChC,8BAA8B,EAC9B,wBAAwB,EACxB,sCAAsC,EACtC,kCAAkC,EAClC,kCAAkC,EAClC,6BAA6B,EAC7B,iCAAiC,EACjC,0BAA0B,GAC3B,MAAM,YAAY,CAAC"}